HttpContext

HttpContext is the execution context passed to every HTTP operation handler. It provides decoded and validated access to all parts of the incoming request — path parameters, query parameters, headers, cookies, and the request body — and exposes the raw Node.js request/response objects for cases that require lower-level control.

Package: @opra/http

---

Properties

Property	Type	Description
request	HttpIncoming	The incoming HTTP request. → See HttpIncoming
response	HttpOutgoing	The outgoing HTTP response. → See HttpOutgoing
pathParams	Record<string, any>	Decoded path parameters, keyed by the name declared in .PathParam().
queryParams	Record<string, any>	Decoded query string parameters, keyed by the name declared in .QueryParam().
headers	Record<string, any>	Decoded request headers, keyed by the name declared in .Header().
cookies	Record<string, any>	Decoded cookies, keyed by the name declared in .Cookie().
errors	Error[]	Accumulated errors during request processing. The adapter checks this after the handler returns.
mediaType	HttpMediaType | undefined	The matched request content type definition, derived from the .RequestContent() declaration.
isMultipart	boolean	true when the request Content-Type is multipart/*.

note

pathParams, queryParams, headers, and cookies only contain parameters explicitly declared on the controller or operation. Use ctx.request to access undeclared values from the raw request.

---

Methods

getBody<T>()

getBody<T>(args?: { toFile: boolean | string }): Promise<T>

Reads, parses, and validates the request body. The body is cached — calling getBody() multiple times returns the same decoded value.

Supported content types out of the box: application/json, application/yaml, application/toml, text/plain, and binary. The actual decode is driven by the type declared in .RequestContent().

Parameter	Type	Description
args.toFile	boolean | string	Save the raw body to a temp file instead of buffering in memory. Pass true for an auto-named file or a string for a specific path.

// JSON body — decoded against the declared RequestContent type
const body = await ctx.getBody<Customer>();

// Save a large binary upload to a temp file
const file = await ctx.getBody<LocalFile>({ toFile: true });

Throws BadRequestError if parsing or validation fails.

---

getMultipartReader()

getMultipartReader(): Promise<MultipartReader>

Returns a MultipartReader for streaming a multipart/form-data request. The same instance is returned on repeated calls.

if (ctx.isMultipart) {
  const reader = await ctx.getMultipartReader();
  const parts  = await reader.getAll();
}

Throws InternalServerError if the request is not multipart.
Throws NotAcceptableError if the operation does not declare .MultipartContent().

---

info

ctx.request is an HttpIncoming — a Node.js IncomingMessage extended with Express-compatible helpers for headers, content negotiation, and body reading.

ctx.response is an HttpOutgoing — a Node.js ServerResponse extended with Express-compatible helpers for cookies, redirects, and response status. In most OPRA handlers you return a value instead of writing to the response directly.