Request Composables

The request composables provide various functions to interact with the incoming HTTP request in a Wooks HTTP application. These functions allow you to access different aspects of the request, such as headers, query parameters, cookies, authorization headers, and more.

Content

• Content
• Raw Request Instance
• URI Parameters
• Query Parameters
• Method and Headers
• Cookies
• Authorization
• Body Size Limits
  • App-level configuration
  • Per-request overrides
• Body Parser

Raw Request Instance

To get a reference to the raw request instance, you can use the useRequest composable function. However, in most cases, you won't need to directly access the raw request instance unless you're developing a new feature or require low-level control over the request.

import { useRequest } from '@wooksjs/event-http'
// cjs:
// const { useRequest } = require('@wooksjs/event-http')

app.get('/test', () => {
    const { rawRequest } = useRequest()
    // Access the raw request instance if needed
})

URI Parameters

URI parameters are automatically parsed by the router and are covered in the Retrieving URI Parameters section.

Query Parameters

The useSearchParams composable provides three functions for working with query parameters:

• urlSearchParams() — returns an instance of WooksURLSearchParams, which extends the standard URLSearchParams with a toJson method that returns a JSON object of the query parameters.
• jsonSearchParams() — is a shortcut for urlSearchParams().toJson(), returning the query parameters as a JSON object.
• rawSearchParams() — returns the raw search parameter string, such as ?param1=value&....

import { useSearchParams } from '@wooksjs/event-http'

app.get('hello', () => {
    const { urlSearchParams, jsonSearchParams, rawSearchParams } =
        useSearchParams()

    // curl http://localhost:3000/hello?name=World
    console.log(jsonSearchParams()) // { name: 'World' }
    console.log(rawSearchParams()) // ?name=World

    return `Hello ${urlSearchParams().get('name')}!`
})

Example usage with cURL:

curl http://localhost:3000/hello?name=World
# Hello World!

Method and Headers

The useRequest composable provides additional shortcuts for accessing useful data related to the request, such as the URL, method, headers, and the raw request body.

import { useRequest } from '@wooksjs/event-http'

app.get('/test', async () => {
    const {
        url, // Request URL (string)
        method, // Request method (string)
        headers, // Request headers (object)
        rawBody, // Request body (() => Promise<Buffer>)
    } = useRequest()

    const body = await rawBody() // Body as a Buffer
})

Cookies

Cookies are not automatically parsed unless requested. The useCookies composable function provides a cookie getter and access to the raw cookies string.

import { useCookies } from '@wooksjs/event-http'

app.get('/test', async () => {
    const {
        rawCookies, // Raw "cookie" from headers (string | undefined)
        getCookie, // Cookie getter ((name) => string | null)
    } = useCookies()

    console.log(getCookie('session'))
    // Prints the value of the cookie with the name "session"
})

Authorization

The useAuthorization function provides helpers for working with authorization headers:

import { useAuthorization } from '@wooksjs/event-http'

app.get('/test', async () => {
    const {
        authorization, // The raw value of the "authorization" header (string)
        authType, // The authentication type (Bearer/Basic) (string)
        authRawCredentials, // The authentication credentials that follow the auth type (string)
        isBasic, // Returns true if authType === 'Basic' (() => boolean)
        isBearer, // Returns true if authType === 'Bearer' (() => boolean)
        basicCredentials, // Parsed basic auth credentials (() => { username: string, password: string })
    } = useAuthorization()

    if (isBasic()) {
        const { username, password } = basicCredentials()
        console.log({ username, password })
    } else if (isBearer()) {
        const token = authRawCredentials
        console.log({ token })
    } else {
        // Unknown or empty authorization header
    }
})

Body Size Limits

Request body reading is protected by configurable limits:

Limit	Default	Description
maxCompressed	1 MB	Max compressed body size in bytes
maxInflated	10 MB	Max decompressed body size in bytes
maxRatio	100	Max compression ratio (zip-bomb protection)
readTimeoutMs	10 000 ms	Body read timeout

App-level configuration

import { createHttpApp } from '@wooksjs/event-http'

const app = createHttpApp({
    requestLimits: {
        maxCompressed: 50 * 1024 * 1024,  // 50 MB
        maxInflated: 100 * 1024 * 1024,   // 100 MB
        maxRatio: 200,
        readTimeoutMs: 30_000,
    },
})

Per-request overrides

Override limits inside a handler before reading the body:

import { useRequest } from '@wooksjs/event-http'

app.post('/upload', async () => {
    const {
        setMaxCompressed,
        setMaxInflated,
        setMaxRatio,
        setReadTimeoutMs,
        rawBody,
    } = useRequest()

    // Raise limits for this route only
    setMaxCompressed(50 * 1024 * 1024)  // 50 MB
    setMaxInflated(100 * 1024 * 1024)   // 100 MB

    const body = await rawBody()
    return { size: body.length }
})

Per-request setters use copy-on-write — they do not mutate the app-level configuration.

Body Parser

The implementation of the body parser is isolated into a separate package called @wooksjs/http-body. For more details on using the body parser, refer to the Body Parser section.