adapt-authoring-api 0.0.1

package/lib/AbstractApiUtils.js

@@ -0,0 +1,145 @@
+/**
+ * Utilities for APIs
+ * @memberof api
+ */
+class AbstractApiUtils {
+  /**
+   * Converts HTTP methods to a corresponding 'action' for use in auth
+   * @param {String} method The HTTP method
+   * @return {String}
+   */
+  static httpMethodToAction (method) {
+    switch (method.toLowerCase()) {
+      case 'get':
+        return 'read'
+      case 'post':
+      case 'put':
+      case 'patch':
+      case 'delete':
+        return 'write'
+      default:
+        return ''
+    }
+  }
+
+  /**
+   * Converts HTTP methods to a corresponding database function
+   * @param {String} method The HTTP method
+   * @return {String}
+   */
+  static httpMethodToDBFunction (method) {
+    switch (method.toLowerCase()) {
+      case 'post': return 'insert'
+      case 'get': return 'find'
+      case 'put': case 'patch': return 'update'
+      case 'delete': return 'delete'
+      default: return ''
+    }
+  }
+
+  /**
+   * Generates a list of arguments to be passed to the MongoDBModule from a request object
+   * @param {external:ExpressRequest} req
+   * @return {Array<*>}
+   */
+  static argsFromReq (req) {
+    const opts = { schemaName: req.apiData.schemaName, collectionName: req.apiData.collectionName }
+    switch (req.method) {
+      case 'GET': case 'DELETE':
+        return [req.apiData.query, opts]
+      case 'POST':
+        return [req.apiData.data, opts]
+      case 'PUT': case 'PATCH':
+        return [req.apiData.query, req.apiData.data, opts]
+    }
+  }
+
+  /**
+   * Generates REST API metadata and stores on route config
+   * @param {AbstractApiModule} instance The current AbstractApiModule instance
+   */
+  static generateApiMetadata (instance) {
+    const getData = isList => {
+      const $ref = { $ref: `#/components/schemas/${instance.schemaName}` }
+      return {
+        description: `The ${instance.schemaName} data`,
+        content: { 'application/json': { schema: isList ? { type: 'array', items: $ref } : $ref } }
+      }
+    }
+    const queryParams = [
+      {
+        name: 'limit',
+        in: 'query',
+        description: `How many results should be returned Default value is ${instance.app.config.get('adapt-authoring-api.defaultPageSize')} (max value is ${instance.app.config.get('adapt-authoring-api.maxPageSize')})`
+      },
+      {
+        name: 'page',
+        in: 'query',
+        description: 'The page of results to return (determined from the limit value)'
+      }
+    ]
+    const verbMap = {
+      put: 'Replace',
+      get: 'Retrieve',
+      patch: 'Update',
+      delete: 'Delete',
+      post: 'Insert'
+    }
+    instance.routes.forEach(r => {
+      r.meta = {}
+      Object.keys(r.handlers).forEach(method => {
+        let summary, parameters, requestBody, responses
+        switch (r.route) {
+          case '/':
+            if (method === 'post') {
+              summary = `${verbMap.post} a new ${instance.schemaName} document`
+              requestBody = getData()
+              responses = { 201: getData() }
+            } else {
+              summary = `${verbMap.get} all ${instance.collectionName} documents`
+              parameters = queryParams
+              responses = { 200: getData(true) }
+            }
+            break
+
+          case '/:_id':
+            summary = `${verbMap[method]} an existing ${instance.schemaName} document`
+            requestBody = method === 'put' || method === 'patch' ? getData() : method === 'delete' ? undefined : {}
+            responses = { [method === 'delete' ? 204 : 200]: getData() }
+            break
+
+          case '/query':
+            summary = `Query all ${instance.collectionName}`
+            parameters = queryParams
+            responses = { 200: getData(true) }
+            break
+
+          case '/schema':
+            summary = `Retrieve ${instance.schemaName} schema`
+            break
+        }
+        r.meta[method] = { summary, parameters, requestBody, responses }
+      })
+    })
+  }
+
+  /**
+   * Clones an object and converts any Dates and ObjectIds to Strings
+   * @param {Object} data
+   * @returns A clone object with stringified ObjectIds
+   */
+  static stringifyValues (data) {
+    return Object.entries(data).reduce((cloned, [key, val]) => {
+      const type = val?.constructor?.name
+      cloned[key] =
+        type === 'Date' || type === 'ObjectId'
+          ? val.toString()
+          : type === 'Array' || type === 'Object'
+            ? this.stringifyValues(val)
+            : val
+      return cloned
+    }, Array.isArray(data) ? [] : {})
+  }
+}
+
+export default AbstractApiUtils

