Skip to main content

Request Lifecycle & Handlers

OpenAPIBackend defines a rich set of hooks to intercept and control each step of the request lifecycle. Each handler receives the parsed Context object as the first argument, followed by any arguments passed to .handleRequest(), such as Express req, res, and next.

Built-in Lifecycle Handlers​

These can be registered to hook into specific steps.

preRoutingHandler​

Called before routing, after parsing the request. Can be used for logging, metrics, or overriding routing behavior.

api.register("preRoutingHandler", (c, req, res) => {
  console.log("Request received", req.method, req.url);
});

postRoutingHandler​

Called after routing, regardless of match success. Useful for metrics or auditing.

api.register("postRoutingHandler", (c, req, res) => {
  console.log("Matched operation:", c.operation?.operationId);
});

postSecurityHandler​

Called after all security handlers have run.

api.register("postSecurityHandler", (c, req, res) => {
  if (!c.security.authorized) console.warn("Unauthorized access attempt");
});

preOperationHandler​

Called right before the operation handler. Can be used for setting response headers, request mutation, etc.

api.register("preOperationHandler", (c, req, res) => {
  res.setHeader("x-trace-id", generateTraceId());
});

postResponseHandler​

Called after the main operation handler. You can use this to validate responses or mutate them.

api.register("postResponseHandler", (c, req, res) => {
  const result = c.api.validateResponse(c.response, c.operation);
  if (result.errors) {
    return res
      .status(500)
      .json({ error: "Invalid response", details: result.errors });
  }
  return res.send(c.response);
});

Error Handlers​

notFound​

Called if the path doesn't match any operation.

api.register("notFound", (c, req, res) => {
  res.status(404).json({ error: "Route not found" });
});

methodNotAllowed​

Called if the path matches but the method doesn't.

api.register("methodNotAllowed", (c, req, res) => {
  res.status(405).json({ error: "Method not allowed" });
});

notImplemented​

Called if the operation is matched but no handler is registered.

api.register("notImplemented", (c, req, res) => {
  res.status(501).json({ error: "Not implemented" });
});

unauthorizedHandler​

Called if the request does not satisfy OpenAPI security requirements.

api.register("unauthorizedHandler", (c, req, res) => {
  res.status(401).json({ error: "Unauthorized" });
});

validationFail​

Called if the request validation fails.

api.register("validationFail", (c, req, res) => {
  res
    .status(400)
    .json({ error: "Validation failed", details: c.validation.errors });
});