feat(models): OpenAI-compatible /v1/* gateway as built-in Resources (#631, Phase 4 of #510)

components/Scope.ts

@@ -145,6 +145,7 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 		this.options = new OptionsWatcher(pluginName, configFilePath, this.#logger, isRootConfig)
 			.on('error', this.#handleError.bind(this))
 			.on('change', this.#optionsWatcherChangeListener.bind(this)())
+			.on('remove', this.#optionsWatcherRemoveListener())
 			.on('ready', this.#handleOptionsWatcherReady.bind(this));
 
 		// Bridge cross-thread deploy lifecycle events for this component. The
@@ -361,6 +362,23 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 		};
 	}
 
+	#optionsWatcherRemoveListener() {
+		// eslint-disable-next-line @typescript-eslint/no-this-alias
+		const scope = this;
+		// Deleting a component's config block emits `remove` (not `change`), so without
+		// this listener a running component keeps serving until some unrelated restart —
+		// even though absence is the canonical disabled state for opt-in built-ins like
+		// the /v1 models gateway. Mirrors the change listener: a plugin that registers
+		// its own `remove` handler owns the response and no restart is requested.
+		return function handleOptionsWatcherRemove(this: OptionsWatcher) {
+			if (this.listenerCount('remove') > 1) {
+				return;
+			}
+			scope.#logger.debug?.('Options removed, requesting restart');
+			scope.requestRestart();
+		};
+	}
+
 	#getFilesOption(): FileAndURLPathConfig | undefined {
 		const config = this.options.getAll();
 		if (

components/componentLoader.ts

@@ -113,6 +113,16 @@ export const TRUSTED_RESOURCE_PLUGINS: any = {
 		return require('../server/fastifyRoutes');
 	},
 	login,
+	// String entry: the loader `await import()`s these lazily when the component is actually
+	// processed, so the gateway's module graph is not pulled into componentLoader's own
+	// evaluation. `#src/*` is used rather than a relative path because it resolves under both
+	// conditions (source under --conditions=typestrip, dist otherwise); a relative extensionless
+	// require would only resolve against dist.
+	//
+	// The component is only *processed* when a `modelsGateway` key exists in the config, since
+	// the root loop skips absent keys (`if (!componentConfig) continue`). `defaultConfig.yaml`
+	// ships no such key, so an instance that never opts in pays nothing for this entry.
+	modelsGateway: '#src/resources/models/v1/index',
 	static: staticFiles,
 	customFunctions: {},
 	http: httpComponent,

integrationTests/server/fixtures/v1-gateway-test-backend.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * Minimal test backend for the /v1/* gateway integration test (#631).
+ *
+ * Implements a simple echo backend inline — no imports from the Harper dist
+ * directory. Loaded by `bootstrapModels()` via a `backend: <absolute-path>`
+ * entry in the test config. Uses `global.models.registerBackend()` (which is
+ * already populated when this register function is invoked).
+ */
+
+function textFromInput(input) {
+	if (typeof input === 'string') return input;
+	const messages = Array.isArray(input) ? input : input.messages;
+	return messages.map((m) => m.content || '').join(' ');
+}
+
+const echoGenerative = {
+	name: 'integration-test-echo',
+	capabilities: () => ({ embed: false, generate: true, stream: true, tools: false, adapters: false }),
+	async generate(input) {
+		const text = textFromInput(input);
+		const content = `[echo]: ${text}`;
+		return {
+			status: 'completed',
+			output: { content, finishReason: 'stop' },
+			usage: { promptTokens: text.length, completionTokens: content.length },
+		};
+	},
+	async *generateStream(input) {
+		const text = textFromInput(input);
+		const words = `[echo stream]: ${text}`.split(' ');
+		for (const word of words) {
+			yield { deltaContent: word + ' ' };
+		}
+		yield { finishReason: 'stop' };
+	},
+};
+
+const echoEmbedding = {
+	name: 'integration-test-echo-embed',
+	capabilities: () => ({ embed: true, generate: false, stream: false, tools: false, adapters: false }),
+	async embed(input) {
+		const inputs = Array.isArray(input) ? input : [input];
+		return {
+			status: 'completed',
+			output: inputs.map(() => new Float32Array([0.1, 0.2, 0.3, 0.4])),
+			usage: { embeddingTokens: inputs.length },
+		};
+	},
+};
+
+/**
+ * Called by `registerFromModule` in bootstrap.ts. `global.models` is
+ * available at call time (Models singleton is set before bootstrapModels runs).
+ * @param {{ logicalName: string, kind: 'embedding' | 'generative' }} args
+ */
+exports.register = function ({ logicalName, kind }) {
+	const models = global.models;
+	if (!models) throw new Error('global.models is not set — bootstrap order violation');
+	if (kind === 'generative') {
+		models.registerBackend('generative', logicalName, echoGenerative);
+	} else if (kind === 'embedding') {
+		models.registerBackend('embedding', logicalName, echoEmbedding);
+	}
+};

