@harperfast/harper 5.2.0 → 5.2.1

package/resources/models/v1/chatCompletions.ts

@@ -0,0 +1,128 @@
+/**
+ * `POST /v1/chat/completions` — OpenAI-compatible chat endpoint (#631).
+ *
+ * SSE serving-path note: the OpenAI SDK sends `Accept: application/json` for
+ * ALL requests including streaming ones (`client.ts:1160` in the SDK source).
+ * Harper's REST layer dispatches `Accept: text/event-stream` as CONNECT, and
+ * everything else as the HTTP method. So `stream: true` from an OpenAI SDK
+ * client reaches this `post()` handler, NOT `connect()`. We detect the `stream`
+ * flag in the body and return `{ body: Readable }` which REST.ts bypasses
+ * serialisation on (REST.ts:165-193) — exactly like any SSE resource response,
+ * but initiated from `post()` rather than `connect()`.
+ */
+
+import type { Readable } from 'node:stream';
+import { contentTypes } from '../../../server/serverHelpers/contentTypes.ts';
+import { Resource } from '../../Resource.ts';
+import { models } from '../Models.ts';
+import { openaiStream } from '../openaiStream.ts';
+import { toOpenAIError, badRequest, authorizeV1Request } from './errors.ts';
+import {
+	translateMessages,
+	translateTools,
+	toGenerateInput,
+	toGenerateOpts,
+	toChatCompletion,
+	validateChatRequest,
+} from './translation.ts';
+import type { OAIChatRequest } from './translation.ts';
+
+type SseHandler = { serializeStream: (iterable: AsyncIterable<unknown>) => Readable };
+const sseHandler = contentTypes.get('text/event-stream') as SseHandler;
+
+// @ts-ignore — Resource base class is not typed for static dispatch; pattern mirrors login.ts
+export class V1ChatCompletions extends Resource {
+	// Reserve this fixed route: a later app registration at the same path becomes a
+	// loud conflict (ErrorResource) instead of silently replacing the gateway and its
+	// super_user gate. See Resources.set.
+	static reservedPath = true;
+
+	static async post(_target: unknown, body: unknown, request: unknown) {
+		const authError = authorizeV1Request(request as any);
+		if (authError) return authError;
+
+		// REST.ts passes `request.data` directly, which is the (unawaited) streaming
+		// JSON deserializer's Promise — awaiting here is a no-op for callers (e.g.
+		// unit tests) that already pass a plain object. A malformed JSON body rejects
+		// this promise, which is a client error, not a 500.
+		try {
+			body = await body;
+		} catch (err) {
+			return badRequest(`Could not parse request body: ${err instanceof Error ? err.message : 'invalid JSON'}`);
+		}
+		if (!body || typeof body !== 'object' || Array.isArray(body)) {
+			return badRequest('Request body must be a JSON object');
+		}
+		const req = body as OAIChatRequest;
+
+		// Validate the nested wire shapes before mapping: the mappers assume well-formed
+		// input, so an unvalidated `messages:[null]` / `tools:[{}]` would throw a TypeError
+		// and surface as an RFC 9457 500 instead of an OpenAI 400.
+		const invalid = validateChatRequest(req);
+		if (invalid) return badRequest(invalid);
+
+		const model = typeof req.model === 'string' ? req.model : 'default';
+
+		try {
+			const messages = translateMessages(req.messages);
+			// tool_choice: 'none' means "do not call tools" — the only faithful way to honor
+			// that against a returns-tool-calls backend is to not offer the tools at all.
+			// 'required'/named selection are rejected in validateChatRequest.
+			const tools = req.tool_choice === 'none' || !req.tools?.length ? undefined : translateTools(req.tools);
+			const input = toGenerateInput(messages, tools);
+			const opts = toGenerateOpts(req);
+			if (req.stream) {
+				const tokenStream = models.generateStream(input, opts);
+				// serializeStream wraps the async iterable in a Node Readable so REST.ts
+				// can return it without re-serialising. The `body` presence on the return
+				// value skips REST.ts's own serialize() call (REST.ts:165-193).
+				// formatError reuses the non-streaming error mapping so a mid-stream backend
+				// failure reaches the client as an OpenAI-shaped SSE error frame.
+				const readable = sseHandler.serializeStream(
+					openaiStream(tokenStream, { model, formatError: (err) => toOpenAIError(err).data.error })
+				);
+				return {
+					status: 200,
+					headers: {
+						'Content-Type': 'text/event-stream',
+						'Cache-Control': 'no-cache',
+						'X-Accel-Buffering': 'no',
+					},
+					body: readable,
+				};
+			}
+
+			const result = await models.generate(input, opts);
+			return toChatCompletion(result, model);
+		} catch (err) {
+			return toOpenAIError(err);
+		}
+	}
+
+	/**
+	 * A client that sends an explicit `Accept: text/event-stream` with its POST is
+	 * dispatched by REST as CONNECT (REST.ts), not POST. The OpenAI SDK happens to send
+	 * `Accept: application/json` even when streaming, but other valid SSE clients do not.
+	 *
+	 * Without this override the request reached `Resource`'s default `connect`, whose
+	 * instance path returns `subscribe()` — an empty `IterableEventQueue` — so the client
+	 * got a 200 SSE response that stayed open forever emitting nothing, rather than an
+	 * error it could act on.
+	 *
+	 * REST passes `null` as the CONNECT body (`resource.connect(target, null, request)`),
+	 * so the parsed body is taken off the request and handed to the same `post()`
+	 * implementation — one code path, identical validation and error shaping.
+	 *
+	 * `connect` is also reachable from the WebSocket handler with a different signature
+	 * (`resourceRequest, incomingMessages, request`), where there is no `request.data`;
+	 * that case is rejected as a client error rather than returning an envelope the WS
+	 * path would fail to iterate.
+	 */
+	static async connect(target: unknown, _data: unknown, request: unknown) {
+		const data = (request as { data?: unknown })?.data;
+		if (data === undefined) {
+			return badRequest('This endpoint requires a JSON request body; WebSocket connections are not supported');
+		}
+		return this.post(target, data, request);
+	}
+}

