@defra/forms-engine-plugin 0.0.1

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

@@ -0,0 +1,446 @@
+import { ComponentType, type PageFileUpload } from '@defra/forms-model'
+import Boom from '@hapi/boom'
+import { type ResponseToolkit } from '@hapi/hapi'
+import { wait } from '@hapi/hoek'
+import { type ValidationErrorItem } from 'joi'
+
+import {
+  tempItemSchema,
+  type FileUploadField
+} from '~/src/server/plugins/engine/components/FileUploadField.js'
+import {
+  getError,
+  getExponentialBackoffDelay
+} from '~/src/server/plugins/engine/helpers.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import { getProxyUrlForLocalDevelopment } from '~/src/server/plugins/engine/pageControllers/helpers.js'
+import {
+  getUploadStatus,
+  initiateUpload
+} from '~/src/server/plugins/engine/services/uploadService.js'
+import {
+  FileStatus,
+  UploadStatus,
+  type FeaturedFormPageViewModel,
+  type FileState,
+  type FormContext,
+  type FormContextRequest,
+  type FormSubmissionError,
+  type FormSubmissionState,
+  type ItemDeletePageViewModel,
+  type UploadInitiateResponse,
+  type UploadStatusFileResponse
+} from '~/src/server/plugins/engine/types.js'
+import {
+  type FormRequest,
+  type FormRequestPayload
+} from '~/src/server/routes/types.js'
+
+const MAX_UPLOADS = 25
+const CDP_UPLOAD_TIMEOUT_MS = 60000 // 1 minute
+
+export function prepareStatus(status: UploadStatusFileResponse) {
+  const file = status.form.file
+  const isPending = file.fileStatus === FileStatus.pending
+
+  if (!file.errorMessage && isPending) {
+    file.errorMessage = 'The selected file has not fully uploaded'
+  }
+
+  return status
+}
+
+function prepareFileState(fileState: FileState) {
+  prepareStatus(fileState.status)
+
+  return fileState
+}
+
+export class FileUploadPageController extends QuestionPageController {
+  declare pageDef: PageFileUpload
+
+  fileUpload: FileUploadField
+  fileDeleteViewName = 'item-delete'
+
+  constructor(model: FormModel, pageDef: PageFileUpload) {
+    super(model, pageDef)
+
+    const { collection } = this
+
+    // Get the file upload fields from the collection
+    const fileUploads = collection.fields.filter(
+      (field): field is FileUploadField =>
+        field.type === ComponentType.FileUploadField
+    )
+
+    const fileUpload = fileUploads.at(0)
+
+    // Assert we have exactly 1 file upload component
+    if (!fileUpload || fileUploads.length > 1) {
+      throw Boom.badImplementation(
+        `Expected 1 FileUploadFieldComponent in FileUploadPageController '${pageDef.path}'`
+      )
+    }
+
+    // Assert the file upload component is the first form component
+    if (collection.fields.indexOf(fileUpload) !== 0) {
+      throw Boom.badImplementation(
+        `Expected '${fileUpload.name}' to be the first form component in FileUploadPageController '${pageDef.path}'`
+      )
+    }
+
+    // Assign the file upload component to the controller
+    this.fileUpload = fileUpload
+    this.viewName = 'file-upload'
+  }
+
+  getFormDataFromState(
+    request: FormContextRequest | undefined,
+    state: FormSubmissionState
+  ) {
+    const { fileUpload } = this
+
+    const payload = super.getFormDataFromState(request, state)
+    const files = this.getFilesFromState(state)
+
+    // Append the files to the payload
+    payload[fileUpload.name] = files.length ? files : undefined
+
+    return payload
+  }
+
+  async getState(request: FormRequest | FormRequestPayload) {
+    const { fileUpload } = this
+
+    // Get the actual state
+    const state = await super.getState(request)
+    const files = this.getFilesFromState(state)
+
+    // Overwrite the files with those in the upload state
+    state[fileUpload.name] = files
+
+    return this.refreshUpload(request, state)
+  }
+
+  /**
+   * Get the uploaded files from state.
+   */
+  getFilesFromState(state: FormSubmissionState) {
+    const { path } = this
+
+    const uploadState = state.upload?.[path]
+    return uploadState?.files ?? []
+  }
+
+  /**
+   * Get the initiated upload from state.
+   */
+  getUploadFromState(state: FormSubmissionState) {
+    const { path } = this
+
+    const uploadState = state.upload?.[path]
+    return uploadState?.upload
+  }
+
+  makeGetItemDeleteRouteHandler() {
+    return (
+      request: FormRequest,
+      context: FormContext,
+      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    ) => {
+      const { viewModel } = this
+      const { params } = request
+      const { state } = context
+
+      const files = this.getFilesFromState(state)
+
+      const fileToRemove = files.find(
+        ({ uploadId }) => uploadId === params.itemId
+      )
+
+      if (!fileToRemove) {
+        throw Boom.notFound('File to delete not found')
+      }
+
+      const { filename } = fileToRemove.status.form.file
+
+      return h.view(this.fileDeleteViewName, {
+        ...viewModel,
+        context,
+        backLink: this.getBackLink(request, context),
+        pageTitle: `Are you sure you want to remove this file?`,
+        itemTitle: filename,
+        confirmation: { text: 'You cannot recover removed files.' },
+        buttonConfirm: { text: 'Remove file' },
+        buttonCancel: { text: 'Cancel' }
+      } satisfies ItemDeletePageViewModel)
+    }
+  }
+
+  makePostItemDeleteRouteHandler() {
+    return async (
+      request: FormRequestPayload,
+      context: FormContext,
+      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    ) => {
+      const { path } = this
+      const { state } = context
+
+      const { confirm } = this.getFormParams(request)
+
+      // Check for any removed files in the POST payload
+      if (confirm) {
+        await this.checkRemovedFiles(request, state)
+        return this.proceed(request, h, path)
+      }
+
+      return this.proceed(request, h)
+    }
+  }
+
+  getErrors(details?: ValidationErrorItem[]) {
+    const { fileUpload } = this
+
+    if (details) {
+      const errors: FormSubmissionError[] = []
+
+      details.forEach((error) => {
+        const isUploadError = error.path[0] === fileUpload.name
+        const isUploadRootError = isUploadError && error.path.length === 1
+
+        if (!isUploadError || isUploadRootError) {
+          // The error is for the root of the upload or another
+          // field on the page so defer to the getError helper
+          errors.push(getError(error))
+        } else {
+          const { context, path, type } = error
+
+          if (type === 'object.unknown' && path.at(-1) === 'errorMessage') {
+            const value = context?.value as string | undefined
+
+            if (value) {
+              const name = fileUpload.name
+              const text = typeof value === 'string' ? value : 'Unknown error'
+              const href = `#${name}`
+
+              errors.push({ path, href, name, text })
+            }
+          }
+        }
+      })
+
+      return errors
+    }
+  }
+
+  getViewModel(
+    request: FormContextRequest,
+    context: FormContext
+  ): FeaturedFormPageViewModel {
+    const { fileUpload } = this
+    const { state } = context
+
+    const upload = this.getUploadFromState(state)
+
+    const viewModel = super.getViewModel(request, context)
+    const { components } = viewModel
+
+    // Featured form component
+    const [formComponent] = components.filter(
+      ({ model }) => model.id === fileUpload.name
+    )
+
+    const index = components.indexOf(formComponent)
+
+    const proxyUrl = getProxyUrlForLocalDevelopment(upload?.uploadUrl)
+
+    return {
+      ...viewModel,
+      formAction: upload?.uploadUrl,
+      uploadId: upload?.uploadId,
+      formComponent,
+
+      // Split out components before/after
+      componentsBefore: components.slice(0, index),
+      components: components.slice(index),
+      proxyUrl
+    }
+  }
+
+  /**
+   * Refreshes the CDP upload and files in the
+   * state and checks for any removed files.
+   *
+   * If an upload exists and hasn't been consumed
+   * it gets re-used, otherwise we initiate a new one.
+   * @param request - the hapi request
+   * @param state - the form state
+   */
+  private async refreshUpload(
+    request: FormRequest | FormRequestPayload,
+    state: FormSubmissionState
+  ) {
+    state = await this.checkUploadStatus(request, state)
+
+    return state
+  }
+
+  /**
+   * If an upload exists and hasn't been consumed
+   * it gets re-used, otherwise a new one is initiated.
+   * @param request - the hapi request
+   * @param state - the form state
+   * @param depth - the number of retries so far
+   */
+  private async checkUploadStatus(
+    request: FormRequest | FormRequestPayload,
+    state: FormSubmissionState,
+    depth = 1
+  ): Promise<FormSubmissionState> {
+    const upload = this.getUploadFromState(state)
+    const files = this.getFilesFromState(state)
+
+    // If no upload exists, initiate a new one.
+    if (!upload?.uploadId) {
+      return this.initiateAndStoreNewUpload(request, state)
+    }
+
+    const uploadId = upload.uploadId
+    const statusResponse = await getUploadStatus(uploadId)
+    if (!statusResponse) {
+      throw Boom.badRequest(
+        `Unexpected empty response from getUploadStatus for ${uploadId}`
+      )
+    }
+
+    // Re-use the upload if it is still in the "initiated" state.
+    if (statusResponse.uploadStatus === UploadStatus.initiated) {
+      return state
+    }
+
+    if (statusResponse.uploadStatus === UploadStatus.pending) {
+      // Using exponential backoff delays:
+      // Depth 1: 2000ms, Depth 2: 4000ms, Depth 3: 8000ms, Depth 4: 16000ms, Depth 5+: 30000ms (capped)
+      // A depth of 5 (or more) implies cumulative delays roughly reaching 55 seconds.
+      if (depth >= 5) {
+        request.logger.error(
+          `Exceeded cumulative retry delay for ${uploadId} (depth: ${depth}). Re-initiating a new upload.`
+        )
+        await this.initiateAndStoreNewUpload(request, state)
+        throw Boom.gatewayTimeout(
+          `Timed out waiting for ${uploadId} after cumulative retries exceeding ${((CDP_UPLOAD_TIMEOUT_MS - 5000) / 1000).toFixed(0)} seconds`
+        )
+      }
+      const delay = getExponentialBackoffDelay(depth)
+      request.logger.info(
+        `Waiting ${delay / 1000} seconds for ${uploadId} to complete (depth: ${depth})`
+      )
+      await wait(delay)
+      return this.checkUploadStatus(request, state, depth + 1)
+    }
+
+    // Only add to files state if the file validates.
+    // This secures against html tampering of the file input
+    // by adding a 'multiple' attribute or it being
+    // changed to a simple text field or similar.
+    const validationResult = tempItemSchema.validate(
+      { uploadId, status: statusResponse },
+      { stripUnknown: true }
+    )
+    const error = validationResult.error
+    const fileState = validationResult.value as FileState
+
+    if (error) {
+      return this.initiateAndStoreNewUpload(request, state)
+    }
+
+    const file = fileState.status.form.file
+    if (file.fileStatus === FileStatus.complete) {
+      files.unshift(prepareFileState(fileState))
+      await this.mergeState(request, state, {
+        upload: { [this.path]: { files, upload } }
+      })
+    } else {
+      // Flash the error message.
+      const { fileUpload } = this
+      const { cacheService } = request.services([])
+      const name = fileUpload.name
+      const text = file.errorMessage ?? 'Unknown error'
+      const errors: FormSubmissionError[] = [
+        { path: [name], href: `#${name}`, name, text }
+      ]
+      cacheService.setFlash(request, { errors })
+    }
+
+    return this.initiateAndStoreNewUpload(request, state)
+  }
+
+  /**
+   * Checks the payload for a file getting removed
+   * and removes it from the upload files if found
+   * @param request - the hapi request
+   * @param state - the form state
+   * @returns updated state if any files have been removed
+   */
+  private async checkRemovedFiles(
+    request: FormRequestPayload,
+    state: FormSubmissionState
+  ) {
+    const { path } = this
+    const { params } = request
+
+    const upload = this.getUploadFromState(state)
+    const files = this.getFilesFromState(state)
+
+    const filesUpdated = files.filter(
+      ({ uploadId }) => uploadId !== params.itemId
+    )
+
+    if (filesUpdated.length === files.length) {
+      return
+    }
+
+    await this.mergeState(request, state, {
+      upload: { [path]: { files: filesUpdated, upload } }
+    })
+  }
+
+  /**
+   * Initiates a CDP file upload and stores in the upload state
+   * @param request - the hapi request
+   * @param state - the form state
+   */
+  private async initiateAndStoreNewUpload(
+    request: FormRequest | FormRequestPayload,
+    state: FormSubmissionState
+  ) {
+    const { fileUpload, href, path } = this
+    const { options, schema } = fileUpload
+
+    const files = this.getFilesFromState(state)
+
+    // Reset the upload in state
+    let upload: UploadInitiateResponse | undefined
+
+    // Don't initiate anymore after minimum of `schema.max` or MAX_UPLOADS
+    const max = Math.min(schema.max ?? MAX_UPLOADS, MAX_UPLOADS)
+
+    if (files.length < max) {
+      const outputEmail =
+        this.model.def.outputEmail ?? 'defraforms@defra.gov.uk'
+
+      const newUpload = await initiateUpload(href, outputEmail, options.accept)
+
+      if (newUpload === undefined) {
+        throw Boom.badRequest('Unexpected empty response from initiateUpload')
+      }
+
+      upload = newUpload
+    }
+
+    return this.mergeState(request, state, {
+      upload: { [path]: { files, upload } }
+    })
+  }
+}

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

