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.

Format

Killswitches are stored in a JSON file that is queried by EDMC on startup. The format is as follows:

Key	Type	Description
`version`	`int`	the version of the Kill Switch JSON file, always 2, 1 exists and will be upgraded if needed.
`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:

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).

Key (* = required)	Type	Description
`reason`*	`str`	The reason that this killswitch was added
`set_fields`	`Dict[str, Any]`	A map of key -> contents to update (or overwrite) existing data with
`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.

An example follows:

{
    "version": 2,
    "last_updated": "3 July 2021",
    "kill_switches": [
        {
            "version": "1.0.0",
            "kills": {
                "plugins.eddn.send": {
                    "reason": "some reason",
                    "delete_fields": ["world_domination_plans"],
                    "set_fields": {
                        "bad_bases_for_systems_of_government": ["Strange women lying in ponds distributing swords"],
                        "ruler_map": {"emperor": "scimitar"}
                    },
                    "redact_fields": ["relation_to_thargoids"]
                },
                "plugins.some_plugin.some_thing": {
                    "reason": "Some thing is disabled pending investigation of NMLA relations."
                }
            }
        }
    ]
}

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)

Testing

Killswitch files can be tested using the script in scripts/killswitch_test.py. Providing a file as an argument or - for stdin will output the behaviour of the provided file, including indicating typos, if applicable.

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.*), 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.

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

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:

Kill Switch	Supported Plugins	Description
`plugins.eddn.send`	eddn	Disables all use of the send method on EDDN (effectively disables EDDN updates)
`plugins.<plugin>.journal`	eddn, inara, edsm, eddb	Disables all journal processing for the plugin
`plugins.<plugin>.worker`	edsm, *inara	Disables the plugins worker thread (effectively disables updates) (does not close thread)
`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.

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 be taken as correct regardless of others.

7.2 KiB Raw Blame History