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:
@@ -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 절차로 실행한다.
|
||||
|
||||
|
||||
@@ -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`).
|
||||
|
||||
Reference in New Issue
Block a user