@octanejs/app-core 0.0.15 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/app-core",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -79,10 +79,10 @@
     "esbuild": "^0.28.1"
   },
   "peerDependencies": {
-    "octane": "0.1.19"
+    "octane": "0.1.20"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "octane": "0.1.19"
+    "octane": "0.1.20"
   }
 }

package/src/index.js

@@ -17,3 +17,5 @@ export {
 	runMiddlewareChain,
 } from './middleware.js';
 export { handleRpcRequest } from './server/rpc.js';
+export { getRequestContext, tryGetRequestContext } from './server/request-context.js';
+export { createRpcRegistry } from './server/rpc-registry.js';

package/src/resolve-config.js

@@ -174,6 +174,9 @@ export function resolveOctaneConfig(raw, options = {}) {
 	) {
 		throw new Error('[octane] compiler must be an object when provided.');
 	}
+	if (raw.compiler?.strong !== undefined && typeof raw.compiler.strong !== 'boolean') {
+		throw new Error('[octane] compiler.strong must be a boolean when provided.');
+	}
 
 	if (raw.router?.routes !== undefined && !Array.isArray(raw.router.routes)) {
 		throw new Error('[octane] router.routes must be an array.');
@@ -232,6 +235,7 @@ export function resolveOctaneConfig(raw, options = {}) {
 		},
 		adapter: raw.adapter,
 		compiler: {
+			strong: raw.compiler?.strong ?? false,
 			renderers: normalizeRendererConfig(raw.compiler?.renderers),
 		},
 		router: {

package/src/server/production.js

@@ -25,6 +25,7 @@
 import { createRouter } from './router.js';
 import { createContext, runMiddlewareChain } from './middleware.js';
 import { handleRpcRequest } from './rpc.js';
+import { rpcIdCollision } from './rpc-registry.js';
 import { handleServerRoute } from './server-route.js';
 import { composeHtmlStream } from './html-stream.js';
 import {
@@ -95,6 +96,34 @@ function getFetchCoordinator(runtime) {
 	return coordinator;
 }
 
+/**
+ * Name every server function id, built once per handler.
+ *
+ * `build_rpc_lookup` keeps only the namespace object and export name, but a
+ * middleware policy needs the declaring module before the function is resolved.
+ *
+ * @param {Record<string, Record<string, Function>>} rpcModules
+ * @param {(value: string) => string} hashFn
+ * @returns {Map<string, { module: string, export: string }>}
+ */
+function buildRpcDescriptors(rpcModules, hashFn) {
+	/** @type {Map<string, { module: string, export: string }>} */
+	const descriptors = new Map();
+	for (const [entryPath, serverObj] of Object.entries(rpcModules)) {
+		for (const funcName of Object.keys(serverObj)) {
+			const id = hashFn(entryPath + '#' + funcName);
+			// Each manifest entry is listed once, so an id already taken here is a
+			// genuine collision. `build_rpc_lookup` would resolve it by overwriting.
+			const existing = descriptors.get(id);
+			if (existing !== undefined) {
+				throw rpcIdCollision(id, existing, { module: entryPath, export: funcName });
+			}
+			descriptors.set(id, { module: entryPath, export: funcName });
+		}
+	}
+	return descriptors;
+}
+
 /**
  * @typedef {import('@octanejs/app-core').RenderRoute} RenderRoute
  * @typedef {import('@octanejs/app-core').Middleware} Middleware
@@ -134,6 +163,8 @@ export function createHandler(manifest, deps) {
 	// (compiler hash → server function).
 	const rpcLookup =
 		manifest.rpcModules && runtime ? build_rpc_lookup(manifest.rpcModules, runtime.hash) : null;
+	const rpcDescriptors =
+		manifest.rpcModules && runtime ? buildRpcDescriptors(manifest.rpcModules, runtime.hash) : null;
 
 	// Request-scoped async context + same-origin fetch short-circuit: fetch()
 	// during SSR that resolves to this origin routes through the handler
@@ -162,6 +193,9 @@ export function createHandler(manifest, deps) {
 					const fn = entry.serverObj[entry.funcName];
 					return typeof fn === 'function' ? fn : null;
 				},
+				describeFunction(/** @type {string} */ hash) {
+					return rpcDescriptors?.get(hash) ?? null;
+				},
 				executeServerFunction,
 				asyncContext,
 				trustProxy,

package/src/server/request-context.js

@@ -0,0 +1,72 @@
+// @ts-check
+/**
+ * Request-scoped context lookup for `module server` functions.
+ *
+ * A server function is loaded through the SSR module graph in dev and through
+ * the server manifest in production, so the `@octanejs/app-core` instance it
+ * imports is not necessarily the one that handled the request. The active async
+ * context is therefore published on a `Symbol.for` global, the same technique
+ * the fetch coordinator uses, so every evaluated copy resolves the one live
+ * store.
+ *
+ * The holder tracks one boundary, which is what a process has: dev serves RPC
+ * through the plugin's single async context and production through the single
+ * fetch coordinator. A process running two boundaries concurrently would see the
+ * later registration win, and a server function under the earlier one reports no
+ * request rather than the wrong one.
+ */
+
+/**
+ * @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
+ */
+
+const REQUEST_CONTEXT_KEY = Symbol.for('octane.app-core.request-context');
+
+const globals =
+	/** @type {typeof globalThis & { [REQUEST_CONTEXT_KEY]?: RequestContextHolder }} */ (globalThis);
+
+/**
+ * Publish the async context a request boundary runs its handler inside. Called
+ * per request from `handleRpcRequest` rather than once at construction so any
+ * embedder of that boundary is covered without a second registration step; the
+ * identity check keeps the steady state a read.
+ *
+ * @param {RequestAsyncContext} asyncContext
+ * @returns {void}
+ */
+export function setRequestContextSource(asyncContext) {
+	const current = globals[REQUEST_CONTEXT_KEY];
+	if (current === undefined) {
+		globals[REQUEST_CONTEXT_KEY] = { asyncContext };
+	} else if (current.asyncContext !== asyncContext) {
+		current.asyncContext = asyncContext;
+	}
+}
+
+/**
+ * The `Context` for the in-flight request, or `null` when there is none.
+ *
+ * @returns {Context | null}
+ */
+export function tryGetRequestContext() {
+	return globals[REQUEST_CONTEXT_KEY]?.asyncContext.getStore()?.context ?? null;
+}
+
+/**
+ * The `Context` for the in-flight request.
+ *
+ * @returns {Context}
+ */
+export function getRequestContext() {
+	const context = tryGetRequestContext();
+	if (context === null) {
+		throw new Error(
+			'[octane] getRequestContext() was called outside of a request. It is available inside ' +
+				'`module server` functions and the middleware chain that runs them. Use ' +
+				'tryGetRequestContext() for code that must also run outside a request.',
+		);
+	}
+	return context;
+}

package/src/server/rpc-registry.js

@@ -0,0 +1,62 @@
+// @ts-check
+/**
+ * Collision guard for `module server` function ids.
+ *
+ * An id is a truncated SHA-256 of `"<module>#<export>"`, so two different
+ * exports can produce the same one. Both registration paths are a plain Map
+ * set, which resolves a collision by overwriting: one function becomes
+ * unreachable and its calls execute the other one instead, silently and with
+ * whatever authorization that other function carries. Fail the boot instead.
+ */
+
+/**
+ * @typedef {{ module: string, export: string }} RpcDeclaration
+ */
+
+/**
+ * @param {string} id
+ * @param {RpcDeclaration} first
+ * @param {RpcDeclaration} second
+ * @returns {Error}
+ */
+export function rpcIdCollision(id, first, second) {
+	return new Error(
+		`[octane] Two server functions share the id "${id}": \`${first.export}\` in ${first.module} ` +
+			`and \`${second.export}\` in ${second.module}. An id is a truncated hash of the module ` +
+			'path and export name, so renaming either export resolves it.',
+	);
+}
+
+/**
+ * `globalThis.rpc_modules`, rejecting a second declaration under an id already
+ * taken by a different one. Re-registering the same export is a no-op, which
+ * dev module reloads depend on.
+ */
+class RpcRegistry extends Map {
+	/**
+	 * @param {string} id
+	 * @param {[modulePath: string, exportName: string]} declaration
+	 * @returns {this}
+	 */
+	set(id, declaration) {
+		const existing = this.get(id);
+		if (
+			existing !== undefined &&
+			(existing[0] !== declaration[0] || existing[1] !== declaration[1])
+		) {
+			throw rpcIdCollision(
+				id,
+				{ module: existing[0], export: existing[1] },
+				{ module: declaration[0], export: declaration[1] },
+			);
+		}
+		return super.set(id, declaration);
+	}
+}
+
+/**
+ * @returns {Map<string, [modulePath: string, exportName: string]>}
+ */
+export function createRpcRegistry() {
+	return new RpcRegistry();
+}

package/src/server/rpc.js

@@ -12,6 +12,7 @@ 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';
 
 const RPC_PATH_PREFIX = '/_$_ripple_rpc_$_/';
 
@@ -213,8 +214,23 @@ export async function handleRpcRequest(request, options) {
 	const corsOrigin = browserOrigin === origin ? null : browserOrigin;
 
 	const context = createContext(request, {}, options.platform);
+	// Name the target before middleware so a policy can authorize per function.
+	// The id alone is a compiler artifact, so a policy written against it would
+	// break on any rename.
+	const described = options.describeFunction?.(hash);
+	context.rpc = {
+		id: hash,
+		module: described?.module ?? null,
+		export: described?.export ?? null,
+	};
+	// `context` rides the request store so a server function can read what the
+	// middleware chain established (auth, tenant) instead of trusting arguments
+	// the browser sent. The body is already consumed by the time it runs.
 	const store =
-		options.platform === undefined ? { origin } : { origin, platform: options.platform };
+		options.platform === undefined
+			? { origin, context }
+			: { origin, platform: options.platform, context };
+	setRequestContextSource(options.asyncContext);
 
 	try {
 		const response = await options.asyncContext.run(store, async () =>

package/types/index.d.ts

@@ -111,6 +111,34 @@ export interface Context {
 	state: Map<string, unknown>;
 	/** Request-scoped bindings supplied by the active platform integration. */
 	platform?: unknown;
+	/**
+	 * The `module server` export this request targets, present only on an RPC
+	 * request. Set before the middleware chain runs, so a policy can authorize
+	 * per function instead of per endpoint.
+	 */
+	rpc?: RpcTarget;
+}
+
+/**
+ * Identifies the `module server` export an RPC request targets.
+ *
+ * `module` and `export` are `null` when the integration supplies no
+ * {@link RpcRequestOptions.describeFunction}. A policy that matches on them then
+ * matches nothing and allows the request, so an integration that hand-rolls the
+ * RPC boundary must supply it before writing per-function authorization. Both
+ * first-party integrations (the Vite plugin and the production handler) do.
+ */
+export interface RpcTarget {
+	/**
+	 * Compiler-assigned function id, taken from the request path. Stable only for
+	 * a given build: it is a hash of the declaring module and export name, so it
+	 * changes on rename. Authorize on `module`/`export`, not on this.
+	 */
+	id: string;
+	/** Module that declared the export, or `null` when the integration cannot name it. */
+	module: string | null;
+	/** Exported function name, or `null` when the integration cannot name it. */
+	export: string | null;
 }
 
 export type NextFunction = () => Promise<Response>;
@@ -142,8 +170,15 @@ export function is_rpc_request(pathname: string): boolean;
 /** Security policy and execution dependencies for a server-function request. */
 export interface RpcRequestOptions {
 	resolveFunction: (hash: string) => Function | null | Promise<Function | null>;
+	/**
+	 * Name the export a function id refers to, without loading its module. Called
+	 * once per RPC request, before middleware, to populate {@link Context.rpc}.
+	 * Synchronous by contract: both first-party integrations already hold the
+	 * mapping, and the middleware chain must not wait on it.
+	 */
+	describeFunction?: (hash: string) => { module: string; export: string } | null;
 	executeServerFunction: (fn: Function, body: string) => Promise<string>;
-	asyncContext: AsyncContext<{ origin?: string; platform?: unknown }>;
+	asyncContext: AsyncContext<{ origin?: string; platform?: unknown; context?: Context }>;
 	trustProxy?: boolean;
 	middlewares?: Middleware[];
 	allowedOrigins?: readonly string[];
@@ -154,6 +189,38 @@ export interface RpcRequestOptions {
 /** Apply Octane's security policy and global middleware to a server function. */
 export function handleRpcRequest(request: Request, options: RpcRequestOptions): Promise<Response>;
 
+/**
+ * The `Context` for the in-flight request.
+ *
+ * Available inside a `module server` function and inside the middleware chain
+ * that runs it, so a server function can read the identity its middleware
+ * established rather than trusting an argument the browser supplied. It is the
+ * same `Context` instance the middleware saw, including `state` mutations.
+ *
+ * `context.request.body` is already consumed on the RPC path (the boundary
+ * reads it under the configured size limit before dispatching), so
+ * `bodyUsed` is `true`; headers, cookies, and `url` are unaffected.
+ *
+ * Throws outside a request. Use {@link tryGetRequestContext} in code that must
+ * also run outside one.
+ */
+export function getRequestContext(): Context;
+
+/** {@link getRequestContext}, returning `null` outside a request instead of throwing. */
+export function tryGetRequestContext(): Context | null;
+
+/**
+ * The `globalThis.rpc_modules` registry compiled `module server` declarations
+ * register into, guarding against an id collision.
+ *
+ * An id is a truncated hash of the module path and export name, so two exports
+ * can produce the same one. A plain Map would resolve that by overwriting, which
+ * makes one function unreachable and routes its calls to the other. This throws
+ * instead. Re-registering the same export is a no-op, which module reloads rely
+ * on.
+ */
+export function createRpcRegistry(): Map<string, [modulePath: string, exportName: string]>;
+
 // ============================================================================
 // Configuration
 // ============================================================================
@@ -326,6 +393,8 @@ export interface OctaneConfigOptions {
 	adapter?: OctaneAdapter;
 	/** @experimental Compiler-owned configuration shared by all bundler integrations. */
 	compiler?: {
+		/** Reject unsafe state updates and ref writes in application-owned modules. @default false */
+		strong?: boolean;
 		renderers?: ExperimentalRendererConfigOptions;
 	};
 	router?: {
@@ -385,6 +454,8 @@ export interface ResolvedOctaneConfig {
 	};
 	adapter?: OctaneAdapter;
 	compiler: {
+		/** @default false */
+		strong: boolean;
 		renderers: ExperimentalResolvedRendererConfig;
 	};
 	router: {