Skip to content
14 changes: 14 additions & 0 deletions .changeset/call-cost.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
"@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 changes from `RATE_LIMITED` to `PAYLOAD_TOO_LARGE`, not retryable. The metadata gives `reason: "capacity"`, `units` and `capacity`. The HTTP face answers 413 in place of 429, 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.

Migration steps:

1. Code that reads a capacity refusal as `RATE_LIMITED` with `reason: "capacity"` reads `PAYLOAD_TOO_LARGE`. An HTTP client reads 413 in place of 429.
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.
1 change: 1 addition & 0 deletions packages/client-mcp/src/transport/conformance.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 }),
});
}

Expand Down
5 changes: 5 additions & 0 deletions packages/client-mcp/src/transport/mcp-transport.ts
Original file line number Diff line number Diff line change
Expand Up @@ -519,6 +519,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: [
{
Expand All @@ -532,6 +536,7 @@ export class McpServerTransport implements ServerTransport {
retryable: response.status.retryable === true,
...(reason ? { reason } : {}),
...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
...(sized ? { units, capacity } : {}),
},
};
}
Expand Down
2 changes: 2 additions & 0 deletions packages/client-server/src/host/contract.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 }),
Expand Down
6 changes: 3 additions & 3 deletions packages/client/src/adapters/http/client/batch.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -457,13 +457,13 @@ 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 };
const out: 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) };
}
4 changes: 3 additions & 1 deletion packages/client/src/adapters/http/client/transport.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand Down Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions packages/client/src/adapters/http/server/batch.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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`. */
Expand Down Expand Up @@ -139,6 +142,7 @@ export function batchErrorOf(status: Extract<Status, { type: "error" }>, metadat
...(typeof wait === "number" && Number.isFinite(wait) && wait >= 0 ? { retryAfterMs: wait } : {}),
...(typeof reason === "string" ? { reason } : {}),
...(Array.isArray(conflicts) ? { conflicts } : {}),
...capacityFieldsOf(metadata),
};
}

Expand Down
4 changes: 4 additions & 0 deletions packages/client/src/adapters/http/server/handler.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -539,13 +540,16 @@ 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,
retryable: status.retryable,
...(hasRetryAfter ? { retryAfterMs } : {}),
...(reason !== undefined ? { reason } : {}),
...(conflicts !== undefined ? { conflicts } : {}),
...capacity,
});
};

Expand Down
16 changes: 16 additions & 0 deletions packages/client/src/client/middleware/items.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,22 @@ export function retryAfterOf(item: ResponseItem<unknown>): 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<string, never> {
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,
Expand Down
1 change: 1 addition & 0 deletions packages/client/src/server/conformance.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ async function serverOf(spec: ContractSpec): Promise<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 }),
});
return server;
}
Expand Down
61 changes: 54 additions & 7 deletions packages/client/src/server/limits.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,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 { rateLimitedResponse, type CallLimit } from "./limits.js";
import { rateLimitedResponse, type CallLimit, type LimitedCall } from "./limits.js";
import type { PrincipalOf, ServerResponse } from "./types.js";
import { LOCAL_CREDENTIALS } from "./request-auth.js";

Expand Down Expand Up @@ -86,11 +86,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<ServerResponse<unknown>> {
function call(server: ProcedureServer, tenant: string | undefined, procedure: string, payload: unknown = {}): Promise<ServerResponse<unknown>> {
return server.handle({
id: `call-${++sent}`,
method: pathToMethod(["notes", procedure]),
payload: {},
payload,
metadata: {},
credentials: tenant !== undefined ? { bearer: `tok-${tenant}` } : LOCAL_CREDENTIALS,
});
Expand Down Expand Up @@ -293,14 +293,61 @@ describe("the limits of the calls of a server (CLI-40)", () => {
expect("limits" in hostPolicy({ limits: [] })).toBe(false);
});

it("gives a capacity refusal as RATE_LIMITED that is not retryable and has no wait", () => {
it("gives a capacity refusal as PAYLOAD_TOO_LARGE that is not retryable, with its units and the capacity", () => {
const response = rateLimitedResponse("1", { limit: "uploads", refused: { allowed: false, cause: "capacity", units: 5, capacity: 3 } });
expect(response.status).toEqual({
type: "error",
code: "RATE_LIMITED",
message: "The limit uploads of the host refuses the call at each time: 5 units are over its capacity of 3",
code: "PAYLOAD_TOO_LARGE",
message: "The limit uploads of the host refuses the call: it costs 5 units, over the capacity of 3",
retryable: false,
});
expect(response.metadata).toEqual({ reason: "capacity" });
expect(response.metadata).toEqual({ reason: "capacity", units: 5, capacity: 3 });
});
});

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/);
});
});
Loading
Loading