@octanejs/app-core 0.0.50 → 0.0.51

package/src/server/production.js

@@ -25,6 +25,9 @@
 import { createRouter } from './router.js';
 import { createContext, runMiddlewareChain } from './middleware.js';
 import { handleRpcRequest } from './rpc.js';
+import { setRequestContextSource } from './request-context.js';
+import { createServerCallHost } from './server-calls.js';
+import { runServerRequest } from './signal-owners.js';
 import { rpcIdCollision } from './rpc-registry.js';
 import { handleServerRoute } from './server-route.js';
 import { composeHtmlStream } from './html-stream.js';
@@ -32,6 +35,7 @@ import {
 	applyHydrationNonce,
 	getContextNonce,
 	nonceAttribute,
+	prepareStreamingHydrationTemplate,
 	splitSsrTemplate,
 	validateSsrTemplate,
 } from './html-template.js';
@@ -69,7 +73,7 @@ const FETCH_COORDINATOR_KEY = Symbol.for('octane.app-core.fetch-coordinator');
 
 /**
  * @typedef {Object} FetchCoordinator
- * @property {import('@ripple-ts/adapter/rpc').AsyncContext<{ origin?: string, platform?: unknown }>} asyncContext
+ * @property {import('@octanejs/app-core').RpcRequestOptions['asyncContext']} asyncContext
  * @property {((request: Request, platform?: unknown) => Promise<Response>) | null} handler
  */
 
