gorsee 0.2.3 → 0.2.5

package/dist-pkg/server/request-security-policy.js

@@ -0,0 +1,34 @@
+export function createRequestSecurityPolicy(options = {}) {
+  const trustedHosts = new Set, explicitTrustedHosts = options.trustedHosts ?? [];
+  for (const host of options.trustedHosts ?? [])
+    if (host.trim())
+      trustedHosts.add(normalizeHost(host));
+  if (options.trustedOrigin)
+    try {
+      trustedHosts.add(normalizeHost(new URL(options.trustedOrigin).host));
+    } catch {}
+  return {
+    trustedOrigin: options.trustedOrigin,
+    trustForwardedHeaders: options.trustForwardedHeaders === !0,
+    trustedForwardedHops: options.trustForwardedHeaders === !0 ? Math.max(1, options.trustedForwardedHops ?? 1) : 0,
+    trustedHosts: [...trustedHosts],
+    enforceTrustedHosts: options.enforceTrustedHosts ?? explicitTrustedHosts.length > 0
+  };
+}
+export function validateRequestSecurityPolicy(metadata, executionPolicy, securityPolicy) {
+  if (securityPolicy.enforceTrustedHosts && securityPolicy.trustedHosts.length > 0 && !securityPolicy.trustedHosts.includes(normalizeHost(metadata.effectiveHost)))
+    return new Response("Invalid Host", { status: 400 });
+  if (executionPolicy.access === "internal" && securityPolicy.trustedOrigin && metadata.origin && !sameOrigin(metadata.origin, securityPolicy.trustedOrigin))
+    return new Response("Forbidden", { status: 403 });
+  return null;
+}
+function normalizeHost(host) {
+  return host.trim().toLowerCase();
+}
+function sameOrigin(left, right) {
+  try {
+    return new URL(left).origin === new URL(right).origin;
+  } catch {
+    return !1;
+  }
+}

package/dist-pkg/server/request-surface.d.ts

@@ -0,0 +1,8 @@
+export type RuntimeRequestSurface = "hmr" | "rpc" | "bundle" | "static" | "prerendered" | "route" | "not-found";
+export interface RuntimeRequestPlanOptions {
+    pathname: string;
+    hasRouteMatch: boolean;
+    allowHMR?: boolean;
+    allowPrerendered?: boolean;
+}
+export declare function createRuntimeRequestPlan(options: RuntimeRequestPlanOptions): RuntimeRequestSurface[];

package/dist-pkg/server/request-surface.js

@@ -0,0 +1,19 @@
+export function createRuntimeRequestPlan(options) {
+  const { pathname, hasRouteMatch, allowHMR = !1, allowPrerendered = !1 } = options;
+  if (allowHMR && pathname === "/__gorsee_hmr")
+    return ["hmr"];
+  if (/^\/api\/_rpc\/[a-zA-Z0-9]+$/.test(pathname))
+    return ["rpc"];
+  if (pathname.startsWith("/_gorsee/"))
+    return ["bundle", "not-found"];
+  const plan = [];
+  if (pathname !== "/") {
+    plan.push("static");
+    if (allowPrerendered)
+      plan.push("prerendered");
+  }
+  if (hasRouteMatch)
+    plan.push("route");
+  plan.push("not-found");
+  return plan;
+}

package/dist-pkg/server/route-request.d.ts

@@ -0,0 +1,31 @@
+import { type Context, type MiddlewareFn } from "./middleware.js";
+import { type ResolvedPageRoute } from "./page-render.js";
+import { type RequestSecurityPolicy } from "./request-security-policy.js";
+import type { MatchResult } from "../router/matcher.js";
+import { type AITraceContext } from "../ai/index.js";
+type RouteModule = Record<string, unknown>;
+interface RouteRequestContext {
+    match: MatchResult;
+    request: Request;
+    mod: RouteModule;
+    ctx: Context;
+}
+interface ResolvedRouteRequestContext extends RouteRequestContext {
+    resolved: ResolvedPageRoute;
+}
+interface RouteRequestOptions {
+    match: MatchResult;
+    request: Request;
+    trustedOrigin?: string;
+    trustForwardedHeaders?: boolean;
+    trustedForwardedHops?: number;
+    securityPolicy?: RequestSecurityPolicy;
+    trace?: Partial<AITraceContext>;
+    extraMiddlewares?: MiddlewareFn[];
+    onActionRequest?: (ctx: RouteRequestContext) => Promise<Response>;
+    onPartialRequest: (ctx: ResolvedRouteRequestContext) => Promise<Response>;
+    onPageRequest: (ctx: ResolvedRouteRequestContext) => Promise<Response>;
+    onRouteError?: (error: unknown, ctx: RouteRequestContext) => Promise<Response>;
+}
+export declare function handleRouteRequest(options: RouteRequestOptions): Promise<Response>;
+export {};

