Commit Graph
8 Commits
Author SHA1 Message Date
DongHyeonka 47fec5c27c fix(query): 처리 중 409의 Retry-After 전 재전송은 그 시각까지 기다린다 (백엔드 1101/02-01)
문제
짝 백엔드는 같은 키의 첫 요청이 아직 실행 중이면 409
IDEMPOTENT_IN_FLIGHT, retryable=true, Retry-After: 2를 준다(백엔드
docs/web/http-contract.md §2). 클라이언트 행동은 "같은 키로 Retry-After 뒤
재전송"이다.
- 같은 키: 0929/03-01이 이 409를 MAYBE_APPLIED로 두어 코디네이터가 intent를
  붙든다. 재전송은 같은 키를 쓴다(기존 vertical 테스트가 [K, K, K]를
  고정). 이 부분은 이미 맞다.
- Retry-After: 지키지 않는다. V3는 응답 metadata에 retryAfterMs를 읽지만
  feature binding이 PROBLEM을 AppFailure로 옮길 때 버린다. V2는 409의
  Retry-After를 읽지 않는다. 그래서 결과 불명 화면의 "같은 요청으로 다시
  보내기"(또는 같은 입력 다시 저장)를 바로 누르면 즉시 나가서 같은 409를
  한 번 더 받는다.

고른 방법
재전송이 그 시각 전이면 기다렸다 보낸다.
- feature binding이 PROBLEM의 metadata.retryAfterMs를 AppFailure에 싣는다.
  V2는 409의 Retry-After도 읽는다(409는 여전히 자동 재시도하지 않는다).
- mutation 코디네이터(application-query.ts)가 MAYBE_APPLIED로 남기는
  admission에 resendNotBefore = 지금 + min(retryAfterMs, 5초)를 적는다.
  같은 intent를 다시 쓰는 submit(재전송 버튼, 같은 입력 저장)이 그 시각까지
  기다린 뒤 보낸다. 기다리는 동안 admission이 ACTIVE라 화면은 pending이다.
  scope가 바뀌면 기존 mutationFn 검사가 NOT_STARTED로 막는다.
- 상한 5초는 V3 실행기의 Retry-After 상한(RETRY_AFTER_CEILING_MS)과 같다.
  더 일찍 보내도 같은 키라 서버가 다시 409를 줄 뿐 두 번 적용하지 않으므로,
  긴 Retry-After를 다 기다리게 하지 않는다.

버린 대안
- Retry-After 전에는 버튼을 막기: 화면과 시각 회귀 골든이 바뀌고, 다시
  열어 줄 타이머와 문구가 더 든다. 기다렸다 보내는 쪽이 변경이 작다.
- V3 실행기가 키별 "이 시각 전 금지" 표를 들기: 실행기에 키를 기억하는
  상태와 정리 규칙이 생긴다. 재전송을 만드는 곳은 코디네이터 하나다.
- 그대로 두기(이른 재전송은 409를 한 번 더 받을 뿐): 서버 문서가 허용하는
  동작이지만 사용자는 같은 결과 불명 화면을 한 번 더 본다. 요구는
  Retry-After를 지키는 것이다.

위험·한계
- AppFailure.retryAfterMs가 V3 PROBLEM에도 실린다(추가 필드). 이 값을 읽는
  곳은 코디네이터뿐이다.
- 기다림은 MAYBE_APPLIED로 남은 admission을 다시 보낼 때만 생긴다. 다른
  상태(NOT_APPLIED 등)는 그대로다.
- 시계는 performance.now(), 대기는 setTimeout이다. 탭이 백그라운드면
  브라우저가 타이머를 늦출 수 있다(더 늦게 보낼 뿐이다).

검증
- RED: 4행 실패.
  - tests/features/reference-feature/reference-production-vertical.test.tsx
    처리 중 409(Retry-After: 1) 뒤 재전송 간격 39.7ms(기대 990ms 이상)
  - tests/component/application-mutation-admission.test.tsx 재전송이
    retryAfterMs 300을 기다리지 않음
  - tests/features/reference-feature/reference-http-problem-mapping.test.ts
    retryAfterMs 없음
  - tests/integration/http-client.test.ts V2 409 retryAfterMs 없음
  상한 행은 수정 전에도 통과하고, 상한을 뺀 변이에서 시간 초과로 실패하는
  것을 확인했다.
- GREEN: 위 행 모두 통과. tests/component·features·contract/reusable-
  capability, tests/integration/http-client·http-diagnostics, tests/unit/
  http-execution-v3 62 files 491 tests 통과. tsc app·test 통과, 바꾼 파일
  eslint 통과.

Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
2026-11-03 02:00:45 +09:00
DongHyeonka 969979d904 fix(http): 짝 백엔드가 생략한 Envelope 키를 null과 같이 읽는다 (백엔드 1101/02-02)
문제
짝 백엔드는 이제 값이 null인 필드를 키째 뺀다(백엔드
docs/web/http-contract.md §1). V2 Envelope 스키마
(src/adapters/http/schema-registry.ts)는 두 곳에서 "키 없음"을 null과
다르게 읽는다.
- 성공 응답의 data: z.unknown()은 키가 없으면 거절한다(zod 4). 백엔드가
  data:null을 빼고 보낸 성공이 ENVELOPE_MISMATCH 실패가 된다. data:null은
  그대로 통과한다.
