fix(presentation): show a support reference on failure screens (08-07)

Route render, unrecovered chunk and query failure screens now show the id
a user quotes to support, and the render diagnostic records the same id as
correlation_id. The route failure page also offers a reload.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-26 00:32:12 +09:00
co-authored by Claude Opus 5.5
parent f17572a4be
commit b7fc7e53ce
10 changed files with 219 additions and 27 deletions
@@ -5,6 +5,7 @@ import {
} from "react";
import { Button, LoadingSurface } from "../design-system/index.ts";
import { useLocale } from "../i18n/index.ts";
import { newIncidentId } from "./render-error-boundary.tsx";
type RecoveryResult =
| Readonly<{ action: "reload-once"; releasePair: string }>
@@ -17,12 +18,17 @@ type Props = Readonly<{
chunkId: string;
failureKind: "CHUNK_LOAD_FAILURE";
}>): Promise<RecoveryResult>;
/** 08-07. Shown with the incident id as the support reference. */
buildId?: string;
/** 08-07. Records the incident id the support surface shows. */
onUnrecovered?: (incidentId: string) => void;
}>;
type State = Readonly<{
error: unknown | null;
recovery: "idle" | "checking" | "reload-requested" | "support";
reason?: string;
incidentId?: string;
}>;
export function isChunkLoadFailure(error: unknown): boolean {
@@ -55,26 +61,29 @@ export class ChunkRecoveryBoundary extends Component<Props, State> {
failureKind: "CHUNK_LOAD_FAILURE",
})
.then((result) => {
this.setState({
error,
recovery:
result.action === "reload-once"
? "reload-requested"
: "support",
...(result.action === "support" ? { reason: result.reason } : {}),
});
if (result.action === "support") {
this.showSupport(error, result.reason);
} else {
this.setState({ error, recovery: "reload-requested" });
}
})
.catch(() => {
this.setState({
error,
recovery: "support",
reason: "recovery-controller-failed",
});
this.showSupport(error, "recovery-controller-failed");
});
}
private showSupport(error: unknown, reason: string) {
const incidentId = newIncidentId();
this.setState({ error, recovery: "support", reason, incidentId });
try {
this.props.onUnrecovered?.(incidentId);
} catch {
// Diagnostics must never hide the recovery surface.
}
}
render() {
const { error, recovery, reason } = this.state;
const { error, recovery, reason, incidentId } = this.state;
if (error && !isChunkLoadFailure(error)) throw error;
if (error && recovery === "checking") {
return <ChunkRecoverySurface recovery="checking" />;
@@ -83,7 +92,15 @@ export class ChunkRecoveryBoundary extends Component<Props, State> {
return <ChunkRecoverySurface recovery="reload-requested" />;
}
if (error && recovery === "support") {
return <ChunkRecoverySurface recovery="support" reason={reason} />;
return (
<ChunkRecoverySurface
recovery="support"
reason={reason}
supportReference={[this.props.buildId, incidentId]
.filter(Boolean)
.join(":")}
/>
);
}
return this.props.children;
}
@@ -92,9 +109,11 @@ export class ChunkRecoveryBoundary extends Component<Props, State> {
function ChunkRecoverySurface({
recovery,
reason,
supportReference,
}: Readonly<{
recovery: Exclude<State["recovery"], "idle">;
reason?: string;
supportReference?: string;
}>) {
const { message } = useLocale();
if (recovery === "checking") {
@@ -119,6 +138,13 @@ function ChunkRecoverySurface({
<Button onClick={() => window.location.reload()}>
{message("action.reloadOnce")}
</Button>
{supportReference ? (
<p>
{message("template.supportReference", {
reference: supportReference,
})}
</p>
) : null}
</section>
);
}
@@ -10,10 +10,24 @@ export type RenderBoundaryProps = Readonly<{
buildId: string;
resetKey?: string;
onRenderFailure?: (report: RenderFailureReport) => void;
fallback?: ReactNode;
/** A function receives the incident id the failure was reported with. */
fallback?: ReactNode | ((incidentId: string) => ReactNode);
}>;
type RenderBoundaryState = Readonly<{ hasError: boolean }>;
type RenderBoundaryState = Readonly<{
hasError: boolean;
incidentId?: string;
}>;
/**
* 08-07. A short id a failure page shows as its support reference and the
* render diagnostic records, so a user's report finds the event.
* `getRandomValues` also works outside secure contexts, unlike `randomUUID`.
*/
export function newIncidentId(): string {
const [value = 0] = crypto.getRandomValues(new Uint32Array(1));
return value.toString(16).padStart(8, "0");
}
export class RenderErrorBoundary extends Component<
RenderBoundaryProps,
@@ -22,7 +36,7 @@ export class RenderErrorBoundary extends Component<
state: RenderBoundaryState = { hasError: false };
static getDerivedStateFromError(): RenderBoundaryState {
return { hasError: true };
return { hasError: true, incidentId: newIncidentId() };
}
componentDidCatch(): void {
@@ -31,6 +45,9 @@ export class RenderErrorBoundary extends Component<
routeId: this.props.routeId,
buildId: this.props.buildId,
boundaryName: this.props.boundaryName,
...(this.state.incidentId === undefined
? {}
: { incidentId: this.state.incidentId }),
});
} catch {
// Diagnostics must never recurse into another render failure.
@@ -49,9 +66,11 @@ export class RenderErrorBoundary extends Component<
render(): ReactNode {
if (this.state.hasError) {
return (
this.props.fallback ?? <DefaultRenderFailure onRetry={this.reset} />
);
const { fallback } = this.props;
if (typeof fallback === "function") {
return fallback(this.state.incidentId ?? newIncidentId());
}
return fallback ?? <DefaultRenderFailure onRetry={this.reset} />;
}
return this.props.children;
}
@@ -57,6 +57,8 @@ export type TerminalErrorSurfaceProps = Readonly<{
onAction?: () => void;
/** Read before the action, inside the same alert. */
description?: string;
/** 08-07. The id a user quotes to support, e.g. `AppFailure.requestId`. */
supportReference?: string;
}>;
export function TerminalErrorSurface({
@@ -64,6 +66,7 @@ export function TerminalErrorSurface({
action,
onAction,
description,
supportReference,
}: TerminalErrorSurfaceProps) {
const { locale, message } = useLocale();
const messageId = useId();
@@ -88,6 +91,13 @@ export function TerminalErrorSurface({
{action !== "none" && onAction && (
<Button onClick={onAction}>{actionLabels[action]}</Button>
)}
{supportReference ? (
<p>
{message("template.supportReference", {
reference: supportReference,
})}
</p>
) : null}
</section>
);
}
@@ -130,6 +140,7 @@ export function AsyncSurface({
? onRetry ?? onAction
: onAction
}
supportReference={state.failure.requestId}
/>
);
}
+43 -6
View File
@@ -91,8 +91,11 @@ function RouteLoadingSurface({
function RouteFailureSurface({
definition,
supportReference,
}: {
definition?: RouteDefinition;
/** 08-07. The build and, when reported, the incident id. */
supportReference: string;
}) {
const { message } = useLocale();
return (
@@ -101,6 +104,14 @@ function RouteFailureSurface({
title: message("route.failure.title"),
description: message("route.failure.description"),
}}
// RENDER_FAILURE's registry action: a render defect stays until the
// URL changes, so the page offers the reload itself.
primaryAction={{
kind: "button",
label: message("action.reloadOnce"),
onAction: () => window.location.reload(),
}}
supportReference={supportReference}
surface={definition?.errorSurface ?? "route-boundary"}
variant="unexpected"
/>
@@ -328,6 +339,8 @@ function RouteSurface({
if (!runtime) return <DisabledFeatureSurface featureId={owner ?? routeId} />;
const parsed = parseRouteInput(routeId, params, search);
if (!parsed.success) return <InvalidRouteSurface code={parsed.code} />;
const boundaryName =
definition.errorSurface === "feature-boundary" ? "feature" : "route";
const content = (
<RouteInputProvider input={parsed.data}>
@@ -339,6 +352,15 @@ function RouteSurface({
key={definition.routeId}
chunkId={definition.chunkId}
recover={recovery.recoverChunk}
buildId={buildId}
onUnrecovered={(incidentId) =>
diagnostics.reportRenderFailure({
routeId,
buildId,
boundaryName,
incidentId,
})
}
>
<runtime.Component />
</ChunkRecoveryBoundary>
@@ -356,10 +378,15 @@ function RouteSurface({
buildId,
resetKey: `${location.pathname}${location.search}`,
onRenderFailure: diagnostics.reportRenderFailure,
fallback: <RouteFailureSurface definition={definition} />,
fallback: (incidentId: string) => (
<RouteFailureSurface
definition={definition}
supportReference={`${buildId}:${incidentId}`}
/>
),
children: protectedContent,
};
return definition.errorSurface === "feature-boundary" ? (
return boundaryName === "feature" ? (
<FeatureBoundary {...boundaryProps} />
) : (
<RouteBoundary {...boundaryProps} />
@@ -404,6 +431,7 @@ function ContextRouteGateway({
}: Readonly<{ routeModule: ContextRouteModule; buildId: string }>) {
const location = useLocation();
const recovery = useApplicationRecovery();
const diagnostics = useApplicationDiagnostics();
const [routes, setRoutes] = useState<readonly RouteObject[] | null>(null);
const [failure, setFailure] = useState<Readonly<{ error: unknown }> | null>(
null,
@@ -431,7 +459,7 @@ function ContextRouteGateway({
<ContextErrorBoundary
contextId={routeModule.id}
resetKey={resetKey}
fallback={<RouteFailureSurface />}
fallback={<RouteFailureSurface supportReference={buildId} />}
>
{content}
</ContextErrorBoundary>
@@ -444,11 +472,20 @@ function ContextRouteGateway({
<ChunkRecoveryBoundary
chunkId={routeChunkId(location.pathname) ?? routeModule.id}
recover={recovery.recoverChunk}
buildId={buildId}
onUnrecovered={(incidentId) =>
diagnostics.reportRenderFailure({
routeId: routeModule.id,
buildId,
boundaryName: "route",
incidentId,
})
}
>
<Rethrow error={failure.error} />
</ChunkRecoveryBoundary>
) : (
<RouteFailureSurface />
<RouteFailureSurface supportReference={buildId} />
);
}
if (routes === null) return <RouteLoadingSurface />;
@@ -475,7 +512,7 @@ function ContextRouteGateway({
<FeatureErrorBoundary
featureId={featureId}
resetKey={resetKey}
fallback={<RouteFailureSurface />}
fallback={<RouteFailureSurface supportReference={buildId} />}
>
{route}
</FeatureErrorBoundary>
@@ -522,7 +559,7 @@ function createRegisteredRoutes(buildId: string): RouteObject[] {
id: "APP_SHELL",
path: "/",
element: <AppShell />,
errorElement: <RouteFailureSurface />,
errorElement: <RouteFailureSurface supportReference={buildId} />,
children: [...platformChildren, ...contextChildren],
},
];