Stable Middleware IDs for Instrumentation

[jellevanwezel]

Middleware instrumentation IDs

Status: Stage 0 — Proposal
Modes: Data and Framework (server and client middleware)

Summary

Allow route middleware to declare an ID that is passed to middleware
instrumentation. This gives observability integrations a stable way to identify
individual middleware on a route.

Motivation

Instrumentation can currently observe that a middleware is running, but it
cannot reliably tell which of several middleware functions on the same route is
being invoked. Using a function name is not reliable: names can be absent,
change during minification, or be shared by multiple middleware functions.

This makes it difficult for logging, tracing, and metrics integrations to name,
filter, or aggregate middleware spans. An array index would distinguish entries,
but changes whenever middleware is reordered.

Proposal

Middleware arrays continue to accept functions. They may additionally contain
an object with a string or number ID and a middleware function:

export const middleware = [
  loggingMiddleware,
  { id: "auth", middleware: requireUser },
];

The same shape is available for Data Mode route objects and Framework Mode
middleware and clientMiddleware exports. The generated route types expose
Route.MiddlewareDefinition and Route.ClientMiddlewareDefinition for users
who want to annotate these arrays explicitly.

Middleware instrumentation receives the ID alongside the existing context:

route.instrument({
  async middleware(callMiddleware, { id }) {
    await tracer.startActiveSpan(`middleware.${id}`, async (span) => {
      await callMiddleware();
      span.end();
    });
  },
});

For a function entry, React Router supplies its zero-based index in that
route's middleware array. For an object entry, it supplies the declared id.
IDs are route-local and need not be unique; instrumentation already has the
route identity, so the pair of route ID and middleware ID identifies an
instrumented middleware invocation. Applications that need stable telemetry
should use explicit IDs.

This is additive and does not alter middleware ordering, execution, or the
behavior of existing function entries.

Alternatives considered

• Use only array indexes. This avoids a new object form, but reordering
  middleware silently changes telemetry identity.
• Infer IDs from function names. Function names are not a dependable public
  identifier and are especially unsuitable for production builds.
• Attach an ID to the function. A wrapper object keeps middleware functions
  unmodified and makes the identifier visible at the call site.
• Use middleware classes. A class could expose an ID as a static or instance
  property and implement the middleware behavior. This adds a class-based API
  and changes the existing function-first middleware model for a small piece of
  metadata.
• Use tuples. Middleware could be expressed as [id, middleware]. While
  compact, positional entries are less self-documenting and are easier to
  misread than { id, middleware }, particularly when middleware definitions
  are shared or generated.

Prior art

A working implementation and tests were previously submitted in
PR #15304.