Adapt authoring tool UI documentation

v1.0.0-rc.4

adapt-authoring-adaptframework/lib/AdaptFrameworkUtils.js

  1. import { App } from 'adapt-authoring-core'
  2. import FrameworkBuild from './AdaptFrameworkBuild.js'
  3. import FrameworkImport from './AdaptFrameworkImport.js'
  4. import fs from 'fs'
  5. import path from 'upath'
  6. import semver from 'semver'
  8. /** @ignore */ const buildCache = {}
  10. let fw
  11. /**
  12.  * Logs a message using the framework module
  13.  * @param {...*} args Arguments to be logged
  14.  */
  15. /** @ignore */
  16. async function log (...args) {
  17.   if (!fw) fw = await App.instance.waitForModule('adaptframework')
  18.   return fw.log(...args)
  19. }
  20. /**
  21.  * Utilities for use with the AdaptFrameworkModule
  22.  * @memberof adaptframework
  23.  */
  24. class AdaptFrameworkUtils {
  25.   /**
  26.    * Infers the framework action to be executed from a given request URL
  27.    * @param {external:ExpressRequest} req
  28.    * @return {String}
  29.    */
  30.   static inferBuildAction (req) {
  31.     return req.url.slice(1, req.url.indexOf('/', 1))
  32.   }
  34.   /**
  35.    * Retrieves metadata for a build attempt
  36.    * @param {String} id ID of build document
  37.    * @return {Promise}
  38.    */
  39.   static async retrieveBuildData (id) {
  40.     if (buildCache[id]) {
  41.       return buildCache[id]
  42.     }
  43.     const mdb = await App.instance.waitForModule('mongodb')
  44.     const [data] = await mdb.find('adaptbuilds', { _id: id })
  45.     buildCache[id] = data
  46.     return data
  47.   }
  49.   /**
  50.    * @typedef {AdaptFrameworkImportSummary}
  51.    * @property {String} title Course title
  52.    * @property {String} courseId Course _id
  53.    * @property {Object} statusReport Status report
  54.    * @property {Object<String>} statusReport.info Information messages
  55.    * @property {Array<String>} statusReport.warn Warning messages
  56.    * @property {Object} content Object mapping content types to the number of items of that type found in the imported course
  57.    * @property {Object} versions A map of plugins used in the imported course and their versions
  58.    *
  59.    * @param {AdaptFrameworkImport} importer The import instance
  60.    * @return {AdaptFrameworkImportSummary} Object mapping all import versions to server installed versions
  61.    * @example
  62.    * {
  63.    *   adapt_framework: [1.0.0, 2.0.0],
  64.    *   adapt-contrib-vanilla: [1.0.0, 2.0.0]
  65.    * }
  66.    */
  67.   static async getImportSummary (importer) {
  68.     const [framework, contentplugin] = await App.instance.waitForModule('adaptframework', 'contentplugin')
  69.     const installedPlugins = await contentplugin.find()
  70.     const {
  71.       pkg: { name: fwName, version: fwVersion },
  72.       idMap: { course: courseId },
  73.       contentJson,
  74.       usedContentPlugins: usedPlugins,
  75.       newContentPlugins: newPlugins,
  76.       statusReport,
  77.       settings: { updatePlugins }
  78.     } = importer
  79.     const versions = [
  80.       { name: fwName, versions: [framework.version, fwVersion] },
  81.       ...Object.values(usedPlugins),
  82.       ...Object.values(newPlugins)
  83.     ].map(meta => {
  84.       const p = installedPlugins.find(p => p.name === meta.name)
  85.       const versions = meta.versions ?? [p?.version, meta.version]
  86.       return {
  87.         name: meta.name,
  88.         status: this.getPluginUpdateStatus(versions, p?.isLocalInstall, updatePlugins),
  89.         versions
  90.       }
  91.     })
  92.     return {
  93.       title: contentJson.course.displayTitle || contentJson.course.title,
  94.       courseId,
  95.       statusReport,
  96.       content: this.getImportContentCounts(contentJson),
  97.       versions
  98.     }
  99.   }
  101.   /**
  102.    * Determines the update status code
  103.    * @param {Array} versions
  104.    * @param {Boolean} isLocalInstall
  105.    * @param {Boolean} updatePlugins
  106.    * @returns {String} The update status code
  107.    */
  108.   static getPluginUpdateStatus (versions, isLocalInstall, updatePlugins) {
  109.     const [installedVersion, importVersion] = versions
  110.     if (!installedVersion) return 'INSTALLED'
  111.     if (semver.lt(importVersion, installedVersion)) return 'OLDER'
  112.     if (semver.gt(importVersion, installedVersion)) {
  113.       if (!updatePlugins && !isLocalInstall) return 'UPDATE_BLOCKED'
  114.       return 'UPDATED'
  115.     }
  116.     return 'NO_CHANGE'
  117.   }
  119.   /**
  120.    * Returns a map of content types and their instance count in the content JSON
  121.    * @param {Object} content Course content
  122.    * @returns {Object}
  123.    */
  124.   static getImportContentCounts (content) {
  125.     return Object.values(content).reduce((m, c) => {
  126.       const items = c._type ? [c] : Object.values(c)
  127.       return items.reduce((m, { _type }) => {
  128.         return { ...m, [_type]: m[_type] !== undefined ? m[_type] + 1 : 1 }
  129.       }, m)
  130.     }, {})
  131.   }
  133.   /**
  134.    * Handles GET requests to the API
  135.    * @param {external:ExpressRequest} req
  136.    * @param {external:ExpressResponse} res
  137.    * @param {Function} next
  138.    * @return {Promise}
  139.    */
  140.   static async getHandler (req, res, next) {
  141.     const action = AdaptFrameworkUtils.inferBuildAction(req)
  142.     const id = req.params.id
  143.     let buildData
  144.     try {
  145.       buildData = await AdaptFrameworkUtils.retrieveBuildData(id)
  146.     } catch (e) {
  147.       return next(e)
  148.     }
  149.     if (!buildData || new Date(buildData.expiresAt).getTime() < Date.now()) {
  150.       return next(App.instance.errors.FW_BUILD_NOT_FOUND.setData({ _id: id }))
  151.     }
  152.     if (action === 'publish' || action === 'export') {
  153.       res.set('content-disposition', `attachment; filename="adapt-${action}-${buildData._id}.zip"`)
  154.       try {
  155.         return res.sendFile(path.resolve(buildData.location))
  156.       } catch (e) {
  157.         return next(e)
  158.       }
  159.     }
  160.     if (action === 'preview') {
  161.       if (!req.auth.user) {
  162.         return res.status(App.instance.errors.MISSING_AUTH_HEADER.statusCode).end()
  163.       }
  164.       const filePath = path.resolve(buildData.location, req.path.slice(req.path.indexOf(id) + id.length + 1) || 'index.html')
  165.       try {
  166.         await fs.promises.stat(filePath)
  167.         res.sendFile(filePath)
  168.       } catch (e) {
  169.         if (e.code === 'ENOENT') return next(App.instance.errors.NOT_FOUND.setData({ type: 'file', id: filePath }))
  170.         return next(e)
  171.       }
  172.     }
  173.   }
  175.   /**
  176.    * Handles POST requests to the API
  177.    * @param {external:ExpressRequest} req
  178.    * @param {external:ExpressResponse} res
  179.    * @param {Function} next
  180.    * @return {Promise}
  181.    */
  182.   static async postHandler (req, res, next) {
  183.     const startTime = Date.now()
  184.     const framework = await App.instance.waitForModule('adaptframework')
  185.     const action = AdaptFrameworkUtils.inferBuildAction(req)
  186.     const courseId = req.params.id
  187.     const userId = req.auth.user._id.toString()
  189.     log('info', `running ${action} for course '${courseId}'`)
  190.     try {
  191.       const { isPreview, buildData } = await FrameworkBuild.run({ action, courseId, userId })
  192.       const duration = Math.round((Date.now() - startTime) / 10) / 100
  193.       log('info', `finished ${action} for course '${courseId}' in ${duration} seconds`)
  194.       const urlRoot = isPreview ? framework.rootRouter.url : framework.apiRouter.url
  195.       res.json({
  196.         [`${action}_url`]: `${urlRoot}/${action}/${buildData._id}/`,
  197.         versions: buildData.versions
  198.       })
  199.     } catch (e) {
  200.       log('error', `failed to ${action} course '${courseId}'`)
  201.       return next(e)
  202.     }
  203.   }
  205.   /**
  206.    * Handles POST /import requests to the API
  207.    * @param {external:ExpressRequest} req
  208.    * @param {external:ExpressResponse} res
  209.    * @param {Function} next
  210.    * @return {Promise}
  211.    */
  212.   static async importHandler (req, res, next) {
  213.     try {
  214.       log('info', 'running course import')
  216.       await AdaptFrameworkUtils.handleImportFile(req, res)
  218.       const [course] = req.fileUpload.files.course
  219.       const importer = await FrameworkImport.run({
  220.         unzipPath: course.filepath,
  221.         userId: req.auth.user._id.toString(),
  222.         isDryRun: AdaptFrameworkUtils.toBoolean(req.body.dryRun),
  223.         assetFolders: req.body.formAssetFolders,
  224.         tags: req.body.tags?.length > 0 ? req.body.tags?.split(',') : [],
  225.         importContent: AdaptFrameworkUtils.toBoolean(req.body.importContent),
  226.         importPlugins: AdaptFrameworkUtils.toBoolean(req.body.importPlugins),
  227.         updatePlugins: AdaptFrameworkUtils.toBoolean(req.body.updatePlugins)
  228.       })
  229.       const summary = await AdaptFrameworkUtils.getImportSummary(importer)
  230.       res.json(summary)
  231.     } catch (e) {
  232.       return next(App.instance.errors.FW_IMPORT_FAILED.setData({ error: e }))
  233.     }
  234.   }
  236.   /**
  237.    * Handles POST /update requests to the API
  238.    * @param {external:ExpressRequest} req
  239.    * @param {external:ExpressResponse} res
  240.    * @param {Function} next
  241.    * @return {Promise}
  242.    */
  243.   static async postUpdateHandler (req, res, next) {
  244.     try {
  245.       log('info', 'running framework update')
  246.       const framework = await App.instance.waitForModule('adaptframework')
  247.       const previousVersion = framework.version
  248.       await framework.updateFramework(req.body.version)
  249.       const currentVersion = framework.version !== previousVersion ? framework.version : undefined
  250.       res.json({
  251.         from: previousVersion,
  252.         to: currentVersion
  253.       })
  254.     } catch (e) {
  255.       return next(e)
  256.     }
  257.   }
  259.   /**
  260.    * Handles GET /update requests to the API
  261.    * @param {external:ExpressRequest} req
  262.    * @param {external:ExpressResponse} res
  263.    * @param {Function} next
  264.    * @return {Promise}
  265.    */
  266.   static async getUpdateHandler (req, res, next) {
  267.     try {
  268.       const framework = await App.instance.waitForModule('adaptframework')
  269.       const current = framework.version
  270.       const latest = await framework.getLatestVersion()
  271.       res.json({
  272.         canBeUpdated: semver.gt(latest, current),
  273.         currentVersion: current,
  274.         latestCompatibleVersion: latest
  275.       })
  276.     } catch (e) {
  277.       return next(e)
  278.     }
  279.   }
  281.   /**
  282.    * Converts a body value to a valid boolean
  283.    * @param {*} val
  284.    * @returns {Boolean}
  285.    */
  286.   static toBoolean (val) {
  287.     if (val !== undefined) return val === true || val === 'true'
  288.   }
  290.   /**
  291.    * Deals with an incoming course (supports both local zip and remote URL stream)
  292.    * @param {external:ExpressRequest} req
  293.    * @param {external:ExpressResponse} res
  294.    * @return {Promise}
  295.    */
  296.   static async handleImportFile (req, res) {
  297.     const [fw, middleware] = await App.instance.waitForModule('adaptframework', 'middleware')
  298.     const handler = req.get('Content-Type').indexOf('multipart/form-data') === 0
  299.       ? middleware.fileUploadParser
  300.       : middleware.urlUploadParser
  301.     return new Promise((resolve, reject) => {
  302.       handler(middleware.zipTypes, { maxFileSize: fw.getConfig('importMaxFileSize'), unzip: true })(req, res, e => e ? reject(e) : resolve())
  303.     })
  304.   }
  305. }
  307. export default AdaptFrameworkUtils