Building Request Context

Welcome back! In the previous lesson, you replaced repeated route-level parsing with reusable Zod schemas and validateRequest() middleware. Validated parameters, query strings, and bodies now flow through response.locals.validated, while the centralized error handler formats every ZodError consistently. In this lesson, you’ll extend that middleware architecture in two directions. First, every request will receive shared context—a stable request ID and start timestamp—near the beginning of the Express pipeline. Second, only routes that consume JSON bodies will enforce Content-Type: application/json . You’ll also compare the two ways errors enter Express 5’s final error handler: rejected async promises and explicit next(error) calls.

Understanding Middleware Scope

Express middleware can be mounted globally or attached to specific routes. Global middleware runs for every request: text GET /health GET /api/tickets POST /api/tickets PATCH /api/tickets/:ticketId DELETE /api/tickets/:ticketId Route-level middleware runs only where it is explicitly added. This project follows a useful rule: text Global concern \to mount broadly Representation rule \to mount narrowly Request IDs are useful on every request, including successful responses, validation failures, missing routes, and internal errors. The request-context middleware therefore belongs near the beginning of the application. JSON enforcement is different. Only routes that actually consume JSON bodies should require a JSON content type. Applying that rule globally would incorrectly reject ordinary GET and DELETE requests.

Creating a Request Context

The global middleware lives in src/middleware/request-context.ts . TypeScript import { randomUUID } from "node:crypto"; import type { RequestHandler } from "express"; export const requestContext: RequestHandler = (request, response, next,) => {const requestId = request.header("x-request-id")?.trim() || randomUUID(); response.locals.requestId = requestId; response.locals.startedAt = Date.now(); response.setHeader("X-Request-Id", requestId); next();}; request.header("x-request-id") reads an optional incoming trace identifier. HTTP header names are case-insensitive, so clients may display the name as X-Request-Id . .trim() removes surrounding whitespace. A non-empty client value is preserved, while a missing or whitespace-only value falls through to randomUUID() . response.locals.requestId stores the selected identifier for the rest of the current request. Later middleware and route handlers can reuse it without reading the header again or generating another ID. response.locals.startedAt records Date.now() when the request enters the application. It can later support request-duration logging or response metadata. The same request ID is echoed through the X-Request-Id response header. A client can therefore correlate its request with logs or diagnostics on the server. next() passes control to the following middleware. This middleware establishes context but does not complete the response. A custom incoming value such as: text X-Request-Id: simulator-trace-001 is preserved exactly after trimming. Without the header, the response contains a generated UUID instead.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

The request-context middleware is registered once in src/app.ts.

TypeScript

export function createApp() {
  const app = express();

  app.use(requestContext);
  app.use(cors());
  app.use(express.json());
  app.use(express.urlencoded({ extended: true }));

  if (env.NODE_ENV !== "test") {
    app.use(morgan("dev"));
  }

  app.use(healthRoutes);
  app.use("/api/tickets", ticketRoutes);
  app.use("/api/async-demo", asyncDemoRoutes);

  app.use(notFound);
  app.use(errorHandler);

  return app;
}

export function createApp() {
  const app = express();

  app.use(requestContext);
  app.use(cors());
  app.use(express.json());
  app.use(express.urlencoded({ extended: true }));

  if (env.NODE_ENV !== "test") {
    app.use(morgan("dev"));
  }

  app.use(healthRoutes);
  app.use("/api/tickets", ticketRoutes);
  app.use("/api/async-demo", asyncDemoRoutes);

  app.use(notFound);
  app.use(errorHandler);

  return app;
}

requestContext runs before body parsers and feature routers. Every later stage can depend on response.locals.requestId and response.locals.startedAt.
It also runs before notFound and errorHandler. Even unsuccessful requests receive the same trace identifier established at the start.
The middleware is mounted only once. Feature routes should not create replacement request IDs because that would break correlation across the pipeline.
errorHandler remains last. Errors produced by parsing, validation, route handlers, or later middleware can flow into it.

Middleware order describes the path a request follows. Global context must be created before anything that may need it.

The API Simulator provides a Headers tab alongside Params, Authorization, and Body.

Keep the base URL set to:

text

http://localhost:4000

http://localhost:4000

Send:

text

GET /api/tickets

GET /api/tickets

Add this header:

text

X-Request-Id: middleware-observation-001

X-Request-Id: middleware-observation-001

After sending the request, inspect the response headers. The response should contain:

text

X-Request-Id: middleware-observation-001

X-Request-Id: middleware-observation-001

Remove the custom header and resend the request. The server should generate a UUID and return it in the same response header.

