@dwp/govuk-casa 7.0.6 → 8.0.0-alpha1

package/middleware/i18n/i18n.js

@@ -1,56 +0,0 @@
-/**
- * Configure multi-lingual support.
- *
- * This middleware will determine the language to use for each request, by
- * inspecting the query and existing session.
- *
- * Enhances `req` with:
- *   string language = The language code to use (ISO 639-1).
- *   Function i18nTranslator = A class instance to translate for the current req.
- *
- * Enhances `req.session` with:
- *   string language = The language code to use (ISO 639-1).
- *
- * Enhances `req.casa.journeyContext.nav` with
- *   string language = The language code to use (ISO 639-1).
- */
-
-module.exports = (logger, supportedLocales = [], translatorFactory) => (req, res, next) => {
-  const currentSessionLanguage = (req.session || Object.create(null)).language;
-
-  // Language pulled from query first, then session, then default
-  let language = req.query.lang || currentSessionLanguage || supportedLocales[0];
-  if (!supportedLocales.includes(language)) {
-    [language] = supportedLocales;
-  }
-  req.language = language;
-
-  // Update the journey context
-  if (req.casa && req.casa.journeyContext) {
-    req.casa.journeyContext.setNavigationLanguage(req.language);
-  }
-
-  // Create usable references to the translation function
-  req.i18nTranslator = translatorFactory(req.language);
-  res.locals.t = req.i18nTranslator.t.bind(req.i18nTranslator);
-  res.locals.locale = req.language;
-
-  // This is used by the GOVUK layout template
-  res.locals.htmlLang = req.language;
-
-  // When updating the session, we need to explicitly save before sending
-  // response because - depending on the session store - this operation may
-  // otherwise overlap with subsequent requests from the user.
-  if (req.session && req.language !== currentSessionLanguage) {
-    req.session.language = req.language;
-    logger.debug('saving new language (%s) to session', req.session.language)
-    req.session.save((err) => {
-      if (err) {
-        logger.error('Failed to save language to session. Error: %s', err.message);
-      }
-      next(err);
-    });
-  } else {
-    next();
-  }
-};

package/middleware/i18n/index.js

@@ -1,16 +0,0 @@
-const logger = require('../../lib/Logger.js')('i18n');
-
-const mwI18n = require('./i18n.js');
-
-module.exports = (app, supportedLocales = [], I18nUtility) => {
-  if (!Array.isArray(supportedLocales) || !supportedLocales.length) {
-    throw new TypeError('At least one supported locale is required');
-  }
-  if (typeof I18nUtility !== 'object') {
-    throw new TypeError('An instance of the I18n utility is required');
-  } else if (typeof I18nUtility.Translator !== 'function') {
-    throw new TypeError('Provided I18n utility is an invalid type');
-  }
-
-  app.use(mwI18n(logger, supportedLocales, (lang) => (new I18nUtility.Translator(lang))));
-};

package/middleware/index.js

@@ -1,55 +0,0 @@
-const errors = require('./errors/index.js');
-const errors404 = require('./errors/404.js');
-const errorsCatchAll = require('./errors/catch-all.js');
-
-const headers = require('./headers/index.js');
-const headersApply = require('./headers/headers.js');
-
-const i18n = require('./i18n/index.js');
-const i18nSetLanguage = require('./i18n/i18n.js');
-
-const mount = require('./mount/index.js');
-const mountRedirect = require('./mount/mount.js');
-
-const nunjucks = require('./nunjucks/index.js');
-const nunjucksEnvironment = require('./nunjucks/environment.js');
-
-const page = require('./page/index.js');
-const pageCsrf = require('./page/csrf.js');
-const pageEditMode = require('./page/edit-mode.js');
-const pageGather = require('./page/gather.js');
-const pageJourneyContinue = require('./page/journey-continue.js');
-const pageJourneyRails = require('./page/journey-rails.js');
-const pagePrepareRequest = require('./page/prepare-request.js');
-const pageRender = require('./page/render.js');
-const pageSkip = require('./page/skip.js');
-const pageValidate = require('./page/validate.js');
-
-module.exports = {
-  errors,
-  errors404,
-  errorsCatchAll,
-
-  headers,
-  headersApply,
-
-  i18n,
-  i18nSetLanguage,
-
-  mount,
-  mountRedirect,
-
-  nunjucks,
-  nunjucksEnvironment,
-
-  page,
-  pageCsrf,
-  pageEditMode,
-  pageGather,
-  pageJourneyContinue,
-  pageJourneyRails,
-  pagePrepareRequest,
-  pageRender,
-  pageSkip,
-  pageValidate,
-};

