Files
DongHyeonka b26517e6f2 fix(docs): 설계 주석에 문서 이름을 붙이고 지운 뒤 끊기는 링크를 없앤다 (1101/14-01)
문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N"
처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4).
가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에
있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지
못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다:
docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로,
docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와
docs/superpowers/plans의 계획으로.

고른 방법:
- 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞
  커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절
  번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다.
- tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 +
  "§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에
  .dependency-cruiser.json을 넣는다.
- README "Files you can delete after copying"에서 INVENTORY.md 한 파일
  대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과
  ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다.
  INVENTORY의 행 구조는 바꾸지 않는다.
- 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은
  링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다.
버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도
상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기
목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시
다른 이력을 가리키면 남길 목록이 계속 커진다.

위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는
주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다.
src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼
이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미
docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의
이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다.
check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던
실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가
바뀐다.

검증:
- RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed).
- GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를
  src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림.
- 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0).
- 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크
  148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계
  참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서
  verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트
  2 passed.
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- node scripts/check-adapter-inventory.ts: PASS
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
  tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts:
  50 passed. tests/architecture: 39 passed.
- npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과.
  .dependency-cruiser.json JSON 파싱 통과.
- 미실행: check:architecture(pnpm 필요).
2026-11-03 07:17:49 +09:00

807 lines
27 KiB
TypeScript

