updog/readme.md

# Updog

## What's updog?

Not much, you?

<small>(it's a simple, extensible uptime monitor)</small>

## Warning

**Extensions will be executed with no safety checks!** Make sure an extension isn't malicious before adding it.

## Uptime Checker Extensions

<!-- move to docs folder later -->

Updog doesn't do any monitoring by itself. Instead, extensions are used to check the status of whatever thing, send alerts, and log stuff. Updog just chains them together.

Some examples extensions:

- [askiiart/updog-checker_template](https://git.askiiart.net/askiiart/updog-checker_template)
- Others will be added later

### Folder layout

Extensions need to be put in the `./extensions/checkers` folder and the name of the file must match the name of the folder. In the future, `alerts` and `logging` folders will be added for those extensions. For now, there is only support for checkers.

### Methods

`*`: indicates a method is required

#### `__init__()`*

**Arguments**:

- A dict of arguments from `checker-args` in `services.json` - For no arguments, an empty dict will be used

Example:

```py
{
    "url": "https://example.net",
    "port": 443
}
```

**Return**: None

#### `get_status()`*

**Arguments**: None

**Return**: An integer indicating status; the codes; what the code means is provided by [`get_return_codes()`](#get_return_codes)

These values can be overriden by providing [`get_return_codes()`](#get_return_codes)

#### `get_return_codes()`*

**Arguments**: None

**Return**: A `dict` containing integers and their associated statuses.

Example:

```py
{
    0: "Down",
    50: "Partial outage",
    100: "Up"
}
```

## To-do

- Add basic functionality
  - Read `services.json` file:

```json
{
    "site": {
        "name": "A Website",
        "checker": "CheckerTemplate",
        "checker-args": {
            "url": "https://example.net",
            "port": 443
        },
        "rate": 60,
        "alerts": "AlertsTemplate",
        "alerts-args": {
            "url": "https://example.com/webhook-url-or-whatever-goes-here"
        },
        "logging": "LoggingTemplate",
        "logging-args": {
            "format": "irrelevant, LoggingTemplate has no options lol"
        }
    }
}
```

The args are just passed to the extension as a `dict`, the extension handles it from there.

- Add support for logging and alert extensions

---

***All specs are still a work-in-progress, breaking changes are likely!***