mirror of
https://github.com/EDCD/EDMarketConnector.git
synced 2025-04-14 00:07:14 +03:00
updated docs
This commit is contained in:
A_D
parent
c86b9790ca
commit
5a080c8e55
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user