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.

Context

View as Markdownllms.txt

When a request comes in, many small pieces of code run for it: middleware, your controller, a model, a helper, a log call. They all need to know a few things about this request (which app, which user, which team, its request id) without you passing them from function to function. Context is that shared, per-request information.

Strutvane keeps it in Node’s AsyncLocalStorage: a built-in way to attach a value to one request, so that it follows the code across every await, and two requests running at the same time never see each other’s value.

You already use context every time you call a helper:

app/http/controllers/home.controller.ts
import { config, Controller, type HttpContext } from '@strutvane/framework'
export class HomeController extends Controller {
async index(ctx: HttpContext): Promise<Response> {
await new Promise((resolve) => setTimeout(resolve, 10)) // any await…
return ctx.json({ app: config('app.name') }) // …still knows which app this is
}
}

What you’ll see: { "app": "My App" }. config() found the app through the context, after an await, with no app object passed in.

Value Set by Used by
The current app (container, config, URLs) Strutvane, around every request and command config(), route(), now(), app(), models, facades
The request id Strutvane, for every request every log line of the request, error reports
The signed-in user the auth middleware every log line (as an id), policies
The current team tenancy, when teams are on the ORM tenant scope, every log line
Your own values you, with Context.add() every log line, and queued jobs from 0.3

Values that are about the request itself (the body, the bound models, the route) live on ctx, the request object every action receives. Context is for what all code should know without being handed ctx.

Every log line written during a request carries its context, so you can find everything one request did:

import { Log } from '@strutvane/framework'
Log.info('Post published', { postId: 42 })

What you’ll see in storage/logs/strutvane-2026-11-15.log:

[2026-11-15 10:22:01.123] local.INFO: Post published {"postId":42,"requestId":"01JD7Q6Y9X3V2K8M4N5P6R7S8T","userId":1}

Add your own value for the rest of the request with Log.withContext():

Log.withContext({ orderId: 'ord_123' })
Log.info('Charging the card') // context: { orderId: 'ord_123', requestId: … }

Secrets are redacted from context like from everything else that’s logged. See Logging.

app/http/middleware/add-plan-context.ts
import { Context, type HttpContext, type Middleware, type Next } from '@strutvane/framework'
export class AddPlanContext implements Middleware {
async handle(ctx: HttpContext, next: Next): Promise<Response> {
Context.add('plan', ctx.user === null ? 'guest' : 'pro')
return next()
}
}

Anywhere later in the same request:

Context.get('plan') // → 'pro'

Some values are useful to code but must never reach a log file: an internal key, a customer’s account number.

Context.addHidden('partnerAccount', account.number)
Context.getHidden('partnerAccount') // available to your code, never written to logs

When a request dispatches a job, its context (request id, user, team and your own values, hidden ones included) is saved with the job and restored when a worker runs it. So the job’s log lines carry the same request id as the request that queued it, and the job runs inside the same team. Code that runs work on other threads (Concurrency.run) passes the team and request context along explicitly for the same reason (Concurrency).

A standalone script or a test isn’t a request, so there’s no context until you create one. Helpers then stop with a clear message:

✖ 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 () => …)).

Wrap the code in app.run(), which sets the context for everything inside it:

tests/feature/context.test.ts
import { randomBytes } from 'node:crypto'
import { expect, test } from 'vitest'
import { config } from '@strutvane/framework'
import { createApp } from '../../bootstrap/app.ts'
test('code inside app.run() sees the app', async () => {
const app = createApp({ APP_ENV: 'testing', APP_KEY: `base64:${randomBytes(32).toString('base64')}`, APP_NAME: 'Test App', DB_CONNECTION: 'sqlite' })
await app.boot()
expect(await app.run(async () => config('app.name'))).toBe('Test App')
})

node strut commands get a context automatically, like requests.

A global “current user” works when one process handles one request (PHP). A Node server handles many requests at the same time: while request A waits for the database, request B runs. A global would let B overwrite A’s user mid-request. AsyncLocalStorage gives each request its own value, carried across every await, and it’s also why two apps in one test file never see each other.

“… was called outside a request or console command”

Section titled ““… was called outside a request or console command””

Why: the code ran at the top level of a file (when it was imported), in a setTimeout started before the request, or in a script. Fix: move it into a function that runs during a request, or wrap it in app.run(() => …).

My log lines from a background callback have no request id

Section titled “My log lines from a background callback have no request id”

Why: work started outside the request (for example from a timer created at start-up) has no request context. Fix: do the work inside the request, or queue a job (from 0.3 it carries the context).

I put the user’s password in the context

Section titled “I put the user’s password in the context”

Why: context values are written to every log line of the request. Fix: never put secrets in context; use hidden context for values code needs but logs must not show.