package/resources/models/v1/embeddings.ts

@@ -0,0 +1,70 @@
+/**
+ * `POST /v1/embeddings` — OpenAI-compatible embedding endpoint (#631).
+ *
+ * Maps OpenAI's `{ model, input }` request body to `scope.models.embed()` and
+ * returns `{ object: 'list', data: [...], model, usage }` per the OpenAI wire spec.
+ */
+
+import { Resource } from '../../Resource.ts';
+import { models } from '../Models.ts';
+import { toOpenAIError, badRequest, authorizeV1Request } from './errors.ts';
+import { toEmbedOpts, toEmbedResponse } from './translation.ts';
+
+// Cap batched input, matching OpenAI's own 2048-item limit. The endpoint is
+// super_user-only and off by default, so this is a sanity bound (avoid an
+// unbounded fan-out to the backend), not a security control.
+const MAX_EMBEDDING_INPUTS = 2048;
+
+// @ts-ignore — Resource base class is not typed for static dispatch; pattern mirrors login.ts
+export class V1Embeddings extends Resource {
+	// Reserve this fixed route: a later app registration at the same path becomes a
+	// loud conflict (ErrorResource) instead of silently replacing the gateway and its
+	// super_user gate. See Resources.set.
+	static reservedPath = true;
+
+	static async post(_target: unknown, body: Record<string, unknown>, request: unknown) {
+		const authError = authorizeV1Request(request as any);
+		if (authError) return authError;
+
+		// REST.ts passes `request.data` directly, which is the (unawaited) streaming
+		// JSON deserializer's Promise — awaiting here is a no-op for callers (e.g.
+		// unit tests) that already pass a plain object. A malformed JSON body rejects
+		// this promise, which is a client error, not a 500 (matches chatCompletions).
+		try {
+			body = await body;
+		} catch (err) {
+			return badRequest(`Could not parse request body: ${err instanceof Error ? err.message : 'invalid JSON'}`);
+		}
+		if (!body || typeof body !== 'object' || Array.isArray(body))
+			return badRequest('Request body must be a JSON object');
+		const raw = body as Record<string, unknown>;
+
+		// Mirrors validateChatRequest: a non-string model would silently invoke the
+		// configured default rather than being rejected.
+		if (raw.model !== undefined && typeof raw.model !== 'string') return badRequest("'model' must be a string");
+
+		const input = raw.input;
+		if (input === undefined || input === null) return badRequest("'input' is required");
+		if (typeof input !== 'string' && !Array.isArray(input)) {
+			return badRequest("'input' must be a string or array of strings");
+		}
+		if (Array.isArray(input) && !input.every((v) => typeof v === 'string')) {
+			return badRequest("'input' array elements must be strings");
+		}
+		if (Array.isArray(input) && input.length > MAX_EMBEDDING_INPUTS) {
+			return badRequest(`'input' array must not exceed ${MAX_EMBEDDING_INPUTS} items`);
+		}
+
+		const model = typeof raw.model === 'string' ? raw.model : 'default';
+		const opts = toEmbedOpts(raw as any);
+
+		try {
+			// embedWithUsage, not embed(): the public facade drops the result-level usage
+			// backends report, and OpenAI clients read real token counts off the response.
+			const { vectors, usage } = await models.embedWithUsage(input as string | string[], opts);
+			return toEmbedResponse(vectors, model, usage);
+		} catch (err) {
+			return toOpenAIError(err);
+		}
+	}
+}

