@chipmobilesdk/rn-ai 0.2.1 → 0.4.0

package/src/config/behaviorConfig.ts

@@ -1,3 +1,5 @@
+import { createListenerSet, createSingleFlight, type KeyValuePort } from '@chipmobilesdk/rn-core';
+
 import { AiError } from '../diagnostics/errors';
 import { DEFAULT_AI_TIMEOUTS, withTimeout } from '../transport/timeouts';
 
@@ -33,18 +35,84 @@ export class MemoryConfigCache implements AiConfigCache {
 	}
 }
 
+/**
+ * An `AiConfigCache` over rn-core's synchronous `KeyValuePort` (AI-10).
+ *
+ * Without a durable cache every launch waits for the network before the first
+ * chat, which is exactly what the cache-first design exists to avoid. Open the
+ * port the way the app opens its other durable state, for example
+ * `openDurable(() => createMMKV({ id: 'app' }))`.
+ */
+export function configCacheFromKeyValue(port: KeyValuePort): AiConfigCache {
+	return {
+		async get(key) {
+			return port.getString(key) ?? null;
+		},
+		async set(key, value) {
+			port.set(key, value);
+		},
+	};
+}
+
 export type BehaviorState = 'unloaded' | 'ready-network' | 'ready-cache' | 'unavailable';
 
+/** The newest document layout this release understands. */
+export const SUPPORTED_SCHEMA_VERSION = 1;
+
+/** Bounds on the remote-configured recovery, so a bad document cannot stall a chat. */
+const MAX_SILENT_RETRIES = 5;
+const MIN_REFRESH_TTL_SECONDS = 30;
+const DEFAULT_REFRESH_TTL_SECONDS = 21_600;
+
 const numbers = (value: unknown): number[] | undefined =>
 	Array.isArray(value) ? value.filter((n): n is number => Number.isFinite(n)) : undefined;
 
