feature: Add Feature discovery API endpoint and plugin interface

packages/server-api/src/index.ts

@@ -172,6 +172,17 @@ export interface ServerAPI extends PluginServerApp {
     ) => void
   }) => void
   getSerialPorts: () => Promise<Ports>
+
+  getFeatures: () => {
+    apis: string[]
+    plugins: {
+      id: string
+      name: string
+      version: string
+      enabled: boolean
+    }
+  }
+
   getCourse: () => Promise<CourseInfo>
   clearDestination: () => Promise<void>
   setDestination: (

src/api/discovery/index.ts

@@ -0,0 +1,54 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { createDebug } from '../../debug'
+const debug = createDebug('signalk-server:api:features')
+
+import { IRouter, Request, Response } from 'express'
+
+import { SignalKMessageHub, WithConfig, WithFeatures } from '../../app'
+import { WithSecurityStrategy } from '../../security'
+
+const FEATURES_API_PATH = `/signalk/v2/features`
+
+interface FeaturesApplication
+  extends IRouter,
+    WithConfig,
+    WithFeatures,
+    WithSecurityStrategy,
+    SignalKMessageHub {}
+
+interface FeatureInfo {
+  apis: string[]
+  plugins: string[]
+}
+
+export class FeaturesApi {
+  private features: FeatureInfo = {
+    apis: [],
+    plugins: []
+  }
+
+  constructor(private app: FeaturesApplication) {}
+
+  async start() {
+    return new Promise<void>((resolve) => {
+      this.initApiRoutes()
+      resolve()
+    })
+  }
+
+  private initApiRoutes() {
+    debug(`** Initialise ${FEATURES_API_PATH} path handlers **`)
+    // return Feature information
+    this.app.get(
+      `${FEATURES_API_PATH}`,
+      async (req: Request, res: Response) => {
+        debug(`** GET ${FEATURES_API_PATH}`)
+        res.json(
+          await this.app.getFeatures(
+            typeof req.query.enabled !== 'undefined' ? true : false
+          )
+        )
+      }
+    )
+  }
+}

src/api/discovery/openApi.json

@@ -14,10 +14,19 @@
   },
   "servers": [
     {
-      "url": "/"
+      "url": "/signalk"
+    }
+  ],
+  "tags": [
+    {
+      "name": "server",
+      "description": "Signal K Server."
+    },
+    {
+      "name": "features",
+      "description": "Signal K Server features."
     }
   ],
-  "tags": [],
   "components": {
     "schemas": {
       "DiscoveryData": {
@@ -70,6 +79,46 @@
             }
           }
         }
+      },
+      "PluginMetaData": {
+        "type": "object",
+        "required": ["id", "name", "version"],
+        "description": "Plugin metadata.",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Plugin ID."
+          },
+          "name": {
+            "type": "string",
+            "description": "Plugin name."
+          },
+          "version": {
+            "type": "string",
+            "description": "Plugin verison."
+          }
+        }
+      },
+      "FeaturesModel": {
+        "type": "object",
+        "required": ["apis", "plugins"],
+        "description": "Features response",
+        "properties": {
+          "apis": {
+            "type": "array",
+            "description": "Implemented APIs.",
+            "items": {
+              "type": "string"
+            }
+          },
+          "plugins": {
+            "type": "array",
+            "description": "Installed Plugins.",
+            "items": {
+              "$ref": "#/components/schemas/PluginMetaData"
+            }
+          }
+        }
       }
     },
     "responses": {
@@ -82,21 +131,107 @@
             }
           }
         }
+      },
+      "200Ok": {
+        "description": "OK",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "state": {
+                  "type": "string",
+                  "enum": ["COMPLETED"]
+                },
+                "statusCode": {
+                  "type": "number",
+                  "enum": [200]
+                }
+              },
+              "required": ["state", "statusCode"]
+            }
+          }
+        }
+      },
+      "ErrorResponse": {
+        "description": "Failed operation",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "description": "Request error response",
+              "properties": {
+                "state": {
+                  "type": "string",
+                  "enum": ["FAILED"]
+                },
+                "statusCode": {
+                  "type": "number",
+                  "enum": [404]
+                },
+                "message": {
+                  "type": "string"
+                }
+              },
+              "required": ["state", "statusCode", "message"]
+            }
+          }
+        }
+      },
+      "FeaturesResponse": {
+        "description": "Server features response.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "description": "Features response.",
+              "$ref": "#/components/schemas/FeaturesModel"
+            }
+          }
+        }
       }
     }
   },
 
   "paths": {
-    "/signalk": {
+    "/": {
       "get": {
-        "tags": [],
+        "tags": ["server"],
+        "summary": "Retrieve server version and service endpoints.",
         "description": "Returns data about server's endpoints and versions.",
         "responses": {
           "200": {
             "$ref": "#/components/responses/DiscoveryResponse"
           }
         }
       }
+    },
+    "/v2/features": {
+      "get": {
+        "tags": ["features"],
+        "parameters": [
+          {
+            "name": "enabled",
+            "in": "query",
+            "description": "Limit results to enabled features.",
+            "required": false,
+            "explode": false,
+            "schema": {
+              "type": "string",
+              "enum": ["enabled"]
+            }
+          }
+        ],
+        "summary": "Retrieve available server features.",
+        "description": "Returns object detailing the available server features.",
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/FeaturesResponse"
+          },
+          "default": {
+            "$ref": "#/components/responses/ErrorResponse"
+          }
+        }
+      }
     }
   }
 }

