From 7c8cb19e94535658d34c0de04f9c9ceb6f02e95e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 20:23:17 +0900 Subject: [PATCH] =?UTF-8?q?fix(routes):=20=EB=93=B1=EB=A1=9D=20=EB=9D=BC?= =?UTF-8?q?=EC=9A=B0=ED=8A=B8=20=EC=97=86=EB=8A=94=20URL=EC=9D=98=20?= =?UTF-8?q?=EC=A0=81=EC=9E=AC=20=EC=8B=A4=ED=8C=A8=EB=A5=BC=20UNREGISTERED?= =?UTF-8?q?=5FROUTE=EB=A1=9C=20=EC=A0=81=EB=8A=94=EB=8B=A4=20(1101/14.3)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: context gateway가 라우트 적재 실패를 `ui.render.failed`로 남길 때 `route_id`를 URL에서 고른다. 고르는 곳이 세 군데이고 결과가 서로 다르다. - 청크 누락이 아닌 실패: `registeredRouteIdAt(...) ?? routeModule.id`. 레지스트리의 NOT_FOUND splat이 모든 URL에 맞아서 등록 라우트가 없는 URL은 `NOT_FOUND`가 되고 대체값은 한 번도 쓰이지 않는다. 운영에서는 not-found 화면이 깨진 것처럼 읽혀 플랫폼 담당에게 간다. 실제로 실패한 것은 context의 라우트 모듈이다. - 복구하지 못한 청크 실패: 늘 `routeModule.id`(context id). telemetry는 `route_id`를 `^[A-Z][A-Z0-9_]{0,63}$`로만 받는다. 그래서 이 이벤트는 `invalid-attribute-value`로 버려진다(`projectTelemetryEvent`로 확인). - 레이아웃 청크 실패: `?? "NOT_FOUND"`. 레이아웃 아래 context는 등록 경로에만 붙어서 지금은 닿지 않는 값이다. 이 진단이 구분해야 하는 것은 둘이다. 어느 화면(그래서 어느 기능)이 실패했나, 그리고 not-found 화면 자체가 실패했나. 그 값은 telemetry까지 가야 한다. 고른 방법: 세 곳이 `failedRouteIdAt(pathname)` 하나를 쓴다. URL의 등록 라우트 id를 쓰고, 등록 라우트가 없으면(NOT_FOUND만 맞으면) 명시값 `UNREGISTERED_ROUTE`(`UNREGISTERED_ROUTE_ID`, src/contracts/routes.ts)를 쓴다. 등록 URL의 청크 실패는 context id 대신 그 라우트 id가 된다. 라우트 id로 소유 기능과 context를 찾을 수 있다. 청크 복구의 chunkId 선택은 바꾸지 않았다. 버린 대안: - context id(`routeModule.id`, 원래 의도한 대체값): 실패한 모듈을 정확히 가리키지만 telemetry가 버린다. 받게 하려면 `route_id` 문법을 소문자 kebab까지 넓혀야 한다. 그러면 `api.request.failed` 등 모든 이벤트의 `route_id` 검사가 약해진다. - context id를 대문자 snake로 바꿔 쓰기: 숨은 이름 규칙이 생기고 실제 라우트 id와 섞인다. - `context_id` 속성 추가: 진단·telemetry 허용 목록과 레지스트리 기준선을 바꿔야 한다. 기준선 재승인은 이 작업 범위가 아니다. 위험·한계: - 등록 라우트가 없는 URL의 실패는 어느 context인지 진단에 남지 않는다. 같은 결함은 그 context의 등록 URL에서도 나므로 그 보고로 찾는다. - [계약] `ui.render.failed`의 `route_id`에 `UNREGISTERED_ROUTE` 값이 생긴다. 복구하지 못한 context 라우트 청크 실패는 context id 대신 라우트 id를 적는다. `route_id` 이름과 허용 문법은 그대로다. - 기능이 `UNREGISTERED_ROUTE`라는 route id를 선언하면 구분되지 않는다. 막지 않았다. 검증: - RED: context-boundary-diagnostics "unregistered handle" 1건이 `"route_id": "NOT_FOUND"`로 실패. context-route-gateway 새 2건이 `"route_id": "context-offline"`로 실패(8건 중 3 실패). - GREEN: 두 파일과 context-layouts 14건 통과. 각 보고는 telemetry 투영 (`projectTelemetryEvent`)도 통과한다. - 회귀: tests/{architecture,unit,features,platform,component,contract, runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306 files, 3,572건 통과. - tsc app·test 통과. 바꾼 파일 eslint 통과. check-registries, check-diagnostics 통과. verify-documentation-readiness PASS_SCOPED. --- .../routing-pages-and-patterns.md | 4 +++ src/contracts/routes.ts | 8 +++++ src/presentation/routes/app-router.tsx | 19 ++++++++-- .../context-boundary-diagnostics.test.tsx | 12 +++++-- .../component/context-route-gateway.test.tsx | 35 +++++++++++++++++++ 5 files changed, 72 insertions(+), 6 deletions(-) diff --git a/docs/architecture/routing-pages-and-patterns.md b/docs/architecture/routing-pages-and-patterns.md index bb5cfe0c..fdc9a828 100644 --- a/docs/architecture/routing-pages-and-patterns.md +++ b/docs/architecture/routing-pages-and-patterns.md @@ -290,6 +290,10 @@ chunk recovery 순서: "한 번 새로고침" 버튼이 있다(`app-router.tsx`의 `RouteFailureSurface`). - 복구하지 못한 청크 실패: 같은 형식이다. `ChunkRecoveryBoundary`의 `onUnrecovered`가 같은 ID로 `ui.render.failed`를 기록한다. +- context가 라우트나 레이아웃을 불러오지 못한 실패: `route_id`는 그 URL의 등록 + 라우트 id다. 등록 라우트가 없는 URL이면 `UNREGISTERED_ROUTE`다. not-found + 화면이 실패한 것이 아니므로 `NOT_FOUND`를 쓰지 않는다(`app-router.tsx`의 + `failedRouteIdAt`). - 조회 실패: `AppFailure.requestId`. HTTP 진단의 `correlation_id`와 같은 값이다 (`async-surface.tsx`의 `TerminalErrorSurface`). diff --git a/src/contracts/routes.ts b/src/contracts/routes.ts index 8abbad36..e4bcf431 100644 --- a/src/contracts/routes.ts +++ b/src/contracts/routes.ts @@ -97,6 +97,14 @@ export const PLATFORM_ROUTE_REGISTRY = Object.freeze({ }), }); +/** + * 1101/14.3. The `route_id` a render failure reports when no registered route + * names the URL: a context failed to load at an address none of its routes + * has. NOT_FOUND would say the not-found page failed, and a context id is not + * a route id, which telemetry drops. + */ +export const UNREGISTERED_ROUTE_ID = "UNREGISTERED_ROUTE"; + /** * 09-03. Platform routes an installed feature may take over by declaring the * same route id: a product whose home is a feature screen. The feature's diff --git a/src/presentation/routes/app-router.tsx b/src/presentation/routes/app-router.tsx index 1ecff079..d391d1a8 100644 --- a/src/presentation/routes/app-router.tsx +++ b/src/presentation/routes/app-router.tsx @@ -30,6 +30,7 @@ import { import { PLATFORM_ROUTE_REGISTRY, type RouteDefinition, + UNREGISTERED_ROUTE_ID, } from "../../contracts/routes.ts"; import { TEMPLATE_APP_MODULE } from "../../apps/template-app.ts"; import { @@ -468,6 +469,18 @@ function registeredRouteIdAt(pathname: string): string | undefined { return matchRoutes(routes, pathname)?.at(-1)?.route.id; } +/** + * 1101/14.3. The route a gateway or layout failure is reported under. The + * NOT_FOUND splat matches every URL, but there the context failed, not the + * not-found page. + */ +function failedRouteIdAt(pathname: string): string { + const routeId = registeredRouteIdAt(pathname); + return routeId === undefined || routeId === "NOT_FOUND" + ? UNREGISTERED_ROUTE_ID + : routeId; +} + /** The chunk that route recovers, to key chunk recovery on it. */ function routeChunkId(pathname: string): string | undefined { const routeId = registeredRouteIdAt(pathname); @@ -567,7 +580,7 @@ function ContextRouteGateway({ buildId={buildId} onUnrecovered={(incidentId) => diagnostics.reportRenderFailure({ - routeId: routeModule.id, + routeId: failedRouteIdAt(location.pathname), buildId, boundaryName: "route", incidentId, @@ -581,7 +594,7 @@ function ContextRouteGateway({ // evaluates, a feature runtime that does not load) escalates to the // context boundary, which reports it. withinContext( - registeredRouteIdAt(location.pathname) ?? routeModule.id, + failedRouteIdAt(location.pathname), , ) ); @@ -639,7 +652,7 @@ function ContextLayout({ buildId={buildId} onUnrecovered={(incidentId) => diagnostics.reportRenderFailure({ - routeId: registeredRouteIdAt(pathname) ?? "NOT_FOUND", + routeId: failedRouteIdAt(pathname), buildId, boundaryName: "route", incidentId, diff --git a/tests/component/context-boundary-diagnostics.test.tsx b/tests/component/context-boundary-diagnostics.test.tsx index 23f92f00..b71c1afb 100644 --- a/tests/component/context-boundary-diagnostics.test.tsx +++ b/tests/component/context-boundary-diagnostics.test.tsx @@ -3,6 +3,7 @@ import { render, screen } from "@testing-library/react"; import { afterEach, describe, expect, it, vi } from "vitest"; +import { projectTelemetryEvent } from "../../src/contracts/telemetry.ts"; import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx"; import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx"; import { AppRouter } from "../../src/presentation/routes/app-router.tsx"; @@ -105,10 +106,11 @@ async function expectReportedFailure( // React logs every caught render error; the assertions below are the point. vi.spyOn(console, "error").mockImplementation(() => {}); const record = vi.fn(); + const emit = vi.fn(); window.history.pushState({}, "", url); render( @@ -133,6 +135,9 @@ async function expectReportedFailure( }, }, ]); + // The same failure reaches telemetry, which takes route ids only. + const [telemetry] = emit.mock.calls.filter(([name]) => name === "ui.render.failed"); + expect(projectTelemetryEvent(telemetry?.[0], telemetry?.[1])).toMatchObject({ success: true }); } describe("context gateway failure diagnostics", () => { @@ -158,9 +163,10 @@ describe("context gateway failure diagnostics", () => { }); it("reports an unregistered handle refused while the routes load", async () => { - // No feature route owns this URL; the registry's NOT_FOUND splat does. + // 1101/14.3. No registered route names this URL. The context failed, not + // the not-found page, so the report must not say NOT_FOUND. await expectReportedFailure("/fixture/checked", { - routeId: "NOT_FOUND", + routeId: "UNREGISTERED_ROUTE", boundary: "route", }); }); diff --git a/tests/component/context-route-gateway.test.tsx b/tests/component/context-route-gateway.test.tsx index b4cba8d6..8295b0e1 100644 --- a/tests/component/context-route-gateway.test.tsx +++ b/tests/component/context-route-gateway.test.tsx @@ -3,6 +3,7 @@ import { act, render, screen, waitFor } from "@testing-library/react"; import { describe, expect, it, vi } from "vitest"; +import { projectTelemetryEvent } from "../../src/contracts/telemetry.ts"; import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx"; import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx"; import { AppRouter } from "../../src/presentation/routes/app-router.tsx"; @@ -147,4 +148,38 @@ describe("context route gateway", () => { await screen.findByText("새 버전으로 한 번만 전환합니다."), ).toBeVisible(); }); + + // 1101/14.3. Without a new deploy the download stays failed. The report + // names the route at the URL, or UNREGISTERED_ROUTE when no route does + // (not NOT_FOUND, whose page did not fail), and telemetry takes it: it + // accepts route ids only, so the context id was dropped there. + it.each([ + ["/fixture/items/new", "FIXTURE_ITEM_FORM"], + ["/fixture/items/new/unknown", "UNREGISTERED_ROUTE"], + ])("reports an unrecovered routes-module download at %s as %s", async (url, routeId) => { + const record = vi.fn(); + const emit = vi.fn(); + window.history.pushState({}, "", url); + render( + + + + + , + ); + + await screen.findByText(/^지원 참조: build-a:[0-9a-f]{8}$/); + expect(record).toHaveBeenCalledWith( + expect.objectContaining({ + eventId: "ui.render.failed", + context: expect.objectContaining({ route_id: routeId }), + }), + ); + const [telemetry] = emit.mock.calls.filter(([name]) => name === "ui.render.failed"); + expect(projectTelemetryEvent(telemetry?.[0], telemetry?.[1])).toMatchObject({ + success: true, + }); + }); });