-/** Parse + validate; unknown fields ignored (forward compatibility). */
-export function parseBehaviorConfig(json: string): AppBehaviorConfig {
+const positiveInt = (value: unknown, fallback: number): number =>
+	typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+
+function invalid(reason: string): never {
+	throw new AiError('config-unavailable', `behavior config ${reason}`);
+}
+
+/** https, or http on a development machine: a bearer token travels to this host. */
+export function isTrustedUrl(url: string): boolean {
+	if (/^https:\/\//i.test(url)) {
+		return true;
+	}
+	return /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i.test(url);
+}
+
+function hostOf(url: string): string {
+	return url
+		.replace(/^[a-z]+:\/\//i, '')
+		.split(/[/:?#]/)[0]!
+		.toLowerCase();
+}
+
+export interface ParseBehaviorConfigOptions {
+	/** The app this document must be for; a document for another app is refused. */
+	expectedAppId?: string;
+	/** Hosts `api.baseUrl` may name. Any host is accepted when omitted. */
+	allowedHosts?: readonly string[];
+}
+
+/**
+ * Parse + validate; unknown fields ignored (forward compatibility).
+ *
+ * Every field this package acts on is checked here, because the document is
+ * remote and the alternative is a TypeError inside an XHR callback, a revalidate
+ * on every single request, or a bearer token sent to a host nobody vetted
+ * (AI-06, AI-07).
+ */
+export function parseBehaviorConfig(
+	json: string,
+	options: ParseBehaviorConfigOptions = {},
+): AppBehaviorConfig {
 	let raw: Record<string, unknown>;
 	try {
 		raw = JSON.parse(json) as Record<string, unknown>;
 	} catch {
-		throw new AiError('config-unavailable', 'behavior config is not valid JSON');
+		invalid('is not valid JSON');
 	}
 	const api = raw.api as Partial<AppBehaviorConfig['api']> | undefined;
 	if (
@@ -52,17 +120,42 @@ export function parseBehaviorConfig(json: string): AppBehaviorConfig {
 		typeof api?.baseUrl !== 'string' ||
 		!Array.isArray(api.scopes)
 	) {
-		throw new AiError('config-unavailable', 'behavior config is missing required fields');
+		invalid('is missing required fields');
+	}
+
+	const schemaVersion = positiveInt(raw.schemaVersion, 1);
+	if (schemaVersion > SUPPORTED_SCHEMA_VERSION) {
+		// A newer layout may mean something different by the same field names.
+		invalid(`declares schema version ${schemaVersion}, newer than ${SUPPORTED_SCHEMA_VERSION}`);
 	}
+	if (options.expectedAppId !== undefined && raw.appId !== options.expectedAppId) {
+		// The cache key and the request path carry the app id; a document for
+		// another app would send this app's traffic somewhere else entirely.
+		invalid(`is for another app (${raw.appId})`);
+	}
+
+	const baseUrl = api.baseUrl.replace(/\/$/, '');
+	if (!isTrustedUrl(baseUrl)) {
+		invalid('names a baseUrl that is not https');
+	}
+	if (options.allowedHosts && !options.allowedHosts.includes(hostOf(baseUrl))) {
+		invalid(`names a baseUrl outside the allowed hosts (${hostOf(baseUrl)})`);
+	}
+
 	const recovery = (raw.recovery ?? {}) as Partial<AppBehaviorConfig['recovery']>;
 	const features = (raw.features ?? {}) as Partial<AppBehaviorConfig['features']>;
 	return {
-		schemaVersion: Number(raw.schemaVersion ?? 1),
+		schemaVersion,
 		appId: raw.appId,
-		configVersion: Number(raw.configVersion ?? 0),
-		refreshTtlSeconds: Number(raw.refreshTtlSeconds ?? 21600),
+		configVersion: positiveInt(raw.configVersion, 0),
+		// A TTL that was NaN made `isFresh` false forever, so every request
+		// revalidated over the network (AI-06).
+		refreshTtlSeconds: Math.max(
+			MIN_REFRESH_TTL_SECONDS,
+			positiveInt(raw.refreshTtlSeconds, DEFAULT_REFRESH_TTL_SECONDS),
+		),
 		api: {
-			baseUrl: api.baseUrl.replace(/\/$/, ''),
+			baseUrl,
 			scopes: api.scopes.filter((s): s is string => typeof s === 'string'),
 			supportsStreaming: api.supportsStreaming !== false,
 		},
@@ -71,9 +164,12 @@ export function parseBehaviorConfig(json: string): AppBehaviorConfig {
 		// throw a TypeError inside the XHR error callback, where nothing caught it.
 		recovery: {
 			reloadOnHttpStatus: numbers(recovery.reloadOnHttpStatus) ?? [404, 410],
-			maxSilentRetries: Number.isFinite(recovery.maxSilentRetries)
-				? Number(recovery.maxSilentRetries)
-				: 1,
+			maxSilentRetries: Math.min(
+				MAX_SILENT_RETRIES,
+				Number.isFinite(recovery.maxSilentRetries)
+					? Math.max(0, Number(recovery.maxSilentRetries))
+					: 1,
+			),
 			retryBackoffMs: numbers(recovery.retryBackoffMs) ?? [500, 2000],
 		},
 		features: { aiEnabled: features.aiEnabled !== false },
@@ -94,6 +190,8 @@ export interface BehaviorConfigDeps {
 	now?: () => number;
 	/** Limit on one config fetch, body included. Defaults to 10 s. */
 	timeoutMs?: number;
+	/** Hosts the document's `api.baseUrl` may name. */
+	allowedHosts?: readonly string[];
 }
 
 /**
@@ -106,64 +204,125 @@ export class BehaviorConfigManager {
 	private fetchFn: typeof fetch;
 	private now: () => number;
 	private current?: { config: AppBehaviorConfig; envelope: CacheEnvelope };
-	state: BehaviorState = 'unloaded';
+	/**
+	 * One cache read and one network fetch at a time (AI-08): a cold start makes a
+	 * chat and a quota call together, and each used to fetch the config itself.
+	 */
+	private readonly cacheRead = createSingleFlight<void>();
+	private readonly networkFetch = createSingleFlight<AppBehaviorConfig>();
+	private currentState: BehaviorState = 'unloaded';
+	private readonly stateListeners = createListenerSet<[]>();
+
+	/** Where the config came from, or why there is none. */
+	get state(): BehaviorState {
+		return this.currentState;
+	}
+
+	/** Called whenever `state` changes (AI-09). */
+	subscribe(listener: () => void): () => void {
+		return this.stateListeners.add(listener);
+	}
+
+	private setState(next: BehaviorState): void {
+		if (next === this.currentState) return;
+		this.currentState = next;
+		this.stateListeners.notify();
+	}
 
 	constructor(private deps: BehaviorConfigDeps) {
+		if (!isTrustedUrl(deps.configUrl)) {
+			// The document decides where the tokens go, so where it comes from
+			// matters as much (AI-07).
+			throw new AiError('config-unavailable', 'configUrl must be https');
+		}
 		this.cacheKey = `rn-ai:config:${deps.appId}`;
 		this.cache = deps.cache ?? new MemoryConfigCache();
 		this.fetchFn = deps.fetchFn ?? fetch;
 		this.now = deps.now ?? Date.now;
 	}
 
+	private parse(json: string): AppBehaviorConfig {
+		return parseBehaviorConfig(json, {
+			expectedAppId: this.deps.appId,
+			...(this.deps.allowedHosts ? { allowedHosts: this.deps.allowedHosts } : {}),
+		});
+	}
+
 	private isFresh(envelope: CacheEnvelope, config: AppBehaviorConfig): boolean {
 		return this.now() - envelope.fetchedAt < config.refreshTtlSeconds * 1000;
 	}
 
-	private async loadFromCache(): Promise<void> {
+	private loadFromCache(): Promise<void> {
+		return this.current ? Promise.resolve() : this.cacheRead.run(() => this.readCache());
+	}
+
+	private async readCache(): Promise<void> {
 		if (this.current) return;
 		const stored = await this.cache.get(this.cacheKey).catch(() => null);
 		if (!stored) return;
 		try {
 			const envelope = JSON.parse(stored) as CacheEnvelope;
-			this.current = { config: parseBehaviorConfig(envelope.configJson), envelope };
-			this.state = 'ready-cache';
+			this.current = { config: this.parse(envelope.configJson), envelope };
+			this.setState('ready-cache');
 		} catch {
 			// corrupted cache entries are ignored, not fatal
 		}
 	}
 
-	private async fetchNetwork(): Promise<AppBehaviorConfig | undefined> {
+	private fetchNetwork(): Promise<AppBehaviorConfig> {
+		return this.networkFetch.run(() => this.fetchFromNetwork());
+	}
+
+	/** One attempt; `conditional` sends the stored ETag when there is one. */
+	private async fetchOnce(
+		conditional: boolean,
+	): Promise<{ status: number; text: string; etag?: string }> {
 		const headers: Record<string, string> = {};
-		if (this.current?.envelope.etag) {
-			headers['If-None-Match'] = this.current.envelope.etag;
+		const etag = this.current?.envelope.etag;
+		if (conditional && etag) {
+			headers['If-None-Match'] = etag;
 		}
 		// Bounded: with no cache, a hung fetch used to block every chat and quota call.
-		const { response, configJson } = await withTimeout(
+		return withTimeout(
 			this.deps.timeoutMs ?? DEFAULT_AI_TIMEOUTS.configMs,
 			async signal => {
-				const res = await this.fetchFn(this.deps.configUrl, { headers, signal });
-				return { response: res, configJson: res.ok && res.status !== 304 ? await res.text() : '' };
+				const response = await this.fetchFn(this.deps.configUrl, { headers, signal });
+				return {
+					status: response.status,
+					text: response.ok && response.status !== 304 ? await response.text() : '',
+					etag: response.headers.get('etag') ?? undefined,
+				};
 			},
 			() => new AiError('config-unavailable', 'config fetch timed out'),
 		);
-		if (response.status === 304 && this.current) {
-			this.current.envelope.fetchedAt = this.now();
-			await this.persist(this.current.envelope);
-			this.state = 'ready-network';
-			return this.current.config;
+	}
+
+	private async fetchFromNetwork(): Promise<AppBehaviorConfig> {
+		let result = await this.fetchOnce(true);
+		if (result.status === 304) {
+			if (this.current) {
+				this.current.envelope.fetchedAt = this.now();
+				await this.persist(this.current.envelope);
+				this.setState('ready-network');
+				return this.current.config;
+			}
+			// Not-modified against a cache that is no longer there (it was cleared,
+			// or it failed to parse). Asking again without the ETag is the answer;
+			// reporting `config fetch failed: 304` was not (AI-17).
+			result = await this.fetchOnce(false);
 		}
-		if (!response.ok) {
-			throw new AiError('config-unavailable', `config fetch failed: ${response.status}`);
+		if (result.status < 200 || result.status >= 300) {
+			throw new AiError('config-unavailable', `config fetch failed: ${result.status}`);
 		}
-		const config = parseBehaviorConfig(configJson);
+		const config = this.parse(result.text);
 		const envelope: CacheEnvelope = {
-			configJson,
-			etag: response.headers.get('etag') ?? undefined,
+			configJson: result.text,
+			etag: result.etag,
 			fetchedAt: this.now(),
 		};
 		this.current = { config, envelope };
 		await this.persist(envelope);
-		this.state = 'ready-network';
+		this.setState('ready-network');
 		return config;
 	}
 
@@ -185,16 +344,11 @@ export class BehaviorConfigManager {
 			return this.current.config;
 		}
 		try {
-			const fetched = await this.fetchNetwork();
-			if (fetched) return fetched;
+			return await this.fetchNetwork();
 		} catch (e) {
 			if (this.current) return this.current.config; // stale beats broken
-			this.state = 'unavailable';
+			this.setState('unavailable');
 			throw e instanceof AiError ? e : new AiError('config-unavailable', String(e));
 		}
-		// fetchNetwork only returns undefined when a 304 raced an empty cache.
-		if (this.current) return (this.current as { config: AppBehaviorConfig }).config;
-		this.state = 'unavailable';
-		throw new AiError('config-unavailable', 'no configuration available');
 	}
 }

package/src/contract/gateway.ts

@@ -0,0 +1,91 @@
+/**
+ * The gateway↔client contract: error codes, quota headers, stream events.
+ *
+ * One definition, imported by both sides (GW-13). The gateway's own codes and
+ * the client's map of them were two hand-maintained lists, and they had already
+ * drifted: `BAD_REQUEST`, `ENDPOINT_RETIRED` and `INTERNAL` existed on the
+ * server and were unknown to the client, which fell back to a guess from the
+ * status. Adding a code now fails to compile on whichever side has not handled
+ * it.
+ *
+ * Types and plain constants only, and no import of anything: the gateway runs
+ * on Node and imports this file for its types alone.
+ */
+
+/** Every error the gateway answers with (`error.code` in the body). */
+export type GatewayErrorCode =
+	| 'BAD_REQUEST'
+	| 'AUTH_INVALID'
+	| 'NOT_ENTITLED'
+	| 'USER_BLOCKED'
+	| 'APP_UNKNOWN'
+	| 'ENDPOINT_RETIRED'
+	| 'PAYLOAD_TOO_LARGE'
+	| 'MODALITY_NOT_ALLOWED'
+	| 'RATE_LIMITED'
+	| 'UPSTREAM_BUSY'
+	| 'UPSTREAM_ERROR'
+	| 'INTERNAL';
+
+/** The HTTP status each code is sent with. */
+export const GATEWAY_ERROR_STATUS: Readonly<Record<GatewayErrorCode, number>> = {
+	BAD_REQUEST: 400,
+	AUTH_INVALID: 401,
+	NOT_ENTITLED: 403,
+	USER_BLOCKED: 403,
+	APP_UNKNOWN: 404,
+	ENDPOINT_RETIRED: 410,
+	PAYLOAD_TOO_LARGE: 413,
+	MODALITY_NOT_ALLOWED: 415,
+	RATE_LIMITED: 429,
+	UPSTREAM_BUSY: 429,
+	UPSTREAM_ERROR: 500,
+	INTERNAL: 500,
+};
+
+/** The error body. `message` is safe to log; it never carries upstream detail. */
+export interface GatewayErrorBody {
+	error: {
+		code: GatewayErrorCode;
+		message: string;
+		retryAfterSeconds?: number;
+	};
+}
+
+/** The quota headers, by name. A rename here breaks both sides' compile. */
+export const QUOTA_HEADERS = {
+	minuteRemaining: 'X-Quota-Minute-Remaining',
+	dayRemaining: 'X-Quota-Day-Remaining',
+	dayTokensRemaining: 'X-Quota-Day-Tokens-Remaining',
+} as const;
+
+/** The names field by field, so a side declaring its own literals is checked exactly. */
+export type QuotaHeaderNames = typeof QUOTA_HEADERS;
+export type QuotaHeaderName = QuotaHeaderNames[keyof QuotaHeaderNames];
+
+/** What is left of an app's allowance, as the gateway reports it. */
+export interface GatewayQuota {
+	minuteRemaining: number;
+	dayRemaining: number;
+	dayTokensRemaining: number;
+}
+
+/** What one answer cost. */
+export interface GatewayUsage {
+	promptTokens: number;
+	completionTokens: number;
+	totalTokens: number;
+}
+
+/** The `data:` payloads of a chat stream, before the `[DONE]` sentinel. */
+export type GatewayStreamEvent =
+	| { type: 'delta'; text: string }
+	| { type: 'done'; usage: GatewayUsage; quota?: GatewayQuota }
+	| { type: 'error'; code: GatewayErrorCode };
+
+/** The last `data:` line of a stream that completed. */
+export const SSE_DONE_SENTINEL = '[DONE]';
+export type SseDoneSentinel = typeof SSE_DONE_SENTINEL;
+
+/** The `Retry-After` header, which a 429 always carries. */
+export const RETRY_AFTER_HEADER = 'Retry-After';