@@ -0,0 +1,205 @@
+import { type ResponseToolkit } from '@hapi/hapi'
+
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
+import { type FormRequest } from '~/src/server/routes/types.js'
+import definition from '~/test/form/definitions/basic.js'
+
+describe('PageController', () => {
+  let model: FormModel
+  let controller1: PageController
+  let controller2: PageController
+
+  beforeEach(() => {
+    const { pages } = definition
+
+    const page1 = pages[0]
+    const page2 = pages[1]
+
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+
+    controller1 = new PageController(model, page1)
+    controller2 = new PageController(model, page2)
+  })
+
+  describe('Properties', () => {
+    it('returns path', () => {
+      expect(controller1).toHaveProperty('path', '/licence')
+      expect(controller2).toHaveProperty('path', '/full-name')
+    })
+
+    it('returns href', () => {
+      expect(controller1).toHaveProperty('href', '/test/licence')
+      expect(controller2).toHaveProperty('href', '/test/full-name')
+    })
+
+    it('returns keys (empty)', () => {
+      expect(controller1).toHaveProperty('keys', [])
+      expect(controller2).toHaveProperty('keys', [])
+    })
+
+    it('returns the page section', () => {
+      expect(controller1).toHaveProperty('section', {
+        name: 'licenceDetails',
+        title: 'Licence details',
+        hideTitle: false
+      })
+
+      expect(controller2).toHaveProperty('section', {
+        name: 'personalDetails',
+        title: 'Personal details',
+        hideTitle: false
+      })
+    })
+
+    it('returns feedback link (from form definition)', () => {
+      expect(controller1).toHaveProperty('feedbackLink', undefined)
+
+      const emailAddress = 'test@feedback.cat'
+
+      model.def.feedback = {
+        emailAddress
+      }
+
+      expect(controller1).toHaveProperty(
+        'feedbackLink',
+        `mailto:${emailAddress}`
+      )
+    })
+
+    it('returns phase tag (from form definition)', () => {
+      expect(controller1).toHaveProperty('phaseTag', undefined)
+
+      model.def.phaseBanner = {
+        phase: 'alpha'
+      }
+
+      expect(controller1).toHaveProperty('phaseTag', 'alpha')
+    })
+
+    it('sets default viewName to "index"', () => {
+      expect(controller1).toHaveProperty('viewName', 'index')
+      expect(controller2).toHaveProperty('viewName', 'index')
+    })
+
+    it('overrides viewName when pageDef.view is provided', () => {
+      const customPage = {
+        ...definition.pages[0],
+        view: 'custom-view'
+      }
+
+      const customController = new PageController(model, customPage)
+
+      expect(customController).toHaveProperty('viewName', 'custom-view')
+    })
+  })
+
+  describe('Path methods', () => {
+    describe('Link href', () => {
+      it('prefixes paths into link hrefs', () => {
+        const href1 = controller1.getHref('/')
+        const href2 = controller1.getHref('/page-one')
+
+        expect(href1).toBe('/test')
+        expect(href2).toBe('/test/page-one')
+      })
+    })
+
+    describe('Start path', () => {
+      it('returns path to start page', () => {
+        const startPath = controller1.getStartPath()
+        expect(startPath).toBe('/licence')
+      })
+
+      it('returns path to start page (default)', () => {
+        delete model.def.startPage
+
+        const startPath = controller1.getStartPath()
+        expect(startPath).toBe('/start')
+      })
+    })
+
+    describe('Summary path', () => {
+      it('returns path to summary page', () => {
+        const summaryPath = controller1.getSummaryPath()
+        expect(summaryPath).toBe('/summary')
+      })
+    })
+
+    describe('Status path', () => {
+      it('returns path to status page', () => {
+        const summaryPath = controller1.getStatusPath()
+        expect(summaryPath).toBe('/status')
+      })
+    })
+  })
+
+  describe('Route handlers', () => {
+    const page1Url = new URL('http://example.com/test/licence')
+
+    const request = {
+      method: 'get',
+      url: page1Url,
+      path: page1Url.pathname,
+      params: {
+        path: 'licence',
+        slug: 'test'
+      },
+      query: {},
+      app: { model }
+    } as FormRequest
+
+    const h: Pick<ResponseToolkit, 'redirect' | 'view'> = {
+      redirect: jest.fn(),
+      view: jest.fn()
+    }
+
+    it('returns default route options', () => {
+      expect(controller1.getRouteOptions).toEqual({})
+      expect(controller1.postRouteOptions).toEqual({})
+    })
+
+    it('supports GET route handler', async () => {
+      expect(() => controller1.makeGetRouteHandler()).not.toThrow()
+      expect(() => controller1.makeGetRouteHandler()).toBeInstanceOf(Function)
+
+      await controller1.makeGetRouteHandler()(
+        request,
+        model.getFormContext(request, {}),
+        h
+      )
+
+      await controller2.makeGetRouteHandler()(
+        request,
+        model.getFormContext(request, {}),
+        h
+      )
+
+      expect(h.view).toHaveBeenNthCalledWith(
+        1,
+        controller1.viewName,
+        expect.objectContaining({
+          pageTitle: 'Buy a rod fishing licence',
+          sectionTitle: 'Licence details'
+        })
+      )
+
+      expect(h.view).toHaveBeenNthCalledWith(
+        2,
+        controller1.viewName,
+        expect.objectContaining({
+          pageTitle: "What's your name?",
+          sectionTitle: 'Personal details'
+        })
+      )
+    })
+
+    it('does not support POST route handler', () => {
+      expect(() => controller1.makePostRouteHandler()).toThrow(
+        'Unsupported POST route handler for this page'
+      )
+    })
+  })
+})