integrationTests/server/v1-gateway-collision-app/config.yaml

@@ -0,0 +1,7 @@
+# Fixture for the /v1 route-reservation test: an app that (wrongly) tries to claim
+# the gateway's fixed `v1/models` path with its own custom Resource. The gateway's
+# reservedPath marking must turn this into a loud conflict rather than a silent
+# replacement of the endpoint and its super_user gate.
+rest: true
+jsResource:
+  files: resources.js

integrationTests/server/v1-gateway-collision-app/resources.js

@@ -0,0 +1,19 @@
+// An app Resource that tries to claim the gateway's fixed `v1/models` route.
+// Before path reservation, this silently replaced the gateway endpoint (both are
+// non-table Resources, so Resources.set saw no conflict). Now it must produce a
+// loud conflict (ErrorResource → 500 + logged error), never this payload.
+class Imposter extends Resource {
+	static path = 'v1/models';
+	get() {
+		return { imposter: true };
+	}
+}
+
+// A legitimately-named app resource, proving the app itself still loads and serves.
+export class Legit extends Resource {
+	get() {
+		return { legit: true };
+	}
+}
+
+export { Imposter };

integrationTests/server/v1-gateway-mixed-app.test.ts

@@ -0,0 +1,202 @@
+/**
+ * Mixed-app regression test for the `/v1/*` gateway (#631, PR #1616 review).
+ *
+ * An earlier revision made componentLoader start REST on the gateway's behalf
+ * whenever `modelsGateway` was enabled:
+ *
+ *   if (isRoot && resources.isWorker && config.modelsGateway?.enabled) {
+ *     REST.ensureStarted({ server, resources });
+ *   }
+ *
+ * Root components load before application directories, and REST serves the
+ * shared `Resources` registry, so that force-start exposed every REST-exportable
+ * entry — including apps that had deliberately omitted `rest`. It also set
+ * `REST.started` before a later app could contribute its own port/host/urlPath/
+ * WebSocket options.
+ *
+ * The force-start is gone; the gateway is a plain plugin that requires REST to
+ * already be configured. This pins that.
+ *
+ * IMPORTANT — what this test can and cannot show. Once a root `rest` section
+ * exists, REST serves the shared registry and an app's `@export`ed table is
+ * reachable whether or not that app declared `rest` itself. That is existing
+ * Harper behavior and is not what this test is about. The gateway-specific
+ * regression is only observable with NO `rest` section anywhere: previously,
+ * enabling the gateway alone was enough to stand REST up and expose the app.
+ * So this suite deliberately configures no `rest` at all.
+ *
+ * Expected now: enabling the gateway starts nothing, so the app stays off the
+ * wire. `/v1/*` is unserved too — that is the documented trade-off in
+ * resources/models/v1/index.ts, which logs a warning rather than forcing REST.
+ */
+import { suite, test, before, after } from 'node:test';
+import assert from 'node:assert';
+import { resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setupHarperWithFixture, teardownHarper, type ContextWithHarper } from '@harperfast/integration-testing';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const FIXTURE_PATH = resolvePath(__dirname, 'v1-gateway-mixed-app');
+const ECHO_BACKEND_PATH = resolvePath(__dirname, 'fixtures/v1-gateway-test-backend.cjs');
+
+function authHeader(ctx: ContextWithHarper): string {
+	return `Basic ${Buffer.from(`${ctx.harper.admin.username}:${ctx.harper.admin.password}`).toString('base64')}`;
+}
+
+/**
+ * With no REST server expected, a request may be refused outright rather than
+ * answered. Both outcomes mean "not served"; only a 200 is a regression.
+ */
+async function statusOrRefused(ctx: ContextWithHarper, path: string): Promise<number | 'refused'> {
+	try {
+		const res = await fetch(`${ctx.harper.httpURL}${path}`, {
+			headers: { Authorization: authHeader(ctx) },
+			signal: AbortSignal.timeout(5_000),
+		});
+		return res.status;
+	} catch {
+		return 'refused';
+	}
+}
+
+suite('/v1 gateway does not stand REST up on another component behalf', (ctx: ContextWithHarper) => {
+	before(async () => {
+		await setupHarperWithFixture(ctx, FIXTURE_PATH, {
+			config: {
+				// Deliberately NO `rest` section — see the header. This is the only
+				// configuration in which the gateway's own effect on REST is observable.
+				modelsGateway: { enabled: true },
+				models: {
+					generative: { default: { backend: ECHO_BACKEND_PATH } },
+					embedding: { default: { backend: ECHO_BACKEND_PATH } },
+				},
+			},
+			env: {},
+		});
+	});
+
+	after(async () => {
+		await teardownHarper(ctx);
+	});
+
+	test('an app that omitted `rest` is not exposed by enabling the gateway', async () => {
+		const status = await statusOrRefused(ctx, '/MixedAppPrivate/');
+		assert.notEqual(
+			status,
+			200,
+			'enabling modelsGateway must not start REST, which would expose an app that ' +
+				'declared no `rest` section of its own'
+		);
+	});
+
+	test('the gateway does not serve itself either, rather than forcing REST', async () => {
+		// The other half of the same property: the gateway declines to start REST for
+		// its own benefit too. resources/models/v1/index.ts warns about exactly this.
+		const status = await statusOrRefused(ctx, '/v1/models');
+		assert.notEqual(status, 200, 'the gateway must not force REST to start for its own resources');
+	});
+});
+
+/**
+ * Control for the suite above.
+ *
+ * Without this, the primary assertions could pass vacuously — a typo'd path or a
+ * fixture that never deployed would also "not be reachable". Here the identical
+ * fixture and URL are exercised with a root `rest` section present, which is the
+ * state the removed force-start effectively created. The table becomes reachable,
+ * so `notEqual(status, 200)` above is a real constraint and not an artifact.
+ *
+ * This also documents current Harper behavior: once REST is running it serves the
+ * shared `Resources` registry, so an `@export`ed table is reachable even though
+ * this app declares no `rest` of its own. Whether that ought to be per-app scoped
+ * is a separate question (#1931) — this test only pins that enabling the gateway
+ * is not what causes it.
+ */
+suite('control: the same table IS reachable once REST is configured', (ctx: ContextWithHarper) => {
+	before(async () => {
+		await setupHarperWithFixture(ctx, FIXTURE_PATH, {
+			config: {
+				// `webSocket` is a leaf value because a plain empty object is dropped by
+				// flattenObject() in harperConfigEnvVars.ts.
+				rest: { webSocket: true },
+				modelsGateway: { enabled: true },
+				models: {
+					generative: { default: { backend: ECHO_BACKEND_PATH } },
+					embedding: { default: { backend: ECHO_BACKEND_PATH } },
+				},
+			},
+			env: {},
+		});
+	});
+
+	after(async () => {
+		await teardownHarper(ctx);
+	});
+
+	test('proves the probe URL is live when REST is running', async () => {
+		const status = await statusOrRefused(ctx, '/MixedAppPrivate/');
+		assert.equal(status, 200, 'if this stops returning 200 the regression guard above has gone vacuous');
+	});
+});
+
+/**
+ * Route reservation (#1616 review): the gateway's fixed routes are non-table
+ * Resources, and `Resources.set` compares databaseName/tableName (both undefined)
+ * for conflict identity — so before `reservedPath`, an app registering its own
+ * Resource at `v1/models` silently replaced the gateway endpoint and its
+ * super_user gate, with no startup error. Now it must be a loud conflict: the
+ * path serves an ErrorResource (500), never the app's payload, and the rest of
+ * the gateway keeps working.
+ */
+suite('an app claiming a reserved /v1 route is a loud conflict, not a silent takeover', (ctx: ContextWithHarper) => {
+	before(async () => {
+		await setupHarperWithFixture(ctx, resolvePath(__dirname, 'v1-gateway-collision-app'), {
+			config: {
+				rest: { webSocket: true },
+				modelsGateway: { enabled: true },
+				models: {
+					generative: { default: { backend: ECHO_BACKEND_PATH } },
+					embedding: { default: { backend: ECHO_BACKEND_PATH } },
+				},
+			},
+			env: {},
+		});
+	});
+
+	after(async () => {
+		await teardownHarper(ctx);
+	});
+
+	test('the contested path never serves the imposter payload', async () => {
+		const res = await fetch(`${ctx.harper.httpURL}/v1/models`, {
+			headers: { Authorization: authHeader(ctx) },
+			signal: AbortSignal.timeout(5_000),
+		});
+		const text = await res.text();
+		assert.ok(
+			!text.includes('imposter'),
+			`app resource must not take over a reserved route, got: ${text.slice(0, 200)}`
+		);
+		// Loud conflict: the reserved path serves the conflict ErrorResource (500),
+		// which is the same behavior table-path conflicts have always had.
+		assert.equal(res.status, 500, `expected the conflict ErrorResource, got ${res.status}: ${text.slice(0, 200)}`);
+	});
+
+	test('the rest of the gateway still serves (conflict is contained to the contested path)', async () => {
+		const res = await fetch(`${ctx.harper.httpURL}/v1/embeddings`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': authHeader(ctx) },
+			body: JSON.stringify({ model: 'default', input: 'hello' }),
+			signal: AbortSignal.timeout(5_000),
+		});
+		assert.equal(res.status, 200, 'uncontested gateway routes must be unaffected');
+	});
+
+	test('the app itself still loads and serves its legitimately-named resource', async () => {
+		const res = await fetch(`${ctx.harper.httpURL}/Legit/`, {
+			headers: { Authorization: authHeader(ctx) },
+			signal: AbortSignal.timeout(5_000),
+		});
+		assert.equal(res.status, 200, 'the collision must not break the rest of the app');
+	});
+});

integrationTests/server/v1-gateway-mixed-app/config.yaml

@@ -0,0 +1,7 @@
+# Deliberately declares NO `rest` section.
+#
+# This app exports a table, so it has a REST-exportable entry in the shared
+# Resources registry — but by omitting `rest` it opts out of being served over
+# REST. Enabling the /v1 gateway must not change that.
+graphqlSchema:
+  files: '*.graphql'

integrationTests/server/v1-gateway-mixed-app/schema.graphql

@@ -0,0 +1,9 @@
+# An @export table in an app that does not declare `rest`.
+#
+# @export puts it in the shared Resources registry; the missing `rest` section is
+# what should keep it off the wire. If enabling modelsGateway ever starts REST on
+# this app's behalf, this table becomes reachable and the regression test fails.
+type MixedAppPrivate @table @export {
+	id: ID @primaryKey
+	value: String
+}