@defra/forms-engine-plugin 0.0.1

package/src/server/plugins/engine/pageControllers/StartPageController.ts

@@ -0,0 +1,18 @@
+import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import { type FormContext } from '~/src/server/plugins/engine/types.js'
+import { type FormRequest } from '~/src/server/routes/types.js'
+
+export class StartPageController extends QuestionPageController {
+  /**
+   * The controller which is used when Page["controller"] is defined as "./pages/start.js"
+   * This page should not be used in production. This page is helpful for prototyping start pages within the app,
+   * but start pages should really live on gov.uk (whitehall publisher) so a user can be properly signposted.
+   */
+
+  getViewModel(request: FormRequest, context: FormContext) {
+    return {
+      ...super.getViewModel(request, context),
+      isStartPage: true
+    }
+  }
+}

package/src/server/plugins/engine/pageControllers/StatusPageController.ts

@@ -0,0 +1,50 @@
+import { type PageStatus } from '@defra/forms-model'
+import { type ResponseToolkit } from '@hapi/hapi'
+
+import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import { type FormContext } from '~/src/server/plugins/engine/types.js'
+import { type FormRequest } from '~/src/server/routes/types.js'
+
+export class StatusPageController extends QuestionPageController {
+  declare pageDef: PageStatus
+
+  constructor(model: FormModel, pageDef: PageStatus) {
+    super(model, pageDef)
+    this.viewName = 'confirmation'
+  }
+
+  getRelevantPath() {
+    return this.getStatusPath()
+  }
+
+  makeGetRouteHandler() {
+    return async (
+      request: FormRequest,
+      context: FormContext,
+      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    ) => {
+      const { viewModel, viewName } = this
+
+      const { cacheService } = request.services([])
+      const confirmationState = await cacheService.getConfirmationState(request)
+
+      // If there's no confirmation state, then
+      // redirect the user back to the start of the form
+      if (!confirmationState.confirmed) {
+        return this.proceed(request, h, this.getStartPath())
+      }
+
+      const slug = request.params.slug
+      const { formsService } = this.model.services
+      const { getFormMetadata } = formsService
+
+      const { submissionGuidance } = await getFormMetadata(slug)
+
+      return h.view(viewName, {
+        ...viewModel,
+        submissionGuidance
+      })
+    }
+  }
+}

package/src/server/plugins/engine/pageControllers/SummaryPageController.ts

