@defra/forms-engine-plugin 0.0.1

package/src/config/index.ts

@@ -0,0 +1,271 @@
+import { resolve } from 'node:path'
+
+import convict, { type SchemaObj } from 'convict'
+import { type LevelWithSilent } from 'pino'
+
+import 'dotenv/config'
+
+const isProduction = process.env.NODE_ENV === 'production'
+const isDev = process.env.NODE_ENV !== 'production'
+const isTest = process.env.NODE_ENV === 'test'
+
+const oneMinute = 1000 * 60
+const oneHour = oneMinute * 60
+
+export const config = convict({
+  appDir: {
+    format: String,
+    default: resolve(import.meta.dirname, '../server')
+  },
+  publicDir: {
+    format: String,
+    default: isTest
+      ? resolve(import.meta.dirname, '../../test/fixtures')
+      : resolve(import.meta.dirname, '../../.public')
+  },
+
+  /**
+   * Server
+   */
+  port: {
+    format: 'port',
+    default: 3009,
+    env: 'PORT'
+  },
+  env: {
+    doc: 'The application environment.',
+    format: ['production', 'development', 'test'],
+    default: 'development',
+    env: 'NODE_ENV'
+  },
+  cdpEnvironment: {
+    doc: 'The CDP environment the app is currently in, with the addition of "local"',
+    format: [
+      'local',
+      'infra-dev',
+      'management',
+      'dev',
+      'test',
+      'perf-test',
+      'ext-test',
+      'prod'
+    ],
+    default: 'local',
+    env: 'ENVIRONMENT'
+  },
+  enforceCsrf: {
+    format: Boolean,
+    default: isProduction,
+    env: 'ENFORCE_CSRF'
+  },
+
+  /**
+   * Helper flags
+   */
+  isProduction: {
+    doc: 'If this application running in the production environment',
+    format: Boolean,
+    default: isProduction
+  },
+  isDevelopment: {
+    doc: 'If this application running in the development environment',
+    format: Boolean,
+    default: isDev
+  },
+  isTest: {
+    doc: 'If this application running in the test environment',
+    format: Boolean,
+    default: isTest
+  },
+
+  /**
+   * Service
+   */
+  serviceName: {
+    doc: 'Applications Service Name',
+    format: String,
+    default: 'Submit a form to Defra'
+  },
+  serviceVersion: {
+    doc: 'The service version, this variable is injected into your docker container in CDP environments',
+    format: String,
+    nullable: true,
+    default: null,
+    env: 'SERVICE_VERSION'
+  } as SchemaObj<string>,
+  feedbackLink: {
+    doc: 'Used in your phase banner. Can be a URL or more commonly mailto mailto:feedback@department.gov.uk',
+    format: String,
+    default: null,
+    env: 'FEEDBACK_LINK'
+  } as SchemaObj<string>,
+  phaseTag: {
+    format: String,
+    default: 'beta', // Accepts "alpha" |"beta" | ""
+    env: 'PHASE_TAG'
+  },
+
+  /**
+   * Session storage
+   * Redis integration is optional, but recommended for production environments.
+   */
+  sessionTimeout: {
+    format: Number,
+    default: oneHour * 24, // 1 day
+    env: 'SESSION_TIMEOUT'
+  },
+  confirmationSessionTimeout: {
+    format: Number,
+    default: oneMinute * 20,
+    env: 'CONFIRMATION_SESSION_TIMEOUT'
+  },
+  sessionCookiePassword: {
+    format: String,
+    default: null,
+    sensitive: true,
+    env: 'SESSION_COOKIE_PASSWORD'
+  } as SchemaObj<string>,
+  redis: {
+    host: {
+      doc: 'Redis cache host',
+      format: String,
+      default: null,
+      env: 'REDIS_HOST'
+    } as SchemaObj<string>,
+    username: {
+      doc: 'Redis cache username',
+      format: String,
+      default: null,
+      env: 'REDIS_USERNAME'
+    } as SchemaObj<string>,
+    password: {
+      doc: 'Redis cache password',
+      format: '*',
+      default: null,
+      sensitive: true,
+      env: 'REDIS_PASSWORD'
+    } as SchemaObj<string>,
+    keyPrefix: {
+      doc: 'Redis cache key prefix name used to isolate the cached results across multiple clients',
+      format: String,
+      default: null,
+      env: 'REDIS_KEY_PREFIX'
+    } as SchemaObj<string>
+  },
+  tracing: {
+    header: {
+      doc: 'Tracing header name',
+      format: String,
+      default: 'x-cdp-request-id',
+      env: 'TRACING_HEADER'
+    } as SchemaObj<string>
+  },
+
+  /**
+   * Email outputs
+   * Email outputs will use notify to send an email to a single inbox.
+   */
+  notifyTemplateId: {
+    format: String,
+    default: null,
+    env: 'NOTIFY_TEMPLATE_ID'
+  } as SchemaObj<string>,
+  notifyAPIKey: {
+    format: String,
+    default: null,
+    env: 'NOTIFY_API_KEY'
+  } as SchemaObj<string>,
+
+  /**
+   * API integrations
+   */
+  managerUrl: {
+    format: String,
+    default: null,
+    env: 'MANAGER_URL'
+  } as SchemaObj<string>,
+
+  designerUrl: {
+    format: String,
+    default: null,
+    env: 'DESIGNER_URL'
+  } as SchemaObj<string>,
+
+  submissionUrl: {
+    format: String,
+    default: null,
+    env: 'SUBMISSION_URL'
+  } as SchemaObj<string>,
+
+  uploaderUrl: {
+    format: String,
+    default: null,
+    env: 'UPLOADER_URL'
+  } as SchemaObj<string>,
+
+  uploaderBucketName: {
+    format: String,
+    default: 'files',
+    env: 'UPLOADER_BUCKET_NAME'
+  },
+
+  /**
+   * Logging
+   */
+  log: {
+    enabled: {
+      doc: 'Is logging enabled',
+      format: Boolean,
+      default: !isTest,
+      env: 'LOG_ENABLED'
+    },
+    level: {
+      doc: 'Logging level',
+      format: ['fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent'],
+      default: 'info',
+      env: 'LOG_LEVEL'
+    } as SchemaObj<LevelWithSilent>,
+    format: {
+      doc: 'Format to output logs in.',
+      format: ['ecs', 'pino-pretty'],
+      default: isProduction ? 'ecs' : 'pino-pretty',
+      env: 'LOG_FORMAT'
+    } as SchemaObj<'ecs' | 'pino-pretty'>,
+    redact: {
+      doc: 'Log paths to redact',
+      format: Array,
+      default: isProduction
+        ? ['req.headers.authorization', 'req.headers.cookie', 'res.headers']
+        : ['req', 'res', 'responseTime']
+    }
+  },
+
+  safelist: {
+    format: Array,
+    default: ['61bca17e-fe74-40e0-9c15-a901ad120eca.mock.pstmn.io'],
+    env: 'SAFELIST'
+  },
+
+  stagingPrefix: {
+    doc: 'Prefix for staging files in S3',
+    format: String,
+    default: 'staging',
+    env: 'STAGING_PREFIX'
+  },
+
+  serviceBannerText: {
+    doc: 'Service banner text used to show a maintenance message on all pages when set',
+    format: String,
+    default: '',
+    env: 'SERVICE_BANNER_TEXT'
+  },
+
+  googleAnalyticsTrackingId: {
+    doc: 'Google analytics tracking ID to be used when a user has opted in to additional cookies',
+    format: String,
+    default: '',
+    env: 'GOOGLE_ANALYTICS_TRACKING_ID'
+  }
+})
+
+config.validate({ allowed: 'strict' })

