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
문제: 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
210 lines
9.1 KiB
TypeScript
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;
|
|
}>;
|