Merge lane/F: service worker / web push (06-01~06-10, F-8)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-27 13:03:51 +09:00
co-authored by Claude Opus 5.5
31 changed files with 1424 additions and 158 deletions
@@ -106,6 +106,22 @@ type은 facade 밖으로 노출하지 않는다.
SSOT다. 문서와 catalog가 다르면 gate가 검사하는 catalog를 우선 고치고 이 표도
같이 갱신한다.
Service Worker를 켤 때 확인할 것(06-05). 템플릿은 1·2·6만 갖고 있다.
1. `src/features/installed-runtime-capabilities.ts`의 `SERVICE_WORKER`를
`ACTIVE`로 바꾼다. `scripts/build-frontend.ts`가 worker 빌드를 추가로 돈다.
2. 관측: `createRuntimeComposition`이 텔레메트리 포트를 optional host에 넘긴다.
시작 결과가 `FAILED`나 `INCOMPATIBLE`이면 `service-worker.start.failed`가 1건
남는다(`src/bootstrap/optional-runtime-host.ts`). 업데이트 설치 실패와 page
controller의 `observe`는 아직 어디에도 연결되지 않는다.
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
@@ -1316,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
@@ -1335,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했다”고 주장하지
@@ -1491,7 +1521,10 @@ worker가 종료·재시작된 뒤에도 click을 처리할 수 있도록 이 bo
envelope만 `NotificationOptions.data`에 넣는다. click handler는 codec/size/expiry,
current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch
(만료, fence·release 불일치, fence 읽기 실패, 모르는 route)는 notification을 닫고
요청한 route 대신 **앱 루트(`<origin>/`)를 handoff 데이터 없이 연다**(D-14).
요청한 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`는 루트 창의
@@ -460,8 +460,11 @@ committed object를 sync handle로 in-place repair하지 않는다. 새 generati
## 8. Cache Storage/Service Worker stale or poisoned release
public static Cache release runtime은 존재하지만 cursor/count/deadline이 있는
bounded inspect/cleanup과 Service Worker waiting/client-drain controller는 아직
없다. Service Worker는 제품이 PWA/offline fetch를 별도로 선택한 경우에만 아래
bounded inspect/cleanup은 아직 없다. Service Worker의 waiting/client-drain
활성화는 page controller의 `requestActivation()` 핸드셰이크로 구현돼 있다
(`src/adapters/service-worker/service-worker-page-controller.ts`). 템플릿에는 이를
부르는 화면이 없다. Service Worker는 제품이 static selection
(`src/features/installed-runtime-capabilities.ts`)을 `ACTIVE`로 바꾼 경우에만 아래
worker 절차를 적용한다.
### 신호
@@ -506,12 +509,38 @@ static Cache-only 조합:
invocation을 추가 budget으로 반복 실행하지 않는다. VD-15 bounded cursor
runtime 구현 전에는 큰 namespace를 자동 sweep하지 않는다.
Service Worker를 별도 선택한 조합에서만 추가:
Service Worker를 별도 선택한 조합에서만 추가. 워커의 fetch 가로채기만 끄는
스위치는 없다. 끄는 경로는 아래 둘이다.
- fetch interception을 network-only kill switch로 전환
- new worker activation 중지
- 필요하면 unregister + 다음 navigation cleanup migration
- old controlled client가 drain되기 전 해당 release cleanup 금지
- 페이지가 부팅하면: runtime config에 `CAPABILITY_OVERRIDES.SERVICE_WORKER:
"DISABLED"`를 넣는다. 재빌드는 필요 없다. 다음 부팅 때 page controller가 scope와
script가 정확히 일치하는 등록만 unregister하고, 새 등록은 하지 않는다
(`src/contracts/runtime-capabilities.ts` `resolveRuntimeCapabilities`,
`service-worker-page-controller.ts` `start()`의 `disabledCleanup` 분기). 소유
캐시는 지우지 않는다. unregister는 이미 열린 탭의 제어를 끊지 않으므로, 그 탭은
닫히거나 다시 load될 때까지 현재 워커를 쓴다.
- 워커 때문에 페이지가 부팅하지 못하면: static selection을
`{ mode: "REMOVE_REGISTRATION", scriptPath: "service-worker.js" }`로 바꾼
release를 배포한다. 이 release는 같은 URL에 자기 해제 `service-worker.js`를 낸다
(`scripts/build-frontend.ts`, `scripts/lib/self-unregistering-service-worker.ts`).
페이지 코드가 돌지 않아도 브라우저 update 검사(내비게이션 때, 등록은
`updateViaCache: "none"`)가 이 파일을 받아 설치한다. 설치 즉시
`skipWaiting()`하고, 활성화 때 `registration.unregister()`한다. fetch handler가
없어서 그동안의 요청은 모두 네트워크로 간다. 다음 load부터는 제어받지 않는다.
브라우저 확인: `tests/e2e/service-worker-recovery.spec.ts`.
- 이 경로가 동작하려면 `service-worker.js`를 `Cache-Control: no-cache`로 서빙해야
한다. `verify:hosting-headers`는 파일이 있는지만 보고 이 헤더는 보지 않는다
(`scripts/lib/hosting-probe.ts` `checkPublicServiceWorkers`).
- 새 워커는 install에서 `skipWaiting()`하지 않는다(`service-worker-entry.ts`).
활성화는 페이지의 `requestActivation()`으로만 일어나므로, 새 worker 활성화를
멈추려고 따로 할 일은 없다.
- 제거는 `ACTIVE → REMOVE_REGISTRATION → PURGE_OWNED_RESOURCES → null` 순서로
release를 나눈다(`src/contracts/service-worker.ts`
`InstalledServiceWorkerSelection`). 소유 캐시는 `PURGE_OWNED_RESOURCES` release의
page controller가 지운다(`service-worker-removal.ts` `purgeOwnedResources`).
old controlled client가 drain되기 전에는 이 release를 배포하지 않는다. 캐시가
사라지면 그 탭의 워커는 요청을 네트워크로 넘기고(`service-worker-entry.ts`
fetch 리스너의 `cached ?? fetch(request)`), 서버에 없는 옛 청크는 404가 된다.
hosting/CDN purge는 두 branch와 분리된 provider 절차로 실행한다.
+36 -2
View File
@@ -45,8 +45,10 @@ The provider-independent cache defaults are:
- runtime config and release manifest: `no-store`
- public source maps: disabled
- service worker/offline cache: disabled, unless the static selection in
`src/features/installed-runtime-capabilities.ts` is `ACTIVE`; then `dist`
holds exactly the selected `service-worker.js`
`src/features/installed-runtime-capabilities.ts` is `ACTIVE` or
`REMOVE_REGISTRATION`; then `dist` holds exactly the selected
`service-worker.js`, served `no-cache` so the browser's update check sees
each release's worker
HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared
to the declared allowlist; a cache-correct response with a mismatched
@@ -73,3 +75,35 @@ request them. The minimum is the previous release while the next one is
active (the rolling window modeled in `tests/release/release-fixture.ts`).
Size it to the longest session the product supports; a tab older than that
depends on the reload-once recovery (FE-RB-002).
## Service Worker steps (only when the static selection is not `null`)
The worker is part of the release tuple: `service-worker.js` comes from the
same build as the HTML and assets it caches.
1. **Rollback N+1 → N.** Switching the tuple serves N's `service-worker.js`.
The browser's update check installs it; the worker never calls
`skipWaiting()` on install (`src/adapters/service-worker/service-worker-entry.ts`),
so it waits until every tab of the scope closes or a page calls
`requestActivation()`. The template has no page that calls it. The cache
name is the asset-set digest, so if N's cache is still there as the
retained previous cache, the install reuses it and never deletes it on
failure (`service-worker-static-assets.ts` `installStaticAssets`). Tabs still on N+1 keep worker N+1, so N+1's assets
stay reachable for the rolling window above.
2. **Turn the worker off without a rebuild.** Set
`CAPABILITY_OVERRIDES.SERVICE_WORKER: "DISABLED"` in the runtime config. The
next boot unregisters the owned registration and registers nothing; owned
caches stay (`src/contracts/runtime-capabilities.ts`
`resolveRuntimeCapabilities`, `service-worker-page-controller.ts` `start()`).
This needs a page that boots.
3. **A worker stops the page from booting.** Deploy a release whose static
selection is `REMOVE_REGISTRATION`. It ships a self-unregistering
`service-worker.js` (`scripts/build-frontend.ts`,
`scripts/lib/self-unregistering-service-worker.ts`): the update check
installs it over the broken worker, it skips waiting, unregisters on
activation and answers no fetch. The next load is uncontrolled
(`tests/e2e/service-worker-recovery.spec.ts`). Runbook:
`docs/operations/browser-file-storage-recovery.md` §8.
4. **Removing the worker** takes three releases:
`REMOVE_REGISTRATION` → `PURGE_OWNED_RESOURCES` (deletes owned caches) →
`null` (`src/contracts/service-worker.ts` `InstalledServiceWorkerSelection`).