hof 22.7.0-service-paused-beta.13 → 22.7.0-service-unavailable-beta.2

package/CHANGELOG.md

@@ -1,9 +1,11 @@
-## 2025-05-14, Version 22.7.0 (Stable), @Rhodine-orleans-lindsay
+## 2025-05-20, Version 22.7.0 (Stable), @Rhodine-orleans-lindsay @sulthan-ahmed
 ### Added
-- Service paused funtionality that allows for services to redirect to a 'Service Unavailable' when there is a need to pause a service.
-  - Adds 'service paused' error middleware
-  - Includes default service paused html view
-  - Includes flag to set service paused config to true or false in order to enable page
+- 'Service Unavailable' functionality added which allows for services to redirect to a 'Service Unavailable' page when there is a need to pause a service for things like maintenance:
+  - Adds 'service unavailable' error middleware
+  - Includes default service unavailable html view
+  - Includes flag to set `SERVICE_UNAVAILABLE` config to true to enable the functionality
+### Changed
+- Error pages can now show the service name in the title and journey header
 ### Security
 - Updates patch and minor dependencies
 

package/README.md

@@ -805,7 +805,7 @@ const pdfData = await pdfModel.save();
 
 # HOF Middleware
 
-A collection of commonly used HOF middleware, exports `cookies`, `notFound`, `servicePaused` and `errors` on `middleware`
+A collection of commonly used HOF middleware, exports `cookies`, `notFound`, `serviceUnavailable` and `errors` on `middleware`
 
 ## Arranging the middleware in your app
 
@@ -844,18 +844,18 @@ You can also provide an array of healthcheck URLs with `healthcheckUrls`,
 should you not want to throw a Cookies required error when requesting the app with specific URLs.
 Kubernetes healthcheck URLs are provided as defaults if no overrides are supplied.
 
-## Service Unavailable (Service Paused)
-Allows a service to be paused when required and then resumed. It ensures that anyone using the service  that lands on any part of the form is diverted to a "Service Unavailable" page which will communicate to the user that the service is not available at this time.
+## Service Unavailable
+Allows a service to be paused when required and then resumed. It ensures that anyone using the service that lands on any part of the form is diverted to a "Service Unavailable" page which will communicate to the user that the service is not available at this time.
 
 ### Usage