package/lib/DataCache.js

@@ -0,0 +1,46 @@
+import { App } from 'adapt-authoring-core'
+/**
+ * Time-limited data cache
+ * @memberof api
+ */
+class DataCache {
+  /** @override */
+  constructor ({ enable, lifespan }) {
+    this.isEnabled = enable !== false
+    this.lifespan = lifespan ?? App.instance.config.get('adapt-authoring-api.defaultCacheLifespan')
+    this.cache = {}
+  }
+
+  /**
+   * Retrieve cached data, or run fresh query if no cache exists or cache is invalid
+   * @param {Object} query
+   * @param Object} options
+   * @param {Object} mongoOptions
+   * @returns {*} The cached data
+   */
+  async get (query, options, mongoOptions) {
+    const key = JSON.stringify(query) + JSON.stringify(options) + JSON.stringify(mongoOptions)
+    this.prune()
+    if (this.cache[key]) {
+      return this.cache[key].data
+    }
+    const mongodb = await App.instance.waitForModule('mongodb')
+    const data = await mongodb.find(options.collectionName, query, mongoOptions)
+    this.cache[key] = { data, timestamp: Date.now() }
+    return data
+  }
+
+  /**
+   * Removes invalid cache data
+   */
+  prune () {
+    Object.keys(this.cache).forEach(k => {
+      const cache = this.cache[k]
+      if (Date.now() > (cache.timestamp + this.lifespan)) {
+        delete this.cache[k]
+      }
+    })
+  }
+}
+
+export default DataCache

package/lib/typedefs.js

