diff --git a/.changeset/call-cost.md b/.changeset/call-cost.md new file mode 100644 index 000000000..e60d87267 --- /dev/null +++ b/.changeset/call-cost.md @@ -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. 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 bbfa04104..9ace656b1 100644 --- a/packages/client-mcp/src/transport/mcp-transport.ts +++ b/packages/client-mcp/src/transport/mcp-transport.ts @@ -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: [ { @@ -532,6 +536,7 @@ export class McpServerTransport implements ServerTransport { retryable: response.status.retryable === true, ...(reason ? { reason } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), + ...(sized ? { units, capacity } : {}), }, }; } 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 }), diff --git a/packages/client/src/adapters/http/client/batch.ts b/packages/client/src/adapters/http/client/batch.ts index aeb212c6f..1763cf999 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"; @@ -457,7 +457,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 }; @@ -465,5 +465,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 62f58bb50..e48fef14a 100644 --- a/packages/client/src/server/limits.test.ts +++ b/packages/client/src/server/limits.test.ts @@ -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"; @@ -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> { +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, }); @@ -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/); }); }); diff --git a/packages/client/src/server/limits.ts b/packages/client/src/server/limits.ts index 2f87a20bc..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,9 +259,9 @@ 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. - * A refusal with the cause `capacity` is not retryable and has no wait: no wait lets its units in. + * 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; @@ -245,11 +270,11 @@ export function rateLimitedResponse(id: string, refusal: CallLimitRefusal): Serv id, status: { type: "error", - code: "RATE_LIMITED", - message: `The limit ${limit} of the host refuses the call at each time: ${refused.units} units are over its capacity of ${refused.capacity}`, + 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 }, + metadata: { reason: refused.cause, units: refused.units, capacity: refused.capacity }, }; } const waitMs = valueIn(refused.retryAfter, "ms"); 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 cc142d627..27520e188 100644 --- a/packages/client/test/api/public-api.txt +++ b/packages/client/test/api/public-api.txt @@ -6406,6 +6406,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 @@ -6888,6 +6889,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