diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index a63a822e..654f4743 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -324,7 +324,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 - 멱등성 응답(`IDEMPOTENT_*`, `IDEMPOTENCY_*`)과 V3 표에 있는 web 공통 응답은 V3 실행기와 같은 표(`backend-envelope.ts`, 4절)로 판정한다. 400 `IDEMPOTENCY_KEY_INVALID`·422 `IDEMPOTENT_REQUEST_MISMATCH`는 `NOT_APPLIED`, 409 `IDEMPOTENT_IN_FLIGHT`·503 `IDEMPOTENCY_UNAVAILABLE`·503 `IDEMPOTENCY_COMPLETION_UNKNOWN`·500 `IDEMPOTENCY_RECOVERY_REQUIRED`는 `MAYBE_APPLIED`다. - `APPLIED_CONFIRMED`: 서버는 만들었다고 답했지만 응답을 읽지 못했다. 다시 올리지 않는다. - `code`는 백엔드 code 그대로다(`FILE_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, `MALWARE_DETECTED` …). 백엔드가 code를 주지 않는 거절은 client가 이름을 붙인다(`FILE_REJECTED`, `FILE_EMPTY`, `FILE_NOT_READABLE`). 화면 문구는 기능이 code로 고른다. -- 실패 Envelope의 `meta.traceId`는 실패의 `traceId`로 온다. V3 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다. +- 실패 Envelope의 `meta.traceId`는 실패의 `traceId`로 온다. V3 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다. 202 `REJECTED`의 `FILE_REJECTED`도 성공 Envelope의 `meta.traceId`를 싣는다. 이 응답에는 거절 이유가 없다. 짝 백엔드는 검증기 code를 파일 레코드에만 적는다. 그래서 화면은 이유별 문구를 고를 수 없다. - client는 스스로 다시 보내지 않는다. `retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(`maxRetryAfterMs`, 기본 30초)보다 길게 기다리라고 하면 `retryable: false`다. - `MAYBE_APPLIED`는 언제나 `retryable: false`다. 백엔드가 Envelope에 `retryable: true`와 `Retry-After`를 붙여도(504 `TRANSFER_TIMEOUT`) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다. diff --git a/src/adapters/http/backend-envelope.ts b/src/adapters/http/backend-envelope.ts index b9e0c971..990277a5 100644 --- a/src/adapters/http/backend-envelope.ts +++ b/src/adapters/http/backend-envelope.ts @@ -93,13 +93,23 @@ const ENVELOPE_INVALID: EnvelopeRead = Object.freeze({ ok: false }); /** * The success `data`. A missing key is the null the backend dropped. * 1103/03-02. A page list's `meta.page` comes with it. + * 1106/01-01. And the backend's `meta.traceId`, when it sent one, as + * `readFailureEnvelope` gives it, for a client that turns a well-formed + * answer into a failure (Fileserver's 202 `REJECTED`). */ export function readSuccessEnvelope( value: unknown, -): Readonly<{ ok: true; value: unknown; page?: EnvelopePage }> | Readonly<{ ok: false }> { +): + | Readonly<{ + ok: true; + value: unknown; + page?: EnvelopePage; + traceId?: string; + }> + | Readonly<{ ok: false }> { const parsed = successEnvelopeSchema.safeParse(value); if (!parsed.success) return ENVELOPE_INVALID; - const page = parsed.data.meta.page; + const { page, traceId } = parsed.data.meta; return Object.freeze({ ok: true as const, value: parsed.data.data, @@ -113,6 +123,7 @@ export function readSuccessEnvelope( ...(typeof page.sort === "string" ? { sort: page.sort } : {}), }), }), + ...(traceId === undefined ? {} : { traceId }), }); } diff --git a/src/adapters/http/fileserver-upload.ts b/src/adapters/http/fileserver-upload.ts index 736392ed..5e21d39d 100644 --- a/src/adapters/http/fileserver-upload.ts +++ b/src/adapters/http/fileserver-upload.ts @@ -682,9 +682,15 @@ async function readAnswer( // 1105/01-01. The file is the user's to replace, as with a 413, 415 or // 422 refusal. The backend keeps the record unpublished and schedules // its bytes for removal, so nothing usable was stored. + // 1106/01-01. The server answered, so the failure carries its + // `meta.traceId` as an Envelope failure does (1105/01-03). The answer + // names no reason: the backend keeps the verifier's code on its record. return failure("VALIDATION_REJECTED", "FILE_REJECTED", { httpStatus: status, effect: "NOT_APPLIED", + ...(envelope.traceId === undefined + ? {} + : { traceId: envelope.traceId }), }); } return Object.freeze({ @@ -790,6 +796,7 @@ function failure( details: Readonly<{ effect: FailureEffectCertainty; httpStatus?: number; + traceId?: string; }>, ): Result { return Object.freeze({ diff --git a/tests/integration/fileserver-upload.test.ts b/tests/integration/fileserver-upload.test.ts index c4981fa0..0c9da0a4 100644 --- a/tests/integration/fileserver-upload.test.ts +++ b/tests/integration/fileserver-upload.test.ts @@ -214,6 +214,8 @@ describe("Fileserver multipart upload — success", () => { it("reads 202 REJECTED as a refused file, not as a broken answer", async () => { // 1105/01-01. A verifier refused the file for a reason other than malware. + // 1106/01-01. The server answered, so its `meta.traceId` comes with the + // failure for support to find the upload in the server logs. answer({ status: 202, body: successEnvelope( @@ -233,6 +235,7 @@ describe("Fileserver multipart upload — success", () => { retryable: false, action: "none", operationId: "FILESERVER_UPLOAD", + traceId: "trace-1", }), }); }); diff --git a/tests/runtime-schema/http-schema.test.ts b/tests/runtime-schema/http-schema.test.ts index b30eeeb0..8757e346 100644 --- a/tests/runtime-schema/http-schema.test.ts +++ b/tests/runtime-schema/http-schema.test.ts @@ -19,13 +19,14 @@ describe("paired backend Envelope boundary", () => { }); it("reads data, and a dropped data key as null", () => { + // 1106/01-01. With `meta.traceId`, as the failure reader gives it. expect( readSuccessEnvelope({ success: true, data: [], meta: { requestId: "request-1", traceId: "trace-1" }, }), - ).toEqual({ ok: true, value: [] }); + ).toEqual({ ok: true, value: [], traceId: "trace-1" }); expect(readSuccessEnvelope({ success: true, meta: {} })).toEqual({ ok: true, value: null, diff --git a/tests/unit/a11y-api-answers.test.ts b/tests/unit/a11y-api-answers.test.ts index 3b1f633b..53cb47f0 100644 --- a/tests/unit/a11y-api-answers.test.ts +++ b/tests/unit/a11y-api-answers.test.ts @@ -50,7 +50,12 @@ describe("accessibility e2e API answers", () => { expect(answer.kind).toBe("empty-list"); if (answer.kind !== "empty-list") return; // What the executor reads out of the frame is what the operation accepts. - expect(readSuccessEnvelope(answer.body)).toEqual({ ok: true, value: [] }); + // 1106/01-01. The reader also gives the scenario meta's `traceId`. + expect(readSuccessEnvelope(answer.body)).toEqual({ + ok: true, + value: [], + traceId: "0af7651916cd43dd8448eb211c80319c", + }); expect(LIST!.contract.outputValidator.safeParse([]).success).toBe(true); });