package/resources/models/v1/errors.ts

@@ -0,0 +1,141 @@
+/**
+ * OpenAI error envelope helpers for the `/v1/*` gateway (#631).
+ *
+ * Harper's REST layer serialises uncaught errors as RFC 9457 Problem Details.
+ * Resources that need the OpenAI `{ error: { message, type, code, param } }`
+ * shape must catch errors themselves and call `toOpenAIError()` / `badRequest()`.
+ */
+
+import { ModelBackendNotFoundError } from '../backendRegistry.ts';
+import { ModelCapabilityError } from '../Models.ts';
+import harperLogger from '../../../utility/logging/harper_logger.ts';
+
+type OpenAIErrorType =
+	'invalid_request_error' | 'server_error' | 'authentication_error' | 'permission_error' | 'api_error';
+
+export interface OpenAIErrorBody {
+	message: string;
+	type: OpenAIErrorType;
+	code: string | null;
+	param: string | null;
+}
+
+/** HTTP response payload from a gateway error; resource methods return this directly. */
+export interface OpenAIErrorResponse {
+	status: number;
+	headers: { 'Content-Type': 'application/json' };
+	data: { error: OpenAIErrorBody };
+}
+
+/**
+ * Map any thrown value to an OpenAI error envelope. Uses `statusCode` when
+ * present (Harper's `ClientError` / `ServerError` convention). Falls back to
+ * `500 server_error`. `ModelBackendNotFoundError` maps to `404 model_not_found`.
+ */
+export function toOpenAIError(err: unknown): OpenAIErrorResponse {
+	let status = 500;
+	let type: OpenAIErrorType = 'server_error';
+	let code: string | null = null;
+
+	if (err instanceof ModelBackendNotFoundError) {
+		status = 404;
+		type = 'invalid_request_error';
+		code = 'model_not_found';
+	} else if (err instanceof ModelCapabilityError) {
+		// Caller-driven mismatch (e.g. `tools` or streaming against a backend that
+		// doesn't support it): the request is what's wrong, not the server. It extends
+		// ServerError (statusCode 500), so this must precede the statusCode branch —
+		// falling through would report a generic sanitized 500 for a client-actionable
+		// condition. The message is safe to pass through: it names only the backend and
+		// the capability the caller asked for.
+		status = 400;
+		type = 'invalid_request_error';
+		code = 'capability_unsupported';
+	} else if (err instanceof Error && typeof (err as any).statusCode === 'number') {
+		status = (err as any).statusCode;
+		if (status === 401) {
+			type = 'authentication_error';
+		} else if (status === 403) {
+			// OpenAI semantics: 401 = bad/missing credentials, 403 = valid credentials
+			// lacking permission (matches authorizeV1Request's own 403 envelope).
+			type = 'permission_error';
+		} else if (status < 500) {
+			type = 'invalid_request_error';
+		} else {
+			type = 'server_error';
+		}
+	}
+
+	// 5xx messages stay generic: internal error strings (backend stack details, file
+	// paths) don't belong in a wire response. The real error goes to the log. 4xx
+	// messages are client-actionable and pass through.
+	let message: string;
+	if (status >= 500) {
+		harperLogger.error('v1 gateway error', err);
+		message = 'Internal server error';
+	} else {
+		message = err instanceof Error ? err.message : 'Bad request';
+	}
+
+	return {
+		status,
+		headers: { 'Content-Type': 'application/json' },
+		data: { error: { message, type, code, param: null } },
+	};
+}
+
+/** Convenience for early request-body validation failures. */
+export function badRequest(message: string): OpenAIErrorResponse {
+	return {
+		status: 400,
+		headers: { 'Content-Type': 'application/json' },
+		data: { error: { message, type: 'invalid_request_error', code: null, param: null } },
+	};
+}
+
+/**
+ * Gate for the `/v1/*` handlers, since overriding the static `get`/`post` methods
+ * bypasses Resource's `transactional()` wrapper and its default `allowRead`/`allowCreate`
+ * checks (Resource.ts:685-733, 426-435) never run for these endpoints.
+ *
+ * Mirrors Resource's default gate (super_user-only) rather than introducing a new
+ * permission — see PR discussion for whether a dedicated `/v1/*` permission should
+ * replace this later.
+ *
+ * Returns an OpenAI-shape error response when access should be denied, or `null`
+ * when the request may proceed.
+ */
+export function authorizeV1Request(request: {
+	user?: { role?: { permission?: { super_user?: boolean } } };
+}): OpenAIErrorResponse | null {
+	const user = request?.user;
+	if (!user) {
+		return {
+			status: 401,
+			headers: { 'Content-Type': 'application/json' },
+			data: {
+				error: {
+					message: 'You must provide valid credentials to access this endpoint.',
+					type: 'authentication_error' as const,
+					code: null,
+					param: null,
+				},
+			},
+		};
+	}
+	if (!user.role?.permission?.super_user) {
+		return {
+			status: 403,
+			headers: { 'Content-Type': 'application/json' },
+			data: {
+				error: {
+					message: 'You do not have permission to access this endpoint.',
+					type: 'permission_error' as const,
+					code: null,
+					param: null,
+				},
+			},
+		};
+	}
+	return null;
+}

