Files
clean-architecture-frontend…/src/bootstrap/product-composition-contract.ts
T
DongHyeonka a5e6719b18
frontend-quality-gates / merge / static checks (pull_request) Successful in 1m17s
frontend-quality-gates / merge / tests (pull_request) Successful in 11m53s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 5m36s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / self-tests and removal drills (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
fix(service-worker): 제품 활성화 칸을 열고 갱신 실패를 관측한다
문제: SW를 켠 제품이 새 버전 안내·reload 안내를 붙이려면 템플릿
파일을 고쳐야 한다(1103/09-05). 설치에 실패한 갱신(redundant)과 실패한
주기 검사는 아무 기록도 남기지 않는다(0925/06-05). build.assetsDir를
바꾸면 사전 캐시가 조용히 빈다(0925/06-08). 릴리스마다 바뀌지 않은
자산까지 no-store로 다시 받는다(1101/06-05). 쓰지 않는 protocol kind
셋과 reload guard 상수, void 참조, 손으로 쓴 protocol 버전 1, web-push의
fence 검사 두 벌이 남았다(1101/06-03, R1~R3).

고른 방법:
- ProductServiceWorkerWiring에 onUpdateWaiting(activate)·
  onReloadRequired()를 더한다(추가만). create-runtime-composition이 worker
  시작 전에 host 이벤트를 구독해 부르고, 던지면 버린다. page controller는
  시작 때 이미 기다리던 갱신도 onUpdateWaiting 구독자에게 알린다.
- page controller가 update_install REDUNDANT, update_check FAILED를
  observe로 낸다.
- 사전 캐시 생성기와 SW 설치가 빈 asset 목록을 거절하고, 시험이
  vite.config.ts의 build.assetsDir와 BUILD_ASSET_DIRECTORY를 대조한다
  (vite.config.ts는 그룹 C가 고치는 파일이라 건드리지 않았다).
- 설치가 이전 릴리스 캐시의 같은 URL을 digest로 다시 확인해 복사하고,
  없거나 맞지 않을 때만 받는다.
- PAGE_HELLO·WORKER_HELLO_ACK·UPDATE_READY, reloadGuard*·
  retainedPreviousCaches를 지운다. sync 알림은 createServiceWorkerMessage로
  만든다. fence 검사는 push-association-fence-store.ts 하나다.
버린 대안: 활성화 화면을 presentation 슬롯으로 열기 — 화면 문구와 흐름은
제품 것이라 조합 계약의 함수 칸이 작다.

위험·한계: 지운 kind는 보내는 곳이 없었다. 다른 빌드의 worker가 보내도
UNKNOWN_KIND로 관측만 된다. 재사용은 이전 캐시를 읽는 비용이 들고,
읽기 실패는 다운로드로 돌아간다.

검증: desktop check:types·lint·check:architecture·
check:adapter-inventory rc=0, SW 시험 묶음 통과
(/tmp/claude-gates/r9b-pr1-quick). merge 단계는 PR 본문.

Refs: 1103/09-05, 0925/06-05, 0925/06-08, 1101/06-03, 1101/06-05, 1101/R1, 1101/R2, 1101/R3
2026-11-13 19:02:07 +09:00

210 lines
9.1 KiB
TypeScript

import type { ExternalSessionOwner } from "../adapters/auth/index.ts";
import type {
ContractHttpExecutorDependencies,
InstalledHttpOperationExecutor,
} from "../adapters/http/index.ts";
import type { ServiceWorkerActivationOutcome } from "../contracts/service-worker.ts";
import type { FeaturePlatformCapabilities } from "../features/feature-adapter-contribution.ts";
import type { RuntimeConfig } from "./runtime-config-schema.ts";
/**
* 09-02. The template's half of the product extension point. A product fills
* `product-composition.ts` (and `src/contracts/product-contracts.ts` for auth
* profiles and runtime-config keys, `src/features/product-capabilities.ts`
* for the types of its capabilities) and never edits `runtime-adapters.ts`.
*/
/**
* 1103/09-03. A fetch with one deadline over the whole exchange (at most
* `REQUEST_TIMEOUT_MS`; `timeoutMs` may shorten it) and the body read into
* memory, at most 64 KiB. Rejects with a `TimeoutError` or `AbortError`
* DOMException, or a `RangeError` for a larger body. Redirects are refused.
*/
export type SessionOwnerFetch = (
input: string | URL,
init?: Omit<RequestInit, "signal" | "redirect"> &
Readonly<{ signal?: AbortSignal; timeoutMs?: number }>,
) => Promise<Response>;
/** The page a sign-in redirect leaves and returns to. Each throws without one. */
export type ProductSessionOwnerPage = Readonly<{
/** The current URL. */
href(): string;
/** Replaces the current entry without loading, e.g. to drop a sign-in callback query. */
replaceUrl(url: string): void;
/** Loads another page: the identity provider's sign-in or sign-out. */
assign(url: string): void;
}>;
/**
* What a product session owner is built from. It is asked first, before
* `http` exists (`http` needs the session), so it gets no capability.
*/
export type ProductSessionOwnerContext = Readonly<{
/** Validated runtime config, product keys included. */
config: RuntimeConfig;
/** Unbounded; prefer `fetch`. */
fetcher?: typeof fetch;
/** 1103/09-03. Use this one: a probe or token call cannot hang the session. */
fetch: SessionOwnerFetch;
/** A cookie of the page (double-submit CSRF), read when called. */
readCookie(name: string): string | undefined;
page: ProductSessionOwnerPage;
/**
* The page's session storage, when there is one: what must survive a
* sign-in redirect and nothing longer. Never a token (`AUTH_TOKEN` is
* `forbidden` in `src/contracts/storage-keys.ts`).
*/
redirectStorage?: Pick<Storage, "getItem" | "setItem" | "removeItem">;
}>;
/**
* The session owner when the product owns the session itself, such as a BFF
* whose session is an httpOnly cookie only the backend can read. Asked only
* when `AUTH_MODE` is `external`; it comes before the host's
* `__CA_FRONTEND_AUTH_OWNER__`, and `null` leaves the session to that global.
*/
export type ProductSessionOwner = ExternalSessionOwner | null;
/** Built by the template; a product cannot return or replace them. */
export type TemplatePlatformCapabilityId = "http" | "telemetry";
/**
* Credentials for one product auth profile, in the same contract as the
* composition root's own `attachCredentials`. The template calls it only after
* the scope fence and the ANONYMOUS check, before the session, and checks the
* fence again after it answers. A throw closes as `CREDENTIAL_OWNER_FAILED`;
* the executor still sends only the headers the profile allows.
*/
export type ProductCredentialProvider =
ContractHttpExecutorDependencies["attachCredentials"];
/**
* 1112/07-01. The template's own credentials for a request the product sends
* itself rather than through `http`, such as a Fileserver upload
* (`FileserverUploadClientDependencies`): spread it into that capability.
*
* - `attachCredentials` decides as the V3 executor's does: the scope fence,
* then the ANONYMOUS profile, then `credentialProviders`, then the template
* session (an `EXTERNAL_BEARER` upload gets the session owner's bearer this
* way), then the fence again.
* - `onUnauthenticated` takes the server's 401 to that request the same way
* a V3 401 goes: to `onCredentialRejected` for a product provider's
* credential, to the template session for its own, to nobody for an
* ANONYMOUS one.
*/
export type ProductRequestCredentials = Readonly<{
attachCredentials: ProductCredentialProvider;
onUnauthenticated(
binding: Readonly<{ operationId: string; authProfileId: string }>,
): void;
}>;
export type ProductCompositionContext = Readonly<{
/** Validated runtime config, product keys included. */
config: RuntimeConfig;
/** A cookie of the page (double-submit CSRF), read when called. */
readCookie(name: string): string | undefined;
fetcher?: typeof fetch;
/** The `http` capability features receive. Call it per request, not while composing. */
http: InstalledHttpOperationExecutor;
/** False while a session change fences server state; send nothing then. */
isScopeReady(): boolean;
/**
* 1105/09-02. Tells the template session that the server rejected the
* session's own credential, as a 401 to a request the session credentialed
* does: the session goes unauthenticated and server state is fenced. For
* `onCredentialRejected` when a provider sends the session's credential (a
* BFF cookie session: `createSessionCookieRejectionHandler` in
* recipes/session-owners/cookie-session-owner.ts). Not for a provider whose
* credential is not the session's, such as another API's token.
*/
notifySessionUnauthenticated(): void;
/**
* 1112/07-01. Call it per request: called while `composeProduct` runs it
* throws a `TypeError`.
*/
credentials: ProductRequestCredentials;
}>;
/**
* 2026-11-03 02-01. Something a product built that must not outlive a session,
* such as a browser file runtime holding the previous user's files. The
* template closes it on every sign-out and account switch, after FENCED and
* before READY, at the step that releases offline leases. A close that throws
* or rejects keeps the scope from reaching READY, as the template's own do.
*/
export type ProductScopeParticipant = Readonly<{
/**
* 1105/02-01. A lowercase kebab-case token such as `browser-files`
* (`isScopeParticipantLabel` in `src/contracts/diagnostics.ts`). A close
* that throws or rejects records `cache.operation.failed` with
* `operation: "SCOPE_RESET"`, `reason: "PARTICIPANT_FAILED"` and this label
* as `scope_participant`, so the stuck scope names its cause. Composition
* throws a `TypeError` on any other label.
*/
label: string;
close(): void | Promise<void>;
}>;
/**
* 1103/09-05. The page side of the Service Worker the product selected in
* `src/features/product-capabilities.ts`. Unused when no worker is selected.
*/
export type ProductServiceWorkerWiring = Readonly<{
/**
* §17.10. Asked each time this tab is about to let a waiting worker take
* over (`requestActivation()`). One that returns true, or throws, refuses
* with `BLOCKED_DIRTY_CLIENT`: say, while a form has unsaved edits.
*/
blockers?: readonly (() => boolean)[];
/**
* The page controller's diagnostics (`register`, `activation`, `message`,
* `client_drain`, ...), each with its outcome. A throw is ignored.
*/
observe?(observation: Readonly<{ event: string; outcome: string }>): void;
/**
* 1103/09-05. An update finished installing and waits for this tab, found
* when the worker starts or later: show the product's "new version" notice
* and call `activate()` when the user agrees. `activate()` is
* `requestActivation()`, so `blockers` still apply. A throw is ignored.
*/
onUpdateWaiting?(
activate: () => Promise<ServiceWorkerActivationOutcome>,
): void;
/**
* 1103/09-05. A worker of another build took over (this tab asked, or
* another one did), so this page runs old code: ask the user to reload, or
* reload. A throw is ignored.
*/
onReloadRequired?(): void;
}>;
export type ProductComposition = Readonly<{
capabilities: Readonly<
Partial<Omit<FeaturePlatformCapabilities, TemplatePlatformCapabilityId>>
>;
/** Auth profile id → provider. An ANONYMOUS profile never reaches one. */
credentialProviders: Readonly<Record<string, ProductCredentialProvider>>;
/**
* 1103/09-01. Optional. Called when the server answers 401 to a request
* whose credential one of `credentialProviders` supplied. The template
* session is not told, because it did not supply that credential. A BFF
* product whose provider sends the session's own cookie tells the session
* here with `context.notifySessionUnauthenticated()` (1105/09-02); without
* it an ended server session leaves the page signed in. A throw is ignored.
*/
onCredentialRejected?(
binding: Readonly<{ operationId: string; authProfileId: string }>,
): void;
/**
* Closed in this order on each identity change. A capability that needs a
* fresh object for the next session hands features a getter and rebuilds
* behind it, as `recipes/frontend-capabilities/browser-file-session-capability.ts`
* does.
*/
scopeParticipants?: readonly ProductScopeParticipant[];
/** 1103/09-05. Optional. Read once, when the runtime is composed. */
serviceWorker?: ProductServiceWorkerWiring;
}>;