@defra/forms-engine-plugin 1.0.0 → 1.0.2

package/.server/server/plugins/engine/README.md

@@ -85,3 +85,59 @@ There are a number of `LiquidJS` filters available to you from within the templa
   }
 ]
 ```
+
+## Session Rehydration
+
+To support Save and Return functionality, this application now supports session rehydration. This allows user session state to be recovered across browser sessions or devices — even after the in-memory Redis session has expired.
+
+### How it works
+
+To support session rehydration from a backend (e.g. for Save & Return), the consuming application must provide two functions when registering the DXT engine plugin:
+
+```
+export interface PluginOptions {
+  ...
+  keyGenerator?: (request) => string
+  sessionHydrator?: (request) => Promise<FormSubmissionState | null>
+  ...
+}
+
+```
+
+1. `keyGenerator(request)`
+
+This generates a stable and consistent cache key used to store and retrieve user state. It should return a string based on persistent identifiers such as userId, businessId, and grantId — i.e., something like:
+
+```
+const keyGenerator = request => {
+  const { userId, businessId, grantId } = request.app.userContext
+  return `${userId}:${businessId}:${grantId}`
+}
+```
+
+2. `sessionHydrator(request, key)`
+
+This function is called when no session state is found in Redis. It should fetch saved state (e.g., from an API) using the provided key and return it in the same structure expected by the form engine:
+
+```
+const sessionHydrator = async (request, key) => {
+  const response = await fetch(`https://backend.api/state/${key}`)
+  if (!response.ok) return null
+  return await response.json()  // Must match form engine state shape
+}
+```
+
+#### Session flow
+
+- When user resumes a journey and Redis session data is missing or expired, DXT will use `keyGenerator` and `sessionHydrator` to fetch the saved state from an external API (e.g. `/state` endpoint).
+- The fetched state is written back into Redis and used to continue the user journey.
+- The rehydrated state must include enough information to satisfy schema validation on the current or next page.
+- To properly resume a session, users should be redirected to the `/summary` page. This ensures the UI has all required answers preloaded and avoids invalid transitions from deep links.
+
+### Additional notes
+
+Flash messaging and other ephemeral session data still rely on yar.id.
+
+If the restored state does not satisfy the schema for the current page, the user will be redirected to the first incomplete step.
+
+In development, a mock identity and /state response can be used to simulate a persisted session.

package/.server/server/plugins/engine/configureEnginePlugin.d.ts

@@ -1,5 +1,6 @@
 import { type FormDefinition } from '@defra/forms-model';
-import { plugin, type PluginOptions } from '~/src/server/plugins/engine/plugin.js';
+import { plugin } from '~/src/server/plugins/engine/plugin.js';
+import { type PluginOptions } from '~/src/server/plugins/engine/types.js';
 import { type RouteConfig } from '~/src/server/types.js';
 export declare const configureEnginePlugin: ({ formFileName, formFilePath, services, controllers }?: RouteConfig) => Promise<{
     plugin: typeof plugin;

package/.server/server/plugins/engine/configureEnginePlugin.js

@@ -2,9 +2,9 @@ import { join, parse } from 'node:path';
 import { FORM_PREFIX } from "../../constants.js";
 import { FormModel } from "./models/FormModel.js";
 import { plugin } from "./plugin.js";
-import { findPackageRoot } from "./plugin.js";
 import * as defaultServices from "./services/index.js";
 import { formsService } from "./services/localFormsService.js";
+import { findPackageRoot } from "./vision.js";
 import { devtoolContext } from "../nunjucks/context.js";
 export const configureEnginePlugin = async ({
   formFileName,

package/.server/server/plugins/engine/configureEnginePlugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"configureEnginePlugin.js","names":["join","parse","FORM_PREFIX","FormModel","plugin","findPackageRoot","defaultServices","formsService","devtoolContext","configureEnginePlugin","formFileName","formFilePath","services","controllers","model","definition","getForm","name","initialBasePath","basePath","options","cacheName","nunjucks","baseLayoutPath","paths","viewContext","importPath","ext","attributes","type","formImport","with","default"],"sources":["../../../../src/server/plugins/engine/configureEnginePlugin.ts"],"sourcesContent":["import { join, parse } from 'node:path'\n\nimport { type FormDefinition } from '@defra/forms-model'\n\nimport { FORM_PREFIX } from '~/src/server/constants.js'\nimport { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'\nimport {\n  plugin,\n  type PluginOptions\n} from '~/src/server/plugins/engine/plugin.js'\nimport { findPackageRoot } from '~/src/server/plugins/engine/plugin.js'\nimport * as defaultServices from '~/src/server/plugins/engine/services/index.js'\nimport { formsService } from '~/src/server/plugins/engine/services/localFormsService.js'\nimport { devtoolContext } from '~/src/server/plugins/nunjucks/context.js'\nimport { type RouteConfig } from '~/src/server/types.js'\n\nexport const configureEnginePlugin = async ({\n  formFileName,\n  formFilePath,\n  services,\n  controllers\n}: RouteConfig = {}): Promise<{\n  plugin: typeof plugin\n  options: PluginOptions\n}> => {\n  let model: FormModel | undefined\n\n  if (formFileName && formFilePath) {\n    const definition = await getForm(join(formFilePath, formFileName))\n    const { name } = parse(formFileName)\n\n    const initialBasePath = `${FORM_PREFIX}${name}`\n\n    model = new FormModel(\n      definition,\n      { basePath: initialBasePath },\n      services,\n      controllers\n    )\n  }\n\n  return {\n    plugin,\n    options: {\n      model,\n      services: services ?? {\n        // services for testing, else use the disk loader option for running this service locally\n        ...defaultServices,\n        formsService: await formsService()\n      },\n      controllers,\n      cacheName: 'session',\n      nunjucks: {\n        baseLayoutPath: 'dxt-devtool-baselayout.html',\n        paths: [join(findPackageRoot(), 'src/server/devserver')] // custom layout to make it really clear this is not the same as the runner\n      },\n      viewContext: devtoolContext\n    }\n  }\n}\n\nexport async function getForm(importPath: string) {\n  const { ext } = parse(importPath)\n\n  const attributes: ImportAttributes = {\n    type: ext === '.json' ? 'json' : 'module'\n  }\n\n  const formImport = import(importPath, { with: attributes }) as Promise<{\n    default: FormDefinition\n  }>\n\n  const { default: definition } = await formImport\n  return definition\n}\n"],"mappings":"AAAA,SAASA,IAAI,EAAEC,KAAK,QAAQ,WAAW;AAIvC,SAASC,WAAW;AACpB,SAASC,SAAS;AAClB,SACEC,MAAM;AAGR,SAASC,eAAe;AACxB,OAAO,KAAKC,eAAe;AAC3B,SAASC,YAAY;AACrB,SAASC,cAAc;AAGvB,OAAO,MAAMC,qBAAqB,GAAG,MAAAA,CAAO;EAC1CC,YAAY;EACZC,YAAY;EACZC,QAAQ;EACRC;AACW,CAAC,GAAG,CAAC,CAAC,KAGb;EACJ,IAAIC,KAA4B;EAEhC,IAAIJ,YAAY,IAAIC,YAAY,EAAE;IAChC,MAAMI,UAAU,GAAG,MAAMC,OAAO,CAAChB,IAAI,CAACW,YAAY,EAAED,YAAY,CAAC,CAAC;IAClE,MAAM;MAAEO;IAAK,CAAC,GAAGhB,KAAK,CAACS,YAAY,CAAC;IAEpC,MAAMQ,eAAe,GAAG,GAAGhB,WAAW,GAAGe,IAAI,EAAE;IAE/CH,KAAK,GAAG,IAAIX,SAAS,CACnBY,UAAU,EACV;MAAEI,QAAQ,EAAED;IAAgB,CAAC,EAC7BN,QAAQ,EACRC,WACF,CAAC;EACH;EAEA,OAAO;IACLT,MAAM;IACNgB,OAAO,EAAE;MACPN,KAAK;MACLF,QAAQ,EAAEA,QAAQ,IAAI;QACpB;QACA,GAAGN,eAAe;QAClBC,YAAY,EAAE,MAAMA,YAAY,CAAC;MACnC,CAAC;MACDM,WAAW;MACXQ,SAAS,EAAE,SAAS;MACpBC,QAAQ,EAAE;QACRC,cAAc,EAAE,6BAA6B;QAC7CC,KAAK,EAAE,CAACxB,IAAI,CAACK,eAAe,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC,CAAC;MAC3D,CAAC;MACDoB,WAAW,EAAEjB;IACf;EACF,CAAC;AACH,CAAC;AAED,OAAO,eAAeQ,OAAOA,CAACU,UAAkB,EAAE;EAChD,MAAM;IAAEC;EAAI,CAAC,GAAG1B,KAAK,CAACyB,UAAU,CAAC;EAEjC,MAAME,UAA4B,GAAG;IACnCC,IAAI,EAAEF,GAAG,KAAK,OAAO,GAAG,MAAM,GAAG;EACnC,CAAC;EAED,MAAMG,UAAU,GAAG,MAAM,CAACJ,UAAU,EAAE;IAAEK,IAAI,EAAEH;EAAW,CAAC,CAExD;EAEF,MAAM;IAAEI,OAAO,EAAEjB;EAAW,CAAC,GAAG,MAAMe,UAAU;EAChD,OAAOf,UAAU;AACnB","ignoreList":[]}
+{"version":3,"file":"configureEnginePlugin.js","names":["join","parse","FORM_PREFIX","FormModel","plugin","defaultServices","formsService","findPackageRoot","devtoolContext","configureEnginePlugin","formFileName","formFilePath","services","controllers","model","definition","getForm","name","initialBasePath","basePath","options","cacheName","nunjucks","baseLayoutPath","paths","viewContext","importPath","ext","attributes","type","formImport","with","default"],"sources":["../../../../src/server/plugins/engine/configureEnginePlugin.ts"],"sourcesContent":["import { join, parse } from 'node:path'\n\nimport { type FormDefinition } from '@defra/forms-model'\n\nimport { FORM_PREFIX } from '~/src/server/constants.js'\nimport { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'\nimport { plugin } from '~/src/server/plugins/engine/plugin.js'\nimport * as defaultServices from '~/src/server/plugins/engine/services/index.js'\nimport { formsService } from '~/src/server/plugins/engine/services/localFormsService.js'\nimport { type PluginOptions } from '~/src/server/plugins/engine/types.js'\nimport { findPackageRoot } from '~/src/server/plugins/engine/vision.js'\nimport { devtoolContext } from '~/src/server/plugins/nunjucks/context.js'\nimport { type RouteConfig } from '~/src/server/types.js'\n\nexport const configureEnginePlugin = async ({\n  formFileName,\n  formFilePath,\n  services,\n  controllers\n}: RouteConfig = {}): Promise<{\n  plugin: typeof plugin\n  options: PluginOptions\n}> => {\n  let model: FormModel | undefined\n\n  if (formFileName && formFilePath) {\n    const definition = await getForm(join(formFilePath, formFileName))\n    const { name } = parse(formFileName)\n\n    const initialBasePath = `${FORM_PREFIX}${name}`\n\n    model = new FormModel(\n      definition,\n      { basePath: initialBasePath },\n      services,\n      controllers\n    )\n  }\n\n  return {\n    plugin,\n    options: {\n      model,\n      services: services ?? {\n        // services for testing, else use the disk loader option for running this service locally\n        ...defaultServices,\n        formsService: await formsService()\n      },\n      controllers,\n      cacheName: 'session',\n      nunjucks: {\n        baseLayoutPath: 'dxt-devtool-baselayout.html',\n        paths: [join(findPackageRoot(), 'src/server/devserver')] // custom layout to make it really clear this is not the same as the runner\n      },\n      viewContext: devtoolContext\n    }\n  }\n}\n\nexport async function getForm(importPath: string) {\n  const { ext } = parse(importPath)\n\n  const attributes: ImportAttributes = {\n    type: ext === '.json' ? 'json' : 'module'\n  }\n\n  const formImport = import(importPath, { with: attributes }) as Promise<{\n    default: FormDefinition\n  }>\n\n  const { default: definition } = await formImport\n  return definition\n}\n"],"mappings":"AAAA,SAASA,IAAI,EAAEC,KAAK,QAAQ,WAAW;AAIvC,SAASC,WAAW;AACpB,SAASC,SAAS;AAClB,SAASC,MAAM;AACf,OAAO,KAAKC,eAAe;AAC3B,SAASC,YAAY;AAErB,SAASC,eAAe;AACxB,SAASC,cAAc;AAGvB,OAAO,MAAMC,qBAAqB,GAAG,MAAAA,CAAO;EAC1CC,YAAY;EACZC,YAAY;EACZC,QAAQ;EACRC;AACW,CAAC,GAAG,CAAC,CAAC,KAGb;EACJ,IAAIC,KAA4B;EAEhC,IAAIJ,YAAY,IAAIC,YAAY,EAAE;IAChC,MAAMI,UAAU,GAAG,MAAMC,OAAO,CAAChB,IAAI,CAACW,YAAY,EAAED,YAAY,CAAC,CAAC;IAClE,MAAM;MAAEO;IAAK,CAAC,GAAGhB,KAAK,CAACS,YAAY,CAAC;IAEpC,MAAMQ,eAAe,GAAG,GAAGhB,WAAW,GAAGe,IAAI,EAAE;IAE/CH,KAAK,GAAG,IAAIX,SAAS,CACnBY,UAAU,EACV;MAAEI,QAAQ,EAAED;IAAgB,CAAC,EAC7BN,QAAQ,EACRC,WACF,CAAC;EACH;EAEA,OAAO;IACLT,MAAM;IACNgB,OAAO,EAAE;MACPN,KAAK;MACLF,QAAQ,EAAEA,QAAQ,IAAI;QACpB;QACA,GAAGP,eAAe;QAClBC,YAAY,EAAE,MAAMA,YAAY,CAAC;MACnC,CAAC;MACDO,WAAW;MACXQ,SAAS,EAAE,SAAS;MACpBC,QAAQ,EAAE;QACRC,cAAc,EAAE,6BAA6B;QAC7CC,KAAK,EAAE,CAACxB,IAAI,CAACO,eAAe,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC,CAAC;MAC3D,CAAC;MACDkB,WAAW,EAAEjB;IACf;EACF,CAAC;AACH,CAAC;AAED,OAAO,eAAeQ,OAAOA,CAACU,UAAkB,EAAE;EAChD,MAAM;IAAEC;EAAI,CAAC,GAAG1B,KAAK,CAACyB,UAAU,CAAC;EAEjC,MAAME,UAA4B,GAAG;IACnCC,IAAI,EAAEF,GAAG,KAAK,OAAO,GAAG,MAAM,GAAG;EACnC,CAAC;EAED,MAAMG,UAAU,GAAG,MAAM,CAACJ,UAAU,EAAE;IAAEK,IAAI,EAAEH;EAAW,CAAC,CAExD;EAEF,MAAM;IAAEI,OAAO,EAAEjB;EAAW,CAAC,GAAG,MAAMe,UAAU;EAChD,OAAOf,UAAU;AACnB","ignoreList":[]}

package/.server/server/plugins/engine/plugin.d.ts

@@ -1,33 +1,8 @@
-import { type PluginProperties, type Server } from '@hapi/hapi';
-import { type Environment } from 'nunjucks';
-import { FormModel } from '~/src/server/plugins/engine/models/index.js';
-import { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js';
-import { type FilterFunction } from '~/src/server/plugins/engine/types.js';
-import { type Services } from '~/src/server/types.js';
-export declare function findPackageRoot(): string;
-export interface PluginOptions {
-    model?: FormModel;
-    services?: Services;
-    controllers?: Record<string, typeof PageController>;
-    cacheName?: string;
-    filters?: Record<string, FilterFunction>;
-    pluginPath?: string;
-    nunjucks: {
-        baseLayoutPath: string;
-        paths: string[];
-    };
-    viewContext: PluginProperties['forms-engine-plugin']['viewContext'];
-}
+import { type Server } from '@hapi/hapi';
+import { type PluginOptions } from '~/src/server/plugins/engine/types.js';
 export declare const plugin: {
     name: string;
     dependencies: string[];
     multiple: true;
     register(server: Server, options: PluginOptions): Promise<void>;
 };
-interface CompileOptions {
-    environment: Environment;
-}
-export interface EngineConfigurationObject {
-    compileOptions: CompileOptions;
-}
-export {};