CAPI killswitches: endpoint killswitches & eddn export ones too

* Added `capi.request.<endpoint>` killswitches at appropriate call points.
* Added `eddn.capi_export.<type>` killswitches.  This allows for killing
  just the EDDN export of such CAPI-derived data, without stopping the actual
  queries, as other plugins/functionality might still have harmless use of
  the data.
* PLUGINS.md: Actually describe the contents of `data` passed to plugins, and
  point out it might not always contain market or shipyard data.  This is
  not only because of the new killswitches, but could already have happened
  if the station/port docked at didn't have the services.
* Some misc typing cleanups.

EDMarketConnector.py

@@ -1228,6 +1228,11 @@ class AppWindow(object):
                 if err:
                     play_bad = True
 
+                should_return, new_data = killswitch.check_killswitch('capi.request./market', {})
+                if should_return:
+                    logger.warning("capi.request./market has been disabled by killswitch.  Returning.")
+
+                else:
                     # Export market data
                     if not self.export_market_data(capi_response.capi_data):
                         err = 'Error: Exporting Market data'

PLUGINS.md

@@ -910,10 +910,9 @@ constants.
 
 ### Commander Data from Frontier CAPI
 If a plugin has a `cmdr_data()` function it gets called when the application
-has just fetched fresh Cmdr and station data from Frontier's servers, **but not
+has just fetched fresh Cmdr and station data from Frontier's CAPI servers,
-for the Legacy galaxy**.  See `cmdr_data_legacy()` below for Legacy data
+**but not for the Legacy galaxy**.  See `cmdr_data_legacy()` below for Legacy
-handling.
+data handling.
-
 ```python
 from companion import CAPIData, SERVER_LIVE, SERVER_LEGACY, SERVER_BETA
 
@@ -948,6 +947,16 @@ have extra properties, such as `source_host`, as shown above.  Plugin authors
 are free to use *that* property, **but MUST NOT rely on any other extra
 properties present in `CAPIData`, they are for internal use only.**
 
+The contents of `data` will always have at least the data returned by a CAPI
+`/profile` query.  If the player is docked at a station, and the relevant
+services are available then the `lastStarport` key's value will have been
+augmented with `/market` and/or `/shipyard` data.  **But do not assume this
+will always be the case**.
+
+If there is a killswitch in effect for some of the CAPI endpoints, then the
+data passed to this function might not be as complete as you expect.  Code
+defensively.
+
 
 #### CAPI data for Legacy
 When CAPI data has been retrieved from the separate CAPI host for the Legacy

companion.py

@@ -601,7 +601,7 @@ class EDMCCAPIFailedRequest(EDMCCAPIReturn):
     ):
         super().__init__(query_time=query_time, play_sound=play_sound, auto_update=auto_update)
         self.message: str = message  # User-friendly reason for failure.
-        self.exception: int = exception  # Exception that recipient should raise.
+        self.exception: BaseException = exception  # Exception that recipient should raise.
 
 
 class Session(object):
@@ -772,7 +772,12 @@ class Session(object):
             :param timeout: requests query timeout to use.
             :return: The resulting CAPI data, of type CAPIData.
             """
-            capi_data: CAPIData
+            capi_data: CAPIData = CAPIData()
+            should_return, new_data = killswitch.check_killswitch('capi.request.' + capi_endpoint, {})
+            if should_return:
+                logger.warning(f"capi.request.{capi_endpoint} has been disabled by killswitch.  Returning.")
+                return capi_data
+
             try:
                 logger.trace_if('capi.worker', 'Sending HTTP request...')
                 if conf_module.capi_pretend_down:
@@ -854,6 +859,10 @@ class Session(object):
             """
             station_data = capi_single_query(capi_host, self.FRONTIER_CAPI_PATH_PROFILE, timeout=timeout)
 
+            if not station_data.get('commander'):
+                # If even this doesn't exist, probably killswitched.
+                return station_data
+
             if not station_data['commander'].get('docked') and not monitor.state['OnFoot']:
                 return station_data
 
@@ -894,6 +903,10 @@ class Session(object):
 
             if services.get('commodities'):
                 market_data = capi_single_query(capi_host, self.FRONTIER_CAPI_PATH_MARKET, timeout=timeout)
+                if not market_data.get('id'):
+                    # Probably killswitched
+                    return station_data
+
                 if last_starport_id != int(market_data['id']):
                     logger.warning(f"{last_starport_id!r} != {int(market_data['id'])!r}")
                     raise ServerLagging()
@@ -904,6 +917,10 @@ class Session(object):
 
             if services.get('outfitting') or services.get('shipyard'):
                 shipyard_data = capi_single_query(capi_host, self.FRONTIER_CAPI_PATH_SHIPYARD, timeout=timeout)
+                if not shipyard_data.get('id'):
+                    # Probably killswitched
+                    return station_data
+
                 if last_starport_id != int(shipyard_data['id']):
                     logger.warning(f"{last_starport_id!r} != {int(shipyard_data['id'])!r}")
                     raise ServerLagging()

plugins/eddn.py

@@ -636,6 +636,16 @@ class EDDN:
         :param data: a dict containing the starport data
         :param is_beta: whether or not we're currently in beta mode
         """
+        should_return, new_data = killswitch.check_killswitch('capi.request./market', {})
+        if should_return:
+            logger.warning("capi.request./market has been disabled by killswitch.  Returning.")
+            return
+
+        should_return, new_data = killswitch.check_killswitch('eddn.capi_export.commodities', {})
+        if should_return:
+            logger.warning("eddn.capi_export.commodities has been disabled by killswitch.  Returning.")
+            return
+
         modules, ships = self.safe_modules_and_ships(data)
         horizons: bool = capi_is_horizons(
             data['lastStarport'].get('economies', {}),
@@ -757,6 +767,16 @@ class EDDN:
         :param data: dict containing the outfitting data
         :param is_beta: whether or not we're currently in beta mode
         """
+        should_return, new_data = killswitch.check_killswitch('capi.request./shipyard', {})
+        if should_return:
+            logger.warning("capi.request./shipyard has been disabled by killswitch.  Returning.")
+            return
+
+        should_return, new_data = killswitch.check_killswitch('eddn.capi_export.outfitting', {})
+        if should_return:
+            logger.warning("eddn.capi_export.outfitting has been disabled by killswitch.  Returning.")
+            return
+
         modules, ships = self.safe_modules_and_ships(data)
 
         # Horizons flag - will hit at least Int_PlanetApproachSuite other than at engineer bases ("Colony"),
@@ -813,6 +833,16 @@ class EDDN:
         :param data: dict containing the shipyard data
         :param is_beta: whether or not we are in beta mode
         """
+        should_return, new_data = killswitch.check_killswitch('capi.request./shipyard', {})
+        if should_return:
+            logger.warning("capi.request./shipyard has been disabled by killswitch.  Returning.")
+            return
+
+        should_return, new_data = killswitch.check_killswitch('eddn.capi_export.shipyard', {})
+        if should_return:
+            logger.warning("eddn.capi_export.shipyard has been disabled by killswitch.  Returning.")
+            return
+
         modules, ships = self.safe_modules_and_ships(data)
 
         horizons: bool = capi_is_horizons(
@@ -1857,7 +1887,7 @@ class EDDN:
         match = self.CANONICALISE_RE.match(item)
         return match and match.group(1) or item
 
-    def capi_gameversion_from_host_endpoint(self, capi_host: str, capi_endpoint: str) -> str:
+    def capi_gameversion_from_host_endpoint(self, capi_host: Optional[str], capi_endpoint: str) -> str:
         """
         Return the correct CAPI gameversion string for the given host/endpoint.