octane 0.2.11 → 0.2.13

package/dist/cjs/server-rpc-batch-client.cjs

@@ -0,0 +1,141 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var server_rpc_batch_client_exports = {};
+__export(server_rpc_batch_client_exports, {
+  SERVER_BATCH_CONTENT_TYPE: () => SERVER_BATCH_CONTENT_TYPE,
+  batchServerCalls: () => batchServerCalls,
+  enqueueServerCall: () => enqueueServerCall
+});
+module.exports = __toCommonJS(server_rpc_batch_client_exports);
+var import_server_rpc_stream_client = require("./server-rpc-stream-client.cjs");
+var import_server_rpc_protocol = require("./server-rpc-protocol.cjs");
+const SERVER_BATCH_CONTENT_TYPE = "application/x-octane-rpc-batch+ndjson";
+let collecting;
+function batchServerCalls(options, callback) {
+  (0, import_server_rpc_protocol.validateServerCallBatch)(options);
+  const previous = collecting;
+  collecting = { options: { ...options }, members: [] };
+  try {
+    return callback();
+  } finally {
+    collecting = previous;
+  }
+}
+function enqueueServerCall(hash, body, options, limits) {
+  const batch = collecting;
+  if (batch === void 0 || limits !== void 0) return void 0;
+  if (batch.members.length === 32) {
+    collecting = { options: batch.options, members: [] };
+    return enqueueServerCall(hash, body, options);
+  }
+  if (batch.members.length === 0)
+    queueMicrotask(() => {
+      void dispatch(batch);
+    });
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      if (member.settled) return;
+      member.settled = true;
+      member.dispose();
+      reject(new import_server_rpc_protocol.ServerCallUncertainError(options.signal?.reason));
+    };
+    const member = {
+      hash,
+      body,
+      signal: options.signal,
+      resolve,
+      reject,
+      settled: false,
+      dispose: () => options.signal?.removeEventListener("abort", abort)
+    };
+    options.signal?.addEventListener("abort", abort, { once: true });
+    batch.members.push(member);
+    if (options.signal?.aborted) abort();
+  });
+}
+async function dispatch(batch) {
+  const members = batch.members.filter((member) => !member.settled);
+  if (members.length === 0) return;
+  const limits = (0, import_server_rpc_protocol.serverResultLimits)(batch.options);
+  const transport = new AbortController();
+  let definitiveRejection = false;
+  const timer = setTimeout(
+    () => transport.abort(new DOMException("Server batch timed out", "TimeoutError")),
+    limits.timeoutMs
+  );
+  try {
+    const response = await fetch(
+      new URL("/_$_ripple_rpc_$_/" + members[0].hash, globalThis.location.href).href,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: SERVER_BATCH_CONTENT_TYPE },
+        body: JSON.stringify([1, members.map((member, id) => [id, member.hash, member.body])]),
+        signal: transport.signal
+      }
+    );
+    if (!response.ok || response.headers.get("content-type")?.split(";", 1)[0] !== SERVER_BATCH_CONTENT_TYPE) {
+      definitiveRejection = !response.ok && response.headers.get("Octane-RPC-Outcome") === "rejected";
+      try {
+        void response.body?.cancel().catch(() => {
+        });
+      } catch {
+      }
+      throw new Error("Server-call batching was rejected or is unavailable");
+    }
+    const result = await (0, import_server_rpc_stream_client.readServerResult)(response, { ...limits, signal: transport.signal });
+    if (result === null || typeof result !== "object" || !(Symbol.asyncIterator in result)) {
+      throw new Error("Invalid server batch result");
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for await (const frame of result) {
+      if (!Array.isArray(frame) || frame.length !== 3 || !Number.isSafeInteger(frame[0]) || frame[0] < 0 || frame[0] >= members.length || seen.has(frame[0]) || !["value", "rejected", "uncertain"].includes(frame[1]) || frame[1] !== "value" && typeof frame[2] !== "string") {
+        throw new Error("Invalid or duplicate server batch member");
+      }
+      seen.add(frame[0]);
+      const member = members[frame[0]];
+      if (member.settled) continue;
+      member.settled = true;
+      member.dispose();
+      if (frame[1] === "value") member.resolve(frame[2]);
+      else {
+        const error = new Error(frame[2]);
+        member.reject(frame[1] === "rejected" ? error : new import_server_rpc_protocol.ServerCallUncertainError(error));
+      }
+    }
+    if (seen.size !== members.length) throw new Error("Server batch ended with missing members");
+  } catch (error) {
+    for (const member of members) {
+      if (member.settled) continue;
+      member.settled = true;
+      member.dispose();
+      member.reject(
+        definitiveRejection || error instanceof import_server_rpc_protocol.ServerCallUncertainError ? error : new import_server_rpc_protocol.ServerCallUncertainError(error)
+      );
+    }
+  } finally {
+    clearTimeout(timer);
+    transport.abort();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SERVER_BATCH_CONTENT_TYPE,
+  batchServerCalls,
+  enqueueServerCall
+});

