From c933b5a8a1888f10914b0f8b3d4287e65fea869d Mon Sep 17 00:00:00 2001 From: askiiart Date: Mon, 29 Jan 2024 17:26:50 -0600 Subject: [PATCH] Move docs to docs folder, rename files --- README.md | 55 +++++++++++++++++++ docs/extensions/README.md | 35 ++++++++++++ docs/extensions/checkers.md | 62 +++++++++++++++++++++ readme.md | 106 ------------------------------------ main.py => updog.py | 0 5 files changed, 152 insertions(+), 106 deletions(-) create mode 100644 README.md create mode 100644 docs/extensions/README.md create mode 100644 docs/extensions/checkers.md delete mode 100644 readme.md rename main.py => updog.py (100%) diff --git a/README.md b/README.md new file mode 100644 index 0000000..8b32c4c --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +# Updog + +## What's updog? + +Not much, you? + +(it's a simple, extensible uptime monitor) + +## Warning + +**Extensions will be executed with no safety checks!** Make sure an extension isn't malicious before adding it. + +## Docs + +Docs are in the `./docs/` folder, but here's a quick overview on how to use this: + +1. Clone this repository - or just download `updog.py` +2. Install your extensions in the appropriate folders: `./extensions/checkers`, `./extensions/alerts` (optional), and `./extensions/logging` +3. Create your `services.json` file, example below. + +```json +{ + "site": { + "name": "A Website", + "checker": "CheckerTemplate", + "checker-args": { + "url": "https://example.net", + "port": 443, + "lol": "CheckerTemplate ignores these options lol" + }, + "rate": 60, + "alerts": "AlertsTemplate", + "alerts-args": { + "url": "https://example.com/webhook-url-or-whatever-goes-here", + "lol": "irrelevant, AlertsTemplate ignores these options lol" + }, + "logging": "LoggingTemplate", + "logging-args": { + "lol": "irrelevant, LoggingTemplate ignores these options lol" + } + } +} +``` + +## To-do + +- Add basic functionality + - Read `services.json` file + - Call the extensions +- Add support for logging and alert extensions +- Add maintenance windows (optionally recurring) + +--- + +***All specs are still a work-in-progress, breaking changes are likely!*** diff --git a/docs/extensions/README.md b/docs/extensions/README.md new file mode 100644 index 0000000..cf53621 --- /dev/null +++ b/docs/extensions/README.md @@ -0,0 +1,35 @@ +# Extensions + +Extensions go in the `./extensions/` folder, where exactly depends on which type of extension. + +- Extensions for checking status ("checkers") go in `./extensions/checkers/` +- Extensions for alerting go in `./extensions/alerts/` +- Extensions for logging go in `./extensions/logging/` + +Note that the folder name *must* be the same as the file name for the extension (excluding .py)! + +## Example + +```txt +. +├── extensions +│ ├── alerts +│ │ └── alerts_template +│ │ └── alerts_template.py +│ ├── checkers +│ │ └── checker_template +│ │ └── checker_template.py +│ └── logging +│ └── logging_template +│ └── logging_template.py +``` + +## List of extensions + +There are none yet, so consider this secret a placeholder + +### Checkers + +### Alerts + +## Logging \ No newline at end of file diff --git a/docs/extensions/checkers.md b/docs/extensions/checkers.md new file mode 100644 index 0000000..504b9a0 --- /dev/null +++ b/docs/extensions/checkers.md @@ -0,0 +1,62 @@ +# Uptime Checker Extensions + +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. + +Example extension: [askiiart/updog-checker_template](https://git.askiiart.net/askiiart/updog-checker_template) + +## 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. + +```txt +. +├── extensions +│ ├── alerts +│ └── alerts_template +│ └── alerts_template.py +``` + +## 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" +} +``` diff --git a/readme.md b/readme.md deleted file mode 100644 index 70742a9..0000000 --- a/readme.md +++ /dev/null @@ -1,106 +0,0 @@ -# Updog - -## What's updog? - -Not much, you? - -(it's a simple, extensible uptime monitor) - -## Warning - -**Extensions will be executed with no safety checks!** Make sure an extension isn't malicious before adding it. - -## Uptime Checker Extensions - - - -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!*** diff --git a/main.py b/updog.py similarity index 100% rename from main.py rename to updog.py