Because request context is global, the behavior is not limited to tickets. Health checks, missing routes, validation failures, and internal errors also pass through the middleware.

The application already mounts Express’s JSON parser globally:

TypeScript

app.use(express.json());

app.use(express.json());

This middleware answers:

If a request contains JSON, how should Express parse it?

The project’s requireJson middleware answers a different question:

Does this particular route accept anything other than JSON?

These concerns should remain separate. Global parsing makes parsed JSON available throughout the app, while route-level enforcement determines which handlers require that representation.

The media-type guard lives in src/middleware/require-json.ts.

TypeScript

import type { RequestHandler } from "express";

export const requireJson: RequestHandler = (
  request,
  response,
  next,
) => {
  if (!request.is("application/json")) {
    response.status(415).json({
      error: {
        code: "UNSUPPORTED_MEDIA_TYPE",
        message: "Content-Type must be application/json.",
      },
    });
    return;
  }

  next();
};

import type { RequestHandler } from "express";

export const requireJson: RequestHandler = (
  request,
  response,
  next,
) => {
  if (!request.is("application/json")) {
    response.status(415).json({
      error: {
        code: "UNSUPPORTED_MEDIA_TYPE",
        message: "Content-Type must be application/json.",
      },
    });
    return;
  }

  next();
};

request.is("application/json") checks the request’s content type using Express’s media-type logic.
This is safer than comparing the raw header to one exact string. It accepts standard variants such as:

text

application/json
application/json; charset=utf-8

application/json
application/json; charset=utf-8

A missing or unsupported content type produces HTTP 415 Unsupported Media Type.
The response uses the focused code UNSUPPORTED_MEDIA_TYPE and explains which content type the endpoint requires.
The handler returns after sending the rejection, preventing validation or repository work from running.
A supported JSON request calls next() exactly once.

A global JSON requirement would reject requests that do not need bodies:

text

GET /api/tickets
GET /api/tickets/tkt_1001
GET /api/tickets/tkt_1001/comments
DELETE /api/tickets/tkt_1001

GET /api/tickets
GET /api/tickets/tkt_1001
GET /api/tickets/tkt_1001/comments
DELETE /api/tickets/tkt_1001

These requests should work without a Content-Type header.

Only the routes that consume JSON bodies use requireJson:

text

POST  /api/tickets
PATCH /api/tickets/:ticketId
POST  /api/tickets/:ticketId/comments

POST  /api/tickets
PATCH /api/tickets/:ticketId
POST  /api/tickets/:ticketId/comments

This keeps the rule at the narrowest useful scope.

Ordering JSON Enforcement Before Zod

The ticket creation route in src/routes/ticket-routes.ts composes several middleware functions.

TypeScript

ticketRoutes.post(
  "/",
  requireJson,
  validateRequest({ body: createTicketBodySchema }),
  async (_request, response) => {
    const { body } = response.locals.validated as {
      body: CreateTicketBody;
    };

    if (!(await userExists(body.requesterId))) {
      response.status(400).json({
        error: {
          code: "INVALID_REQUESTER",
          message:
            "requesterId does not reference an existing user.",
        },
      });
      return;
    }

    const ticket = await createTicket(body);

    response.setHeader(
      "Location",
      `/api/tickets/${ticket.id}`,
    );
    response.status(201).json(ticket);
  },
);

ticketRoutes.post(
  "/",
  requireJson,
  validateRequest({ body: createTicketBodySchema }),
  async (_request, response) => {
    const { body } = response.locals.validated as {
      body: CreateTicketBody;
    };

    if (!(await userExists(body.requesterId))) {
      response.status(400).json({
        error: {
          code: "INVALID_REQUESTER",
          message:
            "requesterId does not reference an existing user.",
        },
      });
      return;
    }

    const ticket = await createTicket(body);

    response.setHeader(
      "Location",
      `/api/tickets/${ticket.id}`,
    );
    response.status(201).json(ticket);
  },
);

The execution order is:

text

requireJson
    ↓
validateRequest
    ↓
userExists
    ↓
createTicket

requireJson
    ↓
validateRequest
    ↓
userExists
    ↓
createTicket

requireJson runs first. A plain-text request stops with 415 before Zod examines the body.
A JSON request continues into validateRequest(), which applies trimming, defaults, enum checks, and length rules.
Structurally valid data then reaches the requester existence check and PostgreSQL repository.

This produces distinct responses for distinct problems:

text

Wrong content type       → 415 UNSUPPORTED_MEDIA_TYPE
Invalid JSON body shape  → 400 VALIDATION_ERROR
Missing requester row    → 400 INVALID_REQUESTER
Successful creation      → 201 Created