-- Set the `SERVICE_PAUSED` env to `true` in your service.
+- Set the `SERVICE_UNAVAILABLE` env to `true` in your service.
 
 ### Page Content Customisation
 There is default text for this page. Default text can be overridden by setting the `message` and `answers-saved` properties in the `errors.json` file of the service. Note that information relating to who to contact and alternatives to using the form is optional and so there is no default text for these unless the properties `contact` and `alternative` are set in errors.json:
 
 ```json
 {
-  "service-paused" : {
+  "service-unavailable" : {
     "message": "This service will be unavailble for a week.",
     "answers-saved":  "Your answers have not been saved.",
     "contact":  "You can contact test@test.com for more information",

package/config/hof-defaults.js

@@ -1,6 +1,8 @@
 'use strict';
 /* eslint no-process-env: "off" */
 const rateLimits = require('./rate-limits');
+const Helper = require('../utilities/helpers');
+const parseBoolean = Helper.getEnvBoolean;
 
 const defaults = {
   appName: process.env.APP_NAME || 'HOF Application',
@@ -9,7 +11,7 @@ const defaults = {
   translations: 'translations',
   start: true,
   csp: {
-    disabled: process.env.DISABLE_CSP === 'true'
+    disabled: parseBoolean(process.env.DISABLE_CSP, false, 'DISABLE_CSP')
   },
   getCookies: true,
   getTerms: true,
@@ -52,7 +54,7 @@ const defaults = {
   },
   serveStatic: process.env.SERVE_STATIC_FILES !== 'false',
   sessionTimeOutWarning: process.env.SESSION_TIMEOUT_WARNING || 300,
-  servicePaused: process.env.SERVICE_PAUSED || false
+  serviceUnavailable: parseBoolean(process.env.SERVICE_UNAVAILABLE, false, 'SERVICE_UNAVAILABLE')
 };
 
 module.exports = Object.assign({}, defaults, rateLimits);

package/frontend/template-partials/translations/src/en/errors.json

@@ -27,7 +27,7 @@
     "pre-time-to-wait": "Please try again in ",
     "post-time-to-wait": " minutes."
   },
-  "service-paused": {
+  "service-unavailable": {
     "title": "Sorry, the service is unavailable",
     "message": "This service is temporarily unavailable.",
     "answers-saved": "Your answers have not been saved."

package/frontend/template-partials/views/service-unavailable.html

@@ -0,0 +1,13 @@
+{{<error}}
+  {{$content}}
+   <h1 class="govuk-heading-l">{{title}}</h1>
+   <p class="govuk-body">{{message}}</p>
+   <p class="govuk-body">{{answers-saved}}</p>
+   {{#contact}}
+   <p class="govuk-body">{{contact}}</p>
+   {{/contact}}
+   {{#alternative}}
+   <p class="govuk-body">{{alternative}}</p>
+   {{/alternative}}
+  {{/content}}
+{{/error}}

package/index.js

@@ -51,8 +51,8 @@ const loadRoutes = (app, config) => {
 };
 
 const applyErrorMiddlewares = (app, config) => {
-  if (config.servicePaused === true || config.servicePaused === 'true') {
-    app.use(hofMiddleware.servicePaused({
+  if (config.serviceUnavailable === true) {
+    app.use(hofMiddleware.serviceUnavailable({
       logger: config.logger
     }));
   }
@@ -161,7 +161,7 @@ function bootstrap(options) {
     res.locals.sessionTimeoutWarningContent = config.sessionTimeoutWarningContent;
     res.locals.exitFormContent = config.exitFormContent;
     res.locals.saveExitFormContent = config.saveExitFormContent;
-    res.locals.servicePaused = config.servicePaused;
+    res.locals.serviceUnavailable = config.serviceUnavailable;
     next();
   });
 
@@ -238,10 +238,12 @@ function bootstrap(options) {
   // Set up routing so <YOUR-SITE-URL>/assets are served from /node_modules/govuk-frontend/govuk/assets
   app.use('/assets', express.static(path.join(__dirname, '/node_modules/govuk-frontend/govuk/assets')));
   // Check if service has been paused and redirect accordingly
-  if (config.servicePaused === true || config.servicePaused === 'true') {
+  const bypassPaths = ['/assets', '/healthcheck', '/service-unavailable'];
+
+  if (config.serviceUnavailable === true) {
     app.use((req, res, next) => {
-      if (req.path !== '/service-paused') {
-        return res.redirect('/service-paused');
+      if (!bypassPaths.some(bypassPath => req.path.startsWith(bypassPath))) {
+        return res.redirect('/service-unavailable');
       }
       return next();
     });

package/middleware/errors.js

@@ -5,71 +5,75 @@ const rateLimitsConfig = require('../config/rate-limits');
 
 const errorTitle = code => `${code}_ERROR`;
 const errorMsg = code => `There is a ${code}_ERROR`;
+
 // eslint-disable-next-line complexity
 const getContent = (err, translate) => {
   const content = {};
 
+  // Helper to safely call translate if it's a function
+  const t = key => (typeof translate === 'function' ? translate(key) : undefined);
+
   if (err.code === 'SESSION_TIMEOUT') {
     err.status = 401;
     err.template = 'session-timeout';
-    err.serviceName = (translate && translate('journey.serviceName') || translate('journey.header'));
-    err.title = (translate && translate('errors.session.title'));
-    err.message = (translate && translate('errors.session.message'));
-    content.serviceName = (translate && translate('journey.serviceName') || translate('journey.header'));
-    content.title = (translate && translate('errors.session.title'));
-    content.message = (translate && translate('errors.session.message'));
+    err.serviceName = t('journey.serviceName') || t('journey.header');
+    err.title = t('errors.session.title');
+    err.message = t('errors.session.message');
+    content.serviceName = t('journey.serviceName') || t('journey.header');
+    content.title = t('errors.session.title');
+    content.message = t('errors.session.message');
   }
 
   if (err.code === 'NO_COOKIES') {
     err.status = 403;
     err.template = 'cookie-error';
-    content.serviceName = (translate && translate('journey.serviceName') || translate('journey.header'));
-    content.title = (translate && translate('errors.cookies-required.title'));
-    content.message = (translate && translate('errors.cookies-required.message'));
+    content.serviceName = t('journey.serviceName') || t('journey.header');
+    content.title = t('errors.cookies-required.title');
+    content.message = t('errors.cookies-required.message');
   }
 
   if (err.code === 'DDOS_RATE_LIMIT') {
     err.status = 429;
     err.template = 'rate-limit-error';
-    err.serviceName = (translate && translate('journey.serviceName') || translate('journey.header'));
-    err.title = (translate && translate('errors.ddos-rate-limit.title'));
-    err.message = (translate && translate('errors.ddos-rate-limit.message'));
-    err.preTimeToWait = (translate && translate('errors.ddos-rate-limit.pre-time-to-wait'));
+    err.serviceName = t('journey.serviceName') || t('journey.header');
+    err.title = t('errors.ddos-rate-limit.title');
+    err.message = t('errors.ddos-rate-limit.message');
+    err.preTimeToWait = t('errors.ddos-rate-limit.pre-time-to-wait');
     err.timeToWait = rateLimitsConfig.rateLimits.requests.windowSizeInMinutes;
-    err.postTimeToWait = (translate && translate('errors.ddos-rate-limit.post-time-to-wait'));
-    content.title = (translate && translate('errors.ddos-rate-limit.title'));
-    content.serviceName = (translate && translate('journey.serviceName') || translate('journey.header'));
-    content.message = (translate && translate('errors.ddos-rate-limit.message'));
-    content.preTimeToWait = (translate && translate('errors.ddos-rate-limit.pre-time-to-wait'));
+    err.postTimeToWait = t('errors.ddos-rate-limit.post-time-to-wait');
+    content.title = t('errors.ddos-rate-limit.title');
+    content.serviceName = t('journey.serviceName') || t('journey.header');
+    content.message = t('errors.ddos-rate-limit.message');
+    content.preTimeToWait = t('errors.ddos-rate-limit.pre-time-to-wait');
     content.timeToWait = rateLimitsConfig.rateLimits.requests.windowSizeInMinutes;
-    content.postTimeToWait = (translate && translate('errors.ddos-rate-limit.post-time-to-wait'));
+    content.postTimeToWait = t('errors.ddos-rate-limit.post-time-to-wait');
   }
 
   if (err.code === 'SUBMISSION_RATE_LIMIT') {
     err.status = 429;
     err.template = 'rate-limit-error';
-    err.serviceName = (translate && translate('journey.serviceName') || translate('journey.header'));
-    err.title = (translate && translate('errors.submission-rate-limit.title'));
-    err.message = (translate && translate('errors.submission-rate-limit.message'));
-    err.preTimeToWait = (translate && translate('errors.submission-rate-limit.pre-time-to-wait'));
+    err.serviceName = t('journey.serviceName') || t('journey.header');
+    err.title = t('errors.submission-rate-limit.title');
+    err.message = t('errors.submission-rate-limit.message');
+    err.preTimeToWait = t('errors.submission-rate-limit.pre-time-to-wait');
     err.timeToWait = rateLimitsConfig.rateLimits.submissions.windowSizeInMinutes;
-    err.postTimeToWait = (translate && translate('errors.submission-rate-limit.post-time-to-wait'));
-    content.serviceName = (translate && translate('journey.serviceName') || translate('journey.header'));
-    content.title = (translate && translate('errors.submission-rate-limit.title'));
-    content.message = (translate && translate('errors.submission-rate-limit.message'));
-    content.preTimeToWait = (translate && translate('errors.submission-rate-limit.pre-time-to-wait'));
+    err.postTimeToWait = t('errors.submission-rate-limit.post-time-to-wait');
+    content.serviceName = t('journey.serviceName') || t('journey.header');
+    content.title = t('errors.submission-rate-limit.title');
+    content.message = t('errors.submission-rate-limit.message');
+    content.preTimeToWait = t('errors.submission-rate-limit.pre-time-to-wait');
     content.timeToWait = rateLimitsConfig.rateLimits.submissions.windowSizeInMinutes;
-    content.postTimeToWait = (translate && translate('errors.submission-rate-limit.post-time-to-wait'));
+    content.postTimeToWait = t('errors.submission-rate-limit.post-time-to-wait');
   }
 
   err.code = err.code || 'UNKNOWN';
   err.status = err.status || 500;
 
   if (!content.title) {
-    content.title = (translate && translate('errors.default.title')) || errorTitle(err.code);
+    content.title = t('errors.default.title') || errorTitle(err.code);
   }
   if (!content.message) {
-    content.message = (translate && translate('errors.default.message')) || errorMsg(err.code);
+    content.message = t('errors.default.message') || errorMsg(err.code);
   }
   return content;
 };

package/middleware/index.js

@@ -6,5 +6,5 @@ module.exports = {
   notFound: require('./not-found'),
   deepTranslate: require('./deep-translate'),
   rateLimiter: require('./rate-limiter'),
-  servicePaused: require('./service-paused')
+  serviceUnavailable: require('./service-unavailable')
 };

package/middleware/service-unavailable.js

@@ -0,0 +1,64 @@
+/* eslint-disable consistent-return */
+'use strict';
+
+const getTranslations = translate => {
+  const translations = {
+    title: 'Sorry, this service is unavailable',
+    message: 'This service is temporarily unavailable',
+    'answers-saved': 'Your answers have not been saved'
+  };
+
+  if (translate) {
+    const contact = translate('errors.service-unavailable.contact');
+    const alternative = translate('errors.service-unavailable.alternative');
+    translations.serviceName = translate('journey.serviceName') || translate('journey.header');
+    translations.title = translate('errors.service-unavailable.title');
+    translations.message = translate('errors.service-unavailable.message');
+    translations['answers-saved'] = translate('errors.service-unavailable.answers-saved');
+
+    // Only render contact and alternative information if the key has a value set
+    if (contact === 'errors.service-unavailable.contact') {
+      translations.contact = '';
+    } else {
+      translations.contact = translate('errors.service-unavailable.contact');
+    }
+    if (alternative === 'errors.service-unavailable.alternative') {
+      translations.alternative = '';
+    } else {
+      translations.alternative = translate('errors.service-unavailable.alternative');
+    }
+  }
+  return translations;
+};
+
+module.exports = options => {
+  const opts = options || {};
+  const logger = opts.logger;
+  // These are paths that are allowed to bypass the "service unavailable" middleware.
+  // When the service is unavailable (for example, for maintenance), all routes except those listed here
+  // will return a paused response, typically a maintenance page.
+  //
+  // - '/assets': Static assets (CSS, JS, images) must still be served so the paused page displays correctly.
+  // - '/readyz' and '/livez': Health check endpoints must remain available for Kubernetes or other orchestration
+  //   systems to determine if the container is healthy, even during maintenance.
+  const bypassPaths = opts.bypassPaths || ['/readyz', '/health', '/assets'];
+
+  return (req, res, next) => {
+    if (bypassPaths.some(path => req.path.startsWith(path))) {
+      return next();
+    }
+    const translate = opts.translate || req.translate;
+    const translations = getTranslations(translate);
+    if (logger && logger.warn) {
+      logger.warn('Service temporarily unavailable - service paused.');
+    }
+    res.status(503).render('service-unavailable', {
+      serviceName: translations.serviceName,
+      title: translations.title,
+      message: translations.message,
+      'answers-saved': translations['answers-saved'],
+      contact: translations.contact,
+      alternative: translations.alternative
+    });
+  };
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hof",
   "description": "A bootstrap for HOF projects",
-  "version": "22.7.0-service-paused-beta.13",
+  "version": "22.7.0-service-unavailable-beta.2",
   "license": "MIT",
   "main": "index.js",
   "author": "HomeOffice",
@@ -27,7 +27,7 @@
     "test:lint": "eslint . --config ./node_modules/eslint-config-hof/default.js",
     "test:functional": "funkie mocha ./test/functional-tests --timeout 20000 --exit",
     "test:client": "karma start test/frontend/toolkit/karma.conf.js",
-    "test:jest": "jest test/frontend/jest",
+    "test:jest": "jest test/frontend/jest test/utilities/helpers/jest",
     "test:acceptance": "TAGS=\"${TAGS:=@feature}\" yarn run test:cucumber",
     "test:acceptance_browser": "ACCEPTANCE_WITH_BROWSER=true TAGS=\"${TAGS:=@feature}\" yarn run test:cucumber",
     "test:cucumber": "cucumber-js -f @cucumber/pretty-formatter \"sandbox/test/_features/**/*.feature\" --require sandbox/test/_features/test.setup.js --require \"sandbox/test/_features/step_definitions/**/*.js\" --tags $TAGS",

package/sandbox/.env

@@ -1 +1,2 @@
 SERVICE_PAUSED=false
+# REDIRECT_TO_PAGE=true

package/sandbox/apps/sandbox/translations/en/default.json

@@ -1,9 +1,4 @@
 {
-  "errors": {
-    "service-paused": {
-      "contact": "You can email for more information"
-    }
-  },
   "exit": {
     "header": "You have left this form",
     "title": "You have left this form"
@@ -111,7 +106,6 @@
   },
   "journey": {
     "header": "HOF Bootstrap Sandbox Form",
-    "serviceName": "HOF Bootstrap Sandbox Form",
     "confirmation": {
       "details": "Your reference number <br><strong>HDJ2123F</strong>"
     }
@@ -186,6 +180,10 @@
       "paragraph-1": "Your form doesn't appear to have been worked on for 30 minutes so we closed it for security.",
       "paragraph-2": "Any answers you saved have not been affected.",
       "paragraph-3": "You can sign back in to your application at any time by returning to the <a href='/' class='govuk-link'>start page</a>."
+    },
+    "service-down": {
+      "message": "hello",
+      "descriptions": "hello"
     }
   },
   "validation": {

package/sandbox/apps/sandbox/translations/src/en/errors.json

@@ -1,5 +1,5 @@
 {
-  "service-paused": {
+  "service-unavailable": {
     "contact": "You can email for more information"
   }
 }

package/sandbox/package.json

@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node server.js",
-    "start:dev": "HOF_SANDBOX=true ../bin/hof-build watch --env",
+    "start:dev": "HOF_SANDBOX=true ../bin/hof-build watch",
     "dev": "yarn && GA_TAG=test nodemon server",
     "build": "HOF_SANDBOX=true ../bin/hof-build",
     "postinstall": "yarn run build"

package/utilities/helpers/index.js

@@ -2,6 +2,7 @@
 'use strict';
 
 const _ = require('lodash');
+const logger = require('../../lib/logger');
 
 module.exports = class Helpers {
   /**
@@ -146,4 +147,43 @@ module.exports = class Helpers {
       (!Object.keys(req.form.values).includes(condition.field) &&
       _.get(req, `form.historicalValues[${condition.field}]`)));
   }
+
+  /**
+   * Read an environment variable and coerce it to boolean.
+   *
+   * @param {*}     rawValue    The raw value (e.g. process.env.FEATURE_FLAG)
+   * @param {boolean} [fallback=false]   Value to use if rawValue is null/undefined/invalid
+   * @param {string} [envVarName='ENV_VAR']  Name for log context
+   * @returns {boolean}
+   */
+  static getEnvBoolean(rawValue, fallback = false, envVarName = 'ENV_VAR') {
+    if (typeof rawValue === 'boolean') {
+      return rawValue;
+    }
+
+    if (rawValue === null || rawValue === undefined) {
+      return fallback;
+    }
+
+    if (typeof rawValue === 'string') {
+      const normalized = rawValue.trim().toLowerCase();
+      if (normalized === 'true') {
+        return true;
+      }
+      if (normalized === 'false') {
+        return false;
+      }
+      logger.warn(
+        `Invalid environment variable ${envVarName} value "${rawValue}" ` +
+        '– must be "true" or "false"; defaulting to ' +
+        `${fallback}`
+      );
+      return fallback;
+    }
+
+    logger.warn(
+      `Invalid environment variable ${envVarName} type (${typeof rawValue}); defaulting to ${fallback}`
+    );
+    return fallback;
+  }
 };

package/frontend/template-partials/translations/src/en/pages.json

@@ -1,8 +0,0 @@
-{
-  "service-paused": {
-    "title": "Sorry, the service is unavailable",
-    "header": "Sorry, the service is unavailable",
-    "message": "This service is temporarily unavailable",
-    "answers-saved": "Your answers have not been saved"
-  }
-}

package/middleware/service-paused.js

@@ -1,52 +0,0 @@
-'use strict';
-
-const getTranslations = translate => {
-  const translations = {
-    title: 'Sorry, this service is unavailable',
-    message: 'This service is temporarily unavailable',
-    'answers-saved': 'Your answers have not been saved'
-  };
-
-  if (translate) {
-    const contact = translate('errors.service-paused.contact');
-    const alternative = translate('errors.service-paused.alternative');
-    translations.serviceName = translate('journey.serviceName') || translate('journey.header');
-    translations.title = translate('errors.service-paused.title');
-    translations.message = translate('errors.service-paused.message');
-    translations['answers-saved'] = translate('errors.service-paused.answers-saved');
-
-    // Only render contact and alternative information if the key has a value set
-    if (contact === 'errors.service-paused.contact') {
-      translations.contact = '';
-    } else {
-      translations.contact = translate('errors.service-paused.contact');
-    }
-    if (alternative === 'errors.service-paused.alternative') {
-      translations.alternative = '';
-    } else {
-      translations.alternative = translate('errors.service-paused.alternative');
-    }
-  }
-  return translations;
-};
-
-module.exports = options => {
-  const opts = options || {};
-  const logger = opts.logger;
-
-  return (req, res) => {
-    const translate = opts.translate || req.translate;
-    const translations = getTranslations(translate);
-    if (logger && logger.warn) {
-      logger.warn('Service temporarily unavailable - service paused.');
-    }
-    res.status(503).render('service-paused', {
-      serviceName: translations.serviceName,
-      title: translations.title,
-      message: translations.message,
-      'answers-saved': translations['answers-saved'],
-      contact: translations.contact,
-      alternative: translations.alternative
-    });
-  };
-};