adapt-authoring-server 0.0.1

package/.eslintignore

@@ -0,0 +1 @@
+node_modules

package/.eslintrc

@@ -0,0 +1,14 @@
+{
+  "env": {
+      "browser": false,
+      "node": true,
+      "commonjs": false,
+      "es2020": true
+  },
+  "extends": [
+      "standard"
+  ],
+  "parserOptions": {
+      "ecmaVersion": 2020
+  }
+}

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,55 @@
+name: Bug Report
+description: File a bug report
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Please describe the issue
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: Tell us what should have happened
+  - type: textarea
+    id: repro-steps
+    attributes:
+      label: Steps to reproduce
+      description: Tell us how to reproduce the issue
+    validations:
+      required: true
+  - type: input
+    id: aat-version
+    attributes:
+      label: Authoring tool version
+      description: What version of the Adapt authoring tool are you running?
+    validations:
+      required: true
+  - type: input
+    id: fw-version
+    attributes:
+      label: Framework version
+      description: What version of the Adapt framework are you running?
+  - type: dropdown
+    id: browsers
+    attributes:
+      label: What browsers are you seeing the problem on?
+      multiple: true
+      options:
+        - Firefox
+        - Chrome
+        - Safari
+        - Microsoft Edge
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: sh

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Request a new feature
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to request a new feature in the Adapt authoring tool! The Adapt team will consider all new feature requests, but unfortunately cannot commit to every one.
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature description
+      description: Please describe your feature request
+    validations:
+      required: true
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Can you work on this feature?
+      description: If you are able to commit your own time to work on this feature, it will greatly increase the liklihood of it being implemented by the core dev team. Otherwise, it will be triaged and prioritised alongside the core team's current priorities.
+      options:
+        - label: I can contribute

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+[//]: # (Please title your PR according to eslint commit conventions)
+[//]: # (See https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint#eslint-convention for details)
+
+[//]: # (Add a link to the original issue)
+
+[//]: # (Delete as appropriate)
+### Fix
+* A sentence describing each fix
+
+### Update
+* A sentence describing each udpate
+
+### New
+* A sentence describing each new feature
+
+### Breaking
+* A sentence describing each breaking change
+
+[//]: # (List appropriate steps for testing if needed)
+### Testing
+1. Steps for testing
+
+[//]: # (Mention any other dependencies)
+
+

package/.github/workflows/new.yml

@@ -0,0 +1,19 @@
+name: Add to main project
+
+on:
+  issues:
+    types:
+      - opened
+  pull_request:
+    types:
+      - opened
+
+jobs:
+  add-to-project:
+    name: Add to main project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v0.1.0
+        with:
+          project-url: https://github.com/orgs/adapt-security/projects/5
+          github-token: ${{ secrets.PROJECTS_SECRET }}

package/adapt-authoring.json

@@ -0,0 +1,8 @@
+{
+  "documentation": {
+    "enable": true,
+    "manualPages": {
+      "server-requests.md": "advanced"      
+    }
+  }
+}

package/conf/config.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "host": {
+      "description": "Name of the host machine the server is running from",
+      "type": "string"
+    },
+    "port": {
+      "description": "Port to be used for listening to incoming connections",
+      "type": ["number", "string"]
+    },
+    "url": {
+      "description": "URL the server can be accessed from",
+      "type": "string",
+      "format": "uri",
+      "_adapt": {
+        "isPublic": true
+      }
+    },
+    "trustProxy": {
+      "description": "Whether to trust the client's x-Forwarded-For header for the request IP address. Only enable if using your own trusted reverse proxy",
+      "type": ["number", "boolean"],
+      "default": 0
+    },
+    "debugRequestTime": {
+      "description": "Will log the execution time of each request",
+      "type": "boolean",
+      "default": false
+    },
+    "verboseErrorLogging": {
+      "description": "Whether to log errors in their entirety",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": ["host", "port", "url"]
+}

package/docs/server-requests.md

@@ -0,0 +1,29 @@
+# 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. 
+
+## 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. 
+
+## 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.
+
+See the [Mozilla Developer Network docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) for a full list of HTTP response status codes and what they mean.
+
+## Use the built-in error handler
+The Server module adds a `sendError` utility function to the ServerResponse object that's passed to every route handler in the stack. Making use of this in your own code will ensure errors are formatted in a consistent way.
+
+Using the helper function is as simple as:
+
+```js
+async myHandler(req, res, next) {
+  try {
+    // do some stuff
+  } catch() {
+    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)

package/errors/errors.json

@@ -0,0 +1,24 @@
+{
+  "ENDPOINT_NOT_FOUND": {
+    "data": {
+      "endpoint": "The missing endpoint",
+      "method": "The HTTP method"
+    },
+    "description": "API endpoint does not exist",
+    "statusCode": 404
+  },
+  "NO_NET_CONN": {
+    "data": {
+      "hostname": "The hostname we were trying to reach"
+    },
+    "description": "No network connection",
+    "statusCode": 400
+  },
+  "SERVER_START": {
+    "data": {
+      "error": "The error"
+    },
+    "description": "Failed to start server",
+    "statusCode": 500
+  }
+}

package/index.js

@@ -0,0 +1,5 @@
+/**
+ * HTTP server functionality using Express.js
+ * @namespace server
+ */
+export { default } from './lib/ServerModule.js'

package/lib/Router.js

@@ -0,0 +1,272 @@
+import _ from 'lodash'
+import { App } from 'adapt-authoring-core'
+import express from 'express'
+import ServerUtils from './ServerUtils.js'
+/**
+ * Handles the Express routing functionality
+ * @memberof server
+ */
+class Router {
+  /**
+   * If passing an {@link ExpressRouter} as the parentRouter, it is assumed that the Express Router is the top of the router 'heirarchy' (which will have an impact of some of the {@link Router} methods)
+   * @param {String} root Route API endpoint for this router
+   * @param {Router|ExpressRouter} parentRouter Parent to mount router
+   * @param {Array<Route>} routes Array of routes
+   */
+  constructor (root, parentRouter, routes) {
+    /**
+     * The root route the router will be mounted at
+     * @type {String}
+     */
+    this.root = root
+    /**
+     * Routes config
+     * @type {Array<Route>}
+     */
+    this.routes = routes ?? []
+    /**
+     * Express router instance
+     * @type {external:ExpressRouter}
+     */
+    this.expressRouter = express.Router()
+    /**
+     * Express router instance
+     * @type {ExpressApp|Router}
+     */
+    this.parentRouter = parentRouter
+    /**
+     * List of sub-routers
+     * @type {Array<Router>}
+     */
+    this.childRouters = []
+    /**
+     * Middleware stack to be added directly to the router
+     * @type {Array<Function>}
+     */
+    this.routerMiddleware = [
+      ServerUtils.addErrorHandler
+    ]
+    /**
+     * Middleware stack to be added before route handlers (useful if you need access to specific request attributes that don't exist when standard middleware runs)
+     * @type {Array<Function>}
+     */
+    this.handlerMiddleware = [
+      ServerUtils.addExistenceProps,
+      ServerUtils.handleInternalRoutes
+    ]
+    /** @ignore */this._initialised = false
+  }
+
+  /**
+   * Returns the map of routes attached to this router
+   * @type {Object}
+   */
+  get map () {
+    return ServerUtils.generateRouterMap(this)
+  }
+
+  /**
+   * Generates this router's path from its ancestors
+   * @type {String}
+   */
+  get path () {
+    let p = ''
+
+    if (_.isString(this.parentRouter.path)) {
+      p += this.parentRouter.path
+    }
+    if (p[p.length - 1] !== '/' && this.root[0] !== '/') {
+      p += '/'
+    }
+    return p + this.root
+  }
+
+  /**
+   * Returns the URL for the router
+   * @return {String} The URL
+   */
+  get url () {
+    try {
+      const serverUrl = App.instance.dependencyloader.instances['adapt-authoring-server'].url
+      return serverUrl + this.path
+    } catch (e) {
+      this.log('error', e)
+      return ''
+    }
+  }
+
+  /**
+   * Adds middleware to the router stack. Accepts multiple params.
+   * @param {...Function} func Middleware function(s) to be added
+   * @return {AbstractApiModule} This instance, for chaining
+   * @see https://expressjs.com/en/guide/using-middleware.html
+   */
+  addMiddleware (...func) {
+    return this._addMiddleware(this.routerMiddleware, ...func)
+  }
+
+  /**
+   * Adds middleware to be called prior to any route handlers. Accepts multiple params. Useful if you need access to specific request attributes that don't exist when standard middleware runs.
+   * @param {...Function} func Middleware function(s) to be added
+   * @return {AbstractApiModule} This instance, for chaining
+   * @see https://expressjs.com/en/guide/using-middleware.html
+   */
+  addHandlerMiddleware (...func) {
+    return this._addMiddleware(this.handlerMiddleware, ...func)
+  }
+
+  /** @ignore */ _addMiddleware (stack, ...func) {
+    if (func.length) {
+      this.warnOnInited('middleware may not be called before any route handlers')
+      func.forEach(f => _.isFunction(f) && !stack.includes(f) && stack.push(f))
+    }
+    return this
+  }
+
+  /**
+   * Recursively gets middleware of the current router heirarchy
+   * @param {Router} router The current router (used when run recursively)
+   * @param {Array<function>} middleware Middleware function(s) (used when run recursively)
+   * @return {Array<Function>}
+   */
+  getHandlerMiddleware (router = this, middleware = []) {
+    if (!(router instanceof Router)) {
+      return middleware
+    }
+    return _.uniq(this.getHandlerMiddleware(router.parentRouter, [...router.handlerMiddleware, ...middleware]))
+  }
+
+  /**
+   * Store route definition. Accepts multiple params.
+   * @param {...Route} route Config of route(s) to be added
+   * @return {AbstractApiModule} This instance, for chaining
+   */
+  addRoute (...route) {
+    const inited = this.warnOnInited(`cannot set further routes (${this.path} ${route.map(r => r.route).join(', ')})`)
+    if (!inited && route.length) {
+      this.routes.push(...route.filter(this.validateRoute, this))
+    }
+    return this
+  }
+
+  /**
+   * Function for filtering bad route configs
+   * @param {Route} r Route config
+   * @return {Boolean}
+   */
+  validateRoute (r) {
+    const ePrefix = `invalid route config for ${this.route} router`
+    if (!_.isString(r.route)) {
+      this.log('warn', `${ePrefix}, route must be a string`)
+      return false
+    }
+    if (!r.handlers) {
+      this.log('warn', `${ePrefix}, no route handlers defined`)
+      return false
+    }
+    // handlers can be single function or array of functions
+    const allHandlersFuncs = Object.entries(r.handlers).every(([m, h]) => {
+      if (this.expressRouter[m] === undefined) {
+        this.log('warn', `${ePrefix}, ${m} must be a valid Express.js function`)
+        return false
+      }
+      if (!_.isFunction(h) && !(_.isArray(h) && h.every(_.isFunction))) {
+        this.log('warn', `${ePrefix} ${m.toUpperCase()} ${r.route}, all route handlers must be functions`)
+        return false
+      }
+      return true
+    })
+    if (!allHandlersFuncs) {
+      return false
+    }
+    return true
+  }
+
+  /**
+   * Creates and adds a sub-router to this router.
+   * @param {string} root The root of the child router
+   * @param {Array<Route>} routes Array of Routes to add
+   * @return {Router} The new router instance
+   */
+  createChildRouter (root, routes) {
+    if (this.warnOnInited(`cannot create further child routers (${this.path}/${root})`)) {
+      return this
+    }
+    const router = new Router(root, this, routes)
+
+    this.childRouters.push(router)
+
+    this.log('debug', 'ADD_ROUTER', router.path)
+
+    return router
+  }
+
+  /**
+   * Initialises the API
+   */
+  init () {
+    if (this.warnOnInited(`(${this.path})`)) {
+      return
+    }
+    if (this.routerMiddleware.length) {
+      this.expressRouter.use(...this.routerMiddleware)
+    }
+    if (this.childRouters.length) {
+      this.childRouters.forEach(c => {
+        c.init()
+        this.expressRouter.use(c.root, c.expressRouter)
+      })
+    }
+    if (this.routes.length) {
+      this.routes.forEach(r => {
+        Object.entries(r.handlers).forEach(([method, handler]) => {
+          this.expressRouter[method](r.route, ServerUtils.cacheRouteConfig(r), ...this.getHandlerMiddleware(), handler)
+          this.log('debug', 'ADD_ROUTE', method.toUpperCase(), `${this.path !== '/' ? this.path : ''}${r.route}`)
+        })
+      })
+    }
+    // add to the parent stack
+    if (this.parentRouter instanceof Router) {
+      this.parentRouter.expressRouter.use(`/${this.root}`, this.expressRouter)
+    } else {
+      const route = this.root[0] !== '/' ? `/${this.root}` : this.root
+      this.parentRouter.use(route, this.expressRouter)
+    }
+    this._initialised = true
+  }
+
+  /**
+   * Shortcut for checking Router has initialised, logging a warning if not
+   * @param {String} message Message to log on error
+   * @return {Boolean}
+   */
+  warnOnInited (message) {
+    if (this._initialised) {
+      this.log('warn', `router has already initialised, ${message}`)
+    }
+    return this._initialised
+  }
+
+  /**
+   * Creates an array defining the router inheritance hierarchy
+   * @param {Router} router The root router
+   * @return {Array}
+   */
+  flattenRouters (router = this) {
+    return router.childRouters.reduce((a, c) => {
+      c.childRouters ? a.push(...this.flattenRouters(c)) : a.push(c)
+      return a
+    }, [router])
+  }
+
+  /**
+   * Logs a message
+   * @param {String} level Level of log
+   * @param {...*} args Arguments to be logged
+   */
+  log (level, ...args) {
+    App.instance.logger.log(level, this.constructor.name.toLowerCase(), ...args)
+  }
+}
+
+export default Router

package/lib/ServerModule.js

@@ -0,0 +1,153 @@
+import express from 'express'
+import { AbstractModule, Hook } from 'adapt-authoring-core'
+import Router from './Router.js'
+import ServerUtils from './ServerUtils.js'
+/**
+ * Adds an Express server to the authoring tool
+ * @memberof server
+ * @extends {AbstractModule}
+ */
+class ServerModule extends AbstractModule {
+  /** @override */
+  async init () {
+    /**
+     * The main Express Application
+     * @type {external:ExpressApp}
+     */
+    this.expressApp = express()
+    /**
+     * The default/'root' router for the application
+     * @type {Router}
+     */
+    this.root = new Router('/', this.expressApp)
+    /**
+     * The router which handles all APIs
+     * @type {Router}
+     */
+    this.api = new Router('api', this.root)
+    /**
+     * Whether the HTTP server is listening for requests
+     * @type {Boolean}
+     */
+    this.isListening = false
+    /**
+     * Hook invoked when the HTTP server is listening
+     * @type {Hook}
+     */
+    this.listeningHook = new Hook()
+    /**
+     * Hook for interrupting requests
+     * @type {Hook}
+     */
+    this.requestHook = new Hook({ mutable: true })
+    /**
+     * Reference to the HTTP server used by Express
+     * @type {external:HttpServer}
+     */
+    this.httpServer = undefined
+
+    this.expressApp.set('trust proxy', this.getConfig('trustProxy'))
+    this.expressApp.set('view engine', 'hbs')
+    /**
+     * Need to wait for other modules to load before we properly initialise &
+     * start listening for incoming connections
+     */
+    this.app.onReady().then(this.start.bind(this)).catch(e => this.log('error', e))
+  }
+
+  /**
+   * Starts the HTTP server
+   */
+  async start () {
+    // Initialise the root router
+    this.root.init()
+    // Initialise the API router
+    this.api.expressRouter.get('/', ServerUtils.mapHandler(this.api).bind(this))
+    this.api.addMiddleware(
+      ServerUtils.debugRequestTime
+    )
+    this.api.init()
+    // add not-found handlers
+    this.api.expressRouter.use(ServerUtils.apiNotFoundHandler.bind(this))
+    this.root.expressRouter.use(ServerUtils.rootNotFoundHandler.bind(this))
+    // add generic error handling
+    this.expressApp.use(ServerUtils.genericErrorHandler.bind(this))
+
+    await this.listen()
+    this.log('info', `listening on ${this.port}`)
+  }
+
+  /**
+   * Server hostname
+   * @type {String}
+   */
+  get host () {
+    return this.getConfig('host')
+  }
+
+  /**
+   * Port the app should listen on
+   * @type {String}
+   */
+  get port () {
+    return this.getConfig('port')
+  }
+
+  /**
+   * The URL for the server from its config
+   * @type {String}
+   */
+  get url () {
+    return this.getConfig('url') || `${this.getConfig('host')}:${this.port}`
+  }
+
+  /**
+   * Middleware function to allow serving of static files
+   * @see https://expressjs.com/en/4x/api.html#express.static
+   * @param {String} root The root directory from which to serve static assets
+   * @param {Object} options Options to pass to the function
+   * @return {Function}
+   */
+  static (root, options) {
+    return express.static(root, options)
+  }
+
+  /**
+   * Start the Express server (shortcut to the Express function of the same name).
+   * @see https://expressjs.com/en/4x/api.html#app.listen
+   * @param {function} func Callback function to be called on connection.
+   * @return {Promise} Resolves with the server instance
+   */
+  listen () {
+    return new Promise((resolve, reject) => {
+      this.httpServer = this.expressApp.listen(this.port, this.host, () => {
+        this.isListening = true
+        this.listeningHook.invoke()
+        resolve(this.httpServer)
+      }).once('error', e => reject(this.app.errors.SERVER_START.setData({ error: e })))
+    })
+  }
+
+  /**
+   * Stops the Express server
+   * @return {Promise}
+   */
+  close () {
+    return new Promise((resolve, reject) => {
+      if (!this.httpServer) {
+        this.log('warn', 'cannot stop server, it wasn\'t running!')
+        return resolve()
+      }
+      if (!this.isListening) return this.listeningHook.tap(this.close.bind(this))
+      else this.listeningHook.untap(this.close)
+
+      this.httpServer.close(() => {
+        this.httpServer = undefined
+        this.log('info', `no longer listening on ${this.port}`)
+        return resolve()
+      })
+    })
+  }
+}
+
+export default ServerModule

package/lib/ServerUtils.js

@@ -0,0 +1,191 @@
+import _ from 'lodash'
+import { App } from 'adapt-authoring-core'
+/**
+ * Server-related utilities
+ * @memberof server
+ */
+class ServerUtils {
+  /**
+   * Middleware for handling 404 errors on the API router
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   * @param {Function} next
+   */
+  static apiNotFoundHandler (req, res, next) {
+    next(App.instance.errors.ENDPOINT_NOT_FOUND.setData({ endpoint: req.originalUrl, method: req.method }))
+  }
+
+  /**
+   * Generic error handling middleware for the API router
+   * @param {Error} error
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   * @param {Function} next
+   */
+  static genericErrorHandler (error, req, res, next) {
+    this.log('error', App.instance.lang.translate(undefined, error), this.getConfig('verboseErrorLogging') && error.stack ? error.stack : '')
+    res.sendError(error)
+  }
+
+  /**
+   * Middleware for handling 404 errors on the root router
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   */
+  static rootNotFoundHandler (req, res) {
+    res.status(App.instance.errors.NOT_FOUND.statusCode).end()
+  }
+
+  /**
+   * Handler for returning an API map
+   * @param {Router} topRouter
+   * @return {Function} Middleware function
+   */
+  static mapHandler (topRouter) {
+    return (req, res) => res.json(topRouter.map)
+  }
+
+  /**
+   * Generates a map for a given router
+   * @param {Router} topRouter
+   * @return {Object} The route map
+   */
+  static generateRouterMap (topRouter) {
+    return topRouter.flattenRouters()
+      .sort((a, b) => a.root.localeCompare(b.root))
+      .reduce((m, r) => {
+        const key = `${getRelativeRoute(topRouter, r)}endpoints`
+        const endpoints = getEndpoints(r)
+        return endpoints.length ? { ...m, [key]: endpoints } : m
+      }, {})
+  }
+
+  /**
+   * Adds extra properties to the request object to allow for easy translations
+   * @param {Function} next
+   */
+  static addErrorHandler (req, res, next) {
+    res.sendError = error => {
+      if (error.constructor.name !== 'AdaptError') {
+        const e = App.instance.errors[error.code]
+        if (e) {
+          if (error.statusCode) e.statusCode = error.statusCode
+          e.error = error.message
+          error = e
+        } else {
+          error = App.instance.errors.SERVER_ERROR
+        }
+      }
+      res
+        .status(error.statusCode)
+        .json({ code: error.code, message: req.translate?.(error) ?? error.message })
+    }
+    next()
+  }
+
+  /**
+   * Adds logs for debugging each request time
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   * @param {Function} next
+   */
+  static async debugRequestTime (req, res, next) {
+    const server = await App.instance.waitForModule('server')
+    if (server.getConfig('debugRequestTime')) {
+      const start = new Date()
+      res.on('finish', () => server.log('debug', 'REQUEST_DURATION', req.method, req.originalUrl, new Date() - start))
+    }
+    next()
+  }
+
+  /**
+   * Adds extra properties to the request object to allow for easy existence checking of common request objects
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   * @param {Function} next
+   * @example
+   * "IMPORTANT NOTE: body data is completely ignored for GET requests, any code
+   * requiring it should switch to use POST."
+   *
+   * let req = { 'params': { 'foo':'bar' }, 'query': {}, 'body': {} };
+   * req.hasParams // true
+   * req.hasQuery // false
+   * req.hasBody // false
+   */
+  static addExistenceProps (req, res, next) {
+    if (req.method === 'GET') {
+      req.body = {}
+    }
+    const storeVal = (key, exists) => {
+      req[`has${_.capitalize(key)}`] = exists
+    }
+    ['body', 'params', 'query'].forEach(attr => {
+      if (!req[attr]) {
+        return storeVal(attr, true)
+      }
+      const entries = Object.entries(req[attr])
+      let deleted = 0
+      if (entries.length === 0) {
+        return storeVal(attr, false)
+      }
+      entries.forEach(([key, val]) => {
+        if (val === undefined || val === null) {
+          delete req[attr][key]
+          deleted++
+        }
+      })
+      storeVal(attr, deleted < entries.length)
+    })
+    next()
+  }
+
+  /**
+   * Handles restriction of routes marked as internal
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   * @param {Function} next
+   */
+  static async handleInternalRoutes (req, res, next) {
+    const server = await App.instance.waitForModule('server')
+    const isInternalIp = server.getConfig('host') === req.ip || req.ip === '127.0.0.1' || req.ip === '::1'
+    if (req.routeConfig.internal && !isInternalIp) {
+      return next(App.instance.errors.UNAUTHORISED.setData({ url: req.originalUrl, method: req.method }))
+    }
+    next()
+  }
+
+  /**
+   * Caches the route config on the incoming request
+   * @param {Route} routeConfig
+   * @return {Function}
+   */
+  static cacheRouteConfig (routeConfig) {
+    return (req, res, next) => {
+      req.routeConfig = routeConfig
+      next()
+    }
+  }
+}
+/** @ignore */ function getEndpoints (r) {
+  return r.routes.map(route => {
+    return {
+      url: `${r.url}${route.route}`,
+      accepted_methods: Object.keys(route.handlers).reduce((memo, method) => {
+        return {
+          ...memo,
+          [method]: route?.meta?.[method] ?? {}
+        }
+      }, {})
+    }
+  })
+}
+/** @ignore */ function getRelativeRoute (relFrom, relTo) {
+  if (relFrom === relTo) {
+    return `${relFrom.route}_`
+  }
+  let route = ''
+  for (let r = relTo; r !== relFrom; r = r.parentRouter) route = `${r.root}_${route}`
+  return route
+}
+
+export default ServerUtils

package/lib/typedefs.js

@@ -0,0 +1,57 @@
+/**
+ * This file exists to define the below types for documentation purposes.
+ */
+/**
+ * Built-in HTTP server
+ * @memberof server
+ * @external HttpServer
+ * @see {@link https://nodejs.org/api/http.html#http_class_http_server}
+ */
+/**
+ * Express.js top-level application
+ * @memberof server
+ * @external ExpressApp
+ * @see {@link https://expressjs.com/en/4x/api.html#app}
+ */
+/**
+ * Express.js HTTP router
+ * @memberof server
+ * @external ExpressRouter
+ * @see {@link https://expressjs.com/en/4x/api.html#router}
+ */
+/**
+ * Express.js HTTP request
+ * @memberof server
+ * @external ExpressRequest
+ * @see {@link https://expressjs.com/en/4x/api.html#req}
+ */
+/**
+ * Express.js HTTP response
+ * @memberof server
+ * @external ExpressResponse
+ * @see {@link https://nodejs.org/api/http.html#http_class_http_serverresponse}
+ */
+/**
+ * Defines how an individual API route should be handled
+ * @memberof server
+ * @typedef {Object} Route
+ * @property {String} route The name of the api (this will be used as the API endpoint)
+ * @property {Object} handlers Object mapping HTTP methods to request handler functions. Note: Any HTTP methods not specified in `handlers` will not be exposed.
+ * @property {Array<Function>|Function} [handlers.post] POST handlers for the route
+ * @property {Array<Function>|Function} [handlers.get] GET handlers for the route
+ * @property {Array<Function>|Function} [handlers.put] PUT handlers for the route
+ * @property {Array<Function>|Function} [handlers.delete] DELETE handlers for the route
+ * @example
+ * {
+ *   route: '/:id?',
+ *   handlers: {
+ *     // can be an array of middleware/handlers
+ *     post: [beforePost, handlePostRequest, afterPost],
+ *     // or an individual function
+ *     get: getRequest,
+ *     put: putRequest,
+ *     // or an in-line function
+ *     delete: (req, res, next) => { next(); }
+ *   }
+ * }
+ */

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "adapt-authoring-server",
+  "version": "0.0.1",
+  "description": "Provides an Express application routing and more",
+  "homepage": "https://github.com/adapt-security/adapt-authoring-server",
+  "license": "GPL-3.0",
+  "type": "module",
+  "main": "index.js",
+  "repository": "github:adapt-security/adapt-authoring-server",
+  "dependencies": {
+    "express": "^5.1.0",
+    "hbs": "^4.2.0",
+    "lodash": "^4.17.21"
+  },
+  "peerDependencies": {
+    "adapt-authoring-core": "github:adapt-security/adapt-authoring-core"
+  },
+  "devDependencies": {
+    "eslint": "^9.12.0",
+    "standard": "^17.1.0"
+  }
+}

package/tests/router.spec.js

@@ -0,0 +1,142 @@
+const { App } = require('adapt-authoring-core');
+const express = require('express');
+const Router = require('../lib/Router');
+const should = require('should');
+const supertest = require('supertest');
+
+describe('Server router', function() {
+  before(function() {
+    this.createRouter = (r = 'test') => new Router(r, express());
+    this.testRequest = (router, done, expectedStatus = 200) => {
+      const l = router.parentRouter.listen(undefined, function() {
+        supertest(router.parentRouter)
+          .get(`${router.path}`)
+          .expect(expectedStatus)
+          .end((e, res) => l.close(done))
+      });
+    };
+  });
+  describe('#addRoute()', function() {
+    const r1 = { route: 'test1', handlers: { get: () => {} } };
+    const r2 = { route: 'test2', handlers: { get: () => {} } };
+    const r3 = { route: 'test3', handlers: { get: () => {} } };
+    it('should add a route function to the stack', function() {
+      const router = this.createRouter();
+      router.addRoute(r1);
+      router.routes.should.containEql(r1);
+    });
+    it('should add multiple routes to the stack', function() {
+      const router = this.createRouter();
+      router.addRoute(r1, r2);
+      router.routes.should.containEql(r2);
+    });
+    it('should return router reference so as to be chainable', function() {
+      const router = this.createRouter();
+      const r = router.addRoute(r2);
+      r.should.equal(router);
+    });
+    it('should call route handler on client request', function(done) {
+      const router = this.createRouter();
+      router.addRoute({
+        route: '/',
+        handlers: { get: (req, res, next) => res.end() }
+      });
+      router.init();
+      this.testRequest(router, done);
+    });
+  });
+  describe('#addMiddleware()', function() {
+    const m1 = (req, res, next) => next();
+    const m2 = (req, res, next) => next();
+    it('should add a middleware function to the stack', function() {
+      const router = this.createRouter();
+      router.addMiddleware(m1);
+      router.middleware.should.containEql(m1);
+    });
+    it('should add multiple middleware functions to the stack', function() {
+      const router = this.createRouter();
+      router.addMiddleware(m1, m2);
+      router.middleware.should.containEql(m2);
+    });
+    it('should return router reference so as to be chainable', function() {
+      const router = this.createRouter();
+      const r = router.addMiddleware(m2);
+      r.should.equal(router);
+    });
+    it('should call custom middleware on client request', function(done) {
+      const router = this.createRouter();
+      router.addRoute({
+        route: '/',
+        handlers: { get: (req, res, next) => res.status(500).end() }
+      });
+      router.addMiddleware((req, res, next) => res.status(200).end());
+      router.init();
+      this.testRequest(router, done);
+    });
+  });
+  describe('#createChildRouter()', function() {
+    let parent, child;
+    before(function() {
+      parent = this.createRouter();
+      child = parent.createChildRouter('child');
+    });
+    it('should return a router instance', function() {
+      child.should.be.instanceof(Router);
+    });
+    it('should expose specified route', function() {
+      child.route.should.equal('child');
+    });
+    it('should be added to child routers', function() {
+      parent.childRouters.should.containEql(child);
+    });
+    it('should reference current router as parent', function() {
+      child.parentRouter.should.equal(parent);
+    });
+  });
+  describe('#path()', function() {
+    it('should generate the endpoint of the router', function() {
+      const child = new Router('child', new Router('parent', {}));
+      child.path.should.equal('/parent/child');
+    });
+  });
+  describe('#handleRequest()', function() {
+    it('should invoke listeners to Server#requestHook', function(done) {
+      let isDone = false;
+      App.instance.getModule('server').requestHook.tap(() => {
+        if(!isDone) done();
+        isDone = true;
+      });
+      const router = this.createRouter();
+      router.addRoute({
+        route: '/',
+        handlers: { get: (req, res, next) => {} }
+      });
+      router.init();
+      this.testRequest(router, () => {}, 500);
+    });
+  });
+  describe('#genericNotFoundHandler()', function() {
+    it('should return 404 HTTP status', function(done) {
+      const router = this.createRouter();
+      router.addRoute({
+        route: '/',
+        handlers: { get: (req, res, next) => res.end() }
+      });
+      router.addMiddleware(router.genericNotFoundHandler);
+      router.init();
+      this.testRequest(router, done, 404);
+    });
+  });
+  describe('#genericErrorHandler()', function() {
+    it('should return error HTTP status', function(done) {
+      const router = this.createRouter();
+      router.addRoute({
+        route: '/',
+        handlers: { get: (req, res, next) => next(new Error('Something bad happened')) }
+      });
+      router.addMiddleware(router.genericErrorHandler);
+      router.init();
+      this.testRequest(router, done, 500);
+    });
+  });
+});

package/tests/serverModule.spec.js

@@ -0,0 +1,51 @@
+const { Hook } = require('adapt-authoring-core');
+const Router = require('../lib/Router');
+const ServerModule = require('../lib/ServerModule');
+const should = require('should');
+const supertest = require('supertest');
+
+describe('Server module', function() {
+  before(function() {
+    this.server = new ServerModule(global.ADAPT.app, { name: require('../package.json').name });
+  });
+  describe('#constructor()', function() {
+    it('should expose the Express application', function() {
+      false.should.be.true();
+    });
+    it('should expose a `root` Router', function() {
+      this.server.root.should.be.an.instanceof(Router);
+    });
+    it('should expose an `api` Router', function() {
+      this.server.api.should.be.an.instanceof(Router);
+    });
+    it('should expose a hook to modify requests', function() {
+      this.server.requestHook.should.be.an.instanceof(Hook);
+    });
+  });
+  describe('#url()', function() {
+    it('should return the URL of the server', function() {
+      this.server.url.should.be.a.String();
+    });
+  });
+  describe('#static()', function() {
+    it('should expose Express#static', function() {
+      false.should.be.true();
+    });
+  });
+  describe('#listen()', function() {
+    it('should accept requests on the specified URL/port', function(done) {
+      supertest(this.server.expressApp)
+        .get(`${this.server.api.path}`)
+        .expect(200)
+        .end(done);
+    });
+    it('should not accept requests on unspecified URLs/ports', function(done) {
+      false.should.be.true();
+    });
+  });
+  describe('#close()', function() {
+    it('should stop accepting requests', function() {
+      false.should.be.true();
+    });
+  });
+});