@@ -0,0 +1,67 @@
+/**
+ * This file exists to define the below types for documentation purposes.
+ */
+/**
+ * For AbstractApiModule subclasses the Express ClientRequest object is given an extra apiData property which contains useful data related to the incoming request.
+ * Extends Route definition with additional API-specific attributes
+ * @memberof api
+ * @typedef {Object} ApiRequestData
+ * @property {Object} config The API route's config data. Set when the route is initialised.
+ * @property {String} collectionName The DB collection name
+ * @property {Object} data The request body data
+ * @property {Object} query The request query data
+ * @property {String} schemaName The schema name for data validation
+ * @property {Boolean} modifying Whether the request modifies data
+ * @see {ApiRoute}
+ */
+/**
+ * Extends the existing Route definition with additional API-specific attributes
+ * @memberof api
+ * @typedef {Route} ApiRoute
+ * @extends {Route}
+ * @property {Array<string>} modifiers Defines which HTTP methods can modify data (verbs must be lower-case). This only needs do be defined for routes are non standard. By default, it is assumed that 'get' requests are non-modifying, and 'post', 'put', 'patch' and 'delete' are modifying.
+ * @example
+ * modifiers: ['post']
+ * @property {Boolean} validate Whether the request data should be validated
+ * @property {Object} permissions Definition of permissions allowed required to access each handler
+ * @property {Array<string>} [permissions.post] Permissions scopes required to access this route
+ * @property {Array<string>} [permissions.get] Permissions scopes required to access this route
+ * @property {Array<string>} [permissions.put] Permissions scopes required to access this route
+ * @property {Array<string>} [permissions.delete] Permissions scopes required to access this route
+ * @example
+ * {
+ *    route: '/',
+ *    handlers: { post: postHandler },
+ *    permissions: { post: ['write:scope'] }
+ *    modifiers: ['post'],
+ * }
+ */
+/**
+ * @memberof api
+ * @typedef {Object} InsertOptions
+ * @property {String} schemaName Name of the schema to validate against
+ * @property {String} collectionName DB collection to insert document into
+ * @property {String} validate Whether the incoming data should be validated
+ * @property {String} invokePostHook Whether the function should invoke the 'post' action hook on success
+ */
+/**
+ * @memberof api
+ * @typedef {Object} FindOptions
+ * @property {String} schemaName Name of the schema to validate against
+ * @property {String} collectionName DB collection to insert document into
+ */
+/**
+ * @memberof api
+ * @typedef {Object} UpdateOptions
+ * @property {String} schemaName Name of the schema to validate against
+ * @property {String} collectionName DB collection to insert document into
+ * @property {Boolean} validate Whether the incoming data should be validated
+ * @property {String} invokePostHook Whether the function should invoke the 'post' action hook on success
+ * @property {Boolean} rawUpdate Whether the provided data should be considered 'raw' (i.e. not format and apply $set MongoDB keyword)
+ */
+/**
+ * @memberof api
+ * @typedef {Object} DeleteOptions
+ * @property {String} collectionName DB collection to remove document from
+ * @property {String} invokePostHook Whether the function should invoke the 'post' action hook on success
+ */

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "adapt-authoring-api",
+  "version": "0.0.1",
+  "description": "Abstract module for creating APIs",
+  "homepage": "https://github.com/adapt-security/adapt-authoring-api",
+  "license": "GPL-3.0",
+  "type": "module",
+  "main": "index.js",
+  "repository": "github:adapt-security/adapt-authoring-api",
+  "dependencies": {
+    "lodash": "^4.17.21"
+  },
+  "peerDependencies": {
+    "adapt-authoring-auth": "github:adapt-security/adapt-authoring-auth",
+    "adapt-authoring-core": "github:adapt-security/adapt-authoring-core",
+    "adapt-authoring-jsonschema": "github:adapt-security/adapt-authoring-jsonschema",
+    "adapt-authoring-mongodb": "github:adapt-security/adapt-authoring-mongodb"
+  },
+  "devDependencies": {
+    "eslint": "^9.14.0",
+    "standard": "^17.1.0"
+  }
+}

package/tests/abstractApiModule.spec.js

@@ -0,0 +1,84 @@
+const { App } = require('adapt-authoring-core');
+const should = require('should');
+const TestApiModule = require('./data/testApiModule');
+
+describe('Abstract API module', function() {
+  before(function(done) {
+    const loadModule = (mod, done) => {
+      const m = this.app.getModule(mod);
+      m.preload (this.app, () => m.boot(this.app, done, done), done);
+    };
+    this.app = App.instance;
+
+    loadModule('server', () => loadModule('mongodb', done));
+
+    this.tmi = new TestApiModule(this.app, {});
+    this.tmi.router.should.not.be.undefined();
+  });
+  describe('#requestHandler()', function() {
+    it('should customise the request object', function() {
+      const req = { method: 'GET' };
+      TestApiModule.requestHandler()(req, {}, () => {});
+      should.exist(req.type);
+      should.exist(req.dsquery);
+    });
+    it('should correctly map HTTP methods to MongoDBModule functions', function() {
+      const m1 = this.app.getModule('mongodb');
+      const m2 = {
+        retrieve: () => {
+          return new Promise((resolve, reject) => { correctlyMapped = true; })
+        }
+      };
+      let correctlyMapped = false;
+      this.app.dependencyloader.modules['adapt-authoring-mongodb'] = m2;
+      TestApiModule.requestHandler()({ method: 'GET' }, {}, () => {});
+      this.app.dependencyloader.modules['adapt-authoring-mongodb'] = m1;
+      correctlyMapped.should.be.true();
+    });
+  });
+  describe('#preload()', function() {
+    it('should create a child Router with the correct route', function(done) {
+      this.tmi.preload(this.app, () => {
+        this.tmi.router.constructor.name.should.equal('Router');
+        done();
+      }, done);
+    });
+  });
+  describe('#initSchemas()', function() {
+    it('should add specified schemas to the DB', function(done) {
+      this.tmi.boot(this.app, () => {
+        should.exist(this.app.getModule('mongodb').connection.models.test);
+        done();
+      }, done);
+    });
+    it('should ignore badly configured data', function() {
+      const mongoModels = this.app.getModule('mongodb').connection.models;
+      Object.keys(mongoModels).length.should.equal(1);
+    });
+  });
+  describe('#initMiddleware()', function() {
+    it('should add middleware to the API router', function() {
+      const middleware = this.tmi.router.middleware;
+      middleware.length.should.equal(1);
+      middleware[0].name.should.equal('testMiddleware');
+    });
+  });
+  describe('#initRoutes()', function() {
+    it('should add routes defined as an object', function() {
+      const routes = this.tmi.router.routes.map(r => r.route);
+      routes.should.containEql('/objectroute');
+    });
+    it('should add routes defined as an array', function() {
+      const routes = this.tmi.router.routes.map(r => r.route);
+      routes.should.containEql('/arrayroute');
+    });
+    it('should set custom permissions scopes if specified', function() {
+      const postScopes = this.app.auth.routes.secure['/api/arrayroute'].post;
+      postScopes.should.containEql('testscope');
+    });
+    it('should set generic permissions scopes if not specified', function() {
+      const scopes = this.app.auth.routes.secure['/api/objectroute'];
+      scopes.should.not.be.undefined();
+    });
+  });
+});

