New: Add registerRoutes utility for non-API modules

docs/server-requests.md

@@ -1,8 +1,69 @@
 # Handling server requests
-This page gives you some pointers on how to handle incoming requests in a way that will reduce the work needed by you as a developer, and create consistent and easy-to-process responses. 
+This page gives you some pointers on how to handle incoming requests in a way that will reduce the work needed by you as a developer, and create consistent and easy-to-process responses.
+
+## Defining routes with `routes.json`
+
+For modules that expose HTTP endpoints, the preferred approach is to declare routes in a `routes.json` file in the module root. This keeps route definitions, permissions, and API metadata in one place.
+
+```json
+{
+  "root": "mymodule",
+  "routes": [
+    {
+      "route": "/action",
+      "handlers": { "post": "actionHandler" },
+      "permissions": { "post": ["write:myresource"] },
+      "meta": {
+        "post": {
+          "summary": "Perform an action",
+          "requestBody": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "name": { "type": "string" }
+                  }
+                }
+              }
+            }
+          },
+          "responses": { "204": {} }
+        }
+      }
+    }
+  ]
+}
+```
+
+Then in your module code, use `loadRouteConfig` and `registerRoutes` to load and wire up the routes:
+
+```javascript
+import { loadRouteConfig, registerRoutes } from 'adapt-authoring-server'
+
+async init () {
+  const [auth, server] = await this.app.waitForModule('auth', 'server')
+  const config = await loadRouteConfig(this.rootDir, this)
+  const router = server.api.createChildRouter(config.root)
+  registerRoutes(router, config.routes, auth)
+}
+```
+
+### Route properties
+
+| Property | Required | Description |
+| -------- | -------- | ----------- |
+| `route` | Yes | Express-style route path (e.g. `"/reset/:id"`) |
+| `handlers` | Yes | Object mapping HTTP methods to handler method names on the module |
+| `permissions` | No | Object mapping HTTP methods to scope arrays (secured) or `null` (unsecured) |
+| `meta` | No | Object mapping HTTP methods to OpenAPI operation metadata |
+| `internal` | No | When `true`, restricts the route to localhost |
+| `override` | No | When `true` and defaults are in use, merges this route onto the matching default route instead of adding a duplicate |
+
+Handler strings are resolved to bound methods on the module instance automatically.
 
 ## Extend the `AbstractApiModule` class
-If you're building a non-trivial API (particularly one that uses the database), we highly recommend that you use `AbstractApiModule` as a base, as this includes a lot of boilerplate code and helper functions to make handling HTTP requests much easier. See [this page](writing-an-api) for more info on using the `AbstractApiModule` class. 
+If you're building a non-trivial API (particularly one that uses the database), we highly recommend that you use `AbstractApiModule` as a base, as this includes a lot of boilerplate code and helper functions to make handling HTTP requests much easier. See [this page](writing-an-api) for more info on using the `AbstractApiModule` class.
 
 ## Use HTTP status codes
 This may go without saying, but please stick to standardised HTTP response codes; they state your intentions and make it nice and easy for other devs to work with and react to.
