diff --git a/docs/Killswitches.md b/docs/Killswitches.md index 8b6c9398..92c3d317 100644 --- a/docs/Killswitches.md +++ b/docs/Killswitches.md @@ -1,10 +1,13 @@ # 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 -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 | | --------------: | :------: | :------------------------------------------------------------------------------------------- | @@ -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) | | `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 | | --------: | :---------------------------: | :--------------------------------------------------------------------------- | | `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 | -Each entry in `kills` must contain at least a `reason` field describing why the killswitch was added. EDMC will show -this to the user (for internal killswitches, anyway). +Each entry in `kills` must contain at least a `reason` field describing why the +killswitch was added. EDMC will show this to the user +(for internal killswitches, anyway). | 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" | | `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 -then all delete fields are deleted. +The order listed above is the precedence for actions. i.e. All set fields are +set, then all redact fields are redacted then all delete fields are deleted. 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.some_plugin.some_thing` will never be allowed to continue (as all fields are blank) +- `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.some_plugin.some_thing` will never be allowed to continue + (as all fields are blank) ### Versions -Versions are checked using contains checks on `semantic_version.SimpleSpec` 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.*`), +Versions are checked using contains checks on `semantic_version.SimpleSpec` +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`) ## Plugin support -Plugins may use the killswitch system simply by hosting their own version of the killswitch file, and fetching it -using `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. +Plugins may use the killswitch system simply by hosting their own version of the +killswitch file, and fetching it using +`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 -KillSwitches. It starts a new thread, performs the HTTP request, and sends the results to the given callback. +A helper method `killswitch.get_kill_switch_thread` is provided to allow for +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** -**methods** +**Note that your callback is invoked off-thread. Take precaution for locking** +**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. -No behaviour changes will occur--Any killswitches defined in older versions will simply become unconditional kills in -the new version. +The version of the JSON file will be automatically upgraded if possible by the +code KillSwitch code. No behaviour changes will occur, any killswitches defined +in older versions will simply become unconditional kills in the new version. ## 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 | | :------------------------------------------- | :---------------------: | :---------------------------------------------------------------------------------------- | @@ -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>.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 -will simply stop processing. +Killswitches marked with `*` do **not** support modification of their values via +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 -inara events +For `plugin.inara.worker`, events are checked individually later by the +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 -The main killswitch file is kept in the `releases` branch on the EDMC github 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 +The main killswitch file is kept in the `releases` branch on the EDMC github +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.