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:
co-authored by
Claude Opus 5.5
parent
9f2305a562
commit
cd47516592
@@ -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
|
||||
|
||||
@@ -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",
|
||||
};
|
||||
|
||||
@@ -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<
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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();
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user