package/dist-pkg/server/route-request.js

@@ -0,0 +1,112 @@
+import {
+  RedirectError,
+  sanitizeRedirectTarget
+} from "./middleware.js";
+import { handleAction } from "./action.js";
+import { resolvePageRoute } from "./page-render.js";
+import { executeServerExecution } from "./server-execution.js";
+import {
+  classifyRouteRequest
+} from "./request-policy.js";
+import {
+  createRequestSecurityPolicy
+} from "./request-security-policy.js";
+import { emitAIEvent } from "../ai/index.js";
+export async function handleRouteRequest(options) {
+  const { match, request, extraMiddlewares = [], onActionRequest, onPartialRequest, onPageRequest, onRouteError } = options, mod = await import(match.route.filePath), requestKind = classifyRouteRequest(mod, request), securityPolicy = options.securityPolicy ?? createRequestSecurityPolicy({
+    trustedOrigin: options.trustedOrigin,
+    trustForwardedHeaders: options.trustForwardedHeaders,
+    trustedForwardedHops: options.trustedForwardedHops
+  });
+  let routeCtx, resolvedRouteCtx;
+  try {
+    const middlewares = await loadRouteMiddlewares(match, mod, extraMiddlewares);
+    return await executeServerExecution({
+      request,
+      kind: requestKind,
+      params: match.params,
+      securityPolicy,
+      middlewares,
+      trace: options.trace,
+      route: match.route.path,
+      handler: async ({ ctx }) => {
+        routeCtx = { match, request, mod, ctx };
+        if (requestKind === "route-handler") {
+          const handlerName = request.method === "POST" ? "POST" : "GET";
+          return mod[handlerName](ctx);
+        }
+        if (requestKind === "action") {
+          if (onActionRequest)
+            return onActionRequest(routeCtx);
+          return handleActionRequest(mod.action, ctx, request);
+        }
+        if (requestKind === "partial")
+          return onPartialRequest(await ensureResolvedRouteContext());
+        return onPageRequest(await ensureResolvedRouteContext());
+      }
+    });
+  } catch (error) {
+    if (error instanceof RedirectError) {
+      const ctx = routeCtx?.ctx;
+      await emitAIEvent({
+        kind: "redirect",
+        severity: "info",
+        source: "runtime",
+        message: "route redirect thrown",
+        requestId: typeof ctx?.locals.requestId === "string" ? ctx.locals.requestId : void 0,
+        traceId: typeof ctx?.locals.traceId === "string" ? ctx.locals.traceId : void 0,
+        spanId: typeof ctx?.locals.spanId === "string" ? ctx.locals.spanId : void 0,
+        route: match.route.path,
+        data: {
+          method: request.method,
+          pathname: ctx?.url.pathname ?? new URL(request.url).pathname,
+          status: error.status,
+          requestKind
+        }
+      });
+      return new Response(null, {
+        status: error.status,
+        headers: {
+          Location: sanitizeRedirectTarget(error.url, securityPolicy.trustedOrigin ?? routeCtx?.ctx.url ?? new URL(request.url))
+        }
+      });
+    }
+    if (onRouteError && routeCtx)
+      return onRouteError(error, routeCtx);
+    throw error;
+  }
+  async function ensureResolvedRouteContext() {
+    if (resolvedRouteCtx)
+      return resolvedRouteCtx;
+    if (!routeCtx)
+      throw Error("Route context is not initialized");
+    const resolved = await resolvePageRoute(mod, match, routeCtx.ctx);
+    if (!resolved)
+      throw Error("Route has no default export");
+    resolvedRouteCtx = { ...routeCtx, resolved };
+    return resolvedRouteCtx;
+  }
+}
+async function loadRouteMiddlewares(match, mod, extraMiddlewares) {
+  const middlewares = [...extraMiddlewares];
+  for (const mwPath of match.route.middlewarePaths) {
+    const mwMod = await import(mwPath);
+    if (typeof mwMod.default === "function")
+      middlewares.push(mwMod.default);
+  }
+  if (typeof mod.guard === "function")
+    middlewares.push(mod.guard);
+  return middlewares;
+}
+async function handleActionRequest(action, ctx, request) {
+  const result = await handleAction(action, ctx);
+  if (request.headers.get("Accept")?.includes("application/json"))
+    return new Response(JSON.stringify(result), {
+      status: result.status,
+      headers: { "Content-Type": "application/json" }
+    });
+  return new Response(null, {
+    status: 303,
+    headers: { Location: request.url }
+  });
+}