package/middleware/mount/index.js

@@ -1,9 +0,0 @@
-const logger = require('../../lib/Logger.js')('journey');
-const mwMount = require('./mount.js');
-
-module.exports = (app, mountUrl = '/') => {
-  if (mountUrl !== '/') {
-    logger.info('Attaching mount redirection for %s', mountUrl);
-    app.all('/', mwMount(logger, mountUrl));
-  }
-}

package/middleware/mount/mount.js

@@ -1,10 +0,0 @@
-/**
- * Redirect all requests to the configured mount point. This should only be
- * added to the `/` route, and only when a mount url other than "/" is
- * configured.
- */
-
-module.exports = (logger, mountUrl) => (req, res) => {
-  logger.trace('Redirecting to mountUrl %s', mountUrl);
-  res.status(302).redirect(mountUrl);
-}

package/middleware/nunjucks/environment.js

@@ -1,57 +0,0 @@
-/**
- * Configures view template engine (Nunjucks). Note that we do not set a
- * specific `view engine` setting, preferring to use explicit template file
- * extensions instead.
- *
- * This creates a `render()` method on the HTTP response object. To render a
- * template, `res.render('name-of-template', varsObject)`.
- *
- * Enhances `res` with:
- *  function render = Function to render and return a template response
- *  Environment nunjucksEnvironment = Nunjucks environment for this request.
- */
-
-const nunjucks = require('nunjucks');
-const path = require('path');
-
-/**
- * `govukFrontendDir` must be the path to the layout template file template.njk
- * which would typically be passed in from the result of:
- *   require.resolve('govuk-frontend')
- *
- * @param {object} logger Logger.
- * @param {Function} app Express app.
- * @param {Array} viewDirs List of view directories to register with Nunjucks.
- * @param {string} govukFrontendDir Path to `govuk-frontend` module.
- * @returns {nunjucks.Environment} Configured environment.
- */
-module.exports = (logger, app, viewDirs = [], govukFrontendDir = '') => {
-  // Resolve all application template search paths, and add CASA-specific dirs.
-  // Resolove priority: userland template > CASA templates > GOVUK templates
-  const dirViews = viewDirs.map((dir) => path.resolve(dir)).concat([
-    path.resolve(__dirname, '..', '..', 'views'),
-    path.resolve(govukFrontendDir),
-  ]);
-
-  // Prepare a single Nunjucks environment for all responses to use. Note that
-  // we cannot prepare response-specific global functions/filters if we use a
-  // single environment, but the performance gains of doing so are significant.
-  const loader = new nunjucks.FileSystemLoader(dirViews, {
-    watch: false,
-    noCache: false,
-  });
-
-  const env = new nunjucks.Environment(loader, {
-    autoescape: true,
-    throwOnUndefined: false,
-    trimBlocks: false,
-    lstripBlocks: false,
-  });
-
-  // Apply Nunjucks to Express and set as the default rendering engine
-  env.express(app);
-  app.set('view engine', 'njk');
-
-  logger.info('Nunjucks configured');
-  return env;
-}

package/middleware/nunjucks/index.js

@@ -1,8 +0,0 @@
-const logger = require('../../lib/Logger.js')('nunjucks');
-const mwEnvironment = require('./environment.js');
-const loadViewFilters = require('../../lib/view-filters/index.js');
-
-module.exports = (app, viewDirs = [], govukFrontendDir = '') => {
-  const env = mwEnvironment(logger, app, viewDirs, govukFrontendDir);
-  loadViewFilters(env);
-}

package/middleware/page/csrf.js