@@ -0,0 +1,261 @@
+import { type PageSummary, type SubmitPayload } from '@defra/forms-model'
+import Boom from '@hapi/boom'
+import { type ResponseToolkit, type RouteOptions } from '@hapi/hapi'
+
+import { FileUploadField } from '~/src/server/plugins/engine/components/FileUploadField.js'
+import { getAnswer } from '~/src/server/plugins/engine/components/helpers.js'
+import {
+  checkEmailAddressForLiveFormSubmission,
+  checkFormStatus
+} from '~/src/server/plugins/engine/helpers.js'
+import {
+  SummaryViewModel,
+  type FormModel
+} from '~/src/server/plugins/engine/models/index.js'
+import {
+  type Detail,
+  type DetailItem
+} from '~/src/server/plugins/engine/models/types.js'
+import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import {
+  type FormContext,
+  type FormContextRequest,
+  type FormSubmissionState
+} from '~/src/server/plugins/engine/types.js'
+import {
+  type FormRequest,
+  type FormRequestPayload,
+  type FormRequestPayloadRefs
+} from '~/src/server/routes/types.js'
+
+export class SummaryPageController extends QuestionPageController {
+  declare pageDef: PageSummary
+
+  /**
+   * The controller which is used when Page["controller"] is defined as "./pages/summary.js"
+   */
+
+  constructor(model: FormModel, pageDef: PageSummary) {
+    super(model, pageDef)
+    this.viewName = 'summary'
+  }
+
+  getSummaryViewModel(
+    request: FormContextRequest,
+    context: FormContext
+  ): SummaryViewModel {
+    const viewModel = new SummaryViewModel(request, this, context)
+
+    // We already figure these out in the base page controller. Take them and apply them to our page-specific model.
+    // This is a stop-gap until we can add proper inheritance in place.
+    viewModel.backLink = this.getBackLink(request, context)
+    viewModel.feedbackLink = this.feedbackLink
+    viewModel.phaseTag = this.phaseTag
+
+    return viewModel
+  }
+
+  /**
+   * Returns an async function. This is called in plugin.ts when there is a GET request at `/{id}/{path*}`,
+   */
+  makeGetRouteHandler() {
+    return async (
+      request: FormRequest,
+      context: FormContext,
+      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    ) => {
+      const { viewName } = this
+
+      const viewModel = this.getSummaryViewModel(request, context)
+
+      viewModel.hasMissingNotificationEmail =
+        await this.hasMissingNotificationEmail(request, context)
+
+      return h.view(viewName, viewModel)
+    }
+  }
+
+  /**
+   * Returns an async function. This is called in plugin.ts when there is a POST request at `/{id}/{path*}`.
+   * If a form is incomplete, a user will be redirected to the start page.
+   */
+  makePostRouteHandler() {
+    return async (
+      request: FormRequestPayload,
+      context: FormContext,
+      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    ) => {
+      const { model } = this
+      const { params } = request
+      const { state } = context
+
+      const { cacheService } = request.services([])
+      const { formsService } = this.model.services
+      const { getFormMetadata } = formsService
+
+      // Get the form metadata using the `slug` param
+      const { notificationEmail } = await getFormMetadata(params.slug)
+      const { isPreview } = checkFormStatus(request.path)
+      const emailAddress = notificationEmail ?? this.model.def.outputEmail
+
+      checkEmailAddressForLiveFormSubmission(emailAddress, isPreview)
+
+      // Send submission email
+      if (emailAddress) {
+        const viewModel = this.getSummaryViewModel(request, context)
+        await submitForm(request, viewModel, model, state, emailAddress)
+      }
+
+      await cacheService.setConfirmationState(request, { confirmed: true })
+
+      // Clear all form data
+      await cacheService.clearState(request)
+
+      return this.proceed(request, h, this.getStatusPath())
+    }
+  }
+
+  get postRouteOptions(): RouteOptions<FormRequestPayloadRefs> {
+    return {
+      ext: {
+        onPreHandler: {
+          method(request, h) {
+            return h.continue
+          }
+        }
+      }
+    }
+  }
+}
+
+async function submitForm(
+  request: FormRequestPayload,
+  summaryViewModel: SummaryViewModel,
+  model: FormModel,
+  state: FormSubmissionState,
+  emailAddress: string
+) {
+  await extendFileRetention(model, state, emailAddress)
+
+  const { path } = request
+  const formStatus = checkFormStatus(path)
+  const logTags = ['submit', 'submissionApi']
+
+  request.logger.info(logTags, 'Preparing email', formStatus)
+
+  // Get detail items
+  const items = getFormSubmissionData(
+    summaryViewModel.context,
+    summaryViewModel.details
+  )
+
+  // Submit data
+  request.logger.info(logTags, 'Submitting data')
+  const submitResponse = await submitData(
+    model,
+    items,
+    emailAddress,
+    request.yar.id
+  )
+
+  if (submitResponse === undefined) {
+    throw Boom.badRequest('Unexpected empty response from submit api')
+  }
+
+  return model.services.outputService.submit(
+    request,
+    model,
+    emailAddress,
+    items,
+    submitResponse
+  )
+}
+
+async function extendFileRetention(
+  model: FormModel,
+  state: FormSubmissionState,
+  updatedRetrievalKey: string
+) {
+  const { formSubmissionService } = model.services
+  const { persistFiles } = formSubmissionService
+  const files: { fileId: string; initiatedRetrievalKey: string }[] = []
+
+  // For each file upload component with files in
+  // state, add the files to the batch getting persisted
+  model.pages.forEach((page) => {
+    const fileUploadComponents = page.collection.fields.filter(
+      (component) => component instanceof FileUploadField
+    )
+
+    fileUploadComponents.forEach((component) => {
+      const values = component.getFormValueFromState(state)
+      if (!values?.length) {
+        return
+      }
+
+      files.push(
+        ...values.map(({ status }) => ({
+          fileId: status.form.file.fileId,
+          initiatedRetrievalKey: status.metadata.retrievalKey
+        }))
+      )
+    })
+  })
+
+  if (files.length) {
+    return persistFiles(files, updatedRetrievalKey)
+  }
+}
+
+function submitData(
+  model: FormModel,
+  items: DetailItem[],
+  retrievalKey: string,
+  sessionId: string
+) {
+  const { formSubmissionService } = model.services
+  const { submit } = formSubmissionService
+
+  const payload: SubmitPayload = {
+    sessionId,
+    retrievalKey,
+
+    // Main form answers
+    main: items
+      .filter((item) => 'field' in item)
+      .map((item) => ({
+        name: item.name,
+        title: item.label,
+        value: getAnswer(item.field, item.state, { format: 'data' })
+      })),
+
+    // Repeater form answers
+    repeaters: items
+      .filter((item) => 'subItems' in item)
+      .map((item) => ({
+        name: item.name,
+        title: item.label,
+
+        // Repeater item values
+        value: item.subItems.map((detailItems) =>
+          detailItems.map((subItem) => ({
+            name: subItem.name,
+            title: subItem.label,
+            value: getAnswer(subItem.field, subItem.state, { format: 'data' })
+          }))
+        )
+      }))
+  }
+
+  return submit(payload)
+}
+
+export function getFormSubmissionData(context: FormContext, details: Detail[]) {
+  return context.relevantPages
+    .map(({ href }) =>
+      details.flatMap(({ items }) =>
+        items.filter(({ page }) => page.href === href)
+      )
+    )
+    .flat()
+}