package/dist/cjs/server-rpc-client.cjs

@@ -32,37 +32,104 @@ __export(server_rpc_client_exports, {
 });
 module.exports = __toCommonJS(server_rpc_client_exports);
 var devalue = __toESM(require("devalue"), 1);
-async function __serverRpc(hash, args) {
-  let response;
-  try {
-    response = await fetch("/_$_ripple_rpc_$_/" + hash, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: devalue.stringify(args)
-    });
-  } catch {
-    throw new Error("An error occurred while trying to call the Octane server function.");
+var import_server_rpc_protocol = require("./server-rpc-protocol.cjs");
+var import_server_rpc_stream_client = require("./server-rpc-stream-client.cjs");
+var import_server_rpc_batch_client = require("./server-rpc-batch-client.cjs");
+async function __serverRpc(hash, args, options = {}, stream = false, limits) {
+  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");
+  options.signal?.throwIfAborted();
+  const resolvedLimits = stream ? (0, import_server_rpc_protocol.serverResultLimits)(limits) : void 0;
+  const payload = stream ? (0, import_server_rpc_protocol.encodeServerArguments)(args) : devalue.stringify(args);
+  if (stream) {
+    const batched = (0, import_server_rpc_batch_client.enqueueServerCall)(hash, payload, options, limits);
+    if (batched !== void 0) return batched;
   }
-  if (!response.ok) {
-    let message = `Server function call failed with status ${response.status}`;
-    const body2 = await response.text().catch(() => "");
-    if (body2) {
-      try {
-        const parsed = JSON.parse(body2);
-        message = typeof parsed?.error === "string" && parsed.error ? parsed.error : body2;
-      } catch {
-        message = body2;
+  const deadline = resolvedLimits === void 0 ? void 0 : Date.now() + resolvedLimits.timeoutMs;
+  const cancellation = resolvedLimits === void 0 ? void 0 : new AbortController();
+  const timer = resolvedLimits === void 0 ? void 0 : setTimeout(() => {
+    cancellation.abort(new DOMException("Server function timed out", "TimeoutError"));
+  }, resolvedLimits.timeoutMs);
+  const signal = cancellation === void 0 ? options.signal : options.signal === void 0 ? cancellation.signal : AbortSignal.any([options.signal, cancellation.signal]);
+  try {
+    let response;
+    try {
+      response = await fetch(new URL("/_$_ripple_rpc_$_/" + hash, globalThis.location.href).href, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...stream ? { Accept: import_server_rpc_protocol.SERVER_RESULT_CONTENT_TYPE } : {}
+        },
+        body: payload,
+        signal
+      });
+    } catch (cause) {
+      throw new import_server_rpc_protocol.ServerCallUncertainError(
+        new Error("An error occurred while trying to call the Octane server function.", { cause })
+      );
+    }
+    if (!response.ok) {
+      let message = `Server function call failed with status ${response.status}`;
+      let body2 = "";
+      if (stream) {
+        try {
+          void response.body?.cancel().catch(() => {
+          });
+        } catch {
+        }
+      } else {
+        body2 = await response.text().catch(() => "");
       }
+      if (body2) {
+        try {
+          const parsed = JSON.parse(body2);
+          message = typeof parsed?.error === "string" && parsed.error ? parsed.error : body2;
+        } catch {
+          message = body2;
+        }
+      }
+      const error = Object.assign(new Error(message), { status: response.status });
+      throw response.headers.get("Octane-RPC-Outcome") === "rejected" ? error : new import_server_rpc_protocol.ServerCallUncertainError(error);
     }
-    throw new Error(message);
-  }
-  const body = await response.text();
-  if (body === "") {
-    throw new Error(
-      "The server function endpoint returned an empty response. Is the Octane server running?"
-    );
+    if (stream) {
+      if (response.headers.get("content-type")?.split(";", 1)[0] !== import_server_rpc_protocol.SERVER_RESULT_CONTENT_TYPE) {
+        void response.body?.cancel().catch(() => {
+        });
+        throw new import_server_rpc_protocol.ServerCallUncertainError(
+          new Error("The server does not support the requested result protocol")
+        );
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        void response.body?.cancel().catch(() => {
+        });
+        throw new import_server_rpc_protocol.ServerCallUncertainError(
+          new DOMException("Server function timed out", "TimeoutError")
+        );
+      }
+      return await (0, import_server_rpc_stream_client.readServerResult)(response, { ...resolvedLimits, timeoutMs: remaining, signal });
+    }
+    let body;
+    try {
+      body = await response.text();
+    } catch (error) {
+      throw new import_server_rpc_protocol.ServerCallUncertainError(error);
+    }
+    if (body === "") {
+      throw new import_server_rpc_protocol.ServerCallUncertainError(
+        new Error(
+          "The server function endpoint returned an empty response. Is the Octane server running?"
+        )
+      );
+    }
+    try {
+      return devalue.parse(body).value;
+    } catch (error) {
+      throw new import_server_rpc_protocol.ServerCallUncertainError(error);
+    }
+  } finally {
+    clearTimeout(timer);
   }
-  return devalue.parse(body).value;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/cjs/server-rpc-protocol.cjs

@@ -0,0 +1,141 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var server_rpc_protocol_exports = {};
+__export(server_rpc_protocol_exports, {
+  SERVER_RESULT_CONTENT_TYPE: () => SERVER_RESULT_CONTENT_TYPE,
+  ServerCallUncertainError: () => ServerCallUncertainError,
+  decodeServerArguments: () => decodeServerArguments,
+  decodeServerResultFrame: () => decodeServerResultFrame,
+  encodeServerArguments: () => encodeServerArguments,
+  encodeServerResultFrame: () => encodeServerResultFrame,
+  serverResultLimits: () => serverResultLimits,
+  serverResultReader: () => serverResultReader,
+  validateServerCallBatch: () => validateServerCallBatch
+});
+module.exports = __toCommonJS(server_rpc_protocol_exports);
+var import_data_encoding = require("./data-encoding.cjs");
+const SERVER_RESULT_CONTENT_TYPE = "application/x-octane-rpc+ndjson";
+function encodeServerArguments(args) {
+  return JSON.stringify([1, (0, import_data_encoding.encodeSignalValue)(args)]);
+}
+function decodeServerArguments(body) {
+  const envelope = JSON.parse(body);
+  if (!Array.isArray(envelope) || envelope.length !== 2 || envelope[0] !== 1) {
+    throw new Error("Invalid server argument protocol");
+  }
+  const args = (0, import_data_encoding.decodeSignalValue)(envelope[1]);
+  if (!Array.isArray(args)) throw new Error("Invalid server arguments");
+  return args;
+}
+class ServerCallUncertainError extends Error {
+  code = "OCTANE_RPC_UNCERTAIN";
+  constructor(cause) {
+    super(cause instanceof Error ? cause.message : "Server function outcome is uncertain", {
+      cause
+    });
+    this.name = "ServerCallUncertainError";
+  }
+}
+function validateServerCallBatch(options) {
+  if (options.kind !== "independent-reads" || !options.authority || !options.document) {
+    throw new TypeError(
+      "A server-call batch requires independent reads and authority/document keys"
+    );
+  }
+  serverResultLimits(options);
+}
+function serverResultLimits(limits = {}) {
+  const result = {
+    maxFrameBytes: limits.maxFrameBytes ?? 1024 * 1024,
+    maxTotalBytes: limits.maxTotalBytes ?? 16 * 1024 * 1024,
+    timeoutMs: limits.timeoutMs ?? 3e4
+  };
+  for (const value of Object.values(result)) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new RangeError("Server result limits must be positive safe integers");
+    }
+  }
+  if (result.maxFrameBytes > result.maxTotalBytes) {
+    throw new RangeError("A server result frame cannot exceed the total response budget");
+  }
+  return result;
+}
+function encodeServerResultFrame(sequence, frame) {
+  const payload = frame.kind === "value" ? (0, import_data_encoding.encodeSignalValue)(frame.value) : frame.kind === "error" ? frame.error : null;
+  return new TextEncoder().encode(JSON.stringify([1, sequence, frame.kind, payload]) + "\n");
+}
+function decodeServerResultFrame(line, sequence) {
+  const frame = JSON.parse(line);
+  if (!Array.isArray(frame) || frame.length !== 4 || frame[0] !== 1 || frame[1] !== sequence) {
+    throw new Error("Invalid or out-of-order server result frame");
+  }
+  const [, , kind, payload] = frame;
+  if (kind === "value") {
+    return { kind, value: (0, import_data_encoding.decodeSignalValue)(payload) };
+  }
+  if (kind === "error" && typeof payload === "string") return { kind, error: payload };
+  if ((kind === "stream" || kind === "complete") && payload === null) return { kind };
+  throw new Error("Invalid server result frame");
+}
+function serverResultReader(reader, limits) {
+  let chunk = new Uint8Array(0);
+  let offset = 0;
+  let sequence = 0;
+  let totalBytes = 0;
+  return async () => {
+    const parts = [];
+    let bytes = 0;
+    while (true) {
+      if (offset === chunk.length) {
+        const next = await reader.read();
+        if (next.done) throw new Error("Server result ended without a terminal frame");
+        chunk = next.value;
+        offset = 0;
+      }
+      const newline = chunk.indexOf(10, offset);
+      const end = newline === -1 ? chunk.length : newline + 1;
+      const part = chunk.subarray(offset, end);
+      bytes += part.length;
+      totalBytes += part.length;
+      if (bytes > limits.maxFrameBytes || totalBytes > limits.maxTotalBytes) {
+        throw new Error("Server result exceeded its response budget");
+      }
+      parts.push(part);
+      offset = end;
+      if (newline !== -1) {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        const text = parts.map((value) => decoder.decode(value, { stream: true }));
+        text.push(decoder.decode());
+        return decodeServerResultFrame(text.join(""), sequence++);
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SERVER_RESULT_CONTENT_TYPE,
+  ServerCallUncertainError,
+  decodeServerArguments,
+  decodeServerResultFrame,
+  encodeServerArguments,
+  encodeServerResultFrame,
+  serverResultLimits,
+  serverResultReader,
+  validateServerCallBatch
+});

package/dist/cjs/server-rpc-stream-client.cjs

@@ -0,0 +1,118 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var server_rpc_stream_client_exports = {};
+__export(server_rpc_stream_client_exports, {
+  readServerResult: () => readServerResult
+});
+module.exports = __toCommonJS(server_rpc_stream_client_exports);
+var import_server_rpc_protocol = require("./server-rpc-protocol.cjs");
+async function readServerResult(response, options = {}) {
+  if (response.body === null)
+    throw new import_server_rpc_protocol.ServerCallUncertainError(new Error("Server function returned an empty response"));
+  const limits = (0, import_server_rpc_protocol.serverResultLimits)(options);
+  const reader = response.body.getReader();
+  const read = (0, import_server_rpc_protocol.serverResultReader)(reader, limits);
+  let finished = false;
+  let failure;
+  const cleanup = () => {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", abort);
+  };
+  const close = async () => {
+    if (finished) return;
+    finished = true;
+    cleanup();
+    try {
+      void reader.cancel().catch(() => {
+      });
+    } catch {
+    }
+    reader.releaseLock();
+  };
+  const abort = () => {
+    failure = new import_server_rpc_protocol.ServerCallUncertainError(
+      options.signal?.reason ?? new DOMException("Server function canceled", "AbortError")
+    );
+    void close();
+  };
+  const timer = setTimeout(() => {
+    failure = new import_server_rpc_protocol.ServerCallUncertainError(
+      new DOMException("Server function timed out", "TimeoutError")
+    );
+    void close();
+  }, limits.timeoutMs);
+  options.signal?.addEventListener("abort", abort, { once: true });
+  if (options.signal?.aborted) abort();
+  const next = async () => {
+    if (failure !== void 0) throw failure;
+    try {
+      const frame = await read();
+      if (failure !== void 0) throw failure;
+      if (frame.kind === "error") throw new Error(frame.error);
+      return frame;
+    } catch (error) {
+      await close();
+      throw failure ?? new import_server_rpc_protocol.ServerCallUncertainError(error);
+    }
+  };
+  try {
+    const first = await next();
+    if (first.kind === "value") {
+      if ((await next()).kind !== "complete") throw new Error("Invalid one-shot server result");
+      await close();
+      return first.value;
+    }
+    if (first.kind !== "stream") throw new Error("Invalid server result opening frame");
+    let claimed = false;
+    return {
+      [Symbol.asyncIterator]() {
+        if (claimed) throw new Error("A server result stream supports one consumer");
+        claimed = true;
+        let pulls = Promise.resolve();
+        const pull = async () => {
+          if (failure !== void 0) throw failure;
+          if (finished) return { done: true, value: void 0 };
+          const frame = await next();
+          if (frame.kind === "value") return { done: false, value: frame.value };
+          await close();
+          if (frame.kind !== "complete") throw new Error("Invalid server result continuation");
+          return { done: true, value: void 0 };
+        };
+        return {
+          next() {
+            const result = pulls.then(pull, pull);
+            pulls = result;
+            return result;
+          },
+          async return() {
+            await close();
+            return { done: true, value: void 0 };
+          }
+        };
+      }
+    };
+  } catch (error) {
+    await close();
+    throw error instanceof import_server_rpc_protocol.ServerCallUncertainError ? error : new import_server_rpc_protocol.ServerCallUncertainError(error);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  readServerResult
+});