Move docs to docs folder, rename files

This commit is contained in:
askiiart 2024-01-29 17:26:50 -06:00
parent 082ffbe79a
commit c933b5a8a1
Signed by untrusted user who does not match committer: askiiart
GPG key ID: BC3800E55FB54D67
5 changed files with 152 additions and 106 deletions

55
README.md Normal file
View file

@ -0,0 +1,55 @@
# 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.
## 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!***

35
docs/extensions/README.md Normal file
View file

@ -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

View file

@ -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"
}
```

106
readme.md
View file

@ -1,106 +0,0 @@
# 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!***

View file