package/src/server/plugins/engine/pageControllers/TerminalController.test.ts

@@ -0,0 +1,28 @@
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { TerminalPageController } from '~/src/server/plugins/engine/pageControllers/TerminalPageController.js'
+import definition from '~/test/form/definitions/basic.js'
+
+describe('TerminalController', () => {
+  let model: FormModel
+  let controller1: TerminalPageController
+
+  beforeEach(() => {
+    const { pages } = definition
+
+    const page1 = pages[0]
+
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+
+    controller1 = new TerminalPageController(model, page1)
+  })
+
+  describe('Route handlers', () => {
+    it('does not support POST route handler', () => {
+      expect(() => controller1.makePostRouteHandler()).toThrow(
+        'POST method not allowed for terminal pages'
+      )
+    })
+  })
+})

package/src/server/plugins/engine/pageControllers/TerminalPageController.ts

@@ -0,0 +1,19 @@
+import { type PageTerminal } from '@defra/forms-model'
+import Boom from '@hapi/boom'
+import { type ResponseObject, type ResponseToolkit } from '@hapi/hapi'
+
+import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import { type FormContext } from '~/src/server/plugins/engine/types.js'
+import { type FormRequestPayload } from '~/src/server/routes/types.js'
+
+export class TerminalPageController extends QuestionPageController {
+  declare pageDef: PageTerminal
+
+  makePostRouteHandler(): (
+    request: FormRequestPayload,
+    context: FormContext,
+    h: Pick<ResponseToolkit, 'redirect' | 'view'>
+  ) => Promise<ResponseObject> {
+    throw Boom.methodNotAllowed('POST method not allowed for terminal pages')
+  }
+}

package/src/server/plugins/engine/pageControllers/helpers.test.ts

