Files
clean-architecture-frontend…/tests/integration/http-execution-v3-envelope.test.ts
T
DongHyeonka bd83b496cc fix(http): V3 Envelope 진단이 V2와 같은 멱등성 거절 reason을 싣는다
문제
V2 클라이언트는 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH와 400
IDEMPOTENCY_KEY_INVALID를 진단(http.request.completed)의 reason으로
남긴다(93782b0). V3 실행기의 진단에는 백엔드 code가 없다(리뷰 README
14.4). Problem 타입이 계약 패키지 소유라 실행기가 code를 몰랐기 때문이다.
7db32e1 뒤로 responseEnvelope: "ENVELOPE_V1" operation의 실행기는
Envelope error.code를 읽는다.

고른 방법
- Envelope operation의 실패에서 backend-envelope.ts의
  idempotencyRefusalReason(code, status)를 불러 V2와 같은 두 값을
  HttpDiagnosticReason으로 싣는다. projector(runtime-adapters.ts)는 이미
  diagnosticReason을 reason으로 옮기므로 bootstrap은 바꾸지 않았다.
- 표의 reason 타입을 IdempotencyRefusalReason으로 좁혀 두 값이 닫힌
  목록임을 타입으로 둔다.

버린 대안
- 백엔드 code를 reason에 그대로 넣기: reason은 이 repo가 소유한 닫힌
  목록(taxonomy)이고, 서버 code를 그대로 넣지 않는다는 93782b0 결정과
  어긋난다. V2도 넣지 않는다.
- 새 진단 키(problem_code) 추가: src/contracts/diagnostics.ts 허용 목록과
  bootstrap projector를 함께 바꿔야 하고 cardinality 등급을 새로 정해야
  한다. 이 변경 범위를 넘는다.

위험·한계
- 그 밖의 백엔드 code는 진단에 없다. 실패의 AppFailure.code에만 있다.
- DTO 모드 operation(참조 기능)의 진단에는 여전히 code가 없다.
- classifyProblem이 던져 CLASSIFIER_FAILED가 되는 경우는 Envelope 판정이
  있으면 분류기를 부르지 않으므로 둘이 겹치지 않는다.

검증
- RED: tests/integration/http-execution-v3-envelope.test.ts의 "V3 Envelope
  diagnostics name what V2 names" 4행 중 2행 실패(422·400에서 V3 reason
  undefined). 409 두 행은 처음부터 통과(reason 없음 고정).
- GREEN: 같은 파일 29건 통과. 같은 응답의 V2 진단 기록과 V3 진단 기록의
  reason을 비교한다.
- check:types, lint, check:architecture, check:diagnostics 통과.
  test:unit 2,604, test:integration 204, test:component 244,
  tests/features·tests/contract 124건 통과.
- check:bundle 통과(203,352 / 204,800 B, 7db32e1 대비 +31 B).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6
2026-11-03 20:13:02 +09:00

722 lines
23 KiB
TypeScript

