From ffb6782b0c0cb05361cdad02f2da84fb9712b7d3 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:26:36 +0900 Subject: [PATCH] =?UTF-8?q?fix(query):=20=EB=AC=B4=ED=9A=A8=ED=99=94=20top?= =?UTF-8?q?ic=EC=9D=B4=20=EB=8B=BF=EC=A7=80=20=EC=95=8A=EB=8A=94=20?= =?UTF-8?q?=EC=A1=B0=ED=9A=8C=20namespace=EB=A5=BC=20=EC=A7=84=EB=8B=A8?= =?UTF-8?q?=EC=9C=BC=EB=A1=9C=20=EC=95=8C=EB=A6=B0=EB=8B=A4=20(03-01)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 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 --- docs/architecture/client-cache-and-storage.md | 7 +++ .../query-cache/tanstack-cache-coordinator.ts | 49 +++++++++++++++++ src/contracts/query-keys.ts | 12 ++++ src/contracts/server-state.ts | 41 +++++++++++--- .../presentation/use-reference-feature.ts | 8 +-- .../adapters/query/application-query.ts | 10 +++- tests/unit/tanstack-cache-coordinator.test.ts | 55 +++++++++++++++++++ 7 files changed, 168 insertions(+), 14 deletions(-) diff --git a/docs/architecture/client-cache-and-storage.md b/docs/architecture/client-cache-and-storage.md index afa249fd..f7915853 100644 --- a/docs/architecture/client-cache-and-storage.md +++ b/docs/architecture/client-cache-and-storage.md @@ -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는 diff --git a/src/adapters/query-cache/tanstack-cache-coordinator.ts b/src/adapters/query-cache/tanstack-cache-coordinator.ts index 305db5d7..83581774 100644 --- a/src/adapters/query-cache/tanstack-cache-coordinator.ts +++ b/src/adapters/query-cache/tanstack-cache-coordinator.ts @@ -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(); + 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; + } +} diff --git a/src/contracts/query-keys.ts b/src/contracts/query-keys.ts index 8de078e3..3f32544b 100644 --- a/src/contracts/query-keys.ts +++ b/src/contracts/query-keys.ts @@ -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, diff --git a/src/contracts/server-state.ts b/src/contracts/server-state.ts index f7476c64..d0da23fd 100644 --- a/src/contracts/server-state.ts +++ b/src/contracts/server-state.ts @@ -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 = 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>; }>; +/** + * 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 = 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>; -}>; +}> & + QueryDefinitionNamespace; export function bindQuery( definition: QueryDefinition, @@ -181,10 +199,16 @@ export function bindQuery( `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( profile: getServerStateProfile(definition.profileId), identity, scope, + ...(definition.invalidation === undefined + ? {} + : { invalidation: definition.invalidation }), measureResult: (value: Value) => definition.measureResult(value), execute: (context) => definition.execute(input, context), }); diff --git a/src/features/reference-feature/presentation/use-reference-feature.ts b/src/features/reference-feature/presentation/use-reference-feature.ts index ca1f9761..fd51b25c 100644 --- a/src/features/reference-feature/presentation/use-reference-feature.ts +++ b/src/features/reference-feature/presentation/use-reference-feature.ts @@ -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, diff --git a/src/presentation/adapters/query/application-query.ts b/src/presentation/adapters/query/application-query.ts index c747c916..aa87347f 100644 --- a/src/presentation/adapters/query/application-query.ts +++ b/src/presentation/adapters/query/application-query.ts @@ -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( "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( const query = useQuery({ queryKey, enabled, + ...(invalidation === "NONE" + ? { meta: QUERY_WITHOUT_INVALIDATION_META } + : {}), retry: false, staleTime: profile?.staleTimeMs, gcTime: profile?.gcTimeMs, diff --git a/tests/unit/tanstack-cache-coordinator.test.ts b/tests/unit/tanstack-cache-coordinator.test.ts index aa8aa888..dc89ac2e 100644 --- a/tests/unit/tanstack-cache-coordinator.test.ts +++ b/tests/unit/tanstack-cache-coordinator.test.ts @@ -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(),