fix(bootstrap): report a Service Worker that did not start through telemetry (06-05)

An ACTIVE worker whose install failed left a trace only in health(), which
nothing reads. The optional host now emits service-worker.start.failed on the
application telemetry port, and the recipe doc lists what else to wire.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-26 00:26:54 +09:00
co-authored by Claude Opus 5.5
parent 9f2305a562
commit cd47516592
6 changed files with 103 additions and 3 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
+1
View File
@@ -33,6 +33,7 @@ const telemetryProducerFiles: Readonly<Record<string, string>> = {
"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",
};
+11 -3
View File
@@ -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<
+10
View File
@@ -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<typeof createServiceWorkerRuntimeHost>[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;
+7
View File
@@ -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",
+58
View File
@@ -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<ServiceWorkerStartOutcome> => 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();
},
);
});