@defra/forms-engine-plugin 1.0.0 → 1.0.2

package/src/server/plugins/engine/routes/repeaters/summary.ts

@@ -0,0 +1,137 @@
+// List summary GET route
+import { slugSchema } from '@defra/forms-model'
+import Boom from '@hapi/boom'
+import {
+  type ResponseToolkit,
+  type RouteOptions,
+  type ServerRoute
+} from '@hapi/hapi'
+import Joi from 'joi'
+
+import { RepeatPageController } from '~/src/server/plugins/engine/pageControllers/RepeatPageController.js'
+import { redirectOrMakeHandler } from '~/src/server/plugins/engine/routes/index.js'
+import {
+  type FormRequest,
+  type FormRequestPayload,
+  type FormRequestPayloadRefs,
+  type FormRequestRefs
+} from '~/src/server/routes/types.js'
+import {
+  actionSchema,
+  crumbSchema,
+  pathSchema,
+  stateSchema
+} from '~/src/server/schemas/index.js'
+
+function getHandler(
+  request: FormRequest,
+  h: Pick<ResponseToolkit, 'redirect' | 'view'>
+) {
+  const { params } = request
+
+  return redirectOrMakeHandler(request, h, (page, context) => {
+    if (!(page instanceof RepeatPageController)) {
+      throw Boom.notFound(`No repeater page found for /${params.path}`)
+    }
+
+    return page.makeGetListSummaryRouteHandler()(request, context, h)
+  })
+}
+
+function postHandler(
+  request: FormRequestPayload,
+  h: Pick<ResponseToolkit, 'redirect' | 'view'>
+) {
+  const { params } = request
+
+  return redirectOrMakeHandler(request, h, (page, context) => {
+    const { isForceAccess } = context
+
+    if (isForceAccess || !(page instanceof RepeatPageController)) {
+      throw Boom.notFound(`No repeater page found for /${params.path}`)
+    }
+
+    return page.makePostListSummaryRouteHandler()(request, context, h)
+  })
+}
+
+export function getRoutes(
+  getRouteOptions: RouteOptions<FormRequestRefs>,
+  postRouteOptions: RouteOptions<FormRequestPayloadRefs>
+): (ServerRoute<FormRequestRefs> | ServerRoute<FormRequestPayloadRefs>)[] {
+  return [
+    {
+      method: 'get',
+      path: '/{slug}/{path}/summary',
+      handler: getHandler,
+      options: {
+        ...getRouteOptions,
+        validate: {
+          params: Joi.object().keys({
+            slug: slugSchema,
+            path: pathSchema
+          })
+        }
+      }
+    },
+
+    {
+      method: 'get',
+      path: '/preview/{state}/{slug}/{path}/summary',
+      handler: getHandler,
+      options: {
+        ...getRouteOptions,
+        validate: {
+          params: Joi.object().keys({
+            state: stateSchema,
+            slug: slugSchema,
+            path: pathSchema
+          })
+        }
+      }
+    },
+
+    {
+      method: 'post',
+      path: '/{slug}/{path}/summary',
+      handler: postHandler,
+      options: {
+        ...postRouteOptions,
+        validate: {
+          params: Joi.object().keys({
+            slug: slugSchema,
+            path: pathSchema
+          }),
+          payload: Joi.object()
+            .keys({
+              crumb: crumbSchema,
+              action: actionSchema
+            })
+            .required()
+        }
+      }
+    },
+
+    {
+      method: 'post',
+      path: '/preview/{state}/{slug}/{path}/summary',
+      handler: postHandler,
+      options: {
+        ...postRouteOptions,
+        validate: {
+          params: Joi.object().keys({
+            state: stateSchema,
+            slug: slugSchema,
+            path: pathSchema
+          }),
+          payload: Joi.object()
+            .keys({
+              crumb: crumbSchema,
+              action: actionSchema
+            })
+            .required()
+        }
+      }
+    }
+  ]
+}

package/src/server/plugins/engine/types.ts