@@ -0,0 +1,198 @@
+import {
+  ComponentType,
+  ControllerType,
+  ControllerTypes,
+  PageTypes,
+  type Page
+} from '@defra/forms-model'
+
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
+import {
+  createPage,
+  getProxyUrlForLocalDevelopment,
+  isPageController,
+  type PageControllerType
+} from '~/src/server/plugins/engine/pageControllers/helpers.js'
+import {
+  FileUploadPageController,
+  QuestionPageController,
+  RepeatPageController,
+  StartPageController,
+  StatusPageController,
+  SummaryPageController,
+  TerminalPageController
+} from '~/src/server/plugins/engine/pageControllers/index.js'
+import definition from '~/test/form/definitions/blank.js'
+
+describe('Page controller helpers', () => {
+  const examples = PageTypes.map((pageType) => {
+    const pageDef = structuredClone(pageType)
+
+    let controller: PageControllerType | undefined
+
+    switch (pageDef.controller) {
+      case ControllerType.Start:
+        controller = StartPageController
+        break
+
+      case ControllerType.Page:
+        controller = QuestionPageController
+        break
+
+      case ControllerType.Terminal:
+        controller = TerminalPageController
+        break
+
+      case ControllerType.Repeat:
+        controller = RepeatPageController
+        break
+
+      case ControllerType.FileUpload:
+        controller = FileUploadPageController
+
+        // Avoid minimum component requirements
+        pageDef.components = [
+          {
+            type: ComponentType.FileUploadField,
+            name: 'fileUpload',
+            title: 'Upload something',
+            options: {},
+            schema: {}
+          }
+        ]
+        break
+
+      case ControllerType.Summary:
+        controller = SummaryPageController
+        break
+
+      case ControllerType.Status:
+        controller = StatusPageController
+        break
+    }
+
+    return {
+      controller,
+      pageDef
+    }
+  })
+
+  describe('Helper: createPage', () => {
+    const model = new FormModel(definition, {
+      basePath: 'test'
+    })
+
+    it.each([...examples])(
+      "creates page for controller '$pageDef.controller'",
+      ({ controller, pageDef }) => {
+        const pageDef1 = structuredClone(pageDef)
+        const pageDef2 = structuredClone(pageDef)
+
+        expect(createPage(model, pageDef1)).toBeInstanceOf(controller)
+
+        const controllerType = ControllerTypes.find(
+          ({ name }) => name === pageDef1.controller
+        )
+
+        // @ts-expect-error - Allow invalid property for test
+        pageDef2.controller = controllerType?.path
+
+        // Check for legacy path support
+        expect(createPage(model, pageDef2)).toBeInstanceOf(controller)
+      }
+    )
+
+    describe('Helper: createPage (custom controllers)', () => {
+      it('uses custom controllers from model.controllers', () => {
+        class CustomPageController extends PageController {
+          customProperty: string
+
+          constructor(model: FormModel, pageDef: Page) {
+            super(model, pageDef)
+            this.customProperty = 'some-value'
+          }
+        }
+
+        const customPageDef = {
+          path: '/custom-page',
+          title: 'Custom Page',
+          controller: 'CustomController',
+          components: []
+        }
+
+        const testModel = new FormModel(definition, {
+          basePath: 'test'
+        })
+
+        type ControllerMap = Record<string, typeof PageController>
+        testModel.controllers = {
+          CustomController: CustomPageController
+        } as ControllerMap
+
+        const controller = createPage(testModel, customPageDef as Page)
+
+        expect(controller).toBeInstanceOf(CustomPageController)
+        expect(controller).toHaveProperty('customProperty', 'some-value')
+      })
+    })
+
+    it('throws if page controller is unknown', () => {
+      const pageDef: Page = {
+        title: 'Unknown page',
+        path: '/unknown-page',
+        // @ts-expect-error - Allow invalid property for test
+        controller: 'UnknownPageController'
+      }
+
+      expect(() => createPage(model, pageDef)).toThrow(
+        `Page controller ${pageDef.controller} does not exist`
+      )
+    })
+  })
+
+  describe('Helper: isPageController', () => {
+    it.each([...examples])(
+      "allows valid page controller '$pageDef.controller'",
+      ({ pageDef }) => {
+        expect(isPageController(pageDef.controller)).toBe(true)
+      }
+    )
+
+    it.each([
+      { name: './pages/unknown.js' },
+      { name: 'UnknownPageController' },
+      { name: undefined },
+      { name: '' }
+    ])("rejects invalid page controller '$name'", ({ name }) => {
+      expect(isPageController(name)).toBe(false)
+    })
+  })
+
+  describe('Helper: getProxyUrlForLocalDevelopment', () => {
+    it('returns null if uploadUrl is undefined', () => {
+      expect(getProxyUrlForLocalDevelopment(undefined)).toBeNull()
+    })
+
+    it('returns null if uploadUrl does not include localhost:7337', () => {
+      expect(getProxyUrlForLocalDevelopment('https://some-url.com')).toBeNull()
+      expect(getProxyUrlForLocalDevelopment('http://localhost:8080')).toBeNull()
+    })
+
+    it('replaces localhost:7337 with uploader.127.0.0.1.sslip.io:7300', () => {
+      const originalUrl = 'http://localhost:7337/upload'
+      const expectedUrl = 'http://uploader.127.0.0.1.sslip.io:7300/upload'
+
+      expect(getProxyUrlForLocalDevelopment(originalUrl)).toBe(expectedUrl)
+    })
+
+    it('handles multiple occurrences of localhost:7337', () => {
+      const originalUrl =
+        'http://localhost:7337/path?redirect=http://localhost:7337/callback'
+      const expectedUrl =
+        'http://uploader.127.0.0.1.sslip.io:7300/path?redirect=http://uploader.127.0.0.1.sslip.io:7300/callback'
+
+      expect(getProxyUrlForLocalDevelopment(originalUrl)).toBe(expectedUrl)
+    })
+  })
+})

