Carries 359 template commits, tag v0.2.0 plus one documentation commit: the generator-built feature index with its app, bounded-context and feature declarations, the src/platform kernel and scale tooling, the 2026-09-24 src review fixes, and the 2026-09-25 maturity review round with its CHANGELOG [보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them merged with product changes; 127 are not carried. Product identity is unchanged: name, version 0.1.0, routes, design and the TechLog domain. Three decisions worth naming. TechLog stays composed directly, as the last two syncs recorded; its directory carries a NOT_INSTALLED marker that says so, and every installed-* composer takes the template's projection with TechLog added on top. The reference sample is no longer installed: the template now installs a feature only through feature-module.ts and context-routes.ts, which load the screens this product deleted, so its three operations, six schemas and one topic leave the registries, recorded as registry change evidence. And AppRouter mounts the platform and TechLog routes only; the template's bounded-context route gateway waits for a generator-installed feature. Required fixes: readSubject on the BFF session owner (without it every HTTP Studio session would close as integration-failed), zod through the facade in nine TechLog files, noUnusedLocals, and public/config.json written out to match the local profile. Derived baselines were recomputed after reproducing both sides' values: CI contract 101 commands / 106 references / 141 artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime config schema baseline equals the schema at8210d48. Verified here: types, lint, architecture, adapter inventory, CI contract, i18n, design system, diagnostics, browser security, dev release manifest, TechLog contract and build pass; 220 component, 155 integration, 15 contract, 418 TechLog, 43 reference-feature, 18 recipe and 46 release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at8210d48first and unchanged: check:registries (byte-identical), test:runtime-schema, verify:documentation. Brought by the template and escalated rather than suppressed: check:request-fanout on TechLog's cursor pagination, check:remediation-ledger (fails upstream too), the shared-chunk hash test, and the registry-dependent sample removal and second-feature tests. Playwright suites were not run. Full record, the five open questions and the follow-ups in docs/operations/template-sync-2026-09-29.md. (cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
5961 lines
154 KiB
Markdown
5961 lines
154 KiB
Markdown
# 프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계
|
|
|
|
- 작성일: 2026-07-30
|
|
- 상태: 구현 결정 정본 v1
|
|
- 대상 저장소: `clean-architecture-frontend-template`
|
|
- 기준 저장소 스냅샷: 제공된 Repomix 전체 저장소 표현
|
|
- 상위 설계:
|
|
- `2026-07-30-frontend-production-capability-repository-aligned-deep-design.md`
|
|
- 계약 정본:
|
|
- 별도 API·이벤트 계약 관리 저장소에서 발행한 immutable TypeScript contract package
|
|
- 기준 기술:
|
|
- Node.js 24 major
|
|
- pnpm 11
|
|
- TypeScript strict / `allowJs: false`
|
|
- React 19
|
|
- React Router 7 data mode
|
|
- TanStack Query 5
|
|
- Zod 4
|
|
- Vite 8
|
|
- 문서 규칙:
|
|
- **MUST**: 구현자가 변경할 수 없는 기본 결정
|
|
- **MUST NOT**: 존재하면 설계 위반
|
|
- **MAY**: 명시적으로 선택된 capability에만 허용
|
|
- 본 문서의 exact literal, 상태, 상한, 순서와 source path는 예시가 아니라 구현 정본이다.
|
|
|
|
---
|
|
|
|
## 목차
|
|
|
|
- [0. 문서 권한과 제외 범위](#0-문서-권한과-제외-범위)
|
|
- [1. 현재 저장소 기준선](#1-현재-저장소-기준선)
|
|
- [2. 구현 결정 폐쇄 표](#2-구현-결정-폐쇄-표)
|
|
- [3. 목표 런타임 구조와 lifecycle](#3-목표-런타임-구조와-lifecycle)
|
|
- [4. 외부 계약 package 소비 경계](#4-외부-계약-package-소비-경계)
|
|
- [5. Contract Set과 release coherence](#5-contract-set과-release-coherence)
|
|
- [6. Runtime Config와 boot](#6-runtime-config와-boot)
|
|
- [7. Fetch HTTP execution runtime](#7-fetch-http-execution-runtime)
|
|
- [8. Retry·cancellation·mutation effect certainty](#8-retrycancellationmutation-effect-certainty)
|
|
- [9. Router](#9-router)
|
|
- [10. Query lifecycle과 cache](#10-query-lifecycle과-cache)
|
|
- [11. Mutation lifecycle](#11-mutation-lifecycle)
|
|
- [12. Cross-context invalidation](#12-cross-context-invalidation)
|
|
- [13. Realtime product composition](#13-realtime-product-composition)
|
|
- [14. Connection·Reconnect·Resume](#14-connectionreconnectresume)
|
|
- [15. Event validation과 subscription cleanup](#15-event-validation과-subscription-cleanup)
|
|
- [16. Generic Web Worker](#16-generic-web-worker)
|
|
- [17. Service Worker lifecycle](#17-service-worker-lifecycle)
|
|
- [18. Cache Storage와 fetch policy](#18-cache-storage와-fetch-policy)
|
|
- [19. Offline Command와 Background Sync](#19-offline-command와-background-sync)
|
|
- [20. 공통 start·stop·dispose](#20-공통-startstopdispose)
|
|
- [21. Security와 privacy](#21-security와-privacy)
|
|
- [22. Runtime observability](#22-runtime-observability)
|
|
- [23. 구현 검증](#23-구현-검증)
|
|
- [24. Source 배치와 migration](#24-source-배치와-migration)
|
|
- [25. 구현 순서와 stop condition](#25-구현-순서와-stop-condition)
|
|
- [26. 완료 기준](#26-완료-기준)
|
|
- [27. 위험 등록부](#27-위험-등록부)
|
|
- [28. Normative decision ledger](#28-normative-decision-ledger)
|
|
- [부록 A. Numeric constants](#부록-a-numeric-constants)
|
|
- [부록 B. 금지 구현 목록](#부록-b-금지-구현-목록)
|
|
- [부록 C. 플랫폼 참고 기준](#부록-c-플랫폼-참고-기준)
|
|
|
|
---
|
|
|
|
## 0. 문서 권한과 제외 범위
|
|
|
|
### 0.1 목적
|
|
|
|
이 문서는 다음 프론트엔드 런타임 capability를 현재 저장소 구조에 맞춰 구현할 때 개발자가 다시 선택하거나 질문할 지점을 제거한다.
|
|
|
|
```text
|
|
Fetch HTTP Client
|
|
Runtime Config
|
|
Router
|
|
Query / Mutation
|
|
Connection / Reconnect / Resume
|
|
Event Validation
|
|
Subscription Cleanup
|
|
Web Worker
|
|
Service Worker
|
|
Background Sync
|
|
```
|
|
|
|
상위 저장소 정합형 설계가 방향과 책임을 고정했다면, 본 문서는 다음을 추가로 고정한다.
|
|
|
|
- exact source path;
|
|
- exact public type shape;
|
|
- exact lifecycle state;
|
|
- exact startup/shutdown order;
|
|
- exact timeout, queue, payload와 retry ceiling;
|
|
- exact optional capability selection과 removal 절차;
|
|
- external contract package를 저장소 runtime에 연결하는 단일 경로;
|
|
- browser lifecycle과 session/account transition ordering;
|
|
- failure union과 mutation uncertainty 처리;
|
|
- 구현 중 허용되지 않는 fallback;
|
|
- 구현 완료를 판정할 deterministic behavior case.
|
|
|
|
### 0.2 본 문서가 대체하는 범위
|
|
|
|
상위 설계의 다음 절은 본 문서가 더 구체적인 정본이다.
|
|
|
|
| 상위 범위 | 본 문서 정본 |
|
|
| --- | --- |
|
|
| Runtime Config와 boot coherence | §5–§6 |
|
|
| Fetch HTTP Client | §4, §7–§8 |
|
|
| Router | §9 |
|
|
| Query와 Mutation | §10–§12 |
|
|
| Realtime 공통 경계 | §13–§15 |
|
|
| Web Worker | §16 |
|
|
| Service Worker | §17–§18 |
|
|
| Offline Command와 Background Sync | §19 |
|
|
| optional capability 조립 | §3, §17.3, §24 |
|
|
| lifecycle·security·observability | §20–§22 |
|
|
| source 배치와 구현 순서 | §24–§25 |
|
|
|
|
상위 설계와 본 문서가 충돌하면 위 범위에서는 본 문서를 따른다.
|
|
|
|
### 0.3 API·이벤트 계약 관련 명시적 제외
|
|
|
|
다음은 별도 API·이벤트 계약 관리 저장소가 소유한다. 본 문서에서 다시 정의하거나 frontend local schema로 복제하지 않는다.
|
|
|
|
```text
|
|
OpenAPI / AsyncAPI 원문
|
|
operation method/path/status/media semantics
|
|
Problem Details type/code/extensions
|
|
pagination cursor wire shape
|
|
idempotency server semantics와 retention
|
|
event type/envelope/payload schema
|
|
replay/cursor/snapshot server protocol
|
|
provider compatibility와 deprecation/sunset
|
|
backend controller/event publisher conformance
|
|
contract package 생성·발행·서명·provenance
|
|
```
|
|
|
|
본 저장소가 소유하는 것은 다음뿐이다.
|
|
|
|
```text
|
|
immutable TypeScript contract package pin
|
|
package manifest/digest 검증
|
|
frontend-owned normalized descriptor interface
|
|
runtime validator 호출
|
|
wire DTO -> application value mapper
|
|
HTTP/Query/Realtime runtime behavior
|
|
contractSet와 frontend release coherence
|
|
unknown/future contract input의 safe failure
|
|
```
|
|
|
|
외부 package의 의미가 부족하거나 서로 모순되면 frontend가 임의 의미를 보충하지 않는다. 해당 feature contribution을 composition하지 않고 `CONTRACT_CONTRIBUTION_INVALID`로 종료한다.
|
|
|
|
### 0.4 CI 명시적 비범위
|
|
|
|
다음은 별도 CI/CD 플랫폼이 소유하며 본 문서에서 설계하지 않는다.
|
|
|
|
- workflow YAML;
|
|
- merge/release stage 구성;
|
|
- gate ID와 promotion formula;
|
|
- artifact retention service;
|
|
- package publication identity;
|
|
- vulnerability/signing/SBOM pipeline;
|
|
- deployment/canary controller;
|
|
- CI evidence aggregation.
|
|
|
|
§23은 코드가 만족해야 할 **행동 검증 케이스**만 정의한다. 어느 pipeline에서 실행할지는 정의하지 않는다.
|
|
|
|
### 0.5 정본 우선순위
|
|
|
|
충돌 시 다음 순서를 사용한다.
|
|
|
|
1. 현재 저장소 source와 실행 가능한 test가 증명하는 사실;
|
|
2. 별도 계약 저장소에서 발행한 exact immutable package;
|
|
3. 본 문서의 MUST/MUST NOT와 decision ledger;
|
|
4. 상위 저장소 정합형 설계;
|
|
5. 기존 일반 greenfield 설계;
|
|
6. 예시 코드와 설명 문구.
|
|
|
|
예시가 public type과 다르면 public type이 정본이다. 두 설정이 같은 의미를 서로 다르게 지정하면 precedence를 만들지 않고 startup을 실패시킨다.
|
|
|
|
---
|
|
|
|
## 1. 현재 저장소 기준선
|
|
|
|
### 1.1 물리 구조
|
|
|
|
현재 저장소의 canonical source root는 다음과 같다.
|
|
|
|
```text
|
|
src/
|
|
contracts/ # 저장소 내부 registry와 provider-neutral runtime contract
|
|
application/ # input/output port, use case, policy, view model
|
|
adapters/ # HTTP, query cache, storage, realtime, web-push 등 concrete adapter
|
|
presentation/ # React inbound adapter, Router, Query hook, UI
|
|
bootstrap/ # 유일한 composition root와 boot
|
|
features/ # 제거 가능한 vertical feature
|
|
```
|
|
|
|
다음 신규 parallel root는 만들지 않는다.
|
|
|
|
```text
|
|
src/platform
|
|
src/service-worker
|
|
src/workers
|
|
src/infrastructure
|
|
src/api
|
|
src/shared/api
|
|
```
|
|
|
|
### 1.2 계층 방향
|
|
|
|
현재 방향을 유지한다. 기준은 `.dependency-cruiser.json` 하나이고 `check:architecture`가 강제한다(`config/architecture/layers.json`은 아무도 읽지 않는 낡은 사본이라 지웠다, 리뷰 12-09).
|
|
|
|
```text
|
|
domain -> domain only
|
|
application -> application, domain, contracts
|
|
presentation -> presentation, application, domain, contracts
|
|
adapters -> adapters, application, domain, contracts
|
|
bootstrap -> src 전체
|
|
```
|
|
|
|
추가 불변조건:
|
|
|
|
```text
|
|
presentation MUST NOT import adapters
|
|
application MUST NOT import React, Router, TanStack Query, browser API
|
|
adapters MUST NOT import presentation/bootstrap
|
|
feature presentation MUST call application input or approved inbound bridge
|
|
bootstrap alone selects concrete runtime
|
|
```
|
|
|
|
### 1.3 현재 구현을 재사용하는 항목
|
|
|
|
다음 source를 제거하거나 동일 기능으로 다시 만들지 않는다.
|
|
|
|
| Capability | 현재 source | 판정 |
|
|
| --- | --- | --- |
|
|
| Runtime Config schema/load | `src/bootstrap/runtime-config-schema.ts`, `load-runtime-config.ts` | 보강 |
|
|
| Release manifest/load | `src/bootstrap/load-release-manifest.ts` | V2 migration |
|
|
| composition root | `src/bootstrap/create-runtime-composition.ts`, `composition-root.ts` | 확장 |
|
|
| bounded HTTP response | `src/adapters/http/bounded-json.ts` | 공통 bounded body reader로 확장 |
|
|
| Fetch client | `src/adapters/http/client.ts` | execution V3 보강 |
|
|
| request builder | `src/adapters/http/request-builder.ts` | package descriptor bridge 연결 |
|
|
| REST registry/profile | `src/contracts/api-operations.ts`, `rest-profiles.ts` | external contribution normalization으로 migration |
|
|
| Query adapter | `src/presentation/adapters/query/application-query.ts` | 유지·보강 |
|
|
| Query cache coordinator | `src/adapters/query-cache/*` | scope/invalidation 보강 |
|
|
| Router runtime | `src/presentation/routes/*` | 유지 |
|
|
| realtime registry/runtime | `src/contracts/realtime-*`, `src/adapters/realtime/*` | 제품 조립만 추가 |
|
|
| Web Push worker handler | `src/adapters/web-push/service-worker-runtime.ts` | 단일 SW entry handler로 재사용 |
|
|
| IndexedDB reference runtime | `src/adapters/storage/indexeddb/*` | offline dataset backend로 재사용 |
|
|
| OPFS Worker | `src/adapters/storage/opfs/*` | generic CPU Worker와 분리 유지 |
|
|
| Cache Storage reference | `src/adapters/cache-storage/*` | static asset handler에서 재사용 |
|
|
|
|
### 1.4 현재 삭제하지 않는 compatibility surface
|
|
|
|
다음 public/runtime surface는 migration 동안 유지한다.
|
|
|
|
- existing reference feature route와 local fixture;
|
|
- current `ApiOperationV2` reader;
|
|
- current runtime config V1 reader;
|
|
- current release manifest V1 parser;
|
|
- current query key and invalidation contracts;
|
|
- current RT-01~RT-04 common runtime;
|
|
- current browser file/storage reference runtime.
|
|
|
|
새 writer가 V2를 사용하도록 먼저 전환한 뒤 V1 reader를 제거한다. 같은 release에서 source shape, manifest shape와 runtime behavior를 동시에 big-bang 교체하지 않는다.
|
|
|
|
### 1.5 현재 상태 taxonomy
|
|
|
|
이 문서는 저장소 기존 상태 literal을 유지한다.
|
|
|
|
```text
|
|
COMPOSED
|
|
AVAILABLE_NOT_COMPOSED
|
|
DESIGNED_NOT_IMPLEMENTED
|
|
NOT_SELECTED
|
|
PLATFORM_LIMITED
|
|
```
|
|
|
|
현재 주요 판정:
|
|
|
|
| Capability | 현재 | 본 문서 목표 |
|
|
| --- | --- | --- |
|
|
| Runtime Config | `COMPOSED` V1 | V2 bounded boot |
|
|
| Release coherence | `COMPOSED` scalar contract version | contractSet V2 |
|
|
| HTTP reference path | `COMPOSED` | execution V3 |
|
|
| Router | `COMPOSED` | ownership closed |
|
|
| Query memory cache | `COMPOSED` | scope/result/invalidation closed |
|
|
| Query persistence | `NOT_SELECTED` | 계속 disabled |
|
|
| Realtime common runtime | `AVAILABLE_NOT_COMPOSED` | 그대로 재사용 |
|
|
| Product realtime | `NOT_SELECTED` | explicit contribution 필요 |
|
|
| Generic CPU Worker | `NOT_SELECTED` | opt-in runtime |
|
|
| OPFS Worker | `AVAILABLE_NOT_COMPOSED` | 별도 유지 |
|
|
| Cache Storage | `AVAILABLE_NOT_COMPOSED` | static asset only |
|
|
| PWA Service Worker lifecycle | `DESIGNED_NOT_IMPLEMENTED` | reference runtime |
|
|
| Offline command queue | `NOT_SELECTED` | opt-in reference runtime |
|
|
| Background Sync guarantee | `PLATFORM_LIMITED` | wake-only enhancement |
|
|
|
|
---
|
|
|
|
## 2. 구현 결정 폐쇄 표
|
|
|
|
다음 표의 선택은 구현 중 다시 묻지 않는다.
|
|
|
|
| 질문 | 결정 |
|
|
| --- | --- |
|
|
| capability별 새 `src/platform/*`를 만드는가 | 아니다. 기존 `contracts/application/adapters/presentation/bootstrap/features`에 배치한다. |
|
|
| API·이벤트 schema를 frontend에 복사하는가 | 아니다. exact immutable contract package만 소비한다. |
|
|
| deployed OpenAPI/AsyncAPI를 runtime에 읽는가 | 아니다. build dependency만 사용한다. |
|
|
| `API_CONTRACT_VERSION` scalar를 유지하는가 | 제거한다. Release Manifest V2 `contractSet`으로 교체한다. |
|
|
| Runtime Config가 optional feature를 켤 수 있는가 | 아니다. static installed capability를 끌 수만 있다. |
|
|
| boot JSON을 `response.json()`으로 읽는가 | 아니다. streaming byte bound 후 UTF-8/JSON parse한다. |
|
|
| HTTP retry owner | HTTP transport 하나다. Query/Mutation retry는 false다. |
|
|
| redirect | 모든 API/boot request에서 reject한다. |
|
|
| mutation timeout/abort를 실패로 단정하는가 | 아니다. send 이후는 `MAYBE_APPLIED`다. |
|
|
| Router loader가 server fetch/cache를 소유하는가 | 아니다. URL parse/guard/lazy lifecycle만 소유한다. |
|
|
| QueryClient 수 | application runtime당 하나다. |
|
|
| Query persistence | 기본 비활성이다. Web Storage와 IndexedDB에 query payload를 넣지 않는다. |
|
|
| query result size 추정 | 모든 definition의 required `measureResult`만 사용한다. generic fallback은 없다. |
|
|
| cross-tab data 전송 | 금지한다. opaque invalidation topic만 전송한다. |
|
|
| realtime transport 자동 fallback | 금지한다. registration이 explicit fallback을 선택한다. |
|
|
| connection open과 resume success | 별도 상태다. `OPEN_UNRESUMED`에서 event를 적용하지 않는다. |
|
|
| event checkpoint commit | application effect 성공 이후다. |
|
|
| component가 raw socket을 소유하는가 | 아니다. ref-counted subscription lease만 소유한다. |
|
|
| generic Worker 기본 설치 | 아니다. profiling과 static contribution이 있어야 한다. |
|
|
| Worker가 network/auth를 소유하는가 | 아니다. CPU task만 수행한다. |
|
|
| PWA와 Web Push worker registration을 나누는가 | 아니다. 동일 scope에 physical worker 하나다. |
|
|
| `skipWaiting()` | client drain handshake 성공 후에만 호출한다. |
|
|
| `clients.claim()` | baseline에서 사용하지 않는다. |
|
|
| navigation offline shell | 제공하지 않는다. navigation은 network-only다. |
|
|
| API response Cache Storage | 금지한다. verified static asset만 cache한다. |
|
|
| Service Worker 등록 시점 | Runtime Config/release 검증과 첫 committed render 이후다. |
|
|
| Background Sync가 command를 전송하는가 | baseline에서는 아니다. foreground drain wake-up만 기록한다. |
|
|
| offline sender 수 | origin/account partition당 하나다. |
|
|
| `SENDING` 중 crash | `PENDING`으로 되돌리지 않고 `EFFECT_UNKNOWN`이다. |
|
|
| 일반 disabled capability | listener/DB/worker/timer를 만들지 않는다. |
|
|
| persisted Service Worker disable | 새 register 없이 exact-owned registration만 unregister하고 cache를 보존한다. |
|
|
| Service Worker source 제거 | `ACTIVE -> REMOVE_REGISTRATION -> PURGE_OWNED_RESOURCES -> null` 순서다. |
|
|
| lifecycle correctness를 unload에 의존하는가 | 아니다. transaction, TTL, recovery로 닫는다. |
|
|
|
|
---
|
|
|
|
## 3. 목표 런타임 구조와 lifecycle
|
|
|
|
### 3.1 전체 흐름
|
|
|
|
```text
|
|
Vite embedded build identity
|
|
+ installed contract contributions
|
|
+ installed runtime capabilities
|
|
|
|
|
v
|
|
bounded Runtime Config V2
|
|
|
|
|
v
|
|
bounded Release Manifest V2 + contractSet check
|
|
|
|
|
v
|
|
base composition
|
|
HTTP / auth bridge / application / QueryClient / Router
|
|
|
|
|
v
|
|
React first committed render
|
|
|
|
|
v
|
|
post-mount optional runtime start
|
|
offline foreground observer
|
|
realtime hosts
|
|
lazy Web Worker registry
|
|
Service Worker active/cleanup controller
|
|
```
|
|
|
|
### 3.2 boot state machine
|
|
|
|
```text
|
|
UNINITIALIZED
|
|
-> LOADING_RUNTIME_CONFIG
|
|
-> VALIDATING_RUNTIME_CONFIG
|
|
-> LOADING_RELEASE_MANIFEST
|
|
-> VALIDATING_RELEASE_COHERENCE
|
|
-> COMPOSING_BASE
|
|
-> MOUNTING
|
|
-> BASE_READY
|
|
-> STARTING_OPTIONAL
|
|
-> READY
|
|
```
|
|
|
|
terminal/degraded state:
|
|
|
|
```text
|
|
BOOT_FAILED_SAFE
|
|
BASE_READY_OPTIONAL_DEGRADED
|
|
DISPOSED
|
|
```
|
|
|
|
`BOOT_FAILED_SAFE`에서는 product Router와 Query provider를 mount하지 않는다. safe boot shell만 render한다.
|
|
|
|
### 3.3 composition result
|
|
|
|
```ts
|
|
export interface RuntimeComposition {
|
|
readonly application: ApplicationApi;
|
|
readonly queryClient: QueryClient;
|
|
readonly router: Router;
|
|
readonly scopeRuntime: ServerStateScopeRuntime;
|
|
readonly optional: OptionalRuntimeHost;
|
|
dispose(): Promise<void>;
|
|
}
|
|
```
|
|
|
|
feature page에 다음을 노출하지 않는다.
|
|
|
|
- raw Fetch client;
|
|
- endpoint URL;
|
|
- auth credential attacher;
|
|
- browser storage;
|
|
- QueryClient;
|
|
- WebSocket/EventSource;
|
|
- Worker;
|
|
- ServiceWorkerRegistration;
|
|
- IndexedDB transaction.
|
|
|
|
### 3.4 optional runtime host
|
|
|
|
```ts
|
|
export interface OptionalRuntimeHost {
|
|
readonly realtime: RealtimeRuntimeHost | null;
|
|
readonly webWorkers: WebWorkerRuntimeHost | null;
|
|
readonly serviceWorker: ServiceWorkerRuntimeHost | null;
|
|
readonly offlineCommands: OfflineCommandRuntimeHost | null;
|
|
startAfterMount(): Promise<void>;
|
|
stop(): Promise<void>;
|
|
}
|
|
```
|
|
|
|
start order:
|
|
|
|
```text
|
|
1. offline foreground browser lifecycle observer
|
|
2. realtime runtime
|
|
3. Web Worker prewarm 없음
|
|
4. Service Worker active/cleanup controller
|
|
```
|
|
|
|
stop order는 역순이다.
|
|
|
|
### 3.5 static capability selection SSOT
|
|
|
|
```text
|
|
src/features/installed-runtime-capabilities.ts
|
|
```
|
|
|
|
```ts
|
|
export interface InstalledRuntimeCapabilities {
|
|
readonly realtime: readonly InstalledRealtimeContribution[];
|
|
readonly webWorkers: readonly InstalledWebWorkerContribution[];
|
|
readonly serviceWorker: InstalledServiceWorkerSelection | null;
|
|
readonly offlineCommands: InstalledOfflineCommandContribution | null;
|
|
}
|
|
|
|
export type RuntimeCapabilityOverride = "DEFAULT" | "DISABLED";
|
|
|
|
export type InstalledServiceWorkerSelection =
|
|
| Readonly<{
|
|
mode: "ACTIVE";
|
|
scriptPath: "service-worker.js";
|
|
handlers: readonly ServiceWorkerHandlerId[];
|
|
}>
|
|
| Readonly<{
|
|
mode: "REMOVE_REGISTRATION";
|
|
scriptPath: "service-worker.js";
|
|
}>
|
|
| Readonly<{
|
|
mode: "PURGE_OWNED_RESOURCES";
|
|
scriptPath: "service-worker.js";
|
|
}>;
|
|
|
|
export type ServiceWorkerHandlerId =
|
|
| "WEB_PUSH"
|
|
| "PWA_STATIC_ASSETS"
|
|
| "OFFLINE_SYNC_WAKEUP";
|
|
```
|
|
|
|
규칙:
|
|
|
|
- source contribution이 설치 capability를 결정한다;
|
|
- Runtime Config는 `DEFAULT | DISABLED`만 제공한다;
|
|
- config가 source에 없는 capability를 켤 수 없다;
|
|
- dynamic import path를 config 문자열에서 만들지 않는다;
|
|
- contribution array와 object는 composition 시 deep snapshot/freeze한다;
|
|
- duplicate ID와 contradictory selection은 mount 전 실패한다.
|
|
|
|
### 3.6 zero-side-effect 원칙과 persistent 예외
|
|
|
|
realtime/Web Worker/offline command가 unselected 또는 disabled이면:
|
|
|
|
```text
|
|
factory call 0
|
|
window listener 0
|
|
timer 0
|
|
network 0
|
|
IndexedDB open 0
|
|
Worker creation 0
|
|
```
|
|
|
|
Service Worker는 browser에 persistent registration이 남을 수 있으므로 다음 예외만 허용한다.
|
|
|
|
```text
|
|
static ACTIVE + runtime DISABLED
|
|
-> new register 0
|
|
-> exact owned registration lookup 1
|
|
-> owned registration unregister at most 1
|
|
-> owned cache delete 0
|
|
```
|
|
|
|
이 예외를 다른 capability의 hidden cleanup side effect 근거로 확대하지 않는다.
|
|
|
|
---
|
|
|
|
## 4. 외부 계약 package 소비 경계
|
|
|
|
### 4.1 단일 import 위치
|
|
|
|
service별 generated package import는 다음 파일 한 곳에서만 허용한다.
|
|
|
|
```text
|
|
src/features/<feature>/contracts/<service>-contract-contribution.ts
|
|
```
|
|
|
|
예:
|
|
|
|
```text
|
|
src/features/worklog/
|
|
contracts/
|
|
worklog-service-contract-contribution.ts
|
|
worklog-mapper.ts
|
|
application/
|
|
adapters/
|
|
worklog-http-gateway.ts
|
|
presentation/
|
|
```
|
|
|
|
금지 import:
|
|
|
|
```text
|
|
src/domain/** -> @org-contracts/*
|
|
src/application/** -> @org-contracts/*
|
|
src/presentation/** -> @org-contracts/*
|
|
src/adapters/http/** -> service-specific package
|
|
src/bootstrap/** -> service-specific package direct import
|
|
```
|
|
|
|
bootstrap은 normalized feature contribution만 수집한다.
|
|
|
|
### 4.2 normalized contribution
|
|
|
|
```ts
|
|
export interface InstalledContractContribution {
|
|
readonly featureId: string;
|
|
readonly source: ContractContributionSource;
|
|
readonly http: readonly InstalledHttpContract<unknown, unknown, unknown>[];
|
|
readonly events: readonly InstalledEventContract<unknown, unknown>[];
|
|
}
|
|
|
|
export type ContractContributionSource =
|
|
| Readonly<{
|
|
kind: "EXTERNAL_PACKAGE";
|
|
package: InstalledContractPackageIdentity;
|
|
}>
|
|
| Readonly<{
|
|
kind: "TEMPLATE_FIXTURE";
|
|
fixtureId: "REFERENCE_FEATURE_V1";
|
|
revision: 1;
|
|
}>;
|
|
|
|
export interface InstalledContractPackageIdentity {
|
|
readonly packageId: string;
|
|
readonly version: string;
|
|
readonly digest: `sha256:${string}`;
|
|
readonly runtimeProtocolVersion: 1;
|
|
readonly sourceRevision: string;
|
|
}
|
|
```
|
|
|
|
frontend interface는 package의 business model을 소유하지 않는다. descriptor와 runtime validator reference만 보관한다.
|
|
|
|
### 4.3 HTTP contribution
|
|
|
|
```ts
|
|
export interface InstalledHttpContract<Input, WireOutput, Problem> {
|
|
readonly contract: Readonly<{
|
|
operationId: string;
|
|
method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
|
|
pathTemplate: string;
|
|
inputValidator: RuntimeValidator<Input>;
|
|
outputValidator: RuntimeValidator<WireOutput>;
|
|
problemValidator: RuntimeValidator<Problem>;
|
|
acceptedStatuses: readonly number[];
|
|
emptyBodyStatuses: readonly number[];
|
|
retrySemantics: "SAFE" | "IDEMPOTENT" | "KEYED" | "NEVER";
|
|
requestBody: "NONE" | "JSON";
|
|
responseBody: "REQUIRED_JSON" | "OPTIONAL_JSON" | "NONE";
|
|
commandRecovery: CommandRecoveryDescriptor | null;
|
|
commandEffect: CommandEffectDescriptor<Problem> | null;
|
|
}>;
|
|
readonly frontend: HttpExecutionPolicy;
|
|
}
|
|
|
|
export interface HttpExecutionPolicy {
|
|
readonly policyId: string;
|
|
readonly requestByteLimit: number;
|
|
readonly responseByteLimit: number;
|
|
readonly totalDeadlineMs: number;
|
|
readonly retryBudget: 0 | 1 | 2;
|
|
readonly authProfileId: string;
|
|
readonly diagnosticsOperation: string;
|
|
}
|
|
```
|
|
|
|
`contract`는 package가 제공한다. frontend가 method/path/status/retry/effect 의미를 다시 적지 않는다.
|
|
|
|
`frontend`만 이 저장소가 소유한다. 값은 §7의 hard ceiling 안에 있어야 한다.
|
|
|
|
### 4.4 command recovery descriptor
|
|
|
|
frontend는 server semantics를 새로 설계하지 않고 package가 제공하는 recovery capability만 소비한다.
|
|
|
|
```ts
|
|
export type CommandRecoveryDescriptor = Readonly<{
|
|
mode: "IDEMPOTENCY_REPLAY" | "INSPECT_OPERATION";
|
|
operationIdentityField: string;
|
|
inspectOperationId?: string;
|
|
}>;
|
|
|
|
export interface CommandEffectDescriptor<Problem> {
|
|
readonly successEffect: "APPLIED_CONFIRMED";
|
|
classifyProblem(input: Readonly<{
|
|
status: number;
|
|
problem: Problem;
|
|
}>): "NOT_APPLIED" | "APPLIED_CONFIRMED" | "MAYBE_APPLIED";
|
|
classifyStatus?(status: 401 | 403 | 429): "NOT_APPLIED" | "MAYBE_APPLIED";
|
|
}
|
|
```
|
|
|
|
규칙:
|
|
|
|
- query/read operation은 `commandRecovery=null`, `commandEffect=null`이다;
|
|
- command operation은 `commandEffect`가 필수다;
|
|
- command operation에 `retrySemantics=KEYED`이면 `commandRecovery`도 필수다;
|
|
- descriptor가 없거나 invalid이면 automatic retry와 durable queue가 모두 금지된다;
|
|
- frontend는 inspect request/response wire shape나 problem effect meaning을 작성하지 않는다;
|
|
- `classifyProblem`은 package가 제공한 pure bounded classifier다;
|
|
- classifier가 throw/unknown을 반환하면 effect는 fail-safe `MAYBE_APPLIED`이고 contract runtime failure를 기록한다;
|
|
- 401·403·429는 본문을 읽기 전에 판정하므로 `classifyProblem`을 거치지 않는다. package가 `classifyStatus`를 주면 그 판정을 쓰고, 없거나 `NOT_APPLIED` 외 값·throw면 전송 뒤 `MAYBE_APPLIED`다(`src/adapters/http/http-effect-certainty.ts` `classifyStatusEffect`);
|
|
- `AUTH_REQUIRED`는 effect가 `MAYBE_APPLIED`여도 action이 `reauth`다(`src/contracts/errors.ts` `unknownEffectAction`);
|
|
- feature gateway가 package의 inspect operation을 application-safe outcome으로 mapping한다.
|
|
|
|
### 4.5 event contribution
|
|
|
|
```ts
|
|
export interface InstalledEventContract<Envelope, Payload> {
|
|
readonly eventType: string;
|
|
readonly envelopeValidator: RuntimeValidator<Envelope>;
|
|
readonly payloadValidator: RuntimeValidator<Payload>;
|
|
}
|
|
```
|
|
|
|
package identity는 enclosing `InstalledContractContribution.source`가 단 한 번 소유한다. HTTP와 event가 서로 다른 package identity라면 contribution을 둘로 나눈다.
|
|
|
|
connection, queue, dedupe, scope, recovery와 application effect는 frontend realtime contribution이 소유한다. generated package는 socket을 열거나 QueryClient를 참조하지 않는다.
|
|
|
|
### 4.6 runtime validator protocol
|
|
|
|
```ts
|
|
export interface RuntimeValidator<T> {
|
|
readonly schemaId: string;
|
|
safeParse(value: unknown):
|
|
| Readonly<{ success: true; data: T }>
|
|
| Readonly<{
|
|
success: false;
|
|
issues: readonly RuntimeValidationIssue[];
|
|
}>;
|
|
}
|
|
|
|
export interface RuntimeValidationIssue {
|
|
readonly path: readonly (string | number)[];
|
|
readonly code: string;
|
|
}
|
|
```
|
|
|
|
규칙:
|
|
|
|
- external response/event는 항상 `unknown`에서 시작한다;
|
|
- generated interface와 `as T`는 validator를 대체하지 않는다;
|
|
- validator throw는 `CONTRACT_RUNTIME_FAILURE`다;
|
|
- ordinary mismatch는 `CONTRACT_VALUE_INVALID`다;
|
|
- raw value, server detail, validator internals를 diagnostics에 넣지 않는다;
|
|
- 성공 값은 mapper 전에 caller-owned mutable reference로 재사용하지 않는다.
|
|
|
|
### 4.7 mapper ownership
|
|
|
|
```text
|
|
wire DTO
|
|
-> feature contract mapper
|
|
-> domain factory/application value
|
|
-> Query cache/UI
|
|
```
|
|
|
|
mapper MUST:
|
|
|
|
- feature가 소유한다;
|
|
- no-throw discriminated result를 반환한다;
|
|
- date/number/enum/null을 application canonical value로 변환한다;
|
|
- generated DTO를 Query cache에 직접 넣지 않는다;
|
|
- package metadata/header를 application value에 포함하지 않는다;
|
|
- collection count와 field bound를 mapper 단계에서도 확인한다.
|
|
|
|
```ts
|
|
export type MappingResult<T> =
|
|
| Readonly<{ ok: true; value: T }>
|
|
| Readonly<{
|
|
ok: false;
|
|
error: Readonly<{ kind: "MAPPING_CONTRACT_VIOLATION"; code: string }>;
|
|
}>;
|
|
```
|
|
|
|
### 4.8 installed contribution composer
|
|
|
|
```text
|
|
src/features/installed-contract-contributions.ts
|
|
```
|
|
|
|
```ts
|
|
export const INSTALLED_CONTRACT_CONTRIBUTIONS = Object.freeze([
|
|
REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION,
|
|
] as const);
|
|
```
|
|
|
|
reference fixture 규칙:
|
|
|
|
```text
|
|
featureId = reference-feature
|
|
source.kind = TEMPLATE_FIXTURE
|
|
fixtureId = REFERENCE_FEATURE_V1
|
|
revision = 1
|
|
events = []
|
|
```
|
|
|
|
`TEMPLATE_FIXTURE`는 current reference HTTP vertical을 deterministic test data로 유지하기 위한 유일한 예외다. product feature는 반드시 `EXTERNAL_PACKAGE`다. fixture는 `contractSet`에 포함하지 않는다.
|
|
|
|
### 4.9 composer exact validation
|
|
|
|
composition 전에 다음을 모두 검사한다.
|
|
|
|
```text
|
|
featureId:
|
|
^[a-z][a-z0-9-]{0,63}$
|
|
|
|
packageId:
|
|
^@[a-z0-9][a-z0-9._-]{0,62}/[a-z0-9][a-z0-9._-]{0,62}$
|
|
|
|
version:
|
|
exact SemVer
|
|
leading v 금지
|
|
range/tag/whitespace 금지
|
|
|
|
digest:
|
|
^sha256:[0-9a-f]{64}$
|
|
|
|
sourceRevision:
|
|
^[0-9a-f]{7,64}$
|
|
|
|
operationId:
|
|
^[A-Za-z][A-Za-z0-9_.-]{0,127}$
|
|
|
|
eventType:
|
|
UTF-8 <= 160 bytes
|
|
whitespace/control character 금지
|
|
|
|
pathTemplate:
|
|
startsWith /
|
|
UTF-8 <= 512 bytes
|
|
query/hash 금지
|
|
```
|
|
|
|
추가 검증:
|
|
|
|
- external runtime protocol version은 정확히 1;
|
|
- package ID별 정확히 한 version/digest;
|
|
- duplicate operation ID 없음;
|
|
- duplicate event type 없음;
|
|
- status는 100..599, 1..32개, sorted unique;
|
|
- empty-body status는 accepted status의 subset;
|
|
- validator와 non-empty `schemaId` 필수;
|
|
- request/response limit은 §7 hard ceiling 이하;
|
|
- same operation method/path/status projection drift 없음;
|
|
- fixture 외 local product contract 없음.
|
|
|
|
package identity 검증은 `EXTERNAL_PACKAGE`에만 적용한다. fixture에 가짜 digest를 부여하지 않는다.
|
|
|
|
### 4.10 package dependency 규칙
|
|
|
|
- `package.json`은 exact version만 사용한다;
|
|
- `latest`, caret, tilde, tag, Git URL, workspace link 금지;
|
|
- lockfile resolved integrity와 package export manifest가 존재해야 한다;
|
|
- runtime registry/Git/deployed docs에서 package를 보충하지 않는다;
|
|
- package root barrel 전체 import 금지;
|
|
- 사용 operation/event subpath만 정적 import한다;
|
|
- package import는 top-level network/DOM/listener side effect가 없어야 한다;
|
|
- package source와 generated output을 frontend에서 수정하지 않는다.
|
|
|
|
### 4.11 reference feature에서 product feature로의 migration
|
|
|
|
금지:
|
|
|
|
```text
|
|
copy reference-schemas.ts
|
|
edit URL/status/type
|
|
ship as product local contract
|
|
```
|
|
|
|
필수:
|
|
|
|
```text
|
|
external package pin
|
|
-> feature contribution adapter
|
|
-> feature mapper
|
|
-> feature gateway
|
|
-> application input
|
|
-> query/mutation/realtime bridge
|
|
```
|
|
|
|
reference fixture는 template 자체 제거 가능성 검증용이며 서비스 계약 authoring template가 아니다.
|
|
|
|
---
|
|
|
|
## 5. Contract Set과 release coherence
|
|
|
|
### 5.1 scalar 계약 version 제거
|
|
|
|
현재 다음 scalar는 여러 package를 표현할 수 없다.
|
|
|
|
```text
|
|
RuntimeConfig.API_CONTRACT_VERSION
|
|
ReleaseManifest.apiContractVersion
|
|
```
|
|
|
|
V2 전환 결과:
|
|
|
|
```text
|
|
Runtime Config
|
|
= deployment/browser operational setting
|
|
|
|
Release Manifest
|
|
= build/release/assets/compiled external contract package set
|
|
```
|
|
|
|
`RuntimeConfig`에서 API contract version을 제거한다.
|
|
|
|
### 5.2 Release Manifest V2
|
|
|
|
```ts
|
|
export interface ReleaseManifestV2 {
|
|
readonly schemaVersion: 2;
|
|
readonly appVersion: string;
|
|
readonly buildId: string;
|
|
readonly commitSha: string;
|
|
readonly configSchemaVersion: string;
|
|
readonly assetManifestHash: string;
|
|
readonly releaseId: string;
|
|
readonly builtAt: string;
|
|
readonly routeChunks: Readonly<Record<string, string>>;
|
|
readonly contractSet: Readonly<{
|
|
setAlgorithm: "CA_CONTRACT_SET_V1";
|
|
setDigest: `sha256:${string}`;
|
|
packages: readonly ContractSetPackage[];
|
|
}>;
|
|
}
|
|
|
|
export interface ContractSetPackage {
|
|
readonly packageId: string;
|
|
readonly version: string;
|
|
readonly digest: `sha256:${string}`;
|
|
readonly runtimeProtocolVersion: 1;
|
|
readonly sourceRevision: string;
|
|
}
|
|
```
|
|
|
|
fixture contribution은 `packages`에 들어가지 않는다.
|
|
|
|
### 5.3 canonicalization
|
|
|
|
단일 구현:
|
|
|
|
```text
|
|
src/contracts/contract-set-canonical.ts
|
|
```
|
|
|
|
```ts
|
|
export function canonicalizeContractSet(
|
|
packages: readonly ContractSetPackage[],
|
|
): Uint8Array;
|
|
```
|
|
|
|
algorithm:
|
|
|
|
```text
|
|
header = UTF-8("CA_FRONTEND_CONTRACT_SET_V1\0")
|
|
entries = packages sorted by UTF-8 byte lexicographic packageId
|
|
for each entry:
|
|
append u32be(length(packageId)) + packageId bytes
|
|
append u32be(length(version)) + version bytes
|
|
append u32be(length(digest)) + digest bytes
|
|
append u32be(runtimeProtocolVersion)
|
|
append u32be(length(sourceRevision)) + sourceRevision bytes
|
|
setDigest = lower-hex SHA-256(canonical bytes)
|
|
```
|
|
|
|
중복 package ID는 hash 전에 실패한다. JSON property order나 locale sort에 의존하지 않는다.
|
|
|
|
Node build script와 browser runtime은 canonical byte 생성 함수를 공유한다. hash adapter만 Node `crypto`와 Web Crypto로 분리한다.
|
|
|
|
### 5.4 build-time expected set
|
|
|
|
```text
|
|
INSTALLED_CONTRACT_CONTRIBUTIONS
|
|
-> EXTERNAL_PACKAGE identities only
|
|
-> canonicalize
|
|
-> setDigest
|
|
-> build manifest embed
|
|
```
|
|
|
|
`TEMPLATE_FIXTURE`는 filtering 후 set에 포함하지 않는다.
|
|
|
|
### 5.5 runtime check
|
|
|
|
boot에서 다음을 비교한다.
|
|
|
|
```text
|
|
embedded expected package list
|
|
manifest package list
|
|
embedded expected setDigest
|
|
manifest setDigest
|
|
recomputed manifest setDigest
|
|
runtime protocol version
|
|
```
|
|
|
|
모두 일치해야 한다. package range negotiation, deployed server docs와 `latest` lookup을 하지 않는다.
|
|
|
|
### 5.6 failure code
|
|
|
|
```text
|
|
CONTRACT_SET_SCHEMA_INVALID
|
|
CONTRACT_SET_ENTRY_INVALID
|
|
CONTRACT_SET_DUPLICATE_PACKAGE
|
|
CONTRACT_SET_DIGEST_INVALID
|
|
CONTRACT_SET_DIGEST_MISMATCH
|
|
CONTRACT_SET_PACKAGE_MISSING
|
|
CONTRACT_SET_PACKAGE_UNEXPECTED
|
|
CONTRACT_SET_VERSION_MISMATCH
|
|
CONTRACT_RUNTIME_PROTOCOL_UNSUPPORTED
|
|
```
|
|
|
|
이 failure는 product route mount 전 safe boot error다.
|
|
|
|
### 5.7 independent deployment 의미
|
|
|
|
frontend manifest는 **frontend build에 compile된 package set**을 검증한다. provider runtime version을 추측하거나 provider와 exact equality를 요구하지 않는다.
|
|
|
|
provider compatibility와 server support range는 별도 계약 시스템의 release responsibility다. frontend runtime은 build package set과 자신의 artifact coherence만 검증한다.
|
|
|
|
### 5.8 V1 migration
|
|
|
|
```text
|
|
Release 1
|
|
reader: V1 + V2
|
|
writer: V1
|
|
API_CONTRACT_VERSION 유지
|
|
|
|
Release 2
|
|
reader: V1 + V2
|
|
writer: V2
|
|
contractSet 생성
|
|
V1 input parser만 scalar를 읽음
|
|
V2 input에 scalar가 있으면 strict reject
|
|
|
|
Release 3
|
|
reader: V2
|
|
writer: V2
|
|
RuntimeConfig scalar reject as unknown field
|
|
V1 fixtures 제거
|
|
```
|
|
|
|
V1과 V2 값을 동시에 비교해 precedence를 만들지 않는다. V2 manifest에서 scalar가 추가로 존재하면 strict parser가 거절한다.
|
|
|
|
---
|
|
## 6. Runtime Config와 boot
|
|
|
|
### 6.1 Runtime Config V2
|
|
|
|
```ts
|
|
export const runtimeConfigV2Schema = z
|
|
.object({
|
|
APP_ENV: z.enum(["local", "development", "staging", "production"]),
|
|
API_BASE_URL: z.url(),
|
|
REQUEST_TIMEOUT_MS: z.int().min(100).max(60_000).default(10_000),
|
|
MAX_RETRY_ATTEMPTS: z.int().min(0).max(2).default(2),
|
|
TELEMETRY_ENABLED: z.boolean(),
|
|
TELEMETRY_ENDPOINT: z.url().optional(),
|
|
AUTH_MODE: z.enum(["external", "demo"]),
|
|
CONFIG_SCHEMA_VERSION: z.literal("2.0"),
|
|
RELEASE_MANIFEST_URL: z.string().min(1).default("/release-manifest.json"),
|
|
RELEASE_ID: z.string().min(1).optional(),
|
|
BUILD_ID: z.string().min(1).optional(),
|
|
CAPABILITY_OVERRIDES: z
|
|
.object({
|
|
REALTIME: z.enum(["DEFAULT", "DISABLED"]).default("DEFAULT"),
|
|
WEB_WORKER: z.enum(["DEFAULT", "DISABLED"]).default("DEFAULT"),
|
|
SERVICE_WORKER: z.enum(["DEFAULT", "DISABLED"]).default("DEFAULT"),
|
|
OFFLINE_COMMANDS: z.enum(["DEFAULT", "DISABLED"]).default("DEFAULT"),
|
|
})
|
|
.strict()
|
|
.default({}),
|
|
})
|
|
.strict();
|
|
```
|
|
|
|
`API_CONTRACT_VERSION`은 V2에 없다.
|
|
|
|
### 6.2 URL validation
|
|
|
|
`API_BASE_URL`:
|
|
|
|
- absolute URL;
|
|
- username/password/hash 없음;
|
|
- pathname은 `/`로 끝남;
|
|
- local/development 외 `https:`;
|
|
- query는 없음;
|
|
- canonical `new URL(value).href`를 runtime snapshot에 저장.
|
|
|
|
`TELEMETRY_ENDPOINT`:
|
|
|
|
- enabled일 때 필수;
|
|
- absolute URL;
|
|
- username/password/hash 없음;
|
|
- local/development 외 `https:`;
|
|
- API base와 같을 필요 없음.
|
|
|
|
`RELEASE_MANIFEST_URL`:
|
|
|
|
- same-origin absolute path;
|
|
- `/`로 시작;
|
|
- query/hash 없음;
|
|
- `//`, backslash, percent-encoded slash, dot segment 거절;
|
|
- maximum UTF-8 256 bytes.
|
|
|
|
### 6.3 config secret-name scan
|
|
|
|
기존 `assertSafeConfigNames`를 유지하고 다음 key fragment를 case-insensitive로 거절한다.
|
|
|
|
```text
|
|
PASSWORD
|
|
SECRET
|
|
TOKEN
|
|
PRIVATE_KEY
|
|
CLIENT_SECRET
|
|
ACCESS_KEY
|
|
REFRESH_TOKEN
|
|
COOKIE
|
|
AUTHORIZATION
|
|
```
|
|
|
|
`AUTH_MODE`, `TELEMETRY_ENABLED`처럼 fragment가 semantic enum인 known allowlist는 exact key allowlist로만 허용한다. arbitrary nested key에는 allowlist를 적용하지 않는다.
|
|
|
|
### 6.4 bounded boot body reader
|
|
|
|
공통 source:
|
|
|
|
```text
|
|
src/bootstrap/read-bounded-boot-json.ts
|
|
```
|
|
|
|
```ts
|
|
export interface BootJsonPolicy {
|
|
readonly operation: "RUNTIME_CONFIG" | "RELEASE_MANIFEST";
|
|
readonly maximumBytes: number;
|
|
readonly totalDeadlineMs: 5_000;
|
|
}
|
|
```
|
|
|
|
numeric policy:
|
|
|
|
```text
|
|
Runtime Config maximum = 65,536 bytes
|
|
Release Manifest maximum = 1,048,576 bytes
|
|
total deadline = 5,000 ms each
|
|
```
|
|
|
|
request options:
|
|
|
|
```ts
|
|
{
|
|
method: "GET",
|
|
cache: "no-store",
|
|
credentials: "same-origin",
|
|
redirect: "error",
|
|
referrerPolicy: "no-referrer",
|
|
headers: { Accept: "application/json" },
|
|
signal,
|
|
}
|
|
```
|
|
|
|
### 6.5 response admission
|
|
|
|
순서:
|
|
|
|
```text
|
|
fetch settled
|
|
-> status 200 only
|
|
-> content-type parse
|
|
-> application/json or +json only
|
|
-> Content-Length precheck when finite
|
|
-> ReadableStream bounded read
|
|
-> actual bytes <= policy maximum
|
|
-> UTF-8 fatal decode
|
|
-> JSON.parse
|
|
-> object shape check
|
|
-> Zod strict parse
|
|
-> deep snapshot
|
|
```
|
|
|
|
금지:
|
|
|
|
- `response.json()`;
|
|
- unbounded `response.text()`;
|
|
- redirect follow;
|
|
- HTML error page를 JSON으로 parse;
|
|
- `Content-Length`만 신뢰;
|
|
- timeout 후 body read continuation.
|
|
|
|
body overflow 시 reader를 cancel하고 `AbortController`를 abort한다.
|
|
|
|
### 6.6 boot failure union
|
|
|
|
```ts
|
|
export type BootLoadFailure =
|
|
| "FETCH_FAILED"
|
|
| "TIMEOUT"
|
|
| "HTTP_STATUS_INVALID"
|
|
| "CONTENT_TYPE_INVALID"
|
|
| "BODY_TOO_LARGE"
|
|
| "UTF8_INVALID"
|
|
| "JSON_INVALID"
|
|
| "SHAPE_INVALID"
|
|
| "SECRET_NAME_REJECTED"
|
|
| "SCHEMA_INVALID"
|
|
| "BUILD_MISMATCH"
|
|
| "RELEASE_MISMATCH"
|
|
| "ASSET_MISMATCH"
|
|
| "CONTRACT_SET_MISMATCH";
|
|
```
|
|
|
|
safe error는 다음만 포함한다.
|
|
|
|
```text
|
|
failure kind/code
|
|
buildId
|
|
releaseId if already validated
|
|
config schema version if safe
|
|
support reference = buildId + bounded failure code
|
|
```
|
|
|
|
URL, response body, validation value, endpoint hostname, stack trace를 포함하지 않는다.
|
|
|
|
### 6.7 boot order
|
|
|
|
```text
|
|
1. read embedded build config
|
|
2. load/validate Runtime Config V2
|
|
3. compare optional BUILD_ID
|
|
4. load/validate Release Manifest V2
|
|
5. verify build/config/release/assets
|
|
6. verify contractSet
|
|
7. compile static optional selection + runtime overrides
|
|
8. create diagnostics/telemetry no-op or selected sink
|
|
9. create auth/session adapter
|
|
10. create HTTP runtime
|
|
11. create application inputs/gateways
|
|
12. create QueryClient/scope/invalidation
|
|
13. create Router
|
|
14. create optional host objects without start side effect
|
|
15. mount React tree
|
|
16. committed effect starts optional runtime
|
|
```
|
|
|
|
### 6.8 partial composition rollback
|
|
|
|
각 step은 cleanup stack에 disposer를 push한다.
|
|
|
|
```text
|
|
create A -> push dispose A
|
|
create B -> push dispose B
|
|
create C fails
|
|
-> dispose B
|
|
-> dispose A
|
|
-> render safe boot error
|
|
```
|
|
|
|
cleanup은 reverse order이며 하나의 cleanup failure가 다음 cleanup을 막지 않는다. 모든 cleanup failure를 bounded count와 kind로 합산한다.
|
|
|
|
### 6.9 boot retry
|
|
|
|
safe boot shell의 retry action:
|
|
|
|
- 사용자의 explicit action만;
|
|
- 동일 page session에서 maximum 1회;
|
|
- 이전 attempt의 controller/resource settle 후 실행;
|
|
- 1초 minimum interval;
|
|
- retry 실패 후 automatic loop 없음;
|
|
- retry success 시 full product root를 새로 mount;
|
|
- partial composition object 재사용 금지.
|
|
|
|
### 6.10 Runtime Config immutability
|
|
|
|
validated config는 deep snapshot/freeze한다.
|
|
|
|
- runtime 중 config endpoint polling 없음;
|
|
- dynamic mutation 없음;
|
|
- kill switch 변경은 page reload/new boot에서만 적용;
|
|
- config object를 context로 노출하지 않음;
|
|
- application은 typed port를 통해 필요한 value만 본다.
|
|
|
|
---
|
|
|
|
## 7. Fetch HTTP execution runtime
|
|
|
|
### 7.1 source ownership
|
|
|
|
유지/수정:
|
|
|
|
```text
|
|
src/adapters/http/client.ts
|
|
src/adapters/http/request-builder.ts
|
|
src/adapters/http/bounded-json.ts
|
|
src/adapters/http/retry-policy.ts
|
|
```
|
|
|
|
신규:
|
|
|
|
```text
|
|
src/adapters/http/bounded-body-reader.ts
|
|
src/adapters/http/http-execution-v3.ts
|
|
src/adapters/http/http-effect-certainty.ts
|
|
src/adapters/http/http-contract-bridge.ts
|
|
```
|
|
|
|
범용 Axios-like API를 만들지 않는다. caller는 `InstalledHttpContract`와 typed input을 전달한다.
|
|
|
|
### 7.2 execution interface
|
|
|
|
```ts
|
|
export interface ContractHttpExecutor {
|
|
execute<Input, WireOutput, Problem>(
|
|
operation: InstalledHttpContract<Input, WireOutput, Problem>,
|
|
input: Input,
|
|
context: HttpExecutionContext,
|
|
): Promise<HttpExecutionOutcome<WireOutput, Problem>>;
|
|
}
|
|
|
|
export interface HttpExecutionContext {
|
|
readonly signal?: AbortSignal;
|
|
readonly scope: CacheScopeSnapshot;
|
|
readonly intent?: MutationIntentContext;
|
|
}
|
|
```
|
|
|
|
`MutationIntentContext`는 command에만 사용한다.
|
|
|
|
```ts
|
|
export interface MutationIntentContext {
|
|
readonly intentId: string;
|
|
readonly idempotencyKey?: string;
|
|
readonly startedBy: "USER" | "FOREGROUND_RETRY" | "OUTBOX_REPLAY";
|
|
}
|
|
```
|
|
|
|
### 7.3 hard ceilings
|
|
|
|
```text
|
|
default request body 262,144 bytes
|
|
hard request body 1,048,576 bytes
|
|
default success response 1,048,576 bytes
|
|
hard response body 8,388,608 bytes
|
|
problem response maximum 65,536 bytes
|
|
path template maximum 512 bytes
|
|
encoded query maximum 8,192 bytes
|
|
header value examined maximum 8,192 bytes per allowlisted header
|
|
total deadline default 10,000 ms
|
|
total deadline hard 60,000 ms
|
|
retry count hard 2
|
|
```
|
|
|
|
external contribution의 frontend policy는 default보다 작거나 같게 줄일 수 있다. hard ceiling을 초과할 수 없다.
|
|
|
|
### 7.4 input validation과 request projection
|
|
|
|
순서:
|
|
|
|
```text
|
|
capture scope
|
|
-> verify scope current
|
|
-> package input validator
|
|
-> feature/application input already canonical
|
|
-> request projection
|
|
-> encoded path/query/body byte check
|
|
-> credential patch
|
|
-> final invariant recheck
|
|
-> dispatch
|
|
```
|
|
|
|
final invariant recheck 항목:
|
|
|
|
- method unchanged;
|
|
- URL origin/path allowlist;
|
|
- redirect mode error;
|
|
- credentials mode expected;
|
|
- credential patch header allowlist;
|
|
- forbidden header 없음;
|
|
- body/request byte bound;
|
|
- abort/deadline not expired;
|
|
- scope still current.
|
|
|
|
final invariant failure면 fetch 호출은 0회다.
|
|
|
|
### 7.5 URL construction
|
|
|
|
- base는 validated `API_BASE_URL`;
|
|
- path placeholder는 descriptor의 named input projection만 사용;
|
|
- segment는 `encodeURIComponent` semantics로 한 번만 encode;
|
|
- raw slash를 path value에 허용하지 않음;
|
|
- query key order는 descriptor-generated order;
|
|
- array encoding은 package descriptor가 제공한 exact projection;
|
|
- `undefined` omit, `null`은 descriptor가 허용한 representation만;
|
|
- URL string concatenation 금지;
|
|
- absolute path override, origin override 금지;
|
|
- final URL maximum 16,384 bytes.
|
|
|
|
### 7.6 request body
|
|
|
|
`requestBody=NONE`이면 body와 Content-Type 모두 없다.
|
|
|
|
`requestBody=JSON`이면:
|
|
|
|
```text
|
|
package request projection
|
|
-> deterministic JSON encoder
|
|
-> UTF-8 bytes
|
|
-> requestByteLimit check
|
|
-> Content-Type application/json
|
|
```
|
|
|
|
`JSON.stringify`의 default property enumeration에 semantic digest를 의존하지 않는다. idempotency request digest가 필요하면 package가 canonical request digest projection을 제공한다.
|
|
|
|
### 7.7 credential bridge
|
|
|
|
```ts
|
|
export type CredentialPatchOutcome =
|
|
| Readonly<{
|
|
kind: "READY";
|
|
headers: Readonly<Record<string, string>>;
|
|
credentials: RequestCredentials;
|
|
}>
|
|
| Readonly<{ kind: "UNAUTHENTICATED" }>
|
|
| Readonly<{ kind: "UNAVAILABLE" }>
|
|
| Readonly<{ kind: "SCOPE_FENCED" }>;
|
|
```
|
|
|
|
허용 header:
|
|
|
|
```text
|
|
Authorization
|
|
X-CSRF-Token
|
|
X-Tenant-Context
|
|
```
|
|
|
|
실제 profile이 쓰는 subset만 등록한다. caller가 arbitrary header를 추가하지 않는다.
|
|
|
|
credential unavailable에서 anonymous request로 downgrade하지 않는다.
|
|
|
|
### 7.8 physical attempt state
|
|
|
|
```ts
|
|
export type PhysicalAttemptState =
|
|
| "PREPARING"
|
|
| "READY_TO_SEND"
|
|
| "DISPATCHED"
|
|
| "RESPONSE_HEADERS"
|
|
| "READING_BODY"
|
|
| "VALIDATING"
|
|
| "MAPPING_READY"
|
|
| "SETTLED";
|
|
```
|
|
|
|
`fetch()` invocation 직전에 `DISPATCHED`로 바꾸지 않는다. invocation expression에 들어가기 직전 local state를 `READY_TO_SEND`, promise가 반환된 직후 `DISPATCHED`로 기록한다. synchronous throw는 `NOT_STARTED`다.
|
|
|
|
### 7.9 response admission
|
|
|
|
순서:
|
|
|
|
```text
|
|
redirected=false
|
|
-> status package allowlist
|
|
-> content-type policy
|
|
-> Content-Length precheck
|
|
-> bounded stream read
|
|
-> empty-body policy
|
|
-> UTF-8/JSON parse when required
|
|
-> problem or success validator
|
|
-> scope current fence
|
|
-> typed outcome
|
|
```
|
|
|
|
`response.ok`만 사용하지 않는다.
|
|
|
|
### 7.10 body policy
|
|
|
|
`REQUIRED_JSON`:
|
|
|
|
- allowed success status에서 non-empty body 필수;
|
|
- JSON media 필수;
|
|
- empty/whitespace는 contract violation.
|
|
|
|
`OPTIONAL_JSON`:
|
|
|
|
- empty-body status 또는 zero body 허용;
|
|
- body가 있으면 JSON media/validator 필수;
|
|
- body 없는 값을 `undefined`로 명시적으로 mapping.
|
|
|
|
`NONE`:
|
|
|
|
- body를 application value로 읽지 않음;
|
|
- `Content-Length > 0`이면 즉시 violation + body cancel;
|
|
- length가 없고 body stream이 있으면 최대 1 byte만 probe한다;
|
|
- 첫 chunk가 있으면 violation + reader cancel;
|
|
- immediately done이면 empty success;
|
|
- descriptor가 unexpected body를 허용하지 않으므로 arbitrary drain하지 않는다.
|
|
|
|
### 7.11 typed outcome
|
|
|
|
```ts
|
|
export type HttpExecutionOutcome<Value, Problem> =
|
|
| Readonly<{
|
|
kind: "SUCCESS";
|
|
value: Value;
|
|
metadata: SafeResponseMetadata;
|
|
effect: "NOT_APPLICABLE" | "APPLIED_CONFIRMED";
|
|
}>
|
|
| Readonly<{
|
|
kind: "PROBLEM";
|
|
problem: Problem;
|
|
metadata: SafeResponseMetadata;
|
|
effect: "NOT_APPLIED" | "APPLIED_CONFIRMED" | "MAYBE_APPLIED";
|
|
}>
|
|
| Readonly<{
|
|
kind: "UNAUTHENTICATED";
|
|
effect: "NOT_APPLICABLE" | "NOT_APPLIED" | "MAYBE_APPLIED";
|
|
}>
|
|
| Readonly<{
|
|
kind: "FORBIDDEN";
|
|
effect: "NOT_APPLICABLE" | "NOT_APPLIED" | "MAYBE_APPLIED";
|
|
}>
|
|
| Readonly<{
|
|
kind: "RATE_LIMITED";
|
|
retryAfterMs?: number;
|
|
effect: "NOT_APPLICABLE" | "NOT_APPLIED" | "MAYBE_APPLIED";
|
|
}>
|
|
| Readonly<{
|
|
kind: "CONTRACT_VIOLATION";
|
|
violation: HttpContractViolation;
|
|
}>
|
|
| Readonly<{
|
|
kind: "TRANSPORT_FAILURE";
|
|
failure: HttpTransportFailure;
|
|
effect: "NOT_STARTED" | "MAYBE_APPLIED";
|
|
}>
|
|
| Readonly<{
|
|
kind: "CANCELLED";
|
|
effect: "NOT_STARTED" | "MAYBE_APPLIED";
|
|
}>;
|
|
```
|
|
|
|
### 7.12 safe response metadata
|
|
|
|
```ts
|
|
export interface SafeResponseMetadata {
|
|
readonly status: number;
|
|
readonly correlationReference?: string;
|
|
readonly retryAfterMs?: number;
|
|
readonly validatorToken?: string;
|
|
}
|
|
```
|
|
|
|
metadata에 raw header map, URL, server, cookie, traceparent, ETag raw value를 노출하지 않는다. validator token은 conditional validator store 내부 opaque binding이며 UI/application에 직접 전달하지 않는다.
|
|
|
|
### 7.13 contract violation
|
|
|
|
```text
|
|
UNEXPECTED_STATUS
|
|
UNEXPECTED_EMPTY_BODY
|
|
UNEXPECTED_BODY
|
|
CONTENT_TYPE_MISMATCH
|
|
RESPONSE_TOO_LARGE
|
|
UTF8_INVALID
|
|
JSON_INVALID
|
|
SUCCESS_SCHEMA_INVALID
|
|
PROBLEM_SCHEMA_INVALID
|
|
VALIDATOR_RUNTIME_FAILURE
|
|
MAPPING_CONTRACT_VIOLATION
|
|
FINAL_REQUEST_INVARIANT_FAILED
|
|
SCOPE_FENCED
|
|
```
|
|
|
|
```ts
|
|
export type HttpContractViolation = Readonly<{
|
|
kind:
|
|
| "UNEXPECTED_STATUS"
|
|
| "UNEXPECTED_EMPTY_BODY"
|
|
| "UNEXPECTED_BODY"
|
|
| "CONTENT_TYPE_MISMATCH"
|
|
| "RESPONSE_TOO_LARGE"
|
|
| "UTF8_INVALID"
|
|
| "JSON_INVALID"
|
|
| "SUCCESS_SCHEMA_INVALID"
|
|
| "PROBLEM_SCHEMA_INVALID"
|
|
| "VALIDATOR_RUNTIME_FAILURE"
|
|
| "MAPPING_CONTRACT_VIOLATION"
|
|
| "FINAL_REQUEST_INVARIANT_FAILED"
|
|
| "SCOPE_FENCED";
|
|
operation: "REQUEST" | "RESPONSE" | "VALIDATION" | "MAPPING";
|
|
}>;
|
|
```
|
|
|
|
contract violation은 ordinary network retry 대상이 아니다.
|
|
|
|
### 7.14 transport failure
|
|
|
|
```text
|
|
DNS_OR_CONNECT_FAILURE
|
|
TLS_OR_NETWORK_FAILURE
|
|
TIMEOUT
|
|
RESPONSE_STREAM_FAILURE
|
|
ABORTED_BY_SCOPE
|
|
ABORTED_BY_CALLER
|
|
OVERLOADED_BEFORE_SEND
|
|
```
|
|
|
|
```ts
|
|
export type HttpTransportFailure = Readonly<{
|
|
kind:
|
|
| "DNS_OR_CONNECT_FAILURE"
|
|
| "TLS_OR_NETWORK_FAILURE"
|
|
| "NETWORK_FAILURE"
|
|
| "TIMEOUT"
|
|
| "RESPONSE_STREAM_FAILURE"
|
|
| "ABORTED_BY_SCOPE"
|
|
| "ABORTED_BY_CALLER"
|
|
| "OVERLOADED_BEFORE_SEND";
|
|
retryable: boolean;
|
|
}>;
|
|
```
|
|
|
|
browser가 세부 네트워크 원인을 제공하지 않으면 하나의 `NETWORK_FAILURE` bucket으로 축약한다. native exception message를 boundary 밖으로 내보내지 않는다.
|
|
|
|
---
|
|
|
|
## 8. Retry·cancellation·mutation effect certainty
|
|
|
|
### 8.1 retry owner
|
|
|
|
```text
|
|
HTTP transport retry = enabled by exact operation policy
|
|
TanStack Query retry = false
|
|
TanStack Mutation retry = false
|
|
realtime reconnect = realtime coordinator
|
|
Background Sync retry = offline drain state machine
|
|
```
|
|
|
|
서로 다른 계층이 같은 physical operation을 중복 retry하지 않는다.
|
|
|
|
### 8.2 HTTP retry algorithm
|
|
|
|
```text
|
|
base delay = 250 ms
|
|
max local delay = 2,000 ms
|
|
algorithm = full jitter
|
|
maximum retries = min(operation.retryBudget, RuntimeConfig.MAX_RETRY_ATTEMPTS, 2)
|
|
```
|
|
|
|
retry index 0의 ceiling:
|
|
|
|
```text
|
|
min(2,000, 250 * 2^0) = 250 ms
|
|
```
|
|
|
|
실제 delay:
|
|
|
|
```text
|
|
floor(random[0,1) * ceiling)
|
|
```
|
|
|
|
validated `Retry-After`가 있으면 local delay의 lower bound로 사용한다. 5,000ms를 넘거나 remaining total deadline을 넘으면 retry하지 않는다.
|
|
|
|
### 8.3 retry classification
|
|
|
|
`SAFE`:
|
|
|
|
- GET/HEAD;
|
|
- network failure after dispatch 허용;
|
|
- 408, 425, 429, 502, 503, 504 중 accepted retry policy;
|
|
- same frozen request 사용.
|
|
|
|
`IDEMPOTENT`:
|
|
|
|
- package가 operation 자체 idempotent라고 선언;
|
|
- same frozen request;
|
|
- SAFE와 같은 failure/status subset.
|
|
|
|
`KEYED`:
|
|
|
|
- same user intent의 동일 idempotency key 필수;
|
|
- known response status가 retry 가능하다고 package가 명시한 경우만;
|
|
- dispatch 후 response 없는 network/timeout/abort는 automatic retry 금지;
|
|
- inspect/reconciliation path로 이동.
|
|
|
|
`NEVER`:
|
|
|
|
- automatic retry 0.
|
|
|
|
### 8.4 auth retry
|
|
|
|
401 response 뒤 hidden refresh-and-replay를 하지 않는다.
|
|
|
|
- credential owner는 **send 전** READY/UNAUTHENTICATED/UNAVAILABLE을 결정한다;
|
|
- response 401은 terminal `UNAUTHENTICATED`;
|
|
- 사용자 re-auth 뒤 새 user intent 또는 explicit retry로 실행;
|
|
- command를 새 credential로 자동 replay하지 않는다.
|
|
|
|
### 8.5 deadline
|
|
|
|
one logical operation deadline은 다음 전체를 포함한다.
|
|
|
|
```text
|
|
credential resolution
|
|
request encode
|
|
retry backoff
|
|
all physical attempts
|
|
response read
|
|
runtime validation
|
|
mapper preparation
|
|
```
|
|
|
|
operation start에서 monotonic deadline을 capture한다. 각 sub-step이 remaining budget을 받는다. physical attempt별로 full timeout을 새로 부여하지 않는다.
|
|
|
|
### 8.6 cancellation sources
|
|
|
|
```ts
|
|
export type CancellationOwner =
|
|
| "CALLER"
|
|
| "ROUTE_TRANSITION"
|
|
| "SCOPE_FENCE"
|
|
| "APPLICATION_SHUTDOWN"
|
|
| "DEADLINE";
|
|
```
|
|
|
|
linked AbortController는 first reason만 terminal reason으로 저장한다. later reason은 diagnostics count에만 반영한다.
|
|
|
|
### 8.7 mutation effect certainty
|
|
|
|
```ts
|
|
export type MutationEffectCertainty =
|
|
| "NOT_STARTED"
|
|
| "NOT_APPLIED"
|
|
| "MAYBE_APPLIED"
|
|
| "APPLIED_CONFIRMED";
|
|
```
|
|
|
|
판정:
|
|
|
|
| 관측 | certainty |
|
|
| --- | --- |
|
|
| validation/config/auth/final invariant에서 종료 | `NOT_STARTED` |
|
|
| fetch synchronous throw | `NOT_STARTED` |
|
|
| package가 no-effect problem/status로 명시 | `NOT_APPLIED` |
|
|
| success/committed receipt | `APPLIED_CONFIRMED` |
|
|
| dispatch 후 timeout/network/abort/body loss | `MAYBE_APPLIED` |
|
|
| unknown/unclassified problem | `MAYBE_APPLIED` |
|
|
|
|
frontend가 HTTP status만 보고 `NOT_APPLIED`를 추측하지 않는다.
|
|
|
|
### 8.8 mutation intent identity
|
|
|
|
```ts
|
|
export interface MutationIntent {
|
|
readonly intentId: string;
|
|
readonly operationId: string;
|
|
readonly canonicalInputIdentity: string;
|
|
readonly idempotencyKey?: string;
|
|
readonly createdAtMonotonicMs: number;
|
|
}
|
|
```
|
|
|
|
- `intentId`: `crypto.randomUUID()`;
|
|
- 같은 submit의 transport retry/reconcile에는 동일 intent/key;
|
|
- form value가 변경되면 새 intent;
|
|
- double click은 duplicate coordinator가 처리;
|
|
- key/identity를 log/URL/query key에 넣지 않는다.
|
|
|
|
### 8.9 uncertain outcome handling
|
|
|
|
`MAYBE_APPLIED`면:
|
|
|
|
```text
|
|
1. automatic resend 금지
|
|
2. optimistic layer를 arbitrary rollback하지 않음
|
|
3. mutation coordinator state = EFFECT_UNKNOWN
|
|
4. package recovery descriptor 확인
|
|
5. inspect operation이 있으면 bounded inspect
|
|
6. committed -> canonical result 적용
|
|
7. no effect -> explicit user retry 허용
|
|
8. unknown 유지 -> status UI/support path
|
|
```
|
|
|
|
inspect도 timeout이면 unknown을 유지한다.
|
|
|
|
### 8.10 UI projection
|
|
|
|
```text
|
|
NOT_STARTED -> ordinary retry 가능
|
|
NOT_APPLIED -> policy상 retry 가능
|
|
MAYBE_APPLIED -> "처리 상태 확인 필요"
|
|
APPLIED_CONFIRMED-> success
|
|
```
|
|
|
|
사용자 문구는 i18n catalog가 소유한다. native error와 server detail을 표시하지 않는다.
|
|
|
|
---
|
|
|
|
## 9. Router
|
|
|
|
### 9.1 ownership
|
|
|
|
Router owns:
|
|
|
|
```text
|
|
route registry
|
|
path/search codec
|
|
navigation
|
|
redirect
|
|
lazy module lifecycle
|
|
route error boundary
|
|
focus/scroll/title
|
|
dirty navigation guard
|
|
session/access hint guard
|
|
```
|
|
|
|
Router does not own:
|
|
|
|
```text
|
|
server data cache
|
|
HTTP retry
|
|
mutation lifecycle
|
|
realtime connection
|
|
business authorization
|
|
contract package loading
|
|
```
|
|
|
|
### 9.2 server-data loader/action 금지
|
|
|
|
baseline에서 loader/action은 server fetch를 수행하지 않는다.
|
|
|
|
허용 loader:
|
|
|
|
- URL/path/search parse;
|
|
- local route registration lookup;
|
|
- synchronous redirect;
|
|
- session snapshot 기반 access hint;
|
|
- route-local static metadata.
|
|
|
|
금지:
|
|
|
|
- direct fetch;
|
|
- gateway call;
|
|
- QueryClient prefetch/ensure;
|
|
- IndexedDB read;
|
|
- mutation action;
|
|
- separate loader cache.
|
|
|
|
서버 data는 page의 feature query/mutation hook이 application input을 호출해 가져온다.
|
|
|
|
### 9.3 route registration
|
|
|
|
```ts
|
|
export interface InstalledRouteContribution {
|
|
readonly routeId: string;
|
|
readonly path: string;
|
|
readonly ownerFeatureId: string;
|
|
readonly load: () => Promise<RouteRuntimeModule>;
|
|
readonly inputCodecId: string;
|
|
readonly accessPolicyId: string;
|
|
}
|
|
```
|
|
|
|
- route ID: existing registry format 유지;
|
|
- duplicate route ID/path 거절;
|
|
- feature page가 app-router를 import하지 않음;
|
|
- lazy module은 route runtime module만 export;
|
|
- Router가 feature gateway/adapter를 props로 전달하지 않음.
|
|
|
|
### 9.4 URL codec
|
|
|
|
path/search raw input은 `unknown`이다.
|
|
|
|
```text
|
|
URLSearchParams
|
|
-> registered route codec
|
|
-> normalized route input
|
|
-> RouteInputProvider
|
|
-> page/controller
|
|
```
|
|
|
|
- `Object.fromEntries(searchParams)` raw trust 금지;
|
|
- duplicate query key policy를 codec이 명시;
|
|
- unknown key는 default reject;
|
|
- array/count/string byte bound;
|
|
- route param은 domain ID factory 전까지 string;
|
|
- malformed input은 safe bad-request route surface;
|
|
- network/application gateway call 0.
|
|
|
|
### 9.5 route transition cleanup
|
|
|
|
feature page unmount 순서:
|
|
|
|
```text
|
|
1. Query observer release
|
|
2. feature realtime subscription lease release
|
|
3. page browser listener cleanup
|
|
4. form/dirty guard cleanup
|
|
5. object URL/temporary file lease cleanup
|
|
6. page-owned abort controller abort
|
|
```
|
|
|
|
다음 global runtime은 유지한다.
|
|
|
|
```text
|
|
QueryClient
|
|
scope runtime
|
|
cross-context coordinator
|
|
realtime host
|
|
Service Worker registration
|
|
offline repository
|
|
```
|
|
|
|
### 9.6 chunk recovery
|
|
|
|
```text
|
|
chunk load failure
|
|
-> no-store Release Manifest V2 refresh
|
|
-> build/release/asset/contractSet compare
|
|
-> dirty state inspect
|
|
-> one guarded reload
|
|
-> second failure terminal safe surface
|
|
```
|
|
|
|
reload guard key:
|
|
|
|
```text
|
|
CHUNK_RELOAD_GUARD = oldBuildId + newBuildId + failedRouteId
|
|
```
|
|
|
|
동일 pair/route당 한 번만 reload한다. localStorage record는 10분 TTL과 512-byte hard cap을 갖는다.
|
|
|
|
### 9.7 focus/scroll/title
|
|
|
|
- successful route commit 후 `main-content` focus;
|
|
- navigation마다 scroll top;
|
|
- explicit registered hash-anchor route만 anchor focus;
|
|
- document title은 typed message catalog;
|
|
- background Query refresh는 focus/scroll을 변경하지 않음;
|
|
- reduced motion 존중;
|
|
- error route도 heading focus를 제공.
|
|
|
|
### 9.8 navigation blocker
|
|
|
|
blocking 조건:
|
|
|
|
```text
|
|
dirty form
|
|
active non-cancellable local file workflow
|
|
mutation EFFECT_UNKNOWN recovery in progress
|
|
offline command conflict resolution draft
|
|
```
|
|
|
|
ordinary loading/query refresh는 navigation을 막지 않는다.
|
|
|
|
browser unload dialog는 browser standard prompt만 사용한다. custom string에 의존하지 않는다.
|
|
|
|
---
|
|
|
|
## 10. Query lifecycle과 cache
|
|
|
|
### 10.1 QueryClient 수와 기본 정책
|
|
|
|
application runtime당 QueryClient 하나다.
|
|
|
|
```ts
|
|
export const QUERY_CACHE_DEFAULTS = Object.freeze({
|
|
staleTime: 30_000,
|
|
gcTime: 300_000,
|
|
refetchOnWindowFocus: true,
|
|
retry: false,
|
|
mutationRetry: false,
|
|
persistence: false,
|
|
});
|
|
```
|
|
|
|
route/feature/session마다 새 QueryClient를 만들지 않는다.
|
|
|
|
### 10.2 fixed server-state profiles
|
|
|
|
```ts
|
|
export type ServerStateProfileId =
|
|
| "DETAIL_STANDARD"
|
|
| "LIST_STANDARD"
|
|
| "LOOKUP_STABLE"
|
|
| "VOLATILE_STATUS";
|
|
|
|
export interface ServerStateProfile {
|
|
readonly profileId: ServerStateProfileId;
|
|
readonly staleTimeMs: number;
|
|
readonly gcTimeMs: number;
|
|
readonly refetchOnWindowFocus: boolean;
|
|
readonly maxResultItems: number;
|
|
readonly maxEstimatedResultBytes: number;
|
|
}
|
|
```
|
|
|
|
```text
|
|
DETAIL_STANDARD
|
|
stale 30s, gc 5m, focus true, items 1, bytes 256KiB
|
|
|
|
LIST_STANDARD
|
|
stale 15s, gc 5m, focus true, items 200, bytes 1MiB
|
|
|
|
LOOKUP_STABLE
|
|
stale 5m, gc 30m, focus false, items 500, bytes 2MiB
|
|
|
|
VOLATILE_STATUS
|
|
stale 0, gc 1m, focus true, items 1, bytes 64KiB
|
|
```
|
|
|
|
feature가 임의 숫자를 선언하지 않는다. 네 profile로 표현할 수 없으면 본 문서와 profile registry를 개정한다.
|
|
|
|
### 10.3 query definition
|
|
|
|
```ts
|
|
export interface QueryDefinition<Input, Value> {
|
|
readonly definitionId: string;
|
|
readonly definitionVersion: number;
|
|
readonly owner: string;
|
|
readonly namespace: string;
|
|
readonly namespaceVersion: number;
|
|
readonly operationId: string;
|
|
readonly profileId: ServerStateProfileId;
|
|
measureResult(value: Value): QueryResultMeasure;
|
|
execute(
|
|
input: Input,
|
|
context: Readonly<{ signal: AbortSignal }>,
|
|
): Promise<Result<Value>>;
|
|
}
|
|
|
|
export interface QueryResultMeasure {
|
|
readonly itemCount: number;
|
|
readonly estimatedBytes: number;
|
|
}
|
|
```
|
|
|
|
### 10.4 result measurement
|
|
|
|
`measureResult`는 모든 definition에 필수다.
|
|
|
|
- detail/scalar: item 1;
|
|
- empty optional: item 0;
|
|
- list/page: actual mapped items;
|
|
- bytes: mapped application value의 bounded string UTF-8 bytes + primitive fixed width + collection overhead;
|
|
- `JSON.stringify` fallback 금지;
|
|
- wire DTO 재직렬화 금지;
|
|
- generic recursive walker 금지;
|
|
- throw/non-finite/negative/unsafe integer는 `RESULT_MEASUREMENT_FAILED`;
|
|
- ceiling 초과는 `RESULT_BUDGET_EXCEEDED`;
|
|
- measurement failure/overflow는 cache commit 0, retry 0.
|
|
|
|
### 10.5 client scope authority
|
|
|
|
현재 `ServerStateScopeRuntime`을 browser client scope authority로 확장한다.
|
|
|
|
```ts
|
|
export type ClientScopeLifecycleEvent =
|
|
| Readonly<{ kind: "FENCED"; previousGeneration: number }>
|
|
| Readonly<{ kind: "READY"; snapshot: CacheScopeSnapshot }>
|
|
| Readonly<{ kind: "DISPOSED" }>;
|
|
|
|
export interface ServerStateScopeRuntime {
|
|
getSnapshot(): CacheScopeSnapshot;
|
|
subscribe(listener: () => void): () => void;
|
|
subscribeLifecycle(
|
|
listener: (event: ClientScopeLifecycleEvent) => void,
|
|
): () => void;
|
|
dispose(): void;
|
|
}
|
|
```
|
|
|
|
### 10.6 scope transition exact order
|
|
|
|
identity-affecting session change:
|
|
|
|
```text
|
|
1. generation increment
|
|
2. old snapshot isCurrent=false
|
|
3. FENCED synchronously publish
|
|
4. new HTTP/realtime/offline admission close
|
|
5. active Query cancel
|
|
6. QueryClient clear
|
|
7. conditional validator clear
|
|
8. mutation/invalidation pending lease clear
|
|
9. realtime stop/checkpoint detach
|
|
10. offline drain lease release and old partition hide
|
|
11. old identity registry close
|
|
12. new fingerprint/identity registry create
|
|
13. READY publish
|
|
14. React subscriber notify
|
|
15. new scope admission open
|
|
```
|
|
|
|
`FENCED`와 `READY` 사이 old value를 render하지 않는다. UI는 `scope-transition` state를 사용한다.
|
|
|
|
### 10.7 query key
|
|
|
|
```text
|
|
[
|
|
"query",
|
|
1,
|
|
scopeFingerprint,
|
|
namespace,
|
|
namespaceVersion,
|
|
definitionVersion,
|
|
runtimeIdentityToken
|
|
]
|
|
```
|
|
|
|
raw account/resource ID, URL, filter object, document, cursor, message를 key에 넣지 않는다.
|
|
|
|
runtime identity registry bounds:
|
|
|
|
```text
|
|
max depth 12
|
|
max nodes 512
|
|
max string bytes 2,048
|
|
max encoded bytes 16,384
|
|
entries 4,096
|
|
canonical bytes 4 MiB
|
|
```
|
|
|
|
active reference가 있는 identity를 evict하지 않는다. capacity 부족은 network 전 local failure다.
|
|
|
|
### 10.8 execution commit fence
|
|
|
|
```text
|
|
capture scope
|
|
-> acquire identity lease
|
|
-> execute application input with TanStack signal
|
|
-> scope current check
|
|
-> Result success check
|
|
-> measureResult
|
|
-> profile budget check
|
|
-> immutable value return
|
|
-> Query cache commit
|
|
-> finally identity release
|
|
```
|
|
|
|
scope가 stale면 successful response도 `SCOPE_FENCED`로 폐기한다.
|
|
|
|
### 10.9 UI states
|
|
|
|
```text
|
|
initial-loading
|
|
success-fresh
|
|
success-refreshing
|
|
success-stale-degraded
|
|
empty
|
|
known-problem
|
|
transport-error
|
|
contract-error
|
|
scope-transition
|
|
```
|
|
|
|
background refresh에서 complete data를 full-page skeleton으로 숨기지 않는다.
|
|
|
|
### 10.10 persistence
|
|
|
|
baseline:
|
|
|
|
```text
|
|
memory QueryClient = COMPOSED
|
|
query persistence = disabled
|
|
SSR hydration = NOT_SELECTED
|
|
```
|
|
|
|
Web Storage나 existing generic IndexedDB runtime에 Query payload를 자동 저장하지 않는다. persistence 요구는 VD-13 별도 selection을 통과해야 한다.
|
|
|
|
### 10.11 conditional validator
|
|
|
|
conditional validator store는 Query value와 분리한다.
|
|
|
|
- exact operation/representation/scope/release binding;
|
|
- max entries 1,024;
|
|
- max token bytes 1,024;
|
|
- LRU zero-ref eviction;
|
|
- session transition clear;
|
|
- 304는 current complete cached value가 있을 때만 success;
|
|
- cache miss + 304는 contract/recovery failure;
|
|
- raw ETag를 Query key/UI/log에 넣지 않음.
|
|
|
|
---
|
|
|
|
## 11. Mutation lifecycle
|
|
|
|
### 11.1 mutation definition
|
|
|
|
```ts
|
|
export interface MutationDefinition<Input, Value> {
|
|
readonly definitionId: string;
|
|
readonly operationId: string;
|
|
readonly duplicatePolicy:
|
|
| "JOIN_IDENTICAL"
|
|
| "REJECT_WHILE_ACTIVE"
|
|
| "ALLOW_PARALLEL";
|
|
readonly optimisticPolicyId: "NONE" | string;
|
|
readonly invalidationTopics: readonly string[];
|
|
canonicalIdentity(input: Input): string;
|
|
execute(
|
|
input: Input,
|
|
context: Readonly<{
|
|
signal: AbortSignal;
|
|
intent: MutationIntent;
|
|
}>,
|
|
): Promise<MutationResult<Value>>;
|
|
}
|
|
|
|
export type MutationResult<Value> =
|
|
| Readonly<{
|
|
ok: true;
|
|
value: Value;
|
|
effect: "APPLIED_CONFIRMED";
|
|
}>
|
|
| Readonly<{
|
|
ok: false;
|
|
failure: AppFailure;
|
|
effect: "NOT_STARTED" | "NOT_APPLIED" | "MAYBE_APPLIED";
|
|
}>;
|
|
```
|
|
|
|
### 11.2 duplicate policy defaults
|
|
|
|
```text
|
|
command default = REJECT_WHILE_ACTIVE
|
|
query-like idempotent action = JOIN_IDENTICAL only when exact semantic input identity is stable
|
|
ALLOW_PARALLEL = explicit feature decision only
|
|
```
|
|
|
|
`JOIN_IDENTICAL`은 같은 scope, definition, canonical input과 same user intent에서만 가능하다. 서로 다른 input을 logical key 하나로 합치지 않는다.
|
|
|
|
### 11.3 duplicate coordinator bounds
|
|
|
|
```text
|
|
active definitions per runtime = 256
|
|
active intents total = 1,024
|
|
canonical identity bytes = 16,384
|
|
waiters per joined intent = 32
|
|
settled retention = 0 ms; immediate removal
|
|
```
|
|
|
|
coordinator map을 result cache로 사용하지 않는다.
|
|
|
|
### 11.4 optimistic default
|
|
|
|
`optimisticPolicyId=NONE`이 기본이다.
|
|
|
|
optimistic update 허용 조건:
|
|
|
|
- deterministic local projection;
|
|
- rollback snapshot bounded;
|
|
- server revision/canonical response가 최종 authority;
|
|
- list membership/sort/filter effect가 deterministic;
|
|
- effect unknown recovery가 정의됨;
|
|
- same query key layer order가 관리됨.
|
|
|
|
### 11.5 ordered optimistic layer
|
|
|
|
```text
|
|
layers per query key <= 8
|
|
single layer estimate <= 262,144 bytes
|
|
all layers per query key <= 2,097,152 bytes
|
|
layer age <= mutation total deadline + 60s
|
|
```
|
|
|
|
overflow면 pessimistic execution으로 전환한다. 기존 layer를 silent evict하지 않는다.
|
|
|
|
### 11.6 result ordering
|
|
|
|
success:
|
|
|
|
```text
|
|
1. external wire validation
|
|
2. feature mapper
|
|
3. scope current check
|
|
4. mutation effect confirmed
|
|
5. exact detail seed if registered
|
|
6. optimistic layer commit/remove
|
|
7. registered invalidation topics emit
|
|
8. local active Query refetch schedule
|
|
9. success UI/navigation
|
|
```
|
|
|
|
list/aggregate는 default invalidate다. deterministic membership policy가 없으면 direct patch하지 않는다.
|
|
|
|
### 11.7 failure ordering
|
|
|
|
`NOT_STARTED/NOT_APPLIED`:
|
|
|
|
```text
|
|
rollback optimistic layer
|
|
-> expose retryable failure
|
|
```
|
|
|
|
`MAYBE_APPLIED`:
|
|
|
|
```text
|
|
optimistic layer를 committed/rolled-back으로 단정하지 않음
|
|
-> effect-unknown overlay
|
|
-> inspect/reconcile
|
|
-> confirmed outcome 후 canonical cache update
|
|
```
|
|
|
|
### 11.8 local invalidation failure
|
|
|
|
server command가 committed된 뒤 local invalidation이 실패해도 mutation을 failure로 바꾸지 않는다.
|
|
|
|
```text
|
|
mutation result = success
|
|
cache health = degraded
|
|
bounded authoritative refetch schedule
|
|
```
|
|
|
|
command를 다시 보내지 않는다.
|
|
|
|
### 11.9 form submit
|
|
|
|
- double-submit coordinator 사용;
|
|
- dirty state는 `APPLIED_CONFIRMED` 뒤 clear;
|
|
- effect unknown이면 dirty state를 clear하지 않음;
|
|
- successful navigation은 invalidation scheduling 뒤;
|
|
- route blocker는 active effect-unknown recovery를 고려;
|
|
- browser abort가 server rollback 증거가 아님.
|
|
|
|
---
|
|
|
|
## 12. Cross-context invalidation
|
|
|
|
### 12.1 wire 의미
|
|
|
|
cross-tab wire는 invalidate-only hint다.
|
|
|
|
전송 금지:
|
|
|
|
```text
|
|
query key
|
|
query data
|
|
input/filter
|
|
cursor
|
|
validator
|
|
optimistic layer
|
|
mutation body
|
|
account ID
|
|
resource ID
|
|
```
|
|
|
|
전송:
|
|
|
|
```text
|
|
protocol version
|
|
release epoch
|
|
scope epoch
|
|
sequence
|
|
opaque topic ID
|
|
source instance ID digest
|
|
```
|
|
|
|
### 12.2 registry
|
|
|
|
```ts
|
|
export interface InvalidationRegistry {
|
|
readonly topics: readonly string[];
|
|
readonly namespaces: readonly string[];
|
|
readonly edges: readonly Readonly<{
|
|
topicId: string;
|
|
namespace: string;
|
|
}>[];
|
|
}
|
|
```
|
|
|
|
bounds:
|
|
|
|
```text
|
|
topics 256
|
|
namespaces 256
|
|
edges 1,024
|
|
topic fan-out 64
|
|
namespace fan-in 64
|
|
ID bytes 80
|
|
```
|
|
|
|
duplicate edge와 orphan topic/namespace를 startup에서 거절한다.
|
|
|
|
### 12.3 primary/fallback transport
|
|
|
|
```text
|
|
primary = BroadcastChannel
|
|
fallback = localStorage pulse + storage event
|
|
```
|
|
|
|
channel/key는 registry-issued opaque token을 사용한다.
|
|
|
|
fallback pulse:
|
|
|
|
```text
|
|
maximum 1,024 bytes
|
|
TTL 60 seconds
|
|
write then remove not used; latest bounded envelope overwrite
|
|
storageArea must equal localStorage
|
|
same-tab local dispatch is explicit, storage event를 기대하지 않음
|
|
```
|
|
|
|
### 12.4 ordering
|
|
|
|
source instance별 monotonic sequence를 사용한다.
|
|
|
|
- duplicate sequence: ignore;
|
|
- lower sequence: stale duplicate ignore;
|
|
- exact next: topic apply;
|
|
- gap: 모든 registered namespace stale mark;
|
|
- release/scope epoch mismatch: event ignore + local full stale transition;
|
|
- event는 authority가 아니라 refetch hint.
|
|
|
|
### 12.5 mutation coalescing
|
|
|
|
current local mutation lease 동안 같은 topic remote hint를 coalesce한다.
|
|
|
|
mutation settlement 후:
|
|
|
|
- one invalidation apply;
|
|
- active query bounded refetch;
|
|
- inactive query는 next mount/focus revalidate;
|
|
- remote hint 때문에 optimistic layer를 tab 간 복제하지 않는다.
|
|
|
|
### 12.6 lifecycle
|
|
|
|
- application runtime start에서 one host;
|
|
- session transition 시 scope epoch rotate;
|
|
- logout에서 old event ignore;
|
|
- pagehide bfcache는 host suspend, restore에서 duplicate listener 없이 resume;
|
|
- dispose는 listener/channel/timer 제거;
|
|
- hidden page도 invalidation hint 수신은 유지하되 refetch는 visibility policy를 따른다.
|
|
|
|
---
|
|
## 13. Realtime product composition
|
|
|
|
### 13.1 existing runtime reuse
|
|
|
|
다음 existing source를 common runtime으로 유지한다.
|
|
|
|
```text
|
|
src/contracts/realtime-events.ts
|
|
src/contracts/realtime-streams.ts
|
|
src/application/ports/realtime/*
|
|
src/adapters/realtime/event-codec.ts
|
|
src/adapters/realtime/event-consumer.ts
|
|
src/adapters/realtime/reconnect-coordinator.ts
|
|
src/adapters/realtime/live-poll-handoff-coordinator.ts
|
|
src/adapters/realtime/stream-coordinator.ts
|
|
src/adapters/realtime/sse/*
|
|
src/adapters/realtime/websocket/*
|
|
src/adapters/realtime/polling/*
|
|
src/adapters/web-push/*
|
|
```
|
|
|
|
RT-01~RT-04를 새 protocol로 다시 구현하지 않는다.
|
|
|
|
### 13.2 product contribution source
|
|
|
|
```text
|
|
src/features/<feature>/contracts/<feature>-realtime-contribution.ts
|
|
```
|
|
|
|
```ts
|
|
export interface InstalledRealtimeContribution {
|
|
readonly contributionId: string;
|
|
readonly featureId: string;
|
|
readonly contractSourcePackageId: string;
|
|
readonly stream: RealtimeStreamRegistration;
|
|
readonly eventEffects: readonly InstalledRealtimeEventEffect[];
|
|
readonly transport: InstalledRealtimeTransport;
|
|
}
|
|
|
|
export interface InstalledRealtimeEventEffect {
|
|
readonly eventType: string;
|
|
readonly mapperId: string;
|
|
readonly effect:
|
|
| "INVALIDATE_TOPICS"
|
|
| "APPLY_AUTHORITATIVE_DELTA"
|
|
| "EPHEMERAL_NOTIFICATION";
|
|
readonly invalidationTopics: readonly string[];
|
|
}
|
|
|
|
export type InstalledRealtimeTransport =
|
|
| Readonly<{ kind: "SSE"; endpointId: string }>
|
|
| Readonly<{ kind: "WEBSOCKET"; endpointId: string }>
|
|
| Readonly<{
|
|
kind: "POLLING";
|
|
operationId: string;
|
|
intervalMs: number;
|
|
}>;
|
|
```
|
|
|
|
endpoint/event/recovery meaning is imported from the external package/approved frontend contribution. Frontend does not invent a server path or event payload.
|
|
|
|
### 13.3 contribution validation
|
|
|
|
```text
|
|
contributions max 64
|
|
streams max 128
|
|
event types max 512
|
|
effects per event max 8
|
|
invalidation topics per event 32
|
|
```
|
|
|
|
validation:
|
|
|
|
- contribution ID unique;
|
|
- stream/event registration existing registry rules pass;
|
|
- external event type exists in installed contract contribution;
|
|
- event validator package belongs to `contractSourcePackageId`;
|
|
- mapper exists and input schema matches payload validator;
|
|
- invalidation topic exists;
|
|
- transport endpoint/operation exists in installed package contribution;
|
|
- polling interval 5,000..300,000ms;
|
|
- transport exactly one;
|
|
- fallback is explicit, not inferred from runtime support.
|
|
|
|
### 13.4 no mega port
|
|
|
|
SSE, WebSocket, Polling, Web Push는 다음 의미로 분리한다.
|
|
|
|
```text
|
|
SSE active page one-way stream
|
|
WebSocket active page duplex protocol
|
|
Polling visible finite HTTP scheduling
|
|
Web Push inactive/background user notification hint
|
|
```
|
|
|
|
하나의 `RealtimePort.connect(any)`로 합치지 않는다.
|
|
|
|
### 13.5 transport selection
|
|
|
|
기본 선택 규칙:
|
|
|
|
- one-way active stream: SSE;
|
|
- duplex application protocol: WebSocket;
|
|
- stream provider가 없고 bounded freshness로 충분: Polling;
|
|
- inactive user notification: Web Push;
|
|
- Web Push를 foreground state synchronization으로 사용 금지;
|
|
- Polling을 connection failure 자동 downgrade로 사용 금지;
|
|
- primary/fallback pair는 contribution의 `stream.fallback`이 명시한다.
|
|
|
|
### 13.6 product composition stop condition
|
|
|
|
다음 중 하나라도 없으면 product realtime을 composition하지 않는다.
|
|
|
|
```text
|
|
exact external package event descriptor
|
|
exact endpoint/operation descriptor
|
|
feature mapper
|
|
feature effect mapping
|
|
scope mode
|
|
recovery mode
|
|
selected transport
|
|
kill switch contribution
|
|
browser lifecycle owner
|
|
```
|
|
|
|
common source가 존재한다는 이유로 production bootstrap에 연결하지 않는다.
|
|
|
|
### 13.7 host topology
|
|
|
|
application runtime당 `RealtimeRuntimeHost` 하나다.
|
|
|
|
```ts
|
|
export interface RealtimeRuntimeHost {
|
|
acquire(subscription: RealtimeSubscriptionRequest): RealtimeSubscriptionLease;
|
|
start(): Promise<void>;
|
|
stop(reason: RuntimeStopReason): Promise<void>;
|
|
dispose(): Promise<void>;
|
|
}
|
|
```
|
|
|
|
transport connection은 stream registration 단위로 공유한다. component/route마다 socket을 만들지 않는다.
|
|
|
|
### 13.8 single-writer rule
|
|
|
|
동일 stream/scope에는 active delivery writer가 하나다.
|
|
|
|
```text
|
|
SSE or WebSocket writer
|
|
XOR
|
|
bounded Polling writer
|
|
```
|
|
|
|
handoff:
|
|
|
|
```text
|
|
old writer admission close
|
|
-> old in-flight settle/cancel
|
|
-> checkpoint snapshot
|
|
-> new writer recovery barrier
|
|
-> new writer OPEN
|
|
```
|
|
|
|
live와 polling이 동시에 same effect를 적용하지 않는다.
|
|
|
|
---
|
|
|
|
## 14. Connection·Reconnect·Resume
|
|
|
|
### 14.1 state machine
|
|
|
|
```ts
|
|
export type RealtimeConnectionState =
|
|
| "IDLE"
|
|
| "CONNECTING"
|
|
| "AUTHENTICATING"
|
|
| "OPEN_UNRESUMED"
|
|
| "RECOVERING"
|
|
| "OPEN"
|
|
| "BACKING_OFF"
|
|
| "PAUSED_OFFLINE"
|
|
| "PAUSED_HIDDEN"
|
|
| "DEGRADED"
|
|
| "FATAL"
|
|
| "STOPPED";
|
|
```
|
|
|
|
`OPEN_UNRESUMED`에서 application event effect를 실행하지 않는다.
|
|
|
|
### 14.2 connection success
|
|
|
|
connection success는 다음만 뜻한다.
|
|
|
|
```text
|
|
transport handshake completed
|
|
selected protocol accepted
|
|
connection generation current
|
|
```
|
|
|
|
다음을 뜻하지 않는다.
|
|
|
|
```text
|
|
authenticated subscription active
|
|
event gap recovered
|
|
server state latest
|
|
checkpoint durable
|
|
application effect applied
|
|
```
|
|
|
|
### 14.3 reconnect policy
|
|
|
|
exact default:
|
|
|
|
```ts
|
|
export const DEFAULT_REALTIME_RECONNECT_POLICY = Object.freeze({
|
|
baseDelayMs: 500,
|
|
maxDelayMs: 30_000,
|
|
maxAttempts: 10,
|
|
maxElapsedMs: 300_000,
|
|
stableOpenMs: 60_000,
|
|
});
|
|
```
|
|
|
|
- algorithm: full jitter;
|
|
- server not-before hint: local delay lower bound;
|
|
- hint valid range: 0..60,000ms;
|
|
- remaining episode budget 초과 hint: reconnect 종료;
|
|
- attempts/exhausted: `DEGRADED`, explicit recovery action;
|
|
- automatic new episode cooldown: 300,000ms;
|
|
- valid event/heartbeat를 받고 60s stable open도 지난 뒤에만 attempt counter reset;
|
|
- offline state에서는 timer 대신 `online` signal을 기다림.
|
|
|
|
### 14.4 error classification
|
|
|
|
reconnect candidate:
|
|
|
|
```text
|
|
network close
|
|
provider unavailable
|
|
retryable server close
|
|
idle timeout
|
|
validated auth refresh-ready transition
|
|
```
|
|
|
|
fatal:
|
|
|
|
```text
|
|
protocol mismatch
|
|
unknown required event version
|
|
schema/mapper runtime failure
|
|
forbidden
|
|
invalid endpoint
|
|
repeated recovery invariant failure
|
|
```
|
|
|
|
rate limited:
|
|
|
|
- validated delay 사용;
|
|
- maximum delay/episode budget 안에서만 retry;
|
|
- no immediate retry storm.
|
|
|
|
### 14.5 visibility policy
|
|
|
|
```text
|
|
VISIBLE -> normal connection/recovery
|
|
HIDDEN -> 30,000ms grace
|
|
HIDDEN after grace -> close transport, PAUSED_HIDDEN
|
|
VISIBLE restore -> authoritative recovery before OPEN
|
|
```
|
|
|
|
hidden 상태에서 Polling fallback을 시작하지 않는다. Web Push는 별도 capability다.
|
|
|
|
### 14.6 network hint
|
|
|
|
`navigator.onLine`은 hint다.
|
|
|
|
- `offline` event: new connection/retry 중지, active transport close;
|
|
- `online` event: immediate recovery admission one time;
|
|
- online인데 connect failure면 ordinary backoff;
|
|
- offline인데 existing request가 성공해도 network authority를 재정의하지 않음.
|
|
|
|
### 14.7 resume authority
|
|
|
|
resume mode는 existing `RealtimeRecoveryProfile` literal을 유지한다.
|
|
|
|
```text
|
|
CURSOR
|
|
SNAPSHOT_ONLY
|
|
SESSION_REBUILD
|
|
```
|
|
|
|
frontend owns:
|
|
|
|
- checkpoint storage lifecycle;
|
|
- connection generation;
|
|
- duplicate/gap detection;
|
|
- barrier ordering;
|
|
- snapshot application ordering.
|
|
|
|
external package/provider owns server cursor/replay/snapshot semantics. Frontend는 cursor를 decode/modify하지 않는다.
|
|
|
|
### 14.8 recovery barrier
|
|
|
|
`CURSOR`:
|
|
|
|
```text
|
|
open transport
|
|
-> send/attach opaque checkpoint through selected adapter
|
|
-> replay begins
|
|
-> validate/apply events sequentially
|
|
-> replay terminal barrier
|
|
-> OPEN
|
|
```
|
|
|
|
`SNAPSHOT_ONLY`:
|
|
|
|
```text
|
|
open transport or hold/buffer
|
|
-> authoritative snapshot query
|
|
-> scope current check
|
|
-> apply snapshot
|
|
-> release buffered event barrier
|
|
-> OPEN
|
|
```
|
|
|
|
`SESSION_REBUILD`:
|
|
|
|
```text
|
|
close old stream
|
|
-> rebuild feature input
|
|
-> reset feature state
|
|
-> fresh subscription
|
|
-> OPEN
|
|
```
|
|
|
|
barrier가 `NONE`인 snapshot profile도 connection open만으로 latest라고 표시하지 않는다. snapshot operation 성공이 필요하다.
|
|
|
|
### 14.9 checkpoint record
|
|
|
|
```ts
|
|
export interface RealtimeCheckpointRecord {
|
|
readonly recordVersion: 1;
|
|
readonly streamId: string;
|
|
readonly scopeBinding: string;
|
|
readonly connectionGeneration: number;
|
|
readonly opaqueCheckpoint: string;
|
|
readonly lastAppliedEventIdentity: string;
|
|
readonly writtenAt: string;
|
|
readonly expiresAt: string;
|
|
readonly contractPackageDigest: `sha256:${string}`;
|
|
}
|
|
```
|
|
|
|
bounds:
|
|
|
|
```text
|
|
checkpoint UTF-8 <= 4,096 bytes
|
|
record encoded <= 16,384 bytes
|
|
TTL <= 7 days
|
|
records per stream/scope = 1
|
|
```
|
|
|
|
credential, endpoint, raw account ID를 넣지 않는다.
|
|
|
|
### 14.10 gap handling
|
|
|
|
다음은 gap이다.
|
|
|
|
- expected sequence보다 큼;
|
|
- same sequence different fingerprint;
|
|
- cursor expired;
|
|
- dedupe window overflow;
|
|
- queue overflow;
|
|
- checkpoint version/package mismatch;
|
|
- connection generation conflict.
|
|
|
|
처리:
|
|
|
|
```text
|
|
new event admission stop
|
|
-> queued unapplied delta discard
|
|
-> state = RECOVERING
|
|
-> authoritative snapshot/session rebuild
|
|
-> checkpoint replace after effect
|
|
-> OPEN
|
|
```
|
|
|
|
gap 이후 delta를 계속 best-effort 적용하지 않는다.
|
|
|
|
### 14.11 SSE specifics
|
|
|
|
- Fetch streaming adapter reuse;
|
|
- response status/media validate;
|
|
- maximum line/event bytes는 common event bound;
|
|
- UTF-8 streaming decode;
|
|
- incomplete terminal event discard;
|
|
- heartbeat/comment는 payload event가 아님;
|
|
- idle deadline 45s default;
|
|
- total connection deadline 없음, lifecycle controls close;
|
|
- server `retry` hint is lower bound, max 60s;
|
|
- `Last-Event-ID` usage is adapter/profile-owned, opaque only.
|
|
|
|
### 14.12 WebSocket specifics
|
|
|
|
- exact URL/profile from installed endpoint;
|
|
- binary/text mode fixed per registration;
|
|
- subprotocol allowlist exact;
|
|
- outbound command disabled unless separate registered protocol;
|
|
- max event bytes 64KiB baseline;
|
|
- bufferedAmount high watermark 256KiB for outbound control messages;
|
|
- heartbeat expected 30s, idle timeout 45s when protocol declares heartbeat;
|
|
- browser WebSocket API가 backpressure를 보장한다고 가정하지 않음;
|
|
- receive queue hard bounds are common runtime authority;
|
|
- close code/reason raw text를 UI/log에 노출하지 않음.
|
|
|
|
### 14.13 bounded polling specifics
|
|
|
|
- existing registered terminal query operation only;
|
|
- visible page only;
|
|
- default interval 30s;
|
|
- minimum 5s, maximum 5m;
|
|
- one in-flight request;
|
|
- next schedule after previous settlement;
|
|
- hidden/offline pause;
|
|
- full jitter ±10% schedule spread;
|
|
- Query retry disabled, HTTP transport owns attempt;
|
|
- polling result enters same mapper/scope/result budget;
|
|
- polling is freshness policy, not realtime delivery guarantee.
|
|
|
|
---
|
|
|
|
## 15. Event validation과 subscription cleanup
|
|
|
|
### 15.1 hard limits
|
|
|
|
existing constants are normative.
|
|
|
|
```text
|
|
max event bytes 64 KiB
|
|
max payload depth 16
|
|
max payload nodes 4,096
|
|
max queue events 256
|
|
max queue bytes 4 MiB
|
|
max dedupe entries 2,048
|
|
max dedupe bytes 4 MiB
|
|
dedupe TTL 10 min
|
|
```
|
|
|
|
feature contribution can reduce but not raise them.
|
|
|
|
### 15.2 validation pipeline
|
|
|
|
```text
|
|
raw frame
|
|
-> frame byte bound
|
|
-> protocol decode
|
|
-> common envelope validation
|
|
-> stream registration lookup
|
|
-> event type membership check
|
|
-> package payload validator
|
|
-> feature mapper
|
|
-> scope binding/generation check
|
|
-> duplicate/sequence/gap decision
|
|
-> queue admission
|
|
-> sequential effect
|
|
-> effect success
|
|
-> checkpoint transaction commit
|
|
-> subscriber notification
|
|
```
|
|
|
|
순서를 바꾸지 않는다.
|
|
|
|
### 15.3 envelope/payload failure
|
|
|
|
```text
|
|
MALFORMED_FRAME
|
|
EVENT_TOO_LARGE
|
|
UNKNOWN_EVENT_TYPE
|
|
EVENT_NOT_ALLOWED_FOR_STREAM
|
|
ENVELOPE_SCHEMA_INVALID
|
|
PAYLOAD_SCHEMA_INVALID
|
|
VALIDATOR_RUNTIME_FAILURE
|
|
MAPPING_CONTRACT_VIOLATION
|
|
SCOPE_PROTOCOL_VIOLATION
|
|
```
|
|
|
|
unknown event를 generic object로 application에 전달하지 않는다.
|
|
|
|
state-bearing event failure:
|
|
|
|
```text
|
|
admission stop -> recovery
|
|
```
|
|
|
|
ephemeral notification failure:
|
|
|
|
```text
|
|
drop + bounded observation
|
|
```
|
|
|
|
### 15.4 duplicate/conflict
|
|
|
|
same event identity + same semantic fingerprint:
|
|
|
|
```text
|
|
duplicate -> no effect, no checkpoint regression
|
|
```
|
|
|
|
same identity + different fingerprint:
|
|
|
|
```text
|
|
EVENT_CONFLICT -> recovery
|
|
```
|
|
|
|
lower sequence but unknown dedupe entry:
|
|
|
|
```text
|
|
STALE_EVENT -> drop only when registration semantics allow
|
|
otherwise recovery
|
|
```
|
|
|
|
### 15.5 queue
|
|
|
|
- admission count/bytes atomic in host;
|
|
- event processing sequential per stream;
|
|
- different streams can progress independently;
|
|
- queue overflow triggers recovery, not oldest-drop;
|
|
- no unbounded `Promise.then` chain retained after settlement;
|
|
- queued item owns immutable mapped event and byte estimate;
|
|
- shutdown aborts admission and drains up to 2s, then drops unapplied items without checkpoint.
|
|
|
|
### 15.6 effect types
|
|
|
|
`INVALIDATE_TOPICS`:
|
|
|
|
```text
|
|
registered opaque topics only
|
|
-> local invalidation coordinator
|
|
-> active Query bounded refetch
|
|
```
|
|
|
|
`APPLY_AUTHORITATIVE_DELTA`:
|
|
|
|
- feature-owned reducer;
|
|
- current immutable snapshot and revision required;
|
|
- deterministic/no throw;
|
|
- result size budget;
|
|
- failure triggers recovery;
|
|
- partial delta not stored as event history.
|
|
|
|
`EPHEMERAL_NOTIFICATION`:
|
|
|
|
- no server-state authority;
|
|
- bounded UI notification;
|
|
- missed notification does not require state recovery unless separately marked state-bearing.
|
|
|
|
### 15.7 checkpoint commit ordering
|
|
|
|
금지:
|
|
|
|
```text
|
|
checkpoint write
|
|
-> application effect
|
|
```
|
|
|
|
필수:
|
|
|
|
```text
|
|
validate/map
|
|
-> effect commit
|
|
-> scope current recheck
|
|
-> checkpoint transaction commit
|
|
-> notify
|
|
```
|
|
|
|
checkpoint write failure after effect:
|
|
|
|
- event effect success를 rollback할 수 없음;
|
|
- state `RECOVERING`;
|
|
- next connection uses authoritative snapshot;
|
|
- same delta replay에 reducer idempotency를 가정하지 않음.
|
|
|
|
### 15.8 subscription lease
|
|
|
|
```ts
|
|
export interface RealtimeSubscriptionLease {
|
|
readonly leaseId: string;
|
|
readonly streamId: string;
|
|
readonly state: "ACTIVE" | "RELEASED";
|
|
release(): void;
|
|
}
|
|
```
|
|
|
|
key:
|
|
|
|
```text
|
|
streamId + scope generation + subscription projection identity
|
|
```
|
|
|
|
ref-count behavior:
|
|
|
|
```text
|
|
0 -> 1 : server/transport subscription admission
|
|
1 -> N : local subscriber only
|
|
N -> 1 : local release
|
|
1 -> 0 : 5s grace
|
|
0 after grace: unsubscribe/connection policy evaluation
|
|
```
|
|
|
|
### 15.9 cleanup triggers
|
|
|
|
immediate release:
|
|
|
|
- explicit component cleanup;
|
|
- route removal;
|
|
- feature disable;
|
|
- scope fence/logout;
|
|
- application shutdown;
|
|
- fatal protocol failure.
|
|
|
|
grace release:
|
|
|
|
- ordinary React remount/navigation;
|
|
- StrictMode setup-cleanup-setup;
|
|
- short route transition.
|
|
|
|
scope fence는 grace를 사용하지 않는다.
|
|
|
|
### 15.10 React bridge
|
|
|
|
component uses feature hook only.
|
|
|
|
```text
|
|
Component
|
|
-> useFeatureRealtime
|
|
-> acquire lease in effect
|
|
-> cleanup release
|
|
-> read external store via useSyncExternalStore
|
|
```
|
|
|
|
component does not:
|
|
|
|
- open/close socket;
|
|
- store cursor;
|
|
- schedule reconnect;
|
|
- parse event;
|
|
- call QueryClient directly.
|
|
|
|
### 15.11 StrictMode
|
|
|
|
required behavior:
|
|
|
|
```text
|
|
setup A acquire
|
|
cleanup A release -> grace starts
|
|
setup B acquire within grace -> same runtime retained
|
|
after final cleanup -> 5s -> actual unsubscribe
|
|
```
|
|
|
|
listener/ref count cannot go negative. release is idempotent.
|
|
|
|
### 15.12 bfcache
|
|
|
|
`pagehide persisted=true`:
|
|
|
|
- new event effect admission close;
|
|
- transport close;
|
|
- checkpoint remains;
|
|
- lease registry retained in suspended state.
|
|
|
|
`pageshow persisted=true`:
|
|
|
|
- release manifest refresh;
|
|
- scope current check;
|
|
- authoritative resume;
|
|
- leases reactivate after OPEN;
|
|
- duplicate listeners/connections 없음.
|
|
|
|
---
|
|
|
|
## 16. Generic Web Worker
|
|
|
|
### 16.1 capability boundary
|
|
|
|
Generic CPU Worker is separate from:
|
|
|
|
```text
|
|
OPFS dedicated worker
|
|
Service Worker
|
|
Web Push handler
|
|
SharedWorker
|
|
worklet
|
|
```
|
|
|
|
existing OPFS worker source is not moved into generic runtime.
|
|
|
|
### 16.2 selection condition
|
|
|
|
Generic Worker remains `NOT_SELECTED` until:
|
|
|
|
- measured main-thread task exceeds named interaction budget;
|
|
- task is CPU-bound;
|
|
- input/output/cancellation owner exists;
|
|
- safe main-thread fallback is defined or unsupported state is accepted;
|
|
- static `InstalledWebWorkerContribution` exists.
|
|
|
|
network I/O task, ordinary JSON validation, small mapper work를 worker로 옮기지 않는다.
|
|
|
|
### 16.3 source layout
|
|
|
|
```text
|
|
src/application/ports/web-worker/
|
|
worker-task-port.ts
|
|
src/contracts/web-worker.ts
|
|
src/adapters/web-worker/
|
|
web-worker-runtime.ts
|
|
web-worker-client.ts
|
|
web-worker-protocol.ts
|
|
web-worker-entry.ts
|
|
web-worker-task-registry.ts
|
|
```
|
|
|
|
application port is semantic task-specific, not generic arbitrary function execution.
|
|
|
|
### 16.4 installed contribution
|
|
|
|
```ts
|
|
export interface InstalledWebWorkerContribution {
|
|
readonly taskGroupId: string;
|
|
readonly tasks: readonly InstalledWorkerTask[];
|
|
readonly fallback: "MAIN_THREAD_CHUNKED" | "UNSUPPORTED";
|
|
}
|
|
|
|
export interface InstalledWorkerTask {
|
|
readonly taskId: string;
|
|
readonly taskVersion: 1;
|
|
readonly maximumInputBytes: number;
|
|
readonly maximumOutputBytes: number;
|
|
readonly deadlineMs: number;
|
|
}
|
|
```
|
|
|
|
bounds:
|
|
|
|
```text
|
|
task groups max 16
|
|
tasks per group 32
|
|
input default 1 MiB
|
|
input hard 8 MiB
|
|
output default 1 MiB
|
|
output hard 8 MiB
|
|
deadline default 5 s
|
|
deadline hard 30 s
|
|
```
|
|
|
|
### 16.5 worker topology
|
|
|
|
- task group당 worker 1개;
|
|
- baseline pool size 1;
|
|
- same group FIFO;
|
|
- groups can run independently;
|
|
- max active groups 4;
|
|
- no shared global pool;
|
|
- first task에서 lazy create;
|
|
- idle 60s with no active/queue -> terminate;
|
|
- next task creates new generation.
|
|
|
|
### 16.6 protocol V1
|
|
|
|
```ts
|
|
export type WorkerRequestMessage = Readonly<{
|
|
protocol: "CA_WEB_WORKER_V1";
|
|
kind: "EXECUTE";
|
|
taskId: string;
|
|
taskVersion: 1;
|
|
requestId: string;
|
|
workerGeneration: number;
|
|
deadlineEpochMs: number;
|
|
payload: unknown;
|
|
}>;
|
|
|
|
export type WorkerCancelMessage = Readonly<{
|
|
protocol: "CA_WEB_WORKER_V1";
|
|
kind: "CANCEL";
|
|
requestId: string;
|
|
workerGeneration: number;
|
|
}>;
|
|
|
|
export type WorkerResponseMessage =
|
|
| Readonly<{
|
|
protocol: "CA_WEB_WORKER_V1";
|
|
kind: "SUCCESS";
|
|
requestId: string;
|
|
workerGeneration: number;
|
|
payload: unknown;
|
|
}>
|
|
| Readonly<{
|
|
protocol: "CA_WEB_WORKER_V1";
|
|
kind: "FAILURE";
|
|
requestId: string;
|
|
workerGeneration: number;
|
|
code: WorkerFailureCode;
|
|
}>;
|
|
```
|
|
|
|
### 16.7 failure code
|
|
|
|
```text
|
|
TASK_UNKNOWN
|
|
VERSION_UNSUPPORTED
|
|
INPUT_INVALID
|
|
INPUT_TOO_LARGE
|
|
OUTPUT_INVALID
|
|
OUTPUT_TOO_LARGE
|
|
QUEUE_FULL
|
|
DEADLINE_EXCEEDED
|
|
CANCELLED
|
|
CRASHED
|
|
TRANSFER_FAILED
|
|
STALE_RESULT
|
|
RUNTIME_PROTOCOL_FAILURE
|
|
```
|
|
|
|
```ts
|
|
export type WorkerFailureCode =
|
|
| "TASK_UNKNOWN"
|
|
| "VERSION_UNSUPPORTED"
|
|
| "INPUT_INVALID"
|
|
| "INPUT_TOO_LARGE"
|
|
| "OUTPUT_INVALID"
|
|
| "OUTPUT_TOO_LARGE"
|
|
| "QUEUE_FULL"
|
|
| "DEADLINE_EXCEEDED"
|
|
| "CANCELLED"
|
|
| "CRASHED"
|
|
| "TRANSFER_FAILED"
|
|
| "STALE_RESULT"
|
|
| "RUNTIME_PROTOCOL_FAILURE";
|
|
```
|
|
|
|
native error message/stack is not posted to page.
|
|
|
|
### 16.8 queue bounds
|
|
|
|
```text
|
|
queued tasks per group 32
|
|
queued encoded bytes 16 MiB
|
|
active tasks per group 1
|
|
waiters per request 1
|
|
```
|
|
|
|
queue full is a local typed failure. It does not create another worker.
|
|
|
|
### 16.9 cancellation
|
|
|
|
queued:
|
|
|
|
- remove immediately;
|
|
- settle `CANCELLED`;
|
|
- no worker message.
|
|
|
|
active:
|
|
|
|
```text
|
|
send CANCEL
|
|
-> cooperative task checks signal
|
|
-> 250ms grace
|
|
-> not settled: terminate worker
|
|
-> all active/queued in same generation settle CRASHED/CANCELLED
|
|
-> next task creates new generation subject to restart budget
|
|
```
|
|
|
|
### 16.10 crash/restart budget
|
|
|
|
```text
|
|
maximum restarts = 3 per 5 minutes per task group
|
|
fourth crash -> group FATAL
|
|
manual retry -> new 5-minute window only after user action/page reload
|
|
```
|
|
|
|
crash does not retry completed/unknown task automatically.
|
|
|
|
### 16.11 structured clone/transfer
|
|
|
|
- message schema validates cloned shape;
|
|
- credentials, AbortSignal, class instance, function, DOM node prohibited;
|
|
- ArrayBuffer transfer allowed only when task declares ownership transfer;
|
|
- sender must treat transferred buffer as detached immediately;
|
|
- output transfer is validated after receive;
|
|
- SharedArrayBuffer baseline prohibited;
|
|
- transferable list count max 16.
|
|
|
|
### 16.12 stale result fence
|
|
|
|
result is accepted only when all match.
|
|
|
|
```text
|
|
requestId
|
|
workerGeneration
|
|
current task lease
|
|
caller scope generation
|
|
not cancelled
|
|
before deadline
|
|
```
|
|
|
|
stale result is dropped and observed. Query/UI is not updated.
|
|
|
|
### 16.13 worker network prohibition
|
|
|
|
worker entry cannot import HTTP adapter or use `fetch`, WebSocket, EventSource, credential/session adapter.
|
|
|
|
CPU task requiring remote input:
|
|
|
|
```text
|
|
page/application HTTP
|
|
-> validate/map/bound payload
|
|
-> Worker task
|
|
-> validate result
|
|
-> application/UI
|
|
```
|
|
|
|
### 16.14 main-thread fallback
|
|
|
|
`MAIN_THREAD_CHUNKED` only:
|
|
|
|
- same semantic task interface;
|
|
- chunk budget max 8ms;
|
|
- yield via scheduler/MessageChannel adapter;
|
|
- same total deadline;
|
|
- same cancellation/result validator;
|
|
- input hard max reduced to 1MiB;
|
|
- not presented as equivalent performance guarantee.
|
|
|
|
`UNSUPPORTED` returns typed unavailable; it does not execute synchronously.
|
|
|
|
---
|
|
|
|
## 17. Service Worker lifecycle
|
|
|
|
### 17.1 one physical registration
|
|
|
|
same scope has one worker entry.
|
|
|
|
```text
|
|
PWA lifecycle
|
|
verified static asset fetch
|
|
Web Push event/click
|
|
optional sync wake-up
|
|
```
|
|
|
|
separate registration prohibited.
|
|
|
|
```text
|
|
src/adapters/service-worker/service-worker-entry.ts
|
|
```
|
|
|
|
existing Web Push service-worker runtime becomes a handler factory inside this entry.
|
|
|
|
### 17.2 source layout
|
|
|
|
```text
|
|
src/contracts/service-worker.ts
|
|
src/adapters/service-worker/
|
|
service-worker-entry.ts
|
|
service-worker-protocol.ts
|
|
service-worker-page-controller.ts
|
|
service-worker-lifecycle.ts
|
|
service-worker-static-assets.ts
|
|
service-worker-sync-handler.ts
|
|
service-worker-removal.ts
|
|
src/bootstrap/register-service-worker.ts
|
|
```
|
|
|
|
### 17.2.1 TypeScript execution realms
|
|
|
|
main DOM, generic Web Worker와 Service Worker는 같은 TypeScript global lib를 공유하지 않는다.
|
|
|
|
```text
|
|
tsconfig.app.json lib = DOM + ES
|
|
|
|
tsconfig.web-worker.json lib = WebWorker + ES
|
|
include generic worker entry/runtime only
|
|
|
|
tsconfig.service-worker.json lib = WebWorker + ES
|
|
include service-worker entry/handlers only
|
|
```
|
|
|
|
- worker tsconfig에서 DOM global type을 사용하지 않는다;
|
|
- service-worker tsconfig에서 React/presentation/bootstrap page code를 include하지 않는다;
|
|
- shared protocol file은 DOM/WebWorker global type 대신 structural types만 사용한다;
|
|
- root `tsconfig.json` project references에 두 config를 추가한다;
|
|
- `skipLibCheck`로 realm collision을 숨기지 않는다.
|
|
|
|
### 17.2.2 deterministic two-pass build
|
|
|
|
Service Worker가 exact hashed app asset 목록을 compile-time으로 가져야 하므로 build 순서를 다음으로 고정한다.
|
|
|
|
```text
|
|
1. clean dist and .generated/frontend-runtime
|
|
2. generate contractSet + build-info source
|
|
3. Vite app build (emptyOutDir=true)
|
|
4. scan app dist and generate static asset source
|
|
5. ACTIVE mode일 때 Vite Service Worker build (emptyOutDir=false)
|
|
6. generate Release Manifest V2/build manifest
|
|
```
|
|
|
|
source:
|
|
|
|
```text
|
|
scripts/build-frontend.ts
|
|
scripts/generate-contract-set.ts
|
|
scripts/generate-service-worker-assets.ts
|
|
vite.service-worker.config.ts
|
|
.generated/frontend-runtime/contract-set.ts
|
|
.generated/frontend-runtime/service-worker-build-info.ts
|
|
.generated/frontend-runtime/service-worker-assets.ts
|
|
```
|
|
|
|
Service Worker build rules:
|
|
|
|
- input exactly `src/adapters/service-worker/service-worker-entry.ts`;
|
|
- output exactly `dist/service-worker.js` relative to deployed app root;
|
|
- ES module format;
|
|
- `inlineDynamicImports=true`;
|
|
- no additional worker chunk;
|
|
- sourcemap off by default;
|
|
- minification uses same pinned Vite toolchain;
|
|
- `REMOVE_REGISTRATION`, `PURGE_OWNED_RESOURCES`, `null` mode does not run active worker build;
|
|
- generated asset source excludes `service-worker.js` itself and `index.html`.
|
|
|
|
static delivery requirement:
|
|
|
|
```text
|
|
service-worker.js Cache-Control = no-cache
|
|
runtime config/release manifest = no-store
|
|
hashed assets = immutable
|
|
```
|
|
|
|
runtime does not fetch hosting policy to prove it. Static delivery configuration owns this requirement.
|
|
|
|
### 17.3 static selection modes
|
|
|
|
#### `ACTIVE`
|
|
|
|
handlers contain one or more unique values.
|
|
|
|
```text
|
|
WEB_PUSH
|
|
PWA_STATIC_ASSETS
|
|
OFFLINE_SYNC_WAKEUP
|
|
```
|
|
|
|
worker entry and register code are included.
|
|
|
|
#### `REMOVE_REGISTRATION`
|
|
|
|
- worker entry not included;
|
|
- cleanup controller included;
|
|
- exact registration scope/script ownership check;
|
|
- unregister only;
|
|
- caches retained.
|
|
|
|
#### `PURGE_OWNED_RESOURCES`
|
|
|
|
- repeat unregister check;
|
|
- exact owned caches/metadata purge;
|
|
- outbox/OPFS/file data untouched.
|
|
|
|
#### `null`
|
|
|
|
- entry and cleanup code absent;
|
|
- registration lookup 0;
|
|
- Cache Storage access 0.
|
|
|
|
transition:
|
|
|
|
```text
|
|
ACTIVE
|
|
-> REMOVE_REGISTRATION for at least one deployed release
|
|
-> PURGE_OWNED_RESOURCES after rollback retention
|
|
-> null
|
|
```
|
|
|
|
### 17.4 exact ownership check
|
|
|
|
expected:
|
|
|
|
```text
|
|
scope = new URL(routerBasePath, location.origin).href
|
|
script = new URL("service-worker.js", scope).href
|
|
```
|
|
|
|
`getRegistration(routerBasePath)` result is owned only if:
|
|
|
|
- registration.scope exact equals expected scope;
|
|
- every present installing/waiting/active worker scriptURL is same-origin;
|
|
- at least one present worker scriptURL exact equals expected script;
|
|
- no present worker has different script URL.
|
|
|
|
ownership mismatch means no unregister/purge.
|
|
|
|
### 17.5 registration timing
|
|
|
|
```text
|
|
Runtime Config valid
|
|
-> Release Manifest/contractSet valid
|
|
-> base composition
|
|
-> React first committed effect
|
|
-> PostMountRuntimeStarter.start
|
|
-> ACTIVE/cleanup mode action
|
|
```
|
|
|
|
`ACTIVE` registration call:
|
|
|
|
```ts
|
|
const expectedScope = new URL(routerBasePath, location.origin);
|
|
const scriptUrl = new URL("service-worker.js", expectedScope);
|
|
|
|
navigator.serviceWorker.register(scriptUrl, {
|
|
scope: expectedScope.pathname,
|
|
type: "module",
|
|
updateViaCache: "none",
|
|
});
|
|
```
|
|
|
|
StrictMode repeat returns same in-flight promise.
|
|
|
|
### 17.6 runtime override `DISABLED`
|
|
|
|
static `ACTIVE` + config disabled:
|
|
|
|
```text
|
|
new register 0
|
|
worker message/update timer 0
|
|
sync register 0
|
|
push handler activation 0
|
|
exact-owned registration lookup 1
|
|
owned registration unregister <= 1
|
|
owned cache delete 0
|
|
```
|
|
|
|
failure code `DISABLE_CLEANUP_FAILED`; capability remains inactive. next clean navigation may retry once, no loop.
|
|
|
|
### 17.7 protocol identity
|
|
|
|
```text
|
|
serviceWorkerProtocolVersion = 1
|
|
cacheSchemaVersion = 1
|
|
buildId
|
|
releaseId
|
|
contractSetDigest
|
|
staticAssetSetDigest
|
|
```
|
|
|
|
page and worker read the same compile-time virtual build-info module.
|
|
|
|
### 17.8 message protocol
|
|
|
|
```text
|
|
PAGE_HELLO
|
|
WORKER_HELLO_ACK
|
|
UPDATE_READY
|
|
ACTIVATE_REQUEST
|
|
ACTIVATE_ACCEPTED
|
|
ACTIVATE_REJECTED
|
|
CLIENT_DRAIN_REQUEST
|
|
CLIENT_DRAINED
|
|
ACTIVATED_RELOAD_REQUIRED
|
|
CACHE_RESET_REQUEST
|
|
CACHE_RESET_RESULT
|
|
SYNC_WAKE_OBSERVED
|
|
```
|
|
|
|
common fields:
|
|
|
|
```text
|
|
protocolVersion = 1
|
|
messageId = UUID
|
|
sourceBuildId
|
|
targetBuildId optional
|
|
nonce optional
|
|
```
|
|
|
|
origin/source client ID, exact message keys, runtime schema and one-time nonce validation required.
|
|
|
|
### 17.9 install
|
|
|
|
without static asset handler:
|
|
|
|
- Cache Storage open 0;
|
|
- lifecycle/push/sync handlers register only.
|
|
|
|
with static assets:
|
|
|
|
```text
|
|
1. embedded manifest validate
|
|
2. candidate cache open
|
|
3. fetch concurrency 4
|
|
4. status/content-type/bytes/integrity verify
|
|
5. candidate marker write
|
|
6. all success -> install resolve
|
|
7. any failure -> candidate cache delete and install reject
|
|
```
|
|
|
|
bounds:
|
|
|
|
```text
|
|
assets count 256
|
|
single asset 2 MiB
|
|
asset set 5 MiB
|
|
concurrency 4
|
|
install deadline 60 s
|
|
```
|
|
|
|
partial candidate is never used.
|
|
|
|
### 17.10 waiting update
|
|
|
|
waiting worker sends `UPDATE_READY` to controlled clients.
|
|
|
|
it does not call `skipWaiting()` itself.
|
|
|
|
page blocks activation when:
|
|
|
|
- dirty form;
|
|
- active mutation;
|
|
- effect unknown recovery;
|
|
- offline command `SENDING`;
|
|
- unresolved local file write;
|
|
- incompatible protocol tuple.
|
|
|
|
### 17.11 client drain activation
|
|
|
|
```text
|
|
page creates one-time nonce
|
|
-> ACTIVATE_REQUEST(expected tuple)
|
|
-> waiting worker validates
|
|
-> CLIENT_DRAIN_REQUEST to all controlled window clients
|
|
-> each client closes new mutation/realtime/offline admission
|
|
-> active effects settle
|
|
-> CLIENT_DRAINED(nonce)
|
|
-> all clients within 30s
|
|
-> ACTIVATE_ACCEPTED
|
|
-> waiting worker skipWaiting
|
|
-> activate event
|
|
-> no clients.claim
|
|
-> ACTIVATED_RELOAD_REQUIRED
|
|
-> clean page user/guarded reload once
|
|
```
|
|
|
|
one missing client rejects automatic activation.
|
|
|
|
### 17.12 no clients.claim
|
|
|
|
baseline does not call `clients.claim()`.
|
|
|
|
- first install page is not silently controlled;
|
|
- update does not mix new worker with old page without reload;
|
|
- current page becomes controlled after explicit clean reload;
|
|
- future claim adoption requires separate compatibility decision.
|
|
|
|
### 17.13 first install
|
|
|
|
Service Worker reload guard is distinct from chunk recovery.
|
|
|
|
```text
|
|
storage key = SERVICE_WORKER_RELOAD_GUARD
|
|
value schema = { version: 1, oldBuildId, newBuildId, writtenAt }
|
|
maximum bytes = 512
|
|
TTL = 10 minutes
|
|
```
|
|
|
|
`CHUNK_RELOAD_GUARD`를 재사용하지 않는다. Storage registry/codec이 exact key와 envelope를 소유한다.
|
|
|
|
if active tuple matches current build but `navigator.serviceWorker.controller` is null:
|
|
|
|
```text
|
|
state = RELOAD_TO_ENABLE
|
|
```
|
|
|
|
- no automatic reload;
|
|
- user action only when page clean;
|
|
- reload guard once per build;
|
|
- after reload `PAGE_HELLO` handshake required;
|
|
- handshake failure -> `INCOMPATIBLE`, capability inactive.
|
|
|
|
### 17.14 update checking
|
|
|
|
- no immediate repeated `registration.update()`;
|
|
- visible page at most once per 6 hours;
|
|
- manual action once independently rate-limited;
|
|
- hidden page no scheduled update;
|
|
- network failure does not fail product flow;
|
|
- controllerchange reload guard `(oldBuild,newBuild)` once.
|
|
|
|
### 17.15 activate cleanup
|
|
|
|
- candidate marker and tuple validate;
|
|
- current revision active;
|
|
- previous verified revision retain one;
|
|
- older owned cache delete;
|
|
- exact prefix + parser only;
|
|
- config/release/API cache found -> security violation and delete;
|
|
- unregister != cache cleanup.
|
|
|
|
### 17.16 page controller interface
|
|
|
|
```ts
|
|
export type ServiceWorkerStartOutcome =
|
|
| Readonly<{ kind: "ACTIVE"; buildId: string }>
|
|
| Readonly<{ kind: "RELOAD_TO_ENABLE" }>
|
|
| Readonly<{ kind: "UPDATE_WAITING" }>
|
|
| Readonly<{ kind: "DISABLED" }>
|
|
| Readonly<{ kind: "INCOMPATIBLE" }>
|
|
| Readonly<{ kind: "FAILED"; code: string }>;
|
|
|
|
export type ServiceWorkerActivationOutcome =
|
|
| Readonly<{ kind: "ACTIVATED_RELOAD_REQUIRED" }>
|
|
| Readonly<{ kind: "BLOCKED_DIRTY_CLIENT" }>
|
|
| Readonly<{ kind: "CLIENT_DRAIN_TIMEOUT" }>
|
|
| Readonly<{ kind: "NO_WAITING_WORKER" }>
|
|
| Readonly<{ kind: "PROTOCOL_MISMATCH" }>
|
|
| Readonly<{ kind: "FAILED"; code: string }>;
|
|
|
|
export type ServiceWorkerResetOutcome =
|
|
| Readonly<{ kind: "RESET"; cachesDeleted: number }>
|
|
| Readonly<{ kind: "NOT_CONTROLLED" }>
|
|
| Readonly<{ kind: "PROTOCOL_MISMATCH" }>
|
|
| Readonly<{ kind: "FAILED"; code: string }>;
|
|
|
|
export interface ServiceWorkerRuntimeHost {
|
|
start(): Promise<ServiceWorkerStartOutcome>;
|
|
requestActivation(): Promise<ServiceWorkerActivationOutcome>;
|
|
resetOwnedCaches(): Promise<ServiceWorkerResetOutcome>;
|
|
stop(): Promise<void>;
|
|
}
|
|
```
|
|
|
|
`stop()` removes page listener/update timer. ordinary shutdown does not unregister.
|
|
|
|
### 17.17 cleanup mode outcomes
|
|
|
|
```ts
|
|
export type ServiceWorkerRemovalOutcome =
|
|
| Readonly<{ kind: "ABSENT" }>
|
|
| Readonly<{ kind: "UNREGISTERED" }>
|
|
| Readonly<{ kind: "PURGED"; cachesDeleted: number; metadataDeleted: number }>
|
|
| Readonly<{ kind: "OWNERSHIP_MISMATCH" }>
|
|
| Readonly<{ kind: "FAILED"; operation: "LOOKUP" | "UNREGISTER" | "PURGE" }>;
|
|
```
|
|
|
|
foreign resource count can be observed only as bounded count, no names.
|
|
|
|
---
|
|
|
|
## 18. Cache Storage와 fetch policy
|
|
|
|
### 18.1 existing runtime reuse
|
|
|
|
```text
|
|
src/adapters/cache-storage/public-cache-policy.ts
|
|
src/adapters/cache-storage/public-response-cache-adapter.ts
|
|
```
|
|
|
|
no generic `CacheService`.
|
|
|
|
### 18.2 cache name
|
|
|
|
```text
|
|
ca-static-v1-<first-16-lower-hex-of-staticAssetSetDigest>
|
|
```
|
|
|
|
parser requires exact prefix, schema literal and 16 hex chars.
|
|
|
|
### 18.3 embedded static asset manifest
|
|
|
|
Vite virtual modules:
|
|
|
|
```text
|
|
virtual:ca-service-worker-assets
|
|
virtual:ca-service-worker-build-info
|
|
```
|
|
|
|
```ts
|
|
export interface StaticAssetManifestV1 {
|
|
readonly schemaVersion: 1;
|
|
readonly buildId: string;
|
|
readonly releaseId: string;
|
|
readonly setDigest: `sha256:${string}`;
|
|
readonly assets: readonly Readonly<{
|
|
url: string;
|
|
sha256: `sha256:${string}`;
|
|
bytes: number;
|
|
contentType: string;
|
|
}>[];
|
|
}
|
|
```
|
|
|
|
worker does not fetch a manifest endpoint.
|
|
|
|
### 18.4 manifest inclusion
|
|
|
|
include only:
|
|
|
|
- Vite immutable hashed JS/CSS assets;
|
|
- approved font/image assets with immutable hashed URL;
|
|
- worker-owned static metadata.
|
|
|
|
exclude:
|
|
|
|
```text
|
|
index.html
|
|
runtime config
|
|
release manifest
|
|
API response
|
|
user/account data
|
|
telemetry/auth endpoint
|
|
source map unless explicitly public
|
|
unhashed mutable asset
|
|
cross-origin opaque response
|
|
```
|
|
|
|
### 18.5 fetch classification order
|
|
|
|
```text
|
|
non-GET -> network passthrough
|
|
navigation request -> network-only
|
|
runtime config URL -> network-only
|
|
release manifest URL -> network-only
|
|
exact static asset manifest hit -> verified cache-first
|
|
all other requests -> network passthrough
|
|
```
|
|
|
|
API base can be `/`; exact static hit is evaluated before generic network passthrough.
|
|
|
|
### 18.6 cache hit validation
|
|
|
|
- exact URL;
|
|
- method GET;
|
|
- only build-generated query if manifest contains it;
|
|
- cached marker matches set digest;
|
|
- status 200;
|
|
- content type exact normalized match;
|
|
- no opaque response;
|
|
- expected byte count;
|
|
- install-time integrity verified.
|
|
|
|
invalid hit is deleted and treated as release mismatch/network fetch. It is not returned stale.
|
|
|
|
### 18.7 cache miss
|
|
|
|
runtime fetch success is returned but not written into active cache. Static cache population is install-time only.
|
|
|
|
missing immutable asset:
|
|
|
|
```text
|
|
network failure/404
|
|
-> release mismatch classification
|
|
-> page chunk recovery path
|
|
```
|
|
|
|
### 18.8 navigation
|
|
|
|
baseline has no offline shell.
|
|
|
|
- navigation network-only;
|
|
- cached `index.html` fallback prohibited;
|
|
- network error uses browser/app boot failure;
|
|
- stale HTML and new assets/contractSet never intentionally mix;
|
|
- installability/offline document is a separate product capability.
|
|
|
|
### 18.9 quota
|
|
|
|
- asset set hard max 5MiB;
|
|
- `StorageManager.estimate()` is advisory only;
|
|
- actual `QuotaExceededError` is authoritative;
|
|
- install quota failure deletes candidate;
|
|
- existing current/previous cache retained;
|
|
- no browser file/OPFS/outbox cleanup to make room;
|
|
- user data has higher priority than recomputable static cache.
|
|
|
|
### 18.10 reset
|
|
|
|
`CACHE_RESET_REQUEST` requires:
|
|
|
|
- controlled same-origin client;
|
|
- current protocol;
|
|
- one-time nonce;
|
|
- user/incident action;
|
|
- owned prefix parser.
|
|
|
|
reset deletes static caches only. registration remains. reload after reset is user/guarded action.
|
|
|
|
---
|
|
|
|
## 19. Offline Command와 Background Sync
|
|
|
|
### 19.1 capability status
|
|
|
|
baseline product selection remains `NOT_SELECTED`.
|
|
|
|
reference runtime can be implemented without composing a product operation. It must not create DB/listener when unselected.
|
|
|
|
### 19.2 scope
|
|
|
|
Offline Command is for durable user command retry after foreground interruption. It is not:
|
|
|
|
- Query persistence;
|
|
- arbitrary request cache;
|
|
- background execution guarantee;
|
|
- exactly-once guarantee;
|
|
- event queue;
|
|
- file upload checkpoint replacement.
|
|
|
|
### 19.3 external prerequisite consumption
|
|
|
|
an operation is queueable only when external package contribution provides:
|
|
|
|
```text
|
|
retrySemantics = KEYED
|
|
commandRecovery non-null
|
|
stable input validator/projection
|
|
stable operation identity
|
|
runtime validator for terminal result/problem
|
|
```
|
|
|
|
frontend does not define server idempotency or inspect protocol.
|
|
|
|
### 19.4 source layout
|
|
|
|
```text
|
|
src/application/ports/offline-command/
|
|
offline-command-port.ts
|
|
src/contracts/offline-command.ts
|
|
src/adapters/offline-command/
|
|
offline-command-codec.ts
|
|
indexeddb-offline-command-repository.ts
|
|
offline-command-drain.ts
|
|
offline-command-lifecycle.ts
|
|
offline-command-summary.ts
|
|
```
|
|
|
|
existing generic IndexedDB runtime is reused as dataset backend.
|
|
|
|
### 19.5 installed contribution
|
|
|
|
```ts
|
|
export interface InstalledOfflineCommandContribution {
|
|
readonly datasetId: "OFFLINE_COMMANDS_V1";
|
|
readonly operations: readonly InstalledOfflineOperation[];
|
|
}
|
|
|
|
export interface InstalledOfflineOperation {
|
|
readonly operationId: string;
|
|
readonly contractPackageId: string;
|
|
readonly maximumRequestBytes: number;
|
|
readonly retentionClass: "STANDARD_7D";
|
|
}
|
|
```
|
|
|
|
bounds:
|
|
|
|
```text
|
|
operations 64
|
|
single request 256 KiB
|
|
hard single request 1 MiB
|
|
records 1,000
|
|
dataset bytes 50 MiB
|
|
```
|
|
|
|
### 19.6 record
|
|
|
|
```ts
|
|
export interface OfflineCommandRecordV1 {
|
|
readonly recordVersion: 1;
|
|
readonly commandId: string;
|
|
readonly operationId: string;
|
|
readonly contractPackageId: string;
|
|
readonly contractPackageVersion: string;
|
|
readonly contractPackageDigest: `sha256:${string}`;
|
|
readonly scopePartition: string;
|
|
readonly requestDigest: `sha256:${string}`;
|
|
readonly requestPayload: Uint8Array;
|
|
readonly idempotencyKey: string;
|
|
readonly state: OfflineCommandState;
|
|
readonly attempt: number;
|
|
readonly createdAt: string;
|
|
readonly updatedAt: string;
|
|
readonly nextAttemptAt?: string;
|
|
readonly leaseOwner?: string;
|
|
readonly leaseExpiresAt?: string;
|
|
readonly terminalCode?: string;
|
|
}
|
|
```
|
|
|
|
```ts
|
|
export type OfflineCommandState =
|
|
| "PENDING"
|
|
| "LEASED"
|
|
| "FOREGROUND_REQUIRED"
|
|
| "SENDING"
|
|
| "RETRY_WAIT"
|
|
| "ACKED"
|
|
| "CONFLICT"
|
|
| "EFFECT_UNKNOWN"
|
|
| "EXPIRED";
|
|
```
|
|
|
|
### 19.7 physical storage
|
|
|
|
- opaque DB/dataset name from existing governance;
|
|
- account/session scope partition binding;
|
|
- transaction-complete is write success;
|
|
- record codec V1 strict;
|
|
- future schema fail closed/read-only;
|
|
- blocked/versionchange typed;
|
|
- no credential/token except opaque idempotency key;
|
|
- request payload minimized to exact package request projection;
|
|
- no raw URL/header.
|
|
|
|
### 19.8 enqueue
|
|
|
|
```text
|
|
scope current
|
|
-> operation allowlist
|
|
-> package identity current
|
|
-> package input validator
|
|
-> deterministic request encode
|
|
-> request bytes/digest
|
|
-> create idempotency key
|
|
-> dataset count/byte admission
|
|
-> one IDB transaction insert + counters
|
|
-> PENDING
|
|
```
|
|
|
|
same user intent duplicate uses feature/mutation coordinator before enqueue. Repository does not silently merge by payload digest.
|
|
|
|
### 19.9 sender topology
|
|
|
|
origin/account partition has one sender lease.
|
|
|
|
```text
|
|
lease TTL 30s
|
|
renew every 10s
|
|
batch count 10
|
|
batch window 30s
|
|
parallel send 1
|
|
```
|
|
|
|
foreground tabs coordinate through existing cross-context hint and IndexedDB lease CAS. BroadcastChannel is hint, IDB lease is local authority.
|
|
|
|
### 19.10 state transitions
|
|
|
|
```text
|
|
PENDING -> LEASED -> SENDING
|
|
SENDING -> ACKED
|
|
SENDING -> RETRY_WAIT
|
|
SENDING -> CONFLICT
|
|
SENDING -> EFFECT_UNKNOWN
|
|
PENDING/RETRY_WAIT -> FOREGROUND_REQUIRED
|
|
PENDING/RETRY_WAIT/FOREGROUND_REQUIRED -> EXPIRED
|
|
```
|
|
|
|
invalid transitions are corruption.
|
|
|
|
### 19.11 transaction boundaries
|
|
|
|
before network:
|
|
|
|
```text
|
|
IDB transaction:
|
|
verify current state
|
|
verify lease owner/live
|
|
increment attempt
|
|
state=SENDING
|
|
write operation attempt identity
|
|
commit
|
|
```
|
|
|
|
after terminal response:
|
|
|
|
```text
|
|
validate/map/effect classify
|
|
-> IDB transaction terminal/retry state commit
|
|
-> lease release
|
|
```
|
|
|
|
### 19.12 crash recovery
|
|
|
|
expired `LEASED` before send:
|
|
|
|
```text
|
|
safe -> PENDING
|
|
```
|
|
|
|
expired `SENDING`:
|
|
|
|
```text
|
|
EFFECT_UNKNOWN
|
|
```
|
|
|
|
never reset SENDING to PENDING automatically.
|
|
|
|
### 19.13 foreground drain triggers
|
|
|
|
```text
|
|
startup
|
|
online
|
|
visible
|
|
focus
|
|
manual
|
|
```
|
|
|
|
triggers coalesce into one scheduled drain. hidden page pauses new sends. active send result still settles.
|
|
|
|
### 19.14 auth and package fence
|
|
|
|
before each send:
|
|
|
|
- scope current;
|
|
- credential READY;
|
|
- installed contract package identity exact matches record;
|
|
- operation still installed;
|
|
- request payload revalidated;
|
|
- idempotency key present;
|
|
- total deadline available.
|
|
|
|
failure:
|
|
|
|
```text
|
|
auth unavailable -> FOREGROUND_REQUIRED
|
|
package missing/version/digest mismatch -> FOREGROUND_REQUIRED(CONTRACT_PACKAGE_UNAVAILABLE)
|
|
scope stale -> old partition hidden, no send
|
|
schema invalid -> CONFLICT/terminal corruption review
|
|
```
|
|
|
|
### 19.15 retry
|
|
|
|
retryable response/failure is package/HTTP runtime decision.
|
|
|
|
```text
|
|
base delay 1s
|
|
max delay 5m
|
|
full jitter
|
|
attempt cap 10
|
|
```
|
|
|
|
Retry-After is lower bound up to 5m.
|
|
|
|
never retry:
|
|
|
|
- contract/schema/mapper failure;
|
|
- effect maybe applied;
|
|
- auth unavailable;
|
|
- conflict;
|
|
- expired retention.
|
|
|
|
attempt cap -> `FOREGROUND_REQUIRED(RETRY_EXHAUSTED)`, not silent drop.
|
|
|
|
### 19.16 effect unknown
|
|
|
|
```text
|
|
automatic send stop
|
|
-> package recovery descriptor
|
|
-> foreground inspect when auth ready
|
|
-> committed: ACKED + canonical refresh
|
|
-> no effect: PENDING only after explicit transition
|
|
-> still unknown: EFFECT_UNKNOWN
|
|
```
|
|
|
|
manual retry button cannot resend EFFECT_UNKNOWN directly.
|
|
|
|
### 19.17 retention
|
|
|
|
```text
|
|
PENDING/RETRY_WAIT/FOREGROUND_REQUIRED max age 7d
|
|
ACKED payload delete immediately; safe summary 24h
|
|
CONFLICT/EFFECT_UNKNOWN payload max 30d
|
|
EXPIRED payload delete; safe summary 7d
|
|
```
|
|
|
|
30d 이후 unresolved payload를 자동 send하지 않는다.
|
|
|
|
### 19.18 Background Sync baseline
|
|
|
|
Background Sync is optional wake-up.
|
|
|
|
```text
|
|
sync tag = ca-outbox-v1
|
|
```
|
|
|
|
register only when:
|
|
|
|
- service worker handler `OFFLINE_SYNC_WAKEUP` selected;
|
|
- `registration.sync` exists;
|
|
- pending/foreground-required record exists;
|
|
- no in-flight same tag;
|
|
- last registration >= 1 minute.
|
|
|
|
sync handler:
|
|
|
|
```text
|
|
1. inspect bounded outbox metadata
|
|
2. update wakeRequestedAt
|
|
3. post SYNC_WAKE_OBSERVED to controlled clients
|
|
4. send authenticated command = 0
|
|
5. resolve handler
|
|
```
|
|
|
|
### 19.19 foreground fallback
|
|
|
|
Background Sync unsupported/fails/never fires is normal.
|
|
|
|
foreground triggers remain required. Queue semantics are identical with or without native Sync.
|
|
|
|
### 19.20 future worker send explicitly excluded
|
|
|
|
Service Worker authenticated send requires separate future design covering:
|
|
|
|
- worker-safe credential owner;
|
|
- no credential persistence;
|
|
- refresh/revocation;
|
|
- package validators in worker bundle;
|
|
- effect reconciliation;
|
|
- logout/version fence;
|
|
- platform execution limitations;
|
|
- user recovery.
|
|
|
|
until then worker send code is prohibited.
|
|
|
|
### 19.21 safe summary
|
|
|
|
```ts
|
|
export interface OfflineCommandSummary {
|
|
readonly commandId: string;
|
|
readonly operationLabelKey: string;
|
|
readonly state: OfflineCommandState;
|
|
readonly createdAt: string;
|
|
readonly nextAction:
|
|
| "WAIT"
|
|
| "OPEN_APP"
|
|
| "CHECK_STATUS"
|
|
| "RESOLVE_CONFLICT"
|
|
| "CONTACT_SUPPORT"
|
|
| "DISMISS";
|
|
}
|
|
```
|
|
|
|
raw payload, idempotency key, package digest, account partition are not exposed to UI.
|
|
|
|
### 19.22 removal
|
|
|
|
```text
|
|
1. new enqueue close
|
|
2. drain stop
|
|
3. active send settle/lease expire
|
|
4. unresolved count inspect
|
|
5. product recovery/export decision
|
|
6. selected dataset only delete when safe
|
|
7. sync registration stop
|
|
8. SW sync handler remove
|
|
9. composition remove
|
|
```
|
|
|
|
unresolved user command is not silently purged with source deletion.
|
|
|
|
---
|
|
## 20. 공통 start·stop·dispose
|
|
|
|
### 20.1 lifecycle interface
|
|
|
|
```ts
|
|
export interface RuntimeLifecycle {
|
|
start(): void | Promise<void>;
|
|
stop(reason: RuntimeStopReason): void | Promise<void>;
|
|
dispose(): void | Promise<void>;
|
|
}
|
|
|
|
export type RuntimeStopReason =
|
|
| "APPLICATION_SHUTDOWN"
|
|
| "SCOPE_FENCED"
|
|
| "FEATURE_DISABLED"
|
|
| "HIDDEN_POLICY"
|
|
| "INCIDENT_CONTAINMENT";
|
|
```
|
|
|
|
invariants:
|
|
|
|
- `start()` idempotent;
|
|
- concurrent start returns same promise;
|
|
- start failure cleans partial resource and state `FAILED`;
|
|
- `stop()` is restartable quiesce unless capability says terminal;
|
|
- `dispose()` terminal;
|
|
- dispose after dispose no-op;
|
|
- start after dispose throws typed lifecycle error;
|
|
- concurrent stop/dispose has one settlement;
|
|
- cleanup error aggregation does not skip remaining cleanup.
|
|
|
|
### 20.2 runtime lifecycle states
|
|
|
|
```text
|
|
NEW
|
|
STARTING
|
|
RUNNING
|
|
STOPPING
|
|
STOPPED
|
|
FAILED
|
|
DISPOSING
|
|
DISPOSED
|
|
```
|
|
|
|
allowed transitions:
|
|
|
|
```text
|
|
NEW -> STARTING -> RUNNING
|
|
STARTING -> FAILED
|
|
RUNNING -> STOPPING -> STOPPED
|
|
STOPPED -> STARTING
|
|
NEW/STOPPED/FAILED/RUNNING -> DISPOSING -> DISPOSED
|
|
```
|
|
|
|
`FAILED -> STARTING` automatic transition is prohibited. Explicit owner recovery creates a new runtime instance or calls a named reset method.
|
|
|
|
### 20.3 application shutdown order
|
|
|
|
```text
|
|
1. close new navigation/mutation/optional admission
|
|
2. stop Service Worker page controller/cleanup action
|
|
3. close Web Worker task admission
|
|
4. cooperative cancel/terminate Web Workers
|
|
5. stop realtime subscriptions/reconnect and drain
|
|
6. stop offline foreground drain and release lease
|
|
7. dispose client scope runtime
|
|
8. clear conditional validator store
|
|
9. dispose invalidation coordinator
|
|
10. cancel and clear QueryClient
|
|
11. close cross-context transport
|
|
12. dispose session subscription
|
|
13. telemetry flush up to deadline
|
|
14. diagnostics dispose
|
|
```
|
|
|
|
QueryClient를 realtime보다 먼저 clear하지 않는다. late realtime effect가 cleared cache를 다시 채우는 race를 막는다.
|
|
|
|
### 20.4 browser lifecycle owner
|
|
|
|
window listener owner:
|
|
|
|
```text
|
|
src/adapters/platform/browser-lifecycle.ts
|
|
```
|
|
|
|
single listener set:
|
|
|
|
```text
|
|
visibilitychange
|
|
online
|
|
offline
|
|
focus
|
|
pagehide
|
|
pageshow
|
|
beforeunload only while dirty state exists
|
|
```
|
|
|
|
capability별 direct window listener를 추가하지 않는다.
|
|
|
|
```ts
|
|
export interface BrowserLifecycleSnapshot {
|
|
readonly visibility: "VISIBLE" | "HIDDEN";
|
|
readonly connectivityHint: "ONLINE" | "OFFLINE";
|
|
readonly pageState: "ACTIVE" | "PAGEHIDE" | "BFCACHE_RESTORED";
|
|
readonly generation: number;
|
|
}
|
|
```
|
|
|
|
### 20.5 pagehide and bfcache
|
|
|
|
`pagehide persisted=true`:
|
|
|
|
- terminal dispose하지 않음;
|
|
- lifecycle state `SUSPENDED` projection;
|
|
- realtime transport close;
|
|
- offline new send pause;
|
|
- active Worker follows task cancellation policy;
|
|
- Query memory remains;
|
|
- Service Worker registration remains;
|
|
- no blocking telemetry flush.
|
|
|
|
`pageshow persisted=true`:
|
|
|
|
```text
|
|
1. browser lifecycle generation increment
|
|
2. Release Manifest V2 no-store refresh once
|
|
3. scope current check
|
|
4. active Query refetch
|
|
5. realtime authoritative recovery
|
|
6. offline expired lease recovery
|
|
7. duplicate listener/runtime check
|
|
```
|
|
|
|
manifest incompatible면 product runtime을 resume하지 않고 safe reload/recovery surface로 이동한다.
|
|
|
|
### 20.6 unload non-guarantee
|
|
|
|
다음을 `beforeunload`, `unload`, `sendBeacon` correctness로 처리하지 않는다.
|
|
|
|
- command complete;
|
|
- checkpoint write;
|
|
- subscription unsubscribe guarantee;
|
|
- lease release guarantee;
|
|
- Service Worker activation acknowledgement;
|
|
- telemetry guaranteed delivery.
|
|
|
|
correctness is transaction/TTL/recovery based.
|
|
|
|
### 20.7 cleanup deadlines
|
|
|
|
```text
|
|
realtime drain 2,000ms
|
|
worker cooperative stop 250ms per active group
|
|
telemetry flush 1,000ms
|
|
offline local lease release 2,000ms
|
|
Service Worker page stop no network wait
|
|
overall application stop 5,000ms
|
|
```
|
|
|
|
overall deadline expires:
|
|
|
|
- remaining worker terminate;
|
|
- transport close;
|
|
- listener/timer remove;
|
|
- unresolved durable state left for recovery;
|
|
- no additional network retry.
|
|
|
|
### 20.8 scope fence vs shutdown
|
|
|
|
scope fence:
|
|
|
|
- application remains alive;
|
|
- global Router/QueryClient object remains;
|
|
- account-bound data/listener/connection fenced;
|
|
- new scope READY after reset.
|
|
|
|
shutdown:
|
|
|
|
- all admission terminal close;
|
|
- no new scope;
|
|
- every runtime disposed.
|
|
|
|
두 lifecycle을 같은 `clearEverything()`로 합치지 않는다.
|
|
|
|
---
|
|
|
|
## 21. Security와 privacy
|
|
|
|
### 21.1 trust boundary
|
|
|
|
trusted build inputs:
|
|
|
|
```text
|
|
exact installed contract package bytes
|
|
frontend source
|
|
embedded contractSet identity
|
|
embedded static asset manifest
|
|
```
|
|
|
|
untrusted runtime inputs:
|
|
|
|
```text
|
|
Runtime Config bytes until validated
|
|
Release Manifest bytes until validated
|
|
HTTP response/problem
|
|
realtime frame/event
|
|
postMessage
|
|
IndexedDB historical record
|
|
Cache Storage response
|
|
URL/path/search/form input
|
|
```
|
|
|
|
trusted package does not make server response trusted. Runtime validation remains mandatory.
|
|
|
|
### 21.2 secret prohibition
|
|
|
|
must not contain credential/secret:
|
|
|
|
```text
|
|
Runtime Config
|
|
Release Manifest
|
|
contractSet
|
|
Query key/value
|
|
Web Storage
|
|
IndexedDB query metadata
|
|
Cache Storage
|
|
Worker message
|
|
Service Worker message
|
|
realtime checkpoint diagnostics
|
|
URL
|
|
telemetry attributes
|
|
support reference
|
|
```
|
|
|
|
offline outbox may store opaque idempotency key but treats it as sensitive command identity:
|
|
|
|
- no log;
|
|
- no UI;
|
|
- no cross-context message;
|
|
- delete with payload retention.
|
|
|
|
### 21.3 generated package isolation
|
|
|
|
contract package must:
|
|
|
|
- have no required postinstall script;
|
|
- perform no network/DOM/listener side effect on import;
|
|
- expose descriptor/validator/type only;
|
|
- have no mutable singleton carrying user state;
|
|
- not reference `window`, `document`, `navigator`, `fetch`, WebSocket at runtime;
|
|
- not include credential helper;
|
|
- not provide user-facing error copy.
|
|
|
|
violation blocks contribution composition.
|
|
|
|
### 21.4 boot request security
|
|
|
|
- same-origin Runtime Config/release manifest;
|
|
- redirect error;
|
|
- no credentials beyond same-origin browser policy;
|
|
- no-store;
|
|
- strict content type;
|
|
- byte bound;
|
|
- secret-name scan;
|
|
- safe error only;
|
|
- no arbitrary manifest URL from query/local storage.
|
|
|
|
### 21.5 HTTP security
|
|
|
|
- HTTPS outside local;
|
|
- final URL allowlist;
|
|
- redirect reject;
|
|
- `referrerPolicy=no-referrer`;
|
|
- credential patch allowlist;
|
|
- raw URL/query/body/header no logs;
|
|
- response byte bound;
|
|
- duplicate JSON key semantics not relied upon;
|
|
- prototype pollution keys rejected/stripped by validator/mapper;
|
|
- problem detail rendered through safe text;
|
|
- `dangerouslySetInnerHTML` forbidden.
|
|
|
|
### 21.6 Router security
|
|
|
|
- open redirect forbidden;
|
|
- return URL created only by same-origin route builder;
|
|
- route param validation before domain ID;
|
|
- frontend access guard not authorization proof;
|
|
- chunk URL not user-generated;
|
|
- search data not interpolated into raw HTML/style/script;
|
|
- malformed route causes local failure before network.
|
|
|
|
### 21.7 Query/cache security
|
|
|
|
- cache hit not authorization;
|
|
- old scope value hidden immediately at FENCED;
|
|
- raw IDs/URL/document/message absent from key;
|
|
- credential/header/trace absent from value;
|
|
- query persistence disabled;
|
|
- production devtools governed by build profile;
|
|
- optimistic layer excludes full command body/token.
|
|
|
|
### 21.8 Cross-context security
|
|
|
|
- no data/query key;
|
|
- opaque topic/source;
|
|
- protocol/epoch validation;
|
|
- `storageArea` exact check;
|
|
- message bytes bound;
|
|
- foreign/malformed event ignored;
|
|
- channel name not based on account ID;
|
|
- event is hint, not authority.
|
|
|
|
### 21.9 Realtime security
|
|
|
|
- exact endpoint/profile allowlist;
|
|
- frame/event bounds;
|
|
- envelope/payload validation;
|
|
- scope binding;
|
|
- unknown event safe recovery;
|
|
- cursor/endpoint/push subscription absent from diagnostics;
|
|
- no arbitrary WebSocket outbound command;
|
|
- open connection not auth success;
|
|
- raw close reason not user/log.
|
|
|
|
### 21.10 Worker security
|
|
|
|
- module worker static URL;
|
|
- Blob/data URL worker forbidden;
|
|
- `eval`, `Function`, dynamic `importScripts` forbidden;
|
|
- no credential/network;
|
|
- cloned payload validator;
|
|
- input/output bounds;
|
|
- generation/request fence;
|
|
- SharedArrayBuffer disabled;
|
|
- WASM only as separate exact-digest/memory-bound task capability.
|
|
|
|
### 21.11 Service Worker security
|
|
|
|
- same-origin scope/script;
|
|
- source client ID/origin/nonce validation;
|
|
- no blind skipWaiting/clients.claim;
|
|
- API/private response cache forbidden;
|
|
- opaque cache forbidden;
|
|
- owned prefix/parser cleanup only;
|
|
- global variable not durable authority;
|
|
- push payload validator and notification registry;
|
|
- notification URL registered same-origin route only;
|
|
- foreign registration never unregistered.
|
|
|
|
### 21.12 IndexedDB/outbox privacy
|
|
|
|
- opaque physical DB name;
|
|
- scope binding;
|
|
- historical codec validation;
|
|
- package digest recheck;
|
|
- quota/corrupt/future schema separated;
|
|
- logout old partition hidden immediately;
|
|
- same-origin encryption not XSS authorization boundary;
|
|
- payload minimization;
|
|
- retention ceiling;
|
|
- unresolved command export/recovery product-owned.
|
|
|
|
### 21.13 diagnostics redaction
|
|
|
|
prohibited values:
|
|
|
|
```text
|
|
raw URL/query
|
|
request/response body
|
|
header/token/cookie
|
|
account/resource ID
|
|
event payload/cursor
|
|
idempotency key
|
|
contract package source path
|
|
cache key/value
|
|
worker payload
|
|
file name/path
|
|
```
|
|
|
|
allowed dimensions are closed enums and bounded IDs declared in §22.
|
|
|
|
---
|
|
|
|
## 22. Runtime observability
|
|
|
|
### 22.1 ownership
|
|
|
|
existing diagnostics/telemetry adapters are reused.
|
|
|
|
```text
|
|
src/adapters/diagnostics/bounded-diagnostics.ts
|
|
src/adapters/telemetry/best-effort-telemetry.ts
|
|
src/contracts/diagnostics.ts
|
|
src/contracts/telemetry.ts
|
|
```
|
|
|
|
raw SDK is not exposed to feature/application.
|
|
|
|
### 22.2 closed event families
|
|
|
|
```text
|
|
frontend_boot
|
|
frontend_http
|
|
frontend_query
|
|
frontend_mutation
|
|
frontend_scope
|
|
frontend_realtime
|
|
frontend_worker
|
|
frontend_service_worker
|
|
frontend_offline_command
|
|
frontend_drop
|
|
```
|
|
|
|
new arbitrary event name is prohibited. Add a typed registry entry first.
|
|
|
|
### 22.3 common attributes
|
|
|
|
allowlisted:
|
|
|
|
```text
|
|
operationCategory
|
|
outcome
|
|
failureKind
|
|
appEnv
|
|
buildId bucket/release reference
|
|
featureId
|
|
operationId declared stable ID
|
|
profileId
|
|
transportKind
|
|
browserEngine bucket
|
|
queueSize bucket
|
|
payloadSize bucket
|
|
attempt bucket
|
|
lifecycleState
|
|
```
|
|
|
|
not allowlisted:
|
|
|
|
```text
|
|
URL
|
|
user/account/resource ID
|
|
request ID from server
|
|
cursor/checkpoint
|
|
package digest full value
|
|
idempotency key
|
|
message/error string
|
|
```
|
|
|
|
contract package digest may be represented only as `MATCH | MISMATCH | MISSING`, not tag value.
|
|
|
|
### 22.4 HTTP observation
|
|
|
|
one logical operation terminal event plus bounded physical attempt counters.
|
|
|
|
```text
|
|
logical operation ID
|
|
attempt count bucket
|
|
terminal outcome
|
|
certainty
|
|
request/response size bucket
|
|
latency bucket
|
|
retry reason category
|
|
```
|
|
|
|
physical attempts do not each emit high-cardinality traces by default.
|
|
|
|
### 22.5 Query observation
|
|
|
|
```text
|
|
profileId
|
|
cache state: MISS | FRESH | STALE | REFRESH
|
|
result budget: ADMITTED | REJECTED
|
|
scope current: CURRENT | FENCED
|
|
```
|
|
|
|
query key/input/value absent.
|
|
|
|
### 22.6 Mutation observation
|
|
|
|
```text
|
|
duplicate policy
|
|
duplicate outcome
|
|
optimistic used boolean
|
|
effect certainty
|
|
invalidation result
|
|
recovery state
|
|
```
|
|
|
|
intent/idempotency identity absent.
|
|
|
|
### 22.7 Realtime observation
|
|
|
|
```text
|
|
streamId stable registry ID
|
|
eventType stable registry ID
|
|
transport
|
|
state transition
|
|
reconnect attempt bucket
|
|
queue bucket
|
|
recovery reason
|
|
validation outcome
|
|
effect outcome
|
|
```
|
|
|
|
cursor/payload/endpoint absent.
|
|
|
|
### 22.8 Worker observation
|
|
|
|
```text
|
|
taskGroupId
|
|
taskId
|
|
queue bucket
|
|
input/output size bucket
|
|
latency bucket
|
|
cancel/crash/restart outcome
|
|
fallback mode
|
|
```
|
|
|
|
payload and native stack absent.
|
|
|
|
### 22.9 Service Worker observation
|
|
|
|
```text
|
|
mode
|
|
handler set bitmask or closed enum
|
|
registration outcome
|
|
update state
|
|
client drain outcome
|
|
cache install/reset outcome
|
|
owned removal outcome
|
|
```
|
|
|
|
scope/script URL/cache name absent. ownership mismatch is a boolean/outcome only.
|
|
|
|
### 22.10 Offline observation
|
|
|
|
```text
|
|
state transition
|
|
attempt bucket
|
|
age bucket
|
|
queue count/byte bucket
|
|
lease outcome
|
|
terminal/recovery category
|
|
sync wake observed boolean
|
|
```
|
|
|
|
operation label uses stable operation ID; no payload/key/partition.
|
|
|
|
### 22.11 bounded queue and failure
|
|
|
|
telemetry is best effort.
|
|
|
|
```text
|
|
maximum queued events 500
|
|
maximum estimated bytes 1 MiB
|
|
flush batch 50
|
|
shutdown flush 1s
|
|
drop oldest non-critical observation when full
|
|
never block product flow
|
|
never recursively report sink failure
|
|
```
|
|
|
|
security/contract fatal events can be mirrored to bounded local diagnostics but do not gain infinite retention.
|
|
|
|
### 22.12 health semantics
|
|
|
|
frontend does not expose one global `healthy` boolean.
|
|
|
|
```ts
|
|
export type RuntimeHealth =
|
|
| "AVAILABLE"
|
|
| "DEGRADED"
|
|
| "UNAVAILABLE"
|
|
| "INCOMPATIBLE"
|
|
| "DISABLED";
|
|
```
|
|
|
|
capability health is independent:
|
|
|
|
- HTTP unavailable does not mark Router unavailable;
|
|
- realtime fatal can fall back to explicit stale/polling policy;
|
|
- Service Worker disabled does not fail product;
|
|
- offline outbox conflict does not mean IndexedDB runtime globally corrupt;
|
|
- contractSet mismatch is boot incompatible.
|
|
|
|
---
|
|
|
|
## 23. 구현 검증
|
|
|
|
### 23.1 범위
|
|
|
|
이 절은 local/unit/component/integration/real-browser behavior를 정의한다. CI stage, workflow, promotion formula는 정의하지 않는다.
|
|
|
|
### 23.2 Runtime Config/boot cases
|
|
|
|
```text
|
|
valid V2
|
|
unknown field reject
|
|
API_CONTRACT_VERSION in V2 reject
|
|
secret-like key reject
|
|
URL credential/hash/query reject
|
|
HTTPS rule
|
|
config 64KiB exact and +1
|
|
manifest 1MiB exact and +1
|
|
Content-Length lie
|
|
chunked overflow
|
|
invalid UTF-8
|
|
invalid JSON/media/status
|
|
5s timeout
|
|
redirect reject
|
|
build/release/assets mismatch
|
|
contractSet canonical/digest mismatch
|
|
fixture excluded from contractSet
|
|
partial composition reverse cleanup
|
|
retry once/no loop
|
|
```
|
|
|
|
### 23.3 contract package consumer cases
|
|
|
|
```text
|
|
only contribution file imports package
|
|
exact version/integrity
|
|
packageId/version/digest/source regex
|
|
runtime protocol mismatch
|
|
package duplicate/mismatch
|
|
duplicate operation/event
|
|
status sorted unique/subset
|
|
path/query/hash bound
|
|
validator missing/throw
|
|
fixture exact identity/events empty
|
|
product local fixture reject
|
|
package top-level side-effect fixture reject
|
|
```
|
|
|
|
### 23.4 HTTP cases
|
|
|
|
```text
|
|
request validation before fetch
|
|
final invariant after auth patch
|
|
request 256KiB/default and hard +1
|
|
response/problem byte bounds
|
|
redirect/media/status/body policy
|
|
required/optional/none body
|
|
success/problem validator
|
|
scope fence before/after response
|
|
safe/idempotent retry
|
|
keyed dispatch-loss no retry
|
|
never retry
|
|
full jitter deterministic source
|
|
Retry-After ceiling/deadline
|
|
401 no hidden replay
|
|
caller/route/scope/deadline cancellation
|
|
NOT_STARTED vs MAYBE_APPLIED
|
|
inspect recovery projection
|
|
```
|
|
|
|
### 23.5 Router cases
|
|
|
|
```text
|
|
static route registration
|
|
lazy module
|
|
path/search codec duplicate/unknown/bounds
|
|
no direct fetch/QueryClient/adapter import
|
|
loader/action server-data reject
|
|
focus/scroll/title
|
|
route unmount lease cleanup
|
|
chunk release/contractSet recovery
|
|
reload guard once
|
|
dirty navigation/effect-unknown blocker
|
|
```
|
|
|
|
### 23.6 Query/scope cases
|
|
|
|
```text
|
|
one QueryClient
|
|
fixed profile registry only
|
|
required measureResult
|
|
measure throw/non-finite/negative/overflow
|
|
item/byte ceiling
|
|
scope FENCED synchronous
|
|
old snapshot immediately false
|
|
cancel/clear/validator/realtime/offline exact ordering
|
|
late success discarded
|
|
identity bounds/active lease eviction
|
|
retry false
|
|
memory-only/no persistence
|
|
304 with/without current cache
|
|
```
|
|
|
|
### 23.7 Mutation cases
|
|
|
|
```text
|
|
three duplicate policies
|
|
same input different scope not joined
|
|
join waiter bound
|
|
optimistic default none
|
|
layer count/single/total bytes
|
|
out-of-order commit/rollback
|
|
effect unknown no arbitrary rollback
|
|
success seed/invalidation ordering
|
|
local invalidation failure does not resend
|
|
form dirty state clearing only confirmed
|
|
```
|
|
|
|
### 23.8 Cross-context cases
|
|
|
|
```text
|
|
registry bounds/fanout/fanin
|
|
no key/data on wire
|
|
BroadcastChannel primary
|
|
localStorage fallback/storageArea
|
|
same-tab local dispatch
|
|
duplicate/lower/gap
|
|
release/scope epoch
|
|
mutation coalescing
|
|
overflow full stale
|
|
logout/dispose leak
|
|
two-page Chromium/Firefox/WebKit semantics
|
|
```
|
|
|
|
### 23.9 Realtime cases
|
|
|
|
```text
|
|
zero contribution no connection/listener
|
|
one host/multiple leases
|
|
OPEN_UNRESUMED no effect
|
|
recovery barrier
|
|
500ms/30s/10/5m/60s reconnect policy
|
|
offline wait
|
|
hidden 30s/no hidden poll
|
|
visible recovery
|
|
unknown/malformed/schema/mapper/scope
|
|
64KiB event +1
|
|
queue/dedupe bounds
|
|
conflict/gap/expired cursor
|
|
single-writer live/poll handoff
|
|
effect before checkpoint
|
|
checkpoint failure after effect -> recovery
|
|
5s subscription grace
|
|
StrictMode acquire/release
|
|
logout/dispose/bfcache
|
|
```
|
|
|
|
### 23.10 Generic Worker cases
|
|
|
|
```text
|
|
unselected no worker
|
|
protocol/version/generation
|
|
input/output bounds
|
|
queue count/bytes/FIFO
|
|
queued cancellation
|
|
active cooperative cancellation
|
|
250ms terminate
|
|
stale result fence
|
|
transfer ownership/detached buffer
|
|
crash 3/5m then fatal
|
|
idle 60s
|
|
fallback exact
|
|
no network/DOM/credential
|
|
```
|
|
|
|
### 23.11 Service Worker cases
|
|
|
|
```text
|
|
null selection no lookup/register/cache
|
|
ACTIVE first-render idempotent registration
|
|
module/scope/updateViaCache
|
|
ACTIVE+DISABLED exact-owned unregister/cache retain
|
|
foreign registration ownership mismatch
|
|
ACTIVE -> REMOVE -> PURGE -> null
|
|
install all-or-nothing
|
|
asset count/item/set/integrity/media
|
|
waiting no blind skipWaiting
|
|
dirty/effect-unknown activation block
|
|
multi-client drain/30s missing client
|
|
no clients.claim
|
|
first install reload-to-enable
|
|
update 6h/manual rate
|
|
controllerchange guard
|
|
network-only navigation/config/manifest/API
|
|
exact static hit before API base root
|
|
unknown GET no runtime cache
|
|
current+previous retention
|
|
owned parser cleanup only
|
|
Web Push handler composition
|
|
future protocol mismatch
|
|
```
|
|
|
|
### 23.12 Offline/Sync cases
|
|
|
|
```text
|
|
unselected no DB/listener
|
|
operation not KEYED/recovery missing reject
|
|
package identity/digest
|
|
request/count/dataset bounds
|
|
transaction complete
|
|
lease acquire/renew/release/takeover
|
|
LEASED expiry -> PENDING
|
|
SENDING expiry -> EFFECT_UNKNOWN
|
|
single sender/batch 10/30s
|
|
retry/backoff/attempt cap
|
|
auth/package/scope fence
|
|
ACKED payload delete
|
|
retention
|
|
unsupported Sync foreground works
|
|
Sync event sends zero command
|
|
wake message only
|
|
crash/reload restore
|
|
no credential persistence
|
|
removal unresolved command no silent purge
|
|
```
|
|
|
|
### 23.13 browser result vocabulary
|
|
|
|
```text
|
|
SUPPORTED_AND_PASSED
|
|
SUPPORTED_AND_FAILED
|
|
UNSUPPORTED_WITH_FALLBACK_PASSED
|
|
UNSUPPORTED_WITHOUT_REQUIRED_CAPABILITY
|
|
ENVIRONMENT_UNAVAILABLE
|
|
```
|
|
|
|
unsupported is not ordinary pass. Background Sync requires foreground fallback pass.
|
|
|
|
### 23.14 leak inspection
|
|
|
|
lifecycle suite terminal checks:
|
|
|
|
```text
|
|
active listeners = 0 except declared singleton
|
|
active timers = 0
|
|
open generic workers = 0
|
|
open realtime transports = 0
|
|
subscription refs = 0
|
|
queued worker/realtime task = 0
|
|
active IDB transaction = 0
|
|
owned abort controller settled
|
|
unhandled rejection = 0
|
|
```
|
|
|
|
persistent Service Worker registration is inspected according to selection mode, not counted as generic leak.
|
|
|
|
---
|
|
|
|
## 24. Source 배치와 migration
|
|
|
|
### 24.1 existing files to modify
|
|
|
|
```text
|
|
src/bootstrap/runtime-config-schema.ts
|
|
src/bootstrap/load-runtime-config.ts
|
|
src/bootstrap/load-release-manifest.ts
|
|
src/bootstrap/create-runtime-composition.ts
|
|
src/bootstrap/composition-root.ts
|
|
src/bootstrap/runtime-adapters.ts
|
|
src/bootstrap/runtime-application.tsx
|
|
src/bootstrap/main.tsx
|
|
src/contracts/env.ts
|
|
src/contracts/release-tokens.ts
|
|
src/contracts/storage-keys.ts
|
|
src/contracts/api-operations.ts
|
|
src/contracts/rest-profiles.ts
|
|
src/contracts/server-state.ts
|
|
src/contracts/server-state-scope.ts
|
|
src/contracts/query-invalidation.ts
|
|
src/contracts/realtime-events.ts
|
|
src/contracts/realtime-streams.ts
|
|
src/adapters/http/bounded-json.ts
|
|
src/adapters/http/client.ts
|
|
src/adapters/http/request-builder.ts
|
|
src/adapters/http/retry-policy.ts
|
|
src/adapters/query-cache/server-state-scope-runtime.ts
|
|
src/adapters/query-cache/tanstack-cache-coordinator.ts
|
|
src/adapters/cross-context-invalidation/browser-cross-context-host.ts
|
|
src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts
|
|
src/adapters/cross-context-invalidation/index.ts
|
|
src/presentation/adapters/query/application-query.ts
|
|
src/presentation/adapters/query/optimistic-layer-runtime.ts
|
|
src/presentation/routes/app-router.tsx
|
|
src/presentation/routes/navigation-policy.ts
|
|
src/presentation/routes/platform-route-codecs.ts
|
|
src/presentation/routes/route-codecs.ts
|
|
src/presentation/routes/route-contract.ts
|
|
src/presentation/routes/route-input.tsx
|
|
src/presentation/routes/route-runtime.tsx
|
|
src/features/installed-feature-contracts.ts
|
|
src/features/installed-feature-adapters.ts
|
|
src/features/installed-feature-runtimes.tsx
|
|
scripts/generate-build-manifest.ts
|
|
vite.config.ts
|
|
tsconfig.json
|
|
tsconfig.app.json
|
|
package.json
|
|
.gitignore
|
|
eslint.config.ts
|
|
vitest.config.ts
|
|
playwright.capabilities.config.ts
|
|
config/hosting/cache-policy.json
|
|
public/config.json
|
|
public/release-manifest.json
|
|
```
|
|
|
|
### 24.2 new common files
|
|
|
|
```text
|
|
src/contracts/contract-set.ts
|
|
src/contracts/contract-set-canonical.ts
|
|
src/contracts/external-contract-runtime.ts
|
|
src/contracts/runtime-capabilities.ts
|
|
src/contracts/service-worker.ts
|
|
src/contracts/web-worker.ts
|
|
src/contracts/offline-command.ts
|
|
src/bootstrap/read-bounded-boot-json.ts
|
|
src/bootstrap/register-service-worker.ts
|
|
src/features/installed-contract-contributions.ts
|
|
src/features/installed-runtime-capabilities.ts
|
|
src/adapters/http/bounded-body-reader.ts
|
|
src/adapters/http/http-execution-v3.ts
|
|
src/adapters/http/http-effect-certainty.ts
|
|
src/adapters/http/http-contract-bridge.ts
|
|
src/adapters/platform/browser-lifecycle.ts
|
|
scripts/build-frontend.ts
|
|
scripts/generate-contract-set.ts
|
|
scripts/generate-service-worker-assets.ts
|
|
vite.service-worker.config.ts
|
|
tsconfig.web-worker.json
|
|
tsconfig.service-worker.json
|
|
.generated/frontend-runtime/contract-set.ts
|
|
.generated/frontend-runtime/service-worker-build-info.ts
|
|
.generated/frontend-runtime/service-worker-assets.ts
|
|
```
|
|
|
|
`.generated/frontend-runtime`은 build-time derived source다. 사람이 수정하지 않고 build 시작 시 전체 삭제 후 재생성한다. Git에 commit하지 않는다.
|
|
|
|
### 24.3 optional source files
|
|
|
|
Generic Worker selected only:
|
|
|
|
```text
|
|
src/application/ports/web-worker/*
|
|
src/adapters/web-worker/*
|
|
```
|
|
|
|
Service Worker active/removal selected:
|
|
|
|
```text
|
|
src/adapters/service-worker/*
|
|
```
|
|
|
|
Offline Commands selected only:
|
|
|
|
```text
|
|
src/application/ports/offline-command/*
|
|
src/adapters/offline-command/*
|
|
```
|
|
|
|
### 24.4 feature files
|
|
|
|
```text
|
|
src/features/<feature>/contracts/<service>-contract-contribution.ts
|
|
src/features/<feature>/contracts/<feature>-mapper.ts
|
|
src/features/<feature>/contracts/<feature>-realtime-contribution.ts
|
|
src/features/<feature>/adapters/<feature>-http-gateway.ts
|
|
src/features/<feature>/application/<feature>-api.ts
|
|
src/features/<feature>/presentation/use-<feature>.ts
|
|
```
|
|
|
|
path token replacement is deterministic.
|
|
|
|
```text
|
|
<feature> = InstalledContractContribution.featureId exactly
|
|
lowercase kebab-case regex already validated
|
|
|
|
<service> = external package name의 slash 뒤 segment
|
|
lowercase npm segment 그대로
|
|
```
|
|
|
|
팀이 임의 abbreviation/pluralization을 선택하지 않는다. 파일 충돌이 나면 package contribution을 한 feature 안의 named subdirectory로 분리하되 token 자체를 바꾸지 않는다.
|
|
|
|
### 24.5 architecture rule amendments
|
|
|
|
static checks must reject:
|
|
|
|
```text
|
|
@org-contracts import outside feature contract contribution
|
|
presentation direct fetch
|
|
presentation direct adapters/QueryClient
|
|
application React/TanStack/browser API
|
|
generic Worker fetch/WebSocket/EventSource
|
|
separate Service Worker registration
|
|
Service Worker API response cache
|
|
runtime deployed spec/registry lookup
|
|
product TEMPLATE_FIXTURE
|
|
Router loader/action server-data call
|
|
```
|
|
|
|
### 24.6 Runtime Config/manifest migration
|
|
|
|
```text
|
|
RC-1 add V2 schema/parser and bounded reader
|
|
RC-2 support V1/V2 reader, current writer V1
|
|
RC-3 generate contractSet and writer V2
|
|
RC-4 ignore accepted V1 scalar only in V1 input
|
|
RC-5 all fixtures/public files V2
|
|
RC-6 remove V1 parser/scalar after compatibility window
|
|
```
|
|
|
|
### 24.7 HTTP migration
|
|
|
|
```text
|
|
HTTP-1 normalize current local reference fixture into contribution
|
|
HTTP-2 introduce external package contribution interface
|
|
HTTP-3 bridge current ApiOperationV2 reader
|
|
HTTP-4 add execution V3/outcome/certainty
|
|
HTTP-5 move feature gateway one operation at a time
|
|
HTTP-6 remove duplicate local path/status/type
|
|
HTTP-7 retire V2 writer after all installed operations V3
|
|
```
|
|
|
|
### 24.8 Query migration
|
|
|
|
```text
|
|
Q-1 fixed profile registry
|
|
Q-2 required measureResult for current reference definitions
|
|
Q-3 scope lifecycle FENCED/READY
|
|
Q-4 commit fence/result budget
|
|
Q-5 many-to-many invalidation registry
|
|
Q-6 mutation duplicate/optimistic exact policies
|
|
```
|
|
|
|
### 24.9 Realtime migration
|
|
|
|
```text
|
|
RT-1 keep common source unchanged where possible
|
|
RT-2 external event contract bridge
|
|
RT-3 feature effect contribution
|
|
RT-4 optional runtime host integration
|
|
RT-5 no product selection -> no bootstrap composition
|
|
```
|
|
|
|
### 24.10 Service Worker migration/removal
|
|
|
|
first adoption:
|
|
|
|
```text
|
|
SW-1 protocol/build-info virtual module
|
|
SW-2 physical entry/handler composition
|
|
SW-3 static asset manifest/cache
|
|
SW-4 page controller/waiting/drain
|
|
SW-5 first-install/update lifecycle
|
|
```
|
|
|
|
removal:
|
|
|
|
```text
|
|
Release N mode ACTIVE
|
|
Release N+1 mode REMOVE_REGISTRATION
|
|
Release N+2 mode PURGE_OWNED_RESOURCES after rollback window
|
|
Release N+3 null
|
|
```
|
|
|
|
### 24.11 optional source zero-side-effect
|
|
|
|
optional source may exist as `AVAILABLE_NOT_COMPOSED`, but production bootstrap import is absent unless static selection references it.
|
|
|
|
Vite module inventory must show:
|
|
|
|
- unselected worker entry absent;
|
|
- unselected Service Worker active entry absent;
|
|
- unselected offline adapter absent from production runtime graph where tree-shaking/static import boundary permits;
|
|
- recipe/test source is not production import.
|
|
|
|
### 24.12 sample/reference removal
|
|
|
|
removing `src/features/reference-feature` must not remove common runtime.
|
|
|
|
removal sequence:
|
|
|
|
```text
|
|
reference feature directory
|
|
-> reference template contribution
|
|
-> reference route/messages/runtime registration
|
|
-> reference tests
|
|
-> no remaining import/string in production bundle
|
|
```
|
|
|
|
common external contract consumer interfaces remain.
|
|
|
|
---
|
|
|
|
## 25. 구현 순서와 stop condition
|
|
|
|
### 25.1 principle
|
|
|
|
각 phase는 independently reviewable runtime increment다. API/backend contract authoring과 CI workflow는 이 순서에 포함하지 않는다.
|
|
|
|
### Phase A — authority cleanup
|
|
|
|
1. old generic design을 non-authoritative로 표시;
|
|
2. this document reference add;
|
|
3. external package ownership boundary document;
|
|
4. current source path inventory freeze.
|
|
|
|
stop condition:
|
|
|
|
- current repository snapshot/path가 문서와 다르면 후속 code 금지;
|
|
- contract package format이 library design과 다르면 contribution interface부터 amend.
|
|
|
|
### Phase B — contract package consumer foundation
|
|
|
|
1. `RuntimeValidator` adapter;
|
|
2. normalized contribution types;
|
|
3. installed contribution composer;
|
|
4. fixture vs external provenance;
|
|
5. validation/duplicate checks;
|
|
6. reference fixture normalization.
|
|
|
|
exit:
|
|
|
|
- package import one path;
|
|
- product fixture prohibited;
|
|
- no runtime network/package lookup.
|
|
|
|
### Phase C — contractSet and boot V2
|
|
|
|
1. canonical bytes/digest;
|
|
2. Release Manifest V2 schema;
|
|
3. bounded boot reader;
|
|
4. Runtime Config V2;
|
|
5. contractSet boot check;
|
|
6. partial cleanup stack;
|
|
7. public fixture migration.
|
|
|
|
exit:
|
|
|
|
- scalar API contract version no longer writer source;
|
|
- boot body bounded/deadline;
|
|
- product mount gated by contractSet.
|
|
|
|
### Phase D — HTTP execution V3
|
|
|
|
1. request/response hard ceilings;
|
|
2. package descriptor bridge;
|
|
3. final invariant after credential patch;
|
|
4. outcome/failure union;
|
|
5. total deadline/retry owner;
|
|
6. effect certainty;
|
|
7. current reference operation migration.
|
|
|
|
exit:
|
|
|
|
- direct/duplicate path/status schema removed for migrated operation;
|
|
- keyed uncertain command never automatic replayed.
|
|
|
|
### Phase E — Router/Query/Mutation lifecycle
|
|
|
|
1. Router no-server-data rule;
|
|
2. fixed Query profiles;
|
|
3. required measureResult;
|
|
4. scope FENCED/READY exact ordering;
|
|
5. commit fence;
|
|
6. invalidation many-to-many;
|
|
7. duplicate mutation coordinator;
|
|
8. bounded optimistic layers.
|
|
|
|
exit:
|
|
|
|
- old scope late result cannot commit;
|
|
- Query/Mutation retry false;
|
|
- local invalidation failure cannot resend command.
|
|
|
|
### Phase F — Cross-context
|
|
|
|
1. registry bounds;
|
|
2. protocol/epoch envelope;
|
|
3. BroadcastChannel;
|
|
4. localStorage fallback;
|
|
5. gap/full-stale;
|
|
6. scope/logout lifecycle.
|
|
|
|
exit:
|
|
|
|
- no data/key on wire;
|
|
- two-page semantics;
|
|
- disposal leak zero.
|
|
|
|
### Phase G — Realtime product bridge
|
|
|
|
1. external event validator bridge;
|
|
2. installed realtime contribution;
|
|
3. host lifecycle;
|
|
4. subscription lease bridge;
|
|
5. recovery/effect/checkpoint ordering;
|
|
6. no-selection zero side effect.
|
|
|
|
stop condition:
|
|
|
|
- no exact endpoint/event/recovery contribution -> remain `NOT_SELECTED`;
|
|
- common runtime is not enough to compose.
|
|
|
|
### Phase H — Generic Worker optional
|
|
|
|
execute only when a selected task exists.
|
|
|
|
1. task port/protocol;
|
|
2. group worker runtime;
|
|
3. queue/cancel/crash;
|
|
4. fallback;
|
|
5. browser behavior.
|
|
|
|
stop condition:
|
|
|
|
- no profiling/owner/task contribution -> do not implement production entry.
|
|
|
|
### Phase I — Service Worker reference runtime
|
|
|
|
1. static selection/removal mode;
|
|
2. one physical entry;
|
|
3. protocol/registration;
|
|
4. static cache;
|
|
5. waiting/client drain;
|
|
6. first install/update;
|
|
7. runtime disabled unregister;
|
|
8. removal cleanup.
|
|
|
|
exit:
|
|
|
|
- no API/navigation cache;
|
|
- no blind activation/claim;
|
|
- persistent removal path proven.
|
|
|
|
### Phase J — Offline Command optional
|
|
|
|
execute only when product operation is selected.
|
|
|
|
1. operation allowlist/record codec;
|
|
2. IDB repository;
|
|
3. foreground sender lease;
|
|
4. state transitions;
|
|
5. effect unknown recovery;
|
|
6. retention/summary;
|
|
7. optional Sync wake handler;
|
|
8. removal.
|
|
|
|
stop condition:
|
|
|
|
- no KEYED+recovery package descriptor -> remain `NOT_SELECTED`;
|
|
- no product conflict/recovery UX -> do not compose.
|
|
|
|
### Phase K — final integration review
|
|
|
|
1. lifecycle shutdown/bfcache;
|
|
2. security/redaction;
|
|
3. all behavior cases;
|
|
4. source/path/document consistency;
|
|
5. old compatibility reader removal only after no caller.
|
|
|
|
---
|
|
|
|
## 26. 완료 기준
|
|
|
|
### 26.1 common
|
|
|
|
- current repository path/architecture retained;
|
|
- no parallel platform layer;
|
|
- no backend/API/event source ownership duplication;
|
|
- no CI design included;
|
|
- optional unselected side effect zero;
|
|
- exact lifecycle/disposal;
|
|
- bounded input/output/queue/deadline;
|
|
- typed failure and uncertainty;
|
|
- current scope fence;
|
|
- secret/privacy rules;
|
|
- source/removal path.
|
|
|
|
### 26.2 external contract consumer
|
|
|
|
- exact immutable package pin;
|
|
- one import location;
|
|
- fixture/product provenance separated;
|
|
- normalized descriptor/validator;
|
|
- package validation bounds;
|
|
- local product schema duplication absent;
|
|
- runtime registry/deployed docs lookup absent;
|
|
- mapper boundary.
|
|
|
|
### 26.3 contractSet/boot
|
|
|
|
- V2 manifest;
|
|
- canonical length-prefixed digest;
|
|
- fixture excluded;
|
|
- Runtime Config scalar removed;
|
|
- 64KiB/1MiB/5s bounded read;
|
|
- strict URL/media/JSON/schema;
|
|
- reverse partial cleanup;
|
|
- safe retry once.
|
|
|
|
### 26.4 HTTP
|
|
|
|
- package descriptor-driven;
|
|
- request/response bounds;
|
|
- final invariant after auth;
|
|
- redirect reject;
|
|
- total deadline;
|
|
- transport-only retry;
|
|
- body/status/media validation;
|
|
- effect certainty;
|
|
- keyed uncertainty no automatic resend;
|
|
- scope fence.
|
|
|
|
### 26.5 Router
|
|
|
|
- static route/codec;
|
|
- no server-data loader/action;
|
|
- no direct fetch/cache;
|
|
- lazy/focus/scroll/error;
|
|
- chunk contractSet recovery;
|
|
- dirty/effect-unknown blocker.
|
|
|
|
### 26.6 Query/Mutation
|
|
|
|
- one QueryClient;
|
|
- fixed profiles;
|
|
- required result measurement;
|
|
- scope exact reset order;
|
|
- late result discard;
|
|
- memory-only;
|
|
- bounded identity/invalidation;
|
|
- duplicate coordinator;
|
|
- optimistic default none/bounded layer;
|
|
- success/failure ordering.
|
|
|
|
### 26.7 Realtime
|
|
|
|
- existing common runtime reused;
|
|
- product contribution exact;
|
|
- open/resume separated;
|
|
- reconnect policy exact;
|
|
- hidden/offline lifecycle;
|
|
- validation pipeline;
|
|
- queue/dedupe bounds;
|
|
- gap recovery;
|
|
- effect-before-checkpoint;
|
|
- ref-counted cleanup;
|
|
- zero selection side effect.
|
|
|
|
### 26.8 Generic Worker
|
|
|
|
- explicit selected task;
|
|
- semantic port;
|
|
- one worker per group;
|
|
- protocol validation;
|
|
- queue/input/output/deadline;
|
|
- cancellation/terminate;
|
|
- crash budget;
|
|
- stale fence;
|
|
- no network/credential;
|
|
- fallback exact.
|
|
|
|
### 26.9 Service Worker
|
|
|
|
- one physical registration;
|
|
- post-mount module registration;
|
|
- build/protocol handshake;
|
|
- all-or-nothing static cache;
|
|
- navigation/API/config/manifest network-only;
|
|
- waiting/client drain;
|
|
- no blind skipWaiting/clients.claim;
|
|
- first install reload-to-enable;
|
|
- runtime disabled exact unregister;
|
|
- ACTIVE→REMOVE→PURGE→null;
|
|
- foreign resource protection.
|
|
|
|
### 26.10 Offline/Background Sync
|
|
|
|
- product operation selected;
|
|
- external KEYED/recovery descriptor;
|
|
- IDB transaction-complete;
|
|
- exact bounds;
|
|
- single sender lease;
|
|
- SENDING crash -> EFFECT_UNKNOWN;
|
|
- no automatic unknown resend;
|
|
- foreground fallback;
|
|
- Sync wake only;
|
|
- retention/recovery/removal.
|
|
|
|
---
|
|
|
|
## 27. 위험 등록부
|
|
|
|
| ID | 위험 | 차단 결정 | 잔여 위험 |
|
|
| --- | --- | --- | --- |
|
|
| FRT-R001 | frontend local API schema가 두 번째 SSOT | external package one import/provenance | package publication quality는 external owner |
|
|
| FRT-R002 | scalar contract version으로 multi-service mismatch | contractSet V2 | provider compatibility는 external release system |
|
|
| FRT-R003 | boot body memory amplification | streaming byte bound/deadline | browser/network implementation variance |
|
|
| FRT-R004 | auth patch가 URL/method/header 변조 | final invariant recheck | external auth adapter defect |
|
|
| FRT-R005 | duplicate retry amplification | HTTP-only retry owner | user repeated intent remains product UX |
|
|
| FRT-R006 | command timeout duplicate effect | MAYBE_APPLIED/inspect/no resend | server inspect may remain unavailable |
|
|
| FRT-R007 | Router/Query dual cache | loader server-data prohibition | future SSR requires separate design |
|
|
| FRT-R008 | old account late result leak | synchronous scope FENCED/commit fence | third-party widget outside scope |
|
|
| FRT-R009 | result memory blowup | required measure/fixed profiles | feature estimator defect |
|
|
| FRT-R010 | cross-tab stale data replication | hint-only protocol | hints can be lost; refetch recovery |
|
|
| FRT-R011 | reconnect storm | full jitter/attempt/episode bounds | provider-wide outage |
|
|
| FRT-R012 | connection open mistaken as recovered | OPEN_UNRESUMED/barrier | server recovery semantics external |
|
|
| FRT-R013 | malformed event corrupts state | validator/mapper/gap recovery | malicious volume before edge controls |
|
|
| FRT-R014 | subscription leak under StrictMode | ref-count + 5s grace | browser process crash |
|
|
| FRT-R015 | Worker queue/crash heap amplification | exact bounds/restart budget | heavy task still impacts CPU/battery |
|
|
| FRT-R016 | multiple Service Worker registrations | one physical entry | existing foreign registration conflict |
|
|
| FRT-R017 | stale worker mixed with new page | drain/no claim/reload handshake | user may postpone update |
|
|
| FRT-R018 | service worker removed from source but persists | staged removal modes | clients not revisiting app remain registered |
|
|
| FRT-R019 | Cache Storage poisoning/stale HTML | static manifest only/no navigation cache | immutable asset host misconfiguration |
|
|
| FRT-R020 | offline command duplicate after crash | SENDING->EFFECT_UNKNOWN | external reconciliation may need human |
|
|
| FRT-R021 | Background Sync assumed reliable | wake-only/foreground fallback | browser may throttle background work |
|
|
| FRT-R022 | logout leaves old durable data visible | scope partition fence | physical cleanup may be delayed |
|
|
| FRT-R023 | diagnostics leak | closed allowlist/redaction | vendor SDK internal behavior |
|
|
| FRT-R024 | bfcache resumes stale release | manifest refresh/recovery | offline manifest fetch unavailable |
|
|
| FRT-R025 | over-design installs optional capability unused | static selection/stop conditions | future teams may bypass process |
|
|
|
|
---
|
|
|
|
## 28. Normative decision ledger
|
|
|
|
| Decision ID | 결정 | 정본 |
|
|
| --- | --- | --- |
|
|
| FRT-D001 | 기존 repository layers 유지 | §1.1–§1.2 |
|
|
| FRT-D002 | backend/API/event source design 제외 | §0.3 |
|
|
| FRT-D003 | CI design 제외 | §0.4 |
|
|
| FRT-D004 | immutable external package only | §4 |
|
|
| FRT-D005 | package import one feature contribution path | §4.1 |
|
|
| FRT-D006 | template fixture HTTP-only and contractSet excluded | §4.8–§4.9 |
|
|
| FRT-D007 | scalar API contract version removed | §5.1 |
|
|
| FRT-D008 | length-prefixed contractSet canonical digest | §5.3 |
|
|
| FRT-D009 | Runtime Config may disable, never enable source-absent capability | §3.5, §6.1 |
|
|
| FRT-D010 | boot 64KiB/1MiB/5s | §6.4–§6.5 |
|
|
| FRT-D011 | boot reverse cleanup | §6.8 |
|
|
| FRT-D012 | descriptor-driven HTTP execution | §7.1–§7.2 |
|
|
| FRT-D013 | request/response hard bounds | §7.3 |
|
|
| FRT-D014 | transport-only retry | §8.1 |
|
|
| FRT-D015 | 250ms/2s/full-jitter/max2 HTTP retry | §8.2 |
|
|
| FRT-D016 | 401 no hidden replay | §8.4 |
|
|
| FRT-D017 | dispatch loss MAYBE_APPLIED | §8.7–§8.9 |
|
|
| FRT-D018 | Router server-data loader/action prohibited | §9.2 |
|
|
| FRT-D019 | one QueryClient | §10.1 |
|
|
| FRT-D020 | four fixed Query profiles | §10.2 |
|
|
| FRT-D021 | required feature-owned measureResult, no fallback | §10.3–§10.4 |
|
|
| FRT-D022 | synchronous scope FENCED exact order | §10.5–§10.6 |
|
|
| FRT-D023 | Query persistence disabled | §10.10 |
|
|
| FRT-D024 | mutation duplicate default reject | §11.2 |
|
|
| FRT-D025 | optimistic default none, layer bounds | §11.4–§11.5 |
|
|
| FRT-D026 | cross-tab hint-only, many-to-many bounds | §12 |
|
|
| FRT-D027 | existing realtime runtime reused | §13.1 |
|
|
| FRT-D028 | product realtime explicit contribution | §13.2–§13.6 |
|
|
| FRT-D029 | single writer live XOR polling | §13.8 |
|
|
| FRT-D030 | OPEN_UNRESUMED separate | §14.1–§14.2 |
|
|
| FRT-D031 | realtime reconnect 500ms/30s/10/5m/60s | §14.3 |
|
|
| FRT-D032 | hidden 30s then close, no hidden polling | §14.5 |
|
|
| FRT-D033 | event hard limits reuse current constants | §15.1 |
|
|
| FRT-D034 | effect before checkpoint | §15.7 |
|
|
| FRT-D035 | subscription 5s grace, scope immediate | §15.8–§15.9 |
|
|
| FRT-D036 | generic Worker default not selected | §16.2 |
|
|
| FRT-D037 | one Worker per group, lazy/60s idle | §16.5 |
|
|
| FRT-D038 | Worker queue/cancel/crash exact policy | §16.8–§16.10 |
|
|
| FRT-D039 | Worker no network/credential | §16.13 |
|
|
| FRT-D040 | one physical Service Worker | §17.1 |
|
|
| FRT-D041 | Service Worker after first committed render | §17.5 |
|
|
| FRT-D042 | ACTIVE/REMOVE/PURGE/null lifecycle | §17.3 |
|
|
| FRT-D043 | disabled exact-owned unregister, cache retained | §17.6 |
|
|
| FRT-D044 | no blind skipWaiting, no clients.claim | §17.10–§17.12 |
|
|
| FRT-D045 | static asset cache only | §18 |
|
|
| FRT-D046 | navigation/API/config/manifest network-only | §18.5–§18.8 |
|
|
| FRT-D047 | Offline queue selected only with KEYED recovery package | §19.3 |
|
|
| FRT-D048 | offline records 1000/50MiB/256KiB | §19.5 |
|
|
| FRT-D049 | sender lease 30s/renew10s/batch10/30s | §19.9 |
|
|
| FRT-D050 | SENDING crash -> EFFECT_UNKNOWN | §19.12 |
|
|
| FRT-D051 | Background Sync wake-only | §19.18 |
|
|
| FRT-D052 | lifecycle shutdown exact order | §20.3 |
|
|
| FRT-D053 | no unload correctness | §20.6 |
|
|
| FRT-D054 | closed diagnostics allowlist | §22 |
|
|
| FRT-D055 | behavior verification separate from CI | §23 |
|
|
| FRT-D056 | implementation phase stop conditions | §25 |
|
|
|
|
---
|
|
|
|
## 부록 A. Numeric constants
|
|
|
|
### A.1 Boot
|
|
|
|
| Constant | Value |
|
|
| --- | ---: |
|
|
| Runtime Config bytes | 65,536 |
|
|
| Release Manifest bytes | 1,048,576 |
|
|
| each boot request deadline | 5,000ms |
|
|
| boot retry count | 1 |
|
|
| manifest URL bytes | 256 |
|
|
|
|
### A.2 HTTP
|
|
|
|
| Constant | Value |
|
|
| --- | ---: |
|
|
| default request | 262,144 bytes |
|
|
| hard request | 1,048,576 bytes |
|
|
| default response | 1,048,576 bytes |
|
|
| hard response | 8,388,608 bytes |
|
|
| problem body | 65,536 bytes |
|
|
| query string | 8,192 bytes |
|
|
| final URL | 16,384 bytes |
|
|
| default deadline | 10,000ms |
|
|
| hard deadline | 60,000ms |
|
|
| retry base | 250ms |
|
|
| retry local max | 2,000ms |
|
|
| Retry-After max | 5,000ms |
|
|
| retries | 2 |
|
|
|
|
### A.3 Query
|
|
|
|
| Profile | stale | gc | items | bytes |
|
|
| --- | ---: | ---: | ---: | ---: |
|
|
| DETAIL_STANDARD | 30s | 5m | 1 | 256KiB |
|
|
| LIST_STANDARD | 15s | 5m | 200 | 1MiB |
|
|
| LOOKUP_STABLE | 5m | 30m | 500 | 2MiB |
|
|
| VOLATILE_STATUS | 0 | 1m | 1 | 64KiB |
|
|
|
|
identity registry:
|
|
|
|
| Constant | Value |
|
|
| --- | ---: |
|
|
| depth | 12 |
|
|
| nodes | 512 |
|
|
| string bytes | 2,048 |
|
|
| identity bytes | 16,384 |
|
|
| entries | 4,096 |
|
|
| canonical memory | 4MiB |
|
|
|
|
### A.4 Invalidation
|
|
|
|
| Constant | Value |
|
|
| --- | ---: |
|
|
| topics | 256 |
|
|
| namespaces | 256 |
|
|
| edges | 1,024 |
|
|
| topic fan-out | 64 |
|
|
| namespace fan-in | 64 |
|
|
| pulse bytes | 1,024 |
|
|
| pulse TTL | 60s |
|
|
|
|
### A.5 Realtime
|
|
|
|
| Constant | Value |
|
|
| --- | ---: |
|
|
| event bytes | 64KiB |
|
|
| payload depth | 16 |
|
|
| payload nodes | 4,096 |
|
|
| queue events | 256 |
|
|
| queue bytes | 4MiB |
|
|
| dedupe entries | 2,048 |
|
|
| dedupe bytes | 4MiB |
|
|
| dedupe TTL | 10m |
|
|
| reconnect base | 500ms |
|
|
| reconnect max | 30s |
|
|
| attempts | 10 |
|
|
| episode | 5m |
|
|
| stable reset | 60s |
|
|
| hidden grace | 30s |
|
|
| subscription grace | 5s |
|
|
| stream drain | 2s |
|
|
|
|
### A.6 Web Worker
|
|
|
|
| Constant | Value |
|
|
| --- | ---: |
|
|
| groups | 16 |
|
|
| tasks/group | 32 |
|
|
| active groups | 4 |
|
|
| queued/group | 32 |
|
|
| queued bytes/group | 16MiB |
|
|
| default input/output | 1MiB |
|
|
| hard input/output | 8MiB |
|
|
| default deadline | 5s |
|
|
| hard deadline | 30s |
|
|
| cancel grace | 250ms |
|
|
| idle terminate | 60s |
|
|
| restarts | 3/5m |
|
|
| transferables | 16 |
|
|
|
|
### A.7 Service Worker/static cache
|
|
|
|
| Constant | Value |
|
|
| --- | ---: |
|
|
| assets | 256 |
|
|
| single asset | 2MiB |
|
|
| set | 5MiB |
|
|
| fetch concurrency | 4 |
|
|
| install deadline | 60s |
|
|
| client drain | 30s |
|
|
| update check | 6h |
|
|
| retained previous cache | 1 |
|
|
|
|
### A.8 Offline Commands
|
|
|
|
| Constant | Value |
|
|
| --- | ---: |
|
|
| operations | 64 |
|
|
| default request | 256KiB |
|
|
| hard request | 1MiB |
|
|
| records | 1,000 |
|
|
| dataset | 50MiB |
|
|
| sender lease | 30s |
|
|
| renew | 10s |
|
|
| batch | 10 |
|
|
| batch window | 30s |
|
|
| parallel send | 1 |
|
|
| retry base | 1s |
|
|
| retry max | 5m |
|
|
| attempts | 10 |
|
|
| ordinary retention | 7d |
|
|
| conflict/unknown | 30d |
|
|
| Sync re-register minimum | 1m |
|
|
|
|
---
|
|
|
|
## 부록 B. 금지 구현 목록
|
|
|
|
```text
|
|
create src/platform/* parallel runtime
|
|
copy OpenAPI/AsyncAPI/JSON Schema into product frontend
|
|
import backend Java DTO/module
|
|
fetch deployed /v3/api-docs during build/runtime
|
|
resolve Schema Registry latest at runtime
|
|
use mutable package tag/range
|
|
let component/hook call raw fetch/socket/Worker/IndexedDB
|
|
let Router loader create server cache or fetch
|
|
enable TanStack retry while HTTP transport retries
|
|
retry keyed command after dispatched response loss
|
|
interpret abort as server rollback
|
|
store generated wire DTO directly in Query cache
|
|
use JSON.stringify as generic Query result size fallback
|
|
persist Query payload in Web Storage by default
|
|
broadcast Query key/data/input/cursor
|
|
open one realtime connection per component
|
|
apply event before validation/scope/gap checks
|
|
write checkpoint before effect
|
|
continue applying deltas after gap/overflow
|
|
use hidden polling automatically
|
|
create generic Worker for network I/O
|
|
allow Worker credential/fetch/WebSocket
|
|
create Blob/data URL Worker
|
|
register PWA and Web Push workers separately for same scope
|
|
call skipWaiting without client drain
|
|
call clients.claim in baseline
|
|
cache index.html navigation fallback
|
|
cache API/private/auth responses in Cache Storage
|
|
treat unregister as cache deletion
|
|
switch Service Worker ACTIVE directly to null
|
|
unregister foreign registration by scope prefix guess
|
|
send authenticated command from baseline Background Sync
|
|
reset expired SENDING record to PENDING
|
|
manual resend EFFECT_UNKNOWN without inspect
|
|
store token/URL/header/cursor in diagnostics
|
|
use unload/sendBeacon as correctness boundary
|
|
claim unsupported browser capability as pass
|
|
claim COMPOSED means production/provider-ready
|
|
```
|
|
|
|
---
|
|
|
|
## 부록 C. 플랫폼 참고 기준
|
|
|
|
구현 시 pinned browser/library version의 공식 문서를 다시 확인하되 본 문서의 repository decision을 임의 변경하지 않는다.
|
|
|
|
- Fetch Standard: <https://fetch.spec.whatwg.org/>
|
|
- HTML — Web Workers: <https://html.spec.whatwg.org/multipage/workers.html>
|
|
- WebSockets Standard: <https://websockets.spec.whatwg.org/>
|
|
- HTML — Server-sent events: <https://html.spec.whatwg.org/multipage/server-sent-events.html>
|
|
- Service Workers: <https://w3c.github.io/ServiceWorker/>
|
|
- ServiceWorkerContainer.register: <https://developer.mozilla.org/docs/Web/API/ServiceWorkerContainer/register>
|
|
- Background Synchronization: <https://wicg.github.io/background-sync/spec/>
|
|
- SyncManager: <https://developer.mozilla.org/docs/Web/API/SyncManager>
|
|
- Cache API: <https://developer.mozilla.org/docs/Web/API/Cache>
|
|
- IndexedDB: <https://w3c.github.io/IndexedDB/>
|
|
- TanStack Query v5: <https://tanstack.com/query/v5/docs/framework/react/overview>
|
|
- React Router: <https://reactrouter.com/>
|
|
- React `useSyncExternalStore`: <https://react.dev/reference/react/useSyncExternalStore>
|
|
|
|
---
|
|
|
|
## 최종 판정
|
|
|
|
본 문서는 프론트엔드 저장소가 소유하지 않는 backend/API/event 계약 authoring과 CI orchestration을 제거하고, 현재 코드 구조 안에서 contract package 소비부터 HTTP, Router, Query/Mutation, realtime, Worker, Service Worker와 offline lifecycle까지 구현 결정을 닫는다.
|
|
|
|
구현자는 다음을 다시 선택하지 않는다.
|
|
|
|
```text
|
|
source root
|
|
contract import boundary
|
|
contractSet format/digest
|
|
Runtime Config V2 shape
|
|
boot byte/deadline
|
|
HTTP retry owner/limits
|
|
mutation uncertainty
|
|
Router data ownership
|
|
Query profiles/result measurement
|
|
scope reset order
|
|
cross-tab wire
|
|
realtime reconnect/resume/queue
|
|
subscription cleanup
|
|
Worker topology/bounds
|
|
Service Worker registration/update/removal/cache policy
|
|
offline sender/state/retention
|
|
Background Sync role
|
|
shutdown order
|
|
```
|
|
|
|
외부 contract package가 필요한 의미를 제공하지 않으면 frontend가 가정으로 채우지 않는다. 해당 product contribution은 `NOT_SELECTED` 또는 `INCOMPATIBLE` 상태로 남기며, common runtime 구현은 계속 독립적으로 검증 가능해야 한다.
|