@@ -1,37 +0,0 @@
-/**
- * Generate CSRF protection to use on all mutating (POST) requests. The
- * `csrfSupplyToken` function will make the current token available to views
- * via the `casa.csrfToken` variable, which you can use as so:
- *   <input type="hidden" name="_csrf" value="{{ casa.csrfToken }}">.
- */
-
-const csrf = require('csurf');
-const commonBodyParser = require('../../lib/commonBodyParser.js');
-
-const mwCsrfProtection = csrf({
-  cookie: false,
-  sessionKey: 'session',
-  value: (req) => {
-    /* eslint-disable no-underscore-dangle */
-    // Here we clear the token after extracting to maintain cleaner data. It
-    // is only used for this CSRF purpose.
-    const token = String(req.body._csrf);
-    delete req.body._csrf;
-    return token;
-    /* eslint-enable no-underscore-dangle */
-  },
-});
-
-const mwCsrfSupplyToken = (req, res, next) => {
-  res.locals.casa.csrfToken = req.csrfToken();
-  next();
-};
-
-// All of these middleware are required to run in this sequence, so for
-// convenience they are returned as an array so they can be added to Express
-// middleware chain as one entity.
-module.exports = [
-  commonBodyParser,
-  mwCsrfProtection,
-  mwCsrfSupplyToken,
-];

package/middleware/page/edit-mode.js

@@ -1,52 +0,0 @@
-/**
- * Set `req.inEditMode`, `req.editOriginUrl`, and `req.editSearchParams`
- * attributes.
- *
- * Note `req.{query|body}.*` are all uri-decoded prior to this point.
- */
-
-const { createGetRequest, parseRequest } = require('../../lib/utils/index.js');
-const logger = require('../../lib/Logger')('page.edit-mode');
-
-module.exports = (mountUrl, allowPageEdit) => (req, res, next) => {
-  // Parse the request
-  const request = parseRequest(req);
-  const defaultEditOrigin = createGetRequest({
-    mountUrl,
-    ...request,
-    editMode: false,
-    editOrigin: '',
-  });
-
-  // Store edit information on request
-  req.editOriginUrl = allowPageEdit ? (request.editOrigin || defaultEditOrigin) : '';
-  req.inEditMode = allowPageEdit && request.editMode;
-  logger.trace('Set edit mode: %s (origin = %s)', req.inEditMode, req.editOriginUrl);
-
-  // Create a urlencoded string of the parameters for use in custom URLs
-  req.editSearchParams = req.inEditMode ? createGetRequest({
-    ...request,
-    mountUrl: undefined,
-    waypoint: undefined,
-    editMode: req.inEditMode,
-    editOrigin: req.editOriginUrl,
-  }) : '';
-
-  // Clean up
-  // We're no longer interested in these parameters, so declutter
-  if (req.query && 'edit' in req.query) {
-    delete req.query.edit;
-  }
-  if (req.body && 'edit' in req.body) {
-    delete req.body.edit;
-  }
-  if (req.query && 'editorigin' in req.query) {
-    delete req.query.editorigin;
-  }
-  if (req.body && 'editorigin' in req.body) {
-    delete req.body.editorigin;
-  }
-
-  // Next middleware
-  next();
-};

package/middleware/page/gather.js

