2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는 문서가 지금 코드와 다른 말을 한다. - 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로 가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/, 패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06). - 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다. optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리 블록이 옮긴 곳을 가리킨다(1112/09-02). - 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로 가리킨다(1112/08-17). - 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007), drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는 꼬리 문장(1112/02-08). - 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다 (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은 verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07). - create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자 (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15). - secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장 (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫 (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조 (1106/14-02). 고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다. 버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다). 위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제 docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드 예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture 규칙과 부딪쳐 결정 대기로 남긴다. 검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과 FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다. Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04, 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15, 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02, 0929/14-03, 0929/13-10, 1106/14-02
432 lines
32 KiB
Markdown
432 lines
32 KiB
Markdown
# 선택형 frontend adapter recipe
|
|
|
|
이 문서는 도메인과 무관한 선택형 frontend capability를 실제 프로젝트에
|
|
도입하는 실행 가이드다. 기본 스켈레톤에는 vendor runtime을 설치하지 않는다.
|
|
`RECIPE_AVAILABLE`은 catalog에 복사해 좁힐 recipe가 있다는 availability
|
|
표시다. runtime 구현이나 제품 선택·조립 상태가 아니다. 현재 catalog의 product
|
|
selection과 production composition은 별도로 `NOT_SELECTED`/미설치다.
|
|
일부 browser-native capability에는 dependency 없는
|
|
`referenceRuntime.status=AVAILABLE_NOT_COMPOSED` 구현이 함께 있지만, 이것도
|
|
제품 dataset·owner·policy가 정해져 bootstrap에 연결되기 전에는 설치된 기능이나
|
|
production readiness를 뜻하지 않는다.
|
|
|
|
## 1. 현재 상태와 파일 지도
|
|
|
|
| 항목 | 경로 | production 포함 |
|
|
| --- | --- | --- |
|
|
| 선택/금지/예산 SSOT | `config/recipes/frontend-capability-recipes.json` | 정책만 |
|
|
| catalog JSON schema | `config/schemas/recipes/frontend-capability-recipes.schema.json` | 아니오 |
|
|
| TypeScript port | `recipes/frontend-capabilities/contracts.ts` | 아니오 |
|
|
| fake/unavailable | `recipes/frontend-capabilities/fake-adapters.ts` | 아니오 |
|
|
| contract test | `tests/recipes/optional-capability-contracts.test.ts` | 아니오 |
|
|
| file/IndexedDB/OPFS/Cache 심층 계약. reference runtime이 있는 port는 복사하지 않고 `src/application/ports`의 port를 다시 내보낸다([0929] 05-03) | `recipes/frontend-capabilities/browser-file-storage-contracts.ts` | 아니오 |
|
|
| 심층 deterministic fake. file·storage durability·OPFS fake는 `src` port를 `implements`한다 | `recipes/frontend-capabilities/browser-file-storage-fakes.ts` | 아니오 |
|
|
| 심층 contract test | `tests/recipes/browser-file-storage-contracts.test.ts` | 아니오 |
|
|
| 짝 백엔드 세션 owner(JWT·Keycloak PKCE, Redis session 쿠키+CSRF). catalog 밖이고 복사해서 쓴다. src가 import하면 `PRODUCTION_IMPORTS_RECIPE` | `recipes/session-owners/`, 테스트 `tests/recipes/oidc-pkce-session-owner.test.ts`, `tests/recipes/cookie-session-owner.test.ts`, `tests/recipes/session-owners-runtime.test.ts`, 절차 `docs/manual/04-paired-backend-session.md` | 아니오 |
|
|
| browser data current-status ledger | `docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md` | 문서만 |
|
|
| 심층 설계/ADR | `docs/design/2026-07-27-browser-file-and-origin-storage-design.md`, `docs/adr/VD-11-browser-file-and-origin-storage.md` | 문서만 |
|
|
| client cache scope/persistence 설계 | `docs/design/2026-07-28-client-cache-and-storage-design.md`, `docs/adr/VD-13-client-cache-scope-and-persistence.md` | 문서만 |
|
|
| realtime/Web Push/Polling 설계와 reference runtime | `docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md`, `docs/adr/VD-28-realtime-events-web-push-and-bounded-polling.md`, `src/adapters/realtime`, `src/adapters/web-push` | composition 전에는 tree-shaken |
|
|
| transfer/CDN 설계/ADR | `docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md`, `docs/adr/VD-12-presigned-transfer-and-image-cdn.md` | 문서만 |
|
|
| Range/background 결정 | `docs/adr/VD-14-resumable-download-and-background-transfer.md` | 문서만 |
|
|
| storage lifecycle/migration 결정 | `docs/adr/VD-15-origin-storage-lifecycle-and-migration.md` | 문서만 |
|
|
| transfer composition/Image provider 결정 | `docs/adr/VD-16-browser-transfer-composition-and-image-delivery.md` | 문서만 |
|
|
| REST/GraphQL/Connect/gRPC-Web·Protobuf/REST Gateway·Schema·Mapper·Server State 설계 | `docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md`, `docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md`, `docs/adr/VD-23-api-transport-selection-and-rest-execution.md`, `docs/adr/VD-24-runtime-schema-and-boundary-mapper.md`, `docs/adr/VD-25-server-state-cache-lifecycle.md`, `docs/adr/VD-26-persisted-graphql-operation.md`, `docs/adr/VD-27-grpc-web-unary-and-server-stream.md`, `docs/adr/VD-29-connect-web-and-browser-protobuf-runtime.md`, `docs/adr/VD-30-protobuf-contract-and-rest-gateway.md` | 문서만 |
|
|
| provider-neutral Browser RPC V3 계약/port/runtime | `src/contracts/browser-rpc.ts`, `src/application/ports/browser-rpc`, `src/adapters/browser-rpc`, `tests/unit/browser-rpc` | composition 전에는 tree-shaken |
|
|
| API contract/server-state 복구 runbook | `docs/operations/api-contract-and-server-state-recovery.md` | 문서만 |
|
|
| storage 복구 runbook template | `docs/operations/browser-file-storage-recovery.md` | 문서만 |
|
|
| transfer/CDN 복구 runbook template | `docs/operations/browser-transfer-recovery.md` | 문서만 |
|
|
| browser-native reference runtime | `src/adapters/browser-files`, `src/adapters/browser-transfer`, `src/adapters/storage/indexeddb`, `src/adapters/storage/opfs`, `src/adapters/cache-storage` | composition 전에는 tree-shaken |
|
|
| reference runtime browser evidence | `tests/browser-capabilities` | 아니오 |
|
|
| 정적/번들 gate | `scripts/check-optional-recipes.ts` | build 도구 |
|
|
| negative fixture | `scripts/check-optional-recipe-fixtures.ts` | 아니오 |
|
|
| 완전 제거 gate | `scripts/test-optional-recipe-removal.ts` | 아니오 |
|
|
| native reference runtime 제거 gate | `scripts/test-browser-file-storage-runtime-removal.ts` | 아니오 |
|
|
|
|
현재 `productionRuntimeDependencies`는 빈 배열이며 카탈로그의 recipe 모두 선택되지
|
|
않았다. `recipes/`의 TypeScript example은 선택 시 복사하고 좁힐 출발점이고,
|
|
`src/adapters`의 browser-native reference runtime은 공통 lifecycle·failure
|
|
mechanism을 재사용할 수 있는 실제 구현이다. 제품 feature는 이 runtime에
|
|
schema/codec/query와 dataset 정책을 주입하고 더 좁은 facade 뒤에서 조립한다.
|
|
|
|
### Reference runtime bundle budget
|
|
|
|
`referenceRuntime`이 있는 recipe는 catalog의 `sourceRoots`를 실제 budget entry로
|
|
사용한다. gate는 중첩 root의 실행 가능한 source를 중복 제거하고 경로순으로
|
|
정렬한 뒤, 모든 module을 하나의 synthetic entry에 포함한다. 이 entry는 Vite
|
|
production mode, ES2022/ES module, esbuild minify로 build하며 tree-shaking을
|
|
명시적으로 끈다. 따라서 synthetic consumer가 호출 여부를 알 수 없다는 이유로
|
|
validation, quota, integrity, cleanup 같은 fail-closed guard가 예산에서 빠지지
|
|
않는다. 생성된 모든 chunk/asset의 Node zlib gzip byte 합계를 catalog의
|
|
`bundleBudgetGzipBytes`와 비교하고 결과와 SHA-256을
|
|
`artifacts/quality/optional-recipes.json`에 기록한다.
|
|
|
|
이 synthetic build는 설치 크기 상한을 검증하기 위한 것이며 product bootstrap에
|
|
runtime을 compose하지 않는다. 별도의 production manifest/module-inventory
|
|
검사는 선택되지 않은 runtime source가 실제 `dist`에 없는지 계속 검증한다.
|
|
|
|
예산 값은 `config/recipes/frontend-capability-recipes.json`이 정본이다. 정하는
|
|
규칙은 아래와 같다(2026-11-03, 리뷰 결정 0929/05-04).
|
|
|
|
- 예산 = 측정값 + 3%를 100 B 단위로 올린 값.
|
|
- 측정값의 3% 안에서 늘면 예산을 고치지 않는다.
|
|
- 3%를 넘게 늘면 예산을 올리는 커밋 본문에 늘어난 이유를 적는다. 그때 다시 이
|
|
규칙으로 정한다.
|
|
- 이유: 전에는 수정마다 100 B씩 올렸다. 그러면 한도가 늘 직전 측정값이라,
|
|
예산 초과가 "왜 커졌나"를 묻는 신호가 되지 못하고 수정마다 인상 커밋만 남았다.
|
|
- 버린 대안: 레시피 예산에서 kernel(`src/adapters/platform/` 등 공유 source)을 빼는
|
|
것. kernel이 커지는 것을 놓친다.
|
|
|
|
2026-11-03 측정(`check:optional-recipes:source`, 기준 `d166aa3`)으로 정한 값:
|
|
|
|
| recipe | 측정 gzip B | 예산 gzip B |
|
|
|---|---:|---:|
|
|
| `file-transfer` | 56,053 | 57,800 |
|
|
| `offline-indexeddb` | 37,327 | 38,500 |
|
|
| `realtime` | 40,902 | 42,200 |
|
|
| `service-worker-pwa` | 9,716 | 10,100 |
|
|
|
|
source가 예산을 넘으면 gate를 우회하지 않는다. output artifact와 늘어난 이유를
|
|
검토한 뒤 위 규칙으로 올린다.
|
|
|
|
## 2. 어느 경계에 두는가
|
|
|
|
| capability 성격 | port 소유자 | adapter 방향 | concrete 위치 예 |
|
|
| --- | --- | --- | --- |
|
|
| application이 외부 결과를 요청 | application | outbound | `src/adapters/<capability>` |
|
|
| URL/browser event가 의도를 전달 | application input | inbound | `src/presentation/adapters` |
|
|
| React 렌더링 동작만 교체 | presentation | local facade | `src/presentation/<capability>` |
|
|
| feature 전용 protocol | feature application | in/out 분리 | `src/features/<name>/adapters` |
|
|
|
|
WebSocket 연결 생성, reconnect와 credential attachment는 outbound다. 수신 JSON
|
|
검증과 application input 호출은 inbound다. Service Worker update event,
|
|
BroadcastChannel event도 같은 원칙을 적용한다. generated DTO와 vendor SDK
|
|
type은 facade 밖으로 노출하지 않는다.
|
|
|
|
## 3. recipe 선택표
|
|
|
|
| recipe | 설치하는 경우 | 설치하면 안 되는 경우 | 핵심 fallback |
|
|
| --- | --- | --- | --- |
|
|
| realtime | foreground ordered event 또는 duplex protocol이 확정됨 | focus refetch/manual refresh가 충분하거나 ordering·replay owner 없음 | bounded polling 또는 stale UI |
|
|
| offline/IndexedDB/OPFS | structured offline data/queue 또는 large local binary가 제품 요구 | credential, partition/retention/recovery 미정, HTTP cache로 충분 | read-only/online-only 또는 승인된 bounded Blob |
|
|
| Service Worker/Cache Storage | 설치형(installability) 또는 public HTTP representation cache owner 승인. 오프라인 셸은 지원하지 않는다(이 절 끝) | auth/private/opaque cache, update/rollback UX 없음 | hosting cache 기반 network app |
|
|
| file/picker/download | selection/preview/upload/download와 크기 제한이 있는 memory/integrity 요구 | backend 재검증 없음, 큰 파일을 통째로 buffer에 올림, 오래 사는 credential URL | native input + 인가된 직접 download |
|
|
| generated API | versioned source와 drift CI가 있음 | DTO가 domain/UI로 노출됨 | typed request builder + schema |
|
|
| feature flag | rollout/kill switch owner와 default 있음 | authorization에 사용 | typed local default |
|
|
| Web Worker | profiler가 main-thread 병목을 증명 | 단순 network I/O | chunked/deferred execution |
|
|
| multi-tab | 비민감 event 동기화가 필요 | server가 conflict authority | focus 시 authoritative refresh |
|
|
| browser permission | user gesture 기반 기능 필요 | boot 요청, denied UX 없음 | manual input/instruction |
|
|
| client workflow | cross-page client-only state가 실재 | query/server state 복제 | URL/local/context/query |
|
|
| large data UI | 실측 scale이 budget 초과 | pagination으로 충분, a11y 미정 | accessible pagination |
|
|
| analytics/error sink | provider·consent·retention 승인 | arbitrary payload/redaction 우회 | bounded local diagnostics |
|
|
|
|
정확한 failure matrix, security/privacy, gzip budget과 제거 순서는 JSON catalog가
|
|
SSOT다. 문서와 catalog가 다르면 gate가 검사하는 catalog를 우선 고치고 이 표도
|
|
같이 갱신한다.
|
|
|
|
Service Worker를 켤 때 확인할 것(06-05). 템플릿은 1·6·7, 2의 시작 실패
|
|
이벤트, 2의 `observe`와 3을 제품 소유 파일에서 잇는 자리를 갖고 있다. 4·5를
|
|
잇는 제품 소유 자리는 아직 없다.
|
|
|
|
1. 제품 소유 파일 `src/features/product-capabilities.ts`의 `SERVICE_WORKER`를
|
|
`ACTIVE`로 바꾼다. `scripts/build-frontend.ts`가 worker 빌드를 추가로 돈다.
|
|
템플릿 파일 `src/features/installed-runtime-capabilities.ts`는 그 선택을
|
|
검사하고 투영만 하므로 고치지 않는다.
|
|
2. 관측: `createRuntimeComposition`이 텔레메트리 포트를 optional host에 넘긴다
|
|
(`src/bootstrap/create-runtime-composition.ts`). 시작 결과가 `FAILED`나
|
|
`INCOMPATIBLE`이면 `service-worker.start.failed`가 1건 남는다
|
|
(`src/bootstrap/optional-runtime-host.ts`). 실제 composition에서 첫 설치가
|
|
실패하면 이벤트가 1건 나가는 것은
|
|
`tests/component/runtime-composition-service-worker-telemetry.test.ts`가
|
|
확인한다. 템플릿이 연결하지 않은 것은 셋이다. 업데이트 설치 실패
|
|
(`watchForUpdates`, `src/adapters/service-worker/service-worker-page-controller.ts`)는
|
|
이벤트를 남기지 않는다. page controller의 `observe`는 제품이
|
|
`src/bootstrap/product-composition.ts`의 `composeProduct`에서
|
|
`serviceWorker.observe`로 돌려준다(1103/09-05). 템플릿 조립이 그것을 optional
|
|
host에 넘기고, 던지면 무시한다. `OptionalRuntimeHost.health()`는 `src` 안에서
|
|
읽는 코드가 없다.
|
|
3. blockers: 저장하지 않은 편집이 있는 탭이 활성화를 거절하게 `composeProduct`가
|
|
`serviceWorker.blockers`를 돌려준다. 하나가 true를 돌려주거나 던지면
|
|
`requestActivation()`이 `BLOCKED_DIRTY_CLIENT`로 거절한다. 템플릿 파일
|
|
`src/bootstrap/create-runtime-composition.ts`는 고치지 않는다. 실제 조립에서 두
|
|
값이 page controller에 닿는 것은
|
|
`tests/component/runtime-composition-service-worker-product-wiring.test.ts`가
|
|
확인한다.
|
|
4. 활성화 UI: `ServiceWorkerRuntimeHost.onUpdateWaiting`을 구독하고, 사용자가
|
|
동의하면 `requestActivation()`을 부른다(`src/contracts/service-worker.ts`).
|
|
5. reload 처리: `onReloadRequired`를 구독해 reload를 안내한다.
|
|
6. 끄기·롤백·제거: `docs/operations/release-cache-rollback.md`의 Service Worker
|
|
절차. `service-worker.js`는 `Cache-Control: no-cache`로 서빙한다.
|
|
7. 실제 브라우저 검사: `tests/e2e/service-worker-update.spec.ts`와
|
|
`service-worker-recovery.spec.ts`를 제품 구성으로 돌린다. helper는 이미
|
|
`ACTIVE`인 선택을 그대로 쓰고, 캐시 단언은 빌드가 만든 사전 캐시 목록과
|
|
비교한다. 준비 단계에서 실패하면 helper(`tests/e2e/support/service-worker-builds.ts`)
|
|
머리 주석의 전제 목록과 두 spec 머리 주석에서 바뀐 곳을 찾는다.
|
|
|
|
오프라인 셸(0929/06-03): reference 워커는 navigation을 가로채지 않는다
|
|
(`service-worker-static-assets.ts` navigation `NETWORK_ONLY`,
|
|
`service-worker-lifecycle.ts` `intercepts`). 사전 캐시는 해시 이름의
|
|
`assets/`(`src/contracts/service-worker.ts` `BUILD_ASSET_DIRECTORY`)뿐이고 `index.html`은
|
|
넣지 않는다(`scripts/generate-service-worker-assets.ts`). `public/`에서 dist 루트로 복사된
|
|
PWA 아이콘 같은 파일은 이름이 해시처럼 보여도 넣지 않는다(1105/06-01).
|
|
설계가 cached `index.html` fallback을 금지한다(closed deep design 18.8). 오프라인
|
|
셸이 필요한 제품은 템플릿 워커를 켜는 것으로 얻지 못한다. 별도 제품 capability로
|
|
설계하고, 그때 넘겨받는 파일은 위 세 파일과 `vite.service-worker.config.ts`다.
|
|
`tests/e2e/service-worker-update.spec.ts`의 사전 캐시 단언과 "HTML과 자산은 같은
|
|
release" 성질은 제품이 다시 증명한다. 넘겨받은 뒤에는 템플릿 동기화에서 이 파일들이
|
|
충돌한다.
|
|
|
|
Web Push target은 현재 13번째 설치 recipe가 아니다. 기존 `realtime`,
|
|
`service-worker-pwa`, `browser-permission`의 인접 경계를 조합해야 하는 별도
|
|
`NOT_SELECTED` capability다. 실제 선택 전 VD-10 amendment와 machine-readable
|
|
catalog에 권한(permission), subscription/backend provider, worker handler, 알림(notification)
|
|
정책과 제거 source를 명시하며, foreground realtime이 선택됐다는 이유로
|
|
Web Push를 함께 설치하지 않는다.
|
|
|
|
## 4. 공통 구현 순서
|
|
|
|
1. 문제를 vendor 이름이 아닌 capability와 측정값으로 기록한다.
|
|
2. catalog의 trigger와 forbidden 조건을 모두 검토한다.
|
|
3. project owner, security/privacy reviewer, gzip budget과 재검토 날짜를 VD-10
|
|
amendment에 기록한다.
|
|
4. existing URL/local/context/query/application port로 해결되지 않는지 확인한다.
|
|
5. 필요한 contract만 `recipes`에서 해당 application/presentation 경계로 복사해
|
|
실제 payload와 failure union으로 좁힌다.
|
|
6. concrete SDK는 `src/adapters/...` 또는 local presentation facade adapter에서만
|
|
import한다.
|
|
7. composition root가 concrete adapter를 주입한다. page/use case가 constructor를
|
|
직접 호출하지 않는다.
|
|
8. fake, 사용 불가(unavailable), timeout/cancel, cleanup, 형식이 틀린 입력, redaction과
|
|
integration test를 작성한다.
|
|
9. runtime config schema, 의존성 inventory/승인, SBOM, bundle budget,
|
|
browser support와 runbook을 갱신한다.
|
|
운영 CSP(`config/hosting/security-headers.json`)도 여기서 넓힌다. 기본 CSP는
|
|
아래 기능을 막는다(리뷰 0925/13-08).
|
|
- 다른 origin의 realtime: `connect-src`에 `wss://<realtime origin>`을 더한다.
|
|
`https:`는 `wss:`를 허용하지 않는다(CSP3 scheme 비교).
|
|
- 파일 preview(`src/adapters/browser-files/object-url-lease.ts`의 object URL):
|
|
`img-src`에 `blob:`을 더한다.
|
|
- 이미지 CDN: `img-src`에 CDN origin을 더한다.
|
|
바꾼 CSP 아래에서 `tests/e2e/production-csp.spec.ts`가 그 기능의 화면을 열도록
|
|
smoke를 늘린다.
|
|
10. 실제 provider integration과 negative behavior가 통과한 뒤에만 catalog 상태를
|
|
별도 project catalog에서 `INSTALLED`로 바꾼다.
|
|
|
|
## 5. capability별 필수 검증
|
|
|
|
### Realtime
|
|
|
|
- runtime schema로 envelope/version/event ID/sequence/timestamp를 검증한다.
|
|
- reconnect는 exponential backoff 상한, visibility/offline 상태, auth refresh와
|
|
resume token expiry를 정의한다.
|
|
- duplicate/out-of-order는 domain use case에 전달하기 전에 정책화한다.
|
|
- route unmount/logout에서 unsubscribe하고 heartbeat timer를 종료한다.
|
|
- SSE는 active document의 one-way stream, WebSocket은 duplex protocol,
|
|
Web Push는 Service Worker가 받는 background notification hint, Polling은
|
|
visible/finite HTTP scheduling policy로 분리한다.
|
|
- 기본 event 효과는 query namespace invalidation과 authoritative refetch다.
|
|
gap, cursor expiry와 queue overflow에서는 delta 적용을 중단하고 snapshot으로
|
|
복구한다.
|
|
- Web Push permission은 user action에서만 요청하고 subscription endpoint/key와
|
|
payload를 storage, URL, telemetry나 application state에 노출하지 않는다.
|
|
- 설계 배경(기록)은
|
|
[Realtime events, Web Push, and bounded polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)이다.
|
|
현재 concrete runtime과 product selection은 없다.
|
|
- 짝 백엔드 템플릿의 실시간 출구(STOMP-over-SockJS, NDJSON)와 이 repo의 SSE·
|
|
`realtime.v1` WebSocket 어댑터는 그대로 연결되지 않는다. 지금 두 템플릿만으로
|
|
되는 경로는 bounded polling이다. 대응표와 push를 고를 때의 세 길은 아래
|
|
「짝 백엔드 실시간 출구와의 대응」이다(1103/04-02).
|
|
- bounded polling의 `execute`가 실행기 결과를 poll attempt 결과로 바꾸는 표는 아래
|
|
「poll attempt 결과 대응」이다(1106/04-02).
|
|
|
|
#### 짝 백엔드 실시간 출구와의 대응
|
|
|
|
2026-11-08에 설계서가 기록(`docs/design/`)으로 옮겨진 뒤에도 지금 규칙인 표라 여기로 옮겼다(1112/09-02).
|
|
|
|
결론: 짝 백엔드(`clean-architecture-backend-template`)의 실시간 출구와 이
|
|
repo의 SSE·WebSocket 어댑터는 **지금 그대로 연결되는 조합이 없다.** 지금 두
|
|
템플릿만으로 되는 경로는 bounded polling 하나다. push가 필요하면 한쪽에 새 코드를
|
|
써야 하고, 어느 쪽을 쓸지는 제품이 정한다.
|
|
|
|
```text
|
|
프론트 SSE 어댑터 → Accept: text/event-stream, REALTIME_EVENT_V1 envelope
|
|
프론트 WS 어댑터 → subprotocol 정확히 "realtime.v1", REALTIME_EVENT_V1 envelope
|
|
짝 백엔드 STOMP 채널 → SockJS /ws, /topic 구독 1개, Map<String,String> 투영, 재전송 없음
|
|
짝 백엔드 스트리밍 → NDJSON, JSON text sequence(RFC 7464). SSE writer는 없다
|
|
```
|
|
|
|
| 프론트 transport | 짝 백엔드 출구 | 지금 연결되나 | 이유 |
|
|
| --- | --- | --- | --- |
|
|
| SSE (`fetch-sse-connection.ts`) | 없음 | 아니오 | 백엔드에 SSE writer가 없다(`StreamMediaType.SSE`는 OpenAPI 생성기만 쓴다). 아키텍처 테스트가 MVC `SseEmitter`를 금지한다(`ForbiddenApiArchitectureTest` `NO_SSE_EMITTER`, 백엔드 결정 D3). 스트리밍 writer는 NDJSON·JSON text sequence뿐이다(`clean-architecture-backend-template/src/adapter/inbound/web-advanced/README.md`) |
|
|
| WebSocket (`websocket-connection.ts`) | STOMP-over-SockJS 채널 | 아니오 | 프론트는 협상된 subprotocol이 정확히 `realtime.v1`이어야 연다(`websocket-protocol.ts`). 백엔드에는 subprotocol 협상 코드가 없다. STOMP frame은 `REALTIME_EVENT_V1` envelope(streamEpoch, sequence, eventId, scopeBinding)이 아니다 |
|
|
| WebSocket | raw WebSocket 라이브러리 API(`servlet/`) | 아니오(새 코드 필요) | 서비스 어댑터가 handler를 직접 조립한다. `realtime.v1` 협상과 envelope을 구현한 예시는 없다 |
|
|
| bounded polling (`bounded-poll-coordinator.ts`) | REST GET + Envelope | **예** | V3 실행기가 짝 백엔드 Envelope을 읽는다. poll 전용 operation의 `retryBudget`을 0으로 둔다(설계서 9.2절) |
|
|
|
|
push가 필요할 때 고를 길(제품 결정, 리뷰 1103/04-02 결정의 근거):
|
|
|
|
1. **백엔드에 `realtime.v1` WebSocket handler를 쓴다.** 프론트 어댑터를 그대로
|
|
쓰고 `CURSOR` 복구까지 갈 수 있다. 백엔드에 sequence·replay 저장소(outbox)가
|
|
필요하다. SSE는 백엔드 결정 D3을 먼저 바꿔야 하므로 이 표에서는 WebSocket을
|
|
먼저 적는다.
|
|
2. **프론트에 STOMP transport를 쓴다.** 백엔드는 그대로다. STOMP frame에는
|
|
sequence·epoch가 없어 stream coordinator의 gap·cursor 기능을 못 쓴다. frame을
|
|
query 무효화 hint로만 쓰고 데이터는 snapshot(REST GET)으로 다시 읽는다
|
|
(`INVALIDATION_HINT` + `SNAPSHOT_ONLY`). simple broker는 재전송이 없으므로
|
|
연결이 끊긴 동안의 변경은 재연결 뒤 snapshot으로만 회복한다.
|
|
3. **push 없이 bounded polling만 쓴다.** 두 repo 모두 새 코드가 없다. freshness는
|
|
poll 주기(최소 5초)로 정해진다.
|
|
|
|
다시 볼 때: 백엔드에 `realtime.v1` handler나 SSE writer가 생기거나, 프론트에 STOMP
|
|
transport가 생기면 이 표를 고친다. 백엔드 쪽 정본은
|
|
`clean-architecture-backend-template/src/adapter/inbound/websocket/README.md`다.
|
|
|
|
#### poll attempt 결과 대응
|
|
|
|
`execute`는 실행기 결과를 아래 표대로 poll attempt 결과로 바꾼다(1106/04-02).
|
|
poll이 재시도하는 kind는 `retryable: true`인 `CONNECT_TIMEOUT`·`RATE_LIMITED`·
|
|
`PROVIDER_UNAVAILABLE`뿐이고, `retryAfterMs`는 뒤 둘만 읽는다.
|
|
|
|
| V3 결과 `kind` | poll attempt 결과 |
|
|
| --- | --- |
|
|
| `SUCCESS` | `ok: true`, `kind: "VALUE"`, `value`, terminal 판정에 쓸 `state`. 결과에 본문 크기가 없으므로 `responseBytes`는 `0`을 둔다. 본문 상한은 실행기가 `frontend.responseByteLimit`으로 지킨다(넘으면 `CONTRACT_VIOLATION`). 그래서 poll descriptor의 `responseByteLimit`을 lease `maxResponseBytes` 이하로 둔다 |
|
|
| `PROBLEM` | `metadata.status`가 5xx·`408`·`425`이면 `PROVIDER_UNAVAILABLE`, `retryable: true`, `retryAfterMs`는 `metadata.retryAfterMs`. 그 밖의 status는 다시 보내도 같은 답이라 `PROTOCOL_MISMATCH`, `retryable: false`. 설계서 9.4절의 reset 계약이 있는 `409`·`410`만 `CURSOR_EXPIRED`, `retryable: false` |
|
|
| `UNAUTHENTICATED` | `AUTH_REQUIRED`, `retryable: false`. lease가 끝나고, session owner가 회복한 뒤 새 lease를 연다(설계서 9.3절) |
|
|
| `FORBIDDEN` | `FORBIDDEN`, `retryable: false` |
|
|
| `RATE_LIMITED` | `RATE_LIMITED`, `retryable: true`, `retryAfterMs`는 결과의 `retryAfterMs` |
|
|
| `CONTRACT_VIOLATION` | `metadata.status`가 5xx·`408`·`425`이면 쓸 수 있는 problem 본문 없이 온 서버 장애라 `PROBLEM`의 장애 행과 같다. 그 밖(입력 거절 `INPUT_INVALID`, 응답 schema·크기 위반)은 `PROTOCOL_MISMATCH`, `retryable: false` |
|
|
| `TRANSPORT_FAILURE` | `failure.kind`가 `TIMEOUT`이면 `CONNECT_TIMEOUT`, `retryable: true`. `ABORTED_BY_CALLER`면 `ABORTED`, `ABORTED_BY_SCOPE`면 `SCOPE_FENCED`, 둘 다 `retryable: false`. 나머지(`NETWORK_FAILURE` 등)는 `PROVIDER_UNAVAILABLE`, `retryable: true`. 실행기가 끝낸 transport 실패의 `failure.retryable`은 모두 `false`라 옮기지 않는다 |
|
|
| `CANCELLED` | `ABORTED`, `retryable: false` |
|
|
| `AUTH_INTEGRATION_FAILURE` | `reason`이 `CREDENTIAL_OWNER_UNAVAILABLE`이면 `PROVIDER_UNAVAILABLE`, `retryable: true`. 그 밖은 구성 결함이라 `PROTOCOL_MISMATCH`, `retryable: false`. 어느 쪽도 로그아웃 경로로 보내지 않는다 |
|
|
|
|
실패 결과의 `operation`은 모두 `"POLL"`이다. `retryAfterMs`는 값이 있을 때만
|
|
칸을 둔다. 값이 `undefined`인 칸은 모양이 틀린 결과라 lease가 `PROTOCOL_MISMATCH`로
|
|
끝난다. lease 상태 검사가 결과 해석보다 먼저라, 그사이 hidden·offline·scope
|
|
변경·close가 있었으면 표와 상관없이 그 kind로 끝난다. 이 표를 따르는 조합 예는
|
|
`tests/unit/realtime/bounded-poll-coordinator.test.ts`의 `pollAttemptResult`다.
|
|
- realtime 레지스트리(`createRealtimePolicyRegistry`)가 받는 세 바인딩의 출처
|
|
(1103/04-06). 기능 모듈에는 codec·mapper를 낼 칸이 없으므로 조합 코드가 모은다.
|
|
- `apiOperations`: `loadInstalledFeatureRuntimeRegistries().apiOperations`
|
|
(`projectApiOperationRows`). snapshot·checkpoint operation이 여기서 온다.
|
|
- `schemaCodecs`: 기능 contract contribution의 V3 `events[].payloadValidator`
|
|
(`composedContractContributions.eventByType`)와 checkpoint 응답의
|
|
`outputValidator`를 `runtimeSchemaCodecFromValidator`로 바꿔
|
|
`composeRuntimeSchemaCodecs`로 합친다. event type의 `payloadSchemaId`가 그
|
|
validator의 `schemaId`와 같아야 등록된다. 같은 이벤트의 스키마를 V3 `events`와
|
|
realtime 등록 두 곳에 따로 쓰지 않는다.
|
|
- `mappers`: 조합 코드가 `BoundaryMapper`(`src/contracts/boundary-mapper.ts`)를
|
|
쓰고 `composeBoundaryMapperRegistry`로 합친다. mapper의 `inputSchemaId`는 event
|
|
type의 `payloadSchemaId`와 같아야 한다. 템플릿이 만드는 출처는 없다.
|
|
- 기능 모듈에 칸을 더하는 것(V3 `events`에서 event type을 뽑거나
|
|
`realtimeMappers` 칸)은 위 대응표에서 push 경로를 고른 뒤 정한다. STOMP hint
|
|
경로면 delta mapper가 필요 없을 수 있다.
|
|
|
|
### IndexedDB/OPFS
|
|
|
|
- 기존 동기식 preference `StoragePort`에 넣지 않고 feature-specific async
|
|
repository와 large-object port를 사용한다.
|
|
- raw database/transaction/store/index/schema version은 adapter 밖으로 노출하지
|
|
않는다. request success가 아니라 transaction complete 이후에만 성공이다.
|
|
- DDL schema와 record codec version을 분리하고 schema upgrade는 additive,
|
|
data migration은 resumable bounded batch로 실행한다.
|
|
- versionchange/blocked/future schema를 read-only/online-only 상태로 드러내며
|
|
자동 reload와 database 삭제를 금지한다.
|
|
- OPFS는 immutable bytes만 소유하고 IndexedDB journal이
|
|
`PREPARING -> FILES_READY -> COMMITTED -> CLEANED` commit authority를 가진다.
|
|
- quota, 깨진 row/manifest, migration checkpoint, worker 비정상 종료, storage 축출(eviction),
|
|
N-1 rollback을 fixture와 실제 browser에서 검증한다.
|
|
|
|
### Cache Storage/Service Worker
|
|
|
|
- Cache Storage는 public HTTP representation 전용이며 application repository나
|
|
query cache가 아니다.
|
|
- 인증 필요, cookie 의존, private, 개인 정보, no-store, opaque, redirect, 206 응답을
|
|
거절하고 query/Vary exact match를 보존한다.
|
|
- candidate 전체의 type/size/integrity가 검증된 뒤에만 release를 활성화하고
|
|
verified previous release를 rollback용으로 유지한다.
|
|
- stale worker loop를 막고 unregister와 parsed owned-cache cleanup을 별도 lifecycle로
|
|
검증한다.
|
|
|
|
### File/Blob/picker/download, presigned transfer와 generated API
|
|
|
|
- native File/Blob/handle은 transient adapter vault 안에 두고 application에는
|
|
opaque ref, untrusted metadata와 bounded range/chunk만 전달한다.
|
|
- native input을 baseline으로 두고 system picker는 user activation 안에서만
|
|
progressive enhancement한다. dismissal은 failure가 아니다.
|
|
- upload는 client MIME을 신뢰하지 않고 count/size/signature/server rejection,
|
|
resumable session, part checksum/idempotency, quarantine을 다룬다.
|
|
- presigned URL은 application에 raw URL로 노출하지 않고 in-memory identity
|
|
capability로 보관한다. method/resource 또는 session-part/offset/length/checksum,
|
|
expiry, origin/path/query/header를 정확히 묶고 data-plane fetch는 credential,
|
|
redirect, referrer와 cache를 fail-closed 정책으로 제한한다.
|
|
- resume는 IndexedDB checkpoint만 신뢰하지 않고 server status와 다시 선택한
|
|
source의 part digest를 대조한다. checkpoint에는 URL/query/signed header/token을
|
|
저장하지 않으며 explicit abort가 불명확하면 reconcile 전까지 유지한다.
|
|
- progress는 unknown total을 허용하며 navigation/unmount에서 AbortSignal로
|
|
취소한다. server upload session은 별도 abort/TTL cleanup이 필요하다.
|
|
- 큰 download는 single `Uint8Array`/Blob이 아니라 browser handoff 또는
|
|
backpressure stream을 사용하고 handoff와 confirmed save를 구분한다.
|
|
- Image CDN은 raw transform URL builder가 아니라 opaque asset과
|
|
composition-registered preset으로만 responsive descriptor를 만든다. immutable
|
|
revision, format/width/pixel/decode/cache/expiry와 CDN origin을 검증한다.
|
|
- object URL은 explicit lease로 만들고 replacement/unmount에서 revoke한다.
|
|
- generated code는 facade 뒤 DTO이며 runtime response schema와 contract drift
|
|
gate를 유지한다.
|
|
|
|
### Flag/worker/multi-tab/browser
|
|
|
|
- flag unknown/unavailable/stale에서 명시적 typed fallback을 사용하고 access
|
|
control로 사용하지 않는다.
|
|
- worker는 task ID/generation/cancel을 사용해 stale result를 폐기하고 crash를
|
|
normalized failure로 바꾼다.
|
|
- multi-tab은 source/event/version으로 self-echo와 duplicate를 막고 payload를
|
|
비민감 invalidation hint로 제한한다.
|
|
- browser permission은 user gesture에서만 요청하고 denied/dismissed/unsupported를
|
|
서로 다른 UX 결과로 처리한다.
|
|
|
|
### Client workflow/large data/analytics
|
|
|
|
- workflow store는 server entity/collection을 복제하지 않고 query key나 ID 참조만
|
|
보관한다. logout/reset/version mismatch 정책을 테스트한다.
|
|
- virtualization은 profiler와 production-like row count로 정당화하며 keyboard,
|
|
focus restoration, screen reader와 stale row identity를 검증한다.
|
|
- analytics는 essential diagnostics와 consent-required event를 분리하고 closed
|
|
event/attribute registry, queue에 넣기 전 redaction, sampling, 크기 제한 queue와
|
|
retention을 적용한다.
|
|
|
|
## 6. 검증 명령
|
|
|
|
```bash
|
|
corepack pnpm check:types:test
|
|
corepack pnpm test:recipes
|
|
corepack pnpm test:browser-capabilities
|
|
corepack pnpm build
|
|
corepack pnpm check:optional-recipes
|
|
corepack pnpm check:optional-recipe-fixtures
|
|
corepack pnpm test:optional-recipe-removal
|
|
corepack pnpm test:browser-file-storage-removal
|
|
```
|
|
|
|
negative gate는 cleanup 누락, 선택하지 않은 의존성, local adapter 밖 vendor
|
|
import, credential localStorage/URL/telemetry 경로, workflow store의 server-state
|
|
복제, production source의 recipe import와 선택 전 reference runtime composition을
|
|
거절한다. removal gate는 recipe와 recipe test를 삭제한 임시 사본에서 base
|
|
typecheck, architecture, test와 build를 실행한다.
|
|
별도 native-runtime removal gate는 browser file/storage source와 전용 test,
|
|
catalog metadata를 제거한 임시 사본에서 typecheck, architecture, 전체 base test,
|
|
build와 optional catalog 검사를 다시 실행한다.
|
|
|
|
## 7. 제거 체크리스트
|
|
|
|
1. 신규 호출과 background 작업을 중지한다.
|
|
2. subscription, worker, channel, media track, observer를 정리(cleanup)한다.
|
|
3. persisted store/cache/event queue의 migrate 또는 purge 정책을 실행한다.
|
|
4. composition registration과 runtime config를 제거한다.
|
|
5. concrete adapter, facade/port와 vendor dependency를 제거한다.
|
|
6. dependency baseline, SBOM과 bundle baseline을 갱신한다.
|
|
7. typecheck/test/build, production bundle absence와 도메인 기능 fallback을
|
|
검증한다.
|
|
|
|
provider 장애 시 fake로 바꾸어 production을 PASS 처리하지 않는다. 문서화된
|
|
unavailable fallback만 사용하고 provider가 필수인 promotion은
|
|
`FAIL_UNVERIFIED` 또는 blocked 상태로 유지한다.
|