fix(cross-context-invalidation): publish 실패 원인을 관측 reason에 싣는다 (02-05)

문제: cross-context publish가 실패하면 원인과 상관없이 관측 reason이
INVALID_ENVELOPE다. createEventId가 던질 때(host에서는 secure random
실패)와 자기 envelope 검사 실패가 같은 invalidPublish()로 가고, 그
함수가 reason을 고정한다. bootstrap은 이 reason을 그대로
cache.operation.failed 진단에 싣는다. 난수 실패나 topic version
불일치가 "wire 형식 오류"로 보여 원인을 찾으려면 코드를 읽어야 한다.

고른 방법: invalidPublish가 reason을 인자로 받는다. event ID 실패는
이미 reason 목록에 있는 SECURE_RANDOM_UNAVAILABLE, envelope 검사
실패는 parse 결과의 reason(TOPIC_REJECTED 등)을 싣는다. 새 reason
값은 만들지 않는다. 호출자에게 돌려주는 결과
{ok:false, reason:"INVALID_EVENT"}는 그대로다.

위험·한계: 관측 reason 값이 바뀌므로 INVALID_ENVELOPE로 경보를 거는
대시보드가 있다면 새 값도 봐야 한다. 이 repo 안에는 그런 소비자가
없다. cross-context는 기본 조립이라 초기 JS에 들어간다. 바뀐 코드는
수십 바이트이고, 빌드 기반 번들 게이트(check:bundle)는 pnpm이 필요해
이 worktree에서 돌리지 않았다.

검증:
- RED(수정 전): cross-tab-invalidation.test.ts 새 1건이
  "expected [ 'INVALID_ENVELOPE' ] to deeply equal
  [ 'SECURE_RANDOM_UNAVAILABLE' ]"로 실패.
- GREEN: 같은 파일 통과.
- 회귀: cross-tab-invalidation·tanstack-cache-coordinator·
  runtime-adapters 단위 3파일 46건 통과. tsc app·test 통과. 바꾼 파일
  eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
This commit is contained in:
DongHyeonka
2026-11-01 23:14:47 +09:00
parent 3bb1829cda
commit 5b96529c53
2 changed files with 45 additions and 4 deletions
@@ -314,7 +314,8 @@ export function createBrowserCrossContextInvalidation(
try {
eventId = dependencies.createEventId();
} catch {
return invalidPublish();
// The host's event IDs come from secure random (02-05).
return invalidPublish("SECURE_RANDOM_UNAVAILABLE");
}
const candidate: CacheInvalidationWireEvent = Object.freeze({
protocolVersion: CACHE_INVALIDATION_PROTOCOL_VERSION,
@@ -333,7 +334,7 @@ export function createBrowserCrossContextInvalidation(
topicVersions,
nowEpochMilliseconds: emittedAt,
});
if (!parsed.ok) return invalidPublish();
if (!parsed.ok) return invalidPublish(parsed.reason);
sequence = candidate.sequence;
pruneTracking(emittedAt);
@@ -364,12 +365,14 @@ export function createBrowserCrossContextInvalidation(
return publishThroughStorage(candidate);
}
function invalidPublish(): CrossContextInvalidationPublishResult {
function invalidPublish(
reason: CrossContextInvalidationObservationReason,
): CrossContextInvalidationPublishResult {
observe({
operation: "PUBLISH",
outcome: "FAILED",
transport: "NONE",
reason: "INVALID_ENVELOPE",
reason,
});
return Object.freeze({ ok: false, reason: "INVALID_EVENT" });
}
+38
View File
@@ -869,4 +869,42 @@ describe("browser cross-context invalidation transport", () => {
expect(network.messages).toHaveLength(0);
runtime.close();
});
it("observes why a publish failed instead of one envelope reason (2026-11-01 02-05)", () => {
const failedReasons = (
overrides: Partial<BrowserCrossContextInvalidationDependencies>,
topicVersion: number,
) => {
const reasons: string[] = [];
const runtime = createBrowserCrossContextInvalidation(
dependencies("tab-a", {
createBroadcastChannel: new FakeBroadcastNetwork().createChannel,
observe: (observation) => {
if (observation.operation === "PUBLISH") {
reasons.push(observation.reason);
}
},
...overrides,
}),
);
expect(runtime.publish({ topic: TOPIC, topicVersion })).toEqual({
ok: false,
reason: "INVALID_EVENT",
});
runtime.close();
return reasons;
};
expect(
failedReasons(
{
createEventId: () => {
throw new Error("secure random unavailable");
},
},
1,
),
).toEqual(["SECURE_RANDOM_UNAVAILABLE"]);
expect(failedReasons({}, 2)).toEqual(["TOPIC_REJECTED"]);
});
});