Support for external secondary instances

.changeset/seven-eels-drop.md

@@ -0,0 +1,8 @@
+---
+'@getodk/xforms-engine': minor
+'@getodk/web-forms': minor
+'@getodk/scenario': minor
+'@getodk/common': minor
+---
+
+Support for external secondary instances (XML, CSV, GeoJSON)

package.json

@@ -42,6 +42,7 @@
     "@types/eslint": "^9.6.1",
     "@types/eslint-config-prettier": "^6.11.3",
     "@types/eslint__js": "^8.42.3",
+    "@types/geojson": "^7946.0.14",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^22.7.2",
     "@typescript-eslint/eslint-plugin": "^8.7.0",

packages/common/src/fixtures/import-glob-helper.ts

@@ -0,0 +1,60 @@
+import { IS_NODE_RUNTIME } from '../env/detection.ts';
+
+interface GlobURLFetchResponse {
+	text(): Promise<string>;
+}
+
+type Awaitable<T> = Promise<T> | T;
+
+type FetchGlobURL = (globURL: string) => Awaitable<GlobURLFetchResponse>;
+
+let fetchGlobURL: FetchGlobURL;
+
+if (IS_NODE_RUNTIME) {
+	const { readFile } = await import('node:fs/promises');
+
+	class NodeGlobURLFetchResponse {
+		readonly fsPath: string;
+
+		constructor(globURL: string) {
+			this.fsPath = globURL.replace('/@fs/', '/');
+		}
+
+		text(): Promise<string> {
+			return readFile(this.fsPath, 'utf-8');
+		}
+	}
+
+	fetchGlobURL = (globURL) => {
+		return new NodeGlobURLFetchResponse(globURL);
+	};
+} else {
+	fetchGlobURL = fetch;
+}
+
+type ImportMetaGlobURLRecord = Readonly<Record<string, string>>;
+
+export type ImportMetaGlobLoader = (this: void) => Promise<string>;
+
+export type GlobLoaderEntry = readonly [absolutePath: string, loader: ImportMetaGlobLoader];
+
+const globLoader = (globURL: string): ImportMetaGlobLoader => {
+	return async () => {
+		const response = await fetchGlobURL(globURL);
+
+		return response.text();
+	};
+};
+
+export const toGlobLoaderEntries = (
+	importMeta: ImportMeta,
+	globObject: ImportMetaGlobURLRecord
+): readonly GlobLoaderEntry[] => {
+	const parentPathURL = new URL('./', importMeta.url);
+
+	return Object.entries(globObject).map(([relativePath, value]) => {
+		const { pathname: absolutePath } = new URL(relativePath, parentPathURL);
+
+		return [absolutePath, globLoader(value)];
+	});
+};

packages/common/src/fixtures/test-scenario/csv-attachment.csv

@@ -0,0 +1,3 @@
+item-label,item-value
+Y,y
+Z,z

packages/common/src/fixtures/test-scenario/xml-attachment.xml

@@ -0,0 +1,10 @@
+<instance-root>
+  <instance-item>
+    <item-label>A</item-label>
+    <item-value>a</item-value>
+  </instance-item>
+  <instance-item>
+    <item-label>B</item-label>
+    <item-value>b</item-value>
+  </instance-item>
+</instance-root>

packages/common/src/fixtures/xform-attachments.ts

