import { describe, expect, it } from "vitest"; import { composeApiOperations, defineRestOperation, type RestOperationV2, } from "../../src/contracts/api-operations.ts"; import { API_OPERATIONS } from "../../src/features/loaded-feature-runtimes.ts"; function operation(operationId = "GET_RESOURCE") { return defineRestOperation({ contractVersion: 2, protocol: "REST", semantics: "QUERY", method: "GET", path: "/resources/{resourceId}", operationId, auth: "external-session", timeoutMs: 5_000, idempotency: "safe", retry: "runtime", replayPolicy: "SAFE", idempotencyKeyPolicy: "NONE", requestSource: "none", requestSchema: "NoRequest", responseSchema: "ResourcePayload", mapperId: "ResourceMapper", successStatuses: [200], responseMediaTypes: ["application/json"], maxResponseBytes: 32_768, providerId: "PRIMARY_API", authProfileId: "EXTERNAL_BEARER", csrfProfileId: "NO_CSRF_BEARER", pathSchema: "ResourceParams", pathParameterNames: ["resourceId"], maxEncodedSearchBytes: 0, owner: "test", }); } describe("REST operation v2 registry", () => { it("rejects duplicate contributions before an object spread can overwrite them", () => { const selected = operation(); expect(() => composeApiOperations([ { GET_RESOURCE: selected }, { GET_RESOURCE: selected }, ]), ).toThrow("Duplicate API operation"); }); it("rejects an unsafe query/replay policy combination", () => { expect(() => defineRestOperation({ ...operation(), method: "POST", }), ).toThrow("Incoherent REST replay contract"); }); // 07-06 (MX5). A KEYED command without a required idempotency key would be // resent with no key to bind the retry to. it("rejects a KEYED_COMMAND whose idempotency key is not required", () => { expect(() => defineRestOperation({ ...command(), idempotencyKeyPolicy: "NONE" }), ).toThrow("Incoherent REST replay contract: CREATE_RESOURCE"); expect(defineRestOperation(command()).idempotencyKeyPolicy).toBe("REQUIRED"); }); }); function command(): RestOperationV2 { return { ...operation(), semantics: "COMMAND", method: "POST", path: "/resources", operationId: "CREATE_RESOURCE", idempotency: "keyed", replayPolicy: "KEYED_COMMAND", idempotencyKeyPolicy: "REQUIRED", requestSource: "body", pathSchema: "NoRequest", pathParameterNames: [], }; } /** * R-7.4. CSRF protection is chosen from the HTTP method, so a COMMAND sent * as GET/HEAD would skip it. browser-rpc and the V3 composition already bind * commands to unsafe methods; REST V2 must too. */ describe("REST operation v2 command method and enum rules", () => { it.each(["POST", "PUT", "PATCH", "DELETE"])("accepts a COMMAND sent as %s", (method) => { expect(defineRestOperation({ ...command(), method }).method).toBe(method); }); it.each(["GET", "HEAD", "OPTIONS", "post"])("rejects a COMMAND sent as %s", (method) => { expect(() => defineRestOperation({ ...command(), method })).toThrow(TypeError); expect(() => composeApiOperations([{ CREATE_RESOURCE: { ...command(), method } }]), ).toThrow(TypeError); }); it.each<[string, Record]>([ ["semantics", { semantics: "SUBSCRIBE" }], ["replayPolicy", { replayPolicy: "ALWAYS" }], ])("rejects an unknown %s value", (_field, patch) => { void _field; const candidate = { ...command(), ...patch } as unknown as RestOperationV2; expect(() => defineRestOperation(candidate)).toThrow(TypeError); }); it("keeps every installed REST v2 operation valid", () => { for (const installed of Object.values(API_OPERATIONS)) { if (installed.contractVersion !== 2) continue; expect( () => defineRestOperation(installed as RestOperationV2), installed.operationId, ).not.toThrow(); } }); });