package/dist-pkg/server/route-response.d.ts

@@ -0,0 +1,22 @@
+import type { MatchResult } from "../router/matcher.js";
+import type { Context } from "./middleware.js";
+import { type HTMLWrapOptions } from "./html-shell.js";
+import { type ResolvedPageRoute } from "./page-render.js";
+interface RouteResponseOptions {
+    match: MatchResult;
+    ctx: Context;
+    resolved: ResolvedPageRoute;
+    clientScript?: string;
+    nonce?: string;
+    secHeaders?: Record<string, string>;
+    wrapHTML?: (body: string, nonce: string | undefined, options?: HTMLWrapOptions) => string;
+}
+export declare function renderRoutePageResponse(options: RouteResponseOptions): Promise<Response>;
+export declare function renderRoutePartialResponse(options: RouteResponseOptions): Response;
+export declare function renderRouteErrorBoundaryResponse(errorPath: string, error: Error, options: {
+    match: MatchResult;
+    nonce?: string;
+    secHeaders?: Record<string, string>;
+    wrapHTML: (body: string, nonce: string | undefined, options?: HTMLWrapOptions) => string;
+}): Promise<Response>;
+export {};

package/dist-pkg/server/route-response.js

@@ -0,0 +1,58 @@
+import { renderToString, ssrJsx } from "../runtime/server.js";
+import { renderToStream, streamJsx } from "../runtime/stream.js";
+import { getServerHead, resetServerHead } from "../runtime/head.js";
+import {
+  buildPartialResponsePayload,
+  renderPageDocument
+} from "./page-render.js";
+import { partialNavigationHeaders } from "./partial-navigation.js";
+export async function renderRoutePageResponse(options) {
+  const { match, ctx, resolved, clientScript, nonce, secHeaders = {}, wrapHTML } = options, { pageComponent, loaderData, cssFiles, renderMode } = resolved, pageProps = { params: match.params, ctx, data: loaderData }, htmlOptions = {
+    clientScript,
+    loaderData,
+    params: match.params,
+    cssFiles
+  };
+  if (renderMode === "stream") {
+    if (!wrapHTML)
+      throw Error("wrapHTML is required for streaming page responses");
+    resetServerHead();
+    const vnode = streamJsx(pageComponent, pageProps), stream = renderToStream(vnode, {
+      shell: (body) => wrapHTML(body, nonce, {
+        ...htmlOptions,
+        headElements: getServerHead()
+      })
+    });
+    return new Response(stream, {
+      headers: { "Content-Type": "text/html", ...secHeaders }
+    });
+  }
+  const rendered = renderPageDocument(pageComponent, ctx, match.params, loaderData);
+  if (!wrapHTML)
+    return new Response(rendered.html, {
+      headers: { "Content-Type": "text/html", ...secHeaders }
+    });
+  const html = wrapHTML(rendered.html, nonce, {
+    ...htmlOptions,
+    headElements: rendered.headElements
+  });
+  return new Response(html, {
+    headers: { "Content-Type": "text/html", ...secHeaders }
+  });
+}
+export function renderRoutePartialResponse(options) {
+  const { match, ctx, resolved, clientScript, secHeaders = {} } = options, { pageComponent, loaderData, cssFiles } = resolved, rendered = renderPageDocument(pageComponent, ctx, match.params, loaderData), payload = buildPartialResponsePayload(rendered, loaderData, match.params, cssFiles, clientScript);
+  return new Response(JSON.stringify(payload), {
+    headers: partialNavigationHeaders(secHeaders)
+  });
+}
+export async function renderRouteErrorBoundaryResponse(errorPath, error, options) {
+  const { match, nonce, secHeaders = {}, wrapHTML } = options, ErrorComponent = (await import(errorPath)).default;
+  if (typeof ErrorComponent !== "function")
+    throw error;
+  const vnode = ssrJsx(ErrorComponent, { error, params: match.params }), body = renderToString(vnode), html = wrapHTML(body, nonce, { title: "Error" });
+  return new Response(html, {
+    status: 500,
+    headers: { "Content-Type": "text/html", ...secHeaders }
+  });
+}