@@ -0,0 +1,137 @@
+import { UpsertableMap } from '../lib/collections/UpsertableMap.ts';
+import { UnreachableError } from '../lib/error/UnreachableError.ts';
+import type { ImportMetaGlobLoader } from './import-glob-helper.ts';
+import { toGlobLoaderEntries } from './import-glob-helper.ts';
+
+/**
+ * @todo Support Windows paths?
+ */
+const getFileName = (absolutePath: string): string => {
+	const fileName = absolutePath.split('/').at(-1);
+
+	if (fileName == null) {
+		throw new Error(`Failed to get file name for file system path: ${absolutePath}`);
+	}
+
+	return fileName;
+};
+
+// prettier-ignore
+const xformAttachmentFileExtensions = [
+	'.csv',
+	'.geojson',
+	'.xml',
+	'.xml.example',
+	'.xlsx',
+] as const;
+
+type XFormAttachmentFileExtensions = typeof xformAttachmentFileExtensions;
+type XFormAttachmentFileExtension = XFormAttachmentFileExtensions[number];
+
+const getFileExtension = (absolutePath: string): XFormAttachmentFileExtension => {
+	for (const extension of xformAttachmentFileExtensions) {
+		if (absolutePath.endsWith(extension)) {
+			return extension;
+		}
+	}
+
+	throw new Error(`Unknown file extension for file name: ${getFileName(absolutePath)}`);
+};
+
+const getParentDirectory = (absolutePath: string): string => {
+	const fileName = getFileName(absolutePath);
+
+	return absolutePath.slice(0, absolutePath.length - fileName.length - 1);
+};
+
+const xformAttachmentFixtureLoaderEntries = toGlobLoaderEntries(
+	import.meta,
+	import.meta.glob<true, 'url', string>('./*/**/*', {
+		query: '?url',
+		import: 'default',
+		eager: true,
+	})
+);
+
+export class XFormAttachmentFixture {
+	readonly fileName: string;
+	readonly fileExtension: string;
+	readonly mimeType: string;
+
+	constructor(
+		readonly absolutePath: string,
+		readonly load: ImportMetaGlobLoader
+	) {
+		const fileName = getFileName(absolutePath);
+		const fileExtension = getFileExtension(fileName);
+
+		this.fileName = fileName;
+		this.fileExtension = fileExtension;
+
+		switch (fileExtension) {
+			case '.csv':
+				this.mimeType = 'text/csv';
+				break;
+
+			case '.geojson':
+				this.mimeType = 'application/geo+json';
+				break;
+
+			case '.xml':
+			case '.xml.example':
+				this.mimeType = 'text/xml';
+				break;
+
+			case '.xlsx':
+				this.mimeType = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+				break;
+
+			default:
+				throw new UnreachableError(fileExtension);
+		}
+	}
+}
+
+type XFormAttachmentFixtureEntry = readonly [absolutePath: string, fixture: XFormAttachmentFixture];
+
+type XFormAttachmentFixtureEntries = readonly XFormAttachmentFixtureEntry[];
+
+const xformAttachmentFixtureEntries: XFormAttachmentFixtureEntries =
+	xformAttachmentFixtureLoaderEntries.map(([absolutePath, load]) => {
+		const fixture = new XFormAttachmentFixture(absolutePath, load);
+
+		return [absolutePath, fixture];
+	});
+
+type XFormAttachmentFixturesByAbsolutePath = ReadonlyMap<string, XFormAttachmentFixture>;
+
+const buildXFormAttachmentFixturesByAbsolutePath = (
+	entries: XFormAttachmentFixtureEntries
+): XFormAttachmentFixturesByAbsolutePath => {
+	return new Map(entries);
+};
+
+export const xformAttachmentFixturesByPath = buildXFormAttachmentFixturesByAbsolutePath(
+	xformAttachmentFixtureEntries
+);
+
+type XFormAttachmentFixturesByDirectory = ReadonlyMap<string, readonly XFormAttachmentFixture[]>;
+
+const buildXFormAttachmentFixturesByDirectory = (
+	entries: XFormAttachmentFixtureEntries
+): XFormAttachmentFixturesByDirectory => {
+	const result = new UpsertableMap<string, XFormAttachmentFixture[]>();
+
+	for (const [absolutePath, fixture] of entries) {
+		const parentDirectory = getParentDirectory(absolutePath);
+		const subset = result.upsert(parentDirectory, () => []);
+
+		subset.push(fixture);
+	}
+
+	return result;
+};
+
+export const xformAttachmentFixturesByDirectory = buildXFormAttachmentFixturesByDirectory(
+	xformAttachmentFixtureEntries
+);

packages/common/src/fixtures/xforms.ts

@@ -1,24 +1,40 @@
-import { IS_NODE_RUNTIME } from '../env/detection.ts';
+import { JRResourceService } from '../jr-resources/JRResourceService.ts';
+import type { JRResourceURL } from '../jr-resources/JRResourceURL.ts';
 import { UpsertableMap } from '../lib/collections/UpsertableMap.ts';
+import { toGlobLoaderEntries } from './import-glob-helper.ts';
 
 type XFormResourceType = 'local' | 'remote';
 
+type ResourceServiceFactory = () => JRResourceService;
+
 interface BaseXFormResourceOptions {
 	readonly localPath: string | null;
 	readonly identifier: string | null;
 	readonly category: string | null;
+	readonly initializeFormAttachmentService?: ResourceServiceFactory;
 }
 
 interface LocalXFormResourceOptions extends BaseXFormResourceOptions {
 	readonly localPath: string;
 	readonly identifier: string;
 	readonly category: string;
+	readonly initializeFormAttachmentService: ResourceServiceFactory;
 }
 
 interface RemoteXFormResourceOptions extends BaseXFormResourceOptions {
 	readonly category: string | null;
 	readonly localPath: null;
 	readonly identifier: string;
+
+	/**
+	 * @todo Note that {@link RemoteXFormResourceOptions} corresponds to an API
+	 * primarily serving
+	 * {@link https://getodk.org/web-forms-preview/ | Web Forms Preview}
+	 * functionality. In theory, we could allow a mechanism to support form
+	 * attachments in for that use case, but we'd need to design for it. Until
+	 * then, it doesn't make a whole lot of sense to accept arbitrary IO here.
+	 */
+	readonly initializeFormAttachmentService?: never;
 }
 
 type XFormResourceOptions<Type extends XFormResourceType> = {
@@ -71,20 +87,28 @@ const xformURLLoader = (url: URL): LoadXFormXML => {
 	};
 };
 
