octane 0.2.11 → 0.2.13

package/dist/server/streamed-signals.js

@@ -0,0 +1,488 @@
+import { encodeSignalValue } from "../data-encoding.js";
+import {
+  encodeStreamedRendererFrameForScript,
+  isStreamFrameIdentity,
+  isStreamedRendererFrame
+} from "../streamed-signals-protocol.js";
+import { createServerSignalQueryAttemptObservations } from "./signal-query-observation.js";
+const DEFAULT_MAX_FRAME_BYTES = 4 * 1024 * 1024;
+const DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const DEFAULT_TIMEOUT = 3e4;
+function positiveLimit(value, fallback) {
+  const limit = value ?? fallback;
+  if (!Number.isSafeInteger(limit) || limit <= 0) {
+    throw new RangeError("Streamed renderer limits must be positive safe integers.");
+  }
+  return limit;
+}
+function limits(options) {
+  return {
+    maxFrameBytes: positiveLimit(options.maxFrameBytes, DEFAULT_MAX_FRAME_BYTES),
+    maxTotalBytes: positiveLimit(options.maxTotalBytes, DEFAULT_MAX_TOTAL_BYTES),
+    timeoutMs: positiveLimit(options.timeoutMs, DEFAULT_TIMEOUT)
+  };
+}
+function isAsyncIterable(value) {
+  return value !== null && (typeof value === "object" || typeof value === "function") && typeof value[Symbol.asyncIterator] === "function";
+}
+async function* createStreamedSignalResultFrames(identity, result, options = {}) {
+  if (!isStreamFrameIdentity(identity)) throw new TypeError("Invalid streamed signal identity.");
+  let sequence = 0;
+  let resource = "promise";
+  let iterator;
+  const run = options.run ?? ((callback) => callback());
+  try {
+    const resolved = await result;
+    options.signal?.throwIfAborted();
+    if (isAsyncIterable(resolved)) {
+      resource = "stream";
+      iterator = run(() => resolved[Symbol.asyncIterator]());
+      yield { identity, sequence: sequence++, channel: "result", kind: "open", resource: "stream" };
+      for (; ; ) {
+        options.signal?.throwIfAborted();
+        const next = await run(() => iterator.next());
+        options.signal?.throwIfAborted();
+        if (next.done) break;
+        yield {
+          identity,
+          sequence: sequence++,
+          channel: "result",
+          kind: "value",
+          value: encodeSignalValue(next.value)
+        };
+      }
+      iterator = void 0;
+    } else {
+      yield {
+        identity,
+        sequence: sequence++,
+        channel: "result",
+        kind: "open",
+        resource: "promise"
+      };
+      yield {
+        identity,
+        sequence: sequence++,
+        channel: "result",
+        kind: "value",
+        value: encodeSignalValue(resolved)
+      };
+    }
+    yield { identity, sequence, channel: "result", kind: "complete" };
+  } catch {
+    if (sequence === 0) {
+      yield { identity, sequence: sequence++, channel: "result", kind: "open", resource };
+    }
+    yield { identity, sequence, channel: "result", kind: "error", code: "SERVER_RESULT_FAILED" };
+  } finally {
+    if (iterator !== void 0) {
+      try {
+        await run(() => iterator.return?.());
+      } catch {
+      }
+    }
+  }
+}
+function line(frame) {
+  if (!isStreamedRendererFrame(frame)) throw new TypeError("Invalid streamed renderer frame.");
+  return new TextEncoder().encode(JSON.stringify(frame) + "\n");
+}
+function createStreamedRendererFrameStream(frames, options = {}) {
+  const budget = limits(options);
+  const iterator = frames[Symbol.asyncIterator]();
+  let totalBytes = 0;
+  let finished = false;
+  let controller;
+  const timer = setTimeout(
+    () => fail(new Error("Streamed renderer response timed out.")),
+    budget.timeoutMs
+  );
+  const cleanup = () => {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", abort);
+  };
+  const closeIterator = () => {
+    try {
+      void Promise.resolve(iterator.return?.(void 0)).catch(() => {
+      });
+    } catch {
+    }
+  };
+  const fail = (error) => {
+    if (finished) return;
+    finished = true;
+    cleanup();
+    closeIterator();
+    controller?.error(error);
+  };
+  const abort = () => fail(options.signal?.reason ?? new DOMException("Aborted", "AbortError"));
+  return new ReadableStream(
+    {
+      start(streamController) {
+        controller = streamController;
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted) abort();
+      },
+      async pull() {
+        if (finished) return;
+        try {
+          const next = await iterator.next();
+          if (finished) return;
+          if (next.done) {
+            finished = true;
+            cleanup();
+            controller.close();
+            return;
+          }
+          const encoded = line(next.value);
+          if (encoded.byteLength > budget.maxFrameBytes || totalBytes + encoded.byteLength > budget.maxTotalBytes) {
+            throw new Error("Streamed renderer response exceeded its byte budget.");
+          }
+          totalBytes += encoded.byteLength;
+          controller.enqueue(encoded);
+        } catch (error) {
+          fail(error);
+        }
+      },
+      cancel() {
+        if (finished) return;
+        finished = true;
+        cleanup();
+        closeIterator();
+      }
+    },
+    { highWaterMark: 0 }
+  );
+}
+function escapeAttribute(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function streamedRendererFrameScript(frame, nonce) {
+  const encoded = encodeStreamedRendererFrameForScript(frame);
+  return `<script${nonce === void 0 ? "" : ` nonce="${escapeAttribute(nonce)}"`}>globalThis.__octaneStreamedRenderer.receive(${encoded});</script>`;
+}
+function streamedSignalSelectionScript(identity, nonce) {
+  if (!isStreamFrameIdentity(identity)) throw new TypeError("Invalid streamed signal identity.");
+  const encoded = JSON.stringify(identity).replace(/&/g, "\\u0026").replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+  return `<script${nonce === void 0 ? "" : ` nonce="${escapeAttribute(nonce)}"`}>(function(g){var k="__octaneStreamedRenderer",e=g[k];if(!e){var q=[];g[k]={version:1,frames:q,receive:function(f){if(q.length>=512){this.overflow=true;return;}q.push(f);}};}var z="__octaneStreamedSignalSelections",v=g[z];if(!v){var a=[];v=g[z]={version:1,identities:a,register:function(i){if(a.length>=256){this.overflow=true;return;}a.push(i);}};}v.register(${encoded});})(globalThis);</script>`;
+}
+function createStreamedSignalInjection(identity, result, options = {}) {
+  const budget = limits(options);
+  const iterator = createStreamedSignalResultFrames(identity, result, options)[Symbol.asyncIterator]();
+  let queued = options.announceSelection ? streamedSignalSelectionScript(identity, options.nonce) : "";
+  let pending = false;
+  let finished = false;
+  let subscribed = false;
+  let totalBytes = 0;
+  let notify;
+  let resolveDone;
+  let rejectDone;
+  const done = new Promise((resolve, reject) => {
+    resolveDone = resolve;
+    rejectDone = reject;
+  });
+  let timer;
+  const cleanup = () => {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", abort);
+  };
+  const closeIterator = () => {
+    try {
+      void Promise.resolve(iterator.return?.(void 0)).catch(() => {
+      });
+    } catch {
+    }
+  };
+  const fail = (error) => {
+    if (finished) return;
+    finished = true;
+    cleanup();
+    closeIterator();
+    rejectDone(error);
+  };
+  const pump = () => {
+    if (!subscribed || pending || queued !== "" || finished) return;
+    pending = true;
+    void iterator.next().then(
+      (next) => {
+        pending = false;
+        if (finished) return;
+        if (next.done) {
+          finished = true;
+          cleanup();
+          resolveDone();
+          return;
+        }
+        const html = streamedRendererFrameScript(next.value, options.nonce);
+        const bytes = new TextEncoder().encode(html).byteLength;
+        if (bytes > budget.maxFrameBytes || totalBytes + bytes > budget.maxTotalBytes) {
+          fail(new Error("Streamed renderer injection exceeded its byte budget."));
+          return;
+        }
+        totalBytes += bytes;
+        queued = html;
+        notify?.();
+      },
+      (error) => {
+        pending = false;
+        fail(error);
+      }
+    );
+  };
+  const abort = () => {
+    fail(options.signal?.reason ?? new DOMException("Aborted", "AbortError"));
+  };
+  timer = setTimeout(
+    () => fail(new Error("Streamed renderer injection timed out.")),
+    budget.timeoutMs
+  );
+  options.signal?.addEventListener("abort", abort, { once: true });
+  if (options.signal?.aborted) abort();
+  return {
+    streamedRenderer: true,
+    take() {
+      const html = queued;
+      queued = "";
+      return html;
+    },
+    subscribe(callback) {
+      notify = callback;
+      subscribed = true;
+      pump();
+      return () => {
+        if (notify === callback) notify = void 0;
+      };
+    },
+    accepted() {
+      pump();
+    },
+    cancel: fail,
+    done,
+    renderComplete() {
+      pump();
+    }
+  };
+}
+function createAutomaticStreamedSignalInjection(options, external) {
+  if (!options.buildId || !options.documentId) {
+    throw new TypeError("Automatic streamed signals require buildId and documentId.");
+  }
+  const budget = limits(options);
+  const selectionGeneration = options.selectionGeneration ?? 0;
+  if (!Number.isSafeInteger(selectionGeneration) || selectionGeneration < 0) {
+    throw new RangeError("selectionGeneration must be a nonnegative safe integer.");
+  }
+  const children = [];
+  const observedAttempts = /* @__PURE__ */ new Set();
+  let initialSelections = [];
+  let queued = "";
+  let active;
+  let subscribed = false;
+  let renderComplete = false;
+  let finished = false;
+  let totalBytes = 0;
+  let notify;
+  let timer;
+  let resolveDone;
+  let rejectDone;
+  const done = new Promise((resolve, reject) => {
+    resolveDone = resolve;
+    rejectDone = reject;
+  });
+  const cleanupChild = (child) => {
+    try {
+      child.unsubscribe();
+    } catch {
+    }
+    try {
+      child.release();
+    } catch {
+    }
+  };
+  const fail = (error) => {
+    if (finished) return;
+    finished = true;
+    if (timer !== void 0) clearTimeout(timer);
+    for (const child of children) {
+      try {
+        child.source.cancel?.(error);
+      } catch {
+      }
+      cleanupChild(child);
+    }
+    rejectDone(error);
+  };
+  const maybeDone = () => {
+    if (finished || !renderComplete || active !== void 0 || queued !== "") return;
+    for (const child of children) if (!child.done) return;
+    finished = true;
+    if (timer !== void 0) clearTimeout(timer);
+    for (const child of children) cleanupChild(child);
+    resolveDone();
+  };
+  const takeInitialSelections = () => {
+    const selections = initialSelections;
+    initialSelections = void 0;
+    let html = "";
+    for (const { identity, attempt } of selections ?? []) {
+      if (attempt.signal.aborted) continue;
+      const script = streamedSignalSelectionScript(identity, options.nonce);
+      const bytes = new TextEncoder().encode(script).byteLength;
+      if (bytes > budget.maxFrameBytes || totalBytes + bytes > budget.maxTotalBytes) {
+        const error = new Error("Automatic streamed signals exceeded their byte budget.");
+        fail(error);
+        throw error;
+      }
+      totalBytes += bytes;
+      html += script;
+    }
+    return html;
+  };
+  const pump = () => {
+    if (!subscribed || finished || active !== void 0 || queued !== "") return;
+    if (initialSelections !== void 0) {
+      try {
+        queued = takeInitialSelections();
+      } catch {
+        return;
+      }
+      if (queued !== "") {
+        notify?.();
+        return;
+      }
+    }
+    for (const child of children) {
+      const html = child.source.take();
+      if (html === "") continue;
+      const bytes = new TextEncoder().encode(html).byteLength;
+      if (bytes > budget.maxFrameBytes || totalBytes + bytes > budget.maxTotalBytes) {
+        fail(new Error("Automatic streamed signals exceeded their byte budget."));
+        return;
+      }
+      totalBytes += bytes;
+      active = child;
+      queued = html;
+      notify?.();
+      return;
+    }
+    maybeDone();
+  };
+  const addChild = (source, release, attempt) => {
+    const child = {
+      source,
+      release,
+      unsubscribe: () => {
+      },
+      ...attempt === void 0 ? {} : { attempt },
+      done: false
+    };
+    children.push(child);
+    child.unsubscribe = source.subscribe(pump);
+    source.done.then(
+      () => {
+        child.done = true;
+        pump();
+      },
+      (error) => {
+        if (child.attempt !== void 0 && !child.attempt.isCurrent()) {
+          child.done = true;
+          pump();
+        } else fail(error);
+      }
+    );
+  };
+  if (external !== void 0) addChild(external, () => {
+  });
+  return {
+    takeInitialSelections,
+    createSignalAttemptObservations: createServerSignalQueryAttemptObservations,
+    get streamedRenderer() {
+      return external?.streamedRenderer === true || children.some((child) => child.attempt !== void 0) ? true : void 0;
+    },
+    observeSignalAttempt(attempt, run) {
+      if (finished || !attempt.isCurrent()) {
+        attempt.release();
+        return;
+      }
+      const attemptKey = JSON.stringify([
+        attempt.ownerKey,
+        attempt.instanceKey,
+        attempt.nodeKey,
+        attempt.selectionKey,
+        attempt.attempt
+      ]);
+      if (observedAttempts.has(attemptKey)) {
+        attempt.release();
+        return;
+      }
+      if (children.length >= 256) {
+        attempt.release();
+        fail(new Error("Automatic streamed signals exceeded their channel budget."));
+        return;
+      }
+      observedAttempts.add(attemptKey);
+      if (timer === void 0) {
+        timer = setTimeout(
+          () => fail(new Error("Automatic streamed signals timed out.")),
+          budget.timeoutMs
+        );
+      }
+      const identity = {
+        protocol: 1,
+        buildId: options.buildId,
+        documentId: options.documentId,
+        ownerKey: attempt.ownerKey,
+        instanceKey: attempt.instanceKey,
+        nodeKey: attempt.nodeKey,
+        selectionKey: attempt.selectionKey,
+        selectionGeneration,
+        attempt: attempt.attempt
+      };
+      initialSelections?.push({ identity, attempt });
+      const source = createStreamedSignalInjection(identity, attempt.result, {
+        signal: attempt.signal,
+        run,
+        nonce: options.nonce,
+        announceSelection: initialSelections === void 0,
+        maxFrameBytes: budget.maxFrameBytes,
+        maxTotalBytes: budget.maxTotalBytes,
+        timeoutMs: budget.timeoutMs
+      });
+      addChild(source, attempt.release, attempt);
+      pump();
+    },
+    take() {
+      const html = queued;
+      queued = "";
+      return html;
+    },
+    subscribe(callback) {
+      notify = callback;
+      subscribed = true;
+      pump();
+      return () => {
+        if (notify === callback) notify = void 0;
+      };
+    },
+    accepted() {
+      const child = active;
+      active = void 0;
+      child?.source.accepted?.();
+      pump();
+    },
+    cancel: fail,
+    done,
+    renderComplete() {
+      renderComplete = true;
+      for (const child of children) child.source.renderComplete?.();
+      maybeDone();
+    }
+  };
+}
+export {
+  createAutomaticStreamedSignalInjection,
+  createStreamedRendererFrameStream,
+  createStreamedSignalInjection,
+  createStreamedSignalResultFrames,
+  streamedRendererFrameScript
+};

package/dist/server-call.d.ts

@@ -0,0 +1,41 @@
+/** Trusted, request-local capabilities. None of these fields are RPC arguments. */
+export interface ServerCallContext<Viewer = unknown> {
+    readonly request: Request;
+    readonly signal: AbortSignal;
+    readonly viewer: Viewer;
+    readonly platform?: unknown;
+}
+/** Local caller options; the compiler never serializes these into RPC arguments. */
+export interface ServerCallOptions {
+    signal?: AbortSignal;
+}
+export interface ServerFunctionTarget {
+    readonly id: string;
+    readonly module: string;
+    readonly export: string;
+}
+/** The host must authorize each invocation inside its own async request store. */
+export interface ServerCallHost {
+    invoke<T>(target: ServerFunctionTarget, options: ServerCallOptions, execute: (context: ServerCallContext) => T): T | Promise<T>;
+}
+export interface ServerCallContextSource {
+    getStore(): ServerCallHost | undefined;
+}
+type CallerArguments<Args extends unknown[]> = Args extends [...infer Input, unknown] ? [...Input, options?: ServerCallOptions] : never;
+export type ServerFunction<Fn extends (...args: any[]) => any> = (...args: CallerArguments<Parameters<Fn>>) => Promise<Awaited<ReturnType<Fn>>>;
+export declare class InvalidServerFunctionPayloadError extends Error {
+    readonly code = "OCTANE_INVALID_RPC_PAYLOAD";
+    constructor(cause?: unknown);
+}
+/** @internal Host integration; the source contains no process-global request value. */
+export declare function __setServerCallContextSource(source: ServerCallContextSource): void;
+/** @internal Compiler target for exports with a final ServerCallContext parameter. */
+export declare function __registerServerFunction<Fn extends (...args: any[]) => any>(fn: Fn, contextIndex: number, target: ServerFunctionTarget): ServerFunction<Fn>;
+/**
+ * @internal Call a registered export in-process with the same per-invocation
+ * authorization as RPC. Returning/aliasing the export retains this wrapper.
+ */
+export declare function __serverCall(fn: (...args: any[]) => unknown, args: unknown[], options?: ServerCallOptions): Promise<unknown>;
+/** @internal Used only after the host has authorized this particular invocation. */
+export declare function invokeServerFunction(fn: Function, args: unknown[], context?: ServerCallContext): unknown;
+export {};

package/dist/server-call.js

@@ -0,0 +1,75 @@
+const SERVER_FUNCTION = /* @__PURE__ */ Symbol.for("octane.server.function");
+const SERVER_CALL_SOURCE = /* @__PURE__ */ Symbol.for("octane.server.call-context");
+const globals = globalThis;
+class InvalidServerFunctionPayloadError extends Error {
+  code = "OCTANE_INVALID_RPC_PAYLOAD";
+  constructor(cause) {
+    super("Invalid server function arguments", { cause });
+    this.name = "InvalidServerFunctionPayloadError";
+  }
+}
+function __setServerCallContextSource(source) {
+  globals[SERVER_CALL_SOURCE] = source;
+}
+function registration(fn) {
+  return fn[SERVER_FUNCTION];
+}
+function __registerServerFunction(fn, contextIndex, target) {
+  if (!Number.isSafeInteger(contextIndex) || contextIndex < 0) {
+    throw new TypeError("Invalid server function context position");
+  }
+  const registered = Object.freeze({ fn, contextIndex, target: Object.freeze({ ...target }) });
+  const callable = (...args) => {
+    let options;
+    if (args.length === contextIndex + 1) {
+      options = args.pop();
+    }
+    return __serverCall(callable, args, options);
+  };
+  Object.defineProperty(callable, SERVER_FUNCTION, { value: registered });
+  return callable;
+}
+async function __serverCall(fn, args, options = {}) {
+  const registered = registration(fn);
+  if (registered === void 0) {
+    throw new TypeError("The server function is not registered");
+  }
+  if (options === null || typeof options !== "object" || Object.keys(options).some((key) => key !== "signal") || options.signal !== void 0 && !(options.signal instanceof AbortSignal)) {
+    throw new TypeError("Server function options accept only a local AbortSignal");
+  }
+  if (args.length > registered.contextIndex) {
+    throw new InvalidServerFunctionPayloadError();
+  }
+  options.signal?.throwIfAborted();
+  const host = globals[SERVER_CALL_SOURCE]?.getStore();
+  if (host === void 0) {
+    throw new Error("A contextual server function requires an active server request");
+  }
+  return host.invoke(
+    registered.target,
+    options,
+    (context) => invokeServerFunction(fn, args, context)
+  );
+}
+function invokeServerFunction(fn, args, context) {
+  const registered = registration(fn);
+  if (registered === void 0) return fn.apply(null, args);
+  if (context === void 0) {
+    throw new Error("A contextual server function requires trusted request context");
+  }
+  if (args.length > registered.contextIndex) {
+    throw new InvalidServerFunctionPayloadError();
+  }
+  context.signal.throwIfAborted();
+  const input = args.slice();
+  while (input.length < registered.contextIndex) input.push(void 0);
+  input.push(Object.freeze({ ...context }));
+  return registered.fn.apply(null, input);
+}
+export {
+  InvalidServerFunctionPayloadError,
+  __registerServerFunction,
+  __serverCall,
+  __setServerCallContextSource,
+  invokeServerFunction
+};

package/dist/server-rpc-batch-client.d.ts

@@ -0,0 +1,7 @@
+import type { ServerCallOptions } from './server-call.js';
+import { type ServerCallBatchOptions, type ServerResultLimits } from './server-rpc-protocol.js';
+export declare const SERVER_BATCH_CONTENT_TYPE = "application/x-octane-rpc-batch+ndjson";
+export type { ServerCallBatchOptions } from './server-rpc-protocol.js';
+export declare function batchServerCalls<T>(options: ServerCallBatchOptions, callback: () => T): T;
+/** @internal Called only after local argument encoding and abort validation. */
+export declare function enqueueServerCall(hash: string, body: string, options: ServerCallOptions, limits?: ServerResultLimits): Promise<unknown> | undefined;