chore: sync the frontend template from ebea300 to af3d8e6
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)
This commit is contained in:
+5
-2
@@ -206,7 +206,7 @@ src/shared/api
|
||||
|
||||
### 1.2 계층 방향
|
||||
|
||||
현재 `config/architecture/layers.json`의 방향을 유지한다.
|
||||
현재 방향을 유지한다. 기준은 `.dependency-cruiser.json` 하나이고 `check:architecture`가 강제한다(`config/architecture/layers.json`은 아무도 읽지 않는 낡은 사본이라 지웠다, 리뷰 12-09).
|
||||
|
||||
```text
|
||||
domain -> domain only
|
||||
@@ -635,6 +635,7 @@ export interface CommandEffectDescriptor<Problem> {
|
||||
status: number;
|
||||
problem: Problem;
|
||||
}>): "NOT_APPLIED" | "APPLIED_CONFIRMED" | "MAYBE_APPLIED";
|
||||
classifyStatus?(status: 401 | 403 | 429): "NOT_APPLIED" | "MAYBE_APPLIED";
|
||||
}
|
||||
```
|
||||
|
||||
@@ -647,6 +648,8 @@ export interface CommandEffectDescriptor<Problem> {
|
||||
- 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
|
||||
@@ -2604,7 +2607,7 @@ export const DEFAULT_REALTIME_RECONNECT_POLICY = Object.freeze({
|
||||
- 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;
|
||||
- valid event/heartbeat를 받고 60s stable open도 지난 뒤에만 attempt counter reset;
|
||||
- offline state에서는 timer 대신 `online` signal을 기다림.
|
||||
|
||||
### 14.4 error classification
|
||||
|
||||
@@ -253,7 +253,9 @@ Cross-origin bearer provider 최소 CORS:
|
||||
- exact allow-origin 목록과 bounded preflight cache
|
||||
- `Authorization`, `Content-Type`, `Idempotency-Key`,
|
||||
`X-Correlation-ID`, 향후 `If-None-Match`, `If-Match` 허용
|
||||
- 필요한 경우 `ETag`, `Retry-After`, request/trace header만 expose
|
||||
- 필요한 경우 `ETag`, `Retry-After`, request/trace header만 expose.
|
||||
`X-Correlation-ID`를 expose하면 V3 실패의 `AppFailure.requestId`가 된다
|
||||
(`src/adapters/http/feature-http-binding.ts`)
|
||||
- redirect login page, HTML error body와 wildcard credential 금지
|
||||
|
||||
## 6. Command와 idempotency
|
||||
@@ -593,6 +595,21 @@ query invalidate hint로만 쓸지 operation별 reducer contract가 필요하다
|
||||
- rate limit key는 principal/tenant/operation과 abuse policy에 binding하며 raw
|
||||
credential/IP를 metric label에 넣지 않는다.
|
||||
|
||||
### 16.1 전송별 재시도·타임아웃 규칙 (2026-09-25 코드 기준)
|
||||
|
||||
같은 이름의 정책이라도 전송마다 동작이 다르다. operation을 다른 전송으로 옮기면
|
||||
이 표로 동작 변화를 확인한다.
|
||||
|
||||
| 규칙 | V3 contract executor (기본 경로) | V2 client (기본 조합에 없음) | Browser RPC |
|
||||
|---|---|---|---|
|
||||
| KEYED 명령 자동 재시도 | 전송 전 실패만 재시도한다. 전송 뒤 실패는 재시도하지 않고 `MAYBE_APPLIED`다. 응답(5xx·429)으로는 재시도하지 않는다 (`src/adapters/http/http-retry-lifecycle.ts` `canRetryTransport`, `isRetryableSemantics`) | 네트워크·타임아웃·429·408/425/502/503/504 뒤 같은 키로 다시 보낸다. 전송 여부를 보지 않는다 (`src/adapters/http/retry-policy.ts` `shouldRetry`) | `KEYED_COMMAND`는 유효한 키가 있고 profile `retryOwner`가 `FRONTEND_ADAPTER`면 `retryableFailures`에서 같은 키로 다시 보낸다 (`src/adapters/browser-rpc/browser-rpc-runtime.ts` `shouldRetry`) |
|
||||
| 재시도 횟수 상한 | min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2) (`http-execution-v3.ts` `retryCeiling`) | `MAX_RETRY_ATTEMPTS`, 기본 2 (`client.ts` `maxRetryAttempts`) | profile `maxAttempts`(시도 횟수), 하드 상한 4 (`src/contracts/browser-rpc.ts` `BROWSER_RPC_HARD_LIMITS`) |
|
||||
| `Retry-After` | 5초를 넘으면 재시도하지 않는다. 이하면 hint에 jitter를 더해 기다린다 (`http-retry-lifecycle.ts` `retryDelayFor`) | 30초를 넘으면 재시도하지 않는다. 이하면 max(backoff, hint)만큼 기다린다 (`retry-policy.ts`) | profile `maxRetryAfterMs`로 잘라 max(backoff, hint)만큼 기다린다. 하드 상한 60초 (`browser-rpc-runtime.ts` `retryDelay`) |
|
||||
| `REQUEST_TIMEOUT_MS` | 상한이다. 계약 `totalDeadlineMs`를 줄이기만 한다 (`runtime-adapters.ts` `requestDeadlineCeilingMs`) | 기본값이다. operation `timeoutMs`가 있으면 그 값을 쓰고, 더 길 수도 있다 (`client.ts` `defaultTimeoutMs`) | 쓰지 않는다. operation `totalDeadlineMs`만 쓴다. 하드 상한 30분 |
|
||||
|
||||
결과 불명 뒤 사용자 재전송은 전송과 무관하게 같은 intent·같은 키를 쓴다
|
||||
(`src/presentation/adapters/query/application-query.ts` `resendUnknownEffect`).
|
||||
|
||||
## 17. Observability와 privacy
|
||||
|
||||
허용되는 공통 dimension:
|
||||
|
||||
@@ -353,8 +353,23 @@ digest 또는 별도 검토된 streaming hash adapter를 사용한다.
|
||||
- one-shot 작은 download는 click handoff 뒤 cross-engine scheduling을 위해 기본
|
||||
30초 grace를 두고 revoke한다. feature/runtime dispose는 grace를 기다리지 않고
|
||||
모든 active lease를 즉시 revoke한다.
|
||||
- preview와 download는 runtime 하나의 lease registry를 같이 쓴다
|
||||
(`src/adapters/browser-files/create-browser-file-runtime.ts:154`, `:163`).
|
||||
lease 개수나 합계 바이트 한도가 차면 둘 다 `LIMIT_EXCEEDED`를
|
||||
`retryable: true`, `recovery: "RETRY"`로 반환한다
|
||||
(`src/adapters/browser-files/object-url-lease.ts:48-73`, `:131-139`). download
|
||||
lease는 grace(`download-delivery-adapter.ts:149`)가 끝나면 풀리므로 잠시 뒤
|
||||
다시 시도하면 된다. Blob 하나가 단일 lease 상한을 넘으면 재시도 불가다.
|
||||
- URL을 global state, IndexedDB, query cache, log, analytics에 보관하지 않는다.
|
||||
- Service Worker에서 object URL을 사용하지 않는다.
|
||||
- 로그아웃·계정 전환에서는 runtime 전체를 dispose한다. browser file runtime은
|
||||
세션을 모른다(`src/adapters/browser-files/create-browser-file-runtime.ts:93`).
|
||||
`runtime.dispose()`(`:177-185`)가 이전 사용자가 고른 File 참조, preview lease,
|
||||
진행 중 download(`download-delivery-adapter.ts:385-391`)를 한 번에 닫는다.
|
||||
runtime을 route·feature보다 오래 사는 곳에서 만들었다면 server-state scope
|
||||
reset participant(`src/adapters/query-cache/server-state-scope-runtime.ts:19`,
|
||||
등록 예 `src/bootstrap/runtime-adapters.ts:410-416`)로 `dispose()`를 등록하고
|
||||
다음 세대에서 새 runtime을 만든다. dispose한 runtime은 다시 쓸 수 없다.
|
||||
- SVG, HTML, untrusted PDF 같은 active content를 same-origin object URL iframe에
|
||||
직접 preview하지 않는다. 별도 격리 origin 또는 안전한 decode/re-encode 결과,
|
||||
아니면 attachment-only 정책을 사용한다.
|
||||
@@ -525,6 +540,14 @@ recipe의 feature-facing `StoredRecord<T>` view model과 혼동하지 않는다.
|
||||
`writtenAtEpochMs`, synchronization, `measuredBytes`, `eligibleAtEpochMs`는 record
|
||||
envelope에 중복 저장하지 않고 `retentionStore` sidecar에 둔다.
|
||||
|
||||
revision은 살아 있는 record 하나 안에서만 순서를 매긴다(D-13). `remove`는 행을
|
||||
tombstone 없이 지우므로 같은 key를 다시 만들면 revision이 1부터 다시 시작한다.
|
||||
그래서 `(key, revision)`은 key의 전체 수명에서 유일하지 않다. 삭제 전에
|
||||
revision N을 읽은 writer는 재생성된 record가 N에 도달하면 `expectedRevision: N`
|
||||
CAS로 그 record를 덮어쓸 수 있다. 이 구분이 필요한 호출자는 revision과 함께
|
||||
자기가 소유한 값(server version, payload 안의 ID)을 비교한다. tombstone으로
|
||||
번호를 이어 가는 방식은 저장 스키마 변경이라 이 템플릿 범위 밖이다.
|
||||
|
||||
- structured clone 성공을 업무 schema 검증으로 간주하지 않는다.
|
||||
- 모든 read는 `unknown`에서 runtime codec으로 envelope와 payload version을
|
||||
검증한 뒤 domain value로 mapping한다.
|
||||
@@ -751,8 +774,10 @@ CLEANED -> journal 제거
|
||||
|
||||
- journal row와 budget reservation은 physical cleanup effect가
|
||||
`CLEANED` 또는 `ALREADY_CLEAN`으로 확인된 뒤에만 해제한다. timeout, crash,
|
||||
malformed response, `EFFECT_UNKNOWN`은 성공이 아니며 `PREPARING`/`FILES_READY`를
|
||||
그대로 남기고 `OBJECT_RECONCILE`로 반환한다.
|
||||
malformed response, worker cleanup 실패는 성공이 아니며 `PREPARING`/`FILES_READY`를
|
||||
그대로 남긴다. 이때 put은 자기 실패 코드(취소면 `ABORTED`, 쿼터 초과면
|
||||
`QUOTA_EXCEEDED` 등)를 그대로 반환하고 recovery만 `RECONCILE`로 바꾼다
|
||||
(Q-6.5-9). journal rollback이 실패해도 같다.
|
||||
- coordinator가 `abortPreparedPut()` 하나만 소유한다. worker client는 prepare 실패
|
||||
시 별도의 fire-and-forget abort를 발행하지 않는다. 중복 보상은 아직 남아 있어야
|
||||
할 journal row를 조기에 지우는 경로였다.
|
||||
@@ -771,6 +796,11 @@ CLEANED -> journal 제거
|
||||
`STORAGE_EVICTED`; reconstructable만 rehydrate한다.
|
||||
- delete는 logical row tombstone을 먼저 commit해 신규 open을 막고 physical bytes를
|
||||
나중에 정리한다.
|
||||
- delete가 끝나면 logical row가 없어지므로 같은 object ID의 다음 put은
|
||||
generation 1부터 다시 시작한다(D-13). 삭제 전에 기억한 generation이나
|
||||
`expectedGeneration`은 다른 객체와 일치할 수 있다. `(objectId, generation)`을
|
||||
객체 수명 전체의 식별자로 쓰지 않고, 필요하면 integrity root digest를 함께
|
||||
비교한다.
|
||||
- operation ID로 replay를 deduplicate한다.
|
||||
|
||||
`Web Locks`를 쓰면 고정된 origin mutation lock과 AbortSignal/timeout을 사용한다.
|
||||
|
||||
@@ -15,15 +15,16 @@ The existing reference feature is the executable REST consumer.
|
||||
It covers list/detail/create behavior, mapping, typed operation inputs,
|
||||
application ports and an optimistic mutation path.
|
||||
|
||||
Current source size:
|
||||
The feature-owned boundary and application source is these four files:
|
||||
|
||||
| Feature-owned area | LOC |
|
||||
| --- | ---: |
|
||||
| `application/reference-feature-api.ts` | 91 |
|
||||
| `contracts/reference-mapper.ts` | 109 |
|
||||
| `adapters/reference-http-gateway.ts` | 65 |
|
||||
| `adapters/create-reference-feature-input.ts` | 41 |
|
||||
| Total measured boundary/application source | 306 |
|
||||
- `application/reference-feature-api.ts`
|
||||
- `contracts/reference-mapper.ts`
|
||||
- `adapters/reference-http-gateway.ts`
|
||||
- `adapters/create-reference-feature-input.ts`
|
||||
|
||||
This document does not keep their line counts; a hand-typed count drifted
|
||||
from the code (review 14-07). Measure them with
|
||||
`wc -l src/features/reference-feature/{application/reference-feature-api.ts,contracts/reference-mapper.ts,adapters/reference-http-gateway.ts,adapters/create-reference-feature-input.ts}`.
|
||||
|
||||
The important boundary metric is not the raw total. It is what those files need
|
||||
to know about the platform.
|
||||
@@ -48,20 +49,19 @@ its business requirement.
|
||||
|
||||
## Scenario B — IndexedDB local draft
|
||||
|
||||
The original executable consumer probe remains at:
|
||||
The executable consumer probe is:
|
||||
|
||||
`tests/contract/consumer-experience/indexeddb-local-draft.test.ts`
|
||||
|
||||
with its isolated fixture:
|
||||
It runs and reads the one Local Draft implementation under
|
||||
`src/features/local-draft-feature`; the isolated fixture copy it used to probe
|
||||
had drifted from `src` and was removed (09-12).
|
||||
|
||||
`tests/contract/consumer-experience/fixtures/local-draft-feature.ts`
|
||||
|
||||
The architecture is now also exercised by a real vertical slice under:
|
||||
|
||||
`src/features/local-draft-feature`
|
||||
|
||||
It owns the Local Draft domain/application API and binds an
|
||||
`IndexedDbRepositoryPort<LocalDraft, never>` in its feature adapter. The
|
||||
The feature owns the Local Draft domain/application API and declares the slice
|
||||
of the repository it calls (`LocalDraftRepository` in
|
||||
`src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts`). The
|
||||
host hands in an `IndexedDbRepositoryPort<LocalDraft, never>` through the
|
||||
`indexedDb` capability; the port satisfies that slice structurally. The
|
||||
cross-capability composition contract lives at:
|
||||
|
||||
`tests/contract/reusable-capability/feature-adapter-composition.test.ts`
|
||||
@@ -80,25 +80,24 @@ It runs against native browser IndexedDB. The test creates the platform
|
||||
save/find/remove through the feature API. The Local Draft feature still does
|
||||
not import the IndexedDB runtime or native browser API.
|
||||
|
||||
Measured probe result:
|
||||
Measured on `src/features/local-draft-feature` (09-12):
|
||||
|
||||
| Metric | Result |
|
||||
| --- | ---: |
|
||||
| feature-owned fixture LOC | 97 |
|
||||
| platform import statements | 1 |
|
||||
| feature LOC (all `.ts` files) | 295 |
|
||||
| import statements leaving the feature (`contracts/errors`, `contracts/result`, `application-api`, `feature-adapter-contribution`) | 7 |
|
||||
| native IndexedDB API references | 0 |
|
||||
| `src/adapters/storage/indexeddb/**` imports | 0 |
|
||||
| runtime-internal IndexedDB types imported by feature | 0 |
|
||||
| `src/application/ports/browser-file-storage/**` imports | 0 |
|
||||
|
||||
The feature depends only on the public application boundary:
|
||||
|
||||
`src/application/ports/browser-file-storage/index.ts`
|
||||
|
||||
and specifically `IndexedDbRepositoryPort<LocalDraft, never>`.
|
||||
The feature does not import the storage runtime or its port, so removing the
|
||||
browser file/storage runtime (`test:browser-file-storage-removal`) leaves it
|
||||
compiling.
|
||||
|
||||
The contract test rejects feature source that reaches for
|
||||
`globalThis.indexedDB`, `IDBFactory`, `IDBDatabase`, `IDBTransaction`,
|
||||
`IDBObjectStore` or the concrete IndexedDB adapter directory.
|
||||
`IDBObjectStore`, the concrete IndexedDB adapter directory or the
|
||||
browser-file-storage port.
|
||||
|
||||
## What this does and does not prove
|
||||
|
||||
|
||||
@@ -41,8 +41,8 @@
|
||||
| `NOT_SELECTED` | 제품 요구·owner·policy가 승인되지 않았다. |
|
||||
| `PLATFORM_LIMITED` | browser/platform이 요구 의미를 cross-browser로 보장하지 못한다. |
|
||||
|
||||
현재 `src/adapters/query-cache/tanstack-query-cache.ts`는 한 runtime당
|
||||
`QueryClient`를 만들고, query retry를 끄며, 30초 `staleTime`과 5분 `gcTime`을
|
||||
현재 `src/adapters/query-cache/tanstack-query-cache.ts`는 server-state
|
||||
generation마다 `QueryClient`를 만들고, query retry를 끄며, 30초 `staleTime`과 5분 `gcTime`을
|
||||
기본값으로 사용한다. `src/bootstrap/runtime-adapters.ts`와
|
||||
`src/bootstrap/runtime-application.tsx`가 이 client를 실제 provider tree에
|
||||
조립한다.
|
||||
@@ -79,13 +79,26 @@ native two-page browser spec은 BroadcastChannel primary와 localStorage fallbac
|
||||
delivery/cleanup을 검증한다. 다만 production QueryClient/coordinator까지 연결한
|
||||
account transition, bfcache/StrictMode lifecycle E2E는 없고, 현재 보존 artifact도
|
||||
Chromium/Firefox만 통과해 WebKit을 포함한 promotion evidence는 충족하지 않는다.
|
||||
localStorage fallback physical key는 아직 storage registry 밖의 상수이고 native
|
||||
`StorageEvent.storageArea`도 facade에서 검증하지 않는다.
|
||||
localStorage fallback physical key는 storage registry의
|
||||
`CACHE_INVALIDATION_PULSE` 항목에서 온다(`src/contracts/storage-keys.ts:102`,
|
||||
`src/adapters/cross-context-invalidation/browser-cross-context-host.ts:36-37`).
|
||||
host facade는 native `StorageEvent.storageArea`를 캡처한 `localStorage` 객체와
|
||||
동일성으로 비교하고(`browser-cross-context-host.ts:286-296`), core는
|
||||
`EXPECTED_LOCAL_STORAGE`로 표시된 pulse만 받는다
|
||||
(`browser-cross-context-invalidation.ts:197-201`).
|
||||
|
||||
현재 epoch 구현은 `release.<releaseId>` 하나다. session/account epoch, opaque
|
||||
account partition, scope 전환 시 새 QueryClient 생성과 durable namespace epoch는
|
||||
아직 구현되지 않았다. 따라서 현재 cross-tab event는 같은 release의 등록 query
|
||||
topic을 빠르게 stale 처리하는 용도에 한정된다.
|
||||
현재 epoch는 release 하나다. `cacheEpoch`는 release ID의 64-bit FNV-1a digest를
|
||||
`release.<16자리 hex>`로 쓴 값이다(`browser-cross-context-host.ts:45-51`, 조립
|
||||
`src/bootstrap/runtime-adapters.ts:364-366`). 세션 identity가 바뀌면 scope
|
||||
runtime이 다음 server-state generation을 열고
|
||||
(`src/adapters/query-cache/server-state-scope-runtime.ts:148`), generation마다
|
||||
새 `QueryClient`와 새 cross-context transport(새 `sourceId`·`sourceEpoch`)를
|
||||
만든다(`src/bootstrap/server-state-generation-store.ts:50-57`,
|
||||
`runtime-adapters.ts:359-372`). 이전 generation의 transport는 coordinator
|
||||
dispose에서 닫힌다(`src/adapters/query-cache/tanstack-cache-coordinator.ts:276-280`).
|
||||
session/account epoch, opaque account partition과 durable namespace epoch는
|
||||
아직 없다. wire event에 사용자·세션 scope가 없으므로 현재 cross-tab event는 같은
|
||||
release의 등록 query topic을 빠르게 stale 처리하는 용도에 한정된다.
|
||||
|
||||
`QUERY_REGISTRY`의 모든 현재 entry와
|
||||
`createTanStackCacheCoordinator()`는 `persistence: "disabled"`만 허용한다.
|
||||
@@ -113,10 +126,10 @@ blocked/versionchange를 다루는 reference runtime이 있다. 이 설계는
|
||||
|
||||
| capability | primary current status | current implementation | target delta | delta implementation status |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| memory QueryClient | `COMPOSED` | runtime별 생성, global stale/gc/retry default | session/account scope owner, generation fence, per-query policy | `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| memory QueryClient | `COMPOSED` | server-state generation별 생성(session identity 변경 시 FENCED 뒤 새 client), global stale/gc/retry default | per-query policy | `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| application query bridge | `COMPOSED` | AbortSignal, stale error, optimistic rollback/conflict surface | old-generation query/mutation callback 폐기 | `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| Web Storage | `COMPOSED` | 두 key, strict v1 envelope/codec, lazy TTL, global 16 KiB cap | per-key cap, HIT/MISS, durability, v2 scope, migration, sweep/logout | `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| cross-tab invalidation | `COMPOSED` | release epoch, versioned hint, duplicate/gap, BC→localStorage | composite scope epoch, registered pulse, storageArea, durable ledger hook | `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| cross-tab invalidation | `COMPOSED` | release epoch(FNV-1a digest), versioned hint, duplicate/gap, BC→localStorage, registry pulse key, storageArea 동일성 검사, generation별 transport | composite scope epoch, durable ledger hook | `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| generic IndexedDB | `AVAILABLE_NOT_COMPOSED` | reusable repository/maintenance runtime | product dataset schema/codec/query/policy composition | product selection `NOT_SELECTED` |
|
||||
| query persistence facade | `DESIGNED_NOT_IMPLEMENTED` | 없음, registry가 disabled 강제 | stable per-query record, bounded restore, namespace epoch/CAS | `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| product persistence | `NOT_SELECTED` | owner/query allowlist 없음 | measured need와 explicit composition | `NOT_SELECTED` |
|
||||
|
||||
@@ -50,7 +50,10 @@ architecture/security/type negative input으로 전환했다. 이는 7번 결정
|
||||
|
||||
- `check:types`는 app, Node scripts/config, tests project를 모두 검사한다.
|
||||
- TS invalid-call, invalid port, discriminated-union fixture는 실패해야 한다.
|
||||
- ESLint와 dependency-cruiser는 TS/TSX architecture fixture를 검사한다.
|
||||
- ESLint와 `check:architecture`의 import 그래프(`scripts/check-architecture.ts`)가
|
||||
TS/TSX architecture fixture를 검사한다. dependency-cruiser 18은 TypeScript 7을
|
||||
해석하지 못해 0개 모듈을 검사하고 통과했으므로 실행하지 않는다(리뷰 12-05).
|
||||
`.dependency-cruiser.json`은 이름만 남은 규칙 파일이고 그래프가 읽는다.
|
||||
- registry scanner는 TS registry의 required field, uniqueness와 reference를
|
||||
검증한다.
|
||||
- browser security gate는 TSX의 금지된 raw HTML fixture를 거절한다.
|
||||
|
||||
@@ -18,7 +18,8 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다.
|
||||
2. Zod presentation schema, application command mapper와 domain invariant는 서로
|
||||
다른 소유물로 유지한다.
|
||||
3. page와 feature는 `useAppForm`, `Form`, `FormField`, `ErrorSummary`,
|
||||
`mapValidationFailureToFields`, `useDirtyNavigationGuard`만 사용한다.
|
||||
`FormFailureStatus`, `mapValidationFailureToFields`, `useDirtyNavigationGuard`만
|
||||
사용한다.
|
||||
4. 422 details는 승인된 `path`와 `code`만 HTTP 경계에서 투영한다. backend
|
||||
message와 알 수 없는 field는 field에 전달하지 않고 안전한 form-level
|
||||
error로 이동한다.
|
||||
@@ -27,6 +28,16 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다.
|
||||
dirty 상태를 해제한다.
|
||||
7. `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage`, `StatusPage`는
|
||||
layout과 state slot만 소유하며 application/query/HTTP를 import하지 않는다.
|
||||
8. (2026-09-25, 08-01) 입력 오류가 아닌 저장 실패는 ErrorSummary에 넣지 않는다.
|
||||
`useAppForm`은 `action: "reauth"`를 `reauth-required`, `FORBIDDEN`을 `forbidden`,
|
||||
`action: "retry"`를 `retry-later`로, 나머지 입력 외 실패를 `unavailable`로 구분하고
|
||||
그 실패를 `failure`로 낸다(F-10). 화면은
|
||||
`FormFailureStatus`로 문구와 행동(로그인·이동·다시 시도)을 보여 준다. 재로그인은
|
||||
입력을 지운다는 안내를 버튼 앞에 둔다(`src/presentation/forms/use-app-form.ts`,
|
||||
`form-components.tsx`).
|
||||
9. (2026-09-25, 03-01) 결과 불명 저장은 사용자가 "변경되지 않음"을 판정하지 않는다.
|
||||
`resendUnknown(mutation.resendUnknownEffect)`로 같은 intent·같은
|
||||
`Idempotency-Key`를 다시 보낸다(`src/presentation/adapters/query/application-query.ts`).
|
||||
|
||||
## React Hook Form 도입 조건
|
||||
|
||||
|
||||
@@ -38,9 +38,18 @@
|
||||
|
||||
## 경계와 검증
|
||||
|
||||
- 제품 코드는 `presentation/design-system/index`만 import한다.
|
||||
- design-system 검사기는 direct icon/headless import, deep import, raw palette,
|
||||
undefined token과 tooltip-only required information fixture를 거절한다.
|
||||
- 제품 코드는 `presentation/design-system/index`만 import한다. 예외는 규칙에
|
||||
이름으로 적는다. `presentation/components/ui/*.ts`는 아래 Rollback의 재수출
|
||||
facade이고, `presentation/templates/page-templates.tsx`는 index가 내보내지
|
||||
않는 `PaginationLandmarkContext`를 읽는다.
|
||||
- deep import와 direct icon import는 `check:architecture` 그래프 규칙
|
||||
`design-system-is-reached-through-its-index`, `icon-vendor-is-facade-only`
|
||||
(`.dependency-cruiser.json`)가 거절한다. 경로 해석이 끝난 간선을 보므로
|
||||
presentation 안의 상대 경로 import도 잡는다(리뷰 12-08). 음성 fixture는
|
||||
`tests/fixtures/architecture/dependency-graph/import-boundaries`다.
|
||||
- design-system 검사기(`scripts/check-design-system.ts`)는 headless vendor
|
||||
import, raw palette, undefined token과 tooltip-only required information
|
||||
fixture를 거절한다.
|
||||
- type negative fixture는 accessible name 없는 `IconButton`을 거절한다.
|
||||
- component test는 decorative icon, form control, Menu, Tabs, Drawer와 Toast를
|
||||
검증한다.
|
||||
|
||||
@@ -66,9 +66,15 @@ route/form/failure 의미 값
|
||||
|
||||
## 검증
|
||||
|
||||
- `check:i18n`은 catalog key와 placeholder parity, common UI의 한국어 literal,
|
||||
backend message JSX 렌더링과 raw HTML 사용을 검사한다.
|
||||
- `check:i18n:fixture`는 세 금지 사례를 실제로 거절해야 성공으로 인정된다.
|
||||
- `check:i18n`은 catalog key와 placeholder parity, 화면 코드의 한국어 literal,
|
||||
backend message JSX 렌더링과 raw HTML 사용을 검사한다. 검사 범위는 공통 UI
|
||||
디렉터리, `src/presentation/pages`, 모든 `src/features/*/presentation`이다.
|
||||
컴포넌트 갤러리 `src/presentation/examples`는 일부러 뺐다
|
||||
(`scripts/check-i18n.ts`의 `commonDirectories`, `featurePresentationDirectories`).
|
||||
- `check:i18n:fixture`는 같은 탐색 규칙을 `tests/fixtures/i18n/forbidden` 트리에
|
||||
돌린다. fixture 파일 하나라도 거절되지 않으면 종료 코드 2로 실패한다.
|
||||
- `tests/unit/i18n-contract.test.ts`는 `ERROR_REGISTRY`의 모든 `userMessageKey`가
|
||||
ko-KR·en-US catalog에 있는지 확인한다.
|
||||
- type negative fixture는 unknown key와 잘못된 parameter shape를 거절한다.
|
||||
- unit test는 fallback, alias, pseudo 확장, direction과 timezone/number/relative/
|
||||
list/plural/select의 결정성을 검증한다.
|
||||
|
||||
@@ -43,13 +43,17 @@ vendor 결정 전에는 안전한 기본값이 아니다.
|
||||
`createHttpObservationProjector`가 유일한 projection authority다. observation은
|
||||
arbitrary context map이 아니며 projector는 `route_id`, `operation_id`,
|
||||
`operation`, `outcome`, `error_kind`, `http_status_group`,
|
||||
`attempt_count_bucket`, `duration_bucket`만 사용한다. raw attempt count,
|
||||
`attempt_count_bucket`, `duration_bucket`만 사용한다. diagnostics에만
|
||||
`correlation_id`(서버가 돌려준 `x-correlation-id`, 없으면 실행이 보낸 요청 ID)를
|
||||
더한다. telemetry에는 넣지 않는다(03-03, `createHttpObservationProjector`). raw attempt count,
|
||||
duration, status, URL, intent, key, input identity와 내부 `terminalReason`은
|
||||
sink로 나가지 않는다. effect certainty가 운영상 필요해지면 `effect_certainty`
|
||||
key와 닫힌 value policy를 contract·fixture·이 ADR에 동시에 추가한 뒤에만
|
||||
전달한다.
|
||||
5-2. caller cancellation과 scope fence는 API failure가 아니다. diagnostics는 한
|
||||
번 남기고 `api.request.failed`는 발행하지 않는다.
|
||||
번 남기고 `api.request.failed`는 발행하지 않는다. 자격증명이 없어 한 번도
|
||||
보내지 않은 `UNAUTHENTICATED`(응답 status 없음)도 같다(03-07,
|
||||
`src/bootstrap/runtime-adapters.ts` `isTerminalNonAbortFailure`).
|
||||
5-3. `routeId`는 installed operation-executor 경계의 필수 입력이다. feature
|
||||
gateway가 소유한 low-cardinality route identity를 URL에서 재구성하지 않는다.
|
||||
6. `app.boot.failed`, `ui.render.failed`, `release.mismatch.detected`,
|
||||
@@ -72,6 +76,11 @@ vendor 결정 전에는 안전한 기본값이 아니다.
|
||||
아니거나 1 미만이거나 문서화된 ceiling(각각 `MAX_TELEMETRY_QUEUE`,
|
||||
`MAX_DIAGNOSTIC_ENTRIES` = 10,000)을 넘으면 `TypeError`로 거절한다. NaN/Infinity가
|
||||
조용히 eviction을 비활성화하는 경로를 남기지 않는다.
|
||||
7-5. (2026-09-25) 두 telemetry port는 collector 하나로 보낸다
|
||||
(`src/adapters/telemetry/telemetry-collector.ts`). collector는 본문을 60KiB 아래로
|
||||
나누고, 진행 중인 keepalive 본문 합이 64KiB를 넘으면 그 부분은 keepalive 없이
|
||||
보낸다(03-05). 조합 루트가 release manifest의 `buildId`·`releaseId`를 넘기면 모든
|
||||
이벤트에 `build_id`·`release_id`를 붙인다(13-11, `src/bootstrap/runtime-adapters.ts`).
|
||||
8. diagnostics와 telemetry failure는 제품 흐름, HTTP 결과, route transition,
|
||||
storage/cache fallback과 React error surface를 바꾸지 않는다.
|
||||
9. mount 전 bootstrap failure는 안전한 build/config/error kind만 별도 evidence로
|
||||
|
||||
@@ -255,15 +255,20 @@ reconnect는 capped full-jitter exponential backoff를 사용한다. base/max de
|
||||
max attempts와 max elapsed는 immutable registry/implementation ceiling으로
|
||||
제한한다.
|
||||
|
||||
- stable-open window 또는 valid heartbeat/event 뒤에만 attempt reset
|
||||
- valid heartbeat/event와 stable-open window를 둘 다 충족한 뒤에만 attempt와
|
||||
elapsed budget reset. session의 모든 종료 경로(server close, offline,
|
||||
`waitClosed` throw)에서 확인한다
|
||||
- valid server hint는 local delay보다 이른 retry를 금지하는 not-before bound
|
||||
- server hint가 implementation max/remaining elapsed budget을 넘으면 낮춰
|
||||
clamp하지 않고 degraded/stale로 종료
|
||||
- offline에서는 timer retry를 멈춤
|
||||
- offline에서는 timer retry를 멈춤. offline 대기 시간은 elapsed budget에 넣지
|
||||
않고 online 복귀 시 elapsed budget을 다시 시작한다. attempt 상한은 유지한다
|
||||
- auth expiry는 session owner single-flight recovery 한 번
|
||||
- forbidden/protocol/schema failure는 terminal
|
||||
- 외부 rate/provider failure는 exact bounded server not-before hint가 있을 때만
|
||||
retry하고, hint가 없으면 terminal
|
||||
- retry 여부는 transport가 보고한 `retryable`이 정한다. retryable 실패는 hint가
|
||||
없어도 bounded retry한다. hint가 꼭 필요한 실패(SSE `429`/`503`, WebSocket
|
||||
`OVERLOADED`)는 hint가 없으면 transport가 terminal로 보고한다. SSE
|
||||
`502`/`504`와 WebSocket `RESTART`·`NETWORK_LOST`는 hint 없이 bounded retry
|
||||
- retry budget 소진 뒤 declared Polling fallback 또는 stale UI
|
||||
- reconnect는 realtime coordinator, auth는 session owner, Poll cadence는 poll
|
||||
coordinator가 소유하고 Poll-bound HTTP/Query retry는 비활성
|
||||
@@ -456,7 +461,7 @@ push hint와 worker deadline을 제한한다. 제품 config는 더 작게만 설
|
||||
|
||||
2026-07-28 reference-runtime amendment로, RT-01~RT-04 source 전체를
|
||||
tree-shaking 없이 합성하는 optional-recipe gzip 예산을 40,000 bytes로
|
||||
고정한다. 이는 production bundle 허용량이 아니며 미선택 production asset의
|
||||
고정한다(2026-09-27 성숙도 리뷰 반영으로 40,900 bytes로 올림. 근거는 `config/recipes/frontend-capability-recipes.json` 변경 커밋). 이는 production bundle 허용량이 아니며 미선택 production asset의
|
||||
realtime module 허용량은 계속 0이다. SSE replay-open과 WebSocket
|
||||
`SUBSCRIBED`가 exact recovery checkpoint를 증명하고 common barrier가 확인될
|
||||
때까지 event admission을 막는 readiness gate는 attempt당 최대 30초다.
|
||||
|
||||
@@ -138,6 +138,17 @@ browser-capability test composes the feature over the real
|
||||
`createIndexedDbRuntime` and native IndexedDB, proving that this seam is not
|
||||
limited to an in-memory contract fixture.
|
||||
|
||||
The bootstrap does not build `indexedDb`: IndexedDB is an opt-in reference
|
||||
runtime (`productionComposition: false` in
|
||||
`config/recipes/frontend-capability-recipes.json`). The composition example is
|
||||
`recipes/frontend-capabilities/indexeddb-feature-capability.ts`
|
||||
(`createLocalDraftIndexedDbCapability`, exercised by
|
||||
`tests/recipes/indexeddb-feature-capability.test.ts`). A product that installs a
|
||||
feature with `needs: ["indexedDb"]` copies it and adds `indexedDb` to the feature
|
||||
capabilities in `src/bootstrap/runtime-adapters.ts`. Until it does, that object
|
||||
fails the app typecheck, and `composeFeatureAdapterInputs()` rejects the
|
||||
composition with `feature <id> needs indexedDb, which the host did not provide`.
|
||||
|
||||
## Presentation consumer surface
|
||||
|
||||
`ApplicationProvider` remains the composition root for presentation, but new
|
||||
|
||||
@@ -65,7 +65,7 @@ P0/P1 acceptance와 P2 recipe 기본값은 `LOCAL_TEMPLATE_READY`다. 다만 실
|
||||
| 영역 | 현재 판정 | 근거 | 필요한 다음 상태 |
|
||||
| --- | --- | --- | --- |
|
||||
| 부트·런타임 설정 | 준비됨 | `src/bootstrap`, runtime schema, release 검사 | 현 상태 유지, TS 전환 시 동일 게이트 유지 |
|
||||
| 계층 의존 방향 | 준비됨 | dependency-cruiser + TS-aware static graph, unresolved/parse/layer/cycle negative fixture | 새 rule shape와 source extension도 같은 fail-closed graph에 추가 |
|
||||
| 계층 의존 방향 | 준비됨 | TS-aware static graph(`scripts/check-architecture.ts`, 규칙 `.dependency-cruiser.json`), unresolved/parse/layer/cycle negative fixture. dependency-cruiser 자체는 TS 7을 해석하지 못해 실행하지 않음(12-05) | 새 rule shape와 source extension도 같은 fail-closed graph에 추가 |
|
||||
| application facade | 준비됨 | module-augmented feature input registry, typed output catalog, provider, production composition test | feature별 input contribution과 제거 gate 유지 |
|
||||
| REST HTTP client | 준비됨 + hardening delta | reference vertical의 path/search/body projection, attempt timeout/retry, abort/cleanup은 `COMPOSED` | auth fail-close/final invariant, total deadline, bounded decoder, status/media/CSRF/conditional/pagination은 `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| Browser RPC 공통 계약/runtime | 준비됨/미조립 | V3 operation/profile registry, typed application port, bounded unary/server-stream lifecycle와 unavailable adapter는 `AVAILABLE_NOT_COMPOSED` | actual descriptor/generated client, protocol transport, proxy/provider/browser conformance |
|
||||
|
||||
+40
-13
@@ -25,6 +25,15 @@ The following edges are forbidden:
|
||||
- an adapter to presentation, bootstrap internals, or another concrete adapter
|
||||
- feature domain/application to its presentation or outbound adapter, and
|
||||
feature presentation to its outbound adapter
|
||||
- a module presentation may import to a concrete adapter: files outside a
|
||||
feature's layer folders (`src/features/*.ts`, `src/features/<id>/*.ts`),
|
||||
`src/contexts` and `src/apps` (`feature-and-app-roots-do-not-reach-adapters`).
|
||||
The graph checks one edge at a time, so a re-export there would carry an
|
||||
adapter into presentation with every other rule passing. The one exception is
|
||||
the type-only `src/features/feature-adapter-contribution.ts`
|
||||
- presentation to `src/apps` or `src/contexts`, except
|
||||
`src/presentation/routes/app-router.tsx`, which mounts the app's route tree
|
||||
(`presentation-does-not-import-apps-or-contexts`)
|
||||
|
||||
## The adapter kernel
|
||||
|
||||
@@ -35,14 +44,25 @@ purpose and is the only adapter code an adapter may reach across a group for:
|
||||
the bounded-capacity guard
|
||||
- `src/adapters/browser-file-storage/result.ts` — the browser-data result and
|
||||
failure constructors
|
||||
- `src/adapters/cross-context-invalidation/index.ts` — the cross-context
|
||||
invalidation transport and its types. Any adapter may import it; today
|
||||
`query-cache` does
|
||||
|
||||
Each rule above is enforced by `check:architecture`, including the kernel
|
||||
carve-out, so this table and the executable rules cannot drift apart. Two edges
|
||||
are still open and are named explicitly in `.dependency-cruiser.json` rather
|
||||
than left silent: the generic presentation modules that read the installed
|
||||
registries today, and the two collaborator types `query-cache` reads from
|
||||
`cross-context-invalidation`. Both lists are frozen — a new edge of either kind
|
||||
fails the gate.
|
||||
carve-out, so this table and the executable rules cannot drift apart.
|
||||
|
||||
Every exception is written in the rule itself (`.dependency-cruiser.json`): the
|
||||
exempted path in `pathNot`, and the reason, owner and revisit condition in
|
||||
`comment` (review 12-07). Besides the kernel, the exceptions are:
|
||||
|
||||
- the generic presentation modules that read the installed registries today
|
||||
(`generic-presentation-does-not-compose-the-product`). The list names exact
|
||||
files, so a new module that reads a registry fails the gate
|
||||
- `src/presentation/adapters/query`, the TanStack Query binding
|
||||
(`presentation-does-not-know-adapters`)
|
||||
- `src/presentation/routes/app-router.tsx` importing the app
|
||||
(`presentation-does-not-import-apps-or-contexts`)
|
||||
- the design-system facades (`design-system-is-reached-through-its-index`)
|
||||
|
||||
## 어댑터 그룹의 공개 경계
|
||||
|
||||
@@ -63,10 +83,15 @@ fails the gate.
|
||||
위한 것이다.
|
||||
|
||||
`storage`는 최상위 배럴이 `indexeddb/`·`opfs/` 서브배럴을 재수출하지
|
||||
않는다. 두 런타임이 각자 독립적으로 제거 가능하고
|
||||
(`test:browser-file-storage-removal`), 그래서 각 서브배럴이 곧 경계다.
|
||||
규칙의 도착점 정규식이 1단계 중첩 `index.ts`를 배럴로 인정하는 이유가
|
||||
이것이다.
|
||||
않는다. 두 폴더는 browser-file-storage 번들의 런타임이다. 제거 드릴
|
||||
(`test:browser-file-storage-removal`)은 그 번들 전체(`browser-file-storage`,
|
||||
`browser-files`, `browser-transfer`, `cache-storage`, `storage/indexeddb`,
|
||||
`storage/opfs`)를 함께 지운다. 최상위 `storage` 배럴(Web Storage)은 그 뒤에도
|
||||
남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개
|
||||
경계다.
|
||||
규칙의 도착점 정규식은 이 두 서브배럴만 배럴로 인정한다. 다른 그룹의 2단계
|
||||
`index.ts`(예: `http/internals/index.ts`)는 공개 배럴이 아니고, 그룹 바깥에서
|
||||
import하면 실패한다(리뷰 12-07, `dependency-graph/barrel` fixture).
|
||||
|
||||
`service-worker/index.ts`는 `tsconfig.service-worker.json`의 `exclude`에
|
||||
들어 있다. 그 설정이 그룹 폴더를 통째로 WebWorker lib로 컴파일하면서 페이지
|
||||
@@ -83,8 +108,9 @@ application APIs augment the generic typed input registry. Concrete output
|
||||
ports are composed in bootstrap and stay hidden behind the application facade.
|
||||
Project-selected capabilities still implement the same output boundaries.
|
||||
|
||||
`check:architecture` keeps dependency-cruiser's report and adds the
|
||||
authoritative TypeScript-aware graph below it:
|
||||
`check:architecture` writes the TypeScript-aware graph below. It reads the rules
|
||||
from `.dependency-cruiser.json` but does not run dependency-cruiser, which cannot
|
||||
parse TypeScript 7 and checked zero modules (review 12-05):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -103,7 +129,8 @@ authoritative TypeScript-aware graph below it:
|
||||
```
|
||||
|
||||
The graph scans TypeScript and TSX, including static, dynamic, type, CommonJS
|
||||
and JSDoc import references. It applies the path rules from
|
||||
and JSDoc import references. `import.meta.glob` is a parse failure: it loads
|
||||
modules without naming one, so no edge rule could see them (review 12-06). It applies the path rules from
|
||||
`.dependency-cruiser.json`, requires explicit TypeScript extensions for local
|
||||
source imports, and fails closed on JavaScript-family source/specifiers,
|
||||
unsupported rule shapes, unresolved imports, parse failures, error-severity
|
||||
|
||||
@@ -106,6 +106,30 @@ type은 facade 밖으로 노출하지 않는다.
|
||||
SSOT다. 문서와 catalog가 다르면 gate가 검사하는 catalog를 우선 고치고 이 표도
|
||||
같이 갱신한다.
|
||||
|
||||
Service Worker를 켤 때 확인할 것(06-05). 템플릿은 1·6과 2의 시작 실패
|
||||
이벤트만 갖고 있다.
|
||||
|
||||
1. `src/features/installed-runtime-capabilities.ts`의 `SERVICE_WORKER`를
|
||||
`ACTIVE`로 바꾼다. `scripts/build-frontend.ts`가 worker 빌드를 추가로 돈다.
|
||||
2. 관측: `createRuntimeComposition`이 텔레메트리 포트를 optional host에 넘긴다
|
||||
(`src/bootstrap/create-runtime-composition.ts`). 시작 결과가 `FAILED`나
|
||||
`INCOMPATIBLE`이면 `service-worker.start.failed`가 1건 남는다
|
||||
(`src/bootstrap/optional-runtime-host.ts`). 실제 composition에서 첫 설치가
|
||||
실패하면 이벤트가 1건 나가는 것은
|
||||
`tests/component/runtime-composition-service-worker-telemetry.test.ts`가
|
||||
확인한다. 템플릿이 연결하지 않은 것은 셋이다. 업데이트 설치 실패
|
||||
(`watchForUpdates`, `src/adapters/service-worker/service-worker-page-controller.ts`)는
|
||||
이벤트를 남기지 않는다. page controller의 `observe`는 composition이 넘기지
|
||||
않는다. `OptionalRuntimeHost.health()`는 `src` 안에서 읽는 코드가 없다.
|
||||
필요하면 다운스트림이 `createRuntimeComposition`에서 연결한다.
|
||||
3. blockers: 저장하지 않은 편집이 있는 탭이 활성화를 거절하게
|
||||
`createOptionalRuntimeHost`에 `blockers`를 넘긴다. 템플릿은 넘기지 않는다.
|
||||
4. 활성화 UI: `ServiceWorkerRuntimeHost.onUpdateWaiting`을 구독하고, 사용자가
|
||||
동의하면 `requestActivation()`을 부른다(`src/contracts/service-worker.ts`).
|
||||
5. reload 처리: `onReloadRequired`를 구독해 reload를 안내한다.
|
||||
6. 끄기·롤백·제거: `docs/operations/release-cache-rollback.md`의 Service Worker
|
||||
절차. `service-worker.js`는 `Cache-Control: no-cache`로 서빙한다.
|
||||
|
||||
Web Push target은 현재 13번째 설치 recipe가 아니다. 기존 `realtime`,
|
||||
`service-worker-pwa`, `browser-permission`의 인접 경계를 조합해야 하는 별도
|
||||
`NOT_SELECTED` capability다. 실제 선택 전 VD-10 amendment와 machine-readable
|
||||
@@ -130,6 +154,15 @@ Web Push를 함께 설치하지 않는다.
|
||||
integration test를 작성한다.
|
||||
9. runtime config schema, dependency inventory/approval, SBOM, bundle budget,
|
||||
browser support와 runbook을 갱신한다.
|
||||
운영 CSP(`config/hosting/security-headers.json`)도 여기서 넓힌다. 기본 CSP는
|
||||
아래 기능을 막는다(리뷰 13-08).
|
||||
- 다른 origin의 realtime: `connect-src`에 `wss://<realtime origin>`을 더한다.
|
||||
`https:`는 `wss:`를 허용하지 않는다(CSP3 scheme 비교).
|
||||
- 파일 preview(`src/adapters/browser-files/object-url-lease.ts`의 object URL):
|
||||
`img-src`에 `blob:`을 더한다.
|
||||
- 이미지 CDN: `img-src`에 CDN origin을 더한다.
|
||||
바꾼 CSP 아래에서 `tests/e2e/production-csp.spec.ts`가 그 기능의 화면을 열도록
|
||||
smoke를 늘린다.
|
||||
10. 실제 provider integration과 negative behavior가 통과한 뒤에만 catalog 상태를
|
||||
별도 project catalog에서 `INSTALLED`로 바꾼다.
|
||||
|
||||
|
||||
@@ -53,8 +53,9 @@ and exact input type.
|
||||
Route contracts/codecs, the route-input provider, and lazy runtime modules are
|
||||
separate modules so feature pages do not import the router that loads them.
|
||||
Expected application failures use the shared `Result`/`AppFailure` contract.
|
||||
The architecture gate analyzes TS/TSX imports independently of
|
||||
dependency-cruiser, rejects local JavaScript-family specifiers and executable
|
||||
The architecture gate analyzes TS/TSX imports with its own graph (the rules
|
||||
live in `.dependency-cruiser.json`; dependency-cruiser itself cannot parse
|
||||
TypeScript 7 and does not run), rejects local JavaScript-family specifiers and executable
|
||||
JavaScript-family files, and fails on unresolved imports, parse failures,
|
||||
forbidden layer edges, or cycles. The remaining project-owned work includes
|
||||
selecting and verifying real hosting, identity, telemetry, vulnerability and
|
||||
|
||||
@@ -164,8 +164,24 @@ URL을 발급하면 안 된다.
|
||||
|
||||
- capability를 async 대기하는 동안 caller 입력과 dependency method를 snapshot한다.
|
||||
- 사용 전에 만료뿐 아니라 최소 잔여 lifetime도 검사한다.
|
||||
- 기기 시계가 서버보다 `maxClockSkewMs`(기본 60초)까지 늦어도 수명 상한 검사는
|
||||
거절하지 않는다. 서버는 session 수명을 `maxSessionLifetimeMs` 이하, capability
|
||||
수명을 `maxCapabilityTtlMs` 이하로 주면 된다(`upload-response-validation.ts`
|
||||
`validateSession`, `presigned-capability-http-provider.ts` `maxClockSkewMs`).
|
||||
하한은 느슨하게 하지 않는다. 기기 시계가 빠르면 수명이 그만큼 짧아 보이므로
|
||||
서버 capability 수명은 `minimumRemainingLifetimeMs + maxClockSkewMs`와
|
||||
`capabilityRefreshSkewMs + maxClockSkewMs`보다 길어야 한다. 기기 시계가 이보다
|
||||
더 빠르면 그 기기에서는 capability가 만료로 보인다.
|
||||
- 만료/403은 임의 retry가 아니라 control plane의 새 capability 발급으로 복구한다.
|
||||
- ambiguous network failure 뒤 upload part를 새 bytes로 덮어쓰지 않는다.
|
||||
- 실행기의 `put()`·`open()`은 받은 capability를 어떤 경로로 끝나든 vault에서
|
||||
뺀다. 성공하면 `consume()`이 빼고, 그 밖의 모든 경로(잘못된 입력, 이미 중단된
|
||||
signal, 바이트 길이 불일치, 바인딩 거절, 만료, replay claim 실패, digest 중단이나
|
||||
불일치, 전송 실패)는 공개 메서드의 `finally`가 `revoke()`로 뺀다
|
||||
(`presigned-transfer-executor.ts`의 `release`). 실행기에 닿기 전에
|
||||
버려진 capability(runtime 응답 검증 실패, part 실행기 사전 검사 실패, fail-fast로
|
||||
`put()` 전에 멈춘 형제 worker)는 만료까지 `maxActiveCapabilities` 자리를
|
||||
차지하고, 다음 `register()`가 만료 항목을 정리한다.
|
||||
- client-side single-use map은 UX 최적화일 뿐이다. cross-tab/replay authority는
|
||||
server 또는 composition-owned atomic consumer다.
|
||||
- signed response의 URL, query, raw header와 exception text를 관측성에 남기지 않는다.
|
||||
@@ -198,6 +214,15 @@ capability는 앞 절의 별도 fixed BFF endpoint를 redirect 금지로 사용
|
||||
response envelope 및 request/response의 `UPLOAD_PART` binding protocol이
|
||||
`PRESIGNED_MULTIPART_V1`인지 대조한다.
|
||||
|
||||
part 수 상한과 byte cap은 서로 맞아야 한다. complete 요청과 status 응답에는 part
|
||||
receipt가 모두 들어간다. 조립할 때 runtime 정책의 `maxPartCount`를 전송의
|
||||
`maxPartCount`로 넘기면, 전송 factory가 최악의 receipt(모든 필드가 문법 최대,
|
||||
token 512자, part당 691바이트)로 계산해 들어가지 않는 조합을 `TypeError`로
|
||||
거절한다(`fetch-json-transport.ts` `MAX_RECEIPT_JSON_BYTES`). 기본값(1,024 part,
|
||||
요청 1MiB, 응답 2MiB)은 들어간다. 요청 1MiB로는 약 1,500 part, 최대치 4MiB로는
|
||||
약 6,000 part까지다. 넘기지 않으면 검사하지 않고, 넘치는 upload는 모든 part를
|
||||
보낸 뒤 complete에서 `LIMIT_EXCEEDED`로 끝난다.
|
||||
|
||||
Session은 적어도 opaque ID, protocol version, exact total bytes, media type,
|
||||
part size, part count, concurrency ceiling, checksum algorithm과 expiry를 묶는다.
|
||||
part number는 1부터 연속적이어야 하고 마지막 part를 제외한 part length는
|
||||
@@ -261,6 +286,16 @@ session state 검사를 대체하지 않는다.
|
||||
- 429/모든 `5xx`/network retry는 composition의 bounded attempt, bounded
|
||||
`Retry-After`와 abortable backoff 안에서만 수행한다.
|
||||
- 만료/authorization failure는 최대 정책 범위 안에서 capability를 재발급한다.
|
||||
object store PUT의 401/403/409/410과 실행기의 만료 판정(`REISSUE_CAPABILITY`)은
|
||||
`maxRetries` 안에서 다음 시도가 새 capability로 다시 보낸다. BFF 발급 단계의
|
||||
401/403은 재시도하지 않는다(`resumable-upload-runtime.ts` `uploadPartWithRetry`).
|
||||
- part PUT 한 번의 제한 시간은 `providerAttemptTimeoutMs + part 바이트 /
|
||||
minTransferBytesPerSecond`다. 기본값은 30초 + 5MiB ÷ 64KiB/s = 110초다
|
||||
(`runtime-policy.ts`). 즉 지원하는 최저 업링크는 기본 약 0.5Mbit/s이고, 이보다
|
||||
느리면 정책의 `minTransferBytesPerSecond`를 낮춘다. fetch는 업로드 진행을 알려
|
||||
주지 않으므로 PUT에는 idle 제한이 없고 이 크기 비례 제한이 멈춘 연결을 끊는다.
|
||||
presigned 실행기도 `timeoutMs`에 같은 식의 바이트 몫을 더한다
|
||||
(`presigned-transfer-executor.ts`, `http-common.ts` `transferAllowanceMs`).
|
||||
- upload response의 opaque receipt/ETag를 whole-file digest로 해석하지 않는다.
|
||||
- PUT capability는 성공 status, receipt header와
|
||||
`expectedResponseByteLength`를 묶는다. runtime은 exact `Content-Length`를
|
||||
@@ -299,6 +334,12 @@ resume 시 checkpoint만 신뢰하지 않는다.
|
||||
전환한다.
|
||||
5. 새 part만 업로드한 뒤 전체 ordered set을 다시 reconcile한다.
|
||||
|
||||
재개 때 서버 session은 저장된 checkpoint 값(session ID, 동시성, 만료 시각)과
|
||||
일치하는지만 본다. 정책 상한(`maxConcurrency`, `maxSessionLifetimeMs`)은 새
|
||||
session을 만들 때만 검사한다. 그래서 정책을 낮춘 빌드도 이전 빌드가 시작한
|
||||
업로드를 이어 간다. worker 수는 `min(현재 정책, session 동시성)`이다
|
||||
(`upload-response-validation.ts` `validateSession`의 `stage`).
|
||||
|
||||
`GET_STATUS`가 HTTP `404` 또는 `410`을 반환하거나 decoded status가
|
||||
`NOT_FOUND`/`EXPIRED`이면 해당 session은 terminal이다. runtime은 CAS revision을
|
||||
확인해 checkpoint를 제거하고 새 session으로 restart하거나
|
||||
@@ -324,6 +365,42 @@ signed URL이나 receipt를 포함하거나 저장하지 않으며 server state
|
||||
reconcile에서 server 상태를 확인한다. backend는 만료된 orphan multipart를
|
||||
정리하는 TTL job을 가져야 한다.
|
||||
|
||||
complete 결과를 모를 때 클라이언트는 다음처럼 동작한다.
|
||||
|
||||
- complete 응답을 잃으면(시간 초과, 연결 끊김) `upload()`는 같은 COMPLETE key로
|
||||
`maxRetries`번 다시 보낸 뒤 `UNAVAILABLE/UPLOAD_COMPLETE, retryable:true`를
|
||||
돌려준다. 모든 part가 수락된 checkpoint는 남는다
|
||||
(`resumable-upload-runtime.ts` `completeUpload`).
|
||||
- 같은 파일로 `upload()`를 다시 부르면 `GET_STATUS`가 `QUARANTINED`일 때
|
||||
resourceId와 `replayed:true`를 돌려준다. `ACTIVE`이면 같은 key로 complete를
|
||||
다시 보낸다.
|
||||
- `abort()`에 서버가 `ALREADY_COMPLETED`로 답하면 checkpoint를 지우기 전에
|
||||
`GET_STATUS`로 resourceId를 읽어 `{ state: "ALREADY_COMPLETED", resourceId }`로
|
||||
돌려준다. status 조회가 일시적으로 실패하면 `ABORT_PENDING` checkpoint를 남기고
|
||||
실패를 돌려준다. `abort()`를 다시 부르면 된다. 서버가 session을 모르면(404/410)
|
||||
resourceId 없이 닫는다(`resumable-upload-runtime.ts` `readCompletedResourceId`).
|
||||
- 서버가 complete를 반영한 뒤 로컬 checkpoint 삭제가 실패해도(IndexedDB 오류,
|
||||
complete 직후 caller abort) `upload()`는 성공을 돌려준다. 남은 행은 다음
|
||||
`upload()`나 `abort()`가 같은 자원으로 정리한다.
|
||||
|
||||
서버 계약 — complete 진행 중(`ResumableUploadControlPlane.complete` 주석):
|
||||
|
||||
- 같은 COMPLETE key의 complete가 아직 끝나지 않았으면 서버는 `429`와
|
||||
`Retry-After`로 답한다. 값은 전송과 runtime의 `maxRetryAfterMs`(기본 30초)
|
||||
이하여야 한다. 클라이언트는 이것을 `UNAVAILABLE, retryable:true`로 읽고 그만큼
|
||||
기다린 뒤 같은 key로 다시 보낸다(`fetch-json-transport.ts` `statusFailure`).
|
||||
`Retry-After`가 없거나 상한을 넘으면 재시도하지 않는다. `503`도 재시도되지만
|
||||
`Retry-After`는 읽지 않는다.
|
||||
- `409`는 쓰지 않는다. 클라이언트는 `409`를 `CONFLICT, retryable:false`로 읽고
|
||||
멈춘다.
|
||||
- 그동안 `GET_STATUS`는 `ACTIVE`(모든 part 수락)를 유지하고, 자원이 확정된 뒤에만
|
||||
`QUARANTINED`와 resourceId를 준다. 클라이언트 status 계약(`UploadSessionStatus`)에는
|
||||
"완료 중" 값이 없고, 모르는 state는 `INTEGRITY_FAILED`로 거절한다.
|
||||
- 서버 문서의 `OPERATION_IN_PROGRESS`(`server-file-capability-infrastructure.md`
|
||||
8.2, 11.1)는 이 wire 표현으로 내보낸다.
|
||||
- 재시도가 모두 끝나도 진행 중이면 `upload()`는 `UNAVAILABLE/RESUME`을 돌려주고
|
||||
checkpoint가 남는다. 다음 `upload()`나 `abort()`가 위 순서로 조정한다.
|
||||
|
||||
application-facing upload 성공값은 `state`, opaque `resourceId`, `byteLength`,
|
||||
`replayed`만 반환한다. control-plane 검증에 사용한 `sessionId`,
|
||||
`requestBindingSha256`와 file fingerprint는 public outcome에 노출하지 않는다.
|
||||
@@ -360,7 +437,10 @@ resume through upload()
|
||||
정한 `schemaVersion: 2`가 필요하다. 기존 schema에 필드를 몰래 추가하지 않는다.
|
||||
|
||||
현재 checkpoint store도 single-key `read/CAS/remove`와 account partition 전체
|
||||
삭제만 제공한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local
|
||||
삭제만 제공한다. 예외로 읽을 수 없는 행(손상, 또는 이 빌드가 모르는
|
||||
`schemaVersion`)은 명시적 `abort()`가 `removeUnreadable`로 지우고 `ORPHANED`로
|
||||
보고한다. 그 행에서는 session을 알 수 없으므로 server session은 만료에 맡긴다.
|
||||
`upload()`는 같은 행에서 계속 `CORRUPT_DATA`로 fail-closed한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local
|
||||
checkpoint를 retention 기준으로 자동 발견·정리하지 못한다. 향후 admin lifecycle은
|
||||
다음을 제공한다.
|
||||
|
||||
@@ -397,6 +477,11 @@ Streaming download는 server resource를 전체 `Blob`/`ArrayBuffer`로 material
|
||||
- abort/consumer early return에서 reader를 cancel하고 lock/capability lease를
|
||||
해제한다.
|
||||
- byte source는 기본 one-shot이며 두 번째 stream 소비를 거절한다.
|
||||
- 전체 제한과 idle 제한을 따로 둔다. 전체 제한은 `timeoutMs + byteLength /
|
||||
minTransferBytesPerSecond`(기본 64KiB/s)라 느리지만 진행하는 큰 download는
|
||||
끝까지 받는다. chunk 하나를 기다리는 시간은 `idleTimeoutMs`(기본 `timeoutMs`)가
|
||||
상한이고, 진행이 멈추면 여기서 `UNAVAILABLE/REISSUE_CAPABILITY`로 끝난다
|
||||
(`presigned-transfer-executor.ts` `readChunk`, `http-common.ts` `readWithSignal`).
|
||||
|
||||
File System Access save picker가 있으면 user activation 안에서 destination을 먼저
|
||||
열고 stream을 쓴다. close와 integrity verification이 끝난 경우만 `SAVED`다.
|
||||
@@ -545,6 +630,9 @@ DOM, persisted state, telemetry 또는 query cache에 장기 보관하지 않는
|
||||
private delivery는 `PRIMARY_REQUIRED` browser probe가 필수이며 이를 `NONE`으로
|
||||
낮출 수 없다. probe는 `credentials: omit`, redirect 금지, exact response URL과
|
||||
`Cache-Control: no-store`를 실제 response에서 확인한다.
|
||||
probe는 decode 크기가 primary 후보의 pixel 크기와 정확히 같아야 통과하므로
|
||||
`PRIMARY_REQUIRED` preset의 `fit`은 `cover`/`contain`/`fill`만 허용한다(D-12).
|
||||
원본 비율을 유지하는 `inside`/`outside`는 probe를 쓰지 않는 preset에서만 쓴다.
|
||||
실제 `<img crossorigin="anonymous">`는 same-origin일 때 cookie를 보낼 수
|
||||
있으므로 registry는 CDN origin이 composition의 application origin과 같으면
|
||||
생성 단계에서 거절한다. private CDN 응답은 cookie나 ambient authorization에
|
||||
@@ -559,6 +647,14 @@ private delivery는 `PRIMARY_REQUIRED` browser probe가 필수이며 이를 `NON
|
||||
- private rendition은 짧은 expiry와 필수 `no-store`를 쓴다.
|
||||
- CDN cache hit 여부는 authorization이나 asset safety proof가 아니다.
|
||||
|
||||
`PRIMARY_REQUIRED` preset(private asset은 항상)의 `resolve()`는 primary candidate를
|
||||
preset의 encoded·decoded 예산까지 내려받아 decode한다. private 응답은 `no-store`라
|
||||
`<img>`가 같은 URL을 한 번 더 받는다. 그래서 runtime은 같은 asset reference와
|
||||
preset에 대해 통과한 probe를 capability가 유효한 동안 재사용하고, 동시에 도는
|
||||
probe를 `maxConcurrentProbes`(기본 4, 최대 32)개로 제한한다. 넘는 호출은 자리를
|
||||
기다리며, 기다리다 abort하면 자리를 차지하지 않는다(`image-cdn-runtime.ts`
|
||||
`passedProbes`, `acquireProbeSlot`).
|
||||
|
||||
image probe의 단일 bounded deadline은 response header fetch, streamed body read와
|
||||
native decode 전체를 포함한다. timeout/cancel/error 시 reader를 cancel하고,
|
||||
abort 뒤 늦게 resolve한 response body도 cancel하며 늦게 생성된 `ImageBitmap`도
|
||||
@@ -624,12 +720,31 @@ analytics는 제품 presentation이 소유한다.
|
||||
| image capability verification concurrency ceiling | `LIMIT_EXCEEDED` | 진행 작업 종료 대기 또는 runtime 부하 조사 |
|
||||
| closed Image CDN runtime 사용 | `UNAVAILABLE` | 새 runtime composition |
|
||||
| network/429/모든 5xx | `UNAVAILABLE` | bounded retry/backoff |
|
||||
| complete 응답 유실·진행 중 | `UNAVAILABLE`(`UPLOAD_COMPLETE`, retryable) | 같은 파일로 `upload()` 재호출, 또는 `abort()`가 resourceId와 함께 `ALREADY_COMPLETED` 반환(4.3) |
|
||||
|
||||
관측성에는 operation, safe outcome, byte/part/candidate bucket, retry bucket과
|
||||
`ResumableUploadPort.upload()` 실패의 `recovery`는 호출자가 할 행동 하나를
|
||||
가리킨다(`resumable-upload.ts` port 주석, `resumable-upload-runtime.ts`
|
||||
`toUploadAction`). 이 다섯 값 밖의 값은 `upload()`에서 나오지 않는다.
|
||||
|
||||
| recovery | 호출자 행동 |
|
||||
| --- | --- |
|
||||
| `RESUME` | 같은 파일·key로 `upload()`를 다시 부른다. `retryable:true`면 자동 재시도해도 된다. capability 재발급이 필요한 실패도 여기로 온다 |
|
||||
| `RECONCILE` | `upload()`를 다시 부른다. 서버 상태를 먼저 읽는다(예: 다른 문맥이 checkpoint를 먼저 씀) |
|
||||
| `RESTART` | `abort()` 뒤 `upload()`로 새 session을 연다. abort가 남아 있음(operation `UPLOAD_ABORT`), 읽을 수 없는 checkpoint 행, 서버 part가 파일과 다름 |
|
||||
| `RESELECT` | 파일을 다시 고르거나, 다른 파일이면 새 key를 쓴다 |
|
||||
| `NONE` | 이 요청으로 할 행동이 없다. 잘못된 입력, 상한·정책·권한 거절, 호출자 자신의 abort, 다시 불러도 같은 답이 오는 서버 응답(정책보다 긴 session 등) |
|
||||
|
||||
관측성에는 operation, safe outcome, byte/candidate bucket, retry bucket과
|
||||
failure code만 기록한다. capability ID, URL, query, asset/resource/session ID,
|
||||
file name, digest, raw ETag, receipt와 backend message는 log/diagnostics/telemetry에
|
||||
기록하지 않는다. 앞 절의 strict checkpoint allowlist만 durable 예외다.
|
||||
|
||||
같은 observer를 두 계층에 넘겨도 한 사건은 한 번만 센다. resumable runtime은
|
||||
part마다 최종 결과 하나를 `UPLOAD_PART`로 남기고, 그 part에 쓴 시도 수를
|
||||
`countBucket`에 넣는다(retry bucket). presigned 실행기의 PUT 시도 하나하나는
|
||||
`PRESIGNED_TRANSFER`로 따로 남는다(`resumable-upload-runtime.ts`
|
||||
`transferMissingParts`, `presigned-transfer-executor.ts` `uploadParts.put`).
|
||||
|
||||
## 8. 조합 조건
|
||||
|
||||
현재 `src/adapters/browser-transfer/index.ts`는 개별 presigned, upload와 Image CDN
|
||||
|
||||
@@ -618,7 +618,8 @@ stream + epoch별 `lastAppliedSequence`를 기준으로 처리한다.
|
||||
| `sequence == lastApplied + 1` | 순차 적용 |
|
||||
| `sequence > lastApplied + 1` | gap; delta 적용 중지, `RESYNC_REQUIRED` |
|
||||
| unknown `streamEpoch` | old/new epoch를 섞지 않고 registered snapshot 또는 session rebuild |
|
||||
| dedupe/queue ceiling 초과 | 임의 eviction 후 계속 적용하지 않고 registered recovery |
|
||||
| dedupe window 가득 참 | 가장 오래된 항목부터 제거(FIFO)하고 계속 적용. 창에서 밀려난 재전송은 `sequence <= lastApplied`로 drop |
|
||||
| queue ceiling 초과 | 임의 eviction 후 계속 적용하지 않고 registered recovery |
|
||||
| captured old runtime generation | late callback safe drop + aggregate diagnostic |
|
||||
| current connection의 `scopeBinding` mismatch | effect/sequence/cursor 0, freshness `UNKNOWN`, close + session revalidation + registered recovery |
|
||||
|
||||
@@ -763,21 +764,39 @@ effectiveDelay = max(localDelay, validServerNotBefore)
|
||||
bound로 취급한다. `effectiveDelay`가 implementation max delay나 남은 elapsed
|
||||
budget을 넘으면 낮춰 clamp하지 않고 reconnect/poll을 종료해
|
||||
`DEGRADED`/`STALE`로 전환한다.
|
||||
- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. stable-open
|
||||
window 또는 valid heartbeat/event 뒤에만 reset한다.
|
||||
- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. valid
|
||||
heartbeat/event를 받았고 stable-open window도 지났을 때만 attempt 수와
|
||||
elapsed budget을 reset한다(둘 중 하나만으로는 reset하지 않는다,
|
||||
`reconnect-policy.ts:131-149`). 이 확인은 server close뿐 아니라 offline과
|
||||
`waitClosed` throw를 포함한 session의 모든 종료 경로에서 한다
|
||||
(`reconnect-coordinator.ts:886-900`). valid heartbeat는 SSE `onComment`와
|
||||
WebSocket `HEARTBEAT_ACK` 관측이다. 조합 코드가 이를
|
||||
`markValidHeartbeatOrEvent`로 넘긴다.
|
||||
- stream reconnect는 realtime recovery coordinator, credential recovery는
|
||||
session owner, Poll attempt 사이 cadence는 poll coordinator가 각각 소유한다.
|
||||
Poll-bound REST transport retry와 Query retry는 끈다. 같은 logical recovery의
|
||||
effect writer나 timer가 둘 이상 활성화되지 않게 generation으로 배타화한다.
|
||||
- `offline` 상태에서는 timer로 재시도하지 않고 online hint를 기다린다.
|
||||
`navigator.onLine`은 실제 backend reachability authority가 아니다.
|
||||
offline 대기 시간은 elapsed budget에 넣지 않는다. online으로 돌아오면
|
||||
elapsed budget을 다시 시작하고 attempt 상한은 유지한다
|
||||
(`reconnect-coordinator.ts:550-559`).
|
||||
- auth expiry는 session owner의 single-flight recovery를 한 번 요청한다.
|
||||
실패하면 `AUTH_REQUIRED`로 멈춘다.
|
||||
- protocol/schema/forbidden/policy failure는 retry하지 않는다.
|
||||
- 외부 close/result의 rate limit/provider unavailable은 유효한 bounded server
|
||||
not-before hint가 있을 때만 재시도한다. hint가 없거나 ceiling 밖이면
|
||||
terminal이다. adapter 내부 provider throw처럼 server 응답이 아닌 실패만
|
||||
남은 retry budget 안에서 local full-jitter를 사용할 수 있다.
|
||||
- 재시도 여부는 transport가 보고한 `retryable`이 정한다. reconnect
|
||||
coordinator는 retryable인 `CONNECT_TIMEOUT`·`IDLE_TIMEOUT`·`OFFLINE`·
|
||||
`PROVIDER_UNAVAILABLE`·`RATE_LIMITED`를 server hint가 없어도 남은 budget
|
||||
안에서 local full-jitter로 재시도한다(`reconnect-coordinator.ts:1582-1593`).
|
||||
server hint가 꼭 필요한 실패는 transport가 hint 없을 때 `retryable: false`로
|
||||
보고해 terminal이 된다. SSE `429`/`503`에 유효한 `Retry-After`가 없을 때
|
||||
(`sse/fetch-sse-connection.ts:592-616`)와 WebSocket `OVERLOADED`
|
||||
(`websocket/websocket-connection.ts:1818-1823`)가 여기 해당한다. SSE
|
||||
`502`/`504`와 WebSocket `RESTART`·`NETWORK_LOST`는 hint 없이 bounded
|
||||
재시도한다. hint가 있으면 not-before bound이고, ceiling을 넘으면 terminal이다.
|
||||
SSE `Retry-After`는 `onRetryHint`로만 나오므로 `readSseForReconnect`로 읽어야
|
||||
reconnect coordinator의 `serverNotBeforeMs`에 닿는다
|
||||
(`sse/fetch-sse-connection.ts:488-506`).
|
||||
- budget을 소진하면 infinite reconnect가 아니라 `DEGRADED`와 명시된 fallback
|
||||
또는 stale UI로 전환한다.
|
||||
|
||||
@@ -801,6 +820,17 @@ attempt당 상한은 30초다.
|
||||
|
||||
### 5.4 Visibility, page lifecycle와 network
|
||||
|
||||
5.4~5.6의 "기본 동작"은 조합 코드가 해야 하는 일이다. reference runtime은 이
|
||||
동작을 강제하지 않는다.
|
||||
|
||||
- reconnect coordinator가 따르는 환경 신호는 online 하나다
|
||||
(`reconnect-coordinator.ts:106-113`). SSE와 WebSocket 연결에는 visibility 입력이
|
||||
없다. visibility를 직접 듣는 것은 polling뿐이다
|
||||
(`polling/bounded-poll-coordinator.ts:202-205`).
|
||||
- registry의 `hiddenPolicy`, `killSwitchId`, `fallback`은 검증만 하고 읽지 않는다
|
||||
(`src/contracts/realtime-streams.ts:74-79`). hidden·`pagehide`·logout 때 닫기,
|
||||
kill switch, fallback 전환은 조합 코드가 한다.
|
||||
|
||||
| signal | 기본 동작 |
|
||||
| --- | --- |
|
||||
| `visibilitychange -> hidden` | 새 Polling 중지, configured grace 뒤 live connection pause/close |
|
||||
@@ -844,10 +874,17 @@ session authority announces local transition
|
||||
late socket event, poll response, auth recovery, snapshot, notification handoff와
|
||||
Service Worker message는 old generation/scope면 적용하지 않는다.
|
||||
|
||||
reference runtime에서 위 흐름의 "close SSE/WebSocket"은 조합 코드가 reconnect
|
||||
coordinator의 `close()`를 불러야 일어난다. `isCurrent`는 attempt·sleep·waitClosed
|
||||
경계에서만 확인하므로, 열린 채 조용한 session은 다음 event나 server close까지
|
||||
남는다(`reconnect-coordinator.ts:175-181`). 그동안 도착한 event는 stream
|
||||
coordinator의 scope fence가 막는다.
|
||||
|
||||
long-lived connection은 connect-time authorization만 신뢰하지 않는다. backend는
|
||||
active subscription의 permission/session revoke를 control event 또는 close로
|
||||
전파하고, registry-owned `maxConnectionAge`/reauth deadline 안에 current
|
||||
credential로 재연결하게 한다. SSE처럼 별도 subscribe command가 없는 transport는
|
||||
credential로 재연결하게 한다. `maxConnectionAge`는 아직 registry 필드가 아니다.
|
||||
채택하는 제품이 조합 코드에서 정한다. SSE처럼 별도 subscribe command가 없는 transport는
|
||||
권한 변경 시 server가 stream을 종료해야 한다. server hint는 client hard
|
||||
connection-age ceiling을 늘릴 수 없다.
|
||||
|
||||
@@ -873,7 +910,7 @@ best-effort hint다.
|
||||
|
||||
- tab 하나당 selected primary transport physical connection 1개
|
||||
- WebSocket logical subscription multiplexing 또는 SSE single-feed local dispatch
|
||||
- hidden tab close/pause 정책
|
||||
- hidden tab close/pause 정책(조합 코드가 적용한다. 5.4 참조)
|
||||
- visible 복귀 시 authoritative snapshot
|
||||
|
||||
SharedWorker나 leader election으로 origin 전체 connection을 하나로 만드는 기능은
|
||||
@@ -1004,8 +1041,8 @@ Last-Event-ID = approved current cursor, CURSOR profile only
|
||||
| `401` | session recovery 한 번, 실패 시 `AUTH_REQUIRED` |
|
||||
| `403` | `FORBIDDEN`, retry 금지 |
|
||||
| `409`/`410` with exact reset contract | cursor expired, snapshot resync |
|
||||
| `429` | bounded `Retry-After`, retry budget 소비 |
|
||||
| `502`/`503`/`504` | bounded provider backoff |
|
||||
| `429`/`503` | 유효한 `Retry-After`가 있으면 그 시각 이후 bounded 재시도, retry budget 소비. 없거나 상한 밖이면 terminal |
|
||||
| `502`/`504` | hint 없이 bounded provider backoff |
|
||||
| redirect, wrong type, malformed stream | protocol/policy failure, fail-closed |
|
||||
|
||||
generic HTTP client의 전체-body decoder와 retry를 우회하되 credential, diagnostics,
|
||||
@@ -1148,7 +1185,7 @@ closed category로 mapping한다.
|
||||
| --- | --- | --- |
|
||||
| `NORMAL` | intentional close/drain | 아니오 |
|
||||
| `RESTART` | server deploy/restart | bounded |
|
||||
| `OVERLOADED` | server capacity/rate | exact server hint가 있을 때만 bounded; 없으면 terminal |
|
||||
| `OVERLOADED` | server capacity/rate | exact server hint가 있을 때만 bounded; 없으면 terminal. 현재 closed protocol에는 hint 필드가 없어 항상 terminal이다 |
|
||||
| `AUTH_REQUIRED` | session expired | single-flight recovery 뒤 한 번 |
|
||||
| `FORBIDDEN` | policy/authorization | 아니오 |
|
||||
| `PROTOCOL_MISMATCH` | version/schema/subprotocol | 아니오 |
|
||||
@@ -1279,6 +1316,16 @@ user opt-in
|
||||
`matchAll()`이 signal을 따르지 않거나 `waitUntil()`이 동기 예외를 내도 늦은
|
||||
`postMessage`를 허용하지 않고 degraded observation으로 닫는다.
|
||||
- re-subscribe가 실패하면 notification을 끄고 foreground fallback을 유지한다.
|
||||
- 여러 tab은 native subscription(worker registration당 1개)과 origin의 fence
|
||||
record를 공유한다. 그래서 `enable`·`reconcile`·`revoke`는 origin 단위 Web Lock
|
||||
`web-push-control` 안에서 하나씩 실행한다. `inspect`는 읽기만 하므로 lock을
|
||||
잡지 않는다. composition이 `navigator.locks`를 `lockManager`로 넘기고, Web
|
||||
Locks가 없으면 `PUSH_UNSUPPORTED`로 보고한다
|
||||
(`src/adapters/web-push/push-subscription-adapter.ts`의 `exclusive`,
|
||||
`supportReadiness`). activate 실패나 session binding 불일치의 보상은 backend
|
||||
association을 revoke하지만 native `unsubscribe()`는 그 호출이 새로 만든
|
||||
subscription에만 한다. 이미 있던 subscription은 다른 tab의 association일 수
|
||||
있다(`activateCommit`, 06-02).
|
||||
|
||||
`associationEpoch`은 backend registration authority가 발급한다.
|
||||
`releaseEpoch`은 signed/verified release manifest에서 온다. backend registration
|
||||
@@ -1298,6 +1345,26 @@ logout/account switch:
|
||||
찾아 best-effort close한다.
|
||||
6. 새 account opt-in은 기존 consent와 association 정책을 다시 평가한다.
|
||||
|
||||
logout 없이 account가 바뀐 경우(session 만료, cookie 삭제, logout 중 crash)에는
|
||||
새 session이 이전 authority를 모른다. 그래서 `revoke`를 부를 수 없고, `enable`과
|
||||
`reconcile`은 `STALE_AUTHORITY`로 막힌다. 이때는 `revokeForeign({ nextAuthority })`
|
||||
를 한 번 부른다(`src/application/ports/out/web-push-control.ts`). 다른
|
||||
`fenceGeneration`이 가진 fence를 `nextAuthority`의 `REVOKED`로 회전하고, 그 fence가
|
||||
갖던 association을 revoke하고, native subscription과 그 association의 notification을
|
||||
위 1~5 순서로 정리한다. 그 뒤 새 account의 opt-in이 가능하다. `nextAuthority`의
|
||||
`fenceGeneration`이 이미 가진 fence(같은 session의 다른 tab이 opt-in한 경우 등)는
|
||||
건드리지 않고 `inspect` 결과를 돌려준다(`push-subscription-adapter.ts`
|
||||
`revokeForeign`, 06-06). 이 연산은 저장된 authority를 증명으로 요구하지 않는다.
|
||||
그래서 BFF가 방금 확인한 현재 session의 authority로만 부른다. 오래된 session을 가진
|
||||
tab이 부르면 현재 account의 association을 revoke하게 된다.
|
||||
|
||||
Web Push를 채택하려면 server 쪽에 다음 두 가지가 있어야 한다. 비정상 전환에서
|
||||
client revoke가 늦거나 실패해도 이전 account의 push를 막는 것은 이 둘뿐이다.
|
||||
|
||||
- 짧은 association TTL: 갱신되지 않은 association은 server가 스스로 만료시킨다.
|
||||
- send-time authorization: 보낼 때마다 association의 account와 session binding이
|
||||
아직 유효한지 확인한다.
|
||||
|
||||
backend revoke가 ambiguous하면 server subscription은 짧은 association TTL,
|
||||
session/account epoch 확인과 send-time authorization으로 추가 방어한다.
|
||||
local `REVOKED` transaction이 실패하면 “late push를 반드시 drop했다”고 주장하지
|
||||
@@ -1411,6 +1478,20 @@ Service Worker는 언제든 종료될 수 있다. in-memory cursor, queue, auth
|
||||
timer를 authority로 사용하지 않는다. `waitUntil`도 무제한 lifetime을 보장하지
|
||||
않으므로 large fetch, retry loop, data migration을 넣지 않는다.
|
||||
|
||||
**조용한 drop은 설계 의도다(D-14).** 검증에 실패한 push(EXPIRED,
|
||||
RELEASE_MISMATCH, association mismatch, fence 읽기 실패, handler deadline 초과,
|
||||
malformed/unknown)는 알림을 띄우지 않고 끝난다. 계정 정보가 없는 generic
|
||||
알림으로 대신 띄우지 않는 이유는 logout·계정 전환 뒤에 도착한 push가 어떤
|
||||
형태로든 사용자에게 보이면 안 되기 때문이다. 대가는 두 가지다.
|
||||
|
||||
- Chrome은 `userVisibleOnly` push가 알림 없이 끝나면 "This site has been updated
|
||||
in the background" 같은 기본 알림을 대신 띄울 수 있다.
|
||||
- Safari(WebKit)는 알림 없는 push가 반복되면 구독을 취소할 수 있다.
|
||||
|
||||
그래서 drop은 드물어야 한다. backend는 ACTIVE association에만 보내고, 짧은
|
||||
server TTL을 쓰고, release를 바꾼 직후에는 이전 release epoch로 보내지 않는다.
|
||||
drop은 `web_push_hint_processed`의 `FAILED` + reason으로 관측한다.
|
||||
|
||||
### 8.5 Notification content와 click
|
||||
|
||||
- title/body/icon/action은 closed notification registry가 만든다.
|
||||
@@ -1438,8 +1519,17 @@ type NotificationClickDataV1 = Readonly<{
|
||||
|
||||
worker가 종료·재시작된 뒤에도 click을 처리할 수 있도록 이 bounded, non-sensitive
|
||||
envelope만 `NotificationOptions.data`에 넣는다. click handler는 codec/size/expiry,
|
||||
current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch는
|
||||
route를 열지 않고 notification을 닫는다. 이미 표시된 notification은 logout 뒤
|
||||
current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch
|
||||
(만료, fence·release 불일치, fence 읽기 실패, 모르는 route)는 notification을 닫고
|
||||
요청한 route 대신 **앱 루트를 handoff 데이터 없이 연다**(D-14). 앱 루트는 worker의
|
||||
`registration.scope`, 즉 router base path다(예: `/app/`). scope를 모르면
|
||||
`<origin>/`을 쓴다(`src/adapters/web-push/service-worker-scope-host.ts`,
|
||||
`inbound/notification-click-adapter.ts`의 `appRootUrl`, 06-09).
|
||||
사용자의 탭이 아무 반응 없이 사라지지 않게 하되, 거절된 click의 route와
|
||||
notification 정보는 페이지로 넘기지 않는다. 결과는 여전히 실패로 보고하고
|
||||
(`web_push_click_dispatched` `FAILED` + reason, `nativeEffect`는 루트 창의
|
||||
확실성), 브라우저가 창 열기를 거절한 native 실패나 deadline/abort 뒤에는 루트를
|
||||
다시 시도하지 않는다. 이미 표시된 notification은 logout 뒤
|
||||
OS notification center에 남을 수 있으므로 copy는 항상 account-neutral하고
|
||||
민감하지 않아야 하며, `getNotifications()` cleanup 성공을 privacy 보장으로
|
||||
과장하지 않는다.
|
||||
@@ -1709,7 +1799,7 @@ task는 run을 fail-closed로 끝내되 underlying task가 settle할 때까지 l
|
||||
`DRAINING`으로 유지하여 다음 physical connection을 허용하지 않는다.
|
||||
|
||||
미선택 reference source 전체를 tree-shaking 없이 합성하는 optional-recipe
|
||||
측정의 gzip 상한은 40,000 bytes다. 이 값은 production bundle 허용량이 아니라
|
||||
측정의 gzip 상한은 40,900 bytes다(2026-09-27 성숙도 리뷰 04-x·06-x 반영 뒤 측정값 40,886을 100바이트 단위로 올림). 이 값은 production bundle 허용량이 아니라
|
||||
RT-01~RT-04 reference runtime의 회귀 예산이며, production asset에는 계속
|
||||
미선택 realtime module이 0이어야 한다.
|
||||
|
||||
@@ -1828,6 +1918,13 @@ drop-only malformed 처리는 명시적으로 non-state-bearing heartbeat/contro
|
||||
허용하며, threshold를 넘으면 protocol close한다. state-bearing event나 unknown
|
||||
event type을 버리고 freshness를 `CURRENT`로 유지하지 않는다.
|
||||
|
||||
stream을 찾은 뒤 decode가 실패하면 consumer가 그 stream의 freshness를 `UNKNOWN`으로
|
||||
바꾼다. 다음 event는 recovery부터 한다(`event-consumer.ts:89-90`,
|
||||
`stream-coordinator.ts:998-1001`). registry에 없는 event type은 `MALFORMED_EVENT`가
|
||||
아니라 `PROTOCOL_MISMATCH`(operation `REGISTRY`)로 닫는다(`event-codec.ts:172-175`).
|
||||
event type 추가는 이전 bundle에는 호환 변경이 아니다. 조합 코드는 operation
|
||||
`REGISTRY` 실패를 "구버전 client"로 보고 reload를 유도한다.
|
||||
|
||||
### 13.2 Effect certainty
|
||||
|
||||
| effect | certainty |
|
||||
@@ -1883,6 +1980,23 @@ push:
|
||||
- `web_push_click_dispatched`
|
||||
- `web_push_association_revoked`
|
||||
|
||||
reference runtime의 관측 지점은 다음과 같다. 조합 코드는 attempt나 session을
|
||||
감싸지 않고 이 관측을 위 event로 옮긴다.
|
||||
|
||||
| runtime 관측 | 만들 수 있는 event |
|
||||
| --- | --- |
|
||||
| reconnect `ATTEMPT_STARTED` | `realtime_connect_attempted` |
|
||||
| reconnect `SESSION_OPENED`, 또는 open 전의 `RETRY_SCHEDULED`·`RUN_ENDED` | `realtime_connect_finished` |
|
||||
| reconnect `SESSION_CLOSED` | `realtime_connection_closed` |
|
||||
| reconnect `RETRY_SCHEDULED`(실패 kind, 대기 bucket), `RUN_ENDED`(`EXHAUSTED`·`TERMINAL`·`ABORTED`·`COMPLETED`) | 14.2 재연결 시도·대기·소진 비율 |
|
||||
| WebSocket `HEARTBEAT_ACK` | `realtime_heartbeat_observed` |
|
||||
| polling `LEASE_STARTED`, `ATTEMPT_FINISHED`(`VALUE`·`UNCHANGED`·실패 kind), `LEASE_STOPPED` | `bounded_poll_*` |
|
||||
|
||||
근거는 `reconnect-coordinator.ts:128-182`,
|
||||
`polling/bounded-poll-coordinator.ts:87-113`,
|
||||
`websocket/websocket-connection.ts:376-378`이다. sink가 throw해도 제어 흐름은
|
||||
바뀌지 않는다(`result.ts`의 `observeRealtime`).
|
||||
|
||||
모든 event는 semantic registry에 등록하고 arbitrary payload를 받지 않는다.
|
||||
diagnostics sink failure는 connection, worker handler, poll lease와 cleanup을
|
||||
실패시키지 않으며 재귀 telemetry를 만들지 않는다.
|
||||
@@ -1919,7 +2033,7 @@ server-side metric을 함께 사용한다.
|
||||
- CURSOR/non-CURSOR discriminated codec와 conditional cursor commit
|
||||
- effect failure 뒤 cursor 미commit
|
||||
- deterministic fake clock/random의 full-jitter backoff
|
||||
- stable-open 이후에만 retry attempt reset
|
||||
- valid heartbeat/event와 stable-open을 둘 다 충족한 뒤에만 retry attempt reset
|
||||
- queue/dedupe/reorder ceiling
|
||||
- old-generation late callback drop와 current scope-binding protocol violation 분리
|
||||
- effect/recovery callback lease의 `isCurrent()` commit 직전 확인과 callback
|
||||
|
||||
@@ -280,6 +280,18 @@ chunk recovery 순서:
|
||||
4. 안전한 support surface와 trace/build ID를 표시한다.
|
||||
5. recovery 결과를 redacted diagnostics에 기록한다.
|
||||
|
||||
지원 참조는 사용자가 문의할 때 말하는 값이고, 진단 이벤트에서 같은 값을 찾을
|
||||
수 있다.
|
||||
|
||||
- 라우트 렌더 실패: `buildId:incidentId`. 같은 incident ID가 `ui.render.failed`
|
||||
진단의 `correlation_id`에 남는다(`render-error-boundary.tsx`의
|
||||
`newIncidentId`, `create-application.ts`의 `reportRenderFailure`). 화면에는
|
||||
"한 번 새로고침" 버튼이 있다(`app-router.tsx`의 `RouteFailureSurface`).
|
||||
- 복구하지 못한 청크 실패: 같은 형식이다. `ChunkRecoveryBoundary`의
|
||||
`onUnrecovered`가 같은 ID로 `ui.render.failed`를 기록한다.
|
||||
- 조회 실패: `AppFailure.requestId`. HTTP 진단의 `correlation_id`와 같은 값이다
|
||||
(`async-surface.tsx`의 `TerminalErrorSurface`).
|
||||
|
||||
custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary는
|
||||
`location.key` 또는 route ID가 바뀌면 적절히 reset된다.
|
||||
|
||||
@@ -289,9 +301,15 @@ custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary
|
||||
- mouse 사용자가 불필요한 focus ring을 보지 않게 할 수는 있지만 keyboard focus
|
||||
indication을 전역으로 제거하지 않음
|
||||
- modal/drawer가 닫히면 opener에 focus 복원
|
||||
- backward/forward navigation은 저장한 scroll 복원
|
||||
- backward/forward navigation은 저장한 scroll 복원. 복원은 브라우저가 하고,
|
||||
`RouteLifecycle`은 POP이 아닐 때만 top으로 보낸다(`app-router.tsx`).
|
||||
`PageHeader`의 heading focus는 `preventScroll`이라 복원된 위치를 옮기지 않는다
|
||||
- 새 primary route는 top으로 이동
|
||||
- hash target은 fixed header offset과 focus 가능 여부를 처리
|
||||
- hash target은 fixed header offset과 focus 가능 여부를 처리. 페이지가 그려진 뒤
|
||||
`PageHeader`가 대상으로 스크롤하고, 대상이 focus 가능하면 대상에, 아니면
|
||||
heading에 focus한다(`page-header.tsx`). header 높이는 `html`의
|
||||
`scroll-padding-top`으로 뺀다(`shell.css`). 브라우저 검증은
|
||||
`tests/e2e/scroll-restoration.spec.ts`
|
||||
- screen reader용 route title/live announcement는 중복 발표를 피함
|
||||
|
||||
### 6.4 취소와 dirty form
|
||||
|
||||
@@ -26,14 +26,10 @@ remain stable in the shell.
|
||||
|
||||
## Registered routes
|
||||
|
||||
| ID | Path | Access | Surface |
|
||||
| --- | --- | --- | --- |
|
||||
| `APP_HOME` | `/` | public | readiness dashboard |
|
||||
| `EXAMPLES_UI` | `/examples/ui` | public | interactive primitives and tokens |
|
||||
| `EXAMPLES_STATES` | `/examples/states` | public | async and access state matrix |
|
||||
| `EXAMPLES_AUTH` | `/examples/auth` | public | session integration controls |
|
||||
| `REFERENCE_RESOURCE_LIST` | `/examples/reference-resources` | session-required | removable vertical slice |
|
||||
| `NOT_FOUND` | `*` | public | safe navigation recovery |
|
||||
The route list is `ROUTE_REGISTRY` (`src/features/installed-feature-contracts.ts`):
|
||||
the platform routes of `src/contracts/routes.ts` plus the routes of every
|
||||
installed feature. The platform overview page (`/examples/platform`) shows the
|
||||
composed list at runtime, so this document does not keep a copy of it.
|
||||
|
||||
Navigation labels and order come from `ROUTE_REGISTRY`; the sidebar does not
|
||||
maintain a second route list. The client access decision never claims to be
|
||||
@@ -49,31 +45,113 @@ remain opaque to the application and presentation layers.
|
||||
- `external`: delegates to `globalThis.__CA_FRONTEND_AUTH_OWNER__`
|
||||
- missing/invalid external owner: fails closed as `integration-failed`
|
||||
|
||||
An external owner implements `readState`, `subscribe`, `beginSignIn`,
|
||||
`signOut`, `attachCredential`, `recoverSession`, and
|
||||
`notifyUnauthenticated`. It owns token acquisition and storage.
|
||||
An external owner implements `readState`, `readSubject`, `subscribe`,
|
||||
`beginSignIn`, `signOut`, `attachCredential`, `recoverSession`, and
|
||||
`notifyUnauthenticated`. It owns token acquisition and storage. An owner that
|
||||
lacks any of these methods is rejected, and the session fails closed as
|
||||
`integration-failed`.
|
||||
|
||||
`readSubject()` is required. The server-state cache is cleared only when the
|
||||
session state or the subject changes, so a token refresh for the same user
|
||||
keeps cached data. `readSubject()` must return:
|
||||
|
||||
- an opaque, non-empty string that stays the same for one user across token
|
||||
refreshes and differs between users: the OIDC `sub` claim, Supabase
|
||||
`session.user.id`, or Firebase `user.uid`
|
||||
- `null` when nobody is signed in
|
||||
- never an access token, refresh token, or any other credential
|
||||
|
||||
If `readSubject()` returns `null` or `""` while the owner reports
|
||||
`authenticated`, the runtime cannot tell a refresh from an account switch. It
|
||||
fails closed: every such notification clears server state, and each one records
|
||||
the `cache.operation.failed` diagnostic with `operation: SCOPE_FENCE` and
|
||||
`reason: SUBJECT_MISSING`. Seeing that diagnostic means the owner is not
|
||||
reporting its subject. The `demo` adapter reports one fixed demo user as its
|
||||
subject.
|
||||
|
||||
Migration: `readSubject()` used to be optional. An owner written for an earlier
|
||||
release must add it; without it the owner is rejected at startup (the session
|
||||
becomes `integration-failed`) and a TypeScript owner no longer compiles
|
||||
against `ExternalSessionOwner`. A code path that implements `AuthSessionPort`
|
||||
or `SessionGateway` directly must add `getSubject()` the same way.
|
||||
|
||||
## Extending the starter
|
||||
|
||||
The steps below describe the current extension path. New platform work should follow
|
||||
New platform work should follow
|
||||
[routing, page templates, and reusable patterns](./routing-pages-and-patterns.md)
|
||||
and the
|
||||
[TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md)
|
||||
rather than adding another independent route or data-loading convention.
|
||||
|
||||
1. Add a serializable contribution under the feature ownership boundary and
|
||||
install it through `src/features/installed-feature-contracts.ts`.
|
||||
2. Add the lazy component and route codecs through
|
||||
`src/features/installed-feature-runtimes.tsx`.
|
||||
3. Compose feature application inputs and outbound gateways only through
|
||||
`src/features/installed-feature-adapters.ts`.
|
||||
4. Use the semantic tokens, UI primitives, and state surfaces before adding a
|
||||
project-specific variant.
|
||||
5. Add component behavior, all-engine E2E, automated axe, and signed manual
|
||||
route evidence.
|
||||
6. Run `test:sample-removal` to prove the generic starter typechecks, passes
|
||||
architecture/registry/tests/coverage/source-evidence/home smoke, and builds
|
||||
without the complete reference feature.
|
||||
### Ownership declarations
|
||||
|
||||
Features, contexts and apps are discovered by
|
||||
`scripts/generate-product-feature-index.ts`. Each boundary declares only its
|
||||
parent, as exported string or integer literals the generator reads:
|
||||
|
||||
| File | Exports |
|
||||
| --- | --- |
|
||||
| `src/apps/<app>/app-module.ts` | `APP_MODULE_ID`, `APP_MAX_CONTEXTS` |
|
||||
| `src/contexts/<context>/context-module.ts` | `CONTEXT_MODULE_ID`, `CONTEXT_APP_ID`, `CONTEXT_ROUTE_PATH`, `CONTEXT_MAX_FEATURES` |
|
||||
| `src/features/<feature>/feature-module.ts` | `FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID`, `FEATURE_MODULE` |
|
||||
| `src/features/<feature>/context-routes.ts` | `FEATURE_CONTEXT_ROUTES` |
|
||||
|
||||
The generator writes `src/.generated/` (git-ignored): the feature index the
|
||||
installed catalogs import, the context index the router loads lazily, and the
|
||||
selected app. Every build and check script runs it first; run it yourself with
|
||||
`corepack pnpm generate:feature-index`. It fails, naming the file, when:
|
||||
|
||||
- a directory under `src/features/` has no `feature-module.ts` and no
|
||||
`NOT_INSTALLED` marker file (`src/features/local-draft-feature/NOT_INSTALLED`
|
||||
is the one intentional example);
|
||||
- a feature names an undeclared context, or a context an undeclared app;
|
||||
- a context or app exceeds its declared budget;
|
||||
- `VITE_PRODUCT_FEATURES` names a feature the app does not declare. The
|
||||
variable narrows the installed set here, before anything is compiled.
|
||||
|
||||
### Adding a feature
|
||||
|
||||
1. Create `src/features/<feature>/feature-module.ts`. Build `FEATURE_MODULE`
|
||||
with `defineFeatureModule` (`src/features/feature-module.ts`): the feature's
|
||||
contract (routes, route runtime contracts, API operations, invalidation,
|
||||
schemas, runtime schemas, mappers), its adapter contributions
|
||||
(`defineFeatureAdapterContribution`, with `needs` naming the platform
|
||||
capabilities it receives), its runtime descriptor (route codecs), its message
|
||||
catalogs and its contract contributions.
|
||||
`src/features/reference-feature/feature-module.ts` is the complete example.
|
||||
2. Create `src/features/<feature>/context-routes.ts` exporting
|
||||
`FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here; the
|
||||
owning context loads this file only when its route root is visited
|
||||
(`src/features/reference-feature/context-routes.ts`).
|
||||
3. Name the owning context in `FEATURE_CONTEXT_ID`. Use an existing context or
|
||||
add `src/contexts/<context>/context-module.ts` owned by the app.
|
||||
4. If the feature has application input, augment `ApplicationFeatureInputs`
|
||||
from the feature (`src/features/local-draft-feature/application/local-draft-api.ts`).
|
||||
5. Run `corepack pnpm check:architecture`, `corepack pnpm check:types`,
|
||||
`corepack pnpm check:registries` and the tests. `tests/unit/two-feature-install-typecheck.test.ts`
|
||||
keeps the installed catalogs compiling with more than one feature.
|
||||
6. Run `corepack pnpm test:sample-removal -- --feature=<feature id>` to prove
|
||||
the product still builds and passes its gates without the feature.
|
||||
|
||||
Files outside the feature directory:
|
||||
|
||||
| File | Change |
|
||||
| --- | --- |
|
||||
| `src/.generated/*` | regenerated automatically |
|
||||
| `src/contexts/<context>/context-module.ts` | only when the feature needs a new context |
|
||||
| `config/runtime/<profile>.json` | optional `FEATURE_OVERRIDES` entry to switch the feature off |
|
||||
| `src/bootstrap/runtime-adapters.ts` | only when `needs` includes `indexedDb`: add the capability, built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts` |
|
||||
|
||||
The central catalogs (`src/features/installed-*.ts`) and the registry
|
||||
governance file do not change: consumer directories there are globs over every
|
||||
feature (`src/features/*/adapters`, `config/contracts/registry-governance.json`).
|
||||
|
||||
### Before shipping
|
||||
|
||||
- Use the semantic tokens, UI primitives, and state surfaces before adding a
|
||||
project-specific variant.
|
||||
- Add component behavior, all-engine E2E, automated axe, and signed manual
|
||||
route evidence.
|
||||
|
||||
Theme preference is the public `COLOR_SCHEME` storage contract. Authentication
|
||||
tokens and other secrets remain forbidden storage keys.
|
||||
|
||||
@@ -29,5 +29,10 @@ sequenceDiagram
|
||||
CI->>Browser: boot, route, API, and reload-loop smoke
|
||||
```
|
||||
|
||||
In this repository the workflow stops at promotion. The upload, pointer switch
|
||||
and smoke steps above belong to the project's provider adapter; after it has
|
||||
deployed the promoted release, FE-GATE-019 probes the live headers (review
|
||||
13-05, [`release-cache-rollback.md`](../operations/release-cache-rollback.md)).
|
||||
|
||||
Rollback changes the active pointer only after confirming that the prior
|
||||
immutable release has a coherent HTML/assets/config/API/manifest tuple.
|
||||
|
||||
@@ -52,7 +52,9 @@ TypeScript 전환 목적은 확장자 변경이 아니라 이 계약을 컴파
|
||||
1. ESLint가 product와 negative fixture의 `ts`/`tsx`를 모두 검사한다.
|
||||
2. React Hooks 규칙을 추가하고 TypeScript/ESLint parser와 JSX accessibility
|
||||
도구는 설치된 compiler/linter의 공식 peer 범위 안에서 선택한다.
|
||||
3. dependency-cruiser의 extension과 resolver가 TS/TSX를 포함한다.
|
||||
3. `check:architecture`의 import 그래프가 TS/TSX를 해석한다. 규칙은
|
||||
`.dependency-cruiser.json`에 있지만 dependency-cruiser는 실행하지 않는다.
|
||||
TypeScript 7을 해석하지 못해 0개 모듈을 검사했기 때문이다(리뷰 12-05).
|
||||
4. `scripts/check-registries.ts`가 TS/TSX를 검색한다.
|
||||
5. `config/contracts/registry-governance.json`과 승인 baseline은 `.ts/.tsx`
|
||||
source 경로를 사용한다.
|
||||
@@ -597,6 +599,7 @@ Form 또는 TanStack Form adapter를 평가한다.
|
||||
- `Description`
|
||||
- `FieldError`
|
||||
- `ErrorSummary`
|
||||
- `FormFailureStatus` (재로그인·권한 없음·잠시 후 재시도·그 밖의 저장 불가 실패)
|
||||
- `useAppForm`
|
||||
- `mapValidationFailureToFields`
|
||||
- `useDirtyNavigationGuard`
|
||||
@@ -620,6 +623,7 @@ backend message와 알 수 없는 path는 field copy로 사용하지 않는다.
|
||||
3. submitting 중 중복 제출 방지
|
||||
4. 422 응답의 알려진 field만 표시하고 나머지는 form-level failure로 처리
|
||||
5. 409 conflict는 validation error로 위장하지 않음
|
||||
5a. 401·403·429와 404 같은 입력 외 실패는 ErrorSummary가 아니라 `FormFailureStatus`로 표시(`use-app-form.ts`의 `STATUS_RESULTS`)
|
||||
6. 취소와 route 이탈 시 dirty policy 적용
|
||||
7. form value → application command mapper를 별도 함수로 둠
|
||||
8. browser autofill, IME composition, paste, password manager를 방해하지 않음
|
||||
|
||||
Reference in New Issue
Block a user