Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Requests

View as Markdownllms.txt

Every controller action, middleware and closure route receives one argument: ctx, the HTTP context. It holds everything about the current request: the URL, the parameters, the body, the headers, the signed-in user and the records found by route model binding.

routes/api.ts
Route.get('/echo/{word}', (ctx) =>
ctx.json({ word: ctx.param('word'), shout: ctx.query.get('shout') === 'yes', method: ctx.method }),
),
Terminal window
curl "http://localhost:3000/api/echo/hello?shout=yes"

What you’ll see:

{ "word": "hello", "shout": true, "method": "GET" }
Property or method Type What it is
ctx.request Request The raw Web-standard request
ctx.url URL The parsed URL
ctx.method string GET, POST… (upper case)
ctx.query URLSearchParams The query string
ctx.params Record<string, string> All path parameters, as text
ctx.param(name) string One path parameter
ctx.body(limit?) Promise<unknown> The JSON body, parsed once
ctx.user your user type | null The signed-in user, or null
ctx.requireUser() your user type The user, or a 401
ctx.model(Post) Post The record bound from the route
ctx.wantsJson() boolean Does the client want JSON?
ctx.ip string The client address
ctx.route { name, method, uri, action } The matched route
Route.get('/reports/{year}/{month}', (ctx) =>
ctx.json({ year: Number(ctx.param('year')), month: Number(ctx.param('month')) }),
),

GET /api/reports/2026/11 → { "year": 2026, "month": 11 }.

Parameters are always text: convert them yourself (Number(...)). Asking for a parameter the route doesn’t have is a programming mistake, so it throws (see Common mistakes).

ctx.query is a standard URLSearchParams:

const page = Number(ctx.query.get('page') ?? '1') // ?page=2 → 2
const tags = ctx.query.getAll('tag') // ?tag=a&tag=b → ['a', 'b']
const hasDrafts = ctx.query.has('drafts') // ?drafts → true

Read any header from the raw request:

const version = ctx.request.headers.get('x-client-version') // string | null

Header names are case-insensitive.

app/http/controllers/note.controller.ts
import { Controller, type HttpContext } from '@strutvane/framework'
export class NoteController extends Controller {
async store(ctx: HttpContext): Promise<Response> {
const body = await ctx.body() // unknown: validate before you trust it
return ctx.json({ received: body }, 201)
}
}
Terminal window
curl -X POST http://localhost:3000/api/notes \
-H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
-d '{"text":"Buy milk"}'

What you’ll see:

{ "received": { "text": "Buy milk" } }

The body is typed unknown on purpose: it came from outside. Use a form request to turn it into checked, typed values. Calling ctx.body() twice is fine; it’s parsed once and cached.

ctx.body() refuses bad bodies with a clear problem+json response:

Problem Status code detail
Content-Type isn’t application/json 415 unsupported_media_type Send the body as JSON with "Content-Type: application/json".
The JSON doesn’t parse 400 invalid_json The request body is not valid JSON. Check for trailing commas and unquoted keys.
Bigger than 1 MiB 413 payload_too_large The body is larger than 1048576 bytes.
Nested more than 32 levels deep 413 json_too_deep The JSON is nested 40 levels deep; the limit is 32.
More than 1,000 keys in total 413 json_too_many_keys The JSON has 1500 keys; the limit is 1000.
A __proto__ key (a known attack) 400 forbidden_json_key The JSON contains a "__proto__" key, which is never accepted.

The size limit holds even when Content-Length is missing or lies: bytes are counted as they arrive, and reading stops at the limit. Allow a bigger body on one action by passing a limit in bytes:

const body = await ctx.body(5 * 1024 * 1024) // up to 5 MiB here

Or change the limits for the whole app:

bootstrap/app.ts
.withMiddleware((middleware) => {
middleware.limits({ maxBytes: 5 * 1024 * 1024, maxDepth: 64, maxKeys: 5000 })
})

Why such limits? A huge or deeply nested body can tie up the server for seconds; these limits make that impossible, and the __proto__ check stops prototype pollution (a trick that changes every object in your app through one crafted key).

Never use the raw body directly. A form request is a small class that says what a valid body looks like, and turns unknown into typed, checked values (or a 422 listing every problem):

app/http/requests/note.request.ts
import { z } from 'zod'
import { FormRequest, type StandardSchema } from '@strutvane/framework'
const schema = z.object({ text: z.string().trim().min(1).max(500) })
export class StoreNoteRequest extends FormRequest<z.infer<typeof schema>> {
rules(): StandardSchema<z.infer<typeof schema>> {
return schema
}
}
app/http/controllers/note.controller.ts
import { Controller, type HttpContext } from '@strutvane/framework'
import { StoreNoteRequest } from '../requests/note.request.ts'
export class NoteController extends Controller {
async store(ctx: HttpContext): Promise<Response> {
const input = await new StoreNoteRequest().validate(ctx) // { text: string }
return ctx.json({ data: input }, 201)
}
}