Wrong content type       → 415 UNSUPPORTED_MEDIA_TYPE
Invalid JSON body shape  → 400 VALIDATION_ERROR
Missing requester row    → 400 INVALID_REQUESTER
Successful creation      → 201 Created

Ticket updates use the same middleware order.

TypeScript

.patch(
  requireJson,
  validateRequest({
    params: ticketIdParamsSchema,
    body: updateTicketBodySchema,
  }),
  async (_request, response) => {
    const { params, body } =
      response.locals.validated as {
        params: TicketIdParams;
        body: UpdateTicketBody;
      };

    const ticket = await updateTicket(
      params.ticketId,
      body,
    );

    if (!ticket) {
      response.status(404).json({
        error: {
          code: "TICKET_NOT_FOUND",
          message: "Ticket not found.",
        },
      });
      return;
    }

    response.status(200).json(ticket);
  },
)

.patch(
  requireJson,
  validateRequest({
    params: ticketIdParamsSchema,
    body: updateTicketBodySchema,
  }),
  async (_request, response) => {
    const { params, body } =
      response.locals.validated as {
        params: TicketIdParams;
        body: UpdateTicketBody;
      };

    const ticket = await updateTicket(
      params.ticketId,
      body,
    );

    if (!ticket) {
      response.status(404).json({
        error: {
          code: "TICKET_NOT_FOUND",
          message: "Ticket not found.",
        },
      });
      return;
    }

    response.status(200).json(ticket);
  },
)

A JSON content type is required because PATCH consumes an update body.
Zod validates both the ticket parameter and the body after the media-type guard passes.
A valid empty JSON object still reaches Zod, which rejects it because the update schema requires at least one field.
The neighboring detail GET and DELETE handlers do not use requireJson.

Comment creation in src/routes/comment-routes.ts follows the same pattern.

TypeScript

commentRoutes.post(
  "/",
  requireJson,
  validateRequest({ body: createCommentBodySchema }),
  async (_request, response) => {
    const { params, body } =
      response.locals.validated as {
        params: TicketIdParams;
        body: CreateCommentBody;
      };

    if (!(await userExists(body.authorId))) {
      response.status(400).json({
        error: {
          code: "INVALID_AUTHOR",
          message:
            "authorId does not reference an existing user.",
        },
      });
      return;
    }

    response.status(201).json(
      await createComment(
        params.ticketId,
        body.authorId,
        body.message,
      ),
    );
  },
);

commentRoutes.post(
  "/",
  requireJson,
  validateRequest({ body: createCommentBodySchema }),
  async (_request, response) => {
    const { params, body } =
      response.locals.validated as {
        params: TicketIdParams;
        body: CreateCommentBody;
      };

    if (!(await userExists(body.authorId))) {
      response.status(400).json({
        error: {
          code: "INVALID_AUTHOR",
          message:
            "authorId does not reference an existing user.",
        },
      });
      return;
    }

    response.status(201).json(
      await createComment(
        params.ticketId,
        body.authorId,
        body.message,
      ),
    );
  },
);

The parent ticket router has already validated and preserved params.ticketId.
The child route first enforces JSON, then validates and adds the body to response.locals.validated.
The author existence check remains separate from shape validation.
Listing comments with GET requires no content type because it consumes no body.

In the API Simulator, select:

text

POST /api/tickets

POST /api/tickets

Choose Body, select JSON, and send:

JSON

{
  "title": "Request context composition check",
  "description": "Created with JSON middleware.",
  "priority": "high",
  "requesterId": "usr_customer_1"
}

{
  "title": "Request context composition check",
  "description": "Created with JSON middleware.",
  "priority": "high",
  "requesterId": "usr_customer_1"
}

The request should pass requireJson, reach Zod, and return 201 Created.

Next, switch the body mode to TEXT and set:

text

Content-Type: text/plain

Content-Type: text/plain

Send the same textual content. The response should be:

JSON

{
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Content-Type must be application/json."
  }
}

{
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Content-Type must be application/json."
  }
}

Removing the content-type header should produce the same 415 response.

A GET /api/tickets request should still work without any content-type header because the JSON guard is not mounted there.

The routes in src/routes/async-demo-routes.ts demonstrate two ways an error can reach the final handler.

The first route rejects from an async handler:

TypeScript

asyncDemoRoutes.get("/rejected", async () => {
  await Promise.resolve();
  throw new Error(
    "Rejected async route demonstration",
  );
});

asyncDemoRoutes.get("/rejected", async () => {
  await Promise.resolve();
  throw new Error(
    "Rejected async route demonstration",
  );
});