package/tests/abstractApiUtils.spec.js

@@ -0,0 +1,49 @@
+const should = require('should');
+
+describe('Abstract API utilities', function() {
+  describe('#callDbFunction()', function() {
+    it('should fail if request parameter doesn\'t specify a type', function() {
+      false.should.be.true();
+    });
+    it('should fail if attempting to call an unknown DB function', function() {
+      false.should.be.true();
+    });
+    it('should return data in response', function() {
+      false.should.be.true();
+    });
+    it('should set response HTTP status', function() {
+      false.should.be.true();
+    });
+  });
+  describe('#httpMethodToAction()', function() {
+    it('should return a string', function() {
+      false.should.be.true();
+    });
+    it('should return action string for known action', function() {
+      false.should.be.true();
+    });
+    it('should return empty string for unknown action', function() {
+      false.should.be.true();
+    });
+  });
+  describe('#validateSchemaDef()', function() {
+    it('should fail if def isn\'t an object', function() {
+      false.should.be.true();
+    });
+    it('should fail if def has no name', function() {
+      false.should.be.true();
+    });
+    it('should fail if def has no model', function() {
+      false.should.be.true();
+    });
+    it('should fail if schemas isn\'t an array', function() {
+      false.should.be.true();
+    });
+    it('should fail if def has no routes', function() {
+      false.should.be.true();
+    });
+    it('should validate routes', function() {
+      false.should.be.true();
+    });
+  });
+});

package/tests/data/testApiModule.js

@@ -0,0 +1,50 @@
+const AbstractAPIModule = require('../../lib/AbstractApiModule');
+
+const TestSchema = {
+  name: 'test',
+  definition: {
+    isTest: {
+      type: "boolean", default: true
+    }
+  }
+};
+
+class TestApiModule extends AbstractAPIModule {
+  static get def() {
+    return {
+      name: 'test',
+      model: 'test',
+      schemas: [
+        TestSchema,
+        { name: 't2' },
+        { definition: {} }
+      ],
+      middleware: [testMiddleware],
+      routes: [
+        {
+          route: '/arrayroute',
+          handlers: ['post','get','put','delete'],
+          scopes: { post: 'testscope' }
+        },
+        {
+          route: '/objectroute',
+          handlers: {
+            post: testRouteHandler,
+            get: testRouteHandler,
+            put: testRouteHandler,
+            delete: testRouteHandler
+          }
+        }
+      ]
+    };
+  }
+}
+
+function testMiddleware(req, res, next) {
+  console.log('Test middleware called');
+}
+function testRouteHandler(req, res, next) {
+  console.log('Test handler called');
+}
+
+module.exports = TestApiModule;