@jeffusion/bungee-core 5.10.0 → 5.11.0

package/dist/plugins/token-budget/control.js

@@ -1,4 +1,512 @@
 // @bun
+// packages/core/src/plugin-services/host-rpc.ts
+import { AsyncLocalStorage } from "async_hooks";
+
+// packages/core/src/plugin-services/wire-contract.ts
+import { isProxy } from "util/types";
+var RPC_JSON_MAX_BYTES = 64 * 1024;
+var RPC_CONTRACT_MAX_BYTES = 256 * 1024;
+var JSON_MAX_DEPTH = 64;
+var SCHEMA_MAX_DEPTH = 64;
+var RPC_MAX_TIMEOUT_MS = 300000;
+var RPC_MAX_METHODS = 128;
+var RPC_SERVICE_ID = /^[a-z][a-z0-9.-]{0,127}$/;
+var RPC_METHOD_NAME = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;
+var RPC_CALL_PURPOSES = new Set(["bootstrap", "background", "management", "request", "attempt"]);
+var RPC_COMMAND_DEDUPLICATION = new Set(["local-transaction", "external-contract", "none"]);
+var RPC_COMMAND_POLICY_KEYS = new Set(["deduplication", "resultRetentionMs", "quotaBytes", "maxResultBytes"]);
+var CONTRACT_KEYS = ["id", "version", "methods"];
+var METHOD_KEYS = [
+  "kind",
+  "input",
+  "output",
+  "purposes",
+  "timeoutMs",
+  "maxInputBytes",
+  "maxOutputBytes",
+  "command"
+];
+
+class RpcProtocolError extends Error {
+  code;
+  name = "RpcProtocolError";
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+function failData(category) {
+  throw new RpcProtocolError("invalid_data", `invalid_data in ${category}`);
+}
+function failSize() {
+  throw new RpcProtocolError("size_limit", "size_limit: JSON value exceeds the byte limit");
+}
+function failContract(reason) {
+  throw new RpcProtocolError("invalid_contract", `invalid_contract: ${reason}`);
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
+  if (isProxy(value))
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function isPositiveSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isNonNegativeSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function hasLoneSurrogate(value) {
+  for (let index = 0;index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 55296 && code <= 56319) {
+      if (index + 1 >= value.length)
+        return true;
+      const next = value.charCodeAt(index + 1);
+      if (next < 56320 || next > 57343)
+        return true;
+      index += 1;
+    } else if (code >= 56320 && code <= 57343) {
+      return true;
+    }
+  }
+  return false;
+}
+function isArrayIndex(key, length) {
+  if (!/^(?:0|[1-9]\d*)$/.test(key))
+    return false;
+  const index = Number(key);
+  return Number.isSafeInteger(index) && index >= 0 && index < length;
+}
+function assertKnownKeys(input, allowed, category) {
+  for (const key of Object.keys(input)) {
+    if (!allowed.includes(key))
+      failContract(`unknown ${category} field`);
+  }
+}
+function spend(budget, bytes) {
+  budget.left -= bytes;
+  if (budget.left < 0)
+    failSize();
+}
+function snapshot(value, depth, ancestors, budget) {
+  if (value === null) {
+    spend(budget, 4);
+    return null;
+  }
+  if (typeof value === "boolean") {
+    spend(budget, value ? 4 : 5);
+    return value;
+  }
+  if (typeof value === "string") {
+    if (hasLoneSurrogate(value))
+      failData("string");
+    spend(budget, Buffer.byteLength(value, "utf8") + 2);
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      failData("number");
+    spend(budget, 1);
+    return value;
+  }
+  if (typeof value !== "object")
+    failData("json");
+  const object = value;
+  if (isProxy(object))
+    failData("json");
+  if (ancestors.has(object))
+    failData("json");
+  const nextDepth = depth + 1;
+  if (nextDepth > JSON_MAX_DEPTH)
+    failData("json");
+  if (Array.isArray(object)) {
+    if (Object.getPrototypeOf(object) !== Array.prototype)
+      failData("array");
+    const lengthDescriptor = Object.getOwnPropertyDescriptor(object, "length");
+    if (!lengthDescriptor || !("value" in lengthDescriptor) || typeof lengthDescriptor.value !== "number") {
+      failData("array");
+    }
+    const length = lengthDescriptor.value;
+    if (!Number.isSafeInteger(length) || length < 0)
+      failData("array");
+    if (length > budget.left)
+      failSize();
+    spend(budget, 2);
+    if (length > 1)
+      spend(budget, length - 1);
+    ancestors.add(object);
+    const items = new Array(length);
+    let count = 0;
+    for (const key of Reflect.ownKeys(object)) {
+      if (key === "length")
+        continue;
+      if (typeof key !== "string" || !isArrayIndex(key, length))
+        failData("array");
+      const descriptor = Object.getOwnPropertyDescriptor(object, key);
+      if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+        failData("array");
+      items[Number(key)] = snapshot(descriptor.value, nextDepth, ancestors, budget);
+      count += 1;
+    }
+    if (count !== length)
+      failData("array");
+    ancestors.delete(object);
+    return items;
+  }
+  const prototype = Object.getPrototypeOf(object);
+  if (prototype !== Object.prototype && prototype !== null)
+    failData("object");
+  const keys = Reflect.ownKeys(object);
+  if (keys.length > budget.left)
+    failSize();
+  spend(budget, 2);
+  if (keys.length > 1)
+    spend(budget, keys.length - 1);
+  ancestors.add(object);
+  const result = {};
+  for (const key of keys) {
+    if (typeof key !== "string")
+      failData("object");
+    if (hasLoneSurrogate(key))
+      failData("object");
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+      failData("object");
+    spend(budget, Buffer.byteLength(key, "utf8") + 3);
+    Object.defineProperty(result, key, {
+      value: snapshot(descriptor.value, nextDepth, ancestors, budget),
+      enumerable: true,
+      writable: true,
+      configurable: true
+    });
+  }
+  ancestors.delete(object);
+  return result;
+}
+function snapshotPureInput(input) {
+  try {
+    const pure = snapshot(input, 0, new Set, { left: RPC_CONTRACT_MAX_BYTES });
+    if (Buffer.byteLength(JSON.stringify(pure), "utf8") > RPC_CONTRACT_MAX_BYTES)
+      failContract("input must be bounded pure JSON data");
+    return pure;
+  } catch (error) {
+    if (error instanceof RpcProtocolError && (error.code === "invalid_data" || error.code === "size_limit")) {
+      failContract("input must be bounded pure JSON data");
+    }
+    throw error;
+  }
+}
+function checkOptionalNonNegative(value, field) {
+  if (value === undefined)
+    return;
+  if (!isNonNegativeSafeInteger(value))
+    failContract(`${field} must be a non-negative safe integer`);
+  return value;
+}
+function checkOptionalFinite(value, field) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "number" || !Number.isFinite(value))
+    failContract(`${field} must be a finite number`);
+  return value;
+}
+function checkSchema(input, depth, seen) {
+  if (depth > SCHEMA_MAX_DEPTH)
+    failContract("schema nesting exceeds the limit");
+  if (!isPlainObject(input))
+    failContract("schema must be a plain object");
+  if (seen.has(input))
+    failContract("schema must not contain cycles");
+  seen.add(input);
+  const type = input.type;
+  if (type === "string") {
+    assertKnownKeys(input, ["type", "minLength", "maxLength"], "schema");
+    const min = checkOptionalNonNegative(input.minLength, "minLength");
+    const max = checkOptionalNonNegative(input.maxLength, "maxLength");
+    if (min !== undefined && max !== undefined && min > max)
+      failContract("string minLength must not exceed maxLength");
+  } else if (type === "number") {
+    assertKnownKeys(input, ["type", "integer", "minimum", "maximum"], "schema");
+    if (input.integer !== undefined && typeof input.integer !== "boolean")
+      failContract("number integer flag must be boolean");
+    const min = checkOptionalFinite(input.minimum, "minimum");
+    const max = checkOptionalFinite(input.maximum, "maximum");
+    if (min !== undefined && max !== undefined && min > max)
+      failContract("number minimum must not exceed maximum");
+  } else if (type === "boolean") {
+    assertKnownKeys(input, ["type"], "schema");
+  } else if (type === "null") {
+    assertKnownKeys(input, ["type"], "schema");
+  } else if (type === "literal") {
+    assertKnownKeys(input, ["type", "value"], "schema");
+    if (!Object.prototype.hasOwnProperty.call(input, "value"))
+      failContract("literal schema requires a value");
+    try {
+      snapshot(input.value, 0, new Set, { left: Infinity });
+    } catch (error) {
+      if (error instanceof RpcProtocolError && error.code === "invalid_data") {
+        failContract("literal value must be pure JSON");
+      }
+      throw error;
+    }
+  } else if (type === "array") {
+    assertKnownKeys(input, ["type", "items", "maxItems"], "schema");
+    if (!Object.prototype.hasOwnProperty.call(input, "items"))
+      failContract("array schema requires items");
+    checkSchema(input.items, depth + 1, seen);
+    checkOptionalNonNegative(input.maxItems, "maxItems");
+  } else if (type === "object") {
+    assertKnownKeys(input, ["type", "properties", "optional"], "schema");
+    const properties = input.properties;
+    if (!isPlainObject(properties))
+      failContract("object schema requires a properties record");
+    for (const key of Object.keys(properties))
+      checkSchema(properties[key], depth + 1, seen);
+    const optional = input.optional;
+    if (optional !== undefined) {
+      if (!Array.isArray(optional))
+        failContract("object optional must be an array of field names");
+      const names = new Set;
+      for (const name of optional) {
+        if (typeof name !== "string")
+          failContract("object optional entries must be strings");
+        if (names.has(name))
+          failContract("object optional entries must be unique");
+        names.add(name);
+        if (!Object.prototype.hasOwnProperty.call(properties, name)) {
+          failContract("object optional names must exist in properties");
+        }
+      }
+    }
+  } else if (type === "record") {
+    assertKnownKeys(input, ["type", "values", "maxEntries"], "schema");
+    if (!Object.prototype.hasOwnProperty.call(input, "values"))
+      failContract("record schema requires values");
+    checkSchema(input.values, depth + 1, seen);
+    checkOptionalNonNegative(input.maxEntries, "maxEntries");
+  } else if (type === "union") {
+    assertKnownKeys(input, ["type", "variants"], "schema");
+    const variants = input.variants;
+    if (!Array.isArray(variants) || variants.length === 0) {
+      failContract("union schema requires a non-empty variants array");
+    }
+    for (const variant of variants)
+      checkSchema(variant, depth + 1, seen);
+  } else if (type === "json") {
+    assertKnownKeys(input, ["type", "maxBytes"], "schema");
+    if (input.maxBytes !== undefined && !isPositiveSafeInteger(input.maxBytes)) {
+      failContract("json schema maxBytes must be a positive safe integer");
+    }
+  } else {
+    failContract("unknown schema type");
+  }
+  seen.delete(input);
+}
+function checkByteLimit(value, field) {
+  if (value === undefined)
+    return;
+  if (!isPositiveSafeInteger(value) || value > RPC_JSON_MAX_BYTES) {
+    failContract(`${field} must be a positive integer no larger than the RPC envelope`);
+  }
+  return value;
+}
+function checkCommandPolicy(policy, maxOutputBytes) {
+  const keys = Object.keys(policy);
+  if (keys.length !== RPC_COMMAND_POLICY_KEYS.size || keys.some((key) => !RPC_COMMAND_POLICY_KEYS.has(key))) {
+    failContract("command policy fields are fixed");
+  }
+  const deduplication = policy.deduplication;
+  if (typeof deduplication !== "string" || !RPC_COMMAND_DEDUPLICATION.has(deduplication)) {
+    failContract("invalid command deduplication");
+  }
+  const retention = policy.resultRetentionMs;
+  if (retention !== null && !isPositiveSafeInteger(retention)) {
+    failContract("resultRetentionMs must be a positive integer or null");
+  }
+  const maxResultBytes = policy.maxResultBytes;
+  if (!isPositiveSafeInteger(maxResultBytes))
+    failContract("maxResultBytes must be a positive safe integer");
+  if (maxResultBytes > maxOutputBytes)
+    failContract("maxResultBytes must not exceed maxOutputBytes");
+  const quotaBytes = policy.quotaBytes;
+  if (!isPositiveSafeInteger(quotaBytes))
+    failContract("quotaBytes must be a positive safe integer");
+  if (quotaBytes < maxResultBytes)
+    failContract("quotaBytes must be able to hold maxResultBytes");
+}
+function checkMethod(definition) {
+  assertKnownKeys(definition, METHOD_KEYS, "method");
+  const kind = definition.kind;
+  if (kind !== "query" && kind !== "command")
+    failContract("method kind must be query or command");
+  checkSchema(definition.input, 0, new Set);
+  checkSchema(definition.output, 0, new Set);
+  const purposes = definition.purposes;
+  if (!Array.isArray(purposes) || purposes.length === 0)
+    failContract("purposes must be a non-empty array");
+  const seenPurposes = new Set;
+  for (const purpose of purposes) {
+    if (typeof purpose !== "string" || !RPC_CALL_PURPOSES.has(purpose))
+      failContract("invalid purpose");
+    if (seenPurposes.has(purpose))
+      failContract("purposes must be unique");
+    seenPurposes.add(purpose);
+  }
+  if (definition.timeoutMs !== undefined) {
+    if (!isPositiveSafeInteger(definition.timeoutMs) || definition.timeoutMs > RPC_MAX_TIMEOUT_MS) {
+      failContract("timeoutMs must be a positive integer no larger than the timeout bound");
+    }
+  }
+  checkByteLimit(definition.maxInputBytes, "maxInputBytes");
+  const maxOutputBytes = checkByteLimit(definition.maxOutputBytes, "maxOutputBytes");
+  const command = definition.command;
+  if (kind === "command") {
+    if (!isPlainObject(command))
+      failContract("command methods require an explicit command policy");
+    checkCommandPolicy(command, maxOutputBytes ?? RPC_JSON_MAX_BYTES);
+  } else if (command !== undefined) {
+    failContract("query methods must not declare a command policy");
+  }
+}
+function checkContract(contract) {
+  if (!isPlainObject(contract))
+    failContract("contract must be a plain object");
+  assertKnownKeys(contract, CONTRACT_KEYS, "contract");
+  if (typeof contract.id !== "string" || !RPC_SERVICE_ID.test(contract.id))
+    failContract("invalid service id");
+  if (!isPositiveSafeInteger(contract.version))
+    failContract("service version must be a positive safe integer");
+  const methods = contract.methods;
+  if (!isPlainObject(methods))
+    failContract("methods must be a plain object");
+  const names = Object.keys(methods);
+  if (names.length === 0)
+    failContract("service must declare at least one method");
+  if (names.length > RPC_MAX_METHODS)
+    failContract("service declares too many methods");
+  for (const name of names) {
+    if (!RPC_METHOD_NAME.test(name))
+      failContract("invalid method name");
+    const definition = methods[name];
+    if (!isPlainObject(definition))
+      failContract("method definition must be a plain object");
+    checkMethod(definition);
+  }
+}
+function deepFreeze(value) {
+  if (Array.isArray(value)) {
+    for (const item of value)
+      deepFreeze(item);
+    return Object.freeze(value);
+  }
+  if (isPlainObject(value)) {
+    for (const key of Object.keys(value))
+      deepFreeze(value[key]);
+    return Object.freeze(value);
+  }
+  return value;
+}
+function defineRpcService(contract) {
+  const pure = snapshotPureInput(contract);
+  checkContract(pure);
+  return deepFreeze(pure);
+}
+
+// packages/core/src/plugin-services/rpc-runtime.ts
+var PROCESSES = new Set(["control", "worker", "ingress"]);
+var SCOPES = new Set(["global", "binding"]);
+var PURPOSES = new Set(["bootstrap", "background", "management", "request", "attempt"]);
+var ENDPOINTS = new WeakMap;
+var REVOKED = new WeakMap;
+
+// packages/core/src/plugin-services/host-rpc.ts
+var SERVICE_ERROR_MESSAGES = {
+  unauthorized: "RPC call is not authorized",
+  not_ready: "RPC endpoint is not ready",
+  retired: "RPC endpoint is retiring",
+  revoked: "RPC endpoint generation was revoked",
+  unsupported_method: "RPC method is not published",
+  wrong_purpose: "RPC method is not published for this purpose",
+  invalid_input: "RPC input is not valid",
+  invalid_output: "RPC output is not valid",
+  invalid_operation_id: "RPC command operation id is invalid",
+  overloaded: "RPC runtime is at capacity",
+  cancelled: "RPC call was cancelled",
+  timeout: "RPC call deadline exceeded",
+  unknown: "RPC command outcome is unknown",
+  capability_unavailable: "RPC command execution is unavailable",
+  closed: "RPC runtime is closed",
+  failed: "RPC call failed",
+  conflict: "RPC command identity conflicts with an existing record",
+  expired: "RPC command result has expired",
+  pending: "RPC command is still pending",
+  rejected: "RPC command was rejected",
+  missing: "RPC command has no stored result",
+  storage_failure: "RPC command storage failed",
+  deadlock: "RPC call chain would deadlock",
+  call_depth_exceeded: "RPC call depth exceeded",
+  undeclared: "RPC service is not declared by the manifest",
+  unavailable: "RPC service is unavailable",
+  ambiguous_placement: "RPC service placement is ambiguous",
+  invalid_registration: "RPC registration is invalid"
+};
+var SERVICE_ERROR_CODES = new Set(Object.keys(SERVICE_ERROR_MESSAGES));
+var EMPTY_OPTIONS = Object.freeze({});
+var FRAME_STORE = new AsyncLocalStorage;
+var CALLEE_INFO = new WeakMap;
+// packages/core/src/plugin-services/peer-channel-protocol.ts
+var CHANNEL_REQUEST_MAX_BYTES = 4 * 1024;
+var CHANNEL_RESULT_MAX_BYTES = 60 * 1024;
+var CHANNEL_MAX_CHUNK_BYTES = 60 * 1024;
+var PLUGIN_CHANNEL_LANES = Object.freeze(["event", "snapshot", "stream"]);
+var ERROR_CODES = new Set([
+  "unavailable",
+  "ambiguous",
+  "unauthorized",
+  "invalid",
+  "overloaded",
+  "expired",
+  "conflict",
+  "gap",
+  "truncated",
+  "rejected",
+  "cancelled",
+  "closed",
+  "unknown",
+  "failed"
+]);
+var RPC_CALL_PURPOSES2 = new Set(["bootstrap", "background", "management", "request", "attempt"]);
+
+// packages/core/src/plugin-services/peer-channel-hub.ts
+var CHANNEL_MAX_TRANSFER_BUFFER_BYTES = 4 * CHANNEL_MAX_CHUNK_BYTES;
+var CHANNEL_MAX_TOTAL_BUFFER_BYTES = 16 * CHANNEL_MAX_CHUNK_BYTES;
+var CHANNEL_STREAM_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+var CHANNEL_STREAM_MAX_CREDIT_BYTES = 8 * CHANNEL_MAX_CHUNK_BYTES;
+var CHANNEL_STREAM_DEFAULT_CREDIT_BYTES = 4 * CHANNEL_MAX_CHUNK_BYTES;
+var CHANNEL_SNAPSHOT_MAX_BYTES = 64 * 1024 * 1024;
+var CHANNEL_EVENT_MAX_PAYLOAD_BYTES = 60 * 1024;
+var EMPTY = new Uint8Array(0);
+var HANDLE_REGISTRATIONS = new WeakMap;
+
+// packages/core/src/plugin-services/snapshot-store.ts
+var DEFAULT_CHUNK_BYTES = 60 * 1024;
+var SNAPSHOT_FAMILY_REFS = new Map;
+
+// packages/core/src/plugin-services.ts
+var CHANNEL_KINDS = new Set(["events", "snapshot", "stream"]);
+
+// plugins/token-budget/server/rpc.ts
+var command = { deduplication: "none", resultRetentionMs: null, quotaBytes: 65536, maxResultBytes: 65536 };
+var businessRpc = defineRpcService({ id: "token-budget.admission.v1", version: 1, methods: {
+  prepare: { kind: "command", input: { type: "object", properties: { snapshot: { type: "json" } } }, output: { type: "json" }, purposes: ["attempt"], command, timeoutMs: 15000 },
+  status: { kind: "query", input: { type: "null" }, output: { type: "json" }, purposes: ["attempt"], timeoutMs: 15000 },
+  cancel: { kind: "command", input: { type: "object", properties: { sent: { type: "literal", value: false } } }, output: { type: "json" }, purposes: ["attempt"], command, timeoutMs: 15000 },
+  settle: { kind: "command", input: { type: "object", properties: { result: { type: "json" }, costNanoUsd: { type: "union", variants: [{ type: "null" }, { type: "number", integer: true, minimum: 0 }] } }, optional: ["costNanoUsd"] }, output: { type: "json" }, purposes: ["attempt"], command, timeoutMs: 15000 }
+} });
+
 // plugins/token-budget/server/policy.ts
 function usdToNanoUsd(value) {
   if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || Number(value.toFixed(6)) !== value)
