fix(query): 무효화 topic이 닿지 않는 조회 namespace를 진단으로 알린다 (03-01)
문제
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
This commit is contained in:
@@ -466,6 +466,13 @@ normative key layout:
|
||||
non-finite number, DOM/native object를 fail-closed로 거절한다.
|
||||
- array 순서는 의미가 있으므로 유지한다.
|
||||
- query namespace는 arbitrary caller string이 아니라 registry reference다.
|
||||
현재 구현(03-01): `QueryDefinition.namespace`에 무효화 registry의
|
||||
`QueryNamespaceIdentity` 객체를 그대로 넘긴다(참조 기능이 이렇게 한다).
|
||||
예전 형태인 문자열 id와 `namespaceVersion` 쌍도 아직 받는다. 어느 등록
|
||||
topic도 닿지 않는 namespace로 bound query가 만들어지면 cache coordinator가
|
||||
namespace당 한 번 `cache.operation.failed`(`operation:
|
||||
unregistered-query-namespace`) 진단을 남긴다. 저장으로 무효화할 일이 없는
|
||||
정적 조회는 `invalidation: "NONE"`으로 선언해 이 진단에서 뺀다.
|
||||
- cross-tab event에는 전체 query key나 filter를 넣지 않는다.
|
||||
|
||||
현재 `src/contracts/query-keys.ts`의 `canonicalize()`는 object key order는
|
||||
|
||||
@@ -10,6 +10,8 @@ import type {
|
||||
import { INVALIDATION_REGISTRY_BOUNDS } from "../../contracts/query-invalidation.ts";
|
||||
import {
|
||||
createQueryInvalidationPrefix,
|
||||
QUERY_KEY_SCHEMA_VERSION,
|
||||
QUERY_WITHOUT_INVALIDATION_META,
|
||||
queryNamespaceIdentityKey,
|
||||
type QueryNamespaceIdentity,
|
||||
} from "../../contracts/query-keys.ts";
|
||||
@@ -49,6 +51,32 @@ export function createTanStackCacheCoordinator(
|
||||
receiveRemote(delivery);
|
||||
});
|
||||
|
||||
// 03-01. A save invalidates topics, and a topic reaches only registered
|
||||
// namespaces. A bound query under any other namespace never refreshes after
|
||||
// a save, silently, so each such namespace is reported once.
|
||||
const reportedNamespaces = new Set<string>();
|
||||
const unsubscribeQueryCache = dependencies.queryClient
|
||||
.getQueryCache()
|
||||
.subscribe((event) => {
|
||||
if (event.type !== "added") return;
|
||||
if (
|
||||
event.query.meta?.invalidation ===
|
||||
QUERY_WITHOUT_INVALIDATION_META.invalidation
|
||||
) {
|
||||
return;
|
||||
}
|
||||
const namespaceKey = boundQueryNamespaceKey(event.query.queryKey);
|
||||
if (
|
||||
namespaceKey === null ||
|
||||
reportedNamespaces.has(namespaceKey) ||
|
||||
dependencies.invalidationIndex.topicsForNamespace.has(namespaceKey)
|
||||
) {
|
||||
return;
|
||||
}
|
||||
reportedNamespaces.add(namespaceKey);
|
||||
report("unregistered-query-namespace");
|
||||
});
|
||||
|
||||
function namespacesFor(
|
||||
topic: QueryInvalidationTopic,
|
||||
): readonly QueryNamespaceIdentity[] {
|
||||
@@ -277,6 +305,7 @@ export function createTanStackCacheCoordinator(
|
||||
if (disposed) return;
|
||||
disposed = true;
|
||||
unsubscribe?.();
|
||||
unsubscribeQueryCache();
|
||||
dependencies.crossContext?.close();
|
||||
pendingRemote.clear();
|
||||
mutationLeases.clear();
|
||||
@@ -320,3 +349,23 @@ function validateConfiguration(
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 03-01. The registry key of a `bindQuery` key's namespace, read from the
|
||||
* prefix `createQueryInvalidationPrefix` builds. Any other key is not a bound
|
||||
* query and yields `null`.
|
||||
*/
|
||||
function boundQueryNamespaceKey(queryKey: readonly unknown[]): string | null {
|
||||
const [root, schemaVersion, namespaceId, namespaceVersion] = queryKey;
|
||||
if (root !== "query" || schemaVersion !== QUERY_KEY_SCHEMA_VERSION) {
|
||||
return null;
|
||||
}
|
||||
try {
|
||||
return queryNamespaceIdentityKey({
|
||||
namespaceId: namespaceId as string,
|
||||
namespaceVersion: namespaceVersion as number,
|
||||
});
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -65,6 +65,18 @@ export function createQueryInvalidationPrefix(
|
||||
] as const);
|
||||
}
|
||||
|
||||
/**
|
||||
* 03-01. The TanStack query `meta` of a bound query declared
|
||||
* `invalidation: "NONE"` (`QueryDefinition`). `useApplicationQuery` sets it and
|
||||
* the cache coordinator reads it, so a static lookup is not reported as a
|
||||
* namespace no invalidation topic reaches. It lives here, beside the key
|
||||
* layout the coordinator already reads, so the coordinator does not pull
|
||||
* `server-state.ts` into the initial bundle.
|
||||
*/
|
||||
export const QUERY_WITHOUT_INVALIDATION_META = Object.freeze({
|
||||
invalidation: "NONE" as const,
|
||||
});
|
||||
|
||||
export function createBoundQueryKey(
|
||||
namespace: QueryNamespaceIdentity,
|
||||
scopeFingerprint: string,
|
||||
|
||||
@@ -3,6 +3,7 @@ import type { QueryInvalidationTopic } from "./query-invalidation.ts";
|
||||
import {
|
||||
createBoundQueryKey,
|
||||
defineQueryNamespaceIdentity,
|
||||
type QueryNamespaceIdentity,
|
||||
type RuntimeIdentityBinding,
|
||||
} from "./query-keys.ts";
|
||||
import type { CacheScopeSnapshot } from "./server-state-scope.ts";
|
||||
@@ -152,24 +153,41 @@ export type BoundQuery<Value> = Readonly<{
|
||||
profile: ServerStateProfile;
|
||||
identity: RuntimeIdentityBinding;
|
||||
scope: CacheScopeSnapshot;
|
||||
/** 03-01. Copied from `QueryDefinition.invalidation`. */
|
||||
invalidation?: "NONE";
|
||||
measureResult(value: Value): QueryResultMeasure;
|
||||
execute(context: Readonly<{ signal: AbortSignal }>): Promise<Result<Value>>;
|
||||
}>;
|
||||
|
||||
/**
|
||||
* 03-01. Pass the registry's `QueryNamespaceIdentity` (the object the
|
||||
* feature's invalidation registry lists) as `namespace`. The older pair of a
|
||||
* caller-written id and `namespaceVersion` still binds, but nothing ties it to
|
||||
* the registry: a typo there only shows up as the cache coordinator's
|
||||
* `unregistered-query-namespace` diagnostic.
|
||||
*/
|
||||
type QueryDefinitionNamespace =
|
||||
| Readonly<{ namespace: QueryNamespaceIdentity; namespaceVersion?: never }>
|
||||
| Readonly<{ namespace: string; namespaceVersion: number }>;
|
||||
|
||||
export type QueryDefinition<Input, Value> = Readonly<{
|
||||
definitionId: string;
|
||||
definitionVersion: number;
|
||||
owner: string;
|
||||
namespace: string;
|
||||
namespaceVersion: number;
|
||||
operationId: string;
|
||||
profileId: ServerStateProfileId;
|
||||
/**
|
||||
* 03-01. `"NONE"` declares a query no save invalidates (a static lookup).
|
||||
* Without it, a namespace no registered topic reaches is reported.
|
||||
*/
|
||||
invalidation?: "NONE";
|
||||
measureResult(value: Value): QueryResultMeasure;
|
||||
execute(
|
||||
input: Input,
|
||||
context: Readonly<{ signal: AbortSignal }>,
|
||||
): Promise<Result<Value>>;
|
||||
}>;
|
||||
}> &
|
||||
QueryDefinitionNamespace;
|
||||
|
||||
export function bindQuery<Input, Value>(
|
||||
definition: QueryDefinition<Input, Value>,
|
||||
@@ -181,10 +199,16 @@ export function bindQuery<Input, Value>(
|
||||
`Query definition requires measureResult: ${definition.definitionId}`,
|
||||
);
|
||||
}
|
||||
const namespace = defineQueryNamespaceIdentity(
|
||||
definition.namespace,
|
||||
definition.namespaceVersion,
|
||||
);
|
||||
const namespace =
|
||||
typeof definition.namespace === "string"
|
||||
? defineQueryNamespaceIdentity(
|
||||
definition.namespace,
|
||||
definition.namespaceVersion as number,
|
||||
)
|
||||
: defineQueryNamespaceIdentity(
|
||||
definition.namespace.namespaceId,
|
||||
definition.namespace.namespaceVersion,
|
||||
);
|
||||
const identity = scope.identities.intern(input);
|
||||
return Object.freeze({
|
||||
definitionId: definition.definitionId,
|
||||
@@ -199,6 +223,9 @@ export function bindQuery<Input, Value>(
|
||||
profile: getServerStateProfile(definition.profileId),
|
||||
identity,
|
||||
scope,
|
||||
...(definition.invalidation === undefined
|
||||
? {}
|
||||
: { invalidation: definition.invalidation }),
|
||||
measureResult: (value: Value) => definition.measureResult(value),
|
||||
execute: (context) => definition.execute(input, context),
|
||||
});
|
||||
|
||||
@@ -87,9 +87,7 @@ export function useReferenceDetail(resourceId: string) {
|
||||
definitionId: "reference-resource-detail-v1",
|
||||
definitionVersion: 1,
|
||||
owner: REFERENCE_FEATURE_ID,
|
||||
namespace: REFERENCE_RESOURCE_QUERY_NAMESPACE.namespaceId,
|
||||
namespaceVersion:
|
||||
REFERENCE_RESOURCE_QUERY_NAMESPACE.namespaceVersion,
|
||||
namespace: REFERENCE_RESOURCE_QUERY_NAMESPACE,
|
||||
operationId: "GET_REFERENCE_RESOURCE",
|
||||
profileId: "DETAIL_STANDARD",
|
||||
measureResult: measureResourceView,
|
||||
@@ -124,9 +122,7 @@ export function useReferenceFeature() {
|
||||
definitionId: "reference-resource-list-v1",
|
||||
definitionVersion: 1,
|
||||
owner: REFERENCE_FEATURE_ID,
|
||||
namespace: REFERENCE_RESOURCE_QUERY_NAMESPACE.namespaceId,
|
||||
namespaceVersion:
|
||||
REFERENCE_RESOURCE_QUERY_NAMESPACE.namespaceVersion,
|
||||
namespace: REFERENCE_RESOURCE_QUERY_NAMESPACE,
|
||||
operationId: "LIST_REFERENCE_RESOURCES",
|
||||
profileId: "LIST_STANDARD",
|
||||
measureResult: measureResourceList,
|
||||
|
||||
@@ -37,7 +37,10 @@ import {
|
||||
MUTATION_COORDINATOR_BOUNDS,
|
||||
type MutationDuplicatePolicy,
|
||||
} from "../../../contracts/server-state.ts";
|
||||
import { runtimeIdentityToken } from "../../../contracts/query-keys.ts";
|
||||
import {
|
||||
QUERY_WITHOUT_INVALIDATION_META,
|
||||
runtimeIdentityToken,
|
||||
} from "../../../contracts/query-keys.ts";
|
||||
import { useQueryInvalidationCoordinator } from "./query-invalidation-provider.tsx";
|
||||
import { useMutationIntentFactory } from "./mutation-intent-provider.tsx";
|
||||
import {
|
||||
@@ -81,6 +84,8 @@ export function useApplicationQuery<Value>(
|
||||
"measureResult" in options ? options.measureResult : undefined;
|
||||
const queryDefinitionId =
|
||||
"definitionId" in options ? options.definitionId : "APPLICATION_QUERY";
|
||||
const invalidation =
|
||||
"invalidation" in options ? options.invalidation : undefined;
|
||||
const [staleFailure, setStaleFailure] = useState(false);
|
||||
useEffect(() => {
|
||||
identity?.acquire();
|
||||
@@ -89,6 +94,9 @@ export function useApplicationQuery<Value>(
|
||||
const query = useQuery<Value, ApplicationQueryError>({
|
||||
queryKey,
|
||||
enabled,
|
||||
...(invalidation === "NONE"
|
||||
? { meta: QUERY_WITHOUT_INVALIDATION_META }
|
||||
: {}),
|
||||
retry: false,
|
||||
staleTime: profile?.staleTimeMs,
|
||||
gcTime: profile?.gcTimeMs,
|
||||
|
||||
@@ -11,6 +11,7 @@ import {
|
||||
indexInvalidationRegistry,
|
||||
} from "../../src/contracts/query-invalidation.ts";
|
||||
import {
|
||||
createBoundQueryKey,
|
||||
createRuntimeIdentityRegistry,
|
||||
defineQueryNamespaceIdentity,
|
||||
type QueryNamespaceIdentity,
|
||||
@@ -344,6 +345,60 @@ describe("TanStack cross-context cache coordinator", () => {
|
||||
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(),
|
||||
|
||||
Reference in New Issue
Block a user