Feature request: Provide a way to stop / shutdown a connected GatewayAPI

[rmelick-muon]

Hi,

We've been integrating the GatewayAPI into our application, and have successfully used the connect_with_retries method to establish a long lived connection from our app to Major Tom. However, when we want to shut down our application (for example, when redeploying), we couldn't find a way to gracefully stop the GatewayAPI.

The documentation for the websockets library that is used by GatewayAPI recommends closing the websocket, but the current connect_with_retries method will then immediately try to reconnect. It's good that normally it tries to reconnect closed sockets, since this can handle MajorTom restarts, temporary internet outages, etc., but it's bad when we're trying to shut down our end.

It would be great if there was a stop or shutdown method we could invoke on a connected GatewayAPI that would allow it to gracefully terminate without trying to reconnect.

We've gone ahead and prototyped this in our own wrapper code by creating a slightly different connect_with_retries method.

We added a shutdown_requested internal field, and check that if we get a closed connection, but it means we're modifying more of the internal state of the GatewayAPI than I would like (since we're interacting directly with the websocket)

class MajorTomIntegration:
    def __init__(
        self,
        majortom_host: str,
        api_token: str,
    ) -> None:
        self.gateway_api = GatewayAPI(
            host=majortom_host,
            gateway_token=api_token,
            command_callback=self.command_callback,
            error_callback=self.error_callback,
            rate_limit_callback=self.rate_limit_callback,
            cancel_callback=self.cancel_callback,
            transit_callback=self.upcoming_transit_callback,
            received_blob_callback=self.log_unimplemented_method_callback,
        )

        self._shutdown_requested = False

  async def connect_with_retries(self) -> None:
        while True:
            try:
                await self.gateway_api.connect()
                return
            except wsexceptions.ConnectionClosed as e:
                self.gateway_api.websocket = None
                # here is where we introduce the new logic quit this loop during shutdown
                if self._shutdown_requested:
                    log.info("Shutdown requested, MajorTom websocket has been closed")
                    return
                else:
                    log.warning(
                        "MajorTom Websocket has been closed, retrying in 5 seconds ({})".format(
                            e
                        )
                    )
                    await asyncio.sleep(5)
            except (OSError, IncompleteReadError) as e:
                self.gateway_api.websocket = None
                log.warning(
                    "Connection error encountered, retrying in 5 seconds ({})".format(e)
                )
                await asyncio.sleep(5)
            ....
   
  async def shutdown(self) -> None:
        log.info("Beginning to shut down MajorTom")
        self._shutdown_requested = True
        if self.gateway_api.websocket:
            await self.gateway_api.websocket.close()
        else:
            log.warning(
                "Could not find open websocket to MajorTom, shutdown will not function"
            )