The handler returns a promise because it is declared async.
Throwing inside the handler rejects that promise.
Express 5 automatically forwards rejected route-handler promises into its error flow.
The handler does not need a manual try/catch whose only purpose is calling next(error).

Requesting:

text

GET /api/async-demo/rejected

GET /api/async-demo/rejected

therefore reaches the final error handler and returns HTTP 500.

The second demonstration uses ordinary synchronous middleware.

TypeScript

asyncDemoRoutes.get(
  "/delegated",
  (_request, _response, next) => {
    next(
      new Error("Explicit next(error) demonstration"),
    );
  },
);

asyncDemoRoutes.get(
  "/delegated",
  (_request, _response, next) => {
    next(
      new Error("Explicit next(error) demonstration"),
    );
  },
);

This handler receives Express’s next function.
Calling next(error) explicitly tells Express to skip normal middleware and enter the error-handling pipeline.
This pattern remains useful when synchronous middleware deliberately delegates an error or callback-based code reports one.

Requesting:

text

GET /api/async-demo/delegated

GET /api/async-demo/delegated

also reaches the final handler and returns 500.

The two requests have the same destination but enter the error flow differently:

text

Async route throws
    → rejected promise
    → Express 5 forwards automatically

Middleware calls next(error)
    → explicit delegation
    → Express error flow

Async route throws
    → rejected promise
    → Express 5 forwards automatically

Middleware calls next(error)
    → explicit delegation
    → Express error flow

The existing final middleware still handles Zod errors separately from unexpected failures.

TypeScript

export const errorHandler: ErrorRequestHandler = (
  error,
  _request,
  response,
  _next,
) => {
  if (error instanceof ZodError) {
    response.status(400).json({
      error: {
        code: "VALIDATION_ERROR",
        message: "Request validation failed.",
        details: error.issues.map((issue) => ({
          path: issue.path.join("."),
          message: issue.message,
        })),
      },
    });
    return;
  }

  console.error("Unhandled request error", error);
  response.status(500).json({
    error: "Internal Server Error",
  });
};

export const errorHandler: ErrorRequestHandler = (
  error,
  _request,
  response,
  _next,
) => {
  if (error instanceof ZodError) {
    response.status(400).json({
      error: {
        code: "VALIDATION_ERROR",
        message: "Request validation failed.",
        details: error.issues.map((issue) => ({
          path: issue.path.join("."),
          message: issue.message,
        })),
      },
    });
    return;
  }

  console.error("Unhandled request error", error);
  response.status(500).json({
    error: "Internal Server Error",
  });
};

Zod failures still become structured 400 VALIDATION_ERROR responses.
Errors from the two demonstration routes are not Zod errors, so they use the generic 500 fallback.
Because requestContext ran before the routes, both error responses also contain the X-Request-Id response header.

Add this request header:

text

X-Request-Id: compose-check-001

X-Request-Id: compose-check-001

Send a valid JSON creation request:

text

POST /api/tickets

POST /api/tickets

Confirm:

HTTP 201 Created
A Location header for the new ticket
X-Request-Id: compose-check-001
A persisted ticket in the response body

Copy the returned ID and send a JSON patch:

text

PATCH /api/tickets/<new-id>

PATCH /api/tickets/<new-id>

JSON

{
  "priority": "high",
  "status": "in_progress"
}

{
  "priority": "high",
  "status": "in_progress"
}

Then resend the patch as text/plain and compare the successful 200 response with the 415 rejection.

Add a nested comment as JSON:

text

POST /api/tickets/<new-id>/comments

POST /api/tickets/<new-id>/comments

JSON

{
  "authorId": "usr_agent_1",
  "message": "Request context reaches nested routes."
}

{
  "authorId": "usr_agent_1",
  "message": "Request context reaches nested routes."
}

Resend it as plain text to confirm the same route-level media-type rule.

Finally, send JSON with invalid fields. Once requireJson accepts the representation, Zod should still return 400 VALIDATION_ERROR.

You’ve added a global request context that gives every request one stable ID and start timestamp. The middleware preserves valid incoming X-Request-Id values, generates UUIDs when necessary, stores context in response.locals, and echoes the identifier in the response.

You also added requireJson at the narrowest useful scope. Ticket creation, ticket updates, and comment creation require JSON, while bodyless GET and DELETE routes remain unaffected. Placing the guard before Zod cleanly separates unsupported representations from invalid JSON data.

Finally, you compared Express 5’s automatic forwarding of rejected async handlers with explicit next(error) delegation. Both paths converge on the final error handler, completing a middleware pipeline that is easier to trace, compose, and extend.