add server status API endpoint

Author: bollwyvl

py_src/jupyter_lsp/handlers.py

@@ -41,12 +41,20 @@ def on_close(self):
 
 
 class LanguageServersHandler(BaseHandler):
+    """ Reports the status of all current servers
+
+        Response should conform to schema in schema/servers.schema.json
+    """
+
     def get(self):
+        """ finish with the JSON representations of the sessions
+        """
         self.finish(
             {
+                "version": 0,
                 "sessions": sorted(
                     [session.to_json() for session in self.manager.sessions.values()],
                     key=lambda session: session["languages"],
-                )
+                ),
             }
         )

py_src/jupyter_lsp/schema/__init__.py

@@ -6,7 +6,9 @@
 HERE = pathlib.Path(__file__).parent
 
 
-def servers_schema():
+def servers_schema() -> jsonschema.validators.Draft7Validator:
+    """ return a JSON Schema Draft 7 validator for the server status API
+    """
     return jsonschema.validators.Draft7Validator(
         json.loads((HERE / "servers.schema.json").read_text())
     )

py_src/jupyter_lsp/schema/servers.schema.json

@@ -1,21 +1,32 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$ref": "#/definitions/servers-response",
+  "title": "jupyter_lsp server status response",
+  "description": "describes the current state of (potentially) running language servers",
   "definitions": {
     "servers-response": {
       "type": "object",
       "properties": {
         "sessions": {
           "type": "array",
+          "description": "a list of servers that are, could be, or were running",
           "items": { "$ref": "#/definitions/session" }
+        },
+        "version": {
+          "type": "integer",
+          "description": "the version of the schema",
+          "enum": [0]
         }
       },
-      "required": ["sessions"]
+      "required": ["sessions", "version"]
     },
     "nullable-date-time": {
+      "description": "a date/time that might not have been recorded",
       "oneOf": [{ "type": "string", "format": "date-time" }, { "type": "null" }]
     },
     "session": {
+      "title": "Language Server Session",
+      "description": "a language server session",
       "additionalProperties": false,
       "required": [
         "languages",
@@ -26,20 +37,29 @@
       ],
       "properties": {
         "languages": {
+          "description": "languages supported by this Language Server",
           "type": "array",
-          "items": {"type": "string"},
+          "items": { "type": "string" },
           "uniqueItems": true,
           "minItems": 1
         },
-        "handler_count": { "type": "integer", "minValue": 0 },
+        "handler_count": {
+          "title": "handler count",
+          "description": "the count of currently-connected WebSocket handlers",
+          "type": "integer",
+          "minValue": 0
+        },
         "status": {
+          "description": "a string describing the current state of the server",
           "type": "string",
           "enum": ["not_started", "starting", "started", "stopping", "stopped"]
         },
         "last_server_message_at": {
+          "description": "date-time of last seen message from the language server",
           "$ref": "#/definitions/nullable-date-time"
         },
         "last_handler_message_at": {
+          "description": "date-time of last seen message from a WebSocket handler",
           "$ref": "#/definitions/nullable-date-time"
         }
       }

py_src/jupyter_lsp/tests/test_session.py

@@ -9,7 +9,8 @@ def assert_status_set(handler, expected_statuses, language=None):
     handler.get()
     payload = handler._payload
 
-    SERVERS_SCHEMA.validate(payload)
+    errors = list(SERVERS_SCHEMA.iter_errors(payload))
+    assert not errors
 
     statuses = {
         s["status"]
@@ -60,11 +61,17 @@ async def test_start_unknown(known_unknown_language, handlers, jsonrpc_init_msg)
     handler, ws_handler = handlers
     manager = handler.manager
     manager.initialize()
+
+    assert_status_set(handler, {"not_started"})
+
     ws_handler.open(known_unknown_language)
     assert not list(manager.sessions_for_handler(ws_handler))
 
-    ws_handler.on_message(jsonrpc_init_msg)
+    assert_status_set(handler, {"not_started"})
 
+    ws_handler.on_message(jsonrpc_init_msg)
+    assert_status_set(handler, {"not_started"})
     ws_handler.on_close()
 
     assert not list(manager.sessions_for_handler(ws_handler))
+    assert_status_set(handler, {"not_started"})