- meta.requestId·traceId가 필수다. 백엔드는 요청 id 필터 앞에서 끊긴
  응답(보안 entry point 등)에서 이 키를 뺄 수 있다고 적는다. 그러면 실패
  Envelope 전체가 거절되어 백엔드 error.code가 HTTP_FAILURE로 바뀐다.
error.details(키 없음 허용), meta.correlationId(선택), meta.page(strip)는
이미 키가 없어도 받는다.

고른 방법
- data를 z.unknown().default(null)로 둔다. 키가 없으면 스키마가 null을
  채우므로 client.ts의 "data" in 검사와 payload 검증이 data:null과 같은
  길을 탄다. 정규화가 wire 스키마 한 곳에 있다.
- meta.requestId·traceId를 optional로 둔다. safeMeta()는 이미 키가 없는
  경우를 처리한다.

버린 대안
- client.ts에서 "data" in 검사를 빼고 data ?? null로 읽기: 스키마와
  클라이언트 두 곳이 같은 규칙을 나눠 갖는다.
- 성공의 error:null, 실패의 data:null도 다시 받기: 백엔드가 더는 보내지
  않는 모양이다. 최상위 strict는 그대로 둔다.

위험·한계
- meta id가 없는 Envelope도 이제 유효하다. 그런 응답의 HttpResult.meta와
  AppFailure에는 requestId·traceId가 없다(이전에는 응답 전체가 거절됐다).
- V3 실행기는 Envelope를 읽지 않는다(DTO 자체를 검증). 이 변경은 V2
  경로만 바꾼다. bulk Envelope(results)는 프론트에 쓰는 곳이 없어 다루지
  않았다.

검증
- RED: tests/integration/http-client.test.ts "envelope keys the paired
  backend omits" 5행 중 2행 실패. data 키 없는 성공이 ok:false, id 키 없는
  403이 code HTTP_FAILURE.
- GREEN: 같은 5행 통과. tests/integration/http-client·http-diagnostics·
  http-execution-contract·auth-recovery·legacy-http-credential-authority,
  tests/runtime-schema 8 files 150 tests 통과. tsc app·test 통과, 바꾼
  파일 eslint 통과.

Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
2026-11-03 02:00:45 +09:00
DongHyeonkaandClaude Opus 5.5 c6300e9d40 feat(auth): require readSubject so a token refresh keeps server state
An external owner without readSubject made every authenticated
notification (every token refresh) abort requests and clear the
server-state cache. readSubject is now a required owner method and
getSubject a required SessionGateway method.

- ExternalSessionOwner.readSubject(): required; the host owner check
  (EXTERNAL_OWNER_METHODS) rejects an owner without it, so the session
  fails closed as integration-failed like any other missing method.
- SessionGateway.getSubject(): required. Anonymous and unavailable
  adapters return null; demo already returned its fixed user.
- Scope runtime: same (state, subject) still skips the fence; a state
  or subject change still fences. An authenticated session with a
  null/empty subject still fences (fail closed) and now records
  cache.operation.failed {operation: SCOPE_FENCE, reason:
  SUBJECT_MISSING} once per fence. Bootstrap passes diagnostics in.
- Docs: starter-experience external owner section and port comments
  describe what readSubject returns, the fail-closed diagnostic and a
  migration note.

RED before the change (vitest tests/unit/server-state-scope-runtime.test.ts
tests/unit/runtime-adapters.test.ts): 4 failed | 31 passed
- fails closed when the owner lacks readSubject:
  expected 'authenticated' to be 'integration-failed'
- fences and reports SUBJECT_MISSING ... null / empty subject, and the
  external owner whose readSubject returns null:
  expected [] to deeply equal [[{ level: 'warn', ... }]]
- type level: an owner literal without readSubject compiled (tsc exit
  0). The new @ts-expect-error pin fails check:types:test with TS2578
  if readSubject becomes optional again.
Pins that stayed green: same-subject token refresh keeps the cache,
subject change fences, sign-out fences, owner missing readState is
rejected.

GREEN: check:architecture, check:types:app, check:types:test, lint,
test:unit (2084), test:component (182), test:reference-feature (59),
test:integration (151), verify:documentation, check:diagnostics,
check:ci all pass.

BREAKING: external auth owners must implement readSubject(); code that
implements AuthSessionPort/SessionGateway directly must implement
getSubject().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 16:25:22 +09:00
DongHyeonkaandClaude Opus 5.5 108ac6a606 fix(http): classify 408/425 error envelopes as server failures and honor 503 Retry-After (R3-1)
- client: the final V2 classification step maps a 408/425 response with a
  valid error envelope to SERVER_FAILURE (via gatewayFailureOr), keeping
  the backend code and request/trace ids. contracts/errors.ts is unchanged.
