fix(routes): 등록 라우트 없는 URL의 적재 실패를 UNREGISTERED_ROUTE로 적는다 (1101/14.3)
문제: 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.
This commit is contained in:
@@ -290,6 +290,10 @@ chunk recovery 순서:
|
|||||||
"한 번 새로고침" 버튼이 있다(`app-router.tsx`의 `RouteFailureSurface`).
|
"한 번 새로고침" 버튼이 있다(`app-router.tsx`의 `RouteFailureSurface`).
|
||||||
- 복구하지 못한 청크 실패: 같은 형식이다. `ChunkRecoveryBoundary`의
|
- 복구하지 못한 청크 실패: 같은 형식이다. `ChunkRecoveryBoundary`의
|
||||||
`onUnrecovered`가 같은 ID로 `ui.render.failed`를 기록한다.
|
`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`와 같은 값이다
|
- 조회 실패: `AppFailure.requestId`. HTTP 진단의 `correlation_id`와 같은 값이다
|
||||||
(`async-surface.tsx`의 `TerminalErrorSurface`).
|
(`async-surface.tsx`의 `TerminalErrorSurface`).
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
* 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
|
* same route id: a product whose home is a feature screen. The feature's
|
||||||
|
|||||||
@@ -30,6 +30,7 @@ import {
|
|||||||
import {
|
import {
|
||||||
PLATFORM_ROUTE_REGISTRY,
|
PLATFORM_ROUTE_REGISTRY,
|
||||||
type RouteDefinition,
|
type RouteDefinition,
|
||||||
|
UNREGISTERED_ROUTE_ID,
|
||||||
} from "../../contracts/routes.ts";
|
} from "../../contracts/routes.ts";
|
||||||
import { TEMPLATE_APP_MODULE } from "../../apps/template-app.ts";
|
import { TEMPLATE_APP_MODULE } from "../../apps/template-app.ts";
|
||||||
import {
|
import {
|
||||||
@@ -468,6 +469,18 @@ function registeredRouteIdAt(pathname: string): string | undefined {
|
|||||||
return matchRoutes(routes, pathname)?.at(-1)?.route.id;
|
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. */
|
/** The chunk that route recovers, to key chunk recovery on it. */
|
||||||
function routeChunkId(pathname: string): string | undefined {
|
function routeChunkId(pathname: string): string | undefined {
|
||||||
const routeId = registeredRouteIdAt(pathname);
|
const routeId = registeredRouteIdAt(pathname);
|
||||||
@@ -567,7 +580,7 @@ function ContextRouteGateway({
|
|||||||
buildId={buildId}
|
buildId={buildId}
|
||||||
onUnrecovered={(incidentId) =>
|
onUnrecovered={(incidentId) =>
|
||||||
diagnostics.reportRenderFailure({
|
diagnostics.reportRenderFailure({
|
||||||
routeId: routeModule.id,
|
routeId: failedRouteIdAt(location.pathname),
|
||||||
buildId,
|
buildId,
|
||||||
boundaryName: "route",
|
boundaryName: "route",
|
||||||
incidentId,
|
incidentId,
|
||||||
@@ -581,7 +594,7 @@ function ContextRouteGateway({
|
|||||||
// evaluates, a feature runtime that does not load) escalates to the
|
// evaluates, a feature runtime that does not load) escalates to the
|
||||||
// context boundary, which reports it.
|
// context boundary, which reports it.
|
||||||
withinContext(
|
withinContext(
|
||||||
registeredRouteIdAt(location.pathname) ?? routeModule.id,
|
failedRouteIdAt(location.pathname),
|
||||||
<Rethrow error={failure.error} />,
|
<Rethrow error={failure.error} />,
|
||||||
)
|
)
|
||||||
);
|
);
|
||||||
@@ -639,7 +652,7 @@ function ContextLayout({
|
|||||||
buildId={buildId}
|
buildId={buildId}
|
||||||
onUnrecovered={(incidentId) =>
|
onUnrecovered={(incidentId) =>
|
||||||
diagnostics.reportRenderFailure({
|
diagnostics.reportRenderFailure({
|
||||||
routeId: registeredRouteIdAt(pathname) ?? "NOT_FOUND",
|
routeId: failedRouteIdAt(pathname),
|
||||||
buildId,
|
buildId,
|
||||||
boundaryName: "route",
|
boundaryName: "route",
|
||||||
incidentId,
|
incidentId,
|
||||||
|
|||||||
@@ -3,6 +3,7 @@
|
|||||||
import { render, screen } from "@testing-library/react";
|
import { render, screen } from "@testing-library/react";
|
||||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
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 { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
|
||||||
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
|
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
|
||||||
import { AppRouter } from "../../src/presentation/routes/app-router.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.
|
// React logs every caught render error; the assertions below are the point.
|
||||||
vi.spyOn(console, "error").mockImplementation(() => {});
|
vi.spyOn(console, "error").mockImplementation(() => {});
|
||||||
const record = vi.fn();
|
const record = vi.fn();
|
||||||
|
const emit = vi.fn();
|
||||||
window.history.pushState({}, "", url);
|
window.history.pushState({}, "", url);
|
||||||
render(
|
render(
|
||||||
<ApplicationProvider
|
<ApplicationProvider
|
||||||
application={createTestApplication({ diagnostics: { record } })}
|
application={createTestApplication({ diagnostics: { record }, telemetry: { emit } })}
|
||||||
>
|
>
|
||||||
<PreferenceProviders>
|
<PreferenceProviders>
|
||||||
<AppRouter buildId="build-a" />
|
<AppRouter buildId="build-a" />
|
||||||
@@ -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", () => {
|
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 () => {
|
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", {
|
await expectReportedFailure("/fixture/checked", {
|
||||||
routeId: "NOT_FOUND",
|
routeId: "UNREGISTERED_ROUTE",
|
||||||
boundary: "route",
|
boundary: "route",
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|||||||
@@ -3,6 +3,7 @@
|
|||||||
import { act, render, screen, waitFor } from "@testing-library/react";
|
import { act, render, screen, waitFor } from "@testing-library/react";
|
||||||
import { describe, expect, it, vi } from "vitest";
|
import { describe, expect, it, vi } from "vitest";
|
||||||
|
|
||||||
|
import { projectTelemetryEvent } from "../../src/contracts/telemetry.ts";
|
||||||
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
|
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
|
||||||
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
|
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
|
||||||
import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
|
import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
|
||||||
@@ -147,4 +148,38 @@ describe("context route gateway", () => {
|
|||||||
await screen.findByText("새 버전으로 한 번만 전환합니다."),
|
await screen.findByText("새 버전으로 한 번만 전환합니다."),
|
||||||
).toBeVisible();
|
).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(
|
||||||
|
<ApplicationProvider
|
||||||
|
application={createTestApplication({ diagnostics: { record }, telemetry: { emit } })}
|
||||||
|
>
|
||||||
|
<PreferenceProviders>
|
||||||
|
<AppRouter buildId="build-a" />
|
||||||
|
</PreferenceProviders>
|
||||||
|
</ApplicationProvider>,
|
||||||
|
);
|
||||||
|
|
||||||
|
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,
|
||||||
|
});
|
||||||
|
});
|
||||||
});
|
});
|
||||||
|
|||||||
Reference in New Issue
Block a user