import { HttpResponse, http, type JsonBodyType } from "msw";
import { setupServer } from "msw/node";
import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
import { z } from "zod";
import { createHttpClient } from "../../src/adapters/http/client.ts";
import {
createContractHttpExecutor,
createFeatureHttpBinding,
defineFeatureHttpOperation,
type HttpExecutionObservation,
type InstalledHttpOperationExecutor,
} from "../../src/adapters/http/index.ts";
import { createHttpObservationProjector } from "../../src/bootstrap/runtime-adapters.ts";
import type { DiagnosticRecordInput } from "../../src/contracts/diagnostics.ts";
import { mappingSuccess } from "../../src/contracts/boundary-mapper.ts";
import type { AppFailure } from "../../src/contracts/errors.ts";
import {
composeContractContributions,
type CommandEffectDescriptor,
type InstalledHttpContract,
} from "../../src/contracts/external-contract-runtime.ts";
import { zodValidator } from "../../src/contracts/zod-validator.ts";
import { createDemoSessionAdapter } from "../../src/adapters/auth/external-session-adapter.ts";
import { TEST_CONTRACT_CONTRIBUTION } from "../helpers/external-contract-fixture.ts";
import { createHttpScenarioHandler } from "../mocks/handlers/http-scenarios.ts";
/**
* 1101 README 14.3. The paired backend answers every JSON body as an Envelope
* (clean-architecture-backend-template docs/web/http-contract.md §1) and drops
* a null field together with its key. A V3 operation that declares
* `responseEnvelope: "ENVELOPE_V1"` reads it, and reaches the verdict the V2
* client reaches for the same answer (§2 idempotency, §4 VALIDATION_FAILED).
*/
const BASE_URL = "https://api.test";
const LIST_LIMIT = 2_048;
const itemSchema = z
.object({
id: z.string().min(1),
name: z.string().min(1),
// The backend drops a null field with its key.
description: z.string().optional(),
})
.strip();
/** What the scaffold generates as the problem: the Envelope's `error`. */
const errorSchema = z
.object({
code: z.string().regex(/^[A-Z0-9_]{1,64}$/u),
category: z.string().min(1).max(64).optional(),
retryable: z.boolean().optional(),
details: z.unknown().optional(),
})
.strip();
type EnvelopeProblem = z.output<typeof errorSchema>;
const problemValidator = zodValidator("EnvelopeTestProblem", errorSchema);
const noInput = zodValidator("EnvelopeTestNoInput", z.object({}).strict());
function readPolicy(policyId: string) {
return Object.freeze({
policyId,
requestByteLimit: 0,
responseByteLimit: LIST_LIMIT,
totalDeadlineMs: 10_000,
retryBudget: 0 as const,
authProfileId: "ANONYMOUS",
diagnosticsOperation: "envelope.read",
});
}
const LIST_CONTRACT = Object.freeze({
contract: Object.freeze({
operationId: "ENVELOPE_LIST_ITEMS",
method: "GET" as const,
pathTemplate: "/api/envelope-items",
inputValidator: noInput,
outputValidator: zodValidator(
"EnvelopeTestItemList",
z.array(itemSchema).max(100),
),
problemValidator,
acceptedStatuses: Object.freeze([200]),
emptyBodyStatuses: Object.freeze([]),
retrySemantics: "SAFE" as const,
requestBody: "NONE" as const,
responseBody: "REQUIRED_JSON" as const,
responseEnvelope: "ENVELOPE_V1" as const,
commandRecovery: null,
commandEffect: null,
projectRequest: () =>
Object.freeze({
pathValues: Object.freeze({}),
queryEntries: Object.freeze([]),
body: null,
}),
}),
frontend: readPolicy("ENVELOPE_LIST_V1"),
}) satisfies InstalledHttpContract<
Readonly<Record<never, never>>,
readonly z.output<typeof itemSchema>[],
EnvelopeProblem
>;
/** A success whose `data` is null: the backend sends no `data` key. */
const ARCHIVE_CONTRACT = Object.freeze({
contract: Object.freeze({
...LIST_CONTRACT.contract,
operationId: "ENVELOPE_ARCHIVE_ITEMS",
method: "POST" as const,
pathTemplate: "/api/envelope-items/archive",
outputValidator: zodValidator("EnvelopeTestNull", z.null()),
retrySemantics: "KEYED" as const,
requestBody: "JSON" as const,
commandRecovery: Object.freeze({
mode: "IDEMPOTENCY_REPLAY" as const,
operationIdentityField: "idempotencyKey",
}),
commandEffect: Object.freeze({
successEffect: "APPLIED_CONFIRMED" as const,
classifyProblem: () => "MAYBE_APPLIED" as const,
}) satisfies CommandEffectDescriptor<EnvelopeProblem>,
}),
frontend: Object.freeze({
...readPolicy("ENVELOPE_ARCHIVE_V1"),
requestByteLimit: 1_024,
diagnosticsOperation: "envelope.archive",
}),
}) satisfies InstalledHttpContract<
Readonly<Record<never, never>>,
null,
EnvelopeProblem
>;
/**
* The most conservative package classifier: every problem may have applied.
* What the V3 run then says NOT_APPLIED comes from the backend's own
* operation-independent refusals.
*/
const CREATE_CONTRACT = Object.freeze({
contract: Object.freeze({
...ARCHIVE_CONTRACT.contract,
operationId: "ENVELOPE_CREATE_ITEM",
pathTemplate: "/api/envelope-items",
outputValidator: zodValidator("EnvelopeTestItem", itemSchema),
acceptedStatuses: Object.freeze([201]),
}),
frontend: Object.freeze({
...ARCHIVE_CONTRACT.frontend,
policyId: "ENVELOPE_CREATE_V1",
diagnosticsOperation: "envelope.create",
}),
}) satisfies InstalledHttpContract<
Readonly<Record<never, never>>,
z.output<typeof itemSchema>,
EnvelopeProblem
>;
/** A package that reads every 409 as a domain conflict refused untouched. */
const CREATE_CONFLICT_NOT_APPLIED_CONTRACT = Object.freeze({
...CREATE_CONTRACT,
contract: Object.freeze({
...CREATE_CONTRACT.contract,
commandEffect: Object.freeze({
successEffect: "APPLIED_CONFIRMED" as const,
classifyProblem: ({ status }: Readonly<{ status: number }>) =>
status === 409 || status === 503 ? "NOT_APPLIED" : "MAYBE_APPLIED",
}) satisfies CommandEffectDescriptor<EnvelopeProblem>,
}),
});
const OPERATIONS = Object.freeze({
ENVELOPE_LIST_ITEMS: defineFeatureHttpOperation({
contract: LIST_CONTRACT,
routeId: "ENVELOPE_ROUTE",
mapSuccess: (value) => mappingSuccess(value),
}),
ENVELOPE_ARCHIVE_ITEMS: defineFeatureHttpOperation({
contract: ARCHIVE_CONTRACT,
routeId: "ENVELOPE_ROUTE",
mapSuccess: (value) => mappingSuccess(value),
}),
ENVELOPE_CREATE_ITEM: defineFeatureHttpOperation({
contract: CREATE_CONTRACT,
routeId: "ENVELOPE_ROUTE",
mapSuccess: (value) => mappingSuccess(value),
}),
});
const CONFLICT_OPERATIONS = Object.freeze({
ENVELOPE_CREATE_ITEM: defineFeatureHttpOperation({
contract: CREATE_CONFLICT_NOT_APPLIED_CONTRACT,
routeId: "ENVELOPE_ROUTE",
mapSuccess: (value) => mappingSuccess(value),
}),
});
const META = Object.freeze({
requestId: "req-1",
traceId: "0af7651916cd43dd8448eb211c80319c",
correlationId: "corr-1",
});
function success(data: JsonBodyType, meta: JsonBodyType = META) {
return { success: true, ...(data === null ? {} : { data }), meta };
}
function failure(
code: string,
category: string,
retryable: boolean,
details?: JsonBodyType,
) {
return {
success: false,
error: {
code,
category,
message: "서버가 보낸 문구",
retryable,
...(details === undefined ? {} : { details }),
},
meta: META,
};
}
const server = setupServer();
beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
function answer(
method: "get" | "post",
path: string,
body: JsonBodyType,
init: Readonly<{ status?: number; headers?: Record<string, string> }> = {},
) {
server.use(
http[method](`${BASE_URL}${path}`, () =>
HttpResponse.json(body, {
status: init.status ?? 200,
...(init.headers === undefined ? {} : { headers: init.headers }),
}),
),
);
}
function scope() {
return Object.freeze({
generation: 1,
fingerprint: "envelope-scope",
identities: Object.freeze({}) as never,
signal: new AbortController().signal,
isCurrent: () => true,
});
}
function v3Executor(
fetcher?: typeof fetch,
observe?: (observation: HttpExecutionObservation) => void,
): InstalledHttpOperationExecutor {
const executor = createContractHttpExecutor({
baseUrl: BASE_URL,
...(fetcher === undefined ? {} : { fetcher }),
...(observe === undefined ? {} : { observe }),
maxRetryAttempts: 0,
attachCredentials: () => ({ kind: "READY" as const, headers: {} }),
random: () => 0,
});
return Object.freeze({
execute(contract, input, context) {
return executor.execute(contract, input, {
routeId: context.routeId,
scope: scope(),
...(context.intent === undefined ? {} : { intent: context.intent }),
});
},
});
}
function v3(fetcher?: typeof fetch) {
return createFeatureHttpBinding(v3Executor(fetcher), OPERATIONS);
}
const KEY = "envelope-key-1";
function intent(operationId: string) {
return Object.freeze({
intentId: `intent-${operationId}`,
operationId,
canonicalInputIdentity: "{}",
idempotencyKey: KEY,
createdAtMonotonicMs: 0,
});
}
/** The same paths as V2 rows; V2 always reads the Envelope. */
const V2_OPERATIONS = Object.freeze({
ENVELOPE_LIST_ITEMS: Object.freeze({
method: "GET",
path: "/api/envelope-items",
operationId: "ENVELOPE_LIST_ITEMS",
auth: "external-session",
timeoutMs: null,
idempotency: "safe",
retry: "runtime",
requestSource: "none",
requestSchema: "EnvelopeTestNoInput",
responseSchema: "EnvelopeTestItemList",
maxResponseBytes: LIST_LIMIT,
owner: "test-fixture",
}),
ENVELOPE_CREATE_ITEM: Object.freeze({
method: "POST",
path: "/api/envelope-items",
operationId: "ENVELOPE_CREATE_ITEM",
auth: "external-session",
timeoutMs: null,
idempotency: "keyed",
retry: "never",
requestSource: "body",
requestSchema: "EnvelopeTestNoInput",
responseSchema: "EnvelopeTestItem",
successStatuses: [201],
maxResponseBytes: LIST_LIMIT,
owner: "test-fixture",
}),
});
const V2_PAYLOADS: Readonly<Record<string, z.ZodType>> = Object.freeze({
EnvelopeTestItemList: z.array(itemSchema).max(100),
EnvelopeTestItem: itemSchema,
});
function v2(
fetcher?: typeof fetch,
diagnostics?: Readonly<{ record(input: DiagnosticRecordInput): void }>,
) {
return createHttpClient({
baseUrl: BASE_URL,
...(fetcher === undefined ? {} : { fetcher }),
...(diagnostics === undefined ? {} : { diagnostics }),
maxRetryAttempts: 0,
clock: { now: () => 0, sleep: async () => {} },
authSession: createDemoSessionAdapter("authenticated"),
getOperation: (operationId: string) =>
V2_OPERATIONS[operationId as keyof typeof V2_OPERATIONS],
validatePayload(schemaId: string, value: unknown) {
const parsed = V2_PAYLOADS[schemaId]?.safeParse(value);
return parsed?.success
? { success: true as const, data: parsed.data }
: { success: false as const, issues: [] };
},
validateRequest: (_schemaId: string, value: unknown) => ({
success: true as const,
data: value,
}),
mapPayload: (_operationId: string, payload: unknown) =>
mappingSuccess(payload),
});
}
/** What the mutation coordinator reads (`mutationFailureWithEffect`). */
function verdict(error: AppFailure) {
return {
kind: error.kind,
code: error.code,
httpStatus: error.httpStatus,
effect:
error.effect === undefined || error.effect === "NOT_APPLICABLE"
? "MAYBE_APPLIED"
: error.effect,
retryAfterMs: error.retryAfterMs,
validationIssues: error.validationIssues,
};
}
async function v2CreateFailure(): Promise<AppFailure> {
const result = await v2().execute("ENVELOPE_CREATE_ITEM", {
body: {},
idempotencyKey: KEY,
});
if (result.ok) throw new Error("V2 create unexpectedly succeeded");
return result.error;
}
async function v3CreateFailure(
binding: Pick<ReturnType<typeof v3>, "execute"> = v3(),
): Promise<AppFailure> {
const result = await binding.execute(
"ENVELOPE_CREATE_ITEM",
Object.freeze({}),
{ intent: intent("ENVELOPE_CREATE_ITEM") },
);
if (result.ok) throw new Error("V3 create unexpectedly succeeded");
return result.error;
}
describe("V3 operation that reads the paired backend's Envelope", () => {
it("reads the success data and ignores meta keys it does not know", async () => {
answer(
"get",
"/api/envelope-items",
success([{ id: "item-1", name: "First" }], {
...META,
page: { number: 0, size: 20, total: 1, sort: null },
}),
);
await expect(
v3().execute("ENVELOPE_LIST_ITEMS", Object.freeze({})),
).resolves.toEqual({
ok: true,
value: [{ id: "item-1", name: "First" }],
});
});
it("reads keys the backend dropped as null: a DTO field, the meta ids and the data", async () => {
answer("get", "/api/envelope-items", success([{ id: "item-1", name: "First" }], {}));
await expect(
v3().execute("ENVELOPE_LIST_ITEMS", Object.freeze({})),
).resolves.toEqual({ ok: true, value: [{ id: "item-1", name: "First" }] });
answer("post", "/api/envelope-items/archive", success(null));
await expect(
v3().execute("ENVELOPE_ARCHIVE_ITEMS", Object.freeze({}), {
intent: intent("ENVELOPE_ARCHIVE_ITEMS"),
}),
).resolves.toEqual({ ok: true, value: null });
});
it("reads the failure error's code and keeps the backend message out", async () => {
answer("get", "/api/envelope-items", failure("NOT_FOUND", "NOT_FOUND", false), {
status: 404,
});
const result = await v3().execute(
"ENVELOPE_LIST_ITEMS",
Object.freeze({}),
);
expect(result).toMatchObject({
ok: false,
error: { kind: "NOT_FOUND", code: "NOT_FOUND", httpStatus: 404 },
});
expect(JSON.stringify(result)).not.toContain("서버가 보낸 문구");
});
it.each([
["a bare DTO", [{ id: "item-1", name: "First" }]],
["a failure Envelope", failure("NOT_FOUND", "NOT_FOUND", false)],
["a success Envelope that also carries error", { ...success([]), error: { code: "X" } }],
])("rejects %s on a success status as an Envelope mismatch", async (_label, body) => {
answer("get", "/api/envelope-items", body as JsonBodyType);
await expect(
v3().execute("ENVELOPE_LIST_ITEMS", Object.freeze({})),
).resolves.toMatchObject({
ok: false,
error: { kind: "ENVELOPE_MISMATCH", code: "ENVELOPE_MISMATCH" },
});
});
it("counts the whole Envelope against the byte limit, as V2 counts maxResponseBytes", async () => {
// The data alone fits the limit; with its frame it does not.
const name = "n".repeat(LIST_LIMIT - 120);
const data = [{ id: "item-1", name }];
expect(JSON.stringify(data).length).toBeLessThan(LIST_LIMIT);
expect(JSON.stringify(success(data)).length).toBeGreaterThan(LIST_LIMIT);
// A native Response, as http-execution-contract.test.ts uses: MSW never
// settles a cancel() on a body it is still streaming.
const fetcher = (async () => Response.json(success(data))) as typeof fetch;
const v3Result = await v3(fetcher).execute(
"ENVELOPE_LIST_ITEMS",
Object.freeze({}),
);
const v2Result = await v2(fetcher).execute("ENVELOPE_LIST_ITEMS", {});
expect(v3Result).toMatchObject({ ok: false, error: { kind: "RESPONSE_BODY_LIMIT" } });
expect(v2Result).toMatchObject({ ok: false, error: { kind: "RESPONSE_BODY_LIMIT" } });
});
it("applies the structure budget to the whole Envelope, not only data", async () => {
let deep: JsonBodyType = "leaf";
for (let depth = 0; depth < 70; depth += 1) deep = { nested: deep };
answer("get", "/api/envelope-items", success([], { ...META, deep }));
await expect(
v3().execute("ENVELOPE_LIST_ITEMS", Object.freeze({})),
).resolves.toMatchObject({
ok: false,
error: { kind: "RESPONSE_BODY_LIMIT", code: "RESPONSE_TOO_LARGE" },
});
});
});
describe("V3 Envelope verdicts equal the V2 client's for the same answer", () => {
const cases: readonly (readonly [
string,
Readonly<{ status: number; body: JsonBodyType; headers?: Record<string, string> }>,
])[] = [
[
"409 IDEMPOTENT_IN_FLIGHT",
{
status: 409,
body: failure("IDEMPOTENT_IN_FLIGHT", "CONFLICT", true),
headers: { "Retry-After": "2" },
},
],
[
"422 IDEMPOTENT_REQUEST_MISMATCH",
{ status: 422, body: failure("IDEMPOTENT_REQUEST_MISMATCH", "VALIDATION", false) },
],
[
"400 IDEMPOTENCY_KEY_INVALID",
{
status: 400,
body: failure("IDEMPOTENCY_KEY_INVALID", "VALIDATION", false, {
reason: "MALFORMED",
}),
},
],
[
"503 IDEMPOTENCY_UNAVAILABLE",
{
status: 503,
body: failure("IDEMPOTENCY_UNAVAILABLE", "TRANSIENT_DEPENDENCY", true),
},
],
[
"400 VALIDATION_FAILED with the field list",
{
status: 400,
body: failure("VALIDATION_FAILED", "VALIDATION", false, [
{ field: "name", code: "NOT_BLANK", message: "비어 있으면 안 됩니다" },
]),
},
],
[
"400 VALIDATION_FAILED without a field list",
{
status: 400,
body: failure("VALIDATION_FAILED", "VALIDATION", false, {
cause: "JsonParseException",
}),
},
],
[
"409 domain conflict",
{ status: 409, body: failure("RESOURCE_CONFLICT", "CONFLICT", false) },
],
];
it.each(cases)("%s", async (_label, response) => {
answer("post", "/api/envelope-items", response.body, response);
const v2Verdict = verdict(await v2CreateFailure());
const v3Verdict = verdict(await v3CreateFailure());
expect(v3Verdict).toEqual(v2Verdict);
});
it("pins what those verdicts are", async () => {
const read = async (response: (typeof cases)[number][1]) => {
answer("post", "/api/envelope-items", response.body, response);
return verdict(await v3CreateFailure());
};
const byLabel = new Map(cases);
await expect(read(byLabel.get("409 IDEMPOTENT_IN_FLIGHT")!)).resolves.toMatchObject({
kind: "CONFLICT",
effect: "MAYBE_APPLIED",
retryAfterMs: 2_000,
});
await expect(
read(byLabel.get("422 IDEMPOTENT_REQUEST_MISMATCH")!),
).resolves.toMatchObject({ kind: "VALIDATION_REJECTED", effect: "NOT_APPLIED" });
await expect(read(byLabel.get("400 IDEMPOTENCY_KEY_INVALID")!)).resolves.toMatchObject({
kind: "UNKNOWN_CLIENT_FAILURE",
code: "IDEMPOTENCY_KEY_INVALID",
effect: "NOT_APPLIED",
});
await expect(read(byLabel.get("503 IDEMPOTENCY_UNAVAILABLE")!)).resolves.toMatchObject({
kind: "SERVER_FAILURE",
effect: "MAYBE_APPLIED",
});
await expect(
read(byLabel.get("400 VALIDATION_FAILED with the field list")!),
).resolves.toMatchObject({
kind: "VALIDATION_REJECTED",
effect: "NOT_APPLIED",
validationIssues: [{ path: "name", code: "NOT_BLANK" }],
});
});
it("keeps an in-flight 409 and an idempotency 503 uncertain even when the package calls them not applied", async () => {
const conflict = createFeatureHttpBinding(v3Executor(), CONFLICT_OPERATIONS);
answer(
"post",
"/api/envelope-items",
failure("IDEMPOTENT_IN_FLIGHT", "CONFLICT", true),
{ status: 409, headers: { "Retry-After": "2" } },
);
await expect(v3CreateFailure(conflict)).resolves.toMatchObject({
effect: "MAYBE_APPLIED",
});
answer(
"post",
"/api/envelope-items",
failure("IDEMPOTENCY_UNAVAILABLE", "TRANSIENT_DEPENDENCY", true),
{ status: 503 },
);
await expect(v3CreateFailure(conflict)).resolves.toMatchObject({
effect: "MAYBE_APPLIED",
});
// A domain 409 is the package's to classify.
answer("post", "/api/envelope-items", failure("RESOURCE_CONFLICT", "CONFLICT", false), {
status: 409,
});
await expect(v3CreateFailure(conflict)).resolves.toMatchObject({
effect: "NOT_APPLIED",
});
});
});
// 1101 README 14.4. V2 names an idempotency refusal in diagnostics (`reason`,
// a closed taxonomy). An Envelope operation's executor now knows the backend
// code and names the same ones; any other code stays out of diagnostics.
describe("V3 Envelope diagnostics name what V2 names", () => {
it.each([
["422 IDEMPOTENT_REQUEST_MISMATCH", 422, "IDEMPOTENT_REQUEST_MISMATCH", "IDEMPOTENT_REQUEST_MISMATCH"],
["400 IDEMPOTENCY_KEY_INVALID", 400, "IDEMPOTENCY_KEY_INVALID", "IDEMPOTENCY_KEY_RULE_MISMATCH"],
["409 IDEMPOTENT_IN_FLIGHT", 409, "IDEMPOTENT_IN_FLIGHT", undefined],
["409 domain conflict", 409, "RESOURCE_CONFLICT", undefined],
] as const)("%s", async (_label, status, code, reason) => {
answer("post", "/api/envelope-items", failure(code, "VALIDATION", false), { status });
const v2Records: DiagnosticRecordInput[] = [];
const v3Records: DiagnosticRecordInput[] = [];
const project = createHttpObservationProjector({
diagnostics: { record: (input) => v3Records.push(input) },
telemetry: { emit: () => {} },
});
await v2(undefined, { record: (input) => v2Records.push(input) }).execute(
"ENVELOPE_CREATE_ITEM",
{ body: {}, idempotencyKey: KEY },
);
await v3CreateFailure(
createFeatureHttpBinding(v3Executor(undefined, project), OPERATIONS),
);
expect(v2Records).toHaveLength(1);
expect(v3Records).toHaveLength(1);
expect(v3Records[0]?.context?.reason).toBe(reason);
expect(v3Records[0]?.context?.reason).toBe(v2Records[0]?.context?.reason);
});
});
describe("shared MSW scenarios for an Envelope operation", () => {
it.each([
["success", { ok: true, value: [{ id: "item-1", name: "First" }] }],
["empty", { ok: true, value: [] }],
["not-found-404", { ok: false, error: { kind: "NOT_FOUND", code: "NOT_FOUND" } }],
[
"server-terminal-503",
{ ok: false, error: { kind: "SERVER_FAILURE", code: "SERVER_FAILURE" } },
],
[
"envelope-mismatch",
{ ok: false, error: { kind: "ENVELOPE_MISMATCH", code: "ENVELOPE_MISMATCH" } },
],
[
"schema-mismatch",
{ ok: false, error: { kind: "SCHEMA_MISMATCH", code: "SUCCESS_SCHEMA_INVALID" } },
],
] as const)("answers %s in the backend's frame", async (scenario, expected) => {
server.use(
createHttpScenarioHandler(LIST_CONTRACT, {
scenario,
payload: [{ id: "item-1", name: "First" }],
}),
);
await expect(
v3().execute("ENVELOPE_LIST_ITEMS", Object.freeze({})),
).resolves.toMatchObject(expected);
});
});
describe("Envelope declaration at composition", () => {
function contribution(responseEnvelope: unknown) {
return Object.freeze({
contributionId: "envelope-test-http-v1",
featureId: "envelope-test",
source: TEST_CONTRACT_CONTRIBUTION.source,
http: Object.freeze([
Object.freeze({
...LIST_CONTRACT,
contract: Object.freeze({ ...LIST_CONTRACT.contract, responseEnvelope }),
}),
]) as never,
events: Object.freeze([]),
});
}
it("installs an operation that declares the Envelope and keeps the declaration", () => {
const composed = composeContractContributions([contribution("ENVELOPE_V1")]);
expect(
composed.httpByOperationId.get("ENVELOPE_LIST_ITEMS")?.contract.responseEnvelope,
).toBe("ENVELOPE_V1");
});
it("refuses a framing it does not know", () => {
expect(() => composeContractContributions([contribution("PROBLEM_JSON")])).toThrow(
expect.objectContaining({ reason: "envelope-test/ENVELOPE_LIST_ITEMS: responseEnvelope" }),
);
});
});