문제
"검증 거절은 적용 안 됨" 판정(64e98ee)의 근거가 추론이었다. 백엔드
http-contract.md 4절은 VALIDATION_FAILED의 출처를 적지만 "상태를 바꾸지
않는다"는 문장이 없다. 그 밖의 400·409·422 code는 어느 단계에서 나오는지
적힌 곳이 없었다. 계약 4.1·6절은 백엔드 커밋이 없어 기준을 결정일로 적었다.
고른 방법
- 백엔드 5786126c 코드에서 400·409·422를 내는 곳을 모두 찾고, code마다
단계(쓰기 전 / 쓰기 뒤 가능)와 프론트 결과(NOT_APPLIED / MAYBE_APPLIED),
백엔드 파일:줄을 6.1절 표에 적었다. 같은 code가 쓰기 전과 뒤에서 모두
나오면 쓰기 뒤 가능으로 둔다. 프론트는 code만으로 둘을 가르지 못한다.
- 4.1·6절 기준을 결정일에서 백엔드 SHA 5786126c로 바꿨다.
- 표와 지금 프론트 판정이 다른 곳을 같은 절에 적었다. client.ts는 다른
작업이 고치고 있어 이 변경에서 건드리지 않았다.
찾은 것
- 쓰기 전: VALIDATION_FAILED(출처 5곳 모두 바인딩·검증 단계, CVE handler는
지금 요청 경로 출처 없음), IDEMPOTENCY_KEY_INVALID, IDEMPOTENT_REQUEST_
MISMATCH. IDEMPOTENT_IN_FLIGHT도 이번 요청은 쓰기 전이지만 앞선 요청이
적용될 수 있어 MAYBE_APPLIED다.
- 쓰기 뒤 가능: BAD_PARAMETER(모든 층의 IllegalArgumentException),
MAPPING_FAILED(멱등성 응답 직렬화는 action이 끝난 뒤), DB_* 409 8종,
LOCK_ACQUISITION_TIMEOUT, 참조 도메인 400·409 6종, 선택 모듈 11종.
fileserver INTEGRITY_MISMATCH·MALWARE_DETECTED(422)는 레코드를 REJECTED로
쓴 뒤 던진다.
- 프론트와 다른 곳: 필드 목록 없는 400 VALIDATION_FAILED는 표로 NOT_APPLIED인데
V2는 effect가 없다. V2는 422 전체를 NOT_APPLIED로 보지만 fileserver 422는
MAYBE_APPLIED다. V3 참조 분류기는 400·422 전체를 NOT_APPLIED로 본다(참조
fixture용, 짝 백엔드에는 맞지 않는다).
버린 대안
- 백엔드 문서 표를 프론트 문서에 복사: 단계 정보는 백엔드 문서에 없다.
복사할 것이 아니라 프론트가 코드에서 읽은 판정이라 SHA와 파일:줄로 적었다.
- 프론트에 백엔드 소스를 읽는 검사 추가: 두 repo가 나란히 있어야만 돈다.
표를 SHA에 묶고, SHA를 올릴 때 표를 다시 확인하라고 적었다.
위험·한계
- "쓰기 전"은 지금 코드에서 handler에 닿는 출처를 센 결과다. 백엔드가
application bean에 @Validated를 달거나 JPA entity에 Bean Validation 제약을
넣으면 필드 목록 있는 VALIDATION_FAILED가 use case 안에서도 나온다. 백엔드에
이것을 막는 검사는 없다.
- 줄 번호는 5786126c 기준이다. 백엔드가 바뀌면 어긋난다.
검증
- node scripts/generate-product-feature-index.ts &&
node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- 표의 파일:줄은 백엔드 5786126c에서 grep·sed로 다시 열어 확인했다.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.4
745 lines
39 KiB
Markdown
745 lines
39 KiB
Markdown
# Backend API와 Server State handoff contract
|
|
|
|
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
|
>
|
|
> Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker,
|
|
> Service Worker, offline command와 Background Sync의 구현 결정은
|
|
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](./2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
|
|
> 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다.
|
|
|
|
|
|
- 상태: frontend handoff design accepted, backend implementation/evidence pending
|
|
- 기준일: 2026-07-28
|
|
- 대상: Web API/BFF, application service, persistence, identity, GraphQL router,
|
|
Connect/gRPC-Web gateway, Protobuf REST Gateway와 운영 owner
|
|
- frontend 기준:
|
|
[API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)
|
|
- browser Protobuf/gateway 기준:
|
|
[Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)
|
|
- 파일 전송 backend 기준:
|
|
[Server file capability infrastructure](./server-file-capability-infrastructure.md)
|
|
- 복구 절차:
|
|
[API contract와 server-state recovery](../operations/api-contract-and-server-state-recovery.md)
|
|
|
|
## 1. 문서의 경계
|
|
|
|
이 문서는 이 frontend template이 실제 제품 backend와 연결될 때 backend가
|
|
제공해야 하는 구조, wire contract, 상태 의미와 운영 증거를 정의한다. 특정
|
|
언어·framework·cloud 제품을 강제하지 않는다. Spring, Nest/Fastify, Go,
|
|
.NET 또는 다른 stack을 사용해도 아래 불변조건은 동일하다.
|
|
|
|
이 repository에는 backend source, database migration, identity provider,
|
|
GraphQL schema/router, protobuf descriptor, Connect/gRPC-Web runtime/proxy,
|
|
REST transcoder와 실제 provider evidence가 없다. 따라서 이 문서는 backend 구현
|
|
완료 증거가 아니다.
|
|
|
|
파일 업로드·다운로드, object storage, presigned URL, multipart와 Image CDN은
|
|
별도 server file 문서가 소유한다. 이 문서는 ordinary REST/GraphQL/Connect/
|
|
gRPC-Web application API, Protobuf REST Gateway와 frontend Server State 계약만
|
|
소유한다.
|
|
|
|
## 2. 권장 논리 구조
|
|
|
|
```text
|
|
Browser
|
|
-> CDN / reverse proxy / WAF
|
|
-> Browser-facing Web API or BFF
|
|
-> authentication + authorization
|
|
-> exact operation registry
|
|
-> request schema / byte / rate limit
|
|
-> REST controller
|
|
-> optional persisted GraphQL router
|
|
-> optional Connect browser RPC gateway
|
|
-> optional gRPC-Web gateway
|
|
-> optional Protobuf REST transcoder
|
|
-> application service
|
|
-> command transaction
|
|
-> query/read-model service
|
|
-> idempotency coordinator
|
|
-> revision/validator owner
|
|
-> outbox/event owner
|
|
-> primary database
|
|
-> idempotency store
|
|
-> read replica/read model
|
|
-> event broker when selected
|
|
```
|
|
|
|
Browser-facing contract owner와 내부 service contract owner를 분리한다.
|
|
|
|
- Browser API/BFF는 CORS, cookie/CSRF 또는 bearer, public DTO, envelope,
|
|
body ceiling, status/media와 redaction을 소유한다.
|
|
- Application service는 authorization 재검사, transaction, idempotency,
|
|
conflict, revision과 domain invariant를 소유한다.
|
|
- Persistence adapter는 SQL/NoSQL/Redis vendor type, row version과 cursor
|
|
implementation을 외부 DTO에 노출하지 않는다.
|
|
- GraphQL router, Connect/gRPC-Web gateway와 REST transcoder는 선택 adapter다.
|
|
다른 protocol로 임의 fallback하거나 frontend에 내부 service address를
|
|
노출하지 않는다.
|
|
|
|
작은 제품은 이 논리 모듈을 하나의 deployable로 구현할 수 있다. deployable을
|
|
나누는 것보다 transaction/idempotency/authorization owner가 하나로 명확한지가
|
|
우선이다.
|
|
|
|
## 3. 공통 contract artifact
|
|
|
|
Backend와 frontend release는 다음 bounded contract set을 공유한다.
|
|
|
|
```text
|
|
ApiContractSetV1
|
|
globalApiContractVersion
|
|
restArtifactId + digest
|
|
runtimeSchemaManifestId + digest
|
|
mapperSemanticManifestId + digest
|
|
errorVocabularyVersion
|
|
minimumFrontendVersion
|
|
minimumBackendVersion
|
|
effectiveAt
|
|
retirementEpoch | null
|
|
|
|
optional:
|
|
graphqlSchemaId + digest
|
|
persistedGraphqlManifestId + digest
|
|
protobufDescriptorId + digest
|
|
protobufSourceOrModuleId + digest
|
|
protobufCodegenProfileId
|
|
connectProviderProfileId
|
|
grpcWebProviderProfileId
|
|
protobufRestGatewayProfileId
|
|
httpRuleArtifactId + digest
|
|
protoJsonProfileId
|
|
gatewayOpenApiArtifactId + digest
|
|
```
|
|
|
|
최소 산출물:
|
|
|
|
- authenticated OpenAPI 또는 동등한 REST schema source
|
|
- exact status/media/envelope fixture
|
|
- stable error code vocabulary
|
|
- request/response byte와 collection ceiling
|
|
- scalar/date/null/enum 의미
|
|
- N/N-1 compatibility 결과
|
|
- backend build와 frontend release가 참조하는 immutable digest
|
|
|
|
runtime config의 version 문자열 일치만 compatibility 증거로 사용하지 않는다.
|
|
artifact digest가 없는 동안에는 실제 staging conformance fixture와 수동 승인
|
|
evidence가 필요하다.
|
|
|
|
## 4. 현재 reference REST 계약
|
|
|
|
현재 frontend에 실제 조립된 operation은 다음 세 개다.
|
|
|
|
| operation | request | success |
|
|
| --- | --- | --- |
|
|
| `LIST_REFERENCE_RESOURCES` | `GET /api/reference-resources?cursor&limit&tags` | `200 application/json` |
|
|
| `GET_REFERENCE_RESOURCE` | `GET /api/reference-resources/{resourceId}` | `200 application/json` |
|
|
| `CREATE_REFERENCE_RESOURCE` | `POST /api/reference-resources` | `200` 또는 `201 application/json` |
|
|
|
|
현재 list payload는 `ReferenceResource[]`다. `cursor` 입력이 존재하더라도
|
|
`CursorPage` 출력 계약은 아직 아니다. backend가 같은 operation에서 배열을
|
|
page object로 조용히 바꾸면 schema mismatch로 실패한다.
|
|
|
|
resource DTO:
|
|
|
|
```text
|
|
ReferenceResourceDtoV1
|
|
id: non-empty string, maximum 120 characters
|
|
name: non-empty string, maximum 240 characters
|
|
createdAt?: RFC 3339 date-time
|
|
```
|
|
|
|
create command:
|
|
|
|
```text
|
|
CreateReferenceResourceCommandV1
|
|
name: trimmed string, 1..120
|
|
note?: trimmed string, 0..500
|
|
```
|
|
|
|
Backend는 frontend validation을 신뢰하지 않고 동일하거나 더 좁은 validation과
|
|
authorization을 다시 수행한다.
|
|
|
|
### 4.1 JSON envelope
|
|
|
|
Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정본이다. 이
|
|
문서에 표를 다시 적지 않는다.
|
|
|
|
- 정본: [`clean-architecture-backend-template/docs/web/http-contract.md`](../../../clean-architecture-backend-template/docs/web/http-contract.md)
|
|
1절 "Envelope 키 존재 규칙"
|
|
- 기준 커밋: 백엔드 `5786126c`. `http-contract.md`는 `34565130`에서 들어왔고
|
|
`1400dc15`에서 마지막으로 바뀌었다. 값이 null인 필드는 키째 생략한다. 백엔드
|
|
기준 커밋을 올리면 6.1절 표를 같은 변경에서 다시 확인한다.
|
|
- 프론트에서 Envelope를 읽는 곳: V2 `src/adapters/http/schema-registry.ts`와
|
|
`src/adapters/http/client.ts`. V3 실행기는 Envelope 없이 DTO를 검증한다
|
|
(`src/adapters/http/index.ts` V2 주석).
|
|
- 실패 Envelope의 `error.code`가 "적용 안 됨"인지는 6.1절이 정한다.
|
|
|
|
### 4.2 Status와 error
|
|
|
|
| HTTP status | 의미 |
|
|
| --- | --- |
|
|
| `400` | malformed request 또는 closed request contract 위반 |
|
|
| `401` | 인증 없음/만료. 이미 적용된 command를 401로 반환하지 않음 |
|
|
| `403` | authenticated principal에게 권한 없음 |
|
|
| `404` | authorization 정책상 공개 가능한 not-found |
|
|
| `409` | domain revision 또는 semantic conflict. 멱등성 응답(409·422·400)은 6절 |
|
|
| `412` | selected conditional write의 `If-Match` precondition 실패 |
|
|
| `422` | field validation. bounded `details.issues[]`만 허용 |
|
|
| `429` | rate limit. 유효한 `Retry-After`와 operation 정책 제공 |
|
|
| `500/502/503/504` | server/provider failure. command effect certainty 별도 |
|
|
|
|
현재 frontend의 ordinary status mapper는 `412` 전용 처리를 아직 연결하지
|
|
않았다. conditional mutation을 선택할 때 frontend failure vocabulary와
|
|
transaction을 함께 승격해야 한다.
|
|
|
|
Backend `error.code`는 machine-readable stable code다. stack, SQL/vendor error,
|
|
raw validation value, authorization reason과 내부 service address를 반환하지
|
|
않는다.
|
|
|
|
## 5. 인증, CSRF와 CORS
|
|
|
|
현재 reference operation은 다음 profile로 조립돼 있다.
|
|
|
|
```text
|
|
auth = external bearer
|
|
Authorization: Bearer <credential>
|
|
fetch credentials = omit
|
|
CSRF profile = none
|
|
redirect = error
|
|
referrer policy = no-referrer
|
|
```
|
|
|
|
Backend/BFF는 bearer의 issuer, audience, signature algorithm, time claims와
|
|
revocation/session policy를 검증하고 operation별 authorization을 적용한다.
|
|
401과 403을 구분하며 frontend cache를 authorization authority로 사용하지 않는다.
|
|
|
|
쿠키 session으로 전환할 경우 같은 profile로 간주하지 않는다. 별도
|
|
`SAME_ORIGIN_COOKIE` profile에 다음을 함께 승인한다.
|
|
|
|
- `Secure`, `HttpOnly`, 명시적 `SameSite`와 host/path scope
|
|
- unsafe method의 CSRF token/header와 Origin/Sec-Fetch-Site 검증
|
|
- credentialed CORS에서 wildcard origin 금지
|
|
- login/logout/session rotation과 cache generation 전환
|
|
- session fixation, token rotation과 concurrent tab 동작
|
|
|
|
Cross-origin bearer provider 최소 CORS:
|
|
|
|
- exact allow-origin 목록과 bounded preflight cache
|
|
- `Authorization`, `Content-Type`, `Idempotency-Key`,
|
|
`X-Correlation-ID`, 향후 `If-None-Match`, `If-Match` 허용
|
|
- 필요한 경우 `ETag`, `Retry-After`, request/trace header만 expose.
|
|
`X-Correlation-ID`를 expose하면 V3 실패의 `AppFailure.requestId`가 된다
|
|
(`src/adapters/http/feature-http-binding.ts`). expose하지 않거나 응답이 없으면
|
|
클라이언트가 보낸 값이 된다
|
|
- redirect login page, HTML error body와 wildcard credential 금지
|
|
|
|
## 6. Command와 idempotency
|
|
|
|
`CREATE_REFERENCE_RESOURCE`는 keyed command다. frontend memory single-flight는
|
|
backend idempotency를 대체하지 않는다.
|
|
|
|
멱등성 응답의 status·`error.code`·`retryable`·`Retry-After`와 키 문법은 짝
|
|
백엔드 템플릿 문서가 정본이다. 이 문서에 표를 다시 적지 않는다.
|
|
|
|
- 정본: [`clean-architecture-backend-template/docs/web/http-contract.md`](../../../clean-architecture-backend-template/docs/web/http-contract.md)
|
|
2절 "멱등성 응답", 4절 "web 전용 오류 코드"
|
|
- 기준 커밋: 4.1절과 같다(백엔드 `5786126c`).
|
|
- 프론트가 그 응답을 읽는 곳:
|
|
- 키 생성·검사: `src/contracts/mutation-intent.ts` `isValidIdempotencyKey`
|
|
- 결과 불명 재전송이 같은 키를 쓰고 `Retry-After`까지 기다리는 곳:
|
|
`src/presentation/adapters/query/application-query.ts`
|
|
- V2 거절 판정: `src/adapters/http/client.ts` `IDEMPOTENCY_REFUSALS`와
|
|
`fieldValidation`
|
|
- V3 참조 기능 판정: `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts`
|
|
(effect), `src/features/reference-feature/adapters/reference-http-gateway.ts`
|
|
(code)
|
|
|
|
### 6.1 거절 code와 적용 여부
|
|
|
|
mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐는지 정해야 한다.
|
|
|
|
- `NOT_APPLIED`: 쓰기 전에 거절됐다. 다음 저장은 새 `Idempotency-Key`를 쓴다.
|
|
- `MAYBE_APPLIED`: 쓰기 뒤에도 나올 수 있다. mutation 코디네이터가 키를 붙들고
|
|
결과 불명으로 보인다. effect가 없는 실패도 이 값이다.
|
|
|
|
백엔드 `http-contract.md`는 code가 어느 단계에서 나오는지 적지 않는다. 아래 표는
|
|
프론트가 백엔드 `5786126c`의 코드를 읽고 정한 판정이다. 같은 code가 쓰기 전과
|
|
뒤에서 모두 나오면 "쓰기 뒤 가능"으로 둔다. 프론트는 code만 보고 둘을 가를 수
|
|
없다.
|
|
|
|
| code (status) | 나오는 곳 | 단계 | 프론트 결과 | 백엔드 파일:줄 |
|
|
| --- | --- | --- | --- | --- |
|
|
| `VALIDATION_FAILED` (400), details = 필드 목록 | 요청 본문 `@Valid` 실패, 컨트롤러 파라미터 제약 실패. 컨트롤러 메서드가 불리기 전 | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:218-231`, `:346-368` |
|
|
| `VALIDATION_FAILED` (400), details = 필드 목록 | `ConstraintViolationException`. 어느 층에서 던져도 이 handler가 받는다. 요청 경로에서 던지는 코드는 없다(application bean에 `@Validated` 없음, JPA entity에 Bean Validation 제약 없음, 직접 throw 없음) | 쓰기 전(현재 출처 없음) | `NOT_APPLIED` | `GlobalExceptionHandler.java:101-106` |
|
|
| `VALIDATION_FAILED` (400), details = `{cause}` 또는 없음 | 본문을 읽지 못함(`HttpMessageNotReadableException`) | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:233-251` |
|
|
| `VALIDATION_FAILED` (400), details = `{field, code}` | 페이지·정렬 파라미터. 목록 GET 컨트롤러가 use case 전에 검사한다 | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:149-153`, `PageParams.java:27-33`, `SortParam.java:16-43` |
|
|
| `IDEMPOTENCY_KEY_INVALID` (400) | KEYED 컨트롤러 첫 줄의 키 파싱 | 쓰기 전 | `NOT_APPLIED` | `IdempotencyKeyHeader.java:32-38`, `PosterImagePublicationController.java:64` |
|
|
| `IDEMPOTENT_REQUEST_MISMATCH` (422) | 멱등성 executor가 action 전에 판정 | 쓰기 전 | `NOT_APPLIED` | `IdempotencyExecutor.java:102-103`, `:134-135` |
|
|
| `IDEMPOTENT_IN_FLIGHT` (409) | 멱등성 executor가 action 전에 판정. 같은 키의 앞선 요청이 실행 중이다 | 이번 요청은 쓰기 전. 앞선 요청은 적용될 수 있다 | `MAYBE_APPLIED` | `IdempotencyExecutor.java:104-105`, `:136-137` |
|
|
| `BAD_PARAMETER` (400) | 타입 변환 실패, 필수 파라미터·헤더 없음(쓰기 전). **어느 층이든 `IllegalArgumentException`**(use case·domain 포함) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `GlobalExceptionHandler.java:92-99`, `:108-116`, `:397-438` |
|
|
| `MAPPING_FAILED` (400) | web 매퍼(쓰기 전), outbound ACL 매퍼(use case 안), 멱등성 응답 직렬화(action이 끝난 뒤) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `WorkLogWebMapper.java:36`, `RepoStatsAclMapper.java:14`, `JsonIdempotentResponseCodec.java:32`, `IdempotencyExecutor.java:229` |
|
|
| `DB_SERIALIZATION_FAILURE`, `DB_DEADLOCK`, `DB_LOCK_TIMEOUT`, `DB_NULL_VIOLATION`, `DB_FK_VIOLATION`, `DB_UNIQUE_VIOLATION`, `DB_CHECK_VIOLATION`, `DB_OPTIMISTIC_CONFLICT` (409) | persistence 어댑터가 SQL·JPA 실패를 바꾼 것. 트랜잭션 안이나 commit에서 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `FailureCategory.java:79-95`, `StandardSqlStateErrorMapping.java:46-52`, `PersistenceExceptionTranslator.java:131` |
|
|
| `LOCK_ACQUISITION_TIMEOUT` (409) | 분산 락 대기 초과. use case 안 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `LockRegistryDistributedLock.java:50`, `:53` |
|
|
| 참조 도메인 `WORKLOG_INVALID`, `POSTER_INVALID_STATE`, `POSTER_IMAGE_REQUIRED` (400), `WORKLOG_CONFLICT`, `POSTER_ALREADY_EXISTS`, `POSTER_IMAGE_ALREADY_PUBLISHED` (409) | application·domain 예외 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `DomainExceptionHandler.java:52-90` |
|
|
| 선택 모듈 web-advanced `PATCH_REJECTED` (400), `PATCH_TEST_FAILED` (409) | patch 라이브러리. 부르는 코드가 단계를 정한다 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `src/adapter/inbound/web-advanced/README.md` 「오류 응답」 |
|
|
| 선택 모듈 fileserver `BAD_REQUEST` (400), `FILE_ALREADY_EXISTS`, `FILE_NOT_READY`, `UPLOAD_OFFSET_MISMATCH`, `CONCURRENT_MODIFICATION` (409), `INTEGRITY_MISMATCH`, `MALWARE_DETECTED`, `INVALID_PATH`, `PATH_OUTSIDE_NAMESPACE` (422) | application·outbound 층. `INTEGRITY_MISMATCH`·`MALWARE_DETECTED`는 레코드를 `REJECTED`로 쓴 뒤 던진다 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `FileserverErrorCode.java:26-44`, `FinalizeUploadApplicationUseCase.java:211-224`, `:336-341` |
|
|
|
|
- application-notification의 `VALIDATION_FAILED`(`NotificationFailureCode`)는
|
|
`ApiErrorCarrier`가 아니다. HTTP로는 500 `INTERNAL_ERROR`로 나가므로 표에 없다.
|
|
- 표에 없는 400·409·422 code는 `MAYBE_APPLIED`로 본다.
|
|
- 파일 위치(백엔드 repo 기준):
|
|
- `GlobalExceptionHandler.java`: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/`
|
|
- `PageParams.java`, `SortParam.java`: 같은 모듈 `.../web/pagination/`
|
|
- `IdempotencyKeyHeader.java`: 같은 모듈 `.../web/http/`
|
|
- `IdempotencyExecutor.java`: `src/application-core/src/main/java/dev/caskeleton/application/idempotency/`
|
|
- `JsonIdempotentResponseCodec.java`: `src/adapter/inbound/web-advanced/.../advanced/idempotency/`
|
|
- `FailureCategory.java`, `StandardSqlStateErrorMapping.java`,
|
|
`PersistenceExceptionTranslator.java`, `LockRegistryDistributedLock.java`:
|
|
`src/adapter/outbound/persistence-jpa/`
|
|
- `PosterImagePublicationController.java`, `WorkLogWebMapper.java`,
|
|
`RepoStatsAclMapper.java`, `DomainExceptionHandler.java`: `src/sample-portfolio/`
|
|
- `FileserverErrorCode.java`, `FinalizeUploadApplicationUseCase.java`:
|
|
`src/application-fileserver/`
|
|
|
|
프론트 판정과 표가 다른 곳(고치면 이 줄을 지운다):
|
|
|
|
- 필드 목록이 없는 400 `VALIDATION_FAILED`(`{cause}`, details 없음,
|
|
`{field, code}`)는 표로는 `NOT_APPLIED`다. V2(`client.ts` `fieldValidation`)는
|
|
effect를 붙이지 않아 `MAYBE_APPLIED`가 된다.
|
|
- V2는 code와 상관없이 422를 모두 `NOT_APPLIED`로 본다. 기본 배포의 422는
|
|
`IDEMPOTENT_REQUEST_MISMATCH` 하나라 맞다. fileserver를 실은 배포의 422 4종은
|
|
표로는 `MAYBE_APPLIED`다.
|
|
- V3 참조 기능 분류기(`classifyProblem`)는 참조 fixture(problem+json)용이라
|
|
400·422를 모두 `NOT_APPLIED`로 본다. V3를 짝 백엔드에 붙이면
|
|
`BAD_PARAMETER`, `MAPPING_FAILED`, 도메인 400이 틀린다.
|
|
|
|
남은 위험: "쓰기 전"은 현재 코드에서 그 handler에 닿는 출처를 센 결과다. 백엔드가
|
|
application bean에 `@Validated`를 달거나 JPA entity에 Bean Validation 제약을
|
|
넣으면, 필드 목록이 있는 400 `VALIDATION_FAILED`가 use case 안에서도 나온다.
|
|
백엔드에는 이것을 막는 검사가 없다.
|
|
|
|
## 7. Cursor pagination과 snapshot
|
|
|
|
Backend가 pagination을 선택할 때 새 response schema/operation version으로 다음
|
|
contract를 제공한다.
|
|
|
|
```text
|
|
CursorPage<T>
|
|
items: T[]
|
|
nextCursor: opaque string | null
|
|
hasMore: boolean
|
|
snapshotToken: opaque string | null
|
|
```
|
|
|
|
필수 불변조건:
|
|
|
|
- `hasMore === (nextCursor !== null)`
|
|
- 동일 chain의 `snapshotToken`은 모든 page에서 동일
|
|
- cursor는 principal/tenant, filter, sort, contract version과 snapshot에 binding
|
|
- cursor는 opaque, 무결성 보호, 만료와 key rotation 정책 보유
|
|
- offset이 아니라 stable keyset ordering 사용
|
|
- total order의 마지막 tie-breaker는 immutable unique ID
|
|
- deleted/inserted row가 duplicate/gap을 만드는 의미를 snapshot 정책으로 결정
|
|
- empty page인데 `hasMore=true`인 sparse page 허용 여부를 operation profile에 고정
|
|
- cursor 최대 encoded byte, page size와 total scan/cost ceiling을 server도 강제
|
|
- invalid, expired, wrong-principal, wrong-filter cursor의 safe error code를 고정
|
|
|
|
권장 query ordering 예:
|
|
|
|
```text
|
|
ORDER BY created_at DESC, resource_id DESC
|
|
cursor payload = version + snapshot watermark + last(created_at, resource_id)
|
|
+ filter digest + principal/tenant binding + expiry
|
|
```
|
|
|
|
Cursor 원문은 log, trace, analytics와 frontend persistent storage에 넣지 않는다.
|
|
|
|
### 7.1 배열에서 page로의 migration
|
|
|
|
1. `ReferenceResourceListPagePayloadV2` schema와 새 operation/version을 추가한다.
|
|
2. backend가 N/N-1 동안 기존 배열과 page contract를 동시에 제공한다.
|
|
3. frontend가 cursor runtime을 새 bound query/infinite query에 연결한다.
|
|
4. loop/snapshot/ceiling/abort conformance를 staging에서 검증한다.
|
|
5. 새 operation을 canary한 뒤 기존 배열 operation을 retirement한다.
|
|
|
|
동일 media/status에서 payload shape만 바꾸는 in-place migration은 금지한다.
|
|
|
|
## 8. Conditional read와 revision/CAS
|
|
|
|
### 8.1 Read validator
|
|
|
|
Backend가 application-managed revalidation을 선택하면 exact mapped
|
|
representation마다 ETag를 제공한다.
|
|
|
|
```text
|
|
GET without validator
|
|
-> 200 + JSON envelope + ETag
|
|
|
|
GET with If-None-Match
|
|
-> representation unchanged: 304 + empty body
|
|
-> changed: 200 + JSON envelope + new ETag
|
|
```
|
|
|
|
불변조건:
|
|
|
|
- validator는 principal/tenant, authorization-visible representation,
|
|
response schema/mapper semantics와 encoding variant에 binding
|
|
- weak/strong 선택을 operation profile에 고정
|
|
- user-private response를 shared CDN/public cache에 저장하지 않음
|
|
- cross-origin이면 `ETag`를 expose하고 `If-None-Match`를 preflight 허용
|
|
- 304에는 JSON success envelope를 넣지 않음
|
|
- validator 원문을 log/metric/diagnostics에 넣지 않음
|
|
- `Vary`와 `Cache-Control` owner를 명확히 하고 browser HTTP cache와
|
|
TanStack/application revalidation이 서로 다른 value owner가 되지 않게 함
|
|
|
|
Frontend는 validator와 mapped cache value의 scope, query identity,
|
|
representation version과 cache revision이 모두 일치할 때만 304를 success로
|
|
받는다. cache value가 없으면 unconditional refetch 또는 safe failure로 닫는다.
|
|
|
|
### 8.2 Conditional command
|
|
|
|
수정/삭제 command가 선택되면 DTO에 opaque domain `revision`을 추가하고:
|
|
|
|
```text
|
|
If-Match: "<revision validator>"
|
|
```
|
|
|
|
를 요구한다. 일치하지 않으면 `412` 또는 승인된 `409` contract 하나만
|
|
사용한다. frontend optimistic layer의 commit/rollback은 backend revision
|
|
authority를 대체하지 않는다.
|
|
|
|
## 9. Optimistic mutation을 위한 backend 의미
|
|
|
|
Frontend ordered optimistic layer runtime은 구현돼 있지만 제품 operation에
|
|
연결하려면 backend가 다음을 결정해야 한다.
|
|
|
|
- resource/list membership을 결정하는 canonical filter와 sort
|
|
- command가 생성/수정/삭제하는 stable identity
|
|
- server-assigned ID와 client correlation의 reconcile 방법
|
|
- authoritative resource/list revision
|
|
- conflict status와 stable error code
|
|
- commit response가 complete resource인지 receipt인지
|
|
- effect certainty와 idempotency status/reconcile endpoint
|
|
- event/outbox가 있을 때 sequence/gap/snapshot reset 의미
|
|
|
|
Create가 server-assigned ID를 사용하는 경우 temporary UI ID를 backend ID로
|
|
원자적으로 교체하고 관련 detail/list key를 reconcile하는 정책이 필요하다.
|
|
이 의미 없이 generic optimistic append를 기본 활성화하지 않는다.
|
|
|
|
## 10. Database와 application service baseline
|
|
|
|
구현 예시는 다음 논리 table/constraint를 만족해야 한다.
|
|
|
|
```text
|
|
reference_resource
|
|
tenant_id
|
|
resource_id
|
|
display_name
|
|
note
|
|
revision
|
|
created_at
|
|
updated_at
|
|
deleted_at | null
|
|
unique(tenant_id, resource_id)
|
|
|
|
idempotency_record
|
|
principal/tenant fingerprint
|
|
operation + contract version
|
|
key hash
|
|
request fingerprint
|
|
state + receipt
|
|
lease/retention timestamps
|
|
unique(principal/tenant, operation, contract version, key hash)
|
|
|
|
outbox_event when selected
|
|
aggregate identity + revision
|
|
event type/version
|
|
sequence
|
|
payload reference or bounded safe projection
|
|
publication state
|
|
```
|
|
|
|
Application service transaction은 authorization scope와 tenant predicate를
|
|
모든 read/write에 적용하고, resource mutation과 revision/outbox 기록을 같은
|
|
transaction boundary에 둔다. cache/replica lag를 고려해 command 직후 read
|
|
consistency와 invalidation owner를 선언한다.
|
|
|
|
## 11. GraphQL 선택 시 추가 구조
|
|
|
|
GraphQL은 제품 operation이 REST보다 aggregation 이점을 실제로 가질 때만
|
|
선택한다.
|
|
|
|
```text
|
|
Browser
|
|
-> persisted-operation endpoint
|
|
-> manifest allowlist
|
|
-> auth/CSRF/rate/cost/depth/alias enforcement
|
|
-> GraphQL router
|
|
-> application services/loaders
|
|
```
|
|
|
|
Backend handoff:
|
|
|
|
- authenticated immutable schema artifact와 digest
|
|
- named operation source와 persisted ID/hash manifest
|
|
- variables/result runtime fixtures
|
|
- selected GraphQL-over-HTTP revision과 exact media/status profile
|
|
- partial data policy와 safe error extension vocabulary
|
|
- field/row authorization, cost/depth/alias/list ceiling
|
|
- N/N-1 router/frontend manifest rollout과 retirement
|
|
|
|
Production endpoint는 arbitrary document와 persisted miss 후 full-document
|
|
fallback을 받지 않는다. normalized frontend entity cache는 별도 제품 선택이다.
|
|
|
|
## 12. gRPC-Web 선택 시 추가 구조
|
|
|
|
gRPC-Web은 browser-facing gateway/proxy가 실제 선택된 unary 또는 bounded
|
|
server-stream operation에만 사용한다.
|
|
|
|
```text
|
|
Browser
|
|
-> same-origin BFF/Envoy/gRPC-Web gateway
|
|
-> exact service/method allowlist
|
|
-> frame/message/deadline/status/trailer enforcement
|
|
-> internal gRPC application service
|
|
```
|
|
|
|
Backend handoff:
|
|
|
|
- authenticated proto source와 immutable descriptor digest
|
|
- Buf/protoc lint/breaking 및 deterministic generation evidence
|
|
- exact service/method/rpc-kind allowlist
|
|
- selected gRPC-Web runtime kind, client API와 binary/JSON/text/wire revision;
|
|
official XHR와 Connect-Web Fetch profile을 분리
|
|
- proxy CORS, content-type, terminal status/trailer behavior
|
|
- Envoy를 선택하면 exact version/config digest, filter order, upstream HTTP/2,
|
|
route/idle/max-stream timeout, timeout offset와 buffering/flush
|
|
- message/frame/count/queue/idle/total budget
|
|
- server-stream sequence, gap, resume와 snapshot reset protocol
|
|
- actual browser/proxy conformance
|
|
|
|
client streaming과 bidirectional streaming은 common gRPC-Web browser contract로
|
|
간주하지 않는다. upload는 REST transfer, duplex는 별도 protocol을 선택한다.
|
|
|
|
## 13. Connect-Web/Connect 선택 시 추가 구조
|
|
|
|
Connect는 Protobuf-first backend의 selected unary 또는 bounded server-stream
|
|
operation에만 사용한다. Connect protocol과 Connect-Web의 gRPC-Web transport는
|
|
서로 다른 provider row다.
|
|
|
|
```text
|
|
Browser Connect-Web adapter
|
|
-> same-origin BFF 또는 exact cross-origin Connect endpoint
|
|
-> auth/CSRF/CORS + service/method allowlist
|
|
-> Connect protocol handler
|
|
-> application service
|
|
```
|
|
|
|
Backend handoff:
|
|
|
|
- authenticated proto/Buf source, descriptor와 generated-service digest
|
|
- exact Connect-Web/client runtime과 server/gateway version
|
|
- protocol revision, JSON/binary encoding, POST 또는 approved GET
|
|
- unary HTTP/error profile 또는 stream EndStream terminal profile
|
|
- request/response/envelope/message/count/queue byte ceiling
|
|
- unary/stream compression capability; stock browser stream은 identity-only
|
|
- total/idle timeout, browser abort→server context→downstream cancellation 전파
|
|
- exact CORS allow/expose/preflight와 auth/CSRF profile
|
|
- actual Chromium/Firefox/WebKit와 selected proxy/server conformance
|
|
|
|
GET은 descriptor `NO_SIDE_EFFECTS`, non-sensitive bounded input, URL/cache key,
|
|
`Vary`와 credential policy가 모두 승인된 unary에만 허용한다. browser
|
|
client-streaming/bidi는 Connect protocol 자체 기능과 별개로 `PLATFORM_LIMITED`다.
|
|
|
|
## 14. Protobuf REST Gateway 선택 시 추가 구조
|
|
|
|
한 route는 `CURATED_BFF | GRPC_GATEWAY | ENVOY_TRANSCODER` 중 하나만 소유한다.
|
|
현재 reference REST의 envelope와 `200|201`, 향후 `204/304/412` 의미를 유지하는
|
|
기본 선택은 curated BFF다.
|
|
|
|
Direct gateway는 ProtoJSON/HttpRule/status/error 자체를 새 public contract로
|
|
승인한 unary operation에서만 선택한다. Backend handoff:
|
|
|
|
- `.proto` annotation 또는 precedence가 고정된 service config의 immutable source
|
|
- descriptor/Buf image, canonical HttpRule route manifest와 digest
|
|
- pinned gateway/runtime/generator/plugin과 generated OpenAPI artifact
|
|
- ProtoJSON name/default/enum/int64/bytes/null/presence/unknown-field profile
|
|
- exact method/path/query/body/response-body/additional-binding와 path escaping
|
|
- safe status/error/header mapping과 raw `google.rpc.Status` detail redaction
|
|
- CORS/auth/CSRF, body/header/query ceiling와 rate limit
|
|
- browser abort/deadline의 upstream gRPC/application work 전파
|
|
- N/N-1 route/OpenAPI/runtime conformance와 coherent rollback
|
|
|
|
Gateway는 durable idempotency, pagination snapshot, ETag/HTTP conditional,
|
|
product envelope, authorization와 file transfer semantics를 자동 구현하지 않는다.
|
|
필요한 operation은 application service와 BFF가 계속 소유한다. generated
|
|
REST streaming은 별도 framing/terminal/cache ADR 없이는 `NOT_SELECTED`다.
|
|
|
|
## 15. Invalidation과 realtime
|
|
|
|
현재 frontend cross-tab invalidation은 같은 browser origin 안의 opaque
|
|
invalidate-only hint다. backend event delivery를 의미하지 않는다.
|
|
|
|
Backend-driven invalidation/realtime을 선택하면:
|
|
|
|
- transactional outbox 또는 동등한 durable publication
|
|
- principal/tenant authorization을 통과한 event projection
|
|
- event type/version, aggregate revision, sequence와 dedupe identity
|
|
- reconnect cursor, gap detection과 snapshot reset
|
|
- retention, replay ceiling과 slow-consumer policy
|
|
|
|
를 제공해야 한다. event payload를 authoritative resource snapshot으로 쓸지
|
|
query invalidate hint로만 쓸지 operation별 reducer contract가 필요하다.
|
|
|
|
## 16. Rate limit, deadline와 retry
|
|
|
|
- backend deadline은 frontend total deadline보다 짧거나 cancellation을 전파할 수
|
|
있어야 한다.
|
|
- disconnect/cancel 뒤 불필요한 query 작업은 중단한다.
|
|
- keyed command는 disconnect가 transaction rollback을 보장하지 않으므로
|
|
idempotency receipt로 effect를 판정한다.
|
|
- `Retry-After`는 selected status에서만 bounded delta/date 형식으로 제공한다.
|
|
- retry-safe read와 keyed command를 구분한다.
|
|
- proxy, BFF와 service retry가 겹쳐 retry amplification을 만들지 않게 한 owner만
|
|
재시도한다.
|
|
- rate limit key는 principal/tenant/operation과 abuse policy에 binding하며 raw
|
|
credential/IP를 metric label에 넣지 않는다.
|
|
|
|
### 16.1 전송별 재시도·타임아웃 규칙 (2026-09-25 코드 기준)
|
|
|
|
같은 이름의 정책이라도 전송마다 동작이 다르다. operation을 다른 전송으로 옮기면
|
|
이 표로 동작 변화를 확인한다.
|
|
|
|
| 규칙 | V3 contract executor (기본 경로) | V2 client (기본 조합에 없음) | Browser RPC |
|
|
|---|---|---|---|
|
|
| KEYED 명령 자동 재시도 | 전송 전 실패만 재시도한다. 전송 뒤 실패는 재시도하지 않고 `MAYBE_APPLIED`다. 응답(5xx·429)으로는 재시도하지 않는다 (`src/adapters/http/http-retry-lifecycle.ts` `canRetryTransport`, `isRetryableSemantics`) | 네트워크·타임아웃·429·408/425/502/503/504 뒤 같은 키로 다시 보낸다. 전송 여부를 보지 않는다 (`src/adapters/http/retry-policy.ts` `shouldRetry`) | `KEYED_COMMAND`는 유효한 키가 있고 profile `retryOwner`가 `FRONTEND_ADAPTER`면 `retryableFailures`에서 같은 키로 다시 보낸다 (`src/adapters/browser-rpc/browser-rpc-runtime.ts` `shouldRetry`) |
|
|
| 재시도 횟수 상한 | min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2) (`http-execution-v3.ts` `retryCeiling`) | `MAX_RETRY_ATTEMPTS`, 기본 2 (`client.ts` `maxRetryAttempts`) | profile `maxAttempts`(시도 횟수), 하드 상한 4 (`src/contracts/browser-rpc.ts` `BROWSER_RPC_HARD_LIMITS`) |
|
|
| `Retry-After` | 5초를 넘으면 재시도하지 않는다. 이하면 hint에 jitter를 더해 기다린다 (`http-retry-lifecycle.ts` `retryDelayFor`) | 30초를 넘으면 재시도하지 않는다. 이하면 max(backoff, hint)만큼 기다린다 (`retry-policy.ts`) | profile `maxRetryAfterMs`로 잘라 max(backoff, hint)만큼 기다린다. 하드 상한 60초 (`browser-rpc-runtime.ts` `retryDelay`) |
|
|
| `REQUEST_TIMEOUT_MS` | 상한이다. 계약 `totalDeadlineMs`를 줄이기만 한다 (`runtime-adapters.ts` `requestDeadlineCeilingMs`) | 기본값이다. operation `timeoutMs`가 있으면 그 값을 쓰고, 더 길 수도 있다 (`client.ts` `defaultTimeoutMs`) | 쓰지 않는다. operation `totalDeadlineMs`만 쓴다. 하드 상한 30분 |
|
|
|
|
결과 불명 뒤 사용자 재전송은 전송과 무관하게 같은 intent·같은 키를 쓴다
|
|
(`src/presentation/adapters/query/application-query.ts` `resendUnknownEffect`).
|
|
|
|
## 17. Observability와 privacy
|
|
|
|
허용되는 공통 dimension:
|
|
|
|
```text
|
|
operation ID
|
|
contract/profile version
|
|
status group / safe error code
|
|
attempt bucket
|
|
duration bucket
|
|
provider/runtime health
|
|
traffic admission stage
|
|
```
|
|
|
|
금지:
|
|
|
|
- Authorization, cookie, CSRF와 idempotency key
|
|
- request/response body와 validation value
|
|
- URL query, cursor, snapshot, ETag/revision
|
|
- GraphQL variables/path/raw error/extensions
|
|
- protobuf bytes, metadata와 trailer 원문
|
|
- user ID/email/file name을 metric label이나 trace attribute로 사용
|
|
|
|
Request ID와 trace ID는 browser에 반환할 수 있지만 credential 역할을 하지 않으며
|
|
추측 가능한 database primary key를 포함하지 않는다.
|
|
|
|
필수 SLO/alert 후보:
|
|
|
|
- operation availability와 latency
|
|
- 401/403/409/412/422/429 및 5xx rate
|
|
- schema/mapper/contract mismatch
|
|
- idempotency in-progress age, collision과 unknown effect
|
|
- cursor invalid/expired/loop-equivalent server detection
|
|
- conditional hit/miss와 invalid 304
|
|
- GraphQL persisted miss/cost reject
|
|
- Connect missing/duplicate EndStream, whole-body/queue overflow와 compression mismatch
|
|
- gRPC-Web missing terminal status, frame/idle/queue overflow
|
|
- REST Gateway route/OpenAPI/runtime rewrite drift와 cancel propagation loss
|
|
|
|
## 18. 배포, compatibility와 rollback
|
|
|
|
권장 순서:
|
|
|
|
1. contract artifact와 compatibility diff를 생성한다.
|
|
2. backend가 N/N-1 fixture를 통과한 상태로 먼저 배포한다.
|
|
3. frontend operation은 traffic disabled 상태에서 staging conformance를 실행한다.
|
|
4. read-only shadow/canary 뒤 query traffic을 올린다.
|
|
5. keyed command는 idempotency/reconcile fault injection 뒤 별도 canary한다.
|
|
6. pagination, conditional, optimistic, GraphQL, Connect, gRPC-Web과 REST
|
|
Gateway는 각각 독립 gate로 승격한다.
|
|
7. provider/browser/operations evidence가 완료된 operation만 enabled한다.
|
|
|
|
Rollback은 frontend/backend/contract artifact를 coherent set으로 되돌린다.
|
|
unknown-effect command를 다른 protocol이나 새 idempotency key로 replay하지 않는다.
|
|
Backend가 old contract를 제거하는 시점은 실제 frontend support window와 cache/CDN
|
|
retention 뒤다.
|
|
|
|
## 19. Conformance와 fault-injection matrix
|
|
|
|
Backend 완료 판정에는 unit test 외에 actual staging provider evidence가 필요하다.
|
|
|
|
| 범위 | 필수 증거 |
|
|
| --- | --- |
|
|
| REST | exact path/query/body, media/status/envelope, max body, malformed/truncated JSON |
|
|
| Auth | missing/expired credential, 401/403, rotation, cross-origin preflight |
|
|
| Command | concurrent same-key replay, fingerprint mismatch, commit 뒤 response loss |
|
|
| Cursor | filter/sort binding, expiry, snapshot stability, loop/gap/duplicate 방지 |
|
|
| Conditional | 200→304, cache-missing 304 방지, representation change, 412 |
|
|
| Schema | additive/breaking/null/enum/time/number fixtures와 N/N-1 |
|
|
| GraphQL | persisted hit/miss/hash mismatch, partial, cost/depth, router rollout |
|
|
| Connect | JSON/binary unary, GET restriction, EndStream, body/message cap, compression, cancel/deadline와 CORS |
|
|
| gRPC-Web | proxy media/status/trailer, oversized frame, cancel, idle, gap/resume |
|
|
| REST Gateway | HttpRule path/query/body, ProtoJSON, OpenAPI/status/error rewrite, abort propagation과 N/N-1 |
|
|
| Operations | deadline/retry amplification, rate limit, kill switch, coherent rollback |
|
|
|
|
## 20. Backend handoff checklist
|
|
|
|
- [ ] Browser-facing API/BFF owner와 on-call이 정해졌다.
|
|
- [ ] reference REST exact endpoint/envelope/status/media fixture가 있다.
|
|
- [ ] bearer 또는 cookie+CSRF 중 하나의 실제 profile과 CORS evidence가 있다.
|
|
- [ ] stable error vocabulary와 redaction contract가 있다.
|
|
- [ ] keyed command idempotency store, TTL, receipt와 reconcile이 있다.
|
|
- [ ] CursorPage를 선택했다면 opaque cursor/snapshot contract가 있다.
|
|
- [ ] conditional을 선택했다면 ETag/304/412와 cache owner가 있다.
|
|
- [ ] optimistic을 선택했다면 identity/membership/revision/conflict 의미가 있다.
|
|
- [ ] OpenAPI/runtime schema/mapper semantic artifact와 digest가 release에 binding됐다.
|
|
- [ ] GraphQL을 선택했다면 schema/persisted manifest/router evidence가 있다.
|
|
- [ ] Connect를 선택했다면 descriptor/runtime/server/browser evidence가 있다.
|
|
- [ ] gRPC-Web을 선택했다면 descriptor/proxy/browser evidence가 있다.
|
|
- [ ] REST Gateway를 선택했다면 kind/HttpRule/ProtoJSON/OpenAPI와 runtime
|
|
conformance evidence가 있다.
|
|
- [ ] staging conformance, fault injection, canary, kill switch와 rollback drill이
|
|
통과했다.
|
|
|
|
## 21. Frontend 완료 경계
|
|
|
|
Backend 구현과 별개로 현재 frontend 상태를 다음처럼 해석한다.
|
|
|
|
| 범위 | 현재 상태 | 남은 owner |
|
|
| --- | --- | --- |
|
|
| REST path/provider/auth/deadline/bounded JSON | `COMPOSED` | actual provider conformance는 backend/operations |
|
|
| runtime schema와 mapper registry | `COMPOSED` | artifact digest/source provenance는 backend contract source + frontend/platform |
|
|
| session generation과 query identity | `COMPOSED` | account identity projection은 identity integration + frontend |
|
|
| Cursor runtime | `AVAILABLE_NOT_COMPOSED` | CursorPage backend 계약 후 frontend query binding |
|
|
| conditional validator store | `AVAILABLE_NOT_COMPOSED` | ETag/304/412 backend 계약 후 frontend HTTP/cache transaction |
|
|
| ordered optimistic layer | `AVAILABLE_NOT_COMPOSED` | product membership/revision 승인 후 frontend mutation definition |
|
|
| GraphQL adapter | `DESIGNED_NOT_IMPLEMENTED` | product/backend 선택 뒤 frontend adapter/codegen |
|
|
| Browser RPC V3 공통 계약/coordinator | `AVAILABLE_NOT_COMPOSED` | selected descriptor/generated client와 protocol transport 확정 뒤 frontend provider adapter |
|
|
| Protobuf schema/codegen | `DESIGNED_NOT_IMPLEMENTED` | authenticated backend contract source 선택 뒤 pinned frontend generation |
|
|
| Connect-Web adapter | `DESIGNED_NOT_IMPLEMENTED` | product/backend/server 선택 뒤 frontend adapter/codegen |
|
|
| gRPC-Web adapter | `DESIGNED_NOT_IMPLEMENTED` | product/backend/proxy 선택 뒤 frontend adapter/codegen |
|
|
| Protobuf REST Gateway | `NOT_SELECTED` | gateway kind와 public HTTP contract 승인 뒤 REST adapter binding |
|
|
| persisted query/offline command | `NOT_SELECTED` | 별도 product ADR와 backend durability 계약 |
|
|
|
|
따라서 “backend만 구현하면 frontend가 아무 변경 없이 모든 capability를 자동
|
|
사용한다”는 의미는 아니다. 현재 선택된 REST reference vertical의 공통 frontend
|
|
기반은 완료됐지만, backend contract가 확정되면 Cursor/conditional/optimistic의
|
|
마지막 composition과 schema/mapper 변경이 frontend에 남는다. GraphQL,
|
|
Connect/gRPC-Web과 Protobuf REST Gateway는 제품이 선택되지 않았다. 공통 Browser
|
|
RPC operation/profile registry, application port와 lifecycle coordinator는
|
|
구현했지만, wire별 generated client/decoder/provider binding은 아직 구현하지
|
|
않았다. 따라서 backend contract가 정해져도 frontend provider adapter와
|
|
composition 작업은 명시적으로 남는다.
|