- client: Retry-After is also parsed (kernel parser) on 503, so the retry
  waits at least that long and the 30s ceiling applies. 502/504 keep the
  local backoff.

RED (before the fix, 14 failing in tests/integration/http-client.test.ts):
- safe GET on a 408/425 error envelope: kind UNKNOWN_CLIENT_FAILURE,
  fetched once (expected SERVER_FAILURE, 3 fetches, code UPSTREAM_BUSY)
- none/keyed command on a 408/425 error envelope: kind
  UNKNOWN_CLIENT_FAILURE; keyed fetched once instead of 3 times
- 408/425 error envelope with Retry-After: 2: not retried
- 503 (gateway body and envelope) with Retry-After: 2: slept 125ms
  instead of 2000ms
- 408/425 envelope and 503 with Retry-After: 31: retryAfterMs missing
Pins that passed before and after: a non-idempotent command is sent once
on 408/425/503 gateway bodies and on a 503 envelope; 502/504 ignore
Retry-After (125ms).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 15:19:42 +09:00
DongHyeonkaandClaude Opus 5.5 db1bc1fc7e fix(http): retry 408/425 server failures and parse Retry-After with the kernel (R3-1)
- retry-policy: a SERVER_FAILURE with status 408/425 follows the
  502/503/504 rule (safe or keyed only; never idempotency "none" or
  retry "never"). Retry-After is honored and its 30s ceiling applies to
  any failure that carries it, not only RATE_LIMITED.
- client: Retry-After is parsed by platform/retry-after.ts for
  408/425/429, on every failure path (gateway bodies included).
  The local parseRetryAfterHeader is removed.

RED (before the fix, 15 failing):
- 408/425 gateway body on a safe GET: expected 3 fetches, got 1
- keyed command on 408/425: expected 3 fetches, got 1
- 408/425 with Retry-After: 2: expected ok after a 2000ms wait, got the
  first failure
- 408/425 with Retry-After: 31: retryAfterMs missing on the failure
- 429 Retry-After "1.5": slept 1500ms instead of the 125ms backoff;
  "Thursday, 01-Jan-70 00:00:05 GMT": slept 5000ms; "1e3", "0x10",
  "-1", "2099-01-01T00:00:00Z": accepted by the old parser, so the
  request was not retried with the 125ms backoff
- unit shouldRetry(safe, SERVER_FAILURE 408): false
Non-idempotent command on 408/425 stays 1 fetch (pinned, passed before
and after).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 15:16:56 +09:00
DongHyeonkaandClaude Opus 5.5 f139b6f7e2 fix(http): classify V2 gateway 5xx/408/425 bodies as server failures (Q-6.3-3b)
V2 checked the content type and decoded the body before looking at the
status. An nginx 502 with an HTML page became CONTENT_TYPE_MISMATCH and
an empty or broken 503/504 JSON body became MALFORMED_JSON: both
non-retryable and shown as a contract breach. For a 5xx/408/425 status
these branches, and the invalid-envelope branch, now return
SERVER_FAILURE with the httpStatus, the same R-3.3 rule V3 uses.

Retry follows V2's existing SERVER_FAILURE rule in retry-policy.ts, so
502/503/504 retry and 408/425/500 do not; SERVER_FAILURE was already in
retryKinds, so retry-policy.ts is unchanged.

The existing "non-JSON response" test used a 502 and pinned the old
CONTENT_TYPE_MISMATCH classification; it now uses a 200, which still
covers the non-JSON rejection and body redaction.

Verified: four new http-client cases (502 HTML, 503 empty JSON, 504
broken JSON, 408 text) failed RED with CONTENT_TYPE_MISMATCH /
MALFORMED_JSON and now pass with the expected fetch counts. All lane
gates pass except the known removal-fixture test; test:reference-feature
timed out once under load and passed on rerun.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:41:45 +09:00
DongHyeonkaandClaude Opus 5 c9e820aed5 fix: harden the legacy HTTP rollback path
N-06: export one idempotency-key authority from mutation-intent.ts and use it
in the V2 client. A caller-supplied key is validated before credentials, timers
and fetch, and an invalid value is rejected as VALIDATION_REJECTED /
IDEMPOTENCY_KEY_INVALID rather than trimmed, regenerated or dropped, so a keyed
command can no longer replay while sending no key.

N-07: bound the legacy credential wait by the existing attempt controller,
which already carries the total deadline and the caller signal, so a
non-cooperative owner cannot hold the request open and no extra timer is
introduced. The owner receives the operation context, and the failure follows
ownership: deadline to REQUEST_TIMEOUT, caller to REQUEST_ABORTED, and only a
genuine rejection to AUTH_INTEGRATION_FAILURE. None of these paths fetch.

N-08: readBoundedJson delegates to the common bounded reader, so cancel and
releaseLock throws stay isolated inside the closed result, and the V2
content-type mismatch now cancels the response body.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-13 23:46:03 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00