package/src/index.ts

@@ -0,0 +1,31 @@
+import { config } from '~/src/config/index.js'
+import { createLogger } from '~/src/server/common/helpers/logging/logger.js'
+import { createServer } from '~/src/server/index.js'
+
+const logger = createLogger()
+
+process.on('unhandledRejection', (error) => {
+  logger.info('Unhandled rejection')
+  logger.error(error)
+  throw error
+})
+
+/**
+ * Main entrypoint to the application.
+ */
+async function startServer() {
+  const server = await createServer()
+  await server.start()
+
+  process.send?.('online')
+
+  server.logger.info('Server started successfully')
+  server.logger.info(
+    `Access your frontend on http://localhost:${config.get('port')}`
+  )
+}
+
+startServer().catch((error: unknown) => {
+  logger.info('Server failed to start :(')
+  logger.error(error)
+})

package/src/server/common/helpers/logging/logger-options.test.ts

@@ -0,0 +1,50 @@
+import { getTraceId } from '@defra/hapi-tracing'
+
+import { loggerOptions } from '~/src/server/common/helpers/logging/logger-options.js'
+
+jest.mock('@defra/hapi-tracing', () => ({
+  getTraceId: jest.fn()
+}))
+
+describe('logger-options', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  describe('configuration', () => {
+    it('has the expected properties', () => {
+      expect(loggerOptions).toHaveProperty('enabled')
+      expect(loggerOptions).toHaveProperty('ignorePaths')
+      expect(loggerOptions).toHaveProperty('redact')
+      expect(loggerOptions).toHaveProperty('level')
+    })
+
+    it('ignores health endpoint', () => {
+      expect(loggerOptions.ignorePaths).toContain('/health')
+    })
+
+    it('has redaction configuration', () => {
+      expect(loggerOptions.redact).toBeDefined()
+    })
+  })
+
+  describe('mixin function', () => {
+    it('returns an empty object when no trace ID is available', () => {
+      jest.mocked(getTraceId).mockReturnValue(null)
+
+      const result = loggerOptions.mixin()
+      expect(result).toEqual({})
+    })
+
+    it('includes trace ID when available', () => {
+      jest.mocked(getTraceId).mockReturnValue('some-trace-id')
+
+      const result = loggerOptions.mixin()
+      expect(result).toEqual({
+        trace: {
+          id: 'some-trace-id'
+        }
+      })
+    })
+  })
+})