@@ -1,75 +0,0 @@
-const commonBodyParser = require('../../lib/commonBodyParser.js');
-const createLogger = require('../../lib/Logger.js');
-const JourneyContext = require('../../lib/JourneyContext.js');
-const { executeHook, extractSessionableData, runGatherModifiers } = require('./utils.js');
-
-module.exports = (pageMeta = {}) => [commonBodyParser, (req, res, next) => {
-  const logger = createLogger('page.gather');
-  logger.setSessionId(req.session.id);
-
-  req.casa = req.casa || Object.create(null);
-
-  const pageId = pageMeta.id;
-  const { journeyOrigin, plan: journey } = req.casa;
-
-  // Take a traversal snapshot of the journey before we mutate the data/error
-  // context
-  logger.trace('Take pre-gather traversal snapshot');
-  req.casa.preGatherTraversalSnapshot = journey.traverse(req.casa.journeyContext, {
-    startWaypoint: journeyOrigin.waypoint,
-  });
-
-  /**
-   * Store data in request, clearing validation flags prior to validation.
-   *
-   * @param {object} data Data to store.
-   * @returns {void}
-   */
-  function storeSessionData(data) {
-    // Store gathered journey data, and clear any cached validation state for
-    // the page. Removing the validation state will prevent onward traversal
-    // from this page unil its new content has been validated (by the next
-    // middleware in the chain).
-    logger.trace('Storing session data for %s', pageId);
-    req.casa.journeyContext.setDataForPage(pageMeta, data);
-    req.casa.journeyContext.removeValidationStateForPage(pageId);
-    JourneyContext.putContext(req.session, req.casa.journeyContext);
-  }
-
-  // Promise
-  return executeHook(logger, req, res, pageMeta, 'pregather')
-    .then(() => {
-      // Only data that has matching validators defined in the page meta will be
-      // gathered and stored in the session
-      const preparedData = extractSessionableData(
-        logger,
-        pageMeta,
-        req.body,
-        req.casa.journeyContext,
-      );
-
-      // Run this page's "gather modifiers" against each prepared data item
-      if (Object.prototype.toString.call(pageMeta.fieldGatherModifiers) === '[object Object]') {
-        Object.keys(pageMeta.fieldGatherModifiers).forEach((fieldName) => {
-          logger.trace('Run gather-modifier for field %s on waypoint %s', fieldName, pageId);
-          const modifiedValue = runGatherModifiers(
-            preparedData[fieldName],
-            pageMeta.fieldGatherModifiers[fieldName],
-          );
-          preparedData[fieldName] = modifiedValue;
-        });
-      }
-
-      // Store all modified data back to req.body so downstream handlers have
-      // access to the modified data.
-      req.body = Object.assign(Object.create(null), req.body, preparedData);
-      return preparedData;
-    })
-    .then((modifiedData) => (storeSessionData(modifiedData)))
-    .then(() => {
-      next();
-    })
-    .catch((err) => {
-      next(err);
-    });
-}]

package/middleware/page/index.js

@@ -1,103 +0,0 @@
-/**
- * Default Page route.
- *
- * The logic in this route caters for 95% of use cases in this data-gathering
- * application. However, to there are a few options available that will allow
- * you to override or thread page-specific logic with this default behaviour if
- * needed:
- *
- * "Hooks":
- * --------
- * Most pages follow the "gather > save > validate > render" pathway, but might
- * need to do something a little different at stages in that pathway. Hooks can
- * be used to achieve this. Define hooks in the page meta object, e.g:
- *   pages['my-page'] = {
- *     hooks: {
- *       pregather: function(req, res, next) {},
- *       postvalidate: function(req, res, next) {},
- *       prerender: function(req, res, next) {}.
- *     }.
- *   }.
- *
- * The `next()` function takes an optional error object containing an array of
- * errors for each field, e.g:
- *   next({
- *     <fieldName>: [{inline: '...', summary: '...'}, ...],
- *     ...
- *   }).
- *
- * "Override":
- * -----------
- * To completely override the behaviour of a POST or GET route, define
- * appropriate handlers in the page's meta object. E.g:
- *   pages['my-page'] = {
- *     handlers: {
- *       get: function(req, res, next) {},
- *       post: function(req, res, next) {}
- *     }
- *   };.
- */
-
-const mwBodyParser = require('../../lib/commonBodyParser.js');
-const mwPrepare = require('./prepare-request.js');
-const mwSkip = require('./skip.js');
-const mwJourneyRails = require('./journey-rails.js');
-const mwJourneyContinue = require('./journey-continue.js');
-const mwCsrfProtection = require('./csrf.js');
-const mwDetectEditMode = require('./edit-mode.js');
-const mwGatherData = require('./gather.js');
-const mwValidateData = require('./validate.js');
-const mwRenderPage = require('./render.js');
-
-module.exports = function routePages(
-  mountUrl,
-  router,
-  pages,
-  plan,
-  allowPageEdit,
-  useStickyEdit,
-) {
-  const pageMetaKeys = pages.getAllPageIds();
-  const origins = plan.getOrigins();
-
-  // If there's only one origin waypoint, we won't bother prefixing urls with the
-  // origin id
-  let routePrefix = '/';
-  if (!origins.length) {
-    throw new ReferenceError('No origin waypoints have been defined. Cannot start plan traversal.');
-  } else if (origins.length > 1) {
-    routePrefix = `/(${origins.map((o) => o.originId).join('|')})`;
-  }
-
-  plan.getWaypoints().filter((w) => pageMetaKeys.includes(w)).forEach((waypoint) => {
-    const routeUrl = new RegExp(`^${routePrefix}/${waypoint}$`.replace(/\/+/g, '/'));
-    const pageMeta = pages.getPageMeta(waypoint);
-
-    router.get(
-      routeUrl,
-      mwBodyParser,
-      mwPrepare(mountUrl, plan),
-      mwDetectEditMode(mountUrl, allowPageEdit),
-      mwJourneyRails(mountUrl, plan),
-      mwCsrfProtection,
-      mwSkip(mountUrl),
-      // TODO: Maybe put the hook executions at this level? e.g.
-      // mwExecutePageHooks(pageMeta, 'prerender')
-      // because then custom routes could choose to include them or not
-      mwRenderPage(pageMeta),
-    );
-
-    router.post(
-      routeUrl,
-      mwBodyParser,
-      mwPrepare(mountUrl, plan),
-      mwDetectEditMode(mountUrl, allowPageEdit),
-      mwJourneyRails(mountUrl, plan),
-      mwCsrfProtection,
-      mwGatherData(pageMeta),
-      mwValidateData(pageMeta),
-      mwJourneyContinue(pageMeta, mountUrl, useStickyEdit),
-      mwRenderPage(pageMeta),
-    );
-  });
-};

