Request Lifecycle
When something goes wrong, the fastest way to find it is to know the order things happen in. This page follows one request from the moment it reaches your app to the moment the response leaves, and names the file you edit for each step.
You don’t need to remember all of it. Read it once, then come back when you wonder “does my middleware run before or after the post is looked up?”.
The whole journey in one picture
Section titled “The whole journey in one picture” node strut serve / npm run dev │ ┌──────────────────▼──────────────────┐ 1 │ bootstrap/app.ts builds the app │ Application.configure(…)…create() └──────────────────┬──────────────────┘ │ first request (or command) ┌──────────────────▼──────────────────┐ 2 │ boot: .env + config/*.ts validated │ every bad variable reported at once 3 │ providers: all register(), then boot()│ bootstrap/providers.ts 4 │ routes compiled and checked │ routes/web.ts, routes/api.ts └──────────────────┬──────────────────┘ │ each request ┌──────────────────▼──────────────────┐ 5 │ global checks: trusted host, │ before any of your code │ maintenance mode, CORS preflight │ 6 │ match the route (404 / 405) │ 7 │ middleware: csrf → signed → auth → │ app/http/middleware │ can → throttle → idempotent, … │ 8 │ route model binding ({post} → Post) │ 404 if not found 9 │ your controller action │ app/http/controllers └──────────────────┬──────────────────┘ │ a Response, or a thrown error 10 ┌──────────────────▼──────────────────┐ │ exception handler → problem+json │ bootstrap/app.ts withExceptions 11 │ security + CORS headers on EVERY │ even on 404s and error pages │ response │ └─────────────────────────────────────┘Steps 1 to 4 happen once per process. Steps 5 to 11 happen for every request.
Step 1: bootstrap/app.ts builds the app
Section titled “Step 1: bootstrap/app.ts builds the app”Everything starts in one file. It’s a single chain that lists your config, providers, routes, middleware and error handling:
import { dirname } from 'node:path'import { Application, type EnvSource } from '@strutvane/framework'import { EnsureAdmin } from '../app/http/middleware/ensure-admin.ts'import { Post } from '../app/models/post.ts'import { config } from '../config/index.ts'import api from '../routes/api.ts'import web from '../routes/web.ts'import { providers } from './providers.ts'
export function createApp(env?: EnvSource): Application { return Application.configure({ basePath: dirname(import.meta.dirname), ...(env === undefined ? {} : { env }) }) .withConfig(config) .withProviders(providers) .withRouting({ web, api, health: '/up', bindings: { post: Post } }) .withMiddleware((middleware) => { middleware.alias({ admin: EnsureAdmin }) middleware.rateLimiter('api', { maxAttempts: 120, decaySeconds: 60 }) }) .withExceptions((exceptions) => exceptions.shouldRenderJsonWhen((ctx) => ctx.wantsJson())) .create()}
export default createApp()Why a function plus a default export? The server and node strut use the default app. Tests call createApp({ APP_ENV: 'testing', … }) to get a fresh app with their own settings, so two tests never share state.
create() does no work: no files are read and no database is opened. That makes importing the app cheap and safe.
Step 2: boot checks your settings
Section titled “Step 2: boot checks your settings”The first request (or the first node strut command) boots the app. Booting starts by reading .env, merging in real environment variables (those win), and running every file in config/.
Every problem is collected and reported together, so you fix them all in one go:
✖ The app can't start: 2 environment variables need attention. - APP_DEBUG must be true or false (got "yes") (read in config/app.ts) - APP_KEY is required (a text value); add it to .env (read in config/app.ts)→ Fix the values in .env (see .env.example for every key) and start again.See Configuration for how config files read .env.
Step 3: providers register, then boot
Section titled “Step 3: providers register, then boot”A service provider is a class that sets up one part of your app: it puts services into the container and adds routes, commands or menu entries. Your providers are listed in bootstrap/providers.ts.
Strutvane calls them in two rounds, exactly like Laravel:
register()on every provider. Only bind things here.boot()on every provider. Now it’s safe to use other services, because everything is registered.
import { ServiceProvider, type Application } from '@strutvane/framework'
export class AppServiceProvider extends ServiceProvider { override register(app: Application): void { // 1st round: bind services }
override boot(app: Application): void { // 2nd round: use services, add menu entries app.navigation.add({ label: 'Posts', route: 'posts.index', order: 10 }) }}More in Service Providers.
Step 4: routes are compiled and checked
Section titled “Step 4: routes are compiled and checked”Strutvane reads routes/web.ts and routes/api.ts, adds the /api prefix to API routes, and then checks every route before any request is served:
| Check | What you’d see if it fails |
|---|---|
| Every middleware alias exists | No middleware is called "auht" (used by GET /api/me). → Did you mean "auth"? |
Every {post:slug} has a model binding |
/api/posts/{post:slug} binds {post:slug}, but no model is bound to "post". |
| Every controller action exists | PostController@publsh doesn't exist (route /api/posts/{post:slug}/publish). |
| Resource controllers have a policy | PostController serves resource routes but has no policy. |
| No two routes share a name or method + path | Two routes are named "posts.show": … |
Why at start-up? Because node strut route:list and your test suite boot the app too. A typo fails there, on your machine, instead of on the first real request in production.
Step 5: global checks, before any of your code
Section titled “Step 5: global checks, before any of your code”Before Strutvane even looks for a route, every request passes three global checks (Laravel calls these “global middleware”):
- Trusted host. The
Hostheader must be one your app serves:APP_URL’s host, pluslocalhost,127.0.0.1and[::1]in local and testing. Anything else is a400 untrusted_host, and the bad host name isn’t echoed back. This stops attacks where a fakeHostends up in a password-reset link. - Maintenance mode. While the app is “down”, requests stop here with a
503(except the health route and people with the bypass cookie). See Maintenance Mode. - CORS preflight. If you switched CORS on for other sites, their browser’s preflight
OPTIONSrequest is answered here.
At the same time the request’s state is worked out once: the real client IP (forwarded headers are believed only from proxies you trust), whether it came over HTTPS, the body size limits, and a fresh CSP nonce (a random value for this response’s inline scripts). Your code reads them as ctx.ip, ctx.nonce and so on.
curl -i http://localhost:3000/up -H "Host: evil.example"What you’ll see:
HTTP/1.1 400 Bad Requestcontent-type: application/problem+json
{"type":"https://strutvane.dev/problems/untrusted_host","title":"Untrusted host","status":400,"code":"untrusted_host","detail":"This server does not answer for the requested host name."}To serve more host names, list them in bootstrap/app.ts: .withMiddleware((m) => m.trustHosts({ at: ['blog.example.com'], subdomains: true })). See Security Features.
Step 6: the route is matched
Section titled “Step 6: the route is matched”For each request, Strutvane finds the route whose method and path match.
- No route has that path: a
404withNothing is at GET /api/postz. - The path exists, but not with that method: a
405, with anAllowheader listing the methods that do work:
curl -i -X DELETE http://localhost:3000/upWhat you’ll see:
HTTP/1.1 405 Method Not Allowedallow: GETcontent-type: application/problem+json
{"type":"https://strutvane.dev/problems/method_not_allowed","title":"Method not allowed","status":405,"code":"method_not_allowed","detail":"DELETE is not supported here. Use GET."}Step 7: middleware runs
Section titled “Step 7: middleware runs”Middleware is code that runs before (and after) your controller, for things every request needs: checking the CSRF token, signing the user in, rate limiting.
Routes in routes/web.ts get the web group (csrf). Routes in routes/api.ts get the api group (csrf, throttle:api). Each route can add more, like auth, and a controller or a wrapped handler can add more again. Strutvane merges all of them for each route at start-up.
Whatever order they’re listed in, the built-in ones always run in this order: csrf → signed → auth → can → throttle → idempotent. Why:
csrffirst: a forged request is refused before anything else happens;signedbeforeauth: a tampered link is a403whoever you are;canafterauth: it needs to know who you are;throttleafterauth: each signed-in user gets their own rate-limit bucket instead of sharing one per IP;idempotentlast: a replayed response never skips the checks before it.
Your own middleware keeps its place in the list. See Middleware.
Step 8: route model binding
Section titled “Step 8: route model binding”If the route has a parameter like {post} or {post:slug}, Strutvane looks up the matching record after middleware has run:
Route.get('/posts/{post:slug}', [PostController, 'show']) // GET /api/posts/hello-world- Found: the controller gets it with
ctx.model(Post). - Not found:
404withNo post matches "hello-world".
Why after middleware? So a guest gets 401 Unauthenticated from auth before they can learn whether a record exists.
Step 9: your controller answers
Section titled “Step 9: your controller answers”Your controller action receives one argument, ctx (the HTTP context: the request, the user, the bound models), and returns a Response:
import { Controller, type HttpContext } from '@strutvane/framework'import { Post } from '../../models/post.ts'
export class PostController extends Controller { show(ctx: HttpContext): Response { return ctx.json({ data: ctx.model(Post) }) }}A new controller object is created for every request, so nothing you store on this can leak from one user’s request into another’s.
Step 10: errors become problem+json
Section titled “Step 10: errors become problem+json”If anything throws (a policy says no, validation fails, or a real bug), the exception handler turns it into a response:
| What was thrown | Logged? | What the client gets |
|---|---|---|
| An HTTP error (401, 403, 404, 422, 429…) | No | application/problem+json with a stable code |
A bug, in local development with APP_DEBUG=true |
Yes | The debug page, or JSON with a debug member |
| A bug, in production | Yes, with a reference id | A plain 500 that quotes the reference id |
See Error Handling.
Step 11: headers on every response
Section titled “Step 11: headers on every response”Last, every response (your JSON, a 404, the debug page, a 500) gets the security headers: a Content-Security-Policy with this request’s nonce, X-Content-Type-Options: nosniff, Referrer-Policy, Permissions-Policy, framing protection, and HSTS in production. If you switched CORS on, the CORS headers are added here too.
This runs outside the exception handler on purpose, so even an error page is protected. You can check it on any route:
curl -i http://localhost:3000/upWhat you’ll see (the headers, shortened):
HTTP/1.1 200 OKcontent-type: application/jsoncontent-security-policy: default-src 'self'; script-src 'nonce-…'; …x-content-type-options: nosniffreferrer-policy: strict-origin-when-cross-originSee Security Features to adjust them.
“The current app”: how helpers find it
Section titled ““The current app”: how helpers find it”Helpers like route(), config() and now() need to know which app they belong to. Strutvane sets the current app around every request and every command, using Node’s AsyncLocalStorage (a way to carry a value through every await of one request, without passing it as an argument).
That’s why:
- two apps in one test file never see each other’s routes or config;
- a helper called at the top level of a file (when it’s imported, before any request) fails with a clear message instead of reading the wrong app.
Outside a request or command (a script, a test), run code inside the app explicitly:
import app from '../bootstrap/app.ts'import { route } from '@strutvane/framework'
await app.boot()const url = app.run(() => route('posts.index'))console.log(url) // → '/api/posts'See Helpers.
After the response: shutdown and deferred work
Section titled “After the response: shutdown and deferred work”When you stop the server with Ctrl+C, node strut serve stops accepting connections, waits for the open ones, then closes the database connection (app.shutdown()), so nothing is cut off halfway.
Calling the app directly (tests)
Section titled “Calling the app directly (tests)”An app is a function from a Request to a Response. Tests don’t need a port or a server:
import { randomBytes } from 'node:crypto'import { expect, test } from 'vitest'import { createApp } from '../../bootstrap/app.ts'
test('the health route answers', async () => { const app = createApp({ APP_ENV: 'testing', APP_KEY: `base64:${randomBytes(32).toString('base64')}`, DB_CONNECTION: 'sqlite' }) const response = await app.handle(new Request('http://localhost/up')) expect(response.status).toBe(200) expect(await response.json()).toEqual({ status: 'ok' })})What you’ll see with npm test: the test passes, and it went through every step on this page: boot, global checks, routing, middleware, your action, and the headers. See Testing.
Console commands follow the same path
Section titled “Console commands follow the same path”node strut route:list boots the app exactly like a request does (steps 1–4), then runs the command instead of a controller. That’s why route:list is a quick way to check that your whole app starts.
node strut route:listCommands that only write files (make:*) skip booting, so they work even before .env exists. See Strut Console.
With Docker, in production, and on Windows
Section titled “With Docker, in production, and on Windows”- With Docker, the same steps run inside the
appcontainer; nothing changes in your code. - In production, boot happens once when the process starts, and the debug page is never shown. With
APP_DEBUG=trueandAPP_ENV=productionthe app refuses to boot unless you pass--force-debug(coming in 0.2; the prototype ignores the flag and logs a warning). - On every operating system, the order is the same; only file paths in error messages look different (
C:\…on Windows).
Common mistakes
Section titled “Common mistakes”“config() was called outside a request”
Section titled ““config() was called outside a request””✖ config() was called outside a request or console command, so there is no current app.→ Call it from a controller, middleware or command, or wrap the code in app.run(() => …) (tests: await app.run(async () => …)).Why: helpers find “the current app” from the request or command that is running. Code at the top level of a file runs when the file is imported, before any request exists.
Fix: call the helper inside a function that runs during a request, or wrap it:
const name = await app.run(() => config('app.name'))“Routes were added after the app booted”
Section titled ““Routes were added after the app booted””✖ Routes were added after the app booted, so they would never be matched.→ Call app.addRoutes() in a provider's register() method.Why: routes are compiled once, during boot (step 4).
Fix: move the app.addRoutes(...) call from boot() to register().
“My controller returned nothing”
Section titled ““My controller returned nothing””PostController@show returned nothing instead of a Response.→ Return ctx.json(...), ctx.html(...) or ctx.noContent().Fix: add return in front of ctx.json(...).
Every request answers 400 “Untrusted host”
Section titled “Every request answers 400 “Untrusted host””{"type":"https://strutvane.dev/problems/untrusted_host","title":"Untrusted host","status":400,"code":"untrusted_host","detail":"This server does not answer for the requested host name."}Why: the request’s host name isn’t APP_URL’s host (or a loopback name in development). It happens when you open the app under a new domain, or behind a proxy that changes the host.
Fix: set APP_URL to the address people use, or allow more names in bootstrap/app.ts:
.withMiddleware((middleware) => { middleware.trustHosts({ at: ['blog.example.com'], subdomains: true })})Behind a load balancer, also tell Strutvane which proxies to believe: middleware.trustProxies({ at: ['10.0.0.0/8'] }).
“… was used before the app booted”
Section titled ““… was used before the app booted””✖ app.routes was used before the app booted.→ Call `await app.boot()` first (requests and commands do it for you).Why: a script or test read app.routes, app.config or app.url on an app that hasn’t booted yet.
Fix: await app.boot() first. Requests (app.handle()) and node strut commands boot for you.
Next steps
Section titled “Next steps”- Service Providers: what goes in
register()andboot(). - Routing: define the routes from step 4.
- Middleware: write your own step 6.