문제
QueryDefinition의 namespace는 아무 문자열, namespaceVersion은 아무
숫자다. bindQuery는 이 둘로 쿼리 키를 만들 뿐 무효화 registry에 있는지
보지 않는다. 저장 뒤 무효화는 topic -> 등록 namespace 접두사로만 가므로,
namespace 오타나 version만 올린 조회, registry에 빠진 namespace의 조회는
저장 뒤에도 갱신되지 않는다. 오류도 진단도 없다(E7). 문서는 "query
namespace는 registry reference"라고 적지만(client-cache-and-storage.md),
참조 기능도 registry 객체에서 두 필드를 꺼내 문자열로 다시 넘긴다.
고른 방법
- 런타임 검사(리뷰 ②): cache coordinator가 QueryCache의 "added"
이벤트를 구독한다. bindQuery 키 접두사(["query", 2, id, version])를
읽어 registry 인덱스(topicsForNamespace)에 없으면 namespace당 한 번
cache.operation.failed(operation: unregistered-query-namespace) 진단을
남긴다. registry와 TanStack 키의 연결은 원래 이 coordinator가 갖고
있으므로(무효화 접두사) 새 결합을 만들지 않는다. dispose 때 구독을 푼다.
- 정적 조회 예외: QueryDefinition에 선택 필드 invalidation: "NONE"을
더한다. bindQuery가 BoundQuery로 옮기고, useApplicationQuery가 공유 상수
QUERY_WITHOUT_INVALIDATION_META를 TanStack meta로 넣고, coordinator가 같은
상수로 읽는다. 상수는 query-keys.ts에 둔다. server-state.ts에 두면
coordinator(초기 청크)가 그 모듈 전체를 끌어와 초기 JS에 server-state
청크가 하나 생긴다(측정: +1,407 B gzip, 파일 16 -> 17).
- 타입(리뷰 ①, 추가만): QueryDefinition.namespace가 registry의
QueryNamespaceIdentity 객체를 그대로 받는다. 참조 기능의 두 조회는 등록
객체를 넘긴다. 문자열 id + namespaceVersion 쌍도 계속 받는다.
버린 대안
- 문자열 쌍을 없애고 객체만 받기(리뷰 ①의 원안): 공개 타입 시그니처를
깨서 다운스트림 조회 정의를 모두 고쳐야 한다. 이번 범위에서는 공개
포트를 추가만 한다. 문자열 쌍의 오타는 위 진단이 잡는다.
- useApplicationQuery에서 검사하고 QueryInvalidationCoordinator에 메서드
추가: 공개 인터페이스가 늘고, 다른 경로로 cache에 들어오는 bound 키는
못 본다.
- 개발 빌드에서 throw(리뷰 ②): QueryCache 구독 콜백에서 throw하면 TanStack
알림 경로가 깨진다. 진단 1건으로 완료 기준("타입 오류 또는 진단 1건")을
채운다.
- 진단에 namespace id 싣기: id는 80바이트까지 허용돼 진단 값 문법(64자)을
넘으면 기록 전체가 버려진다. id 없이 operation만 남겼다.
위험·한계
- 런타임 검사라 그 조회가 처음 cache에 들어갈 때(화면을 열 때) 드러난다.
- "등록은 했지만 edge가 없음"은 registry 인덱스가 시작 때 orphan
namespace로 거절하므로 여기까지 오지 않는다.
- 진단에서 어느 namespace인지는 알 수 없다. 개수만 보인다.
- useApplicationQuery -> meta 연결은 타입 검사로만 확인했다. 그 경로의
런타임 테스트는 없다.
- 공개 타입은 추가만 했다(QueryDefinition namespace 유니언, invalidation,
BoundQuery.invalidation, 상수 1개).
검증
- RED(수정 전): tests/unit/tanstack-cache-coordinator.test.ts "reports a
bound query whose namespace no registered topic reaches (03-01)" 실패.
"expected vi.fn() to be called 2 times, but got 0 times".
- GREEN: 같은 파일 10/10, tests/features/reference-feature 포함 17 files /
89 tests 통과. 변이 M20(참조 목록 조회 namespace를 문자열 오타 쌍으로)을
넣으면 reference-page.test.tsx가 실패하는 것을 확인하고 원복했다.
- 회귀: run-vitest tests/unit tests/integration tests/component
tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일
12개 제외) 228 files 중 227 통과, 2369/2370. 실패 1건은
provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의
다른 실행 때문)로 이 변경과 무관하다.
tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED.
- 번들: build-frontend로 빌드해 check-bundle과 같은 분류로 초기 JS를
gzipSync로 쟀다. 298201f 202,509 B(16 파일) -> 이 커밋까지 세 커밋 누적
202,913 B(16 파일), +404 B. 예산 204,800 B. 예산은 바꾸지 않았다.
- 미실행: check:architecture(pnpm 스크립트 필요). depcruise 직접 실행은
0 modules라 사실상 미검증이다. 새 import는 adapter -> contracts,
presentation -> contracts뿐이다.
Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
418 lines
14 KiB
TypeScript
418 lines
14 KiB
TypeScript
import { QueryClient } from "@tanstack/react-query";
|
|
import { describe, expect, it, vi } from "vitest";
|
|
|
|
import type {
|
|
BrowserCrossContextInvalidation,
|
|
CrossContextInvalidationDelivery,
|
|
} from "../../src/adapters/cross-context-invalidation/index.ts";
|
|
import { createTanStackCacheCoordinator } from "../../src/adapters/query-cache/tanstack-cache-coordinator.ts";
|
|
import {
|
|
defineQueryInvalidationTopic,
|
|
indexInvalidationRegistry,
|
|
} from "../../src/contracts/query-invalidation.ts";
|
|
import {
|
|
createBoundQueryKey,
|
|
createRuntimeIdentityRegistry,
|
|
defineQueryNamespaceIdentity,
|
|
type QueryNamespaceIdentity,
|
|
} from "../../src/contracts/query-keys.ts";
|
|
import { bindQuery } from "../../src/contracts/server-state.ts";
|
|
import type { CacheScopeSnapshot } from "../../src/contracts/server-state-scope.ts";
|
|
|
|
const TOPIC_A = defineQueryInvalidationTopic("qinv.topic-a");
|
|
const TOPIC_B = defineQueryInvalidationTopic("qinv.topic-b");
|
|
const NAMESPACE_A = defineQueryNamespaceIdentity("resource-a", 1);
|
|
const NAMESPACE_B = defineQueryNamespaceIdentity("resource-b", 1);
|
|
const NAMESPACE_C = defineQueryNamespaceIdentity("resource-c", 1);
|
|
|
|
function invalidationIndex() {
|
|
return indexInvalidationRegistry({
|
|
topics: [TOPIC_A, TOPIC_B],
|
|
namespaces: [NAMESPACE_A, NAMESPACE_B, NAMESPACE_C],
|
|
edges: [
|
|
{ topicId: TOPIC_A, namespace: NAMESPACE_A },
|
|
{ topicId: TOPIC_A, namespace: NAMESPACE_B },
|
|
{ topicId: TOPIC_B, namespace: NAMESPACE_B },
|
|
{ topicId: TOPIC_B, namespace: NAMESPACE_C },
|
|
],
|
|
});
|
|
}
|
|
|
|
function topicVersions() {
|
|
return new Map([
|
|
[TOPIC_A, 1],
|
|
[TOPIC_B, 1],
|
|
]);
|
|
}
|
|
|
|
function realBoundQueryKey(namespace: QueryNamespaceIdentity) {
|
|
const scope: CacheScopeSnapshot = {
|
|
generation: 1,
|
|
fingerprint: "scope-fingerprint-0001",
|
|
identities: createRuntimeIdentityRegistry({
|
|
tokenFactory: () => `identity-token-${namespace.namespaceId}`,
|
|
}),
|
|
signal: new AbortController().signal,
|
|
isCurrent: () => true,
|
|
};
|
|
return bindQuery(
|
|
{
|
|
definitionId: `${namespace.namespaceId}-query-v1`,
|
|
definitionVersion: 1,
|
|
owner: "platform-test",
|
|
namespace: namespace.namespaceId,
|
|
namespaceVersion: namespace.namespaceVersion,
|
|
operationId: `GET_${namespace.namespaceId.toUpperCase()}`,
|
|
profileId: "DETAIL_STANDARD",
|
|
measureResult: () => ({ itemCount: 1, estimatedBytes: 8 }),
|
|
execute: async () => ({ ok: true as const, value: namespace.namespaceId }),
|
|
},
|
|
{ selected: namespace.namespaceId },
|
|
scope,
|
|
).queryKey;
|
|
}
|
|
|
|
function crossContextHarness() {
|
|
let listener:
|
|
| ((delivery: CrossContextInvalidationDelivery) => void)
|
|
| undefined;
|
|
const publish = vi.fn(
|
|
(_event: { topic: string; topicVersion: number }) => ({
|
|
ok: true as const,
|
|
transport: "BROADCAST" as const,
|
|
}),
|
|
);
|
|
const close = vi.fn();
|
|
const transport: BrowserCrossContextInvalidation = {
|
|
getStatus: () => "ACTIVE_BROADCAST",
|
|
publish,
|
|
subscribe(next) {
|
|
listener = next;
|
|
return () => {
|
|
listener = undefined;
|
|
};
|
|
},
|
|
close,
|
|
};
|
|
return Object.freeze({
|
|
transport,
|
|
publish,
|
|
close,
|
|
deliver(topic: string, ordering: "NEXT" | "GAP" = "NEXT") {
|
|
listener?.({
|
|
ordering,
|
|
transport: "BROADCAST",
|
|
event: {
|
|
protocolVersion: 1,
|
|
eventId: `event-${topic}-${ordering}`,
|
|
sourceId: "remote-source",
|
|
sourceEpoch: "remote-epoch",
|
|
sequence: 1,
|
|
cacheEpoch: "cache-epoch",
|
|
topic,
|
|
topicVersion: 1,
|
|
emittedAt: 1,
|
|
expiresAt: 60_001,
|
|
},
|
|
});
|
|
},
|
|
});
|
|
}
|
|
|
|
function createClient(): QueryClient {
|
|
return new QueryClient({
|
|
defaultOptions: {
|
|
queries: { retry: false, staleTime: Infinity, gcTime: Infinity },
|
|
mutations: { retry: false },
|
|
},
|
|
});
|
|
}
|
|
|
|
describe("TanStack cross-context cache coordinator", () => {
|
|
it("invalidates every real V2 key connected to one local topic and publishes only topic identity", async () => {
|
|
const client = createClient();
|
|
const harness = crossContextHarness();
|
|
const keyA = realBoundQueryKey(NAMESPACE_A);
|
|
const keyB = realBoundQueryKey(NAMESPACE_B);
|
|
const unrelatedKey = realBoundQueryKey(NAMESPACE_C);
|
|
client.setQueryData(keyA, ["a"]);
|
|
client.setQueryData(keyB, ["b"]);
|
|
client.setQueryData(unrelatedKey, ["c"]);
|
|
const dependencies = {
|
|
queryClient: client,
|
|
invalidationIndex: invalidationIndex(),
|
|
topicVersions: topicVersions(),
|
|
crossContext: harness.transport,
|
|
};
|
|
const coordinator = createTanStackCacheCoordinator(dependencies);
|
|
|
|
await coordinator.invalidate([TOPIC_A]);
|
|
|
|
expect(client.getQueryState(keyA)?.isInvalidated).toBe(true);
|
|
expect(client.getQueryState(keyB)?.isInvalidated).toBe(true);
|
|
expect(client.getQueryState(unrelatedKey)?.isInvalidated).toBe(false);
|
|
expect(harness.publish).toHaveBeenCalledOnce();
|
|
expect(harness.publish.mock.calls[0]?.[0]).toEqual({
|
|
topic: TOPIC_A,
|
|
topicVersion: 1,
|
|
});
|
|
});
|
|
|
|
it("invalidates every real V2 key connected to one remote topic without echoing it", async () => {
|
|
const client = createClient();
|
|
const harness = crossContextHarness();
|
|
const keyA = realBoundQueryKey(NAMESPACE_A);
|
|
const keyB = realBoundQueryKey(NAMESPACE_B);
|
|
const unrelatedKey = realBoundQueryKey(NAMESPACE_C);
|
|
client.setQueryData(keyA, ["a"]);
|
|
client.setQueryData(keyB, ["b"]);
|
|
client.setQueryData(unrelatedKey, ["c"]);
|
|
const dependencies = {
|
|
queryClient: client,
|
|
invalidationIndex: invalidationIndex(),
|
|
topicVersions: topicVersions(),
|
|
crossContext: harness.transport,
|
|
};
|
|
createTanStackCacheCoordinator(dependencies);
|
|
|
|
harness.deliver(TOPIC_A);
|
|
|
|
await vi.waitFor(() => {
|
|
expect(client.getQueryState(keyA)?.isInvalidated).toBe(true);
|
|
expect(client.getQueryState(keyB)?.isInvalidated).toBe(true);
|
|
});
|
|
expect(client.getQueryState(unrelatedKey)?.isInvalidated).toBe(false);
|
|
expect(harness.publish).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("invalidates each real V2 namespace once when a sequence gap spans overlapping topics", async () => {
|
|
const client = createClient();
|
|
const harness = crossContextHarness();
|
|
const keyA = realBoundQueryKey(NAMESPACE_A);
|
|
const keyB = realBoundQueryKey(NAMESPACE_B);
|
|
const keyC = realBoundQueryKey(NAMESPACE_C);
|
|
client.setQueryData(keyA, ["a"]);
|
|
client.setQueryData(keyB, ["b"]);
|
|
client.setQueryData(keyC, ["c"]);
|
|
const invalidate = vi.spyOn(client, "invalidateQueries");
|
|
const dependencies = {
|
|
queryClient: client,
|
|
invalidationIndex: invalidationIndex(),
|
|
topicVersions: topicVersions(),
|
|
crossContext: harness.transport,
|
|
};
|
|
createTanStackCacheCoordinator(dependencies);
|
|
|
|
harness.deliver(TOPIC_A, "GAP");
|
|
|
|
await vi.waitFor(() => {
|
|
expect(client.getQueryState(keyA)?.isInvalidated).toBe(true);
|
|
expect(client.getQueryState(keyB)?.isInvalidated).toBe(true);
|
|
expect(client.getQueryState(keyC)?.isInvalidated).toBe(true);
|
|
});
|
|
expect(invalidate).toHaveBeenCalledTimes(3);
|
|
});
|
|
|
|
it("starts every namespace refetch at once and reports each failure", async () => {
|
|
// Q-6.3-8. invalidateQueries resolves only after active refetches finish,
|
|
// so awaiting namespaces one by one added their refetch times together.
|
|
const client = createClient();
|
|
const pending: Array<() => void> = [];
|
|
const invalidate = vi
|
|
.spyOn(client, "invalidateQueries")
|
|
.mockImplementationOnce(
|
|
() => new Promise<void>((resolve) => pending.push(resolve)),
|
|
)
|
|
.mockImplementationOnce(() => Promise.reject(new Error("refetch failed")));
|
|
const record = vi.fn();
|
|
const coordinator = createTanStackCacheCoordinator({
|
|
queryClient: client,
|
|
invalidationIndex: invalidationIndex(),
|
|
topicVersions: topicVersions(),
|
|
diagnostics: { record } as never,
|
|
});
|
|
|
|
let settled = false;
|
|
const done = coordinator.invalidate([TOPIC_A]).then(() => {
|
|
settled = true;
|
|
});
|
|
await vi.waitFor(() => expect(invalidate).toHaveBeenCalledTimes(2));
|
|
expect(settled).toBe(false);
|
|
|
|
pending.forEach((resolve) => resolve());
|
|
await done;
|
|
expect(record).toHaveBeenCalledOnce();
|
|
expect(record.mock.calls[0]?.[0]).toMatchObject({
|
|
context: { operation: "invalidate" },
|
|
});
|
|
});
|
|
|
|
it("coalesces remote hints while a local mutation lease is held", async () => {
|
|
const client = createClient();
|
|
const harness = crossContextHarness();
|
|
client.setQueryData(["resource-a", 1, "list"], ["a"]);
|
|
const invalidate = vi.spyOn(client, "invalidateQueries");
|
|
const coordinator = createTanStackCacheCoordinator({
|
|
queryClient: client,
|
|
invalidationIndex: invalidationIndex(),
|
|
topicVersions: topicVersions(),
|
|
crossContext: harness.transport,
|
|
});
|
|
const lease = coordinator.beginMutation([TOPIC_A]);
|
|
|
|
harness.deliver(TOPIC_A);
|
|
harness.deliver(TOPIC_A);
|
|
await Promise.resolve();
|
|
expect(invalidate).not.toHaveBeenCalled();
|
|
|
|
await lease.release();
|
|
expect(invalidate).toHaveBeenCalledTimes(2);
|
|
expect(harness.publish).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("fences remote delivery until a local reset has cancelled and cleared the cache", async () => {
|
|
const client = createClient();
|
|
const harness = crossContextHarness();
|
|
client.setQueryData(["resource-a", 1, "list"], ["private-old-scope"]);
|
|
let finishCancellation: (() => void) | undefined;
|
|
const cancelQueries = vi
|
|
.spyOn(client, "cancelQueries")
|
|
.mockImplementation(
|
|
() =>
|
|
new Promise<void>((resolve) => {
|
|
finishCancellation = resolve;
|
|
}),
|
|
);
|
|
const invalidate = vi.spyOn(client, "invalidateQueries");
|
|
const coordinator = createTanStackCacheCoordinator({
|
|
queryClient: client,
|
|
invalidationIndex: invalidationIndex(),
|
|
topicVersions: topicVersions(),
|
|
crossContext: harness.transport,
|
|
});
|
|
|
|
const reset = coordinator.resetLocal();
|
|
await vi.waitFor(() => expect(cancelQueries).toHaveBeenCalledOnce());
|
|
harness.deliver(TOPIC_A);
|
|
await Promise.resolve();
|
|
expect(invalidate).not.toHaveBeenCalled();
|
|
|
|
finishCancellation?.();
|
|
await reset;
|
|
expect(client.getQueryData(["resource-a", 1, "list"])).toBeUndefined();
|
|
await vi.waitFor(() => expect(invalidate).toHaveBeenCalledTimes(2));
|
|
expect(harness.publish).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("rejects a mandatory local reset when query cancellation fails", async () => {
|
|
const client = createClient();
|
|
client.setQueryData(["resource-a", 1, "list"], ["private-old-scope"]);
|
|
vi.spyOn(client, "cancelQueries").mockRejectedValue(
|
|
new Error("cancellation failed"),
|
|
);
|
|
const clear = vi.spyOn(client, "clear");
|
|
const coordinator = createTanStackCacheCoordinator({
|
|
queryClient: client,
|
|
invalidationIndex: invalidationIndex(),
|
|
topicVersions: topicVersions(),
|
|
});
|
|
|
|
await expect(coordinator.resetLocal()).rejects.toThrow(
|
|
"mandatory query cancellation failed",
|
|
);
|
|
expect(clear).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("composes with no installed query topics", () => {
|
|
// §24.12: removing the reference feature leaves the common runtime intact.
|
|
// A template with no installed feature has zero invalidation topics, which
|
|
// is a legitimate state, not a configuration defect.
|
|
const harness = crossContextHarness();
|
|
const coordinator = createTanStackCacheCoordinator({
|
|
queryClient: createClient(),
|
|
invalidationIndex: indexInvalidationRegistry({
|
|
topics: [],
|
|
namespaces: [],
|
|
edges: [],
|
|
}),
|
|
topicVersions: new Map(),
|
|
crossContext: harness.transport,
|
|
});
|
|
|
|
// A remote hint for a topic this build does not install is ignored, not fatal.
|
|
harness.deliver("qinv.topic-a");
|
|
expect(() => coordinator.beginMutation([])).not.toThrow();
|
|
coordinator.dispose();
|
|
});
|
|
|
|
/**
|
|
* 03-01 (E7). A save invalidates topics, and a topic reaches only registered
|
|
* namespaces. A bound query under any other namespace (a typo, a bumped
|
|
* version, a namespace left out of the registry) silently never refreshes,
|
|
* so the coordinator reports it once per namespace.
|
|
*/
|
|
it("reports a bound query whose namespace no registered topic reaches (03-01)", async () => {
|
|
const queryClient = createClient();
|
|
const record = vi.fn();
|
|
const coordinator = createTanStackCacheCoordinator({
|
|
queryClient,
|
|
invalidationIndex: invalidationIndex(),
|
|
topicVersions: topicVersions(),
|
|
diagnostics: { record },
|
|
});
|
|
const typo = defineQueryNamespaceIdentity("resource-x", 1);
|
|
const bumpedOnly = defineQueryNamespaceIdentity("resource-a", 2);
|
|
const declaredStatic = defineQueryNamespaceIdentity("lookup-static", 1);
|
|
|
|
queryClient.setQueryData(realBoundQueryKey(NAMESPACE_A), "registered");
|
|
queryClient.setQueryData(realBoundQueryKey(typo), "typo");
|
|
queryClient.setQueryData(
|
|
createBoundQueryKey(typo, "scope-fingerprint-0002", 1, "identity-token-again"),
|
|
"typo again",
|
|
);
|
|
queryClient.setQueryData(realBoundQueryKey(bumpedOnly), "bumped");
|
|
queryClient.setQueryData(["legacy-key", 1], "not a bound query");
|
|
await queryClient.prefetchQuery({
|
|
queryKey: realBoundQueryKey(declaredStatic),
|
|
queryFn: async () => "static lookup",
|
|
meta: { invalidation: "NONE" },
|
|
});
|
|
await new Promise((resolve) => setTimeout(resolve, 0));
|
|
|
|
expect(record).toHaveBeenCalledTimes(2);
|
|
expect(record).toHaveBeenCalledWith({
|
|
level: "warn",
|
|
eventId: "cache.operation.failed",
|
|
context: {
|
|
operation: "unregistered-query-namespace",
|
|
error_kind: "QUERY_CACHE_FAILURE",
|
|
},
|
|
});
|
|
coordinator.dispose();
|
|
|
|
// A disposed coordinator stops watching the cache.
|
|
queryClient.setQueryData(
|
|
realBoundQueryKey(defineQueryNamespaceIdentity("resource-y", 1)),
|
|
"after dispose",
|
|
);
|
|
await new Promise((resolve) => setTimeout(resolve, 0));
|
|
expect(record).toHaveBeenCalledTimes(2);
|
|
});
|
|
|
|
it("rejects an unregistered topic before opening a mutation lease", () => {
|
|
const coordinator = createTanStackCacheCoordinator({
|
|
queryClient: createClient(),
|
|
invalidationIndex: invalidationIndex(),
|
|
topicVersions: topicVersions(),
|
|
});
|
|
|
|
expect(() =>
|
|
coordinator.beginMutation([
|
|
defineQueryInvalidationTopic("unknown-topic"),
|
|
]),
|
|
).toThrow(
|
|
"Unregistered query invalidation topic",
|
|
);
|
|
});
|
|
});
|