package/dist-pkg/server/rpc-hash.d.ts

@@ -0,0 +1,2 @@
+export declare function hashRPC(filePath: string, index: number): string;
+export declare function scanServerCalls(source: string, filePath: string): string[];

package/dist-pkg/server/rpc-hash.js

@@ -0,0 +1,7 @@
+import { createHash } from "node:crypto";
+export function hashRPC(filePath, index) {
+  return createHash("sha256").update(`${filePath}:${index}`).digest("hex").slice(0, 12);
+}
+export function scanServerCalls(source, filePath) {
+  return [...source.matchAll(/\bserver\s*\(\s*(?=async\s|function\s)/g)].map((_, i) => hashRPC(filePath, i));
+}

package/dist-pkg/server/rpc-protocol.d.ts

@@ -0,0 +1,22 @@
+export declare const RPC_PROTOCOL_VERSION: 1;
+export declare const RPC_CONTENT_TYPE = "application/vnd.gorsee-rpc+json";
+export declare const RPC_ACCEPTED_CONTENT_TYPES: readonly ["application/vnd.gorsee-rpc+json", "application/json"];
+export interface RPCRequestEnvelope {
+    v: typeof RPC_PROTOCOL_VERSION;
+    args: unknown[];
+}
+export interface RPCSuccessEnvelope {
+    v: typeof RPC_PROTOCOL_VERSION;
+    ok: true;
+    encoding: "devalue";
+    data: string;
+}
+export interface RPCErrorEnvelope {
+    v: typeof RPC_PROTOCOL_VERSION;
+    ok: false;
+    error: string;
+}
+export type RPCResponseEnvelope = RPCSuccessEnvelope | RPCErrorEnvelope;
+export declare function encodeRPCSuccess(data: string): RPCSuccessEnvelope;
+export declare function encodeRPCError(error: string): RPCErrorEnvelope;
+export declare function decodeRPCRequest(body: unknown): unknown[] | null;

package/dist-pkg/server/rpc-protocol.js

@@ -0,0 +1,28 @@
+export const RPC_PROTOCOL_VERSION = 1, RPC_CONTENT_TYPE = "application/vnd.gorsee-rpc+json", RPC_ACCEPTED_CONTENT_TYPES = [RPC_CONTENT_TYPE, "application/json"];
+export function encodeRPCSuccess(data) {
+  return {
+    v: RPC_PROTOCOL_VERSION,
+    ok: !0,
+    encoding: "devalue",
+    data
+  };
+}
+export function encodeRPCError(error) {
+  return {
+    v: RPC_PROTOCOL_VERSION,
+    ok: !1,
+    error
+  };
+}
+export function decodeRPCRequest(body) {
+  if (Array.isArray(body))
+    return body;
+  if (!body || typeof body !== "object")
+    return null;
+  const candidate = body;
+  if (candidate.v !== RPC_PROTOCOL_VERSION)
+    return null;
+  if (!Array.isArray(candidate.args))
+    return null;
+  return candidate.args;
+}

package/dist-pkg/server/rpc-utils.d.ts

@@ -0,0 +1,2 @@
+import type { RPCRegistry } from "./rpc.js";
+export declare function createScopedRPCRegistry(registry: RPCRegistry, scope: string): RPCRegistry;

package/dist-pkg/server/rpc-utils.js

@@ -0,0 +1,26 @@
+export function createScopedRPCRegistry(registry, scope) {
+  const prefix = `${scope}:`, fileCounters = new Map, scopedIds = new Set;
+  return {
+    getHandler: (id) => registry.getHandler(prefix + id),
+    setHandler: (id, fn) => {
+      const scopedId = prefix + id;
+      scopedIds.add(scopedId);
+      registry.setHandler(scopedId, fn);
+    },
+    deleteHandler: (id) => {
+      const scopedId = prefix + id;
+      scopedIds.delete(scopedId);
+      registry.deleteHandler(scopedId);
+    },
+    clear: () => {
+      for (const scopedId of scopedIds)
+        registry.deleteHandler(scopedId);
+      scopedIds.clear();
+      fileCounters.clear();
+    },
+    getFileCallCount: (file) => fileCounters.get(file) ?? 0,
+    setFileCallCount: (file, count) => {
+      fileCounters.set(file, count);
+    }
+  };
+}

package/dist-pkg/server/rpc.d.ts

@@ -0,0 +1,20 @@
+import { RPC_ACCEPTED_CONTENT_TYPES, RPC_CONTENT_TYPE } from "./rpc-protocol.js";
+export interface ServerOptions {
+}
+export type RPCHandler = (...args: unknown[]) => Promise<unknown>;
+export interface RPCRegistry {
+    getHandler(id: string): RPCHandler | undefined;
+    setHandler(id: string, fn: RPCHandler): void;
+    deleteHandler(id: string): void;
+    clear(): void;
+    getFileCallCount(file: string): number;
+    setFileCallCount(file: string, count: number): void;
+}
+export declare function createMemoryRPCRegistry(): RPCRegistry;
+export declare function __registerRPC(id: string, fn: RPCHandler): void;
+export declare function __resetRPCState(): void;
+export declare function getRPCHandler(id: string): RPCHandler | undefined;
+export declare function server<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, _options?: ServerOptions): (...args: TArgs) => Promise<TReturn>;
+export declare function handleRPCRequestWithRegistry(request: Request, registry: Pick<RPCRegistry, "getHandler">): Promise<Response | null>;
+export { RPC_CONTENT_TYPE, RPC_ACCEPTED_CONTENT_TYPES };
+export declare function handleRPCRequest(request: Request): Promise<Response | null>;