package/resources/models/v1/index.ts

@@ -0,0 +1,72 @@
+/**
+ * `/v1/*` OpenAI-compatible gateway (#631).
+ *
+ * Registers three REST resources on the REST port:
+ *   POST /v1/embeddings          → V1Embeddings
+ *   POST /v1/chat/completions    → V1ChatCompletions
+ *   GET  /v1/models              → V1Models
+ *
+ * Off by default, and `defaultConfig.yaml` deliberately ships no `modelsGateway`
+ * block: with the key absent the root loader skips the component before resolving
+ * it, so none of this module graph is imported on an instance that does not use
+ * the gateway. Opt in by adding the block to `harperdb-config.yaml` with
+ * `enabled: true`, or via `set_configuration` (`modelsGateway_enabled`).
+ * `enabled: false` is honored too, for an instance that wants the block present
+ * but inert — that costs the import, which is why it is not the shipped default.
+ *
+ * Example (opt in). `rest` is required: these are REST-served resources and the
+ * gateway deliberately does not force REST to start (see `handleApplication`).
+ * Without it the resources register but every `/v1/*` path 404s.
+ *
+ * ```yaml
+ * rest: true
+ * modelsGateway:
+ *   enabled: true
+ * models:
+ *   generative:
+ *     default:
+ *       backend: ollama
+ *       model: llama3.2
+ * ```
+ *
+ * All three endpoints require `super_user` permission. Anonymous or
+ * insufficient-privilege requests receive a well-formed OpenAI error envelope.
+ */
+
+import type { Scope } from '../../../components/Scope.ts';
+import harperLogger from '../../../utility/logging/harper_logger.ts';
+import { getConfigObj } from '../../../config/configUtils.ts';
+import { V1Embeddings } from './embeddings.ts';
+import { V1ChatCompletions } from './chatCompletions.ts';
+import { V1Models } from './models.ts';
+
+export function handleApplication(scope: Scope): void {
+	if (!scope.options.get(['enabled'])) return;
+	// These resources are served by REST's middleware chain, so the instance must also
+	// have a `rest`/`REST` config section — the gateway deliberately does NOT force REST
+	// to start. Doing so requires reaching into REST's module state before application
+	// configs have loaded, which silently discards an app's own `rest` options (webSocket,
+	// urlPath/host, middleware ordering). Core has no supported way yet for a component to
+	// declare "I serve REST resources"; that gap is tracked separately.
+	//
+	// Warn rather than fail: an app loaded later may still declare `rest`, so absence here
+	// is not conclusive. But defaultConfig ships no `rest` section, so enabling the gateway
+	// alone yields three registered resources and a 404 on every /v1 path — worth a line in
+	// the log instead of silence.
+	const rootConfig = getConfigObj() as Record<string, unknown> | undefined;
+	if (rootConfig && !rootConfig.rest && !rootConfig.REST) {
+		harperLogger.warn(
+			'modelsGateway is enabled but no `rest` section is configured; /v1/* endpoints are only served when REST is active'
+		);
+	}
+	// Explicit protocol visibility: these are REST-only wire-protocol endpoints. Without a
+	// policy, the shared registry matches them for every protocol lookup — WS dispatch could
+	// reach V1ChatCompletions.connect() and then fail iterating its non-iterable badRequest
+	// envelope, and they would surface through MQTT/GraphQL/MCP enumeration too. `sse` stays
+	// enabled for chat only: an explicit `Accept: text/event-stream` POST is dispatched via
+	// the sse lookup (REST.ts) and is a supported streaming client shape (see connect()).
+	const restOnly = { rest: true, sse: false, ws: false, mqtt: false, graphql: false, mcp: false };
+	scope.resources.set('v1/models', V1Models, restOnly);
+	scope.resources.set('v1/embeddings', V1Embeddings, restOnly);
+	scope.resources.set('v1/chat/completions', V1ChatCompletions, { ...restOnly, sse: true });
+}

