adapt-authoring-server 0.0.1 → 1.0.0

package/lib/ServerUtils.js

@@ -1,191 +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
+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

@@ -1,57 +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(); }
- *   }
- * }
- */
+/**
+ * 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

@@ -1,22 +1,57 @@
-{
-  "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"
-  }
-}
+{
+  "name": "adapt-authoring-server",
+  "version": "1.0.0",
+  "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",
+    "@semantic-release/commit-analyzer": "^9.0.2",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^8.0.5",
+    "@semantic-release/npm": "^9.0.1",
+    "@semantic-release/release-notes-generator": "^10.0.3",
+    "conventional-changelog-eslint": "^3.0.9",
+    "semantic-release": "^21.0.1",
+    "semantic-release-replace-plugin": "^1.2.7"
+  },
+  "release": {
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "eslint"
+        }
+      ],
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "preset": "eslint"
+        }
+      ],
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "package.json"
+          ],
+          "message": "Chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ]
+    ]
+  }
+}