@@ -138,9 +142,16 @@ function buildRpcDescriptors(rpcModules, hashFn) {
  * the body-marker contract.
  *
  * @param {string} html
+ * @param {boolean} [earlyHydration]
  * @returns {(headContent: string) => string[]}
  */
-function prepareSsrTemplate(html) {
+function prepareSsrTemplate(html, earlyHydration = false) {
+	let afterShell = '';
+	if (earlyHydration) {
+		const prepared = prepareStreamingHydrationTemplate(html);
+		html = prepared.html;
+		afterShell = prepared.afterShell;
+	}
 	const [prefix, suffix] = splitSsrTemplate(html);
 	const prefixHeadAt = prefix.indexOf(HEAD_MARKER);
 	const headInPrefix = prefixHeadAt !== -1;
@@ -153,9 +164,9 @@ function prepareSsrTemplate(html) {
 		const nextPrefix = headInPrefix ? beforeHead + headContent + afterHead : prefix;
 		const nextSuffix = headInPrefix ? suffix : beforeHead + headContent + afterHead;
 		if (headContent.includes(BODY_MARKER) || BODY_CLOSE_TAG.test(headContent)) {
-			return splitSsrTemplate(nextPrefix + BODY_MARKER + nextSuffix);
+			return [...splitSsrTemplate(nextPrefix + BODY_MARKER + nextSuffix), afterShell];
 		}
-		return [nextPrefix, nextSuffix];
+		return [nextPrefix, nextSuffix, afterShell];
 	};
 }
 
@@ -197,6 +208,83 @@ function prepareRenderRoutes(routes) {
 	return prepared;
 }
 
+/**
+ * Freeze the client-build lookup behind the renderer's narrow per-boundary
+ * resolver. Request renders can then join immutable asset identity with their
+ * own encoded captures without consulting global mutable state.
+ *
+ * @param {ServerManifest['independentHydration']} manifest
+ * @returns {import('octane/server').RenderOptions['independentHydration'] | undefined}
+ */
+function prepareIndependentHydration(manifest) {
+	if (manifest == null) return undefined;
+	if (
+		manifest.version !== 1 ||
+		typeof manifest.buildId !== 'string' ||
+		manifest.buildId.length === 0 ||
+		manifest.widgets === null ||
+		typeof manifest.widgets !== 'object' ||
+		Array.isArray(manifest.widgets)
+	) {
+		throw new TypeError('Invalid independent Hydrate build manifest.');
+	}
+	return Object.freeze({
+		buildId: manifest.buildId,
+		resolve(boundaryId) {
+			const entry = manifest.widgets[boundaryId];
+			if (
+				entry === null ||
+				typeof entry !== 'object' ||
+				entry.version !== 1 ||
+				entry.boundaryId !== boundaryId ||
+				typeof entry.moduleId !== 'string' ||
+				!Array.isArray(entry.styles) ||
+				!entry.styles.every((style) => typeof style === 'string') ||
+				entry.parentDependencies !== false
+			) {
+				return undefined;
+			}
+			return { moduleId: entry.moduleId, styles: entry.styles };
+		},
+	});
+}
+
+/**
+ * Snapshot completed build authority once per handler, never from request data.
+ * Legacy custom handlers without a client build retain their existing path.
+ * @param {ServerManifest} manifest
+ * @returns {ServerManifest['clientBuild'] | undefined}
+ */
+function prepareClientBuild(manifest) {
+	const build = manifest.clientBuild;
+	if (build == null) return undefined;
+	if (
+		build.version !== 1 ||
+		typeof build.buildId !== 'string' ||
+		build.buildId.length === 0 ||
+		(build.mode !== 'production' && build.mode !== 'development') ||
+		typeof build.capabilities?.independentHydration !== 'boolean'
+	) {
+		throw new TypeError('Invalid completed client build metadata.');
+	}
+	if (
+		(manifest.independentHydration != null &&
+			manifest.independentHydration.buildId !== build.buildId) ||
+		(build.capabilities.independentHydration && manifest.independentHydration == null) ||
+		(!build.capabilities.independentHydration &&
+			manifest.independentHydration != null &&
+			Object.keys(manifest.independentHydration.widgets).length !== 0)
+	) {
+		throw new Error('Independent Hydrate metadata does not match the completed client build.');
+	}
+	return Object.freeze({
+		version: 1,
+		buildId: build.buildId,
+		mode: build.mode,
+		capabilities: Object.freeze({ independentHydration: build.capabilities.independentHydration }),
+	});
+}
+
 /**
  * @param {ServerManifest} manifest
  * @param {RenderRoute} route
@@ -255,12 +343,17 @@ export function createHandler(manifest, deps) {
 	const trustProxy = manifest.trustProxy ?? false;
 	const rpcPolicy = manifest.rpc;
 	const runtime = manifest.runtime;
+	const independentHydration = prepareIndependentHydration(manifest.independentHydration);
+	const clientBuild = prepareClientBuild(manifest);
 	validateSsrTemplate(htmlTemplate);
 	// Also pin the built-template contract up front. The marker is emitted by
 	// the integration's HTML transform and survives source hashing. Prepare the
 	// normalized no-nonce template once: this is the common request path, and its
 	// static fragments are identical for every request handled by this manifest.
-	const splitHydrationTemplate = prepareSsrTemplate(applyHydrationNonce(htmlTemplate, null));
+	const normalizedTemplate = applyHydrationNonce(htmlTemplate, null);
+	const splitHydrationTemplate = prepareSsrTemplate(normalizedTemplate);
+	/** @type {ReturnType<typeof prepareSsrTemplate> | undefined} */
+	let splitEarlyHydrationTemplate;
 
 	// RPC lookup for statically imported `module server` functions
 	// (compiler hash → server function).
@@ -300,6 +393,10 @@ export function createHandler(manifest, deps) {
 					return rpcDescriptors?.get(hash) ?? null;
 				},
 				executeServerFunction,
+				streamServerFunction: deps.streamServerFunction,
+				batchServerFunctions: deps.batchServerFunctions,
+				signalOwners: deps.signalOwners,
+				resultLimits: rpcPolicy?.resultLimits,
 				asyncContext,
 				trustProxy,
 				middlewares: globalMiddlewares,
@@ -319,22 +416,44 @@ export function createHandler(manifest, deps) {
 		}
 
 		const context = createContext(request, match.params, platform);
-
-		try {
-			if (match.route.type === 'render') {
-				return await runMiddlewareChain(
-					context,
-					globalMiddlewares,
-					match.route.before || [],
-					async () => renderRoute(/** @type {RenderRoute} */ (match.route), context),
-					[],
-				);
+		if (clientBuild != null) Object.defineProperty(context, 'clientBuild', { value: clientBuild });
+		if (manifest.clientAssets != null)
+			Object.defineProperty(context, 'clientAssets', { value: manifest.clientAssets });
+		const run = async () => {
+			try {
+				if (match.route.type === 'render') {
+					return await runMiddlewareChain(
+						context,
+						globalMiddlewares,
+						match.route.before || [],
+						async () => renderRoute(/** @type {RenderRoute} */ (match.route), context),
+						[],
+					);
+				}
+				return await handleServerRoute(match.route, context, globalMiddlewares);
+			} catch (error) {
+				console.error('[octane] Request error:', error);
+				return new Response('Internal Server Error', { status: 500 });
 			}
-			return await handleServerRoute(match.route, context, globalMiddlewares);
-		} catch (error) {
-			console.error('[octane] Request error:', error);
-			return new Response('Internal Server Error', { status: 500 });
-		}
+		};
+		if (!asyncContext) return run();
+		setRequestContextSource(asyncContext);
+		const origin = url.origin;
+		return runServerRequest(
+			asyncContext,
+			{
+				origin,
+				platform,
+				context,
+				serverCallHost: createServerCallHost(context, {
+					asyncContext,
+					middlewares: globalMiddlewares,
+					origin,
+				}),
+			},
+			deps.signalOwners,
+			run,
+		);
 	};
 
 	if (fetchCoordinator) fetchCoordinator.handler = handler;
@@ -388,6 +507,13 @@ export function createHandler(manifest, deps) {
 
 		// The hydration payload — SAME keys, SAME order as dev render-route.js, so
 		// the data script is byte-identical between dev and production.
+		const streamedSignals =
+			clientBuild == null
+				? undefined
+				: {
+						buildId: clientBuild.buildId,
+						documentId: crypto.randomUUID(),
+					};
 		const routeData = JSON.stringify({
 			entry: entryPath,
 			exportName: exportName ?? null,
@@ -397,6 +523,8 @@ export function createHandler(manifest, deps) {
 			url: requestUrl,
 			preHydrate: manifest.preHydrate ?? null,
 			rootBoundary: manifest.rootBoundaryEntries ?? { pending: null, catch: null },
+			clientBuild,
+			streamedSignals,
 		});
 		const dataScript = `<script id="__octane_data" type="application/json"${nonceAttribute(nonce)}>${escapeScript(routeData)}</script>`;
 
@@ -427,12 +555,14 @@ export function createHandler(manifest, deps) {
 		// `$&`, `` $` ``, `$'` and `$1` in the inserted text expand against the
 		// match, and this text now carries author-controlled metadata as well as
 		// the serialized route data.
-		/** @param {string} hoistedHead */
-		const splitAroundBody = (hoistedHead) => {
+		/** @param {string} hoistedHead @param {boolean} [earlyHydration] */
+		const splitAroundBody = (hoistedHead, earlyHydration = false) => {
 			const completeHead = headContent + hoistedHead;
-			return noncedTemplate === null
-				? splitHydrationTemplate(completeHead)
-				: splitSsrTemplate(noncedTemplate.replace(HEAD_MARKER, () => completeHead));
+			if (noncedTemplate !== null)
+				return prepareSsrTemplate(noncedTemplate, earlyHydration)(completeHead);
+			if (!earlyHydration) return splitHydrationTemplate(completeHead);
+			splitEarlyHydrationTemplate ??= prepareSsrTemplate(normalizedTemplate, true);
+			return splitEarlyHydrationTemplate(completeHead);
 		};
 
 		if (manifest.render === 'buffered') {
@@ -447,6 +577,8 @@ export function createHandler(manifest, deps) {
 			} = await prerender(RootComponent, undefined, {
 				nonce: nonce ?? undefined,
 				headChannel: 'separate',
+				...(streamedSignals === undefined ? {} : { streamedSignals }),
+				...(independentHydration === undefined ? {} : { independentHydration }),
 				signal: context.request.signal,
 				onError(/** @type {unknown} */ error) {
 					console.error('[octane] SSR render error:', error);
@@ -459,10 +591,16 @@ export function createHandler(manifest, deps) {
 		// Streaming (default): shell flushes at first await, suspense segments
 		// stream out-of-order behind it — identical to dev.
 		let hoistedHead = '';
+		let earlyHydration = clientBuild?.capabilities.independentHydration === true;
 		/** @type {ReadableStream<Uint8Array>} */
 		const renderStream = await renderToReadableStream(RootComponent, undefined, {
+			onEarlyHydrationReady() {
+				earlyHydration = true;
+			},
 			nonce: nonce ?? undefined,
 			headChannel: 'separate',
+			...(streamedSignals === undefined ? {} : { streamedSignals }),
+			...(independentHydration === undefined ? {} : { independentHydration }),
 			// Fires before the shell is written, so the metadata is in hand before
 			// the template prefix (which carries `<head>`) is composed below.
 			onHeadReady(/** @type {string} */ head) {
@@ -474,8 +612,8 @@ export function createHandler(manifest, deps) {
 			},
 		});
 
-		const [prefix, suffix] = splitAroundBody(hoistedHead);
-		const body = composeHtmlStream(prefix, renderStream, suffix);
+		const [prefix, suffix, afterShell] = splitAroundBody(hoistedHead, earlyHydration);
+		const body = composeHtmlStream(prefix, renderStream, suffix, afterShell);
 
 		return new Response(body, { status, headers });
 	}

package/src/server/request-context.js

@@ -18,14 +18,17 @@
 
 /**
  * @typedef {import('@octanejs/app-core').Context} Context
- * @typedef {import('@ripple-ts/adapter/rpc').AsyncContext<{ origin?: string, platform?: unknown, context?: Context }>} RequestAsyncContext
- * @typedef {{ asyncContext: RequestAsyncContext }} RequestContextHolder
+ * @typedef {import('@octanejs/app-core').RpcRequestOptions['asyncContext']} RequestAsyncContext
+ * @typedef {{ asyncContext: RequestAsyncContext, serverCallSource: import('octane/server').ServerCallContextSource }} RequestContextHolder
  */
 
 const REQUEST_CONTEXT_KEY = Symbol.for('octane.app-core.request-context');
+const SERVER_CALL_CONTEXT_KEY = Symbol.for('octane.server.call-context');
 
 const globals =
-	/** @type {typeof globalThis & { [REQUEST_CONTEXT_KEY]?: RequestContextHolder }} */ (globalThis);
+	/** @type {typeof globalThis & { [REQUEST_CONTEXT_KEY]?: RequestContextHolder, [SERVER_CALL_CONTEXT_KEY]?: import('octane/server').ServerCallContextSource }} */ (
+		globalThis
+	);
 
 /**
  * Publish the async context a request boundary runs its handler inside. Called
@@ -37,12 +40,21 @@ const globals =
  * @returns {void}
  */
 export function setRequestContextSource(asyncContext) {
-	const current = globals[REQUEST_CONTEXT_KEY];
+	let current = globals[REQUEST_CONTEXT_KEY];
 	if (current === undefined) {
-		globals[REQUEST_CONTEXT_KEY] = { asyncContext };
+		current = {
+			asyncContext,
+			serverCallSource: {
+				getStore: () => globals[REQUEST_CONTEXT_KEY]?.asyncContext.getStore()?.serverCallHost,
+			},
+		};
+		globals[REQUEST_CONTEXT_KEY] = current;
 	} else if (current.asyncContext !== asyncContext) {
 		current.asyncContext = asyncContext;
 	}
+	if (globals[SERVER_CALL_CONTEXT_KEY] !== current.serverCallSource) {
+		globals[SERVER_CALL_CONTEXT_KEY] = current.serverCallSource;
+	}
 }
 
 /**

package/src/server/rpc.js

@@ -13,6 +13,8 @@ import { derive_origin } from '@ripple-ts/adapter/rpc';
 import { DEFAULT_RPC_MAX_BODY_BYTES } from '../constants.js';
 import { createContext, runMiddlewareChain } from './middleware.js';
 import { setRequestContextSource } from './request-context.js';
+import { createServerCallHost, serverCallContext } from './server-calls.js';
+import { runServerRequest } from './signal-owners.js';
 
 const RPC_PATH_PREFIX = '/_$_ripple_rpc_$_/';
 
@@ -25,7 +27,11 @@ const RPC_PATH_PREFIX = '/_$_ripple_rpc_$_/';
 function rpcError(status, message, headers) {
 	return new Response(JSON.stringify({ error: message }), {
 		status,
-		headers: { 'Content-Type': 'application/json; charset=utf-8', ...headers },
+		headers: {
+			'Content-Type': 'application/json; charset=utf-8',
+			'Octane-RPC-Outcome': 'rejected',
+			...headers,
+		},
 	});
 }
 
@@ -74,6 +80,7 @@ function withRpcCors(response, origin) {
 
 	const headers = new Headers(response.headers);
 	headers.set('Access-Control-Allow-Origin', origin);
+	headers.set('Access-Control-Expose-Headers', 'Octane-RPC-Outcome');
 	headers.append('Vary', 'Origin');
 	return new Response(response.body, {
 		status: response.status,
@@ -212,6 +219,53 @@ export async function handleRpcRequest(request, options) {
 	}
 	const browserOrigin = request.headers.get('origin');
 	const corsOrigin = browserOrigin === origin ? null : browserOrigin;
+	if (request.headers.get('accept') === 'application/x-octane-rpc-batch+ndjson') {
+		if (options.batchServerFunctions === undefined || options.streamServerFunction === undefined) {
+			return withRpcCors(rpcError(406, 'Server-call batching is not configured'), corsOrigin);
+		}
+		const payload = await readBoundedRpcBody(
+			request,
+			options.maxBodyBytes ?? DEFAULT_RPC_MAX_BODY_BYTES,
+		);
+		if ('error' in payload) return withRpcCors(payload.error, corsOrigin);
+		try {
+			const stream = await options.batchServerFunctions(
+				payload.body,
+				(member, signal) => {
+					const url = new URL(request.url);
+					url.pathname = RPC_PATH_PREFIX + member.hash;
+					const headers = new Headers(request.headers);
+					headers.set('accept', 'application/x-octane-rpc+ndjson');
+					headers.delete('content-length');
+					// Re-enter the complete boundary for every member, with isolated
+					// authorization state. The batch envelope grants no credentials.
+					return handleRpcRequest(
+						new Request(url, {
+							method: 'POST',
+							headers,
+							body: member.body,
+							signal,
+						}),
+						options,
+					);
+				},
+				{ ...options.resultLimits, signal: request.signal },
+			);
+			return withRpcCors(
+				new Response(stream, {
+					headers: {
+						'Content-Type': 'application/x-octane-rpc-batch+ndjson',
+						'Cache-Control': 'no-store',
+					},
+				}),
+				corsOrigin,
+			);
+		} catch (error) {
+			if (isInvalidRpcPayload(error))
+				return withRpcCors(rpcError(400, 'Invalid server batch arguments'), corsOrigin);
+			throw error;
+		}
+	}
 
 	const context = createContext(request, {}, options.platform);
 	// Name the target before middleware so a policy can authorize per function.
@@ -230,41 +284,123 @@ export async function handleRpcRequest(request, options) {
 		options.platform === undefined
 			? { origin, context }
 			: { origin, platform: options.platform, context };
+	Object.assign(store, {
+		serverCallHost: createServerCallHost(context, {
+			asyncContext: options.asyncContext,
+			middlewares: options.middlewares,
+			origin,
+		}),
+	});
 	setRequestContextSource(options.asyncContext);
+	let invoked = false;
 
 	try {
-		const response = await options.asyncContext.run(store, async () =>
-			runMiddlewareChain(
-				context,
-				options.middlewares ?? [],
-				[],
-				async () => {
-					const fn = await options.resolveFunction(hash);
-					if (fn === null) return rpcError(404, 'RPC function not found');
-					const payload = await readBoundedRpcBody(
-						request,
-						options.maxBodyBytes ?? DEFAULT_RPC_MAX_BODY_BYTES,
-					);
-					if ('error' in payload) return payload.error;
-					try {
-						const result = await options.executeServerFunction(fn, payload.body);
-						return new Response(result, {
-							status: 200,
-							headers: { 'Content-Type': 'application/json; charset=utf-8' },
-						});
-					} catch (error) {
-						if (isInvalidRpcPayload(error)) {
-							return rpcError(400, 'Invalid server function arguments');
+		const response = await runServerRequest(
+			options.asyncContext,
+			store,
+			options.signalOwners,
+			async () =>
+				runMiddlewareChain(
+					context,
+					options.middlewares ?? [],
+					[],
+					async () => {
+						const fn = await options.resolveFunction(hash);
+						if (fn === null) return rpcError(404, 'RPC function not found');
+						const payload = await readBoundedRpcBody(
+							request,
+							options.maxBodyBytes ?? DEFAULT_RPC_MAX_BODY_BYTES,
+						);
+						if ('error' in payload) return payload.error;
+						try {
+							if (request.headers.get('accept') === 'application/x-octane-rpc+ndjson') {
+								if (options.streamServerFunction === undefined) {
+									return rpcError(406, 'Streamed RPC results are not configured');
+								}
+								invoked = true;
+								const stream = await options.streamServerFunction(
+									fn,
+									payload.body,
+									serverCallContext(context),
+									options.resultLimits,
+								);
+								const reader = stream.getReader();
+								return new Response(
+									new ReadableStream(
+										{
+											pull(controller) {
+												return options.asyncContext.run(store, async () => {
+													try {
+														const item = await reader.read();
+														if (item.done) {
+															reader.releaseLock();
+															controller.close();
+														} else controller.enqueue(item.value);
+													} catch (error) {
+														controller.error(error);
+													}
+												});
+											},
+											cancel(reason) {
+												return options.asyncContext.run(store, async () => {
+													try {
+														await reader.cancel(reason);
+													} finally {
+														reader.releaseLock();
+													}
+												});
+											},
+										},
+										{ highWaterMark: 0 },
+									),
+									{
+										headers: {
+											'Content-Type': 'application/x-octane-rpc+ndjson',
+											'Cache-Control': 'no-store',
+										},
+									},
+								);
+							}
+							invoked = true;
+							const result = await options.executeServerFunction(
+								fn,
+								payload.body,
+								serverCallContext(context),
+							);
+							return new Response(result, {
+								status: 200,
+								headers: { 'Content-Type': 'application/json; charset=utf-8' },
+							});
+						} catch (error) {
+							if (isInvalidRpcPayload(error)) {
+								return rpcError(400, 'Invalid server function arguments');
+							}
+							throw error;
 						}
-						throw error;
-					}
-				},
-				[],
-			),
+					},
+					[],
+				),
 		);
+		if (!response.ok && !invoked) {
+			const headers = new Headers(response.headers);
+			headers.set('Octane-RPC-Outcome', 'rejected');
+			return withRpcCors(
+				new Response(response.body, {
+					status: response.status,
+					statusText: response.statusText,
+					headers,
+				}),
+				corsOrigin,
+			);
+		}
 		return withRpcCors(response, corsOrigin);
 	} catch (error) {
 		console.error('[octane] RPC request error:', error);
-		return withRpcCors(rpcError(500, 'Internal Server Error'), corsOrigin);
+		return withRpcCors(
+			rpcError(500, 'Internal Server Error', {
+				'Octane-RPC-Outcome': invoked ? 'uncertain' : 'rejected',
+			}),
+			corsOrigin,
+		);
 	}
 }