package/resources/models/v1/models.ts

@@ -0,0 +1,53 @@
+/**
+ * `GET /v1/models` — OpenAI-compatible model list endpoint (#631).
+ *
+ * Enumerates all registered embedding and generative backends from the
+ * process-wide `backendRegistry`. The response mirrors the OpenAI shape:
+ * `{ object: 'list', data: [{ id, object: 'model', created, owned_by }] }`.
+ *
+ * `logicalName` (not `backend.name`) is the `id` — it's what callers pass as
+ * `model` in subsequent requests.
+ */
+
+import { Resource } from '../../Resource.ts';
+import { listBackends } from '../backendRegistry.ts';
+import { authorizeV1Request, type OpenAIErrorResponse } from './errors.ts';
+
+export interface OAIModelEntry {
+	id: string;
+	object: 'model';
+	created: number;
+	owned_by: string;
+}
+
+export interface OAIModelList {
+	object: 'list';
+	data: OAIModelEntry[];
+}
+
+// @ts-ignore — Resource base class is not typed for static dispatch; pattern mirrors login.ts
+export class V1Models extends Resource {
+	// Reserve this fixed route: a later app registration at the same path becomes a
+	// loud conflict (ErrorResource) instead of silently replacing the gateway and its
+	// super_user gate. See Resources.set.
+	static reservedPath = true;
+
+	static get(_target: unknown, request: unknown): OAIModelList | OpenAIErrorResponse {
+		const authError = authorizeV1Request(request as any);
+		if (authError) return authError;
+
+		const created = Math.floor(Date.now() / 1000);
+		// OpenAI model ids are unique; a logical name registered for both generative and
+		// embedding (e.g. `default` in each section) is one model id to callers.
+		const ids = new Set<string>();
+		const data: OAIModelEntry[] = [];
+		for (const kind of ['generative', 'embedding'] as const) {
+			for (const { logicalName } of listBackends(kind)) {
+				if (ids.has(logicalName)) continue;
+				ids.add(logicalName);
+				data.push({ id: logicalName, object: 'model', created, owned_by: 'harper' });
+			}
+		}
+		return { object: 'list', data };
+	}
+}