adapt-authoring-api 3.1.4 → 3.2.0

package/lib/AbstractApiModule.js

@@ -49,6 +49,12 @@ class AbstractApiModule extends AbstractModule {
      * @type {Hook}
      */
     this.preInsertHook = new Hook({ mutable: true })
+    /**
+     * Middleware hook that wraps the entire insert operation (pre-hook, validate, write, post-hook).
+     * Observers receive (next, data, options, mongoOptions) and must call next() to continue.
+     * @type {Hook}
+     */
+    this.insertHook = new Hook({ type: Hook.Types.Middleware })
     /**
      * Hook invoked after data is inserted into the database
      * @type {Hook}
@@ -59,6 +65,12 @@ class AbstractApiModule extends AbstractModule {
      * @type {Hook}
      */
     this.preUpdateHook = new Hook({ mutable: true })
+    /**
+     * Middleware hook that wraps the entire update operation (pre-hook, validate, write, post-hook).
+     * Observers receive (next, query, data, options, mongoOptions) and must call next() to continue.
+     * @type {Hook}
+     */
+    this.updateHook = new Hook({ type: Hook.Types.Middleware })
     /**
      * Hook invoked after data is updated in the database
      * @type {Hook}
@@ -69,6 +81,12 @@ class AbstractApiModule extends AbstractModule {
      * @type {Hook}
      */
     this.preDeleteHook = new Hook()
+    /**
+     * Middleware hook that wraps the entire delete operation (pre-hook, validate, write, post-hook).
+     * Observers receive (next, query, options, mongoOptions) and must call next() to continue.
+     * @type {Hook}
+     */
+    this.deleteHook = new Hook({ type: Hook.Types.Middleware })
     /**
      * Hook invoked after data is deleted
      * @type {Hook}
@@ -79,7 +97,7 @@ class AbstractApiModule extends AbstractModule {
      * @type {Hook}
      */
     this.accessCheckHook = new Hook()
-
+    
     await this.setValues()
     this.validateValues()
     await this.addRoutes()
@@ -123,7 +141,12 @@ class AbstractApiModule extends AbstractModule {
 
     const config = await loadRouteConfig(this.rootDir, this, {
       schema: 'apiroutes',
-      defaults: `${import.meta.dirname}/../default-routes.json`
+      handlerAliases: {
+        default: this.requestHandler(),
+        query: this.queryHandler(),
+        serveSchema: this.serveSchema.bind(this)
+      },
+      defaults: new URL('./default-routes.json', import.meta.url).pathname
     })
     if (config) this.applyRouteConfig(config)
   }
@@ -357,129 +380,135 @@ class AbstractApiModule extends AbstractModule {
    * Middleware to handle a generic API request. Supports POST, GET, PUT and DELETE of items in the database.
    * @return {Function} Express middleware function
    */
-  async requestHandler (req, res, next) {
-    const method = req.method.toLowerCase()
-    const func = this[httpMethodToDBFunction(method)]
-    if (!func) {
-      return next(this.app.errors.HTTP_METHOD_NOT_SUPPORTED.setData({ method }))
-    }
-    let data
-    try {
-      await this.requestHook.invoke(req)
-      const preCheck = method !== 'get' && method !== 'post'
-      const postCheck = method === 'get'
-      if (preCheck) {
-        await this.checkAccess(req, req.apiData.query)
+  requestHandler () {
+    const requestHandler = async (req, res, next) => {
+      const method = req.method.toLowerCase()
+      const func = this[httpMethodToDBFunction(method)]
+      if (!func) {
+        return next(this.app.errors.HTTP_METHOD_NOT_SUPPORTED.setData({ method }))
       }
-      data = await func.apply(this, argsFromReq(req))
-      if (postCheck) {
-        data = await this.checkAccess(req, data)
+      let data
+      try {
+        await this.requestHook.invoke(req)
+        const preCheck = method !== 'get' && method !== 'post'
+        const postCheck = method === 'get'
+        if (preCheck) {
+          await this.checkAccess(req, req.apiData.query)
+        }
+        data = await func.apply(this, argsFromReq(req))
+        if (postCheck) {
+          data = await this.checkAccess(req, data)
+        }
+        data = await this.sanitise(req.apiData.schemaName, data, { isInternal: true, strict: false })
+      } catch (e) {
+        return next(e)
       }
-      data = await this.sanitise(req.apiData.schemaName, data, { isInternal: true, strict: false })
-    } catch (e) {
-      return next(e)
-    }
-    if (Array.isArray(data) && req.params._id) { // special case for when _id param is present
-      if (!data.length) {
-        return next(this.app.errors.NOT_FOUND.setData({ id: req.params._id, type: req.apiData.schemaName }))
+      if (Array.isArray(data) && req.params._id) { // special case for when _id param is present
+        if (!data.length) {
+          return next(this.app.errors.NOT_FOUND.setData({ id: req.params._id, type: req.apiData.schemaName }))
+        }
+        data = data[0]
       }
-      data = data[0]
-    }
-    if (method !== 'get') {
-      const resource = Array.isArray(data) ? req.apiData.query : data._id.toString()
-      this.log('debug', `API_${func.name.toUpperCase()}`, resource, 'by', req.auth.user._id.toString())
+      if (method !== 'get') {
+        const resource = Array.isArray(data) ? req.apiData.query : data._id.toString()
+        this.log('debug', `API_${func.name.toUpperCase()}`, resource, 'by', req.auth.user._id.toString())
+      }
+      res.status(this.mapStatusCode(method)).json(data)
     }
-    res.status(this.mapStatusCode(method)).json(data)
+    return requestHandler
   }
 
   /**
    * Express request handler for advanced API queries. Supports collation/limit/page/skip/sort and pagination. For incoming query data to be correctly parsed, it must be sent as body data using a POST request.
    * @return {function}
    */
-  async queryHandler (req, res, next) {
-    try {
-      const opts = {
-        schemaName: req.apiData.schemaName,
-        collectionName: req.apiData.collectionName
-      }
-      const mongoOpts = {}
-      // find and remove mongo options from the query
-      Object.entries(req.apiData.query).forEach(([key, val]) => {
-        if (['collation', 'limit', 'page', 'skip', 'sort'].includes(key)) {
-          try {
-            mongoOpts[key] = JSON.parse(req.apiData.query[key])
-          } catch (e) {
-            this.log('warn', `failed to parse query ${key} param '${mongoOpts[key]}', ${e}`)
-          }
-          delete req.apiData.query[key]
-        } else {
-          // otherwise assume we have a query field or option and store for later processing
-          opts[key] = val
+  queryHandler () {
+    const queryHandler = async (req, res, next) => {
+      try {
+        const opts = {
+          schemaName: req.apiData.schemaName,
+          collectionName: req.apiData.collectionName
         }
-      })
-      // handle search parameter
-      const search = req.apiData.query.search
-      if (search) {
-        delete req.apiData.query.search
-        try {
-          const schema = await this.getSchema(req.apiData.schemaName)
-          if (schema && schema.built && schema.built.properties) {
-            const searchableFields = Object.keys(schema.built.properties).filter(
-              field => schema.built.properties[field].isSearchable === true
-            )
-            if (searchableFields.length) {
-              // escape special regex characters to prevent ReDoS attacks
-              const escapedSearch = search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-              const regex = { $regex: escapedSearch, $options: 'i' }
-              const searchConditions = searchableFields.map(f => ({ [f]: regex }))
-              // merge with existing $or if present
-              if (req.apiData.query.$or) {
-                req.apiData.query.$and = [
-                  { $or: req.apiData.query.$or },
-                  { $or: searchConditions }
-                ]
-                delete req.apiData.query.$or
-              } else {
-                req.apiData.query.$or = searchConditions
+        const mongoOpts = {}
+        // find and remove mongo options from the query
+        Object.entries(req.apiData.query).forEach(([key, val]) => {
+          if (['collation', 'limit', 'page', 'skip', 'sort'].includes(key)) {
+            try {
+              mongoOpts[key] = JSON.parse(req.apiData.query[key])
+            } catch (e) {
+              this.log('warn', `failed to parse query ${key} param '${mongoOpts[key]}', ${e}`)
+            }
+            delete req.apiData.query[key]
+          } else {
+            // otherwise assume we have a query field or option and store for later processing
+            opts[key] = val
+          }
+        })
+        // handle search parameter
+        const search = req.apiData.query.search
+        if (search) {
+          delete req.apiData.query.search
+          try {
+            const schema = await this.getSchema(req.apiData.schemaName)
+            if (schema && schema.built && schema.built.properties) {
+              const searchableFields = Object.keys(schema.built.properties).filter(
+                field => schema.built.properties[field].isSearchable === true
+              )
+              if (searchableFields.length) {
+                // escape special regex characters to prevent ReDoS attacks
+                const escapedSearch = search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+                const regex = { $regex: escapedSearch, $options: 'i' }
+                const searchConditions = searchableFields.map(f => ({ [f]: regex }))
+                // merge with existing $or if present
+                if (req.apiData.query.$or) {
+                  req.apiData.query.$and = [
+                    { $or: req.apiData.query.$or },
+                    { $or: searchConditions }
+                  ]
+                  delete req.apiData.query.$or
+                } else {
+                  req.apiData.query.$or = searchConditions
+                }
               }
             }
+          } catch (e) {
+            this.log('warn', `failed to process search parameter, ${e.message}`)
           }
-        } catch (e) {
-          this.log('warn', `failed to process search parameter, ${e.message}`)
         }
-      }
-      req.apiData.query = await this.parseQuery(req.apiData.schemaName, req.body, mongoOpts)
-      // remove any valid query keys from the options
-      Object.keys(req.apiData.query).forEach(key => delete opts[key])
+        req.apiData.query = await this.parseQuery(req.apiData.schemaName, req.body, mongoOpts)
+        // remove any valid query keys from the options
+        Object.keys(req.apiData.query).forEach(key => delete opts[key])
 
-      await this.requestHook.invoke(req)
+        await this.requestHook.invoke(req)
 
-      await this.setUpPagination(req, res, mongoOpts)
+        await this.setUpPagination(req, res, mongoOpts)
 
-      let results = await this.find(req.apiData.query, opts, mongoOpts)
+        let results = await this.find(req.apiData.query, opts, mongoOpts)
 
-      results = await this.checkAccess(req, results)
+        results = await this.checkAccess(req, results)
 
-      // If checkAccess filtered some results, fetch more to fill the page
-      const pageSize = mongoOpts.limit
-      if (pageSize && results.length < pageSize) {
-        let fetchSkip = mongoOpts.skip + pageSize
-        while (results.length < pageSize) {
-          const extra = await this.find(req.apiData.query, opts, { ...mongoOpts, skip: fetchSkip })
-          if (!extra.length) break
-          const filtered = await this.checkAccess(req, extra)
-          results = results.concat(filtered)
-          fetchSkip += extra.length
+        // If checkAccess filtered some results, fetch more to fill the page
+        const pageSize = mongoOpts.limit
+        if (pageSize && results.length < pageSize) {
+          let fetchSkip = mongoOpts.skip + pageSize
+          while (results.length < pageSize) {
+            const extra = await this.find(req.apiData.query, opts, { ...mongoOpts, skip: fetchSkip })
+            if (!extra.length) break
+            const filtered = await this.checkAccess(req, extra)
+            results = results.concat(filtered)
+            fetchSkip += extra.length
+          }
+          if (results.length > pageSize) results = results.slice(0, pageSize)
         }
-        if (results.length > pageSize) results = results.slice(0, pageSize)
-      }
 
-      results = await this.sanitise(req.apiData.schemaName, results, { isInternal: true, strict: false })
+        results = await this.sanitise(req.apiData.schemaName, results, { isInternal: true, strict: false })
 
-      res.status(this.mapStatusCode('get')).json(results)
-    } catch (e) {
-      return next(e)
+        res.status(this.mapStatusCode('get')).json(results)
+      } catch (e) {
+        return next(e)
+      }
     }
+    return queryHandler
   }
 
   /**
@@ -594,16 +623,22 @@ class AbstractApiModule extends AbstractModule {
    * @return {Promise} Resolves with DB data
    */
   async insert (data, options = {}, mongoOptions = {}) {
-    options.schemaName = options.schemaName ?? await this.getSchemaName(data)
-    this.setDefaultOptions(options)
-    if (options.invokePreHook !== false) await this.preInsertHook.invoke(data, options, mongoOptions)
+    const core = async (data, options, mongoOptions) => {
+      options.schemaName = options.schemaName ?? await this.getSchemaName(data)
+      this.setDefaultOptions(options)
+      if (options.invokePreHook !== false) await this.preInsertHook.invoke(data, options, mongoOptions)
 
-    data = await this.validate(options.schemaName, data, options)
-    const mongodb = await this.app.waitForModule('mongodb')
-    const results = await mongodb.insert(options.collectionName, data, mongoOptions)
+      data = await this.validate(options.schemaName, data, options)
+      const mongodb = await this.app.waitForModule('mongodb')
+      const results = await mongodb.insert(options.collectionName, data, mongoOptions)
 
-    if (options.invokePostHook !== false) await this.postInsertHook.invoke(results)
-    return results
+      if (options.invokePostHook !== false) await this.postInsertHook.invoke(results)
+      return results
+    }
+    if (this.insertHook.hasObservers) {
+      return this.insertHook.invoke(core, data, options, mongoOptions)
+    }
+    return core(data, options, mongoOptions)
   }
 
   /**
@@ -646,26 +681,32 @@ class AbstractApiModule extends AbstractModule {
    * @return {Promise} Resolves with DB data
    */
   async update (query, data, options = {}, mongoOptions = {}) {
-    options.schemaName = options.schemaName ?? await this.getSchemaName(data)
-    this.setDefaultOptions(options)
+    const core = async (query, data, options, mongoOptions) => {
+      options.schemaName = options.schemaName ?? await this.getSchemaName(data)
+      this.setDefaultOptions(options)
 
-    const mongodb = await this.app.waitForModule('mongodb')
-    const [originalDoc] = await mongodb.find(options.collectionName, query)
+      const mongodb = await this.app.waitForModule('mongodb')
+      const [originalDoc] = await mongodb.find(options.collectionName, query)
 
-    if (!originalDoc) {
-      throw this.app.errors.NOT_FOUND.setData({ id: query._id ?? query.toString(), type: options.schemaName })
-    }
-    const formattedData = options.rawUpdate ? { $set: {}, ...data } : { $set: data }
+      if (!originalDoc) {
+        throw this.app.errors.NOT_FOUND.setData({ id: query._id ?? query.toString(), type: options.schemaName })
+      }
+      const formattedData = options.rawUpdate ? { $set: {}, ...data } : { $set: data }
 
-    if (options.invokePreHook !== false) await this.preUpdateHook.invoke(originalDoc, formattedData.$set, options, mongoOptions)
-    formattedData.$set = await this.validate(options.schemaName, {
-      ...stringifyValues(originalDoc),
-      ...formattedData.$set
-    }, options)
+      if (options.invokePreHook !== false) await this.preUpdateHook.invoke(originalDoc, formattedData.$set, options, mongoOptions)
+      formattedData.$set = await this.validate(options.schemaName, {
+        ...stringifyValues(originalDoc),
+        ...formattedData.$set
+      }, options)
 
-    const results = await mongodb.update(options.collectionName, query, formattedData, mongoOptions)
-    if (options.invokePostHook !== false) await this.postUpdateHook.invoke(originalDoc, results)
-    return results
+      const results = await mongodb.update(options.collectionName, query, formattedData, mongoOptions)
+      if (options.invokePostHook !== false) await this.postUpdateHook.invoke(originalDoc, results)
+      return results
+    }
+    if (this.updateHook.hasObservers) {
+      return this.updateHook.invoke(core, query, data, options, mongoOptions)
+    }
+    return core(query, data, options, mongoOptions)
   }
 
   /**
@@ -705,18 +746,24 @@ class AbstractApiModule extends AbstractModule {
    * @return {Promise} Resolves with DB data
    */
   async delete (query, options = {}, mongoOptions = {}) {
-    this.setDefaultOptions(options)
+    const core = async (query, options, mongoOptions) => {
+      this.setDefaultOptions(options)
 
-    const mongodb = await this.app.waitForModule('mongodb')
-    const [originalDoc] = await mongodb.find(options.collectionName, query)
+      const mongodb = await this.app.waitForModule('mongodb')
+      const [originalDoc] = await mongodb.find(options.collectionName, query)
 
-    if (!originalDoc) {
-      throw this.app.errors.NOT_FOUND.setData({ id: query._id ?? query.toString(), type: options.schemaName })
+      if (!originalDoc) {
+        throw this.app.errors.NOT_FOUND.setData({ id: query._id ?? query.toString(), type: options.schemaName })
+      }
+      if (options.invokePreHook !== false) await this.preDeleteHook.invoke(originalDoc, options, mongoOptions)
+      await mongodb.delete(options.collectionName, query, mongoOptions)
+      if (options.invokePostHook !== false) await this.postDeleteHook.invoke(originalDoc)
+      return originalDoc
+    }
+    if (this.deleteHook.hasObservers) {
+      return this.deleteHook.invoke(core, query, options, mongoOptions)
     }
-    if (options.invokePreHook !== false) await this.preDeleteHook.invoke(originalDoc, options, mongoOptions)
-    await mongodb.delete(options.collectionName, query, mongoOptions)
-    if (options.invokePostHook !== false) await this.postDeleteHook.invoke(originalDoc)
-    return originalDoc
+    return core(query, options, mongoOptions)
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-api",
-  "version": "3.1.4",
+  "version": "3.2.0",
   "description": "Abstract module for creating APIs",
   "homepage": "https://github.com/adapt-security/adapt-authoring-api",
   "license": "GPL-3.0",