import { describe, expect, it, vi } from "vitest";
import { createDiagnosticsAdapter } from "../../src/adapters/diagnostics/bounded-diagnostics.ts";
import {
createTelemetryAdapter,
safeTraceparent,
} from "../../src/adapters/telemetry/best-effort-telemetry.ts";
import {
createFeatureTelemetry,
createFetchTelemetryTransport,
} from "../../src/adapters/telemetry/feature-telemetry.ts";
import { createTelemetryCollector } from "../../src/adapters/telemetry/telemetry-collector.ts";
import {
TELEMETRY_REGISTRY,
projectTelemetryEvent,
} from "../../src/contracts/telemetry.ts";
const validAttributes = {
error_kind: "SERVER_FAILURE",
http_status_group: "5xx",
attempt_count_bucket: "3",
route_id: "TEST_ROUTE",
};
describe("telemetry registry and redaction", () => {
it("defines all event contract fields", () => {
for (const definition of Object.values(TELEMETRY_REGISTRY)) {
expect(definition).toEqual(
expect.objectContaining({
eventName: expect.any(String),
trigger: expect.any(String),
requiredAttributes: expect.any(Array),
optionalAttributes: expect.any(Array),
forbiddenAttributes: expect.any(Array),
sampling: expect.any(String),
delivery: "best-effort",
}),
);
}
});
it("redacts forbidden attributes and rejects unknown context", () => {
const projected = projectTelemetryEvent("api.request.failed", {
...validAttributes,
raw_url: "https://api.test/path?token=secret",
});
expect(projected.success).toBe(true);
expect(JSON.stringify(projected)).not.toMatch(/raw_url|token|secret/);
expect(
projectTelemetryEvent("api.request.failed", {
...validAttributes,
unregistered: "private",
}),
).toEqual({ success: false, reason: "unknown-attributes" });
expect(
projectTelemetryEvent("api.request.failed", {
...validAttributes,
route_id: "/users/actual-user-id",
}),
).toEqual({ success: false, reason: "invalid-attribute-value" });
});
it("validates traceparent without exposing invalid values", () => {
expect(
safeTraceparent(
"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
),
).toBe("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");
expect(safeTraceparent("Bearer secret")).toBeNull();
});
});
describe("best-effort telemetry adapter", () => {
it("bounds the queue using oldest-drop without blocking callers", () => {
const scheduled: Array<() => void> = [];
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
maxQueue: 2,
schedule: (callback: () => void) => scheduled.push(callback),
fetcher: vi.fn(),
});
adapter.emit("api.request.failed", validAttributes);
adapter.emit("api.request.failed", validAttributes);
adapter.emit("api.request.failed", validAttributes);
expect(adapter.pendingCount()).toBe(2);
expect(adapter.droppedCount()).toBe(1);
expect(adapter.dropReasons()).toEqual({ "queue-full": 1 });
expect(adapter.deliveryEvidence()).toMatchObject({
eventName: "telemetry.delivery.dropped",
attributes: { reason: "queue-full", queue_size_bucket: "1-10" },
});
expect(scheduled).toHaveLength(1);
});
it("degrades on sink failure without throwing or recursive events", async () => {
const onDrop = vi.fn(() => {
throw new Error("observer unavailable");
});
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: () => {},
fetcher: async () => {
throw new Error("sink unavailable");
},
onDrop,
});
expect(() => adapter.emit("api.request.failed", validAttributes)).not.toThrow();
await expect(adapter.flush()).resolves.toBeUndefined();
expect(adapter.droppedCount()).toBe(1);
expect(adapter.dropReasons()).toEqual({ "sink-failure": 1 });
expect(onDrop).toHaveBeenCalledOnce();
expect(adapter.pendingCount()).toBe(0);
});
it("reschedules events whose flush callback runs during an active delivery", async () => {
const scheduled: Array<() => void> = [];
const deliveredRouteIds: unknown[][] = [];
let releaseFirstDelivery: () => void = () => {};
const firstDelivery = new Promise<void>((resolve) => {
releaseFirstDelivery = resolve;
});
let deliveryCount = 0;
const fetcher = vi.fn(async (_endpoint: RequestInfo | URL, init?: RequestInit) => {
deliveryCount += 1;
const body = JSON.parse(String(init?.body));
deliveredRouteIds.push(
(body.events as Array<{ attributes: { route_id: unknown } }>).map(
(event) => event.attributes.route_id,
),
);
if (deliveryCount === 1) {
await firstDelivery;
}
return new Response(null, { status: 204 });
});
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: (callback: () => void) => scheduled.push(callback),
fetcher,
});
const runScheduled = () => {
const callback = scheduled.shift();
if (!callback) throw new Error("Expected a scheduled telemetry flush");
callback();
};
adapter.emit("api.request.failed", {
...validAttributes,
route_id: "FIRST_ROUTE",
});
runScheduled();
await vi.waitFor(() => expect(fetcher).toHaveBeenCalledOnce());
adapter.emit("api.request.failed", {
...validAttributes,
route_id: "SECOND_ROUTE",
});
runScheduled();
expect(fetcher).toHaveBeenCalledOnce();
expect(adapter.pendingCount()).toBe(1);
releaseFirstDelivery();
await vi.waitFor(() => expect(scheduled).toHaveLength(1));
runScheduled();
await vi.waitFor(() => expect(fetcher).toHaveBeenCalledTimes(2));
expect(adapter.pendingCount()).toBe(0);
expect(deliveredRouteIds).toEqual([["FIRST_ROUTE"], ["SECOND_ROUTE"]]);
});
it("never serializes circular or unbounded event context", () => {
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: () => {},
});
const circular: Record<string, unknown> = {};
circular.self = circular;
const hostile = new Proxy(
{},
{
ownKeys() {
throw new Error("private proxy value");
},
},
);
expect(() =>
adapter.emit("api.request.failed", {
...validAttributes,
unregistered: circular,
}),
).not.toThrow();
expect(adapter.pendingCount()).toBe(0);
expect(adapter.dropReasons()).toEqual({ "invalid-context": 1 });
expect(() =>
adapter.emit("api.request.failed", hostile),
).not.toThrow();
expect(adapter.dropReasons()).toEqual({
"invalid-context": 1,
"serialization-failure": 1,
});
});
it("performs no network or queue work when disabled", async () => {
const fetcher = vi.fn();
const adapter = createTelemetryAdapter({
enabled: false,
endpoint: "https://telemetry.test/events",
fetcher,
});
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
expect(fetcher).not.toHaveBeenCalled();
expect(adapter.pendingCount()).toBe(0);
});
it("flushes on page exit and removes the lifecycle listener", async () => {
const lifecycle = new EventTarget();
const remove = vi.spyOn(lifecycle, "removeEventListener");
const fetcher = vi.fn(async () => new Response(null, { status: 204 }));
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: () => {},
lifecycle,
fetcher,
});
adapter.emit("api.request.failed", validAttributes);
lifecycle.dispatchEvent(new Event("pagehide"));
await vi.waitFor(() => expect(fetcher).toHaveBeenCalledOnce());
adapter.dispose();
expect(adapter.pendingCount()).toBe(0);
expect(remove).toHaveBeenCalledWith("pagehide", expect.any(Function));
});
it("drops queued events and invalidates scheduled callbacks on dispose", async () => {
const callbacks: Array<() => void> = [];
const fetcher = vi.fn(async () => new Response(null, { status: 204 }));
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: (callback) => callbacks.push(callback),
fetcher,
});
adapter.emit("api.request.failed", validAttributes);
expect(adapter.pendingCount()).toBe(1);
adapter.dispose();
expect(adapter.pendingCount()).toBe(0);
for (const callback of callbacks) callback();
await Promise.resolve();
expect(fetcher).not.toHaveBeenCalled();
// Disposal is a silent shutdown, not a recursive drop event.
expect(adapter.dropReasons()).toEqual({});
});
it("ignores emit after dispose", async () => {
const fetcher = vi.fn(async () => new Response(null, { status: 204 }));
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: () => {},
fetcher,
});
adapter.dispose();
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
expect(adapter.pendingCount()).toBe(0);
expect(fetcher).not.toHaveBeenCalled();
});
it("aborts an in-flight sink and prevents post-dispose rescheduling", async () => {
const callbacks: Array<() => void> = [];
let observedSignal: AbortSignal | undefined;
let releaseSink: (() => void) | undefined;
const fetcher = vi.fn(async (_input: unknown, init?: RequestInit) => {
observedSignal = init?.signal ?? undefined;
await new Promise<void>((resolve) => {
releaseSink = resolve;
});
return new Response(null, { status: 204 });
});
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: (callback) => callbacks.push(callback),
fetcher: fetcher as unknown as typeof fetch,
});
adapter.emit("api.request.failed", validAttributes);
callbacks.splice(0).forEach((callback) => callback());
await vi.waitFor(() => expect(fetcher).toHaveBeenCalledOnce());
adapter.dispose();
expect(observedSignal?.aborted).toBe(true);
// The sink ignored the abort and settles late.
releaseSink?.();
await Promise.resolve();
await Promise.resolve();
expect(callbacks).toHaveLength(0);
expect(fetcher).toHaveBeenCalledOnce();
});
it("joins an already active flush", async () => {
let releaseSink: (() => void) | undefined;
const fetcher = vi.fn(async () => {
await new Promise<void>((resolve) => {
releaseSink = resolve;
});
return new Response(null, { status: 204 });
});
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: () => {},
fetcher: fetcher as unknown as typeof fetch,
});
adapter.emit("api.request.failed", validAttributes);
const first = adapter.flush();
await vi.waitFor(() => expect(fetcher).toHaveBeenCalledOnce());
let secondSettled = false;
const second = adapter.flush().then(() => {
secondSettled = true;
});
await Promise.resolve();
expect(secondSettled).toBe(false);
releaseSink?.();
await first;
await second;
expect(secondSettled).toBe(true);
adapter.dispose();
});
it.each([Number.NaN, Number.POSITIVE_INFINITY, 0, -1, 1.5])(
"rejects invalid telemetry and diagnostics capacity %s",
(value) => {
expect(() =>
createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
maxQueue: value,
}),
).toThrow(TypeError);
expect(() => createDiagnosticsAdapter({ maxEntries: value })).toThrow(
TypeError,
);
},
);
});
describe("telemetry collector payloads (Q-6.9-4)", () => {
function recordingFetcher() {
const calls: Array<Readonly<{ url: string; init: RequestInit }>> = [];
const fetcher = vi.fn(async (url: RequestInfo | URL, init?: RequestInit) => {
calls.push({ url: String(url), init: init ?? {} });
return new Response(null, { status: 204 });
});
return { calls, fetcher: fetcher as unknown as typeof fetch };
}
it("posts the contract projection for the application port", async () => {
const { calls, fetcher } = recordingFetcher();
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: () => {},
now: () => Date.parse("2026-09-24T00:00:00.000Z"),
fetcher,
});
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
expect(calls).toHaveLength(1);
expect(calls[0]?.url).toBe("https://telemetry.test/events");
expect(calls[0]?.init).toMatchObject({
method: "POST",
headers: { "Content-Type": "application/json" },
keepalive: true,
});
expect(JSON.parse(String(calls[0]?.init.body))).toEqual({
events: [
{
eventName: "api.request.failed",
timestamp: "2026-09-24T00:00:00.000Z",
attributes: validAttributes,
},
],
});
adapter.dispose();
});
it("posts the pipeline projection for the feature port", async () => {
const { calls, fetcher } = recordingFetcher();
const transport = createFetchTelemetryTransport({
endpoint: "https://telemetry.test/events",
fetcher,
});
await transport.send([
{
event: { kind: "catalog.load.failed", severity: "error", featureId: "catalog" },
fingerprint: "fp-1",
occurrences: 3,
},
]);
expect(calls).toHaveLength(1);
expect(calls[0]?.url).toBe("https://telemetry.test/events");
expect(calls[0]?.init).toMatchObject({
method: "POST",
headers: { "Content-Type": "application/json" },
keepalive: true,
credentials: "omit",
cache: "no-store",
});
expect(JSON.parse(String(calls[0]?.init.body))).toEqual({
events: [
{
kind: "catalog.load.failed",
severity: "error",
featureId: "catalog",
fingerprint: "fp-1",
occurrences: 3,
},
],
});
});
it("rejects a feature batch the collector refuses", async () => {
const transport = createFetchTelemetryTransport({
endpoint: "https://telemetry.test/events",
fetcher: (async () => new Response(null, { status: 503 })) as typeof fetch,
});
await expect(transport.send([])).rejects.toThrow();
});
});
describe("one collector transport for both telemetry ports (Q-6.9-4)", () => {
const featureEvent = {
kind: "catalog.load.failed",
severity: "error",
featureId: "catalog",
} as const;
const hungFetcher = () => {
const signals: AbortSignal[] = [];
// Never settles and ignores its signal: only the collector can end it.
const fetcher = vi.fn((_url: RequestInfo | URL, init?: RequestInit) => {
if (init?.signal) signals.push(init.signal);
return new Promise<Response>(() => {});
});
return { signals, fetcher: fetcher as unknown as typeof fetch, calls: fetcher };
};
it("sends application telemetry without cookies or HTTP cache", async () => {
const fetcher = vi.fn(async () => new Response(null, { status: 204 }));
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: () => {},
fetcher: fetcher as unknown as typeof fetch,
});
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
expect(fetcher).toHaveBeenCalledWith(
"https://telemetry.test/events",
expect.objectContaining({ credentials: "omit", cache: "no-store" }),
);
adapter.dispose();
});
it("times out a hung collector so later application flushes still send", async () => {
const { fetcher, calls } = hungFetcher();
const collector = createTelemetryCollector({
endpoint: "https://telemetry.test/events",
fetcher,
timeoutMs: 5,
});
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: () => {},
collector,
});
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
expect(adapter.dropReasons()).toEqual({ "sink-failure": 1 });
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
expect(calls).toHaveBeenCalledTimes(2);
adapter.dispose();
});
it("times out a hung collector for feature telemetry", async () => {
const { fetcher } = hungFetcher();
const telemetry = createFeatureTelemetry({
enabled: true,
endpoint: "https://telemetry.test/events",
collector: createTelemetryCollector({
endpoint: "https://telemetry.test/events",
fetcher,
timeoutMs: 5,
}),
});
await telemetry.emit(featureEvent);
await telemetry.flush();
expect(telemetry.stats()).toMatchObject({ sends: 1, failedSends: 1 });
telemetry.dispose();
});
it("shares one send-rate window between the two ports", async () => {
const fetcher = vi.fn(async () => new Response(null, { status: 204 }));
const collector = createTelemetryCollector({
endpoint: "https://telemetry.test/events",
fetcher: fetcher as unknown as typeof fetch,
maxSendsPerMinute: 1,
});
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: () => {},
setTimer: () => 0,
clearTimer: () => {},
collector,
});
const telemetry = createFeatureTelemetry({
enabled: true,
endpoint: "https://telemetry.test/events",
collector,
});
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
await telemetry.emit(featureEvent);
await telemetry.flush();
expect(fetcher).toHaveBeenCalledOnce();
expect(telemetry.stats().buffered).toBe(1);
adapter.dispose();
telemetry.dispose();
});
it("flushes feature telemetry on page exit and stops listening on dispose", async () => {
const lifecycle = new EventTarget();
const remove = vi.spyOn(lifecycle, "removeEventListener");
const fetcher = vi.fn(async () => new Response(null, { status: 204 }));
const telemetry = createFeatureTelemetry({
enabled: true,
endpoint: "https://telemetry.test/events",
collector: createTelemetryCollector({
endpoint: "https://telemetry.test/events",
fetcher: fetcher as unknown as typeof fetch,
lifecycle,
}),
});
await telemetry.emit(featureEvent);
await vi.waitFor(() => expect(fetcher).toHaveBeenCalledOnce());
// A duplicate is held until the next flush; page exit is that flush.
await telemetry.emit(featureEvent);
expect(fetcher).toHaveBeenCalledOnce();
lifecycle.dispatchEvent(new Event("pagehide"));
await vi.waitFor(() => expect(fetcher).toHaveBeenCalledTimes(2));
telemetry.dispose();
expect(remove).toHaveBeenCalledWith("pagehide", expect.any(Function));
});
it("aborts an in-flight feature batch on dispose", async () => {
const { fetcher, signals } = hungFetcher();
const telemetry = createFeatureTelemetry({
enabled: true,
endpoint: "https://telemetry.test/events",
fetcher,
});
await telemetry.emit(featureEvent);
await vi.waitFor(() => expect(signals).toHaveLength(1));
telemetry.dispose();
expect(signals[0]?.aborted).toBe(true);
});
});
/**
* 13-11. Failures must be attributable to a release while old and new tabs
* coexist, so every event the collector sends carries both identities.
*/
describe("collector release identity (13-11)", () => {
it("stamps build_id and release_id on every event of both ports", async () => {
const bodies: { events: Record<string, unknown>[] }[] = [];
const fetcher = vi.fn(async (_url: RequestInfo | URL, init?: RequestInit) => {
bodies.push(JSON.parse(String(init?.body)));
return new Response(null, { status: 204 });
});
const collector = createTelemetryCollector({
endpoint: "https://telemetry.test/events",
fetcher: fetcher as unknown as typeof fetch,
release: { buildId: "build-a", releaseId: "release-a" },
});
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: () => {},
collector,
});
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
await createFetchTelemetryTransport({
endpoint: "https://telemetry.test/events",
collector,
}).send([
{
event: { kind: "catalog.load.failed", severity: "error", featureId: "catalog" },
fingerprint: "fp-1",
occurrences: 1,
},
]);
// A split batch keeps the identity on every part.
await collector.post(
Array.from({ length: 70 }, (_, index) => ({ index, padding: "x".repeat(1_000) })),
);
const events = bodies.flatMap((body) => body.events);
expect(bodies.length).toBeGreaterThan(3);
expect(events).toHaveLength(72);
for (const sent of events) {
expect(sent).toMatchObject({ build_id: "build-a", release_id: "release-a" });
}
adapter.dispose();
});
});
/**
* 03-05. Fetch fails every keepalive request once the in-flight keepalive
* bodies exceed 64KiB, so a large queue must be split and the collector must
* never have more than that in flight with keepalive.
*/
describe("collector keepalive budget (03-05)", () => {
const KEEPALIVE_QUOTA = 64 * 1024;
const utf8 = new TextEncoder();
function recordingFetcher() {
const sent: { bytes: number; keepalive: boolean; events: number }[] = [];
let inflightKeepalive = 0;
let peakKeepalive = 0;
const releases: Array<() => void> = [];
const fetcher = vi.fn((_url: RequestInfo | URL, init?: RequestInit) => {
const body = String(init?.body);
const bytes = utf8.encode(body).byteLength;
const keepalive = init?.keepalive === true;
sent.push({
bytes,
keepalive,
events: (JSON.parse(body) as { events: unknown[] }).events.length,
});
if (keepalive) inflightKeepalive += bytes;
peakKeepalive = Math.max(peakKeepalive, inflightKeepalive);
return new Promise<Response>((resolve) => {
releases.push(() => {
if (keepalive) inflightKeepalive -= bytes;
resolve(new Response(null, { status: 204 }));
});
});
});
return {
sent,
peak: () => peakKeepalive,
releaseAll: () => releases.splice(0).forEach((release) => release()),
fetcher: fetcher as unknown as typeof fetch,
};
}
const bigEvents = (count: number) =>
Array.from({ length: count }, (_, index) => ({
index,
padding: "x".repeat(1_000),
}));
it("splits a queue over the keepalive limit into posts that all arrive", async () => {
const recording = recordingFetcher();
const collector = createTelemetryCollector({
endpoint: "https://telemetry.test/events",
fetcher: recording.fetcher,
});
const delivered = collector.post(bigEvents(70));
await vi.waitFor(() => expect(recording.sent.length).toBeGreaterThan(1));
recording.releaseAll();
await delivered;
expect(recording.sent.every((post) => post.bytes <= KEEPALIVE_QUOTA)).toBe(
true,
);
expect(recording.sent.reduce((sum, post) => sum + post.events, 0)).toBe(70);
expect(recording.peak()).toBeLessThanOrEqual(KEEPALIVE_QUOTA);
});
it("keeps concurrent posts under one keepalive quota", async () => {
const recording = recordingFetcher();
const collector = createTelemetryCollector({
endpoint: "https://telemetry.test/events",
fetcher: recording.fetcher,
});
// Two queues flushing together, as on pagehide.
const first = collector.post(bigEvents(40));
const second = collector.post(bigEvents(40));
await vi.waitFor(() => expect(recording.sent.length).toBeGreaterThan(1));
recording.releaseAll();
await Promise.all([first, second]);
expect(recording.peak()).toBeLessThanOrEqual(KEEPALIVE_QUOTA);
expect(recording.sent.some((post) => post.keepalive)).toBe(true);
expect(recording.sent.reduce((sum, post) => sum + post.events, 0)).toBe(80);
});
});
describe("telemetry adapter send-rate limit (scale-architecture.md §27)", () => {
function harness(maxSendsPerMinute = 3) {
let now = 0;
const timers: Array<() => void> = [];
const lifecycle = new EventTarget();
const fetcher = vi.fn(async () => new Response(null, { status: 204 }));
const adapter = createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
schedule: () => {},
fetcher,
lifecycle,
maxSendsPerMinute,
monotonicNow: () => now,
setTimer: (callback) => {
timers.push(callback);
return timers.length;
},
clearTimer: () => {},
});
return {
adapter,
fetcher,
lifecycle,
timers,
advance(ms: number) {
now += ms;
},
};
}
it("caps collector sends per minute during a sustained failure storm", async () => {
const { adapter, fetcher } = harness(3);
for (let i = 0; i < 25; i += 1) {
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
}
expect(fetcher).toHaveBeenCalledTimes(3);
expect(adapter.pendingCount()).toBeLessThanOrEqual(100);
});
it("delivers held events once the window reopens", async () => {
const { adapter, fetcher, timers, advance } = harness(1);
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
expect(fetcher).toHaveBeenCalledTimes(1);
expect(timers).toHaveLength(1);
advance(60_000);
timers.shift()?.();
await vi.waitFor(() => expect(fetcher).toHaveBeenCalledTimes(2));
expect(adapter.pendingCount()).toBe(0);
});
it("still delivers once on page exit when the window is exhausted", async () => {
const { adapter, fetcher, lifecycle } = harness(1);
adapter.emit("api.request.failed", validAttributes);
await adapter.flush();
adapter.emit("api.request.failed", validAttributes);
lifecycle.dispatchEvent(new Event("pagehide"));
await vi.waitFor(() => expect(fetcher).toHaveBeenCalledTimes(2));
adapter.dispose();
});
it("rejects an unbounded send rate", () => {
expect(() =>
createTelemetryAdapter({
enabled: true,
endpoint: "https://telemetry.test/events",
maxSendsPerMinute: Number.POSITIVE_INFINITY,
}),
).toThrow(TypeError);
});
});