@@ -18,12 +79,12 @@ Using the helper function is as simple as:
 async myHandler(req, res, next) {
   try {
     // do some stuff
-  } catch() {
+  } catch (e) {
     res.sendError(e);
   }
 }
 ```
 
 See the Express.js documentation for information on the extra functions available:
-- [Request](https://expressjs.com/en/4x/api.html#req)
-- [Response](https://expressjs.com/en/4x/api.html#res)
+- [Request](https://expressjs.com/en/5x/api.html#req)
+- [Response](https://expressjs.com/en/5x/api.html#res)

index.js

@@ -2,5 +2,5 @@
  * HTTP server functionality using Express.js
  * @namespace server
  */
-export { addExistenceProps, cacheRouteConfig, generateRouterMap, getAllRoutes, loadRouteConfig, mapHandler } from './lib/utils.js'
+export { addExistenceProps, cacheRouteConfig, generateRouterMap, getAllRoutes, loadRouteConfig, mapHandler, registerRoutes } from './lib/utils.js'
 export { default } from './lib/ServerModule.js'

lib/utils.js

@@ -4,3 +4,4 @@ export { generateRouterMap } from './utils/generateRouterMap.js'
 export { getAllRoutes } from './utils/getAllRoutes.js'
 export { loadRouteConfig } from './utils/loadRouteConfig.js'
 export { mapHandler } from './utils/mapHandler.js'
+export { registerRoutes } from './utils/registerRoutes.js'

lib/utils/loadRouteConfig.js

@@ -38,6 +38,8 @@ function resolveHandlers (routes, target, aliases) {
  * @param {Object} [options.handlerAliases] Map of handler string aliases to pre-resolved functions
  * @param {String} [options.defaults] Path to a default routes template JSON file. When provided and
  *   routes.json is found, the template's routes are resolved and prepended to config.routes.
+ *   Custom routes with `override: true` are merged onto the matching default (by path) instead of
+ *   being appended as duplicates.
  * @return {Promise<Object|null>} Parsed config with resolved handlers, or null if no routes.json
  * @memberof server
  */
@@ -68,7 +70,20 @@ export async function loadRouteConfig (rootDir, target, options = {}) {
   if (options.defaults) {
     const template = await readJson(options.defaults)
     const defaultRoutes = resolveHandlers(template.routes || [], target, aliases)
-    config.routes = [...defaultRoutes, ...customRoutes]
+    // Apply override routes onto matching defaults
+    const overrides = new Map(
+      customRoutes.filter(r => r.override).map(r => [r.route, r])
+    )
+    const matched = new Set()
+    const mergedDefaults = defaultRoutes.map(d => {
+      const o = overrides.get(d.route)
+      if (!o) return d
+      matched.add(d.route)
+      const { override, ...rest } = o
+      return { ...d, ...rest, handlers: { ...d.handlers, ...rest.handlers } }
+    })
+    const remaining = customRoutes.filter(r => !r.override || !matched.has(r.route))
+    config.routes = [...mergedDefaults, ...remaining]
   } else {
     config.routes = customRoutes
   }

lib/utils/registerRoutes.js

@@ -0,0 +1,20 @@
+/**
+ * Registers routes on a router and configures their permissions with auth.
+ * @param {Router} router The router to add routes to
+ * @param {Array} routes Array of route definition objects
+ * @param {Object} auth The auth module instance
+ * @memberof server
+ */
+export function registerRoutes (router, routes, auth) {
+  for (const r of routes) {
+    router.addRoute(r)
+    if (!r.permissions) continue
+    for (const [method, perms] of Object.entries(r.permissions)) {
+      if (perms) {
+        auth.secureRoute(`${router.path}${r.route}`, method, perms)
+      } else {
+        auth.unsecureRoute(`${router.path}${r.route}`, method)
+      }
+    }
+  }
+}

schema/routeitem.schema.json

@@ -33,6 +33,11 @@
       "type": "object",
       "description": "Keys are HTTP methods, values are OpenAPI operation objects",
       "propertyNames": { "enum": ["get", "post", "put", "patch", "delete"] }
+    },
+    "override": {
+      "type": "boolean",
+      "description": "When true and a defaults template is in use, merges this route's properties onto the matching default route (by path) instead of adding a duplicate",
+      "default": false
     }
   },
   "required": ["route", "handlers"]

tests/utils-loadRouteConfig.spec.js

@@ -383,5 +383,96 @@ describe('loadRouteConfig()', () => {
       assert.equal(config.routes[0].permissions.post, null)
       assert.equal(config.routes[0].meta.post.summary, 'Test')
     })
+
+    it('should merge override route properties onto matching default route', async () => {
+      const dir = path.join(tmpDir, 'override-merge')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{
+          route: '/',
+          override: true,
+          handlers: { post: 'myHandler' },
+          meta: { post: { summary: 'Overridden' } }
+        }]
+      })
+      const defaultsPath = path.join(tmpDir, 'override-defaults.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { post: 'myHandler' }, permissions: { post: null } }]
+      })
+      const config = await loadRouteConfig(dir, { myHandler: () => {} }, { defaults: defaultsPath })
+      assert.equal(config.routes.length, 1)
+      assert.equal(config.routes[0].route, '/')
+      assert.equal(config.routes[0].meta.post.summary, 'Overridden')
+      assert.equal(config.routes[0].permissions.post, null)
+    })
+
+    it('should keep default handler when override does not replace it', async () => {
+      const dir = path.join(tmpDir, 'override-keep-handler')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{
+          route: '/',
+          override: true,
+          handlers: { post: 'myHandler' },
+          meta: { post: { summary: 'Added meta' } }
+        }]
+      })
+      const defaultsPath = path.join(tmpDir, 'override-keep-handler-defaults.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { post: 'defaultHandler' } }]
+      })
+      const target = {
+        myHandler: () => {},
+        defaultHandler () {}
+      }
+      const config = await loadRouteConfig(dir, target, { defaults: defaultsPath })
+      // override handler takes precedence
+      assert.equal(typeof config.routes[0].handlers.post, 'function')
+      assert.equal(config.routes[0].meta.post.summary, 'Added meta')
+    })
+
+    it('should not remove override route from results when no matching default exists', async () => {
+      const dir = path.join(tmpDir, 'override-no-match')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{
+          route: '/nomatch',
+          override: true,
+          handlers: { get: 'myHandler' },
+          meta: { get: { summary: 'Orphan' } }
+        }]
+      })
+      const defaultsPath = path.join(tmpDir, 'override-no-match-defaults.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { post: 'myHandler' } }]
+      })
+      const config = await loadRouteConfig(dir, { myHandler: () => {} }, { defaults: defaultsPath })
+      assert.equal(config.routes.length, 2)
+      assert.equal(config.routes[0].route, '/')
+      assert.equal(config.routes[1].route, '/nomatch')
+    })
+
+    it('should strip the override flag from merged route', async () => {
+      const dir = path.join(tmpDir, 'override-strip-flag')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{
+          route: '/',
+          override: true,
+          handlers: { post: 'myHandler' },
+          meta: { post: { summary: 'Test' } }
+        }]
+      })
+      const defaultsPath = path.join(tmpDir, 'override-strip-defaults.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { post: 'myHandler' } }]
+      })
+      const config = await loadRouteConfig(dir, { myHandler: () => {} }, { defaults: defaultsPath })
+      assert.equal(config.routes[0].override, undefined)
+    })
   })
 })