package/dist-pkg/server/rpc.js

@@ -0,0 +1,147 @@
+import { stringify } from "devalue";
+import { hashRPC } from "./rpc-hash.js";
+import {
+  decodeRPCRequest,
+  encodeRPCError,
+  encodeRPCSuccess,
+  RPC_ACCEPTED_CONTENT_TYPES,
+  RPC_CONTENT_TYPE
+} from "./rpc-protocol.js";
+const MAX_RPC_PAYLOAD = 1048576;
+export function createMemoryRPCRegistry() {
+  const rpcHandlers = new Map, fileCallCounters = new Map;
+  return {
+    getHandler: (id) => rpcHandlers.get(id),
+    setHandler: (id, fn) => {
+      rpcHandlers.set(id, fn);
+    },
+    deleteHandler: (id) => {
+      rpcHandlers.delete(id);
+    },
+    clear: () => {
+      rpcHandlers.clear();
+      fileCallCounters.clear();
+    },
+    getFileCallCount: (file) => fileCallCounters.get(file) ?? 0,
+    setFileCallCount: (file, count) => {
+      fileCallCounters.set(file, count);
+    }
+  };
+}
+const defaultRPCRegistry = createMemoryRPCRegistry();
+export function __registerRPC(id, fn) {
+  defaultRPCRegistry.setHandler(id, fn);
+}
+export function __resetRPCState() {
+  defaultRPCRegistry.clear();
+}
+export function getRPCHandler(id) {
+  return defaultRPCRegistry.getHandler(id);
+}
+function getCallerFile() {
+  const orig = Error.prepareStackTrace;
+  Error.prepareStackTrace = (_err, stack) => stack;
+  const stack = Error().stack;
+  Error.prepareStackTrace = orig;
+  for (let i = 2;i < stack.length; i++) {
+    const file = stack[i]?.getFileName();
+    if (file && !file.includes("/server/rpc.ts") && !file.includes("node_modules"))
+      return file;
+  }
+  return null;
+}
+export function server(fn, _options) {
+  const callerFile = getCallerFile();
+  if (callerFile) {
+    const counter = defaultRPCRegistry.getFileCallCount(callerFile);
+    defaultRPCRegistry.setFileCallCount(callerFile, counter + 1);
+    const id = hashRPC(callerFile, counter);
+    defaultRPCRegistry.setHandler(id, fn);
+  }
+  return fn;
+}
+export async function handleRPCRequestWithRegistry(request, registry) {
+  const match = new URL(request.url).pathname.match(/^\/api\/_rpc\/([a-zA-Z0-9]+)$/);
+  if (!match)
+    return null;
+  if (request.method !== "POST")
+    return new Response(JSON.stringify(encodeRPCError("Method not allowed")), {
+      status: 405,
+      headers: {
+        "Content-Type": RPC_CONTENT_TYPE,
+        Allow: "POST"
+      }
+    });
+  const id = match[1], handler = registry.getHandler(id);
+  if (!handler)
+    return new Response(JSON.stringify(encodeRPCError(`RPC handler not found: ${id}`)), {
+      status: 404,
+      headers: { "Content-Type": RPC_CONTENT_TYPE }
+    });
+  try {
+    let args = [];
+    if (Number(request.headers.get("content-length") ?? "0") > MAX_RPC_PAYLOAD)
+      return new Response(JSON.stringify(encodeRPCError("Request body too large")), {
+        status: 413,
+        headers: { "Content-Type": RPC_CONTENT_TYPE }
+      });
+    const reader = request.body?.getReader();
+    let bodyBytes = 0;
+    const chunks = [];
+    if (reader)
+      while (!0) {
+        const { done, value } = await reader.read();
+        if (done)
+          break;
+        bodyBytes += value.byteLength;
+        if (bodyBytes > MAX_RPC_PAYLOAD) {
+          reader.cancel();
+          return new Response(JSON.stringify(encodeRPCError("Request body too large")), {
+            status: 413,
+            headers: { "Content-Type": RPC_CONTENT_TYPE }
+          });
+        }
+        chunks.push(value);
+      }
+    const body = new TextDecoder().decode(chunks.length === 1 ? chunks[0] : Buffer.concat(chunks));
+    if (body) {
+      let parsed;
+      try {
+        parsed = JSON.parse(body);
+      } catch {
+        return new Response(JSON.stringify(encodeRPCError("Invalid JSON in request body")), {
+          status: 400,
+          headers: { "Content-Type": RPC_CONTENT_TYPE }
+        });
+      }
+      const decodedArgs = decodeRPCRequest(parsed);
+      if (!decodedArgs)
+        return new Response(JSON.stringify(encodeRPCError("RPC args must be an array")), {
+          status: 400,
+          headers: { "Content-Type": RPC_CONTENT_TYPE }
+        });
+      args = decodedArgs;
+    }
+    const result = await handler(...args), serialized = stringify(result);
+    if (Buffer.byteLength(serialized, "utf-8") > MAX_RPC_PAYLOAD)
+      return new Response(JSON.stringify(encodeRPCError("Response body too large")), {
+        status: 413,
+        headers: { "Content-Type": RPC_CONTENT_TYPE }
+      });
+    return new Response(JSON.stringify(encodeRPCSuccess(serialized)), {
+      status: 200,
+      headers: { "Content-Type": RPC_CONTENT_TYPE }
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Internal server error";
+    return new Response(JSON.stringify(encodeRPCError(message)), {
+      status: 500,
+      headers: { "Content-Type": RPC_CONTENT_TYPE }
+    });
+  }
+}
+
+export { RPC_CONTENT_TYPE, RPC_ACCEPTED_CONTENT_TYPES };
+export async function handleRPCRequest(request) {
+  return handleRPCRequestWithRegistry(request, defaultRPCRegistry);
+}

package/dist-pkg/server/runtime-dispatch.d.ts

@@ -0,0 +1,19 @@
+import { type AIEventSource, type AITraceContext } from "../ai/index.js";
+import type { RuntimeRequestSurface } from "./request-surface.js";
+type DispatchableRuntimeSurface = Exclude<RuntimeRequestSurface, "hmr">;
+export interface RuntimeDispatchResult {
+    surface: DispatchableRuntimeSurface;
+    response: Response;
+}
+export interface RuntimeDispatchOptions {
+    plan: DispatchableRuntimeSurface[];
+    pathname: string;
+    request: Request;
+    trace: Pick<AITraceContext, "requestId" | "traceId" | "spanId">;
+    startTs: number;
+    source: AIEventSource;
+    route?: string;
+    handlers: Partial<Record<DispatchableRuntimeSurface, () => Promise<Response | null>>>;
+}
+export declare function dispatchRuntimeRequestPlan(options: RuntimeDispatchOptions): Promise<RuntimeDispatchResult | null>;
+export {};

package/dist-pkg/server/runtime-dispatch.js

@@ -0,0 +1,67 @@
+import { emitAIEvent } from "../ai/index.js";
+export async function dispatchRuntimeRequestPlan(options) {
+  for (const surface of options.plan) {
+    const handler = options.handlers[surface];
+    if (!handler)
+      continue;
+    const response = await handler();
+    if (!response)
+      continue;
+    if (surface === "not-found")
+      await emitAIEvent({
+        kind: "route.miss",
+        severity: "warn",
+        source: options.source,
+        message: "no route matched",
+        requestId: options.trace.requestId,
+        traceId: options.trace.traceId,
+        spanId: options.trace.spanId,
+        durationMs: Number((performance.now() - options.startTs).toFixed(2)),
+        data: {
+          method: options.request.method,
+          pathname: options.pathname
+        }
+      });
+    else
+      await emitAIEvent({
+        kind: "request.finish",
+        severity: response.status >= 400 ? "warn" : "info",
+        source: options.source,
+        message: describeSurfaceMessage(surface),
+        requestId: options.trace.requestId,
+        traceId: options.trace.traceId,
+        spanId: options.trace.spanId,
+        route: options.route,
+        durationMs: Number((performance.now() - options.startTs).toFixed(2)),
+        data: {
+          method: options.request.method,
+          pathname: options.pathname,
+          status: response.status,
+          handler: describeSurfaceHandler(surface, response)
+        }
+      });
+    return { surface, response };
+  }
+  return null;
+}
+function describeSurfaceMessage(surface) {
+  switch (surface) {
+    case "rpc":
+      return "rpc request handled";
+    case "bundle":
+      return "client bundle served";
+    case "static":
+      return "static asset served";
+    case "prerendered":
+      return "prerendered page served";
+    case "route":
+      return "route request handled";
+    case "not-found":
+      return "no route matched";
+  }
+}
+function describeSurfaceHandler(surface, response) {
+  if (surface === "route")
+    return response.headers.get("Content-Type")?.includes("application/json") ? "partial" : "route";
+  return surface;
+}

package/dist-pkg/server/server-execution.d.ts

@@ -0,0 +1,22 @@
+import { type EndpointExecutionContext, type EndpointExecutionTrace } from "./endpoint-execution.js";
+import type { MiddlewareFn } from "./middleware.js";
+import type { RequestExecutionKind } from "./request-policy.js";
+import type { RequestSecurityPolicy } from "./request-security-policy.js";
+export type ServerExecutionKind = Exclude<RequestExecutionKind, "static">;
+export interface ServerExecutionContext extends EndpointExecutionContext {
+    kind: ServerExecutionKind;
+    trace: EndpointExecutionTrace;
+}
+export interface ServerExecutionOptions {
+    request: Request;
+    kind: ServerExecutionKind;
+    params?: Record<string, string>;
+    middlewares?: MiddlewareFn[];
+    trustedOrigin?: string;
+    trustForwardedHeaders?: boolean;
+    securityPolicy?: RequestSecurityPolicy;
+    trace?: EndpointExecutionTrace;
+    route?: string;
+    handler: (context: ServerExecutionContext) => Promise<Response>;
+}
+export declare function executeServerExecution(options: ServerExecutionOptions): Promise<Response>;