src/api/index.ts

@@ -1,7 +1,8 @@
 import { IRouter } from 'express'
-import { SignalKMessageHub, WithConfig } from '../app'
+import { SignalKMessageHub, WithConfig, WithFeatures } from '../app'
 import { WithSecurityStrategy } from '../security'
 import { CourseApi } from './course'
+import { FeaturesApi } from './discovery'
 import { ResourcesApi } from './resources'
 
 export interface ApiResponse {
@@ -36,14 +37,45 @@ export const Responses = {
   }
 }
 
+export type SIGNALK_API_ID =
+  | 'resources'
+  | 'course'
+  | 'history'
+  | 'autopilot'
+  | 'anchor'
+  | 'logbook'
+
+export const isSignalKApi = (id: SIGNALK_API_ID): boolean => {
+  return [
+    'resources',
+    'course',
+    'history',
+    'autopilot',
+    'anchor',
+    'logbook'
+  ].includes(id)
+}
+
+export const apiList: Array<SIGNALK_API_ID> = []
+
 export const startApis = (
-  app: SignalKMessageHub & WithSecurityStrategy & IRouter & WithConfig
+  app: SignalKMessageHub &
+    WithSecurityStrategy &
+    IRouter &
+    WithConfig &
+    WithFeatures
 ) => {
   const resourcesApi = new ResourcesApi(app)
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ;(app as any).resourcesApi = resourcesApi
+  apiList.push('resources')
+
   const courseApi = new CourseApi(app, resourcesApi)
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ;(app as any).courseApi = courseApi
-  Promise.all([resourcesApi.start(), courseApi.start()])
+  apiList.push('course')
+
+  const featuresApi = new FeaturesApi(app)
+
+  Promise.all([resourcesApi.start(), courseApi.start(), featuresApi.start()])
 }

src/app.ts

@@ -33,3 +33,17 @@ export interface SelfIdentity {
   selfId: string
   selfContext: string
 }
+
+interface FeaturesCollection {
+  apis: string[]
+  plugins: {
+    id: string
+    name: string
+    version: string
+    enabled: boolean
+  }
+}
+
+export interface WithFeatures {
+  getFeatures: (enabledOnly?: boolean) => FeaturesCollection
+}

src/index.ts

@@ -38,8 +38,14 @@ import http from 'http'
 import https from 'https'
 import _ from 'lodash'
 import path from 'path'
-import { startApis } from './api'
-import { SelfIdentity, ServerApp, SignalKMessageHub, WithConfig } from './app'
+import { startApis, apiList, isSignalKApi, SIGNALK_API_ID } from './api'
+import {
+  SelfIdentity,
+  ServerApp,
+  SignalKMessageHub,
+  WithConfig,
+  WithFeatures
+} from './app'
 import { ConfigApp, load, sendBaseDeltas } from './config/config'
 import { createDebug } from './debug'
 import DeltaCache from './deltacache'
@@ -72,6 +78,7 @@ class Server {
   app: ServerApp &
     SelfIdentity &
     WithConfig &
+    WithFeatures &
     SignalKMessageHub &
     PluginManager &
     WithSecurityStrategy &
@@ -116,6 +123,21 @@ class Server {
 
     app.providerStatus = {}
 
+    // feature detection
+    app.getFeatures = async (enabledOnly?: boolean) => {
+      const pluginApis = app.plugins
+        .filter((p: { feature: SIGNALK_API_ID }) => {
+          return p.feature && isSignalKApi(p.feature) ? true : false
+        })
+        .map((p: { feature: SIGNALK_API_ID }) => {
+          return p.feature
+        })
+      return {
+        apis: apiList.slice().concat(pluginApis),
+        plugins: await app.getPluginsWithFeature(enabledOnly)
+      }
+    }
+
     // create first temporary pluginManager to get typechecks, as
     // app is any and not typechecked
     // TODO separate app.plugins and app.pluginsMap from app