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
+    }
+  }
+  registerFeature: (type: string, id: string) => void
+
   getCourse: () => Promise<CourseInfo>
   clearDestination: () => Promise<void>
   setDestination: (

src/api/course/index.ts

@@ -27,6 +27,7 @@ const { Location, RoutePoint, VesselPosition } = COURSE_POINT_TYPES
 import { isValidCoordinate } from 'geolib'
 import { Responses } from '../'
 import { Store } from '../../serverstate/store'
+import { WithFeatures } from '../../app'
 
 import { buildSchemaSync } from 'api-schema-builder'
 import courseOpenApi from './openApi.json'
@@ -46,6 +47,7 @@ interface CourseApplication
   extends IRouter,
     WithConfig,
     WithSecurityStrategy,
+    WithFeatures,
     SignalKMessageHub {}
 
 export class CourseApi {
@@ -65,6 +67,7 @@ export class CourseApi {
     private resourcesApi: ResourcesApi
   ) {
     this.store = new Store(server, 'course')
+    server.registerFeature('api', 'course')
   }
 
   async start() {

src/api/features/index.ts

@@ -0,0 +1,52 @@
+/* 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 SIGNALK_API_PATH = `/signalk/v2/api`
+const FEATURES_API_PATH = `${SIGNALK_API_PATH}/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 server: FeaturesApplication) {}
+
+  async start() {
+    // eslint-disable-next-line no-async-promise-executor
+    return new Promise<void>(async (resolve) => {
+      this.initApiRoutes()
+      resolve()
+    })
+  }
+
+  private initApiRoutes() {
+    debug(`** Initialise ${FEATURES_API_PATH} path handlers **`)
+    // return Feature information
+    this.server.get(
+      `${FEATURES_API_PATH}`,
+      async (req: Request, res: Response) => {
+        debug(`** GET ${FEATURES_API_PATH}`)
+        res.json(this.server.getFeatures())
+      }
+    )
+  }
+}

src/api/features/openApi.json

@@ -0,0 +1,142 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "version": "2.0.0",
+    "title": "Signal K Features API",
+    "termsOfService": "http://signalk.org/terms/",
+    "license": {
+      "name": "Apache 2.0",
+      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+    }
+  },
+  "externalDocs": {
+    "url": "http://signalk.org/specification/",
+    "description": "Signal K specification."
+  },
+  "tags": [
+    {
+      "name": "features",
+      "description": "Signal K Server features."
+    }
+  ],
+  "components": {
+    "schemas": {
+      "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": {
+      "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": {
+    "/": {
+      "get": {
+        "tags": ["features"],
+        "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/features/openApi.ts

@@ -0,0 +1,8 @@
+import { OpenApiDescription } from '../swagger'
+import featuresApiDoc from './openApi.json'
+
+export const featuresApiRecord = {
+  name: 'features',
+  path: '/signalk/v2/api/features',
+  apiDoc: featuresApiDoc as unknown as OpenApiDescription
+}

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 './features'
 import { ResourcesApi } from './resources'
 
 export interface ApiResponse {
@@ -37,13 +38,18 @@ export const Responses = {
 }
 
 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
   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()])
+  const featuresApi = new FeaturesApi(app)
+  Promise.all([resourcesApi.start(), courseApi.start(), featuresApi.start()])
 }

src/api/resources/index.ts

@@ -18,7 +18,7 @@ import { WithSecurityStrategy } from '../../security'
 
 import { Responses } from '../'
 import { validate } from './validate'
-import { SignalKMessageHub } from '../../app'
+import { SignalKMessageHub, WithFeatures } from '../../app'
 
 export const RESOURCES_API_PATH = `/signalk/v2/api/resources`
 
@@ -27,13 +27,15 @@ export const skUuid = () => `${uuidv4()}`
 interface ResourceApplication
   extends IRouter,
     WithSecurityStrategy,
+    WithFeatures,
     SignalKMessageHub {}
 
 export class ResourcesApi {
   private resProvider: { [key: string]: Map<string, ResourceProviderMethods> } =
     {}
 
   constructor(app: ResourceApplication) {
+    app.registerFeature('api', 'resources')
     this.initResourceRoutes(app)
   }
 

src/api/swagger.ts

@@ -3,6 +3,7 @@ import { IRouter, NextFunction, Request, Response } from 'express'
 import swaggerUi from 'swagger-ui-express'
 import { SERVERROUTESPREFIX } from '../constants'
 import { courseApiRecord } from './course/openApi'
+import { featuresApiRecord } from './features/openApi'
 import { notificationsApiRecord } from './notifications/openApi'
 import { resourcesApiRecord } from './resources/openApi'
 import { securityApiRecord } from './security/openApi'
@@ -28,6 +29,7 @@ const apiDocs = [
   appsApiRecord,
   securityApiRecord,
   courseApiRecord,
+  featuresApiRecord,
   notificationsApiRecord,
   resourcesApiRecord
 ].reduce<ApiRecords>((acc, apiRecord: OpenApiRecord) => {

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
+  }
+}
+
+export interface WithFeatures {
+  getFeatures: () => FeaturesCollection
+  registerFeature: (type: string, id: string) => void
+}

src/index.ts

@@ -39,7 +39,13 @@ import https from 'https'
 import _ from 'lodash'
 import path from 'path'
 import { startApis } from './api'
-import { SelfIdentity, ServerApp, SignalKMessageHub, WithConfig } from './app'
+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,32 @@ class Server {
 
     app.providerStatus = {}
 
+    // feature registration
+    app.apiList = []
+
+    app.registerFeature = (type: string, id: string) => {
+      if (type === 'api' && !app.apiList.includes(id)) {
+        app.apiList.push(id)
+      }
+    }
+
+    // feature detection
+    app.getFeatures = () => {
+      const features = {
+        apis: [],
+        plugins: []
+      }
+      features.plugins = app.plugins.map((plugin: any) => {
+        return {
+          id: plugin.id,
+          name: plugin.name,
+          version: plugin.version
+        }
+      })
+      features.apis = app.apiList.slice()
+      return features
+    }
+
     // create first temporary pluginManager to get typechecks, as
     // app is any and not typechecked
     // TODO separate app.plugins and app.pluginsMap from app