package/src/server/common/helpers/logging/logger-options.ts

@@ -0,0 +1,46 @@
+import { getTraceId } from '@defra/hapi-tracing'
+import { ecsFormat } from '@elastic/ecs-pino-format'
+import { type Options } from 'hapi-pino'
+import { type LoggerOptions, type TransportSingleOptions } from 'pino'
+
+import { config } from '~/src/config/index.js'
+
+const logConfig = config.get('log')
+const serviceName = config.get('serviceName')
+const serviceVersion = config.get('serviceVersion')
+
+const formatters: {
+  ecs: Omit<LoggerOptions, 'mixin' | 'transport'>
+  'pino-pretty': { transport: TransportSingleOptions }
+} = {
+  ecs: {
+    ...ecsFormat(),
+    base: {
+      service: {
+        name: serviceName,
+        type: 'nodeJs',
+        version: serviceVersion
+      }
+    }
+  },
+  'pino-pretty': { transport: { target: 'pino-pretty' } }
+}
+
+export const loggerOptions = {
+  enabled: logConfig.enabled,
+  ignorePaths: ['/health'],
+  redact: {
+    paths: logConfig.redact,
+    remove: true
+  },
+  level: logConfig.level,
+  ...formatters[logConfig.format],
+  mixin() {
+    const mixinValues: { trace?: { id: string } } = {}
+    const traceId = getTraceId()
+    if (traceId) {
+      mixinValues.trace = { id: traceId }
+    }
+    return mixinValues
+  }
+} satisfies Options

package/src/server/common/helpers/logging/logger.ts

@@ -0,0 +1,7 @@
+import { pino } from 'pino'
+
+import { loggerOptions } from '~/src/server/common/helpers/logging/logger-options.js'
+
+export function createLogger() {
+  return pino(loggerOptions)
+}

package/src/server/common/helpers/logging/request-logger.ts

@@ -0,0 +1,9 @@
+import { type ServerRegisterPluginObject } from '@hapi/hapi'
+import hapiPino, { type Options } from 'hapi-pino'
+
+import { loggerOptions } from '~/src/server/common/helpers/logging/logger-options.js'
+
+export const requestLogger = {
+  plugin: hapiPino,
+  options: loggerOptions
+} satisfies ServerRegisterPluginObject<Options>

package/src/server/common/helpers/logging/request-tracing.js

@@ -0,0 +1,10 @@
+import { tracing } from '@defra/hapi-tracing'
+
+import { config } from '~/src/config/index.js'
+
+// Explicitly declare the expected type
+
+export const requestTracing = {
+  plugin: tracing,
+  options: { tracingHeader: config.get('tracing').header }
+}

package/src/server/common/helpers/redis-client.js

@@ -0,0 +1,70 @@
+import { Cluster, Redis } from 'ioredis'
+
+import { config } from '~/src/config/index.js'
+import { createLogger } from '~/src/server/common/helpers/logging/logger.js'
+
+/**
+ * Setup Redis and provide a redis client
+ *
+ * Local development - 1 Redis instance
+ * Out in the wild - Elasticache / Redis Cluster with username and password
+ */
+export function buildRedisClient() {
+  const logger = createLogger()
+
+  const port = 6379
+  const db = 0
+  const redisConfig = config.get('redis')
+  const keyPrefix = redisConfig.keyPrefix
+  const host = redisConfig.host
+  let redisClient
+
+  if (!config.get('isProduction')) {
+    logger.info('Connecting to Redis using single instance')
+
+    redisClient = new Redis({
+      port,
+      host,
+      db,
+      keyPrefix
+    })
+  } else {
+    logger.info('Connecting to Redis using cluster')
+
+    redisClient = new Cluster(
+      [
+        {
+          host,
+          port
+        }
+      ],
+      {
+        keyPrefix,
+        slotsRefreshTimeout: 2000,
+        dnsLookup: (address, callback) => callback(null, address),
+        redisOptions: {
+          username: redisConfig.username,
+          password: redisConfig.password,
+          db,
+          tls: {}
+        }
+      }
+    )
+  }
+
+  redisClient.on('connect', () => {
+    logger.info('Connected to Redis server')
+  })
+
+  redisClient.on('close', () => {
+    logger.warn(
+      'Redis connection closed attempting reconnect with default behavior'
+    )
+  })
+
+  redisClient.on('error', (error) => {
+    logger.error(error, `Redis connection error ${error}.`)
+  })
+
+  return redisClient
+}

package/src/server/constants.js

@@ -0,0 +1 @@
+export const PREVIEW_PATH_PREFIX = '/preview'

package/src/server/forms/README.md

@@ -0,0 +1,10 @@
+# Pre-configured Forms
+
+This folder holds pre-configured form definitions that can be loaded by the runner:
+
+```js
+const server = await createServer({
+  formFileName: 'example.js',
+  formFilePath: join(cwd(), 'server/forms'),
+})
+```