ED/EDMarketConnector
1
0
Fork 0
mirror of https://github.com/EDCD/EDMarketConnector.git synced 2025-06-06 18:33:13 +03:00
Code Issues Projects Releases Wiki Activity

updated docs

Browse Source
This commit is contained in:
A_D 2021-08-19 19:49:39 +02:00
parent c86b9790ca
commit 5a080c8e55
No known key found for this signature in database
GPG Key ID: 4BE9EB7DF45076C4
1 changed files with 43 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
docs/Killswitches.md
View File

@ -1,10 +1,13 @@
# Kill Switches # Kill Switches
EDMarketConnector implements a Kill Switch system that allows us to disable features based on a version mask. Meaning that we can stop major bugs from affecting the services we support, at the expense of disabling that support. EDMarketConnector implements a Kill Switch system that allows us to disable
features based on a version mask. Meaning that we can stop major bugs from
affecting the services we support, at the expense of disabling that support.
## Format ## Format
Killswitches are stored in a JSON file that is queried by EDMC on startup. The format is as follows: Killswitches are stored in a JSON file that is queried by EDMC on startup.
The format is as follows:
| Key | Type | Description | | Key | Type | Description |
| --------------: | :------: | :------------------------------------------------------------------------------------------- | | --------------: | :------: | :------------------------------------------------------------------------------------------- |
@ -12,15 +15,17 @@ Killswitches are stored in a JSON file that is queried by EDMC on startup. The f
| `last_updated` | `string` | When last the kill switches were updated (for human use only) | | `last_updated` | `string` | When last the kill switches were updated (for human use only) |
| `kill_switches` | `array` | The kill switches this file contains (expanded below) | | `kill_switches` | `array` | The kill switches this file contains (expanded below) |
The `kill_switches` array contains kill switch objects. Each contains the following fields: The `kill_switches` array contains kill switch objects. Each contains the
following fields:
| Key | Type | Description | | Key | Type | Description |
| --------: | :---------------------------: | :--------------------------------------------------------------------------- | | --------: | :---------------------------: | :--------------------------------------------------------------------------- |
| `version` | `version spec (see Versions)` | The version of EDMC these kill switches apply to (Must be valid semver spec) | | `version` | `version spec (see Versions)` | The version of EDMC these kill switches apply to (Must be valid semver spec) |
| `kills` | `Dict[str, Dict[...]]` | The various keys disabled -> definition of the killswitch behaviour | | `kills` | `Dict[str, Dict[...]]` | The various keys disabled -> definition of the killswitch behaviour |
Each entry in `kills` must contain at least a `reason` field describing why the killswitch was added. EDMC will show Each entry in `kills` must contain at least a `reason` field describing why the
this to the user (for internal killswitches, anyway). killswitch was added. EDMC will show this to the user
(for internal killswitches, anyway).
| Key (* = required) | Type | Description | | Key (* = required) | Type | Description |
| -----------------: | :--------------: | :-------------------------------------------------------------------------------------------- | | -----------------: | :--------------: | :-------------------------------------------------------------------------------------------- |
@ -29,8 +34,8 @@ this to the user (for internal killswitches, anyway).
| `redact_fields` | `List[str]` | A list of fields to redact. This is equivalent to setting the fields to the string "REDACTED" | | `redact_fields` | `List[str]` | A list of fields to redact. This is equivalent to setting the fields to the string "REDACTED" |
| `delete_fields` | `List[str]` | A list of fields in the matching event to be removed, if they exist. | | `delete_fields` | `List[str]` | A list of fields in the matching event to be removed, if they exist. |
The order listed above is the precedence for actions. i.e. All set fields are set, then all redact fields are redacted The order listed above is the precedence for actions. i.e. All set fields are
then all delete fields are deleted. set, then all redact fields are redacted then all delete fields are deleted.
An example follows: An example follows:
@ -60,35 +65,42 @@ An example follows:
} }
``` ```
- `plugins.edsm.send` will have fields deleted, set, and redacted, and then will *not* be halted, the send will continue with the modified data. - `plugins.edsm.send` will have fields deleted, set, and redacted, and then
- `plugins.some_plugin.some_thing` will never be allowed to continue (as all fields are blank) will *not* be halted, the send will continue with the modified data.
- `plugins.some_plugin.some_thing` will never be allowed to continue
(as all fields are blank)
### Versions ### Versions
Versions are checked using contains checks on `semantic_version.SimpleSpec` instances. SimpleSpec supports both specific Versions are checked using contains checks on `semantic_version.SimpleSpec`
versions (`1.2.3`), non-specific ranges (`1.0` will match `1.0.1` and `1.0.5` etc), wildcards (`1.2.*`), instances. SimpleSpec supports both specific versions (`1.2.3`), non-specific
ranges (`1.0` will match `1.0.1` and `1.0.5` etc), wildcards (`1.2.*`),
and ranges (`<1.0.0`, `>=2.0.0`) and ranges (`<1.0.0`, `>=2.0.0`)
## Plugin support ## Plugin support
Plugins may use the killswitch system simply by hosting their own version of the killswitch file, and fetching it Plugins may use the killswitch system simply by hosting their own version of the
using `killswitch.get_kill_switches(target='https://example.com/myplugin_killswitches.json')`. The returned object can killswitch file, and fetching it using
be used to query the kill switch set, see the docstrings for more information on specifying versions. `killswitch.get_kill_switches(target='https://example.com/myplugin_killswitches.json')`.
The returned object can be used to query the kill switch set, see the docstrings
for more information on specifying versions.
A helper method `killswitch.get_kill_switch_thread` is provided to allow for simple nonblocking requests for A helper method `killswitch.get_kill_switch_thread` is provided to allow for
KillSwitches. It starts a new thread, performs the HTTP request, and sends the results to the given callback. simple nonblocking requests for KillSwitches. It starts a new thread, performs
the HTTP request, and sends the results to the given callback.
**Note that your callback is invoked off-thread. Take precaution for locking if required, and do _NOT_ use tkinter** **Note that your callback is invoked off-thread. Take precaution for locking**
**methods** **if required, and do _NOT_ use tkinter methods**
The version of the JSON file will be automatically upgraded if possible by the code KillSwitch code. The version of the JSON file will be automatically upgraded if possible by the
No behaviour changes will occur--Any killswitches defined in older versions will simply become unconditional kills in code KillSwitch code. No behaviour changes will occur, any killswitches defined
the new version. in older versions will simply become unconditional kills in the new version.
## Currently supported killswitch strings ## Currently supported killswitch strings
The current recognised (to EDMC and its internal plugins) killswitch strings are as follows: The current recognised (to EDMC and its internal plugins) killswitch strings are
as follows:
| Kill Switch | Supported Plugins | Description | | Kill Switch | Supported Plugins | Description |
| :------------------------------------------- | :---------------------: | :---------------------------------------------------------------------------------------- | | :------------------------------------------- | :---------------------: | :---------------------------------------------------------------------------------------- |
@ -98,14 +110,17 @@ The current recognised (to EDMC and its internal plugins) killswitch strings are
| `plugins.<plugin>.worker.<eventname>` | edsm, inara | Disables the plugin worker for the given eventname | | `plugins.<plugin>.worker.<eventname>` | edsm, inara | Disables the plugin worker for the given eventname |
| `plugins.<plugin>.journal.event.<eventname>` | eddn, inara, edsm | Specific events to disable processing for. | | `plugins.<plugin>.journal.event.<eventname>` | eddn, inara, edsm | Specific events to disable processing for. |
Killswitches marked with `*` do **not** support modification of their values via set/redact/delete. And as such any match Killswitches marked with `*` do **not** support modification of their values via
will simply stop processing. set/redact/delete. And as such any match will simply stop processing.
For `plugin.inara.worker`, events are checked individually later by the eventname version. Use that to modify individual For `plugin.inara.worker`, events are checked individually later by the
inara events eventname version. Use that to modify individual inara events. This is due to
inara event batching meaning that the data that would be passed to `.worker`
would not be in a form that could be easily understood (except to blank it)
## File location ## File location
The main killswitch file is kept in the `releases` branch on the EDMC github repo. The file should NEVER be committed to The main killswitch file is kept in the `releases` branch on the EDMC github
any other repos. In the case that the killswitch file is found in other repos, the one in releases should always repo. The file should NEVER be committed to any other repos. In the case that
the killswitch file is found in other repos, the one in releases should always
be taken as correct regardless of others. be taken as correct regardless of others.