Support for external secondary instances

packages/xforms-engine/src/client/EngineConfig.ts

@@ -1,3 +1,5 @@
+import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
+import type { initializeForm } from '../instance/index.ts';
 import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
 
 /**
@@ -29,7 +31,13 @@ export interface FetchResourceResponse {
  * actual resources (likely, but not necessarily, accessed at a corresponding
  * HTTP URL).
  */
-export type FetchResource = (resource: URL) => Promise<FetchResourceResponse>;
+export type FetchResource<Resource extends URL = URL> = (
+	resource: Resource
+) => Promise<FetchResourceResponse>;
+
+export type FormAttachmentURL = JRResourceURL;
+
+export type FetchFormAttachment = FetchResource<FormAttachmentURL>;
 
 /**
  * Options provided by a client to specify certain aspects of engine runtime
@@ -55,29 +63,59 @@ export interface EngineConfig {
 	readonly stateFactory?: OpaqueReactiveObjectFactory;
 
 	/**
-	 * A client may specify a generic function for retrieving resources referenced
-	 * by a form, such as:
 	 *
-	 * - Form definitions themselves (if not provided directly to the engine by
-	 *   the client)
-	 * - External secondary instances
-	 * - Media (images, audio, video, etc.)
+	 * A client may specify an arbitrary {@link fetch}-like function for retrieving an XML XForm form
+	 * definition.
 	 *
-	 * The function is expected to be a subset of the
-	 * {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API | Fetch API},
-	 * performing `GET` requests for:
+	 * Notes:
 	 *
-	 * - Text resources (e.g. XML, CSV, JSON/GeoJSON)
-	 * - Binary resources (e.g. media)
-	 * - Optionally streamed binary data of either (e.g. for optimized
-	 *   presentation of audio/video)
+	 * - This configuration will only be consuled for calls to
+	 *   {@link initializeForm} with a URL referencing an XML XForm definition. It
+	 *   will be ignored for calls passing an XML XForm form definition directly.
 	 *
-	 * If provided by a client, this function will be used by the engine to
-	 * retrieve any such resource, as required for engine functionality. If
-	 * absent, the engine will use the native `fetch` function (if available, a
-	 * polyfill otherwise). Clients may use this function to provide resources
-	 * from sources other than the network, (or even in a test client to provide
-	 * e.g. resources from test fixtures).
+	 * - For calls to {@link initializeForm} with a URL, if this configuration is
+	 *   not specified it will default to the global {@link fetch} function (if
+	 *   one is defined).
+	 */
+	readonly fetchFormDefinition?: FetchResource;
+
+	/**
+	 * @deprecated
+	 * @alias fetchFormDefinition
 	 */
 	readonly fetchResource?: FetchResource;
+
+	/**
+	 * A client may specify an arbitrary {@link fetch}-like function to retrieve a
+	 * form's attachments, i.e. any `jr:` URL referenced by the form (as specified
+	 * by {@link https://getodk.github.io/xforms-spec/ | ODK XForms}).
+	 *
+	 * Notes:
+	 *
+	 * - This configuration will be consulted for all supported form attachments,
+	 *   as a part of {@link initializeForm | form initialization}.
+	 *
+	 * - If this configuration is not specified it will default to the global
+	 *   {@link fetch} function (if one is defined).
+	 *
+	 * This default behavior will typically result in failure to load form
+	 * attachments—and in most cases this will also cause
+	 * {@link initializeForm | form initialization} to fail overall—with the
+	 * following exceptions:
+	 *
+	 * - **CLIENT-SPECIFIC:** Usage in coordination with a client-implemented
+	 *   {@link https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API | Serivce Worker},
+	 *   which can intercept network requests **generally**. Clients already using
+	 *   a Service Worker may opt for the convenience of handling network requests
+	 *   for `jr:` URLs along with any other network interception logic. Client
+	 *   implementors should be warned, however, that such `jr:` URLs are not
+	 *   namespaced or otherwise scoped to a particular form; such a client would
+	 *   therefore inherently need to coordinate state between the Service Worker
+	 *   and the main thread (or whatever other realm calls
+	 *   {@link initializeForm}).
+	 *
+	 * - **PENDING:** Any usage where the engine does not require access to a
+	 *   form's attachments.
+	 */
+	readonly fetchFormAttachment?: FetchFormAttachment;
 }

packages/xforms-engine/src/instance/index.ts

@@ -1,5 +1,6 @@
 import { identity } from '@getodk/common/lib/identity.ts';
 import { getOwner } from 'solid-js';
+import type { EngineConfig } from '../client/EngineConfig.ts';
 import type { RootNode } from '../client/RootNode.ts';
 import type {
 	InitializeFormOptions as BaseInitializeFormOptions,
@@ -17,10 +18,11 @@ interface InitializeFormOptions extends BaseInitializeFormOptions {
 	readonly config: Partial<InstanceConfig>;
 }
 
-const buildInstanceConfig = (options: Partial<InstanceConfig> = {}): InstanceConfig => {
+const buildInstanceConfig = (options: EngineConfig = {}): InstanceConfig => {
 	return {
-		createUniqueId: options.createUniqueId ?? createUniqueId,
-		fetchResource: options.fetchResource ?? fetch,
+		createUniqueId,
+		fetchFormDefinition: options.fetchFormDefinition ?? options.fetchResource ?? fetch,
+		fetchFormAttachment: options.fetchFormAttachment ?? fetch,
 		stateFactory: options.stateFactory ?? identity,
 	};
 };
@@ -32,7 +34,9 @@ export const initializeForm = async (
 	const owner = getOwner();
 	const scope = createReactiveScope({ owner });
 	const engineConfig = buildInstanceConfig(options.config);
-	const sourceXML = await retrieveSourceXMLResource(input, engineConfig);
+	const sourceXML = await retrieveSourceXMLResource(input, {
+		fetchResource: engineConfig.fetchFormDefinition,
+	});
 	const form = new XFormDefinition(sourceXML);
 	const primaryInstance = new PrimaryInstance(scope, form.model, engineConfig);
 

packages/xforms-engine/src/instance/internal-api/InstanceConfig.ts

@@ -1,7 +1,12 @@
-import type { EngineConfig } from '../../client/EngineConfig.ts';
+import type { FetchFormAttachment, FetchResource } from '../../client/EngineConfig.ts';
+import type { OpaqueReactiveObjectFactory } from '../../client/OpaqueReactiveObjectFactory.ts';
 import type { CreateUniqueId } from '../../lib/unique-id.ts';
 
-export interface InstanceConfig extends Required<EngineConfig> {
+export interface InstanceConfig {
+	readonly stateFactory: OpaqueReactiveObjectFactory;
+	readonly fetchFormDefinition: FetchResource;
+	readonly fetchFormAttachment: FetchFormAttachment;
+
 	/**
 	 * Uniqueness per form instance session (so e.g. persistence isn't necessary).
 	 */

packages/xforms-engine/test/instance/PrimaryInstance.test.ts

@@ -77,7 +77,8 @@ describe('PrimaryInstance engine representation of instance state', () => {
 		return scope.runTask(() => {
 			return new PrimaryInstance(scope, xformDefinition.model, {
 				createUniqueId,
-				fetchResource,
+				fetchFormAttachment: fetchResource,
+				fetchFormDefinition: fetchResource,
 				stateFactory,
 			});
 		});