package/src/server/plugins/engine/pageControllers/helpers.ts

@@ -0,0 +1,101 @@
+import {
+  ControllerType,
+  controllerNameFromPath,
+  isControllerName,
+  type Page
+} from '@defra/forms-model'
+
+import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import * as PageControllers from '~/src/server/plugins/engine/pageControllers/index.js'
+
+export function isPageController(
+  controllerName?: string | ControllerType
+): controllerName is keyof typeof PageControllers {
+  return isControllerName(controllerName) && controllerName in PageControllers
+}
+
+export type PageControllerClass = InstanceType<PageControllerType>
+export type PageControllerType =
+  (typeof PageControllers)[keyof typeof PageControllers]
+
+/**
+ * Creates page instance for each {@link Page} type
+ */
+export function createPage(model: FormModel, pageDef: Page) {
+  const controllerName = controllerNameFromPath(pageDef.controller)
+
+  if (!pageDef.controller) {
+    return new PageControllers.QuestionPageController(model, pageDef)
+  }
+
+  // Patch legacy controllers
+  if (controllerName && pageDef.controller !== controllerName) {
+    pageDef.controller = controllerName
+  }
+
+  let controller: PageControllerClass | undefined
+
+  switch (pageDef.controller) {
+    case ControllerType.Start:
+      controller = new PageControllers.StartPageController(model, pageDef)
+      break
+
+    case ControllerType.Page:
+      controller = new PageControllers.QuestionPageController(model, pageDef)
+      break
+
+    case ControllerType.Terminal:
+      controller = new PageControllers.TerminalPageController(model, pageDef)
+      break
+
+    case ControllerType.Summary:
+      controller = new PageControllers.SummaryPageController(model, pageDef)
+      break
+
+    case ControllerType.Status:
+      controller = new PageControllers.StatusPageController(model, pageDef)
+      break
+
+    case ControllerType.FileUpload:
+      controller = new PageControllers.FileUploadPageController(model, pageDef)
+      break
+
+    case ControllerType.Repeat:
+      controller = new PageControllers.RepeatPageController(model, pageDef)
+      break
+  }
+
+  if (typeof controller === 'undefined') {
+    if (model.controllers?.[pageDef.controller]) {
+      const Ctrl = model.controllers[pageDef.controller]
+      controller = new Ctrl(model, pageDef) as unknown as PageControllerClass // type assertion needed because TS can't verify custom controller structure
+    }
+  }
+
+  if (typeof controller === 'undefined') {
+    throw new Error(`Page controller ${pageDef.controller} does not exist`)
+  }
+
+  return controller
+}
+
+/**
+ * In local development environments, we sometimes need to rewrite the
+ * CDP upload URL to work with CSP/CORS restrictions.
+ * This helper function rewrites localhost URLs to use the sslip.io proxy
+ * This is only used when running locally with a development proxy.
+ * In non-local environments, this function returns null
+ * @param uploadUrl - The original upload URL from CDP
+ */
+export function getProxyUrlForLocalDevelopment(
+  uploadUrl?: string
+): string | null {
+  if (!uploadUrl?.includes('localhost:7337')) {
+    return null
+  }
+
+  return uploadUrl.replace(
+    /localhost:7337/g,
+    'uploader.127.0.0.1.sslip.io:7300'
+  )
+}

package/src/server/plugins/engine/pageControllers/index.ts

@@ -0,0 +1,10 @@
+export { StartPageController } from '~/src/server/plugins/engine/pageControllers/StartPageController.js'
+export {
+  QuestionPageController, // Export alongside alias
+  QuestionPageController as PageController
+} from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+export { TerminalPageController } from '~/src/server/plugins/engine/pageControllers/TerminalPageController.js'
+export { SummaryPageController } from '~/src/server/plugins/engine/pageControllers/SummaryPageController.js'
+export { StatusPageController } from '~/src/server/plugins/engine/pageControllers/StatusPageController.js'
+export { FileUploadPageController } from '~/src/server/plugins/engine/pageControllers/FileUploadPageController.js'
+export { RepeatPageController } from '~/src/server/plugins/engine/pageControllers/RepeatPageController.js'