Context
Every request is wrapped in a Context object (c in the examples) passed to each middleware and handler. It exposes the request, the response and utility methods for HTTP, SSE and WebSocket upgrades.
µWebSockets.js invalidates its native request object as soon as a handler awaits. Mousse snapshots everything at construction, so all the accessors below stay safe to use after any await.
Request
| Member | Description |
|---|---|
c.method() |
Actual HTTP method of the request ('get', 'post'...) |
c.url |
Request URL path |
c.route |
Pattern of the matched route (e.g. /users/:id) |
c.headers |
All request headers, lowercased keys |
c.getHeader(name) |
Single header value, null when absent |
c.contentType() |
Shortcut for the content-type header |
c.params |
Route parameters record |
c.param(name) |
Single route parameter |
c.query |
Parsed query string |
c.ip |
Client address. Behind trusted proxies, the first x-forwarded-for hop from the right that is not one of them |
c.ips |
Addresses from the client to the socket peer, trusted proxies in between |
c.protocol |
'http' / 'https', from x-forwarded-proto when the peer is a trusted proxy |
c.host |
Requested host, from x-forwarded-host when the peer is a trusted proxy |
c.body() |
Parsed request body (see below) |
c.body(true) |
Raw body as a Buffer, null when the method carries no body |
c.request |
The underlying µWS request — only valid before the first await |
Body
c.body() is async and cached: reading it twice returns the same value. Mousse starts consuming the body stream as soon as the request arrives, so it is safe to read it late, after other async work:
app.post('/items', async (c) => {
await someAsyncCheck();
const body = await c.body(); // still complete
});Parsing is delegated to the route's BodyParser. The default one understands application/json, application/x-www-form-urlencoded and multipart/form-data, and falls back to the raw Buffer for other content types. Bodies are only consumed for post, put, patch and delete requests.
Bodies are limited to 1 MiB by default, configurable with the bodyLimit route or router option (bytes). A declared content-length above the limit is answered 413 before any middleware runs. A body exceeding it while being received (lying content-length, chunked upload) makes c.body() throw a PayloadTooLargeError, answered 413. Extra chunks are dropped, never buffered.
Query string
c.query parses ?a=1&tags[]=x&tags[]=y into { a: '1', tags: ['x', 'y'] }. Repeated keys become arrays, + decodes to a space, and keys suffixed with [] are stripped.
Response
All response methods return the context, so they chain:
c.status(201).header('x-request-id', id).json({ ok: true });| Member | Description |
|---|---|
c.status(code, message?) |
Set the response status |
c.statusCode |
Current status code |
c.header(name, value) / c.header({...}) |
Set one or several response headers, replacing previous values. An array value is written as one header line per entry |
c.appendHeader(name, value) |
Add a value without replacing the previous ones (e.g. several set-cookie) |
c.type(extOrFilename) |
Set content-type from a file extension (c.type('json')) |
c.respond(body?) |
End the response with an optional string/Buffer body |
c.json(body, status?) |
Serialize through the route's ResponseSerializer and respond as application/json |
c.html(body, status?) |
Respond as text/html |
c.file(path) |
Stream a file with its content type and backpressure handling. 404 when missing or not a regular file, 500 on other errors. The path is used as-is: never build it from unsanitized request data |
c.redirect(url) |
302 redirect |
c.ended |
true once the response has been sent (or the request aborted) |
Calling any respond method after the response ended is a no-op — never an error. All writes are corked as required by µWebSockets.js.
Other
| Member | Description |
|---|---|
c.log(data) |
Forward to the route's Logger, no-op when none is set |
c.onAbort(listener) |
Called if the client goes away before the response ended (long polling, SSE) |
c.aborted |
true once the client went away before the response ended |
c.mousse |
The Mousse instance that created the context |
c.response |
The underlying µWS response, for advanced use |
SSE members (sustain, send, ping) are documented in Server-Sent Events. WebSocket route handlers receive a different, already-connected WSContext — the HTTP Context described here is what ws middlewares get during the upgrade request; see WebSockets.