@@ -402,17 +910,24 @@ function createControl(host) {
   const policy = () => {
     return publication(state);
   };
+  if (host.services?.rpc) {
+    const handlers = Object.fromEntries(Object.keys(businessRpc.methods).map((method) => [method, (payload, context) => {
+      if (!host.runAdmissionOperation)
+        throw new Error("token-budget.host_admission_required");
+      return host.runAdmissionOperation(method, payload, host.resolveRpcCallee?.(context.callee), async (target) => {
+        const before = policy().version;
+        const result = stateRpc(method, payload, { state, requestId: target.requestId, attemptId: target.attemptId, principal: target.principal });
+        const next = policy();
+        if (next.version !== before || method === "settle")
+          await host.publishPolicy?.(next);
+        return result;
+      });
+    }]));
+    host.services.rpc.publish(businessRpc, handlers);
+  }
   return {
     policy,
     rpc: [],
-    stateRpc: async (method, payload, ctx) => {
-      const before = policy().version;
-      const result = stateRpc(method, payload, ctx);
-      const next = policy();
-      if (next.version !== before || method === "settle")
-        await host.publishPolicy?.(next);
-      return result;
-    },
     api: [{ path: "/keys/:keyId", methods: ["GET", "PUT"], handler: "keyPolicy", async invoke(ctx) {
       const keyId = decodeURIComponent(new URL(ctx.request.url).pathname.split("/").pop() ?? "");
       if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(keyId))
@@ -463,4 +978,4 @@ export {
   recoverUsage
 };
 
-//# debugId=E2EF5019BA9B61C964756E2164756E21
+//# debugId=15580272D1CF402D64756E2164756E21