Build schemas on server creation to support custom actions

Author: alexluckett

src/server/plugins/engine/configureEnginePlugin.ts

@@ -3,6 +3,7 @@ import { join, parse } from 'node:path'
 import { type FormDefinition } from '@defra/forms-model'
 
 import { FORM_PREFIX } from '~/src/server/constants.js'
+import { getCacheService } from '~/src/server/plugins/engine/helpers.js'
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { plugin } from '~/src/server/plugins/engine/plugin.js'
 import * as defaultServices from '~/src/server/plugins/engine/services/index.js'
@@ -59,7 +60,22 @@ export const configureEnginePlugin = async ({
       preparePageEventRequestOptions,
       onRequest,
       baseUrl: 'http://localhost:3009', // always runs locally
-      saveAndReturn
+      saveAndReturn,
+      buttons: [
+        {
+          text: 'My custom submit button'
+        },
+        {
+          text: 'Withdraw button',
+          action: 'withdraw-submission'
+        }
+      ],
+      actionHandlers: {
+        'withdraw-submission': async (request, _) => {
+          await getCacheService(request.server).clearState(request)
+          return '/summary'
+        }
+      }
     }
 
     /*

src/server/plugins/engine/helpers.ts

@@ -12,7 +12,7 @@ import Boom from '@hapi/boom'
 import { type ResponseToolkit, type Server } from '@hapi/hapi'
 import { format, parseISO } from 'date-fns'
 import { StatusCodes } from 'http-status-codes'
-import { type Schema, type ValidationErrorItem } from 'joi'
+import Joi, { type Schema, type ValidationErrorItem } from 'joi'
 import { Liquid } from 'liquidjs'
 
 import { createLogger } from '~/src/server/common/helpers/logging/logger.js'
@@ -376,6 +376,18 @@ export function evaluateTemplate(
   })
 }
 
+export function getSchemas(server?: Server) {
+  if (!server) {
+    // only used in debug UI helper where validation isn't really important
+    return {
+      actionSchema: Joi.any().required(),
+      paramsSchema: Joi.any().required()
+    }
+  }
+
+  return getPluginOptions(server).schemas
+}
+
 export function getCacheService(server: Server) {
   return getPluginOptions(server).cacheService
 }

src/server/plugins/engine/options.js

@@ -32,7 +32,8 @@ const pluginRegistrationOptionsSchema = Joi.object({
         action: Joi.string().optional()
       })
     )
-    .optional()
+    .optional(),
+  actionHandlers: Joi.object().pattern(Joi.string(), Joi.function())
 })
 
 /**

src/server/plugins/engine/pageControllers/QuestionPageController.ts

@@ -10,14 +10,15 @@ import {
 } from '@defra/forms-model'
 // import Boom from '@hapi/boom' // No longer needed
 import { type ResponseToolkit, type RouteOptions } from '@hapi/hapi'
-import { type ValidationErrorItem } from 'joi'
+import Joi, { type ValidationErrorItem } from 'joi'
 
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import { optionalText } from '~/src/server/plugins/engine/components/constants.js'
 import { type BackLink } from '~/src/server/plugins/engine/components/types.js'
 import {
   getCacheService,
   getErrors,
+  getSchemas,
   normalisePath,
   proceed
 } from '~/src/server/plugins/engine/helpers.js'
@@ -39,11 +40,7 @@ import {
   type FormRequestPayloadRefs,
   type FormRequestRefs
 } from '~/src/server/routes/types.js'
-import {
-  actionSchema,
-  crumbSchema,
-  paramsSchema
-} from '~/src/server/schemas/index.js'
+import { crumbSchema } from '~/src/server/schemas/index.js'
 import { merge } from '~/src/server/services/cacheService.js'
 
 export class QuestionPageController extends PageController {
@@ -62,7 +59,7 @@ export class QuestionPageController extends PageController {
 
     this.collection.formSchema = this.collection.formSchema.keys({
       crumb: crumbSchema,
-      action: actionSchema
+      action: Joi.string()
     })
   }
 
@@ -274,7 +271,7 @@ export class QuestionPageController extends PageController {
   getFormParams(request?: FormContextRequest): FormPayloadParams {
     const { payload } = request ?? {}
 
-    const result = paramsSchema.validate(payload, {
+    const result = getSchemas(request?.server).paramsSchema.validate(payload, {
       abortEarly: false,
       stripUnknown: true
     })

src/server/plugins/engine/plugin.ts

@@ -22,6 +22,10 @@ import {
   type FormRequestPayloadRefs,
   type FormRequestRefs
 } from '~/src/server/routes/types.js'
+import {
+  buildActionSchema,
+  buildParamsSchema
+} from '~/src/server/schemas/index.js'
 import { CacheService } from '~/src/server/services/index.js'
 
 export const plugin = {
@@ -51,12 +55,20 @@ export const plugin = {
 
     await registerVision(server, options)
 
+    const buttons = getButtons(options)
+    const actionHandlers = getActionHandlers(options)
+    const customActions = Object.keys(actionHandlers)
+
     server.expose('baseLayoutPath', nunjucksOptions.baseLayoutPath)
     server.expose('viewContext', viewContext)
     server.expose('cacheService', cacheService)
     server.expose('saveAndReturn', saveAndReturn)
-    server.expose('buttons', getButtons(options))
-    server.expose('actionHandlers', getActionHandlers(options))
+    server.expose('buttons', buttons)
+    server.expose('actionHandlers', actionHandlers)
+    server.expose('schemas', {
+      actionSchema: buildActionSchema(customActions),
+      paramsSchema: buildParamsSchema(customActions)
+    })
 
     server.app.model = model
 
@@ -90,12 +102,13 @@ export const plugin = {
 
     const routes = [
       ...getQuestionRoutes(
+        server,
         getRouteOptions,
         postRouteOptions,
         preparePageEventRequestOptions
       ),
-      ...getRepeaterSummaryRoutes(getRouteOptions, postRouteOptions),
-      ...getRepeaterItemDeleteRoutes(getRouteOptions, postRouteOptions),
+      ...getRepeaterSummaryRoutes(server, getRouteOptions, postRouteOptions),
+      ...getRepeaterItemDeleteRoutes(server, getRouteOptions, postRouteOptions),
       ...getSaveAndReturnExitRoutes(getRouteOptions),
       ...getFileUploadStatusRoutes()
     ]

src/server/plugins/engine/routes/questions.ts

@@ -4,11 +4,13 @@ import {
   type ResponseObject,
   type ResponseToolkit,
   type RouteOptions,
+  type Server,
   type ServerRoute
 } from '@hapi/hapi'
 import Joi from 'joi'
 
 import {
+  getSchemas,
   normalisePath,
   proceed,
   redirectPath
@@ -35,7 +37,6 @@ import {
   type FormRequestRefs
 } from '~/src/server/routes/types.js'
 import {
-  actionSchema,
   crumbSchema,
   itemIdSchema,
   pathSchema,
@@ -164,10 +165,13 @@ function isSuccessful(response: ResponseObject): boolean {
 }
 
 export function getRoutes(
+  server: Server,
   getRouteOptions: RouteOptions<FormRequestRefs>,
   postRouteOptions: RouteOptions<FormRequestPayloadRefs>,
   preparePageEventRequestOptions?: PreparePageEventRequestOptions
 ): (ServerRoute<FormRequestRefs> | ServerRoute<FormRequestPayloadRefs>)[] {
+  const { actionSchema } = getSchemas(server)
+
   return [
     {
       method: 'get',

src/server/plugins/engine/routes/repeaters/item-delete.ts

@@ -3,10 +3,12 @@ import Boom from '@hapi/boom'
 import {
   type ResponseToolkit,
   type RouteOptions,
+  type Server,
   type ServerRoute
 } from '@hapi/hapi'
 import Joi from 'joi'
 
+import { getSchemas } from '~/src/server/plugins/engine/helpers.js'
 import { FileUploadPageController } from '~/src/server/plugins/engine/pageControllers/FileUploadPageController.js'
 import { RepeatPageController } from '~/src/server/plugins/engine/pageControllers/RepeatPageController.js'
 import { redirectOrMakeHandler } from '~/src/server/plugins/engine/routes/index.js'
@@ -17,7 +19,6 @@ import {
   type FormRequestRefs
 } from '~/src/server/routes/types.js'
 import {
-  actionSchema,
   confirmSchema,
   crumbSchema,
   itemIdSchema,
@@ -70,9 +71,12 @@ function postHandler(
 }
 
 export function getRoutes(
+  server: Server,
   getRouteOptions: RouteOptions<FormRequestRefs>,
   postRouteOptions: RouteOptions<FormRequestPayloadRefs>
 ): (ServerRoute<FormRequestRefs> | ServerRoute<FormRequestPayloadRefs>)[] {
+  const { actionSchema } = getSchemas(server)
+
   return [
     {
       method: 'get',

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

@@ -4,10 +4,12 @@ import Boom from '@hapi/boom'
 import {
   type ResponseToolkit,
   type RouteOptions,
+  type Server,
   type ServerRoute
 } from '@hapi/hapi'
 import Joi from 'joi'
 
+import { getSchemas } from '~/src/server/plugins/engine/helpers.js'
 import { RepeatPageController } from '~/src/server/plugins/engine/pageControllers/RepeatPageController.js'
 import { redirectOrMakeHandler } from '~/src/server/plugins/engine/routes/index.js'
 import {
@@ -17,7 +19,6 @@ import {
   type FormRequestRefs
 } from '~/src/server/routes/types.js'
 import {
-  actionSchema,
   crumbSchema,
   pathSchema,
   stateSchema
@@ -56,9 +57,12 @@ function postHandler(
 }
 
 export function getRoutes(
+  server: Server,
   getRouteOptions: RouteOptions<FormRequestRefs>,
   postRouteOptions: RouteOptions<FormRequestPayloadRefs>
 ): (ServerRoute<FormRequestRefs> | ServerRoute<FormRequestPayloadRefs>)[] {
+  const { actionSchema } = getSchemas(server)
+
   return [
     {
       method: 'get',

src/server/schemas/index.ts

@@ -7,7 +7,7 @@ export const stateSchema = Joi.string<FormStatus>()
   .valid(FormStatus.Draft, FormStatus.Live)
   .required()
 
-export const actionSchema = Joi.string<FormAction>()
+const actionSchema = Joi.string<FormAction>()
   .valid(
     FormAction.Continue,
     FormAction.Validate,
@@ -24,7 +24,7 @@ export const itemIdSchema = Joi.string().uuid().required()
 export const crumbSchema = Joi.string().optional().allow('')
 export const confirmSchema = Joi.boolean().empty(false)
 
-export const paramsSchema = Joi.object<FormPayloadParams>()
+const paramsSchema = Joi.object<FormPayloadParams>()
   .keys({
     action: actionSchema,
     confirm: confirmSchema,
@@ -33,3 +33,13 @@ export const paramsSchema = Joi.object<FormPayloadParams>()
   })
   .default({})
   .optional()
+
+export function buildActionSchema(customActions: string[]) {
+  return actionSchema.valid(...customActions)
+}
+
+export function buildParamsSchema(customActions: string[]) {
+  return paramsSchema.alter({
+    action: (schema) => schema.valid(...customActions)
+  })
+}

src/typings/hapi/index.d.ts

@@ -2,6 +2,7 @@
 
 import { type Plugin } from '@hapi/hapi'
 import { type ServerYar, type Yar } from '@hapi/yar'
+import { type Schema as JoiSchema } from 'joi'
 import { type Logger } from 'pino'
 
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
@@ -36,6 +37,10 @@ declare module '@hapi/hapi' {
         FormAction | string,
         (request: FormRequestPayload, context: FormContext) => Promise<string>
       >
+      schemas: {
+        actionSchema: JoiSchema
+        paramsSchema: JoiSchema
+      }
     }
   }