What you’ll see for {"text":"","pinned":true}: a 422 with one issue for text; once text is valid, pinned is refused as an unknown_field, because fields the schema doesn’t list are rejected (Laravel only does that when you ask). A form request can also say who may send it (authorize(ctx)) and tidy input first (prepareForValidation). Every option is on Validation.

Read Gives you
ctx.cookie('theme') One cookie’s value, or undefined (a malformed value is returned as-is, never a 500)
ctx.sessionId() The session cookie’s id, or undefined. Always undefined when the request carries a Bearer token: a token request is never also a cookie session
ctx.method 'GET', 'POST'… (upper case)
ctx.url The full URL, parsed (ctx.url.pathname, ctx.url.searchParams)
ctx.params Every path parameter as text, before model binding
ctx.route The matched route: { name, method, uri, action }, for logging
ctx.nonce This response’s CSP nonce, for inline <script nonce="…">
ctx.request The raw Web-standard Request, when you need something else

The signed-in user: ctx.user and ctx.requireUser()

Section titled “The signed-in user: ctx.user and ctx.requireUser()”

The auth middleware sets ctx.user. On routes without auth (or with auth:optional), it can be null:

Route.get('/greeting', (ctx) =>
ctx.json({ message: ctx.user === null ? 'Hello, guest' : `Hello, ${ctx.user.name}` }),
).middleware('auth:optional'),

ctx.requireUser() returns the user, or stops the request with 401 when nobody is signed in. Use it in actions that only make sense with a user:

const author = ctx.requireUser() // typed as your user model, never null

ctx.user is typed as your user model, so ctx.user?.is_admin is checked by the compiler. New apps declare it once in bootstrap/app.ts:

bootstrap/app.ts
declare module '@strutvane/framework' {
interface UserRegistry { user: Author }
}

When a route has {post} and post is bound to Post in withRouting({ bindings }), the record is looked up before your action runs:

show(ctx: HttpContext): Response {
const post = ctx.model(Post) // typed as Post; a missing post was already a 404
return ctx.json({ data: post })
}

With two models in one path, pass the parameter name:

// /authors/{author}/posts/{post}
const author = ctx.model(Author, 'author')
const post = ctx.model(Post, 'post')

Does the client want JSON? ctx.wantsJson()

Section titled “Does the client want JSON? ctx.wantsJson()”

true for any /api/... path, or when the Accept header mentions JSON. The error handler uses it to choose between a problem+json body and a small HTML error page; you can use it too:

return ctx.wantsJson() ? ctx.json({ data: post }) : ctx.html(`<h1>${post.title}</h1>`)

ctx.ip is the address the server saw on the connection. Headers like X-Forwarded-For are not trusted by default, because any client can send them.

Behind a load balancer or reverse proxy, the connection comes from the proxy, so every user would share its address (and one rate-limit bucket). Tell Strutvane which proxies to believe:

bootstrap/app.ts
.withMiddleware((middleware) => {
middleware.trustProxies({ at: ['10.0.0.0/8'] }) // your load balancer's network
})

What you’ll see: for requests that arrive from those addresses, ctx.ip becomes the real client from X-Forwarded-For, and HTTPS and the host are read from X-Forwarded-Proto and X-Forwarded-Host. The same header from anyone else is still ignored. See Security Features.

“The route … has no {…} parameter”

Section titled ““The route … has no {…} parameter””
Error: The route "/api/posts/{post:slug}" has no {id} parameter. Parameters here: post.

Why: the name in ctx.param() doesn’t match the name in the route path.

Fix: use the name from the path: ctx.param('post').

Error: No Post is bound on route "/api/posts/{slug}" (bound parameters: none). Add {post} to the route path and register the model in withRouting({ bindings }).

Fix: name the parameter after the binding ({post} or {post:slug}) and register bindings: { post: Post }.

{ "status": 415, "code": "unsupported_media_type", "detail": "Send the body as JSON with \"Content-Type: application/json\"." }

Fix: send JSON with the header Content-Type: application/json.

Why: the route has no auth (or auth:optional) middleware, so nobody signs the user in.

Fix: .middleware('auth') on the route.

Why: the body nests deeper than 32 levels or has more than 1,000 keys, the default limits. Fix: raise them for the app (middleware.limits({ maxDepth: 64, maxKeys: 20000 })), or better, send big imports as a file upload or in batches.

Everyone has the same ctx.ip in production

Section titled “Everyone has the same ctx.ip in production”

Why: the app runs behind a proxy and every connection comes from it. Fix: middleware.trustProxies({ at: ['<your proxy network>'] }) in bootstrap/app.ts.

Why: in PowerShell and cmd, single quotes don’t protect the JSON like they do in bash, so the quotes inside it get lost. Fix: use curl.exe and escape the inner quotes, or put the body in a file:

Terminal window
'{"text":"Buy milk"}' | Out-File -Encoding utf8 body.json
curl.exe -X POST http://localhost:3000/api/notes -H "Content-Type: application/json" --data-binary "@body.json"