+const getNoopResourceService: ResourceServiceFactory = () => {
+	return new JRResourceService();
+};
+
 export class XFormResource<Type extends XFormResourceType> {
 	static forLocalFixture(
-		importerURL: string,
-		relativePath: string,
-		localURL: URL | string,
+		localPath: string,
+		resourceURL: URL,
 		loadXML?: LoadXFormXML
 	): XFormResource<'local'> {
-		const resourceURL = new URL(localURL, importerURL);
-		const localPath = new URL(relativePath, importerURL).pathname;
-
 		return new XFormResource('local', resourceURL, loadXML ?? xformURLLoader(resourceURL), {
 			category: localFixtureDirectoryCategory(localPath),
 			localPath,
 			identifier: pathToFileName(localPath),
+			initializeFormAttachmentService: () => {
+				const service = new JRResourceService();
+				const parentPath = localPath.replace(/\/[^/]+$/, '');
+
+				service.activateFixtures(parentPath, ['file', 'file-csv']);
+
+				return service;
+			},
 		});
 	}
 
@@ -96,6 +120,8 @@ export class XFormResource<Type extends XFormResourceType> {
 		const loadXML = xformURLLoader(resourceURL);
 
 		return new XFormResource('remote', resourceURL, loadXML, {
+			...options,
+
 			category: options?.category ?? 'other',
 			identifier: options?.identifier ?? extractURLIdentifier(resourceURL),
 			localPath: options?.localPath ?? null,
@@ -105,6 +131,7 @@ export class XFormResource<Type extends XFormResourceType> {
 	readonly category: string;
 	readonly localPath: XFormResourceOptions<Type>['localPath'];
 	readonly identifier: XFormResourceOptions<Type>['identifier'];
+	readonly fetchFormAttachment: (url: JRResourceURL) => Promise<Response>;
 
 	private constructor(
 		readonly resourceType: Type,
@@ -115,37 +142,36 @@ export class XFormResource<Type extends XFormResourceType> {
 		this.category = options.category ?? 'other';
 		this.localPath = options.localPath;
 		this.identifier = options.identifier;
-	}
-}
 
-export type XFormFixture = XFormResource<'local'>;
+		const initializeFormAttachmentService =
+			options.initializeFormAttachmentService ?? getNoopResourceService;
 
-const buildXFormFixtures = (): readonly XFormFixture[] => {
-	if (IS_NODE_RUNTIME) {
-		const fixtureXMLByRelativePath = import.meta.glob<false, 'raw', string>('./**/*.xml', {
-			query: '?raw',
-			import: 'default',
-			eager: false,
-		});
+		let resourceService: JRResourceService | null = null;
 
-		return Object.entries(fixtureXMLByRelativePath).map(([path, loadXML]) => {
-			const localURL = new URL(path, import.meta.url);
-			const fixture = XFormResource.forLocalFixture(import.meta.url, path, localURL, loadXML);
+		this.fetchFormAttachment = (url) => {
+			resourceService = resourceService ?? initializeFormAttachmentService();
 
-			return fixture;
-		});
+			return resourceService.handleRequest(url);
+		};
 	}
+}
 
-	const fixtureURLByRelativePath = import.meta.glob<true, 'url', string>('./**/*.xml', {
+const xformFixtureLoaderEntries = toGlobLoaderEntries(
+	import.meta,
+	import.meta.glob<true, 'url', string>('./**/*.xml', {
 		query: '?url',
 		import: 'default',
 		eager: true,
-	});
+	})
+);
 
-	return Object.entries(fixtureURLByRelativePath).map(([path, url]) => {
-		const fixture = XFormResource.forLocalFixture(import.meta.url, path, url);
+export type XFormFixture = XFormResource<'local'>;
+
+const buildXFormFixtures = (): readonly XFormFixture[] => {
+	return xformFixtureLoaderEntries.map(([path, loadXML]) => {
+		const resourceURL = new URL(path, SELF_URL);
 
-		return fixture;
+		return XFormResource.forLocalFixture(path, resourceURL, loadXML);
 	});
 };