package/middleware/page/journey-continue.js

@@ -1,157 +0,0 @@
-const createLogger = require('../../lib/Logger.js');
-const { executeHook } = require('./utils.js');
-const { parseRequest, createGetRequest } = require('../../lib/utils/index.js');
-
-module.exports = (pageMeta = {}, mountUrl = '/', useStickyEdit = false) => (req, res, next) => {
-  const logger = createLogger('page.journey-continue');
-  logger.setSessionId(req.session.id);
-  const pageId = pageMeta.id;
-
-  req.casa = req.casa || Object.create(null);
-
-  // If the page has errors, traversal must stop here until those errors are
-  // resolved. It is the responsibility of the next middleware to deal with
-  // these errors (usually `middleware/page/render.js`)
-  if (req.casa.journeyContext.hasValidationErrorsForPage(pageId)) {
-    logger.trace('Page %s has errors, not progressing journey. Passthrough to next middleware', pageId);
-    return next();
-  }
-
-  const { journeyOrigin, plan: journey } = req.casa;
-
-  const commonRedirectAttributes = {
-    // undefined because we're including the mountUrl in the waypoint portion of the request builder
-    mountUrl: undefined,
-    editOrigin: req.editOriginUrl,
-    contextId: req.casa.journeyContext.identity.id,
-  };
-
-  function calculateNextWaypoint() {
-    let nextWaypoint;
-
-    if (req.inEditMode) {
-      // Extract just the waypoint portion of the editOriginUrl, for comparison
-      // to waypoint during traversal. This will include the mountUrl.
-      const editOriginWaypoint = req.inEditMode && req.editOriginUrl ? `/${parseRequest({
-        method: req.method,
-        url: req.editOriginUrl,
-        query: {},
-        body: {},
-      }).waypoint}` : '';
-
-      // When in edit mode, the user should be redirected back to
-      // `req.editOriginUrl` after submitting their update unless - due to the
-      // journey data being altered - the waypoints along the journey have
-      // changed. If the user hasn't yet reached the edit origin url, the
-      // 'rails' middleware will ensure they are redirected back to the
-      // correct next waypoint.
-      let nextOrigin = journeyOrigin.originId || '';
-      nextWaypoint = editOriginWaypoint;
-      logger.trace('Comparing pre-gather traversal snapshot (starting from origin %s)', nextOrigin);
-
-      // Grab the list of traversed waypoints as it was before gathering, and
-      // generate a new list of traversed waypoints based on the new context.
-      const { preGatherTraversalSnapshot = [] } = req.casa || Object.create(null);
-      const currentTraversalSnapshot = journey.traverseNextRoutes(req.casa.journeyContext, {
-        startWaypoint: journeyOrigin.waypoint,
-      });
-
-      // Compare the two snapshots. Some rules:
-      // `a, b, c` vs `a, b, x, c` <- should stop at `x` (`x` was inserted) <- [..++..]
-      // `a, b, c, d` vs `a, b, d` <- should stop at `d` (`c` was removed) <- [..-.]
-      // `a, b, c, d` vs `a, c, d` <- should stop at `d` (`b` was removed) <- [.-..]
-      // `a, b, c` vs `a, c, d`    <- should stop at `d` (`b` was removed, `d` was added) <- [.-..+]
-      let compareIndex = 0;
-      const compareIndexMax = preGatherTraversalSnapshot.length - 1;
-      for (let i = 0, l = currentTraversalSnapshot.length; i < l; i++) {
-        // Build waypoint URL for the current waypoint
-        const waypointUrl = `${mountUrl}/${currentTraversalSnapshot[i].label.sourceOrigin || nextOrigin}/${currentTraversalSnapshot[i].source}`.replace(/\/+/g, '/');
-
-        // Stop testing if we've arrived at the edit origin waypoint
-        if (editOriginWaypoint === waypointUrl) {
-          nextWaypoint = editOriginWaypoint;
-          break;
-        }
-
-        // Find a match for the current waypoint in the previous snapshot.
-        // And track a change in origin, assuming that all subsequent matches
-        // (until the next change of origin) are accessed from that origin.
-        while (compareIndex <= compareIndexMax) {
-          nextWaypoint = waypointUrl;
-          nextOrigin = currentTraversalSnapshot[i].label.targetOrigin || nextOrigin;
-          if (currentTraversalSnapshot[i].source === preGatherTraversalSnapshot[compareIndex++]) {
-            // The current snapshot may include more waypoints than than the
-            // previous. In this case, if we've exhausted the list of previous
-            // waypoints, with the last one being a match, we must leave the user on
-            // the next waypoint in the current snapshot. Otherwise, the user will
-            // be left on the same after submitting the form.
-            if ((compareIndex > compareIndexMax) && (i < l - 1)) {
-              nextWaypoint = `${mountUrl}/${nextOrigin}/${currentTraversalSnapshot[i + 1].source}`.replace(/\/+/g, '/');
-              nextOrigin = currentTraversalSnapshot[i + 1].label.targetOrigin || nextOrigin;
-            }
-
-            break;
-          }
-        }
-      }
-
-      // Ensure the user remains in edit mode after redirecting, unless they're
-      // being sent back to the edit origin anyway
-      nextWaypoint = createGetRequest({
-        ...commonRedirectAttributes,
-        waypoint: nextWaypoint,
-        editMode: useStickyEdit && nextWaypoint !== editOriginWaypoint,
-      });
-    } else if (journey.containsWaypoint(pageId)) {
-      logger.trace('Check waypoint %s can be reached (journey guid = %s)', pageId, journeyOrigin.originId);
-      const routes = journey.traverseNextRoutes(req.casa.journeyContext, {
-        startWaypoint: journeyOrigin.waypoint,
-      });
-      const waypoints = routes.map((e) => e.source);
-
-      const positionInJourney = Math.min(
-        waypoints.indexOf(pageId),
-        waypoints.length - 2,
-      );
-      if (positionInJourney > -1) {
-        const route = routes[positionInJourney];
-        nextWaypoint = `${mountUrl}/${route.label.targetOrigin || journeyOrigin.originId || ''}/${waypoints[positionInJourney + 1]}`.replace(/\/+/g, '/');
-      } else {
-        nextWaypoint = req.originalUrl;
-      }
-
-      nextWaypoint = createGetRequest({
-        ...commonRedirectAttributes,
-        waypoint: nextWaypoint,
-        editMode: false,
-      });
-    } else {
-      logger.trace('Waypoint %s not in journey %s. Returning to original url', pageId, journeyOrigin.originId);
-      nextWaypoint = req.originalUrl;
-    }
-
-    return nextWaypoint;
-  }
-
-  function redirect(url) {
-    // Because the hash fragment persists over a redirect, we reset it here.
-    // Session does not reliably persist when issuing a redirect, so here we
-    // save explicitly.
-    req.session.save((err) => {
-      if (err) {
-        logger.error('Failed to save session prior to redirect. %s', err.message);
-        next(err);
-      } else {
-        logger.trace('Redirect: %s -> %s', pageId, url);
-        res.status(302).redirect(`${url}#`);
-      }
-    });
-  }
-
-  return executeHook(logger, req, res, pageMeta, 'preredirect')
-    .then(calculateNextWaypoint)
-    .then(redirect)
-    .catch((err) => {
-      next(err);
-    });
-}