@@ -4,6 +4,7 @@ import {
   type List,
   type Page
 } from '@defra/forms-model'
+import { type PluginProperties, type Request } from '@hapi/hapi'
 import { type JoiExpression, type ValidationErrorItem } from 'joi'
 
 import { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
@@ -13,10 +14,16 @@ import {
   type ComponentText,
   type ComponentViewModel
 } from '~/src/server/plugins/engine/components/types.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
 import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
 import { type ViewContext } from '~/src/server/plugins/nunjucks/types.js'
-import { type FormAction, type FormRequest } from '~/src/server/routes/types.js'
+import {
+  type FormAction,
+  type FormRequest,
+  type FormRequestPayload
+} from '~/src/server/routes/types.js'
+import { type Services } from '~/src/server/types.js'
 
 /**
  * Form submission state stores the following in Redis:
@@ -325,3 +332,21 @@ export interface ErrorMessageTemplateList {
   baseErrors: ErrorMessageTemplate[]
   advancedSettingsErrors: ErrorMessageTemplate[]
 }
+
+export interface PluginOptions {
+  model?: FormModel
+  services?: Services
+  controllers?: Record<string, typeof PageController>
+  cacheName?: string
+  filters?: Record<string, FilterFunction>
+  keyGenerator?: (request: Request | FormRequest | FormRequestPayload) => string
+  sessionHydrator?: (
+    request: Request | FormRequest | FormRequestPayload
+  ) => Promise<FormSubmissionState>
+  pluginPath?: string
+  nunjucks: {
+    baseLayoutPath: string
+    paths: string[]
+  }
+  viewContext: PluginProperties['forms-engine-plugin']['viewContext']
+}

package/src/server/plugins/engine/vision.ts

@@ -0,0 +1,95 @@
+import { existsSync } from 'fs'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+import { type Server } from '@hapi/hapi'
+import vision from '@hapi/vision'
+import nunjucks, { type Environment } from 'nunjucks'
+import resolvePkg from 'resolve'
+
+import {
+  VIEW_PATH,
+  context,
+  prepareNunjucksEnvironment
+} from '~/src/server/plugins/engine/index.js'
+import { type PluginOptions } from '~/src/server/plugins/engine/types.js'
+
+export async function registerVision(
+  server: Server,
+  pluginOptions: PluginOptions
+) {
+  const packageRoot = findPackageRoot()
+  const govukFrontendPath = dirname(
+    resolvePkg.sync('govuk-frontend/package.json')
+  )
+
+  const viewPathResolved = join(packageRoot, VIEW_PATH)
+
+  const paths = [
+    ...pluginOptions.nunjucks.paths,
+    viewPathResolved,
+    join(govukFrontendPath, 'dist')
+  ]
+
+  await server.register({
+    plugin: vision,
+    options: {
+      engines: {
+        html: {
+          compile: (
+            path: string,
+            compileOptions: { environment: Environment }
+          ) => {
+            const template = nunjucks.compile(path, compileOptions.environment)
+
+            return (context: object | undefined) => {
+              return template.render(context)
+            }
+          },
+          prepare: (
+            options: EngineConfigurationObject,
+            next: (err?: Error) => void
+          ) => {
+            // Nunjucks also needs an additional path configuration
+            // to use the templates and macros from `govuk-frontend`
+            const environment = nunjucks.configure(paths)
+
+            // Applies custom filters and globals for nunjucks
+            // that are required by the `forms-engine-plugin`
+            prepareNunjucksEnvironment(environment, pluginOptions.filters)
+
+            options.compileOptions.environment = environment
+
+            next()
+          }
+        }
+      },
+      path: paths,
+      // Provides global context used with all templates
+      context
+    }
+  })
+}
+
+interface CompileOptions {
+  environment: Environment
+}
+
+export interface EngineConfigurationObject {
+  compileOptions: CompileOptions
+}
+
+export function findPackageRoot() {
+  const currentFileName = fileURLToPath(import.meta.url)
+  const currentDirectoryName = dirname(currentFileName)
+
+  let dir = currentDirectoryName
+  while (dir !== '/') {
+    if (existsSync(join(dir, 'package.json'))) {
+      return dir
+    }
+    dir = dirname(dir)
+  }
+
+  throw new Error('package.json not found in parent directories')
+}

package/src/server/services/cacheService.test.ts

@@ -2,7 +2,11 @@ import { type Request, type Server } from '@hapi/hapi'
 
 import { config } from '~/src/config/index.js'
 import { type FormRequest } from '~/src/server/routes/types.js'
-import { CacheService, merge } from '~/src/server/services/cacheService.js'
+import {
+  ADDITIONAL_IDENTIFIER,
+  CacheService,
+  merge
+} from '~/src/server/services/cacheService.js'
 
 describe('CacheService', () => {
   let mockServer: Partial<Server>
@@ -31,7 +35,10 @@ describe('CacheService', () => {
       } as unknown as Server['logger']
     }
 
-    cacheService = new CacheService(mockServer as Server)
+    cacheService = new CacheService({
+      server: mockServer as Server,
+      cacheName: 'test-cache'
+    })
   })
 
   describe('getState', () => {
@@ -69,6 +76,40 @@ describe('CacheService', () => {
         expect(result).toEqual({})
       })
     })
+
+    it('should rehydrate state using custom fetcher when cache is missed', async () => {
+      const rehydratedState = { rehydrated: true }
+
+      const customFetcher = jest.fn().mockResolvedValue(rehydratedState)
+
+      cacheService = new CacheService({
+        server: mockServer as Server,
+        cacheName: 'test-cache',
+        options: { sessionHydrator: customFetcher }
+      })
+
+      const mockRequest = {
+        yar: { id: 'session-id' },
+        params: { state: 's', slug: 'p' }
+      } as unknown as FormRequest
+
+      mockCache.get
+        .mockResolvedValueOnce(null)
+        .mockResolvedValueOnce(rehydratedState)
+
+      const result = await cacheService.getState(mockRequest)
+
+      expect(customFetcher).toHaveBeenCalledWith(mockRequest)
+      expect(mockCache.set).toHaveBeenCalledWith(
+        expect.objectContaining({
+          segment: 'cache',
+          id: expect.stringContaining('session-id')
+        }),
+        rehydratedState,
+        config.get('sessionTimeout')
+      )
+      expect(result).toEqual(rehydratedState)
+    })
   })
 
   describe('setState', () => {
@@ -108,6 +149,61 @@ describe('CacheService', () => {
         )
       })
     })
+
+    it('should use custom key generator if provided', async () => {
+      const customKey = 'my-custom-key'
+      const customKeyGenerator = jest.fn().mockReturnValue(customKey)
+
+      cacheService = new CacheService({
+        server: mockServer as Server,
+        cacheName: 'test-cache',
+        options: { keyGenerator: customKeyGenerator }
+      })
+
+      const mockRequest = {
+        yar: { id: 'some-session' },
+        params: { state: 'form1', slug: 'page1' }
+      } as unknown as FormRequest
+
+      await cacheService.setState(mockRequest, { test: 'value' })
+
+      expect(mockCache.set).toHaveBeenCalledWith(
+        {
+          segment: 'cache',
+          id: 'my-custom-key'
+        },
+        { test: 'value' },
+        expect.any(Number)
+      )
+    })
+
+    it('should append additionalIdentifier to custom key', () => {
+      const customKey = 'custom:key:base:'
+      const customKeyGenerator = jest.fn().mockReturnValue(customKey)
+
+      cacheService = new CacheService({
+        server: mockServer as Server,
+        cacheName: 'test-cache',
+        options: { keyGenerator: customKeyGenerator }
+      })
+
+      const mockRequest = {
+        yar: { id: 'session-id' },
+        params: { state: 'formA', slug: 'step1' }
+      } as unknown as FormRequest
+
+      const result = cacheService.Key(
+        mockRequest,
+        ADDITIONAL_IDENTIFIER.Confirmation
+      )
+
+      expect(result).toEqual({
+        segment: 'cache',
+        id: 'custom:key:base::confirmation'
+      })
+
+      expect(customKeyGenerator).toHaveBeenCalledWith(mockRequest)
+    })
   })
 
   describe('merge', () => {

package/src/server/services/cacheService.ts

@@ -16,7 +16,7 @@ import {
 
 const partition = 'cache'
 
-enum ADDITIONAL_IDENTIFIER {
+export enum ADDITIONAL_IDENTIFIER {
   Confirmation = ':confirmation'
 }
 
@@ -25,16 +25,38 @@ export class CacheService {
    * This service is responsible for getting, storing or deleting a user's session data in the cache. This service has been registered by {@link createServer}
    */
   cache
+  generateKey?: (request: Request | FormRequest | FormRequestPayload) => string
+  customFetcher?: (
+    request: Request | FormRequest | FormRequestPayload
+  ) => Promise<FormSubmissionState | null>
+
   logger: Server['logger']
 
-  constructor(server: Server, cacheName?: string) {
+  constructor({
+    server,
+    cacheName,
+    options
+  }: {
+    server: Server
+    cacheName?: string
+    options?: {
+      keyGenerator?: (
+        request: Request | FormRequest | FormRequestPayload
+      ) => string
+      sessionHydrator?: (
+        request: Request | FormRequest | FormRequestPayload
+      ) => Promise<FormSubmissionState | null>
+    }
+  }) {
+    const { keyGenerator, sessionHydrator } = options ?? {}
     if (!cacheName) {
       server.log(
         'warn',
         'You are using the default hapi cache. Please provide a cache name in plugin registration options.'
       )
     }
-
+    this.generateKey = keyGenerator ?? this.defaultKeyGenerator.bind(this)
+    this.customFetcher = sessionHydrator ?? undefined
     this.cache = server.cache({ cache: cacheName, segment: 'formSubmission' })
     this.logger = server.logger
   }
@@ -42,7 +64,21 @@ export class CacheService {
   async getState(
     request: Request | FormRequest | FormRequestPayload
   ): Promise<FormSubmissionState> {
-    const cached = await this.cache.get(this.Key(request))
+    let cached = await this.cache.get(this.Key(request))
+
+    // If nothing in Redis, attempt to rehydrate from backend DB
+    if (!cached && this.customFetcher) {
+      const rehydrated = await this.customFetcher(request)
+
+      if (rehydrated != null) {
+        await this.cache.set(
+          this.Key(request),
+          rehydrated,
+          config.get('sessionTimeout')
+        )
+        cached = await this.getState(request)
+      }
+    }
 
     return cached ?? {}
   }
@@ -103,6 +139,18 @@ export class CacheService {
     request.yar.flash(key.id, message)
   }
 
+  private defaultKeyGenerator(
+    request: Request | FormRequest | FormRequestPayload
+  ): string {
+    if (!request.yar.id) {
+      throw new Error('No session ID found')
+    }
+
+    const state = request.params.state ?? ''
+    const slug = request.params.slug ?? ''
+    return `${request.yar.id}:${state}:${slug}:`
+  }
+
   /**
    * The key used to store user session data against.
    * If there are multiple forms on the same runner instance, for example `form-a` and `form-a-feedback` this will prevent CacheService from clearing data from `form-a` if a user gave feedback before they finished `form-a`
@@ -113,12 +161,13 @@ export class CacheService {
     request: Request | FormRequest | FormRequestPayload,
     additionalIdentifier?: ADDITIONAL_IDENTIFIER
   ) {
-    if (!request.yar.id) {
-      throw Error('No session ID found')
-    }
+    const baseKey = this.generateKey
+      ? this.generateKey(request)
+      : this.defaultKeyGenerator(request)
+
     return {
       segment: partition,
-      id: `${request.yar.id}:${request.params.state ?? ''}:${request.params.slug ?? ''}:${additionalIdentifier ?? ''}`
+      id: `${baseKey}${additionalIdentifier ?? ''}`
     }
   }
 }