diff --git a/docs/architecture/optional-adapter-recipes.md b/docs/architecture/optional-adapter-recipes.md index 4707fa4f..434db1d3 100644 --- a/docs/architecture/optional-adapter-recipes.md +++ b/docs/architecture/optional-adapter-recipes.md @@ -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 diff --git a/scripts/check-diagnostics.ts b/scripts/check-diagnostics.ts index 62a1ac29..8c535246 100644 --- a/scripts/check-diagnostics.ts +++ b/scripts/check-diagnostics.ts @@ -33,6 +33,7 @@ const telemetryProducerFiles: Readonly> = { "api.request.failed": "src/adapters/http/client.ts", "ui.render.failed": "src/application/create-application.ts", "release.mismatch.detected": "src/application/create-application.ts", + "service-worker.start.failed": "src/bootstrap/optional-runtime-host.ts", "telemetry.delivery.dropped": "src/adapters/telemetry/best-effort-telemetry.ts", }; diff --git a/src/bootstrap/create-runtime-composition.ts b/src/bootstrap/create-runtime-composition.ts index 8d1b712a..9240c6b3 100644 --- a/src/bootstrap/create-runtime-composition.ts +++ b/src/bootstrap/create-runtime-composition.ts @@ -1,5 +1,6 @@ import { resolveRuntimeCapabilities } from "../contracts/runtime-capabilities.ts"; import { INSTALLED_RUNTIME_CAPABILITIES } from "../features/installed-runtime-capabilities.ts"; +import type { TelemetryPort } from "../application/ports/telemetry-port.ts"; import { createCompositionRoot } from "./composition-root.ts"; import { loadReleaseManifest } from "./load-release-manifest.ts"; import { loadRuntimeConfig } from "./load-runtime-config.ts"; @@ -23,17 +24,23 @@ export type RuntimeCompositionDependencies = Readonly<{ export async function createRuntimeComposition( dependencies: RuntimeCompositionDependencies = {}, ) { + // 06-05. The optional host reports a Service Worker that did not start + // through the same telemetry port as the application. + let telemetry: TelemetryPort | undefined; const root = await createCompositionRoot({ loadConfig: () => loadRuntimeConfig({ fetcher: dependencies.fetcher }), loadRelease: (runtime) => loadReleaseManifest(runtime, { fetcher: dependencies.fetcher }), - createAdapters: ({ config: runtime, release }) => - createRuntimeAdapters({ + createAdapters: async ({ config: runtime, release }) => { + const adapters = await createRuntimeAdapters({ runtime, release, fetcher: dependencies.fetcher, host: dependencies.host, - }), + }); + telemetry = adapters.outputPorts.telemetry; + return adapters; + }, }); const capabilities = resolveRuntimeCapabilities( @@ -44,6 +51,7 @@ export async function createRuntimeComposition( capabilities, routerBasePath: root.config.build.routerBasePath, buildId: root.release.buildId, + ...(telemetry ? { telemetry } : {}), ...(dependencies.host ? { host: dependencies.host as Parameters< diff --git a/src/bootstrap/optional-runtime-host.ts b/src/bootstrap/optional-runtime-host.ts index 2ace8938..916ac188 100644 --- a/src/bootstrap/optional-runtime-host.ts +++ b/src/bootstrap/optional-runtime-host.ts @@ -8,6 +8,7 @@ import type { RuntimeStopReason, } from "../contracts/runtime-capabilities.ts"; import type { ServiceWorkerRuntimeHost } from "../contracts/service-worker.ts"; +import type { TelemetryPort } from "../application/ports/telemetry-port.ts"; import { createServiceWorkerRuntimeHost } from "./register-service-worker.ts"; /** @@ -39,6 +40,8 @@ export type OptionalRuntimeHostInput = Readonly<{ host?: Parameters[0]["host"]; blockers?: readonly (() => boolean)[]; observe?: (observation: Readonly<{ event: string; outcome: string }>) => void; + /** 06-05. Receives `service-worker.start.failed`. */ + telemetry?: TelemetryPort; }>; export function createOptionalRuntimeHost( @@ -107,6 +110,13 @@ export function createOptionalRuntimeHost( : outcome.kind === "INCOMPATIBLE" ? "INCOMPATIBLE" : "DEGRADED"; + if (outcome.kind === "FAILED" || outcome.kind === "INCOMPATIBLE") { + input.telemetry?.emit("service-worker.start.failed", { + error_kind: + outcome.kind === "FAILED" ? outcome.code : outcome.kind, + build_id: input.buildId, + }); + } } } if (!stopRequested) started = true; diff --git a/src/contracts/telemetry.ts b/src/contracts/telemetry.ts index ad8c90fc..6b2cfdcb 100644 --- a/src/contracts/telemetry.ts +++ b/src/contracts/telemetry.ts @@ -85,6 +85,13 @@ export const TELEMETRY_REGISTRY = Object.freeze({ "release tuple mismatch", ["build_id", "active_release_id", "mismatch_kind"], ), + // 06-05. An ACTIVE worker that did not start (install failure, ownership + // mismatch) is otherwise visible nowhere. + "service-worker.start.failed": event( + "service-worker.start.failed", + "Service Worker start ended FAILED or INCOMPATIBLE", + ["error_kind", "build_id"], + ), "telemetry.delivery.dropped": event( "telemetry.delivery.dropped", "queue or sink failure", diff --git a/tests/unit/optional-runtime-host.test.ts b/tests/unit/optional-runtime-host.test.ts index b6d5f4b2..7087c022 100644 --- a/tests/unit/optional-runtime-host.test.ts +++ b/tests/unit/optional-runtime-host.test.ts @@ -87,4 +87,62 @@ describe("optional runtime host", () => { expect(runtime.health().serviceWorker).toBe("DISABLED"); expect(runtime.browserLifecycle()).toBeNull(); }); + + // 06-05. An ACTIVE selection whose worker install fails must be visible to + // operators, not only in `health()`, which nothing reads. + it.each([ + { + outcome: { kind: "FAILED", code: "INSTALL_FAILED" } as const, + events: [ + [ + "service-worker.start.failed", + { error_kind: "INSTALL_FAILED", build_id: "build-1" }, + ], + ], + }, + { + outcome: { kind: "INCOMPATIBLE" } as const, + events: [ + [ + "service-worker.start.failed", + { error_kind: "INCOMPATIBLE", build_id: "build-1" }, + ], + ], + }, + { outcome: { kind: "ACTIVE", buildId: "build-1" } as const, events: [] }, + { outcome: { kind: "RELOAD_TO_ENABLE" } as const, events: [] }, + ])( + "records $outcome.kind as $events.length telemetry event(s)", + async ({ outcome, events }) => { + const emit = vi.fn(); + const runtime = createOptionalRuntimeHost({ + capabilities: { + ...capabilities, + serviceWorker: { + mode: "ACTIVE", + scriptPath: "service-worker.js", + handlers: ["PWA_STATIC_ASSETS"], + }, + }, + routerBasePath: "/", + buildId: "build-1", + serviceWorkerHost: { + start: vi.fn(async (): Promise => outcome), + requestActivation: vi.fn(), + resetOwnedCaches: vi.fn(), + stop: vi.fn(async () => {}), + }, + browserLifecycleHost: { + addEventListener: vi.fn(), + removeEventListener: vi.fn(), + }, + telemetry: { emit }, + }); + + await runtime.startAfterMount(); + + expect(emit.mock.calls).toEqual(events); + await runtime.stop(); + }, + ); });