From 1a777868f0d21b09852cbd93526d58a962c0f349 Mon Sep 17 00:00:00 2001 From: Mark Russell Date: Sun, 8 Nov 2026 00:44:54 -0500 Subject: [PATCH 1/4] WIP feat(client): a call limit takes a cost for each call, a capacity refusal is a 413 (CLI-122) WIP: this code is written against @mark1russell7/service 0.7.0 (systems#408: take(key, units), the union Refused). The dependency stays ^0.6.0 until 0.7.0 is on npm, thus this commit does not compile yet. The next commit raises it to ^0.7.0. - CallLimit.cost: a whole number of 1 or more, or a function of the call (default 1). admit() takes that many units of each limit. - A capacity refusal is PAYLOAD_TOO_LARGE, not retryable, with the metadata reason "capacity", units and capacity. HTTP answers 413 with both numbers in the body and no Retry-After. The HTTP client, the HTTP batch and the MCP face carry both numbers. WebSocket carries the metadata as it is. - ContractSpec.limits: the transport contract checks the capacity refusal on each server face. Co-Authored-By: Claude Opus 5.5 --- .changeset/call-cost.md | 16 +++++ .../src/transport/conformance.test.ts | 1 + .../client-mcp/src/transport/mcp-transport.ts | 5 ++ .../client/src/adapters/http/client/batch.ts | 6 +- .../src/adapters/http/client/transport.ts | 4 +- .../client/src/adapters/http/server/batch.ts | 4 ++ .../src/adapters/http/server/handler.ts | 4 ++ .../client/src/client/middleware/items.ts | 16 +++++ .../client/src/server/conformance.test.ts | 1 + packages/client/src/server/limits.test.ts | 53 +++++++++++++++- packages/client/src/server/limits.ts | 62 +++++++++++++++---- .../client/src/testing/transport-contract.ts | 19 ++++++ packages/client/test/api/public-api.txt | 2 + 13 files changed, 174 insertions(+), 19 deletions(-) create mode 100644 .changeset/call-cost.md diff --git a/.changeset/call-cost.md b/.changeset/call-cost.md new file mode 100644 index 000000000..c13fef03c --- /dev/null +++ b/.changeset/call-cost.md @@ -0,0 +1,16 @@ +--- +"@procedures/client": minor +"@procedures/mcp-server": patch +--- + +A call limit takes a cost for each call (roadmap CLI-122). The new field `cost` of `CallLimit` is a whole number of 1 or more, or a function of the call. The default is 1. A cost for each item keeps a batch within the limit. + +A call whose cost is over the burst or the limit of the policy gets a capacity refusal. Its code is `PAYLOAD_TOO_LARGE`, not retryable. The metadata gives `reason: "capacity"`, `units` and `capacity`. The HTTP face answers 413 with `units` and `capacity` in the body, and no `Retry-After`. The HTTP client, the batch, the WebSocket and the MCP faces carry both numbers. + +This release uses `@mark1russell7/service` 0.7.0. In that version, `Refused` is a union, and only a wait refusal has `retryAfter`. + +Migration steps: + +1. Code that reads `retryAfter` of a decision of `limiters()` examines `cause` first. A capacity refusal has `units` and `capacity` in place of `retryAfter`. +2. A store with pushes of batches sets `pushBatch` of `HybridStorage` within the capacity of the limit. A 413 with `units` and `capacity` lowers the cap of later pushes. +3. A host with a limit of each call gives no `cost`. Its limits keep one unit for each call. diff --git a/packages/client-mcp/src/transport/conformance.test.ts b/packages/client-mcp/src/transport/conformance.test.ts index dca130c7c..d05cddd0c 100644 --- a/packages/client-mcp/src/transport/conformance.test.ts +++ b/packages/client-mcp/src/transport/conformance.test.ts @@ -37,6 +37,7 @@ function serverOf(spec: ContractSpec): ProcedureServer { ...(spec.principalOf !== undefined && { principalOf: spec.principalOf }), ...(spec.errors !== undefined && { errors: spec.errors }), ...(spec.onError !== undefined && { onError: spec.onError }), + ...(spec.limits !== undefined && { limits: spec.limits }), }); } diff --git a/packages/client-mcp/src/transport/mcp-transport.ts b/packages/client-mcp/src/transport/mcp-transport.ts index 35ca92b06..22ffbe0b2 100644 --- a/packages/client-mcp/src/transport/mcp-transport.ts +++ b/packages/client-mcp/src/transport/mcp-transport.ts @@ -495,6 +495,10 @@ export class McpServerTransport implements ServerTransport { const reason = typeof response.metadata?.["reason"] === "string" ? response.metadata["reason"] : undefined; const wait = response.metadata?.["retry-after"]; const retryAfterMs = typeof wait === "number" && Number.isFinite(wait) && wait >= 0 ? wait : undefined; + // The units and the capacity of a refusal for its size (roadmap CLI-122) + const units = response.metadata?.["units"]; + const capacity = response.metadata?.["capacity"]; + const sized = typeof units === "number" && typeof capacity === "number" && Number.isFinite(units) && Number.isFinite(capacity); return { content: [ { @@ -508,6 +512,7 @@ export class McpServerTransport implements ServerTransport { retryable: response.status.retryable === true, ...(reason ? { reason } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), + ...(sized ? { units, capacity } : {}), }, }; } diff --git a/packages/client/src/adapters/http/client/batch.ts b/packages/client/src/adapters/http/client/batch.ts index 7f5c85d39..3d5004b8d 100644 --- a/packages/client/src/adapters/http/client/batch.ts +++ b/packages/client/src/adapters/http/client/batch.ts @@ -15,7 +15,7 @@ */ import type { Message, Metadata, ResponseItem, Status } from "../../../client/types.js"; -import { DELIVERY_METADATA_KEY, RETRY_AFTER_METADATA_KEY, isNotSentError } from "../../../client/middleware/items.js"; +import { DELIVERY_METADATA_KEY, RETRY_AFTER_METADATA_KEY, capacityFieldsOf, isNotSentError } from "../../../client/middleware/items.js"; import { StreamSequence, streamItemMetadata } from "../../sequence.js"; import { foldedErrorCode, PROTOCOL_HEADER, PROTOCOL_VERSION } from "../../../protocol.js"; import { toMs, type Duration } from "../../../duration.js"; @@ -454,7 +454,7 @@ export class HttpBatcher { } } -/** The metadata of an error body: the wait, the reason and the conflicts (R12, R25, CLI-16). */ +/** The metadata of an error body: the wait, the reason, the conflicts, the units and the capacity (R12, R25, CLI-16, CLI-122). */ function errorMetadataOf(body: unknown): Metadata { if (body === null || typeof body !== "object") return {}; const fields = body as { retryAfterMs?: unknown; reason?: unknown; conflicts?: unknown }; @@ -462,5 +462,5 @@ function errorMetadataOf(body: unknown): Metadata { if (typeof fields.retryAfterMs === "number" && Number.isFinite(fields.retryAfterMs) && fields.retryAfterMs >= 0) out[RETRY_AFTER_METADATA_KEY] = fields.retryAfterMs; if (typeof fields.reason === "string") out["reason"] = fields.reason; if (Array.isArray(fields.conflicts)) out["conflicts"] = fields.conflicts; - return out; + return { ...out, ...capacityFieldsOf(body) }; } diff --git a/packages/client/src/adapters/http/client/transport.ts b/packages/client/src/adapters/http/client/transport.ts index 53e7cb61f..fbd9f588c 100644 --- a/packages/client/src/adapters/http/client/transport.ts +++ b/packages/client/src/adapters/http/client/transport.ts @@ -12,7 +12,7 @@ import type { } from "../../../client/types.js"; import type { HttpTransportOptions } from "./types.js"; -import { DELIVERY_METADATA_KEY, RETRY_AFTER_METADATA_KEY, isNotSentError } from "../../../client/middleware/items.js"; +import { DELIVERY_METADATA_KEY, RETRY_AFTER_METADATA_KEY, capacityFieldsOf, isNotSentError } from "../../../client/middleware/items.js"; import { StreamSequence, streamItemMetadata } from "../../sequence.js"; import { HttpBatcher } from "./batch.js"; @@ -224,6 +224,8 @@ export class HttpTransport implements Transport { // The current items of a VERSION_CONFLICT error (roadmap CLI-16) const conflicts = (responseBody as { conflicts?: unknown } | null | undefined)?.conflicts; if (Array.isArray(conflicts)) metadata["conflicts"] = conflicts; + // The units and the capacity of a refusal for its size (roadmap CLI-122) + Object.assign(metadata, capacityFieldsOf(responseBody)); } // Yield single response item diff --git a/packages/client/src/adapters/http/server/batch.ts b/packages/client/src/adapters/http/server/batch.ts index cc2f25239..b304fd8d7 100644 --- a/packages/client/src/adapters/http/server/batch.ts +++ b/packages/client/src/adapters/http/server/batch.ts @@ -13,6 +13,7 @@ import type { IncomingMessage } from "node:http"; import type { Method, Metadata, Status } from "../../../client/types.js"; import type { RequestHandler, ServerRequest, ServerResponse } from "../../../server/types.js"; import { lastResortError } from "../../../server/last-resort.js"; +import { capacityFieldsOf } from "../../../client/middleware/items.js"; import { pathToMethod } from "../../../server/method.js"; import { segmentsOf } from "./addressing.js"; import type { NdjsonError } from "./ndjson.js"; @@ -73,6 +74,8 @@ export interface BatchError extends NdjsonError { readonly reason?: string | undefined; readonly retryAfterMs?: number | undefined; readonly conflicts?: unknown[] | undefined; + readonly units?: number | undefined; + readonly capacity?: number | undefined; } /** True when the request is a batch: `POST` with the header `Procedures-Batch: 1`. */ @@ -139,6 +142,7 @@ export function batchErrorOf(status: Extract, metadat ...(typeof wait === "number" && Number.isFinite(wait) && wait >= 0 ? { retryAfterMs: wait } : {}), ...(typeof reason === "string" ? { reason } : {}), ...(Array.isArray(conflicts) ? { conflicts } : {}), + ...capacityFieldsOf(metadata), }; } diff --git a/packages/client/src/adapters/http/server/handler.ts b/packages/client/src/adapters/http/server/handler.ts index b3ac32d3f..74b14e8c9 100644 --- a/packages/client/src/adapters/http/server/handler.ts +++ b/packages/client/src/adapters/http/server/handler.ts @@ -22,6 +22,7 @@ import type { RequestHandler, ServerRequest, ServerResponse } from "../../../ser import { lastResortError } from "../../../server/last-resort.js"; import { decodeMetadataHeader, METADATA_HEADER_LIMIT } from "../shared/index.js"; import { ERROR_REGISTRY } from "../../../client/errors/index.js"; +import { capacityFieldsOf } from "../../../client/middleware/items.js"; import { assertNamedOrigins, checkBrowserRequest, needsNamedOrigin, type BrowserGuardOptions } from "../../../server/browser-guard.js"; import { isUnboundedStream } from "../../../server/stream-metadata.js"; import { headerNames, isSecretHeader, queryRecord, requestCredentials, urlParts, withoutSecretHeaders } from "../../../server/request-auth.js"; @@ -539,6 +540,8 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur const reason = typeof metadata["reason"] === "string" ? metadata["reason"] : undefined; // The current items of a VERSION_CONFLICT error (roadmap CLI-16) const conflicts = Array.isArray(metadata["conflicts"]) ? metadata["conflicts"] : undefined; + // The units and the capacity of a refusal for its size (roadmap CLI-122) + const capacity = capacityFieldsOf(metadata); sendJson(res, httpStatusCode, { error: status.message, code: status.code, @@ -546,6 +549,7 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur ...(hasRetryAfter ? { retryAfterMs } : {}), ...(reason !== undefined ? { reason } : {}), ...(conflicts !== undefined ? { conflicts } : {}), + ...capacity, }); }; diff --git a/packages/client/src/client/middleware/items.ts b/packages/client/src/client/middleware/items.ts index 10b3ccb91..70434a9cb 100644 --- a/packages/client/src/client/middleware/items.ts +++ b/packages/client/src/client/middleware/items.ts @@ -46,6 +46,22 @@ export function retryAfterOf(item: ResponseItem): number | undefined { return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined; } +/** The units of a call that a limit refuses for its size, and the capacity of that limit (roadmap CLI-122). */ +export interface CallCapacity { + readonly units: number; + readonly capacity: number; +} + +/** + * This function gives the fields `units` and `capacity` of a record, when both are finite numbers, else an empty + * record. The metadata and the error bodies of a refusal for its size carry these fields (roadmap CLI-122). + */ +export function capacityFieldsOf(fields: unknown): CallCapacity | Record { + if (fields === null || typeof fields !== "object") return {}; + const { units, capacity } = fields as { units?: unknown; capacity?: unknown }; + return typeof units === "number" && typeof capacity === "number" && Number.isFinite(units) && Number.isFinite(capacity) ? { units, capacity } : {}; +} + /** * The error codes that say that the service is not available: the server is down, busy, slow or * stopping, or the network failed. A circuit breaker counts only these (roadmap R12). An abort, diff --git a/packages/client/src/server/conformance.test.ts b/packages/client/src/server/conformance.test.ts index 4e5c236fe..86d064e8b 100644 --- a/packages/client/src/server/conformance.test.ts +++ b/packages/client/src/server/conformance.test.ts @@ -59,6 +59,7 @@ async function serverOf(spec: ContractSpec): Promise { ...(spec.principalOf !== undefined && { principalOf: spec.principalOf }), ...(spec.errors !== undefined && { errors: spec.errors }), ...(spec.onError !== undefined && { onError: spec.onError }), + ...(spec.limits !== undefined && { limits: spec.limits }), }); return server; } diff --git a/packages/client/src/server/limits.test.ts b/packages/client/src/server/limits.test.ts index 547c49705..ab522fec9 100644 --- a/packages/client/src/server/limits.test.ts +++ b/packages/client/src/server/limits.test.ts @@ -23,7 +23,7 @@ import { seconds } from "../duration.js"; import { ProcedureServer } from "./procedure-server.js"; import { hostPolicy, procedureServerOptions } from "./host-policy.js"; import { pathToMethod } from "./method.js"; -import type { CallLimit } from "./limits.js"; +import type { CallLimit, LimitedCall } from "./limits.js"; import type { PrincipalOf, ServerResponse } from "./types.js"; import { LOCAL_CREDENTIALS } from "./request-auth.js"; @@ -85,11 +85,11 @@ function serverOf(limits: readonly CallLimit[], clock: FakeClock = fakeClock(), let sent = 0; /** A call of a procedure: with the token of a tenant (a network call), or with the local marker (a call of this process, CLI-1). */ -function call(server: ProcedureServer, tenant: string | undefined, procedure: string): Promise> { +function call(server: ProcedureServer, tenant: string | undefined, procedure: string, payload: unknown = {}): Promise> { return server.handle({ id: `call-${++sent}`, method: pathToMethod(["notes", procedure]), - payload: {}, + payload, metadata: {}, credentials: tenant !== undefined ? { bearer: `tok-${tenant}` } : LOCAL_CREDENTIALS, }); @@ -292,3 +292,50 @@ describe("the limits of the calls of a server (CLI-40)", () => { expect("limits" in hostPolicy({ limits: [] })).toBe(false); }); }); + +describe("the cost of a call (CLI-122)", () => { + /** The count of the list `items` of the payload of a call. */ + const itemsOf = (call: LimitedCall): number => { + const items = (call.request.payload as { items?: unknown } | undefined)?.items; + return Array.isArray(items) ? items.length : 0; + }; + /** A payload with `n` items. */ + const items = (n: number): { items: string[] } => ({ items: Array.from({ length: n }, (_, index) => `s${String(index)}`) }); + /** A burst of 12 units for each tenant, and a cost of 1 + ceil(items / 50) for each write. */ + const BY_ITEMS: CallLimit = { + ...WRITES_PER_TENANT, + name: "notes.items", + policy: { type: "token-bucket", rate: { value: 1, unit: "count/s" }, burst: count(12) }, + cost: (call) => 1 + Math.ceil(itemsOf(call) / 50), + }; + + it("refuses a call over the capacity with PAYLOAD_TOO_LARGE, the units and the capacity, and takes nothing", async () => { + const server = serverOf([BY_ITEMS]); + // 600 items cost 13 units, over the burst of 12 + const refused = await call(server, "acme", "write", items(600)); + expect(refused.status).toMatchObject({ type: "error", code: "PAYLOAD_TOO_LARGE", retryable: false }); + expect(refused.metadata).toEqual({ reason: "capacity", units: 13, capacity: 12 }); + expect(refused.status.type === "error" ? refused.status.message : "").toContain("notes.items"); + expect(runs["write"]).toBeUndefined(); + // The refusal took nothing: 500 items cost 11 of the 12 units + expect(outcome(await call(server, "acme", "write", items(500)))).toBe("ok"); + // One unit is left: 1 item costs 2 units, thus the call waits for one unit + expect((await call(server, "acme", "write", items(1))).metadata).toEqual({ "retry-after": 1000, reason: "limit" }); + // A call with no items costs 1 unit + expect(outcome(await call(server, "acme", "write"))).toBe("ok"); + expect(runs["write"]).toBe(2); + }); + + it("takes one unit for a limit with no cost, a fixed cost for each call, and refuses a fixed cost that is not a whole number of 1 or more", async () => { + const server = serverOf([{ ...BY_ITEMS, cost: 5 }]); + expect(outcome(await call(server, "acme", "write", items(600)))).toBe("ok"); + expect(outcome(await call(server, "acme", "write"))).toBe("ok"); + // 10 of the 12 units are used: a third call of 5 units waits + expect((await call(server, "acme", "write")).metadata).toMatchObject({ reason: "limit" }); + const { cost: _cost, ...noCost } = BY_ITEMS; + const one = serverOf([noCost]); + for (let index = 0; index < 12; index++) expect(outcome(await call(one, "acme", "write", items(600)))).toBe("ok"); + expect((await call(one, "acme", "write")).metadata).toMatchObject({ reason: "limit" }); + for (const cost of [0, 1.5, -1, Number.NaN]) expect(() => serverOf([{ ...BY_ITEMS, cost }])).toThrow(/The cost of the limit notes.items is a whole number of 1 or more/); + }); +}); diff --git a/packages/client/src/server/limits.ts b/packages/client/src/server/limits.ts index 77700070e..3727c892e 100644 --- a/packages/client/src/server/limits.ts +++ b/packages/client/src/server/limits.ts @@ -3,15 +3,21 @@ * * A limit is data: a key over the call, the calls that it covers, a limit policy, a store and a * bound on its keys. Each limit is a keyed limiter of `@mark1russell7/service/limiter` (SYS-28) on - * the clock of the server. The server takes one unit of each limit that covers a call, after the - * authentication and before the run. Thus the key can read the principal of the call. It takes the - * units in the sequence of the limits, and the first refusal stops the call. A limit before the - * refusal keeps its unit: the server does not give it back. + * the clock of the server. The server takes the cost of the call from each limit that covers it, + * after the authentication and before the run. Thus the key can read the principal of the call. The + * cost is one unit, or the `cost` of the limit (roadmap CLI-122). The server takes the units in the + * sequence of the limits, and the first refusal stops the call. A limit before the refusal keeps its + * units: the server does not give them back. * - * A refusal is `RATE_LIMITED` (retryable), with the wait in the metadata key `retry-after` (in + * A wait refusal is `RATE_LIMITED` (retryable), with the wait in the metadata key `retry-after` (in * milliseconds) and the cause in `reason` (`limit`, `cap` or `store`). The HTTP face answers 429 * with `Retry-After` in whole seconds. The WebSocket face and the MCP face give the same code and * the same wait. The work did not start, so a retry after the wait is safe. + * + * A capacity refusal is `PAYLOAD_TOO_LARGE` (not retryable). The cost of the call is over the most + * units of the limit, thus no wait lets the call in. The metadata keys `units` and `capacity` give + * both numbers, and `reason` is `capacity`. The HTTP face answers 413 with no `Retry-After`. A caller + * sends the work again in calls of at most `capacity` units. */ import { valueIn } from "@mark1russell7/quantity"; @@ -96,6 +102,12 @@ export interface CallLimit { readonly store: LimiterStoreSpec; /** The bound on the keys that the store holds. */ readonly evict: LimiterEviction; + /** + * The units that a call takes: a whole number of 1 or more, or a function of the call that gives + * one. The default is 1. A cost for each item of a batch keeps a batch within the limit (roadmap + * CLI-122). A call whose cost is over the burst or the limit of the policy gets a capacity refusal. + */ + readonly cost?: number | ((call: LimitedCall) => number) | undefined; } /** The refusal of a call by one limit. */ @@ -110,8 +122,8 @@ export interface CallLimiter { /** The keyed limiters, in the sequence of the limits. A host declares each one with `svc.limiter(name, spec)`. */ readonly limiters: readonly KeyedLimiter[]; /** - * This method takes one unit of each limit that covers the call, in the sequence of the limits. - * It gives the first refusal, or undefined. A limit before the refusal keeps its unit. + * This method takes the cost of the call from each limit that covers it, in the sequence of the + * limits. It gives the first refusal, or undefined. A limit before the refusal keeps its units. */ admit(call: LimitedCall): Promise; } @@ -188,6 +200,18 @@ function storeOf(limit: CallLimit, local: LimiterStore, stores: Readonly number | undefined { + const { cost } = limit; + if (cost === undefined) return () => undefined; + if (typeof cost === "function") return cost; + if (!Number.isSafeInteger(cost) || cost < 1) throw new Error(`The cost of the limit ${limit.name} is a whole number of 1 or more, not ${String(cost)}`); + return () => cost; +} + /** * This function makes the runtime of the limits of a server: one keyed limiter for each limit. The * local limits share one memory store on the clock of the options. It refuses two limits with one @@ -202,17 +226,18 @@ export function callLimiter(limits: readonly CallLimit[], options: CallLimiterOp names.add(limit.name); const keyOf = keyFunction(limit.key); const covers = coversFunction(limit.covers); + const costOf = costFunction(limit); const limiter = keyedLimiter(limit.name, { key: keyNameOf(limit), policy: limit.policy, store: limit.store, evict: limit.evict }, storeOf(limit, local, stores)); - return { limiter, keyOf, covers }; + return { limiter, keyOf, covers, costOf }; }); return { limiters: entries.map((entry) => entry.limiter), async admit(call) { - for (const { limiter, keyOf, covers } of entries) { + for (const { limiter, keyOf, covers, costOf } of entries) { if (!covers(call)) continue; const key = keyOf(call); if (key === undefined) continue; - const decision = await limiter.take(key); + const decision = await limiter.take(key, costOf(call)); if (!decision.allowed) return { limit: limiter.name, refused: decision }; } return undefined; @@ -234,11 +259,24 @@ export function limitedCall(procedure: { readonly path: ProcedurePath; readonly } /** - * This function gives the response of a refused call: `RATE_LIMITED`, retryable, with the wait in - * `retry-after` (milliseconds) and the cause in `reason`. The failure of a store stays on the server. + * This function gives the response of a refused call. A wait refusal is `RATE_LIMITED`, retryable, + * with the wait in `retry-after` (milliseconds) and the cause in `reason`. A capacity refusal is + * `PAYLOAD_TOO_LARGE`, not retryable, with `units` and `capacity`. The failure of a store stays on the server. */ export function rateLimitedResponse(id: string, refusal: CallLimitRefusal): ServerResponse { const { limit, refused } = refusal; + if (refused.cause === "capacity") { + return { + id, + status: { + type: "error", + code: "PAYLOAD_TOO_LARGE", + message: `The limit ${limit} of the host refuses the call: it costs ${String(refused.units)} units, over the capacity of ${String(refused.capacity)}`, + retryable: false, + }, + metadata: { reason: refused.cause, units: refused.units, capacity: refused.capacity }, + }; + } const waitMs = valueIn(refused.retryAfter, "ms"); const seconds = retryAfterSeconds(refused.retryAfter); return { diff --git a/packages/client/src/testing/transport-contract.ts b/packages/client/src/testing/transport-contract.ts index 87c34052f..c997e787a 100644 --- a/packages/client/src/testing/transport-contract.ts +++ b/packages/client/src/testing/transport-contract.ts @@ -44,6 +44,7 @@ import type { CollectionStorage } from "../procedures/collection/storage.js"; import type { ProcedureRegistry } from "../procedures/registry.js"; import type { PrincipalOf } from "../server/types.js"; import type { ServerErrorPolicy } from "../server/error-policy.js"; +import type { CallLimit } from "../server/limits.js"; import type { EventPublisherOptions } from "../events/publisher.js"; import type { EventTransport } from "../events/remote.js"; import type { Transport } from "../client/types.js"; @@ -131,6 +132,8 @@ export interface ContractSpec { readonly onError?: ((error: Error) => void) | undefined; /** The size limit of a request, in bytes, for a face with `sizeLimit`. */ readonly sizeLimit?: number | undefined; + /** The limits of the calls of the server (`ProcedureServerOptions.limits`). Only a face with `server` gets them. */ + readonly limits?: readonly CallLimit[] | undefined; } /** The options of one call of a caller. */ @@ -463,6 +466,22 @@ export function describeTransportContract(face: ContractFace, runner: ContractRu expect(logged.length).toBeGreaterThanOrEqual(3); }); + it.skipIf(!caps.server)("refuses a call over the capacity of a limit with PAYLOAD_TOO_LARGE, the units and the capacity (CLI-122)", async () => { + // Each call costs 13 units, over the burst of 12: no wait lets it in, and the procedure does not run + const limit: CallLimit = { + name: "contract.capacity", + key: "route", + policy: { type: "token-bucket", rate: { value: 1, unit: "count/s" }, burst: { value: 12, unit: "count" } }, + store: { kind: "local" }, + evict: { maxKeys: { value: 10, unit: "count" } }, + cost: 13, + }; + const caller = await start(fresh(), { limits: [limit] }); + const error = await errorOf(caller.call(["contract", "fail"], { code: "E_APP" })); + expect(error).toMatchObject({ code: "PAYLOAD_TOO_LARGE", retryable: false }); + if (caps.errorMetadata) expect(error.metadata).toMatchObject({ reason: "capacity", units: 13, capacity: 12 }); + }); + it("gives VERSION_CONFLICT, and the conflicts when the caller gets the metadata of an error (CLI-16)", async () => { const caller = await start(); const error = await errorOf(caller.call(["contract", "conflict"], {})); diff --git a/packages/client/test/api/public-api.txt b/packages/client/test/api/public-api.txt index 72b71c2e7..c9d0d045d 100644 --- a/packages/client/test/api/public-api.txt +++ b/packages/client/test/api/public-api.txt @@ -6388,6 +6388,7 @@ export interface CallLimit { readonly policy: LimitPolicy; readonly store: LimiterStoreSpec; readonly evict: LimiterEviction; + readonly cost?: number | ((call: LimitedCall) => number) | undefined; } ### dist/server/limits.d.ts#CallLimitCovers @@ -6869,6 +6870,7 @@ export interface ContractSpec { readonly errors?: ServerErrorPolicy | undefined; readonly onError?: ((error: Error) => void) | undefined; readonly sizeLimit?: number | undefined; + readonly limits?: readonly CallLimit[] | undefined; } ### dist/testing/transport-contract.d.ts#clientCaller From 700f72c1d1987b01cef85066936e3aa8fe75aeb1 Mon Sep 17 00:00:00 2001 From: Mark Russell Date: Sun, 8 Nov 2026 03:53:46 -0500 Subject: [PATCH 2/4] build: @mark1russell7/service ^0.7.0 in each package (CLI-122) Co-Authored-By: Claude Opus 5.5 --- packages/client-mcp/package.json | 2 +- packages/client-mongo/package.json | 2 +- packages/client-server/package.json | 2 +- packages/client-store/package.json | 2 +- packages/client/package.json | 2 +- packages/impl-mcp-dev/package.json | 2 +- packages/llm/package.json | 2 +- packages/mark/package.json | 2 +- packages/schedule/package.json | 2 +- packages/server/package.json | 2 +- packages/systems/package.json | 2 +- pnpm-lock.yaml | 90 ++++++++++++++++++----------- 12 files changed, 68 insertions(+), 44 deletions(-) diff --git a/packages/client-mcp/package.json b/packages/client-mcp/package.json index 0f93e4549..dabea1503 100644 --- a/packages/client-mcp/package.json +++ b/packages/client-mcp/package.json @@ -79,6 +79,6 @@ "@mark1russell7/cue": "^2.1.1", "vitest": "^5.0.3", "@procedures/client": "workspace:*", - "@mark1russell7/service": "^0.6.0" + "@mark1russell7/service": "^0.7.0" } } diff --git a/packages/client-mongo/package.json b/packages/client-mongo/package.json index 07b1c4dd0..bf3e749d8 100644 --- a/packages/client-mongo/package.json +++ b/packages/client-mongo/package.json @@ -67,7 +67,7 @@ "@mark1russell7/rigor-bench": "^0.2.28", "@mark1russell7/rigor-generators": "^0.1.5", "@mark1russell7/rigor-statistics": "^0.1.9", - "@mark1russell7/service": "^0.6.0", + "@mark1russell7/service": "^0.7.0", "@procedures/peer": "workspace:*", "@procedures/store": "workspace:*", "@types/node": "^22.0.0", diff --git a/packages/client-server/package.json b/packages/client-server/package.json index b97b80485..c9d9e8a5a 100644 --- a/packages/client-server/package.json +++ b/packages/client-server/package.json @@ -87,7 +87,7 @@ "procedures": "./dist/register.js" }, "dependencies": { - "@mark1russell7/service": "^0.6.0", + "@mark1russell7/service": "^0.7.0", "@procedures/client": "workspace:*", "zod": "^4.6.5" } diff --git a/packages/client-store/package.json b/packages/client-store/package.json index 376005bd4..d78ab4fde 100644 --- a/packages/client-store/package.json +++ b/packages/client-store/package.json @@ -84,7 +84,7 @@ ] }, "dependencies": { - "@mark1russell7/service": "^0.6.0", + "@mark1russell7/service": "^0.7.0", "@procedures/client": "workspace:*", "@procedures/collections": "workspace:*", "zod": "^4.6.5" diff --git a/packages/client/package.json b/packages/client/package.json index 00a581358..e9b0dbed3 100644 --- a/packages/client/package.json +++ b/packages/client/package.json @@ -123,7 +123,7 @@ "@mark1russell7/coeval": "^0.22.0", "@mark1russell7/collections": "^0.5.0", "@mark1russell7/quantity": "^0.3.0", - "@mark1russell7/service": "^0.6.0", + "@mark1russell7/service": "^0.7.0", "@types/ws": "^8.18.1", "ws": "^8.18.3", "zod": "^4.6.5" diff --git a/packages/impl-mcp-dev/package.json b/packages/impl-mcp-dev/package.json index 4d70f3a07..5117cd456 100644 --- a/packages/impl-mcp-dev/package.json +++ b/packages/impl-mcp-dev/package.json @@ -59,7 +59,7 @@ "test:watch": "vitest" }, "dependencies": { - "@mark1russell7/service": "^0.6.0", + "@mark1russell7/service": "^0.7.0", "@procedures/bundle-mcp": "workspace:*", "@procedures/client": "workspace:*", "@procedures/compiler": "workspace:*", diff --git a/packages/llm/package.json b/packages/llm/package.json index 59aded97b..6a8e5ee34 100644 --- a/packages/llm/package.json +++ b/packages/llm/package.json @@ -72,7 +72,7 @@ "procedures": "./dist/register.js" }, "dependencies": { - "@mark1russell7/service": "^0.6.0", + "@mark1russell7/service": "^0.7.0", "@procedures/client": "workspace:*", "@procedures/http": "workspace:*", "@procedures/json": "workspace:*", diff --git a/packages/mark/package.json b/packages/mark/package.json index b4697cffc..4c16206a3 100644 --- a/packages/mark/package.json +++ b/packages/mark/package.json @@ -60,7 +60,7 @@ "test:e2e:watch": "vitest --config vitest.e2e.config.ts" }, "dependencies": { - "@mark1russell7/service": "^0.6.0", + "@mark1russell7/service": "^0.7.0", "@procedures/cli-kit": "workspace:*", "@procedures/cli-run": "workspace:*", "@procedures/client": "workspace:*", diff --git a/packages/schedule/package.json b/packages/schedule/package.json index 863f3a021..660f0668b 100644 --- a/packages/schedule/package.json +++ b/packages/schedule/package.json @@ -62,7 +62,7 @@ "@types/node": "^22.0.0", "@mark1russell7/cue": "^2.1.1", "vitest": "^5.0.3", - "@mark1russell7/service": "^0.6.0" + "@mark1russell7/service": "^0.7.0" }, "engines": { "node": ">=22" diff --git a/packages/server/package.json b/packages/server/package.json index c5bd8aa63..2cc674d0c 100644 --- a/packages/server/package.json +++ b/packages/server/package.json @@ -68,7 +68,7 @@ "start": "node dist/cli.js" }, "dependencies": { - "@mark1russell7/service": "^0.6.0", + "@mark1russell7/service": "^0.7.0", "@procedures/client": "workspace:*", "@procedures/peer": "workspace:*", "zod": "^4.6.5" diff --git a/packages/systems/package.json b/packages/systems/package.json index 792c17701..43b11625a 100644 --- a/packages/systems/package.json +++ b/packages/systems/package.json @@ -70,7 +70,7 @@ "procedures": "./dist/register.js" }, "dependencies": { - "@mark1russell7/service": "^0.6.0", + "@mark1russell7/service": "^0.7.0", "@procedures/client": "workspace:*", "zod": "^4.6.5" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d29061540..da1a91b23 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -502,8 +502,8 @@ importers: specifier: ^0.3.0 version: 0.3.0(zod@4.6.7) '@mark1russell7/service': - specifier: ^0.6.0 - version: 0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) + specifier: ^0.7.0 + version: 0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) '@types/ws': specifier: ^8.18.1 version: 8.18.2 @@ -788,8 +788,8 @@ importers: specifier: ^2.1.1 version: 2.1.1 '@mark1russell7/service': - specifier: ^0.6.0 - version: 0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) + specifier: ^0.7.0 + version: 0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) '@procedures/client': specifier: workspace:* version: link:../client @@ -831,8 +831,8 @@ importers: specifier: ^0.1.9 version: 0.1.15 '@mark1russell7/service': - specifier: ^0.6.0 - version: 0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) + specifier: ^0.7.0 + version: 0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) '@procedures/peer': specifier: workspace:* version: link:../client-server @@ -989,8 +989,8 @@ importers: packages/client-server: dependencies: '@mark1russell7/service': - specifier: ^0.6.0 - version: 0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) + specifier: ^0.7.0 + version: 0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) '@procedures/client': specifier: workspace:* version: link:../client @@ -1150,8 +1150,8 @@ importers: packages/client-store: dependencies: '@mark1russell7/service': - specifier: ^0.6.0 - version: 0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) + specifier: ^0.7.0 + version: 0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) '@procedures/client': specifier: workspace:* version: link:../client @@ -1424,8 +1424,8 @@ importers: packages/impl-mcp-dev: dependencies: '@mark1russell7/service': - specifier: ^0.6.0 - version: 0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) + specifier: ^0.7.0 + version: 0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) '@procedures/bundle-mcp': specifier: workspace:* version: link:../bundle-mcp @@ -1514,8 +1514,8 @@ importers: packages/llm: dependencies: '@mark1russell7/service': - specifier: ^0.6.0 - version: 0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) + specifier: ^0.7.0 + version: 0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) '@procedures/client': specifier: workspace:* version: link:../client @@ -1570,8 +1570,8 @@ importers: packages/mark: dependencies: '@mark1russell7/service': - specifier: ^0.6.0 - version: 0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) + specifier: ^0.7.0 + version: 0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) '@procedures/cli-kit': specifier: workspace:* version: link:../cli-kit @@ -1910,8 +1910,8 @@ importers: specifier: ^2.1.1 version: 2.1.1 '@mark1russell7/service': - specifier: ^0.6.0 - version: 0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) + specifier: ^0.7.0 + version: 0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) '@types/node': specifier: ^22.0.0 version: 22.20.5 @@ -1925,8 +1925,8 @@ importers: packages/server: dependencies: '@mark1russell7/service': - specifier: ^0.6.0 - version: 0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) + specifier: ^0.7.0 + version: 0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) '@procedures/client': specifier: workspace:* version: link:../client @@ -2201,8 +2201,8 @@ importers: packages/systems: dependencies: '@mark1russell7/service': - specifier: ^0.6.0 - version: 0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) + specifier: ^0.7.0 + version: 0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7) '@procedures/client': specifier: workspace:* version: link:../client @@ -3336,6 +3336,15 @@ packages: zod: optional: true + '@mark1russell7/algebra@0.8.2': + resolution: {integrity: sha512-eqG1qpLrxSnG4CZaqnGZ9dt05oxX0RO/5Wj08ZNWJwyBeu0CTOm8Z62NLToGqYUL1Kzf/7ZLfhGzjd03ROLniw==} + engines: {node: '>=22.19'} + peerDependencies: + zod: ^4.1.0 + peerDependenciesMeta: + zod: + optional: true + '@mark1russell7/api-report@0.4.1': resolution: {integrity: sha512-kx3vmIdzwGJf+aZ66qoYWm65IlrEzrbSXckAQed0I+fxs6+wFygVoum6ZVBeKdz05rHHLD9kiarwQQcI5LhsDQ==} engines: {node: '>=22'} @@ -3360,6 +3369,10 @@ packages: resolution: {integrity: sha512-/SBxY5LOLjIYuBiSf0hdxA6OeGPJUIAHSQSepVDZVnCLEvY1Jte0E3ec0ahN3oyO7oE677FY9d3LuuN18nyv3g==} engines: {node: '>=22.12'} + '@mark1russell7/collections@0.7.2': + resolution: {integrity: sha512-C5lHeQXAHtwgsdjK1rktRwaGvssMoEiBK5Wx2XBJkejhrjvaK7qATjumlp8EGNNVjkHNfIBw15UevBO7wyKj5g==} + engines: {node: '>=22.12'} + '@mark1russell7/conventions@0.36.1': resolution: {integrity: sha512-Fb9YVVIYWTYX/+2yvtubLB4a0ognZrCs2Gy+U7RARQ9GP9jF1h4oqH5pDZiao1MUOYH070xOerUBqL4PsqnBGQ==} engines: {node: '>=22'} @@ -3374,6 +3387,10 @@ packages: resolution: {integrity: sha512-hPpTZGcf5JZXogDTJMx4o/bfWZSIdK/3aguJc2xcKRksYwG3K0FXYt+j96JT4VCX7BRu/HQb3kWy4q1tkPTIjQ==} engines: {node: '>=22'} + '@mark1russell7/optional@1.2.0': + resolution: {integrity: sha512-vS5jF21WC/VApRv4p8afRZahcMl9cuNp03LxbVngY9nYkzq+S7Oit6ksySt2baML+tp46UF60sxnHxn1jlwtTg==} + engines: {node: '>=22.12'} + '@mark1russell7/quantity@0.3.0': resolution: {integrity: sha512-psfyKmVrOz5ynHgr2ED7WM5Pa/XVy6DR28jCaSGY42gvV0CJEq7HJRpV6sgkvWx8s3Et7evJWR56aG5tjCHZIw==} engines: {node: '>=22.19'} @@ -3414,10 +3431,6 @@ packages: esbuild: optional: true - '@mark1russell7/rigor-generators@0.1.5': - resolution: {integrity: sha512-YkABrG6+AV4oZKWoSIayDGxKTqcTMbp/eGa+3u00X09Jv9TfpHFDeqHlEQARMBzJ/kvy/EMNIXQZMGa3Nobuzw==} - engines: {node: '>=22'} - '@mark1russell7/rigor-generators@0.1.6': resolution: {integrity: sha512-eSuVS6nNd2H63dMrfleop+ffBtNd8Ua0/JrcUWUMxf2jHWw432fSwJ+aSa4ecAYq1Pa2ReCfwpqFUP4MII5+GA==} engines: {node: '>=22'} @@ -3430,8 +3443,8 @@ packages: resolution: {integrity: sha512-9MQpKdW3hluyP4zV1oerpApWcKsiKR2s4PpQ8LcGzep0oJSpE2lYAUWzyo2MaLdkSAnNsh6pxnSbr5KaR7OYIQ==} engines: {node: '>=22'} - '@mark1russell7/service@0.6.5': - resolution: {integrity: sha512-USBAaZX8lQ3nmBzaTycF+6xQJyIQ51ZTWIxw9rZnZ5bhaqZe5FydTgVPYr92/gb8VWcOG4jxWsPnLPBBEaxzSA==} + '@mark1russell7/service@0.7.0': + resolution: {integrity: sha512-xUwbc5wfk4/gCyIiHRUNsULf0LqDZXk2REogpqveAs1u1ojUpt1NWueN9VWWU2EuZaYYe9ue3Dg8ICirDLCrig==} engines: {node: '>=22.19'} peerDependencies: '@grpc/grpc-js': ^1.14.6 @@ -6775,6 +6788,12 @@ snapshots: optionalDependencies: zod: 4.6.7 + '@mark1russell7/algebra@0.8.2(zod@4.6.7)': + dependencies: + '@mark1russell7/quantity': 0.3.0(zod@4.6.7) + optionalDependencies: + zod: 4.6.7 + '@mark1russell7/api-report@0.4.1': {} '@mark1russell7/boundaries@0.2.0(@swc/core@1.16.20)(dependency-cruiser@18.7.0)': @@ -6786,6 +6805,10 @@ snapshots: '@mark1russell7/collections@0.5.0': {} + '@mark1russell7/collections@0.7.2': + dependencies: + '@mark1russell7/optional': 1.2.0 + '@mark1russell7/conventions@0.36.1': dependencies: yaml: 2.9.1 @@ -6797,6 +6820,8 @@ snapshots: '@types/sql.js': 1.4.11 sql.js: 1.14.2 + '@mark1russell7/optional@1.2.0': {} + '@mark1russell7/quantity@0.3.0(zod@4.6.7)': dependencies: '@mark1russell7/rational': 0.1.2 @@ -6826,8 +6851,6 @@ snapshots: optionalDependencies: esbuild: 0.28.2 - '@mark1russell7/rigor-generators@0.1.5': {} - '@mark1russell7/rigor-generators@0.1.6': {} '@mark1russell7/rigor-statistics@0.1.15': @@ -6838,11 +6861,12 @@ snapshots: dependencies: '@mark1russell7/rigor-generators': 0.1.6 - '@mark1russell7/service@0.6.5(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7)': + '@mark1russell7/service@0.7.0(mongodb@7.8.0(socks@2.8.10))(ws@8.22.0)(zod@4.6.7)': dependencies: - '@mark1russell7/algebra': 0.8.1(zod@4.6.7) + '@mark1russell7/algebra': 0.8.2(zod@4.6.7) + '@mark1russell7/collections': 0.7.2 '@mark1russell7/quantity': 0.3.0(zod@4.6.7) - '@mark1russell7/rigor-generators': 0.1.5 + '@mark1russell7/rigor-generators': 0.1.6 optionalDependencies: mongodb: 7.8.0(socks@2.8.10) ws: 8.22.0 From a8c0f346f0c9b0d9d03e51e19afb2961fb7dcbaa Mon Sep 17 00:00:00 2001 From: Mark Russell Date: Sun, 8 Nov 2026 04:30:57 -0500 Subject: [PATCH 3/4] fix(client): the client rate limiter reads retryAfter of a wait refusal only (service 0.7.0) Co-Authored-By: Claude Opus 5.5 --- packages/client/src/client/middleware/rate-limit.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/client/src/client/middleware/rate-limit.ts b/packages/client/src/client/middleware/rate-limit.ts index 468607e4b..1c39aea3e 100644 --- a/packages/client/src/client/middleware/rate-limit.ts +++ b/packages/client/src/client/middleware/rate-limit.ts @@ -308,8 +308,10 @@ export function createRateLimitMiddleware( while (queue.length > 0) { const decision = take(); if (!decision.allowed) { - // The time until the next whole token - const wait = Math.max(1, Math.ceil(valueIn(decision.retryAfter, "ms"))); + // The time until the next whole token. A take of one unit is never over a burst of 1 or more, + // so a capacity refusal does not occur here. If it occurs, the queue waits one window. + const wait = + decision.cause === "capacity" ? Math.max(1, window) : Math.max(1, Math.ceil(valueIn(decision.retryAfter, "ms"))); drainTimer = clock.after(wait, () => { drainTimer = undefined; scheduleDrain(); From e7c2ddb6f7ecb683da392e8ba7f6d062827397e2 Mon Sep 17 00:00:00 2001 From: Mark Russell Date: Sun, 8 Nov 2026 04:57:11 -0500 Subject: [PATCH 4/4] test(client-server): the host contract passes the limits of the spec to the policy (CLI-122) Co-Authored-By: Claude Opus 5.5 --- packages/client-server/src/host/contract.test.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/client-server/src/host/contract.test.ts b/packages/client-server/src/host/contract.test.ts index 42318f84f..0ee7e9612 100644 --- a/packages/client-server/src/host/contract.test.ts +++ b/packages/client-server/src/host/contract.test.ts @@ -60,6 +60,8 @@ async function hostOf(spec: ContractSpec, type: FaceType, connect: (address: str events: spec.events, ...(spec.token !== undefined && { token: spec.token }), ...(spec.principalOf !== undefined && { principalOf: spec.principalOf }), + // The limits of the calls come from the policy of the host (CLI-40) + ...(spec.limits !== undefined && { limits: spec.limits }), }), serverOptions: { ...(spec.errors !== undefined && { errors: spec.errors }),