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:
co-authored by
Claude Opus 5.5
parent
f17572a4be
commit
b7fc7e53ce
@@ -62,6 +62,11 @@ export function createApplication(
|
||||
route_id: report.routeId,
|
||||
build_id: report.buildId,
|
||||
component_boundary: report.boundaryName,
|
||||
// Incident-scoped like a request id: diagnostics only, never
|
||||
// telemetry.
|
||||
...(report.incidentId === undefined
|
||||
? {}
|
||||
: { correlation_id: report.incidentId }),
|
||||
},
|
||||
});
|
||||
} catch {
|
||||
|
||||
@@ -24,6 +24,8 @@ export type RenderFailureReport = Readonly<{
|
||||
routeId: string;
|
||||
buildId: string;
|
||||
boundaryName: "route" | "feature";
|
||||
/** 08-07. The id the failure page shows as its support reference. */
|
||||
incidentId?: string;
|
||||
}>;
|
||||
|
||||
export type RouteChangedReport = Readonly<{
|
||||
|
||||
@@ -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}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -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],
|
||||
},
|
||||
];
|
||||
|
||||
Reference in New Issue
Block a user