# Velocity Documentation

> Velocity is a full-stack Go web framework with unified API, driver-based architecture, and zero configuration lock-in. Build faster, ship sooner.

Source repository: https://github.com/velocitykode/velocity
Live docs: https://vel.build/docs/
Lean index: https://vel.build/llms.txt

================================================================================
# Getting Started

Source: https://vel.build/docs/getting-started/getting-started/
Section: Getting Started
Summary: Install Velocity CLI, create your first Go web application, and run the development server with hot reload.


## Installation

### Prerequisites

- Go 1.26 or higher
- Node.js 18+ (for frontend assets)
- Git

### Install the Velocity CLI




```bash
brew tap velocitykode/tap
brew install velocity
```



```bash
go install github.com/velocitykode/velocity-cli@latest
```




Verify the installation:

```bash
velocity --version
```

## Creating Your First Project

Create a new Velocity application:

```bash
velocity new myapp
```

This creates a new project and automatically starts the development servers. Your application will be available at:


Building an API without a frontend? Use `velocity new myapi --api` to create an API-only project. See the [Installer Commands](/docs/cli/installer/) page for the full `velocity new` flag reference.


- **Go server**: http://localhost:4000
- **Vite dev server**: http://localhost:5173

### Project Structure

```
myapp/
├── internal/
│   ├── app/             # app.Bootstrap: middleware, modules, event listeners
│   ├── handlers/        # HTTP handlers
│   ├── middleware/      # Custom middleware
│   └── models/          # Database models
├── config/              # Configuration files
├── database/
│   └── migrations/      # Database migrations
├── public/              # Static assets
├── resources/
│   ├── js/              # JavaScript/React files
│   ├── css/             # Stylesheets
│   └── views/           # Root HTML template (Inertia)
├── routes/              # Route definitions
├── storage/
│   └── logs/            # Application logs
├── .env                 # Environment variables
├── go.mod               # Go module file
├── package.json         # Node.js dependencies (full-stack only)
├── vite.config.ts       # Vite configuration
└── main.go              # Application entry point
```

## Quick Start Example

Here's what the generated `main.go` looks like:

```go
package main

import (
    "log"

    "myapp/internal/app"
    "myapp/routes"

    "github.com/velocitykode/velocity"
)

func main() {
    v, err := velocity.New()
    if err != nil {
        log.Fatal(err)
    }

    if err := app.Bootstrap(v); err != nil {
        log.Fatal(err)
    }

    routes.Register(v)

    if err := v.Serve(); err != nil {
        log.Fatal(err)
    }
}
```

`velocity.New()` builds the application container (logger, crypto, DB,
cache, queue, router, …) and returns an `*velocity.App`.
`app.Bootstrap(v)` is your own bootstrap function (scaffolded into
`internal/app`) where you configure middleware, modules, and event
listeners. `routes.Register(v)` registers your routes against
`v.Router`, and `v.Serve()` starts the HTTP server.


`*velocity.App` also exposes a fluent bootstrap chain -
`v.Modules(...)`, `v.Middleware(...)`, `v.Routes(...)`,
`v.Events(...)`, `v.Schedule(...)`, `v.Commands(...)`, and
`v.Exceptions(...)` - if you prefer to wire everything from `main.go`.
Call `v.Run()` to dispatch a `vel ...` command from `os.Args`, or
`v.Serve()` to start the server.


Define routes in `routes/web.go`:

```go
package routes

import (
    "myapp/internal/handlers"

    "github.com/velocitykode/velocity"
)

func Register(v *velocity.App) {
    r := v.Router

    r.Get("/", handlers.Home)
}
```

Handlers have the signature `func(ctx *router.Context) error`:

```go
package handlers

import (
    "github.com/velocitykode/velocity/router"
)

func Home(ctx *router.Context) error {
    return ctx.String(200, "Welcome to Velocity!")
}
```

See [Routing](/docs/core/routing) for groups, middleware stacks, API
routes, and the full reference.

## Development Server

Start the development server with hot reload:

```bash
vel serve
```

The development server includes:
- **Hot Reload**: Automatically restarts when Go files change
- **Error Pages**: Detailed error messages with stack traces
- **Request Logging**: Logs all requests and responses

### Serve Options

```bash
# Custom port
vel serve --port 8080

# Disable hot reload
vel serve --no-watch

# Specify environment
vel serve --env production
```

## Building for Production

Create an optimized production build:

```bash
vel build
```

This produces a single binary with:
- Stripped debug symbols for smaller size
- Static linking for portability
- Ready for deployment

### Build Options

```bash
# Custom output path
vel build --output ./bin/myapp

# Cross-compile for Linux
vel build --os linux --arch amd64

# Build with Go build tags
vel build --tags prod
```

## Configuration

### Environment Variables

Velocity uses `.env` files for configuration. The installer writes a
full `.env` with random keys; the most commonly edited values:

```bash
APP_NAME=MyApp
APP_ENV=development
APP_URL=http://localhost:4000
APP_PORT=4000

# Logging
LOG_DRIVER=console      # console, file
LOG_LEVEL=debug

# Encryption / signing - installer populates these at scaffold time
APP_KEY=
QUEUE_SIGNING_KEY=
AUTH_JWT_SECRET=
CRYPTO_CIPHER=AES-256-GCM

# Database
DB_CONNECTION=sqlite    # postgres, mysql, sqlite
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=database.sqlite
DB_USERNAME=
DB_PASSWORD=

# Cache
CACHE_DRIVER=memory     # memory, file, redis, database
```

`APP_KEY` doubles as the crypto key. Set `CRYPTO_KEY` explicitly only
if you want a dedicated encryption key separate from the app key.

### Regenerating the application key

```bash
vel key generate
```

This generates a fresh 32-byte key, base64-encodes it with a `base64:`
prefix, and writes it to `APP_KEY` in `.env` (creating the file if it
doesn't exist) - useful if you need to rotate the key or the installer
didn't run `key generate` for you.

## Next Steps

- [CLI Reference](/docs/cli/) - Full CLI command documentation
- [Routing](/docs/core/routing/) - Learn about routing and middleware
- [Database](/docs/database/) - Set up database connections and models
- [Frontend](/docs/frontend/) - Configure Vite and Inertia.js


================================================================================
# Standalone Packages

Source: https://vel.build/docs/getting-started/standalone/
Section: Getting Started
Summary: Cherry-pick individual Velocity components. Import a single subsystem, construct its Manager directly, and own the lifecycle without velocity.New().


Velocity is a single Go module, but its subsystems are designed as
independent packages. You do not have to call `velocity.New()` to use
them. Import the one package you need (cache, crypto, validation,
httpclient, str, log, pipeline, collect, async), construct it directly,
and own its lifecycle yourself. This is ideal for libraries, CLIs,
one-off scripts, tests, and MCP servers that want Velocity's helpers
without booting a full HTTP application.

## Install

Velocity is one module. Add it to your project with `go get`:

```bash
go get github.com/velocitykode/velocity@latest
```

The module path is `github.com/velocitykode/velocity`. Every subsystem
is a subpackage under it (for example
`github.com/velocitykode/velocity/cache`), so a single `go get` makes
all of them importable. The Go toolchain only compiles the packages you
actually import, so pulling in `str` does not drag in the ORM or the
router.


**Standalone vs full app.** When you import a single package and call
its constructor yourself, *you own the lifecycle*: you build the config,
hold the instance, and decide when to use it. When you call
`velocity.New()` instead, the framework reads your `.env` and `config/`
files and wires every subsystem (logger, crypto, cache, queue, router,
...) into an `*velocity.App` for you. Both paths use the same underlying
constructors shown on this page; the full app is just the batteries-included
assembly of them. See  for the full
app path.


## Standard driver bundles

Several subsystems are *pluggable*: cache, log, orm, queue, and storage
each own a driver registry, and config selects a driver by name at
runtime. A driver only becomes selectable once its factory has been
registered, and registration happens in a package's `init()` at import
time.

The light built-in drivers self-register from the subsystem's own
package, so importing the subsystem makes them available with no extra
work. The heavier drivers live in separate leaf packages so they (and
their dependencies) are only compiled when you ask for them. To register
*every* driver in a subsystem with one line, blank-import its `standard`
bundle:

```go
import (
    _ "github.com/velocitykode/velocity/cache/standard"
    _ "github.com/velocitykode/velocity/log/standard"
    _ "github.com/velocitykode/velocity/orm/standard"
    _ "github.com/velocitykode/velocity/queue/standard"
    _ "github.com/velocitykode/velocity/storage/standard"
)
```

Each bundle wires its subsystem's full driver set into the registry so
config can pick any of them at runtime:

| Bundle | Light drivers (self-register from the subsystem) | Heavy leaf drivers the bundle adds |
|---|---|---|
| `cache/standard` | memory, file | redis (`cache/redis`, go-redis) |
| `log/standard` | console, null | file, daily (`log/file`), stack (`log/stack`) |
| `orm/standard` | modernc SQLite (pure-Go default) | mysql (`orm/mysql`), postgres (`orm/postgres`), cgo SQLite (`orm/sqlite`) |
| `queue/standard` | memory, database | redis (`queue/redis`, go-redis) |
| `storage/standard` | local, memory | s3 (`storage/s3`, AWS SDK) |


**Smaller footprint?** If you only need one heavy driver, skip the
bundle and blank-import just that leaf (for example
`_ "github.com/velocitykode/velocity/cache/redis"`). You only pay for
the dependencies you import. The bundles exist purely to register the
full set in one line; they must not be imported by the framework core,
which is why they live in their own packages.


## Cherry-picking components

Every Velocity subsystem exposes a plain Go constructor. Below are the
real signatures for the most commonly used leaf packages, each shown in
isolation with no `velocity.App`.

### Cache

`cache.NewManager(config *cache.Config) *cache.Manager`. The memory,
file, and database drivers self-register from the `cache` package's own
`init()`, so a memory store needs no bundle import at all:

```go
package main

import (
    "fmt"
    "time"

    "github.com/velocitykode/velocity/cache"
)

func main() {
    mgr := cache.NewManager(&cache.Config{
        Default: "memory",
        Stores: map[string]cache.StoreConfig{
            "memory": {Driver: cache.DriverMemory},
        },
    })

    mgr.Put("greeting", "hello", 5*time.Minute)

    if v, found := mgr.Get("greeting"); found {
        fmt.Println(v) // hello
    }
}
```

To use Redis here you would add
`_ "github.com/velocitykode/velocity/cache/standard"` (or the
`cache/redis` leaf) and set `Driver: cache.DriverRedis` with the host
fields on `StoreConfig`.


**Thread the context.** `Manager` exposes a `*WithContext` variant for
every method (`PutWithContext`, `GetWithContext`,
`RememberEWithContext`, `StoreWithContext`, ...). Stores are created
lazily on first use; passing a `context.Context` lets a slow driver
connect (a Redis dial) honour your deadline. Prefer the context variants
in any code that already has one. See .


### Crypto

`crypto.NewEncryptor(config crypto.Config) (crypto.Encryptor, error)`.
The crypto package never reads the environment; you pass the key
explicitly. Build one encryptor and reuse it:

```go
package main

import (
    "fmt"

    "github.com/velocitykode/velocity/crypto"
)

func main() {
    enc, err := crypto.NewEncryptor(crypto.Config{
        Key:    "base64:your-base64-encoded-key-here",
        Cipher: "AES-256-GCM",
    })
    if err != nil {
        panic(err)
    }

    payload, err := enc.Encrypt("sensitive data")
    if err != nil {
        panic(err)
    }

    plaintext, err := enc.Decrypt(payload)
    if err != nil {
        panic(err)
    }

    fmt.Println(plaintext) // sensitive data
}
```

`crypto.Config` fields are `Key`, `Cipher`, and `PreviousKeys` (for key
rotation). See .

### Validation

`validation.NewValidator() validation.Validator`. Rules are a
`map[string][]string` (`validation.Rules`); each entry is the field name
mapped to its list of rule strings. `Validate` returns a
`*validation.ValidatedData`:

```go
package main

import (
    "fmt"

    "github.com/velocitykode/velocity/validation"
)

func main() {
    v := validation.NewValidator()

    data := map[string]interface{}{
        "name":  "Ada",
        "email": "ada@example.com",
    }

    rules := validation.Rules{
        "name":  {"required", "min:2"},
        "email": {"required", "email"},
    }

    validated, err := v.Validate(data, rules)
    if err != nil {
        panic(err)
    }

    if validated.Errors().HasError("email") {
        fmt.Println("email is invalid")
    }
}
```

### HTTP client

`httpclient.New(opts ...httpclient.Option) *httpclient.Client`. The
client ships with secure defaults: TLS 1.2 or higher, a capped redirect
chain, sensitive headers stripped on cross-host redirects, a 30 second
timeout, and the SSRF private-IP dial guard enabled. Every request takes
a `context.Context`:

```go
package main

import (
    "context"
    "io"
    "time"

    "github.com/velocitykode/velocity/httpclient"
)

func main() {
    client := httpclient.New(
        httpclient.WithBaseURL("https://api.example.com"),
        httpclient.WithTimeout(10*time.Second),
    )

    ctx := context.Background()
    resp, err := client.Get(ctx, "/health")
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    _ = body
}
```

Use `httpclient.WithAllowedHosts(...)` to whitelist specific internal
hosts. `Client` also exposes `Post`, `Put`, `Delete`, and `Do(ctx,
*http.Request)` for full control.

### Strings

The `str` package is pure functions plus a fluent `*str.Stringable`
wrapper. There is no manager to construct; import and call:

```go
package main

import (
    "fmt"

    "github.com/velocitykode/velocity/str"
)

func main() {
    fmt.Println(str.Slug("Hello World"))   // hello-world
    fmt.Println(str.Camel("user_name"))    // userName
    fmt.Println(str.Snake("UserName"))     // user_name

    // Fluent chain via str.Of(...).
    out := str.Of("  Hello World  ").
        Camel().
        ToString()
    fmt.Println(out)
}
```

### Collections

`collect` mirrors `str`: standalone generic helpers over slices plus a
fluent `*collect.Collection[T]` from `collect.From(items)`:

```go
package main

import (
    "fmt"

    "github.com/velocitykode/velocity/collect"
)

func main() {
    nums := []int{1, 2, 3, 4, 5}

    evens := collect.Filter(nums, func(n int) bool { return n%2 == 0 })
    doubled := collect.Map(nums, func(n int) int { return n * 2 })

    fmt.Println(evens)   // [2 4]
    fmt.Println(doubled) // [2 4 6 8 10]
}
```

### Pipeline

`pipeline.New[T any]() *pipeline.Pipeline[T]` sends a value through a
series of stages. A stage is anything implementing
`Handle(passable T, next func(T) error) error`; wrap a function with
`pipeline.Pipe[T]`. `Then` runs the pipeline:

```go
package main

import (
    "fmt"
    "strings"

    "github.com/velocitykode/velocity/pipeline"
)

func main() {
    err := pipeline.New[string]().
        Send("  hello  ").
        Through(
            pipeline.Pipe[string](func(s string, next func(string) error) error {
                return next(strings.TrimSpace(s))
            }),
            pipeline.Pipe[string](func(s string, next func(string) error) error {
                return next(strings.ToUpper(s))
            }),
        ).
        Then(func(s string) error {
            fmt.Println(s) // HELLO
            return nil
        })
    if err != nil {
        panic(err)
    }
}
```

`Pipeline` is not safe for concurrent use: build and run it from a
single goroutine.

### Async

The `async` package is package-level generic helpers; there is nothing
to construct. `async.Run` runs a function on a goroutine and returns a
`*async.Result[T]`; `async.All` / `async.Map` fan out over a set of
functions or items:

```go
package main

import (
    "fmt"

    "github.com/velocitykode/velocity/async"
)

func main() {
    // Run a single task off the calling goroutine.
    r := async.Run(func() int { return 21 * 2 })
    value, err := r.Get()
    if err != nil {
        panic(err)
    }
    fmt.Println(value) // 42

    // Run several functions concurrently and collect results.
    results, allErr := async.All(
        func() int { return 1 },
        func() int { return 2 },
        func() int { return 3 },
    )
    if allErr != nil {
        panic(allErr)
    }
    fmt.Println(results) // [1 2 3]
}
```

Context-aware variants exist where blocking work needs a deadline:
`async.RunWithTimeout(timeout, fn)`, `async.RunWithContext(ctx, fn)`,
and `async.GoCtx(ctx, fn)`. Use them when the work can hang and you want
cancellation to propagate.

### Log

`log.NewManager(cfg log.LoggingConfig) *log.Manager`. The console and
null drivers self-register from the `log` package, so a console logger
needs no bundle import. `Channel(name)` (or `Default()`) returns a
`Logger` with `Debug`, `Info`, `Warn`, and `Error(msg string, kvs
...any)`:

```go
package main

import (
    "github.com/velocitykode/velocity/log"
)

func main() {
    mgr := log.NewManager(log.LoggingConfig{
        Default: "console",
        Channels: map[string]log.ChannelConfig{
            "console": {Driver: "console", Level: "debug"},
        },
    })

    logger, err := mgr.Default()
    if err != nil {
        panic(err)
    }

    logger.Info("standalone logger ready", "driver", "console")
}
```

For the `file`, `daily`, or `stack` drivers, blank-import
`_ "github.com/velocitykode/velocity/log/standard"` (or the individual
leaf) so those factories are registered before you resolve the channel.

## When to reach for the full app

Standalone construction is the right tool for libraries, CLIs, scripts,
tests, and embedded use. Reach for `velocity.New()` when you want the
framework to read `.env` and `config/`, build all subsystems from that
config, and hand you a wired `*velocity.App` (with `app.Cache`,
`app.Log`, the router, and the rest). The constructors are identical
either way; the full app simply assembles them for you. See
 to scaffold a complete application.


================================================================================
# Installation

Source: https://vel.build/docs/cli/installation/
Section: CLI
Summary: Install the Velocity CLI on macOS using Homebrew. Create and manage Go web applications with the velocity command line tool.


Install the Velocity CLI to create and manage Velocity projects.

## Requirements

- **Go 1.26 or higher** - Required for building projects (the installer checks `go version` on startup and refuses to run on an older toolchain)
- **Node.js 20+** - Required for frontend asset compilation (Vite 7)
- **Git** - Required for project initialization (each new project is initialized as a Git repository, and Git clone is used as a fallback when the template tarball download is unavailable)

Full-stack projects install JavaScript dependencies with [bun](https://bun.sh) when it is available, falling back to `npm`. Installing bun is optional but gives much faster installs.

## Install via Homebrew

The recommended way to install Velocity on macOS is through the Homebrew cask:

```bash
brew tap velocitykode/tap
brew install velocity
```

## Verify Installation

Check that the CLI is installed correctly:

```bash
velocity --version
```

You should see the installer version followed by the template tags pinned to that release:

```
velocity 0.21.14
templates:
  api -> v...
  react -> v...
  vue -> v...
```

Each installer release pins exact template tags, so the version output lists those tags as the relevant build coordinates.

## Understanding the CLI Architecture

Velocity uses two CLI tools:

| Tool | Install Method | Purpose |
|------|---------------|---------|
| `velocity` | Homebrew (global) | Create projects, manage config |
| `vel` | Built from source (per-project) | Run dev server, migrations, generators |

When you run `velocity new myapp`, it:
1. Scaffolds a new project from the pinned template
2. Installs dependencies (`go mod tidy`, plus bun/npm for full-stack projects)
3. Builds the `./vel` binary from your project source
4. Runs initial database migrations

When the project is ready it prints the next steps to start the dev servers (`cd myapp` then `./vel serve`). If the database server is not reachable, migrations are skipped and the printed steps include starting your database and running `./vel migrate` manually.

## Using vel in Projects

After creating a project, use `./vel` for development commands:

```bash
cd myapp
./vel serve      # Start dev server
./vel migrate    # Run migrations
```

### Shell Function (Recommended)

Run this once to use `vel` instead of `./vel`:

```bash
grep -q "vel()" ~/.zshrc || echo 'vel() { [ -x ./vel ] && ./vel "$@" || echo "vel: not found"; }' >> ~/.zshrc && source ~/.zshrc
```

Now you can simply run:

```bash
vel serve
vel migrate
```

## Getting Help

View available commands:

```bash
velocity --help
./vel --help
```

Get help for a specific command:

```bash
velocity new --help
./vel serve --help
```

## Setting Project Defaults

Use `velocity config` to set defaults that `velocity new` will apply when a flag is not provided:

```bash
velocity config set default.database postgres
velocity config set default.cache redis
velocity config set default.api true
```

Supported keys are `default.database`, `default.cache`, `default.queue`, `default.auth`, and `default.api`. Read or inspect the current values with:

```bash
velocity config get default.database
velocity config list
velocity config reset
```

Configuration is stored in `~/.vel/config.yaml`.

## Updating

### Update Velocity Installer

For Homebrew installs, upgrade the cask:

```bash
brew upgrade --cask velocity
```

The built-in self-update command detects a Homebrew install and will point you at the `brew upgrade --cask velocity` command above. It only downloads and replaces the binary in place for non-Homebrew (manual) installs:

```bash
velocity self-update
```

### Rebuild vel

The `vel` binary is built from the project's `main.go`. To rebuild it manually from the project root:

```bash
go build -o vel .
```

## Uninstalling

### Remove Velocity Installer

```bash
brew uninstall --cask velocity
brew untap velocitykode/tap
```

### Remove vel

The `vel` binary is project-local and gitignored. Simply delete your project directory.


================================================================================
# vel Commands

Source: https://vel.build/docs/cli/commands/
Section: CLI
Summary: Complete reference for the per-project `vel` CLI - serve, build, migrations, queues, code generation, maintenance, routes, and keys.


`vel` is the per-project binary. It's created in your project root when
you scaffold an app with `velocity new`. Run `./vel <command>` - or
alias `vel` to `./vel` in your shell - from the project directory.

For the installer CLI (`velocity new`, `velocity self-update`, etc.),
see [Installer Commands](/docs/cli/installer/).

## Command grammar

Command names are plain words separated by spaces: `migrate`,
`migrate fresh`, `gen model`, `gen grpc service`. Nothing in the CLI uses
a colon.

The dispatcher joins the leading arguments into a candidate name (at most
three words, the length of the longest registered name) and resolves
longest match first:

- A subcommand beats its bare parent. `vel migrate fresh` runs the fresh
  command; it is never `migrate` with a `fresh` argument.
- Token joining stops at the first flag-like argument, so
  `vel migrate --pretend` resolves to `migrate` with `--pretend` handed
  through as an argument, and `vel run seed` resolves to `run` with
  `seed` (plus any trailing arguments) passed to your custom command.
- An unknown command reports the full unmatched token sequence:
  `vel migrate frsh` fails with `vel: unknown command "migrate frsh"`,
  not just `migrate`.

Unrecognised arguments are rejected rather than silently dropped. An
unknown flag errors with `unknown flag: <flag>`, a stray positional with
`unexpected argument: <arg>`, and a value-taking flag with nothing after
it with `flag <flag> needs a value`. Value-taking flags accept both
`--flag value` and `--flag=value`.


Arguments are parsed **before** the application bootstraps, so a typo
fails immediately without running your module lifecycle.


## Server

### vel serve

Start the development server with live reload.

```bash
vel serve [flags]
```

| Flag        | Short | Default       | Description                               |
| ----------- | ----- | ------------- | ----------------------------------------- |
| `--port`    | `-p`  | `4000`        | HTTP port (falls back to `APP_PORT`)      |
| `--env`     | `-e`  | `development` | Environment name (sets `APP_ENV`)         |
| `--no-watch`|       | off           | Disable file-watching / auto-rebuild      |
| `--tags`    |       | (none)        | Build tags passed to `go build`           |

```bash
vel serve
vel serve --port 3000
vel serve --env staging --no-watch
vel serve --tags="integration"
```

On start:

1. `.env` is loaded and `APP_PORT` / `APP_ENV` are read; flags override
   both. With no environment resolved, `vel serve` defaults to
   `development` and warns that `APP_ENV` was unset.
2. When a `package.json` is present, the Vite dev server is started with
   `npm run dev` (or `bun run dev` when `bun` is on `PATH` and a
   `bun.lock` file exists).
3. The Go app compiles to `.vel/tmp/server`, which is created
   owner-only because the binary embeds build-time configuration.
4. `.go` files are watched; a change debounces for 500ms, then rebuilds
   and restarts the server. The rebuild also refreshes the project's
   `./vel` binary, so one-shot commands in another terminal
   (`vel routes`, `vel migrate`, `vel gen ...`) see current source.


`vel serve run` is the internal entry point the watcher uses to launch
the compiled child process. It's dispatchable but not meant to be typed
by hand, so it's omitted from `vel help`.


### vel build

Compile a production binary.

```bash
vel build [flags]
```

| Flag        | Short | Default          | Description                                          |
| ----------- | ----- | ---------------- | ---------------------------------------------------- |
| `--output`  | `-o`  | project dir name | Output path (`.exe` appended when `--os windows`)    |
| `--os`      |       | (host)           | Target `GOOS`                                        |
| `--arch`    |       | (host)           | Target `GOARCH`                                      |
| `--tags`    |       | (none)           | Go build tags                                        |

```bash
vel build
vel build --output ./bin/myapp
vel build --os linux --arch amd64
```

The build runs with `CGO_ENABLED=0` and stamps version metadata into
`velocity.BuildInfo` via `-ldflags` (`Version`, `Commit`, `Date`).
`Version` defaults to `devel` and `Commit` to the short SHA from
`git rev-parse --short HEAD`, falling back to `devel` when git is
unavailable.

## Database

### vel migrate

Run all pending migrations.

```bash
vel migrate [--pretend]
```

`--pretend` prints the SQL that would run without executing it - useful
for reviewing migration output before committing. It is the only flag
`migrate` accepts; anything else errors.

With no database configured (`DB_CONNECTION` unset) the command warns
and exits cleanly instead of failing.

### vel migrate fresh

Drop all tables, then run every migration from scratch.

```bash
vel migrate fresh [--force]
```

In a production-class environment this command refuses to run unless
`--force` (`-f`) is passed. The guard treats `production`, `prod`,
`staging`, and any unrecognised `APP_ENV` value as production, so a
typo'd `APP_ENV` cannot disable it. `development`, `dev`, `test`,
`testing`, `local`, and an unset `APP_ENV` are non-production.

`--force` / `-f` is the only argument this command accepts.


Destructive - deletes all data. Development / testing only.


### vel migrate rollback

Roll back the most recent batch of migrations.

```bash
vel migrate rollback [--step N] [--force]
```

| Flag      | Short | Default | Description                                                   |
| --------- | ----- | ------- | ------------------------------------------------------------- |
| `--step`  | `-s`  | `1`     | Number of batches to roll back (must be >= 1)                 |
| `--force` | `-f`  | off     | Bypass the production-environment guard                       |

`--step N`, `-s N`, and `--step=N` are equivalent and compose with
`--force` in any order. A non-integer or below-1 value errors.

Like `migrate fresh`, this is gated in production-class environments;
pass `--force` to proceed.

### vel migrate status

Show which migrations have run.

```bash
vel migrate status
```

Takes no arguments.

### vel db wipe

Drop every table in the current database without running migrations.

```bash
vel db wipe [--force]
```

In a production-class environment this command refuses to run unless
`--force` (`-f`) is passed (same guard as `migrate fresh`), and `--force`
/ `-f` is the only argument it accepts.


Destructive. Outside production there is no confirmation prompt. Use
only when you know the database is disposable.


## Queue and Scheduler

### vel queue work

Start a worker that processes queued jobs.

```bash
vel queue work [--queue NAME] [--tries N] [--timeout S]
```

| Flag        | Short | Default      | Description                                |
| ----------- | ----- | ------------ | ------------------------------------------ |
| `--queue`   | `-q`  | `default`    | Queue to consume from                      |
| `--tries`   |       | `3`          | Max attempts per job before marking failed |
| `--timeout` |       | `30`         | Per-job timeout in seconds                 |

`--tries` and `--timeout` require integer values; when omitted the
worker's own defaults apply. Worker errors are routed through the
application logger. `SIGINT` / `SIGTERM` stops the worker gracefully.

```bash
vel queue work
vel queue work --queue emails --tries 3 --timeout 60
```

### vel schedule work

Run the scheduler loop - picks up scheduled tasks defined via
`v.Schedule(...)` and dispatches them when due.

```bash
vel schedule work
```

Takes no arguments. Typically run under a process supervisor (systemd,
Docker, etc.) rather than manually; `SIGINT` / `SIGTERM` shuts it down
gracefully.

## Cache

### vel cache clear

Flush the configured cache store.

```bash
vel cache clear
```

Takes no arguments. With no cache configured it warns and exits cleanly.

## Maintenance Mode

### vel down

Put the app into maintenance mode. Requests return a `503` JSON
response unless they carry the bypass secret (or hit a path the
maintenance middleware is configured to exclude, such as health probes
and webhooks).

```bash
vel down [--secret TOKEN] [--retry N]
```

| Flag       | Default | Description                                            |
| ---------- | ------- | ------------------------------------------------------ |
| `--secret` | (none)  | Bypass token. Send it in the `X-Maintenance-Bypass` header (or visit `/<secret>`) to mint a signed `velocity_maintenance_bypass` cookie that exempts the browser for 12 hours |
| `--retry`  | (none)  | Recorded as `retry_after` in the maintenance marker     |

```bash
vel down --secret "abc123" --retry 60
```

The command writes a `.vel/down` marker file holding the secret, the
retry value, and a UTC timestamp. Both the file (`0600`) and its
directory (`0700`) are owner-only because the marker carries the bypass
secret. The location is resolved independently of the current working
directory and can be moved with `VELOCITY_MAINTENANCE_ROOT`, so the
writer and the runtime middleware always agree on one path.


Prefer the `X-Maintenance-Bypass` header over the legacy `/<secret>`
path: a secret in the URL leaks into access logs, proxy logs, `Referer`
headers, and browser history.


### vel up

Exit maintenance mode by removing the marker file.

```bash
vel up
```

Takes no arguments. A missing marker is not an error.

## Keys

### vel key generate

Generate a fresh 32-byte encryption key and write it to `.env` under
`APP_KEY`, base64-encoded with a `base64:` prefix. If `.env` does not
exist it's created; an existing `APP_KEY=` line is replaced in place,
and a file without one gets the key prepended as its first line. The
`.env` file is written with owner-only (`0600`) permissions.

```bash
vel key generate
```

Takes no arguments.

## Routes

### vel routes

Print every registered route with method, path, and name.

```bash
vel routes
```

Takes no arguments. Runs the bootstrap lifecycle internally before
printing - the output always reflects the current `v.Routes(...)`
definition.

## Code Generation

All generators live under `gen <artifact>`. Each scaffolds a file into
the conventional location for that type, converting the name to the
right case for the artifact (snake_case for file names, PascalCase for
types).

Every `gen` command accepts a `--dir <path>` flag to override the
default output directory (the artifact's conventional folder). The value
must be project-relative, is cleaned, and is rejected if it escapes the
project tree or routes through a symlink. Existing files are never
overwritten.

Names are normalised before use: the artifact's own kind suffix is
stripped and the rest is PascalCased, so `vel gen policy PostPolicy` and
`vel gen policy Post` both write `internal/policies/post.go` holding
`type PostPolicy`. File names are the snake_case form of the normalised
name. Passing nothing but the suffix (for example `vel gen module
Module`) errors rather than writing a file named `.go`.

### vel gen handler

```bash
vel gen handler <name> [--resource] [--api] [--dir PATH]
```

| Flag         | Short | Default | Description                                      |
| ------------ | ----- | ------- | ------------------------------------------------ |
| `--resource` | `-r`  | off     | Scaffold CRUD handlers (Index/Create/Store/Show/Edit/Update/Destroy) |
| `--api`      |       | off     | JSON responses instead of string/view responses  |
| `--dir`      |       | `internal/handlers` | Output root override                 |

Output: `internal/handlers/<name>.go`, holding
`func <Name>Index(ctx *router.Context) error`-style functions.
Namespaced names like `Admin/Dashboard` nest under the output root, with
the package taken from the parent segment.

```bash
vel gen handler User
vel gen handler Post --resource
vel gen handler Admin/Dashboard
vel gen handler Product --api --resource
vel gen handler User --dir internal/web/handlers
```

### vel gen model

```bash
vel gen model <name> [--uuid] [--soft-deletes] [--migration] [--dir PATH]
```

| Flag              | Short | Default | Description                          |
| ----------------- | ----- | ------- | ------------------------------------ |
| `--uuid`          |       | off     | Use UUID primary key                 |
| `--soft-deletes`  |       | off     | Add deleted_at column and scope      |
| `--migration`     | `-m`  | off     | Also scaffold the create migration   |
| `--dir`           |       | `internal/models` | Output directory override  |

Output: `internal/models/<name>.go`. The model embeds `orm.Model[T]`,
`orm.UUIDModel[T]`, `orm.SoftDeleteModel[T]`, or
`orm.SoftDeleteUUIDModel[T]` depending on the flags, declares
`TableName()` (pluralised snake_case), and ships a commented-out
`AssignableFields()` allowlist - mass assignment is deny-by-default, so
fill it in (or declare `ProtectedFields()`) before writing to the model
from a map.

With `--migration`, a `create_<table>` migration is generated with the
same `--uuid` / `--soft-deletes` settings. That migration always lands
in `database/migrations`; `--dir` applies to the model file only.

### vel gen migration

```bash
vel gen migration <name> [--create TABLE] [--table TABLE] [--uuid] [--soft-deletes] [--dir PATH]
```

| Flag             | Accepts             | Description                                         |
| ---------------- | ------------------- | --------------------------------------------------- |
| `--create`       | `=VALUE` or space   | Generate a "create" migration for the given table   |
| `--table`        | `=VALUE` or space   | Generate an "alter" migration for the given table   |
| `--uuid`         | flag                | Use UUID primary key in the create template         |
| `--soft-deletes` | flag                | Include deleted_at in the create template           |
| `--dir`          | `=VALUE` or space   | Output directory override (default `database/migrations`) |

Table names passed to `--create` / `--table` must match
`[A-Za-z_][A-Za-z0-9_]*`. Output:
`database/migrations/<timestamp>_<name>.go`.

The timestamp has second resolution. When a file with that version
already exists, the generator walks the version forward a second at a
time so two migrations scaffolded back to back cannot collide.

```bash
vel gen migration create_posts --create=posts
vel gen migration add_slug_to_posts --table=posts
```

### Other gen commands

All take a name argument and scaffold a file into the conventional
directory. Each also accepts `--dir <path>` to override that directory,
and takes no other flags.

| Command                              | Output path                                 | Generated symbol                                   |
| ------------------------------------ | ------------------------------------------- | -------------------------------------------------- |
| `vel gen middleware RateLimit`       | `internal/middleware/rate_limit.go`         | `func RateLimit(next router.HandlerFunc) router.HandlerFunc` |
| `vel gen event UserRegistered`       | `internal/events/user_registered.go`        | `type UserRegistered`, `Name()` returns `user.registered` |
| `vel gen listener SendWelcomeEmail`  | `internal/listeners/send_welcome_email.go`  | `func SendWelcomeEmail(event interface{}) error`   |
| `vel gen job ProcessPayment`         | `internal/jobs/process_payment.go`          | `type ProcessPayment` (`Handle` / `Failed` / `MaxAttempts`) |
| `vel gen mail OrderShipped`          | `internal/mail/order_shipped.go`            | `type OrderShipped` (`Envelope` / `Content`)       |
| `vel gen notification InvoicePaid`   | `internal/notifications/invoice_paid.go`    | `type InvoicePaid` (`Via` / `ToMail`)              |
| `vel gen resource Post`              | `internal/resources/post.go`                | `type PostResource`                                |
| `vel gen policy Post`                | `internal/policies/post.go`                 | `type PostPolicy`                                  |
| `vel gen module Billing`             | `internal/modules/billing.go`               | `type BillingModule`                               |
| `vel gen command SyncInventory`      | `internal/commands/sync_inventory.go`       | `type SyncInventoryCommand`                        |

`vel gen module` writes a `<Name>Module` type in package `modules` with
the full module lifecycle already stubbed:

```go
func (m *BillingModule) Init(s *velocity.Services) error { return nil }
func (m *BillingModule) Start(s *velocity.Services) error { return nil }
func (m *BillingModule) Shutdown(ctx context.Context) error { return nil }
```

`vel gen command` writes a custom command implementing `Name()`,
`Description()`, and `Handle(s *velocity.Services, args []string) error`,
with the invocation name derived in kebab-case (`SyncInventory` becomes
`sync-inventory`). The generated file carries its own registration hint
(`r.Add(&SyncInventoryCommand{})`); once registered it runs through
[`vel run`](#vel-run).

### vel gen grpc service

```bash
vel gen grpc service <Name> [flags]
```

Scaffolds a gRPC service end-to-end in one call:

- `api/proto/<leaf>/v1/<name>.proto` - empty service block
- `api/proto/buf.yaml` + `api/proto/buf.gen.yaml` (first run only)
- `internal/grpc/services/<name>.go` - `<Name>Service` impl with a `New<Name>Service()` constructor and the `<alias>.Unimplemented<Name>ServiceServer` embed
- `internal/modules/grpc_module.go` - created on first call (unless `--no-module`), then **injected at** `// vel:grpc:imports` and `// vel:grpc:services` markers on every subsequent call. The module wires the service via `velgrpc.NewServer(...)` and `Register<Name>ServiceServer(...)`.

| Flag              | Default                     | Description                                                  |
| ----------------- | --------------------------- | ------------------------------------------------------------ |
| `--package`       | derived from `<Name>`       | Directory leaf under `api/proto/` and `api/gen/go/`          |
| `--proto-package` | `<leaf>.v1`                 | Full wire package, e.g. `velship.admin.v1`                   |
| `--dir`           | `internal/grpc/services`    | Go impl output directory                                     |
| `--alias`         | `<leaf>pb`                  | Import alias for the generated proto package                 |
| `--proto-name`    | lower-cased `<Name>` base   | Proto file base name (no extension)                          |
| `--impl-name`     | snake_case `<Name>` base    | Go impl file base name (no extension)                        |
| `--no-module`     | off                         | Skip module scaffolding / wiring (proto + impl only)         |

Name normalisation: `vel gen grpc service Foo`, `FooService`, `foo`, and `fooService` all produce the Go type `FooService` with proto package `foo.v1` and default import alias `foopb`. The proto file uses `option go_package = "<module>/api/gen/go/<leaf>/v1;<leaf>v1"` derived from the host project's `go.mod` (so the generated package itself is named `<leaf>v1`, referenced through the `foopb` alias).

`buf.yaml` / `buf.gen.yaml` are written **before** the proto file, so a config-write failure leaves no partial scaffold on disk. The generated `GRPCModule` does **not** hard-code `WithReflection(true)`; it reads `GRPC_PORT` (default `50051`) and otherwise takes the framework defaults, including reflection off unless `GRPC_REFLECTION=true`.

Wiring guards:

- If `internal/modules/grpc_module.go` already exists **without** the
  marker comments (legacy hand-written module), the command prints a
  manual wire snippet instead of mutating user code.
- If the existing module imports a services package other than this
  service's impl directory, the command stops **before** writing any
  file and tells you to re-run with `--no-module` and wire it by hand.
- When the module already imports the generated proto package under a
  different alias, that alias is reused rather than emitting a duplicate
  import.

```bash
vel gen grpc service Foo
vel gen grpc service ChatService
vel gen grpc service TemplateControl --package admin \
  --proto-package velship.admin.v1 --dir internal/shared/grpc/services --no-module
```

After scaffolding, register `&modules.GRPCModule{}` in
`internal/app/bootstrap.go` (printed as a hint on first run).

### vel gen grpc rpc

```bash
vel gen grpc rpc <Service> <RPC> [--stream | --client-stream | --bidi]
```

Appends a new rpc to an existing service's `.proto` and a matching method stub on the Go impl. The service must already exist; run `vel gen grpc service <Name>` first.


Both paths are derived from the service name alone, matching what
`vel gen grpc service` writes by default:
`api/proto/<name>/v1/<name>.proto` (lower-cased, no underscores) and
`internal/grpc/services/<name>.go` (snake_case). A service scaffolded
with `--package`, `--dir`, `--proto-name`, or `--impl-name` is not found
under those paths and has to be extended by hand; the error message
prints the exact path that was expected.


| Flag              | Aliases             | RPC shape produced                                |
| ----------------- | ------------------- | ------------------------------------------------- |
| _(none)_          |                     | Unary: `rpc X(XRequest) returns (XResponse)`      |
| `--stream`        | `--server-stream`   | Server-streaming: `returns (stream XResponse)`    |
| `--client-stream` |                     | Client-streaming: `(stream XRequest) returns (X)` |
| `--bidi`          | `--bidirectional`   | Bidi: `(stream XRequest) returns (stream X)`      |

Only one streaming flag may be set per invocation; combining them errors out.

The proto scanner walks the file with brace counting that respects `//` line comments, `/* block */` comments, and `"..."` string literals at every position (header keyword, between keyword and name, between name and `{`, and inside the body). That means rpc-with-options blocks (grpc-gateway HTTP annotations) and commented-out draft headers do not corrupt insertion.

On the Go side, the generated method signature matches the RPC shape (for service `Foo`, impl type `FooService`, default proto alias `foopb`):

| Shape         | Signature                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------- |
| Unary         | `func (s *FooService) X(ctx context.Context, req *foopb.XRequest) (*foopb.XResponse, error)`    |
| Server stream | `func (s *FooService) X(req *foopb.XRequest, stream foopb.FooService_XServer) error`             |
| Client stream | `func (s *FooService) X(stream foopb.FooService_XServer) error`                                  |
| Bidi          | `func (s *FooService) X(stream foopb.FooService_XServer) error`                                  |

`context` is added to the impl's imports for unary only; streaming variants pull ctx from `stream.Context()` and do not need the import.

Idempotent: re-running with the same `<Service> <RPC>` pair detects the existing rpc and skips.

```bash
vel gen grpc rpc Foo Hello
vel gen grpc rpc Foo Tail --stream
vel gen grpc rpc Foo Upload --client-stream
vel gen grpc rpc Foo Chat --bidi
```

### vel gen grpc gen

```bash
vel gen grpc gen
```

Runs `buf generate` inside `api/proto`. Streams buf's stdout and stderr to your terminal so plugin errors are visible in real time. Takes no arguments, and fails with a clear message when:

- `api/proto/` does not exist (run `vel gen grpc service <Name>` first)
- `buf` is not on `PATH` (links to install docs)
- `buf generate` exits non-zero

```bash
vel gen grpc gen
# cd api/proto && buf generate
# Generated Go code in api/gen/go/
```

## Custom Commands

### vel run

Run a command your application registered.

```bash
vel run <command> [arguments]
```

Everything after the command name is passed straight through to the
command's `Handle(s *velocity.Services, args []string) error`, so
`vel run seed --fresh` reaches your code with `["--fresh"]`.

```bash
vel run              # list every registered command
vel run seed
vel run seed --fresh
```

`vel run` with no arguments prints the registered commands (or a hint to
create one with `vel gen command <Name>`). An unknown name prints the
same list and errors, and a flag-like first token (`vel run --bogus`) is
rejected as an unknown flag before the app bootstraps.

Custom commands are reachable only through `vel run`: typing one as a
bare `vel <name>` is an unknown command, so a command sharing a name
with a built-in never shadows it.

## Help

```bash
vel help
vel --help
vel -h
```

Prints a grouped list of every command: Server, Database, Queue &
Scheduler, Cache, Code Generation, Custom Commands, and Other. Running
`vel` with no arguments prints the same listing.


================================================================================
# Configuration

Source: https://vel.build/docs/cli/configuration/
Section: CLI
Summary: Configure a Velocity application through environment variables and the .env file, or override settings in code with the Config struct and functional options.


A Velocity application is configured entirely through **environment variables**, loaded once at startup. There is no separate config store or CLI to manage settings. Every value comes from the process environment (or a `.env` file) and is read into a typed `Config` struct.

## How Configuration Is Loaded

When you call `velocity.New()`, the framework loads configuration with `ConfigFromEnv()`. This reads a `.env` file from the working directory (if present) and then reads each setting from the environment, applying built-in defaults where a variable is unset.

```go
package main

import (
    "log"

    "github.com/velocitykode/velocity"
)

func main() {
    v, err := velocity.New() // loads ConfigFromEnv() internally
    if err != nil {
        log.Fatal(err)
    }

    if err := v.Serve(); err != nil {
        log.Fatal(err)
    }
}
```


If a `.env` file exists but fails to parse, Velocity logs a warning and continues with the process environment. A missing `.env` file is not an error: environment variables alone are sufficient.


## The .env File

Place a `.env` file at the root of your project. Each line sets one environment variable:

```bash
# .env
APP_ENV=production
APP_DEBUG=false
APP_PORT=4000
APP_KEY=base64:...

DB_CONNECTION=postgres
DB_HOST=127.0.0.1
DB_DATABASE=myapp
DB_USERNAME=myapp
DB_PASSWORD=secret

CACHE_DRIVER=redis
QUEUE_DRIVER=redis
```

## Common Settings

The most frequently used variables and their defaults:

| Variable | Description | Default |
|----------|-------------|---------|
| `APP_ENV` | Application environment | _(empty)_ |
| `APP_DEBUG` | Enable debug output | `false` |
| `APP_PORT` | HTTP server port | `4000` |
| `APP_KEY` | Application key used for crypto | _(empty)_ |
| `DB_CONNECTION` | Database driver (`sqlite`, `postgres`, `mysql`) | _(empty)_ |
| `DB_HOST` | Database host | `127.0.0.1` |
| `DB_PORT` | Database port | _(per driver)_ |
| `DB_DATABASE` | Database name | _(empty)_ |
| `DB_USERNAME` | Database username | _(empty)_ |
| `DB_PASSWORD` | Database password | _(empty)_ |
| `CACHE_DRIVER` | Cache driver (`memory`, `file`, `redis`, `database`) | `memory` |
| `QUEUE_DRIVER` | Queue driver (`memory`, `redis`, `database`) | `memory` |
| `STORAGE_DRIVER` | Default storage disk | `local` |
| `LOG_DRIVER` | Log driver | `console` |
| `LOG_LEVEL` | Minimum log level | `debug` |


`APP_ENV` is intentionally empty when unset. Security gates fail closed for an unknown environment, so production deployments that forget to set `APP_ENV` do not inherit development relaxations.


## Overriding Configuration in Code

For tests or single-binary deployments you can bypass the environment and pass configuration directly. `velocity.New` accepts functional options.

### WithConfig

`WithConfig` supplies a fully-built `Config` struct, replacing `ConfigFromEnv()`:

```go
cfg := velocity.ConfigFromEnv()
cfg.Port = "8080"
cfg.Debug = true

v, err := velocity.New(velocity.WithConfig(cfg))
```

### Targeted Options

Smaller overrides have dedicated options:

```go
v, err := velocity.New(
    velocity.WithPort("8080"),
    velocity.WithReadTimeout(15*time.Second),
    velocity.WithWriteTimeout(15*time.Second),
    velocity.WithIdleTimeout(60*time.Second),
)
```

Other options include `velocity.WithModules(...)` to append modules, `velocity.WithSchedulerInProcess()` to run the scheduler inside the HTTP process, and `velocity.WithoutEvents()` / `velocity.WithFakeEvents(...)` for tests.

## Priority Order

Configuration values are resolved in this order:

1. **Functional options** passed to `velocity.New(...)` (highest priority, applied after the base config is built)
2. **Environment variables** (including those loaded from `.env`)
3. **Built-in defaults** (lowest priority)

```go
// DB_DATABASE from the environment is used as the base,
// but this code forces the port regardless of APP_PORT.
v, err := velocity.New(velocity.WithPort("9000"))
```

## Server Timeouts

HTTP server timeouts can be set through the environment or with the matching options:

| Variable | Option | Default |
|----------|--------|---------|
| `SERVER_READ_TIMEOUT` | `WithReadTimeout` | `30s` |
| `SERVER_WRITE_TIMEOUT` | `WithWriteTimeout` | `30s` |
| `SERVER_IDLE_TIMEOUT` | `WithIdleTimeout` | `120s` |
| `SERVER_READ_HEADER_TIMEOUT` | _(env only)_ | `10s` |


================================================================================
# velocity Commands

Source: https://vel.build/docs/cli/installer/
Section: CLI
Summary: Reference for the global `velocity` installer - scaffold new projects, manage CLI defaults, and keep the installer up to date.


`velocity` is the global installer CLI. You install it once
([installation](/docs/cli/installation)) and use it to create new
projects, configure defaults, and update itself.

Per-project commands (`serve`, `build`, `migrate`, `gen *`) live on
the `vel` binary inside each project - see [vel commands](/docs/cli/commands).

## velocity new

Create a new Velocity project.

```bash
velocity new <project-name> [flags]
```

| Flag                     | Default  | Description                                               |
| ------------------------ | -------- | --------------------------------------------------------- |
| `--database`             | `sqlite` | Database driver: `postgres`, `mysql`, `sqlite`            |
| `--cache`                | `memory` | Cache driver: `redis`, `memory`                           |
| `--stack`                | `react`  | Frontend stack for full-stack projects: `react`, `vue`    |
| `--api`                  | `false`  | API-only project (no frontend)                            |
| `--ssr`                  | `false`  | Enable Inertia SSR (sets `VIEW_SSR_ENABLED=true`, wires Vite SSR) |
| `-y`, `--non-interactive`| `false`  | Skip all prompts; use flag values or defaults             |

```bash
velocity new myapp
velocity new myapp --database postgres --cache redis
velocity new myapp --stack vue
velocity new myapi --api --database postgres
velocity new myapp --ssr
velocity new myapp -y --database postgres   # no prompts
```

### Interactive prompts

Run without `-y`/`--non-interactive`, any flag you don't pass is asked
interactively: project type (full stack vs API only), database, cache,
frontend stack (full-stack only), and SSR. A flag you _do_ pass is taken
as-is and not prompted. Pass `-y` (or set every relevant flag) to skip
prompts entirely - useful for scripts and CI.

### What `new` does

1. Fails fast if the destination path already exists.
2. Downloads the appropriate starter template as a tarball from GitHub
   (`velocity-template-react`, `velocity-template-vue`, or
   `velocity-template-api`), resolved live to that template's newest
   released tag (falling back to `main` when no tag is found). Falls back
   to `git clone` if the tarball fetch fails.
3. Rewrites the Go module name to match the project, and strips any local
   `replace` directive for the framework from `go.mod`.
4. Re-initialises git (removes the template's history, creates a fresh
   repo with an initial commit).
5. Creates default migrations when the template doesn't ship its own.
6. Writes `.env` from `.env.example` and seeds freshly generated
   `APP_KEY`, `QUEUE_SIGNING_KEY`, and `AUTH_JWT_SECRET`, then patches the
   chosen database, cache, and SSR settings.
7. Installs Go dependencies (`go mod tidy`) - plus JS dependencies
   (`bun install`, or `npm install` when bun is absent) on full-stack
   projects - and builds the project's `vel` binary concurrently.
8. Checks the database is reachable, then runs the initial migrations. If
   the database isn't ready, scaffolding still completes and the installer
   prints the remaining steps (`./vel migrate`, `./vel serve`) instead of
   failing.

When it finishes, the installer prints the next steps rather than starting
a server. `cd` into the project and run `./vel serve` (Go on `:4000`, Vite
on `:5173` for full-stack).

### API vs full-stack

The `--api` flag picks a different starter:

| Aspect           | Full-stack (default)              | `--api`                          |
| ---------------- | --------------------------------- | -------------------------------- |
| Frontend         | Vite + Inertia (React or Vue)     | None                             |
| CSRF             | Enabled                           | Disabled (stateless)             |
| Auth scheme      | `web` (`AUTH_SCHEME=web`)         | `api` (`AUTH_SCHEME=api`)        |
| Responses        | Inertia-rendered pages            | JSON (`ensure_json` middleware)  |
| Starter routes   | `/`, `/login`, `/register`, `/dashboard`, `/logout`, `/health` | `/health`, `/api/health` |

The `--stack` flag (`react` or `vue`) only applies to full-stack projects;
it's ignored with `--api`. You can't flip between modes after scaffolding -
choose up front.

## velocity config

Manage global CLI defaults stored on disk.

```bash
velocity config set <key> <value>
velocity config get <key>
velocity config list
velocity config reset
```

### Keys

Every key is unset until you set it - there are no seeded defaults. `set`
validates the value against the accepted set and rejects unknown keys.

| Key                 | Accepted values                  |
| ------------------- | -------------------------------- |
| `default.database`  | `postgres`, `mysql`, `sqlite`    |
| `default.cache`     | `redis`, `memory`                |
| `default.queue`     | `redis`, `database`              |
| `default.auth`      | `true`, `false`                  |
| `default.api`       | `true`, `false`                  |

### Examples

```bash
velocity config set default.database postgres
velocity config set default.cache redis
velocity config set default.api true

velocity config get default.database    # → postgres
velocity config list                    # all set values
velocity config reset                   # delete the config file
```

`get` prints the value, or `(not set)` for keys that are empty or `false`.
`list` shows only keys that have been set.

Configuration is stored at `~/.vel/config.yaml` (created with `0600`
permissions, written under a file lock so concurrent runs don't clobber
each other).

## velocity self-update

Fetch and install the latest installer release.

```bash
velocity self-update
```

It checks the latest GitHub release, and if you're already on it, reports
"Already up to date" and stops. Otherwise it downloads the archive for your
OS/architecture, verifies it against the release `checksums.txt`, extracts
the binary, and atomically replaces the running executable in place. On
macOS it also clears the download quarantine attribute.


If the installer was installed via Homebrew, `self-update` detects this and
declines, pointing you to `brew upgrade --cask velocity` instead - let the
package manager own the binary it installed.


## velocity --version

Print the installer version followed by the template tags it would scaffold.
Each stack resolves to its newest released tag (or `main` when no tag can be
resolved), so the output reflects the exact build coordinates of a fresh
project:

```bash
velocity --version
```

```
velocity 0.21.14
templates:
  api -> v0.x.y
  react -> v0.x.y
  vue -> v0.x.y
```

## Go version check

The installer verifies that Go is installed and meets the minimum
version (1.26 or higher) on every run. When the check fails it prints one
of the following and exits:

```
Go is not installed or not in PATH. Velocity requires Go 1.26 or higher.

Please install Go:
  brew install go

Or download from: https://go.dev/dl/
```

```
Go version go1.24.2 is not supported. Velocity requires Go 1.26 or higher.

Please upgrade Go:
  brew upgrade go

Or download from: https://go.dev/dl/
```

Install or upgrade Go and run the command again.


================================================================================
# Configuration

Source: https://vel.build/docs/core/config/
Section: Core Framework
Summary: Manage application configuration with environment variables and the structured velocity.Config struct in Velocity.


Velocity provides a simple yet powerful configuration system that reads from environment variables and a `.env` file, then exposes a single strongly-typed `velocity.Config` struct that every framework package consumes.

## Quick Start


**Environment-Based**: Velocity loads configuration from environment variables and an optional `.env` file, following the twelve-factor app methodology.





```go
import "github.com/velocitykode/velocity"

func main() {
    // velocity.New loads ConfigFromEnv() by default:
    // it reads .env (if present) and the process environment.
    app, err := velocity.New()
    if err != nil {
        panic(err)
    }

    if err := app.Serve(); err != nil {
        panic(err)
    }
}
```



```env
# .env file
APP_ENV=production
APP_DEBUG=false
APP_PORT=4000

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=myapp
DB_USERNAME=root
DB_PASSWORD=secret

# Cache
CACHE_DRIVER=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
```



```go
import "github.com/velocitykode/velocity"

func main() {
    // Build the config explicitly, then override New's env-loaded default.
    cfg := velocity.ConfigFromEnv()
    cfg.Port = "8080"

    app, err := velocity.New(velocity.WithConfig(cfg))
    if err != nil {
        panic(err)
    }
    _ = app
}
```




## How Configuration Loads

`velocity.New()` calls `ConfigFromEnv()` automatically, so a default app reads its
configuration from the environment with no extra wiring. The loader:

1. Calls `godotenv.Load()` to read a `.env` file from the working directory (if present).
   A `.env` that exists but fails to parse is logged as a warning, not a fatal error.
2. Reads every documented environment variable, applying defaults for unset values.
3. Returns a `velocity.Config` whose typed sub-structs (`DB`, `Cache`, `Queue`,
   `Storage`, `Session`, `Auth`, `CSRF`, `Crypto`, `Mail`, `View`, `Log`) are consumed
   by the matching framework packages.

```go
import "github.com/velocitykode/velocity"

func main() {
    cfg := velocity.ConfigFromEnv()

    // cfg.Env is the normalized (lowercased, trimmed) APP_ENV value.
    if cfg.Env == "production" && cfg.Debug {
        panic("APP_DEBUG must be false in production")
    }
}
```

You rarely need to call `ConfigFromEnv()` yourself. Use it only when you want to
inspect or mutate the config before passing it to `velocity.New` via `WithConfig`.

## The Config Struct

`velocity.Config` is the single source of truth for application configuration. The
top-level fields and their backing environment variables are:

```go
type Config struct {
    // App
    Env   string // APP_ENV, empty when unset
    Debug bool   // APP_DEBUG, default false
    Port  string // APP_PORT, default "4000"
    Key   string // APP_KEY (used for crypto)

    DB      DBConfig            // DB_*
    Auth    auth.Config         // AUTH_*
    Cache   CacheConfig         // CACHE_*, REDIS_*
    Log     log.LogConfig       // LOG_*
    Queue   QueueConfig         // QUEUE_*
    Storage StorageConfig       // STORAGE_*, FILESYSTEM_*, AWS_*
    CSRF    csrf.Config         // CSRF_*
    Session auth.SessionConfig  // SESSION_*
    View    view.Config         // VIEW_SSR_*
    Crypto  crypto.Config       // CRYPTO_*
    Mail    mail.MailConfig     // MAIL_*

    // Server timeouts
    ReadTimeout       time.Duration // SERVER_READ_TIMEOUT, default 30s
    WriteTimeout      time.Duration // SERVER_WRITE_TIMEOUT, default 30s
    IdleTimeout       time.Duration // SERVER_IDLE_TIMEOUT, default 120s
    ReadHeaderTimeout time.Duration // SERVER_READ_HEADER_TIMEOUT, default 10s

    // FileRoot bounds Context.File / Context.Download / Context.SaveFile.
    // Sourced from FILE_ROOT; defaults to the process working directory.
    FileRoot string
}
```

### Database Configuration

```go
type DBConfig struct {
    Connection      string        // DB_CONNECTION: sqlite, postgres, mysql
    Host            string        // DB_HOST, default "127.0.0.1"
    Port            string        // DB_PORT, default per driver (mysql 3306, postgres 5432)
    Database        string        // DB_DATABASE
    Username        string        // DB_USERNAME
    Password        string        // DB_PASSWORD
    Charset         string        // DB_CHARSET
    SSLMode         string        // DB_SSL_MODE (postgres)
    TLS             string        // DB_MYSQL_TLS (true/false/skip-verify/preferred)
    MaxIdleConns    int           // DB_MAX_IDLE_CONNS, default 10
    MaxOpenConns    int           // DB_MAX_OPEN_CONNS, default 100
    ConnMaxLifetime time.Duration // DB_CONN_MAX_LIFETIME (seconds), default 3600
    LogQueries      bool          // DB_LOG_QUERIES
    SlowThreshold   time.Duration // DB_SLOW_QUERY_THRESHOLD
}
```

### Cache Configuration

```go
type CacheConfig struct {
    Driver           string // CACHE_DRIVER: memory, file, redis, database (default "memory")
    Prefix           string // CACHE_PREFIX, default "velocity_cache"
    Path             string // CACHE_PATH (required when CACHE_DRIVER=file)
    MemoryMaxEntries int    // CACHE_MEMORY_MAX_ENTRIES (0 = 1,000,000, negative = unlimited)
    MaxValueBytes    int64  // CACHE_MAX_VALUE_BYTES (0 = unlimited)
    RedisHost        string // REDIS_HOST, default "127.0.0.1"
    RedisPort        int    // REDIS_PORT, default 6379
    RedisPassword    string // REDIS_PASSWORD
    RedisDatabase    int    // REDIS_DATABASE, default 0
    RedisTLS         bool   // REDIS_TLS
}
```

### Queue Configuration

```go
type QueueConfig struct {
    Driver        string // QUEUE_DRIVER: memory, redis, database (default "memory")
    RedisHost     string // QUEUE_REDIS_HOST, default "localhost"
    RedisPort     string // QUEUE_REDIS_PORT, default "6379"
    RedisPassword string // QUEUE_REDIS_PASSWORD
    RedisDB       string // QUEUE_REDIS_DB, default "0"
    RedisTLS      bool   // REDIS_TLS
    SigningKey    string // QUEUE_SIGNING_KEY: HMAC key for payload signing
    Encrypt       bool   // QUEUE_ENCRYPT: encrypt job payloads at rest
}
```

### Storage Configuration

```go
type StorageConfig struct {
    Default string                // STORAGE_DRIVER, default "local"
    Disks   map[string]DiskConfig // configured disks
}

type DiskConfig struct {
    Driver     string // "local", "s3", "memory"
    Root       string // root path for the local driver
    URL        string // base URL for file access
    Visibility string // default visibility (public/private)
    Bucket     string // s3
    Region     string // s3
    Key        string // s3
    Secret     string // s3
    MaxSize    int64  // memory driver max bytes
}
```

A `local` disk is always configured (root from `FILESYSTEM_LOCAL_ROOT`, default
`./storage/app`). An `s3` disk is added automatically when `AWS_BUCKET` is set, reading
`AWS_DEFAULT_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_URL`.

## Configuration Options

Pass `velocity.Option` functions to `velocity.New` to override the env-loaded config.

```go
import (
    "time"

    "github.com/velocitykode/velocity"
)

app, err := velocity.New(
    velocity.WithPort("8080"),
    velocity.WithReadTimeout(15*time.Second),
    velocity.WithWriteTimeout(15*time.Second),
    velocity.WithIdleTimeout(60*time.Second),
)
```

Available options include:

| Option | Effect |
| --- | --- |
| `WithConfig(cfg Config)` | Replace the entire configuration. |
| `WithPort(port string)` | Set the HTTP server port. |
| `WithReadTimeout(d time.Duration)` | Set the HTTP read timeout. |
| `WithWriteTimeout(d time.Duration)` | Set the HTTP write timeout. |
| `WithIdleTimeout(d time.Duration)` | Set the HTTP idle timeout. |
| `WithModules(modules ...app.Module)` | Append modules; they are initialized and started in the order given. |
| `WithoutEvents()` | Disable the event dispatcher entirely. |
| `WithFakeEvents(fake *events.FakeDispatcher)` | Record dispatched events for assertions. |
| `WithSchedulerInProcess()` | Run the scheduler loop in the same process as `Serve()`. |

## Validating Configuration

`velocity.New` calls `Config.Validate()` before allocating any resources, so malformed
values (an invalid `APP_PORT`, a negative timeout, an unknown `SESSION_SAME_SITE`, a
`file` cache driver without `CACHE_PATH`) fail fast with a clear error. You can also call
it yourself:

```go
import (
    "errors"

    "github.com/velocitykode/velocity"
)

cfg := velocity.ConfigFromEnv()
if err := cfg.Validate(); err != nil {
    if errors.Is(err, velocity.ErrInvalidConfig) {
        // configuration is structurally invalid
    }
    return err
}
```

`Validate()` performs structural checks only (port is numeric, timeouts are
non-negative, `SESSION_SAME_SITE` / `CSRF_SAME_SITE` are one of `strict|lax|none`, and
each sub-config's `Validate()` passes). It deliberately does not check driver names
against an allowlist: an unknown driver surfaces as a typed registry error when the
relevant subsystem resolves it. Every failure wraps the `velocity.ErrInvalidConfig`
sentinel so callers can branch with `errors.Is`.

## Logging Configuration

The root config stores logging settings in `Config.Log`, a `log.LogConfig`:

```go
import "github.com/velocitykode/velocity/log"

type LogConfig struct {
    // Driver: "console", "file", "stack", "null", or a registered driver.
    Driver string
    // Config holds driver-specific options, e.g. "path" for file,
    // "level" for any driver, "stack" with a []string of channel names.
    Config map[string]any
}
```

`ConfigFromEnv()` populates it from `LOG_DRIVER` (default `console`), `LOG_PATH`,
`LOG_LEVEL` (default `debug`), `LOG_DAYS` (default 14), and `LOG_STACK` (a
comma-separated list of channel names for the `stack` driver).

The `log` package also exposes a multi-channel `LoggingConfig` for applications that
define named channels:

```go
import "github.com/velocitykode/velocity/log"

cfg := log.LoggingConfig{
    Default: "stack",
    Channels: map[string]log.ChannelConfig{
        "daily": {Driver: "file", Level: "debug", Path: "./storage/logs", MaxAge: 14},
    },
}

if channel, ok := cfg.GetChannel("daily"); ok {
    _ = channel.Driver
}

if channel, ok := cfg.GetDefaultChannel(); ok {
    _ = channel.Driver
}
```

```go
type ChannelConfig struct {
    Driver  string         // file, console, syslog, null
    Level   string         // debug, info, warn, error
    Path    string         // file path (for file driver)
    MaxAge  int            // max age in days
    Options map[string]any // driver-specific options
}
```

## Environment Variables Reference

A representative `.env` covering the most common settings:

```env
# Application
APP_ENV=production
APP_DEBUG=false
APP_PORT=4000
APP_KEY=base64:your-32-byte-base64-encoded-key

# Crypto
CRYPTO_KEY=base64:your-32-byte-base64-encoded-key
CRYPTO_CIPHER=AES-256-GCM

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=velocity
DB_USERNAME=root
DB_PASSWORD=

# Cache
CACHE_DRIVER=redis
CACHE_PREFIX=velocity_cache
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DATABASE=0

# Logging
LOG_DRIVER=file
LOG_PATH=./storage/logs
LOG_LEVEL=debug
LOG_DAYS=14

# Queue
QUEUE_DRIVER=memory
QUEUE_REDIS_HOST=localhost
QUEUE_REDIS_PORT=6379

# Mail
MAIL_DRIVER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="${APP_NAME}"

# Session
SESSION_NAME=velocity_session
SESSION_LIFETIME=120
SESSION_SECURE=true
SESSION_HTTP_ONLY=true
SESSION_SAME_SITE=lax

# Server timeouts (accepts Go duration syntax, e.g. 30s)
SERVER_READ_TIMEOUT=30s
SERVER_WRITE_TIMEOUT=30s
SERVER_IDLE_TIMEOUT=120s
```


**Defaults that differ from common expectations**: `MAIL_DRIVER` defaults to `log`
(captured, not sent), `CRYPTO_CIPHER` defaults to `AES-256-GCM`, `CACHE_DRIVER` and
`QUEUE_DRIVER` default to `memory`, `SESSION_SECURE` defaults to `true` (only the literal
`false` disables it), and `DB_HOST` / `REDIS_HOST` default to `127.0.0.1`.


## Environment-Specific Configuration

Velocity classifies `APP_ENV` through the canonical reader, so security gates relax only
when you explicitly opt into a non-production profile. An unset `APP_ENV` is treated as
production (fail-secure).

### Development

```env
APP_ENV=development
APP_DEBUG=true
APP_PORT=4000

LOG_LEVEL=debug
LOG_DRIVER=console

CACHE_DRIVER=memory
QUEUE_DRIVER=memory

DB_HOST=127.0.0.1
DB_DATABASE=myapp_dev
```

### Production

```env
APP_ENV=production
APP_DEBUG=false

LOG_LEVEL=info
LOG_DRIVER=file

CACHE_DRIVER=redis
QUEUE_DRIVER=redis

DB_HOST=db.example.com
DB_DATABASE=myapp_prod
```

### Testing

```env
APP_ENV=testing
APP_DEBUG=true

LOG_LEVEL=error
LOG_DRIVER=null

CACHE_DRIVER=memory
QUEUE_DRIVER=memory

DB_CONNECTION=sqlite
DB_DATABASE=:memory:
```

## Security Best Practices

### Sensitive Data

Never commit secrets to version control:

```bash
# .gitignore
.env
.env.local
.env.production
.env.*.local
```

### Environment Template

Provide a template for required variables:

```env
# .env.example
APP_ENV=development
APP_DEBUG=true
APP_PORT=4000
APP_KEY=

# Database (required)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=
DB_USERNAME=
DB_PASSWORD=

# Crypto (required for production)
CRYPTO_KEY=
```

## Testing Configuration

In tests, build a `velocity.Config` directly and pass it with `WithConfig` rather than
relying on the environment:

```go
import (
    "testing"

    "github.com/velocitykode/velocity"
    "github.com/velocitykode/velocity/log"
    "github.com/velocitykode/velocity/mail"
)

func TestApp(t *testing.T) {
    app, err := velocity.New(velocity.WithConfig(velocity.Config{
        Env:   "testing",
        Debug: true,
        Port:  "0",
        Cache: velocity.CacheConfig{Driver: "memory", Prefix: "test_cache"},
        Log:   log.LogConfig{Driver: "null", Config: make(map[string]any)},
        Queue: velocity.QueueConfig{Driver: "memory"},
        Mail:  mail.MailConfig{Driver: "log"},
    }))
    if err != nil {
        t.Fatalf("New() error: %v", err)
    }
    _ = app
}
```

You can also point the loader at a dedicated env file before constructing the app:

```go
func TestMain(m *testing.M) {
    _ = godotenv.Load(".env.testing")
    os.Exit(m.Run())
}
```

## Docker Integration

### Docker Compose

```yaml
# docker-compose.yml
services:
  app:
    build: .
    ports:
      - "4000:4000"
    environment:
      - APP_ENV=production
      - APP_DEBUG=false
      - APP_PORT=4000
      - DB_HOST=db
      - DB_DATABASE=myapp
      - DB_USERNAME=root
      - DB_PASSWORD=secret
      - REDIS_HOST=redis
    depends_on:
      - db
      - redis

  db:
    image: mysql:8
    environment:
      - MYSQL_ROOT_PASSWORD=secret
      - MYSQL_DATABASE=myapp

  redis:
    image: redis:alpine
```

## Best Practices

1. **Let `New()` load config**: a plain `velocity.New()` reads `.env` and the environment for you.
2. **Override via options**: use `WithConfig` / `WithPort` / `WithReadTimeout` instead of mutating globals.
3. **Validate early**: `Config.Validate()` runs inside `New()`; call it yourself when building config manually.
4. **Provide defaults**: keep an `.env.example` documenting every variable.
5. **Environment-specific files**: use `.env`, `.env.testing`, etc., for different profiles.
6. **Security**: never commit `.env` files; set `APP_KEY` / `CRYPTO_KEY` in production.
7. **Fail-secure env**: leave `APP_ENV` unset only when you intend production-grade defaults.


================================================================================
# Authentication

Source: https://vel.build/docs/core/authentication/
Section: Core Framework
Summary: Implement user login, registration, password hashing, and session management with Velocity's auth system.


Velocity provides a powerful authentication system that handles user login, registration, password hashing, and session management out of the box.

## Setup

### Environment Configuration

Configure authentication in your `.env` file:

```env
# Crypto settings (required for session encryption)
CRYPTO_KEY=base64:your-32-byte-base64-encoded-key
CRYPTO_CIPHER=AES-256-GCM

# Auth settings
AUTH_SCHEME=web
HASH_BCRYPT_COST=10

# Session settings
SESSION_NAME=velocity_session
SESSION_LIFETIME=120
SESSION_PATH=/
SESSION_SECURE=true
SESSION_HTTP_ONLY=true
SESSION_SAME_SITE=lax
```

### Initialization

When you boot the app via `velocity.New()`, the framework reads `AUTH_SCHEME`, `HASH_BCRYPT_COST`, and the `SESSION_*` variables, builds an `auth.Manager`, installs an ORM-backed user store, and wires a `SessionScheme` against the encrypted-cookie store. No manual wiring is required for the common case.

`AUTH_SCHEME` is load-bearing twice over: it names the default scheme, and a non-empty value is what makes `ConfigFromEnv` build the scheme configs at all. The map keys it builds are `web` and `session` (driver `session`) plus `api` and `jwt` (driver `jwt`, skipped when `AUTH_JWT_SECRET` is empty). Leave `AUTH_SCHEME` unset and the app boots with no schemes registered.

If you need to construct the manager yourself (custom scheme, embedded use, tests), the underlying API is:

```go
package main

import (
    "net/http"

    "github.com/velocitykode/velocity/auth"
    "github.com/velocitykode/velocity/auth/drivers/schemes"
    "github.com/velocitykode/velocity/auth/stores/ormauth"
    "github.com/velocitykode/velocity/crypto"

    "myapp/internal/models"
)

func buildAuth(enc crypto.Encryptor) (*auth.Manager, error) {
    manager := auth.NewManager()

    // User store: ORM-backed lookup for the model you authenticate.
    userStore := ormauth.New[models.User](ormauth.WithHasher(manager.GetHasher()))
    if err := userStore.Validate(); err != nil {
        return nil, err
    }
    manager.SetUserStore(userStore)

    // Scheme: encrypted-cookie session store.
    sessionScheme, err := schemes.NewSessionScheme(userStore, auth.SessionConfig{
        Name:     "velocity_session",
        Lifetime: 120,
        Path:     "/",
        Secure:   true,
        HttpOnly: true,
        SameSite: http.SameSiteLaxMode,
    }, enc)
    if err != nil {
        return nil, err
    }
    manager.RegisterScheme("web", sessionScheme)
    manager.SetDefaultScheme("web")

    return manager, nil
}
```

`SetUserStore` installs the single canonical user store (under `auth.DefaultUserStoreName`, value `"default"`) and re-points every scheme already registered, so construction order does not matter. `RegisterUserStore(name, store)` is the code-level escape hatch for the uncommon app that authenticates two separate identity stores in one process, an admin panel colocated with a customer app, for example. Schemes are not notified in that case, so you hand the store to whichever scheme should use it yourself. There is no per-scheme user-store field in `auth.SchemeConfig`.

Inside a handler you reach the manager through `auth.FromContext(ctx)`:

```go
import "github.com/velocitykode/velocity/auth"

m := auth.FromContext(ctx) // *auth.Manager, or nil if auth is not configured
```

Outside a request, in a module lifecycle hook, use `auth.FromServices(s)`.

### Choosing the auth model

The model that authenticates is chosen in code, not in `.env`. The ORM resolves a table from a compile-time Go type, and Go cannot turn the string `"Admin"` into a type, so the model is a type parameter. Editing it is a compile error when you get it wrong, rather than a boot failure:

```go
import "github.com/velocitykode/velocity"

func (m *AppModule) Init(s *velocity.Services) error {
    return velocity.SetAuthModel[models.User](s)
}
```

`velocity.SetAuthModel[T]` validates the model, inherits the auth manager's hasher (so the operator-configured bcrypt cost is preserved), and installs the resulting user store. It returns `velocity.ErrAuthNotConfigured` when the app has no auth manager, which means `velocity.New` built no schemes because `AUTH_SCHEME` was unset.

A model whose columns differ from the defaults (`email`, `password`, `remember_token`) names them with the re-exported options:

```go
func (m *AppModule) Init(s *velocity.Services) error {
    return velocity.SetAuthModel[models.Admin](s,
        velocity.WithAuthIdentifierColumn("username"),
        velocity.WithAuthPasswordColumn("pass_hash"),
    )
}
```

The full option set is `velocity.WithAuthIdentifierColumn`, `velocity.WithAuthPasswordColumn`, `velocity.WithAuthRememberTokenColumn`, and `velocity.WithAuthCredentialsKey` (the key read from the credentials map when it differs from the identifier column, e.g. a form posting `email` against a `users.username` column). All four are aliases of the `ormauth.With*` options, so application code never has to import the store package.

If you want the store itself rather than an installed one, to hand it to a second scheme or to inspect it in a test, `velocity.ORMUserStore[T](opts...)` builds it without installing. The direct form is equivalent:

```go
import (
    "github.com/velocitykode/velocity"
    "github.com/velocitykode/velocity/auth"
    "github.com/velocitykode/velocity/auth/stores/ormauth"
)

func (m *AuthModule) Start(s *velocity.Services) error {
    userStore := ormauth.New[models.Admin](
        ormauth.WithIdentifierColumn("username"),
    )
    if err := userStore.Validate(); err != nil {
        return err
    }

    manager := auth.FromServices(s)
    if manager == nil {
        return velocity.ErrAuthNotConfigured
    }
    manager.SetUserStore(userStore)
    return nil
}
```

`Services.Auth` is typed as `contract.AuthManager`, which carries only `Allows` and `Authorize`, so reach the concrete `*auth.Manager` through `auth.FromServices(s)` before calling `SetUserStore`.

Call it from a module's `Init` or `Start`. `velocity.New` has already built the schemes against the framework's built-in model, and installing a user store re-points every one of them, so ordering does not matter.


An app that configures nothing gets `ormauth.New[ormauth.User]` against the `users` table, reproducing the column set the framework used to hardcode (`id`, `name`, `email`, `password`, `remember_token`).


### User Model Requirements

A model is usable as an auth model when it either implements `auth.Authenticatable` itself (preferred, since it skips the reflection-based column mapping entirely) or exposes the identifier, password, and remember-token columns that `ormauth` maps onto that interface.

It must also declare a mass-assignment policy that permits the remember-token column. The token is persisted through the ORM's map-based update path, which is deny-by-default: a model declaring no policy at all rejects every key, so remember-me would fail on first use. `Store.Validate` refuses at startup instead.

```go
type User struct {
    orm.IDInt[User]
    Name          string  `orm:"column:name" json:"name"`
    Email         string  `orm:"column:email" json:"email"`
    Password      string  `orm:"column:password" json:"-"`
    RememberToken *string `orm:"column:remember_token" json:"-"`
}

// AssignableFields declares the mass-assignment allowlist. Without a
// declared policy (AssignableFields, ProtectedFields, or AllowAllColumns)
// the ORM denies every map-based write, including the remember-token update.
func (User) AssignableFields() []string {
    return []string{"name", "email", "password", "remember_token"}
}

// GetAuthIdentifier returns the user's unique identifier
func (u *User) GetAuthIdentifier() interface{} {
    return u.ID
}

// GetAuthPassword returns the user's hashed password
func (u *User) GetAuthPassword() string {
    return u.Password
}

// GetRememberToken returns the remember token, or "" when the column is NULL
func (u *User) GetRememberToken() string {
    if u.RememberToken == nil {
        return ""
    }
    return *u.RememberToken
}

// SetRememberToken sets the remember token
func (u *User) SetRememberToken(token string) {
    u.RememberToken = &token
}
```

Two shape details are load-bearing. `RememberToken` is a `*string` because the column is nullable for users who have never used remember-me, and scanning SQL NULL into a plain `string` is a driver error. Composing `orm.IDInt[User]` rather than `orm.Model[User]` keeps the ORM from stamping `updated_at` on every remember-token rotation, which happens on every remember-me recall; use `orm.Model[User]` only when you actually want login traffic touching `users.updated_at`.

## Quick Start

Using authentication in handlers:

```go
import (
    "github.com/velocitykode/velocity/auth"
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/view"
)

func (c *AuthHandler) Login(ctx *router.Context) error {
    var formData struct {
        Email    string `json:"email"`
        Password string `json:"password"`
        Remember bool   `json:"remember"`
    }

    if err := ctx.Bind(&formData); err != nil {
        formData.Email = ctx.Request.FormValue("email")
        formData.Password = ctx.Request.FormValue("password")
        formData.Remember = ctx.Request.FormValue("remember") == "on"
    }

    credentials := map[string]interface{}{
        "email":    formData.Email,
        "password": formData.Password,
    }

    m := auth.FromContext(ctx)
    success, _ := m.Attempt(ctx.Response, ctx.Request, credentials, formData.Remember)

    if success {
        view.Location(ctx, "/dashboard")
    } else {
        view.Render(ctx, "Auth/Login", view.Props{
            "errors": map[string]string{
                "email": "These credentials do not match our records.",
            },
        })
    }
    return nil
}
```

## User Authentication

### Login Attempts

```go
m := auth.FromContext(ctx)

credentials := map[string]interface{}{
    "email":    "user@example.com",
    "password": "secret123",
}

success, err := m.Attempt(ctx.Response, ctx.Request, credentials, false)
if err != nil {
    // err is auth.ErrLoginThrottled when the configured throttler rejected
    // the attempt before credentials were even checked.
    return err
}
if success {
    user := m.User(ctx.Request)
    log.Info("User logged in", "user_id", user.GetAuthIdentifier())
}
```

### Remember Me Functionality

```go
// Login with "remember me" for extended sessions
m := auth.FromContext(ctx)
success, _ := m.Attempt(ctx.Response, ctx.Request, credentials, true)
if success {
    user := m.User(ctx.Request)
    log.Info("User logged in with remember me", "user_id", user.GetAuthIdentifier())
}
```

### Checking Authentication Status

```go
m := auth.FromContext(ctx)

if m.Check(ctx.Request) {
    user := m.User(ctx.Request)
    if user != nil {
        log.Info("Authenticated user", "user_id", user.GetAuthIdentifier())
    }
} else {
    return ctx.Redirect(http.StatusFound, "/login")
}
```

### Logout

```go
func LogoutHandler(ctx *router.Context) error {
    m := auth.FromContext(ctx)
    if err := m.Logout(ctx.Response, ctx.Request); err != nil {
        return err
    }
    view.Location(ctx, "/login")
    return nil
}
```

## Password Hashing

Password hashing lives on the manager so the bcrypt cost configured in `HASH_BCRYPT_COST` is honored uniformly.

### Hash Passwords

```go
m := auth.FromContext(ctx)

password := "user_password_123"
hashedPassword, err := m.Hash(password)
if err != nil {
    log.Error("Failed to hash password", "error", err)
    return err
}

// Store hashedPassword in database
user.Password = hashedPassword
```

### Verify Passwords

```go
m := auth.FromContext(ctx)

if m.Verify(providedPassword, user.Password) {
    log.Info("Password verification successful")
} else {
    log.Warn("Password verification failed")
}
```

If you need a hasher outside a request (a CLI seeder, for example), construct one directly with `auth.NewBcryptHasher(cost)` and call `Hash` / `Verify` on it. The minimum cost is clamped to 10 with a warning.

## User Interface

### Authenticatable Interface

`auth.Authenticatable` is the contract every authenticated user satisfies:

```go
// auth.Authenticatable (auth/auth.go)
type Authenticatable interface {
    GetAuthIdentifier() interface{}
    GetAuthPassword() string
    GetRememberToken() string
    SetRememberToken(token string)
}
```

Implementing it on your model directly is the preferred path (see [User Model Requirements](#user-model-requirements)). A model that does not implement it is still usable: `ormauth` maps the configured identifier, password, and remember-token columns onto the interface through ORM metadata, at the cost of reflection on the lookup path.

### Custom User Stores

`auth.UserStore` is the interface behind user lookup. It threads a `context.Context` through every method that does I/O so a cancelled request (client disconnect, timeout middleware) aborts the lookup. Each I/O method comes in a pair: a `Ctx`-suffixed variant that does the real work, and a deprecated non-`Ctx` shim that delegates with `context.Background()`. Implement all six methods plus `ValidateCredentials` (pure CPU, so no `Ctx` variant):

```go
// Implement auth.UserStore for custom user retrieval
type CustomUserStore struct {
    db *sql.DB
}

func (s *CustomUserStore) FindByIDCtx(ctx context.Context, id interface{}) (auth.Authenticatable, error) {
    var user User
    err := s.db.QueryRowContext(ctx, "SELECT id, email, password, name FROM users WHERE id = $1", id).
        Scan(&user.ID, &user.Email, &user.Password, &user.Name)
    if err != nil {
        return nil, err
    }
    return &user, nil
}

// Deprecated: use FindByIDCtx with a request-scoped context.Context.
func (s *CustomUserStore) FindByID(id interface{}) (auth.Authenticatable, error) {
    return s.FindByIDCtx(context.Background(), id)
}

func (s *CustomUserStore) FindByCredentialsCtx(ctx context.Context, credentials map[string]interface{}) (auth.Authenticatable, error) {
    email := credentials["email"].(string)
    var user User
    err := s.db.QueryRowContext(ctx, "SELECT id, email, password, name FROM users WHERE email = $1", email).
        Scan(&user.ID, &user.Email, &user.Password, &user.Name)
    if err != nil {
        return nil, err
    }
    return &user, nil
}

// Deprecated: use FindByCredentialsCtx with a request-scoped context.Context.
func (s *CustomUserStore) FindByCredentials(credentials map[string]interface{}) (auth.Authenticatable, error) {
    return s.FindByCredentialsCtx(context.Background(), credentials)
}

func (s *CustomUserStore) ValidateCredentials(user auth.Authenticatable, credentials map[string]interface{}) bool {
    password, _ := credentials["password"].(string)
    return auth.NewBcryptHasher(10).Verify(password, user.GetAuthPassword())
}

func (s *CustomUserStore) UpdateRememberTokenCtx(ctx context.Context, user auth.Authenticatable, token string) error {
    user.SetRememberToken(token)
    _, err := s.db.ExecContext(ctx, "UPDATE users SET remember_token = $1 WHERE id = $2", token, user.GetAuthIdentifier())
    return err
}

// Deprecated: use UpdateRememberTokenCtx with a request-scoped context.Context.
func (s *CustomUserStore) UpdateRememberToken(user auth.Authenticatable, token string) error {
    return s.UpdateRememberTokenCtx(context.Background(), user, token)
}
```

Install it with `manager.SetUserStore(store)`, which fans out to every registered scheme.

For atomic rotate-on-use of the remember-me credential, a user store may additionally implement `auth.RememberTokenCompareAndSwapper` (`CompareAndSwapRememberToken(ctx, user, oldToken, newToken) (swapped bool, err error)`); `SessionScheme` recall persists rotation exclusively through it. A user store that does not implement it fails remember-cookie recall closed: remember cookies are still issued at login, but can never revive a session.

The interface has an executable specification. Run it against your implementation with `authtest.RunUserStoreContractTests` from `github.com/velocitykode/velocity/auth/authtest`:

```go
func TestCustomUserStore(t *testing.T) {
    authtest.RunUserStoreContractTests(t, authtest.UserStoreFactory{
        New:          func(t *testing.T) auth.UserStore { return newSeededStore(t) },
        SeedUser:     seedUser,
        SeedEmail:    "user@example.com",
        SeedPassword: "secret123",
    })
}
```

## Middleware Integration

### Auth Middleware

Use `auth.AuthMiddleware` to require authentication on a route. It returns 401 JSON for API requests and redirects HTML requests to a clean `/login` (303 See Other). The originally requested GET URL is stashed server-side in the session rather than exposed as a `?redirect=` query parameter, so it cannot be tampered with; `ctx.RedirectToIntended(fallback)` pulls it back after a successful login.

```go
import "github.com/velocitykode/velocity/auth"

r.Get("/dashboard", dashboardHandler.Index, auth.AuthMiddleware(manager))
```

For role- or ability-based access checks, the package also exposes `auth.RequireRole`, `auth.RequireAnyRole`, `auth.RequireAllRoles`, and `auth.AuthorizeMiddleware`. All of them deny with 401 when the request is unauthenticated and 403 when the policy fails. They resolve through the manager's authorizer, `auth.Access`, reachable as `manager.Access()`; `manager.Allows(r, ability, args...)` and `manager.Authorize(r, ability, args...)` are the `contract.AuthManager` methods that wrap it for a request.

### Guest Middleware

`auth.GuestMiddleware` blocks already-authenticated users from login/register pages. Pass a redirect path with `auth.GuestMiddlewareWithRedirect`.

```go
r.Get("/login",    authHandler.ShowLoginForm,    auth.GuestMiddlewareWithRedirect(manager, "/dashboard"))
r.Get("/register", authHandler.ShowRegisterForm, auth.GuestMiddlewareWithRedirect(manager, "/dashboard"))
```

## Session Management

### Session Configuration

Configure sessions in your `.env` file:

```env
# Session settings
SESSION_NAME=velocity_session
SESSION_LIFETIME=120          # Minutes
SESSION_PATH=/
SESSION_DOMAIN=
SESSION_SECURE=true           # HTTPS only
SESSION_HTTP_ONLY=true        # No JavaScript access
SESSION_SAME_SITE=lax         # CSRF protection
```

### Session Backends

Cookie-encrypted sessions are the default, but they are not the only option. The framework defines a `SessionStore` interface so you can swap in a server-side store (for example a Redis- or DB-backed implementation) without changing handler code. The interface lives in `auth/session.go`:

```go
// auth.Session is the value handed to handlers.
type Session interface {
    ID() string
    Get(key string) interface{}
    Put(key string, value interface{})
    Has(key string) bool
    Remove(key string)
    Clear()
    Regenerate() error
    Invalidate() error
    Flash(key string, value interface{})
    GetFlash(key string) interface{}
    FlushFlash() map[string]interface{}
    Save(w http.ResponseWriter) error
}

// auth.SessionStore is what backends implement.
type SessionStore interface {
    Create(id string) (Session, error)
    Get(r *http.Request, id string) (Session, error)
    Save(w http.ResponseWriter, session Session) error
    Destroy(id string) error
    GarbageCollect(maxLifetime time.Duration) error
}
```

The shipped implementation is `auth/drivers/session.CookieStore` (encrypted cookies, with `auth.SessionConfig` controlling cookie attributes). To plug in a custom backend, implement `SessionStore`, construct a `SessionScheme` against it, and register that scheme with the manager. `SessionScheme` accepts whichever store it is given because it talks to the interface, not the cookie struct directly.

For ad-hoc reads you can also call `auth.GetSessionFromRequest(r, store, cookieName)` to resolve a session from a request when you have a store reference outside of scheme code.

`auth.SessionConfig.Validate(env)` enforces safe defaults: `HttpOnly` must be true unless `AllowJSAccess` is explicitly set, `Secure` must be true outside `testing`/`development`, `SameSite` must be non-zero, and `SameSite=None` requires `Secure=true`. Failing this returns `auth.ErrInsecureSessionConfig`, so bootstrap code can fail fast in production and log-then-continue in dev.

#### Server-side session store

The cookie-side `SessionStore` carries per-request state, but it cannot answer two product questions you will eventually need to answer: "log me out everywhere" and "show me my active devices." Both require the server to know which session ids belong to which user, which a stateless cookie cannot tell you. The framework exposes a parallel `auth.ServerSessionStore` interface for that record:

```go
// auth.ServerSessionStore (auth/server_session_store.go)
type ServerSessionStore interface {
    Get(ctx context.Context, id string) (*StoredSession, error)
    Put(ctx context.Context, session *StoredSession) error
    Touch(ctx context.Context, id string, lastSeen time.Time) error
    Delete(ctx context.Context, id string) error
    DeleteAllForUser(ctx context.Context, userID string) error
    ListForUser(ctx context.Context, userID string) ([]*SessionMeta, error)
}
```

`auth.StoredSession` is the full record (`ID`, `UserID`, `Data map[string]any`, `CreatedAt`, `LastSeenAt`, `ExpiresAt`, `IPAddress`, `UserAgent`). `auth.SessionMeta` is the listing-only projection: same fields minus `Data`, so administrative listings cannot leak per-session payloads. Sentinel errors are `auth.ErrSessionNotFound`, `auth.ErrSessionExpired` (returned by `Get` after evicting the expired record), and `auth.ErrNoServerSessionStore` (returned by the manager helpers below when no store is installed).

`Put` is the login-time write only: it creates or replaces the record. The per-request activity refresh (the debounced `LastSeenAt` write the session scheme issues on every authenticated request) goes through `Touch`, which is update-if-present and returns `auth.ErrSessionNotFound` when the record is gone. That distinction is what makes revocation stick: if an administrator deletes the session between the scheme's read and its refresh write, `Touch` cannot recreate the row, and the scheme denies the request that lost the race. When you implement your own store, `Touch` must never insert, and your application code must not call `Put` to record activity.


You usually want both. The encrypted cookie store handles per-request reads and writes with no I/O. The server store underwrites administrative operations only, without it `RevokeSession` and `ListActiveSessions` return `ErrNoServerSessionStore`.


Two drivers ship in `auth/drivers/session`:

- **`session.NewCacheStore(backend)`** is the production driver. It keeps the records in a velocity cache store, so every app instance sharing the same Redis sees the same sessions and a revocation issued on one replica is enforced on all of them. Its writes are atomic on the backend: the per-user index is a backend set (`contract.CacheSetStore`, Redis `SADD`/`SREM`), `Touch` goes through `contract.CacheReplacer` (Redis `SET XX`) so a refresh can never recreate a deleted record, and `DeleteAllForUser` rotates a per-user generation token before it touches the index, with `Get` rejecting any record issued under an older token. That last part is what makes "sign out everywhere" authoritative even if the index is incomplete. Every record is stamped with a token from `Put` on, and a token the backend cannot serve fails closed: the session is rejected, never assumed pre-revocation. The index expiry is extend-only, so a short-lived login after a long-lived one never shortens the listing's life. The backend must implement both capabilities; the memory and redis cache drivers do, the file driver does not, and `NewCacheStore` returns `session.ErrCacheStoreUnsupported` at boot rather than failing at the first revocation.
- **`session.NewMemoryStore()`** is an in-process implementation for development, tests, and single-process deployments. It is `sync.RWMutex`-protected, maintains a secondary `userID -> {sessionID}` index so `DeleteAllForUser` and `ListForUser` are O(sessions-for-user), and runs a background sweep goroutine (default cadence 1 minute, override with `session.WithSweepInterval(d)`) that reaps expired records. The sweep is started by `NewMemoryStore` via `async.Go`, so a panic inside the loop is reported through the framework panic handler rather than crashing the process. `Close(ctx)` stops the sweep and is idempotent.

Wire one at bootstrap and the manager helpers light up:

```go
import (
    "github.com/velocitykode/velocity/auth"
    "github.com/velocitykode/velocity/auth/drivers/session"
)

// Production: share the app's cache backend (CACHE_DRIVER=redis).
backend, err := s.Cache.DefaultStore()
if err != nil {
    return err
}
store, err := session.NewCacheStore(backend)
if err != nil {
    return err
}
manager.SetServerSessionStore(store)

// Development / tests:
manager.SetServerSessionStore(session.NewMemoryStore())
```

Once installed, three methods on `*auth.Manager` cover the administrative surface:

- `RevokeSession(ctx, sessionID) error`: single-session logout (e.g. "log out this device").
- `RevokeAllSessions(ctx, userID) error`: bulk revoke (e.g. "log out everywhere", post-password-change).
- `ListActiveSessions(ctx, userID) ([]*SessionMeta, error)`: feed the "your devices" UI.

All three return `auth.ErrNoServerSessionStore` when no store is configured, so callers can branch on missing capability without a nil-check dance. `SetServerSessionStore(nil)` removes a previously installed store.

##### Recipe: Log out all sessions on password change

**When:** A user changes their password from the account settings page. Anyone holding a session cookie issued before the change should be evicted, including other browsers, mobile apps, and the attacker the user is currently kicking out.

**Code:**

```go
func (h *AccountHandler) ChangePassword(ctx *router.Context) error {
    m := auth.FromContext(ctx)
    user := m.User(ctx.Request)
    if user == nil {
        return ctx.Error(http.StatusUnauthorized, "unauthorized")
    }

    // ... validate current password, hash new one, persist ...

    userID := fmt.Sprint(user.GetAuthIdentifier())
    if err := m.RevokeAllSessions(ctx.Request.Context(), userID); err != nil &&
        !errors.Is(err, auth.ErrNoServerSessionStore) {
        return err
    }

    // The current request's cookie is also gone now; re-issue a session
    // for this device so the user is not bounced to /login mid-flow.
    credentials := map[string]interface{}{
        "email":    user.(*models.User).Email,
        "password": newPassword,
    }
    _, _ = m.Attempt(ctx.Response, ctx.Request, credentials, false)
    return nil
}
```

**Why this shape:** `RevokeAllSessions` walks the secondary `userID -> {sessionID}` index and deletes every record in one shot, so the call is cheap even for users with many devices. Tolerating `ErrNoServerSessionStore` keeps the same handler usable in environments that have not yet provisioned a server-side store (e.g. local dev). Re-attempting after the bulk revoke gives the current request a fresh cookie tied to a brand-new server-side record, which is what you want: the password change should not log out the device performing it.

### LoginThrottler

`SessionScheme.Attempt` (and `JWTScheme.Attempt`) consult a `contract.LoginThrottler` before checking credentials. The interface is the seam for credential-stuffing defense:

```go
// contract.LoginThrottler
type LoginThrottler interface {
    Allow(r *http.Request, key string) bool
    RecordFailure(r *http.Request, key string)
    RecordSuccess(r *http.Request, key string)
}
```

Contract:

- `Allow(r, key)` runs before the credential check. Returning `false` short-circuits the attempt with `auth.ErrLoginThrottled`.
- `RecordFailure(r, key)` runs when credential validation fails.
- `RecordSuccess(r, key)` runs after a successful login; a good implementation clears the failure counter for that key.

The default throttler is `auth.NoopLoginThrottler{}`, which permits every attempt. Install a real one with `scheme.SetLoginThrottler(yourThrottler)` (passing `nil` reverts to the no-op), or with `manager.SetLoginThrottler(yourThrottler)` to reach every scheme that implements `auth.LoginThrottlerReceiver`, including schemes registered later.

The framework also exposes `auth.ThrottleKey(r, credentials, trustedProxies)`, which derives the rate-limit key for the `(identifier, IP)` pair dimension as a length-bounded SHA-256 digest prefixed with `login:`. The `identifier` is the first non-empty value among `email`, `username`, `name`, `login` in the credentials map (normalised: trimmed, NFKC-folded, lowercased), and the client IP is resolved through the trusted-proxy list (pass `nil` to ignore forwarded headers, the secure default). Use it so a custom scheme wrapper produces keys consistent with the built-in schemes.

The built-in schemes actually consult `auth.ThrottleKeys(r, credentials, trustedProxies)`, which returns up to three keys, one per throttle dimension: the `(identifier, IP)` pair (always present, prefix `auth.ThrottleKeyPairPrefix`), the per-identifier key (prefix `auth.ThrottleKeyIdentifierPrefix`, omitted when no identifier is present), and the per-IP key (prefix `auth.ThrottleKeyIPPrefix`, omitted when the IP cannot be resolved). A throttler can branch on those prefixes to apply an independent cap per dimension.

## Two-factor authentication

Velocity ships RFC 6238 TOTP (time-based one-time passwords) plus single-use recovery codes. The surface lives in `auth/totp.go`; everything is HMAC-SHA1, 6-digit, 30-second period by default, matching what Google Authenticator, 1Password, Authy, and friends speak out of the box. The package-level `auth.TOTP` is a pre-configured `*TOTPGenerator` with `Skew: 1` (previous, current, and next windows are accepted on verify), which is the right default for almost every app. Construct your own with `auth.NewTOTP(auth.TOTPConfig{...})` if you need to override `Issuer`, `Digits`, `Period`, or `Skew`.

### Enrollment

Enrollment is two server round-trips: generate a secret, render its `otpauth://` URI as a QR code, then verify the first code the user types from their authenticator app before persisting the secret as enabled.

```go
import "github.com/velocitykode/velocity/auth"

// 1. Begin enrollment: generate a secret and the otpauth:// URI.
secret, qrURL, err := auth.TOTP.Generate("user@example.com")
if err != nil {
    return err
}
// `secret` is base32 (no padding); show qrURL to the user as a QR code,
// and stash secret in a pending-enrollment record (NOT on the user yet).

// 2. User scans the QR with their authenticator and submits the first
//    6-digit code. Use VerifyAndConsume so the matched step gets recorded
//    and replay is rejected from the very first verify.
matched, step := auth.TOTP.VerifyAndConsume(secret, submittedCode, 0)
if !matched {
    return errors.New("invalid code")
}
// Persist secret + step on the user, flip `two_factor_enabled = true`.
user.TOTPSecret = secret
user.TOTPLastUsedStep = step
```

`Generate(label)` returns `(secret, qrURL, err)` where `secret` is a base32-encoded 160-bit value (RFC 6238 section 5.1) and `qrURL` is an `otpauth://totp/<label>?secret=...&issuer=...&algorithm=SHA1&digits=6&period=30` URI. Render that URI to a QR with any QR library; authenticator apps consume it directly.

### Verification at sign-in

Two methods cover verification, with a deliberate split:

- `auth.TOTP.Verify(secret, code) bool`: stateless check across the configured skew window. Fast, but has **no replay protection**: the same code submitted twice in the same 30-second window will succeed twice. Use this only when you have an external replay control (e.g. one-time challenge tokens that already prevent re-submission).
- `auth.TOTP.VerifyAndConsume(secret, code, lastUsedStep) (matched bool, step int64)`: the safe default. Walks the skew window in constant time (no early return, `subtle.ConstantTimeSelect` for the matched step) so timing does not leak which window matched. Rejects replay at the framework level: if the matched step is `<= lastUsedStep`, the call returns `(false, 0)` even though the code itself was valid. The caller persists the returned `step` per user and passes it on the next call.

Pass `lastUsedStep == 0` on first verification (immediately after enrollment); any real TOTP step (`Unix() / period`) is far larger so the comparison still admits the first code. On any rejection (bad code, replay, decode failure) the returned step is always 0; treat `(false, *)` as "do nothing" and never consult the step value.

```go
matched, step := auth.TOTP.VerifyAndConsume(user.TOTPSecret, code, user.TOTPLastUsedStep)
if !matched {
    // Generic error: do not distinguish "bad code" from "replayed code".
    return errors.New("invalid code")
}
user.TOTPLastUsedStep = step
// Persist `user` so the new step is durable before the next attempt.
```

The default `Skew: 1` accepts codes from the previous, current, and next 30-second window, smoothing over clock drift between the user's phone and the server. Set `Skew: 0` for strict current-window-only matching; values greater than 1 widen the acceptance window proportionally.

### Recovery codes

Recovery codes are the user's escape hatch when they lose their authenticator. Generate a batch at enrollment, present them once, and store hashed copies for verification.

```go
codes, err := auth.TOTP.GenerateRecoveryCodes(8)
if err != nil {
    return err
}
// Show `codes` to the user ONCE (download / print). The plaintext is
// never displayed again.

// Hash each code via the manager's Hasher before persisting.
hashed := make([]string, 0, len(codes))
for _, c := range codes {
    h, err := auth.HashRecoveryCode(manager.GetHasher(), c)
    if err != nil {
        return err
    }
    hashed = append(hashed, h)
}
user.RecoveryCodes = hashed // []string of bcrypt hashes
```

Codes are formatted `XXXX-XXXX` from a 31-character unambiguous alphabet (no `0`/`O`, `1`/`I`/`l`), drawn with rejection sampling so the distribution is uniform. `GenerateRecoveryCodes(n)` requires `n > 0` and returns `auth.ErrInvalidRecoveryCount` otherwise.

At redemption time, scan the stored hashes with `ConsumeRecoveryCodeHashed`. The scan is uniform: every call performs `len(stored)` hasher verifications regardless of which (or whether any) hash matches, so timing does not reveal which slot matched. On match the matched hash is removed (single-use semantics) and you persist the trimmed slice.

```go
consumed, remaining, err := auth.TOTP.ConsumeRecoveryCodeHashed(
    manager.GetHasher(), user.RecoveryCodes, submittedCode,
)
if err != nil {
    return err
}
if !consumed {
    return errors.New("invalid recovery code")
}
user.RecoveryCodes = remaining
// Persist user; consider showing a "you have N codes left" warning when
// len(remaining) drops below a threshold.
```


The plaintext analog `auth.TOTP.ConsumeRecoveryCode(stored []string, supplied string)` is retained for compatibility but compares plaintext codes. Storing recovery codes as plaintext at rest is unsafe. Use `HashRecoveryCode` at issuance and `ConsumeRecoveryCodeHashed` at redemption for any production deployment.


`HashRecoveryCode(h Hasher, code string)` and `ConsumeRecoveryCodeHashed(h Hasher, hashed []string, supplied string)` both delegate to the supplied `auth.Hasher`. The bcrypt hasher already configured by the manager works directly, no extra crypto dependency needed. Both return errors when the hasher is nil or the input is empty.

### Gating routes on 2FA

Once enrollment is done, you want protected actions (changing email, exporting data, viewing billing) to require that the current request was made by a user who has actually completed the 2FA challenge for this session, not just one who happens to have 2FA enabled in principle. The framework hands you `auth.RequireTwoFactor`, a `BeforeCallback` you register on an `Access`:

```go
// auth.RequireTwoFactor (auth/totp_access.go)
func RequireTwoFactor(getStatus func(actor any) bool) BeforeCallback
```

The supplied `getStatus` function receives the `Authenticatable` as `any` (so consumer code can type-assert to its own user model without `auth` depending on it) and returns true when the current actor has satisfied the 2FA challenge for this session. Wire it once on the manager's authorizer:

```go
access := manager.Access() // *auth.Access

access.Before(auth.RequireTwoFactor(func(actor any) bool {
    u, ok := actor.(*models.User)
    if !ok {
        return false
    }
    // Pull the per-session "2fa_verified_at" flag the login flow set
    // after a successful VerifyAndConsume.
    return u.TwoFactorVerifiedThisSession
}))
```

Semantics: when `getStatus` reports `true`, the callback returns `nil` and the authorizer falls through to the actual policies and abilities. When it reports `false`, the callback returns a pointer to `false`, denying every ability on this `Access`. When `getStatus` itself is nil (or the actor is nil), the callback is a no-op and returns nil so it cannot accidentally lock every user out of an app where 2FA is not yet provisioned.

#### Recipe: Enable TOTP for an account

**When:** A signed-in user opens "Security" in account settings and clicks "Enable two-factor authentication." You need a stateful enrollment flow: generate, confirm, then activate.

**Code:**

```go
// Step 1: GET /account/2fa/setup
func (h *TwoFactorHandler) Setup(ctx *router.Context) error {
    user := auth.FromContext(ctx).User(ctx.Request).(*models.User)

    secret, qrURL, err := auth.TOTP.Generate(user.Email)
    if err != nil {
        return err
    }

    // Stash secret in a *pending* slot, not the live TOTPSecret column.
    user.PendingTOTPSecret = secret
    if err := orm.Save(ctx.Request.Context(), nil, user); err != nil {
        return err
    }

    return view.Render(ctx, "Account/TwoFactor/Setup", view.Props{
        "qr_url": qrURL,
        "secret": secret, // shown for manual entry
    })
}

// Step 2: POST /account/2fa/confirm  body: { "code": "123456" }
func (h *TwoFactorHandler) Confirm(ctx *router.Context) error {
    m := auth.FromContext(ctx)
    user := m.User(ctx.Request).(*models.User)

    var body struct{ Code string `json:"code"` }
    if err := ctx.Bind(&body); err != nil {
        return err
    }

    matched, step := auth.TOTP.VerifyAndConsume(user.PendingTOTPSecret, body.Code, 0)
    if !matched {
        return ctx.Error(http.StatusUnprocessableEntity, "invalid code")
    }

    // Promote pending -> live, generate recovery codes, hash them.
    plain, err := auth.TOTP.GenerateRecoveryCodes(8)
    if err != nil {
        return err
    }
    hashed := make([]string, 0, len(plain))
    for _, c := range plain {
        h, err := auth.HashRecoveryCode(m.GetHasher(), c)
        if err != nil {
            return err
        }
        hashed = append(hashed, h)
    }

    user.TOTPSecret = user.PendingTOTPSecret
    user.PendingTOTPSecret = ""
    user.TOTPLastUsedStep = step
    user.TwoFactorEnabled = true
    user.RecoveryCodes = hashed
    if err := orm.Save(ctx.Request.Context(), nil, user); err != nil {
        return err
    }

    // Show recovery codes ONCE, plaintext, with a download / print prompt.
    return view.Render(ctx, "Account/TwoFactor/Codes", view.Props{
        "codes": plain,
    })
}
```

**Why this shape:** Splitting setup and confirm into two requests is the load-bearing detail. Generating the secret on the GET and persisting it directly to `TOTPSecret` would enable 2FA on the account before the user proves their authenticator can actually produce valid codes, locking them out if their phone clock is wrong or they botched the QR scan. The pending slot keeps the live column untouched until `VerifyAndConsume` succeeds, and passing `lastUsedStep: 0` admits the first code while still recording its step so an attacker cannot replay the same submission. Recovery codes are generated server-side, shown once, and stored hashed via the manager's existing bcrypt hasher, no new crypto dependency, and a constant-time scan at redemption.

**See also:**

- [`core/middleware`]() for `RateLimitByKey` to throttle 2FA verification attempts the same way you throttle login.

## Registration & User Creation

### User Registration

```go
func RegisterHandler(ctx *router.Context) error {
    m := auth.FromContext(ctx)

    // Get form data
    name := ctx.Request.FormValue("name")
    email := ctx.Request.FormValue("email")
    password := ctx.Request.FormValue("password")
    passwordConfirmation := ctx.Request.FormValue("password_confirmation")

    // Validate passwords match
    if password != passwordConfirmation {
        view.Render(ctx, "auth/register", view.Props{
            "error": "Passwords do not match",
            "old": map[string]string{
                "name": name,
                "email": email,
            },
        })
        return nil
    }

    // Hash password
    hashedPassword, err := m.Hash(password)
    if err != nil {
        return ctx.Error(http.StatusInternalServerError, "Internal Server Error")
    }

    // Create user (using your user model). The map-based Create path is
    // policed by the model's mass-assignment policy, so "name", "email",
    // and "password" must appear in its AssignableFields().
    _, err = models.User{}.Create(ctx.Request.Context(), map[string]any{
        "name":     name,
        "email":    email,
        "password": hashedPassword,
    })
    if err != nil {
        view.Render(ctx, "auth/register", view.Props{
            "error": "Failed to create account",
        })
        return nil
    }

    // Auto-login the new user
    credentials := map[string]interface{}{
        "email":    email,
        "password": password, // Use original password for login
    }

    success, _ := m.Attempt(ctx.Response, ctx.Request, credentials, false)
    if success {
        view.Location(ctx, "/dashboard")
    } else {
        view.Location(ctx, "/login")
    }
    return nil
}
```

## Security Features

### Password Requirements

```go
func validatePassword(password string) []string {
    var errors []string

    if len(password) < 8 {
        errors = append(errors, "Password must be at least 8 characters")
    }

    hasUpper := regexp.MustCompile(`[A-Z]`).MatchString(password)
    if !hasUpper {
        errors = append(errors, "Password must contain uppercase letter")
    }

    hasLower := regexp.MustCompile(`[a-z]`).MatchString(password)
    if !hasLower {
        errors = append(errors, "Password must contain lowercase letter")
    }

    hasNumber := regexp.MustCompile(`\d`).MatchString(password)
    if !hasNumber {
        errors = append(errors, "Password must contain a number")
    }

    return errors
}
```

### Rate Limiting

Per-attempt throttling lives in the `LoginThrottler` seam (see above). For coarser route-level limits, for example capping requests to `/login` regardless of credentials, reach for `router.RateLimitByKey`, which composes cleanly with `auth.AuthMiddleware`.

## Testing Authentication

```go
func TestAuthentication(t *testing.T) {
    hasher := auth.NewBcryptHasher(10)

    // Test password hashing
    password := "test123"
    hash, err := hasher.Hash(password)
    assert.NoError(t, err)
    assert.True(t, hasher.Verify(password, hash))
    assert.False(t, hasher.Verify("wrong", hash))

    // Test authentication attempt against an in-memory manager.
    manager := auth.NewManager()
    manager.SetHasher(hasher)
    // ... install a fake user store (manager.SetUserStore) and register a
    // scheme (manager.RegisterScheme), then:

    credentials := map[string]interface{}{
        "email":    "test@example.com",
        "password": "test123",
    }

    req := httptest.NewRequest("POST", "/login", nil)
    rec := httptest.NewRecorder()

    success, err := manager.Attempt(rec, req, credentials, false)
    assert.NoError(t, err)
    assert.True(t, success)

    user := manager.User(req)
    assert.Equal(t, "test@example.com", user.(*models.User).Email)
}
```

## Best Practices

1. **Always Hash Passwords**: Never store plain text passwords
2. **Use HTTPS**: Enable secure cookies in production
3. **Implement Rate Limiting**: Prevent brute force attacks
4. **Validate Input**: Always validate and sanitize user input
5. **Session Security**: Regenerate session IDs after login
6. **Remember Me**: Use secure tokens for persistent sessions
7. **Logout Everywhere**: Provide ability to logout from all devices

## Recipe: Throttle login attempts by email + IP

**When:** You want to slow down credential-stuffing without locking out an entire office NAT or letting an attacker spray a single IP across thousands of accounts.

**Code:**

```go
// myapp/auth/throttler.go
type EmailIPThrottler struct {
    cache cache.Store // any cache.Store; Redis-backed in prod
}

func (t *EmailIPThrottler) Allow(r *http.Request, key string) bool {
    v, _ := t.cache.GetCtx(r.Context(), "login:fail:"+key)
    n, _ := v.(int)
    return n < 5
}

func (t *EmailIPThrottler) RecordFailure(r *http.Request, key string) {
    v, _ := t.cache.GetCtx(r.Context(), "login:fail:"+key)
    n, _ := v.(int)
    _ = t.cache.PutCtx(r.Context(), "login:fail:"+key, n+1, 15*time.Minute)
}

func (t *EmailIPThrottler) RecordSuccess(r *http.Request, key string) {
    _ = t.cache.ForgetCtx(r.Context(), "login:fail:"+key)
}

// during bootstrap, after building the SessionScheme:
sessionScheme.SetLoginThrottler(&EmailIPThrottler{cache: cacheStore})
```

**Why this shape:** The framework hands you the composite key for free via `auth.ThrottleKey(r, credentials, trustedProxies)`, a length-bounded SHA-256 digest over the normalised identifier and the resolved client IP. Keying on the composite means a single attacker IP cannot exhaust attempts for an unrelated user, and a shared IP (NAT, corporate egress) does not collectively lock out everyone behind it. The 5/15-minute window is a starting point: tune to your traffic. Keying on email-only invites enumeration; IP-only invites NAT lockout; the composite is the load-bearing detail. `RecordSuccess` clearing the counter is what lets a legitimate user recover after a typo storm. For a throttler that caps each dimension independently, consult `auth.ThrottleKeys` instead and branch on the per-key prefix.

**See also:**

- [`core/middleware`]() for `RateLimitByKey` (route-level, complements per-attempt throttling)
- [`core/cache`]() for the `Store` interface used above
- [`core/csrf`]() for the other half of session-based form defense

## Related

- [`core/csrf`]() for CSRF protection on session-based forms
- [`core/cache`]() for the `cache.Store` interface used by Redis-backed throttlers and (eventually) Redis-backed session stores
- [`core/middleware`]() for `RateLimitByKey`, the route-level rate limiter that composes with `auth.AuthMiddleware`


================================================================================
# Handlers

Source: https://vel.build/docs/core/handlers/
Section: Core Framework
Summary: Organize HTTP request handling with Velocity handlers and Context-based handlers.


Handlers in Velocity handle HTTP requests and responses, providing a clean way to organize your application logic following the MVC pattern. Handlers use Context-based functions that receive a `*router.Context` and return an `error`.

## Quick Start

Creating and using handlers in Velocity:

```go
// internal/handlers/user_handler.go
package handlers

import (
    "myapp/internal/models"

    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/view"
)

type UserHandler struct{}

func NewUserHandler() *UserHandler {
    return &UserHandler{}
}

func (c *UserHandler) Index(ctx *router.Context) error {
    users, err := models.User{}.All()
    if err != nil {
        return ctx.JSON(500, map[string]string{"error": "Failed to load users"})
    }

    return view.Render(ctx, "users/index", view.Props{
        "users": users,
    })
}

func (c *UserHandler) Show(ctx *router.Context) error {
    id := ctx.Param("id")
    user, err := models.User{}.Find(id)

    if err != nil {
        return ctx.JSON(404, map[string]string{"error": "User not found"})
    }

    return view.Render(ctx, "users/show", view.Props{
        "user": user,
    })
}
```

## Handler Structure

### Basic Handler

```go
package handlers

import (
    "myapp/internal/models"

    "github.com/velocitykode/velocity/auth"
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/view"
)

type PostHandler struct{}

func NewPostHandler() *PostHandler {
    return &PostHandler{}
}

// Show all posts
func (c *PostHandler) Index(ctx *router.Context) error {
    posts, err := models.Post{}.With("User").OrderBy("created_at", "DESC").Get()
    if err != nil {
        return ctx.JSON(500, map[string]string{"error": "Failed to load posts"})
    }

    return view.Render(ctx, "posts/index", view.Props{
        "posts": posts,
    })
}

// Show single post
func (c *PostHandler) Show(ctx *router.Context) error {
    id := ctx.Param("id")
    post, err := models.Post{}.With("User", "Comments.User").Find(id)

    if err != nil {
        return ctx.JSON(404, map[string]string{"error": "Post not found"})
    }

    return view.Render(ctx, "posts/show", view.Props{
        "post": post,
    })
}

// Show create form
func (c *PostHandler) Create(ctx *router.Context) error {
    return view.Render(ctx, "posts/create", view.Props{})
}

// Store new post
func (c *PostHandler) Store(ctx *router.Context) error {
    // Bind and validate request
    var input struct {
        Title string `json:"title"`
        Body  string `json:"body"`
    }

    if err := ctx.Bind(&input); err != nil {
        return ctx.JSON(400, map[string]string{"error": "Invalid input"})
    }

    // Get authenticated user
    user := auth.FromContext(ctx).User(ctx.Request).(*models.User)

    // Create post
    post, err := models.Post{}.Create(map[string]any{
        "title":   input.Title,
        "body":    input.Body,
        "user_id": user.ID,
    })
    if err != nil {
        return ctx.JSON(500, map[string]string{"error": "Failed to create post"})
    }

    view.Location(ctx, fmt.Sprintf("/posts/%d", post.ID))
    return nil
}

// Show edit form
func (c *PostHandler) Edit(ctx *router.Context) error {
    id := ctx.Param("id")
    post, err := models.Post{}.Find(id)

    if err != nil {
        return ctx.JSON(404, map[string]string{"error": "Post not found"})
    }

    return view.Render(ctx, "posts/edit", view.Props{
        "post": post,
    })
}

// Update post
func (c *PostHandler) Update(ctx *router.Context) error {
    id := ctx.Param("id")
    post, err := models.Post{}.Find(id)

    if err != nil {
        return ctx.JSON(404, map[string]string{"error": "Post not found"})
    }

    var input struct {
        Title string `json:"title"`
        Body  string `json:"body"`
    }

    if err := ctx.Bind(&input); err != nil {
        return ctx.JSON(400, map[string]string{"error": "Invalid input"})
    }

    post.Update(map[string]any{
        "title": input.Title,
        "body":  input.Body,
    })

    view.Location(ctx, fmt.Sprintf("/posts/%d", post.ID))
    return nil
}

// Delete post
func (c *PostHandler) Destroy(ctx *router.Context) error {
    id := ctx.Param("id")
    post, err := models.Post{}.Find(id)

    if err != nil {
        return ctx.JSON(404, map[string]string{"error": "Post not found"})
    }

    if err := post.Delete(); err != nil {
        return ctx.JSON(500, map[string]string{"error": "Failed to delete post"})
    }

    view.Location(ctx, "/posts")
    return nil
}
```


`Create(map[string]any{...})` and `Update(map[string]any{...})` are
deny-by-default. The model must declare `AssignableFields()` (allowlist) or
`ProtectedFields()` (denylist), or opt out with `AllowAllColumns() bool`;
otherwise the write is rejected with a `*orm.MassAssignmentError`. See
[CRUD Operations](/docs/database/crud/).


## Base Handler

Create a base handler with common functionality:

```go
// internal/handlers/base_handler.go
package handlers

import (
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/view"
    "github.com/velocitykode/velocity/auth"
    "myapp/internal/models"
)

type BaseHandler struct{}

// JSON response helper
func (c *BaseHandler) JSON(ctx *router.Context, data interface{}, status ...int) error {
    statusCode := 200
    if len(status) > 0 {
        statusCode = status[0]
    }
    return ctx.JSON(statusCode, data)
}

// Error response helper
func (c *BaseHandler) Error(ctx *router.Context, message string, status ...int) error {
    statusCode := 500
    if len(status) > 0 {
        statusCode = status[0]
    }
    return ctx.JSON(statusCode, map[string]string{
        "error": message,
    })
}

// Not found response
func (c *BaseHandler) NotFound(ctx *router.Context) error {
    return c.Error(ctx, "Resource not found", 404)
}

// Forbidden response
func (c *BaseHandler) Forbidden(ctx *router.Context) error {
    return c.Error(ctx, "Access forbidden", 403)
}

// Unauthorized response
func (c *BaseHandler) Unauthorized(ctx *router.Context) error {
    return c.Error(ctx, "Authentication required", 401)
}

// Redirect helper
func (c *BaseHandler) Redirect(ctx *router.Context, url string, status ...int) error {
    statusCode := 302
    if len(status) > 0 {
        statusCode = status[0]
    }
    return ctx.Redirect(statusCode, url)
}

// Render with validation errors
// ctx.FlashErrors writes the errors to an encrypted flash cookie so they
// survive a redirect and are available to the next view render. Its
// companion, ctx.FlashInput, does the same for old form input.
func (c *BaseHandler) FlashErrors(ctx *router.Context, errors map[string][]string) {
    ctx.FlashErrors(errors)
}

// Authorization helper
func (c *BaseHandler) authorize(ctx *router.Context, action string, resource interface{}) bool {
    user := auth.FromContext(ctx).User(ctx.Request)
    if user == nil {
        return false
    }

    // Implement your authorization logic here
    // For example, check if user can perform action on resource
    return true
}

// Get authenticated user
func (c *BaseHandler) user(ctx *router.Context) *models.User {
    return auth.FromContext(ctx).User(ctx.Request).(*models.User)
}
```

## Resource Handlers

Velocity supports RESTful resource handlers:

```go
// internal/handlers/api/user_handler.go
package api

import (
    "errors"

    "myapp/internal/models"

    "github.com/velocitykode/velocity/auth"
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/validation"
)

type UserHandler struct {
    BaseHandler
}

// GET /api/users
func (c *UserHandler) Index(ctx *router.Context) error {
    page := ctx.Query("page")
    if page == "" {
        page = "1"
    }

    users, err := models.User{}.
        With("Profile").
        Paginate(page, 15)

    if err != nil {
        return c.Error(ctx, "Failed to load users")
    }

    return c.JSON(ctx, users)
}

// GET /api/users/{id}
func (c *UserHandler) Show(ctx *router.Context) error {
    id := ctx.Param("id")
    user, err := models.User{}.With("Profile", "Posts").Find(id)

    if err != nil {
        return c.NotFound(ctx)
    }

    return c.JSON(ctx, user)
}

// POST /api/users
type StoreUserInput struct {
    Name     string `json:"name"`
    Email    string `json:"email"`
    Password string `json:"password"`
}

// Rules makes StoreUserInput a router.Validatable (the same interface
// vform.FormRequest aliases), so ctx.BindValid picks the rules up.
func (in *StoreUserInput) Rules() validation.Rules {
    return validation.Rules{
        "name":     {validation.Required(), validation.String(), validation.Max(255)},
        "email":    {validation.Required(), validation.Email(), validation.Unique("users", "email")},
        "password": {validation.Required(), validation.String(), validation.Min(8)},
    }
}

func (c *UserHandler) Store(ctx *router.Context) error {
    var input StoreUserInput

    // BindValid binds the JSON body and then runs input.Rules() through
    // the same DB-backed rule set ctx.Validate uses, so `unique` resolves
    // here too. Unlike ctx.Validate it neither flashes errors nor
    // redirects back, which is what an API handler wants: the response
    // shape stays yours.
    if err := ctx.BindValid(&input); err != nil {
        var ve validation.ValidationErrors
        if errors.As(err, &ve) {
            return ctx.JSON(422, map[string]interface{}{"errors": ve.All()})
        }
        // Bind/decode failure or no validator wired, not a field error.
        return ctx.JSON(400, map[string]interface{}{"error": "Invalid input"})
    }

    hashedPassword, err := auth.FromContext(ctx).Hash(input.Password)
    if err != nil {
        return c.Error(ctx, "Failed to hash password")
    }

    user := models.User{
        Name:     input.Name,
        Email:    input.Email,
        Password: hashedPassword,
    }

    if err := user.Save(); err != nil {
        return c.Error(ctx, "Failed to create user")
    }

    return ctx.JSON(201, user)
}

// PUT /api/users/{id}
type UpdateUserInput struct {
    Name  string `json:"name"`
    Email string `json:"email"`

    // userID is unexported, so binding never writes it and it never
    // reaches the validated data map. Rules() reads it to scope the
    // uniqueness check to "every row but this one".
    userID uint
}

func (in *UpdateUserInput) Rules() validation.Rules {
    return validation.Rules{
        "name": {validation.Nullable(), validation.String(), validation.Max(255)},
        "email": {
            validation.Nullable(),
            validation.Email(),
            validation.Unique("users", "email").Except(in.userID),
        },
    }
}

func (c *UserHandler) Update(ctx *router.Context) error {
    id := ctx.Param("id")
    user, err := models.User{}.Find(id)

    if err != nil {
        return c.NotFound(ctx)
    }

    input := UpdateUserInput{userID: user.ID}
    if err := ctx.BindValid(&input); err != nil {
        var ve validation.ValidationErrors
        if errors.As(err, &ve) {
            return ctx.JSON(422, map[string]interface{}{"errors": ve.All()})
        }
        return ctx.JSON(400, map[string]interface{}{"error": "Invalid input"})
    }

    if err := user.Update(map[string]any{
        "name":  input.Name,
        "email": input.Email,
    }); err != nil {
        return c.Error(ctx, "Failed to update user")
    }

    return c.JSON(ctx, user)
}

// DELETE /api/users/{id}
func (c *UserHandler) Destroy(ctx *router.Context) error {
    id := ctx.Param("id")
    user, err := models.User{}.Find(id)

    if err != nil {
        return c.NotFound(ctx)
    }

    if err := user.Delete(); err != nil {
        return c.Error(ctx, "Failed to delete user")
    }

    ctx.Response.WriteHeader(204)
    return nil
}
```

### Validation rules are typed values

Rules are constructor values collected into a `validation.Rules` set keyed
by field, never strings. Parameters ride along pre-split, so a value
containing `,` or `|` needs no escaping. The same rule shape is accepted by
`ctx.Validate`, `ctx.BindValid`, `vform.FormRequest.Rules()`,
`validation.Check` / `CheckW` / `CheckData`, and the `dbrules.Check*`
helpers.

`Nullable()` is the partial-update lever: a field whose value is empty
(`nil` or `""`) skips every other rule on that field, so an omitted `name`
in a `PUT` body is left alone while a supplied one still has to pass
`String()` and `Max(255)`.

`Unique(table, column)` and `Exists(table, column)` describe the DB-backed
checks; `Unique(...).Except(id)` and `.IDColumn(name)` return new rule
values rather than mutating the receiver, so a package-level rule set stays
immutable and safe to share across goroutines.

### Choosing a validation entry point

`ctx.Validate(rules, messages...)` is the web-form entry point: on failure
it calls `ctx.FlashErrors` and `ctx.FlashInput`, redirects back through the
view engine when one is wired, and returns `router.ErrValidationAborted`,
which the router treats as "response already written". Return that error
directly rather than writing a second response:

```go
func (c *PostHandler) Store(ctx *router.Context) error {
    if err := ctx.Validate(validation.Rules{
        "title": {validation.Required(), validation.Min(3)},
        "body":  {validation.Required(), validation.Min(10)},
    }); err != nil {
        // Errors and old input are already flashed and the redirect back
        // is already written; returning err stops the router from
        // emitting another response.
        return err
    }

    // Only reached when every field passed.
    return nil
}
```

For JSON APIs use `ctx.BindValid` (as above), which validates without
flashing or redirecting, or reach for `vform.Validate[T]` when you want the
bound struct and a `*validation.Result` to shape the envelope yourself.

## Handler Middleware

Apply middleware to handlers:

```go
// routes/web.go
package routes

import (
    "myapp/internal/handlers"
    "myapp/internal/middleware"

    "github.com/velocitykode/velocity/router"
)

func WebRoutes(r router.Router) {
    // Public routes
    homeHandler := &handlers.HomeHandler{}
    postHandler := &handlers.PostHandler{}

    r.Get("/", homeHandler.Index)
    r.Get("/posts", postHandler.Index)
    r.Get("/posts/{id}", postHandler.Show)

    // Protected routes. Group takes a path prefix ("" for none) and an
    // optional closure that receives the group's router.
    r.Group("", func(r router.Router) {
        r.Use(middleware.Auth)

        r.Get("/posts/create", postHandler.Create)
        r.Post("/posts", postHandler.Store)
        r.Get("/posts/{id}/edit", postHandler.Edit)
        r.Put("/posts/{id}", postHandler.Update)
        r.Delete("/posts/{id}", postHandler.Destroy)
    })
}
```

## Form Handling

Handle form submissions:

```go
func (c *PostHandler) Store(ctx *router.Context) error {
    // Parse form data
    if err := ctx.Request.ParseForm(); err != nil {
        return c.Error(ctx, "Invalid form data")
    }

    // Manual validation
    title := strings.TrimSpace(ctx.Request.FormValue("title"))
    body := strings.TrimSpace(ctx.Request.FormValue("body"))

    if title == "" {
        c.FlashErrors(ctx, map[string][]string{
            "title": {"Title is required"},
        })
        // Flashing only writes the cookie; view.Back issues the redirect
        // that lets the next render read it.
        view.Back(ctx)
        return nil
    }

    if len(body) < 10 {
        c.FlashErrors(ctx, map[string][]string{
            "body": {"Body must be at least 10 characters"},
        })
        view.Back(ctx)
        return nil
    }

    // Create post
    post := models.Post{
        Title:  title,
        Body:   body,
        UserID: c.user(ctx).ID,
    }

    if err := post.Save(); err != nil {
        return c.Error(ctx, "Failed to create post")
    }

    // Flash a success message and redirect. view.For binds the view
    // engine to this request so flash and the terminal redirect chain.
    view.For(ctx).
        Flash("success", "Post created successfully").
        Redirect(fmt.Sprintf("/posts/%d", post.ID))
    return nil
}
```

## File Uploads

Handle file uploads with the Context helpers. `ctx.FormFile` parses the
multipart form (under the router's body-size limit) and returns the
`*multipart.FileHeader`; `ctx.SaveFile` writes it under the router's
configured `FileRoot` with kernel-enforced path containment, so a
traversal or symlinked `dst` cannot escape the upload directory. Pass
`FileValidationOption` values to enforce size, extension, and MIME limits
before any bytes are written:

```go
func (c *UserHandler) UpdateAvatar(ctx *router.Context) error {
    header, err := ctx.FormFile("avatar")
    if err != nil {
        return c.Error(ctx, "No file uploaded")
    }

    // Save under FileRoot, validating size and type before writing.
    fileName := fmt.Sprintf("avatars/%d_%s", c.user(ctx).ID, header.Filename)
    if err := ctx.SaveFile(header, fileName,
        router.MaxFileSize(10<<20), // 10MB max
        router.AllowedMIMETypes("image/jpeg", "image/png", "image/gif"),
    ); err != nil {
        return c.Error(ctx, "Failed to save file")
    }

    // Update user avatar
    user := c.user(ctx)
    user.Update(map[string]any{
        "avatar": fileName,
    })

    return c.JSON(ctx, map[string]string{
        "message": "Avatar updated successfully",
        "avatar":  fileName,
    })
}
```

## Request/Response Helpers

Useful helpers for handlers:

```go
// Get query parameters. The framework also exposes ctx.QueryDefault,
// ctx.QueryInt, ctx.QueryInt64, ctx.QueryFloat64, and ctx.QueryBool for
// typed access.
func (c *BaseHandler) getQuery(ctx *router.Context, key string, defaultValue ...string) string {
    if len(defaultValue) > 0 {
        return ctx.QueryDefault(key, defaultValue[0])
    }
    return ctx.Query(key)
}

// Get form value
func (c *BaseHandler) getForm(ctx *router.Context, key string, defaultValue ...string) string {
    value := ctx.FormValue(key)
    if value == "" && len(defaultValue) > 0 {
        return defaultValue[0]
    }
    return value
}

// Parse JSON body
func (c *BaseHandler) parseJSON(ctx *router.Context, v interface{}) error {
    return ctx.Bind(v)
}

// Get client IP. Prefer ctx.IP(): it resolves the real client address
// through the router's trusted-proxy policy instead of blindly trusting
// X-Forwarded-For, which a client can spoof.
func (c *BaseHandler) getClientIP(ctx *router.Context) string {
    return ctx.IP()
}
```

## Error Handling

Centralized error handling:

```go
// internal/handlers/error_handler.go
package handlers

import (
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/view"
)

type ErrorHandler struct{}

func (c *ErrorHandler) NotFound(ctx *router.Context) error {
    ctx.Response.WriteHeader(404)
    return view.Render(ctx, "errors/404", view.Props{
        "url": ctx.Request.URL.Path,
    })
}

func (c *ErrorHandler) InternalError(ctx *router.Context, err error) error {
    // ctx.Log() returns the request-scoped logger; it logs structured
    // key/value pairs after the message.
    ctx.Log().Error("Internal server error", "error", err, "url", ctx.Request.URL.Path)

    ctx.Response.WriteHeader(500)
    return view.Render(ctx, "errors/500", view.Props{
        "error": err.Error(),
    })
}

func (c *ErrorHandler) Forbidden(ctx *router.Context) error {
    ctx.Response.WriteHeader(403)
    return view.Render(ctx, "errors/403", view.Props{})
}
```

## Testing Handlers

Test your handlers:

```go
// internal/handlers/user_handler_test.go
package handlers

import (
    "net/http"
    "net/http/httptest"
    "testing"
    "net/url"
    "strings"

    "github.com/stretchr/testify/assert"
    "myapp/internal/models"

    "github.com/velocitykode/velocity/router"
)

func TestUserHandler_Index(t *testing.T) {
    // Setup test database
    setupTestDB()
    defer teardownTestDB()

    // Create test user
    user := models.User{
        Name:  "Test User",
        Email: "test@example.com",
    }
    user.Save()

    // Create request and response recorder
    req := httptest.NewRequest("GET", "/users", nil)
    w := httptest.NewRecorder()

    // Create context
    ctx := &router.Context{
        Request:  req,
        Response: w,
    }

    // Call handler
    handler := &UserHandler{}
    err := handler.Index(ctx)

    // Assert response
    assert.NoError(t, err)
    assert.Equal(t, http.StatusOK, w.Code)
    assert.Contains(t, w.Body.String(), "Test User")
}

func TestUserHandler_Store(t *testing.T) {
    setupTestDB()
    defer teardownTestDB()

    // Create form data
    form := url.Values{}
    form.Add("name", "New User")
    form.Add("email", "new@example.com")

    req := httptest.NewRequest("POST", "/users", strings.NewReader(form.Encode()))
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
    w := httptest.NewRecorder()

    // Create context
    ctx := &router.Context{
        Request:  req,
        Response: w,
    }

    // Call handler
    handler := &UserHandler{}
    err := handler.Store(ctx)

    // Assert response
    assert.NoError(t, err)
    assert.Equal(t, http.StatusFound, w.Code)

    // Verify user was created
    user, err := models.User{}.FindBy("email", "new@example.com")
    assert.NoError(t, err)
    assert.Equal(t, "New User", user.Name)
}
```

## Best Practices

1. **Keep handlers thin** - Move business logic to models or services
2. **Use base handler** - Share common functionality across handlers
3. **Validate input** - Always validate user input before processing
4. **Handle errors gracefully** - Provide meaningful error messages
5. **Use middleware** - Apply cross-cutting concerns like authentication
6. **Return appropriate status codes** - Use correct HTTP status codes
7. **Test handlers** - Write unit tests for handler methods
8. **Separate concerns** - Keep API and web handlers separate



================================================================================
# Logging

Source: https://vel.build/docs/core/logging/
Section: Core Framework
Summary: Log messages with Velocity's driver-based logging system supporting console, file, daily rotation, stack fan-out, and secret redaction.


Velocity provides a driver-based logging system that the framework wires up for you
from environment configuration when you boot an app with `velocity.New()`.

## Quick Start


**Wired on boot**: `velocity.New()` reads the `LOG_*` environment variables, builds a
logger via `log.NewLogger`, and exposes it as `app.Log`. Inside a request handler the
same logger is available as `c.Log()`. No manual setup is required for the common case.





```go
import "github.com/velocitykode/velocity"

func main() {
    app, err := velocity.New()
    if err != nil {
        panic(err)
    }

    // app.Log is a contract.Logger wired from your LOG_* env vars.
    app.Log.Info("Application started")
    app.Log.Debug("Debugging information")
    app.Log.Warn("Warning message")
    app.Log.Error("An error occurred")
}
```



```go
// Structured logging with key-value pairs. Every Logger method takes a
// message followed by alternating key/value arguments.
app.Log.Info("User logged in",
    "user_id", 123,
    "email", "user@example.com",
    "ip_address", "192.168.1.1",
)

app.Log.Info("Order processed",
    "order_id", "ORD-123",
    "amount", 99.99,
    "currency", "USD",
)
```



```go
func processOrder(logger contract.Logger, orderID string) error {
    logger.Info("Processing order", "order_id", orderID)

    if err := validateOrder(orderID); err != nil {
        logger.Error("Order validation failed",
            "order_id", orderID,
            "error", err,
        )
        return err
    }

    logger.Info("Order processed successfully", "order_id", orderID)
    return nil
}
```




The logger satisfies the `contract.Logger` interface, so any code that accepts a
`contract.Logger` can log without importing the `log` package directly:

```go
import "github.com/velocitykode/velocity/contract"

type Logger interface {
    Debug(msg string, kvs ...any)
    Info(msg string, kvs ...any)
    Warn(msg string, kvs ...any)
    Error(msg string, kvs ...any)
    Fatal(msg string, kvs ...any)
}
```

## Configuration

`velocity.New()` builds the logger from these environment variables:

```env
# Driver selection
LOG_DRIVER=console       # Options: console, file, daily, stack, null (default: console)

# File / daily driver settings
LOG_PATH=./storage/logs  # Directory for log files
LOG_DAYS=14              # Retention in days for rotated files (default: 14)

# Stack driver (comma-separated channel names)
LOG_STACK=console,file

# General settings
LOG_LEVEL=debug          # Minimum log level (default: debug)

# Optional: redact secrets/PII before they hit any sink
LOG_REDACT=true
```

These map onto a `log.LogConfig`, which you can also construct by hand:

```go
import "github.com/velocitykode/velocity/log"

cfg := log.LogConfig{
    Driver: "file",
    Config: map[string]any{
        "path":  "./storage/logs",
        "days":  14,
        "level": "debug",
    },
}

logger, err := log.NewLogger(cfg)
```

`log.NewLogger` resolves the driver through Velocity's driver registry. An empty
`Driver` defaults to `"console"`, so a zero-value `LogConfig` still produces a working
logger.


**Driver imports**: the `console` and `null` drivers register themselves whenever the
`log` package is imported. The `file`, `daily`, and `stack` drivers live in leaf
packages and must be enabled with a blank import:

```go
import (
    _ "github.com/velocitykode/velocity/log/file"  // file + daily
    _ "github.com/velocitykode/velocity/log/stack" // stack
)
```

Or pull in all built-in drivers at once with the aggregator:

```go
import _ "github.com/velocitykode/velocity/log/standard"
```


## Drivers

### Console Driver

The console driver outputs formatted logs to stdout:

```
[09:42:06] INFO: Application started
[09:42:07] DEBUG: Processing request | method=GET path=/api/users
[09:42:08] ERROR: Database connection failed | error=connection timeout
```

You can construct one directly when you need a logger outside the framework:

```go
import "github.com/velocitykode/velocity/log/drivers"

// level is the minimum severity: 0=debug, 1=info, 2=warn, 3=error, 4=fatal.
logger := drivers.NewConsoleLogger(0)
```

### File and Daily Drivers

The `file` and `daily` drivers both write to daily-rotating files (they share a
factory, so `daily` is an alias):

- **Location**: Configured via `LOG_PATH` / the `path` option.
- **Format**: `velocity-YYYY-MM-DD.log`
- **Rotation**: Automatic daily rotation; retention is controlled by `LOG_DAYS` /
  the `days` option (`0` keeps files forever).
- **Permissions**: Files are created `0o600` inside a `0o700` directory by default.
- **Thread-safe**: Concurrent writes are serialized; opt into cross-process advisory
  locking when multiple instances share a log directory.

Example file output:
```
[2024-01-15 09:42:06.000] INFO: Application started
[2024-01-15 09:42:07.001] DEBUG: Processing request | method=GET path=/api/users
[2024-01-15 09:42:08.002] ERROR: Database connection failed | error=connection timeout
```

Constructing a file logger directly exposes the rotation and permission options:

```go
import "github.com/velocitykode/velocity/log/file"

// path, days (retention), level, then optional functional options.
logger := file.NewFileLogger("./storage/logs", 14, 0,
    file.WithFileMode(0o640), // override the default 0o600
    file.WithFileLock(),      // advisory flock for shared log dirs
)
```

### Stack Driver

The stack driver fans every message out to several child channels at once. Configure
it through the `stack` option (a list of channel names) or the `LOG_STACK` env var:

```go
cfg := log.LogConfig{
    Driver: "stack",
    Config: map[string]any{
        "stack": []string{"console", "file"},
        "path":  "./storage/logs",
    },
}
```

You can also build one directly from existing loggers:

```go
stack := log.NewStackLogger(consoleLogger, fileLogger)
```

### Null Driver

For testing or to disable a channel, use the `null` driver, which discards everything:

```go
logger, _ := log.NewLogger(log.LogConfig{Driver: "null"})
// or directly:
logger := log.NewNullLogger()
```

## Advanced Usage

### Manager for Multiple Channels

For applications that need several independently-configured channels, use the
`Manager`. Channel configuration lives in `log.LoggingConfig` / `log.ChannelConfig`:

```go
import "github.com/velocitykode/velocity/log"

func setupLogging() {
    cfg := log.LoggingConfig{
        Default: "file",
        Channels: map[string]log.ChannelConfig{
            "file": {
                Driver: "file",
                Path:   "./storage/logs",
                MaxAge: 14, // retention in days
            },
            "audit": {
                Driver: "file",
                Path:   "./storage/audit",
            },
            "errors": {
                Driver: "file",
                Path:   "./storage/errors",
                Level:  "error",
            },
            "console": {
                Driver: "console",
            },
        },
    }

    manager := log.NewManager(cfg)

    // Get specific channels (created lazily, thread-safe).
    auditLog, _ := manager.Channel("audit")
    errorLog, _ := manager.Channel("errors")

    // The default channel is available via Default().
    defaultLog, _ := manager.Default()
    _ = defaultLog

    // Use different loggers for different purposes.
    auditLog.Info("User action", "action", "delete", "user_id", 123)
    errorLog.Error("Critical error", "component", "payment")
}
```

A manager channel can itself be a stack that references other configured channels:

```go
cfg := log.LoggingConfig{
    Default: "stack",
    Channels: map[string]log.ChannelConfig{
        "console": {Driver: "console"},
        "file":    {Driver: "file", Path: "./storage/logs"},
        "stack": {
            Driver: "stack",
            Options: map[string]any{
                "channels": []string{"console", "file"},
            },
        },
    },
}
```

## Redaction

Velocity can strip secrets and PII from every log line before it reaches a sink. The
redaction layer runs against the message and each key/value, across all drivers.

Turn it on per channel with the `redact` option, supply your own chain with the
`redactors` option, or flip it on process-wide with `LOG_REDACT=true`:

```go
cfg := log.LogConfig{
    Driver: "console",
    Config: map[string]any{"redact": true},
}
```

The default chain (`log.BuildDefaultRedactors()`) covers `Authorization`-style
headers, JWTs, and card numbers (PAN). Email-address redaction is opt-in: set
`LOG_REDACT_EMAILS=true` and `BuildDefaultRedactors()` adds the email redactor.
You can wrap any logger with a custom chain:

```go
import "github.com/velocitykode/velocity/log"

redacted := log.WithRedactors(inner,
    log.HeaderRedactor(),
    log.JWTRedactor(),
    log.RedactorFunc(func(s string) string {
        // custom rule
        return s
    }),
)
```

## Testing

When testing, use the null driver to silence output:

```go
func TestMyFunction(t *testing.T) {
    logger, _ := log.NewLogger(log.LogConfig{Driver: "null"})

    // Pass the logger into the code under test; it produces no output.
    MyFunction(logger)
}
```

## Best Practices

1. **Use structured logging**: Pass key-value pairs for better searchability.
2. **Choose appropriate levels**: Debug for development, Info for production.
3. **Configure per environment**: Use different drivers for dev/staging/production.
4. **Rotate logs**: The file/daily drivers handle this automatically via `LOG_DAYS`.
5. **Redact secrets**: Enable redaction in compliance-sensitive environments.

## Examples

### HTTP Middleware

Inside the router, the request-scoped logger is available via `c.Log()`:

```go
import (
    "time"
    "github.com/velocitykode/velocity/router"
)

func LoggingMiddleware(next router.HandlerFunc) router.HandlerFunc {
    return func(c *router.Context) error {
        start := time.Now()

        c.Log().Info("Request started",
            "method", c.Request.Method,
            "path", c.Request.URL.Path,
            "ip", c.Request.RemoteAddr,
        )

        // Call the next handler.
        err := next(c)

        c.Log().Info("Request completed",
            "method", c.Request.Method,
            "path", c.Request.URL.Path,
            "duration", time.Since(start),
        )

        return err
    }
}
```

### Error Handling

```go
func ProcessPayment(logger contract.Logger, amount float64) error {
    logger.Debug("Processing payment", "amount", amount)

    err := chargeCard(amount)
    if err != nil {
        logger.Error("Payment failed",
            "amount", amount,
            "error", err,
            "timestamp", time.Now(),
        )
        return err
    }

    logger.Info("Payment successful", "amount", amount)
    return nil
}
```


================================================================================
# Async

Source: https://vel.build/docs/core/async/
Section: Core Framework
Summary: Run concurrent operations with Velocity's Go-idiomatic async wrappers for goroutines and channels.


Velocity's async package provides simple, Go-idiomatic wrappers around goroutines and channels for concurrent programming without traditional async/await complexity.

## Quick Start




```go
import "github.com/velocitykode/velocity/async"

// Run a function asynchronously
result := async.Run(func() string {
    return expensiveOperation()
})

// Get result (blocks until ready)
value, err := result.Get()
```



```go
// Execute multiple functions in parallel
results, err := async.All(
    func() any { return fetchUser(id) },
    func() any { return fetchPosts(id) },
    func() any { return fetchComments(id) },
)
if err != nil {
    // A closure panicked; values slice is undefined
}

user := results[0].(User)
posts := results[1].([]Post)
comments := results[2].([]Comment)
```



```go
// Use the first successful result
result := async.Race(
    func() any { return tryCache() },
    func() any { return tryDatabase() },
    func() any { return tryAPI() },
)

data, err := result.Get()
```




## Decision matrix

Reach for the helper that matches the situation. Skim this table before writing custom goroutine plumbing.

| Situation | Helper |
|---|---|
| Fire-and-forget side job; framework-default panic log fine | `Go` |
| Need custom recover (close pipe, unblock chan, `wg.Done` in panic frame) | `GoWithRecover` |
| Goroutine lifetime tied to a context | `GoCtx` |
| Bounded fan-out across a slice, blocking | `ForEach` |
| Bounded fan-out across a slice, fire-and-forget | `GoForEach` |
| Per-item errors collected | `TryForEach` |
| Parallel fan-out with an explicit concurrency cap | `AllN` / `MapN` / `AllWithErrorN` |
| Need a result back | `Run` / `RunWithTimeout` / `RunWithContext` |

## Core Functions

### Run

Execute a function asynchronously and get a result:

```go
result := async.Run(func() int {
    time.Sleep(100 * time.Millisecond)
    return 42
})

// Non-blocking check
if result.Ready() {
    value, _ := result.Get()
}

// Blocking wait
value, err := result.Get()
```

### RunWithTimeout

Execute with a timeout:

```go
result := async.RunWithTimeout(5*time.Second, func() string {
    return slowOperation()
})

value, err := result.Get()
if result.TimedOut() {
    // Handle timeout
}
```

### RunWithContext

Execute with context for cancellation:

```go
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

result := async.RunWithContext(ctx, func() string {
    return operation()
})

value, err := result.Get()
```

## Parallel Execution

### All

Run multiple functions in parallel and wait for all to complete. `All` returns the collected values in submission order plus the first non-nil error. Errors here come from recovered panics inside the closures, so a panicking `fn` surfaces as an error instead of a silent zero value. Check `err` before reading the values slice; when `err != nil` the slice is undefined.

```go
results, err := async.All(
    func() any { return db.Find[User]() },
    func() any { return db.Find[Post]() },
    func() any { return db.Find[Comment]() },
)
if err != nil {
    // A closure panicked
}
```

`All` applies an internal concurrency cap (1024) so a caller passing an attacker-controlled slice cannot trigger unbounded goroutine fan-out. Use `AllN` when you need an explicit cap:

```go
// Cap parallelism at 8 regardless of how many closures are submitted.
results, err := async.AllN(8,
    func() any { return fetchA() },
    func() any { return fetchB() },
)
```

A `concurrency <= 0` passed to `AllN` means "use the internal default cap".

### AllWithError

Run in parallel with error propagation:

```go
results, err := async.AllWithError(
    func() (User, error) { return userRepo.Find(id) },
    func() ([]Post, error) { return postRepo.FindByUser(id) },
)
if err != nil {
    // Handle first error
}
```

A recovered panic inside a closure is checked before any normal error, so a panicking `fn` cannot be masked by a later closure's returned error. On any panic or error, `AllWithError` returns nil values and that error. Like `All`, it caps fan-out at 1024; use `AllWithErrorN(concurrency, fns...)` for an explicit cap.

### Race

Return the first completed result:

```go
result := async.Race(
    func() any { return searchElastic(query) },
    func() any { return searchDatabase(query) },
    func() any { return searchCache(query) },
)
```

### RaceWithTimeout

Race with a timeout:

```go
result := async.RaceWithTimeout(3*time.Second,
    func() any { return primaryAPI() },
    func() any { return fallbackAPI() },
)

if result.TimedOut() {
    return []Product{} // Return empty on timeout
}
```

## Fire and Forget

### Go

Execute without waiting for result:

```go
async.Go(func() {
    sendEmail(user)
    logActivity(event)
    updateAnalytics(data)
})
```

### GoWithRecover

Execute with a custom panic handler. Use this when the panic frame itself needs to do work the package logger cannot, like closing a pipe, unblocking a channel, calling `wg.Done`, or marking a session as failed.

```go
async.GoWithRecover(func() {
    riskyOperation()
}, func(p any) {
    log.Error("Operation panicked", "error", p)
    alertOps(p)
})
```

`recoverFn` may be `nil`. When it is, panics fall back to the package-level handler (the same path `Go` uses), so callers who only need the framework default can pass `nil` instead of writing a wrapper closure. `SetPanicHook` observers still fire either way.

```go
// nil recoverFn: framework logs the panic, no boilerplate needed.
async.GoWithRecover(func() {
    longLivedListener()
}, nil)
```

### GoWithRecoverE

Same shape as `GoWithRecover`, but `recoverFn` receives a typed `*async.PanicError` so callers skip the `any` type-assert dance:

```go
async.GoWithRecoverE(func() {
    riskyOperation()
}, func(p *async.PanicError) {
    log.Error("panic", "msg", p.Error(), "raw", p.Recovered())
})
```

### GoWithLogger

Run `fn` with panics routed to a scoped logger and tagged with a callsite name. Pass `nil` to use the package logger:

```go
async.GoWithLogger(reqLogger, "billing.charge", func() {
    chargeCard(order)
})
```

## Concurrency primitives

These helpers cover the fan-out and context-bound patterns that come up the moment fire-and-forget stops being enough.

### GoCtx

Run `fn` in a panic-recovered goroutine bound to a context. The supervisor returns when `ctx` is canceled or `fn` returns, whichever happens first; cancellation is logged via the package logger so early termination is traceable.

```go
async.GoCtx(ctx, func(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            return
        case msg := <-stream:
            handle(msg)
        }
    }
})
```

`fn` receives `ctx` so it can wire its own `select` on `ctx.Done()`. Without that, `fn` runs to completion even after cancellation, since Go offers no goroutine preemption.

### GoForEach

Fire-and-forget bounded fan-out. Returns immediately while a supervisor goroutine dispatches workers capped at `concurrency`. Panics in `fn` route to the package panic handler.

```go
async.GoForEach(orders, 10, func(o Order) {
    notify(o.Customer)
})
```

The input slice is snapshotted, so the caller can mutate `items` after `GoForEach` returns. Use `ForEach` when you need to wait for completion.

### TryForEach

Bounded fan-out with per-item error collection. Returns a slice the same length as `items`; index `i` holds `fn`'s result for `items[i]`, or `nil` on success. Panics inside `fn` are converted via `FromRecovered` and surfaced in the matching slot.

```go
errs := async.TryForEach(jobs, 5, func(j Job) error {
    return j.Run()
})
for i, err := range errs {
    if err != nil {
        log.Error("job failed", "id", jobs[i].ID, "err", err)
    }
}
```

Blocking; returns once every item has finished.

## Panic-as-error

The async package re-exports two helpers from the framework's internal `panicerr` so adopters can adopt the panic-to-error shape without depending on an internal package.

- `async.PanicError` is the typed recovered-panic error returned by `GoWithRecoverE` and the helpers that surface panics as errors. Call `Recovered()` to inspect the raw value handed to `recover()`. `errors.Is` / `errors.As` walk the chain when the panicked value was itself an error.
- `async.FromRecovered(r any) error` converts a recovered value into a `*PanicError` typed as `error`. Use it inside your own `defer recover()` blocks if you want the framework's panic shape:

```go
func runJob() (err error) {
    defer func() {
        if p := recover(); p != nil {
            err = async.FromRecovered(p)
        }
    }()
    return doWork()
}
```

## Collection Operations

### ForEach

Execute function for each item with concurrency limit:

```go
users := []User{user1, user2, user3, user4, user5}

async.ForEach(users, 3, func(user User) {
    sendNotification(user)
})
```

### Map

Transform items in parallel. `Map` returns the results in input order plus the first non-nil error (panics recovered inside `fn` are surfaced as that error). Check `err` before consuming the values; indices for panicked calls hold zero values.

```go
userIDs := []int{1, 2, 3, 4, 5}

users, err := async.Map(userIDs, func(id int) User {
    return userRepo.Find(id)
})
if err != nil {
    // A transform panicked
}
```

`Map` caps fan-out at 1024. Use `MapN` for an explicit concurrency limit:

```go
users, err := async.MapN(4, userIDs, func(id int) User {
    return userRepo.Find(id)
})
```

## Result Type

The `Result[T]` type wraps async operation outcomes:

```go
type Result[T any] struct {
    // ...
}

// Methods
func (r *Result[T]) Get() (T, error)           // Block until ready
func (r *Result[T]) GetOrDefault(def T) T      // Get or return default
func (r *Result[T]) Ready() bool               // Non-blocking check
func (r *Result[T]) TimedOut() bool            // Check if timed out
```

## Custom Panic Hook

Install a non-logging interceptor invoked for every panic recovered by the async package's helpers (`Run`, `RunWithTimeout`, `RunWithContext`, `Go`, `GoCtx`, `GoWithRecover`, `GoWithRecoverE`, `GoWithLogger`, `ForEach`, `GoForEach`, `TryForEach`). The hook runs in addition to logging, not in place of it. Pass `nil` to clear.

```go
async.SetPanicHook(func(p any) {
    metrics.Counter("async.panics").Inc()
    sentry.CaptureException(fmt.Errorf("%v", p))
})
```

The hook itself is panic-safe: a panic inside the hook is swallowed so observability sinks cannot take down the goroutine they are observing.

## Package Logger

Recovered panics are logged through a package-level logger that satisfies `async.Logger` (a single `Error(msg string, kvs ...any)` method). Wire your application logger once at startup so panic backtraces land in your structured sink:

```go
async.SetLogger(appLogger) // appLogger.Error(msg, kvs...)
```

`async.GetLogger()` returns the current logger, useful when you want to emit messages tagged with the same sink the async helpers use for panic logs.

## Examples

### Dashboard Handler

```go
func GetDashboard(w http.ResponseWriter, r *http.Request) {
    userID := auth.UserID(r)

    // Fetch all dashboard data in parallel
    data, _ := async.All(
        func() any { return models.User{}.Find(userID) },
        func() any { return models.GetRecentPosts(userID) },
        func() any { return models.GetNotifications(userID) },
        func() any { return analytics.GetStats(userID) },
    )

    view.Render(w, r, "dashboard", map[string]any{
        "user":          data[0],
        "posts":         data[1],
        "notifications": data[2],
        "stats":         data[3],
    })
}
```

### Background Processing

```go
func ProcessOrder(order Order) error {
    // Save synchronously
    if err := order.Save(); err != nil {
        return err
    }

    // Background tasks - don't wait
    async.Go(func() {
        email.SendConfirmation(order)
        inventory.Update(order.Items)
        analytics.TrackPurchase(order)
    })

    return nil
}
```

### API Aggregation with Fallback

```go
func SearchProducts(query string) []Product {
    result := async.RaceWithTimeout(3*time.Second,
        func() any { return searchElastic(query) },
        func() any { return searchDatabase(query) },
    )

    if result.TimedOut() {
        return []Product{}
    }

    products, _ := result.Get()
    return products.([]Product)
}
```

## Best Practices

1. **Use timeouts**: Always set timeouts for external operations
2. **Handle panics**: Use `GoWithRecover` for critical operations
3. **Limit concurrency**: Use `ForEach` with concurrency limit for large datasets
4. **Check readiness**: Use `Ready()` for non-blocking status checks
5. **Error handling**: Always check the error returned by `All`, `Map`, and their `N`-suffixed variants - a recovered panic surfaces there, and the values slice is undefined when it is non-nil. Use `AllWithError` when closures return their own `error` values
6. **Cap fan-out**: Prefer `AllN` / `MapN` / `AllWithErrorN` (or `ForEach` with a limit) over the unbounded variants when the input size is caller-controlled - the unbounded helpers cap internally at 1024 but an explicit cap is clearer

## Related

- [Queue](/docs/advanced/queue/) - durable background jobs; use the queue (not async) when work must survive process restarts
- [Events](/docs/advanced/events/) - the async dispatcher uses these primitives to fan out listeners off the request path
- [Scheduler](/docs/advanced/scheduler/) - long-lived recurring loops belong in the scheduler, not in raw `async.Go`


================================================================================
# Cache

Source: https://vel.build/docs/core/cache/
Section: Core Framework
Summary: Store and retrieve data with Velocity's multi-driver cache system supporting Redis and in-memory storage.


Velocity provides a unified caching interface supporting multiple drivers. The framework reads `CACHE_DRIVER` and the related env vars at boot and constructs a `*cache.Manager` for you, exposed as `app.Cache` (and `ctx.Cache()` from any handler).

## Quick Start


**No global cache.** All cache operations are methods on `*cache.Manager`. Reach for `app.Cache` outside of requests, `ctx.Cache()` inside a handler. The package-level helpers are limited to `cache.NewManager`, `cache.RememberT`, `cache.RememberTWithContext`, `cache.GetAs`, `cache.GetAsWithContext`, and `cache.Drivers()` (the pluggable driver registry).

Inside a handler always prefer the `*WithContext` variant of every method (`PutWithContext`, `GetWithContext`, `RememberEWithContext`, `StoreWithContext`, ...) so the request's deadline flows through to Redis dials, S3 reaches, and DB connects.





```go
import (
    "time"
    "github.com/velocitykode/velocity/router"
)

func handler(ctx *router.Context) error {
    rctx := ctx.Context()

    // Store a value with TTL. PutWithContext threads ctx through to the
    // driver so a slow Redis write is cancelled when the request is.
    ctx.Cache().PutWithContext(rctx, "user:123", userData, 1*time.Hour)

    // Retrieve a value
    var user User
    if val, found := ctx.Cache().GetWithContext(rctx, "user:123"); found {
        user = val.(User)
    }

    // Store permanently
    ctx.Cache().ForeverWithContext(rctx, "app_version", "1.0.0")

    // Remove a value
    ctx.Cache().ForgetWithContext(rctx, "user:123")
    return nil
}
```



```go
import (
    "time"
    "github.com/velocitykode/velocity/router"
)

func getUser(ctx *router.Context, userID int) (*User, error) {
    key := fmt.Sprintf("user:%d", userID)

    // Get from cache or compute and store. Use RememberEWithContext so a
    // transient DB error is propagated instead of poisoning the slot, and
    // the request's deadline flows into both the cache lookup and the
    // upstream call.
    result, err := ctx.Cache().RememberEWithContext(ctx.Context(), key, 15*time.Minute, func() (interface{}, error) {
        return fetchUserFromDB(ctx.Context(), userID)
    })
    if err != nil {
        return nil, err
    }

    return result.(*User), nil
}
```



```go
import (
    "time"
    "github.com/velocitykode/velocity/velocity"
)

func bulkOperations(app *velocity.App) {
    // Store multiple values
    items := map[string]interface{}{
        "key1": "value1",
        "key2": "value2",
        "key3": "value3",
    }
    app.Cache.PutMany(items, 30*time.Minute)

    // Retrieve multiple values
    keys := []string{"key1", "key2", "key3"}
    results := app.Cache.Many(keys)

    for key, value := range results {
        fmt.Printf("%s: %v\n", key, value)
    }
}
```




## Decision matrix

Pick the `Remember*` variant that matches your error and context needs. Default to `RememberEWithContext` (or the typed `RememberTWithContext[T]`) inside any handler that already has a `ctx`.

| Situation | Helper |
|---|---|
| Memoize idempotent fetch; tolerate framework eating callback errors | `Remember` |
| Memoize and propagate callback errors (no cache poison on err) | `RememberE` |
| Inside a handler, propagate request ctx into Redis / S3 / DB lookups | `RememberWithContext` / `RememberEWithContext` |
| Typed return, no `interface{}` assertion at the call site | `RememberT[T]` |
| Typed and ctx-aware (the default for new code) | `RememberTWithContext[T]` |
| Forever cache until explicit `Forget` | `RememberForever` / `RememberForeverWithContext` |
| Forever and error-aware | `RememberForeverE` / `RememberForeverEWithContext` |


`Remember` swallows the error you discard inside the callback. If `fetchUserFromDB` fails, you cache the zero value for the full TTL and every subsequent caller gets garbage back. Use `RememberE` whenever the callback can fail.


## Callback error path

`Remember` takes a `func() interface{}` callback, so the only way to handle a callback failure is to swallow it with `_`, which writes a zero value into the cache and pins it for the full TTL. That is rarely what you want.

`RememberE` takes a `func() (interface{}, error)`. When the callback returns a non-nil error, the cache slot is left untouched and the error is propagated to the caller. The next request retries from scratch.

```go
import "time"

// WRONG: transient DB hiccup poisons the cache for 15 minutes.
result, err := app.Cache.Remember(key, 15*time.Minute, func() interface{} {
    user, _ := fetchUserFromDB(userID) // err discarded
    return user
})

// RIGHT: error propagates, slot is not written, next call retries.
result, err := app.Cache.RememberE(key, 15*time.Minute, func() (interface{}, error) {
    return fetchUserFromDB(userID)
})
if err != nil {
    return nil, err
}
return result.(*User), nil
```

`RememberForeverE` is the equivalent error-aware variant of `RememberForever`.

## Context propagation

Every cache `Store` exposes a `Ctx`-suffixed variant of each operation (`GetCtx`, `PutCtx`, `AddCtx`, `ForeverCtx`, `ForgetCtx`, `FlushCtx`, `HasCtx`, `IncrementCtx`, `DecrementCtx`, `ManyCtx`, `PutManyCtx`) alongside the non-ctx form. The manager threads `context.Context` through to the driver so a slow Redis lookup is cancelled with the request; memory and file drivers honour the ctx where it affects blocking behaviour and otherwise ignore it transparently.

These methods are declared on the `contract.Cache` interface (aliased into the cache package as `cache.Cache`); `cache.Store` is `contract.CacheStore`, which embeds `Cache` plus `GetPrefix() string`.

```go
// Store is contract.CacheStore: every driver exposes both the plain and the
// Ctx-suffixed form of each operation. The non-ctx methods are deprecated
// shims that call the Ctx variant with context.Background().
type Store interface {
    GetCtx(ctx context.Context, key string) (interface{}, bool)
    GetStringCtx(ctx context.Context, key string) (string, bool)
    PutCtx(ctx context.Context, key string, value interface{}, ttl time.Duration) error
    AddCtx(ctx context.Context, key string, value interface{}, ttl time.Duration) (bool, error)
    ForeverCtx(ctx context.Context, key string, value interface{}) error
    ForgetCtx(ctx context.Context, key string) error
    FlushCtx(ctx context.Context) error
    IncrementCtx(ctx context.Context, key string, value int64) (int64, error)
    DecrementCtx(ctx context.Context, key string, value int64) (int64, error)
    ManyCtx(ctx context.Context, keys []string) map[string]interface{}
    PutManyCtx(ctx context.Context, items map[string]interface{}, ttl time.Duration) error
    HasCtx(ctx context.Context, key string) bool
    GetPrefix() string
    // ... plus the deprecated non-ctx shims (Get, Put, Add, ...)
}
```


`ContextStore` is now a deprecated alias for `Store`. The ctx-aware methods that once lived on a separate extension interface have been promoted onto `Store` itself, so every driver satisfies them. Use `Store` directly; the alias is kept for one release so existing type assertions keep compiling.


Every `Manager` operation has a `*WithContext` counterpart: `GetWithContext`, `PutWithContext`, `AddWithContext`, `ForeverWithContext`, `ForgetWithContext`, `RememberWithContext`, `RememberEWithContext`, `RememberForeverWithContext`, `RememberForeverEWithContext`, plus `StoreWithContext(ctx, name)` and `DefaultStoreWithContext(ctx)` for resolving named stores under the caller's deadline. Use them from any handler that already has a `ctx`.

The ctx threads end-to-end: the first call that materialises a store (Redis dial, file mkdir, S3 endpoint check) sees the caller's ctx through the registry's `Resolve(ctx, name, cfg)` path, and every subsequent read/write on a `ContextStore` honours the same ctx. A handler with a 200 ms deadline cancels both the Redis dial AND the Redis `GET` if either runs long.

```go
func handler(ctx *router.Context) error {
    val, err := ctx.Cache().RememberEWithContext(ctx.Context(), "regions", 5*time.Minute, func() (interface{}, error) {
        return upstream.FetchRegions(ctx.Context())
    })
    if err != nil {
        return err
    }
    return ctx.JSON(200, val)
}
```

`Store(name)` and `DefaultStore()` still exist; they call `StoreWithContext(context.Background(), ...)` internally. Reach for them only outside a request scope (boot wiring, scripts, tests).

## Configuration

Configure caching through environment variables in your `.env` file:

```env
# Driver selection
CACHE_DRIVER=memory        # Options: memory, file, redis

# Prefix for cache keys
CACHE_PREFIX=velocity_cache

# Memory driver (default, no additional config needed)

# File driver settings
CACHE_PATH=./storage/cache

# Redis driver settings
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DATABASE=0
REDIS_TLS=false            # set true to dial Redis over TLS (min TLS 1.2)

# Memory driver bounds (optional)
CACHE_MEMORY_MAX_ENTRIES=0  # 0 applies the 1,000,000 default; negative disables the bound
CACHE_MAX_VALUE_BYTES=0     # 0 = unlimited; caps a single serialized value (memory + file)
```


The framework wires a single `default` store from `CACHE_DRIVER`. There is no `CACHE_STORES` env var: extra named stores require building a `cache.Config` with multiple `Stores` entries yourself (see [Multiple Cache Stores](#multiple-cache-stores)).


## Drivers

The cache core self-registers its light drivers (`memory`, `file`) from `cache/init.go` at package import time, plus a `database` placeholder whose factory currently returns `velocity/cache: database driver not yet implemented`. The `redis` driver lives in the heavy `cache/redis` leaf (it carries the go-redis dependency) and self-registers from its own `init()`. Blank-import `github.com/velocitykode/velocity/cache/redis`, or `github.com/velocitykode/velocity/cache/standard` to pull in the full set, before selecting `CACHE_DRIVER=redis`. Any extra factory you install via `cache.Drivers().Register(...)` joins the same registry and becomes selectable through `CACHE_DRIVER` like a built-in.

### Memory Driver

The memory driver stores cache data in application memory:

- **Fast**: In-memory access with no I/O overhead
- **Thread-safe**: Concurrent access properly synchronized
- **Auto-cleanup**: Expired items automatically removed
- **Development**: Perfect for development and testing

**Note**: Cache is lost when the application restarts.

```go
// Auto-configured from .env
CACHE_DRIVER=memory
```

### File Driver

The file driver stores cache data on the filesystem:

- **Persistent**: Cache survives application restarts
- **Simple**: No external dependencies
- **Single-server**: Best for single-server deployments

```env
CACHE_DRIVER=file
CACHE_PATH=./storage/cache
```

### Redis Driver

The redis driver provides distributed caching:

- **Distributed**: Share cache across multiple servers
- **Persistent**: Cache survives application restarts
- **Production**: Best for production environments

```env
CACHE_DRIVER=redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DATABASE=0
REDIS_TLS=false
```

Because the Redis driver lives in the `cache/redis` leaf, it is not compiled into the core. Add a blank import somewhere in your binary so its factory is registered before the manager resolves `CACHE_DRIVER=redis`:

```go
import _ "github.com/velocitykode/velocity/cache/redis"
```

The Redis factory takes the caller's ctx and uses it for the initial `Ping`, so a misconfigured cluster fails under the request deadline rather than the go-redis default dial timeout. Construct one directly when you need to bypass the manager:

```go
import (
    "context"
    "github.com/velocitykode/velocity/cache/redis"
)

store, err := redis.NewRedisStore(ctx, "myapp", "127.0.0.1", 6379, "", 0, false)
if err != nil {
    return err
}
```

`NewRedisStore` validates host non-empty / port positive in the factory itself; `cache.StoreConfig.Validate` no longer enforces driver-specific fields, so third-party drivers stay free to define their own config shape. Note that a Redis store configured with an empty prefix disables `Flush` (returning `cache.ErrCannotFlushUnprefixed`) to avoid wiping an entire shared Redis database, and connecting to a non-loopback host without `REDIS_TLS=true` logs a cleartext-traffic warning.

## Custom Drivers

`cache.Drivers()` returns the canonical driver registry. Register a third-party factory from your driver package's `init()` and the manager will resolve it like any built-in:

```go
package dragonfly

import (
    "context"

    "github.com/velocitykode/velocity/cache"
)

func init() {
    cache.Drivers().Register("dragonfly", func(ctx context.Context, cfg cache.StoreConfig) (cache.Store, error) {
        // Validate the driver-specific fields here. The manager has
        // already merged global + per-store prefix into cfg.Prefix.
        if cfg.Host == "" {
            return nil, fmt.Errorf("dragonfly: host required")
        }
        return newDragonflyStore(ctx, cfg)
    })
}
```

Then point the config at the new driver name:

```env
CACHE_DRIVER=dragonfly
```

A few rules the registry enforces (panicking at boot, never at first request):

- Names are case-insensitive and trimmed; `Dragonfly` and `dragonfly` collide.
- `Register` panics on a duplicate registration. Use `Drivers().Override(name, factory)` from tests when you intentionally want to swap a real driver for a fake; it returns the previous factory so a `t.Cleanup` can restore it.
- A `nil` factory or empty name panics immediately.
- `Resolve` returns a typed `*driverregistry.NotFoundError` (with the available names) when `CACHE_DRIVER` points at an unregistered driver, so the failure surface includes a "did you mean?" hint.

`StoreConfig.Validate` only checks that `Driver` is non-empty. It deliberately does NOT consult `Drivers().Names()`: validation runs at config-load time, while the driver package's `init()` may run later (a blank import). Registry lookup is the resolver's job.

For the cross-subsystem story (queue, storage, mail, notification, log, orm all share the same `driverregistry`), see [Driver Registry](/docs/advanced/driver-registry/).

## API Reference

Every method below has a `*WithContext` sibling that takes `ctx context.Context` as the first argument. The non-ctx forms exist for boot wiring and one-off scripts; inside a handler always reach for the ctx-aware variant.

### Basic Operations

#### Put

Store a value in the cache with a TTL:

```go
import "time"

// Store string (request-scoped)
app.Cache.PutWithContext(ctx, "username", "john_doe", 1*time.Hour)

// Store struct
user := User{ID: 123, Name: "John Doe"}
app.Cache.PutWithContext(ctx, "user:123", user, 30*time.Minute)

// Boot-time wiring without a request ctx: use plain Put.
app.Cache.Put("config", configData, 24*time.Hour)
```

#### Get

Retrieve a value from the cache:

```go
// Get value (ctx threads through to Redis when applicable)
value, found := app.Cache.GetWithContext(ctx, "username")
if found {
    username := value.(string)
    fmt.Println("Username:", username)
}

// Get string value directly. GetString is convenience-only and does not
// take a ctx; use GetWithContext + a type assertion when you need both.
username, found := app.Cache.GetString("username")
if found {
    fmt.Println("Username:", username)
}
```

#### GetAs

The serializing drivers (redis, file) round-trip values through JSON, so a struct comes back as `map[string]interface{}` and an integer as `float64`. `cache.GetAs[T]` (and its ctx-aware sibling `cache.GetAsWithContext[T]`) re-decodes the stored value into the concrete `T` regardless of driver. These are package-level functions that take a `Store`, not `*Manager` methods (Go 1.26 method generics have not shipped):

```go
import "github.com/velocitykode/velocity/cache"

store, _ := app.Cache.DefaultStoreWithContext(ctx)
user, found := cache.GetAsWithContext[User](ctx, store, "user:123")
if found {
    fmt.Println(user.Name)
}
```

On the serializing drivers an integer larger than 2^53 may already have lost precision before `GetAs` runs; store such values as strings if you need exact large integers.

#### Add

Atomically store a value only if the key does not already exist (the SETNX primitive). Returns `(true, nil)` on insert and `(false, nil)` on contention; an error is returned only on a backend failure:

```go
import "time"

inserted, err := app.Cache.AddWithContext(ctx, "lock:job:42", "1", 30*time.Second)
if err != nil {
    return err
}
if !inserted {
    // another caller already holds the slot
}
```

#### Replace and set operations (optional capabilities)

Two capabilities sit next to `Store` as optional interfaces in `contract`. The memory and redis drivers implement both; the file driver implements neither. Check with a type assertion on the store returned by `DefaultStore()`.

`contract.CacheReplacer` is the complement of `Add`: `ReplaceCtx` writes only when the key already exists (Redis `SET XX`) and returns `(false, nil)` when it does not, so it can never recreate a key that a concurrent `Forget` removed:

```go
store, _ := app.Cache.DefaultStore()
if r, ok := store.(contract.CacheReplacer); ok {
    replaced, err := r.ReplaceCtx(ctx, "session:meta:"+id, record, ttl)
    if err == nil && !replaced {
        // the record was deleted between your read and this write
    }
}
```

`contract.CacheSetStore` keeps an unordered set of strings under one key with atomic membership updates (Redis `SADD`/`SREM`/`SMEMBERS`). `SetAddCtx` adds members and guarantees the key lives at least `ttl` longer: a fresh key gets `ttl`, an existing key's expiry is extended when it is shorter and never shortened, and `ttl <= 0` removes the expiry for good. `SetRemoveCtx` removes members (the key goes when the last member does), and `SetMembersCtx` returns the members, nil for an absent key. The point is that concurrent adds and removes from different processes never lose updates, which a JSON array read-modify-written through `Put` cannot promise:

```go
if sets, ok := store.(contract.CacheSetStore); ok {
    _ = sets.SetAddCtx(ctx, "session:user:"+userID, ttl, sessionID)
    ids, _ := sets.SetMembersCtx(ctx, "session:user:"+userID)
    _ = sets.SetRemoveCtx(ctx, "session:user:"+userID, ids...)
}
```

Both are exercised by `cachetest.RunReplacerContractTests` and `cachetest.RunSetStoreContractTests`; a third-party driver that offers them should run those runners.

#### Forever

Store a value permanently (no expiration):

```go
// Store without expiration, request-scoped
app.Cache.ForeverWithContext(ctx, "app_name", "Velocity")
app.Cache.ForeverWithContext(ctx, "build_number", "1234")
```

#### Forget

Remove a value from the cache:

```go
// Remove single key, request-scoped
app.Cache.ForgetWithContext(ctx, "user:123")

// Check if removed
if !app.Cache.Has("user:123") {
    fmt.Println("User cache cleared")
}
```

#### Flush

Clear all values from the cache:

```go
// Clear entire cache
app.Cache.Flush()
```

### Advanced Operations

#### Remember

Get from cache or compute and store. The callback signature is `func() interface{}`, so any error inside the callback must be discarded. Prefer `RememberE` whenever the callback can fail.

```go
import "time"

// Use only when the callback cannot return a meaningful error.
result, err := app.Cache.Remember("config:flags", 15*time.Minute, func() interface{} {
    return staticFlags()
})
```

#### RememberE

Error-aware variant of `Remember`. The callback returns `(interface{}, error)`; on a non-nil error the cache slot is NOT written and the error is propagated. This prevents transient upstream failures from pinning a zero value for the full TTL. Use `RememberEWithContext` whenever a ctx is in scope.

```go
func getExpensiveData(app *velocity.App, id int) (*Data, error) {
    key := fmt.Sprintf("data:%d", id)

    result, err := app.Cache.RememberE(key, 15*time.Minute, func() (interface{}, error) {
        return queryDatabase(id)
    })
    if err != nil {
        return nil, err
    }
    return result.(*Data), nil
}
```

#### RememberEWithContext

`RememberE` with a `context.Context`. The ctx threads through to the underlying driver via `ContextStore` so a slow Redis lookup is cancelled with the request, AND through the registry's `Resolve(ctx, ...)` step the first time the store is materialised so the initial Redis dial honours the same deadline. Memory and file drivers ignore the ctx transparently.

```go
func getRegions(ctx context.Context, app *velocity.App) ([]Region, error) {
    val, err := app.Cache.RememberEWithContext(ctx, "regions", 5*time.Minute, func() (interface{}, error) {
        return upstream.FetchRegions(ctx)
    })
    if err != nil {
        return nil, err
    }
    return val.([]Region), nil
}
```

#### RememberT

Typed-generic shim over `RememberE` that returns `T` directly, skipping the `interface{}` assertion at the call site. The first argument is anything that satisfies `RememberEable` (the cache `*Manager` does).

```go
import "github.com/velocitykode/velocity/cache"

region, err := cache.RememberT[Region](app.Cache, "regions:eu", 5*time.Minute, func() (Region, error) {
    return upstream.FetchRegion("eu")
})
if err != nil {
    return err
}
// region is Region, no cast needed.
```

`RememberTWithContext[T]` is the ctx-aware counterpart, taking any `RememberEContextable` (the cache `*Manager` again):

```go
region, err := cache.RememberTWithContext[Region](app.Cache, ctx, "regions:eu", 5*time.Minute, func() (Region, error) {
    return upstream.FetchRegion(ctx, "eu")
})
```

On a type mismatch (cache slot holds a different type than `T`), the function returns the zero `T` and an error so callers can detect corruption.

#### RememberForever

Get from cache or compute and store permanently:

```go
func getAppConfig(ctx context.Context, app *velocity.App) (*Config, error) {
    result, err := app.Cache.RememberForeverEWithContext(ctx, "app_config", func() (interface{}, error) {
        return loadConfig(ctx)
    })
    if err != nil {
        return nil, err
    }
    return result.(*Config), nil
}
```

`RememberForeverE` is the error-aware variant; `RememberForeverWithContext` and `RememberForeverEWithContext` add ctx propagation. Prefer `RememberForeverEWithContext` for any callback that hits the network.

#### Increment / Decrement

Atomic increment or decrement of numeric values:

```go
// Increment counter
newValue, err := app.Cache.Increment("page_views", 1)
if err != nil {
    log.Error("Failed to increment", "error", err)
}

// Increment by custom amount
app.Cache.Increment("total_sales", 150)

// Decrement counter
app.Cache.Decrement("items_remaining", 1)

// Decrement by custom amount
app.Cache.Decrement("stock_level", 10)
```

#### Has

Check if a key exists in the cache:

```go
if app.Cache.Has("user:123") {
    fmt.Println("User is cached")
} else {
    fmt.Println("User not in cache")
}
```

#### Distributed Locks

`Lock(key string, ttl ...time.Duration)` returns a `cache.Lock` backed by the default store. The TTL auto-expires the lock so a crashed holder cannot pin the key forever; it must be positive (a zero or negative TTL is rejected with `cache.ErrInvalidLockTTL`). `Lock` returns `nil` when the default store does not implement locking.

```go
lock := app.Cache.Lock("report:nightly", 5*time.Minute)
if lock == nil {
    return fmt.Errorf("store does not support locking")
}

// Run acquires the lock, invokes the callback, then releases it. Returns
// cache.ErrLockNotAcquired if the lock is already held.
err := lock.Run(ctx, func() {
    generateNightlyReport()
})
```

The `Lock` interface also exposes `Get(ctx)` / `GetWithErr(ctx)` to acquire, `Release(ctx)`, `Block(ctx, timeout, callback)` to wait for the lock, `Owner()`, and `ForceRelease(ctx)`. `RestoreLock(key, owner)` rebuilds a lock handle from a previously issued owner token so a different goroutine or process can release it.

### Bulk Operations

#### PutMany

Store multiple values at once:

```go
import "time"

func cacheUserData(app *velocity.App, users []User) {
    items := make(map[string]interface{})

    for _, user := range users {
        key := fmt.Sprintf("user:%d", user.ID)
        items[key] = user
    }

    // Store all users with 1 hour TTL
    app.Cache.PutMany(items, 1*time.Hour)
}
```

#### Many

Retrieve multiple values at once:

```go
func getUserBatch(app *velocity.App, userIDs []int) map[string]interface{} {
    keys := make([]string, len(userIDs))
    for i, id := range userIDs {
        keys[i] = fmt.Sprintf("user:%d", id)
    }

    // Get all users at once
    results := app.Cache.Many(keys)

    return results
}
```

## Multiple Cache Stores

Use different cache stores for different purposes. The framework's `.env` wiring only builds a single `default` store from `CACHE_DRIVER`; to register additional named stores, construct a `cache.Manager` yourself with a multi-store `cache.Config`.

### Configuration

```go
import "github.com/velocitykode/velocity/cache"

mgr := cache.NewManager(&cache.Config{
    Default: "default",
    Prefix:  "velocity_cache",
    Stores: map[string]cache.StoreConfig{
        "default": {Driver: cache.DriverMemory},
        "session": {Driver: cache.DriverMemory},
        "api":     {Driver: cache.DriverRedis, Host: "127.0.0.1", Port: 6379},
    },
})
```

Stores are created lazily on first access, so an unreferenced store never dials its backend.

### Using Named Stores

```go
func useMultipleStores(ctx context.Context, app *velocity.App) {
    // Get named store off the manager. StoreWithContext threads ctx into
    // the driver factory the first time the store is materialised, so a
    // slow Redis dial is cancelled when the request is.
    sessionStore, err := app.Cache.StoreWithContext(ctx, "session")
    if err != nil {
        log.Error("Failed to get session store", "error", err)
        return
    }

    // Use specific store
    sessionStore.Put("session:abc123", sessionData, 30*time.Minute)

    // Get from specific store
    val, found := sessionStore.Get("session:abc123")
}
```

`Store(name)` is the ctx-less form (it calls `StoreWithContext(context.Background(), name)` internally). Prefer the ctx-aware variant inside any handler. Subsequent calls to either form return the cached instance, so you only pay the dial cost on the first call.

### Manager for Advanced Usage

The framework constructs a `*cache.Manager` during `velocity.New()` and exposes it as `app.Cache`. Reach for it directly when you need named stores or distributed locks:

```go
func setupCaching(ctx context.Context, app *velocity.App) {
    // Get specific stores from the manager, ctx-scoped.
    apiCache, _ := app.Cache.StoreWithContext(ctx, "api")
    sessionCache, _ := app.Cache.StoreWithContext(ctx, "session")

    // Use different stores for different purposes
    apiCache.Put("api:users", users, 5*time.Minute)
    sessionCache.Put("session:123", sessionData, 30*time.Minute)
}
```

`DefaultStoreWithContext(ctx)` returns the manager's default store under the same ctx contract. If you ever need a manager outside the framework lifecycle (tests, scripts), build one yourself with `cache.NewManager(&cache.Config{...})`. That is the only package-level constructor.

## Usage Patterns

### User Profile Caching

Reduce database queries by caching user profiles:

```go
func getUserProfile(ctx *router.Context, userID int) (*User, error) {
    key := fmt.Sprintf("user:profile:%d", userID)

    user, err := cache.RememberTWithContext[*User](ctx.Cache(), ctx.Context(), key, 1*time.Hour, func() (*User, error) {
        return db.QueryUser(ctx.Context(), userID)
    })
    if err != nil {
        return nil, err
    }
    return user, nil
}

func updateUserProfile(ctx *router.Context, userID int, updates map[string]interface{}) error {
    // Update database
    if err := db.UpdateUser(ctx.Context(), userID, updates); err != nil {
        return err
    }

    // Invalidate cache under the request ctx so a slow Redis is cancellable.
    key := fmt.Sprintf("user:profile:%d", userID)
    ctx.Cache().ForgetWithContext(ctx.Context(), key)

    return nil
}
```

### API Response Caching

Cache expensive API responses:

```go
func fetchWeatherData(ctx *router.Context, city string) (*Weather, error) {
    key := fmt.Sprintf("weather:%s", city)

    return cache.RememberTWithContext[*Weather](ctx.Cache(), ctx.Context(), key, 15*time.Minute, func() (*Weather, error) {
        return callWeatherAPI(ctx.Context(), city)
    })
}
```

### Rate Limiting

Implement rate limiting with cache counters:

```go
func checkRateLimit(ctx *router.Context, userID int) (bool, error) {
    key := fmt.Sprintf("rate_limit:user:%d", userID)

    // Increment request counter
    count, err := ctx.Cache().Increment(key, 1)
    if err != nil {
        return false, err
    }

    // Set expiration on first request
    if count == 1 {
        ctx.Cache().PutWithContext(ctx.Context(), key, count, 1*time.Minute)
    }

    // Check if over limit (e.g., 60 requests per minute)
    if count > 60 {
        return false, fmt.Errorf("rate limit exceeded")
    }

    return true, nil
}
```

### Session Storage

Use cache for session data:

```go
func storeSession(ctx *router.Context, sessionID string, data map[string]interface{}) error {
    key := fmt.Sprintf("session:%s", sessionID)
    return ctx.Cache().PutWithContext(ctx.Context(), key, data, 30*time.Minute)
}

func getSession(ctx *router.Context, sessionID string) (map[string]interface{}, error) {
    key := fmt.Sprintf("session:%s", sessionID)

    val, found := ctx.Cache().GetWithContext(ctx.Context(), key)
    if !found {
        return nil, fmt.Errorf("session not found")
    }

    return val.(map[string]interface{}), nil
}

func destroySession(ctx *router.Context, sessionID string) error {
    key := fmt.Sprintf("session:%s", sessionID)
    return ctx.Cache().ForgetWithContext(ctx.Context(), key)
}
```

### Query Result Caching

Cache database query results:

```go
func getPopularPosts(ctx *router.Context) ([]Post, error) {
    return cache.RememberTWithContext[[]Post](ctx.Cache(), ctx.Context(), "posts:popular", 10*time.Minute, func() ([]Post, error) {
        return db.QueryWithContext(ctx.Context(), `
            SELECT * FROM posts
            WHERE published = true
            ORDER BY views DESC
            LIMIT 10
        `)
    })
}
```

## Testing

Use the memory driver for testing:

```go
func TestCaching(t *testing.T) {
    // Build a manager directly for tests; no .env required.
    mgr := cache.NewManager(&cache.Config{
        Default: "default",
        Stores: map[string]cache.StoreConfig{
            "default": {Driver: cache.DriverMemory},
        },
    })

    // Clear cache before the assertions
    mgr.Flush()

    // Test cache operations
    mgr.Put("test_key", "test_value", 1*time.Minute)

    val, found := mgr.Get("test_key")
    assert.True(t, found)
    assert.Equal(t, "test_value", val.(string))

    // Test expiration
    mgr.Put("expire_key", "value", 1*time.Millisecond)
    time.Sleep(2 * time.Millisecond)

    _, found = mgr.Get("expire_key")
    assert.False(t, found)
}
```

## Best Practices

1. **Use Appropriate TTLs**: Set reasonable expiration times based on data volatility
2. **Cache Invalidation**: Always invalidate cache when underlying data changes
3. **Key Naming**: Use consistent, hierarchical key naming (e.g., `resource:action:id`)
4. **Cache Prefixes**: Use the `CACHE_PREFIX` to avoid key collisions
5. **Error Handling**: Always handle cache errors gracefully
6. **Memory Management**: Monitor cache size and implement eviction policies
7. **Testing**: Use the memory driver for unit tests
8. **Production**: Use Redis driver for production environments
9. **Documentation**: Document which data is cached and for how long

## Performance Considerations

1. **Driver Selection**:
   - Memory: Fastest, but not persistent or distributed
   - File: Moderate speed, persistent, single-server
   - Redis: Fast, persistent, distributed

2. **TTL Selection**: Balance freshness vs. performance
   - Frequently changing data: 1-5 minutes
   - Moderately changing data: 15-60 minutes
   - Rarely changing data: 1-24 hours

3. **Serialization**: Complex objects have serialization overhead

4. **Bulk Operations**: Use `PutMany` and `Many` for batch operations

## Examples

### Complete Handler Example

```go
import (
    "time"
    "github.com/velocitykode/velocity/cache"
    "github.com/velocitykode/velocity/router"
)

type ProductHandler struct{}

func (c *ProductHandler) Show(ctx *router.Context) error {
    productID := ctx.Param("id")
    key := fmt.Sprintf("product:%s", productID)

    // RememberTWithContext returns *Product directly, propagates the
    // request ctx into both the cache lookup and the upstream fetch, and
    // skips the cache write on error so a transient failure does not
    // poison the slot for the full TTL.
    product, err := cache.RememberTWithContext[*Product](ctx.Cache(), ctx.Context(), key, 1*time.Hour, func() (*Product, error) {
        return fetchProduct(ctx.Context(), productID)
    })
    if err != nil {
        return ctx.Error(404, "Product not found")
    }

    return ctx.JSON(200, product)
}

func (c *ProductHandler) Update(ctx *router.Context) error {
    productID := ctx.Param("id")

    // Update product in database
    if err := updateProduct(ctx.Context(), productID, ctx.Request.Body); err != nil {
        return ctx.Error(500, "Failed to update product")
    }

    // Invalidate cache under the request ctx
    ctx.Cache().ForgetWithContext(ctx.Context(), fmt.Sprintf("product:%s", productID))

    return ctx.JSON(200, map[string]string{"status": "updated"})
}
```

## Related

- [Driver Registry](/docs/advanced/driver-registry/) for the shared `Drivers().Register` pattern across cache, queue, storage, mail, notification, log, and orm.
- [Notifications](/docs/advanced/notifications/) for outbound delivery channels that frequently sit behind a cache.
- [Queue](/docs/advanced/queue/) when work is too long for fire-and-forget caching and needs durable retries.
- [CSRF](/docs/core/csrf/) which leans on the cache manager for token storage in distributed deployments.


================================================================================
# Middleware

Source: https://vel.build/docs/core/middleware/
Section: Core Framework
Summary: Add middleware for authentication, logging, CORS, rate limiting, and custom request processing in Velocity.


Middleware wraps Velocity handlers to add cross-cutting concerns -
auth, logging, CORS, rate limiting, CSRF. Each middleware receives
the next handler in the chain and returns a new handler.

## Signature

Velocity middleware uses the `router.MiddlewareFunc` type:

```go
type HandlerFunc    func(*router.Context) error
type MiddlewareFunc func(next HandlerFunc) HandlerFunc
```

A minimal middleware:

```go
package middleware

import "github.com/velocitykode/velocity/router"

func Logging(next router.HandlerFunc) router.HandlerFunc {
    return func(c *router.Context) error {
        c.Log().Info("request",
            "method", c.Request.Method,
            "path",   c.Request.URL.Path,
        )
        return next(c)
    }
}
```

## Stacks: global, web, API

Applications typically split middleware into three scopes:

- **Global** - runs on every request (logging, CORS, recovery,
  maintenance mode)
- **Web** - runs on browser/HTML routes (sessions, CSRF, view engine)
- **API** - runs on JSON API routes (rate limiting, JSON enforcement)

You declare them in a single function passed to `v.Middleware(...)`:

```go
// internal/app/middleware.go
package app

import (
    "myapp/internal/middleware"

    "github.com/velocitykode/velocity"
    "github.com/velocitykode/velocity/csrf"
    "github.com/velocitykode/velocity/view"
)

func Middleware(m *velocity.MiddlewareStack) {
    // Runs on every request.
    m.Global(
        middleware.LoggingMiddleware,
        middleware.TrustProxiesMiddleware,
        middleware.CORSMiddleware,
        middleware.PreventRequestsDuringMaintenanceMiddleware,
        middleware.ValidatePostSizeMiddleware(10<<20),
        middleware.TrimStringsMiddleware,
        middleware.ConvertEmptyStringsToNullMiddleware,
    )

    // The CSRF and view middleware need their service instances -
    // pull them from the *app.Services container.
    s := m.Services()
    csrfInstance := s.CSRF.(*csrf.CSRF)
    viewEngine := s.View.(*view.Engine)

    // Runs on routes inside r.Web(...).
    m.Web(
        middleware.SessionMiddleware,    // session cookie before CSRF
        middleware.CSRFTokenMiddleware,  // expose token to templates
        csrfInstance.RouterMiddleware(), // validate CSRF on unsafe methods
        viewEngine.Middleware(),         // Inertia version + headers
    )

    // Runs on routes inside r.API(prefix, ...).
    m.API(
        middleware.EnsureJSONMiddleware,
    )
}
```

Wire it into `main.go` via the bootstrap chain:

```go
chain := v.
    Modules(app.Configure).
    Middleware(app.Middleware).        // <- this function
    Routes(routes.Register).
    Events(app.Events(v.Log))
```

When you register routes through `v.Routes(...)`, the `r.Web(...)`
group automatically gets the web stack and `r.API(prefix, ...)` gets
the API stack - see [Routing](/docs/core/routing).

## Per-group and per-route middleware

Inside a `Web` or `API` closure, attach middleware to a sub-group or
a single route:

```go
func Register(r *velocity.Routing) {
    r.Web(func(web router.Router) {
        // Group with middleware - applies to every route in the closure.
        web.Group("", func(auth router.Router) {
            auth.Get("/dashboard", handlers.Dashboard).Name("dashboard")
            auth.Get("/account", handlers.Account)
        }).Use(middleware.Auth)

        // Single route with middleware.
        web.Post("/contact", handlers.Contact).Use(middleware.RateLimit(5))
    })
}
```

`Group("", fn).Use(mw)` is the idiom for grouping routes purely so
they share middleware. `.Use(mw)` after a verb method attaches
middleware to just that one route.

## Order of execution

Middleware wraps from the outside in. The first middleware in the
list runs first on the way in and last on the way out:

```go
m.Global(
    middleware.RecoveryMiddleware,  // outermost - catches panics from everything below
    middleware.LoggingMiddleware,   // logs the request
    middleware.AuthMiddleware,      // innermost - runs just before the handler
)
```

Within a request, scopes run in this order:
**global → web/API → group → route → handler**.

## Parameterized middleware

Middleware that needs configuration returns a `MiddlewareFunc`:

```go
func RateLimit(requestsPerMinute int) router.MiddlewareFunc {
    limiter := rate.NewLimiter(rate.Limit(requestsPerMinute)/60, requestsPerMinute)

    return func(next router.HandlerFunc) router.HandlerFunc {
        return func(c *router.Context) error {
            if !limiter.Allow() {
                return c.JSON(http.StatusTooManyRequests, map[string]string{
                    "error": "rate limit exceeded",
                })
            }
            return next(c)
        }
    }
}

// Usage - call once at registration to capture the limiter, then attach.
m.API(middleware.RateLimit(100))
```

The limiter is built once in the outer call. Every request shares it
- exactly what you want for rate limiting.

## Passing data through context

Use the request context to hand data from middleware to the handler:

```go
func Auth(next router.HandlerFunc) router.HandlerFunc {
    return func(c *router.Context) error {
        user, err := authenticate(c.Request)
        if err != nil {
            return c.Redirect(http.StatusSeeOther, "/login")
        }

        ctx := context.WithValue(c.Request.Context(), "user", user)
        c.Request = c.Request.WithContext(ctx)
        return next(c)
    }
}

// In the handler
func Dashboard(c *router.Context) error {
    user := c.Request.Context().Value("user").(*models.User)
    return c.JSON(http.StatusOK, user)
}
```

For request-scoped values that don't need to flow into downstream
handlers, `c.Set(key, value)` / `c.Get(key)` is the lighter option -
see [HTTP Router > Per-request storage](/docs/core/http-router#per-request-storage).

## Common patterns

### Short-circuit

Return without calling `next` to stop the chain. Useful for
auth and guest checks:

```go
func Guest(next router.HandlerFunc) router.HandlerFunc {
    return func(c *router.Context) error {
        if auth.FromContext(c).Check(c.Request) {
            return c.Redirect(http.StatusSeeOther, "/dashboard")
        }
        return next(c)
    }
}
```

### Recover from panics

```go
func Recovery(next router.HandlerFunc) router.HandlerFunc {
    return func(c *router.Context) (err error) {
        defer func() {
            if r := recover(); r != nil {
                c.Log().Error("panic recovered",
                    "value", r,
                    "stack", debug.Stack(),
                )
                err = fmt.Errorf("internal server error")
            }
        }()
        return next(c)
    }
}
```

Register `Recovery` first in the global stack so it wraps everything.

### CORS

```go
func CORS(next router.HandlerFunc) router.HandlerFunc {
    return func(c *router.Context) error {
        c.Response.Header().Set("Access-Control-Allow-Origin", "*")
        c.Response.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS")
        c.Response.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")

        if c.Request.Method == http.MethodOptions {
            c.Response.WriteHeader(http.StatusOK)
            return nil
        }
        return next(c)
    }
}
```

## Built-in middleware

The `router` package ships parameterized middleware for the common
hardening concerns of an API surface. Each one returns a
`router.MiddlewareFunc` you can drop into `m.API(...)`, attach with
`.Use(...)`, or chain inside a sub-group.

### `RateLimitByKey` - per-API-token throttling

`RateLimit` and `RateLimitByIP` cover the usual cases. When the throttle
key isn't the IP - for example, an API token, an account ID, or a tenant
header - reach for `RateLimitByKey`:

```go
func RateLimitByKey(
    requests int,
    window   time.Duration,
    keyFunc  func(*router.Context) string,
    opts     ...router.RateLimitOption,
) router.MiddlewareFunc
```

The `keyFunc` is called once per request and decides which bucket the
request counts against. A canonical setup for "1000 requests/hour per
API token, fall back to IP for unauthenticated calls":

```go
import (
    "strings"
    "time"

    "github.com/velocitykode/velocity/router"
)

func APITokenThrottle() router.MiddlewareFunc {
    return router.RateLimitByKey(1000, time.Hour, func(c *router.Context) string {
        // Authorization: Bearer <token>
        auth := c.Header("Authorization")
        if token := strings.TrimPrefix(auth, "Bearer "); token != "" && token != auth {
            return "tok:" + token
        }
        // Anonymous callers share a per-IP bucket.
        return "ip:" + c.IP()
    },
        router.WithBurst(50),
        router.WithMessage("API quota exceeded"),
    )
}

// In app/middleware.go
m.API(
    middleware.EnsureJSONMiddleware,
    APITokenThrottle(),
)
```

`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and
`Retry-After` headers are set automatically. A background goroutine
sweeps idle buckets so the limiter map can't grow without bound; tune
the sweep with `WithCleanupInterval(...)`.


The `keyFunc` runs on every request - keep it allocation-free. Don't
hash the bearer token here; if you need that, do it once in an upstream
auth middleware and stash the digest with `c.Set(...)`.


For "10/second AND 1000/hour" stacking, compose limiters with
`router.NewRateLimitGroup(...)`.

### `BodyLimit` - cap request bodies on `/v1/*`

`router.BodyLimit(limit int64)` wraps the request body in
`http.MaxBytesReader`. Reads past the cap fail with the usual
`http: request body too large` error, which surfaces through your
binding layer as a 413. Pass it once at API-stack registration so every
write endpoint inherits the same ceiling:

```go
// internal/app/middleware.go
func Middleware(m *velocity.MiddlewareStack) {
    m.API(
        middleware.EnsureJSONMiddleware,
        router.BodyLimit(1<<20), // 1 MiB on every /v1/* JSON request
    )
}
```

Override on a single route when one endpoint legitimately needs more
headroom (file uploads, bulk import):

```go
func Register(r *velocity.Routing) {
    r.API("/v1", func(api router.Router) {
        api.Post("/users", handlers.CreateUser)                     // 1 MiB (inherited)
        api.Post("/imports", handlers.Import).Use(router.BodyLimit(50 << 20)) // 50 MiB
    })
}
```


`BodyLimit` panics at construction if `limit <= 0`; pass a positive byte
count. The middleware also stores the cap in request-scoped state so
later layers (validation, logging) can read it back.


### `Timeout` - bound handler latency on `/v1/*`

`router.Timeout(duration time.Duration)` cancels the request context
after the deadline and writes `503 Service Unavailable` if the handler
hasn't returned. On timeout the request is released to the client
immediately - the middleware does *not* block on a stuck handler. The
handler runs on a shallow-cloned `Context` (its own request, params,
and values), so its late writes are buffered and discarded rather than
racing the pooled parent context. This mirrors `net/http.TimeoutHandler`.

```go
m.API(
    middleware.EnsureJSONMiddleware,
    router.BodyLimit(1<<20),
    router.Timeout(5*time.Second), // global API ceiling
)
```

Per-route override for an endpoint that calls a slow upstream:

```go
r.API("/v1", func(api router.Router) {
    api.Get("/reports/:id", handlers.Report).Use(router.Timeout(30 * time.Second))
})
```

Handlers should respect the cancelled context - pass `c.Request.Context()`
into DB queries, HTTP clients, and queue dispatches so the work unwinds
when the deadline trips.


`Timeout` only protects the handler chain that runs after it. Place it
inside the API stack (or per-route), not in the global stack, so the
recovery and logging middleware still see the response after the
deadline fires.

Streaming (`http.Flusher`), `Hijack`, and `Push` are not supported
under `Timeout` - the buffered timeout-safe writer cannot commit
headers to the wire early. Don't wrap SSE, WebSocket-upgrade, or
streaming-download handlers with it.


### `ContentTypeJSON` - reject non-JSON write requests

For JSON APIs, reject `POST`/`PUT`/`PATCH` (and bodied `DELETE`) calls
that aren't `application/json` before they reach your handler:

```go
m.API(
    router.ContentTypeJSON(),
    middleware.EnsureJSONMiddleware,
)
```

`ContentTypeJSON()` is sugar for `router.ContentType("application/json")`.
Use the longer form when you need to allow more than one media type:

```go
uploads.Use(router.ContentType(
    "multipart/form-data",
    "application/x-www-form-urlencoded",
))
```

The middleware skips `GET`, `HEAD`, `OPTIONS`, and bodyless `DELETE`
requests; it returns `415 Unsupported Media Type` with a JSON body when
the check fails.

## Testing middleware

For unit tests, call the middleware directly with a stub next-handler:

```go
func TestAuthRedirectsGuests(t *testing.T) {
    called := false
    next := func(c *router.Context) error {
        called = true
        return nil
    }

    req := httptest.NewRequest(http.MethodGet, "/dashboard", nil)
    rec := httptest.NewRecorder()
    c := router.NewContext(rec, req)

    if err := middleware.Auth(next)(c); err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
    if called {
        t.Fatal("next handler should not run for unauthenticated request")
    }
    if rec.Code != http.StatusSeeOther {
        t.Errorf("expected 303, got %d", rec.Code)
    }
}
```

For end-to-end tests through the full middleware chain, register the
middleware on a fresh router and exercise it via `httptest`.

## Best practices

- Keep each middleware focused on a single concern.
- Register `Recovery` first in the global stack so it wraps everything.
- Prefer context values over package globals for per-request state.
- For expensive setup (rate limiter, DB pool), build once in the outer
  function and capture it in the closure - don't construct it inside
  the inner handler on every request.

## Related

- [CSRF](/docs/core/csrf/) - token-issuing middleware shipped with the framework
- [Authentication](/docs/core/authentication/) - auth schemes plus the `AuthMiddleware` / `GuestMiddleware` helpers that protect routes
- [Cache](/docs/core/cache/) - the building block behind rate-limiter middleware (counter storage with TTL)


================================================================================
# Form Requests

Source: https://vel.build/docs/core/form-requests/
Section: Core Framework
Summary: Self-validating request types with automatic binding, flashing, and redirect-on-failure.


Form requests bundle binding, validation, and error handling into one
call. You define a struct with rules; the handler calls `vform.Form[T]`
and receives a validated instance, or the request is redirected back
with errors flashed before the handler even continues.

Import path: `github.com/velocitykode/velocity/validation/vform`

See the [validation](/docs/core/validation) page for the underlying
rule catalog. Form requests are the sugar on top for HTTP handlers; the
rules themselves use the canonical `validation.Rules` type, so anything
documented there works inside a `Rules()` method as-is.

## Defining a form request

```go
import "github.com/velocitykode/velocity/validation"

type CreatePostRequest struct {
    Title string `json:"title"`
    Body  string `json:"body"`
}

func (r *CreatePostRequest) Rules() validation.Rules {
    return validation.Rules{
        "title": {validation.Required(), validation.Min(3)},
        "body":  {validation.Required(), validation.Min(10)},
    }
}
```

Rules are typed values built by the constructors in the `validation`
package, not strings. Parameters are carried pre-split, so a parameter may
contain any character (including `,` and `|`) without escaping.

The `Rules()` method makes the struct a `vform.FormRequest`, which is an
alias for `router.Validatable`: one form struct serves both `vform.Form[T]`
and `ctx.BindValid`, so there is a single declaration to satisfy rather
than two identical ones. The return type is `validation.Rules`
(`map[string][]validation.Rule`, aliased from `contract.ValidationRuleSet`)
so the same value can be passed straight into `validation.Check` or
`dbrules.CheckWithDB` without an intermediate conversion.


`contract.ValidationRuleSet` is a defined type, not an alias for a bare
map, so a `Rules()` method returning a structurally identical map type
fails to satisfy the interface. As a backstop, `Validate[T]` and `Form[T]`
detect a method literally named `Rules` whose signature does not satisfy
`FormRequest` and return an error naming the offending signature, rather
than silently skipping validation.


### Custom messages

Implement `WithMessages` to override per-field rule errors:

```go
func (r *CreatePostRequest) ValidationMessages() validation.Messages {
    return validation.Messages{
        {Field: "title", Rule: "required"}: "Please provide a title",
        {Field: "body", Rule: "min"}:       "Body must be at least 10 characters",
    }
}
```

Keys are `validation.MessageKey` values addressing one field+rule pair. The
`Rule` half is the canonical rule name the constructor emits (`required`,
`min`, `email`, `unique`, `alpha_dash`, ...), not the Go constructor
identifier.

### Authorization

`vform.Form[T]` itself does not gate requests, place authorization in
middleware (e.g. an auth-required middleware) or check explicitly inside
the handler before calling `Form[T]`. Authorization that depends on the
bound payload should run after `Form[T]` returns the validated `*T`.

## Using it in a handler

```go
func (h *PostHandler) Store(ctx *router.Context) error {
    req, err := vform.Form[CreatePostRequest](ctx)
    if err != nil {
        // err is router.ErrValidationAborted on validation failure;
        // returning it lets the router skip emitting an error response
        // because vform has already redirected back.
        return err
    }

    post := models.NewPost(req.Title, req.Body)
    if err := post.Save(); err != nil {
        return err
    }
    return ctx.Redirect(http.StatusSeeOther, "/posts/"+post.ID)
}
```

### Failure flow

When validation fails, `Form` takes over the response:

1. Errors are flashed via `ctx.FlashErrors`
2. Original input is flashed as old input via `ctx.FlashInput`
   (sensitive fields are stripped automatically by case-insensitive
   substring match - `password`, `passwd`, `passcode`, `secret`, `token`,
   `pin`, `cvv`, `cvc`, `card`, `ssn`, `otp`, `credential`, `credentials`,
   `api_key`, `apikey`, `private_key`, and `privatekey` are redacted)
3. The view engine's `Back` hook is invoked to redirect to the referrer
   (skipped when no view engine is wired, e.g. an API-only app)
4. `Form` returns `router.ErrValidationAborted` so the router skips
   emitting an additional error response

`FlashErrors` and `FlashInput` write short-lived encrypted flash cookies
(`_velocity_errors` and `_velocity_old`), each sealed under its own AAD
label so one can never be replayed as the other. The view layer reads them
on the next render and injects them as the `errors` and `old` props, so
your template can read `errors.title` and repopulate fields via
`old('title')`. No handler code after a failed `vform.Form` call needs
to run, the early `return err` covers it.

## Custom rendering on validation failure

The default `Form[T]` flow (flash + redirect back) is the right choice
for traditional form posts. For Inertia pages that should re-render with
view-specific props, JSON APIs that want a custom error envelope, or any
case where "redirect back" isn't a fit, use the lower-level
`vform.Validate[T]` entry point.

`Validate[T]` performs the same bind + validate cycle but never flashes
or redirects. It returns the populated `*T` and a nil `*Result` on
success, or a zero-value `*T` and a non-nil `*Result` carrying the
per-field errors on failure. Only consume `*T` when `*Result` is nil.
The `error` return is reserved for non-validation failures: a bind or
decode error, or a malformed rule set (both wrap a handler bug, never
user input).

```go
import (
    "github.com/velocitykode/velocity/validation/vform"
    "github.com/velocitykode/velocity/view"
)

func (h *AcceptInvite) Show(ctx *router.Context) error {
    req, result, err := vform.Validate[AcceptInviteRequest](ctx)
    if err != nil {
        // bind error (e.g. malformed JSON), not a validation error
        return err
    }
    if result != nil {
        // Validation failed. Render the same view with errors + the
        // invitation token still present so the user keeps context.
        return view.Render(ctx, "Invite/Accept", view.Props{
            "errors":     result.All(),
            "old":        result.Old(),
            "invite_id":  ctx.Query("token"),
        })
    }

    // Validation passed; req is the bound *AcceptInviteRequest.
    return h.acceptAndRedirect(ctx, req)
}
```

`view.Render(ctx, component, props...)` is the handler-facing entry point
for the Inertia view engine (`view.Props` is an alias for the engine's
prop map). It resolves the engine from the context's service container
and returns an error if no view engine is wired.

`Result.All()` returns one error per field (`map[string]string`,
Inertia-friendly), `Result.Messages()` returns every error
(`map[string][]string`), `Result.Err()` collapses the result into an error
wrapping `validation.ErrValidationFailed`, and `Result.Old()` returns the
input with sensitive fields removed, ready to flash or pass back as a
view prop.

## Structs without Rules

If `T` does not implement `FormRequest`, both `Form[T]` and `Validate[T]`
just bind the request body into a fresh `*T` and return it, no
validation runs. This lets the same helpers double as a strict DTO
binder when there's nothing to check.

## Types

```go
// In package validation (all aliased from the stdlib-only contract leaf)
type Rule       = contract.ValidationRule        // interface{ Rule() ValidationRuleSpec }
type Rules      = contract.ValidationRuleSet     // map[string][]Rule, keyed by field
type MessageKey = contract.ValidationMessageKey  // struct{ Field, Rule string }
type Messages   = contract.ValidationMessages    // map[MessageKey]string

// In package validation/vform
type FormRequest = router.Validatable  // interface{ Rules() validation.Rules }

type WithMessages interface {
    ValidationMessages() validation.Messages
}

type Result = validation.Result       // re-exported for Validate[T] callers

func Form[T any](ctx *router.Context) (*T, error)
func Validate[T any](ctx *router.Context) (*T, *Result, error)
```

## Relation to the `validation` package

`vform` is the HTTP-handler entry point: it owns binding, flashing, and
redirect-back. The lower-level `validation.Check`, `validation.CheckW`, and
`validation.CheckData` functions are the canonical entry points outside
HTTP, or inside HTTP when you want to control the response shape yourself
without `Validate[T]`'s bind-then-error flow. All of them return
`(*Result, error)`, keeping a malformed rule set (a handler bug) distinct
from field-level failures (user input).

The DB-backed rules (`Unique`, `Exists`) execute in the
`validation/dbrules` subpackage so the core `validation` package pulls in
no `orm` or SQL-driver dependency: use `dbrules.CheckWithDB` /
`CheckWithDBW` and `dbrules.CheckDataWithDB` / `CheckDataWithDBCtx` when
your rule set names them. `vform` already routes through
`dbrules.CheckWithDBW` and resolves the database from the context's
service container, so a `Rules()` method naming `Unique` works without any
extra wiring. When no database is reachable, a `Unique` or `Exists` rule is
reported as a configuration error rather than silently failing the field.

## Related

- [Validation](/docs/core/validation/) - the underlying rule engine `vform` delegates to
- [Handlers](/docs/core/handlers/) - where `Form[T]` and `Validate[T]` plug into request flow
- [Frontend Forms](/docs/frontend/forms/) - client-side form helpers that pair with flashed errors and old input


================================================================================
# Cryptography

Source: https://vel.build/docs/core/crypto/
Section: Core Framework
Summary: Encrypt and decrypt data with AES cipher modes, AAD binding, and key rotation in Velocity.


Velocity provides robust encryption utilities for securing sensitive data with support for multiple AES cipher modes, additional-authenticated-data (AAD) binding, and seamless key rotation.

The crypto package exposes an `Encryptor` interface. You construct an encryptor instance with `crypto.NewEncryptor(crypto.Config{...})` and call methods on it; there are no package-level encrypt/decrypt helpers. When you build an application with `velocity.New(...)`, the framework constructs an encryptor from your environment (see [Configuration](#configuration)) and wires it into the components that need it (sessions, cookies, CSRF, encrypted queue payloads).

## Quick Start


**Construct once, reuse**: Build a single `crypto.Encryptor` with `crypto.NewEncryptor` and share it. The framework already does this for you from your `.env` when you boot an app; the examples below show how to build one yourself for standalone use.





```go
import "github.com/velocitykode/velocity/crypto"

func main() {
    enc, err := crypto.NewEncryptor(crypto.Config{
        Key:    "base64:your-base64-encoded-key-here",
        Cipher: "AES-256-GCM",
    })
    if err != nil {
        log.Error("Failed to build encryptor", "error", err)
        return
    }

    // Encrypt data
    encrypted, err := enc.Encrypt("sensitive data")
    if err != nil {
        log.Error("Encryption failed", "error", err)
        return
    }

    // Decrypt data
    plaintext, err := enc.Decrypt(encrypted)
    if err != nil {
        log.Error("Decryption failed", "error", err)
        return
    }

    fmt.Println(plaintext) // Output: sensitive data
}
```



```go
import (
    "encoding/json"
    "github.com/velocitykode/velocity/crypto"
)

func encryptUserData(enc crypto.Encryptor, user User) (string, error) {
    // Serialize data to JSON
    data, err := json.Marshal(user)
    if err != nil {
        return "", err
    }

    // Encrypt the JSON bytes
    return enc.EncryptBytes(data)
}

func decryptUserData(enc crypto.Encryptor, encrypted string) (*User, error) {
    // Decrypt to bytes
    data, err := enc.DecryptBytes(encrypted)
    if err != nil {
        return nil, err
    }

    // Deserialize from JSON
    var user User
    if err := json.Unmarshal(data, &user); err != nil {
        return nil, err
    }

    return &user, nil
}
```



```go
import "github.com/velocitykode/velocity/crypto"

func generateNewKey(enc crypto.Encryptor) error {
    // Generate a new encryption key for the encryptor's cipher
    key, err := enc.GenerateKey()
    if err != nil {
        return err
    }

    // Key is base64 encoded ("base64:...") and ready to use
    fmt.Printf("Add this to your .env file:\n")
    fmt.Printf("CRYPTO_KEY=%s\n", key)

    return nil
}
```





`GenerateKey` is a method on `Encryptor`: it returns a `base64:`-prefixed key sized for that encryptor's cipher (16/24/32 bytes for AES-128/192/256). To mint a key before you have an encryptor, build a throwaway one with the target cipher and call `GenerateKey` on it.


## Configuration

When you boot an app with `velocity.New(...)`, the framework reads these environment variables from your `.env` and builds the encryptor stored on the app config (`config.Crypto`):

```env
# Encryption key. CRYPTO_KEY takes precedence; if unset, APP_KEY is used.
CRYPTO_KEY=base64:your-base64-encoded-key-here

# Falls back to APP_KEY when CRYPTO_KEY is not set
APP_KEY=base64:your-base64-encoded-key-here

# Cipher algorithm (optional, defaults to AES-256-GCM)
CRYPTO_CIPHER=AES-256-GCM

# Previous keys for rotation (optional, comma-separated)
CRYPTO_OLD_KEYS=base64:old-key-1,base64:old-key-2
```

These map onto the `crypto.Config` fields: `CRYPTO_KEY`/`APP_KEY` to `Key`, `CRYPTO_CIPHER` to `Cipher`, and `CRYPTO_OLD_KEYS` (split on commas) to `PreviousKeys`. The crypto package itself does not read the environment; that wiring lives in the framework's config bootstrap, so a standalone encryptor is always built explicitly via `crypto.NewEncryptor`.

### Cipher Options

Velocity supports AES-128/192/256 in CBC and GCM modes:

| Cipher | Key Size | Mode | Authentication |
|--------|----------|------|----------------|
| `AES-128-CBC` | 16 bytes | CBC | HMAC-SHA256 (encrypt-then-MAC) |
| `AES-192-CBC` | 24 bytes | CBC | HMAC-SHA256 (encrypt-then-MAC) |
| `AES-256-CBC` | 32 bytes | CBC | HMAC-SHA256 (encrypt-then-MAC) |
| `AES-128-GCM` | 16 bytes | GCM | Built-in (AEAD) |
| `AES-192-GCM` | 24 bytes | GCM | Built-in (AEAD) |
| `AES-256-GCM` | 32 bytes | GCM | Built-in (AEAD) |

Cipher names are case-insensitive (upper-cased internally), and an empty `Cipher` defaults to `AES-256-GCM`. The supplied key must decode to exactly the cipher's required raw byte length; an undersized key is rejected with `ErrInvalidKeyLength` rather than stretched (keys are never padded or hashed up to size). Internally the master key is split into distinct encryption and HMAC subkeys via HKDF-SHA256.

**Recommended**: `AES-256-GCM` for new projects (authenticated encryption, the default). Use a CBC mode only if you need interop with existing systems using that cipher; CBC ciphers still authenticate via encrypt-then-MAC and support AAD binding.

## API Reference

### Constructor and config

```go
// NewEncryptor validates the config and returns an Encryptor. Missing keys,
// unsupported ciphers, wrong-length keys, and malformed previous keys are
// all rejected up-front.
func NewEncryptor(config Config) (Encryptor, error)

// Config holds encryption configuration.
type Config struct {
    Key          string   // Primary encryption key (raw or "base64:" encoded)
    PreviousKeys []string  // Previous keys for rotation
    Cipher       string    // Cipher algorithm (empty defaults to AES-256-GCM)
}

// Validate checks that the Config is structurally usable without building a
// driver. Returns ErrInvalidKey (empty key), ErrInvalidCipher (unsupported
// cipher), ErrInvalidKeyLength (wrong key length), or ErrInvalidPreviousKey
// (a malformed/wrong-length rotation key). Consistent with NewEncryptor.
func (c Config) Validate() error
```

### Encryptor interface

```go
type Encryptor interface {
    // Encrypt encrypts plaintext and returns a base64 encoded payload.
    Encrypt(plaintext string) (string, error)

    // EncryptBytes encrypts bytes and returns a base64 encoded payload.
    EncryptBytes(plaintext []byte) (string, error)

    // Decrypt decrypts a base64 encoded payload and returns plaintext.
    Decrypt(payload string) (string, error)

    // DecryptBytes decrypts a base64 encoded payload and returns bytes.
    DecryptBytes(payload string) ([]byte, error)

    // EncryptBytesWithAAD encrypts plaintext and binds aad into the
    // authentication check. GCM folds aad into the AEAD tag; CBC mixes it
    // into the encrypt-then-MAC HMAC under a dedicated domain prefix. aad is
    // NOT persisted; the caller supplies the same aad on decrypt. nil and
    // zero-length aad are equivalent to EncryptBytes.
    EncryptBytesWithAAD(plaintext, aad []byte) (string, error)

    // DecryptBytesWithAAD decrypts a payload produced by EncryptBytesWithAAD.
    // Returns ErrAADMismatch on any authentication failure under the supplied
    // aad (wrong key, wrong aad, tamper, and AAD-vs-no-AAD mixing all collapse
    // to this single error). Returns ErrInvalidPayload for structural defects
    // (empty input, legacy v0 envelope, undersized nonce/tag).
    DecryptBytesWithAAD(payload string, aad []byte) ([]byte, error)

    // GenerateKey generates a new base64-encoded key for the cipher.
    GenerateKey() (string, error)
}
```

### Payload helpers

```go
// Payload is the encrypted wire structure (aliases drivers.Payload).
type Payload = drivers.Payload

// SerializePayload converts a payload to base64url JSON.
func SerializePayload(p *Payload) (string, error)

// DeserializePayload parses a base64url JSON envelope, accepting both v1
// ("v1:"-prefixed) and legacy v0 (bare) envelopes.
func DeserializePayload(encoded string) (*Payload, error)
```

### Sentinel errors

```go
crypto.ErrInvalidKey            // empty key (malformed base64 keys surface the raw decode error)
crypto.ErrInvalidKeyLength      // key does not match the cipher's key size
crypto.ErrInvalidCipher         // unsupported cipher
crypto.ErrInvalidPreviousKey    // a malformed / wrong-length rotation key
crypto.ErrInvalidPayload        // structural envelope defect
crypto.ErrDecrypt               // generic decrypt failure (wrong key/MAC/padding)
crypto.ErrDecryptionFailed      // alias of ErrDecrypt (kept for compatibility)
crypto.ErrAADMismatch           // auth failure on the AAD decrypt path
crypto.ErrLegacyPayloadDisabled // v0 payload rejected when CRYPTO_DISABLE_V0=true
```

Use `errors.Is` against these sentinels; they are re-exported from
`crypto/drivers` (and some hoisted to the `contract` package) under the same
identity so wrapping is transparent. There is no `ErrNotInitialized`: an
encryptor is always built explicitly, so the "not initialized" state cannot
occur.


**No oracle on the wire**: every cryptographic decrypt failure (wrong key, wrong MAC, bad padding, malformed IV) collapses to the single `ErrDecrypt` sentinel so callers cannot distinguish them via the error message (a padding-oracle precursor). Branch on `errors.Is` and never forward the underlying message to clients. Set `CRYPTO_DEBUG=true` to log the underlying stage server-side.


### Authenticating with Additional Authenticated Data (AAD)

All AES ciphers support binding extra context into the authentication check via
`EncryptBytesWithAAD` / `DecryptBytesWithAAD`. GCM folds the AAD into the AEAD
tag; CBC mixes it into the encrypt-then-MAC HMAC under a dedicated domain prefix
with an explicit length frame. The AAD is NOT persisted in the payload; the
caller supplies the same AAD on decrypt, and a mismatch fails the check. Pin
ciphertexts to row identity (`team_id|resource_type|resource_id`) so a row's
payload cannot be replayed against a different row even with a correct key.

```go
import "github.com/velocitykode/velocity/crypto"

func storeSecret(enc crypto.Encryptor, teamID, resourceID uint, plaintext []byte) (string, error) {
    aad := fmt.Appendf(nil, "team=%d|resource=secret|id=%d", teamID, resourceID)
    return enc.EncryptBytesWithAAD(plaintext, aad)
}

func loadSecret(enc crypto.Encryptor, teamID, resourceID uint, payload string) ([]byte, error) {
    aad := fmt.Appendf(nil, "team=%d|resource=secret|id=%d", teamID, resourceID)
    plaintext, err := enc.DecryptBytesWithAAD(payload, aad)
    if errors.Is(err, crypto.ErrAADMismatch) {
        // Wrong key, wrong AAD, AAD-vs-no-AAD payload mixing, or ciphertext
        // tamper. The auth check cannot tell them apart. Investigate key
        // rotation, ciphertext integrity, and aad construction together.
        return nil, fmt.Errorf("payload does not bind to (team=%d, secret=%d)", teamID, resourceID)
    }
    return plaintext, err
}
```

Contract:

- Available on all AES ciphers. GCM modes bind AAD into the AEAD tag; CBC
  modes bind it into the encrypt-then-MAC HMAC. There is no cipher that
  rejects the AAD methods (only third-party `Encryptor` implementations that
  cannot authenticate AAD would signal `crypto.ErrInvalidCipher`).
- `nil` AAD and zero-length AAD are equivalent (matching GCM's empty-AAD
  semantics), so an empty AAD produces the same result as `EncryptBytes`.
- Key rotation is honored: `DecryptBytesWithAAD` tries the active key first,
  then each entry in `Config.PreviousKeys` with the same AAD.
- `DecryptBytesWithAAD` accepts only v1 envelopes (payloads produced by
  `EncryptBytesWithAAD`). Legacy v0 payloads are rejected up-front with
  `crypto.ErrInvalidPayload` so a stray pre-v1 payload cannot surface as a
  fake AAD mismatch. Structural defects (undersized nonce or tag) also return
  `crypto.ErrInvalidPayload`.
- Any authentication failure on the AAD path collapses to
  `crypto.ErrAADMismatch` by design. The auth check cannot distinguish wrong
  key, wrong AAD, tamper, or AAD-vs-no-AAD payload mixing.
- AAD is never written to disk. Existing `Encrypt` / `Decrypt` callers are
  unaffected; the wire format for non-AAD payloads is unchanged.

### Custom Encryptor Instances

```go
import "github.com/velocitykode/velocity/crypto"

func createCustomEncryptor() {
    // Create encryptor with custom configuration
    config := crypto.Config{
        Key:    "base64:your-key-here",
        Cipher: "AES-256-GCM",
        PreviousKeys: []string{
            "base64:old-key-1",
            "base64:old-key-2",
        },
    }

    encryptor, err := crypto.NewEncryptor(config)
    if err != nil {
        log.Error("Failed to create encryptor", "error", err)
        return
    }

    // Use the custom encryptor
    encrypted, _ := encryptor.Encrypt("secret data")
    plaintext, _ := encryptor.Decrypt(encrypted)
}
```

## Key Rotation

Velocity supports seamless key rotation for enhanced security:

```go
// Step 1: Generate a new key (uses the encryptor's cipher)
newKey, _ := enc.GenerateKey()

// Step 2: Update your .env file
// Move current CRYPTO_KEY to CRYPTO_OLD_KEYS
// Set new key as CRYPTO_KEY
```

**Example `.env` after rotation:**
```env
# New key (used for encryption)
CRYPTO_KEY=base64:new-key-here

# Old keys (used for decryption only)
CRYPTO_OLD_KEYS=base64:old-key-1,base64:old-key-2
```

The encryptor will:
1. Always encrypt with the current key (`CRYPTO_KEY` / `Config.Key`)
2. Attempt decryption with the current key first
3. Fall back to previous keys (`CRYPTO_OLD_KEYS` / `Config.PreviousKeys`) in order
4. Return error if all keys fail

Previous keys are validated when the encryptor is built: a malformed or
wrong-length entry fails `NewEncryptor` with `ErrInvalidPreviousKey` rather
than being silently dropped, so a typo cannot quietly disable rotation.

### Re-encrypting Data

```go
func reencryptUserTokens(enc crypto.Encryptor) error {
    // Fetch all encrypted tokens
    var tokens []EncryptedToken
    db.Find(&tokens)

    for _, token := range tokens {
        // Decrypt with old key (automatic fallback)
        plaintext, err := enc.Decrypt(token.Value)
        if err != nil {
            log.Error("Failed to decrypt", "id", token.ID, "error", err)
            continue
        }

        // Re-encrypt with new key
        newEncrypted, err := enc.Encrypt(plaintext)
        if err != nil {
            log.Error("Failed to encrypt", "id", token.ID, "error", err)
            continue
        }

        // Update database
        token.Value = newEncrypted
        db.Save(&token)
    }

    return nil
}
```

## Payload Format

Every ciphertext is self-describing. The outer string is a version sentinel
followed by a base64url-encoded JSON envelope:

```
v1:<base64url(JSON)>
```

The `v1:` prefix marks the current wire format (the colon cannot appear in
base64 output, so it is unambiguous). The inner JSON fields are individually
base64-encoded:

### CBC Mode Payload
```json
{
  "iv": "base64-encoded-initialization-vector",
  "value": "base64-encoded-ciphertext",
  "mac": "base64-encoded-hmac-sha256"
}
```

### GCM Mode Payload
```json
{
  "iv": "base64-encoded-nonce",
  "value": "base64-encoded-ciphertext",
  "tag": "base64-encoded-auth-tag"
}
```

You can inspect a stored ciphertext with `crypto.DeserializePayload`, which
returns the `crypto.Payload` struct and accepts both `v1:`-prefixed and legacy
bare (v0) envelopes.


**Legacy v0 payloads**: bare (unprefixed) envelopes from before the versioned wire format are still accepted on decrypt for one release cycle (removed in v2.0). A successful v0 decrypt logs a one-shot warning and dispatches a `crypto.legacy_decrypt` event so you can track the rotation window. Set `CRYPTO_DISABLE_V0=true` to reject v0 outright (with `ErrLegacyPayloadDisabled`) once you have confirmed no v0 ciphertexts remain.


## Common Use Cases

### Encrypting Sensitive Database Fields

```go
type User struct {
    ID              uint
    Email           string
    EncryptedAPIKey string `orm:"column:api_key"`
}

func (u *User) SetAPIKey(enc crypto.Encryptor, key string) error {
    encrypted, err := enc.Encrypt(key)
    if err != nil {
        return err
    }
    u.EncryptedAPIKey = encrypted
    return nil
}

func (u *User) GetAPIKey(enc crypto.Encryptor) (string, error) {
    return enc.Decrypt(u.EncryptedAPIKey)
}
```

### Encrypting Session Data

```go
func encryptSession(enc crypto.Encryptor, data map[string]interface{}) (string, error) {
    // Serialize to JSON
    jsonData, err := json.Marshal(data)
    if err != nil {
        return "", err
    }

    // Encrypt
    return enc.EncryptBytes(jsonData)
}

func decryptSession(enc crypto.Encryptor, encrypted string) (map[string]interface{}, error) {
    // Decrypt
    jsonData, err := enc.DecryptBytes(encrypted)
    if err != nil {
        return nil, err
    }

    // Deserialize from JSON
    var data map[string]interface{}
    if err := json.Unmarshal(jsonData, &data); err != nil {
        return nil, err
    }

    return data, nil
}
```

### Encrypting File Contents

```go
func encryptFile(enc crypto.Encryptor, inputPath, outputPath string) error {
    // Read file
    data, err := os.ReadFile(inputPath)
    if err != nil {
        return err
    }

    // Encrypt
    encrypted, err := enc.EncryptBytes(data)
    if err != nil {
        return err
    }

    // Write encrypted data
    return os.WriteFile(outputPath, []byte(encrypted), 0644)
}

func decryptFile(enc crypto.Encryptor, inputPath, outputPath string) error {
    // Read encrypted file
    encrypted, err := os.ReadFile(inputPath)
    if err != nil {
        return err
    }

    // Decrypt
    data, err := enc.DecryptBytes(string(encrypted))
    if err != nil {
        return err
    }

    // Write decrypted data
    return os.WriteFile(outputPath, data, 0644)
}
```

## Security Best Practices

1. **Use Strong Keys**: Always use `enc.GenerateKey()` to generate cryptographically secure keys
2. **Rotate Keys Regularly**: Implement periodic key rotation (e.g., every 90 days)
3. **Use GCM for New Projects**: GCM mode provides authenticated encryption
4. **Protect Your Keys**: Never commit `.env` files to version control
5. **Use HTTPS**: Always transmit encrypted data over secure connections
6. **Validate Before Decrypt**: Check data integrity before decryption
7. **Log Failures Carefully**: Don't log plaintext or keys in error messages

## Error Handling

Validate configuration up-front when building an encryptor:

```go
func buildEncryptor(cfg crypto.Config) (crypto.Encryptor, error) {
    enc, err := crypto.NewEncryptor(cfg)
    if err != nil {
        switch {
        case errors.Is(err, crypto.ErrInvalidKey):
            log.Error("Missing or empty encryption key")
        case errors.Is(err, crypto.ErrInvalidKeyLength):
            log.Error("Key length does not match cipher")
        case errors.Is(err, crypto.ErrInvalidCipher):
            log.Error("Unsupported cipher")
        case errors.Is(err, crypto.ErrInvalidPreviousKey):
            log.Error("A previous (rotation) key is malformed")
        default:
            log.Error("Failed to build encryptor", "error", err)
        }
        return nil, err
    }
    return enc, nil
}
```

Branch on the sentinels when decrypting:

```go
func handleDecrypt(enc crypto.Encryptor, encrypted string) {
    plaintext, err := enc.Decrypt(encrypted)
    if err != nil {
        switch {
        case errors.Is(err, crypto.ErrInvalidPayload):
            log.Error("Invalid encrypted payload format")
        case errors.Is(err, crypto.ErrDecrypt): // ErrDecryptionFailed is an alias
            log.Error("Decryption failed - wrong key or corrupted data")
        case errors.Is(err, crypto.ErrLegacyPayloadDisabled):
            log.Error("Legacy v0 payload rejected - re-encrypt this value")
        default:
            log.Error("Decryption failed", "error", err)
        }
        return
    }

    fmt.Println(plaintext)
}
```

## Testing

```go
func TestEncryption(t *testing.T) {
    // Build an encryptor with a test key
    testKey := "base64:" + base64.StdEncoding.EncodeToString(make([]byte, 32))
    enc, err := crypto.NewEncryptor(crypto.Config{
        Key:    testKey,
        Cipher: "AES-256-GCM",
    })
    assert.NoError(t, err)

    // Test encryption/decryption
    plaintext := "test data"
    encrypted, err := enc.Encrypt(plaintext)
    assert.NoError(t, err)
    assert.NotEqual(t, plaintext, encrypted)

    decrypted, err := enc.Decrypt(encrypted)
    assert.NoError(t, err)
    assert.Equal(t, plaintext, decrypted)

    // Test bytes encryption
    data := []byte("binary data")
    encryptedBytes, err := enc.EncryptBytes(data)
    assert.NoError(t, err)

    decryptedBytes, err := enc.DecryptBytes(encryptedBytes)
    assert.NoError(t, err)
    assert.Equal(t, data, decryptedBytes)
}
```

To verify a third-party `Encryptor` implementation satisfies the full
behavioral contract (round-trip, AAD binding, key rotation, tamper detection),
run it against the executable spec in the `cryptotest` package:

```go
import "github.com/velocitykode/velocity/crypto/cryptotest"

func TestMyEncryptor_Contract(t *testing.T) {
    cryptotest.RunEncryptorContractTests(t, func(t *testing.T) crypto.Encryptor {
        enc, err := crypto.NewEncryptor(crypto.Config{
            Key:    "base64:" + base64.StdEncoding.EncodeToString(make([]byte, 32)),
            Cipher: "AES-256-GCM",
        })
        if err != nil {
            t.Fatalf("NewEncryptor: %v", err)
        }
        return enc
    })
}
```

## Performance Considerations

- **AES-GCM is faster**: GCM mode typically performs better than CBC
- **Encrypt once**: Cache encrypted values when possible
- **Batch operations**: Group encryption operations to amortize overhead
- **Key size impact**: AES-256 is slightly slower than AES-128 but more secure
- **Reuse the encryptor**: subkey derivation (HKDF) happens once at construction, so build the `Encryptor` once and share it rather than per-operation


================================================================================
# Routing

Source: https://vel.build/docs/core/routing/
Section: Core Framework
Summary: Define routes in Velocity using the declarative Routing API.


Velocity organizes routing around a single `Register` function in your
`routes` package. The framework calls it during bootstrap and hands
you a `*velocity.Routing` value - that value knows how to attach the
right middleware stack (web vs API) to each group of routes you
declare.

This page covers:

- Defining web and API routes with their middleware stacks
- Wiring `Register` into `main.go` via the declarative bootstrap chain
- Applying middleware to groups and individual routes
- The reference for `*velocity.Routing` and `router.Router`

For low-level details - the `Context` API, JSON binding, named-route
URL generation - see [HTTP Router](/docs/core/http-router).

## Defining routes

```go
// routes/web.go
package routes

import (
    "myapp/internal/handlers"
    "myapp/internal/middleware"

    "github.com/velocitykode/velocity"
    "github.com/velocitykode/velocity/router"
)

// Register is the single entry point. main.go passes this function to
// v.Routes(...) - the framework calls it with a *velocity.Routing
// already wired with the configured middleware stacks.
func Register(r *velocity.Routing) {
    // Operational endpoints sit at the top level - they don't run any
    // middleware stack so load balancers can probe /health cheaply.
    r.Health("/health")
    r.Static("public")

    r.Web(func(web router.Router) {
        // Public web pages
        web.Get("/", handlers.Home)        // /
        web.Get("/about", handlers.About)  // /about

        // Guest-only - middleware.Guest redirects authenticated users
        // to /dashboard.
        web.Group("", func(guest router.Router) {
            guest.Get("/login", handlers.AuthShowLoginForm)        // /login
            guest.Post("/login", handlers.AuthLogin)               // /login
            guest.Get("/register", handlers.AuthShowRegisterForm)  // /register
            guest.Post("/register", handlers.AuthRegister)         // /register
        }).Use(middleware.Guest)

        web.Post("/logout", handlers.AuthLogout)  // /logout

        // Authenticated - middleware.Auth redirects guests to /login.
        web.Group("", func(auth router.Router) {
            auth.Get("/dashboard", handlers.Dashboard).Name("dashboard")  // /dashboard
            auth.Get("/account", handlers.Account)                        // /account
        }).Use(middleware.Auth)
    })

    // API routes - every route here is prefixed with /api/v1 and runs
    // the API middleware stack (JSON enforcement, etc.). It does NOT
    // run the web stack - no sessions, no CSRF.
    r.API("/api/v1", func(api router.Router) {
        api.Get("/users", handlers.ListUsers)      // /api/v1/users
        api.Post("/users", handlers.CreateUser)    // /api/v1/users
        api.Get("/users/{id}", handlers.ShowUser)  // /api/v1/users/{id}
    })
}
```

## Wiring routes into the app

`main.go` builds the bootstrap chain - Modules (auth, CSRF, view
config), Middleware (the global / web / API stacks), Routes (this
file), Events (your listeners) - then either runs a CLI command or
serves HTTP based on whether arguments were passed.

```go
// main.go
package main

import (
    "log"
    "os"

    "myapp/internal/app"
    "myapp/routes"

    "github.com/velocitykode/velocity"

    // Blank import so each migration file's init() runs and calls
    // migrate.Register() - otherwise `vel migrate` finds nothing.
    _ "myapp/database/migrations"
)

func main() {
    v, err := velocity.New()
    if err != nil {
        log.Fatal(err)
    }

    chain := v.
        Modules(app.Configure).
        Middleware(app.Middleware).
        Routes(routes.Register).
        Events(app.Events(v.Log))

    // With CLI args (`vel migrate`, `vel gen handler`, ...) dispatch
    // the command. Routes still need to be registered before this so
    // `vel routes` sees them.
    if len(os.Args) > 1 {
        if err := chain.Run(); err != nil {
            log.Fatal(err)
        }
        return
    }

    // No args - start the HTTP server.
    if err := chain.Serve(); err != nil {
        log.Fatal(err)
    }
}
```

The callbacks (`app.Configure`, `app.Middleware`, `app.Events`,
`routes.Register`) live in your own packages. Each one matches the
argument type of the chain method it is passed to; the relevant
signatures are:

```go
// internal/app/bootstrap.go
func Configure(reg *velocity.ModuleRegistry)

// internal/app/middleware.go
func Middleware(m *velocity.MiddlewareStack)

// internal/app/events.go
func Events(logger log.Logger) func(events.Dispatcher)

// routes/web.go
func Register(r *velocity.Routing)
```

`Events` is a function that returns a function so the listener body
can capture the logger. The other three take a single configuration
value.

## HTTP verb methods

Inside a `r.Web(...)` or `r.API(...)` closure, every verb method
takes a path and a handler:

```go
web.Get("/users", handlers.ListUsers)          // /users
web.Post("/users", handlers.CreateUser)        // /users
web.Put("/users/{id}", handlers.ReplaceUser)   // /users/{id}
web.Patch("/users/{id}", handlers.UpdateUser)  // /users/{id}
web.Delete("/users/{id}", handlers.DeleteUser) // /users/{id}
web.Options("/users", handlers.UsersOptions)   // /users
web.Head("/users/{id}", handlers.HeadUser)     // /users/{id}
```

Path parameters use `{name}`. Read them in the handler with
`c.Param("name")` - see the [HTTP Router page](/docs/core/http-router#reading-parameters)
for the full Context API.

Each verb method returns a `RouteConfig` for chaining `.Name(...)`
and `.Use(...)`:

```go
web.Get("/posts/{id}", handlers.ShowPost).  // /posts/{id}
    Name("posts.show").
    Use(middleware.Cache(5 * time.Minute))
```

`.Name("posts.show")` registers the route under a stable identifier
so you can generate URLs from anywhere in the app - handlers,
templates, redirects - without hardcoding the path. Build a URL with
`r.Router().RouteURL("posts.show", map[string]string{"id": "42"})`
and you get `/posts/42` back. If you later rename the path to
`/articles/{id}`, every callsite using the name keeps working.

## Groups

`Group` opens a sub-router with a shared path prefix and (optionally)
shared middleware. Groups can nest.

### With a path prefix

```go
web.Group("/admin", func(admin router.Router) {
    admin.Get("/dashboard", handlers.AdminDashboard)  // /admin/dashboard
    admin.Post("/users/{id}/ban", handlers.BanUser)   // /admin/users/{id}/ban
}).Use(middleware.RequireAdmin)
```

### With no prefix - middleware grouping

A `""` prefix is the idiom for grouping routes purely so they share
middleware:

```go
web.Group("", func(auth router.Router) {
    auth.Get("/account", handlers.Account)  // /account
    auth.Get("/billing", handlers.Billing)  // /billing
}).Use(middleware.Auth)
```

### Nested groups

```go
r.API("/api", func(api router.Router) {
    api.Group("/v1", func(v1 router.Router) {
        v1.Get("/users", handlers.ListUsers)    // /api/v1/users
        v1.Post("/users", handlers.CreateUser)  // /api/v1/users
    })

    api.Group("/v2", func(v2 router.Router) {
        v2.Get("/users", handlers.ListUsersV2)  // /api/v2/users
    })
})
```

Each level inherits the parent's prefix and middleware.

## Reference: `*velocity.Routing`

The value `Register` receives. Use it to declare the top-level shape
of your routes - health checks, static assets, web group, API groups.

| Method                  | Purpose                                                         |
| ----------------------- | --------------------------------------------------------------- |
| `r.Web(fn)`             | Open a web group. Inside, the configured **web** middleware stack runs (sessions, CSRF, view engine). Use for browser/HTML routes. |
| `r.API(prefix, fn)`     | Open an API group under `prefix`. Inside, the configured **api** middleware stack runs (JSON enforcement, etc.). Use for JSON APIs. |
| `r.Health(path)`        | Register a `GET path` that returns `200 OK` with body `OK`. Sits outside any middleware stack - load balancers can probe it without paying for sessions/CSRF. |
| `r.Static(dir)`         | Serve every file under `dir` as a static asset at the URL path matching the relative file path. Also outside middleware stacks. |
| `r.Services()`          | Get the `*app.Services` container - useful when you need a service at registration time rather than via the request context. |
| `r.Router()`            | Escape hatch - returns the underlying `*router.VelocityRouterV2`. Reach for this only when none of the above fits. |

## Reference: `router.Router`

The value passed into your `r.Web(...)` / `r.API(...)` / `Group(...)`
closures. The routing primitive - verb methods, sub-groups, middleware.

### Verb methods

| Method                              | Purpose                  |
| ----------------------------------- | ------------------------ |
| `Get(path, handler) RouteConfig`    | Register a `GET` route   |
| `Post(path, handler) RouteConfig`   | Register a `POST` route  |
| `Put(path, handler) RouteConfig`    | Register a `PUT` route   |
| `Patch(path, handler) RouteConfig`  | Register a `PATCH` route |
| `Delete(path, handler) RouteConfig` | Register a `DELETE` route|
| `Options(path, handler) RouteConfig`| Register an `OPTIONS` route |
| `Head(path, handler) RouteConfig`   | Register a `HEAD` route  |

### Composition

| Method                                     | Purpose                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------ |
| `Group(prefix, fn ...func(Router)) Router` | Open a sub-group. Returns the inner Router so you can chain `.Use(...)`. |
| `Use(mw ...MiddlewareFunc) Router`         | Apply middleware to every route in this scope.                           |

### Per-route configuration: `RouteConfig`

Every verb method returns a `RouteConfig` for chaining:

| Method                                   | Purpose                                                                                                                              |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `.Name(name) RouteConfig`                | Name the route. Generate URLs with `r.Router().RouteURL(name, params)`. Names must be unique across the app.                         |
| `.Use(mw ...MiddlewareFunc) RouteConfig` | Apply middleware to just this one route - wraps the handler last (innermost).                                                        |


================================================================================
# Validation

Source: https://vel.build/docs/core/validation/
Section: Core Framework
Summary: Validate HTTP requests and form data with Velocity's typed, rule-based validation system.


Velocity provides a flexible, extensible validation system for validating HTTP requests, form data, and general data structures. Rules are **typed values** built by constructors in the `validation` package and collected in a `validation.Rules` set keyed by field name.

Import path: `github.com/velocitykode/velocity/validation`

Database-backed rules (`Unique`, `Exists`) execute in `github.com/velocitykode/velocity/validation/dbrules`, a separate leaf so the core validation package carries no ORM or SQL-driver dependency.

For HTTP handlers, the higher-level [form-request](/docs/core/form-requests) helper (`vform.Form[T]`) wraps the rules below with binding, flashing, and redirect-on-failure. Reach for `vform` first; reach for `validation.Check*` directly when you need a custom render path or you're validating data that isn't an HTTP request.

## Quick Start


**Typed and declarative**: a rule is a value, not a string. `validation.Min(8)` is a function call the compiler checks, so a typo is a build failure instead of a runtime "unknown validation rule".





```go
import "github.com/velocitykode/velocity/validation"

func validateUser(data map[string]interface{}) error {
    rules := validation.Rules{
        "email":    {validation.Required(), validation.Email()},
        "password": {validation.Required(), validation.Min(8)},
        "age":      {validation.Required(), validation.Numeric(), validation.Gte("18")},
        "username": {validation.Required(), validation.AlphaNum()},
    }

    result, err := validation.CheckData(data, rules)
    if err != nil {
        // Malformed rule set (wraps validation.ErrInvalidRule): a bug in this
        // code, not bad user input. Field failures never travel here.
        return err
    }
    if result.HasErrors() {
        // result.All() is map[string]string (first error per field).
        // result.Messages() is map[string][]string (all errors per field).
        fmt.Println("Validation failed:", result.All())
        return result.Err()
    }

    // No errors, use the input directly.
    return nil
}
```



```go
import (
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/validation"
)

func RegisterUser(c *router.Context) error {
    rules := validation.Rules{
        "name":     {validation.Required(), validation.String()},
        "email":    {validation.Required(), validation.Email()},
        "password": {validation.Required(), validation.Min(8), validation.Confirmed()},
        "age":      {validation.Required(), validation.Numeric(), validation.Gte("18")},
        "terms":    {validation.Required(), validation.Accepted()},
    }

    result, err := validation.CheckW(c.Response, c.Request, rules)
    if err != nil {
        return err
    }
    if result.HasErrors() {
        return c.JSON(422, map[string]interface{}{
            "errors": result.Messages(),
        })
    }

    // Validation passed, bind the request body and proceed.
    var input struct {
        Name, Email, Password string
        Age                   int
    }
    if err := c.BindAuto(&input); err != nil {
        return err
    }

    return c.JSON(200, input)
}
```



```go
import (
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/validation"
)

func validateWithCustomMessages(c *router.Context) error {
    rules := validation.Rules{
        "email":    {validation.Required(), validation.Email()},
        "password": {validation.Required(), validation.Min(8)},
    }

    // Messages are keyed by a {Field, Rule} pair, not a "field.rule" string.
    messages := validation.Messages{
        {Field: "email", Rule: "required"}:    "Please provide your email address",
        {Field: "email", Rule: "email"}:       "Please enter a valid email address",
        {Field: "password", Rule: "required"}: "Password is required",
        {Field: "password", Rule: "min"}:      "Password must be at least 8 characters",
    }

    result, err := validation.CheckW(c.Response, c.Request, rules, messages)
    if err != nil {
        return err
    }
    if result.HasErrors() {
        return c.JSON(422, map[string]interface{}{
            "errors": result.Messages(),
        })
    }

    return nil
}
```




## Configuration

The validation package works out of the box with no configuration required and reads no environment variables. Behavior is fixed by the engine: rules for a field run in declared order and evaluation **bails on the first failing rule per field** (the field stops accumulating errors once one rule fails), while every other field is still evaluated. Custom messages are supplied per call (or once per `Validator` via `SetMessages`), and custom rules carry their own handler on the rule value (see [Custom Validation Rules](#custom-validation-rules)), so neither goes through a global registry.

Request bodies read by `Check` / `CheckW` are capped at `validation.DefaultMaxBodyBytes` (10 MiB, matching `router.DefaultMaxBodySize`). An oversized body does not truncate silently; it produces a field-level error keyed `_body` reading `"The request body is too large."`.

## Rules are values

A `validation.Rules` set maps a field name to the rules applied to it. Each entry is a `validation.Rule` value returned by a constructor:

```go
rules := validation.Rules{
    "name":  {validation.Required(), validation.Min(3)},
    "email": {validation.Required(), validation.Email(), validation.Unique("users", "email")},
}
```

Three properties follow from rules being values rather than strings:

- **Parameters are carried pre-split and are never re-tokenized.** A parameter may contain any character, including `,` and `|`, so `validation.Regex("^(foo|bar),(baz)$")` and `validation.In("Doe, John", "Roe, Jane")` survive intact.
- **Rule values are immutable and safe to share.** Builder methods such as `Unique(...).Except(id)` return a new value instead of mutating the receiver, so a package-level `var CommonRules = validation.Rules{...}` can be reused concurrently.
- **Rule sets are checked before they run.** Normalization reports a nil rule, an empty rule name, an unusable `Except` argument, a custom rule with a nil handler, a custom name that shadows a framework rule, and two distinct rule values claiming one custom name. Every such failure wraps `validation.ErrInvalidRule` and comes back on the `error` return, never as a field message.


Evaluation is preceded by a resolution check. A rule that nothing provides (a `Custom` name that was never wired, or `Unique` / `Exists` with no database attached) is reported to the caller through the `error` return instead of failing the user's field. That keeps a handler bug distinct from bad input.


## Available Rules

Velocity ships 49 built-in rules plus two database rules (`Unique`, `Exists`) supplied by `validation/dbrules` when validation runs against an `orm.Database`.

The table below is the complete catalog. The **Rule name** column is the string the engine reports on failure, which is what a `validation.Messages` key and `ValidationErrors.HasRule` match on. The **Absent / nil** column describes how the rule treats a field that is missing or `nil`; combine with `Required()` to enforce presence and with `Nullable()` / `Filled()` for opt-out semantics.

| Constructor | Rule name | Example | Absent / nil |
|---|---|---|---|
| `Accepted()` | `accepted` | `{"terms": {validation.Accepted()}}` | fails |
| `Alpha()` | `alpha` | `{"name": {validation.Alpha()}}` | passes (use with `Required()`) |
| `AlphaDash()` | `alpha_dash` | `{"slug": {validation.AlphaDash()}}` | passes |
| `AlphaNum()` | `alpha_num` | `{"username": {validation.AlphaNum()}}` | passes |
| `Array()` | `array` | `{"tags": {validation.Array()}}` | passes |
| `Between(min, max int)` | `between` | `{"age": {validation.Numeric(), validation.Between(18, 65)}}` | passes |
| `Boolean()` | `boolean` | `{"active": {validation.Boolean()}}` | passes |
| `Confirmed()` | `confirmed` | `{"password": {validation.Confirmed()}}` | passes (skipped when value is `nil`) |
| `Date()` | `date` | `{"published_at": {validation.Date()}}` | passes |
| `DateFormat(layout string)` | `date_format` | `{"day": {validation.DateFormat("2006-01-02")}}` | passes |
| `Different(field string)` | `different` | `{"alt_email": {validation.Different("email")}}` | passes |
| `Email()` | `email` | `{"email": {validation.Email()}}` | empty string fails; `nil` passes |
| `EndsWith(suffix string, ...)` | `ends_with` | `{"file": {validation.EndsWith(".pdf", ".png")}}` | passes |
| `Exists(table, column string)` | `exists` | `{"team_id": {validation.Exists("teams", "id")}}` | passes (DB rule, see below) |
| `File()` | `file` | `{"avatar": {validation.File()}}` | passes |
| `Filled()` | `filled` | `{"bio": {validation.Filled()}}` | passes when field absent; fails when present-but-empty |
| `Gt(field string)` | `gt` | `{"max": {validation.Gt("min")}}` | passes |
| `Gte(field string)` | `gte` | `{"qty": {validation.Gte("1")}}` | passes |
| `Image()` | `image` | `{"avatar": {validation.Image()}}` | passes |
| `In(value string, ...)` | `in` | `{"role": {validation.In("admin", "user", "mod")}}` | passes |
| `Integer()` | `integer` | `{"age": {validation.Integer()}}` | passes |
| `IP()` | `ip` | `{"addr": {validation.IP()}}` | empty string fails; `nil` passes |
| `IPv4()` | `ipv4` | `{"addr": {validation.IPv4()}}` | empty string fails; `nil` passes |
| `IPv6()` | `ipv6` | `{"addr": {validation.IPv6()}}` | empty string fails; `nil` passes |
| `JSON()` | `json` | `{"meta": {validation.JSON()}}` | passes |
| `Lt(field string)` | `lt` | `{"min": {validation.Lt("max")}}` | passes |
| `Lte(field string)` | `lte` | `{"qty": {validation.Lte("100")}}` | passes |
| `Max(n int)` | `max` | `{"bio": {validation.Max(500)}}` | passes |
| `Mimes(ext string, ...)` | `mimes` | `{"upload": {validation.Mimes("jpg", "png", "pdf")}}` | passes |
| `Min(n int)` | `min` | `{"password": {validation.Min(8)}}` | passes |
| `NotIn(value string, ...)` | `not_in` | `{"username": {validation.NotIn("admin", "root")}}` | passes |
| `Nullable()` | `nullable` | `{"middle_name": {validation.Nullable(), validation.String()}}` | always passes (marker) |
| `Numeric()` | `numeric` | `{"price": {validation.Numeric()}}` | passes |
| `Password()` | `password` | `{"pw": {validation.Password()}}` | fails (treats empty as missing) |
| `Present()` | `present` | `{"opt_in": {validation.Present()}}` | fails when key absent; passes when key present-but-empty |
| `Regex(pattern string)` | `regex` | `{"sku": {validation.Regex("^[A-Z]{3}$")}}` | passes (pattern must be `^...$` anchored) |
| `Required()` | `required` | `{"name": {validation.Required()}}` | fails on `nil`, `""`, empty slice/map |
| `RequiredIf(field, value string)` | `required_if` | `{"phone": {validation.RequiredIf("contact", "phone")}}` | conditional |
| `RequiredUnless(field, value string)` | `required_unless` | `{"company": {validation.RequiredUnless("type", "personal")}}` | conditional |
| `RequiredWith(field string, ...)` | `required_with` | `{"shipping": {validation.RequiredWith("address")}}` | conditional (any named field present) |
| `RequiredWithout(field string, ...)` | `required_without` | `{"sku": {validation.RequiredWithout("gtin")}}` | conditional (any named field absent) |
| `Same(field string)` | `same` | `{"pw_confirm": {validation.Same("password")}}` | passes |
| `Size(n int)` | `size` | `{"zip": {validation.Size(5)}}` | passes |
| `StartsWith(prefix string, ...)` | `starts_with` | `{"url": {validation.StartsWith("https://")}}` | passes |
| `String()` | `string` | `{"name": {validation.String()}}` | passes |
| `Timezone()` | `timezone` | `{"tz": {validation.Timezone()}}` | empty string fails; `nil` passes |
| `ULID()` | `ulid` | `{"id": {validation.ULID()}}` | passes |
| `Unique(table, column string)` | `unique` | `{"email": {validation.Unique("users", "email")}}` | passes (DB rule, see below) |
| `URL()` | `url` | `{"website": {validation.URL()}}` | empty string fails; `nil` passes |
| `URLPublic()` | `url_public` | `{"webhook": {validation.URLPublic()}}` | same as `URL()` plus rejects private/internal hosts |
| `UUID()` | `uuid` | `{"id": {validation.UUID()}}` | passes |

Constructors whose handler needs at least one parameter take the first one as a required argument, so an empty parameter list does not compile: `In`, `NotIn`, `StartsWith`, `EndsWith`, `Mimes`, `RequiredWith`, and `RequiredWithout`.

Four constructors return a builder value rather than a bare `Rule`, because they accept options: `Password()` returns `PasswordSpec`, `Mimes(...)` returns `MimesSpec`, `Image()` returns `ImageSpec`, and `Unique(...)` returns `UniqueSpec`. All four satisfy the `Rule` interface, so they drop into a `Rules` set unchanged.


The `confirmed` rule on field `<X>` looks for a sibling field named `<X>_confirmation` in the input map and compares the two with `reflect.DeepEqual`. The convention is fixed; the suffix is not configurable. If the confirmation field is missing or differs, validation fails with `"The <X> confirmation does not match."`, reported on `<X>` itself (not on the confirmation field), so bind the message to the primary input.

```go
rules := validation.Rules{
    "password": {validation.Required(), validation.Min(8), validation.Confirmed()},
}

// Both fields must arrive in the request:
//   password=secret123
//   password_confirmation=secret123
```

`Confirmed()` returns success when the source field is `nil`, so combine it with `Required()` if the field itself is mandatory. Use [`Same`](#confirmed--same--different) instead when you need to match against an arbitrary field name.


### Highlights

#### Required()

Field must be present and not empty (`nil`, `""`, empty slice, empty map all fail):

```go
rules := validation.Rules{"name": {validation.Required()}}
```

#### Nullable() / Filled() / Present()

`Nullable()` is a marker whose effect lives in the engine loop: when the field's value is empty (`nil` or `""`), **every other rule on that field is skipped, including `Required()`**. `Filled()` accepts an absent field but fails when the field is present and empty. `Present()` requires the key to exist in the input map but allows an empty value.

```go
rules := validation.Rules{
    "middle_name": {validation.Nullable(), validation.String()},
    "bio":         {validation.Filled()},
    "opt_in":      {validation.Present()},
}
```

`Nullable()`'s notion of empty is deliberately narrow (`nil` or `""`) and does not extend to empty slices or maps: it exists for the HTML-form case where an untouched optional text input submits `""`.

#### Min() / Max() / Size() / Between()

These rules adapt to the value's runtime type. On strings they measure byte length (Go's `len`, not rune count, so multi-byte UTF-8 characters count as more than one); on `int` and `float64` they compare values; on slices they count elements.

```go
rules := validation.Rules{
    "password": {validation.Min(8)},
    "bio":      {validation.Max(500)},
    "zip_code": {validation.Size(5)},
    "age":      {validation.Numeric(), validation.Between(18, 65)},
}
```


`Min` / `Max` / `Size` / `Between` branch on the Go type they receive. A number posted through an HTML form arrives as a `string`, so `validation.Min(18)` on it measures **length**, not magnitude. Use `Gte("18")` for numeric bounds on values that may arrive as strings: the numeric comparison rules parse strings into `float64` first.


#### Confirmed() / Same() / Different()

Cross-field comparisons. `Confirmed()` is a special-cased `Same` that targets `<field>_confirmation`. `Same` and `Different` accept any sibling field name as their parameter.

```go
rules := validation.Rules{
    "password":         {validation.Required(), validation.Confirmed()},
    "password_confirm": {validation.Same("password")},
    "alt_email":        {validation.Different("email")},
}
```

#### In() / NotIn()

Value must (or must not) be one of the listed values. The first value is a separate parameter, so a zero-value call does not compile:

```go
rules := validation.Rules{
    "role":     {validation.In("admin", "user", "moderator")},
    "username": {validation.NotIn("admin", "root", "system")},
}
```

Because parameters are carried pre-split, a value containing a comma is fine: `validation.In("Doe, John", "Roe, Jane")`.

#### Accepted()

Field must be `yes`, `on`, `1`, or `true` (case-insensitive for strings; `true` and `1` also accepted as `bool` / `int`). Useful for terms-of-service checkboxes:

```go
rules := validation.Rules{"terms": {validation.Accepted()}}
```

#### RequiredIf() / RequiredUnless() / RequiredWith() / RequiredWithout()

Conditional presence rules. Use them when a field is required only when another field has a particular value, or only when other fields are present/absent:

```go
rules := validation.Rules{
    "phone":    {validation.RequiredIf("contact", "phone")},
    "company":  {validation.RequiredUnless("type", "personal")},
    "shipping": {validation.RequiredWith("address")},
    "sku":      {validation.RequiredWithout("gtin")},
}
```

`RequiredWith` and `RequiredWithout` take any number of field names and honour every one of them: `RequiredWith("a", "b")` requires the field when **any** of the named fields is present, `RequiredWithout("a", "b")` when **any** is absent.

```go
rules := validation.Rules{
    "billing_zip": {validation.RequiredWith("billing_street", "billing_city")},
}
```

#### Gt() / Gte() / Lt() / Lte()

Strict / inclusive numeric comparisons. The parameter is a string that is first parsed as a numeric literal; if that fails it is looked up as another field name and the threshold is read from that field's numeric value:

```go
rules := validation.Rules{
    "max_price": {validation.Numeric(), validation.Gt("min_price")}, // field reference
    "qty":       {validation.Numeric(), validation.Lte("100")},      // numeric literal
}
```

A parameter that is neither numeric nor an existing numeric field fails the field with a message naming the offending parameter.

#### Password()

Stricter than `Min`. Requires length >= 8 plus at least one uppercase letter, one lowercase letter, one digit, and one symbol. `MinLength(n)` returns a new rule that raises the length floor (values below 1 leave the built-in floor of 8 in place); the character-class requirements are always on.

```go
rules := validation.Rules{
    "pw": {validation.Required(), validation.Password()},            // >= 8, all classes
    "pw": {validation.Required(), validation.Password().MinLength(12)}, // >= 12
}
```

#### Regex()

The pattern must be anchored with `^...$` and is rejected if AST analysis finds a catastrophic-backtracking shape (e.g. `(a+)+`). Values longer than 4096 bytes are rejected before matching, and each evaluation is bounded to 10 ms. Compiled patterns are cached.

```go
rules := validation.Rules{"sku": {validation.Regex(`^[A-Z]{3}-\d{4}$`)}}
```

The pattern is carried verbatim in a single parameter, so alternations (`|`) and quantifiers (`{2,4}`) need no escaping.

#### File() / Mimes() / Image()

`File()` confirms the value carries `*multipart.FileHeader`-shaped metadata (any type exposing a `Filename` and `Size`, plus `Open() (multipart.File, error)` for sniffing). `Mimes(...)` checks the filename's extension against an allowlist **and** sniffs the first 512 bytes so a renamed payload (e.g. `payload.php.jpg`) is rejected; script-runner extensions and PE/ELF/Mach-O/Java-class magic bytes are refused outright regardless of the parameter list. `Image()` is a shortcut for the raster image extensions (`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.bmp`, `.heic`, `.heif`, `.avif`).

SVG is **excluded by default** because SVG is XML and can carry `<script>`. Opt in with the builder method:

```go
rules := validation.Rules{
    "avatar":   {validation.Image(), validation.Max(2048)},
    "document": {validation.File(), validation.Mimes("pdf", "docx")},
    "logo":     {validation.Image().AllowSVG()},
    "asset":    {validation.Mimes("jpg", "svg").AllowSVG()},
}
```


`ExtractRequestData` does not populate multipart files, so `File` / `Mimes` / `Image` see nothing for an upload field unless you merge the `*multipart.FileHeader` into the data map yourself and validate with `CheckData`. For a one-off header check without a rule set, `ctx.ValidateFile(fh, opts...)` in the router package takes the header directly.


#### Unique() / Exists() (database rules)

`Unique` and `Exists` describe the check; execution lives in `validation/dbrules`, which owns the ORM dependency. They resolve whenever validation runs through a DB-aware entry point: `ctx.Validate`, `ctx.BindValid`, `vform.Form[T]` / `vform.Validate[T]`, or `dbrules.Check*` called directly. An empty column argument defaults to the field name at evaluation time.

```go
rules := validation.Rules{
    "email":   {validation.Required(), validation.Email(), validation.Unique("users", "email")},
    "team_id": {validation.Required(), validation.Exists("teams", "id")},
}

// On update, exclude the current row. Except accepts any integer, unsigned
// integer, or string kind (including named types such as `type UserID int64`)
// and any fmt.Stringer; the value is converted once, at construction.
rules = validation.Rules{
    "email": {
        validation.Required(),
        validation.Email(),
        validation.Unique("users", "email").Except(user.ID),
    },
}

// Match Except against a column other than "id":
validation.Unique("users", "email").Except(tenantID).IDColumn("tenant_id")
```

Both builder methods return a new value, so the base rule stays reusable. `IDColumn` has no effect without `Except`.


The rule runs a `SELECT COUNT(*)` and returns; the caller's subsequent `INSERT` races any other request that passed the same `SELECT`. Velocity deliberately does not lock or serialize the query: enforcing uniqueness at scale is the database's job.

Add a UNIQUE constraint at the database layer, then route the resulting write error through `dbrules.AsValidationError(err, fieldRules)`, which maps a driver-specific violation (Postgres SQLSTATE 23505, MySQL errno 1062, SQLite extended code 2067) back onto the offending field with the same "has already been taken" message the rule emits.


Raw database errors are never surfaced to the client. A failing `unique` / `exists` query produces a generic `"Unable to validate <field>."` message and logs the underlying error through `slog.Default()` at ERROR level.

## API Reference

### Entry points

Every entry point takes the same `validation.Rules` value. There are two families: the orm-free ones in `validation`, and the DB-backed ones in `validation/dbrules`.

| Function | Package | Signature |
|---|---|---|
| `Check` | `validation` | `Check(r *http.Request, rules Rules, messages ...Messages) (*Result, error)` |
| `CheckW` | `validation` | `CheckW(w http.ResponseWriter, r *http.Request, rules Rules, messages ...Messages) (*Result, error)` |
| `CheckData` | `validation` | `CheckData(data map[string]interface{}, rules Rules, messages ...Messages) (*Result, error)` |
| `CheckWithDB` | `dbrules` | `CheckWithDB(r *http.Request, rules validation.Rules, db orm.Database, messages ...validation.Messages) (*validation.Result, error)` |
| `CheckWithDBW` | `dbrules` | `CheckWithDBW(w http.ResponseWriter, r *http.Request, rules validation.Rules, db orm.Database, messages ...validation.Messages) (*validation.Result, error)` |
| `CheckDataWithDB` | `dbrules` | `CheckDataWithDB(data map[string]interface{}, rules validation.Rules, db orm.Database, messages ...validation.Messages) (*validation.Result, error)` |
| `CheckDataWithDBCtx` | `dbrules` | `CheckDataWithDBCtx(ctx context.Context, data map[string]interface{}, rules validation.Rules, db orm.Database, messages ...validation.Messages) (*validation.Result, error)` |

All seven return `(*Result, error)`. The `error` is a malformed rule set; field failures travel on `*Result`. On the `error` path `*Result` is `nil`, so check `err` first.

#### Check / CheckW

Validate an HTTP request (form values or JSON body, auto-detected from `Content-Type`). Prefer `CheckW` when a `http.ResponseWriter` is in hand: it wraps the body read with `http.MaxBytesReader` so an oversized body can also signal the connection to close.

```go
func handler(c *router.Context) error {
    rules := validation.Rules{
        "email": {validation.Required(), validation.Email()},
        "name":  {validation.Required(), validation.String()},
    }

    result, err := validation.CheckW(c.Response, c.Request, rules)
    if err != nil {
        return err
    }
    if result.HasErrors() {
        return c.JSON(422, map[string]interface{}{
            "errors": result.Messages(),
        })
    }
    // ... bind and continue
    return nil
}
```

#### CheckData

Validate a pre-extracted `map[string]interface{}`:

```go
data := map[string]interface{}{"email": "user@example.com", "age": 25}
result, err := validation.CheckData(data, validation.Rules{
    "email": {validation.Required(), validation.Email()},
    "age":   {validation.Required(), validation.Numeric(), validation.Gte("18")},
})
if err != nil {
    return err // malformed rule set
}
if err := result.Err(); err != nil {
    // err wraps validation.ErrValidationFailed and unwraps to ValidationErrors
    return err
}
```

#### dbrules.CheckWithDBW / CheckDataWithDBCtx

Same as above with `Unique` and `Exists` wired to an `orm.Database`. The request context is threaded into the queries, so a slow `unique` lookup is dropped when the client disconnects.

```go
import (
    "github.com/velocitykode/velocity/orm"
    "github.com/velocitykode/velocity/validation/dbrules"
)

// c.DB() returns the stdlib-only contract.Database; recover the wider
// orm.Database with the supported type assertion.
db, _ := c.DB().(orm.Database)

result, err := dbrules.CheckWithDBW(c.Response, c.Request, rules, db)
```

For non-HTTP code paths (jobs, workers, seeders) use `CheckDataWithDBCtx` and pass the caller's context.

### Handler-side entry points

Two `router.Context` methods wrap the same rule sets and are usually what a handler reaches for.

#### ctx.Validate

```go
func (c *Context) Validate(rules contract.ValidationRuleSet, messages ...contract.ValidationMessages) error
```

`validation.Rules` is an alias for `contract.ValidationRuleSet`, so a rule set passes straight in. On failure `ctx.Validate` flashes the errors and the redacted old input, redirects back when a view engine is installed, and returns `router.ErrValidationAborted` so the handler can return early without the router emitting a second response. DB-backed rules resolve here.

```go
func (h *Handler) Store(ctx *router.Context) error {
    if err := ctx.Validate(validation.Rules{
        "name":  {validation.Required()},
        "email": {validation.Required(), validation.Email(), validation.Unique("users", "email")},
    }); err != nil {
        return err
    }
    // only reaches here if valid
    return nil
}
```

It returns an ordinary error (not a panic) when no validator is wired, since it runs per request.

#### ctx.BindValid

`router.Validatable` is the self-validating request contract:

```go
type Validatable interface {
    Rules() contract.ValidationRuleSet
}
```

`vform.FormRequest` is an alias for it, so one form struct serves both `ctx.BindValid` and `vform.Form[T]`.

```go
type UpdateProfile struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func (r *UpdateProfile) Rules() validation.Rules {
    return validation.Rules{
        "name":  {validation.Required(), validation.Min(2)},
        "email": {validation.Required(), validation.Email(), validation.Unique("users", "email")},
    }
}

func (h *Handler) Update(c *router.Context) error {
    var req UpdateProfile
    if err := c.BindValid(&req); err != nil {
        return err
    }
    // ...
    return nil
}
```

`BindValid` binds JSON, then validates the resulting struct through the data-validator seam the framework wires during boot, so DB-backed rules resolve here too. Unlike `ctx.Validate` it neither flashes nor redirects: it just returns the validation error. It returns an error when no validator is wired.

### Result methods

| Method | Returns |
|---|---|
| `HasErrors()` | `bool`: true when at least one field failed |
| `First(field)` | first message for `field`, or `""` |
| `All()` | `map[string]string`, first message per field (Inertia-friendly shape) |
| `Messages()` | `map[string][]string`, all messages per field |
| `Err()` | `error` wrapping `ErrValidationFailed`; `nil` on success. Satisfies `errors.As(&ValidationErrors{})` |
| `Old()` | `map[string]interface{}` of original input with sensitive fields stripped (case-insensitive substring match on `password`, `passwd`, `passcode`, `secret`, `token`, `pin`, `cvv`, `cvc`, `card`, `ssn`, `otp`, `credential`, `credentials`, `api_key`, `apikey`, `private_key`, `privatekey`), suitable for flashing |

### ValidationErrors

When you unwrap `Result.Err()` with `errors.As(&validation.ValidationErrors{})`, you get the lower-level shape:

```go
var ve validation.ValidationErrors
if errors.As(result.Err(), &ve) {
    ve.Count()                      // total error count
    ve.HasError("email")            // bool
    ve.First("email")               // first message
    ve.All()                        // map[string][]string
    ve.HasRule("email", "required") // bool, prefer over substring match
    ve.RulesFor("email")            // []string of rule names that failed
}
```

`errors.Is(result.Err(), validation.ErrValidationFailed)` works for the generic "validation failed" branch, and `errors.Is(err, validation.ErrInvalidRule)` for the malformed-rule-set branch on the `error` return.

### Validator

`validation.NewValidator()` returns a long-lived `Validator` (the same type the framework installs as `Services.Validator`):

```go
type Validator interface {
    Validate(data interface{}, rules ValidationRuleSet) (*ValidatedData, error)
    ValidateValue(value interface{}, rules ...ValidationRule) error
    SetMessages(messages ValidationMessages)
}
```

`Validate` accepts a `map[string]interface{}` or a `map[string]string` and returns `*ValidatedData` alongside the error. `ValidateValue` validates a single unnamed value against a rule list; messages and message-key lookups for it use the field name `"value"`.

```go
v := validation.NewValidator()

if err := v.ValidateValue("not-an-email", validation.Required(), validation.Email()); err != nil {
    // err is a validation.ValidationErrors describing the "value" field,
    // or wraps ErrInvalidRule when the rule list is malformed.
}
```

## Custom Validation Rules

`validation.Custom(name, handler)` builds a rule that carries its own handler, so it runs anywhere the rule set reaches, including the fresh per-request validator the `Check` helpers build. There is no registration step and no global rule registry.

```go
import (
    "fmt"
    "unicode"

    "github.com/velocitykode/velocity/validation"
)

// The returned value IS the rule's identity: declare it once at package level
// and reuse it wherever the rule applies. Two distinct Custom values sharing a
// name inside one rule set are rejected during normalization, because nothing
// could decide which handler wins.
var StrongPassword = validation.Custom("strong_password", func(
    field string,
    value interface{},
    params []string,
    data map[string]interface{},
) error {
    pw, ok := value.(string)
    if !ok {
        return fmt.Errorf("The %s field must be a string.", field)
    }

    var hasUpper, hasLower, hasNumber, hasSpecial bool
    for _, r := range pw {
        switch {
        case unicode.IsUpper(r):
            hasUpper = true
        case unicode.IsLower(r):
            hasLower = true
        case unicode.IsNumber(r):
            hasNumber = true
        case unicode.IsPunct(r) || unicode.IsSymbol(r):
            hasSpecial = true
        }
    }
    if !hasUpper || !hasLower || !hasNumber || !hasSpecial {
        return fmt.Errorf("The %s must contain uppercase, lowercase, number, and special character.", field)
    }
    return nil
})

// Usage: identical to any built-in.
rules := validation.Rules{
    "password": {validation.Required(), validation.Min(8), StrongPassword},
}
```

The handler signature is `validation.RuleHandler`:

```go
type RuleHandler func(field string, value interface{}, params []string, data map[string]interface{}) error
```

`params` is a copy handed to each invocation, so a handler that mutates it cannot corrupt the shared rule set. A `Custom` name that shadows a built-in (including `unique` and `exists`) is rejected during normalization, as is a nil handler.

For most adopters the built-in [`Password()`](#password) rule is enough; reach for a custom rule only when the policy is genuinely app-specific.

## Custom Error Messages

`validation.Messages` is keyed by a `{Field, Rule}` pair. `Rule` is the rule name from the [catalog](#available-rules) table; a key with an empty `Rule` is never consulted, because an override always names the rule it replaces.

```go
messages := validation.Messages{
    {Field: "email", Rule: "required"}:    "Email is required",
    {Field: "email", Rule: "email"}:       "Invalid email format",
    {Field: "password", Rule: "required"}: "Password is required",
    {Field: "password", Rule: "min"}:      "Password must be at least 8 characters",
}

result, err := validation.CheckW(c.Response, c.Request, rules, messages)
```

Every `Check*` helper, `ctx.Validate`, and `Validator.SetMessages` accept the same map. From a [form-request](/docs/core/form-requests), implement `vform.WithMessages` and the messages are passed through automatically:

```go
func (r *SignupRequest) ValidationMessages() validation.Messages {
    return validation.Messages{
        {Field: "email", Rule: "required"}: "We need your email.",
    }
}
```

Velocity ships English-only messages; there is no locale setting. `SetMessages` is the override path.

## Best Practices

### 1. Validate at the edge

Validate as soon as input enters the handler, before any business logic:

```go
func CreateUser(c *router.Context) error {
    result, err := validation.CheckW(c.Response, c.Request, validation.Rules{
        "email": {validation.Required(), validation.Email()},
        "name":  {validation.Required(), validation.String()},
    })
    if err != nil {
        return err
    }
    if result.HasErrors() {
        return c.JSON(422, map[string]interface{}{
            "errors": result.Messages(),
        })
    }
    // ... bind + business logic
    return nil
}
```

### 2. Prefer `vform.Form[T]` for HTTP

[Form requests](/docs/core/form-requests) bundle binding, validation, flashing, and redirect-back into one call. Use `validation.Check*` or `dbrules.Check*` directly only when you need a custom render path or you're validating data that isn't an HTTP request.

### 3. Separate the two error paths

The `error` return means the rule set is broken (a handler bug, a 500). `result.HasErrors()` means the user's input is bad (a 422 or a redirect back). Never render the first as a field message.

```go
result, err := validation.CheckW(c.Response, c.Request, rules)
if err != nil {
    return err // 500: ErrInvalidRule, not user-facing
}
if result.HasErrors() {
    return c.JSON(422, map[string]interface{}{"errors": result.Messages()})
}
```

### 4. Provide clear error messages

```go
messages := validation.Messages{
    {Field: "email", Rule: "email"}:     "Please enter a valid email address",
    {Field: "password", Rule: "min"}:    "Your password needs to be at least 8 characters",
    {Field: "terms", Rule: "accepted"}:  "You must accept the terms of service",
}
```

### 5. Order rules from general to specific

```go
rules := validation.Rules{
    // Good: required first, then type, then constraints.
    "age": {validation.Required(), validation.Numeric(), validation.Gte("18"), validation.Lte("120")},
}
```

### 6. Reuse rule sets

Rule values are immutable, so a package-level rule list is safe to share across handlers and goroutines:

```go
var (
    EmailRules    = []validation.Rule{validation.Required(), validation.Email()}
    PasswordRules = []validation.Rule{validation.Required(), validation.Min(8), StrongPassword}
    PhoneRules    = []validation.Rule{validation.Required(), validation.Numeric(), validation.Size(10)}
)

rules := validation.Rules{
    "email":    EmailRules,
    "password": PasswordRules,
    "phone":    PhoneRules,
}
```

## Complete Example

A full user-registration endpoint using `dbrules.CheckWithDBW`, so `Unique` resolves against the database:

```go
package handlers

import (
    "github.com/velocitykode/velocity/orm"
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/validation"
    "github.com/velocitykode/velocity/validation/dbrules"
)

type UserHandler struct{}

func (uc *UserHandler) Register(c *router.Context) error {
    rules := validation.Rules{
        "name":                  {validation.Required(), validation.String(), validation.Min(2), validation.Max(100)},
        "email":                 {validation.Required(), validation.Email(), validation.Unique("users", "email")},
        "password":              {validation.Required(), validation.Min(8), validation.Confirmed()},
        "password_confirmation": {validation.Required()},
        "age":                   {validation.Required(), validation.Numeric(), validation.Gte("18")},
        "terms":                 {validation.Required(), validation.Accepted()},
        "newsletter":            {validation.Nullable(), validation.Boolean()},
    }

    messages := validation.Messages{
        {Field: "name", Rule: "required"}:      "Please tell us your name",
        {Field: "name", Rule: "min"}:           "Name must be at least 2 characters",
        {Field: "email", Rule: "required"}:     "We need your email address",
        {Field: "email", Rule: "email"}:        "Please enter a valid email address",
        {Field: "email", Rule: "unique"}:       "That email is already registered",
        {Field: "password", Rule: "required"}:  "Password is required",
        {Field: "password", Rule: "min"}:       "Password must be at least 8 characters",
        {Field: "password", Rule: "confirmed"}: "Passwords do not match",
        {Field: "age", Rule: "required"}:       "Please provide your age",
        {Field: "age", Rule: "gte"}:            "You must be at least 18 years old",
        {Field: "terms", Rule: "accepted"}:     "You must accept the terms of service",
    }

    db, _ := c.DB().(orm.Database)

    result, err := dbrules.CheckWithDBW(c.Response, c.Request, rules, db, messages)
    if err != nil {
        // Malformed rule set: a bug here, not bad input.
        return err
    }
    if result.HasErrors() {
        return c.JSON(422, map[string]interface{}{
            "message": "Validation failed",
            "errors":  result.Messages(),
        })
    }

    var input struct {
        Name, Email, Password string
        Age                   int
        Newsletter            bool
    }
    if err := c.BindAuto(&input); err != nil {
        return err
    }

    user := &User{
        Name:            input.Name,
        Email:           input.Email,
        Password:        hashPassword(input.Password),
        Age:             input.Age,
        NewsletterOptIn: input.Newsletter,
    }
    if err := user.Save(); err != nil {
        return c.JSON(500, map[string]string{"error": "Failed to create user"})
    }

    return c.JSON(201, map[string]interface{}{
        "message": "Registration successful",
        "user":    user,
    })
}
```

## Testing

```go
func TestValidation(t *testing.T) {
    data := map[string]interface{}{
        "email":    "user@example.com",
        "password": "secret12",
        "age":      25,
    }

    rules := validation.Rules{
        "email":    {validation.Required(), validation.Email()},
        "password": {validation.Required(), validation.Min(8)},
        "age":      {validation.Required(), validation.Numeric(), validation.Gte("18")},
    }

    result, err := validation.CheckData(data, rules)
    require.NoError(t, err)
    assert.False(t, result.HasErrors())
}

func TestValidationErrors(t *testing.T) {
    data := map[string]interface{}{
        "email": "invalid-email",
        "age":   "not-a-number",
    }

    rules := validation.Rules{
        "email": {validation.Required(), validation.Email()},
        "age":   {validation.Required(), validation.Numeric()},
    }

    result, err := validation.CheckData(data, rules)
    require.NoError(t, err)
    assert.True(t, result.HasErrors())

    var ve validation.ValidationErrors
    require.True(t, errors.As(result.Err(), &ve))
    assert.True(t, ve.HasRule("email", "email"))
    assert.True(t, ve.HasRule("age", "numeric"))
    assert.Equal(t, 2, ve.Count())
}
```

The `validation/testing` package ships three helpers for rule-level tests:

```go
import vtesting "github.com/velocitykode/velocity/validation/testing"

func TestEmailRule(t *testing.T) {
    // Applies the rules to every key in the input map.
    // expectedErr=true means the input is expected to fail.
    vtesting.RuleAssertion(t, map[string]interface{}{"email": "bad"}, true,
        validation.Required(), validation.Email())

    v := vtesting.NewTestValidator()
    _, err := v.Validate(map[string]interface{}{"email": ""}, validation.Rules{
        "email": {validation.Required(), validation.Email()},
    })

    // Asserts the field failed the NAMED rule, not just "something failed".
    vtesting.AssertErrorRule(t, err, "email", "required")

    // Use only where the exact wording is load-bearing.
    vtesting.AssertErrorMessage(t, err, "email", "is required")
}
```

Prefer `AssertErrorRule` (or `ValidationErrors.HasRule`) over substring-matching messages: a test asserting `HasError("email")` still passes when the wrong rule fired.

## Related

- [Form Requests](/docs/core/form-requests/) - HTTP-handler entry point that wraps validation with binding, flashing, and redirect-back
- [Middleware](/docs/core/middleware/) - where global input shaping (CSRF, rate limit, body parsing) runs before validation


================================================================================
# HTTP Router

Source: https://vel.build/docs/core/http-router/
Section: Core Framework
Summary: Low-level router reference - Context API, route definition, parameters, JSON binding, and named routes.


This page documents the underlying `router` package - the
`*router.Context` API, route definition primitives, and helpers for
working with requests and responses.

For app-level routing (web/API stacks, declarative `v.Routes(...)`),
see [Routing](/docs/core/routing).

Import path: `github.com/velocitykode/velocity/router`

## Quick start

Most apps register routes through `v.Routes(...)`. To use the router
directly - typically in tests or when embedding Velocity into a bare
`net/http` server:

```go
package main

import (
    "net/http"

    "github.com/velocitykode/velocity/router"
)

func main() {
    r := router.New()

    r.Get("/users/{id}", func(c *router.Context) error {
        return c.JSON(http.StatusOK, map[string]any{
            "id": c.Param("id"),
        })
    })

    http.ListenAndServe(":4000", r)
}
```

`router.New()` returns a `*router.VelocityRouterV2` that satisfies
`http.Handler`.

## Defining routes

### HTTP methods

```go
r.Get("/users", listUsers)
r.Post("/users", createUser)
r.Put("/users/{id}", replaceUser)
r.Patch("/users/{id}", updateUser)
r.Delete("/users/{id}", deleteUser)
r.Options("/users", listOptions)
r.Head("/users/{id}", headUser)

// Match every method:
r.Any("/health", healthCheck)

// Match a custom set:
r.Match([]string{http.MethodGet, http.MethodPost}, "/webhook", handleWebhook)
```

Each verb returns a `RouteConfig` for chaining `.Name(...)` and
`.Use(...)`.

### Route parameters

`{name}` segments capture path values:

```go
r.Get("/users/{id}", func(c *router.Context) error {
    id := c.Param("id")
    return c.String(http.StatusOK, "user "+id)
})
```

Typed accessors return `(value, error)`:

```go
id, err := c.ParamInt("id")
big, err := c.ParamInt64("id")
```

### Groups and middleware

Sub-groups inherit middleware from their parent and add their own:

```go
api := r.Group("/api/v1")
api.Use(authMiddleware)

api.Get("/me", showProfile)
api.Get("/posts", listPosts)
```

Or pass a closure to scope the group:

```go
r.Group("/admin", func(admin router.Router) {
    admin.Use(adminAuth)
    admin.Get("/dashboard", dashboard)
    admin.Post("/users", createUser)
})
```

### Static files

Serve a directory of static assets:

```go
r.Static("public")  // serves ./public at /
```

## The Context

`*router.Context` wraps the request, response, and helpers. Every
handler has signature `func(*router.Context) error`.

### Reading parameters

```go
id := c.Param("id")              // string
n, err := c.ParamInt("page")     // int
big, err := c.ParamInt64("id")   // int64
```

### Query strings

```go
q       := c.Query("q")                       // string
sort    := c.QueryDefault("sort", "newest")    // string with default
page    := c.QueryInt("page", 1)              // int with default
limit   := c.QueryInt64("limit", 25)          // int64 with default
amount  := c.QueryFloat64("amount", 0.0)      // float64 with default
verbose := c.QueryBool("verbose")             // accepts 1/0, true/false, t/f, etc.
```

### Headers

```go
ua    := c.Header("User-Agent")               // read
size  := c.HeaderInt64("Content-Length", 0)   // read as int64

c.SetHeader("X-Request-ID", requestID)        // write (replaces)
c.AddHeader("Vary", "Accept")                 // append (list-valued)
```

`SetHeader` and `AddHeader` reject names or values containing CR/LF to
prevent header injection.

### Cookies

```go
sess, err := c.Cookie("session_id")

c.SetCookie(&http.Cookie{
    Name:     "session_id",
    Value:    id,
    Path:     "/",
    HttpOnly: true,
    Secure:   true,
})
```

### JSON binding

`c.Bind` decodes the request body as JSON:

```go
type CreateUser struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

r.Post("/users", func(c *router.Context) error {
    var req CreateUser
    if err := c.Bind(&req); err != nil {
        return c.BadRequest("invalid body")
    }
    // ...
    return c.JSON(http.StatusCreated, req)
})
```

The body is wrapped with a 10MB limit by default
(`router.DefaultMaxBodySize`). Routes that must accept larger payloads
should install the `router.BodyLimit(N)` middleware for their chain;
when present it sets the cap for `Bind`, `BindForm`, `BindXML`,
`FormValue`, and `FormFile` instead of the default.

### Form data

`c.FormValue` reads a single URL-encoded or multipart value (capping the
body at `DefaultMaxBodySize` unless `BodyLimit` is installed), and
`c.FormFile` returns the first uploaded file for a key:

```go
name := c.FormValue("name")

fh, err := c.FormFile("avatar")
if err != nil {
    return c.BadRequest("invalid upload")
}
```

To map an entire form into a struct, use `c.BindForm` (`form` tags),
`c.BindQuery` (`query` tags), `c.BindXML`, or `c.BindAuto` (which picks a
binder from the `Content-Type`, defaulting to JSON):

```go
type Filter struct {
    Sort string `form:"sort"`
    Page int    `form:"page"`
}

var f Filter
if err := c.BindForm(&f); err != nil {
    return c.BadRequest("invalid form")
}
```

`c.BindValid` binds JSON and then runs the struct's own
`ValidationRules()` if it implements `Validatable`.

### Responses

```go
c.JSON(http.StatusOK, payload)
c.XML(http.StatusOK, payload)         // application/xml
c.String(http.StatusOK, "hello")
c.HTML(http.StatusOK, "<h1>Hi</h1>")  // raw - sanitize user input
c.Resource(userResource)              // calls ToResource() and serializes
c.NoContent()                         // 204
c.Status(http.StatusAccepted)         // header only

// For a streamed body or full control, write to the writer directly:
c.Response.Header().Set("Content-Type", "application/octet-stream")
c.Response.Write(data)
```

`c.JSON` also sets `X-Content-Type-Options: nosniff`.

### Serving files

`File` and `Download` serve a path resolved relative to the router's
configured `FileRoot` (set via `SetFileRoot`, defaulting to the process
working directory). Containment is kernel-enforced via `*os.Root`, so a
`..` segment or a symlink escaping the root is rejected:

```go
c.File("reports/q3.pdf")                 // inline; ServeContent
c.Download("reports/q3.pdf", "Q3.pdf")   // Content-Disposition: attachment
c.Attachment("reports/q3.pdf", "Q3.pdf") // alias for Download
```

Both default to `Cache-Control: private, no-store` (a caller-set header
is preserved).

### Streaming and Server-Sent Events

`c.SSE` writes one `event:`/`data:` frame (JSON-encoded) and flushes,
setting the streaming headers and clearing the write deadline on the
first call:

```go
r.Get("/stream", func(c *router.Context) error {
    for ev := range updates {
        if err := c.SSE("update", ev); err != nil {
            return err
        }
    }
    return nil
})
```

For hand-rolled streams (NDJSON, custom frames), call `c.PrepareStream()`
once and then write to `c.Response` directly.

### Redirects

```go
c.Redirect(http.StatusSeeOther, "/dashboard")
```

`Redirect` sanitizes the URL: relative paths are always allowed, and
absolute URLs are allowed only when their host is in the router's
`RedirectAllowedHosts` allowlist. Everything else (cross-host URLs,
protocol-relative `//evil`, `javascript:`/`data:` schemes, and
backslash/Unicode-slash lookalikes) is rewritten to `"/"` to prevent
open redirects. The same logic is exported as `router.SanitizeRedirect`.

For post-login flows, `c.RedirectToIntended(fallback)` issues a 303 to
the safe "intended" destination stashed by the auth middleware (or the
sanitized fallback). `c.Intended(fallback)` returns that target without
redirecting. Never feed a raw `?redirect=` query value to `c.Redirect`
directly - route it through these helpers so the open-redirect sanitizer
runs.

### Errors

Convenience constructors return JSON-shaped errors with the standard
status text or your message:

```go
return c.NotFound()                      // {"code":404,"message":"Not Found"}
return c.BadRequest("missing field")     // {"code":400,"message":"missing field"}
return c.Unauthorized("expired token")
return c.Forbidden()
return c.Error(http.StatusConflict, "duplicate email")
```

For richer error handling - typed exceptions, custom renderers, dev
pages - see [Exceptions](/docs/core/exceptions).

### Request inspection

```go
method := c.Method()      // GET, POST, ...
path   := c.Path()        // /users/42
ip     := c.IP()          // honors X-Forwarded-For from trusted proxies

if c.IsAjax() { /* X-Requested-With: XMLHttpRequest */ }
if c.WantsJSON() { /* Accept == application/json, or X-Inertia set */ }
```

### Per-request storage

Pass values from middleware to handlers using `Set`/`Get`:

```go
func auth(next router.HandlerFunc) router.HandlerFunc {
    return func(c *router.Context) error {
        user, err := authenticate(c.Request)
        if err != nil {
            return c.Unauthorized()
        }
        c.Set("user", user)
        return next(c)
    }
}

r.Get("/me", func(c *router.Context) error {
    user := c.Get("user").(*models.User)
    return c.JSON(http.StatusOK, user)
})
```

`GetString(key)` is a typed shortcut. For complex types, type-assert
the result of `Get`.

### Service accessors

When the router is attached to a Velocity app (the usual case), the
context exposes the service container:

```go
c.DB()           // contract.Database
c.Cache()        // contract.CacheManager
c.Log()          // contract.Logger
c.Queue()        // contract.QueueDriver
c.Storage()      // contract.StorageManager
c.Mail()         // contract.Mailer
c.Notification() // contract.Notifier
c.Events()       // contract.Dispatcher
c.Crypto()       // contract.Encryptor
c.Validator()    // contract.Validator
c.Exceptions()   // contract.ExceptionHandler
c.Scheduler()    // scheduler.TaskScheduler
c.Auth()         // contract.AuthManager
c.CSRF()         // contract.CSRFProtector
c.View()         // contract.ViewEngine
c.Services()     // *app.Services (the whole container)
```

Each accessor returns a narrow stdlib-only `contract` interface so the
`router` package carries no heavy driver dependencies. They **panic**
when the corresponding service is not configured (e.g. a raw
`router.New()` with no Velocity app wired in). To probe the container
without panicking, use `c.ServicesIfSet()`, which returns `nil` when
services have not been wired.

## Named routes and URL generation

```go
r.Get("/posts/{id}", showPost).Name("posts.show")
```

After all routes are registered, generate URLs from the name:

```go
url, err := r.RouteURL("posts.show", map[string]string{"id": "42"})
// url == "/posts/42"
```

`RouteURL` returns `*RouteNotFoundError` if the name is unknown or if
called before the route table is committed. Velocity commits the table
on first request; call `r.Freeze()` to commit eagerly (e.g. in tests, or
to move the commit cost off the first request) before calling
`RouteURL`.

## Tracing

The router does not magically populate `TraceID` / `RequestID` fields
on the context. Use the `trace` package to read trace state from the
request context:

```go
import "github.com/velocitykode/velocity/trace"

r.Get("/api/log", func(c *router.Context) error {
    traceID, spanID, parent := trace.GetTraceContext(c.Request.Context())

    c.Log().Info("processing", "trace_id", traceID, "span_id", spanID, "parent", parent)
    return c.NoContent()
})
```

Velocity's middleware injects fresh trace IDs per request - see
[Tracing](/docs/advanced/trace) for end-to-end propagation.

## Embedding into net/http

The router is an `http.Handler` directly:

```go
http.ListenAndServe(":4000", r)
```

To use it inside a larger mux, mount it under a path prefix:

```go
mux := http.NewServeMux()
mux.Handle("/api/", http.StripPrefix("/api", r))
http.ListenAndServe(":4000", mux)
```

## Testing routes

Use `httptest`:

```go
func TestShowPost(t *testing.T) {
    r := router.New()
    r.Get("/posts/{id}", func(c *router.Context) error {
        return c.JSON(http.StatusOK, map[string]string{"id": c.Param("id")})
    })

    req := httptest.NewRequest(http.MethodGet, "/posts/42", nil)
    rec := httptest.NewRecorder()
    r.ServeHTTP(rec, req)

    if rec.Code != http.StatusOK {
        t.Fatalf("status = %d, want 200", rec.Code)
    }

    if !strings.Contains(rec.Body.String(), `"id":"42"`) {
        t.Fatalf("body = %q, want id=42", rec.Body.String())
    }
}
```

For full app-level tests that exercise middleware, providers, and
services, use the `github.com/velocitykode/velocity/testing/http`
package - `NewTestClient(t, r)` returns a `*TestClient` whose requests
yield assertable `*TestResponse` values.

## Adapting standard handlers

Wrap a `router.HandlerFunc` to use it with stdlib mux:

```go
http.Handle("/health", router.Wrap(myHandler))
```

If the inner handler returns a `*HTTPError`, the wrapper responds with
its code - echoing the message for 4xx, but a generic body for 5xx so
server detail never leaks. Any other error becomes a generic 500. For
richer error handling, attach the route to a router so the exception
handler runs.


================================================================================
# Resources

Source: https://vel.build/docs/core/resource/
Section: Core Framework
Summary: Transform domain models into API responses with collections, pagination, and conditional fields.


The `resource` package is a transformation layer that converts domain
models into serializable maps ready for JSON responses. It keeps the
public shape of your API decoupled from internal struct layout.

Import path: `github.com/velocitykode/velocity/resource`

## The Resource interface

Every resource type implements a single method:

```go
type Resource interface {
    ToResource() map[string]any
}
```

Define a resource for each model that leaves your application:

```go
package resources

import "myapp/internal/models"

type UserResource struct {
    models.User
}

func (r UserResource) ToResource() map[string]any {
    return map[string]any{
        "id":    r.ID,
        "name":  r.Name,
        "email": r.Email,
        // Password deliberately excluded - never leaves the server
    }
}
```

Send it from a handler with `ctx.Resource`:

```go
func Show(ctx *router.Context) error {
    user, err := models.FindUser(ctx.Param("id"))
    if err != nil {
        return err
    }
    return ctx.Resource(resources.UserResource{User: user})
}
```

`ctx.Resource` calls `ToResource()` and writes it as a 200 JSON response.

## Collections

`NewCollection` transforms a typed slice into `[]map[string]any`:

```go
users := []models.User{ /* ... */ }

resources := resource.NewCollection([]resources.UserResource{
    {User: users[0]},
    {User: users[1]},
})

return ctx.JSON(http.StatusOK, resources)
```

The generic constraint `[T Resource]` ensures at compile time that every
element has a `ToResource()` method.

## Paginated collections

`NewPaginatedCollection` wraps items in a `{data, meta}` envelope:

```go
return ctx.JSON(http.StatusOK, resource.NewPaginatedCollection(
    []resources.UserResource{{User: u1}, {User: u2}},
    resource.PaginationMeta{
        Total:       42,
        PerPage:     15,
        CurrentPage: 1,
    },
))
```

`LastPage` is computed automatically (ceiling division) - you only
supply `Total`, `PerPage`, and `CurrentPage`. Negative `Total` or
`PerPage` values are clamped to `0`.

Response shape:

```json
{
  "data": [
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"}
  ],
  "meta": {
    "total": 42,
    "per_page": 15,
    "current_page": 1,
    "last_page": 3
  }
}
```

## Building meta from an ORM paginator

ORM paginators satisfy the `Paginator` interface:

```go
type Paginator interface {
    Total() int
    PerPage() int
    CurrentPage() int
    Items() any
}
```

Use `FromPaginator` to convert a paginator into `PaginationMeta`:

```go
page, err := models.Users().Paginate(ctx, 1, 15)
if err != nil {
    return err
}

items := page.Data() // typed []models.User
userResources := make([]resources.UserResource, 0, len(items))
for _, u := range items {
    userResources = append(userResources, resources.UserResource{User: u})
}

return ctx.JSON(http.StatusOK, resource.NewPaginatedCollection(
    userResources,
    resource.FromPaginator(page),
))
```

`Paginate(ctx, page, perPage)` takes the 1-based page number and the page
size. `Data()` returns the typed `[]T` slice directly, while `Items()`
(used by `FromPaginator`) returns the same slice as `any`.

## Conditional fields

Four helpers let you include fields only when a condition holds.

### When - static condition

```go
func (r UserResource) ToResource() map[string]any {
    m := map[string]any{
        "id":   r.ID,
        "name": r.Name,
    }

    if k, v, ok := resource.When(r.ShowEmail, "email", r.Email); ok {
        m[k] = v
    }
    return m
}
```

### WhenNotNil - skip nil values (including typed nils)

```go
if k, v, ok := resource.WhenNotNil("avatar_url", r.AvatarURL); ok {
    m[k] = v
}
```

Uses reflection so that `(*string)(nil)` is correctly detected as nil.
A plain `v == nil` check misses typed nils wrapped in an interface.

### WhenFunc - lazy evaluation

When computing the value is expensive, defer it until the condition is
actually true:

```go
if k, v, ok := resource.WhenFunc(r.IncludePosts, "posts", func() any {
    return loadPostsForUser(r.ID)  // only called when IncludePosts is true
}); ok {
    m[k] = v
}
```

### Merge - compose conditional blocks

For longer resources, group conditions into closures and apply them in
sequence:

```go
func (r UserResource) ToResource() map[string]any {
    m := map[string]any{"id": r.ID, "name": r.Name}

    resource.Merge(m,
        func(m map[string]any) {
            if r.ShowEmail {
                m["email"] = r.Email
            }
        },
        func(m map[string]any) {
            if r.CreatedAt != nil {
                m["created_at"] = r.CreatedAt.Format(time.RFC3339)
            }
        },
    )
    return m
}
```

## Design notes

- **Leaf package.** `resource` imports nothing from velocity - only the
  standard library (`reflect`). It can be consumed by tests and tools
  without dragging in the rest of the framework.
- **Decoupling pagination.** The `Paginator` interface lets the `orm`
  package produce meta without `resource` importing `orm`.
- **No middleware, no side effects.** Pure transformation - deterministic
  and easy to test.


================================================================================
# CSRF Protection

Source: https://vel.build/docs/core/csrf/
Section: Core Framework
Summary: Protect your Velocity application against cross-site request forgery attacks with built-in CSRF middleware.


Velocity provides comprehensive CSRF (Cross-Site Request Forgery) protection to secure your application against unauthorized form submissions and state-changing requests.

## Quick Start




`velocity.New` builds the CSRF instance for you from `Config.CSRF`
(seeded from `csrf.DefaultConfig()` and overridable via `CSRF_*`
environment variables) and exposes it on the app as `v.CSRF`
(type `contract.CSRFProtector`, concrete `*csrf.CSRF`). It also installs
a `SessionIDResolver` that decrypts the session cookie - the token store
is keyed by the plaintext session ID, never by the raw cookie value.

To build an instance by hand (custom middleware stacks, tests), use the
error-returning constructor and supply a `SessionIDResolver` - it is
**required**:

```go
import (
    "net/http"

    "github.com/velocitykode/velocity/csrf"
    "github.com/velocitykode/velocity/csrf/stores"
)

config := csrf.DefaultConfig()
config.Store = stores.NewSessionStore(config.TokenLifetime)
config.SessionIDResolver = func(r *http.Request) (string, error) {
    // Return the plaintext session ID, or csrf.ErrNoSession when the
    // request carries no session. Keying tokens by an unauthenticated
    // cookie value is rejected at construction time.
    if c, err := r.Cookie("session_id"); err == nil && c.Value != "" {
        return c.Value, nil
    }
    return "", csrf.ErrNoSession
}

protection, err := csrf.NewE(config)
if err != nil {
    // ErrInsecureCSRFConfig: nil resolver or unsupported Mode.
    panic(err)
}
```

`csrf.New(config)` is the panic-on-error variant of `NewE`.



```go
// Apply CSRF to the web middleware stack
v.Middleware(func(m *velocity.MiddlewareStack) {
    csrfInstance := v.CSRF.(*csrf.CSRF)

    m.Web(
        csrfInstance.RouterMiddleware(), // validates token on unsafe methods
    )
})
```

`RouterMiddleware()` returns a `router.MiddlewareFunc` that resolves the
session ID, looks up the token, and validates the request. The session
middleware is installed globally by `velocity.New`, so it already runs
ahead of the web stack.



```html
<!-- Meta tag: render the token your shared-props function published -->
<head>
    <meta name="csrf-token" content="{{ .csrfToken }}">
</head>

<!-- Form field: include the token on unsafe requests -->
<form method="POST" action="/submit">
    <input type="hidden" name="_token" value="{{ .csrfToken }}">
    <input type="text" name="email" />
    <button type="submit">Submit</button>
</form>

<script>
    // Read the token for AJAX
    const token = document.querySelector('meta[name="csrf-token"]').content;

    fetch('/api/data', {
        method: 'POST',
        headers: {
            'X-CSRF-Token': token,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(data)
    });
</script>
```

The token is obtained via `csrf.TokenForRequest(r)`, which returns the
per-response **masked** form (memoized for the request so the meta tag,
form field, and `XSRF-TOKEN` cookie all carry byte-identical values).
Plug it into the view engine's shared props under the key your template
reads:

```go
engine.SetSharePropsFunc(func(r *http.Request) (view.Props, error) {
    props := view.Props{}
    if token, err := csrf.TokenForRequest(r); err == nil && token != "" {
        props["csrfToken"] = token
    }
    return props, nil
})
```

`TokenForRequest` requires the CSRF middleware to have run on the request
(it attaches the request-scoped token state); it returns
`csrf.ErrNoTokenState` otherwise, which callers treat as "no token to
embed".



```go
// SPAs read the token from a refresh endpoint
v.Routes(func(r *velocity.Routing) {
    csrfInstance := v.CSRF.(*csrf.CSRF)

    r.Web(func(web router.Router) {
        web.Get("/csrf/token", func(c *router.Context) error {
            csrfInstance.RefreshHandler()(c.Response, c.Request)
            return nil
        })
    })
})
```

Exclude the refresh endpoint from CSRF validation itself:

```go
config.ExcludePaths = []string{"/csrf/token"}
```




## Configuration

### Default Configuration

```go
config := csrf.DefaultConfig()
// Returns:
// {
//     TokenLifetime:     24 * time.Hour,
//     HeaderName:        "X-CSRF-Token",
//     FormField:         "_token",
//     CookieName:        "csrf_token",
//     SessionCookieName: "session_id",
//     MaxFormBodyBytes:  1 << 20, // csrf.DefaultMaxFormBodyBytes (1 MiB)
//     Mode:              csrf.ModeSession,
//     SameSite:          http.SameSiteLaxMode,
//     Secure:            true,
//     HttpOnly:          true,
//     SingleUse:         false,
//     WriteXSRFCookie:   true,
//     XSRFCookieName:    "XSRF-TOKEN",
//     ErrorMessage:      "CSRF token validation failed. Please refresh and try again.",
// }
```

### Custom Configuration

```go
config := &csrf.Config{
    // Token settings
    TokenLifetime:     12 * time.Hour,      // Token expiration
    HeaderName:        "X-CSRF-Token",       // Header name for token
    FormField:         "_token",             // Form field name
    CookieName:        "csrf_token",         // Cookie name
    SessionCookieName: "velocity_session",   // Session cookie name
    MaxFormBodyBytes:  1 << 20,              // urlencoded body cap (default 1 MiB)

    // Binding mode (only ModeSession is implemented today)
    Mode: csrf.ModeSession,

    // Security settings
    SameSite:  http.SameSiteStrictMode,     // CSRF protection level
    Secure:    true,                         // HTTPS only
    HttpOnly:  true,                         // No JavaScript access (matches net/http casing)
    SingleUse: false,                        // Reusable tokens

    // axios/Angular convenience cookie (non-HttpOnly XSRF-TOKEN)
    WriteXSRFCookie: true,
    XSRFCookieName:  "XSRF-TOKEN",

    // Storage
    Store: stores.NewSessionStore(),         // Token storage

    // Required: resolve the plaintext session ID tokens are keyed by.
    SessionIDResolver: resolveSession,

    // Exception handling
    ExcludePaths: []string{                  // Paths to exclude
        "/api/webhooks/*",
        "/health",
    },
    ExcludeFunc: func(r *http.Request) bool {
        // Custom exclusion logic
        return strings.HasPrefix(r.URL.Path, "/public/")
    },

    // Error handling
    ErrorMessage: "Invalid CSRF token",
    ErrorHandler: customErrorHandler,
}
```


`SessionIDResolver` is required: `csrf.NewE` (and `csrf.New`) reject a nil
resolver with `ErrInsecureCSRFConfig`. It must return the plaintext
session ID, or `csrf.ErrNoSession` when the request carries no session.
`velocity.New` installs an encrypted-session resolver automatically when
the app encryptor, session cookie name, and `SessionCookieName` all align;
otherwise it installs a strict-reject resolver so the deployment fails
closed (419 on every unsafe request) instead of silently bypassing CSRF.


### Validation

`Config.Validate(env)` rejects insecure configurations at boot.
`velocity.New` calls it for you. The rules:

- `Mode` must be `ModeSession` (`ModeDoubleSubmit` is reserved).
- `HttpOnly` must be `true` unless `AllowJSAccess` is set.
- `Secure` must be `true` outside a dev/test profile (`APP_ENV` one of
  `development`, `dev`, `test`, `testing`, `local`).
- `SameSite` must be explicit (not the zero/default value).
- `SameSite=None` requires `Secure=true`.

### Environment variables

`velocity.New` overrides the package defaults from these variables:

| Variable | Field |
|----------|-------|
| `CSRF_TOKEN_LIFETIME` | `TokenLifetime` |
| `CSRF_HEADER` | `HeaderName` |
| `CSRF_FORM_FIELD` | `FormField` |
| `CSRF_COOKIE_NAME` | `CookieName` |
| `CSRF_SESSION_COOKIE` | `SessionCookieName` (defaults to the session cookie name) |
| `CSRF_SAME_SITE` | `SameSite` |
| `CSRF_SECURE` | `Secure` (set to `false` to disable) |
| `CSRF_HTTP_ONLY` | `HttpOnly` |
| `CSRF_SINGLE_USE` | `SingleUse` |
| `CSRF_WRITE_XSRF_COOKIE` | `WriteXSRFCookie` |
| `CSRF_XSRF_COOKIE_NAME` | `XSRFCookieName` |
| `CSRF_ERROR_MESSAGE` | `ErrorMessage` |

## Token Storage Strategies

### Session Store (Default)

Server-side token storage using sessions. Most secure for traditional web applications.

```go
import "github.com/velocitykode/velocity/csrf/stores"

config := csrf.DefaultConfig()
config.Store = stores.NewSessionStore()
```

**Pros:**
- Most secure (server-side validation)
- Works with server-side sessions
- Tokens never exposed to client

**Cons:**
- Requires session management
- Not suitable for stateless APIs

### Custom Store Implementation

The `csrf.Store` interface has four methods: `Get`, `Set`, `Delete`, and
`Exists`. `Get` must return `stores.ErrTokenNotFound` for a missing entry
(`GetToken` mints a fresh token only on that sentinel; any other error is
surfaced unchanged).

```go
import "github.com/velocitykode/velocity/csrf/stores"

type CustomStore struct {
    cache map[string]string
    mu    sync.RWMutex
}

func (s *CustomStore) Get(id string) (string, error) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    token, exists := s.cache[id]
    if !exists {
        return "", stores.ErrTokenNotFound
    }
    return token, nil
}

func (s *CustomStore) Set(id string, token string) error {
    s.mu.Lock()
    defer s.mu.Unlock()

    s.cache[id] = token
    return nil
}

func (s *CustomStore) Delete(id string) error {
    s.mu.Lock()
    defer s.mu.Unlock()

    delete(s.cache, id)
    return nil
}

func (s *CustomStore) Exists(id string) bool {
    s.mu.RLock()
    defer s.mu.RUnlock()

    _, ok := s.cache[id]
    return ok
}

// Use custom store
config.Store = &CustomStore{
    cache: make(map[string]string),
}
```


For cross-process **single-use** enforcement, a store may also implement
the optional `csrf.AtomicConsumer` interface
(`ConsumeIfMatch(id, expected string) (bool, error)`). Without it, the
middleware falls back to a per-process lock and logs a one-time warning -
single-use is then best-effort across replicas.


## Template integration

Expose the token to templates as a shared prop (e.g. `csrfToken`) by
publishing `csrf.TokenForRequest(r)` from your `SetSharePropsFunc` (see
[Quick Start](#quick-start)). Include it in your root template's meta tag
and in any form that submits to an unsafe method:

```html
<meta name="csrf-token" content="{{ .csrfToken }}">

<form method="POST" action="/submit">
    <input type="hidden" name="_token" value="{{ .csrfToken }}">
    <!-- other fields -->
</form>
```

The middleware looks for the token in this order:

1. The configured header (`config.HeaderName`, default `X-CSRF-Token`).
2. The `X-XSRF-TOKEN` header (axios/Angular convention - clients echo the
   URL-encoded `XSRF-TOKEN` cookie value).
3. The `_token` form field (settable via `config.FormField`), parsed only
   from an `application/x-www-form-urlencoded` body up to
   `config.MaxFormBodyBytes`. Multipart bodies are never parsed - send the
   token in a header instead.

Tokens are emitted in a per-response **masked** form (see `csrf.MaskToken`)
so identical bytes never repeat across responses, defeating BREACH-style
compression-oracle extraction. The middleware accepts both the masked form
and a raw framework-length token.

## Middleware integration

### Applying CSRF to the web stack

Add `RouterMiddleware()` to the web middleware list so it runs on all
browser routes:

```go
v.Middleware(func(m *velocity.MiddlewareStack) {
    csrfInstance := v.CSRF.(*csrf.CSRF)

    m.Web(
        csrfInstance.RouterMiddleware(), // CSRF validation on unsafe methods
    )
})
```

The session middleware is registered globally by `velocity.New` and runs
ahead of the web stack, so the session ID is resolvable by the time CSRF
validation runs.

### Selective application

To apply CSRF only to a subset of routes, omit it from the web stack and
add it to a specific group instead:

```go
v.Routes(func(r *velocity.Routing) {
    csrfInstance := v.CSRF.(*csrf.CSRF)

    r.Web(func(web router.Router) {
        web.Get("/", handlers.Home)

        web.Group("/account", func(acc router.Router) {
            acc.Post("/update", handlers.AccountUpdate)
            acc.Delete("/delete", handlers.AccountDelete)
        }).Use(csrfInstance.RouterMiddleware())
    })
})
```

### Conditional bypass

Use `ExcludeFunc` on the config rather than wrapping middleware:

```go
config.ExcludeFunc = func(r *http.Request) bool {
    // skip CSRF for requests carrying a bearer token
    return strings.HasPrefix(r.Header.Get("Authorization"), "Bearer ")
}
```

## Path Exclusions

### Wildcard Patterns

```go
config.ExcludePaths = []string{
    "/api/webhooks/*",      // All webhook endpoints
    "/health",              // Exact match
    "/metrics",             // Exact match
    "/public/*",            // All public endpoints
}
```

### Custom Exclusion Logic

```go
config.ExcludeFunc = func(r *http.Request) bool {
    // Exclude if API key is present
    if r.Header.Get("X-API-Key") != "" {
        return true
    }

    // Exclude if OAuth bearer token
    if strings.HasPrefix(r.Header.Get("Authorization"), "Bearer ") {
        return true
    }

    // Exclude specific user agents (e.g., monitoring tools)
    if strings.Contains(r.UserAgent(), "Monitoring") {
        return true
    }

    return false
}
```

## AJAX and Single Page Applications

### Setting Up for SPAs

Expose a refresh endpoint and exclude it from CSRF validation:

```go
// Config: exclude the refresh endpoint from validation. With velocity.New
// the CSRF instance is built from Config.CSRF, so set this on the config
// (or via CSRF_* env) rather than constructing a second instance.
cfg.CSRF.ExcludePaths = []string{"/csrf/token"}

// Routes: register the refresh handler off the framework-built v.CSRF.
v.Routes(func(r *velocity.Routing) {
    csrfInstance := v.CSRF.(*csrf.CSRF)
    handler := csrfInstance.RefreshHandler()

    r.Web(func(web router.Router) {
        web.Get("/csrf/token", func(c *router.Context) error {
            handler(c.Response, c.Request)
            return nil
        })
    })
})
```

### JavaScript Integration

```javascript
// Fetch token on page load
async function getCSRFToken() {
    const response = await fetch('/csrf/token');
    const data = await response.json();
    return data.token;
}

// Use in AJAX requests
async function submitForm(formData) {
    const token = await getCSRFToken();

    const response = await fetch('/api/submit', {
        method: 'POST',
        headers: {
            'X-CSRF-Token': token,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(formData)
    });

    return response.json();
}

// Or store in meta tag and reuse
const token = document.querySelector('meta[name="csrf-token"]').content;

fetch('/api/data', {
    method: 'POST',
    headers: {
        'X-CSRF-Token': token,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
});
```

### Axios Integration

```javascript
// Set default header for all requests
const token = document.querySelector('meta[name="csrf-token"]').content;

axios.defaults.headers.common['X-CSRF-Token'] = token;

// Now all POST/PUT/DELETE requests include the token
axios.post('/api/submit', data);
```

## Error Handling

### Default Error Response

**HTML Requests:**
```
HTTP/1.1 419 Authentication Timeout
Content-Type: text/plain

CSRF token validation failed. Please refresh and try again.
```

**JSON Requests:**
```json
{
  "code": 419,
  "message": "CSRF token validation failed. Please refresh and try again."
}
```

A request is treated as JSON when its `Content-Type` or `Accept` header
contains `application/json`.

### Custom Error Handler

```go
config.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
    // Log the error
    log.Warn("CSRF validation failed",
        "error", err,
        "ip", r.RemoteAddr,
        "path", r.URL.Path,
    )

    // Check if it's a JSON request
    if strings.Contains(r.Header.Get("Accept"), "application/json") {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(419)
        json.NewEncoder(w).Encode(map[string]interface{}{
            "error": "csrf_validation_failed",
            "message": "Your session has expired. Please refresh the page.",
        })
        return
    }

    // Render custom error page for HTML requests
    w.WriteHeader(419)
    template.Must(template.ParseFiles("views/errors/csrf.html")).Execute(w, nil)
}
```

## Security Considerations

### HTTP Status Code 419

Velocity uses status code `419 Authentication Timeout` for CSRF failures. This distinguishes CSRF errors from other validation errors.

### SameSite Cookie Attribute

```go
// Strict: Maximum CSRF protection, may break cross-site navigation
config.SameSite = http.SameSiteStrictMode

// Lax: Balanced protection (default, recommended)
config.SameSite = http.SameSiteLaxMode

// None: Minimal protection, requires Secure=true
config.SameSite = http.SameSiteNoneMode
```

### Single-Use Tokens

```go
// Enable single-use tokens for maximum security
config.SingleUse = true

// Note: Requires token refresh after each request
// Best for high-security operations
```

When `SingleUse` is enabled the `XSRF-TOKEN` convenience cookie is **not**
written (the value would be consumed by the next unsafe request and go
stale). Use `RefreshHandler` to hand out a new token after each request.

### Token Lifetime

```go
// Short lifetime for high-security applications
config.TokenLifetime = 1 * time.Hour

// Longer lifetime for better UX
config.TokenLifetime = 24 * time.Hour
```

### Session lifecycle

`*csrf.CSRF` implements `contract.CSRFTokenRotator`, which the auth
subsystem uses to keep tokens aligned with the session:

- `RotateToken(oldID, newID)` - delete the old session's token and mint a
  fresh one for the new ID (called after session regeneration on login).
- `RevokeToken(id)` - delete a session's token (called on logout).
- `WriteXSRFCookie(w, sessionID)` / `ClearXSRFCookie(w, r)` - write or
  clear the `XSRF-TOKEN` cookie so SPA clients pick up the rotated token.

Release the token store's background goroutine on shutdown with
`(*csrf.CSRF).Shutdown(ctx)`; `velocity.New` registers this for you.

### Events

When the middleware cannot resolve a session on an unsafe request it
dispatches a `csrf.session_fallback` event (`csrf.SessionFallback`).
Frequent occurrences usually mean the session middleware is not running
ahead of CSRF, or `SessionCookieName` does not match your session cookie.

## Best Practices

1. **Always Use CSRF for State-Changing Operations**: Protect POST, PUT, DELETE, PATCH requests
2. **Exclude Read-Only Operations**: GET, HEAD, OPTIONS don't need CSRF protection
3. **Use HTTPS in Production**: Set `Secure: true` to prevent token interception
4. **Implement Token Refresh**: Provide `/csrf/token` endpoint for SPAs
5. **Set Appropriate SameSite**: Use `Lax` or `Strict` based on your needs
6. **Monitor CSRF Failures**: Log failures to detect potential attacks
7. **Handle Expired Tokens Gracefully**: Show user-friendly error messages

## Testing

```go
func TestCSRFProtection(t *testing.T) {
    config := csrf.DefaultConfig()
    // SessionIDResolver is required; key tokens by the session_id cookie.
    config.SessionIDResolver = func(r *http.Request) (string, error) {
        if c, err := r.Cookie("session_id"); err == nil && c.Value != "" {
            return c.Value, nil
        }
        return "", csrf.ErrNoSession
    }
    protection := csrf.New(config)
    mw := protection.Middleware

    next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
    })
    handler := mw(next)

    // POST without token → 419
    req := httptest.NewRequest(http.MethodPost, "/submit", nil)
    rec := httptest.NewRecorder()
    handler.ServeHTTP(rec, req)
    assert.Equal(t, 419, rec.Code)

    // POST with valid token → 200
    sessionID := "test-session"
    token, _ := protection.GetToken(sessionID)

    req = httptest.NewRequest(http.MethodPost, "/submit", nil)
    req.Header.Set("X-CSRF-Token", token)
    req.AddCookie(&http.Cookie{Name: "session_id", Value: sessionID})

    rec = httptest.NewRecorder()
    handler.ServeHTTP(rec, req)
    assert.Equal(t, http.StatusOK, rec.Code)

    // GET → passes (safe method)
    req = httptest.NewRequest(http.MethodGet, "/page", nil)
    rec = httptest.NewRecorder()
    handler.ServeHTTP(rec, req)
    assert.Equal(t, http.StatusOK, rec.Code)
}
```

`Middleware` takes an `http.Handler` (net/http compatible). For the
router-compatible variant, call `RouterMiddleware()` - see the
[testing docs](/docs/core/testing) for end-to-end tests through the
full Velocity middleware chain.

## Troubleshooting

### Token Validation Always Failing

**Problem:** CSRF validation fails even with valid tokens

**Solutions:**
1. Verify session cookie is being sent
2. Check `SessionCookieName` matches your session cookie
3. Ensure cookies are not blocked by browser
4. Verify HTTPS if `Secure: true` is set

### Tokens Not Reaching Templates

**Problem:** `{{ .csrfToken }}` renders empty

**Solutions:**
1. Verify the shared-props function (`engine.SetSharePropsFunc`) is
   publishing `csrf.TokenForRequest(r)` - see
   [Template integration](#template-integration)
2. Confirm the CSRF middleware runs before the handler that renders the
   page; `TokenForRequest` returns `csrf.ErrNoTokenState` otherwise
3. Confirm the session cookie is being sent with the request (an
   anonymous request has no token to embed yet)

### AJAX Requests Failing

**Problem:** AJAX POST/PUT/DELETE returns 419

**Solutions:**
1. Include token in `X-CSRF-Token` header
2. Ensure token is fetched from meta tag or API
3. Check token hasn't expired
4. Verify content-type header is set correctly


================================================================================
# String Utilities

Source: https://vel.build/docs/core/string-utilities/
Section: Core Framework
Summary: Manipulate strings with Velocity's fluent string utilities for slugs, cases, truncation, and more.


Velocity provides a comprehensive string utilities package with powerful text manipulation functions inspired by popular web frameworks, offering fluent interfaces and lazy loading for optimal performance.

## Quick Start


**Two Ways to Use**: String utilities work with both static functions and a fluent interface for method chaining.





```go
import "github.com/velocitykode/velocity/str"

func main() {
    // Static functions - simple and direct
    result := str.Snake("HelloWorldExample")
    // Returns: "hello_world_example"

    // Case conversions
    camel := str.Camel("hello_world_example")    // "helloWorldExample"
    kebab := str.Kebab("HelloWorldExample")      // "hello-world-example"
    studly := str.Studly("hello_world_example")  // "HelloWorldExample"

    // String manipulation
    after := str.After("user@example.com", "@")  // "example.com"
    before := str.Before("user@example.com", "@") // "user"
    contains := str.Contains("Hello World", "World") // true
}
```



```go
import "github.com/velocitykode/velocity/str"

func main() {
    // Fluent interface - chain multiple operations
    result := str.Of("  Hello World Example  ").
        Trim().                    // Remove whitespace
        Snake().                   // Convert to snake_case
        Upper().                   // Convert to uppercase
        String()                   // Get final string

    // Result: "HELLO_WORLD_EXAMPLE"

    // Complex transformation
    username := str.Of("  John Doe  ").
        Trim().
        Lower().
        Replace(" ", "_").
        String()
    // Result: "john_doe"
}
```




## Case Conversion Functions




**Snake Case**: Convert strings to snake_case (lowercase with underscores)

```go
str.Snake("HelloWorldExample")    // "hello_world_example"
str.Snake("camelCaseString")      // "camel_case_string"
str.Snake("kebab-case-string")    // "kebab_case_string"
str.Snake("Mixed String Types")   // "mixed_string_types"
```


Snake case is commonly used for variable names, database column names, and file names.




**Camel Case**: Convert strings to camelCase (first letter lowercase, subsequent words capitalized)

```go
str.Camel("hello_world_example")  // "helloWorldExample"
str.Camel("kebab-case-string")    // "kebabCaseString"
str.Camel("Mixed String Types")   // "mixedStringTypes"
```


Camel case is the standard for JavaScript variables and Go field names when exported.




**Kebab Case**: Convert strings to kebab-case (lowercase with hyphens)

```go
str.Kebab("HelloWorldExample")    // "hello-world-example"
str.Kebab("camelCaseString")      // "camel-case-string"
str.Kebab("hello_world_example")  // "hello-world-example"
```


Kebab case is commonly used for URL slugs, CSS class names, and HTML attributes.




**Studly Case**: Convert strings to StudlyCase/PascalCase (all words capitalized)

```go
str.Studly("hello_world_example") // "HelloWorldExample"
str.Studly("kebab-case-string")   // "KebabCaseString"
str.Studly("Mixed String Types")  // "MixedStringTypes"
```


Studly case is used for Go struct names, class names, and other type definitions.





## String Manipulation Functions

### Extract Substrings

```go
// Get text after a substring
str.After("user@example.com", "@")          // "example.com"
str.After("internal/handlers/UserHandler", "/") // "handlers/UserHandler"

// Get text before a substring
str.Before("user@example.com", "@")         // "user"
str.Before("path/to/file.txt", ".")         // "path/to/file"

// Get text between two substrings
str.Between("Hello [World] Test", "[", "]") // "World"
str.Between("<div>Content</div>", ">", "<") // "Content"
```

### String Checks

```go
// Check if string contains substring
str.Contains("Hello World", "World")        // true
str.Contains("Hello World", "world")        // false (case-sensitive)

// Check if string starts with substring
str.StartsWith("Hello World", "Hello")      // true
str.StartsWith("Hello World", "World")      // false

// Check if string ends with substring
str.EndsWith("Hello World", "World")        // true
str.EndsWith("Hello World", "Hello")        // false

// Check if a string exactly matches another (case-sensitive)
str.Exactly("Hello", "Hello")               // true
str.Exactly("Hello", "hello")               // false
```

### String Transformations

```go
// Limit string to specified length (default suffix "...")
str.Limit("This is a long string", 10)      // "This is a ..."
str.Limit("Short", 10)                      // "Short"
str.Limit("This is a long string", 7, "")   // "This is"

// Generate a cryptographically random alphanumeric string.
// Length defaults to 16; returns (string, error). The error is
// non-nil only if the system entropy source fails.
token, err := str.Random()                  // 16-character random string
token, err = str.Random(8)                  // 8-character random string

// Repeat string
str.Repeat("Hello", 3)                      // "HelloHelloHello"
str.Repeat("-=", 5)                         // "-=-=-=-=-="

// Replace all occurrences. Signature is Replace(search, replace, subject)
str.Replace("World", "Go", "Hello World World") // "Hello Go Go"

// Reverse string (UTF-8 aware)
str.Reverse("Hello")                        // "olleH"
str.Reverse("12345")                        // "54321"
```

### Formatting and Inflection

```go
// Title and headline casing
str.Title("hello world")                    // "Hello World"
str.Headline("steve_jobs")                  // "Steve Jobs"

// Mask part of a string with a character (negative index counts from end)
str.Mask("1234567890", '*', 3)              // "123*******"
str.Mask("taylor@example.com", '*', 1, 3)   // "t***or@example.com"

// Padding (default pad string is a single space)
str.PadLeft("5", 3, "0")                    // "005"
str.PadRight("5", 3, "0")                   // "500"
str.PadBoth("5", 5, "-")                     // "--5--"

// Collapse whitespace (Squish also folds Unicode spaces)
str.Squish("  hello   world  ")             // "hello world"

// Simple English inflection
str.Plural("child")                         // "childs" (basic rules only)
str.Plural("category")                      // "categories"
str.Singular("categories")                  // "category"
```


`Plural` and `Singular` apply a small set of common English rules and are not
a full inflection engine; verify irregular words before relying on them.


## Fluent Interface (Stringable)

For method chaining, use the fluent interface:

```go
import "github.com/velocitykode/velocity/str"

result := str.Of("  Hello World Example  ").
    Trim().                    // Remove whitespace
    Snake().                   // Convert to snake_case
    Upper().                   // Convert to uppercase
    String()                   // Get final string

// Result: "HELLO_WORLD_EXAMPLE"
```

### Available Fluent Methods

```go
s := str.Of("Hello World")

// Case conversions
s.Snake()                     // Chain snake_case conversion
s.Camel()                     // Chain camelCase conversion
s.Kebab()                     // Chain kebab-case conversion
s.Studly()                    // Chain StudlyCase conversion
s.Upper()                     // Chain uppercase conversion
s.Lower()                     // Chain lowercase conversion

// String manipulations
s.Trim()                      // Chain whitespace trimming
s.Replace("World", "Go")      // Chain replacement
s.After("@")                  // Chain after extraction
s.Before("@")                 // Chain before extraction
s.Limit(10)                   // Chain length limiting

// Get final result
finalString := s.String()     // Convert back to string
```

## Markdown

`Markdown` renders CommonMark plus the GitHub extensions (tables, strikethrough, task lists, autolinks) to HTML, and `InlineMarkdown` renders inline syntax only with no block wrappers. Both strip raw HTML and drop unsafe link destinations unless `markdown.AllowHTML()` is passed, and both accept any `markdown.Option`. The fluent `Markdown()` and `InlineMarkdown()` methods do the same.

```go
str.Markdown("# Title\n\nSome **bold** text")
// <h1>Title</h1>
// <p>Some <strong>bold</strong> text</p>

str.InlineMarkdown("**bold** text")
// <strong>bold</strong> text

str.Markdown("<script>x</script> [go](javascript:alert(1))")
// <p>x <a>go</a></p>
```

See the [Markdown](/docs/core/markdown/) page for documents, directives, highlighting and site collections.

## Performance

The string helpers are plain functions, so Go's linker strips any helper you
never call from the final binary. Functions that rely on regular expressions
share a bounded, thread-safe LRU cache of compiled patterns, so repeated calls
do not recompile.


**Performance notes:**
- **Regex caching**: Compiled patterns are cached and reused across calls.
- **Bounded memory**: The cache uses LRU eviction with a fixed cap (1024 entries), so user-controlled patterns cannot drive unbounded growth.
- **UTF-8 aware**: Helpers like `Limit`, `Reverse`, `Length`, and `Substr` operate on runes, not bytes.


## Advanced Usage

### Slugs and Custom Separators

`Slug` produces a URL-friendly slug. The separator defaults to `-` but can
be overridden with an optional second argument:

```go
str.Slug("Hello World!")        // "hello-world"
str.Slug("Hello World!", "_")   // "hello_world"
str.Slug("Café del Mar", ".")   // "caf.del.mar" (non-ASCII is collapsed)
```

### Regex Pattern Caching

The package automatically caches compiled regex patterns for better performance:

```go
// First call compiles and caches the regex
str.Slug("First String")

// Subsequent calls reuse the cached regex
str.Slug("Second String")  // Faster execution
str.Slug("Third String")   // Even faster
```


Only regex-backed helpers (such as `Slug`, `IsUrl`, `IsUuid`, and `Match`)
touch this cache. Case converters like `Snake` and `Kebab` use plain string
scanning and never compile a regex, and `Markdown` renders through the
`markdown` package.


## Testing String Functions

```go
func TestStringUtilities(t *testing.T) {
    // Test case conversions
    assert.Equal(t, "hello_world", str.Snake("HelloWorld"))
    assert.Equal(t, "helloWorld", str.Camel("hello_world"))
    assert.Equal(t, "hello-world", str.Kebab("HelloWorld"))

    // Test string manipulation
    assert.Equal(t, "example.com", str.After("user@example.com", "@"))
    assert.Equal(t, "user", str.Before("user@example.com", "@"))
    assert.True(t, str.Contains("Hello World", "World"))

    // Test fluent interface
    result := str.Of("  Hello World  ").Trim().Snake().String()
    assert.Equal(t, "hello_world", result)
}
```

## Configuration

The string utilities require no configuration and read no environment
variables. Regex pattern caching is always on (see below) and needs no
setup.

## Best Practices

1. **Use Static Functions**: For simple operations, use static functions like `str.Snake()`
2. **Use Fluent Interface**: For complex transformations, chain operations with `str.Of()`
3. **Cache Results**: Store frequently used transformations in variables
4. **Validate Input**: Check for empty strings before processing
5. **Consider Unicode**: The package handles UTF-8 correctly for international text

## Examples




**Processing user input for registration:**

```go
func processUsername(input string) string {
    return str.Of(input).
        Trim().                    // Remove whitespace
        Lower().                   // Normalize case
        Replace(" ", "_").         // Replace spaces
        Limit(20).                 // Limit length
        String()
}

username := processUsername("  John Doe  ")
// Result: "john_doe"
```


Perfect for cleaning user input while maintaining readability and enforcing length limits.




**Generating API endpoints from model names:**

```go
func generateEndpoint(modelName string) string {
    return "/api/" + str.Snake(modelName)
}

endpoint := generateEndpoint("UserHandler")
// Result: "/api/user_handler"

// Multiple endpoints
endpoints := []string{
    generateEndpoint("ProductHandler"),  // "/api/product_handler"
    generateEndpoint("OrderHandler"),    // "/api/order_handler"
    generateEndpoint("CustomerHandler"), // "/api/customer_handler"
}
```


Automatically converts Go struct names to REST API conventions.




**Sanitizing file names for safe storage:**

```go
func sanitizeFileName(name string) string {
    return str.Of(name).
        Replace(" ", "_").         // Replace spaces
        Snake().                   // Convert to snake_case
        Lower().                   // Lowercase
        String()
}

fileName := sanitizeFileName("My Important Document")
// Result: "my_important_document"

// Batch processing
files := []string{
    "User Profile Picture",
    "Invoice 2024-01",
    "Meeting Notes",
}

for _, file := range files {
    safe := sanitizeFileName(file)
    fmt.Printf("%s -> %s\n", file, safe)
}
```


Ensures file names are safe across different operating systems and file systems.







================================================================================
# Markdown

Source: https://vel.build/docs/core/markdown/
Section: Core Framework
Summary: Render Markdown safely with the str helpers, or build documentation sites from embedded Markdown with the markdown package.


Velocity renders Markdown at two levels. The `str` package converts a string to HTML in one call, safe by default. The `markdown` package renders whole documents and hands back the structure a docs site needs: front matter, title, table of contents, plain text for search, and a collection helper that turns an embedded directory of Markdown files into pages, navigation, search index and llms.txt output.

## Quick Start




```go
import "github.com/velocitykode/velocity/str"

html := str.Markdown("# Release notes\n\nFixes **12** bugs.")
// <h1>Release notes</h1>
// <p>Fixes <strong>12</strong> bugs.</p>

label := str.InlineMarkdown("Read the **docs**")
// Read the <strong>docs</strong>
```



```go
import "github.com/velocitykode/velocity/markdown"

r := markdown.New()

doc, err := r.Render(src)
if err != nil {
    return err // only malformed front matter fails
}

doc.HTML        // template.HTML, ready for a template or an Inertia prop
doc.Title       // front matter title, else the first h1
doc.TOC         // []markdown.Heading nested from h2 and h3
doc.FrontMatter // map[string]any
doc.Plain       // text without markup, for search and llms.txt
doc.Words       // word count of Plain
```



```go
import (
    "embed"

    "github.com/velocitykode/velocity/markdown"
)

//go:embed docs
var docsFS embed.FS

site, err := markdown.LoadFS(docsFS, "docs", markdown.New())
if err != nil {
    return err
}

site.Tree()                 // sections and pages, ordered by weight
site.Find("apps/deploy")    // by slug or by path
site.SearchIndex("/docs")   // title, section, url, excerpt per page
site.LLMSText("https://example.com/docs")
```





**Safe by default.** Both levels strip raw HTML and drop link, image and autolink destinations that use `javascript:`, `vbscript:`, `file:` or a non-image `data:` scheme. Pass `markdown.AllowHTML()` only for input you trust.


## String Helpers

`str.Markdown` renders CommonMark plus the GitHub extensions: tables, strikethrough, task lists and autolinks. Headings render as bare `<h1>` through `<h6>` and fenced code as `<pre><code class="language-go">`. It fits user-facing content such as comments, descriptions and release notes.

```go
str.Markdown("- [x] shipped\n- [ ] pending")
// <ul>
// <li><input checked="" disabled="" type="checkbox"> shipped</li>
// <li><input disabled="" type="checkbox"> pending</li>
// </ul>

str.Markdown("Visit https://vel.build")
// <p>Visit <a href="https://vel.build">https://vel.build</a></p>
```

`str.InlineMarkdown` recognises inline syntax only and wraps nothing in `<p>`. Block syntax such as `# ` or `- ` stays literal text, which makes it the right call for labels, titles and single-line fields.

```go
str.InlineMarkdown("**Bold** and `code` with a [link](/docs)")
// <strong>Bold</strong> and <code>code</code> with a <a href="/docs">link</a>

str.InlineMarkdown("# not a heading")
// # not a heading
```

Both accept the same options as the `markdown` package, and the fluent interface mirrors them:

```go
str.Markdown(trusted, markdown.AllowHTML())
str.Markdown(body, markdown.WithLinkRewrite(func(href string) string {
    return strings.TrimSuffix(href, ".md")
}))

str.Of("**bold**").InlineMarkdown().Upper().String()
// <STRONG>BOLD</STRONG>
```

What the safety defaults do to hostile input:

```go
str.Markdown("hello <script>alert(1)</script>")
// <p>hello alert(1)</p>

str.Markdown("[click](javascript:alert(1))")
// <p><a>click</a></p>

str.Markdown("![x](data:text/html,x)")
// <p><img alt="x"></p>
```

## Documents

`markdown.New` builds a `*Renderer`. Build it once, at startup or as a package variable, and reuse it: it holds no per-document state and is safe for concurrent use.

```go
var docs = markdown.New(
    markdown.TOCLevels(2, 4),
    markdown.WithHighlighter(chroma.New()),
)
```

### Front matter

A YAML block between `---` lines at the top of the file is decoded into `Document.FrontMatter` and removed from the body. `title`, when it is a non-empty string, becomes `Document.Title`; otherwise the first h1 does.

```markdown
---
title: Deploy an app
weight: 2
description: Ship a Velocity app to Velship.
---
# Deploy an app
```

`markdown.ParseFrontMatter(src)` splits the block on its own, for code that builds a navigation tree before rendering. A `---` line with no closing fence is a thematic break, not front matter, and malformed YAML is the one error `Render` returns.

### Headings and the table of contents

Every heading gets a stable, GitHub-style id: lower-cased, punctuation removed, spaces turned into hyphens, letters of any script kept. Repeated headings get `-1`, `-2` suffixes and `## Title {#custom-id}` sets an explicit id. Explicit ids win wherever they appear in the document: a generated id never takes a slug an explicit id claims, so `## Foo` followed by `## Bar {#foo}` renders `foo-1` and `foo`. Headings from h2 down carry an anchor link:

```html
<h2 id="install">Install<a class="anchor" href="#install" aria-label="Link to this section">#</a></h2>
```

`Document.TOC` nests the h2 and h3 headings in document order; `markdown.TOCLevels(min, max)` widens or narrows the range.

```go
type Heading struct {
    ID       string
    Level    int
    Text     string    // heading text without markup
    Children []Heading
}
```

`markdown.WithHeading(fn)` replaces the heading markup. The hook receives the `Heading` (with its id and plain text) and the rendered inline body:

```go
markdown.WithHeading(func(w io.Writer, h markdown.Heading, body template.HTML) {
    fmt.Fprintf(w, `<h%d id="%s">%s</h%d>`+"\n", h.Level, h.ID, body, h.Level)
})
```

### Extensions

Tables, strikethrough, task lists, autolinks, footnotes and definition lists are on. Smart punctuation is off on purpose: quotes, dashes and ellipses in code-heavy prose render as typed.

### Container directives

A fenced block of three or more colons followed by a name groups content under a directive. An optional title follows the name.

```markdown
:::note
Rendering is pure and reusable.
:::

:::warning Keys rotate
Restarting the process rotates the signing key.
:::
```

Any name renders as a neutral callout, labelled with the title or the capitalised name:

```html
<aside class="callout" data-kind="note"><p class="callout-label">Note</p><p>Rendering is pure and reusable.</p>
</aside>
```

`:::steps` turns the h3 headings in its body into an ordered list, one `<li>` per step; content before the first h3 renders ahead of the list.

```markdown
:::steps
### Install the CLI
Run the installer.
### Create an app
Run `vel new`.
:::
```

```html
<ol class="steps"><li><h3 id="install-the-cli">Install the CLI<a class="anchor" ...>#</a></h3>
<p>Run the installer.</p>
</li>
<li><h3 id="create-an-app">Create an app<a class="anchor" ...>#</a></h3>
<p>Run <code>vel new</code>.</p>
</li>
</ol>
```

A line of colons inside a fenced code block is code, not the end of the directive, so examples that show the directive syntax render as expected. To nest directives, give the outer fence more colons than the inner one:

```markdown
::::steps
### First
:::note
Nested inside a step.
:::
::::
```

`markdown.WithContainer(name, fn)` replaces the markup for one name. The hook receives the title and the rendered body; for `steps` the body is the sequence of `<li>` items.

```go
markdown.WithContainer("note", func(w io.Writer, title string, body template.HTML) {
    fmt.Fprintf(w, `<div class="admonition admonition-note">%s</div>`+"\n", body)
})
```

### Code blocks

The info string carries the language and optional `key=value` attributes. A `title` wraps the block in a figure:

````markdown
```go title="main.go"
fmt.Println("hi")
```
````

```html
<figure class="code"><figcaption>main.go</figcaption><pre><code class="language-go">fmt.Println(&quot;hi&quot;)
</code></pre></figure>
```

`markdown.WithCodeBlock(fn)` replaces the markup for every fenced and indented block:

```go
markdown.WithCodeBlock(func(w io.Writer, b markdown.CodeBlock) {
    // b.Lang, b.Title, b.Attrs, b.Code (raw source), b.Body (highlighted or escaped)
    fmt.Fprintf(w, `<code-block lang="%s" title="%s">%s</code-block>`+"\n", b.Lang, b.Title, b.Body)
})
```

Highlighting is a hook. `markdown.WithHighlighter(fn)` receives the language and source and returns the markup for the inside of `<code>`, or reports false to keep the escaped source. The `markdown/chroma` subpackage adapts Chroma so the base package carries no highlighter dependency:

```go
import "github.com/velocitykode/velocity/markdown/chroma"

r := markdown.New(markdown.WithHighlighter(chroma.New()))

// Tokens carry CSS classes; serve the stylesheet for a Chroma style once.
// Its rules are scoped to pre, matching the default markup, so the pre
// takes the style's background and every token its colour with no wiring.
css, err := chroma.Stylesheet("github")

// Or emit inline styles for self-contained output. Only the tokens carry
// styles; give the pre the style's background yourself.
r = markdown.New(markdown.WithHighlighter(chroma.New(chroma.WithStyle("monokai"))))
```

### Link rewriting

Docs written for GitHub link to sibling files. `markdown.WithLinkRewrite(fn)` maps every link and image destination before it is written; the safety check runs on the original and on the rewritten value.

```go
markdown.WithLinkRewrite(func(href string) string {
    if strings.Contains(href, "://") || !strings.HasSuffix(href, ".md") {
        return href
    }
    href = strings.TrimPrefix(strings.TrimPrefix(href, "../"), "./")
    return "/docs/" + strings.TrimSuffix(href, ".md")
})
// ../apps/deploy.md becomes /docs/apps/deploy
```

### Basic and inline modes

`markdown.Basic()` limits the engine to CommonMark plus the GitHub extensions with plain headings and code blocks and no front matter, directives, footnotes or definition lists. `markdown.Inline()` renders inline syntax only, with no block wrappers. `str.Markdown` and `str.InlineMarkdown` use these modes.

## Sites

`markdown.LoadFS(fsys, root, r)` walks every `.md` and `.markdown` file below `root`, renders each with `r` (a default renderer when nil) and returns a `*Collection`. The first file that fails to render aborts the load with an error naming the file.

### Pages

```go
type Page struct {
    Path     string    // apps/deploy.md, relative to root
    Slug     string    // apps/deploy; index pages take their directory
    Section  string    // front matter section, else the first directory
    Weight   int       // front matter weight, 0 when absent
    Index    bool      // index.md, _index.md or README.md
    Document *Document
    Source   []byte    // Markdown body, front matter removed
}

page.URL("/docs")   // /docs/apps/deploy; the root index gives /docs
```

### Navigation

`Tree()` returns the sections in order: root-level pages first, then sections by the weight of their index page (lower first), then by name. A section without an index page, or whose index page has no weight, comes after every weighted section, alphabetically. Within a section the index page leads and the rest sort by weight, then title, then path; unweighted pages follow every weighted one. Authors weight what matters and the rest fall in alphabetically. The docs navigation depends on this order, so give every section an index page with a weight.

```go
for _, section := range site.Tree() {
    fmt.Println(section.Title)            // index title, or "Getting Started" from getting-started
    for _, page := range section.Pages {
        fmt.Println("  ", page.Document.Title, page.URL("/docs"))
    }
}

page, ok := site.Find("apps/deploy")      // slug or path, leading slash ignored
prev, next := site.Prev(page), site.Next(page)  // within the section, nil at the ends
```

### Search and llms.txt

`SearchIndex(baseURL)` returns one entry per page with the title, section name, url and an excerpt: the front matter `description` when present, otherwise the opening words of the plain text.

`LLMSText(baseURL)` renders an llms.txt index: an H1 with the root index title, its description as a blockquote, then one H2 per section listing `- [title](url): excerpt`. `LLMSFullText(baseURL)` concatenates every page as an H1, a `URL:` line and the Markdown body.

```go
r.Get("/llms.txt", func(ctx *router.Context) error {
    return ctx.String(200, site.LLMSText("https://example.com/docs"))
})
```

### Serving through Inertia

```go
func (h *DocsHandler) Show(ctx *router.Context) error {
    page, ok := site.Find(ctx.Param("slug"))
    if !ok {
        return router.NewHTTPError(404, "page not found")
    }
    props := view.Props{
        "nav":   site.Tree(),
        "title": page.Document.Title,
        "html":  page.Document.HTML,
        "toc":   page.Document.TOC,
    }
    if prev := site.Prev(page); prev != nil {
        props["prev"] = map[string]string{"title": prev.Document.Title, "url": prev.URL("/docs")}
    }
    if next := site.Next(page); next != nil {
        props["next"] = map[string]string{"title": next.Document.Title, "url": next.URL("/docs")}
    }
    return view.Render(ctx, "Docs/Show", props)
}
```

### Hook types

```go
type Option func(*config)                                            // markdown.New and the str helpers accept these
type ContainerFunc func(w io.Writer, title string, body template.HTML) // markdown.WithContainer
type CodeBlockFunc func(w io.Writer, block CodeBlock)                  // markdown.WithCodeBlock
type Highlighter   func(lang, code string) (template.HTML, bool)       // markdown.WithHighlighter
type HeadingFunc   func(w io.Writer, heading Heading, body template.HTML) // markdown.WithHeading

type SearchEntry struct {                                              // (*Collection).SearchIndex
    Title   string
    Section string
    URL     string
    Excerpt string
}
```

`chroma.Option` values configure `chroma.New`; `chroma.WithStyle` is the only one today.

## API Reference

| Symbol | Purpose |
|--------|---------|
| `str.Markdown(s, opts...)` | Render GitHub Flavored Markdown to HTML |
| `str.InlineMarkdown(s, opts...)` | Render inline Markdown with no block wrappers |
| `markdown.New(opts...)` | Build a reusable, concurrency-safe `*Renderer` |
| `(*Renderer).Render(src)` | Render a document to a `*Document` |
| `markdown.ParseFrontMatter(src)` | Split YAML front matter from a source |
| `markdown.Slug(text)` | GitHub-style heading id |
| `markdown.AllowHTML()` | Pass raw HTML and unsafe destinations through |
| `markdown.Basic()` | CommonMark plus GitHub extensions only |
| `markdown.Inline()` | Inline syntax only, no block wrappers |
| `markdown.TOCLevels(min, max)` | Heading levels collected into the TOC |
| `markdown.WithContainer(name, fn)` | Replace the markup of one directive |
| `markdown.WithCodeBlock(fn)` | Replace the code block markup |
| `markdown.WithHighlighter(fn)` | Plug in syntax highlighting |
| `markdown.WithLinkRewrite(fn)` | Map link and image destinations |
| `markdown.WithHeading(fn)` | Replace the heading markup |
| `markdown.LoadFS(fsys, root, r)` | Render a directory of Markdown into a `*Collection` |
| `(*Collection).Pages()` | Every page in navigation order |
| `(*Collection).Tree()` | Sections and pages ordered by weight |
| `(*Collection).Find(key)` | Look up a page by slug or path |
| `(*Collection).Prev(p)`, `Next(p)` | Neighbours within a section |
| `(*Collection).SearchIndex(baseURL)` | Search entries with excerpts |
| `(*Collection).LLMSText(baseURL)` | llms.txt index |
| `(*Collection).LLMSFullText(baseURL)` | llms-full.txt body |
| `(*Page).URL(baseURL)` | Public URL of a page |
| `chroma.New(opts...)` | Chroma-backed `markdown.Highlighter` |
| `chroma.WithStyle(name)` | Inline styles instead of CSS classes |
| `chroma.Stylesheet(name)` | CSS for class-based output, scoped to `pre` |


================================================================================
# Exceptions

Source: https://vel.build/docs/core/exceptions/
Section: Core Framework
Summary: Structured error handling with rich dev pages, safe production responses, content negotiation, and pluggable reporters.


The `exceptions` package turns errors returned from handlers into
correctly negotiated HTTP responses - verbose stack traces in
development, safe minimal responses in production - and runs reporters
so errors reach your logs or monitoring service.

Import path: `github.com/velocitykode/velocity/exceptions`

## The Handler

`*exceptions.Handler` is the central type. Velocity constructs one in
`velocity.New()` and stores it at `app.Services.Exceptions`. You can
reconfigure it via `v.Exceptions(...)` during bootstrap. The callback
receives the handler as an `exceptions.ExceptionHandler` interface,
which exposes the configuration methods (`AddReporter`,
`AddRenderer`, `SetReporters`, `DontReport`, `SetAPIMode`,
`SetAPIPrefixes`, `RegisterCustomHandler`, `SetDebug`, ...).

```go
v.Exceptions(func(h exceptions.ExceptionHandler) {
    // add reporters, renderers, custom handlers
})
```

Build one yourself with `NewHandler(opts...)`:

```go
h := exceptions.NewHandler(
    exceptions.WithDebug(true),
    exceptions.WithEnvironment("development"),
)
```

Debug mode is **force-disabled in production** regardless of the
`WithDebug` flag - the handler logs a warning and continues without
exposing stack traces.

### Available options

| Option                          | Effect                                                                 |
| ------------------------------- | ---------------------------------------------------------------------- |
| `WithDebug(bool)`               | Include stack traces and source context in responses                   |
| `WithEnvironment(string)`       | Environment name; `"production"` force-disables debug                  |
| `WithReporters(...Reporter)`    | Replace the default log reporter                                       |
| `WithRenderers(map[string]Renderer)` | Merge in renderers by content type (overrides the `"html"`/`"json"` defaults) |
| `WithDontReport(...string)`     | Exception type names that should be silenced                           |
| `WithAPIMode(bool)`             | Always respond with JSON                                               |
| `WithAPIPrefixes(...string)`    | URL prefixes treated as API routes (JSON by default)                   |
| `WithTrustedProxies([]*net.IPNet)` | Proxy networks whose forwarded headers may be honoured when capturing the client IP (nil = ignore forwarded headers) |
| `WithHandlerLogger(Logger)`     | Logger used for internal handler warnings                              |

## The Exception interface

Any error satisfying `Exception` participates in the exception
lifecycle:

```go
type Exception interface {
    error
    GetMessage() string
    GetCode() int
    GetPrevious() error
    GetContext() map[string]any
}
```

Two optional interfaces opt in to more behavior:

- `Reportable` - returns whether the exception should be sent to
  reporters
- `Renderable` - renders its own response

## BaseException

`*BaseException` is the starter implementation. Use it directly or
embed it in a custom type:

```go
e := exceptions.NewBaseException("payment declined", 402).
    WithPrevious(err).
    WithContext("user_id", user.ID).
    WithContext("order_id", order.ID)
```

Context data is serialized into dev-mode responses and passed to
reporters.

## HTTP-specific exceptions

Preconstructed exceptions cover the common HTTP failure cases. Each
carries a status code and a sensible default message; most accept an
optional override:

| Constructor                                      | Status |
| ------------------------------------------------ | ------ |
| `NewHttpException(code, msg)`                    | any    |
| `NewBadRequestHttpException(msg?)`               | 400    |
| `NewUnauthorizedHttpException(msg?)`             | 401    |
| `NewForbiddenHttpException(msg?)`                | 403    |
| `NewNotFoundHttpException(msg?)`                 | 404    |
| `NewMethodNotAllowedHttpException(methods, msg?)`| 405    |
| `NewConflictHttpException(msg?)`                 | 409    |
| `NewGoneHttpException(msg?)`                     | 410    |
| `NewTooManyRequestsException(retryAfter, msg?)`  | 429    |
| `NewInternalServerErrorException(msg?)`          | 500    |
| `NewServiceUnavailableException(retryAfter, msg?)` | 503  |
| `NewValidationException(errors, msg?)`           | 422    |

All 4xx HTTP exceptions return `false` from `ShouldReport()` - they
aren't surfaced to reporters by default. 5xx and non-HTTP exceptions
report by default.

Attach headers with `.WithHeader()` or `.WithHeaders()`:

```go
return exceptions.NewTooManyRequestsException(60, "slow down").
    WithHeader("Retry-After", "60")
```

## Abort helpers

Three free functions let you bail out of a handler concisely:

```go
func Show(c *router.Context) error {
    post, err := models.FindPost(c.Param("id"))
    if err != nil {
        return exceptions.Abort(http.StatusNotFound, "post not found")
    }

    if err := exceptions.AbortUnless(post.Published, http.StatusForbidden, "draft"); err != nil {
        return err
    }

    return c.JSON(http.StatusOK, post)
}
```

- `Abort(code, msg?)` - always returns an `HttpException`
- `AbortIf(condition, code, msg?)` - exception when condition is `true`, else `nil`
- `AbortUnless(condition, code, msg?)` - exception when condition is `false`, else `nil`

## ValidationException

```go
return exceptions.NewValidationException(map[string][]string{
    "email":    {"must be a valid email"},
    "password": {"must be at least 8 characters"},
}, "the given data was invalid")
```

Rendered as a 422 response with the error map serialized alongside the
top-level message. Use this type when you need to surface per-field
validation errors without running the full `validation` pipeline.

## Content negotiation

The handler picks a renderer based on the request:

1. `WithAPIMode(true)` - always JSON.
2. Request path matches any `WithAPIPrefixes` entry - JSON.
3. `Accept` header contains `application/json` - JSON.
4. `Content-Type` contains `application/json` - JSON.
5. `X-Requested-With: XMLHttpRequest` - JSON.
6. Request path starts with `/api` - JSON.
7. Otherwise - HTML.

Swap the defaults with `WithRenderers(...)` if you need a custom
serialization (protobuf, XML) or a templated HTML error page.

## Custom handlers per type

Register behavior for specific error types with
`RegisterCustomHandler(exceptionType any, handler func(RenderContext, error, *ExceptionContext))`.
The first argument is matched by runtime type (`reflect.TypeOf`), so
pass a value of the concrete error type you want to intercept:

```go
v.Exceptions(func(h exceptions.ExceptionHandler) {
    h.RegisterCustomHandler(&mypkg.RecordNotFoundError{}, func(ctx exceptions.RenderContext, err error, ec *exceptions.ExceptionContext) {
        ctx.WriteHeader(http.StatusNotFound)
        ctx.Write([]byte(`{"error":"not found"}`))
    })
})
```

The handler consults this registration before falling back to the
default renderer. Note that the type is matched exactly: an error must
be of the same concrete type (after `Renderable` is checked) for its
custom handler to fire.

## Reporters

Reporters are called for every exception that opts into reporting.
The default is `LogReporter` - writes a structured log line via the
app's logger.

```go
type Reporter interface {
    Report(err error, ctx *ExceptionContext)
}
```

Build your own by implementing the interface:

```go
type SentryReporter struct { /* ... */ }

func (s *SentryReporter) Report(err error, ctx *exceptions.ExceptionContext) {
    sentry.CaptureException(err, sentry.WithExtras(ctx.Extra))
}

v.Exceptions(func(h exceptions.ExceptionHandler) {
    h.AddReporter(&SentryReporter{})
})
```

For lightweight side-effects, use `NewCallbackReporter(fn)` where `fn`
has the signature `func(err error, ctx *exceptions.ExceptionContext)`.
`NewMultiReporter(...Reporter)` fans a single error out to several
reporters. The built-in `LogReporter` accepts options:
`WithLogger(log.Logger)`, `WithContextKeys(...string)`, and
`WithoutContext()`.

### ExceptionContext

`*ExceptionContext` carries request metadata into reporters:

```go
ec := exceptions.NewExceptionContext().
    WithRequestInfo("POST", "/checkout", "10.0.0.1", "curl/8.0").
    WithIDs("req_123", "trace_abc").
    WithUserID(strconv.Itoa(user.ID)).
    WithExtra("order_id", order.ID)
```

The request middleware populates this automatically; you only build
one directly when reporting outside the request path (e.g. from a
queue worker).

## Silencing exception types

`WithDontReport(types...)` matches on the runtime type name. The name
is the bare type identifier with the package prefix and pointer marker
stripped (e.g. a `*NotFoundHttpException` matches `"NotFoundHttpException"`):

```go
h := exceptions.NewHandler(
    exceptions.WithDontReport(
        "NotFoundHttpException",
        "ClientCanceledError",
    ),
)
```

The same list can be appended at runtime with `h.DontReport(name)`.
Reporter calls are skipped; the response is still rendered normally.

## Dev-mode pages

When `WithDebug(true)` is set outside production, the HTML renderer
includes:

- Exception type, message, and code
- Stack trace with source context (5 lines either side of each frame)
- Request method, path, IP, user-agent
- Attached context from `WithContext` / `WithExtra`

In production the response shows only the status text and message.

## Middleware integration

The exception middleware is applied automatically when you run
`velocity.New()`; you rarely wire it yourself. If you're embedding
Velocity's handler in a bare `net/http` server, use:

```go
mw := exceptions.Middleware(h)
srv := &http.Server{Handler: mw(myMux)}
```

For per-handler wrapping use `MiddlewareFunc` or pass
`ErrorHandler(h)` anywhere you need a plain `func(http.ResponseWriter, *http.Request, error)`.


================================================================================
# Frontend Setup

Source: https://vel.build/docs/frontend/setup/
Section: Frontend & Views
Summary: Set up Velocity's frontend stack with Inertia.js, React, TypeScript, and Vite for hot-reload development.


Velocity's frontend stack combines Go, Inertia.js, React, TypeScript, and Vite for a modern development experience.

## How It Works

The frontend stack combines four technologies:

- **Go Backend** - Handles routing, handlers, and data
- **Inertia.js** - Bridge between Go and React (no API endpoints needed)
- **React + TypeScript** - Type-safe frontend components
- **Vite** - Fast development server and production bundling

The flow works like this:

1. User visits `/posts`
2. Go router calls `PostHandler.Index()`
3. Handler fetches data and calls `view.Render(ctx, "Posts/Index", props)`
4. Inertia sends props to React component at `resources/js/pages/Posts/Index.tsx`
5. React renders the page with full SPA navigation

No REST API, no GraphQL, no separate frontend routing. Just handlers and components.

## Project Structure

```
your-app/
├── app/
│   └── handlers/       # Go handlers
├── resources/
│   ├── js/
│   │   ├── app.tsx        # React entry point
│   │   ├── pages/         # Page components (mapped to routes)
│   │   ├── components/    # Reusable UI components
│   │   ├── layouts/       # Layout wrappers
│   │   └── hooks/         # Custom React hooks
│   ├── css/
│   │   └── app.css        # Tailwind CSS
│   └── views/
│       └── app.html       # HTML template
├── public/
│   └── build/             # Compiled assets (generated)
├── vite.config.ts         # Vite configuration
├── tsconfig.json          # TypeScript configuration
└── package.json           # npm dependencies
```

## Install Dependencies

```bash
npm install
```

Key packages included:

| Package | Purpose |
|---------|---------|
| `@inertiajs/react` | Inertia.js React adapter |
| `react` / `react-dom` | React 19 |
| `typescript` | Type checking |
| `vite` | Build tool |
| `tailwindcss` | Utility-first CSS |

## Vite Configuration

```typescript
// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import path from 'path';
import { defineConfig } from 'vite';

export default defineConfig({
    plugins: [tailwindcss()],
    resolve: {
        alias: {
            '@': path.resolve(__dirname, './resources/js'),
        },
    },
    build: {
        outDir: 'public/build',
        manifest: true,
        rollupOptions: {
            input: 'resources/js/app.tsx',
        },
    },
    server: {
        port: 5173,
        strictPort: true,
        host: 'localhost',
    },
    esbuild: {
        jsx: 'automatic',
    },
});
```

Configuration breakdown:

- **`@` alias** - Import from `@/components/Button` instead of `../../components/Button`
- **`public/build`** - Compiled assets go here, served by Go
- **`manifest: true`** - Generates manifest.json for production asset versioning
- **Port 5173** - Vite dev server runs separately from Go server

## TypeScript Configuration

```json
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./resources/js/*"]
    }
  },
  "include": ["resources/js"]
}
```

## React Entry Point

```typescript
// resources/js/app.tsx
import '../css/app.css';
import { createInertiaApp, router } from '@inertiajs/react';
import { createRoot } from 'react-dom/client';

// CSRF token handling
let csrfToken: string | null = null;

router.on('navigate', (event) => {
    const pageProps = event.detail.page.props as { csrf_token?: string };
    if (pageProps.csrf_token) {
        csrfToken = pageProps.csrf_token;
    }
});

createInertiaApp({
    resolve: async (name) => {
        const pages = import.meta.glob('./pages/**/*.tsx', { eager: true });
        const page = pages[`./pages/${name}.tsx`];
        return page.default;
    },
    setup({ el, App, props }) {
        const root = createRoot(el);
        root.render(<App {...props} />);
    },
    progress: {
        color: '#4B5563',
    },
});
```

Key parts:

- **`import.meta.glob`** - Vite's way to dynamically import all page components
- **Page resolution** - `"Posts/Index"` maps to `./pages/Posts/Index.tsx`
- **CSRF handling** - Token is passed from Go and updated on navigation
- **Progress bar** - Shows loading indicator during page transitions

## Development Workflow

### Start Development Servers

Run both servers in separate terminals:

```bash
# Terminal 1: Go server
go run main.go

# Terminal 2: Vite dev server
npm run dev
```

Or use a process manager like `overmind` or `foreman`.

### Development vs Production

**Development:**
- Vite serves assets with hot module replacement
- Changes to React components update instantly
- Go server proxies to Vite for assets

**Production:**
```bash
# Build assets
npm run build

# Run Go server only
./your-app
```

Go serves pre-built assets from `public/build/`.

## HTML Template

The root template is a Go `html/template`. Instead of hardcoding the Vite
dev-server URLs, render asset tags with the `vite` template helper: in
development (when the Vite dev server has written the `public/hot` marker)
it emits the `@vite/client` script and the dev-server entry; in production it walks
the build manifest and emits the hashed `<link>`/`<script>` tags. The
`viteReactRefresh` helper emits the React Fast Refresh preamble in dev and
nothing in production.

```html
<!-- resources/views/app.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="csrf-token" content="{{ .csrfToken }}">

    <title>Velocity App</title>

    {{ .inertiaHead }}

    {{ viteReactRefresh }}
    {{ vite "resources/js/app.tsx" }}
</head>
<body class="font-sans antialiased">
    {{ .inertia }}
</body>
</html>
```

The template variables come from the renderer:

- **`{{ .inertia }}`** - Inertia page data container for React hydration
- **`{{ .inertiaHead }}`** - Inertia head content (title, meta from React; populated during SSR)
- **`{{ .csrfToken }}`** - CSRF token published per request via middleware (see Template Data below)

The `vite` and `viteReactRefresh` helpers are registered on the engine
through `view.Config.Funcs` (see below).

## Registering the Vite Helpers

The `vite` and `viteReactRefresh` template helpers are not built in. Wire
them onto the view engine by passing a `template.FuncMap` in `view.Config.Funcs`:

```go
import (
    "html/template"

    "github.com/velocitykode/velocity/bond/vite"
    "github.com/velocitykode/velocity/view"
)

helper := vite.New() // defaults: public/, build/, hot file "hot"

engine, err := view.NewEngine(view.Config{
    Funcs: template.FuncMap{
        "vite":             helper.Tags,
        "viteReactRefresh": helper.ReactRefreshTag,
    },
})
```

`vite.New` accepts options to override the defaults:

- `vite.WithPublicPath("public")` - directory containing built assets and the hot file
- `vite.WithBuildDirectory("build")` - subdirectory of public/ where Vite writes output
- `vite.WithHotFile("hot")` - dev-server marker file (its contents are the dev origin)
- `vite.WithManifestFilename("manifest.json")` - manifest filename
- `vite.WithManifestSubdir("")` - manifest subdirectory under the build directory

## Template Data and Functions

Static template helpers are registered once when the engine is built, via
`view.Config.Funcs` (shown above for the Vite helpers). To add your own:

```go
import "html/template"

engine, err := view.NewEngine(view.Config{
    Funcs: template.FuncMap{
        "vite": helper.Tags,
        "formatDate": func(date time.Time) string {
            return date.Format("January 2, 2006")
        },
    },
})
```

Per-request root-template variables (CSP nonce, CSRF token, etc.) are
published onto the request context with `bond.WithTemplateData`, then read by
name in the template (e.g. `{{ .csrfToken }}`):

```go
import "github.com/velocitykode/velocity/bond"

ctx := bond.WithTemplateData(r.Context(), "csrfToken", token)
r = r.WithContext(ctx)
```

To share data with React components (not the root template), use the engine's
shared-props API. These become Inertia props on every page:

```go
// Static shared prop on every response
engine.Share("app_name", "My Velocity App")

// Multiple static props at once
engine.ShareMultiple(view.Props{"version": "1.0.0", "env": "production"})

// Dynamic prop evaluated per request
engine.ShareFunc("user", func(r *http.Request) (any, error) {
    return currentUser(r), nil
})
```


================================================================================
# Inertia.js

Source: https://vel.build/docs/frontend/inertia/
Section: Frontend & Views
Summary: Connect Go handlers to React components with Inertia.js for SPA navigation without building an API.


Inertia.js bridges Go handlers and React components, enabling SPA-like navigation without building an API.

## Quick Start

```go
// Handler
import (
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/view"
)

func (c *UserHandler) Index(ctx *router.Context) error {
    users, _ := models.User{}.All()

    return view.Render(ctx, "Users/Index", view.Props{
        "users": users,
        "title": "All Users",
    })
}
```

```typescript
// resources/js/pages/Users/Index.tsx
import { Link } from '@inertiajs/react'

interface Props {
  users: User[]
  title: string
}

export default function UsersIndex({ users, title }: Props) {
  return (
    <div>
      <h1>{title}</h1>
      {users.map(user => (
        <Link key={user.id} href={`/users/${user.id}`}>
          {user.name}
        </Link>
      ))}
    </div>
  )
}
```

## Configuration

The application bootstrap creates a `*view.Engine` for you and stores it on the
service container as `Services.View` whenever `Config.View.RootTemplate` is set.
You do not construct the engine yourself in normal apps: the package-level
helpers (`view.Render`, `view.Redirect`, `view.For`) resolve the engine from the
request context.

### View Config

`view.Config` controls the root HTML template, asset version, and server-side
rendering:

```go
type Config struct {
    RootTemplate string           // HTML shell containing {{ .inertia }} and {{ .inertiaHead }}
    Version      string           // Asset version for cache busting (defaults to "1")

    SSREnabled   bool             // Pre-render via a Node SSR server, falling back to CSR
    SSRURL       string           // Defaults to http://127.0.0.1:13714
    SSRTimeout   time.Duration    // Defaults to 3s; must be > 0 when SSREnabled
    SSRExcept    []string         // URL prefixes to exclude from SSR

    Funcs        template.FuncMap // Template helpers callable from RootTemplate (e.g. vite)
}
```

The SSR fields are populated from environment variables by the default config
loader: `VIEW_SSR_ENABLED`, `VIEW_SSR_URL`, `VIEW_SSR_TIMEOUT`, and a
comma-separated `VIEW_SSR_EXCEPT`.

### Constructing an engine manually

When you need an engine outside the standard bootstrap (for example in tests),
use `view.NewEngine`:

```go
import "github.com/velocitykode/velocity/view"

engine, err := view.NewEngine(view.Config{
    RootTemplate: `<!DOCTYPE html><html><head>{{ .inertiaHead }}</head><body>{{ .inertia }}</body></html>`,
    Version:      "1",
})
if err != nil {
    // handle error
}
```

`NewEngine` fills in defaults: an empty `RootTemplate` uses a built-in shell and
an empty `Version` becomes `"1"`.

### Wiring Vite assets

Register the [Vite](https://vitejs.dev) helper as a template function so your
root template can emit the right script and stylesheet tags in both dev and
production:

```go
import (
    "html/template"

    "github.com/velocitykode/velocity/bond/vite"
    "github.com/velocitykode/velocity/view"
)

helper := vite.New()
cfg := view.Config{
    RootTemplate: rootTemplate,
    Version:      "1",
    Funcs:        template.FuncMap{"vite": helper.Tags},
}
```

Then the root template calls `{{ vite "resources/js/app.tsx" }}`.

## Rendering Pages

### Basic Rendering

```go
import (
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/view"
)

func (c *PostHandler) Index(ctx *router.Context) error {
    posts, _ := models.Post{}.With("User").Get()

    return view.Render(ctx, "Posts/Index", view.Props{
        "posts": posts,
        "meta": map[string]interface{}{
            "title": "All Posts",
            "description": "Browse all posts",
        },
    })
}

func (c *PostHandler) Show(ctx *router.Context) error {
    id := ctx.Param("id")
    post, err := models.Post{}.With("User", "Comments").Find(id)

    if err != nil {
        return view.Render(ctx, "Errors/NotFound", view.Props{
            "message": "Post not found",
        })
    }

    return view.Render(ctx, "Posts/Show", view.Props{
        "post": post,
    })
}
```

`view.Render` returns an error when no view engine is configured on the
context, so return it directly from the handler.

### Lazy and Deferred Props

Wrap prop values to control when they are evaluated and sent to the client:

```go
return view.Render(ctx, "Dashboard", view.Props{
    // Always included, even on partial reloads.
    "user": view.Always(currentUser),

    // Evaluated only when a partial reload explicitly requests the key.
    "stats": view.Optional(func() (any, error) {
        return computeExpensiveStats()
    }),

    // Loaded after the initial paint; the client fetches it in a
    // follow-up request. An optional group name batches deferred props.
    "activity": view.Defer(func() (any, error) {
        return loadRecentActivity()
    }, "secondary"),
})
```

`view.Lazy` is deprecated in favor of `view.Optional`.

## Shared Data

Shared props are registered once on the engine at boot, not per request. Resolve
the engine from the context with `view.FromContext` (or hold a reference from
`view.NewEngine`) and register static or dynamic shared props:

```go
func RegisterSharedProps(engine *view.Engine) {
    // Static value shared on every render.
    engine.Share("app", map[string]interface{}{
        "name":    "My Velocity App",
        "version": "1.0.0",
    })

    // Several static values at once.
    engine.ShareMultiple(view.Props{
        "locale": "en",
        "theme":  "light",
    })

    // Dynamic value evaluated per request.
    engine.ShareFunc("path", func(r *http.Request) (interface{}, error) {
        return r.URL.Path, nil
    })
}
```

To compute several request-scoped props in one place, register a
`SharePropsFunc`:

```go
engine.SetSharePropsFunc(func(r *http.Request) (view.Props, error) {
    return view.Props{
        "csrf_token": getCSRFToken(r),
        "flash":      getFlashMessages(r),
    }, nil
})
```

## Navigation and Redirects

Three package-level helpers take the `*router.Context`:

- `view.Redirect(ctx, url)` performs an SPA redirect (303) for internal navigation.
- `view.Location(ctx, url)` forces a full-page reload (409 + `X-Inertia-Location` for Inertia requests, 302 otherwise).
- `view.Back(ctx)` redirects to the `Referer` (or `/` when absent).

```go
func (c *PostHandler) Store(ctx *router.Context) error {
    post := createPost(ctx.Request)

    // SPA redirect to the show page
    view.Redirect(ctx, fmt.Sprintf("/posts/%d", post.ID))

    return nil
}

func (c *PostHandler) Update(ctx *router.Context) error {
    if hasErrors {
        // Go back to the previous page
        view.Back(ctx)
        return nil
    }

    // Redirect on success
    view.Redirect(ctx, "/posts")

    return nil
}
```

### Flash and chained redirects

`view.For(ctx)` returns a request-bound handle that chains flash messages with a
terminal redirect or render. Flash entries are persisted on the session cookie
before the redirect fires, so the destination page can read them:

```go
func (c *PostHandler) Update(ctx *router.Context) error {
    if hasErrors {
        return ctx.JSON(422, errors)
    }

    view.For(ctx).
        Flash("success", "Post updated").
        Redirect("/posts")

    return nil
}
```

`For` is nil-safe: when no view engine is wired it returns `nil` and every chain
method (`Flash`, `FlashMany`, `Redirect`, `Location`, `Back`, `Render`) is a
no-op. Flashing also no-ops when the active guard does not back sessions (for
example JWT-only deployments).

## Middleware Integration

The engine exposes its protocol middleware as a `router.MiddlewareFunc` via
`engine.Middleware()`. It handles the Inertia handshake (version checks,
partial-reload negotiation). Register it on the router before your view routes:

```go
import (
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/view"
)

func SetupRoutes(engine *view.Engine) router.Router {
    r := router.New()

    // Apply Inertia middleware
    r.Use(engine.Middleware())

    // Routes
    r.Get("/", homeHandler.Index)
    r.Get("/posts", postHandler.Index)
    r.Get("/posts/{id}", postHandler.Show)

    return r
}
```

## Testing Views

Because `view.Render` resolves the engine from the context, wire an engine onto
a test context with `ctx.SetServices`. Use `router.NewTestContext` to build the
context and recorder:

```go
import (
    "github.com/velocitykode/velocity/app"
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/view"
)

func TestPostHandler_Index(t *testing.T) {
    engine, err := view.NewEngine(view.Config{
        RootTemplate: `<html><body>{{ .inertia }}</body></html>`,
        Version:      "1",
    })
    assert.NoError(t, err)

    handler := &PostHandler{}

    // A plain GET returns the full HTML document.
    ctx, w := router.NewTestContext("GET", "/posts")
    ctx.SetServices(&app.Services{View: engine})

    assert.NoError(t, handler.Index(ctx))
    assert.Equal(t, http.StatusOK, w.Code)
    assert.Contains(t, w.Header().Get("Content-Type"), "text/html")

    // An X-Inertia request returns the JSON page payload.
    ctx, w = router.NewTestContext("GET", "/posts")
    ctx.Request.Header.Set("X-Inertia", "true")
    ctx.SetServices(&app.Services{View: engine})

    assert.NoError(t, handler.Index(ctx))
    assert.Equal(t, http.StatusOK, w.Code)
    assert.Contains(t, w.Header().Get("Content-Type"), "application/json")
}
```


================================================================================
# View Engine

Source: https://vel.build/docs/frontend/view/
Section: Frontend & Views
Summary: Server-side view engine for Inertia-style rendering with shared props, lazy/deferred props, and optional SSR.


The `view` package is Velocity's server-side rendering layer. It wraps
the `bond` Inertia primitive with an ergonomic API: render components,
share per-request props, mix lazy and deferred loading, and (optionally)
pre-render through a Node SSR process.

Import path: `github.com/velocitykode/velocity/view`

For the frontend side - setting up the client, writing pages, handling
forms - see [Inertia](/docs/frontend/inertia).

## Engine

```go
engine, err := view.NewEngine(view.Config{
    RootTemplate: rootHTML,   // string: the HTML shell with <div id="app">
    Version:      "1.0.3",    // asset version for Inertia cache busting
    SSREnabled:   false,      // flip to true to enable SSR
    SSRURL:       "http://127.0.0.1:13714",  // defaults to this when blank
    SSRTimeout:   3 * time.Second,           // defaults to 3s; must be > 0 when SSR is on
    SSRExcept:    []string{"/admin"},        // URL prefixes to skip SSR on
})
```

`RootTemplate` and `Version` are optional: when blank, `NewEngine` fills
in a built-in default shell and a `Version` of `"1"`. The root template
content is a plain string - load it however you like (an embedded
`//go:embed` file, `os.ReadFile`, etc.) and pass the result.

`Config.Funcs` registers `template.FuncMap` helpers callable from the
root template. The canonical use is the Vite tag helper:

```go
helper := vite.New()
engine, _ := view.NewEngine(view.Config{
    RootTemplate: root,
    Funcs:        template.FuncMap{"vite": helper.Tags},
})
// app.go.html can then call {{ vite "resources/js/app.tsx" }}
```

Assign it so other services (handlers, CSRF middleware) can reach it:

```go
v.View = engine
```

## Rendering

From a handler:

```go
func (h *DashboardHandler) Show(ctx *router.Context) error {
    return view.Render(ctx, "Dashboard/Index", view.Props{
        "metrics": loadMetrics(),
        "user":    currentUser(ctx),
    })
}
```

`view.Render` pulls the engine from the router context (set by the view
middleware) and forwards to `engine.Render`.

Directly:

```go
engine.Render(w, r, "Dashboard/Index", view.Props{"metrics": m})
```

## Shared props

Shared props are attached to every response. Use them for things every
page needs: the authenticated user, feature flags, the CSRF token.

Static value:

```go
engine.Share("appName", "Acme")
```

Evaluated per request:

```go
engine.ShareFunc("user", func(r *http.Request) (any, error) {
    return currentUserFromRequest(r), nil
})
```

Several static props at once:

```go
engine.ShareMultiple(view.Props{
    "appName": "Acme",
    "locale":  "en",
})
```

Bulk replace via a single per-request function:

```go
engine.SetSharePropsFunc(func(r *http.Request) (view.Props, error) {
    return view.Props{
        "user":     currentUserFromRequest(r),
        "features": featureFlagsFor(r),
    }, nil
})
```

`SetSharePropsFunc` replaces the default - use `ShareFunc` for individual
additions.

## Conditional prop types

The `view` package re-exports four prop wrappers from `bond`. Each
changes when/if a prop is evaluated or sent.

### Always - evaluated, always included

```go
view.Props{"theme": view.Always("dark")}
```

### Lazy - evaluated only when the component needs it

```go
view.Props{"heavyReport": view.Lazy(func() (any, error) {
    return computeHeavyReport(), nil
})}
```

Skipped on partial reloads unless explicitly requested.


`view.Lazy` (and the `view.LazyProp` type) is deprecated - use
`view.Optional` instead. The two behave the same way; the name change
follows the broader Inertia ecosystem's own sunset of `lazy`.


### Optional - evaluated, but only sent on explicit partial request

```go
view.Props{"audit": view.Optional(func() (any, error) {
    return loadAuditTrail(), nil
})}
```

Useful for secondary tabs - don't hit the DB unless the user opens
that section.

### Deferred - sent after initial render

```go
view.Props{"recommendations": view.Defer(func() (any, error) {
    return ml.Recommend(user), nil
}, "widgets")}
```

Second argument is the group name. The client receives initial HTML
first, then requests deferred groups in parallel. Good for slow
computations you don't want to block first paint.

## Redirect helpers

On the engine directly:

```go
engine.Redirect(w, r, "/dashboard")             // Inertia-aware redirect
engine.Location(w, r, "https://acme.com/docs")  // external redirect
engine.Back(w, r)                               // redirect to the Referer (or "/")
```

From a handler, the package-level helpers pull the engine off the router
context for you and are nil-safe (no-op when no engine is wired):

```go
view.Redirect(ctx, "/dashboard")
view.Location(ctx, "https://acme.com/docs")
view.Back(ctx)
```

### Flash and chained terminals

`view.For(ctx)` returns a request-bound handle for chaining flash data
into a redirect or render. The flash bag is persisted onto the encrypted
session cookie when a terminal method (`Redirect` / `Location` / `Back` /
`Render`) runs, so the next page can drain it onto its props:

```go
view.For(ctx).Flash("error", "Save failed").Redirect("/posts")

view.For(ctx).
    FlashMany(map[string]any{"status": "saved", "id": id}).
    Render("Posts/Index", view.Props{"posts": posts})
```

`For` returns `nil` when no view engine is wired, and every chain method
is a no-op on a nil receiver, so the calls are always safe. Flash silently
no-ops when there is no auth manager on the context or the active guard is
not session-backed (for example a JWT-only deployment).

## Middleware

`engine.Middleware()` returns a `router.MiddlewareFunc` that installs
the engine on the request context so `view.Render(ctx, ...)` works from
any handler.

## SSR

When `SSREnabled` is true:

1. On every full-page response, the engine POSTs the Inertia payload
   to the SSR URL.
2. The Node process renders the page and returns the HTML fragment.
3. The fragment replaces `<div id="app">` content in the root template.
4. If anything fails - timeout, non-200, parse error - the engine
   falls back to client-side rendering. The request always succeeds.

Emit an SSR failure event to monitor fallbacks:

```go
engine.SetEventDispatcher(func(ctx context.Context, event any) error {
    return v.Events.Dispatch(ctx, event)
})
```

Listen for `bond.SSRRenderFailed` to count, alert, or log. The event
carries the failing `Component`, `URL`, `Error` message, and a typed
`Type` (`bond.SSRErrorConnection`, `SSRErrorRender`,
`SSRErrorComponentResolution`, `SSRErrorBrowserAPI`, or
`SSRErrorUnknown`), plus optional `Hint`, `BrowserAPI`, `Stack`, and
`SourceLocation` fields.

## Escape hatch

`engine.Bond()` returns the underlying `*bond.Bond` instance for the rare
case you need a protocol primitive the view API does not re-export. Reach
for it sparingly - application code should stay on the `view` surface so
the rendering adapter can evolve without breaking you.

`engine.Shutdown(ctx)` is a no-op: the engine holds no long-lived
resources, but it satisfies the framework's shutdown contract so the
engine can be registered as a managed service.


================================================================================
# React Components

Source: https://vel.build/docs/frontend/components/
Section: Frontend & Views
Summary: Build type-safe React components that receive props directly from Velocity Go handlers.


Build type-safe React components that receive props directly from Go handlers.

## Page Components

Page components live in `resources/js/pages/` and map directly to Inertia render calls:

```typescript
// resources/js/pages/Posts/Index.tsx
import { Link, Head } from '@inertiajs/react'
import Layout from '@/layouts/Layout'

interface Post {
  id: number
  title: string
  body: string
  user: User
  created_at: string
}

interface Props {
  posts: Post[]
  meta: {
    title: string
    description: string
  }
}

export default function PostsIndex({ posts, meta }: Props) {
  return (
    <Layout>
      <Head title={meta.title} />

      <div className="container mx-auto px-4">
        <div className="flex justify-between items-center mb-6">
          <h1 className="text-3xl font-bold">{meta.title}</h1>
          <Link
            href="/posts/create"
            className="bg-blue-500 text-white px-4 py-2 rounded"
          >
            Create Post
          </Link>
        </div>

        <div className="grid gap-6">
          {posts.map(post => (
            <div key={post.id} className="border rounded-lg p-6">
              <h2 className="text-xl font-semibold mb-2">
                <Link href={`/posts/${post.id}`} className="hover:text-blue-600">
                  {post.title}
                </Link>
              </h2>
              <p className="text-gray-600 mb-4">{post.body.substring(0, 150)}...</p>
              <div className="text-sm text-gray-500">
                By {post.user.name} on {new Date(post.created_at).toLocaleDateString()}
              </div>
            </div>
          ))}
        </div>
      </div>
    </Layout>
  )
}
```

## Layout Components

Layouts wrap page content and access shared props:

```typescript
// resources/js/layouts/Layout.tsx
import { Link, usePage } from '@inertiajs/react'
import { PropsWithChildren } from 'react'

interface SharedProps {
  auth?: {
    user: User
  }
  flash?: {
    success?: string
    error?: string
  }
}

export default function Layout({ children }: PropsWithChildren) {
  const { auth, flash } = usePage<SharedProps>().props

  return (
    <div className="min-h-screen bg-gray-50">
      <nav className="bg-white shadow">
        <div className="container mx-auto px-4">
          <div className="flex justify-between items-center h-16">
            <Link href="/" className="text-xl font-bold">
              My App
            </Link>

            <div className="flex space-x-4">
              <Link href="/posts" className="hover:text-blue-600">
                Posts
              </Link>

              {auth?.user ? (
                <div className="flex items-center space-x-4">
                  <span>Hello, {auth.user.name}</span>
                  <Link href="/logout" method="post" className="text-red-600">
                    Logout
                  </Link>
                </div>
              ) : (
                <div className="flex space-x-4">
                  <Link href="/login">Login</Link>
                  <Link href="/register">Register</Link>
                </div>
              )}
            </div>
          </div>
        </div>
      </nav>

      {flash?.success && (
        <div className="bg-green-100 border border-green-400 text-green-700 px-4 py-3">
          {flash.success}
        </div>
      )}

      {flash?.error && (
        <div className="bg-red-100 border border-red-400 text-red-700 px-4 py-3">
          {flash.error}
        </div>
      )}

      <main className="py-8">
        {children}
      </main>
    </div>
  )
}
```

## Navigation

Use Inertia's `Link` component for SPA navigation:

```typescript
import { Link } from '@inertiajs/react'

// Basic link
<Link href="/posts">Posts</Link>

// With method (for logout, delete, etc.)
<Link href="/logout" method="post">Logout</Link>

// Preserve scroll position
<Link href="/posts" preserveScroll>Posts</Link>

// Replace history (no back button)
<Link href="/posts" replace>Posts</Link>

// Only reload specific props
<Link href="/posts" only={['posts']}>Refresh Posts</Link>
```

## Head Component

Manage document head from any component:

```typescript
import { Head } from '@inertiajs/react'

export default function PostShow({ post }: Props) {
  return (
    <>
      <Head>
        <title>{post.title}</title>
        <meta name="description" content={post.excerpt} />
        <meta property="og:title" content={post.title} />
      </Head>

      <article>
        <h1>{post.title}</h1>
        <div>{post.body}</div>
      </article>
    </>
  )
}
```

## Accessing Shared Props

Use `usePage` hook to access shared data:

```typescript
import { usePage } from '@inertiajs/react'

interface SharedProps {
  auth: { user: User }
  csrf_token: string
  flash: { success?: string; error?: string }
}

export default function SomeComponent() {
  const { auth, csrf_token, flash } = usePage<SharedProps>().props

  return (
    <div>
      {auth.user && <p>Welcome, {auth.user.name}</p>}
      {flash.success && <Alert>{flash.success}</Alert>}
    </div>
  )
}
```

## Component Organization

Recommended structure:

```
resources/js/
├── app.tsx             # React/Inertia entry point
├── pages/              # Page components (route-mapped)
│   ├── Auth/
│   │   ├── Login.tsx
│   │   └── Register.tsx
│   ├── Posts/
│   │   ├── Index.tsx
│   │   ├── Show.tsx
│   │   └── Create.tsx
│   └── Dashboard.tsx
├── components/         # Reusable UI components
│   ├── ui/
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   └── Card.tsx
│   └── AppHeader.tsx
├── layouts/           # Layout wrappers
│   ├── Layout.tsx
│   ├── AuthLayout.tsx
│   └── GuestLayout.tsx
├── hooks/             # Custom React hooks
│   ├── use-appearance.ts
│   └── use-mobile.ts
└── types/             # TypeScript interfaces
    └── index.d.ts
```

## Best Practices

1. **Props Typing** - Always define TypeScript interfaces for props
2. **Component Organization** - Keep page components in `pages/` directory
3. **Shared Data** - Use `usePage()` to access globally shared data
4. **Navigation** - Use `<Link>` over anchor tags for SPA navigation
5. **SEO** - Use `<Head>` component for page metadata
6. **Layouts** - Create reusable layouts for consistent page structure


================================================================================
# Forms

Source: https://vel.build/docs/frontend/forms/
Section: Frontend & Views
Summary: Handle form submissions with Inertia's useForm hook for validation, error handling, and submission states.


Inertia's `useForm` hook provides form state management with validation error handling and submission states.

## Basic Form

```typescript
// resources/js/pages/Posts/Create.tsx
import { useForm, Head, Link } from '@inertiajs/react'
import Layout from '@/layouts/Layout'

export default function CreatePost() {
  const { data, setData, post, errors, processing } = useForm({
    title: '',
    body: '',
  })

  function submit(e: React.FormEvent) {
    e.preventDefault()
    post('/posts')
  }

  return (
    <Layout>
      <Head title="Create Post" />

      <div className="container mx-auto px-4 max-w-2xl">
        <h1 className="text-3xl font-bold mb-6">Create New Post</h1>

        <form onSubmit={submit} className="space-y-6">
          <div>
            <label htmlFor="title" className="block text-sm font-medium mb-2">
              Title
            </label>
            <input
              id="title"
              type="text"
              value={data.title}
              onChange={e => setData('title', e.target.value)}
              className={`w-full px-3 py-2 border rounded-md ${
                errors.title ? 'border-red-500' : 'border-gray-300'
              }`}
            />
            {errors.title && (
              <div className="text-red-500 text-sm mt-1">{errors.title}</div>
            )}
          </div>

          <div>
            <label htmlFor="body" className="block text-sm font-medium mb-2">
              Content
            </label>
            <textarea
              id="body"
              value={data.body}
              onChange={e => setData('body', e.target.value)}
              rows={10}
              className={`w-full px-3 py-2 border rounded-md ${
                errors.body ? 'border-red-500' : 'border-gray-300'
              }`}
            />
            {errors.body && (
              <div className="text-red-500 text-sm mt-1">{errors.body}</div>
            )}
          </div>

          <div className="flex justify-between">
            <Link
              href="/posts"
              className="px-4 py-2 text-gray-600 hover:text-gray-800"
            >
              Cancel
            </Link>
            <button
              type="submit"
              disabled={processing}
              className="bg-blue-500 text-white px-6 py-2 rounded-md hover:bg-blue-600 disabled:opacity-50"
            >
              {processing ? 'Creating...' : 'Create Post'}
            </button>
          </div>
        </form>
      </div>
    </Layout>
  )
}
```

## useForm API

```typescript
const {
  data,        // Current form data
  setData,     // Update form field
  post,        // Submit via POST
  put,         // Submit via PUT
  patch,       // Submit via PATCH
  delete: del, // Submit via DELETE
  errors,      // Validation errors from server
  processing,  // True during submission
  progress,    // Upload progress (for files)
  reset,       // Reset form to initial values
  clearErrors, // Clear validation errors
  transform,   // Transform data before submission
} = useForm({
  title: '',
  body: '',
})
```

## Updating Fields

```typescript
// Single field
setData('title', 'New Title')

// Multiple fields
setData({
  title: 'New Title',
  body: 'New Body',
})

// Callback form (for derived values)
setData(data => ({
  ...data,
  slug: data.title.toLowerCase().replace(/\s+/g, '-'),
}))
```

## Form Methods

```typescript
// Create
post('/posts')

// Update
put(`/posts/${post.id}`)
patch(`/posts/${post.id}`)

// Delete
del(`/posts/${post.id}`)

// With options
post('/posts', {
  preserveScroll: true,
  preserveState: true,
  onSuccess: () => {
    reset()
  },
  onError: (errors) => {
    console.log('Validation errors:', errors)
  },
})
```

## File Uploads

```typescript
import { useForm } from '@inertiajs/react'

export default function FileUpload() {
  const { data, setData, post, progress } = useForm({
    avatar: null as File | null,
  })

  function submit(e: React.FormEvent) {
    e.preventDefault()
    post('/profile/avatar', {
      forceFormData: true,
    })
  }

  return (
    <form onSubmit={submit}>
      <input
        type="file"
        onChange={e => setData('avatar', e.target.files?.[0] || null)}
        accept="image/*"
      />

      {progress && (
        <div className="w-full bg-gray-200 rounded-full h-2.5">
          <div
            className="bg-blue-600 h-2.5 rounded-full"
            style={{ width: `${progress.percentage}%` }}
          />
        </div>
      )}

      <button type="submit">Upload</button>
    </form>
  )
}
```

## Transform Data

Modify data before submission:

```typescript
const { data, setData, post, transform } = useForm({
  name: '',
  remember: false,
})

function submit(e: React.FormEvent) {
  e.preventDefault()

  transform(data => ({
    ...data,
    remember: data.remember ? 'on' : '',
  }))

  post('/login')
}
```

## Resetting Forms

```typescript
const { data, setData, reset } = useForm({
  title: '',
  body: '',
})

// Reset all fields
reset()

// Reset specific fields
reset('title')
reset('title', 'body')
```

## Validation Errors

Errors come from Go validation and are keyed by field name. On the server,
validate the request, then flash the errors and old input and redirect back.
`ctx.FlashErrors` and `ctx.FlashInput` write short-lived encrypted flash
cookies; the view layer reads them on the next render and injects them as
the `errors` and `old` props:

```go
// Go handler
import (
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/validation"
    "github.com/velocitykode/velocity/view"
)

func (c *PostHandler) Store(ctx *router.Context) error {
    // CheckW threads the ResponseWriter through so an oversized body can
    // signal the connection to close. The error return is a malformed
    // rule set (a handler bug), never a field-level failure.
    result, err := validation.CheckW(ctx.Response, ctx.Request, validation.Rules{
        "title": {validation.Required(), validation.Min(3)},
        "body":  {validation.Required(), validation.Min(10)},
    })
    if err != nil {
        return err
    }

    if result.HasErrors() {
        ctx.FlashErrors(result.All())
        ctx.FlashInput(result.Old())
        view.Back(ctx)
        return nil
    }

    // Create post...
    return nil
}
```

Rules are typed constructor values collected in a `validation.Rules` set
keyed by field, not strings. `result.All()` is a `map[string]string` (one
message per field), which is the shape Inertia's `errors` prop expects.
`result.Old()` strips sensitive-looking fields (anything whose name
contains `password`, `token`, `secret`, `card`, `otp`, and similar) before
handing input back for replay, so a password never round-trips to the
client.


`validation.Unique` and `validation.Exists` execute in the
`validation/dbrules` subpackage, which owns the `orm` dependency. Use
`dbrules.CheckWithDBW(ctx.Response, ctx.Request, rules, db)` when your rule
set names them, or let `ctx.Validate` / `ctx.BindValid` / `vform.Form` do
it, since those resolve the database from the request's service container
for you.


### vform.Form

For the common case, `vform.Form[T]` binds the request body into a typed
struct, validates it, and on failure flashes errors plus old input, redirects
back, and returns `router.ErrValidationAborted` so the handler can return
early without the router emitting an error response:

```go
import (
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/validation"
    "github.com/velocitykode/velocity/validation/vform"
)

type StorePost struct {
    Title string `json:"title"`
    Body  string `json:"body"`
}

func (p *StorePost) Rules() validation.Rules {
    return validation.Rules{
        "title": {validation.Required(), validation.Min(3)},
        "body":  {validation.Required(), validation.Min(10)},
    }
}

func (c *PostHandler) Store(ctx *router.Context) error {
    post, err := vform.Form[StorePost](ctx)
    if err != nil {
        return err // ErrValidationAborted is handled by the router
    }

    // Create post using post.Title / post.Body...
    return nil
}
```

`vform.FormRequest` is an alias for `router.Validatable`, so the same
`StorePost` also works with `ctx.BindValid(&input)` when a handler needs
validation without the flash-and-redirect-back flow (a JSON endpoint, for
instance). One declaration, both entry points.

```typescript
// React component
{errors.title && (
  <span className="text-red-500">{errors.title}</span>
)}
```

## Form Callbacks

```typescript
post('/posts', {
  onBefore: () => {
    // Called before request
    return confirm('Are you sure?')
  },
  onStart: () => {
    // Request started
  },
  onProgress: (progress) => {
    // Upload progress update
  },
  onSuccess: (page) => {
    // Request succeeded
    reset()
  },
  onError: (errors) => {
    // Validation errors
  },
  onCancel: () => {
    // Request was cancelled
  },
  onFinish: () => {
    // Always called (success or error)
  },
})
```

## Preserving State

```typescript
// Keep scroll position after submission
post('/posts', { preserveScroll: true })

// Keep form state on error (default for errors)
post('/posts', { preserveState: true })

// Replace history entry (no back button to form)
post('/posts', { replace: true })
```

## Best Practices

1. **Disable Buttons** - Use `processing` to disable submit during submission
2. **Show Progress** - Display upload progress for file forms
3. **Clear on Success** - Reset form after successful submission
4. **Preserve Scroll** - Use `preserveScroll` for inline forms
5. **Transform Data** - Use `transform` for data modifications before submit
6. **Type Props** - Define TypeScript interfaces for form data


================================================================================
# Getting Started

Source: https://vel.build/docs/database/getting-started/
Section: Database & Models
Summary: Connect to PostgreSQL, MySQL, or SQLite and define models with Velocity's hand-rolled, ctx-first ORM.


Velocity ships its own ORM: a hand-rolled, generics-aware query builder with composable model traits, a ctx-first read/write API, and a pluggable driver registry. It is **not** built on GORM and shares no struct-tag namespace with it.

## Requirements

- **Go 1.26.3 or newer.** The framework's `go.mod` pins `go 1.26.3`. The ORM uses `weak.Pointer` (Go 1.24+) for its per-instance state side-channel; older toolchains will not compile.
- A driver registered with `orm.Drivers()`. The pure-Go SQLite default (`sqlite`, `sqlite3`) self-registers from `orm`'s own `init()` on import, so a zero-config app has a working database. Postgres and MySQL live in the heavy leaf packages `orm/postgres` and `orm/mysql` (and the cgo SQLite backend in `orm/sqlite`); blank-import the leaf you need, or `orm/standard` for the full set.

## Quick Start

The standard bootstrap is `velocity.New(...)`: it reads `DB_*` env, builds an `*orm.Manager`, and installs it as the package default via `orm.SetDefault`. From there, every read and write terminal takes a `context.Context` as its first argument so transactions, cancellation, and request scope flow through naturally.

```go
package main

import (
    "context"
    "log"

    "github.com/velocitykode/velocity"
    "github.com/velocitykode/velocity/orm"
)

func main() {
    app, err := velocity.New()
    if err != nil {
        log.Fatal(err)
    }

    // app.DB is a contract.Database backed by *orm.Manager;
    // orm.SetDefault has already been called, so pass nil to Save/queries.
    _ = app
    ctx := context.Background()

    user := &User{Name: "Ada", Email: "ada@example.com"}
    if err := orm.Save(ctx, nil, user); err != nil {
        log.Fatal(err)
    }

    found, err := orm.Model[User]{}.Find(ctx, user.ID)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("loaded %s", found.Name)
}
```

`orm.Save(ctx, m, &model)` is the only persistence entry point. There is no `model.Save()` instance method; calling the package function makes the manager (or transaction binding via `ctx`) explicit at every call site. Pass `nil` for `m` to use the package default set by `velocity.New`.

## Configuration

Configure the connection in `.env`:

```env
DB_CONNECTION=postgres
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=velocity_app
DB_USERNAME=postgres
DB_PASSWORD=secret

# Optional pool tuning
DB_MAX_IDLE_CONNS=10
DB_MAX_OPEN_CONNS=100
DB_CONN_MAX_LIFETIME=3600
DB_LOG_QUERIES=true
DB_SLOW_QUERY_THRESHOLD=200ms
```

To bypass `velocity.New` and build a manager directly:

```go
m, err := orm.NewManagerWithContext(ctx, orm.ManagerConfig{
    Driver:   "sqlite",
    Database: ":memory:",
})
if err != nil { /* ... */ }
orm.SetDefault(m)
```

## Supported Drivers

| Driver | Registered name | Notes |
|--------|-----------------|-------|
| PostgreSQL | `postgres` | JSONB, arrays, `RETURNING`-aware insert path. Blank-import `orm/postgres` (or `orm/standard`) to register. |
| MySQL | `mysql` | TLS via the `TLS` config knob (`DB_MYSQL_TLS`). Blank-import `orm/mysql` (or `orm/standard`). |
| SQLite | `sqlite`, `sqlite3` | Pure-Go default, self-registered from `orm`. In-memory mode for tests (`:memory:`). |

The light SQLite default is always available; the heavier backends register from their leaf packages' `init()`:

```go
import (
    _ "github.com/velocitykode/velocity/orm/postgres" // registers "postgres"
    _ "github.com/velocitykode/velocity/orm/mysql"    // registers "mysql"
    // or, for everything at once:
    _ "github.com/velocitykode/velocity/orm/standard"
)
```

Add a third-party backend by registering a factory with `orm.Drivers()`. The factory receives a `drivers.ConnectionConfig` and returns a connected `drivers.Driver`:

```go
import (
    "context"

    "github.com/velocitykode/velocity/orm"
    "github.com/velocitykode/velocity/orm/drivers"
)

func init() {
    orm.Drivers().Register("clickhouse", func(_ context.Context, cfg drivers.ConnectionConfig) (drivers.Driver, error) {
        d := newClickhouseDriver()
        if err := d.Connect(cfg); err != nil {
            return nil, err
        }
        return d, nil
    })
}
```

## Composable Model Traits

A model is a Go struct that embeds one or more **traits**. Traits are orthogonal: each adds one column or one behaviour. The framework detects them by an unexported zero-size sentinel embedded as the first field of every trait struct, so a user-declared `CreatedAt` field that does **not** come from `orm.Timestamps` is treated as a plain column with no auto-stamping.

### The six traits

| Trait | Adds | Behaviour |
|-------|------|-----------|
| `orm.IDInt[T]` | `ID uint` | Auto-increment integer primary key |
| `orm.IDUUID[T]` | `ID string` | UUID PK; v4 generated on insert when empty |
| `orm.Timestamps` | `CreatedAt`, `UpdatedAt` | Both stamped on insert; `UpdatedAt` refreshed on every save |
| `orm.CreatedAtOnly` | `CreatedAt` | Append-log shape; no `UpdatedAt` to write |
| `orm.SoftDeletes[T]` | `DeletedAt *time.Time` | Auto-installs the `deleted_at IS NULL` global scope |
| `orm.AppendOnly` | (marker) | `Save` on an existing row returns `orm.ErrImmutableModelUpdate` |

`IDInt[T]` / `IDUUID[T]` are mutually exclusive, as are `Timestamps` / `CreatedAtOnly`; the framework refuses to detect both. See "Validation" below.

### Convenience compositions

Six pre-baked combinations cover the common shapes. They are thin embeds with no special meaning to the framework: each is identical to its hand-rolled equivalent.

| Composition | Equivalent traits |
|-------------|-------------------|
| `orm.Model[T]` | `IDInt[T]` + `Timestamps` |
| `orm.UUIDModel[T]` | `IDUUID[T]` + `Timestamps` |
| `orm.SoftDeleteModel[T]` | `IDInt[T]` + `Timestamps` + `SoftDeletes[T]` |
| `orm.SoftDeleteUUIDModel[T]` | `IDUUID[T]` + `Timestamps` + `SoftDeletes[T]` |
| `orm.ImmutableModel[T]` | `IDInt[T]` + `CreatedAtOnly` + `AppendOnly` |
| `orm.ImmutableUUIDModel[T]` | `IDUUID[T]` + `CreatedAtOnly` + `AppendOnly` |

### Defining a model

```go
package models

import "github.com/velocitykode/velocity/orm"

type User struct {
    orm.Model[User] // IDInt + Timestamps; methods like Find/Where/Create return *User

    Name     string  `orm:"column:name;type:varchar(255)"`
    Email    string  `orm:"column:email;type:varchar(255)"`
    Password string  `orm:"column:password;type:varchar(255)"`
    Role     string  `orm:"column:role;type:varchar(50)"`
    Active   bool    `orm:"column:active"`

    Profile *Profile `orm:"relation:hasOne,user_id,id"`
    Posts   []Post   `orm:"relation:hasMany,user_id,id"`
}

// Optional: override the inferred table name (snake_case of the model
// name, then pluralized via str.Plural - e.g. Category -> categories).
func (User) TableName() string { return "users" }
```

### Custom shapes

When the convenience compositions don't fit, embed traits directly. Anything missing simply doesn't exist on the row.

```go
// Tombstone-able audit log: append-only content, but the row can be soft-deleted.
type AuditEntry struct {
    orm.IDUUID[AuditEntry]
    orm.CreatedAtOnly
    orm.AppendOnly
    orm.SoftDeletes[AuditEntry]

    Action string
    Actor  string
}

// No timestamp trait embedded, so this CreatedAt is a plain column with
// no auto-stamping; the column:captured_at tag renames it.
type Snapshot struct {
    orm.IDInt[Snapshot]
    orm.SoftDeletes[Snapshot]

    CreatedAt time.Time `orm:"column:captured_at"`
}
```

Embed exactly the traits the table needs. There is no "base" you must inherit from.

## Per-Instance State

Every model carrying at least one trait gets implicit existence tracking from a process-wide side-channel keyed by the model pointer (Go 1.24+ `weak.Pointer` keeps the entry alive for exactly the lifetime of the struct). `orm.Save` consults this bit to choose `INSERT` vs `UPDATE`; you don't carry a separate `IsExisting` field.

Change tracking is opt-in: call `orm.Track(&m)` once after load to capture a baseline snapshot, then inspect deltas as needed.

| Function | Purpose |
|----------|---------|
| `orm.IsExisting(&m)` | True when the row is persisted (set automatically after a successful `Save` or query load) |
| `orm.Track(&m)` | Capture a column snapshot to compare against later |
| `orm.IsDirty(&m)` | True when any tracked column has changed since the snapshot |
| `orm.IsClean(&m)` | Inverse of `IsDirty` |
| `orm.HasChanged(&m, "field")` | True when a specific field differs from the snapshot |
| `orm.MarkClean(&m)` | Re-baseline tracking against the current state |

Models that never call `Track` pay zero per-instance cost beyond the `IsExisting` bit.

## Validation

Trait detection is invariant per type and the result is cached, but mutually-exclusive combinations (`IDInt + IDUUID`, `Timestamps + CreatedAtOnly`) are rejected. Library code surfaces the failure as `*orm.FeaturesError` rather than panicking; the error fires at the request that triggered detection.

Opt in to startup-time validation so misconfigured models fail at boot instead of at first query:

```go
func main() {
    app, err := velocity.New()
    if err != nil { log.Fatal(err) }

    // Returns *orm.FeaturesError on invalid composition.
    if err := orm.RegisterModel[User](); err != nil {
        log.Fatal(err)
    }

    // Or panic-on-failure for unrecoverable misconfigurations.
    orm.MustRegisterModel[Post]()
    orm.MustRegisterModel[AuditEntry]()

    // ...
}
```

## ORM Tags

Velocity's tag namespace is `orm:"..."` with directives separated by `;`. The reflection layer recognises the following:

| Tag | Purpose | Example |
|-----|---------|---------|
| `column:<name>` | Override the snake_case-of-field default | `column:user_name` |
| `type:<sql>` | SQL type hint; `type:json` / `type:jsonb` also flags the column for JSON marshaling | `type:varchar(255)` |
| `primaryKey` | Mark a custom field as PK (rare; PK traits cover the common case) | `primaryKey` |
| `autoIncrement` | Combine with `primaryKey` for auto-increment integers | `primaryKey;autoIncrement` |
| `autoCreateTime` | Stamp on insert | `autoCreateTime` |
| `autoUpdateTime` | Refresh on every save | `autoUpdateTime` |
| `relation:<kind>,<fk>,<localKey>` | `hasOne`, `hasMany`, `belongsTo`; foreign key and local key are required | `relation:hasMany,user_id,id` |
| `manyToMany:<pivot>,<fkLocal>,<fkRelated>` | Many-to-many through a pivot table | `manyToMany:post_tags,post_id,tag_id` |
| `polymorphic:<typeCol>,<idCol>` | Polymorphic morph pair | `polymorphic:morphable_type,morphable_id` |
| `-` | Skip this field entirely | `-` |

There is no `gorm:` tag; pre-existing GORM-style annotations such as `not null`, `unique`, or `default:` are not parsed by the ORM. Express column constraints in your migration instead.

## Scopes

A scope is a chainable method on the model that builds a `*orm.Query[T]`. Define them as ordinary methods that return a query; the terminal `Get`, `First`, `Count`, etc. take `ctx` and run the SQL.

```go
func (User) Active() *orm.Query[User] {
    return orm.Model[User]{}.Where("active = ?", true)
}

func (User) Admins() *orm.Query[User] {
    return orm.Model[User]{}.WhereIn("role", []any{"admin", "super_admin"})
}

// Use:
admins, err := User{}.Admins().Get(ctx)
recent, err := User{}.Active().Where("created_at > ?", since).Get(ctx)
```

For predicates that should apply to **every** read (multi-tenancy, soft-delete, draft visibility), register a global scope with `orm.AddGlobalScope[T]`. See [Global Query Scopes](/docs/database/scopes/).

## Testing

SQLite in-memory plus a fresh manager per test gives a clean slate without touching disk. Database assertions live in the `orm/testing` package and take the manager explicitly:

```go
import (
    "github.com/velocitykode/velocity/orm"
    ormtesting "github.com/velocitykode/velocity/orm/testing"
)

func TestMain(m *testing.M) {
    mgr, err := orm.NewManagerWithContext(context.Background(), orm.ManagerConfig{
        Driver:   "sqlite",
        Database: ":memory:",
    })
    if err != nil { log.Fatal(err) }
    orm.SetDefault(mgr)

    // Run your migrations against mgr here.

    code := m.Run()
    _ = mgr.Shutdown(context.Background())
    os.Exit(code)
}

func TestUserUpdate(t *testing.T) {
    ctx := context.Background()

    user := &User{Name: "Ada", Email: "ada@example.com"}
    if err := orm.Save(ctx, nil, user); err != nil {
        t.Fatal(err)
    }

    user.Role = "admin"
    if err := orm.Save(ctx, nil, user); err != nil {
        t.Fatal(err)
    }

    ormtesting.AssertDatabaseHas(t, orm.Default(), "users", map[string]any{
        "id":   user.ID,
        "role": "admin",
    })
}
```

`ormtesting` also exposes `AssertDatabaseMissing` and `AssertDatabaseCount`, all of which take the `*orm.Manager` as the second argument.

The same `orm.Save(ctx, nil, &m)` call inserts on a fresh struct and updates an existing row; the side-channel decides which.

## Best Practices

1. **Compose traits to match the table.** Reach for `Model[T]` / `UUIDModel[T]` for ordinary CRUD, `SoftDeleteModel[T]` for recoverable rows, `ImmutableModel[T]` for append-only ledgers; drop down to direct trait composition when none fit exactly.
2. **Pass `ctx` everywhere.** Every read and write terminal takes `context.Context` as its first argument so transactions, cancellation, and request scope flow through automatically. There is no `WithContext` decorator.
3. **Validate at boot.** Call `orm.RegisterModel[T]()` (or `MustRegisterModel[T]()`) for every persisted type so misconfigured trait compositions fail immediately.
4. **Track only when you need it.** `orm.Track(&m)` captures a snapshot; otherwise per-instance cost is just the existence bit.
5. **Eager-load relations.** Use `With("posts", "profile")` to avoid N+1; see [Relationships](/docs/database/relationships/).
6. **Use migrations.** ORM tags don't express constraints, indexes, or defaults; declare those in your migration files.


================================================================================
# Query Builder

Source: https://vel.build/docs/database/queries/
Section: Database & Models
Summary: Build complex database queries with Velocity's fluent query builder for filtering, sorting, and pagination.


Velocity provides a fluent, generic query builder over `Model[T]`. Every read and write terminal takes `context.Context` as its first positional argument so cancellation, tracing, and transaction enrollment flow through naturally.

## Context-first terminals

The chain (`Where`, `OrderBy`, `Select`, `Join`, `Limit`, ...) is context-blind; only the terminal methods take `ctx`. There is no `WithContext` step and no out-of-band chain ctx, `ctx` is always a positional argument on the call that issues SQL.

```go
// Static-like helpers on the model: ctx is mandatory
user, err := orm.Model[User]{}.Find(ctx, 1)                         // (*User, error)
user, err := orm.Model[User]{}.FindBy(ctx, "email", "j@example.com")
user, err := orm.Model[User]{}.First(ctx)
user, err := orm.Model[User]{}.Last(ctx)
users, err := orm.Model[User]{}.All(ctx)
count, err := orm.Model[User]{}.Count(ctx)
exists, err := orm.Model[User]{}.Exists(ctx)

// Chain terminals: ctx on the terminal call
var u User
err := orm.Model[User]{}.Where("id = ?", id).First(ctx, &u)
err := orm.Model[User]{}.Where("id = ?", id).Find(ctx, id, &u)

users, err := orm.Model[User]{}.Where("role = ?", "admin").Get(ctx)
count, err := orm.Model[User]{}.Where("role = ?", "admin").Count(ctx)
```


Inside `mgr.Transaction(ctx, func(txCtx context.Context) error { ... })`, every read and write terminal that receives `txCtx` enrolls in that transaction automatically. The chain's driver is rebound from the pool to a tx-bound driver via the ctx value. Pass the original pre-tx `ctx` to a terminal to opt out and route through the pool.



The fluent chain methods (`Select`, `Where`, `WhereBetween`, `Join`, `GroupBy`, `Limit`, `Distinct`, `Sum`, ...) live on `*Query[T]`, not on `Model[T]`. The `Model[T]{}` value exposes a small set of **chain-opening** statics that return a fresh `*Query[T]`: `Where`, `WhereIn`, `WhereNull`, `WhereNotNull`, `OrderBy`, and `With`. Open the builder with one of those, then chain everything else off it. The examples below lead with one of these openers for that reason. `Model[T]{}` also exposes the standalone helpers `Find`, `FindBy`, `First`, `Last`, `All`, `Count`, `Exists`, `DoesntExist`, `Pluck`, `Paginate`, `Create`, `CreateMany`, `Update`, `DeleteWhere`, `Increment`, `Decrement`, `FirstOrCreate`, `UpdateOrCreate`, `FindOrFail`, `FirstOrFail`, and `Raw` directly.


## Basic Queries

```go
// Find single record
user, err := orm.Model[User]{}.Find(ctx, 1)
user, err := orm.Model[User]{}.FindBy(ctx, "email", "john@example.com")
user, err := orm.Model[User]{}.First(ctx)
user, err := orm.Model[User]{}.Last(ctx)

// Find multiple records
users, err := orm.Model[User]{}.All(ctx)
users, err := orm.Model[User]{}.Where("role = ?", "admin").Get(ctx)

// Existence
exists, err := orm.Model[User]{}.Where("email = ?", email).Exists(ctx)
gone,   err := orm.Model[User]{}.Where("email = ?", email).DoesntExist(ctx)

// Count
count, err := orm.Model[User]{}.Count(ctx)
count, err := orm.Model[User]{}.Where("role = ?", "admin").Count(ctx)
```

`Find` on `Model[T]{}` returns `(*T, error)`. The chain variant `q.Find(ctx, id, dest)` writes into the caller's `*T` so it composes with whatever predicates the chain carries.

## FirstOrFail

`First` returns `ErrRecordNotFound` when nothing matches. `FirstOrFail` (and the static `FindOrFail` / `FirstOrFail` on the model) wrap that into `orm.ErrNotFound`, which itself wraps `sql.ErrNoRows`:

```go
user, err := orm.Model[User]{}.FindOrFail(ctx, id)
user, err := orm.Model[User]{}.FirstOrFail(ctx)

// Chain variant: dest is passed to the terminal, like First.
var u User
err := orm.Model[User]{}.Where("email = ?", email).FirstOrFail(ctx, &u)
if errors.Is(err, orm.ErrNotFound) { ... }
```

## Chained Queries

```go
users, err := orm.Model[User]{}.
    Where("role = ?", "admin").
    OrWhere("super_admin = ?", true).
    OrderBy("created_at", "DESC").
    Limit(10).
    Offset(20).
    Get(ctx)
```

## Select Columns

```go
// Select specific columns (open the chain with a Where opener)
users, err := orm.Model[User]{}.
    Where("active = ?", true).
    Select("id", "name", "email").
    Get(ctx)

// Pluck single column (standalone helper on the model)
emails, err := orm.Model[User]{}.Pluck(ctx, "email")

// Pluck distinct values
roles, err := orm.Model[User]{}.
    Where("active = ?", true).
    Distinct().
    Pluck(ctx, "role")
```

`Pluck` (as a standalone helper or a chain terminal) returns `[]any` and honors any `Distinct`, `Where`, and ordering already on the chain.

## Conditions

### Where Clauses

```go
// Basic where
users, _ := orm.Model[User]{}.Where("active = ?", true).Get(ctx)

// Multiple conditions
users, _ := orm.Model[User]{}.
    Where("role = ?", "admin").
    Where("active = ?", true).
    Get(ctx)

// Or where
users, _ := orm.Model[User]{}.
    Where("role = ?", "admin").
    OrWhere("super_admin = ?", true).
    Get(ctx)

// Where in
users, _ := orm.Model[User]{}.WhereIn("role", []any{"admin", "moderator"}).Get(ctx)

// Where between (WhereBetween is a chain method; open with a Where first)
users, _ := orm.Model[User]{}.Where("active = ?", true).WhereBetween("age", 18, 65).Get(ctx)

// Where not in (chain method; open with a Where first)
users, _ := orm.Model[User]{}.Where("active = ?", true).WhereNotIn("role", []any{"banned", "suspended"}).Get(ctx)

// Where null
users, _ := orm.Model[User]{}.WhereNull("deleted_at").Get(ctx)
users, _ := orm.Model[User]{}.WhereNotNull("email_verified_at").Get(ctx)

// Three-argument convenience form: column, operator, value
users, _ := orm.Model[User]{}.Where("age", ">=", 18).Get(ctx)
```


Every `Where` predicate is a single `column operator ?` clause: bind values with `?`, never inline literals (`"age > 18"`) or compound predicates (`"a = ? AND b = ?"`). Chain `Where`/`OrWhere` for multiple conditions, use `WhereBetween`/`WhereIn` for multi-value operators, and `WhereGroup` for parenthesized sub-predicates. Anything else is rejected as a deferred error that surfaces on the next terminal call.


### Raw Projections

`Select` admits plain identifiers, the `*` wildcard, and aggregate expressions using exactly one of the five SQL-standard aggregate functions (`COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, uppercase, with an optional `AS` alias). Every other function name, window function, `CASE` expression, or dialect extension is rejected by the projection whitelist as a deferred error. For those, use `SelectRaw`, which emits a trusted expression verbatim and binds `?` placeholders from its `args`:

```go
// Aggregate projections pass the Select whitelist directly
results, _ := orm.Model[User]{}.
    Where("active = ?", true).
    Select("role", "COUNT(*) AS post_count").
    GroupBy("role").
    Get(ctx)

// SelectRaw is the escape hatch for projections Select cannot express
users, _ := orm.Model[User]{}.
    Where("active = ?", true).
    SelectRaw("id, name, ROW_NUMBER() OVER (ORDER BY created_at) AS rn").
    Get(ctx)

users, _ := orm.Model[User]{}.
    Where("active = ?", true).
    SelectRaw("CASE WHEN amount > ? THEN 'big' ELSE 'small' END AS bucket", 100).
    Get(ctx)
```

The caller owns the safety of the `SelectRaw` expression: values from user input MUST flow through the `args`, never via string interpolation into the expression. Multiple `SelectRaw` calls accumulate and are emitted after any `Select` columns.

### Dialect-specific operators (JSONB, FTS, array)

Drivers can extend the `Where` allowlist with dialect-specific operators via
an `OperatorRegistry`. PostgreSQL registers JSONB containment / key existence,
full-text search, and array overlap out of the box. The typed chain admits
them with no Raw escape hatch, so scopes, soft-delete filters, and chain
composition keep working.

```go
// JSONB containment: WHERE "metadata" @> $1::jsonb
rows, _ := orm.Model[App]{}.
    Where("metadata @> ?", `{"key":"value"}`).
    Get(ctx)

// JSONB key existence (one key): WHERE "metadata" ? $1
rows, _ := orm.Model[App]{}.
    Where("metadata ? ?", "feature").
    Get(ctx)

// JSONB any-of keys: WHERE "metadata" ?| ($1, $2, $3)
rows, _ := orm.Model[App]{}.
    Where("metadata ?| ?", []any{"a", "b", "c"}).
    Get(ctx)

// Full-text search: WHERE "search_vector" @@ to_tsquery($1)
rows, _ := orm.Model[Post]{}.
    Where("search_vector @@ ?", "velocity & framework").
    Get(ctx)

// Array overlap: WHERE "tags" && ARRAY[$1, $2]
rows, _ := orm.Model[Post]{}.
    Where("tags && ?", []any{"go", "orm"}).
    Get(ctx)
```

Built-in scalar operators (`=`, `!=`, `<`, `>`, `LIKE`, ...) keep working
without any registry. Registered operators are matched only when the
built-in allowlist misses, and `cond.Value` is validated against the spec's
`ParamShape` at parse time, so misuse surfaces as a parse error instead of a
runtime SQL syntax error.

PostgreSQL ships these operators today:

| Op | Shape | Example template |
|---|---|---|
| `@>` | JSON | `{{lhs}} @> {{rhs}}::jsonb` |
| `<@` | JSON | `{{lhs}} <@ {{rhs}}::jsonb` |
| `?`  | Scalar | `{{lhs}} ? {{rhs}}` |
| `?|` | Array | `{{lhs}} ?| {{rhs}}` |
| `?&` | Array | `{{lhs}} ?& {{rhs}}` |
| `@@` | Scalar | `{{lhs}} @@ to_tsquery({{rhs}})` |
| `&&` | Array | `{{lhs}} && {{rhs}}` |

SQLite and MySQL return `nil` from `OperatorRegistry()` today; the seam is in
place for `json1` / `fts5` and `JSON_CONTAINS` / `JSON_OVERLAPS` follow-ups.
Use Raw expressions for those dialects until the registrations land.

### Grouped Predicates

`WhereGroup` and `OrWhereGroup` wrap a sub-builder's conditions in parentheses so they bind tighter than the surrounding `AND`/`OR`. Reach for it whenever an `OR` group needs to be scoped by an outer predicate, typically a multi-column free-text search restricted to the current tenant or team.

```go
// WHERE team_id = ? AND (name LIKE ? OR email LIKE ?)
users, err := orm.Model[User]{}.
    Where("team_id = ?", teamID).
    WhereGroup(func(sub *orm.Query[User]) {
        sub.Where("name LIKE ?", "%"+q+"%").
            OrWhere("email LIKE ?", "%"+q+"%")
    }).
    Get(ctx)
```

`OrWhereGroup` is the OR-joined counterpart:

```go
// WHERE active = ? OR (role = ? OR role = ?)
users, err := orm.Model[User]{}.
    Where("active = ?", true).
    OrWhereGroup(func(sub *orm.Query[User]) {
        sub.Where("role = ?", "admin").
            OrWhere("role = ?", "owner")
    }).
    Get(ctx)
```

Empty groups (closure adds no conditions) are dropped, no stray parentheses appear in the SQL. A `nil` closure is a no-op. Errors from the sub-builder propagate to the outer query and surface on the next terminal call.

## Ordering

```go
// Single order
users, _ := orm.Model[User]{}.OrderBy("created_at", "DESC").Get(ctx)

// Multiple orders
users, _ := orm.Model[User]{}.
    OrderBy("role", "ASC").
    OrderBy("name", "ASC").
    Get(ctx)

// OrderByDesc shortcut (chain method; open with an OrderBy or Where first)
users, _ := orm.Model[User]{}.OrderBy("created_at", "DESC").Get(ctx)  // ORDER BY created_at DESC
```

`OrderBy` normalizes the direction to `ASC`/`DESC` (case-insensitive) and falls back to `ASC` for any other value. Once the chain is open, `OrderByDesc(col)` is shorthand for `OrderBy(col, "DESC")`.

## Grouping and Aggregates

```go
// Group by (open the chain with a Where opener)
results, err := orm.Model[User]{}.
    Where("active = ?", true).
    Select("role", "COUNT(*) as count").
    GroupBy("role").
    Get(ctx)

// Having
results, err := orm.Model[User]{}.
    Where("active = ?", true).
    Select("role", "COUNT(*) as count").
    GroupBy("role").
    Having("COUNT(*) > ?", 5).
    Get(ctx)

// Count is a standalone helper on the model; ctx-first
count, err := orm.Model[User]{}.Count(ctx)

// Sum/Avg/Min/Max are chain terminals on *Query[T]; lead with a Where
// (or another opener) to obtain the builder first.
sum, err := orm.Model[Order]{}.Where("status = ?", "paid").Sum(ctx, "total")
avg, err := orm.Model[Product]{}.Where("active = ?", true).Avg(ctx, "price")
max, err := orm.Model[Product]{}.Where("active = ?", true).Max(ctx, "price")
min, err := orm.Model[Product]{}.Where("active = ?", true).Min(ctx, "price")

// Single-column scalar pull from the first matching row
v, err := orm.Model[User]{}.Where("id = ?", id).Value(ctx, "email")
```

`Sum`, `Avg`, `Min`, and `Max` return `(float64, error)` and report `0` when the result set is empty. `Value` returns `orm.ErrNotFound` on no match.

## Joins

`Join`, `LeftJoin`, and `RightJoin` are chain methods, so open the builder with a `Where` (or another opener) first:

```go
// Inner join
users, _ := orm.Model[User]{}.
    Where("users.active = ?", true).
    Join("posts", "posts.user_id", "=", "users.id").
    Select("users.*", "posts.title").
    Get(ctx)

// Left join
users, _ := orm.Model[User]{}.
    Where("users.active = ?", true).
    LeftJoin("posts", "posts.user_id", "=", "users.id").
    Get(ctx)

// Multiple joins
users, _ := orm.Model[User]{}.
    Where("users.active = ?", true).
    Join("posts", "posts.user_id", "=", "users.id").
    Join("comments", "comments.post_id", "=", "posts.id").
    Distinct().
    Get(ctx)
```

Each join validates the table and the two ON identifiers, and admits only the built-in comparison operators (`=`, `!=`, `<`, `>`, `LIKE`, ...) between them.

## Pagination

```go
// Simple pagination via limit/offset (Limit/Offset are chain methods;
// open with a Where or OrderBy first)
users, err := orm.Model[User]{}.
    OrderBy("id", "ASC").
    Limit(10).
    Offset(20).
    Get(ctx)

// Paginate helper: total count + page slice in a single call.
// Paginate is a standalone helper on the model, and also a chain terminal.
result, err := orm.Model[User]{}.
    Where("active = ?", true).
    Paginate(ctx, page, perPage)

// result.Data() / result.Total() / result.PerPage() /
// result.CurrentPage() / result.LastPage()
```

`Paginate` defaults to page 1 and 15 per page when given non-positive values, and runs the count query and the data query against the same conditions so global scopes apply identically to both.

## Chunking

Process large datasets in fixed-size batches. The callback receives one page at a time; returning a non-nil error from the callback aborts the walk.

`Chunk` is a chain terminal, so open the builder first (a stable `OrderBy` is recommended so pages do not overlap or skip rows between batches):

```go
err := orm.Model[User]{}.
    OrderBy("id", "ASC").
    Chunk(ctx, 1000, func(users []User) error {
        for _, u := range users {
            // process u
        }
        return nil
    })
```

## Mass Updates and Deletes

Mass writes are chain terminals on `Query[T]`. They take `ctx` first so they enroll in `mgr.Transaction` automatically:

```go
// Mass update. Copies the input map; never mutated. Auto-stamps updated_at.
affected, err := orm.Model[User]{}.
    Where("role = ?", "guest").
    Update(ctx, map[string]any{"active": false})

// Soft delete (or hard, when the model has no DeletedAt trait)
affected, err := orm.Model[User]{}.Where("id = ?", id).Delete(ctx)

// Hard delete; bypasses the soft-delete trait
affected, err := orm.Model[User]{}.Where("id = ?", id).ForceDelete(ctx)

// Insert + return generated id. InsertGetId is a builder terminal and
// ignores any predicates on the chain; open the builder with a no-op
// opener such as With() to reach it. For the common insert path, prefer
// the Create helper on the model, which returns the populated *T.
id, err := orm.Model[User]{}.With().InsertGetId(ctx, map[string]any{
    "email": "j@example.com",
    "name":  "Jane",
})
```

`Update` injects the driver-appropriate `NOW()` / `CURRENT_TIMESTAMP` sentinel for `updated_at` automatically, except on models that don't carry an `UpdatedAt` column (e.g. `ImmutableModel`). To emit raw SQL deliberately, wrap the value in `orm.RawSQL` (or use the `orm.NOW` constant).

### Chain-style writes

`Save`, `Create`, `CreateMany`, `FirstOrCreate`, and `UpdateOrCreate` are exposed on the chain. They all share the chain's driver, so a tx-bound `ctx` enrolls them in that transaction. `Create`, `CreateMany`, `FirstOrCreate`, and `UpdateOrCreate` are also standalone helpers on the model and can be called on a bare `Model[T]{}`; `Save` is chain-only, so open the builder with a no-op `With()` first:

```go
err := orm.Model[User]{}.With().Save(ctx, &user)
created, err := orm.Model[User]{}.Create(ctx, map[string]any{"email": email})
err = orm.Model[User]{}.CreateMany(ctx, batch)

u, err := orm.Model[User]{}.FirstOrCreate(ctx,
    map[string]any{"email": email},
    map[string]any{"name": name},
)

u, err := orm.Model[User]{}.UpdateOrCreate(ctx,
    map[string]any{"email": email},
    map[string]any{"name": name, "active": true},
)
```

`CreateMany` iterates sequentially and short-circuits on the first error. Inside `mgr.Transaction`, returning that error rolls back the partial batch.

## Raw SQL

`RawQuery[T]` is the escape hatch for queries the builder doesn't express. Every terminal takes `ctx` as the first argument and enrolls in a transaction the same way the fluent builder does. `Exec` returns the standard library's `sql.Result` so callers can inspect both `RowsAffected()` and `LastInsertId()`.

```go
// Read into structs
var u User
err := orm.NewRawQuery[User]("SELECT * FROM users WHERE email = ?", email).First(ctx, &u)

users, err := orm.NewRawQuery[User]("SELECT * FROM users WHERE role = ?", "admin").Get(ctx)

// Scalar / multi-column scan
var count int
err = orm.NewRawQuery[User]("SELECT COUNT(*) FROM users WHERE active").Scan(ctx, &count)

// Exec returns sql.Result
result, err := orm.NewRawQuery[User]("UPDATE users SET active = ? WHERE last_seen < ?", false, cutoff).Exec(ctx)
if err != nil { return err }
affected, _ := result.RowsAffected()
```


`NewRawQuery` runs the SQL verbatim, it does **not** apply the `deleted_at IS NULL` predicate that `Query[T]` adds for soft-delete models. Use `NewRawQuerySoftDeleteOnly` to opt in to that single scope, or write the predicate by hand. User-registered global scopes (multi-tenant, region, archive...) are never applied to raw SQL; if your model has any, use the fluent builder instead.


## Performance Tips

### Select Only Needed Columns

```go
// Bad: fetches all columns
users, _ := orm.Model[User]{}.All(ctx)

// Good: fetches only needed columns (open with a Where, then Select)
users, _ := orm.Model[User]{}.
    Where("active = ?", true).
    Select("id", "name", "email").
    Get(ctx)
```

### Avoid N+1 Queries

```go
// Bad: N+1 queries
users, _ := orm.Model[User]{}.All(ctx)
for _, u := range users {
    posts, _ := orm.Model[Post]{}.Where("user_id = ?", u.ID).Get(ctx) // N queries
}

// Good: eager loading
users, _ := orm.Model[User]{}.With("Posts").Get(ctx) // 2 queries total
```

### Use Indexes

```go
// Ensure columns used in WHERE, ORDER BY, JOIN are indexed
var u User
_ = orm.Model[User]{}.Where("email = ?", email).First(ctx, &u)  // email indexed
users, _ := orm.Model[User]{}.OrderBy("created_at", "DESC").Get(ctx)
```

## Related

- [CRUD](/docs/database/crud/) - create, update, delete, and lifecycle hooks for the same models you query here
- [Relationships](/docs/database/relationships/) - HasMany / BelongsTo helpers and `With(...)` eager loading
- [Global Query Scopes](/docs/database/scopes/) - register predicates that run on every `Get` / `Count` / `Pluck` / `Update`, with per-query opt-out for admin work
- [Transactional Outbox](/docs/database/outbox/) - atomically commit queue jobs and events alongside writes
- [Migrations](/docs/database/migrations/) - schema definitions and indexes that back efficient queries


================================================================================
# Relationships

Source: https://vel.build/docs/database/relationships/
Section: Database & Models
Summary: Define hasOne, hasMany, belongsTo, manyToMany, and polymorphic relationships with eager loading in Velocity ORM.


Velocity ORM supports five relation types: `hasOne`, `hasMany`, `belongsTo`, `manyToMany`, and `polymorphic`. Relations are declared via a struct tag and eager-loaded by chaining `.With(...)` onto a query whose terminal takes `ctx` as the first argument (`Get(ctx)`, `First(ctx, &dest)`, ...).

## Relationship Types

| Type | Cardinality | Tag goes on | Example |
|------|-------------|-------------|---------|
| `hasOne` | One-to-one | Parent | User has one Profile |
| `hasMany` | One-to-many | Parent | User has many Posts |
| `belongsTo` | Inverse of hasOne / hasMany | Child | Post belongs to User |
| `manyToMany` | Many-to-many via pivot | Either side | User has many Roles |
| `polymorphic` | Heterogeneous parent | Child | Comment on Post or Video |

## Tag Syntax

Each relation type uses **comma-separated** values inside an orm tag directive. The three single-key relations share the `relation:` directive; many-to-many and polymorphic each use their own directive (`manyToMany:`, `polymorphic:`):

```
orm:"relation:hasOne,<foreignKey>,<localKey>"
orm:"relation:hasMany,<foreignKey>,<localKey>"
orm:"relation:belongsTo,<foreignKey>,<localKey>"
orm:"manyToMany:<pivotTable>,<localFK>,<relatedFK>"
orm:"polymorphic:<typeColumn>,<idColumn>"
```

- `relation:` accepts only `hasOne`, `hasMany`, or `belongsTo` (case-sensitive). Many-to-many and polymorphic are NOT values of `relation:`; they are distinct directives.
- `hasOne` / `hasMany` / `belongsTo`: `<foreignKey>` is the column on the **child** table; `<localKey>` is the column on the **parent** (almost always `id`).
- `manyToMany:`: `<pivotTable>` is the join table; `<localFK>` and `<relatedFK>` are its two FK columns. See [Many-to-Many](#many-to-many).
- `polymorphic:`: `<typeColumn>` and `<idColumn>` live on the **child** and identify the parent row. See [Polymorphic Relations](#polymorphic-relations).

All parts are required for each shape. There are no convention-based defaults: the parser will not infer key names from the field name.


The outer `orm:"..."` tag uses `;` to separate top-level directives (`column:foo;type:bigint;not_null`). The `relation:` directive value uses `,` internally. Mixing them causes the parser to reject the tag.


## Has One

Tag goes on the parent's pointer field. Foreign key lives on the child table.

```go
type User struct {
    orm.Model[User]
    Name    string   `orm:"column:name;type:varchar(255)"`
    Profile *Profile `orm:"relation:hasOne,user_id,id"`
}

type Profile struct {
    orm.Model[Profile]
    UserID uint   `orm:"column:user_id;type:bigint;not_null"`
    Bio    string `orm:"column:bio;type:text"`
    User   *User  `orm:"relation:belongsTo,user_id,id"`
}
```

Load:

```go
users, err := orm.Model[User]{}.With("Profile").Get(ctx)
for _, u := range users {
    if u.Profile != nil {
        fmt.Println(u.Name, u.Profile.Bio)
    }
}
```

## Has Many

Tag goes on the parent's slice field. Foreign key lives on each child row.

```go
type User struct {
    orm.Model[User]
    Name  string `orm:"column:name;type:varchar(255)"`
    Posts []Post `orm:"relation:hasMany,user_id,id"`
}

type Post struct {
    orm.Model[Post]
    UserID uint   `orm:"column:user_id;type:bigint;not_null"`
    Title  string `orm:"column:title;type:varchar(255)"`
    User   *User  `orm:"relation:belongsTo,user_id,id"`
}
```

Load:

```go
users, err := orm.Model[User]{}.With("Posts").Get(ctx)
for _, u := range users {
    fmt.Printf("%s has %d posts\n", u.Name, len(u.Posts))
}
```

`[]*Post` is also accepted. The element type drives whether each loaded row is allocated as a value or pointer.

## Belongs To

Tag goes on the child's pointer-to-parent field. Foreign key lives on the same struct (the child).

```go
type Comment struct {
    orm.Model[Comment]
    PostID  uint   `orm:"column:post_id;type:bigint;not_null"`
    Content string `orm:"column:content;type:text"`
    Post    *Post  `orm:"relation:belongsTo,post_id,id"`
}
```

Load:

```go
comments, err := orm.Model[Comment]{}.With("Post").Get(ctx)
for _, c := range comments {
    if c.Post != nil {
        fmt.Println(c.Post.Title)
    }
}
```

The same shape applies to any inverse relation: `Post.User`, `Profile.User`, etc.

## Many-to-Many

Many-to-many is declared with the `manyToMany:` tag and a pivot table that holds the two foreign keys. Both ends of the relation get a slice field; the pivot rows are managed through accessor helpers, never through plain `orm.Save(ctx, ...)`.

### Tag syntax

```
orm:"manyToMany:<pivot_table>,<localFK>,<relatedFK>"
```

- `<pivot_table>`: name of the join table (e.g. `team_members`).
- `<localFK>`: column on the pivot pointing at the **declaring** struct's `id`.
- `<relatedFK>`: column on the pivot pointing at the **other** struct's `id`.

All three parts are required. The two ends of the same relation use the **same pivot table**, but swap the order of `localFK` and `relatedFK` so each side's "local" is the column referencing itself.

```go
type User struct {
    orm.Model[User]
    Name  string `orm:"column:name;type:varchar(255)"`
    Roles []Role `orm:"manyToMany:user_roles,user_id,role_id"`
}

type Role struct {
    orm.Model[Role]
    Name  string `orm:"column:name;type:varchar(64)"`
    Users []User `orm:"manyToMany:user_roles,role_id,user_id"`
}
```

The pivot table itself does not need a Go struct. It only has to exist in the database with at least the two FK columns; any extra columns become "pivot extras" (see below).

### Eager loading

`.With("Roles")` works the same as for `hasMany`. The loader issues two SQL queries total per preload regardless of parent count:

1. One `SELECT ... FROM <pivot> WHERE <localFK> IN (?, ?, ...)` to fetch all linkage rows.
2. One `SELECT * FROM <related_table> WHERE id IN (?, ?, ...)` to fetch the related models.

Results are grouped client-side onto each parent's slice field. The pivot table's column list is probed once (`SELECT * FROM <pivot> WHERE 1=0`) and cached in a `sync.Map` keyed by `(driver, table)`, so subsequent loads of the same relation skip the schema lookup.

```go
users, _ := orm.Model[User]{}.With("Roles").Get(ctx)
for _, u := range users {
    fmt.Printf("%s has %d roles\n", u.Name, len(u.Roles))
}
```

### Mutating pivot rows: Attach, Detach, Sync

Use `orm.M2M(parent, "RelationName")` to obtain an `*M2MAccessor`, then call `Attach`, `Detach`, or `Sync`. Each method runs inside a single transaction.

```go
acc, err := orm.M2M(&user, "Roles")
if err != nil {
    return err
}

// Add links. Duplicates and existing rows are skipped.
err = acc.Attach(ctx, adminRole.ID, editorRole.ID)

// Remove specific links.
err = acc.Detach(ctx, editorRole.ID)

// Detach-all when called with no ids.
err = acc.Detach(ctx)

// Replace the entire set: missing rows are inserted, extras deleted.
err = acc.Sync(ctx, adminRole.ID, viewerRole.ID)
```

The parent must have a non-zero `id` before constructing the accessor; `M2M` returns `"parent has no id - save it first"` if you call it on an unsaved struct.

### Pivot extras via `LoadManyToManyWithPivot`

When the pivot table carries extra columns (timestamps, role flags, sort order, etc.), `LoadManyToManyWithPivot[T, R]` returns the related rows paired with a `map[string]any` of every non-FK pivot column for that linkage:

```go
type PivotResult[T any] struct {
    Related T
    Pivot   map[string]any
}
```

```go
results, err := orm.LoadManyToManyWithPivot[User, Role](&user, "Roles")
if err != nil {
    return err
}
for _, r := range results {
    assignedAt, _ := r.Pivot["assigned_at"].(time.Time)
    fmt.Printf("%s, assigned %s\n", r.Related.Name, assignedAt)
}
```

The first type parameter is the parent type, the second is the related type. The function fails fast with a clear error if `R` does not match the related type discovered from the tag.


The pivot table here carries an extra `assigned_at` timestamp on every row. The relation declarations stay clean (no mention of the extra column), and the extra surfaces only when you ask for it via `LoadManyToManyWithPivot`.

```go
// Schema (illustrative migration)
// CREATE TABLE user_roles (
//   user_id     BIGINT NOT NULL,
//   role_id     BIGINT NOT NULL,
//   assigned_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
//   PRIMARY KEY (user_id, role_id)
// );

type User struct {
    orm.Model[User]
    Name  string `orm:"column:name;type:varchar(255)"`
    Roles []Role `orm:"manyToMany:user_roles,user_id,role_id"`
}

type Role struct {
    orm.Model[Role]
    Name string `orm:"column:name;type:varchar(64)"`
}

// Assign a few roles to a user.
acc, _ := orm.M2M(&user, "Roles")
_ = acc.Sync(ctx, adminRole.ID, editorRole.ID)

// Render the roles with their assignment timestamp.
results, _ := orm.LoadManyToManyWithPivot[User, Role](&user, "Roles")
for _, r := range results {
    when, _ := r.Pivot["assigned_at"].(time.Time)
    fmt.Printf("%s (since %s)\n", r.Related.Name, when.Format(time.RFC3339))
}
```


## Polymorphic Relations

A polymorphic relation lets a single field point at one of several different parent tables. For example, a `Comment` that can hang off either a `Post` or a `Video`. The discriminator (which table the row lives in) is stored as a string in a "type" column alongside the foreign-key id.

### Tag syntax

```
orm:"polymorphic:<type_col>,<id_col>"
```

- `<type_col>`: column on the **child** table holding the type-name string (e.g. `commentable_type`).
- `<id_col>`: column on the **child** table holding the foreign key id (e.g. `commentable_id`).

The polymorphic field's Go type **must** be `orm.Morph` (struct value, not pointer or slice). The two scalar columns themselves still need to be declared on the struct so they round-trip through SQL.

```go
type Comment struct {
    orm.Model[Comment]
    Body            string     `orm:"column:body;type:text"`
    CommentableType string     `orm:"column:commentable_type;type:varchar(64);not_null"`
    CommentableID   uint       `orm:"column:commentable_id;type:bigint;not_null"`
    Commentable     orm.Morph  `orm:"polymorphic:commentable_type,commentable_id"`
}
```

### The `Morph` value

```go
type Morph struct {
    TypeName string  // discriminator stored in the type column
    ID       any     // foreign key value
    Resolved any     // populated by eager-load or Resolve (typically *T)
}
```

`Morph.IsZero()` reports whether the morph carries any type/id information. Useful when rendering a list and skipping rows that point nowhere.

### Registering morph types

Each possible target type must be registered once at startup so the loader can map a type-name string to a Go type:

```go
func init() {
    orm.RegisterMorph("post",  reflect.TypeOf(Post{}))
    orm.RegisterMorph("video", reflect.TypeOf(Video{}))
}
```

A common pattern is to register from a service provider's `Boot`. Re-registering the same name overwrites the previous binding, which is convenient for swapping implementations in tests.

`LookupMorph(name)` returns the registered type and a boolean. `ResetMorphRegistry()` clears every binding (test-only).

### Eager loading

`.With("Commentable")` groups parents by the value in the type column, then issues one `SELECT ... WHERE id IN (...)` per distinct type. For `N` parents spread across `K` distinct types, the loader issues `K` SQL round trips for that preload, not `N`.

```go
comments, _ := orm.Model[Comment]{}.With("Commentable").Get(ctx)
for _, c := range comments {
    switch v := c.Commentable.Resolved.(type) {
    case *Post:
        fmt.Println("on post:", v.Title)
    case *Video:
        fmt.Println("on video:", v.URL)
    }
}
```

`Resolved` is set to a `*T` for the registered type. Type-switch on it to branch.

### Single-row resolution

When you have a `Comment` in hand and want to load its target without going through the eager-load path, call `Resolve` on the field's `Morph`:

```go
target, err := comment.Commentable.Resolve(ctx)
if err != nil {
    return err
}
post := target.(*Post)
```

`Resolve` returns a clear error for unknown type-names, an empty `TypeName`, a zero `ID`, or `ErrRecordNotFound` when the target row does not exist.

### Strict vs non-strict mode

The eager-load path and `Morph.Resolve` differ on what happens when a row's `TypeName` is not in the registry:

- **`Morph.Resolve` always errors** on an unknown type. Single-row callers have direct access to the failure and can branch on it.
- **Eager-load defaults to non-strict**: rows of an unknown type are skipped, and a warning is written to `os.Stderr`. The unresolved rows simply have `Resolved == nil`. This way, deploying a new morph type before every caller has been updated to register it does **not** crash list views. The new rows render as "unknown" instead of taking the page down.

Toggle the mode at startup or in tests:

```go
orm.SetMorphStrict(true)   // unknown types fail the entire eager-load batch
orm.SetMorphStrict(false)  // skip + warn (default)
b := orm.MorphStrict()     // read current setting
```

The warning destination is configurable. Pass `nil` to silence warnings entirely, or a buffer to capture them in tests:

```go
var buf bytes.Buffer
prev := orm.SetMorphWarnWriter(&buf)
defer orm.SetMorphWarnWriter(prev) // restore
```

`SetMorphWarnWriter` returns the previous writer so test cleanup can restore it.


A polymorphic schema usually grows by addition: a new morph target gets added to the database before every service that lists those rows is rebuilt with the matching `RegisterMorph` call. If eager-load were strict by default, that ordering would crash any list view containing even one row of the new type. Non-strict mode degrades gracefully: affected rows show up with `Resolved == nil` and the rest of the list renders normally. Use `SetMorphStrict(true)` in tests and in jobs where silent skipping would hide a real bug.



```go
type Post struct {
    orm.Model[Post]
    Title string `orm:"column:title;type:varchar(255)"`
}

type Video struct {
    orm.Model[Video]
    URL string `orm:"column:url;type:varchar(512)"`
}

type Comment struct {
    orm.Model[Comment]
    Body            string    `orm:"column:body;type:text"`
    CommentableType string    `orm:"column:commentable_type;type:varchar(64);not_null"`
    CommentableID   uint      `orm:"column:commentable_id;type:bigint;not_null"`
    Commentable     orm.Morph `orm:"polymorphic:commentable_type,commentable_id"`
}

// Register the targets once at startup.
func init() {
    orm.RegisterMorph("post",  reflect.TypeOf(Post{}))
    orm.RegisterMorph("video", reflect.TypeOf(Video{}))
}

// Create a comment against a post.
c := Comment{
    Body:            "great read",
    CommentableType: "post",
    CommentableID:   post.ID,
}
_ = orm.Save(ctx, mgr, &c)

// Eager-load a feed of comments. One IN query per distinct target type.
comments, _ := orm.Model[Comment]{}.With("Commentable").Get(ctx)
for _, c := range comments {
    switch v := c.Commentable.Resolved.(type) {
    case *Post:
        fmt.Println("post:", v.Title)
    case *Video:
        fmt.Println("video:", v.URL)
    case nil:
        // Non-strict mode: type was not registered; row was skipped with a warning.
    }
}
```


## Eager Loading

`.With(name...)` queues relations to load after the primary query. Pass field names exactly as declared on the struct (case-insensitive match is also accepted, but exact is preferred for clarity).

```go
// One relation
users, _ := orm.Model[User]{}.With("Posts").Get(ctx)

// Multiple relations
users, _ := orm.Model[User]{}.With("Profile", "Posts").Get(ctx)
```

Each preload runs as a single `SELECT ... WHERE <queryColumn> IN (?, ?, ...)` against the related table, then results are grouped back onto their parent rows. The eager-load query reuses the parent terminal's `ctx`, so a tx-bound ctx loads the relations inside the same transaction. Soft-deleted children are filtered automatically when the related model embeds the `orm.SoftDeletes[T]` trait (directly or via a convenience composition like `orm.SoftDeleteModel[T]`).

## Custom Foreign Keys

Use any column name; the parser does not require `<parent>_id` form. Both keys are passed verbatim to SQL.

```go
type Post struct {
    orm.Model[Post]
    AuthorID uint  `orm:"column:author_id;type:bigint;not_null"`
    Author   *User `orm:"relation:belongsTo,author_id,id"`
}

type User struct {
    orm.Model[User]
    Name  string `orm:"column:name;type:varchar(255)"`
    Posts []Post `orm:"relation:hasMany,author_id,id"`
}
```

Composite keys are not supported.

## Common Pitfalls

### 1. Bare relation type with no keys

```go
// WRONG: parser rejects with "relation tag has empty key names".
Posts []Post `orm:"relation:hasMany"`
```

Both keys are required. There is no inferred default.

### 2. Semicolons inside `relation:`

```go
// WRONG: parser sees a single value "hasMany;foreign_key:user_id;..."
// which has only one comma-separated part instead of three.
Posts []Post `orm:"relation:hasMany;foreign_key:user_id;local_key:id"`
```

Use commas for the three parts inside `relation:`. Use semicolons only between top-level directives like `column:`, `type:`, `not_null`.

### 3. Tag on the wrong side of the relation

The parser does not validate which side the tag lives on. Putting a `belongsTo` tag on the parent or a `hasMany` tag on the child compiles fine but loads zero rows because the `IN` query will never match. Always verify:

- `belongsTo`: child struct, points at one parent.
- `hasMany` / `hasOne`: parent struct, points at one or many children.

### 4. Wrong relation type name

```go
// WRONG: "BelongsTo" capitalized; parser expects "belongsTo".
*User `orm:"relation:BelongsTo,user_id,id"`
```

Type names are case-sensitive: `hasOne`, `hasMany`, `belongsTo` (camelCase).

### 5. Unsupported tag forms inside `relation:`

The `relation:` directive itself accepts only `hasOne`, `hasMany`, and `belongsTo`. Many-to-many uses the separate `manyToMany:` tag and polymorphic uses `polymorphic:` (see the dedicated sections above). `morphOne` / `morphMany` style tags are not implemented; the polymorphic field is always a single `orm.Morph` value.

## Error Reference

Errors emitted by `parseRelationTag` (in `orm/relation.go`):

The error strings below render the separator before `expected` as a plain hyphen for readability; the source uses a unicode em-dash (U+2014) in that exact spot, so grep for the rest of the string rather than the dash.

| Error | Cause |
|-------|-------|
| `orm: invalid relation tag "<value>" - expected "type,foreignKey,localKey"` | Wrong number of comma-separated parts. Most often caused by using `;` inside `relation:` or omitting one of the keys. |
| `orm: unknown relation type "<value>"` | First part is not `hasOne`, `hasMany`, or `belongsTo`. |
| `orm: relation tag "<value>" has empty key names` | Foreign or local key is blank, e.g. `relation:hasMany,,id`. |
| `orm: relation "<name>" not found on <model>` | `.With("X")` references a struct field that does not exist or does not carry a `relation:` tag. |
| `orm: invalid foreign key in relation tag` / `orm: invalid local key` | Key name fails identifier validation (non-alphanumeric, starts with a digit, etc.). |

Grep these strings if you hit a runtime error; the prefix `orm:` is consistent across the package.

## Behavior Details

These are observable runtime behaviors of the relation loader that are easy to miss by reading the API alone.

### Case-insensitive name matching

`findRelationField` tries an exact match first, then falls back to lowercase. Both work:

```go
users, _ := orm.Model[User]{}.With("Posts").Get(ctx)  // exact (preferred)
users, _ := orm.Model[User]{}.With("posts").Get(ctx)  // case-insensitive fallback
```

### Numeric key normalization

Parent and child keys are normalized to `int64` before comparison. Mixing `uint`, `uint32`, `int64`, etc., across the foreign / local key columns still matches correctly. String keys (UUIDs) compare as-is.

### Zero-key rows are skipped

Parents whose collected key value is `0` or `""` are dropped from the IN query. Children whose group key is zero are not assigned. This avoids accidental fan-out across all uninitialized rows when seed data contains placeholders.

### Embedded base-model fields are visible as columns

The field walker recurses into anonymous embedded structs (skipping `time.Time`). This is why `id` resolves on a model that embeds `orm.Model[T]` instead of declaring `ID` directly.

### `IsExisting` is set on loaded children

Each loaded related row has its existence bit set to `true` in the side-channel store keyed by pointer. A subsequent `orm.Save(ctx, mgr, &child)` therefore takes the UPDATE path rather than the INSERT path. Useful when mutating a relation in place.

### `hasOne` returns the first match if multiple rows exist

`assignSingle` takes the first row from the matching group. If two child rows share the same foreign key value, the second is silently discarded. Add a uniqueness constraint on the foreign key column to enforce one-to-one at the database level.

### One query per preload, not per parent

Each `.With("X")` adds one preload. The loader issues a single `SELECT ... WHERE <col> IN (?, ?, ...)` per preload regardless of parent count, then groups results client-side. Two preloads on a 1000-row primary query produce three SQL round trips total (one primary + two preload), not 2001.

## Best Practices

1. **Always eager-load.** `.With(...)` prevents N+1 queries on lists.
2. **Index foreign keys.** Every `<x>_id` column should have a database index; add it in the migration.
3. **Match key types.** Foreign and local key columns must be comparable (both `bigint`, both string UUIDs, etc.). Mixed types silently return zero matches.
4. **Soft-delete propagation.** Children whose model composes the `orm.SoftDeletes[T]` trait (directly or through `orm.SoftDeleteModel[T]` / `orm.SoftDeleteUUIDModel[T]`) are filtered automatically; children without it are not.
5. **Verify by loading once.** After declaring a new relation, run a `.With("X").Get(ctx)` against seed data and assert non-empty results before relying on it in handlers.


================================================================================
# Global Query Scopes

Source: https://vel.build/docs/database/scopes/
Section: Database & Models
Summary: Register named scopes that apply to every query for a model, with per-query opt-out for admin and cross-tenant work.


Global query scopes are predicates registered once against a model type that automatically run on every read, count, update, and delete. They are how Velocity implements soft-delete (`WHERE deleted_at IS NULL`) under the hood, and the same primitive is exposed for application-level concerns like multi-tenancy, draft visibility, and feature-gated rows.

## Why global scopes

Without a scope, every query in the codebase has to remember the same `Where("team_id = ?", currentTeam)` clause. Forget once and you leak data across tenants. A global scope moves that predicate to a single registration so the leak path is "explicitly opted out" rather than "forgot to add."

Common shapes:

- Multi-tenant `team_id` / `tenant_id` filtering
- Hide drafts from non-admin reads (`WHERE published = true`)
- Hide archived rows from default listings
- Force a "current schema version" predicate during a migration window

## Registering a scope

Scopes are registered against a concrete model type with `orm.AddGlobalScope[T]`. The function receives the per-call `ctx` and the in-flight `*orm.Query[T]` and mutates the query in place; it does not return a value.

```go
import (
    "context"

    "github.com/velocitykode/velocity/orm"
)

func init() {
    orm.AddGlobalScope[Post]("published_only", func(ctx context.Context, q *orm.Query[Post]) {
        q.Where("published = ?", true)
    })
}
```

The `ctx` passed to the scope is the same `context.Context` the caller handed to the terminal (`Get(ctx)`, `Count(ctx)`, ...), so scopes can read tenant / actor / locale values plumbed through it. Registration is typically done in a service provider, an `init()` in the model file, or a startup hook. Re-registering the same name replaces the prior function. Passing a `nil` fn removes the scope. Order is preserved across runs so generated SQL is deterministic.


Velocity's built-in soft-delete predicate is auto-registered under the reserved name `orm.SoftDeleteScopeName` (`"soft_delete"`) the first time you query a model that embeds the `orm.SoftDeletes[T]` trait (directly or via `orm.SoftDeleteModel[T]` / `orm.SoftDeleteUUIDModel[T]`). You can opt out of it with `WithoutGlobalScope(orm.SoftDeleteScopeName)`, the same mechanism your own scopes use.


## Opting out per query

Two escape hatches let a single query bypass scopes without disturbing the registry. `WithoutGlobalScope` and `WithoutGlobalScopes` are methods on `*Query[T]`, not on `Model[T]`. Start a query with any `*Query[T]`-returning builder method (`Where`, `WhereIn`, `WhereNull`, `WhereNotNull`, `OrderBy`, `With`), then chain the opt-out and a terminal that carries `ctx`:

```go
// Skip one named scope (e.g. show drafts to admins)
posts, err := orm.Model[Post]{}.
    Where("author_id = ?", authorID).
    WithoutGlobalScope("published_only").
    Get(ctx)

// Skip every scope (e.g. an admin export tool)
posts, err := orm.Model[Post]{}.
    OrderBy("created_at", "desc").
    WithoutGlobalScopes().
    Get(ctx)
```

Both methods return the same `*Query[T]`, so they compose with the rest of the builder.


`WithoutGlobalScopes()` disables every registered scope, including the multi-tenant predicate. Reach for `WithoutGlobalScope(name)` when you only need to bypass one. Audit every call site, scopes are how the framework keeps you safe by default.


## Where scopes apply

Scopes run on every terminal that builds SQL from the query: `Get(ctx)`, `First(ctx, &dest)`, `Find(ctx, id, &dest)`, `Count(ctx)`, `Exists(ctx)`, `Pluck(ctx, col)`, `Update(ctx, ...)`, and the soft-delete-driven `Delete(ctx)` path. Idempotency is guaranteed per query, even when one terminal delegates to another (for example `Exists` calling `Count`), the scope predicate is added at most once. Each terminal forwards its `ctx` argument to every scope, so a scope reading a tenant or actor value off the request ctx sees the same value the driver does.

Raw SQL queries built with `orm.NewRawQuery` do not run scopes. If you need the soft-delete predicate woven into a raw statement, use `orm.NewRawQuerySoftDeleteOnly`, see [Query Builder](/docs/database/queries/) for the rationale.

## Recipe: Multi-tenant `team_id` scope

The canonical use case. Auth middleware stashes the active team id on the request `ctx`; the scope reads it back when each terminal fires. There is no goroutine-local state, no singleton resolver, and the same predicate works inside a transaction because `Manager.Transaction(ctx, ...)` threads the same ctx into the closure.

Define the ctx key in your app:

```go
package tenancy

import "context"

type ctxKey struct{}

// WithTeamID returns a child ctx carrying the active team id. Auth
// middleware should call this once per request after resolving the
// caller's team.
func WithTeamID(parent context.Context, id uint) context.Context {
    return context.WithValue(parent, ctxKey{}, id)
}

// TeamID returns the active team id from ctx, or (0, false) if none was set.
func TeamID(ctx context.Context) (uint, bool) {
    id, ok := ctx.Value(ctxKey{}).(uint)
    return id, ok
}
```

Register the scope once at startup. The scope receives the per-call ctx as its first argument:

```go
import (
    "context"

    "github.com/velocitykode/velocity/orm"
)

func init() {
    orm.AddGlobalScope[Project]("tenant", func(ctx context.Context, q *orm.Query[Project]) {
        if id, ok := tenancy.TeamID(ctx); ok {
            q.Where("team_id = ?", id)
        }
    })
}
```

In a handler:

```go
// Tenant-blind: scope adds team_id automatically because ctx carries the team id.
projects, err := orm.Model[Project]{}.
    Where("status = ?", "active").
    Get(ctx)

// Admin export across tenants: explicit opt-out, grep-friendly for review.
// WithoutGlobalScope lives on *Query[T], so start the chain with a
// builder method (here OrderBy) before opting out.
all, err := orm.Model[Project]{}.
    OrderBy("id", "asc").
    WithoutGlobalScope("tenant").
    Get(ctx)
```

Treat any handler that does not run through your tenant-aware middleware as a footgun: if `tenancy.TeamID(ctx)` returns `(0, false)`, the scope adds no predicate and the query goes wide. Pair this with an integration test that asserts every model query in your handlers either has the scope applied or an explicit `WithoutGlobalScope` call.

## Removing a scope

```go
// Remove dynamically (mainly useful in tests)
orm.RemoveGlobalScope[Post]("published_only")

// Equivalent: re-register with nil fn
orm.AddGlobalScope[Post]("published_only", nil)
```

## Related

- [CRUD](/docs/database/crud/) - soft delete and lifecycle hooks; soft delete is itself a built-in global scope
- [Query Builder](/docs/database/queries/) - terminals that scopes attach to (`Get`, `Count`, `Pluck`, `Update`)
- [Transactional Outbox](/docs/database/outbox/) - the other ORM primitive shipped alongside scopes for atomic side effects


================================================================================
# CRUD Operations

Source: https://vel.build/docs/database/crud/
Section: Database & Models
Summary: Create, read, update, and delete database records with Velocity ORM's ctx-first API.


Every state-changing entry point on the ORM (and every read terminal) takes `context.Context` as its first positional argument. There is no implicit auto-commit and no chain-level `WithContext` decoration: pass the ctx your handler already holds, and a tx slot in that ctx (set by `Manager.Transaction` or `WithTxContext`) automatically enrolls the call in the surrounding transaction. A bare `context.Background()` routes through the pool driver.

## Create

### Save Instance

`orm.Save` is the package-level persistence helper. Pass `nil` for the manager to use the package default registered by `velocity.New()`.

```go
user := User{
    Name:  "John Doe",
    Email: "john@example.com",
    Role:  "user",
}
if err := orm.Save(ctx, nil, &user); err != nil {
    return err
}
fmt.Printf("User created with ID: %d\n", user.ID)
```

The same call updates an existing row when `orm.IsExisting(&user)` is true. Rows loaded via `Find`, `Where(...).Get`, `First`, etc. are marked existing automatically.

### Create with Map

```go
user, err := User{}.Create(ctx, map[string]any{
    "name":  "Jane Doe",
    "email": "jane@example.com",
    "role":  "admin",
})
```

`Create` accepts a `map[string]any` or a pre-built `*User`. Map-based writes are governed by the model's mass-assignment policy and are denied unless the model declares one, see [Mass Assignment](#mass-assignment) below.

### Create Multiple

```go
users := []User{
    {Name: "Alice", Email: "alice@example.com"},
    {Name: "Bob", Email: "bob@example.com"},
}
if err := (User{}).CreateMany(ctx, users); err != nil {
    return err
}
```

Iteration is sequential. The first error short-circuits; preceding rows are part of the in-flight tx when ctx carries one, so a `Manager.Transaction` closure can return that error to roll back the partial batch.

### First Or Create

Find by criteria; insert with `conditions ∪ values` if nothing matches.

```go
user, err := User{}.FirstOrCreate(ctx,
    map[string]any{"email": "john@example.com"},        // Search criteria
    map[string]any{"name": "John Doe", "role": "user"}, // Creation attributes
)
```

Returns `(*T, error)`. The "did we just create it" signal moved to a side-channel: call `orm.IsExisting(user)` after the call if you need it (it is always true on the returned pointer; the distinction lives in your branching logic, e.g. counting rows beforehand).

### Update Or Create

Lookup, update if found, insert if not.

```go
user, err := User{}.UpdateOrCreate(ctx,
    map[string]any{"email": "john@example.com"},
    map[string]any{"name": "John Updated", "role": "admin"},
)
```

The `Query[T]` chain forms exist too: `Model[T]{}.Where(...).FirstOrCreate(ctx, conditions, values)` (and the `UpdateOrCreate` counterpart) accept the same `(ctx, conditions, values)` triple, so you can scope the lookup with extra `Where` clauses before the helper resolves.

## Mass Assignment

Writing a model from a `map[string]any` is attacker-shaped input: a client that can slip a `role` or `is_admin` key into a JSON body would otherwise write those columns. Velocity is deny-by-default here. A model must declare a policy before ANY application column can be written from a map.

Declare an allowlist with `AssignableFields()`, which satisfies the `orm.Assignable` interface:

```go
type User struct {
    orm.Model[User]
    Name    string `orm:"column:name"`
    Email   string `orm:"column:email"`
    Role    string `orm:"column:role"`
    IsAdmin bool   `orm:"column:is_admin"`
}

// Only these fields may be set from a map.
func (User) AssignableFields() []string {
    return []string{"name", "email"}
}
```

Or a denylist with `ProtectedFields()`, which satisfies `orm.Protected`:

```go
func (User) ProtectedFields() []string {
    return []string{"role", "is_admin"}
}
```

Both key on the **snake_case Go field name**, not the `orm:"column:..."` tag value. That is the security invariant: a payload submitting the column alias resolves to the same policy entry, so the tag cannot be used to walk around the allowlist. Declaring both narrows twice: a field must be in the allowlist AND absent from the denylist.

### Deny by default

A model that declares neither, and does not opt out, resolves to an empty allowlist. Map-based writes against it fail with `*orm.MassAssignmentError` naming the model and the rejected keys, before any SQL is compiled:

```go
// Comment declares no policy, so every application column is denied.
type Comment struct {
    orm.Model[Comment]
    Body     string `orm:"column:body"`
    Approved bool   `orm:"column:approved"`
}

_, err := Comment{}.Create(ctx, map[string]any{"body": "hi", "approved": true})

var massErr *orm.MassAssignmentError
if errors.As(err, &massErr) {
    log.Warn("mass assignment denied",
        "model", massErr.Model, // e.g. "models.Comment"
        "keys", massErr.Keys)   // the rejected map keys, in column order
}
```

Once a policy IS declared, the established semantics resume: disallowed keys are silently skipped rather than erroring.


The message names the model and the offending keys for developers and logs. The production error renderer already collapses 5xx errors to generic status text; custom handlers should do the same rather than reflecting the type name and column list back to the caller.


### What the policy covers

| Path | Behaviour |
|---|---|
| `Create(map)` | Policed. No declared policy rejects the write with `*MassAssignmentError`. |
| `FirstOrCreate`, `UpdateOrCreate` | Policed across conditions AND values merged, because a condition key becomes a written column on the insert branch. |
| `Update(ctx, updates)`, static and chain form | Policed on the updates map, which is attacker-shaped exactly like a create map. |
| `Create(*T)` | Deny-by-default does not apply, but a DECLARED policy still zeroes every non-assignable field before the insert. |
| `orm.Save`, `CreateMany` | Not policed. You built the struct in code, so there is no map to police. |

Framework-managed embedded columns (`id`, `created_at`, `updated_at`, `deleted_at`) bypass the policy by design and never appear in a `MassAssignmentError`. That is what lets the soft-delete restore below pass `deleted_at` through a mass `Update`.

Key matching on the policed paths is case-insensitive against both the SQL column name and the snake-cased field name, so neither a casing variant like `IS_ADMIN` nor a column alias slips into the compiled statement.

### Opting out

Models that genuinely want every column writable from a map implement the explicit marker:

```go
func (ImportRow) AllowAllColumns() bool { return true }
```

Declaring `ProtectedFields()` with an empty slice is equivalent, since an empty denylist guards nothing. When the model also declares `AssignableFields()` or `ProtectedFields()`, the declared policy wins and `AllowAllColumns` has no effect.

To inspect the resolved policy directly, `orm.AccessFor(&model)` returns the `orm.AssignmentAccess` the write paths use, and `AssignmentAccess.Allows(fieldNameKey)` answers for a single snake_case field name.

## Read

See [Query Builder](/docs/database/queries/) for the full surface. The static helpers terminal in ctx:

```go
user, err := User{}.Find(ctx, 1)
user, err := User{}.FindBy(ctx, "email", "john@example.com")
user, err := User{}.First(ctx)
user, err := User{}.Last(ctx)
users, err := User{}.All(ctx)

// Chained queries return *Query[T]; terminal methods take ctx.
users, err := User{}.Where("role = ?", "admin").Get(ctx)
count, err := User{}.Count(ctx)
exists, err := User{}.Where("email = ?", email).Exists(ctx)
```

## Update

### Update via Save

Modify the loaded struct, then re-save:

```go
user, err := User{}.Find(ctx, 1)
if err != nil {
    return err
}
user.Name = "Updated Name"
user.Email = "newemail@example.com"
if err := orm.Save(ctx, nil, user); err != nil {
    return err
}
```

Because `Find` marked the row as existing, `Save` takes the UPDATE branch.

### Mass Update

Update by static helper:

```go
affected, err := User{}.Update(ctx,
    map[string]any{"role": "guest"},   // conditions
    map[string]any{"active": false},   // updates
)
```

Update through the chain when conditions are richer than `field = value`:

```go
affected, err := User{}.
    Where("role = ?", "guest").
    Where("created_at < ?", cutoff).
    Update(ctx, map[string]any{"active": false})
```

Both forms run the updates map through the same mass-assignment gate as `Create(map)`: a model with no declared policy rejects the write with `*orm.MassAssignmentError` before SQL compilation. See [Mass Assignment](#mass-assignment). Only the updates map is checked here; the conditions map compiles into the WHERE clause. `FirstOrCreate` and `UpdateOrCreate` check conditions and values together, since a condition key becomes a written column when the insert branch fires.

`updated_at` is stamped automatically with the driver-appropriate `NOW()` / `CURRENT_TIMESTAMP` sentinel; pass `orm.NOW` (or any other `orm.RawSQL` value) explicitly when you need a column other than `updated_at` to take the server's clock.

### Bulk write hooks (post-commit)

Per-row `AfterCommit` / `AfterRollback` hooks fire on `Save` / `Create` but
NOT on bulk `Update` / `Delete` / `ForceDelete`: the bulk path never
hydrates row instances. Models that need to react to a bulk write once the
surrounding tx commits implement `BulkAfterCommitHook`:

```go
type Post struct {
    orm.Model[Post]
    Title string `orm:"column:title"`
}

func (Post) BulkAfterCommit(ctx context.Context, ids []any, op orm.BulkOp) error {
    // op is BulkOpUpdate, BulkOpDelete, or BulkOpForceDelete
    // ids is the affected primary-key set (possibly empty)
    return cache.ForgetTags(ctx, "posts")
}
```

The hook fires exactly once per bulk statement, even when zero rows
matched (`len(ids) == 0`). The receiver is the zero value; do NOT touch it.
Composite primary keys are unsupported on this path; reach for
`Query.WithRowHooks()` instead, which materialises rows and falls back to
the per-row `AfterCommitHook` contract.

#### ID-capture by driver

| Driver | Strategy | Race window | QueryExecuted events |
|---|---|---|---|
| PostgreSQL | `RETURNING <pk>` appended to the write | none (atomic) | one per statement |
| MySQL / SQLite | Pre-SELECT before the write | yes (rows may shift) | two per statement (SELECT + write) |

The Postgres path captures ids atomically inside the write itself. MySQL and
SQLite issue a SELECT first, then the write; rows can shift between the two
under concurrent traffic.

#### `WithBulkLock` for race-free capture on the pre-SELECT path

When the bulk hook MUST observe exactly the rows that committed, chain
`WithBulkLock` to issue the pre-SELECT with `FOR UPDATE`:

```go
mgr.Transaction(ctx, func(ctx context.Context) error {
    _, err := orm.Model[Post]{}.
        Where("status = ?", "draft").
        Where("created_at < ?", cutoff).
        WithBulkLock().
        Delete(ctx)
    return err
})
```

Contract:

- **Only meaningful inside `Manager.Transaction`.** Outside a tx the
  auto-commit releases the lock immediately, making the call a no-op.
- **No-op on the atomic RETURNING path** (Postgres today, plus any adapter
  that opts in via `drivers.ReturningGrammar`). The write IS the capture,
  so there is no pre-SELECT to lock.
- **No-op on SQLite.** Its grammar accepts the `LockForUpdate` flag but
  never emits `FOR UPDATE` (SQLite has no row-level locking).
- **Cost: lock contention.** Concurrent writers that touch the same rows
  block for the duration of the surrounding tx.
- Propagates through `Query.Clone` and the soft-delete `Delete -> Update`
  delegation; `q.WithBulkLock().Delete(ctx)` locks the pre-SELECT for
  soft-deletable models on the pre-SELECT path.

Reach for `WithBulkLock` only when exact fidelity between captured ids and
committed rows matters more than throughput, and only on MySQL.

### Increment / Decrement

```go
// Static helpers
err := User{}.Increment(ctx, "login_count")          // +1
err := User{}.Increment(ctx, "points", 100)          // +100
err := User{}.Decrement(ctx, "credits", 10)          // -10

// Chain form: scope the rows first
err := User{}.Where("active = ?", true).Increment(ctx, "bonus", 5)
```

The generated UPDATE is atomic (`SET col = col + ?`) so concurrent increments do not lose updates.

## Delete

### Soft Delete

Models composed with `orm.SoftDeleteModel[T]` (or any composition that includes the `SoftDeletes[T]` trait) carry a `deleted_at *time.Time` column. `Delete` on those models stamps `deleted_at = NOW()`; the row stays in the table and is filtered out of subsequent reads by the registered soft-delete scope.

```go
type User struct {
    orm.SoftDeleteModel[User]
    Name string `orm:"column:name"`
}

// Static helper: soft-delete by conditions.
affected, err := User{}.DeleteWhere(ctx, map[string]any{"role": "guest"})

// Chain: soft-delete with richer predicates.
affected, err := User{}.Where("created_at < ?", cutoff).Delete(ctx)
```

### Force Delete

Permanent removal, even on soft-delete models:

```go
affected, err := User{}.ForceDeleteWhere(ctx, map[string]any{"id": 42})

// Chain form
affected, err := User{}.Where("active = ?", false).ForceDelete(ctx)
```

On models without soft delete, `Delete` and `ForceDelete` are equivalent.

### Working with Soft Deleted Records

```go
// Default scope hides trashed rows.
users, err := User{}.All(ctx)

// Include trashed rows.
users, err := User{}.WithTrashed().Get(ctx)

// Only trashed rows.
users, err := User{}.OnlyTrashed().Get(ctx)
```

To restore a trashed row, clear `deleted_at` via mass update with the trashed-aware scope explicitly opted in:

```go
affected, err := User{}.WithTrashed().
    Where("id = ?", id).
    Update(ctx, map[string]any{"deleted_at": nil})
```

## Append-Only Models

Tables that should never be mutated after insert (`audit_logs`, `events`, `outbox`, ledger entries) embed `orm.ImmutableModel[T]` (or `orm.ImmutableUUIDModel[T]`) instead of `orm.Model[T]`. The composition is `IDInt[T] + CreatedAtOnly + AppendOnly`: there is no `UpdatedAt` column and no UPDATE branch.

```go
type AuditLog struct {
    orm.ImmutableModel[AuditLog]
    Actor  string         `orm:"column:actor"`
    Action string         `orm:"column:action"`
    Meta   map[string]any `orm:"column:meta;type:jsonb"`
}

log, err := AuditLog{}.Create(ctx, map[string]any{
    "actor":  "user:42",
    "action": "user.deleted",
    "meta":   map[string]any{"target": 99},
})
```

Reads work like any other model:

```go
log, err := AuditLog{}.Find(ctx, id)
recent, err := AuditLog{}.
    Where("actor = ?", actor).
    OrderBy("created_at", "DESC").
    Limit(50).
    Get(ctx)
```

`orm.Save(ctx, mgr, &existing)` on an already-persisted immutable record returns `orm.ErrImmutableModelUpdate`. To "edit" an immutable row, append a new one.


The package-level `orm.Save(ctx, mgr, &record)` is the only persistence path for `ImmutableModel[T]` parents; there is no instance method. `Create` / `CreateMany` on the static-like helpers go through `orm.Save` automatically.


## Transactions

`Manager.Transaction` runs a closure inside a database transaction. The ctx passed to the closure carries a `*sql.Tx`; every ORM call you make with that ctx auto-enrolls in the tx.

```go
err := manager.Transaction(ctx, func(ctx context.Context) error {
    user, err := User{}.Create(ctx, map[string]any{
        "name":  "John",
        "email": "john@example.com",
    })
    if err != nil {
        return err // auto rollback
    }

    if _, err := (Profile{}).Create(ctx, map[string]any{
        "user_id": user.ID,
        "bio":     "Developer",
    }); err != nil {
        return err
    }

    return nil // auto commit
})
```

Lifecycle:

- Closure returns a non-nil error: rollback, error returned to caller.
- Closure panics: rollback, panic re-raised. Rollback failures surface as `TxRecover` events.
- Closure returns nil: commit, then per-tx callbacks and buffered events flush.

### Nested Transactions (Savepoints)

Re-entering `Transaction` from inside a closure reuses the outer tx. The inner closure observes savepoint semantics: an inner rollback discards only the inner work; the outer tx still commits or rolls back on its own boundary.

```go
err := manager.Transaction(ctx, func(ctx context.Context) error {
    user, err := User{}.Create(ctx, map[string]any{"name": "John"})
    if err != nil {
        return err
    }

    // Savepoint: inner failure is contained.
    inner := manager.Transaction(ctx, func(ctx context.Context) error {
        _, err := (Post{}).Create(ctx, map[string]any{
            "user_id": user.ID,
            "title":   "Draft",
        })
        return err
    })
    if inner != nil {
        log.Printf("post creation failed: %v", inner)
    }
    return nil
})
```

### Manual Transactions

When the closure form does not fit (long-lived txs, savepoint issuance), `Manager.Begin` returns the raw `*sql.Tx`. Thread it through ctx with `orm.WithTxContext`:

```go
tx, err := manager.Begin(ctx)
if err != nil {
    return err
}
txCtx := orm.WithTxContext(ctx, tx)

if err := orm.Save(txCtx, manager, &user); err != nil {
    _ = tx.Rollback()
    return err
}
return tx.Commit()
```

Prefer `Transaction` for everyday work; the manual path skips the per-tx event buffer and callback drain wiring that `Transaction` installs for you.

## Commit Callbacks

`OnCommit`, `OnRollback`, and `OnCommitFailure` register work to fire after the surrounding transaction settles. They are the durable replacement for "do this thing only if the row actually persisted" branches that used to live inline.

```go
ctx = orm.PrepareTxCallbacks(ctx)

err := manager.Transaction(ctx, func(ctx context.Context) error {
    user, err := User{}.Create(ctx, map[string]any{"email": email})
    if err != nil {
        return err
    }

    // Fires only after a successful commit.
    _ = orm.OnCommit(ctx, func(ctx context.Context) error {
        return cache.Forget(ctx, "users:"+user.Email)
    })

    // Fires only if the tx rolls back.
    _ = orm.OnRollback(ctx, func(ctx context.Context) error {
        log.Warn("user create rolled back", "email", email)
        return nil
    })

    return nil
})
```

`PrepareTxCallbacks` attaches the callback holder to ctx; without it, the `OnCommit` / `OnRollback` calls return `orm.ErrNoTxCallbacks` so callers can fall back to inline execution.

Important guarantees:

- Callbacks fire AFTER the tx has settled, never inside it.
- The ctx supplied to a callback is detached from cancellation via `context.WithoutCancel`. A request deadline that triggered the rollback will not poison the cache-invalidation cascade.
- A panic inside a callback is isolated. It surfaces as a `TxRecover` event with `Cause == "callback_panic"`; subsequent callbacks still run.
- Savepoint inner registrations defer to the outer tx: only the outermost commit/rollback boundary drains.

### Commit Failure

If `tx.Commit()` itself returns an error, the transaction is in an AMBIGUOUS state: the database may have committed but the network failed before the OK reached the client. `OnCommitFailure` is the only callback list that fires in this case; rollback callbacks do NOT run because the rollback was never confirmed.

```go
_ = orm.OnCommitFailure(ctx, func(ctx context.Context, commitErr error) error {
    log.Error("commit ambiguous - leaving outbox/cache untouched",
        "err", commitErr)
    return nil
})
```

The safe default is to log and leave outboxes / caches alone. Aggressive cleanup risks duplicate work (re-enqueueing jobs that already fired) or stale-cache reads (invalidating changes that DID land).

### Model Hooks: AfterCommit / AfterRollback

Models that implement `orm.AfterCommitHook` or `orm.AfterRollbackHook` are auto-registered against the active TxCallbacks on every successful Save. This is the right home for outbox dispatch, cache invalidation, webhook fanout: anything that requires durability before the side effect can be safely observed.

```go
type Order struct {
    orm.Model[Order]
    Customer string `orm:"column:customer"`
    Total    int64  `orm:"column:total"`
}

func (o *Order) AfterCommit(ctx context.Context) error {
    return events.Dispatch(ctx, OrderPlaced{ID: o.ID})
}

func (o *Order) AfterRollback(ctx context.Context) error {
    log.Warn("order rolled back", "id", o.ID)
    return nil
}
```

Outside a `Transaction`, the implicit auto-commit already happened by the time `Save` returns, so `AfterCommit` fires inline immediately after the in-tx hooks. `AfterRollback` only fires inside a `Transaction` that ultimately rolls back.

## Change Tracking

Tracking is opt-in. Calling `orm.Track` snapshots the current field values; `IsDirty`, `IsClean`, and `HasChanged` compare against that snapshot lazily. Models that never call `Track` pay zero: the side-channel is allocated only on demand.

```go
user, err := User{}.Find(ctx, 1)
if err != nil {
    return err
}
orm.Track(&user) // baseline

user.Name = "Updated"

orm.IsDirty(&user)              // true
orm.HasChanged(&user, "Name")   // true
orm.HasChanged(&user, "Email")  // false

if err := orm.Save(ctx, nil, &user); err != nil {
    return err
}
orm.MarkClean(&user) // re-baseline so subsequent edits are diffed against the saved state
orm.IsClean(&user)   // true
```

`HasChanged` keys on the Go field name (e.g. `"Name"`, not `"name"`). Tracking on an in-memory struct that was never persisted is a no-op.

## Existence

`orm.IsExisting(&model)` reports whether the row is persisted. Rows loaded via any read path (`Find`, `Get`, `First`, raw queries) are marked existing automatically; freshly-constructed structs are not until the first successful `Save`.

```go
var u User
u.Name = "draft"

orm.IsExisting(&u) // false

if err := orm.Save(ctx, nil, &u); err != nil {
    return err
}
orm.IsExisting(&u) // true
```

This is the bit that drives `Save`'s INSERT-vs-UPDATE branch. Reach for it directly when you want to branch in user code without round-tripping the database.

## Model Lifecycle Hooks

Models can implement any subset of the lifecycle hook interfaces. The save path detects them via type assertion and fires them at the appropriate point.

```go
type User struct {
    orm.Model[User]
    Name  string `orm:"column:name"`
    Email string `orm:"column:email"`
}

// Before insert: validate or normalize.
func (u *User) BeforeCreate() error {
    u.Email = strings.ToLower(u.Email)
    return nil
}

// After insert.
func (u *User) AfterCreate() error {
    log.Printf("user %d created", u.ID)
    return nil
}

// Before update.
func (u *User) BeforeUpdate() error {
    return nil
}

// After update.
func (u *User) AfterUpdate() error {
    return nil
}

// Before delete.
func (u *User) BeforeDelete() error {
    return nil
}

// After delete.
func (u *User) AfterDelete() error {
    return nil
}
```

These run inside the same connection / transaction as the write. For work that must wait until the row is durable (cache invalidation, queue dispatch), implement `AfterCommit` instead. See [Commit Callbacks](#commit-callbacks).

## Best Practices

1. **Always pass ctx.** The compile-time requirement is the point: there is no silent auto-commit code path to forget about.
2. **Prefer `Manager.Transaction` over `Begin`.** The closure form wires per-tx event buffering and callback drains for you.
3. **Use `AfterCommit` for side effects.** In-tx `AfterCreate` runs before the row is durable; webhooks and queue jobs belong on `AfterCommit`.
4. **Check `OnCommitFailure` semantics.** Treat commit-failure as ambiguous; logging is safe, retrying is not.
5. **Validate in `BeforeCreate` / `BeforeUpdate`.** Mass updates skip lifecycle hooks, so cross-check critical invariants in the request layer when going through the chain `Update`.
6. **Declare `AssignableFields()` on every model that takes map writes.** Deny-by-default means an undeclared model errors instead of silently persisting attacker keys; prefer the allowlist over `ProtectedFields()`, and treat `AllowAllColumns` as a last resort.
7. **Index columns used in WHERE.** The ORM does not synthesize indexes; see [Migrations](/docs/database/migrations/).

## Related

- [Queries](/docs/database/queries/): read-side counterpart, Where / First / Get / pagination patterns
- [Global Query Scopes](/docs/database/scopes/): the primitive behind soft-delete, also useful for multi-tenant filters and draft visibility
- [Transactional Outbox](/docs/database/outbox/): commit queue jobs and events atomically with the write that triggered them
- [Relationships](/docs/database/relationships/): HasMany / BelongsTo wiring used by Save and lifecycle hooks
- [Migrations](/docs/database/migrations/): schema and indexes that back the models you create and update


================================================================================
# Transactions

Source: https://vel.build/docs/database/transactions/
Section: Database & Models
Summary: ctx-bound transactions, savepoints, and post-commit callbacks for the Velocity ORM.


Velocity's ORM transactions are ctx-bound: `Manager.Transaction` opens a `*sql.Tx`, attaches it to the closure-supplied `ctx`, and every ORM terminal that observes that ctx (`Save`, `Create`, `Update`, `FirstOrCreate`, `UpdateOrCreate`, `CreateMany`, `Delete`, `Increment`, `Get`, `First`, `Count`, ...) auto-enrolls. There is no per-call `WithTx` decoration. Post-commit work registers via `orm.OnCommit` / `orm.OnRollback` / `orm.OnCommitFailure` (or the model-level `AfterCommit` / `AfterRollback` hooks) and runs only after the outer tx has settled.

## Closure-style transaction

```go
err := mgr.Transaction(ctx, func(ctx context.Context) error {
    user := User{Name: "Alice", Email: "alice@example.com"}
    if err := orm.Save(ctx, mgr, &user); err != nil {
        return err // -> rollback
    }

    profile := Profile{UserID: user.ID, Bio: "Builder"}
    return orm.Save(ctx, mgr, &profile)
}) // nil return -> commit
```

`fn` returning a non-nil error rolls back. Panicking rolls back and re-panics; rollback failures are logged through the manager's logger and surfaced as a `TxRecover` event with `Cause="panic"`. `fn` returning nil commits, flushes the per-tx event buffer, and drains commit callbacks.

The signature is fixed:

```go
func (m *Manager) Transaction(ctx context.Context, fn func(ctx context.Context) error) error
```

The closure receives a derived ctx, not the outer one. Use the inner ctx for every ORM call inside `fn` so the tx propagates.

## ctx carries the tx

Every ORM terminal takes ctx as its first positional argument. When that ctx carries a `*sql.Tx`, the call enrolls; otherwise it routes through the manager's pool driver. There is no per-call decoration.

```go
mgr.Transaction(ctx, func(ctx context.Context) error {
    // All four writes share one tx because they all use the inner ctx.
    if _, err := (User{}).Create(ctx, map[string]any{"email": "a@b.c"}); err != nil {
        return err
    }
    if err := orm.Save(ctx, mgr, &order); err != nil {
        return err
    }
    if _, err := (Audit{}).FirstOrCreate(ctx,
        map[string]any{"key": "user.created"},
        map[string]any{"actor": "system"},
    ); err != nil {
        return err
    }
    return orm.CreateMany(ctx, items)
})
```

Mixing tx-aware and tx-unaware writes inside the same closure is impossible without explicitly opting out. If you genuinely need a fire-and-forget side write that must commit independently of the surrounding tx (think audit / metrics), pass an explicitly non-tx ctx:

```go
mgr.Transaction(ctx, func(txCtx context.Context) error {
    if err := orm.Save(txCtx, mgr, &order); err != nil {
        return err
    }
    // Auto-commit, regardless of how the surrounding tx settles.
    return orm.Save(ctx, mgr, &MetricsRow{Kind: "order.placed"})
})
```

This is the documented opt-out. Reach for it sparingly.

## Manual transaction via Manager.Begin

```go
func (m *Manager) Begin(ctx context.Context) (*sql.Tx, error)
```

Use the closure form whenever it fits. `Begin` exists for the cases it does not: cross-goroutine SAVEPOINT issuance, integration with non-ORM SQL helpers that take their own `*sql.Tx`, lifecycle that does not match a single function scope.

```go
tx, err := mgr.Begin(ctx)
if err != nil {
    return err
}
ctx = orm.WithTxContext(ctx, tx) // every ORM call below enrolls in tx

if err := orm.Save(ctx, mgr, &order); err != nil {
    _ = tx.Rollback()
    return err
}
if err := tx.Commit(); err != nil {
    return err
}
```

`WithTxContext(ctx, tx)` is the slot Manager.Transaction wires for you. Direct callers must invoke `tx.Commit()` / `tx.Rollback()` themselves; `OnCommit` / `OnRollback` callbacks do **not** fire on this path because there is no Manager-driven boundary to drain them at. If you need post-commit work outside the closure form, register it manually after `tx.Commit()` returns nil.

## TxFromContext

Extract the underlying `*sql.Tx` for raw SQL or driver-specific calls (e.g. issuing a SAVEPOINT, running a non-ORM SQL helper that should join the same transaction):

```go
func TxFromContext(ctx context.Context) (*sql.Tx, bool)
```

```go
mgr.Transaction(ctx, func(ctx context.Context) error {
    tx, ok := orm.TxFromContext(ctx)
    if !ok {
        return errors.New("expected tx-bound ctx")
    }
    if _, err := tx.ExecContext(ctx, "SAVEPOINT before_risky"); err != nil {
        return err
    }
    // ... ORM writes still auto-enroll via ctx
    return nil
})
```

The slot is keyed by an unexported type, so external code cannot smuggle a forged `*sql.Tx` into the ORM via a hand-crafted ctx.

## Nested transactions

Calling `Transaction` from inside another `Transaction` closure does **not**
issue a SAVEPOINT or share the outer `*sql.Tx`. Each call to
`Manager.Transaction` opens its own real transaction (`driver.BeginTx`),
commits or rolls it back at the inner closure's boundary, and dispatches its own
`TransactionExecuted` event. The SQL transactions are independent.

What *is* shared across the nesting is the **bookkeeping**: the inner call
detects the outer's per-tx event buffer and callbacks holder on ctx and reuses
them. Concretely:

- **Commit / rollback callbacks** (`OnCommit` / `OnRollback` /
  `OnCommitFailure`) registered inside a nested call accumulate onto the
  **outer** callback list and drain only when the **outermost** `Transaction`
  settles. The inner call does not own the drain.
- **Buffered events** (`events.Buffer(ctx).Dispatch(...)`) reuse the outer
  buffer: an inner rollback drops only events emitted within the inner scope;
  the outermost commit flushes the rest.
- The inner tx span parents under the outer tx span so an APM exporter can
  render the tree.

```go
mgr.Transaction(ctx, func(ctx context.Context) error {
    if err := orm.Save(ctx, mgr, &order); err != nil {
        return err
    }
    return mgr.Transaction(ctx, func(ctx context.Context) error {
        // OnCommit registered here accumulates onto the OUTER callback
        // list and fires when the OUTERMOST Transaction commits, not when
        // this nested call returns.
        return orm.OnCommit(ctx, func(ctx context.Context) error {
            return invalidateOrderCache(ctx, order.ID)
        })
    })
})
```


Because the inner call opens a separate `*sql.Tx`, its writes commit
independently of the outer transaction. An outer rollback does **not** undo an
already-committed inner transaction. When you need partial rollback within a
single transaction, issue a real `SAVEPOINT` against the tx extracted with
`TxFromContext` rather than nesting `Transaction` calls.


Only the outermost commit drains the callback queue.

## Commit / rollback / commit-failure callbacks

Three package-level helpers register work to fire after the surrounding tx settles:

```go
func OnCommit(ctx context.Context, fn TxCallback) error
func OnRollback(ctx context.Context, fn TxCallback) error
func OnCommitFailure(ctx context.Context, fn TxCommitFailureCallback) error

type TxCallback              func(ctx context.Context) error
type TxCommitFailureCallback func(ctx context.Context, commitErr error) error
```

They solve the durability boundary: outbox emit, cache invalidation, and post-write webhook fanout must run only when the write is guaranteed durable. Calling these from inside `fn` accumulates onto the per-tx callback list; they fire **after** the outer commit / rollback completes, not inside `fn`.

```go
mgr.Transaction(ctx, func(ctx context.Context) error {
    if err := orm.Save(ctx, mgr, &order); err != nil {
        return err
    }
    if err := orm.OnCommit(ctx, func(ctx context.Context) error {
        return invalidateOrderCache(ctx, order.ID)
    }); err != nil {
        return err
    }
    return orm.OnRollback(ctx, func(ctx context.Context) error {
        reservations.Release(order.ID)
        return nil
    })
})
```

When ctx carries no active callbacks holder (no surrounding `Transaction`, or `PrepareTxCallbacks` was not threaded through), the helpers return `orm.ErrNoTxCallbacks` so the caller can fall back to running `fn` inline.

### Hook semantics

- **ctx is detached from cancellation.** The hook ctx is the parent ctx passed through `context.WithoutCancel`, so values (trace IDs, auth, request-scoped data) propagate but a cancel / deadline does NOT. The parent ctx is most often canceled by the same condition that drove the rollback (request abort, deadline) so propagating cancellation would poison every subsequent hook.
- **Panics are isolated.** A panic inside a callback is recovered, logged through the manager's logger when wired, and surfaced as a `TxRecover` event with `Cause="callback_panic"`. The panic does NOT roll back the (already-committed) tx, does NOT abort later callbacks, and does NOT propagate to the original `Transaction` caller (by the time hooks fire, `Transaction` has already returned).
- **Errors are logged, not raised.** Callback return values are logged through the manager's logger but never re-raised. The tx has already settled; there is no caller to surface the error to.
- **Order is registration order.** Callbacks fire in the order they were registered. A hook that registers further hooks during its own body queues onto the same list and is drained in the same pass.

### Commit-error path

When `tx.Commit()` itself returns an error, the tx is in an **ambiguous state**: the database may have committed but the network failed before the client received the OK, OR the commit may have been rejected outright.


On commit error, only `OnCommitFailure` callbacks fire. `OnRollback` callbacks are explicitly NOT drained. Running them would corrupt outboxes (re-enqueue jobs that already fired) or invalidate caches for changes that DID land. The default behavior of an `OnCommitFailure` callback should be to log the ambiguity and leave outboxes / caches alone; reach for driver-specific error-code branching (`pq.Error.Code`, `lib/pq`'s `CommitNotConfirmed`, SQLSTATE inspection) before deciding to compensate.


```go
orm.OnCommitFailure(ctx, func(ctx context.Context, commitErr error) error {
    log.Warn("commit ambiguous; tx may or may not have landed",
        "error", commitErr, "order_id", order.ID)
    return nil
})
```

## PrepareTxCallbacks

```go
func PrepareTxCallbacks(ctx context.Context) context.Context
```

`Manager.Transaction` installs the callbacks holder on the ctx it receives, but only if there is somewhere to put it. If `OnCommit` / `OnRollback` need to be reachable BEFORE `Transaction` enters (e.g. middleware or a wrapping helper that registers callbacks higher in the call stack than the tx open), wrap ctx with `PrepareTxCallbacks` first:

```go
ctx = orm.PrepareTxCallbacks(ctx)

// Some helper higher in the call stack registers a commit callback
// before the Transaction open.
preCommit(ctx)

return mgr.Transaction(ctx, func(ctx context.Context) error {
    return orm.Save(ctx, mgr, &order)
})
```

`PrepareTxCallbacks` is idempotent: re-wrapping an already-prepared ctx returns it unchanged.

## Model lifecycle hooks

Models can implement `AfterCommitHook` and `AfterRollbackHook` to receive the same lifecycle signal as `OnCommit` / `OnRollback` without reaching for the helper functions. Hooks auto-register on every `Save` / `Create` of the model.

```go
type AfterCommitHook interface {
    AfterCommit(ctx context.Context) error
}

type AfterRollbackHook interface {
    AfterRollback(ctx context.Context) error
}
```

```go
type Order struct {
    orm.Model[Order]
    Customer string `orm:"column:customer"`
    Total    int64  `orm:"column:total"`
}

func (o *Order) AfterCommit(ctx context.Context) error {
    return invalidateOrderCache(ctx, o.ID)
}

func (o *Order) AfterRollback(ctx context.Context) error {
    reservations.Release(o.ID)
    return nil
}
```

The hooks observe the model's committed identity (id, timestamps stamped by the in-tx `AfterCreate` / `AfterUpdate` step). Errors are logged but never propagated; by the time the hook runs, the tx has settled.

`AfterRollback` does NOT fire on commit-error. That path is ambiguous; install an `OnCommitFailure` callback when commit-failure observability is required.

### Inline (auto-commit) AfterCommit

Saving a model OUTSIDE a `Transaction` still fires `AfterCommit`: the implicit per-statement auto-commit has already landed by the time `Save` returns, so the hook fires inline immediately afterward. The contract is uniform from the model's perspective.

The Manager's `TxRecover` dispatcher is plumbed through ctx so a panic inside an inline `AfterCommit` surfaces an identical `TxRecover` event (`Cause="callback_panic"`); the auto-commit branch does not silently drop hook panics.

`AfterRollback` does not fire on the inline path: there is no rollback to react to.

## Concurrency contract

`*sql.Tx` is single-goroutine by stdlib contract. The ctx returned by `Transaction` (and any chain rooted in it) MUST be used from the goroutine that owns the tx. Fanning out inside `fn` is fine, but the fanned-out goroutines must serialize back to one goroutine before touching tx-aware ORM helpers.

```go
mgr.Transaction(ctx, func(ctx context.Context) error {
    var wg sync.WaitGroup
    results := make([]Result, len(inputs))
    for i, in := range inputs {
        i, in := i, in
        wg.Add(1)
        go func() {
            defer wg.Done()
            // OK: pure compute, no ORM call.
            results[i] = compute(in)
        }()
    }
    wg.Wait()

    // Back on the owning goroutine; safe to write through the tx ctx.
    return orm.CreateMany(ctx, results)
})
```

A goroutine that calls `orm.Save(ctx, mgr, ...)` with a tx-bound ctx from a different goroutine than the one that opened the tx is a contract violation; the driver's behavior under concurrent statement execution on a single `*sql.Tx` is undefined and the test suite will not catch it.

## APM: tx span + TransactionExecuted

`Manager.Transaction` mints a fresh span on entry and parents every
`QueryExecuted` event dispatched inside `fn` under it, so an APM exporter can
render the tx as a single node grouping its statements.

```text
RequestStarted          (request span)
  TransactionExecuted   (tx span, ParentID = request span)
    QueryExecuted       (stmt root, ParentID = tx span)
    QueryExecuted       (stmt root, ParentID = tx span)
    QueryExecuted       (stmt root, ParentID = tx span)
```

A `TransactionExecuted` event fires on commit, rollback, panic, and
commit-failure paths:

```go
type TransactionExecuted struct {
    Context    context.Context
    Connection string        // Driver name
    Duration   time.Duration // BeginTx success -> Commit / Rollback resolution
    Statements int           // QueryExecuted events under this tx span
    Error      string        // Empty on commit; populated on rollback / panic / commit failure
    TraceID    string        // APM trace ID
    SpanID     string        // The tx span ID; child QueryExecuted ParentID points here
    ParentID   string        // The caller's prior span
}
```

`Statements` counts only direct statements under the tx body. A nested
`Manager.Transaction` call detects the surrounding tx span and parents its own
tx span under it; the inner tx ships its own `TransactionExecuted` with its own
statement count and does NOT bump the outer counter. Exporters that want
all-stmts-under-the-tree semantics sum across the events sharing a `TraceID`.

Top-level callers without an incoming trace get a freshly minted `TraceID`
and an empty `ParentID`; nested or downstream callers preserve and extend
the surrounding trace.

Register a listener against the canonical event name `transaction.executed`. A
listener implements the `events.Listener` interface (`Handle(ctx, event) error`
plus `Async() bool`) and type-asserts the event in its body:

```go
type txLogger struct{}

func (txLogger) Async() bool { return false }

func (txLogger) Handle(ctx context.Context, event any) error {
    e, ok := event.(*orm.TransactionExecuted)
    if !ok {
        return nil
    }
    log.Info("tx",
        "trace_id", e.TraceID,
        "span_id", e.SpanID,
        "duration_ms", e.Duration.Milliseconds(),
        "stmts", e.Statements,
        "error", e.Error,
    )
    return nil
}

dispatcher.Listen("transaction.executed", txLogger{})
```

## Related

- [CRUD](/docs/database/crud/) - the writes that auto-enroll when ctx carries a tx
- [Transactional Outbox](/docs/database/outbox/) - the heavier durability primitive: side-effect rows committed in the same tx as the row that triggered them, drained by a relay
- [Queries](/docs/database/queries/) - read-side terminals that observe the same tx ctx
- [Events](/docs/advanced/events/) - per-tx buffered dispatcher; `events.Buffer(ctx).Dispatch(...)` inside `Transaction` flushes only on commit


================================================================================
# Migrations

Source: https://vel.build/docs/database/migrations/
Section: Database & Models
Summary: Version control your database schema with Velocity migrations for creating tables and modifying columns.


Migrations provide version control for your database schema. Velocity migrations live in the `github.com/velocitykode/velocity/orm/migrate` package: each migration is a registered value with `Up`/`Down` functions that receive a `*migrate.Migrator`, and a `Migrator` applies them against a database connection.

## Creating Migrations

Register a migration in an `init()` function. The `Version` must be a 14-digit `YYYYMMDDHHmmss` timestamp, which determines ordering.

```go
// migrations/20240101000001_create_users_table.go
package migrations

import "github.com/velocitykode/velocity/orm/migrate"

func init() {
    migrate.Register(&migrate.Migration{
        Version:     "20240101000001",
        Description: "create users table",
        Up: func(m *migrate.Migrator) error {
            return m.CreateTable("users", func(t *migrate.TableBuilder) {
                t.ID()
                t.String("name")
                t.String("email").Unique()
                t.String("password")
                t.String("role", 50).Default("user")
                t.Boolean("active").Default(true)
                t.Timestamps()
                t.SoftDeletes()
            })
        },
        Down: func(m *migrate.Migrator) error {
            return m.DropTable("users")
        },
    })
}
```


`Register` validates the migration and panics if the `Version` is missing, malformed, `Up` is nil, or the version is a duplicate. Each version may be registered only once.


## Running Migrations

Build a `Migrator` from the ORM `Manager`'s `*sql.DB` and driver name, then drive it. Import your migrations package (for its `init()` side effects) so they are registered.

```go
import (
    "github.com/velocitykode/velocity/orm"
    "github.com/velocitykode/velocity/orm/migrate"
    _ "myapp/migrations" // import to register migrations
)

manager, err := orm.NewManager(orm.ManagerConfig{
    Driver:   "sqlite",
    Database: "./database.db",
})
if err != nil {
    // handle error
}

migrator := migrate.NewMigrator(manager.DB(), manager.DriverName())

// Run all pending migrations
err = migrator.Up()

// Roll back the last N batches (defaults to 1 batch when steps <= 0)
err = migrator.Down(1)

// Drop all tables and re-run every migration from scratch
err = migrator.Fresh()
```

`Up`, `Down`, and `Fresh` run under a database-level advisory lock, so concurrent migrator processes cannot double-apply a migration. Applied migrations are grouped into batches; `Down(n)` rolls back the last `n` batches.

### Migration Status

```go
statuses, err := migrator.Status()
for _, s := range statuses {
    fmt.Printf("%s: %s (batch %d)\n", s.Version, s.State, s.Batch)
}
```

Each `MigrationStatus` has `Version`, `State` (`"Applied"` or `"Pending"`), `Batch`, and `ExecutedAt`.

## Schema Builder

### Creating Tables

`CreateTable` takes a table name and a builder closure:

```go
m.CreateTable("products", func(t *migrate.TableBuilder) {
    t.ID()
    t.String("name")
    t.Text("description").Nullable()
    t.Decimal("price", 10, 2)
    t.Integer("stock").Default(0)
    t.Boolean("active").Default(true)
    t.Integer("category_id")
    t.Timestamps()
})
```

### Column Types

Each method appends a column to the table. `String` takes an optional length (default `255`).

| Method | Description |
|--------|-------------|
| `ID()` | Auto-increment INTEGER primary key named `id` |
| `BigID()` | Auto-increment BIGINT primary key named `id` |
| `UUIDPrimary()` | UUID primary key named `id` (auto-generated where the driver supports it) |
| `UUID(name)` | UUID column (CHAR(36) on MySQL, TEXT on SQLite) |
| `String(name, length...)` | VARCHAR column (default length 255) |
| `Text(name)` | TEXT column |
| `Integer(name)` | INTEGER column |
| `BigInteger(name)` | BIGINT column |
| `SmallInteger(name)` | SMALLINT column (INTEGER on SQLite) |
| `Boolean(name)` | BOOLEAN column |
| `Decimal(name, precision, scale)` | DECIMAL/NUMERIC column |
| `Date(name)` | DATE column |
| `Timestamp(name)` | TIMESTAMP column |
| `TimestampTz(name)` | Timestamp-with-time-zone column |
| `JSON(name)` | JSON column (TEXT on SQLite) |
| `JSONB(name)` | JSONB column (JSON on MySQL, TEXT on SQLite) |
| `Binary(name)` | Binary blob (BYTEA/LONGBLOB/BLOB) |
| `IP(name)` | VARCHAR(45) suitable for IPv4/IPv6 addresses |
| `Vector(name, dimensions)` | pgvector `vector(N)` column (PostgreSQL only) |

### Column Modifiers

Modifiers apply to the most recently added column:

```go
t.String("bio", 500).Nullable()        // allow NULL
t.String("role", 50).Default("user")   // literal default value
t.String("id").DefaultRaw("gen_random_uuid()") // raw SQL default (unquoted)
t.String("email").Unique()             // UNIQUE constraint
t.UUID("id").Primary()                 // mark column as primary key
```


`DefaultRaw` inlines its expression into the DDL verbatim with no escaping. Pass only trusted, developer-authored SQL, never user input. Use `Default` for ordinary literal values, which are quoted and escaped for you.


Columns are `NOT NULL` by default; call `Nullable()` to allow `NULL`.

### Composite Primary Keys and Check Constraints

```go
m.CreateTable("role_user", func(t *migrate.TableBuilder) {
    t.Integer("role_id")
    t.Integer("user_id")
    t.PrimaryKey("role_id", "user_id")        // composite primary key
})

m.CreateTable("accounts", func(t *migrate.TableBuilder) {
    t.ID()
    t.Decimal("balance", 12, 2)
    t.Check("balance_non_negative", "balance >= 0") // named CHECK constraint
})
```


`Check` emits its expression verbatim. Pass only trusted SQL, never user input. The constraint name is validated as a SQL identifier.


### Timestamps and Soft Deletes

```go
t.Timestamps()      // created_at, updated_at
t.SoftDeletes()     // deleted_at (nullable)
t.TimestampsTz()    // created_at, updated_at with timezone
```

Non-nullable timestamp columns receive a managed default of the current time (`NOW()` / `CURRENT_TIMESTAMP`) unless you set your own `Default`.

### Indexes

Indexes are created via the `Migrator` (not the table builder):

```go
// Auto-named single or composite index (idx_<table>_<cols>)
m.Index("users", "email")
m.Index("users", "role", "active")

// Auto-named unique index (idx_<table>_<cols>_unique)
m.UniqueIndex("users", "email")

// Named index with full control
m.CreateIndex("idx_user_lookup", "users", func(b *migrate.IndexBuilder) {
    b.Columns("email", "active").Unique()
})

// Partial index (PostgreSQL, SQLite)
m.CreateIndex("idx_active_users", "users", func(b *migrate.IndexBuilder) {
    b.Columns("email").Where("deleted_at IS NULL")
})

// Drop an index (MySQL also requires the table name)
m.DropIndex("idx_user_lookup")
m.DropIndex("idx_user_lookup", "users")
```

The `IndexBuilder` supports `Columns`, `Unique`, `Where` (partial index, validated against a narrow grammar), `Include` (PostgreSQL covering columns), `Using` (PostgreSQL access method), `OperatorClass` (pgvector), `IfNotExists`, and `ToSQL`.

### Foreign Keys

The migrate builder does not generate foreign-key constraints. Add foreign keys with a raw statement inside the migration:

```go
m.CreateTable("posts", func(t *migrate.TableBuilder) {
    t.ID()
    t.Integer("user_id")
    t.String("title")
    t.Timestamps()
})

m.Raw(`ALTER TABLE posts
    ADD CONSTRAINT posts_user_id_foreign
    FOREIGN KEY (user_id) REFERENCES users(id)
    ON DELETE CASCADE`)
```


`Raw` executes SQL directly. Never concatenate user input into the statement; it is the caller's responsibility to keep the SQL safe.


## Modifying Tables

`Table` adds new columns (and named CHECK constraints) to an existing table via `ALTER TABLE`. It cannot add a primary-key column, change column types, rename columns, or drop columns.

```go
// Add columns to an existing table
m.Table("users", func(t *migrate.TableBuilder) {
    t.String("phone", 20).Nullable()
    t.Integer("team_id").Nullable()
})

// Add a single column with the column builder
m.AddColumn("users", "nickname", func(c *migrate.ColumnBuilder) {
    c.String(50).Nullable()
})

// Drop a column (SQLite requires version 3.35.0+)
m.DropColumn("users", "old_field")
```

The `ColumnBuilder` used by `AddColumn` exposes type setters (`String(length...)`, `Integer`, `BigInteger`, `SmallInteger`, `Text`, `Boolean`, `Binary`, `Timestamp`, `TimestampTz`, `Date`, `UUID`, `JSON`, `JSONB`, `Vector`, plus a generic `Type`) and modifiers `Nullable`, `Default`, `DefaultRaw`, and `Unique`.

## Dropping Tables

```go
// Drop a table (DROP TABLE IF EXISTS; CASCADE on PostgreSQL)
m.DropTable("old_table")
```

## Raw SQL

```go
migrate.Register(&migrate.Migration{
    Version: "20240101000002",
    Up: func(m *migrate.Migrator) error {
        return m.Raw(`
            CREATE VIEW active_users AS
            SELECT * FROM users WHERE active = true
        `)
    },
    Down: func(m *migrate.Migrator) error {
        return m.Raw("DROP VIEW IF EXISTS active_users")
    },
})
```

Use `m.Driver()` inside a migration to branch on the active driver (`"postgres"`, `"mysql"`, `"sqlite"`) when raw SQL must differ per dialect.

## Pretend (Dry-Run) Mode

`SetPretend(true)` collects the SQL a migration would run instead of executing it. Inspect the collected statements with `PretendLog()`:

```go
migrator.SetPretend(true)
_ = migrator.Up()
for _, stmt := range migrator.PretendLog() {
    fmt.Println(stmt)
}
```

## Vector Columns (PostgreSQL)

For pgvector workloads, ensure the extension exists, declare a `Vector` column, and build an approximate-nearest-neighbour index.

```go
Up: func(m *migrate.Migrator) error {
    if err := m.CreateVectorExtension(); err != nil { // CREATE EXTENSION IF NOT EXISTS vector
        return err
    }
    if err := m.CreateTable("documents", func(t *migrate.TableBuilder) {
        t.ID()
        t.Text("content")
        t.Vector("embedding", 1536)
    }); err != nil {
        return err
    }
    // CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops)
    return m.VectorIndex("documents", "embedding", "hnsw", "vector_cosine_ops")
}
```

`Vector`, `VectorIndex`, and `CreateVectorExtension` are PostgreSQL-only and return an error on other drivers. Vector dimensions must be between 1 and 16000.

## Driver-Specific Notes

The builder emits driver-aware DDL for the three supported drivers. Some highlights:

- **PostgreSQL**: `ID()`/`BigID()` use `SERIAL`/`BIGSERIAL`, `UUIDPrimary()` defaults to `gen_random_uuid()`, `JSONB` maps to native `JSONB`, and `Vector` requires the pgvector extension.
- **MySQL**: `ID()` uses `INT AUTO_INCREMENT`, `UUID` columns are `CHAR(36)`, and `JSONB` falls back to `JSON`. `DropIndex` requires the table name.
- **SQLite**: integers share one storage class (`Integer`, `BigInteger`, `SmallInteger`, `Boolean` all map to `INTEGER`), `UUID`/`JSON`/`JSONB` map to `TEXT`, and `ALTER TABLE` support is limited (no DROP COLUMN before 3.35.0). When adding CHECK constraints to an existing table, Velocity rebuilds the table for you.

## Best Practices

1. **One change per migration** - Keep migrations focused and reversible.
2. **Never modify applied migrations** - Create new migrations for further changes.
3. **Test rollbacks** - Ensure `Down` properly reverses `Up`.
4. **Use timestamp versions** - The 14-digit `YYYYMMDDHHmmss` format avoids ordering conflicts in teams.
5. **Index foreign keys** - Always index foreign-key columns.
6. **Add constraints carefully** - Consider existing data when adding NOT NULL or CHECK constraints.
7. **Backup before migrating** - Especially in production.
</content>
</invoke>


================================================================================
# Vector Search

Source: https://vel.build/docs/database/vector-search/
Section: Database & Models
Summary: Run pgvector similarity search through Velocity's ORM, and use the velocity-ai document store for a batteries-included embed-and-search pipeline.


Velocity's ORM has first-class [pgvector](https://github.com/pgvector/pgvector) support: a dedicated `orm.Vector` column type and nearest-neighbour query methods that compile to native pgvector distance operators. On top of those primitives, the separate `velocity-ai` module ships a document store that pairs the search query with an embedding provider.

This page covers both layers:

1. The **core ORM** vector primitives (`orm.Vector`, distance metrics, and the query methods).
2. The **velocity-ai** `vector.Store`, which adds the `documents` model, its migration, and the embed-then-search pipeline.


Vector search is **PostgreSQL only**. pgvector is a Postgres extension, so both the migration and the search query require a Postgres-backed ORM connection. On any other driver the migration fails closed and the query returns a clear `driver does not support vector search` error rather than emitting SQL the dialect cannot run.


## Core ORM primitives

These live in the `github.com/velocitykode/velocity/orm` package; no AI module is required.

### The `orm.Vector` type

`orm.Vector` is a dense `float32` embedding stored in a pgvector column:

```go
// github.com/velocitykode/velocity/orm
type Vector []float32
```

It implements `driver.Valuer` and `sql.Scanner`, so it round-trips through the ORM with no special-casing: on write it renders the pgvector text literal `[1,2,3]` (bound as a normal parameter), and on read it parses that same literal back. A `nil` Vector maps to SQL `NULL`.

Declare a model field as `orm.Vector` and tag the column type so the migration emits a `vector(N)` column:

```go
import "github.com/velocitykode/velocity/orm"

type Document struct {
    orm.Model[Document]
    Content   string     `orm:"column:content"`
    Embedding orm.Vector `orm:"column:embedding;type:vector(1536)"`
}
```

### Distance metrics

The metric is named by the `orm.DistanceMetric` string type. The concrete SQL operator is resolved by the driver's vector grammar:

```go
const (
    DistanceL2           DistanceMetric = "l2"            // Euclidean (L2): pgvector <->
    DistanceCosine       DistanceMetric = "cosine"        // cosine distance: pgvector <=>
    DistanceInnerProduct DistanceMetric = "inner_product" // negative inner product: pgvector <#>
    DistanceL1           DistanceMetric = "l1"            // taxicab (L1): pgvector <+> (pgvector 0.7+)
)
```

### Query methods

The vector helpers are available on `Model[T]{}` (and the UUID / soft-delete model variants) and on the `*Query[T]` chain:

```go
// Order the result set by vector distance, nearest first.
func (Model[T]) OrderByDistance(column string, vec Vector, metric DistanceMetric) *Query[T]

// Sugar for OrderByDistance(...).Limit(k): the k nearest rows.
func (Model[T]) NearestNeighbors(column string, vec Vector, metric DistanceMetric, k int) *Query[T]

// Add the distance to the projection under alias, so the score can be scanned.
func (Model[T]) SelectDistance(column string, vec Vector, metric DistanceMetric, alias string) *Query[T]
```




```go
import "github.com/velocitykode/velocity/orm"

// The 10 documents closest to queryVec under cosine distance, nearest first.
docs, err := orm.Model[Document]{}.
    NearestNeighbors("embedding", queryVec, orm.DistanceCosine, 10).
    Get(ctx)
```



```go
// SelectDistance projects the computed distance as a column so it can be
// scanned into a model field whose column matches the alias (e.g. a
// `Distance float64` field for alias "distance"). It does not order results,
// so combine it with OrderByDistance for a ranked search with a returned score.
type ScoredDocument struct {
    orm.Model[ScoredDocument]
    Content   string     `orm:"column:content"`
    Embedding orm.Vector `orm:"column:embedding;type:vector(1536)"`
    Distance  float64    `orm:"column:distance"`
}

docs, err := orm.Model[ScoredDocument]{}.
    SelectDistance("embedding", queryVec, orm.DistanceCosine, "distance").
    OrderByDistance("embedding", queryVec, orm.DistanceCosine).
    Limit(10).
    Get(ctx)
```



```go
// OrderByDistance evaluates the distance in ORDER BY only; it is not added to
// the projection. Use it directly when you only need ranking, not the score.
docs, err := orm.Model[Document]{}.
    OrderByDistance("embedding", queryVec, orm.DistanceL2).
    Limit(5).
    Get(ctx)
```




The query vector is always bound as a parameter, never interpolated into SQL. See the  page for the rest of the query builder, and  for the schema builder used below.

### Declaring a vector column in a migration

The migration schema builder declares vector columns and indexes. All three helpers are Postgres-only and return a clear error on any other driver:

```go
import "github.com/velocitykode/velocity/orm/migrate"

func init() {
    migrate.Register(&migrate.Migration{
        Version:     "20260101000000",
        Description: "create documents table with a pgvector embedding column",
        Up: func(m *migrate.Migrator) error {
            // CREATE EXTENSION IF NOT EXISTS vector
            if err := m.CreateVectorExtension(); err != nil {
                return err
            }
            if err := m.CreateTable("documents", func(t *migrate.TableBuilder) {
                t.ID()
                t.Text("content")
                t.Vector("embedding", 1536) // vector(1536)
                t.Timestamps()
            }); err != nil {
                return err
            }
            // CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops)
            return m.VectorIndex("documents", "embedding", "hnsw", "vector_cosine_ops")
        },
        Down: func(m *migrate.Migrator) error {
            return m.DropTable("documents")
        },
    })
}
```

`TableBuilder.Vector(name, dimensions)` emits a `vector(N)` column (dimension validated 1..16000, the pgvector limit). `Migrator.VectorIndex(table, column, method, opClass)` builds an approximate-nearest-neighbour index where `method` is the access method (`hnsw` or `ivfflat`) and `opClass` is the operator class matching your metric (`vector_cosine_ops`, `vector_l2_ops`, `vector_ip_ops`, ...). The index name is auto-generated as `idx_<table>_<column>_<method>`.

## The velocity-ai document store

The `velocity-ai` module is a separate Go module that builds on the ORM primitives above. Its `vector` package ships a ready-made `documents` model, the migration that provisions it, and a `Store` whose `Search` runs the nearest-neighbour query for you.

```bash
go get github.com/velocitykode/velocity-ai
```

### The `Document` model

```go
// github.com/velocitykode/velocity-ai/vector
type Document struct {
    orm.Model[Document]
    Content   string     `orm:"column:content" json:"content"`
    Embedding orm.Vector `orm:"column:embedding;type:vector(1536)" json:"embedding,omitempty"`
}

func (Document) TableName() string { return "documents" }
func (Document) Fillable() []string { return []string{"content", "embedding"} }
```

The embedding width is fixed by the exported constant `vector.EmbeddingDimensions` (`1536`), and the searched column name by `vector.EmbeddingColumn` (`"embedding"`). These are the single source of truth shared by the model, the migration, and any caller producing query vectors; a query vector of a different length is rejected by Postgres at query time.

### Provisioning the table

The migration is registered by importing the `vector/migrations` package for its side effects. It installs the pgvector extension, declares the `vector(1536)` column, and builds an HNSW cosine index:

```go
import (
    _ "github.com/velocitykode/velocity-ai/vector/migrations" // provisions `documents`
    "github.com/velocitykode/velocity-ai/vector"
)
```

### Searching

`NewStore` returns a `Store` bound to the package-default ORM connection (set via `orm.SetDefault`, which must be Postgres-backed). `Search` returns the `k` documents closest to `queryVec` under the given metric, nearest first:

```go
// github.com/velocitykode/velocity-ai/vector
func NewStore() *Store

func (s *Store) Search(ctx context.Context, queryVec orm.Vector, k int, metric orm.DistanceMetric) ([]Result, error)
```

Each match is a `Result`: the matched `Document` plus its 1-based rank in the nearest-first ordering.

```go
type Result struct {
    Document Document
    Rank     int // 1 == nearest neighbour
}
```

```go
import (
    "github.com/velocitykode/velocity-ai/vector"
    "github.com/velocitykode/velocity/orm"
)

// orm.SetDefault(pgManager) must have been called during boot.
hits, err := vector.NewStore().Search(ctx, queryVec, 10, orm.DistanceCosine)
if err != nil {
    return err
}
for _, hit := range hits {
    fmt.Printf("#%d (rank): %s\n", hit.Rank, hit.Document.Content)
}
```

`Search` is built purely from ORM methods (`NearestNeighbors` then `Get`); it never hand-builds SQL or interpolates the query vector. On a non-vector driver it surfaces the same `does not support vector search` error from the ORM, and the query is never issued.

### Producing the query vector with embeddings

`Search` takes a query vector you supply; the embeddings themselves come from the velocity-ai `Manager`. Resolve the Manager from the Velocity service container, then drive the fluent embedding builder:

```go
import (
    "github.com/velocitykode/velocity-ai/manager"
    "github.com/velocitykode/velocity-ai/vector"
    "github.com/velocitykode/velocity/app"
    "github.com/velocitykode/velocity/orm"
)

func semanticSearch(ctx context.Context, s *app.Services, query string) ([]vector.Result, error) {
    m := manager.FromServices(s) // *manager.Manager, nil unless manager.Lifecycle registered it

    // Embeddings(...).For(...).Generate(ctx) returns *provider.EmbeddingsResponse.
    resp, err := m.Embeddings().For(query).Generate(ctx)
    if err != nil {
        return nil, err
    }

    // EmbeddingsResponse.Embeddings is [][]float64; convert the first row to
    // orm.Vector ([]float32) for the search.
    raw := resp.Embeddings[0]
    queryVec := make(orm.Vector, len(raw))
    for i, f := range raw {
        queryVec[i] = float32(f)
    }

    return vector.NewStore().Search(ctx, queryVec, 10, orm.DistanceCosine)
}
```

The `Manager.Embeddings(...)` entrypoint returns a `PendingEmbedding` builder. `For(inputs...)` sets the text to embed, and `Generate(ctx)` resolves the configured embedding provider (the default is selected by `DefaultEmbeddingProvider` in your AI config, e.g. the OpenAI embedding gateway) and returns a `*provider.EmbeddingsResponse`. The builder also exposes `WithProvider` / `WithProviders` (failover), `WithModel`, `WithDimensions`, and `Cached`.


**Two layers, one pipeline.** The core ORM gives you the query primitives (`orm.Vector`, the distance metrics, and `NearestNeighbors` / `OrderByDistance` / `SelectDistance`) so you can run pgvector search against any model you own. The `velocity-ai` `vector` package gives you the batteries-included path: a ready-made `documents` model and migration, an embedding provider to turn text into vectors, and a `Store.Search` that stitches them together.



================================================================================
# Transactional Outbox

Source: https://vel.build/docs/database/outbox/
Section: Database & Models
Summary: Atomically commit side effects (queue jobs, events) alongside database writes using the outbox pattern, with a built-in relay for delivery, retries, and DLQ.


The outbox pattern lets you commit a side effect (a queue job, a domain event) in the *same SQL transaction* as the database row that triggered it. If the transaction commits, the side effect is guaranteed to be delivered eventually. If it rolls back, the side effect disappears with it. No more "we charged the card but the email never went out because the request died between commit and queue.Push."

Velocity ships the producer (`Manager.TransactionWithOutbox`) and the consumer (`orm.Relay`) in the `orm` package. For lighter-weight post-commit side effects that do not need durable redelivery (cache invalidation, fire-and-forget webhooks, in-process domain events), reach for the transaction callbacks API: `orm.OnCommit` / `orm.OnRollback` / `orm.OnCommitFailure`.

## When to reach for it

- After-the-fact emails / webhooks / push notifications that must fire if and only if the user write succeeded.
- Domain events fanned out to other services where "fire and forget" cannot drop messages.
- Cross-system effects in a service that does not own a distributed transaction coordinator.

If the side effect is purely in-process and a dropped message after a crash is acceptable, reach for [`async.Go`](/docs/core/async/), the [queue](/docs/core/queue/), or `orm.OnCommit` (see [Post-commit callbacks](#post-commit-callbacks-oncommit--onrollback--oncommitfailure) below). The outbox is the heavier hammer for "must not lose."

## Schema setup

Outbox rows live in a single table named `velocity_outbox`. Create it via the helper before starting any producers or relays:

```go
if err := manager.EnsureOutboxTable(ctx); err != nil {
    log.Fatal(err)
}
```

`EnsureOutboxTable` is idempotent (uses `CREATE TABLE IF NOT EXISTS`) and emits driver-aware DDL for SQLite, MySQL, and Postgres. If you prefer to drive your own migrations, pull the statements from `orm.OutboxMigrationSQL(driverName)` and wrap them in your usual migration tooling.

The exported constants `orm.OutboxTableName`, `orm.OutboxKindJob`, and `orm.OutboxKindEvent` are useful for admin tooling that inspects the table directly.

## Producer side

`Manager.TransactionWithOutbox` runs your callback inside a database transaction and hands you a `Pending` handle whose `Enqueue` and `Dispatch` methods record outbox rows on the same `*sql.Tx`. The rows commit (or roll back) atomically with your writes.

```go
type OrderPlaced struct {
    OrderID  uint
    Customer string
    Total    int64
}

// Once at startup, before producers run:
orm.RegisterPayloadType(OrderPlaced{})

err := manager.TransactionWithOutbox(ctx, func(tx *sql.Tx, outbox orm.Pending) error {
    if _, err := tx.ExecContext(ctx,
        "INSERT INTO orders (customer, total) VALUES (?, ?)",
        order.Customer, order.Total,
    ); err != nil {
        return err
    }

    // Recorded on the same tx. Commits with the order, rolls back with it.
    if _, err := outbox.Dispatch(OrderPlaced{
        OrderID:  order.ID,
        Customer: order.Customer,
        Total:    order.Total,
    }); err != nil {
        return err
    }
    return nil
})
```

`Pending.Enqueue` records a row to be delivered to your queue driver; `Pending.Dispatch` records an event for the events dispatcher. Both return the row id assigned by the database.


Payloads are encoded with `encoding/gob` and base64-wrapped into a `TEXT` column. Every concrete type passed to `Enqueue` or `Dispatch` must be registered with `orm.RegisterPayloadType` before the relay starts, otherwise decode fails at delivery time. The call is idempotent and safe for concurrent use.


### Per-row options

```go
outbox.Enqueue(payload,
    orm.WithIdempotencyKey("order-placed-" + order.UUID),
    orm.WithPartitionKey("customer-" + order.Customer),
    orm.WithMaxAttempts(10),
    orm.WithAvailableAt(time.Now().Add(30 * time.Second)),
)
```

- `WithIdempotencyKey(key)` overrides the auto-generated 128-bit hex key. Duplicate keys hit a unique index and surface as a SQL error, useful when the producer is itself replayable.
- `WithPartitionKey(key)` opts the row into per-partition FIFO. The relay never leases two rows from the same partition concurrently and processes them in id order. Use the entity id (`"order-42"`) when downstream order matters.
- `WithMaxAttempts(n)` sets the per-row retry ceiling before the row moves to the DLQ. Defaults to 5.
- `WithAvailableAt(t)` schedules the first delivery attempt. Defaults to "now."

### Panic handling

A panic inside the `TransactionWithOutbox` callback is converted to an error and the transaction is rolled back. The panic is *not* re-raised, callers handle the failure as an ordinary error per the framework's "no panics in library code" rule.

## Post-commit callbacks: `OnCommit` / `OnRollback` / `OnCommitFailure`

The transactional outbox is the right tool when a side effect must survive a process crash. For everything else (cache invalidation, in-process events, fire-and-forget webhooks, audit emits) the lighter primitive is the transaction callbacks API: register a function inside the transaction, have it fire only after the tx terminates.

```go
ctx = orm.PrepareTxCallbacks(ctx)

err := mgr.Transaction(ctx, func(ctx context.Context) error {
    if _, err := (Order{}).Create(ctx, map[string]any{
        "customer": "alice",
        "total":    1299,
    }); err != nil {
        return err
    }

    // Fires only if the surrounding tx commits successfully.
    return orm.OnCommit(ctx, func(ctx context.Context) error {
        cache.Forget(ctx, "orders:alice")
        return nil
    })
})
```

Three registration helpers, all ctx-first and all keyed off the per-tx callbacks slot installed by `Manager.Transaction`:

- `orm.OnCommit(ctx, fn)` fires after `tx.Commit` returns successfully. Canonical place for cache invalidation, post-commit webhook publish, in-process event fanout, audit emits.
- `orm.OnRollback(ctx, fn)` fires after a confirmed rollback (closure returned an error, or a panic-driven rollback succeeded, or ctx cancellation triggered the rollback). Use for compensations: clearing in-memory reservations, releasing external locks held outside the database.
- `orm.OnCommitFailure(ctx, fn)` fires when `tx.Commit` returns an error. The tx is in an *ambiguous* state (see below). Receives the commit error so app code can branch on driver-specific SQLSTATE codes.

`orm.PrepareTxCallbacks(ctx)` wraps the incoming ctx with a holder slot so the registration helpers can find the active list. Call it once near the request boundary (typically at the top of an HTTP handler, before any `Transaction` call). It is idempotent and safe to call multiple times.


`OnCommitFailure` runs because `tx.Commit` returned an error. That does **not** mean the database rolled back, the network may have failed *after* the database persisted the change but *before* the client received the OK. Re-enqueuing outbox jobs or aggressively invalidating caches in this branch risks duplicate work or stale reads. The safe default is to **log the ambiguity and leave outboxes / caches untouched**; only branch on driver-specific error codes (`pq.Error.Code`, lib/pq's `CommitNotConfirmed`, libpq SQLSTATE) when you have a verified-rolled-back signal.


### Semantics in one place

- **Hook ctx is detached from cancellation.** Each callback receives a ctx wrapped in `context.WithoutCancel` so trace IDs and request-scoped values flow through, but a parent-ctx deadline does not poison the post-commit cascade. Most rollbacks are triggered *by* a canceled parent ctx; propagating that cancellation would silently drop every subsequent compensation.
- **Savepoints (nested `Transaction`) defer to the outer tx.** Inner `OnCommit` registrations queue onto the outer list. Releasing a savepoint does **not** fire commit hooks; only the outermost `tx.Commit` drains them.
- **A panic inside a hook is isolated.** It is recovered, surfaced as a `TxRecover` event through the manager's dispatcher, logged when a logger is wired, and falls back to stderr only when neither sink exists. Subsequent callbacks still run.
- **Commit-error path runs `OnCommitFailure` only.** Rollback hooks do **not** fire on commit error (the tx state is ambiguous; running rollback compensations would corrupt outboxes / caches).
- **Ctx cancellation that triggers rollback fires `OnRollback`.** A request-abort or deadline that causes the closure to return early still drains rollback hooks, with the detached hook ctx so they actually run.
- **Auto-commit (no surrounding `Transaction`) fires `AfterCommit` inline.** When a model is `Save`d outside `Manager.Transaction`, the implicit auto-commit has already happened by the time `Save` returns, so the model's `AfterCommit` hook fires synchronously before `Save` returns. `AfterRollback` never fires on this path (there is nothing to roll back).

### Auto-registering hooks on a model

Models that implement `AfterCommitHook` or `AfterRollbackHook` get the corresponding callback registered automatically every time the model is `Save`d:

```go
type Order struct {
    orm.Model[Order]
    Customer string
    Total    int64
}

func (o *Order) AfterCommit(ctx context.Context) error {
    return dispatcher.Dispatch(ctx, OrderPlaced{ID: o.ID, Customer: o.Customer})
}

func (o *Order) AfterRollback(ctx context.Context) error {
    inMemReservations.Release(o.Customer)
    return nil
}
```

Inside a `Manager.Transaction` the hook registers against the surrounding callback list and fires on commit (or rollback). Outside a transaction, `AfterCommit` fires inline once the implicit auto-commit returns. Errors returned by the hook are logged but never propagated to the original caller, by the time the hook runs the row is already durable.

### When to pick the outbox vs. `OnCommit`

| Need | Pick |
| --- | --- |
| Side effect must survive a process crash between commit and dispatch | **Outbox** (`TransactionWithOutbox` + relay) |
| Fan-out to another service over the network with at-least-once delivery | **Outbox** |
| Per-partition FIFO ordering, idempotency keys, retries with DLQ | **Outbox** |
| Fire-and-forget cache invalidation after commit | `OnCommit` |
| In-process event dispatch on commit | `OnCommit` (or the per-tx event buffer, see below) |
| Compensation work on rollback (release external locks, clear in-memory state) | `OnRollback` |
| Observe ambiguous-commit failures without re-enqueuing | `OnCommitFailure` |

## Buffered domain events at the tx boundary

`Manager.Transaction` installs a per-transaction `events.BufferedDispatcher` on the incoming ctx. Any `events.Buffer(ctx).Dispatch(ctx, ...)` call inside the closure records the event but does not fire it; the buffer flushes on commit (using the parent tx's ctx so listeners observe trace IDs) and is dropped on rollback.

Every `Listener.Handle` and every `Dispatcher.Dispatch` / `DispatchNow` / `DispatchAsync` / `DispatchAfter` / `Until` takes `ctx` as its first positional argument, so listeners observe request-scoped values when the buffered events flush.

```go
ctx = events.PrepareBuffer(ctx)
ctx = orm.PrepareTxCallbacks(ctx)

err := mgr.Transaction(ctx, func(ctx context.Context) error {
    if _, err := (Order{}).Create(ctx, map[string]any{
        "customer": "alice",
        "total":    1299,
    }); err != nil {
        return err
    }

    // Recorded into the per-tx buffer. Fires on commit; dropped on rollback.
    return events.Buffer(ctx).Dispatch(ctx, OrderPlaced{Customer: "alice"})
})
```

Nested `Transaction` calls reuse the outermost buffer (savepoint semantics): inner rollback drops only events emitted within the inner scope, outer commit flushes the rest.

## Consumer side: the relay

`orm.Relay` polls the outbox table, claims ready rows with a lease + conditional UPDATE (no `SKIP LOCKED` required), decodes the payload, and invokes one of two callbacks:

```go
relay := orm.NewRelay(manager, orm.RelayCallbacks{
    OnJob: func(ctx context.Context, payload any, payloadType, idempotencyKey string) error {
        return queueDriver.Push(ctx, payload)
    },
    OnEvent: func(ctx context.Context, payload any, payloadType, idempotencyKey string) error {
        return dispatcher.Dispatch(ctx, payload)
    },
}, orm.RelayConfig{
    PollInterval:  time.Second,
    LeaseDuration: 30 * time.Second,
    BatchSize:     32,
    WorkerCount:   4,
    MaxAttempts:   5,
    BackoffBase:   time.Second,
    BackoffMax:    5 * time.Minute,
})

if err := relay.Start(ctx); err != nil {
    log.Fatal(err)
}
defer relay.Stop(context.Background())
```

`Start(ctx)` launches the polling loop and returns immediately. Cancel the parent ctx or call `Stop(ctx)` to wind down: in-flight workers run to completion, bounded by `cfg.ShutdownGrace` (default 5s). After the grace window the relay's internal shutdown ctx is cancelled, interrupting any callback or DB writeback still in flight so `Stop` cannot hang indefinitely.

Multiple relay processes may run against the same table concurrently. Row claim uses an atomic conditional UPDATE (`leased_until IS NULL OR leased_until <= now`), so only one relay handles a row at a time even on SQLite where `SKIP LOCKED` does not exist.

### Backoff

Failed deliveries are scheduled for retry with exponential backoff capped at `BackoffMax`. The base and ceiling default to 1s and 5m respectively, matching the shape of [`queue/backoff`](/docs/core/queue/). Tune via `RelayConfig.BackoffBase` / `RelayConfig.BackoffMax`.

### DLQ

When `attempts >= MaxAttempts` the row's `dlq` column flips to true and the relay stops attempting it. DLQ rows are not visible to the polling query and never lease again until you replay them:

```go
if err := relay.Replay(ctx, rowID); err != nil {
    if errors.Is(err, orm.ErrOutboxRowNotFound) {
        // gone, e.g. already cleaned up
    }
    return err
}
```

`Replay` resets `attempts` to zero, clears the lease, sets `available_at = now`, and clears the DLQ flag so the next poll picks it up.

For inspection / admin tooling, `Manager.ListOutboxRows(ctx, limit)` returns `[]OutboxRowSnapshot` (id, kind, attempts, dlq, last error, leased_by, ...) and `Manager.CountOutboxRows(ctx)` returns the total row count. Snapshots do not include the payload, that stays opaque.

## Recipe: Atomic order placement with outbox event

A complete producer/consumer wiring for "place an order, fan out an `order.placed` event."

```go
package orders

import (
    "context"
    "database/sql"
    "log"
    "time"

    "github.com/velocitykode/velocity/orm"
)

type OrderPlaced struct {
    OrderID  uint
    Customer string
    Total    int64
    PlacedAt time.Time
}

// At app startup, before any TransactionWithOutbox call:
func init() {
    orm.RegisterPayloadType(OrderPlaced{})
}

// Producer: invoked from the HTTP handler.
func PlaceOrder(ctx context.Context, mgr *orm.Manager, customer string, total int64) error {
    return mgr.TransactionWithOutbox(ctx, func(tx *sql.Tx, outbox orm.Pending) error {
        var orderID uint
        if err := tx.QueryRowContext(ctx,
            "INSERT INTO orders (customer, total, placed_at) VALUES (?, ?, ?) RETURNING id",
            customer, total, time.Now().UTC(),
        ).Scan(&orderID); err != nil {
            return err
        }

        _, err := outbox.Dispatch(OrderPlaced{
            OrderID:  orderID,
            Customer: customer,
            Total:    total,
            PlacedAt: time.Now().UTC(),
        }, orm.WithPartitionKey("customer-"+customer))
        return err
    })
}

// Consumer: relay started once at app startup.
func StartRelay(ctx context.Context, mgr *orm.Manager) (*orm.Relay, error) {
    relay := orm.NewRelay(mgr, orm.RelayCallbacks{
        OnEvent: func(ctx context.Context, payload any, _ , idem string) error {
            evt, ok := payload.(OrderPlaced)
            if !ok {
                log.Printf("outbox: unexpected payload type %T", payload)
                return nil // permanent failure, don't retry
            }
            return notifyDownstream(ctx, evt, idem)
        },
    }, orm.RelayConfig{})

    return relay, relay.Start(ctx)
}
```

Because the `Dispatch` call lives inside the same transaction as the `INSERT`, the event row is durable the moment the order row is durable, and gone if the order is gone. The `WithPartitionKey("customer-"+customer)` ensures multiple events for the same customer are delivered in order, even when several relay workers are draining the table.

## Recipe: ORM write + outbox emit on commit

When the producer is using the ORM (not raw `*sql.Tx`), the cleanest pattern is `Manager.Transaction` for the write plus `orm.OnCommit` to enqueue an outbox row only on confirmed commit. The handler stays ctx-first, the side effect inherits the same trace ID, and the ambiguous-commit branch is left to the safe default (do nothing).

```go
func PlaceOrder(ctx context.Context, mgr *orm.Manager, customer string, total int64) error {
    ctx = orm.PrepareTxCallbacks(ctx)

    return mgr.Transaction(ctx, func(ctx context.Context) error {
        order, err := (Order{}).Create(ctx, map[string]any{
            "customer": customer,
            "total":    total,
        })
        if err != nil {
            return err
        }

        // Confirmed commit: hand the work off to the durable outbox.
        if err := orm.OnCommit(ctx, func(ctx context.Context) error {
            return mgr.TransactionWithOutbox(ctx, func(tx *sql.Tx, outbox orm.Pending) error {
                _, err := outbox.Dispatch(OrderPlaced{
                    OrderID:  order.ID,
                    Customer: customer,
                    Total:    total,
                }, orm.WithPartitionKey("customer-"+customer))
                return err
            })
        }); err != nil {
            return err
        }

        // Ambiguous commit: log only. NEVER re-enqueue here, the DB may
        // have committed the order row even though Commit returned err.
        return orm.OnCommitFailure(ctx, func(ctx context.Context, commitErr error) error {
            log.Printf("order commit ambiguous; outbox NOT re-enqueued: customer=%s error=%v",
                customer, commitErr)
            return nil
        })
    })
}
```

For the simplest case (the outbox row and the order row in the same tx), prefer the single-pass `TransactionWithOutbox` recipe above, that pattern is strictly atomic and avoids the second tx. Reach for `OnCommit` plus `TransactionWithOutbox` only when the outbox payload depends on values that are not known until after the first tx commits (e.g. an auto-generated id you want to read back through the ORM rather than via `RETURNING`).

## Related

- [Global Query Scopes](/docs/database/scopes/) - the other ORM primitive shipped alongside the outbox; soft-delete is implemented on top of it
- [CRUD](/docs/database/crud/) - regular `Manager.Transaction` for writes that do not need a side-effect commit
- [Queue](/docs/core/queue/) - durable background jobs the relay's `OnJob` callback typically pushes into
- [Events](/docs/core/events/) - in-process event dispatcher the `OnEvent` callback typically forwards to


================================================================================
# Broadcasting

Source: https://vel.build/docs/realtime/broadcast/
Section: Real-time Features
Summary: Broadcast events to multiple clients with public, private, and presence channels in Velocity.


Velocity provides a powerful broadcasting system for real-time event communication built on top of WebSockets. It enables you to broadcast events to multiple connected clients with support for public, private, and presence channels.

## Quick Start


**Built on WebSockets**: The broadcast package provides a high-level API over Velocity's WebSocket server for event-driven real-time communication.


All broadcasting goes through a `*broadcast.BroadcastManager`, which you create with `broadcast.New(driver)`. The examples below assume `b` is a configured manager (see [Configuration](#configuration)).




```go
import (
    "context"

    "github.com/velocitykode/velocity/broadcast"
)

func broadcastOrder(b *broadcast.BroadcastManager, ctx context.Context, orderData any) error {
    // Broadcast to a public channel
    if err := b.Channel("orders").EmitCtx(ctx, "OrderShipped", map[string]interface{}{
        "order_id": 12345,
        "tracking": "ABC123",
    }); err != nil {
        return err
    }

    // Broadcast to multiple channels
    return b.Channel("orders", "notifications").EmitCtx(ctx, "OrderUpdate", orderData)
}
```



```go
import (
    "context"
    "time"

    "github.com/velocitykode/velocity/broadcast"
)

func broadcastAccount(b *broadcast.BroadcastManager, ctx context.Context) error {
    // Broadcast to a private channel (subscribers see "private-user.123")
    return b.Private("user.123").EmitCtx(ctx, "AccountUpdate", map[string]interface{}{
        "balance":    1500.00,
        "updated_at": time.Now(),
    })
}
```



```go
import (
    "context"
    "time"

    "github.com/velocitykode/velocity/broadcast"
)

func broadcastMessage(b *broadcast.BroadcastManager, ctx context.Context) error {
    // Broadcast to a presence channel (subscribers see "presence-chat.room.1")
    return b.Presence("chat.room.1").EmitCtx(ctx, "MessageSent", map[string]interface{}{
        "user":      "John",
        "message":   "Hello everyone!",
        "timestamp": time.Now(),
    })
}
```





**Context-aware emit**: `EmitCtx` threads the caller's `context.Context` through the send so a slow client cannot pin the request goroutine. The older `Emit(event, data)` method is **deprecated**: it now delegates to `EmitCtx` with `context.Background()`. Prefer `EmitCtx`, or chain `WithContext(ctx)` on the builder before calling `Emit`.


## Configuration

The broadcasting system is configured programmatically. Build a `websocket.Config`, wrap it in a WebSocket driver, and hand the driver to `broadcast.New`:

```go
import (
    "time"

    "github.com/velocitykode/velocity/broadcast"
    "github.com/velocitykode/velocity/broadcast/drivers"
    "github.com/velocitykode/velocity/websocket"
)

func newBroadcaster() *broadcast.BroadcastManager {
    config := websocket.Config{
        Host:           "0.0.0.0",
        Port:           6001,
        Path:           "/ws",
        AllowedOrigins: []string{"http://localhost:4000", "http://localhost:8090"},
        PingInterval:   30 * time.Second,
        PongTimeout:    60 * time.Second,
        WriteTimeout:   10 * time.Second,
        MaxMessageSize: 512 * 1024, // 512 KiB
    }

    driver := drivers.NewWebSocketDriver(config)
    return broadcast.New(driver)
}
```


**Secure defaults**: `broadcast.New` installs a deny-all authorizer, so private- and presence- channel access is rejected until you call `SetAuthorizer`. The WebSocket driver also applies a per-client inbound message rate limit (`Config.MessageRateLimit`, defaulting from the zero value) and per-subscribe channel caps. Set `MessageRateLimit` to a negative value to opt out, and `AllowEmptyOrigin: true` only for trusted non-browser clients.


### Driver Options

`NewWebSocketDriver` accepts variadic `DriverOption` values to tune fan-out behavior:

```go
driver := drivers.NewWebSocketDriver(config,
    drivers.WithMaxChannelsPerClient(100),         // cap distinct channels per connection
    drivers.WithMaxChannelNameLength(200),         // cap subscribe channel-name length
    drivers.WithBlockingSend(50*time.Millisecond), // block up to a timeout instead of dropping on a full send buffer
    drivers.WithOnDrop(func(clientID, channel, event string) {
        // observe dropped messages
    }),
)
```

## Channel Types

### Public Channels

Public channels are accessible to all connected clients without authentication:

```go
// Anyone can subscribe to "orders" channel
b.Channel("orders").EmitCtx(ctx, "NewOrder", order)

// Broadcast to multiple public channels
b.Channel("orders", "notifications").EmitCtx(ctx, "OrderCreated", order)
```

### Private Channels

Private channels require authorization before clients can subscribe:

```go
// Broadcast to private user channel
userID := 123
b.Private(fmt.Sprintf("user.%d", userID)).EmitCtx(ctx, "PrivateMessage", message)

// Private channels are prefixed with "private-"
// Client subscribes to: "private-user.123"
```

### Presence Channels

Presence channels track which users are subscribed to the channel:

```go
// Broadcast to presence channel
b.Presence("chat.room.1").EmitCtx(ctx, "MessageSent", message)

// Presence channels are prefixed with "presence-"
// Client subscribes to: "presence-chat.room.1"
```

## Broadcasting Events

### Manual Broadcasting

Directly broadcast events to channels:

```go
import (
    "context"

    "github.com/velocitykode/velocity/broadcast"
)

func shipOrder(b *broadcast.BroadcastManager, ctx context.Context, orderID int) error {
    // Process order...

    // Broadcast shipping notification
    return b.Channel("orders").EmitCtx(ctx, "OrderShipped", map[string]interface{}{
        "order_id":        orderID,
        "status":          "shipped",
        "tracking_number": "ABC123",
    })
}
```

### Conditional Broadcasting

Broadcast only when certain conditions are met:

```go
// Broadcast to others (exclude sender by socket ID)
b.Channel("chat.room.1").
    ToOthers(socketID).
    EmitCtx(ctx, "UserTyping", username)

// Conditional broadcasting: When(false) makes Emit a no-op
b.Channel("orders").
    When(order.Status == "shipped").
    EmitCtx(ctx, "OrderUpdate", order)
```

### Event Interface

The `broadcast.Event` interface defines a standard shape for broadcastable events. Types that implement it describe which channels to broadcast on, the event name, the payload, and an optional condition. You wire the dispatch yourself by reading these methods and calling the manager:

```go
import (
    "context"

    "github.com/velocitykode/velocity/broadcast"
)

// dispatch broadcasts an Event across its channels using the manager.
func dispatch(b *broadcast.BroadcastManager, ctx context.Context, e broadcast.Event) error {
    if !e.BroadcastWhen() {
        return nil
    }
    return b.Channel(e.BroadcastOn()...).EmitCtx(ctx, e.BroadcastAs(), e.BroadcastWith())
}
```

An event type implements the four interface methods:

```go
type OrderShipped struct {
    OrderID  int    `json:"order_id"`
    Tracking string `json:"tracking"`
    UserID   int    `json:"-"`  // Excluded from broadcast
}

// BroadcastOn returns channels to broadcast on
func (e OrderShipped) BroadcastOn() []string {
    return []string{
        "orders",
        fmt.Sprintf("user.%d", e.UserID),
    }
}

// BroadcastAs returns the event name
func (e OrderShipped) BroadcastAs() string {
    return "order.shipped"
}

// BroadcastWith returns the data to broadcast
func (e OrderShipped) BroadcastWith() interface{} {
    return map[string]interface{}{
        "order_id": e.OrderID,
        "tracking": e.Tracking,
    }
}

// BroadcastWhen returns whether to broadcast
func (e OrderShipped) BroadcastWhen() bool {
    return e.Tracking != ""  // Only if tracking exists
}
```

## Channel Authorization

### Setting Up Authorization

`broadcast.New` installs a deny-all authorizer by default, so every private- and presence- channel is rejected until you install your own with `SetAuthorizer`. Public channels bypass the authorizer entirely.

```go
import (
    "fmt"
    "strings"

    "github.com/velocitykode/velocity/broadcast"
)

func setupAuthorization(b *broadcast.BroadcastManager) {
    // Authorizer signature: func(channel string, user interface{}) bool
    b.SetAuthorizer(func(channel string, user interface{}) bool {
        // Authorize private user channels
        if strings.HasPrefix(channel, "private-user.") {
            userID := strings.TrimPrefix(channel, "private-user.")
            currentUser := user.(*User)
            return fmt.Sprintf("%d", currentUser.ID) == userID
        }

        // Authorize presence channels
        if strings.HasPrefix(channel, "presence-chat.") {
            // Check if user can access this chat room
            return checkChatAccess(user, channel)
        }

        // Deny access by default
        return false
    })

    // PresenceDataFunc returns the data published for a presence member.
    b.SetPresenceData(func(channel string, user interface{}) interface{} {
        u := user.(*User)
        return map[string]interface{}{
            "id":     u.ID,
            "name":   u.Name,
            "avatar": u.AvatarURL,
        }
    })
}
```

### Authorizing Subscriptions

When a client wants to join a private- or presence- channel, it first calls your HTTP auth endpoint. Resolve the authorization (and, for presence channels, the channel data) with `Auth`:

```go
// Auth returns the payload to send back to the client, or ErrUnauthorized.
payload, err := b.Auth(channel, socketID, currentUser)
if err != nil {
    // err is broadcast.ErrUnauthorized when the authorizer denies access
    return ctx.JSON(403, map[string]string{"error": "forbidden"})
}
return ctx.JSON(200, payload)
```

### Signed Auth Tokens

By default the authorizer verdict alone gates a subscription. To cryptographically bind an authorized verdict to a specific socket (so a leaked verdict cannot be replayed on another connection), install an HMAC secret with `SetAuthSecret`:

```go
b.SetAuthSecret([]byte(secret)) // 32+ random bytes recommended
```

With a secret installed:

- `Auth` includes an `"auth"` field carrying `hex(HMAC-SHA256(socketID ":" channel))`. For presence channels the response is `{"auth": ..., "channel_data": ...}`.
- The WebSocket driver is auto-wired to require and verify that token on every private/presence subscribe (when the driver implements `TokenVerifierSetter`, which the built-in driver does). Calling `SetAuthSecret` with an empty slice clears the secret and returns the driver to authorizer-only mode.

Helpers for custom flows: `SignAuthToken(socketID, channel)` produces the token (or `ErrUnauthorized` if no secret is set), `VerifyAuthToken(socketID, channel, token)` checks it in constant time, and the package-level `broadcast.SecureCompareToken(a, b)` offers a constant-time string comparison for custom authorizers.

## WebSocket Driver

The default WebSocket driver provides real-time communication:

```go
import (
    "context"
    "time"

    "github.com/velocitykode/velocity/broadcast"
    "github.com/velocitykode/velocity/broadcast/drivers"
    "github.com/velocitykode/velocity/websocket"
)

func main() {
    // Configure WebSocket server
    config := websocket.Config{
        Host:           "0.0.0.0",
        Port:           6001,
        Path:           "/ws",
        AllowedOrigins: []string{"http://localhost:4000"},
        PingInterval:   30 * time.Second,
        PongTimeout:    60 * time.Second,
        WriteTimeout:   10 * time.Second,
        MaxMessageSize: 512 * 1024, // 512 KiB
    }

    // Create WebSocket driver
    driver := drivers.NewWebSocketDriver(config)

    // Create broadcaster with driver
    broadcaster := broadcast.New(driver)

    // Use broadcaster
    broadcaster.Channel("events").EmitCtx(context.Background(), "TestEvent", "Hello WebSocket!")
}
```

## Client-Side Integration

### JavaScript Client Example

```javascript
// Connect to WebSocket server
const ws = new WebSocket('ws://localhost:6001/ws');

ws.onopen = () => {
    console.log('Connected to WebSocket');

    // Subscribe to a public channel
    ws.send(JSON.stringify({
        type: 'subscribe',
        data: {
            channel: 'orders'
        }
    }));

    // Subscribe to a private channel
    ws.send(JSON.stringify({
        type: 'subscribe',
        data: {
            channel: 'private-user.123',
            auth: authToken  // Include auth token
        }
    }));
};

ws.onmessage = (event) => {
    const message = JSON.parse(event.data);

    switch (message.type) {
        case 'subscription_succeeded':
            console.log('Subscribed to:', message.data.channel);
            break;

        case 'order.shipped':
            console.log('Order shipped:', message.data);
            updateOrderUI(message.data);
            break;

        default:
            console.log('Received event:', message.type, message.data);
    }
};

ws.onerror = (error) => {
    console.error('WebSocket error:', error);
};

ws.onclose = () => {
    console.log('WebSocket connection closed');
};
```

## Advanced Usage

### Getting Channel Clients

`GetClients` lives on the driver and returns the **opaque** client identifiers subscribed to a channel. The IDs are derived per-channel from a process-local random seed, so raw socket IDs never leak across channels:

```go
import "github.com/velocitykode/velocity/broadcast/drivers"

func getChannelInfo(driver *drivers.WebSocketDriver, channelName string) {
    // Opaque per-channel client IDs (not raw socket IDs)
    clients := driver.GetClients(channelName)

    log.Info("Channel info",
        "channel", channelName,
        "client_count", len(clients),
    )
}
```

### Custom Driver Implementation

Create a custom broadcast driver by implementing the `Driver` interface:

```go
type Driver interface {
    // BroadcastCtx sends an event to channels. A ctx whose Err() is
    // already non-nil at call time MUST return that error before any send.
    BroadcastCtx(ctx context.Context, channels []string, event string, data interface{}) error

    // Deprecated: use BroadcastCtx with a request-scoped context.Context.
    Broadcast(channels []string, event string, data interface{}) error

    // BroadcastExceptCtx broadcasts to all except the specified socket,
    // honouring the same ctx-cancellation contract as BroadcastCtx.
    BroadcastExceptCtx(ctx context.Context, channels []string, event string, data interface{}, socketID string) error

    // Deprecated: use BroadcastExceptCtx with a request-scoped context.Context.
    BroadcastExcept(channels []string, event string, data interface{}, socketID string) error

    // GetClients returns the clients in a channel.
    GetClients(channel string) []string
}
```

The `Ctx` and non-`Ctx` methods come in pairs: the `Ctx` variant threads the caller's context so a slow client cannot pin the request goroutine, and the deprecated non-`Ctx` shim delegates to it with `context.Background()`. New driver implementations should put their logic in the `Ctx` methods. Implementations must pass `broadcasttest.RunDriverContractTests`, the package's executable specification.

Drivers may also implement `broadcast.TokenVerifierSetter` to opt into the framework's HMAC subscribe-time token verification (the built-in WebSocket driver does):

```go
type TokenVerifierSetter interface {
    SetTokenVerifier(fn func(socketID, channel, token string) bool)
}
```

Example custom driver:

```go
type RedisDriver struct {
    client *redis.Client
}

func (d *RedisDriver) BroadcastCtx(ctx context.Context, channels []string, event string, data interface{}) error {
    if err := ctx.Err(); err != nil {
        return err
    }

    message := map[string]interface{}{
        "event": event,
        "data":  data,
    }

    payload, _ := json.Marshal(message)

    for _, channel := range channels {
        if err := d.client.Publish(ctx, channel, payload).Err(); err != nil {
            return err
        }
    }

    return nil
}

// Deprecated shim required by the Driver interface.
func (d *RedisDriver) Broadcast(channels []string, event string, data interface{}) error {
    return d.BroadcastCtx(context.Background(), channels, event, data)
}
```

## Integration with HTTP Routes

### Broadcasting from Handlers

Inject the manager into your handler (for example as a struct field), then emit with the request's context:

```go
import (
    "github.com/velocitykode/velocity/broadcast"
    "github.com/velocitykode/velocity/router"
)

type OrderHandler struct {
    Broadcaster *broadcast.BroadcastManager
}

func (c *OrderHandler) Ship(ctx *router.Context) error {
    orderID := ctx.Param("id")

    // Ship the order
    order, err := shipOrder(orderID)
    if err != nil {
        return ctx.Error(500, "Failed to ship order")
    }

    // Broadcast shipping notification
    c.Broadcaster.Channel("orders").EmitCtx(ctx.Request.Context(), "OrderShipped", map[string]interface{}{
        "order_id": order.ID,
        "tracking": order.TrackingNumber,
    })

    return ctx.JSON(200, order)
}
```

## Best Practices

1. **Channel Naming**: Use consistent naming conventions (e.g., `resource.action.id`)
2. **Authorization**: Always authorize private and presence channels
3. **Data Size**: Keep broadcast payloads small for better performance
4. **Error Handling**: Handle broadcast errors gracefully
5. **Security**: Validate all user input before broadcasting
6. **Rate Limiting**: Implement rate limiting for broadcast operations
7. **Connection Management**: Handle disconnections and reconnections properly

## Examples

### Real-Time Chat

```go
func (c *ChatHandler) SendMessage(ctx *router.Context) error {
    var msg struct {
        RoomID  string `json:"room_id"`
        Message string `json:"message"`
    }

    if err := ctx.Bind(&msg); err != nil {
        return err
    }

    // Broadcast to presence channel, excluding the sending socket
    c.Broadcaster.Presence(fmt.Sprintf("chat.%s", msg.RoomID)).
        ToOthers(ctx.Request.Header.Get("X-Socket-ID")).
        EmitCtx(ctx.Request.Context(), "MessageSent", map[string]interface{}{
            "user_id":   currentUser.GetAuthIdentifier(),
            "message":   msg.Message,
            "timestamp": time.Now(),
        })

    return ctx.JSON(200, map[string]string{"status": "sent"})
}
```

### Live Notifications

```go
func (c *NotificationHandler) SendNotification(ctx context.Context, userID int, notification Notification) {
    // Broadcast to user's private channel
    c.Broadcaster.Private(fmt.Sprintf("user.%d", userID)).
        EmitCtx(ctx, "NewNotification", map[string]interface{}{
            "id":      notification.ID,
            "title":   notification.Title,
            "message": notification.Message,
            "type":    notification.Type,
        })
}
```

### Live Dashboard Updates

```go
func (c *DashboardHandler) UpdateMetrics(ctx context.Context) {
    metrics := calculateMetrics()

    // Broadcast to admin dashboard channel
    c.Broadcaster.Channel("admin.dashboard").EmitCtx(ctx, "MetricsUpdated", map[string]interface{}{
        "active_users": metrics.ActiveUsers,
        "total_orders": metrics.TotalOrders,
        "revenue":      metrics.Revenue,
        "updated_at":   time.Now(),
    })
}
```


================================================================================
# WebSockets

Source: https://vel.build/docs/realtime/websockets/
Section: Real-time Features
Summary: Real-time bidirectional communication - typed message handlers, groups, broadcasts, and per-client metadata.


The `websocket` package provides a typed WebSocket server with
message routing, group membership for fan-out, per-client metadata,
authentication hooks, and built-in rate limiting.

Import path: `github.com/velocitykode/velocity/websocket`

## Quick start

```go
import "github.com/velocitykode/velocity/websocket"

cfg := websocket.DefaultConfig()
cfg.Host = "0.0.0.0"
cfg.Port = 6001
cfg.Path = "/ws"

srv := websocket.New(cfg)

// The server already enqueues a built-in "welcome" message on connect
// (see below); send your own app-level greeting under a distinct type.
srv.OnConnect(func(c *websocket.Client) {
    c.SendJSON("ready", map[string]any{
        "client_id": c.ID,
        "message":   "connected",
    })
})

srv.On("chat", func(c *websocket.Client, msg websocket.Message) error {
    return srv.Broadcast(websocket.Message{
        Type: "chat",
        From: c.ID,
        Data: msg.Data,
    })
})

if err := srv.Start(); err != nil {
    log.Fatal(err)
}
```

`Start` launches the internal dispatcher goroutine. To accept
connections, mount `srv.HandleConnection` on an HTTP route - see
[Mounting](#mounting-on-an-http-route) below.

On registration the server automatically enqueues a `welcome`
message to each client carrying its assigned ID:

```json
{ "type": "welcome", "data": { "id": "<client-id>", "version": "1.0.0" } }
```

To stop the server, call `Shutdown` with a context that bounds how
long it waits for the dispatcher and every per-client read/write
pump to drain:

```go
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
    log.Error("ws shutdown timed out", "err", err)
}
```

`Shutdown` is safe to call more than once; subsequent calls are
no-ops that return nil.

## Configuration

`DefaultConfig()` provides reasonable defaults. Override what you
need:

```go
cfg := websocket.Config{
    Host:             "0.0.0.0",
    Port:             6001,
    Path:             "/ws",
    AllowedOrigins:   []string{"https://example.com"},
    MaxConnections:   10000,
    ReadBufferSize:   1024,
    WriteBufferSize:  1024,
    MaxMessageSize:   512 * 1024, // 512KB
    PingInterval:     30 * time.Second,
    PongTimeout:      60 * time.Second,
    WriteTimeout:     10 * time.Second,
    MessageRateLimit: 100, // msgs/sec per client (0 = secure default, -1 = unlimited)
    MessageBurstSize: 200, // 0 defaults to 2x MessageRateLimit
    AuthFunc: func(r *http.Request) error {
        if r.URL.Query().Get("token") == "" {
            return errors.New("missing token")
        }
        return nil
    },
}
```

`AuthFunc` runs **before** the WebSocket upgrade - return a non-nil
error to reject the handshake.


Rate limiting is **opt-out**, not opt-in. Leaving `MessageRateLimit`
at its zero value installs the secure default
(`websocket.DefaultMessageRateLimit`, 10 msgs/sec) so an
unconfigured deployment is never silently unthrottled. To run with no
rate limit, set `MessageRateLimit` to a negative value (e.g. `-1`).
See [Rate limiting](#rate-limiting).


### Origin checks

When `AllowedOrigins` is empty (the default), only **same-origin**
upgrades are accepted: the request's `Origin` host must match its
`Host`, case-insensitively, and the scheme must be `http`/`https`.
Set `AllowedOrigins: []string{"*"}` to allow every origin, or list
specific origins to allow them exactly.

Browsers always send an `Origin` header on WebSocket upgrades, so a
missing `Origin` almost always means a non-browser client (curl, a
custom Go/Python client). Such requests are rejected by default. Set
`AllowEmptyOrigin: true` to admit them for trusted non-browser
integrations.

## Mounting on an HTTP route

`HandleConnection` upgrades the connection and registers the client.
Wire it into your Velocity routes:

```go
v.Routes(func(r *velocity.Routing) {
    r.Web(func(web router.Router) {
        web.Get("/ws", func(c *router.Context) error {
            srv.HandleConnection(c.Response, c.Request)
            return nil
        })
    })
})
```

Or attach to a stdlib mux:

```go
http.HandleFunc("/ws", srv.HandleConnection)
```

### Taking over the raw connection

`HandleRaw` upgrades the HTTP request to a WebSocket and hands back
the raw `*websocket.Conn` without registering a managed client,
starting read/write pumps, or entering the message-routing system.
The caller owns the connection - reading, writing, and closing it:

```go
web.Get("/ws/raw", func(c *router.Context) error {
    conn, err := srv.HandleRaw(c.Response, c.Request)
    if err != nil {
        return err
    }
    defer conn.Close()
    // drive conn directly...
    return nil
})
```

## Messages

A message is a JSON envelope:

```go
type Message struct {
    Type   string `json:"type"`             // routing key
    Data   any    `json:"data"`             // payload
    Target string `json:"target,omitempty"` // client ID for direct sends
    From   string `json:"from,omitempty"`   // sender client ID
}
```

### Routing incoming messages

Register handlers per message type:

```go
srv.On("chat", func(c *websocket.Client, msg websocket.Message) error {
    text, _ := msg.Data.(map[string]any)["text"].(string)
    return srv.Broadcast(websocket.Message{
        Type: "chat",
        From: c.ID,
        Data: map[string]any{"text": text},
    })
})

srv.On("join", func(c *websocket.Client, msg websocket.Message) error {
    room, _ := msg.Data.(map[string]any)["room"].(string)
    return srv.JoinGroup(c.ID, room)
})
```

When a message arrives with no registered handler, the server replies
to that client with a generic `error` message (`{"message": "unknown
message type"}`) - register handlers for everything you expect to
receive. Likewise, if a handler returns a non-nil error and no
`OnError` callback is set, the client receives a generic `error`
message (`{"message": "internal error"}`); internal error details are
never reflected back to the client.

### Sending to one client

```go
client.SendJSON("notification", map[string]any{
    "title": "New message",
    "body":  "Alice sent you a DM",
})

// Or build the Message yourself:
client.SendMessage(websocket.Message{
    Type: "ping",
    Data: time.Now().Unix(),
})
```

`SendJSON` and `SendMessage` are non-blocking - they enqueue on the
client's bounded send channel and return immediately. If that channel
is full they return `websocket.ErrSendChannelFull` rather than
blocking, so check the error when delivery matters:

```go
if err := client.SendJSON("ping", nil); err != nil {
    // websocket.ErrSendChannelFull - slow consumer, message dropped
}
```

The package also exports `ErrServerNotRunning`, `ErrClientNotFound`,
`ErrGroupNotFound`, `ErrConnectionLimit`, and `ErrInvalidMessage` for
matching with `errors.Is`.

### Broadcast to everyone

```go
srv.Broadcast(websocket.Message{
    Type: "announce",
    Data: "Server restart in 5 minutes",
})
```

### Send to a specific client by ID

```go
if err := srv.SendToClient("client-42", msg); err != nil {
    // client not found
}
```

## Groups (rooms)

Groups are server-side bags of clients. Join, leave, and broadcast
into them.

### Membership

```go
srv.JoinGroup(client.ID, "room-1")
srv.LeaveGroup(client.ID, "room-1")
srv.LeaveAllGroups(client.ID)  // typically called on disconnect

if client.IsInGroup("room-1") {
    // ...
}
```

### Broadcasting

```go
// Send to every client in the group
srv.BroadcastToGroup("room-1", websocket.Message{
    Type: "chat",
    Data: map[string]any{"text": "Hello room"},
})

// Same as Broadcast but with explicit semantics
srv.SendToGroup("room-1", msg)

// Skip the sender
srv.SendToOthersInGroup("room-1", senderID, msg)
```

### Inspecting groups

```go
clients := srv.GetGroupMembers("room-1")  // []*Client
ids     := srv.GetGroupMemberIDs("room-1")
groups  := srv.GetGroups()                 // all group names
n       := srv.GetGroupCount()             // number of groups
empty   := srv.IsGroupEmpty("room-1")
```

## Lifecycle callbacks

```go
srv.OnConnect(func(c *websocket.Client) {
    log.Info("connected", "id", c.ID)
})

srv.OnDisconnect(func(c *websocket.Client) {
    srv.LeaveAllGroups(c.ID)
    log.Info("disconnected", "id", c.ID)
})

srv.OnError(func(c *websocket.Client, err error) {
    log.Error("client error", "id", c.ID, "err", err)
})
```

`OnConnect`, `OnDisconnect`, and `OnError` each hold a single
callback; calling them again replaces the previous one (pass `nil`
to clear). When you need *several* disconnect observers - for example
an adapter that purges its own state - register them with
`AddOnDisconnect`:

```go
srv.AddOnDisconnect(func(c *websocket.Client) {
    metrics.ClientGone(c.ID)
})
```

Added listeners fire in registration order, alongside the single
`OnDisconnect` callback, **before** the client's send channel is
closed.

## Per-client metadata

Stash request-scoped data on the client itself:

```go
srv.OnConnect(func(c *websocket.Client) {
    user, err := authenticateFromQuery(c.Conn)
    if err != nil {
        c.Close()
        return
    }
    c.SetMetadata("user_id", user.ID)
    c.SetMetadata("plan", user.Plan)
})

srv.On("admin:purge", func(c *websocket.Client, msg websocket.Message) error {
    plan, ok := c.GetMetadata("plan")
    if !ok || plan != "admin" {
        return c.SendJSON("error", map[string]any{"reason": "forbidden"})
    }
    return runPurge()
})
```

## Middleware

Wrap message handlers with cross-cutting concerns:

```go
logging := func(next websocket.MessageHandler) websocket.MessageHandler {
    return func(c *websocket.Client, msg websocket.Message) error {
        log.Info("ws.recv", "client", c.ID, "type", msg.Type)
        err := next(c, msg)
        if err != nil {
            log.Warn("ws.handler.err", "client", c.ID, "err", err)
        }
        return err
    }
}

srv.Use(logging)
```

Middleware runs in registration order around every dispatched
message.

## Authentication

Two layers:

1. **Pre-upgrade** - `Config.AuthFunc(*http.Request) error`. Reject
   the WebSocket handshake before the connection is established.
   Read tokens from headers, query strings, or cookies.

2. **Post-upgrade** - inside `OnConnect` or a message handler. Stash
   the user via `SetMetadata`; gate handlers by reading the metadata.

```go
cfg.AuthFunc = func(r *http.Request) error {
    token := r.Header.Get("Authorization")
    if !validateToken(token) {
        return errors.New("invalid token")
    }
    return nil
}
```

Pre-upgrade auth is preferred - rejected requests never consume a
client slot.

## Rate limiting

Built into the config - no external code needed:

```go
cfg.MessageRateLimit = 50  // msgs/sec
cfg.MessageBurstSize  = 100 // 0 defaults to 2x the rate limit
```

When a client exceeds the burst within a one-second window, the
server sends it a final `error` message (`{"message": "rate limit
exceeded"}`) and closes the connection.

The zero value of `MessageRateLimit` installs the secure default
(`websocket.DefaultMessageRateLimit`, 10 msgs/sec). To turn rate
limiting **off**, set a negative value:

```go
cfg.MessageRateLimit = -1 // explicit opt-out, no rate limit
```

## Stats

```go
stats := srv.GetStats()
log.Info("ws stats",
    "clients", stats.ConnectedClients,
    "sent",    stats.MessagesSent,
    "recv",    stats.MessagesReceived,
    "bytes_in", stats.BytesReceived,
    "bytes_out", stats.BytesSent,
)
```

Read-only snapshot. Useful for `/health` endpoints and Prometheus
exporters.

`RecoveredPanics()` returns how many times the dispatcher's internal
recover has caught a panic in a single handler dispatch - a useful
gauge to alert on:

```go
if n := srv.RecoveredPanics(); n > 0 {
    log.Warn("ws handler panics recovered", "count", n)
}
```

## Logging

The server stays decoupled from the framework's `log` package: it
logs operational events (connects, disconnects, rate-limit
violations, recovered panics) through a minimal interface. Install a
logger with `SetLogger`; the framework's `log.Logger` satisfies it
directly. Logging is off until a logger is set, and passing `nil`
disables it again:

```go
// logger satisfies websocket.Logger (Info/Warn/Error(msg, kvs ...any)).
srv.SetLogger(logger)
```

Any value implementing `websocket.Logger` works:

```go
type Logger interface {
    Info(msg string, kvs ...any)
    Warn(msg string, kvs ...any)
    Error(msg string, kvs ...any)
}
```

`SetLogger` is safe to call concurrently.

## Inspecting clients

```go
client, ok := srv.GetClient("client-42")
if ok {
    client.SendJSON("ping", nil)
}

all := srv.GetClients()  // map[string]*Client - copy of the live set
log.Info("connected", "n", len(all))
```

## Frontend (browser) example

```javascript
const ws = new WebSocket('wss://example.com/ws?token=' + token);

ws.onopen = () => {
    ws.send(JSON.stringify({ type: 'join', data: { room: 'lobby' } }));
};

ws.onmessage = (ev) => {
    const msg = JSON.parse(ev.data);
    switch (msg.type) {
        case 'welcome':
            // built-in welcome envelope: { id, version }
            console.log('connected as', msg.data.id);
            break;
        case 'ready':
            console.log('app ready for', msg.data.client_id);
            break;
        case 'chat':
            renderChat(msg.from, msg.data.text);
            break;
    }
};

function send(type, data) {
    ws.send(JSON.stringify({ type, data }));
}
```

The wire shape matches the Go `Message` struct directly - `type`,
`data`, optional `target` and `from`.

## Testing

Spin up a server on port 0 (OS-assigned) and connect with the
gorilla-websocket dialer:

```go
import gws "github.com/gorilla/websocket"

func TestEcho(t *testing.T) {
    cfg := websocket.DefaultConfig()
    cfg.Port = 0
    cfg.Path = "/ws"

    srv := websocket.New(cfg)
    received := make(chan websocket.Message, 1)

    srv.On("echo", func(c *websocket.Client, m websocket.Message) error {
        received <- m
        return c.SendMessage(m)
    })

    if err := srv.Start(); err != nil {
        t.Fatal(err)
    }
    defer srv.Shutdown(context.Background())

    ts := httptest.NewServer(http.HandlerFunc(srv.HandleConnection))
    defer ts.Close()

    url := "ws" + strings.TrimPrefix(ts.URL, "http") + "/ws"
    conn, _, err := gws.DefaultDialer.Dial(url, nil)
    if err != nil {
        t.Fatal(err)
    }
    defer conn.Close()

    if err := conn.WriteJSON(websocket.Message{Type: "echo", Data: "hi"}); err != nil {
        t.Fatal(err)
    }

    select {
    case got := <-received:
        if got.Type != "echo" || got.Data != "hi" {
            t.Errorf("got %+v", got)
        }
    case <-time.After(time.Second):
        t.Fatal("timeout")
    }
}
```

## Design notes

- **Groups, not rooms.** Every set-of-clients abstraction is a group.
  Use any naming convention you like (`room:lobby`, `tenant:42`,
  `private-user.42`) - they're just strings.
- **One dispatcher goroutine.** The server runs a single goroutine
  fanning out broadcast/register/unregister channel events. Per-client
  read and write pumps run independently.
- **Channel-based send.** `SendJSON` and `SendMessage` enqueue on the
  client's bounded send channel - they're safe to call from any
  goroutine and don't block on slow consumers (full channels drop
  the client).


================================================================================
# Storage

Source: https://vel.build/docs/advanced/storage/
Section: Advanced Topics
Summary: Store and retrieve files with Velocity's unified storage manager for local filesystem and Amazon S3.


Velocity provides a unified storage interface for file operations across different backends including local filesystem and Amazon S3. The storage system uses a driver-based architecture that allows you to switch storage backends through configuration without changing your code.

Storage is exposed as a **manager** that holds one or more named disks. You obtain the manager from the request context (`c.Storage()`) or from `app.Services.Storage`, select a disk with `Disk(name)` or `Default()`, and call methods on the returned driver. Every I/O method comes in two forms: a context-aware `Ctx` variant that threads the request's `context.Context` through to the backend (so a slow S3 GET or a hung write can be cancelled), and a deprecated non-`Ctx` shim. **New code should always call the `Ctx` variants.**

## Quick Start


**Configured from your environment**: When you build your app, Velocity wires a storage manager from your `.env` file (a `local` disk is always configured, and an `s3` disk is added when `AWS_BUCKET` is set). Retrieve it with `c.Storage()` inside a handler.





```go
import "github.com/velocitykode/velocity/router"

func uploadAvatar(c *router.Context, userID int, imageData []byte) error {
    disk, err := c.Storage().Default()
    if err != nil {
        return err
    }

    path := fmt.Sprintf("avatars/user-%d.jpg", userID)
    return disk.PutCtx(c.Request.Context(), path, imageData)
}

func getAvatar(c *router.Context, userID int) ([]byte, error) {
    disk, err := c.Storage().Default()
    if err != nil {
        return nil, err
    }

    path := fmt.Sprintf("avatars/user-%d.jpg", userID)
    return disk.GetCtx(c.Request.Context(), path)
}

func deleteAvatar(c *router.Context, userID int) error {
    disk, err := c.Storage().Default()
    if err != nil {
        return err
    }

    path := fmt.Sprintf("avatars/user-%d.jpg", userID)
    return disk.DeleteCtx(c.Request.Context(), path)
}
```



```go
import (
    "io"
    "os"

    "github.com/velocitykode/velocity/router"
)

func uploadVideo(c *router.Context, videoPath string) error {
    disk, err := c.Storage().Default()
    if err != nil {
        return err
    }

    // Open file for streaming
    file, err := os.Open(videoPath)
    if err != nil {
        return err
    }
    defer file.Close()

    // Stream large files efficiently
    return disk.PutStreamCtx(c.Request.Context(), "videos/intro.mp4", file)
}

func downloadVideo(c *router.Context, outputPath string) error {
    disk, err := c.Storage().Default()
    if err != nil {
        return err
    }

    // Get file as stream
    stream, err := disk.GetStreamCtx(c.Request.Context(), "videos/intro.mp4")
    if err != nil {
        return err
    }
    defer stream.Close()

    // Write to file
    out, err := os.Create(outputPath)
    if err != nil {
        return err
    }
    defer out.Close()

    _, err = io.Copy(out, stream)
    return err
}
```



```go
import (
    "time"

    "github.com/velocitykode/velocity/router"
)

func handleDownload(c *router.Context) error {
    disk, err := c.Storage().Disk("s3")
    if err != nil {
        return err
    }

    reportPath := "reports/monthly-report.pdf"

    // Permanent public URL (pure string operation, no context needed).
    publicURL := disk.URL(reportPath)
    _ = publicURL

    // Temporary signed URL valid for 30 minutes (S3 only).
    url, err := disk.TemporaryURLCtx(c.Request.Context(), reportPath, 30*time.Minute)
    if err != nil {
        return err
    }

    return c.JSON(200, map[string]string{
        "download_url": url,
    })
}
```




## Configuration

Storage is configured from environment variables when your app is built. A `local` disk is always configured; an `s3` disk is added automatically when `AWS_BUCKET` is set.

```env
# Default disk
STORAGE_DRIVER=local           # Options: local, s3

# Local disk configuration
FILESYSTEM_LOCAL_ROOT=./storage/app

# S3 disk configuration (only configured when AWS_BUCKET is set)
AWS_BUCKET=my-app-bucket
AWS_DEFAULT_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_URL=https://my-bucket.s3.amazonaws.com
```


The `STORAGE_DRIVER` value names the default disk (`local` or `s3`). `FILESYSTEM_LOCAL_ROOT` defaults to `./storage/app`. Relative roots are resolved against the working directory at startup.


For full programmatic control, build a `storage.Config` and configure a manager yourself (see [Custom Disk Configuration](#custom-disk-configuration)).

## Drivers

Drivers register themselves into the storage registry from an `init()`. The `local` and `memory` drivers live in the `storage` package itself; the `s3` driver lives in `github.com/velocitykode/velocity/storage/s3` and registers the `"s3"` driver when that package is imported (Velocity imports it for you when an app needs S3).

### Local Driver

The local driver stores files on your server's filesystem:

- **Storage location**: Configured via `FILESYSTEM_LOCAL_ROOT` (default: `./storage/app`)
- **Sandboxed**: The driver opens an `os.Root` at the configured directory and resolves every path beneath it, rejecting traversal and symlink escapes at the kernel level
- **Thread-safe**: Concurrent operations are properly synchronized
- **Cross-platform**: Handles path separators automatically

**Use cases:**
- Development and testing
- Small-scale deployments
- Files that don't need distributed storage


The local driver holds an `os.Root` file descriptor for the lifetime of the driver. The storage manager drains it during app shutdown via `Manager.Shutdown(ctx)`, so you do not normally release it yourself.


### S3 Driver

The S3 driver stores files on Amazon S3:

- **Scalable**: Handle unlimited file storage
- **Distributed**: Access from anywhere
- **Secure**: Supports private files with signed URLs
- **Efficient**: Uses multipart uploads for large files

**Use cases:**
- Production deployments
- Large file storage
- Global content delivery
- Backup and archival

### Memory Driver

The memory driver stores files in memory (useful for tests and ephemeral data):

- **Fast**: No disk I/O overhead
- **Clean**: No filesystem pollution
- **Limited**: Configurable size limit via `MaxSize` (default 100 MB)

**Use cases:**
- Unit testing
- Integration testing
- Development with mock data

## API Reference

All methods below are called on a `Driver` obtained from `c.Storage().Disk(name)` or `c.Storage().Default()`. The examples assume a `disk` variable holding that driver and `ctx` holding the request context (`c.Request.Context()`).

### File Operations

#### PutCtx

Store file contents at a given path:

```go
// Store byte array on the default disk
imageData := []byte{ /* ... */ }
err := disk.PutCtx(ctx, "uploads/image.jpg", imageData)

// Using a specific disk
s3, err := c.Storage().Disk("s3")
if err != nil {
    return err
}
err = s3.PutCtx(ctx, "backups/data.json", jsonData)
```

#### PutStreamCtx

Store a file from an `io.Reader` (efficient for large files):

```go
file, _ := os.Open("large-video.mp4")
defer file.Close()

err := disk.PutStreamCtx(ctx, "videos/tutorial.mp4", file)
```

#### GetCtx

Retrieve file contents as a byte array:

```go
contents, err := disk.GetCtx(ctx, "uploads/document.pdf")
if err != nil {
    if errors.Is(err, storage.ErrFileNotFound) {
        // Handle missing file
    }
    return err
}
```

#### GetStreamCtx

Retrieve a file as an `io.ReadCloser` (efficient for large files):

```go
stream, err := disk.GetStreamCtx(ctx, "videos/tutorial.mp4")
if err != nil {
    return err
}
defer stream.Close()

// Process stream
_, err = io.Copy(outputFile, stream)
```

#### ExistsCtx

Check if a file exists (returns a `bool`):

```go
if disk.ExistsCtx(ctx, "uploads/avatar.jpg") {
    // File exists
}
```

#### DeleteCtx

Delete one or more files:

```go
// Delete single file
err := disk.DeleteCtx(ctx, "uploads/temp.txt")

// Delete multiple files
err := disk.DeleteCtx(ctx,
    "uploads/file1.txt",
    "uploads/file2.txt",
    "uploads/file3.txt",
)
```

### File Management

#### CopyCtx

Copy a file to a new location:

```go
err := disk.CopyCtx(ctx, "uploads/original.jpg", "uploads/copy.jpg")
```

#### MoveCtx

Move a file to a new location:

```go
err := disk.MoveCtx(ctx, "uploads/temp.jpg", "uploads/final.jpg")
```

#### SizeCtx

Get the size of a file in bytes:

```go
size, err := disk.SizeCtx(ctx, "uploads/video.mp4")
fmt.Printf("File size: %d bytes\n", size)
```

#### LastModifiedCtx

Get the last modified time:

```go
modTime, err := disk.LastModifiedCtx(ctx, "uploads/document.pdf")
fmt.Printf("Last modified: %s\n", modTime.Format(time.RFC3339))
```

#### MimeTypeCtx

Get the MIME type of a file:

```go
mimeType, err := disk.MimeTypeCtx(ctx, "uploads/image.jpg")
// Returns: "image/jpeg"
```

### Directory Operations

#### FilesCtx

List files in a directory (non-recursive):

```go
files, err := disk.FilesCtx(ctx, "uploads")
// Returns: ["file1.txt", "file2.pdf"]
```

#### AllFilesCtx

List all files recursively:

```go
files, err := disk.AllFilesCtx(ctx, "uploads")
// Returns: ["file1.txt", "2024/file2.pdf", "2024/01/file3.jpg"]
```

#### DirectoriesCtx

List subdirectories (non-recursive):

```go
dirs, err := disk.DirectoriesCtx(ctx, "uploads")
// Returns: ["2024", "temp"]
```

#### AllDirectoriesCtx

List all subdirectories recursively:

```go
dirs, err := disk.AllDirectoriesCtx(ctx, "uploads")
// Returns: ["2024", "2024/01", "2024/02", "temp"]
```

#### MakeDirectoryCtx

Create a directory:

```go
err := disk.MakeDirectoryCtx(ctx, "uploads/2024/12")
```

#### DeleteDirectoryCtx

Delete a directory and all its contents:

```go
err := disk.DeleteDirectoryCtx(ctx, "uploads/temp")
```

### URL Operations

#### URL

Get a permanent public URL for a file. `URL` is a pure string transformation, so it has no context-aware variant:

```go
// Local disk: returns configured base URL + path
url := disk.URL("public/logo.png")

// S3 disk: returns S3 URL
s3, _ := c.Storage().Disk("s3")
url := s3.URL("images/banner.jpg")
// Returns: "https://my-bucket.s3.amazonaws.com/images/banner.jpg"
```

#### TemporaryURLCtx

Get a temporary signed URL. This is supported by the S3 driver; the local and memory drivers return `storage.ErrNotSupported`:

```go
// Generate URL that expires in 15 minutes
url, err := s3.TemporaryURLCtx(ctx, "private/report.pdf", 15*time.Minute)
if err != nil {
    if errors.Is(err, storage.ErrNotSupported) {
        // Driver cannot mint signed URLs (e.g. local disk)
    }
    return err
}

// Share the URL - it will expire automatically
fmt.Println("Download link:", url)
```

## Working with Multiple Disks

### Using Specific Disks

```go
mgr := c.Storage()

s3, err := mgr.Disk("s3")
if err != nil {
    return err
}
local, err := mgr.Disk("local")
if err != nil {
    return err
}

// Use the disks
s3.PutCtx(ctx, "backups/data.json", jsonData)
local.PutCtx(ctx, "logs/app.log", logData)
```

`Disk` returns `storage.ErrDiskNotFound` when the named disk has not been configured.

### Copying Between Disks

```go
mgr := c.Storage()

src, err := mgr.Disk("local")
if err != nil {
    return err
}
data, err := src.GetCtx(ctx, "uploads/file.pdf")
if err != nil {
    return err
}

dst, err := mgr.Disk("s3")
if err != nil {
    return err
}
if err := dst.PutCtx(ctx, "backups/file.pdf", data); err != nil {
    return err
}
```

### Custom Disk Configuration

Build a `storage.Config` and configure a `*storage.Manager` directly. `Config`, `DiskConfig`, and the driver interface are defined in the `storage` package (backed by the shared `contract` leaf):

```go
import (
    "context"

    "github.com/velocitykode/velocity/storage"
)

func setupCustomStorage(ctx context.Context) (*storage.Manager, error) {
    config := storage.Config{
        Default: "s3",
        Disks: map[string]storage.DiskConfig{
            "local": {
                Driver: "local",
                Root:   "./storage/app",
                URL:    "http://localhost:8090/storage",
            },
            "s3": {
                Driver: "s3",
                Key:    "YOUR_AWS_KEY",
                Secret: "YOUR_AWS_SECRET",
                Region: "us-east-1",
                Bucket: "my-bucket",
            },
            "backup": {
                Driver: "s3",
                Key:    "YOUR_AWS_KEY",
                Secret: "YOUR_AWS_SECRET",
                Region: "us-west-2",
                Bucket: "my-backup-bucket",
            },
        },
    }

    mgr := storage.NewManager(config)
    if err := mgr.ConfigureWithContext(ctx, config); err != nil {
        return nil, err
    }
    return mgr, nil
}
```


To use the S3 driver, import `github.com/velocitykode/velocity/storage/s3` somewhere in your build so its `init()` registers the `"s3"` factory. The `local` and `memory` drivers are registered by the `storage` package itself.


## Best Practices

### 1. Use UUIDs for Uploaded Files

Prevent filename collisions:

```go
import "github.com/google/uuid"

func handleFileUpload(ctx context.Context, disk storage.Driver, originalName string, data []byte) error {
    // Generate unique filename
    ext := filepath.Ext(originalName)
    filename := uuid.New().String() + ext

    path := fmt.Sprintf("uploads/%s", filename)
    return disk.PutCtx(ctx, path, data)
}
```

### 2. Stream Large Files

Don't load large files into memory:

```go
// Good: Stream the file
file, _ := os.Open("large-file.mp4")
defer file.Close()
disk.PutStreamCtx(ctx, "videos/video.mp4", file)

// Bad: Load entire file into memory
data, _ := os.ReadFile("large-file.mp4")
disk.PutCtx(ctx, "videos/video.mp4", data)
```

### 3. Use Appropriate Disks for Sensitive Files

Keep private files on a private disk and mint temporary access for them:

```go
s3, _ := c.Storage().Disk("s3")

// Store a private file
s3.PutCtx(ctx, "invoices/invoice-123.pdf", invoiceData)

// Generate temporary access to a private file
url, _ := s3.TemporaryURLCtx(ctx, "invoices/invoice-123.pdf", 1*time.Hour)
```

### 4. Handle Errors Properly

```go
import "errors"

func getFile(ctx context.Context, disk storage.Driver, path string) ([]byte, error) {
    data, err := disk.GetCtx(ctx, path)
    if err != nil {
        if errors.Is(err, storage.ErrFileNotFound) {
            // Handle missing file specifically
            return nil, fmt.Errorf("file not found: %s", path)
        }
        // Handle other errors
        return nil, fmt.Errorf("failed to read file: %w", err)
    }
    return data, nil
}
```

### 5. Organize Files with Directory Structure

```go
// Good: Organized structure
disk.PutCtx(ctx, fmt.Sprintf("uploads/%d/%s/avatar.jpg", year, month), data)
disk.PutCtx(ctx, fmt.Sprintf("users/%d/documents/%s.pdf", userID, docType), data)

// Bad: Flat structure
disk.PutCtx(ctx, fmt.Sprintf("avatar-%d.jpg", userID), data)
```

## Testing

The `github.com/velocitykode/velocity/storage/testing` package ships an in-memory fake driver plus fluent assertions, so you can verify storage interactions without touching disk or S3.

### Using the Fake Driver

`StorageFake()` returns a `*FakeStorage` that records every operation. Use the `Fake()` builder to synthesize realistic test files:

```go
import (
    storageTesting "github.com/velocitykode/velocity/storage/testing"
)

func TestUserAvatar(t *testing.T) {
    fake := storageTesting.StorageFake()

    // Build a realistic fake image
    img := storageTesting.Fake().Image("avatar.jpg", 200, 200)

    // Exercise your code against the fake
    if err := fake.Put("avatars/user-123.jpg", img.Content()); err != nil {
        t.Fatal(err)
    }

    // Assert against recorded state
    a := fake.Assert(t)
    a.AssertExists("avatars/user-123.jpg")
    a.AssertMissing("avatars/user-456.jpg")
    a.AssertCount(1)
}
```

Available assertions include `AssertExists`, `AssertMissing`, `AssertStored`, `AssertStoredString`, `AssertCount`, `AssertNothingStored`, `AssertSize`, `AssertMimeType`, `AssertDirectory`, `AssertCopied`, `AssertMoved`, `AssertDeleted`, `AssertContains`, `AssertURL`, and `AssertTemporaryURL`. You can also drive failure paths with `fake.ShouldFail("boom")` / `fake.ShouldSucceed()` and reset state with `fake.Clear()`.

## Complete Example

Here's a complete file upload handler using the request-scoped storage manager:

```go
package handlers

import (
    "fmt"
    "path/filepath"
    "time"

    "github.com/google/uuid"
    "github.com/velocitykode/velocity/router"
    "github.com/velocitykode/velocity/storage"
)

type FileHandler struct{}

// Upload handles file uploads
func (fc *FileHandler) Upload(c *router.Context) error {
    disk, err := c.Storage().Default()
    if err != nil {
        return c.JSON(500, map[string]string{"error": "Storage unavailable"})
    }

    // Parse multipart form (32 MB max)
    if err := c.Request.ParseMultipartForm(32 << 20); err != nil {
        return c.JSON(400, map[string]string{"error": "Invalid file upload"})
    }

    // Get the file
    file, header, err := c.Request.FormFile("file")
    if err != nil {
        return c.JSON(400, map[string]string{"error": "No file provided"})
    }
    defer file.Close()

    // Validate file size (10 MB max)
    if header.Size > 10*1024*1024 {
        return c.JSON(400, map[string]string{"error": "File too large (max 10MB)"})
    }

    // Generate unique filename
    ext := filepath.Ext(header.Filename)
    filename := uuid.New().String() + ext
    path := fmt.Sprintf("uploads/%s", filename)

    // Store the file (streaming)
    if err := disk.PutStreamCtx(c.Request.Context(), path, file); err != nil {
        return c.JSON(500, map[string]string{"error": "Failed to store file"})
    }

    return c.JSON(200, map[string]interface{}{
        "message": "File uploaded successfully",
        "path":    path,
        "url":     disk.URL(path),
        "size":    header.Size,
    })
}

// Download generates a temporary download link
func (fc *FileHandler) Download(c *router.Context) error {
    disk, err := c.Storage().Default()
    if err != nil {
        return c.JSON(500, map[string]string{"error": "Storage unavailable"})
    }

    filePath := c.Param("path")
    if !disk.ExistsCtx(c.Request.Context(), filePath) {
        return c.JSON(404, map[string]string{"error": "File not found"})
    }

    // Generate temporary URL (valid for 1 hour); requires a driver that supports it (S3).
    url, err := disk.TemporaryURLCtx(c.Request.Context(), filePath, 1*time.Hour)
    if err != nil {
        return c.JSON(500, map[string]string{"error": "Failed to generate download link"})
    }

    return c.JSON(200, map[string]string{
        "download_url": url,
        "expires_in":   "1 hour",
    })
}

// Delete removes a file
func (fc *FileHandler) Delete(c *router.Context) error {
    disk, err := c.Storage().Default()
    if err != nil {
        return c.JSON(500, map[string]string{"error": "Storage unavailable"})
    }

    filePath := c.Param("path")
    if !disk.ExistsCtx(c.Request.Context(), filePath) {
        return c.JSON(404, map[string]string{"error": "File not found"})
    }

    if err := disk.DeleteCtx(c.Request.Context(), filePath); err != nil {
        return c.JSON(500, map[string]string{"error": "Failed to delete file"})
    }

    return c.JSON(200, map[string]string{"message": "File deleted successfully"})
}
```


================================================================================
# Queue System

Source: https://vel.build/docs/advanced/queue/
Section: Advanced Topics
Summary: Background job processing with Velocity's queue system


Velocity provides a unified queue interface for background job processing, supporting Redis, database, and in-memory drivers.

## Decision matrix

Pick the helper that matches what you are trying to do:

| Situation | Helper |
|---|---|
| Register a job factory with the type-safe key derived from `T` | `RegisterJob[T](factory)` |
| Pass an arbitrary string key (legacy or non-trivial naming) | `Register(name, factory)` |
| One-shot dispatch | `driver.PushCtx(ctx, job, queue...)` |
| Delayed dispatch | `driver.PushDelayedCtx(ctx, job, delay, queue...)` |
| Long-running job that must abort on shutdown / timeout | implement `HandleCtx(ctx) error` (HandleCtxer) |
| Batch with then / catch / finally | `NewBatch(jobs...).Then(...).Catch(...).Finally(...).Dispatch(ctx, driver)` |
| Register a third-party driver backend | `queue.Drivers().Register(name, factory)` |

All dispatch methods are context-aware so cancellation flows through to the backing store. The `queue` parameter is variadic; omit it to fall back to the job's `OnQueue()` (if implemented) or `"default"`.

## Configuration

Configure the queue driver in your `.env` file:

```bash
# Queue configuration
QUEUE_DRIVER=memory  # Options: memory, redis, database

# Redis settings (when using redis driver)
QUEUE_REDIS_HOST=localhost
QUEUE_REDIS_PORT=6379
QUEUE_REDIS_DB=0
QUEUE_REDIS_PASSWORD=

# Payload integrity / encryption (optional)
QUEUE_SIGNING_KEY=        # HMAC-SHA256 key (>= 32 bytes); falls back to APP_KEY
QUEUE_ENCRYPT=false       # Encrypt job payload data at rest with the app encryptor
```

The framework wires a `queue.Driver` into the service container as `s.Queue` (a `contract.QueueDriver`). Application code dispatches through that handle; only worker bootstraps construct drivers directly.

The database driver always reads and writes the fixed `jobs` and `failed_jobs` tables; those names are not configurable via environment variables.


The `redis` driver lives in a separate leaf package so the framework core does not pull in the go-redis client. Setting `QUEUE_DRIVER=redis` only resolves once you blank-import the leaf: `import _ "github.com/velocitykode/velocity/queue/redis"` (or `import _ "github.com/velocitykode/velocity/queue/standard"` to wire every built-in driver at once). The `memory` and `database` drivers register from the queue package's own `init()` and need no extra import.


## Creating Jobs

Jobs implement the `Job` interface (`Handle() error` + `Failed(error)`). Long-running jobs should additionally implement `HandleCtxer` so cancellation reaches the work.

### `Job` (always required)

```go
package jobs

import "log"

type EmailJob struct {
    To      string `json:"to"`
    Subject string `json:"subject"`
    Body    string `json:"body"`
}

func (e *EmailJob) Handle() error {
    log.Printf("Sending email to: %s", e.To)
    // Send email logic here
    return nil
}

func (e *EmailJob) Failed(err error) {
    log.Printf("Failed to send email to %s: %v", e.To, err)
}
```

`Handle()` is fine for fast, non-blocking work. The worker has no way to interrupt it once it starts; if the per-job timeout fires or the worker is shutting down, the goroutine continues until `Handle` returns on its own.

### `HandleCtxer` (optional, ctx-aware)

When a job implements `HandleCtx(ctx context.Context) error`, the worker calls it instead of `Handle()` and threads its per-job context in. Cancellation of that context (worker shutdown, per-job timeout) and any trace span on the worker context flow into the handler. Jobs that implement only `Handle()` keep working unchanged.

```go
package jobs

import (
    "context"
    "fmt"
    "io"
    "net/http"
)

type FetchJob struct {
    URL string `json:"url"`
}

func (j *FetchJob) Handle() error {
    // Fallback for callers that ignore HandleCtxer; the worker won't use this
    // when HandleCtx is also defined.
    return j.HandleCtx(context.Background())
}

func (j *FetchJob) HandleCtx(ctx context.Context) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, j.URL, nil)
    if err != nil {
        return err
    }

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return err // includes ctx errors when shutdown or timeout fires mid-flight
    }
    defer resp.Body.Close()

    // For inner loops without their own ctx-aware I/O, select on ctx.Done()
    // explicitly so a cancellation aborts promptly.
    chunks := make(chan []byte)
    go streamChunks(resp.Body, chunks)
    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        case b, ok := <-chunks:
            if !ok {
                return nil
            }
            if _, err := io.Discard.Write(b); err != nil {
                return err
            }
        }
    }
}

func (j *FetchJob) Failed(err error) {
    fmt.Printf("fetch %s failed: %v\n", j.URL, err)
}
```


The handler goroutine is **not** forcibly terminated. If `HandleCtx` ignores `ctx` and blocks, the goroutine leaks until the process exits. Implementations MUST observe `ctx.Done()` (via ctx-aware I/O or an explicit `select`) and return promptly when the context cancels. The worker bounds its wait on a misbehaving handler (see [Shutdown semantics](#shutdown-semantics)) so `Stop()` cannot hang, but the leak counts as a bug in the handler.


## Pushing Jobs

### Immediate dispatch

```go
import (
    "context"
    "github.com/velocitykode/velocity/queue"
)

job := &jobs.EmailJob{
    To:      "user@example.com",
    Subject: "Welcome",
    Body:    "Welcome to our service!",
}

// Push to default queue (resolved from OnQueuer or "default")
err := s.Queue.PushCtx(ctx, job)

// Push to a named queue
err = s.Queue.PushCtx(ctx, job, "emails")
```

### Delayed dispatch

```go
// Push job with 5 minute delay
err := s.Queue.PushDelayedCtx(ctx, job, 5*time.Minute)

// Push to a named queue with delay
err = s.Queue.PushDelayedCtx(ctx, job, 10*time.Minute, "scheduled")
```

## Job Registration

Workers deserialize incoming payloads through a process-global registry. The producer (push) and consumer (decode) keys must agree, or jobs are dropped with `ErrJobNotFound` at runtime.

### `RegisterJob[T]` (preferred)

`RegisterJob[T]` derives the registry key from `T` itself, so producer and consumer stay symmetric by construction:

```go
import (
    "encoding/json"
    "github.com/velocitykode/velocity/queue"
    "myapp/app/jobs"
)

func init() {
    queue.RegisterJob(func(data []byte) (*jobs.EmailJob, error) {
        j := &jobs.EmailJob{}
        return j, json.Unmarshal(data, j)
    })
}
```

`T` is typically a pointer type (e.g. `*EmailJob`), matching how jobs are dispatched (`s.Queue.PushCtx(ctx, &EmailJob{...})`).

### `Register` (deprecated, explicit naming)

`Register(name, factory)` is retained for backward compatibility and for callers who need a custom naming scheme. It accepts any string and silently succeeds at boot, so a typo only surfaces at runtime as `ErrJobNotFound` when a payload arrives. Prefer `RegisterJob[T]` for new code.

```go
queue.Register("EmailJob", func(data []byte) (queue.Job, error) {
    j := &jobs.EmailJob{}
    return j, json.Unmarshal(data, j)
})
```


Both `RegisterJob` and `Register` route through `normalizeJobType`, which collapses pointer (`*pkg.Foo`), package-qualified (`pkg.Foo`), and bare (`Foo`) forms to the bare type name. That means `Register("*jobs.EmailJob", ...)`, `Register("jobs.EmailJob", ...)`, and `Register("EmailJob", ...)` all produce the same key. Two named types whose unqualified names collide across packages will collide in the registry; keep job type names unique within a process.


## Processing Jobs

### Worker options

`queue.NewWorker(driver, queueName, handler, opts...)` accepts the following options:

| Option | Signature | Behavior |
|---|---|---|
| `WithConcurrency` | `WithConcurrency(n int)` | Number of pump goroutines. Values `<= 0` are ignored; values above `MaxWorkerConcurrency` (10,000) are clamped. |
| `WithInterval` | `WithInterval(d time.Duration)` | Polling interval between empty-queue checks. Default `100ms`. |
| `WithTimeout` | `WithTimeout(d time.Duration)` | Per-job execution timeout. Default `30s`. Values `<= 0` are ignored. |
| `WithMaxRetries` | `WithMaxRetries(n int)` | Maximum attempts before a job is permanently failed. Default `3`. Overridden per-job by `MaxAttempter`. |
| `WithBackoff` | `WithBackoff(strategy BackoffStrategy)` | Retry delay strategy. Default `ExponentialBackoff(1*time.Second, 5*time.Minute)`. Overridden per-job by `Backoffer`. |
| `WithWorkerLogger` | `WithWorkerLogger(l WorkerLogger)` | Routes worker errors and lifecycle messages through the framework logger. When omitted, `NewWorker` falls back to a stderr logger and emits a one-time warning so worker errors are never invisible. |

Bundled `BackoffStrategy` constructors: `ExponentialBackoff(base, max)`, `LinearBackoff(step, max)`, `FixedBackoff(delay)`.

### Starting workers

```go
import (
    "context"
    "github.com/velocitykode/velocity/queue"
)

// The handler is the fallback for jobs that DON'T implement HandleCtxer.
// Jobs that do implement HandleCtx(ctx) are invoked directly by the worker
// with the per-job ctx; this handler is bypassed for them.
handler := func(j queue.Job) error { return j.Handle() }

w := queue.NewWorker(s.Queue, "emails", handler,
    queue.WithConcurrency(5),
    queue.WithInterval(100*time.Millisecond),
    queue.WithMaxRetries(3),
    queue.WithTimeout(45*time.Second),
    queue.WithBackoff(queue.ExponentialBackoff(2*time.Second, 5*time.Minute)),
    queue.WithWorkerLogger(s.Log),
)

w.Start(ctx)   // idempotent; pump goroutines exit when ctx cancels or Stop() is called
defer w.Stop()
```

`Start` is idempotent: a second call while the worker is already running is a no-op. Pump goroutines exit when the parent context cancels or `Stop()` is invoked.

### Shutdown semantics

The worker treats parent-ctx cancellation, `Stop()`, and per-job timeouts distinctly:

| Trigger | What the handler sees | What the worker does |
|---|---|---|
| Parent `ctx` cancels OR `Stop()` is called | Per-job ctx is cancelled (`HandleCtxer` jobs observe `<-ctx.Done()`); `Handle()`-only jobs keep running until they return | Treats the abort as **clean**: no `Failed()` call, no retry push, no `JobFailed`/`JobRetrying` events. The job stays in flight from the driver's perspective; a future worker (or the driver's shutdown path) reclaims it. |
| `WithTimeout` fires while parent ctx is still live | Per-job ctx is cancelled with `DeadlineExceeded` | Routes through `handleJobFailure`: increments attempt, fires `JobRetrying` or `JobFailed`, requeues with backoff or marks failed. |
| Handler returns a non-ctx error during shutdown | n/a | Logs a `WARN` ("Job error swallowed during worker shutdown") and aborts without routing through `Failed()` so the tear-down path stays clean. The error is diagnosable in logs. |

Per-job timeouts also drain the detached handler goroutine. When `WithTimeout` fires (or `Stop()` propagates), the worker waits up to ~5s for the goroutine to observe `ctx.Done()` and unwind. If the handler ignores ctx and blocks past that ceiling, the worker logs a `WARN` ("Handler goroutine did not return after ctx cancellation; leaking") and lets `Stop()` complete; the rogue goroutine leaks until the process exits. This bound exists so a misbehaving handler can't hang shutdown forever.

Practical implications:

- A `HandleCtxer` job that gets cancelled by `Stop()` and returns `ctx.Err()` is **not** a failure. It will be processed again next time a worker picks it up.
- A `Handle()`-only job already running when `Stop()` is called runs to completion; the worker waits for the pump goroutines to drain. Long-running `Handle()` work blocks shutdown.
- Per-job timeouts (`WithTimeout`) **are** real failures and consume retry budget. Reach for `HandleCtxer` if you want the timeout to actually interrupt the work rather than just mark it failed in the background.

## Trace propagation

Every push stamps the producer ctx's trace ids onto the payload before serialisation:

```go
type Payload struct {
    // ...
    TraceID  string `json:"trace_id,omitempty"`
    SpanID   string `json:"span_id,omitempty"`
    ParentID string `json:"parent_id,omitempty"`
}
```

All three bundled drivers (memory, database, redis) implement the optional
`TraceAwareDriver` interface (`PopCtxWithTrace`) and recover the producer trace
when popping a job. `Worker.processJob` then rebuilds the per-job ctx with
`trace.WithFullContext` so `HandleCtxer` handlers and the `JobProcessing` /
`JobProcessed` / `JobFailed` / `JobRetrying` events observe the same
`TraceID` / `SpanID` / `ParentID` as the originating request.

**Backwards compat:** legacy rows pushed by older producers lack the three
fields; the worker skips the `WithFullContext` call and runs the job with no
injected trace. `omitempty` keeps the marshalled bytes unchanged for legacy
producers, so signed payloads still verify across the upgrade.

Third-party drivers that want the same behaviour must implement
`PopCtxWithTrace` and persist the three fields on the payload at push time.
Drivers that only implement `PopCtx` fall through the worker's non-trace
branch and run jobs without producer-side trace context.

## Retry control

Three optional interfaces let a job tune retry behavior without touching the global worker config.

### `MaxAttempter` (per-job retry budget)

```go
type MaxAttempter interface {
    MaxAttempts() int
}
```

Implementing `MaxAttempts()` overrides the worker's `WithMaxRetries` for this job type only. Useful when most jobs should retry 3 times but a slow webhook should retry 10.

```go
func (j *WebhookJob) MaxAttempts() int { return 10 }
```

### `Backoffer` (per-attempt delay schedule)

```go
type Backoffer interface {
    Backoff() []time.Duration
}
```

Returns an explicit per-attempt delay slice. The last value is reused for any attempts beyond the slice length. Use this when transient upstream failures want a tailored backoff curve (fast first retry, then exponential).

```go
func (j *WebhookJob) Backoff() []time.Duration {
    return []time.Duration{
        1 * time.Second,
        5 * time.Second,
        30 * time.Second,
        2 * time.Minute,
    }
}
```

### `RetryDecider` (opt out of retries for specific errors)

```go
type RetryDecider interface {
    ShouldRetry(err error) bool
}
```

Returning `false` permanently fails the job on this error without consuming further attempts. Use this for non-transient failures (validation errors, 4xx upstream responses) that retry cannot fix.

### `OnQueuer` and `Identifiable`

Two more optional interfaces round out the set:

- `OnQueuer.OnQueue() string`: declares a default queue name; used when the caller does not pass one to `PushCtx`.
- `Identifiable.JobID() string`: provides a stable key for attempt tracking across serialization boundaries (Redis, database). Without it the worker derives a stable key by hashing the marshalled job payload (sha256), so two byte-identical jobs share one attempt counter; raw pointer identity is only the last-resort fallback when marshalling fails. Implement `JobID()` when distinct jobs can share identical content but must track attempts independently.

## Batches

`NewBatch` builds a fluent group dispatch with then / catch / finally callbacks:

```go
batch, err := queue.NewBatch(
    &jobs.EmailJob{To: "a@example.com"},
    &jobs.EmailJob{To: "b@example.com"},
).
    Then(func(b *queue.Batch) {
        log.Printf("batch %s: all %d jobs succeeded", b.ID(), b.TotalJobs())
    }).
    Catch(func(b *queue.Batch, err error) {
        log.Printf("batch %s: first failure %v", b.ID(), err)
    }).
    Finally(func(b *queue.Batch) {
        log.Printf("batch %s: %d completed, %d failed", b.ID(), b.CompletedJobs(), b.FailedJobs())
    }).
    AllowFailures().
    OnQueue("emails").
    Dispatch(ctx, s.Queue)
```

`Then` fires only on full success. `Catch` fires once on the first failure. `Finally` always fires when the batch is finished. By default a single failure cancels the batch; opt into best-effort processing with `AllowFailures()`. Look up an active batch with `queue.FindBatch(id)`.

For per-job batch participation implement the `Batchable` interface (`GetBatchID() / SetBatchID(id)`); `Dispatch` will set the batch ID on every job that implements it.

## Queue Management

```go
size, err := s.Queue.Size("emails")     // number of jobs waiting
err = s.Queue.Clear("failed")            // remove every job from a queue
err = s.Queue.Shutdown(ctx)              // drain in-flight work, honor ctx deadline
```

## Driver-specific notes

### Memory driver
- Fast, in-memory processing
- Perfect for development and testing
- Jobs are lost on restart
- Automatic delayed job processing via internal heap

### Redis driver
- Persistent job storage
- Distributed processing
- Lists for ready queues, sorted sets for delayed jobs

### Database driver
- Reservation-based leasing: rows are leased (`reserved_at`/`reserved_by`) to a worker for the duration of handler execution and reclaimed after the lease expires, so a crashed worker's job redelivers
- Row-level locking for concurrent workers
- Failed-job tracking in the fixed `failed_jobs` table

Construct drivers directly when wiring outside the framework's bootstrap:

```go
// Memory driver: call Start() to launch the background delayed-job processor.
d := queue.NewMemoryDriver()
d.Start()

// Or resolve through the registry. NewQueue defaults an empty Driver to
// "memory"; "redis" requires the leaf package to be blank-imported first
// (see Configuration above).
d, err := queue.NewQueue(queue.QueueConfig{Driver: "redis", Redis: redisCfg})

// Database driver: pass a *sql.DB and the dialect name.
d := queue.NewDatabaseDriver(db, "postgres")
```

### Registering a third-party driver

The built-in drivers self-register through Velocity's unified driver registry: `memory` and `database` from the queue package's own `init()`, and `redis` from its leaf package's `init()` once blank-imported. Third-party backends plug in the same way: call `queue.Drivers().Register(name, factory)` from your driver package's `init()` and the name resolves through `queue.NewQueue` / `queue.NewQueueWithContext` like any built-in.

```go
package kafkaqueue

import (
    "context"

    "github.com/velocitykode/velocity/queue"
)

func init() {
    queue.Drivers().Register("kafka", func(ctx context.Context, cfg queue.QueueConfig) (queue.Driver, error) {
        return newKafkaDriver(ctx, cfg)
    })
}
```

```go
// app wiring
import _ "example.com/kafkaqueue" // pulls in the init() that registers "kafka"

d, err := queue.NewQueueWithContext(ctx, queue.QueueConfig{Driver: "kafka"})
```

Setting `QUEUE_DRIVER=kafka` in `.env` then routes the framework's bootstrap through the registered factory. See [Driver Registry](/docs/advanced/driver-registry/) for the registry contract shared with cache, storage, and other subsystems.

## Recipe: retry only on transient errors

**When:** a job calls a flaky upstream API where 5xx responses are worth retrying but 4xx are not.

**Code:**

```go
type WebhookJob struct {
    URL  string `json:"url"`
    Body []byte `json:"body"`
}

func (j *WebhookJob) Handle() error { /* POST to j.URL */ }
func (j *WebhookJob) Failed(err error) { /* persist for inspection */ }

// Per-job retry budget
func (j *WebhookJob) MaxAttempts() int { return 8 }

// Per-attempt delays; last value reused beyond slice length
func (j *WebhookJob) Backoff() []time.Duration {
    return []time.Duration{
        1 * time.Second, 5 * time.Second, 15 * time.Second,
        1 * time.Minute, 5 * time.Minute,
    }
}

// Skip retries for non-transient failures
func (j *WebhookJob) ShouldRetry(err error) bool {
    var httpErr *upstreamHTTPError
    if errors.As(err, &httpErr) && httpErr.StatusCode >= 400 && httpErr.StatusCode < 500 {
        return false
    }
    return true
}
```

**Why this shape:** `MaxAttempter` and `Backoffer` keep retry policy on the job type rather than scattered across worker configs. `RetryDecider` short-circuits the retry loop for errors retrying cannot fix, conserving the attempt budget.

## Best Practices

1. **Job design**: keep jobs small and focused on a single task.
2. **Idempotency**: design `Handle()` / `HandleCtx()` to be safe to retry; uniqueness keys in upstream calls are cheaper than careful retry logic.
3. **Reach for `HandleCtxer` for any I/O or long loop**: ctx-aware I/O (`http.NewRequestWithContext`, `db.QueryContext`, channel receives in a `select`) is the difference between a job that aborts cleanly on shutdown and a goroutine that leaks.
4. **Use `RegisterJob[T]`**: string keys are typo footguns surfaced only at runtime.
5. **Always set `WithWorkerLogger`**: the stderr fallback exists so errors are never silent, but production workers should route through the framework logger.
6. **Graceful shutdown**: call `Stop()` (or cancel the parent context) so pump goroutines drain in-flight jobs. Shutdown-cancelled jobs are not retried or marked failed; a future worker re-picks them from the driver.
7. **Register before starting workers**: late registrations work, but a job that arrives before its handler is registered fails with `ErrJobNotFound`.

## Related

- [Events](/docs/advanced/events/) - in-process pub/sub; pair async listeners with the queue when work must survive restarts
- [Mail](/docs/advanced/mail/) - outbound email is a classic queue payload to keep request latency low
- [Notifications](/docs/advanced/notifications/) - multi-channel delivery that typically dispatches through queue jobs
- [Async](/docs/core/async/) - fire-and-forget for in-process work; reach for the queue when durability matters
- [Driver Registry](/docs/advanced/driver-registry/) - the registry contract `queue.Drivers()` is built on, shared with cache and storage


================================================================================
# Mail

Source: https://vel.build/docs/advanced/mail/
Section: Advanced Topics
Summary: Send emails with Velocity's driver-based mail system supporting SMTP/sendmail, Mailgun, Postmark, and a development log driver.


Velocity provides a driver-based email system that supports multiple mail services through a unified, fluent message builder. Messages are built with `mail.NewMessage()` and delivered through a `Mailer` (the `app.Mail` configured at boot) or a `Manager` that routes to named channels.

## Quick Start


**Configured at boot**: When you build messages and send through `app.Mail`, the mailer is constructed from your `.env` (see [Configuration](#configuration)). The driver factories are wired by blank-importing `github.com/velocitykode/velocity/mail/standard`.





```go
import (
    "context"

    "github.com/velocitykode/velocity/mail"
)

func send(mailer mail.Mailer) error {
    msg := mail.NewMessage().
        To("user@example.com").
        Subject("Welcome to Velocity").
        Body("Thanks for signing up!")

    return mailer.Send(context.Background(), msg)
}
```



```go
import (
    "context"

    "github.com/velocitykode/velocity/mail"
)

func send(mailer mail.Mailer) error {
    html := `
        <h1>Welcome to Velocity</h1>
        <p>Thanks for signing up!</p>
    `

    msg := mail.NewMessage().
        To("user@example.com").
        Subject("Welcome").
        HTMLBody(html).
        TextBody("Thanks for signing up!")

    return mailer.Send(context.Background(), msg)
}
```



```go
import (
    "context"
    "os"

    "github.com/velocitykode/velocity/mail"
)

func send(mailer mail.Mailer) error {
    // AttachFile resolves paths against a registered attachment root.
    root, err := os.OpenRoot("/srv/app/attachments")
    if err != nil {
        return err
    }
    defer root.Close()

    msg := mail.NewMessage().
        To("user@example.com").
        Subject("Your Invoice").
        Body("Please find your invoice attached.").
        WithAttachmentRoot(root)

    // AttachFile returns (*Message, error) and breaks the fluent chain.
    if _, err := msg.AttachFile("invoice.pdf"); err != nil {
        return err
    }

    return mailer.Send(context.Background(), msg)
}
```





`mail.Mailer` is `app.Mail`, constructed from `mail.NewMailer(config)` during boot. It exposes a single method: `Send(ctx context.Context, msg *mail.Message) error`. There is no global `mail.Send()` and no `Message.Send()`: sending always goes through a `Mailer` (or a [`Manager`](#multiple-channels)).


## Configuration

Configure email sending through environment variables in your `.env` file:

### Log Driver (Development)

The log driver writes email details to the log instead of sending them - perfect for development:

```env
MAIL_DRIVER=log
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="My Application"
```

### Local SMTP Driver

Send emails via a local SMTP server or sendmail:

```env
MAIL_DRIVER=local
MAIL_HOST=localhost
MAIL_PORT=587                # Defaults to 587 when unset
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls          # tls/ssl use implicit TLS; any other value uses STARTTLS
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="My Application"

# Or use sendmail instead of SMTP
MAIL_SENDMAIL_PATH=/usr/sbin/sendmail
```

When a username is set, `MAIL_ENCRYPTION=tls` or `ssl` opens an implicit-TLS (SMTPS) connection; any other value (or unset) dials plaintext and requires the server to advertise STARTTLS before credentials are offered. With no username, mail is sent anonymously.

### Postmark Driver

Send transactional emails via Postmark:

```env
MAIL_DRIVER=postmark
MAIL_POSTMARK_TOKEN=your-server-token
MAIL_POSTMARK_MESSAGE_STREAM=outbound  # Defaults to "outbound" when unset
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="My Application"
```

The message stream is validated against an allowlist (`outbound`, `broadcast`, `transactional`, `inbound` by default). Use `mail.ConfigureAllowedPostmarkStreams([]string{...})` to register custom streams.

### Mailgun Driver

Send emails via the Mailgun API:

```env
MAIL_DRIVER=mailgun
MAIL_MAILGUN_DOMAIN=mg.yourdomain.com
MAIL_MAILGUN_SECRET=your-api-key
MAIL_MAILGUN_ENDPOINT=https://api.mailgun.net/v3  # Optional, defaults to the US region
MAIL_MAILGUN_WEBHOOK_SIGNING_KEY=your-webhook-key # Optional, for verifying Mailgun webhooks
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="My Application"
```

The Mailgun endpoint must use `https`; an `http://` endpoint is rejected so credentials are never sent over cleartext.


You can also cap attachment sizes globally with `MAIL_MAX_ATTACHMENT_SIZE` (bytes). It defaults to 25 MiB (`mail.DefaultMaxAttachmentSize`).


## Building Messages

### Fluent API

The `Message` type provides a fluent, chainable builder. The address and content
setters return `*Message`, so they chain. Once built, pass the message to a
`Mailer`:

```go
import (
    "context"

    "github.com/velocitykode/velocity/mail"
)

msg := mail.NewMessage().
    From("sender@example.com", "Sender Name").
    To("recipient@example.com", "Recipient Name").
    CC("manager@example.com").
    BCC("admin@example.com").
    ReplyTo("support@example.com").
    Subject("Important Update").
    TextBody("Plain text content").
    HTMLBody("<h1>HTML content</h1>").
    Priority(mail.HighPriority)

mailer.Send(context.Background(), msg)
```


The address setters (`From`/`To`/`CC`/`BCC`/`ReplyTo`), `Subject`, and `Header`
validate their input and reject CR/LF header-injection payloads, recipient lists
smuggled into a single address, and embedded display names. A rejected value is
stored as a deferred error on the message; `Send` returns it before any driver
sees the message. Call `msg.Err()` to inspect it early.


### Multiple Recipients

```go
msg := mail.NewMessage().
    To("user1@example.com").
    To("user2@example.com").
    To("user3@example.com", "User Three").
    Subject("Newsletter").
    Body("Monthly newsletter content")

mailer.Send(context.Background(), msg)
```

### Custom Headers

```go
msg := mail.NewMessage().
    To("user@example.com").
    Subject("Custom Headers").
    Body("Content").
    Header("X-Custom-ID", "12345").
    Header("X-Campaign", "summer-sale")

mailer.Send(context.Background(), msg)
```

## Templates

Render an HTML template into the message's HTML body. Templates are parsed with
Go's `html/template` and live under `resources/views/emails` by default; the
template name is the file name without the `.html` extension. Change the
directory with `mail.SetTemplatePath`.

`Template` returns `(*Message, error)` (it can fail to find or render the file),
so it breaks the fluent chain:

```go
import (
    "context"

    "github.com/velocitykode/velocity/mail"
)

func send(mailer mail.Mailer) error {
    // Renders resources/views/emails/welcome.html
    data := map[string]any{
        "Name": "John Doe",
        "URL":  "https://example.com/verify",
    }

    msg := mail.NewMessage().
        To("user@example.com").
        Subject("Welcome!")

    if _, err := msg.Template("welcome", data); err != nil {
        return err
    }

    return mailer.Send(context.Background(), msg)
}
```

Template names containing path separators or `..` traversal sequences are
rejected.

Example template (`resources/views/emails/welcome.html`):

```html
<!DOCTYPE html>
<html>
<head>
    <title>Welcome</title>
</head>
<body>
    <h1>Welcome, {{.Name}}!</h1>
    <p>Click here to verify your account:</p>
    <a href="{{.URL}}">Verify Account</a>
</body>
</html>
```

## Attachments

### From File System

`AttachFile` resolves its argument **relative to a registered attachment root**.
A root must be configured first, either per-message via `WithAttachmentRoot` or
process-wide via `mail.SetDefaultAttachmentRoot`. Without one, `AttachFile`
returns `mail.ErrAttachmentRootRequired`. Absolute paths and paths that escape
the root (via `..` or symlinks) are rejected with
`mail.ErrAttachmentPathOutsideRoot`. `AttachFile` returns `(*Message, error)`.

```go
import (
    "context"
    "os"

    "github.com/velocitykode/velocity/mail"
)

func send(mailer mail.Mailer) error {
    root, err := os.OpenRoot("/srv/app/attachments")
    if err != nil {
        return err
    }
    defer root.Close()

    msg := mail.NewMessage().
        To("user@example.com").
        Subject("Documents").
        Body("Please find the documents attached.").
        WithAttachmentRoot(root)

    if _, err := msg.AttachFile("document.pdf"); err != nil {
        return err
    }
    if _, err := msg.AttachFile("image.jpg"); err != nil {
        return err
    }

    return mailer.Send(context.Background(), msg)
}
```

Configure a process-wide root once at boot to avoid passing it to every message:

```go
root, _ := os.OpenRoot("/srv/app/attachments")
mail.SetDefaultAttachmentRoot(root) // caller owns root and closes it at shutdown
```

### From Memory

`AttachData` does not need a root and stays in the fluent chain (it records a
deferred error if the data exceeds the limit):

```go
import (
    "context"

    "github.com/velocitykode/velocity/mail"
)

func send(mailer mail.Mailer) error {
    // Generate PDF or other data
    pdfData := generateInvoicePDF()

    msg := mail.NewMessage().
        To("user@example.com").
        Subject("Your Invoice").
        Body("Invoice attached.").
        AttachData(pdfData, "invoice.pdf", "application/pdf")

    return mailer.Send(context.Background(), msg)
}
```

### Attachment Size Limits

Each attachment is capped at `mail.GetDefaultMaxAttachmentSize()` (25 MiB by
default, or the value of `MAIL_MAX_ATTACHMENT_SIZE`). Exceeding it yields
`mail.ErrAttachmentTooLarge`. Override the limit per message with
`msg.WithMaxAttachmentSize(n)` (call it before attaching).

## Advanced Usage

### Using Context

`Mailer.Send` takes a `context.Context`, so timeouts and cancellation propagate
to the driver's network I/O:

```go
import (
    "context"
    "time"

    "github.com/velocitykode/velocity/mail"
)

func sendEmail(mailer mail.Mailer) error {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    msg := mail.NewMessage().
        To("user@example.com").
        Subject("Hello").
        Body("Content")

    return mailer.Send(ctx, msg)
}
```

### Priority Levels

```go
import (
    "context"

    "github.com/velocitykode/velocity/mail"
)

// High priority (urgent)
high := mail.NewMessage().
    To("admin@example.com").
    Subject("URGENT: Server Down").
    Body("Server is down!").
    Priority(mail.HighPriority)
mailer.Send(context.Background(), high)

// Normal priority (default)
normal := mail.NewMessage().
    To("user@example.com").
    Subject("Update").
    Body("Regular update").
    Priority(mail.NormalPriority)
mailer.Send(context.Background(), normal)

// Low priority
low := mail.NewMessage().
    To("user@example.com").
    Subject("Newsletter").
    Body("Monthly newsletter").
    Priority(mail.LowPriority)
mailer.Send(context.Background(), low)
```

### Constructing a Mailer

Build a `Mailer` directly from a `MailConfig`. Blank-import `mail/standard` (or a
specific leaf driver) so the driver factories are registered before
`NewMailer` resolves them:

```go
import (
    "context"

    "github.com/velocitykode/velocity/mail"
    _ "github.com/velocitykode/velocity/mail/standard" // registers log/local/mailgun/postmark
)

mailer, err := mail.NewMailer(mail.MailConfig{
    Driver:      "postmark",
    FromAddress: "noreply@example.com",
    FromName:    "My Application",
    Postmark: mail.PostmarkConfig{
        Token:         "your-server-token",
        MessageStream: "outbound",
    },
})
if err != nil {
    // handle misconfiguration
}

msg := mail.NewMessage().
    To("user@example.com").
    Subject("Test").
    Body("Content")

mailer.Send(context.Background(), msg)
```

When you only need an in-process recorder for development, the log driver is
available directly:

```go
mailer := mail.NewLogDriver()
```

### Multiple Channels

A `Manager` routes a message through one of several named channels (for example
a transactional channel and a marketing channel) and can broadcast to several at
once. It also dispatches `MailSent` / `MailFailed` events when an event
dispatcher is wired in:

```go
import (
    "context"

    "github.com/velocitykode/velocity/mail"
)

manager := mail.NewManager()

transactional, _ := mail.NewMailer(mail.MailConfig{Driver: "postmark" /* ... */})
marketing, _ := mail.NewMailer(mail.MailConfig{Driver: "mailgun" /* ... */})

manager.SetChannel("transactional", transactional)
manager.SetChannel("marketing", marketing)

msg := mail.NewMessage().
    To("user@example.com").
    Subject("Receipt").
    Body("Thanks for your order")

// Send via one channel.
if err := manager.Send(context.Background(), "transactional", msg); err != nil {
    // handle error
}

// Or deliver the same message through several channels concurrently.
manager.Broadcast(context.Background(), []string{"transactional", "marketing"}, msg)
```

## API Reference

### Package Functions

```go
// Create a new message
func NewMessage() *Message

// Construct a mailer from configuration (drivers must be registered first)
func NewMailer(config MailConfig) (Mailer, error)
func NewMailerWithContext(ctx context.Context, config MailConfig) (Mailer, error)

// The built-in development log driver
func NewLogDriver() *LogDriver

// Multi-channel routing
func NewManager() *Manager

// Driver registry (driver packages register factories into it)
func Drivers() *driverregistry.Registry[Mailer, MailConfig]

// Templates
func SetTemplatePath(path string)

// Attachment containment root and size limits
func SetDefaultAttachmentRoot(root *os.Root)
func GetDefaultAttachmentRoot() *os.Root
func SetDefaultMaxAttachmentSize(n int64)
func GetDefaultMaxAttachmentSize() int64

// Postmark stream allowlist
func ConfigureAllowedPostmarkStreams(streams []string)
func IsAllowedPostmarkStream(name string) bool

// Error helpers
func IsErrAttachmentTooLarge(err error) bool
func IsErrInvalidHeader(err error) bool
```

### Mailer and Manager

```go
// Every driver implements this single-method interface
type Mailer interface {
    Send(ctx context.Context, msg *Message) error
}

// Manager methods
func (m *Manager) SetChannel(name string, mailer Mailer)
func (m *Manager) Channel(name string) (Mailer, error)
func (m *Manager) HasChannel(name string) bool
func (m *Manager) GetChannels() []string
func (m *Manager) RemoveChannel(name string)
func (m *Manager) ClearChannels()
func (m *Manager) Send(ctx context.Context, channel string, msg *Message) error
func (m *Manager) Broadcast(ctx context.Context, channels []string, msg *Message) error
func (m *Manager) Shutdown(ctx context.Context) error
```

### Message Methods

```go
// Recipients (chainable; record a deferred error on invalid input)
func (m *Message) From(email string, name ...string) *Message
func (m *Message) To(email string, name ...string) *Message
func (m *Message) CC(email string, name ...string) *Message
func (m *Message) BCC(email string, name ...string) *Message
func (m *Message) ReplyTo(email string, name ...string) *Message

// Content
func (m *Message) Subject(subject string) *Message
func (m *Message) Body(body string) *Message            // Convenience for TextBody
func (m *Message) TextBody(body string) *Message
func (m *Message) HTMLBody(body string) *Message
func (m *Message) Template(name string, data interface{}) (*Message, error)

// Attachments
func (m *Message) WithAttachmentRoot(root *os.Root) *Message
func (m *Message) WithMaxAttachmentSize(n int64) *Message
func (m *Message) AttachFile(path string) (*Message, error)
func (m *Message) AttachData(data []byte, name, contentType string) *Message

// Metadata
func (m *Message) Header(key, value string) *Message
func (m *Message) Priority(priority Priority) *Message

// Inspect the first deferred setter error (Send returns it too)
func (m *Message) Err() error
```

### Priority Constants

```go
const (
    LowPriority Priority = iota
    NormalPriority
    HighPriority
)
```

## Best Practices

1. **Use the Log Driver in Development**: Set `MAIL_DRIVER=log` to avoid sending real emails during development

2. **Always Set From Address**: Configure `MAIL_FROM_ADDRESS` in your `.env` to ensure all emails have a valid sender

3. **Provide Both Text and HTML**: Include both `TextBody()` and `HTMLBody()` for better email client compatibility:
   ```go
   msg.TextBody("Plain text version").
       HTMLBody("<h1>HTML version</h1>")
   ```

4. **Use Templates for Complex Emails**: Don't build HTML in code - use the `Template()` method

5. **Handle Errors Properly**: Always check the error returned from `Send()`:
   ```go
   if err := mailer.Send(ctx, msg); err != nil {
       log.Error("Failed to send email", "error", err)
       return err
   }
   ```

6. **Use Context for Timeouts**: When sending emails in HTTP handlers, use a context with a timeout:
   ```go
   ctx, cancel := context.WithTimeout(r.Context(), 10*time.Second)
   defer cancel()
   mailer.Send(ctx, msg)
   ```

7. **Validate Email Addresses**: Validate user-provided email addresses before attempting to send

8. **Use Appropriate Drivers**:
   - Development: `log` driver
   - Staging: `local` SMTP or test Postmark account
   - Production: `postmark` or `mailgun` for reliability

## Testing

### Using the Log Driver

The log driver records messages in-process instead of delivering them, which
makes it convenient for tests:

```go
import (
    "context"
    "testing"

    "github.com/velocitykode/velocity/mail"
)

func TestEmailSending(t *testing.T) {
    mailer := mail.NewLogDriver()

    msg := mail.NewMessage().
        To("test@example.com").
        Subject("Test").
        Body("Test email")

    if err := mailer.Send(context.Background(), msg); err != nil {
        t.Fatalf("send failed: %v", err)
    }
}
```

### Using the Fake Mailer

The `mailtest` package provides `FakeMailer`, a recorder that satisfies
`mail.Mailer` and ships with assertion helpers. Inject it anywhere a `Mailer`
is expected:

```go
import (
    "testing"

    "github.com/velocitykode/velocity/mail"
    "github.com/velocitykode/velocity/mail/mailtest"
)

func TestUserRegistration(t *testing.T) {
    fake := mailtest.NewFakeMailer()

    // Test your code, passing fake wherever a mail.Mailer is needed.
    RegisterUser(fake, "test@example.com")

    // Assert exactly one welcome email went to the new user.
    fake.AssertSentTimes(t, 1, func(m *mail.Message) bool {
        return len(m.GetTo()) > 0 && m.GetTo()[0].Email == "test@example.com"
    })
}
```

`FakeMailer` also exposes `GetSent()`, `AssertSent`, `AssertNotSent`, and
`AssertNothingSent`.

## Examples

### Welcome Email

```go
func SendWelcomeEmail(mailer mail.Mailer, user User) error {
    msg := mail.NewMessage().
        To(user.Email, user.Name).
        Subject("Welcome to Our Platform")

    if _, err := msg.Template("welcome", map[string]any{
        "Name":      user.Name,
        "VerifyURL": generateVerificationURL(user),
    }); err != nil {
        return err
    }

    return mailer.Send(context.Background(), msg)
}
```

### Password Reset

```go
func SendPasswordResetEmail(mailer mail.Mailer, email, token string) error {
    resetURL := fmt.Sprintf("https://example.com/reset?token=%s", token)

    msg := mail.NewMessage().
        To(email).
        Subject("Password Reset Request")

    if _, err := msg.Template("password-reset", map[string]any{
        "ResetURL":  resetURL,
        "ExpiresIn": "24 hours",
    }); err != nil {
        return err
    }

    return mailer.Send(context.Background(), msg)
}
```

### Invoice with PDF

```go
func SendInvoice(mailer mail.Mailer, customer Customer, invoice Invoice) error {
    pdfData := generateInvoicePDF(invoice)

    msg := mail.NewMessage().
        To(customer.Email, customer.Name).
        Subject(fmt.Sprintf("Invoice #%s", invoice.Number)).
        AttachData(pdfData, "invoice.pdf", "application/pdf")

    if _, err := msg.Template("invoice", map[string]any{
        "Invoice":  invoice,
        "Customer": customer,
    }); err != nil {
        return err
    }

    return mailer.Send(context.Background(), msg)
}
```

### Notification with Priority

```go
func SendAlertEmail(mailer mail.Mailer, admins []string, alert Alert) error {
    msg := mail.NewMessage().
        Subject(fmt.Sprintf("ALERT: %s", alert.Title)).
        Body(alert.Message).
        Priority(mail.HighPriority)

    for _, email := range admins {
        msg.To(email)
    }

    return mailer.Send(context.Background(), msg)
}
```


================================================================================
# Task Scheduler

Source: https://vel.build/docs/advanced/scheduler/
Section: Advanced Topics
Summary: Schedule recurring tasks with Velocity's fluent scheduler for cron jobs, daily tasks, and periodic work.


Velocity provides a task scheduler for running recurring jobs with an expressive, fluent API.

## Decision matrix

Pick the registration helper that matches the closure shape and naming you need:

| Situation | Helper |
|---|---|
| Closure has no error to report; OK with panic-only `OnFailure` | `Call(fn).Daily()` |
| Closure returns an error you want `OnFailure` to see | `CallE(fn).Daily().OnFailure(handler)` |
| Need a custom job name (not the auto-derived closure name) | `Named(name, fn)` / `NamedE(name, fn)` |
| Register jobs on the app's scheduler | `v.Schedule(func(s scheduler.TaskScheduler) { ... })` |
| Register jobs from a module | `Schedule(s scheduler.TaskScheduler)` on the module |
| Run scheduler alongside HTTP serve | `velocity.WithSchedulerInProcess()` |
| Run scheduler in separate process | `vel schedule work` CLI |

## Quick Start




```go
import (
    "github.com/velocitykode/velocity"
    "github.com/velocitykode/velocity/scheduler"
)

func main() {
    v, err := velocity.New(velocity.WithSchedulerInProcess())
    if err != nil {
        panic(err)
    }

    v.Schedule(func(s scheduler.TaskScheduler) {
        // Run every minute
        s.Named("heartbeat", func() {
            v.Log.Info("Task running every minute")
        }).EveryMinute()

        // Run every hour
        s.Named("hourly-rollup", func() {
            rollUpMetrics()
        }).Hourly()
    })

    if err := v.Serve(); err != nil {
        panic(err)
    }
}
```



```go
import (
    "github.com/velocitykode/velocity"
    "github.com/velocitykode/velocity/scheduler"
)

func registerJobs(v *velocity.App) {
    v.Schedule(func(s scheduler.TaskScheduler) {
        // Clear cache daily at 2 AM
        s.NamedE("cache-clear", func() error {
            return v.Cache.Flush()
        }).DailyAt("02:00")

        // Backup database daily at 3 AM
        s.NamedE("backup-database", func() error {
            return backupDatabase()
        }).DailyAt("03:00")
    })
}
```



```go
import (
    "github.com/velocitykode/velocity"
    "github.com/velocitykode/velocity/scheduler"
)

func registerJobs(v *velocity.App) {
    v.Schedule(func(s scheduler.TaskScheduler) {
        // Process jobs every 5 minutes, weekdays only
        s.Named("jobs-process", func() {
            processJobs()
        }).EveryFiveMinutes().
            Weekdays().
            Between("09:00", "18:00")

        // Weekly report on Mondays at 9 AM
        s.Named("report-weekly", func() {
            generateWeeklyReport()
        }).Weekly().
            Mondays().
            At("09:00")
    })
}
```




## The app scheduler

`velocity.New` builds a scheduler during bootstrap and exposes it as
`v.Scheduler`, typed as `scheduler.TaskScheduler`. It arrives pre-configured
from the app: `SetEnv` from `APP_ENV`, `SetLogger` from the framework logger,
`SetTimezone` from `APP_TIMEZONE`, and a cache-backed `Locker` when the
configured cache driver supports locks (Redis today; other drivers fall back
to the in-process `InMemoryLocker` with a warning).

There are two places to register jobs on it:

```go
// 1. The bootstrap callback.
v.Schedule(func(s scheduler.TaskScheduler) {
    s.Named("reports-generate", generateReports).DailyAt("06:00")
})

// 2. A module that implements the ScheduleModule interface.
func (m *ReportsModule) Schedule(s scheduler.TaskScheduler) {
    s.NamedE("reports-generate", m.generate).DailyAt("06:00")
}
```

`v.Schedule` stores a single callback, so calling it twice replaces the first
one. Register every job inside one callback, or split them across modules.

A module's `Schedule` method is only called when the module is registered
through `v.Modules(...)`. Modules passed to `velocity.WithModules(...)` run
`Init` / `Start` before the bootstrap chain exists and are not dispatched the
optional interfaces. See [Modules]().

`TaskScheduler` covers registration and lifecycle only: `Add`, `Call`,
`CallE`, `Named`, `NamedE`, `Command`, `Run`, `Shutdown`, `Jobs`,
`SetEventDispatcher`, `SetEnv`. The chaining configuration setters
(`SetTimezone`, `SetLogger`, `SetLocker`, `MaintenanceMode`, `Before`,
`After`) live on the concrete `*scheduler.Scheduler` and are meant for
bootstrap wiring or for a standalone `scheduler.New()`.

Throughout this page, `v` is the running app (`*velocity.App`, which embeds
the service container, hence `v.Log` / `v.Cache` / `v.Scheduler`) and `s` is
a scheduler.

## Configuration

### Creating a Scheduler

An app already has one (see [The app scheduler](#the-app-scheduler)).
`scheduler.New()` builds a standalone scheduler for a worker binary or a
test, and starts out unconfigured:

```go
import (
    "time"
    "github.com/velocitykode/velocity/scheduler"
)

s := scheduler.New()

// Set timezone (defaults to time.Local)
location, _ := time.LoadLocation("America/New_York")
s.SetTimezone(location)

// Any type with Debug/Info/Warn/Error satisfies scheduler.Logger,
// including the framework logger.
s.SetLogger(v.Log)

// Environment filter used by Job.Environments(...)
s.SetEnv("production")

// Cross-process overlap guard for WithoutOverlapping / OnOneServer
s.SetLocker(sharedLocker)
```

`s.Timezone()` and `s.Locker()` read the values back.

### Environment Variables

```env
# Environment filter for Job.Environments(...); the app calls SetEnv with it
APP_ENV=production

# IANA zone the app scheduler evaluates cron expressions in (default UTC)
APP_TIMEZONE=America/New_York
```

`APP_TIMEZONE` is the application's presentation timezone: it is applied to
`time.Local` and to scheduler cron evaluation at bootstrap. Persistence is
unconditionally UTC and never reads it.

## Schedule Frequencies

### Time-Based Intervals

```go
s.Call(func() {
    // Task logic
}).EveryMinute()           // Every minute
```

Available frequency methods:

```go
job.EveryMinute()           // Run every minute
job.EveryFiveMinutes()      // Run every 5 minutes
job.EveryTenMinutes()       // Run every 10 minutes
job.EveryFifteenMinutes()   // Run every 15 minutes
job.EveryThirtyMinutes()    // Run every 30 minutes

job.Hourly()                // Run every hour at :00
job.HourlyAt(17)            // Run every hour at :17

job.Daily()                 // Run daily at 00:00
job.DailyAt("13:00")        // Run daily at 1:00 PM

job.Weekly()                // Run weekly on Sunday at 00:00
job.Monthly()               // Run monthly on the 1st at 00:00
job.Yearly()                // Run yearly on Jan 1st at 00:00
```

### Day Constraints

```go
// Specific days
job.Sundays()               // Only on Sundays
job.Mondays()               // Only on Mondays
job.Tuesdays()              // Only on Tuesdays
job.Wednesdays()            // Only on Wednesdays
job.Thursdays()             // Only on Thursdays
job.Fridays()               // Only on Fridays
job.Saturdays()             // Only on Saturdays

// Day groups
job.Weekdays()              // Monday through Friday
job.Weekends()              // Saturday and Sunday
```

### Custom Cron Expressions

For complex schedules, use standard cron syntax:

```go
// Every 2 hours
s.Call(func() {
    // Task
}).Cron("0 */2 * * *")

// Weekdays at midnight
s.Call(func() {
    // Task
}).Cron("0 0 * * 1-5")

// Every 5 minutes
s.Call(func() {
    // Task
}).Cron("*/5 * * * *")
```

Cron format reference:
```
* * * * *
│ │ │ │ │
│ │ │ │ └─── day of week (0-6, Sunday=0)
│ │ │ └───── month (1-12)
│ │ └─────── day of month (1-31)
│ └───────── hour (0-23)
└─────────── minute (0-59)
```

## Task Constraints

### Time Constraints

Limit when tasks can run:

```go
// Only run between 8 AM and 5 PM
s.Call(func() {
    sendNotifications()
}).Hourly().Between("08:00", "17:00")

// Don't run between 10 PM and 6 AM
s.Call(func() {
    processData()
}).EveryFifteenMinutes().UnlessBetween("22:00", "06:00")
```

### Conditional Execution

```go
// Only run when condition is true
s.Call(func() {
    processPayments()
}).Hourly().When(func() bool {
    return isBusinessDay()
})

// Skip when condition is true
s.Call(func() {
    runBackup()
}).Daily().Skip(func() bool {
    return isMaintenanceMode()
})
```

### Environment Constraints

```go
// Only run in specific environments
s.Call(func() {
    cleanupOldData()
}).Daily().Environments("production", "staging")
```

### Prevent Overlapping

Prevent a task from running if the previous execution is still running:

```go
s.Call(func() {
    longRunningTask()
}).Hourly().WithoutOverlapping()
```

### Maintenance Mode

```go
// Allow task to run even in maintenance mode
s.Call(func() {
    criticalTask()
}).Hourly().EvenInMaintenanceMode()

// Enable maintenance mode
s.MaintenanceMode(true)
```

## Task Hooks

### Before and After Callbacks

```go
s.Call(func() {
    processOrders()
}).Daily().
    Before(func() {
        v.Log.Info("Starting order processing")
    }).
    After(func() {
        v.Log.Info("Finished order processing")
    })
```

### Success and Failure Handlers

```go
s.Call(func() {
    err := syncData()
    if err != nil {
        panic(err)
    }
}).Hourly().
    OnSuccess(func() {
        v.Log.Info("Data sync successful")
    }).
    OnFailure(func(err error) {
        v.Log.Error("Data sync failed", "error", err)
        sendAlert(err)
    })
```


Closures registered via `Call` only reach `OnFailure` when they panic; a
plain `error` return is invisible to the scheduler because the signature is
`func()`. Use `CallE` (or `NamedE`) when your closure returns an `error` and
you want `OnFailure` plus the `scheduled.failed` event to fire on the normal
error path.

```go
s.CallE(func() error {
    return syncData()
}).Hourly().
    OnFailure(func(err error) {
        v.Log.Error("Data sync failed", "error", err)
        sendAlert(err)
    })
```


### Global Hooks

Run callbacks before/after each scheduler cycle:

```go
s := scheduler.New()

s.Before(func() {
    v.Log.Info("Scheduler cycle starting")
})

s.After(func() {
    v.Log.Info("Scheduler cycle completed")
})
```

`Before` / `After` are on the concrete `*scheduler.Scheduler`, not on the
`TaskScheduler` interface the app exposes, so wire them where the scheduler
is constructed.

## Task Output

### File Output

Redirect task output to files:

```go
// Overwrite file
s.Command("backup-db").Daily().
    SendOutputTo("storage/logs/backup.log")

// Append to file
s.Command("process-queue").Hourly().
    AppendOutputTo("storage/logs/queue.log")
```

Redirection captures the stdout and stderr of a `Command` job's process.
Closure jobs (`Call` / `CallE` / `Named` / `NamedE`) run in-process and write
through whatever logger they use, so `SendOutputTo` / `AppendOutputTo` have
no effect on them.

## Registering Jobs

The scheduler exposes four closure-registration helpers. They differ along
two axes: whether the closure returns an `error`, and whether you supply
an explicit job name.

```go
// func() closure, auto-derived name (best-effort runtime symbol or "closure")
s.Call(func() {
    generateReports()
}).Daily()

// func() error closure; returned err feeds OnFailure + scheduled.failed
s.CallE(func() error {
    return generateReports()
}).Daily().OnFailure(handleErr)

// Explicit name + func() closure. Recommended when chaining WithoutOverlapping,
// since the overlap guard keys on the job name.
s.Named("reports-generate", func() {
    generateReports()
}).Daily().WithoutOverlapping()

// Explicit name + func() error closure. Combines both ergonomic wins.
s.NamedE("reports-generate", func() error {
    return generateReports()
}).Daily().WithoutOverlapping().OnFailure(handleErr)
```

`Call` and `CallE` derive a best-effort name from the closure's runtime
symbol; anonymous functions land at `pkg.parent.func1` style identifiers
that are not stable across builds. Reach for `Named` / `NamedE` whenever
the job name needs to be stable, such as when you rely on
`WithoutOverlapping` (the overlap guard collides if multiple closures
share the default name).

You can also chain `.Name("...")` on any job to override the derived name
after registration; doing so silences the `WithoutOverlapping` collision
warning for that job.

## Advanced Features

### Named Tasks

Give tasks descriptive names for easier debugging:

```go
s.Call(func() {
    generateReports()
}).Daily().Name("reports-generate")

s.Call(func() {
    cleanupFiles()
}).Weekly().Name("cleanup-files")
```

### Running Commands

Execute system commands:

```go
// Simple command
s.Command("ls", "-la").Daily()

// Command with output
s.Command("backup-db").DailyAt("02:00").
    AppendOutputTo("storage/logs/backup.log").
    Name("backup-database")

// Run in background
s.Command("long-process").Hourly().
    RunInBackground()
```

### Manual Job Execution

```go
// Get all jobs
jobs := s.Jobs()

// Run specific job manually
for _, job := range jobs {
    if job.GetName() == "backup-database" {
        job.Run()
    }
}

// Check job status
lastRun := job.GetLastRun()
nextRun := job.GetNextRun()
isRunning := job.IsRunning()
```

## API Reference

### Scheduler Methods

```go
// Create new scheduler
func New() *Scheduler

// Configuration
func (s *Scheduler) SetTimezone(tz *time.Location) *Scheduler
func (s *Scheduler) Timezone() *time.Location
func (s *Scheduler) SetLogger(logger Logger) *Scheduler
func (s *Scheduler) SetEnv(env string)
func (s *Scheduler) SetLocker(l Locker) *Scheduler
func (s *Scheduler) Locker() Locker
func (s *Scheduler) MaintenanceMode(enabled bool) *Scheduler
func (s *Scheduler) SetEventDispatcher(fn func(ctx context.Context, event interface{}) error)

// Define jobs
func (s *Scheduler) Call(callback func()) *Job
func (s *Scheduler) CallE(callback func() error) *Job
func (s *Scheduler) Named(name string, callback func()) *Job
func (s *Scheduler) NamedE(name string, callback func() error) *Job
func (s *Scheduler) Command(command string, args ...string) *Job
func (s *Scheduler) Add(job *Job) *Job

// Lifecycle
func (s *Scheduler) Run(ctx context.Context) error
func (s *Scheduler) Shutdown(ctx context.Context) error
func (s *Scheduler) ValidateJobs()

// Global hooks
func (s *Scheduler) Before(callback func()) *Scheduler
func (s *Scheduler) After(callback func()) *Scheduler

// Inspection
func (s *Scheduler) Jobs() []*Job
```

### Job Methods

Frequency methods return `*Job` for chaining:

```go
// Time intervals
EveryMinute() *Job
EveryFiveMinutes() *Job
EveryTenMinutes() *Job
EveryFifteenMinutes() *Job
EveryThirtyMinutes() *Job
Hourly() *Job
HourlyAt(minute int) *Job
Daily() *Job
DailyAt(time string) *Job
Weekly() *Job
Monthly() *Job
Yearly() *Job
Cron(expression string) *Job
At(time string) *Job

// Day constraints
Days(days ...int) *Job
Weekdays() *Job
Weekends() *Job
Sundays() *Job
Mondays() *Job
Tuesdays() *Job
Wednesdays() *Job
Thursdays() *Job
Fridays() *Job
Saturdays() *Job

// Execution constraints
WithoutOverlapping() *Job
WithoutOverlappingFor(ttl time.Duration) *Job
OnOneServer() *Job
EvenInMaintenanceMode() *Job
RunInBackground() *Job
When(callback func() bool) *Job
Skip(callback func() bool) *Job
Between(start, end string) *Job
UnlessBetween(start, end string) *Job
Environments(environments ...string) *Job

// Hooks
Before(callback func()) *Job
After(callback func()) *Job
OnSuccess(callback func()) *Job
OnFailure(callback func(error)) *Job

// Output
SendOutputTo(filename string) *Job
AppendOutputTo(filename string) *Job
EmailOutputTo(email string) *Job

// Metadata
Name(name string) *Job

// Inspection
GetName() string
GetLastRun() time.Time
GetNextRun() time.Time
IsRunning() bool
IsDue(t time.Time) bool
ShouldRun() bool

// Execution
Run() error
```

## Running Scheduled Work

The scheduler is constructed during app bootstrap but does not start its
ticker loop on its own. You have two deployment shapes:

### In-process with HTTP serve

For single-process deployments, opt the loop in via the
`WithSchedulerInProcess` option when constructing the app. The scheduler
starts after `Router.Freeze()` and before `http.Server.ListenAndServe`,
and drains in-flight jobs through `App.Shutdown` -> `Scheduler.Shutdown`
on signal-driven shutdown.

```go
import "github.com/velocitykode/velocity"

v, err := velocity.New(
    velocity.WithSchedulerInProcess(),
)
if err != nil {
    return err
}

if err := v.Serve(); err != nil {
    return err
}
```

The loop runs against `context.Background()` rather than the app's shutdown
context, so teardown always flows through `App.Shutdown`.

### Separate process via the CLI

For multi-process deployments (one or more `vel serve` workers plus a
dedicated scheduler), leave `WithSchedulerInProcess` off and run the
scheduler in its own process:

```bash
vel schedule work
```

`vel schedule work` bootstraps the app (so every `v.Schedule` callback and
module `Schedule` method has run), then calls `Scheduler.Run(ctx)` and waits
on SIGINT / SIGTERM before cancelling and draining.

Running the scheduler both in-process and via `vel schedule work` against
the same app will fire each job twice. Pick one shape per deployment.

## Best Practices

1. **Always Name Your Tasks**: Use descriptive names for easier debugging and monitoring
   ```go
   s.Call(func() {
       cleanupOldLogs()
   }).Daily().Name("cleanup-logs")
   ```

2. **Use WithoutOverlapping for Long Tasks**: Prevent job pile-up
   ```go
   s.Call(func() {
       processLargeDataset()
   }).Hourly().WithoutOverlapping()
   ```

3. **Add Error Handling**: Use OnFailure to handle and log errors
   ```go
   job.OnFailure(func(err error) {
       v.Log.Error("Task failed", "error", err)
       sendAlert(err)
   })
   ```

4. **Log Task Output**: Direct output to files for debugging
   ```go
   s.Command("backup").Daily().
       AppendOutputTo("storage/logs/backup.log")
   ```

5. **Test Cron Expressions**: Verify schedules before deploying
   ```go
   job := s.Call(func() {}).Cron("0 */2 * * *")
   nextRun := job.GetNextRun()
   v.Log.Info("Next run", "time", nextRun)
   ```

6. **Use Appropriate Frequencies**: Don't poll too frequently
   - Consider event-driven alternatives for real-time needs
   - Use longer intervals when possible

7. **Monitor Execution**: Track last run times
   ```go
   for _, job := range s.Jobs() {
       v.Log.Info("Job status",
           "name", job.GetName(),
           "last_run", job.GetLastRun(),
           "next_run", job.GetNextRun())
   }
   ```

8. **Let the lifecycle drain the jobs**: `WithSchedulerInProcess` and
   `vel schedule work` already stop the loop and wait for in-flight jobs on
   SIGINT / SIGTERM. A standalone scheduler needs the same treatment:
   `Shutdown` cancels the run context and waits for running jobs, returning
   `ctx.Err()` if the deadline expires first.
   ```go
   ctx, cancel := context.WithCancel(context.Background())
   defer cancel()

   go s.Run(ctx)

   // Graceful shutdown
   <-shutdownSignal
   drainCtx, drainCancel := context.WithTimeout(context.Background(), 30*time.Second)
   defer drainCancel()
   if err := s.Shutdown(drainCtx); err != nil {
       v.Log.Error("scheduler drain timed out", "error", err)
   }
   ```

## Complete Examples

### Application Scheduler

```go
package main

import (
    "github.com/velocitykode/velocity"
    "github.com/velocitykode/velocity/scheduler"
)

func main() {
    v, err := velocity.New(velocity.WithSchedulerInProcess())
    if err != nil {
        panic(err)
    }

    v.Schedule(func(s scheduler.TaskScheduler) {
        // Clear cache every hour
        s.NamedE("cache-clear", func() error {
            v.Log.Info("Clearing cache")
            return v.Cache.Flush()
        }).Hourly()

        // Database backup at 2 AM daily
        s.NamedE("backup-database", backupDatabase).
            DailyAt("02:00").
            WithoutOverlapping().
            OnSuccess(func() {
                v.Log.Info("Database backup completed")
            }).
            OnFailure(func(err error) {
                v.Log.Error("Database backup failed", "error", err)
                sendAlertEmail(err)
            })

        // Process queue every 5 minutes during business hours
        s.Named("queue-process", processQueueJobs).
            EveryFiveMinutes().
            Between("09:00", "18:00").
            Weekdays()

        // Weekly report on Mondays, production only
        s.Named("report-weekly", generateWeeklyReport).
            Weekly().
            Mondays().
            At("09:00").
            Environments("production")

        // Cleanup old files monthly
        s.Named("cleanup-files", cleanupOldFiles).Monthly()
    })

    // Serve() starts the scheduler loop (WithSchedulerInProcess) and drains
    // it through App.Shutdown on SIGINT / SIGTERM.
    if err := v.Serve(); err != nil {
        panic(err)
    }
}

func backupDatabase() error {
    // Database backup logic
    return nil
}

func processQueueJobs() {
    // Queue processing logic
}

func generateWeeklyReport() {
    // Report generation logic
}

func cleanupOldFiles() {
    // File cleanup logic
}

func sendAlertEmail(err error) {
    // Send alert email
}
```

### Development vs Production Schedules

`Environments` filters against the scheduler's env, which the app sets from
`APP_ENV` at bootstrap. A standalone scheduler needs an explicit
`s.SetEnv(...)`, otherwise every `Environments(...)` job is filtered out.

```go
func registerJobs(v *velocity.App) {
    v.Schedule(func(s scheduler.TaskScheduler) {
        // Tasks that run in all environments
        s.NamedE("cache-clear", v.Cache.Flush).Hourly()

        // Production-only tasks
        s.NamedE("backup-database", backupDatabase).
            DailyAt("02:00").
            Environments("production")

        s.NamedE("report-daily", sendDailyReport).
            DailyAt("09:00").
            Environments("production")

        // Development-only tasks
        s.NamedE("seed-test-data", seedTestData).
            Hourly().
            Environments("development")
    })
}
```

### Task with Custom Logger

`scheduler.Logger` is `Debug` / `Info` / `Warn` / `Error`, each
`(msg string, keysAndValues ...interface{})`. The framework logger already
satisfies it, so a standalone scheduler can borrow the app's:

```go
import (
    "github.com/velocitykode/velocity/contract"
    "github.com/velocitykode/velocity/scheduler"
)

s := scheduler.New()
s.SetLogger(v.Log)
```

Wrap it when scheduler output needs its own treatment:

```go
type prefixLogger struct{ inner contract.Logger }

func (l prefixLogger) Debug(msg string, kvs ...interface{}) { l.inner.Debug("[scheduler] "+msg, kvs...) }
func (l prefixLogger) Info(msg string, kvs ...interface{})  { l.inner.Info("[scheduler] "+msg, kvs...) }
func (l prefixLogger) Warn(msg string, kvs ...interface{})  { l.inner.Warn("[scheduler] "+msg, kvs...) }
func (l prefixLogger) Error(msg string, kvs ...interface{}) { l.inner.Error("[scheduler] "+msg, kvs...) }

s.SetLogger(prefixLogger{inner: v.Log})
```

## Testing

### Testing Scheduled Tasks

```go
func TestScheduledTask(t *testing.T) {
    executed := false

    s := scheduler.New()
    job := s.Call(func() {
        executed = true
    }).EveryMinute()

    // Run job manually
    err := job.Run()
    assert.NoError(t, err)
    assert.True(t, executed)
}
```

### Testing Schedule Timing

```go
func TestJobTiming(t *testing.T) {
    s := scheduler.New()

    job := s.Call(func() {
        // Task
    }).DailyAt("09:00")

    nextRun := job.GetNextRun()
    assert.Equal(t, 9, nextRun.Hour())
    assert.Equal(t, 0, nextRun.Minute())
}
```

### Testing Constraints

```go
func TestJobConstraints(t *testing.T) {
    s := scheduler.New()

    job := s.Call(func() {
        // Task
    }).Weekdays()

    // Check if job should run
    monday := time.Date(2024, 1, 1, 12, 0, 0, 0, time.Local) // Monday
    sunday := time.Date(2024, 1, 7, 12, 0, 0, 0, time.Local) // Sunday

    assert.True(t, job.IsDue(monday))
    assert.False(t, job.IsDue(sunday))
}
```

## Related

- [Queue](/docs/advanced/queue/) - durable jobs the scheduler can dispatch when a tick fires
- [Async](/docs/core/async/) - fire-and-forget primitives for in-process work scheduled tasks may kick off
- [Events](/docs/advanced/events/) - emit events from scheduled jobs so other listeners can react without coupling


================================================================================
# Notifications

Source: https://vel.build/docs/advanced/notifications/
Section: Advanced Topics
Summary: Send notifications across mail, database, broadcast, and Slack from a single definition.


The `notification` package lets you define a single notification and
deliver it over any combination of channels - mail, database,
broadcast (WebSocket), Slack. You write `ToMail`, `ToDatabase`,
`ToBroadcast`, `ToSlack` as needed; the manager dispatches to the
right channel driver.

Import path: `github.com/velocitykode/velocity/notification`

## Core interfaces

```go
type Notification interface {
    Via(notifiable any) []string  // channel names, e.g. "mail", "database"
}

type Notifiable interface {
    NotificationRoute(channel string) string  // address for this channel
}

type Channel interface {
    Send(ctx context.Context, notifiable any, notification Notification) error
}
```

A **notification** declares which channels it targets. A **notifiable**
(usually your `User` model) tells each channel where to deliver. A
**channel** performs the actual delivery.

## Defining a notification

```go
type OrderShipped struct {
    OrderID  int
    Carrier  string
    TrackURL string
}

func (n *OrderShipped) Via(_ any) []string {
    return []string{"mail", "database"}
}

func (n *OrderShipped) ToMail(_ any) *notification.MailMessage {
    return notification.NewMailMessage().
        Subject("Your order has shipped").
        Greeting("Hi there!").
        Line("Your order is on its way.").
        Action("Track your package", n.TrackURL).
        Line(fmt.Sprintf("Carrier: %s", n.Carrier)).
        Outro("Thanks for shopping with us.")
}

func (n *OrderShipped) ToDatabase(_ any) *notification.DatabaseMessage {
    return notification.NewDatabaseMessage("orders.shipped").
        Set("order_id", n.OrderID).
        Set("carrier", n.Carrier).
        Set("track_url", n.TrackURL)
}
```

## Defining a notifiable

A notifiable is anything that implements `Notifiable.NotificationRoute(channel string) string`. The channel driver calls this once per send to learn where to deliver. Each built-in channel interprets the returned string differently:

| Channel | What `NotificationRoute` should return | Used by |
|---|---|---|
| `"mail"` | RFC 5322 email address | `MailChannel` falls back to this when `MailMessage.To()` is empty |
| `"database"` | Stable identifier (string) for the row's `notifiable_id` column | `DatabaseChannel` writes this verbatim into `notifications.notifiable_id` |
| `"broadcast"` | A user identifier; the channel prefixes it with `private-` (e.g. `42` becomes `private-42`) when `BroadcastMessage.On(...)` is empty | `BroadcastChannel` |
| `"slack"` | A full Slack incoming-webhook URL | `SlackChannel` POSTs the rendered payload here; URLs that resolve to private/internal addresses are rejected |
| custom | Whatever your channel needs (push token, phone number, etc.) | Your channel implementation |

Return `""` for any channel the notifiable does not support. Channels differ in how they treat an empty route: the Slack channel returns a "no Slack webhook URL for notifiable" error, while the mail, database, and broadcast channels do not error - mail sends with no recipient, database stores an empty `notifiable_id`, and broadcast skips delivery and returns nil. Only list a channel in `Via()` when the notifiable can route it.

```go
type User struct {
    ID              int
    Email           string
    SlackWebhookURL string
}

func (u *User) NotificationRoute(channel string) string {
    switch channel {
    case "mail":
        return u.Email
    case "database":
        return strconv.Itoa(u.ID)
    case "broadcast":
        return strconv.Itoa(u.ID)
    case "slack":
        return u.SlackWebhookURL
    }
    return ""
}
```

The same notifiable can serve every channel; `Via()` decides which routes are actually consulted on a given send.

## Sending

The manager fans out to each channel in `Via()`:

```go
mgr := notification.NewManager()

err := mgr.Send(ctx, user, &OrderShipped{
    OrderID:  42,
    Carrier:  "UPS",
    TrackURL: "https://ups.com/track/42",
})
```

Send to many recipients at once:

```go
mgr.SendMany(ctx, []any{user1, user2, user3}, notif)
```

`SendMany` accumulates errors - one failed recipient doesn't prevent
the others from receiving the notification.

## Recipe: Send the same notification on mail, slack, and database

**When:** A single domain event (a new signup, a paid invoice, a shipped order) needs to land in the user's inbox, post to a team Slack channel, and persist to the in-app inbox at the same time, without writing the dispatch logic three times.

**Code:**
```go
type SignupReceived struct {
    User *User
}

func (n *SignupReceived) Via(_ any) []string {
    return []string{"mail", "slack", "database"}
}

func (n *SignupReceived) ToMail(_ any) *notification.MailMessage {
    return notification.NewMailMessage().
        Subject("Welcome to Acme").
        Greeting("Hi " + n.User.Name).
        Line("Thanks for signing up.").
        Action("Open dashboard", "https://acme.app/dashboard")
}

func (n *SignupReceived) ToSlack(_ any) *notification.SlackMessage {
    return notification.NewSlackMessage().
        Content("New signup: " + n.User.Email).
        AsUser("Signups Bot").
        WithIcon(":wave:")
}

func (n *SignupReceived) ToDatabase(_ any) *notification.DatabaseMessage {
    return notification.NewDatabaseMessage("signup.received").
        Set("user_id", n.User.ID).
        Set("email", n.User.Email)
}

// elsewhere
mgr.Send(ctx, n.User, &SignupReceived{User: n.User})
```

**Why this shape:** `Via()` is the routing decision and lives on the notification, not the notifiable, because the same `User` can receive different notifications over different channel sets. The manager iterates `Via()` in order and calls each channel's `Send`; one channel failing returns an error but does not short-circuit the remaining channels, so a flaky Slack webhook will not block the database row from being written. Each `To*` method must match the channel listed in `Via()`, since channels assert the notification implements their channel-specific interface (e.g. `SlackChannel` requires `SlackNotification`) and return an error otherwise. Routes for each channel come from the notifiable's `NotificationRoute(channel)`; for the recipe above, `User.NotificationRoute("slack")` must return a webhook URL and `NotificationRoute("database")` must return a stable id.

**See also:** [`mail`](/docs/advanced/mail/), [`broadcast`](/docs/realtime/broadcast/), [`events`](/docs/advanced/events/) (listen to `notification.sent` / `notification.failed`).

## Channels

The package ships four built-in channels, each in its own sub-package.
Blank-import `notification/standard` to register all of them at once
via their `init()` side effects:

```go
import _ "github.com/velocitykode/velocity/notification/standard"
```

This pulls in mail, database, broadcast, and slack.

Or cherry-pick by blank-importing only the channel packages you want.
Each channel's `init()` calls `notification.Drivers().Register(...)`
exactly once. Registering the same name twice panics, so import each
channel package only once.

```go
import (
    _ "github.com/velocitykode/velocity/notification/mail"
    _ "github.com/velocitykode/velocity/notification/database"
)
```

After registration, `mgr.Channel("mail")` lazily instantiates the
driver and returns it; the manager uses this internally when a
notification lists `"mail"` in `Via()`. Use `mgr.SetChannel(name, ch)`
to inject a pre-configured channel instance (e.g. a `*mail.MailChannel`
with `SetMailer(...)` already called). `notification.RegisteredChannels()`
returns the names of all registered drivers.

### Mail channel

Notifications implementing `MailNotification` (have a `ToMail` method)
build a `*MailMessage` and send it through the `mail` package.

Message builder covers the common shape - greeting, body lines,
call-to-action button, outro - plus full HTML/text body override when
you need custom templates:

```go
return notification.NewMailMessage().
    From("no-reply@example.com", "Example").
    To(user.Email).
    Subject("Welcome").
    Greeting("Hi "+user.Name).
    Line("Thanks for signing up.").
    Action("Get started", "https://example.com/onboard").
    Outro("Need help? Reply to this email.")
```

For complete control:

```go
return notification.NewMailMessage().
    To(user.Email).
    Subject("Receipt").
    HTMLBody(renderedHTML).
    TextBody(plainText).
    AttachData(pdfBytes, "receipt.pdf", "application/pdf")
```

### Database channel

Stores the notification as a row in a `notifications` table (or
whichever table your store implements). Use this for in-app
notification inboxes.

```go
return notification.NewDatabaseMessage("billing.invoice.paid").
    Set("invoice_id", inv.ID).
    Set("amount", inv.Total)
```

The `Type` field is a logical name; `Data` is serialized as JSON.

### Broadcast channel

Delivers to real-time WebSocket subscribers via the `broadcast`
package. Set the target channels explicitly with `On(...)`. When `On(...)`
is omitted, the channel falls back to the notifiable's
`NotificationRoute("broadcast")` value and prefixes it with `private-`
(so a route of `42` broadcasts on `private-42`); pass a bare identifier
there, not an already-prefixed channel name.

```go
return notification.NewBroadcastMessage("order.shipped").
    On("private-user."+strconv.Itoa(n.UserID)).
    Set("order_id", n.OrderID).
    Set("track_url", n.TrackURL)
```

### Slack channel

Posts to a Slack webhook URL returned by the notifiable:

```go
return notification.NewSlackMessage().
    Content("New signup: "+user.Email).
    AsUser("Signups Bot").
    WithIcon(":wave:").
    Attachment(func(a *notification.SlackAttachment) {
        a.Color = "good"
        a.Title = user.Name
        a.Field("Plan", user.Plan, true)
        a.Field("Trial ends", user.TrialEnd.Format("2006-01-02"), true)
    })
```

## Events

Every send emits one of two events:

- `*notification.NotificationSent` - on successful delivery
- `*notification.NotificationFailed` - on delivery error

Wire them up via the manager:

```go
mgr.SetEventDispatcher(func(ctx context.Context, event any) error {
    return v.Events.Dispatch(ctx, event)
})
```

Useful for delivery metrics, retry workers, or audit logs.

## Custom channels

Implement the `Channel` interface and register it:

```go
type PushChannel struct { /* APNs/FCM client */ }

func (c *PushChannel) Send(ctx context.Context, notifiable any, n notification.Notification) error {
    // 1. Assert n implements your channel-specific interface (e.g. PushNotification)
    // 2. Use notifiable.(notification.Notifiable).NotificationRoute("push") for the token
    // 3. Send it
    return nil
}

func init() {
    notification.Drivers().Register("push", func(_ context.Context, _ notification.ChannelConfig) (notification.Channel, error) {
        return &PushChannel{/* ... */}, nil
    })
}
```

From then on, any notification listing `"push"` in `Via()` goes through
your channel.

## Related

- [Events](/docs/advanced/events/) - emit a domain event and let a listener fan out the notification
- [Queue](/docs/advanced/queue/) - dispatch notifications through queue jobs so request handlers stay snappy
- [Mail](/docs/advanced/mail/) - the underlying transport for the email channel


================================================================================
# HTTP Client

Source: https://vel.build/docs/advanced/httpclient/
Section: Advanced Topics
Summary: Instrumented, secure-by-default outbound HTTP client with APM events and trace propagation.


The `httpclient` package wraps `net/http` and dispatches APM events on
every outbound request. Latency, status, and body sizes flow into your
observability stack automatically. Its defaults are hardened: TLS 1.2
minimum, a capped redirect chain that strips credentials on cross-origin
hops, an SSRF dial guard, a response-body size cap, and per-stage
transport timeouts (see [Secure defaults](#secure-defaults)).

Import path: `github.com/velocitykode/velocity/httpclient`

## Creating a client

```go
c := httpclient.New()
```

Options:

```go
c := httpclient.New(
    httpclient.WithBaseURL("https://api.example.com"),
    httpclient.WithTimeout(10 * time.Second),
    httpclient.WithHTTPClient(&http.Client{ /* custom transport */ }),
)
```

Default timeout is 30 seconds. The default transport caps redirect
chains at 10 hops; tighten or disable that with `WithMaxRedirects` (see
[Secure defaults](#secure-defaults)).

## Methods

All methods take a `context.Context` as the first argument so that
cancellation, deadlines, and trace IDs propagate through the call:

```go
ctx := r.Context()

resp, err := c.Get(ctx, "/users/42")
if err != nil {
    return err
}
defer resp.Body.Close()

// POST with JSON
body := strings.NewReader(`{"name":"alice"}`)
resp, err := c.Post(ctx, "/users", "application/json", body)

// PUT, PATCH, DELETE also available
resp, err := c.Put(ctx, "/users/42", "application/json", body)
resp, err := c.Patch(ctx, "/users/42", "application/json", body)
resp, err := c.Delete(ctx, "/users/42")
```

For full control, build an `*http.Request` yourself and call `Do`:

```go
req, _ := http.NewRequestWithContext(ctx, http.MethodGet, "/search", nil)
req.Header.Set("Authorization", "Bearer "+token)
req.URL.RawQuery = "q=velocity"

resp, err := c.Do(ctx, req)
```

### Base URL resolution

When `WithBaseURL(...)` is set, relative paths starting with `/` are
resolved against the base URL. Absolute URLs are used as-is:

```go
c := httpclient.New(httpclient.WithBaseURL("https://api.example.com"))

c.Get(ctx, "/users")                    // → https://api.example.com/users
c.Get(ctx, "https://other.example/x")   // → https://other.example/x
```

## Events

Every call dispatches one of two events through the application's event
dispatcher:

- `*httpclient.RequestSent` - fired on every successful response
- `*httpclient.RequestFailed` - fired on transport errors

```go
type RequestSent struct {
    Context      context.Context
    Method       string
    URL          string
    StatusCode   int
    DurationMs   int64
    RequestSize  int64
    ResponseSize int64
    TraceID      string
    SpanID       string
    ParentID     string
}

type RequestFailed struct {
    Context    context.Context
    Method     string
    URL        string
    Error      string
    DurationMs int64
    TraceID    string
    SpanID     string
    ParentID   string
}
```

Trace IDs are read from the context via the `trace` package - if your
request came in through Velocity's middleware, the outgoing call
automatically carries the incoming trace.

### Wiring a dispatcher

```go
c := httpclient.New()
c.SetEventDispatcher(func(ctx context.Context, event interface{}) error {
    return v.Events.Dispatch(event)
})
```

The dispatcher receives the request-scoped `context.Context` so
listeners can observe request-scoped values; the `event` is one of the
types above.

Once wired, APM agents subscribing to `http.request.sent` and
`http.request.failed` events will record every outbound request.

## Secure defaults

`httpclient.New()` is hardened out of the box. The defaults apply on the
framework-built transport; when you supply your own via `WithHTTPClient`,
transport-level fields stay under your control (the TLS minimum and dial
guard are still applied in place when your transport is a plain
`*http.Transport`).

| Protection | Default | Tune with |
|------------|---------|-----------|
| Minimum TLS version | TLS 1.2 | `WithMinTLSVersion(tls.VersionTLS13)` |
| Redirect cap | 10 hops | `WithMaxRedirects(n)` (`n <= 0` disables redirect following) |
| Cross-origin credential stripping | `Authorization`, `Cookie`, `Proxy-Authorization` removed when an eTLD+1 host changes (or on an `https` to `http` downgrade) | always on |
| SSRF dial guard | refuses loopback, RFC1918, link-local, CGNAT, and cloud-metadata IPs (IPv4 + IPv6); resolved IP is pinned to defeat DNS rebinding | `WithAllowedHosts(...)`, `WithoutPrivateIPDeny()` |
| Env proxy | `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` ignored while the dial guard is on | `WithProxyAllowed()` |
| Response body cap | 32 MiB; reads past it return `ErrResponseTooLarge` | `WithMaxResponseBytes(n)` (`n <= 0` disables) |
| TLS handshake timeout | 10s | `WithTLSHandshakeTimeout(d)` |
| Response header timeout | 30s | `WithResponseHeaderTimeout(d)` |
| Idle connection timeout | 90s | `WithIdleConnTimeout(d)` |
| Expect-continue timeout | 1s | `WithExpectContinueTimeout(d)` |

The SSRF gate runs both at the URL-host level (so it covers proxy mode)
and at dial time. To reach a known internal service while still blocking
everything else, allowlist its eTLD+1 host:

```go
c := httpclient.New(httpclient.WithAllowedHosts("internal.svc.cluster.local"))
```

The response cap is enforced on the read stream, not the
`Content-Length` header, so a server that lies about its length cannot
bypass it. When the cap is hit, the read returns `httpclient.ErrResponseTooLarge`:

```go
resp, err := c.Get(ctx, "/big")
if err != nil {
    return err
}
defer resp.Body.Close()

data, err := io.ReadAll(resp.Body)
if errors.Is(err, httpclient.ErrResponseTooLarge) {
    // payload exceeded WithMaxResponseBytes
}
```


`WithoutPrivateIPDeny()` disables the SSRF guard entirely, and
`WithProxyAllowed()` re-enables honouring proxy environment variables.
Use them only for tests or trusted egress paths. Prefer
`WithAllowedHosts` for a targeted exception.


## Shutdown

`Shutdown` closes idle keep-alive connections held by the underlying
transport, honouring the context deadline. In-flight requests are not
cancelled, so drive that through the request context:

```go
if err := c.Shutdown(ctx); err != nil {
    return err
}
```

## Design notes

- **One call = one event.** No sampling inside the client. Filter in
  listeners if volume is a concern.
- **No retries.** `httpclient` doesn't retry failed requests; compose a
  retry loop in your caller when you need it, or plug in a custom
  `*http.Client` via `WithHTTPClient`.
- **No middleware chain.** Wrap the client if you need cross-cutting
  behavior (auth headers, circuit breakers) rather than extending it.


================================================================================
# Command Bus

Source: https://vel.build/docs/advanced/bus/
Section: Advanced Topics
Summary: Type-safe command dispatch with middleware, self-handling commands, and async queue delivery.


The `bus` package implements a typed command bus. Commands are plain
structs; handlers are generic functions; middleware composes through
the `pipeline` package. Commands can be dispatched synchronously or
pushed to the queue.

Import path: `github.com/velocitykode/velocity/bus`

## Commands and handlers

A command is any struct. A handler is a function with a single typed
argument:

```go
type CreateInvoice struct {
    UserID int
    Amount int
}

func handleCreateInvoice(cmd CreateInvoice) error {
    // ...
    return nil
}
```

Register the handler against the command type:

```go
b := bus.New()
bus.Register(b, handleCreateInvoice)
```

`Register` is a package-level function (not a method) because Go
generics don't allow type parameters on methods.

`Register` panics with `*contract.RegistrationError` if the handler is
nil, a handler for the same command type is already registered, or the
command type is not JSON-serializable. Serializability is probed at
registration time (a zero value is round-tripped through
`encoding/json`) so that async dispatch can never fail later with an
obscure marshal error.

## Dispatching

```go
err := b.Dispatch(CreateInvoice{UserID: 1, Amount: 5000})
```

`Dispatch` looks up the registered handler, runs any middleware, and
invokes the handler. If no handler is registered it returns an error.

### Self-handling commands

A command can carry its own handler by implementing `SelfHandling`:

```go
type SendReminder struct { UserID int }

func (c SendReminder) Handle() error {
    // send the reminder
    return nil
}

// No Register() call needed - the bus falls back to the Handle method.
b.Dispatch(SendReminder{UserID: 42})
```

## Middleware

Middleware is a `pipeline.Stage[Command]` - use `bus.Middleware` to
build one from a function:

```go
logging := bus.Middleware(func(cmd bus.Command, next func(bus.Command) error) error {
    start := time.Now()
    err := next(cmd)
    log.Info("command", "type", fmt.Sprintf("%T", cmd), "dur", time.Since(start), "err", err)
    return err
})

b.Through(logging, anotherMiddleware)
```

Stages run in order for each dispatch, wrapping the handler in a
pipeline.

`bus.LoggingMiddleware(logger)` is a ready-to-use logger stage.

## Async dispatch

Push commands to the queue to run later in a worker:

```go
b.SetQueue(v.Queue)            // anything implementing QueuePusher
b.SetQueueName("notifications") // optional - otherwise default queue

b.DispatchAsync(CreateInvoice{UserID: 1, Amount: 5000})
```

`QueuePusher` is the single-method slice of the queue driver that async
dispatch needs:

```go
type QueuePusher interface {
    PushCtx(ctx context.Context, job contract.QueueJob, queue ...string) error
}
```

Every shipped driver (memory, database, Redis) and the `queuetest`
fakes satisfy it directly.

The command is wrapped as a queue job; when the worker picks it up it
calls `Dispatch` internally so the same handler + middleware chain
runs.

The command **must be registered with `bus.Register` on this bus** before
it can be dispatched asynchronously - the registration installs the
factory the worker uses to rehydrate the command from its serialized
payload. `DispatchAsync` refuses to enqueue (returning an error) when no
factory is registered for the command type, so a missing `Register` call
is caught at the producer instead of silently routing the job to
`failed_jobs`. Self-handling commands with no `Register` call therefore
cannot be dispatched asynchronously.

`DispatchAsync` enqueues with a background context. Prefer
`DispatchAsyncCtx` so that a client disconnect, deadline, or graceful
shutdown aborts the enqueue before it reaches the backing store:

```go
b.DispatchAsyncCtx(ctx, CreateInvoice{UserID: 1, Amount: 5000})
```

### Cross-process workers

Every bus has a stable id (`b.ID()`) that is written onto every queued
job. The consumer side uses it to route hydration back through the
originating bus, which prevents cross-bus contamination when several
buses are in play (multi-tenant apps, plugin systems, per-test buses).

`bus.New()` assigns a random UUID, which is sufficient when the worker
runs in the same process as the producer (the memory driver, or a
same-process consumer of a durable driver). When the worker runs in a
**separate process** from the producer, pin a deterministic id with
`bus.NewWithID` on both sides so producer and consumer agree:

```go
b := bus.NewWithID("orders-bus")
```

`NewWithID` panics with `*contract.RegistrationError` if the id is empty
or another bus is already registered under the same id. Call `b.Close()`
to remove the bus from the registry when you are done with it; this is
optional, as the registry entry otherwise lives for the process
lifetime.

## Events

Every dispatch emits lifecycle events:

- `*bus.CommandDispatching` - before the handler runs
- `*bus.CommandCompleted` - on success
- `*bus.CommandFailed` - on handler error
- `*bus.CommandQueued` - on `DispatchAsync`

Wire the dispatcher:

```go
b.SetEventDispatcher(v.Events.Dispatch)
```

## Testing

`FakeBus` records dispatched commands without running handlers - handy
for isolating handler tests:

```go
fake := bus.NewFakeBus()
svc := NewOrderService(fake)

svc.Checkout(ctx, order)

if err := fake.AssertDispatched(SendReceipt{}); err != nil {
    t.Error(err)
}
```

Assertions available on `*FakeBus`:

- `AssertDispatched(cmd)` - at least one command of that type was dispatched
- `AssertDispatchedTimes(cmd, n)` - exactly n times
- `AssertNotDispatched(cmd)` - zero times
- `AssertNothingDispatched()` - no commands at all
- `AssertAsyncDispatched(cmd)` - dispatched via `DispatchAsync`
- `GetDispatched()` / `ClearDispatched()` - inspect or reset the log


================================================================================
# Collections

Source: https://vel.build/docs/advanced/collect/
Section: Advanced Topics
Summary: Generic, type-safe collection helpers for slices - filter, map, reduce, group, and more.


The `collect` package is a library of generic slice helpers. Every
function takes a `[]T` and returns a new slice (or scalar) - inputs
are never mutated. Two APIs are provided: free functions and a
fluent `*Collection[T]`.

Import path: `github.com/velocitykode/velocity/collect`

## Free functions

```go
import "github.com/velocitykode/velocity/collect"

users := []User{ /* ... */ }

adults := collect.Filter(users, func(u User) bool { return u.Age >= 18 })
names  := collect.Map(adults, func(u User) string { return u.Name })
total  := collect.Sum(users, func(u User) float64 { return float64(u.Spend) })
```

### Transforms

| Function          | Behavior                                                    |
| ----------------- | ----------------------------------------------------------- |
| `Filter`          | keep elements where `fn(x)` is true                         |
| `Reject`          | inverse of `Filter`                                         |
| `Map[T,R]`        | project `[]T` → `[]R`                                       |
| `FlatMap[T,R]`    | project each to `[]R`, concatenate                          |
| `Reduce[T,R]`     | fold into a single `R`                                      |
| `Pluck[T,R]`      | extract one field per element                               |
| `Reverse`         | reverse order                                               |
| `Sort` / `SortBy` / `SortByDesc` | sort (custom comparator / keyfn)             |
| `Unique` / `UniqueBy` | dedupe (by value / by keyfn)                            |
| `Chunk`           | split into equal-sized groups                               |
| `Flatten`         | `[][]T` → `[]T`                                             |
| `Take` / `Skip`   | first n / after first n                                     |
| `Shuffle`         | random order                                                |
| `Partition`       | split by predicate into `(matches, rest)`                   |
| `Zip[T,U,R]`      | combine two slices pairwise                                 |
| `Times[T]`        | build a slice of length n by calling `fn(i)`                |

### Predicates

| Function          | Behavior                                                    |
| ----------------- | ----------------------------------------------------------- |
| `Contains`        | any element matches                                         |
| `Every`           | all elements match                                          |
| `None`            | zero elements match                                         |
| `CountBy`         | count of matching elements                                  |

### Element access

`First`, `Last`, `FirstWhere` - return `(T, ok)`; `ok` is false when
nothing matched or the slice is empty.

```go
if first, ok := collect.First(users, func(u User) bool { return u.IsAdmin }); ok {
    // use first
}
```

### Aggregation

`Sum`, `Min`, `Max` - `Min` and `Max` return `(T, ok)` so they can
signal empty slices.

```go
total := collect.Sum(orders, func(o Order) float64 { return o.Total })

if mostExpensive, ok := collect.Max(orders, func(o Order) float64 { return o.Total }); ok {
    // use mostExpensive
}
```

### Grouping

```go
byRegion := collect.GroupBy(users, func(u User) string { return u.Region })
// map[string][]User

byID := collect.KeyBy(users, func(u User) int { return u.ID })
// map[int]User  (last-wins on duplicates)
```

### Set operations

`Intersect`, `Diff`, `Partition`, `Shuffle`.

```go
common := collect.Intersect(teamA, teamB)
only   := collect.Diff(teamA, teamB)
```

### Imperative helpers

- `Each` - side-effect iteration
- `Tap` - inspect the slice mid-chain (with fluent API)
- `Pop` / `Push` - immutable stack operations
- `When` - apply a transform only if a condition holds

## Fluent Collection API

`From[T]` wraps a slice so calls chain:

```go
result := collect.From(users).
    Filter(func(u User) bool { return u.Active }).
    Sort(func(a, b User) bool { return a.Name < b.Name }).
    Take(10).
    All()
```

Every method returns `*Collection[T]` so the chain reads top-to-bottom.
Terminal methods:

- `All()` - unwrap to `[]T`
- `Count()`, `IsEmpty()`, `IsNotEmpty()`
- `First`, `Last`, `FirstWhere` - return `(T, ok)`
- `Contains`, `Every`, `None`
- `Chunk(n)` - returns `[][]T` (ends the chain)
- `Pop` - returns `(*Collection[T], T, ok)`

## Design notes

- **Immutable by default.** `Filter`, `Sort`, `Reverse`, etc. return new
  slices - they never mutate their argument.
- **Generic over comparable / ordered where needed.** `Unique` and
  `Intersect` require `T comparable`; `SortBy` requires
  `cmp.Ordered` on the key.
- **No lazy evaluation.** Each function materializes its result.
  For huge streams use iterators from `iter` (stdlib) or channels -
  `collect` is for in-memory collections.


================================================================================
# Pipeline

Source: https://vel.build/docs/advanced/pipeline/
Section: Advanced Topics
Summary: Generic, type-safe middleware-style pipeline for threading values through sequential stages.


The `pipeline` package is a generic "chain of responsibility". A value
passes through a series of stages; each stage can inspect, transform,
short-circuit, or forward the value to the next.

Import path: `github.com/velocitykode/velocity/pipeline`

## Stages

```go
type Stage[T any] interface {
    Handle(passable T, next func(T) error) error
}
```

Any struct implementing `Handle` is a stage. For one-off stages the
`Pipe[T]` adapter turns a function into a `Stage[T]`:

```go
trim := pipeline.Pipe[*Request](func(r *Request, next func(*Request) error) error {
    r.Body = strings.TrimSpace(r.Body)
    return next(r)
})
```

## Building and running

```go
result := pipeline.New[*Request]().
    Send(req).
    Through(trim, validate, authorize).
    Then(func(r *Request) error {
        return handle(r)
    })
```

- `Send(v)` - set the value passing through
- `Through(stages...)` - replace the stage list
- `Add(stages...)` - append to the stage list
- `Then(final)` - run the pipeline ending at `final`
- `ThenReturn()` - run the pipeline with a no-op terminal; use when all
  work happens inside stages

## Pre-compiling

`Build` compiles the stage chain once and returns a callable you can
invoke many times - useful when a pipeline is shared across requests:

```go
chain := pipeline.New[*Request]().
    Through(trim, validate, authorize).
    Build(handle)

// Later:
err := chain(req)
```

## Short-circuiting

A stage that does not call `next(passable)` stops the chain. Return
`nil` or an error to indicate why:

```go
cacheStage := pipeline.Pipe[*Request](func(r *Request, next func(*Request) error) error {
    if cached, ok := cache.Get(r.Key); ok {
        r.Result = cached
        return nil  // skip remaining stages
    }
    return next(r)
})
```

## Mutating the passable

Pipelines pass by whatever semantics `T` has - pointers propagate
mutations, values don't. The examples above use `*Request` so stages
can mutate in place.

## Where it's used in Velocity

The `bus` package uses `pipeline.Stage[bus.Command]` for command
middleware. You can use it directly anywhere you want to compose
sequential processing steps with short-circuit semantics.

## Concurrency

`Pipeline` is not safe for concurrent use during construction. Build
the pipeline (or call `Build`) on a single goroutine; the resulting
chain can be invoked from many goroutines provided the stages
themselves are safe.


================================================================================
# Webhooks

Source: https://vel.build/docs/advanced/webhook/
Section: Advanced Topics
Summary: Primitives for signing, verifying, and retrying webhook deliveries.


The `webhook` package ships three composable primitives for outbound and
inbound webhook plumbing: a `Signer` that produces a Stripe-style header,
a `Verifier` that validates the same header in constant time, and a
`RetryPolicy` for exponential backoff with jitter. The package is a leaf
that depends only on the Go standard library, so you can compose it with
your own queue, transport, or HTTP client of choice.

Import path: `github.com/velocitykode/velocity/webhook`


This package intentionally ships no delivery service, admin UI, or job
runner. Pair `Signer` with [`httpclient`](/docs/advanced/httpclient/) for
outbound delivery and [`queue`](/docs/advanced/queue/) for durable
retries.


## Decision matrix

| Situation | Helper |
|---|---|
| Sign an outbound payload | `NewSigner(secret).Header(payload)` |
| Verify an incoming payload | `NewVerifier(secret).Verify(payload, header)` |
| Reject replays of a previously verified payload | Set `Verifier.Nonces` to a `NonceStore` |
| Opt out of timestamp freshness checks | Set `Verifier.DisableTimestampCheck = true` |
| Schedule the next retry attempt | `DefaultRetryPolicy.Next(attempt)` |
| Plug in a non-default MAC primitive | Implement `Algorithm` and assign it to `Signer.Algorithm` / `Verifier.Algorithm` |

## Signer

`Signer` produces a signature header value over a payload using a
pluggable `Algorithm` and a shared `Secret`. The default algorithm is
`HMACSHA256`; supply your own implementation of the `Algorithm`
interface to swap in a different MAC.

```go
type Algorithm interface {
    Name() string
    Sign(secret, payload []byte) []byte
}
```

Construct a signer with `NewSigner(secret []byte) *Signer`, which
preconfigures `HMACSHA256`. The struct fields are exported so tests can
override the time source via `Now func() time.Time`.

```go
s := webhook.NewSigner([]byte(os.Getenv("WEBHOOK_SECRET")))

header, err := s.Header(payload)
if err != nil {
    return err
}
// header == "t=1714972800,v1=4f3c...e9"
req.Header.Set("X-Signature", header)
```

`Header` returns a fully-formed `t=<unix>,v1=<hex>` value. The format
mirrors Stripe's webhook signature scheme: the timestamp is part of the
signed material, so a verifier can reject stale or replayed deliveries
without trusting the header alone.

If you need the raw parts:

```go
sig, ts, err := s.Sign(payload)
// sig is hex-encoded HMAC, ts is the unix-second timestamp string
```

`Sign` returns `ErrNoAlgorithm` if `Algorithm` is nil and
`ErrMissingSecret` if `Secret` is empty.


The MAC is computed over `<timestamp>.<payload>`, not over `payload`
alone. Without that framing, an attacker who captures a valid header
could swap the visible `t=` value for a fresh one and the MAC would
still verify. Framing binds the timestamp into the signed bytes so the
verifier rejects any tampered timestamp.


## Verifier

`Verifier` parses a header, recomputes the MAC over the same framed
payload, and compares in constant time using `crypto/subtle`. A
`Tolerance` window rejects timestamps that are too far behind or ahead
of the current clock.

`NewVerifier` sets `Algorithm` to `HMACSHA256` and `Tolerance` to its
default of 5 minutes. A zero-value `Verifier` literal must set
`Algorithm` explicitly - defaults are not auto-applied on the bare
struct.

```go
v := webhook.NewVerifier([]byte(os.Getenv("WEBHOOK_SECRET")))
// Tolerance defaults to 5 minutes

if err := v.Verify(payload, r.Header.Get("X-Signature")); err != nil {
    http.Error(w, "invalid signature", http.StatusUnauthorized)
    return
}
```

Use `VerifyContext(ctx, payload, header)` when the underlying
`NonceStore` should observe request cancellation.

`Verify` returns one of the following sentinel errors:

| Error | Meaning |
|---|---|
| `ErrMalformedHeader` | Header is missing, has wrong format, or contains a non-numeric timestamp / non-hex signature. |
| `ErrMissingSecret` | `Verifier.Secret` is nil or empty. |
| `ErrNoAlgorithm` | `Verifier.Algorithm` is nil. |
| `ErrTimestampOutOfTolerance` | `|now - signedAt| > Tolerance`. |
| `ErrSignatureMismatch` | Recomputed MAC does not match the supplied signature. |
| `ErrReplay` | A `NonceStore` is configured and the nonce was already observed. |

Leaving `Tolerance` at its zero value does **not** disable the timestamp
check - zero is treated as the 5-minute default so a zero-value
`Verifier` still rejects stale signatures. To skip freshness validation
entirely, set `DisableTimestampCheck = true`:

```go
v := webhook.NewVerifier(secret)
v.DisableTimestampCheck = true // a correctly signed payload verifies forever
```


With `DisableTimestampCheck` set, any captured delivery can be re-sent
indefinitely unless you also configure a `NonceStore` in `Nonces`. Even
then the nonce TTL is finite, so a replay arriving after the nonce
expires is accepted again. Only opt out when an upstream provider cannot
produce timestamps and replay is mitigated elsewhere.



The errors above are deliberately opaque: they never embed the payload,
secret, or computed MAC. Log the error value, return a generic 401 to
the remote peer, and resist the urge to surface the exact failure
reason in the response body.


## NonceStore

When `Verifier.Nonces` is non-nil, the hex signature itself is used as
the nonce and a successful verification additionally records that nonce
so a second delivery of the same signed payload returns `ErrReplay`.
The TTL written to the store equals `Verifier.Tolerance` (or 5 minutes
when `Tolerance` is zero), so expired signatures cannot be replayed
indefinitely.

```go
type NonceStore interface {
    CheckAndMark(ctx context.Context, nonce string, ttl time.Duration) (alreadySeen bool, err error)
}
```

`CheckAndMark` is a single atomic operation. A naive `Seen(nonce)`
followed by `Mark(nonce)` allows two concurrent verifications of the
same payload to both observe `alreadySeen=false` and both succeed; the
single-call shape eliminates that TOCTOU window by construction.

### Memory driver

Import path: `github.com/velocitykode/velocity/webhook/drivers/nonce`

```go
import nonceMem "github.com/velocitykode/velocity/webhook/drivers/nonce"

store := nonceMem.NewMemory(1 * time.Minute) // sweep interval
defer store.Close(context.Background())

v := webhook.NewVerifier(secret)
v.Nonces = store
```

The memory driver is appropriate for development, single-process
deployments, and tests. It is backed by a `sync.RWMutex`-protected map
with two expiry mechanisms working together:

- **Lazy expiry on read.** `CheckAndMark` checks the stored expiry
  before deciding whether the nonce is still live; an expired entry is
  treated as absent and overwritten with a fresh TTL.
- **Background sweep.** A goroutine scoped to the sweep interval scans
  the map and deletes entries whose expiry has passed. Pass a
  non-positive interval to `NewMemory` to disable the sweep entirely
  (entries still expire on read but stale records accumulate until
  process restart).

The sweep loop wraps each tick in a deferred `recover` so a transient
panic in one iteration never silently disables nonce expiry for the
lifetime of the process. Install an observer with
`store.SetOnPanic(fn func(any))` to surface those recovered panics
through your logger or metrics pipeline.

`store.Len()` reports the current map size (including not-yet-swept
expired entries) and is primarily useful for tests.


The memory driver is process-local. Replicas behind a load balancer
each maintain their own nonce set, so the same payload delivered to two
replicas would verify on both. Ship a Redis or database-backed driver
implementing `webhook.NonceStore` for replay protection across
processes.


## RetryPolicy

`RetryPolicy` describes an exponential-backoff schedule with bounded
uniform jitter and a hard attempt cap. The schedule for attempt `N`
(0-indexed) is:

```
delay = min(BaseDelay * Factor^attempt, Cap)
delay = delay + uniform(-Jitter*delay, +Jitter*delay)
```

```go
type RetryPolicy struct {
    BaseDelay   time.Duration
    Factor      float64
    MaxAttempts int
    Jitter      float64
    Cap         time.Duration
}
```

`DefaultRetryPolicy` is a sensible starting point: 1s base, factor 2,
8 attempts max, 20% jitter, capped at 5 minutes.

```go
p := webhook.DefaultRetryPolicy

for attempt := 0; ; attempt++ {
    err := deliver(ctx, payload)
    if err == nil {
        return nil
    }
    delay, ok := p.Next(attempt)
    if !ok {
        // Out of attempts; route to dead-letter sink.
        return err
    }
    select {
    case <-time.After(delay):
    case <-ctx.Done():
        return ctx.Err()
    }
}
```

`Next(attempt int) (time.Duration, bool)` returns `(0, false)` once
`attempt >= MaxAttempts`. Treat the second return as "stop retrying"
and route the work to a dead-letter sink of your choice.

Field semantics:

- `Factor <= 1` disables growth: every retry happens at `BaseDelay`,
  still subject to jitter and `Cap`.
- `Jitter` is clamped to `[0, 1]`. A value of `0.2` yields a delay
  uniformly distributed in `[0.8*delay, 1.2*delay]`.
- `Cap == 0` disables the upper bound on the exponential delay.
- Negative `attempt` is treated as `0`; negative `BaseDelay` is treated
  as `0`.

Jitter is sampled from `math/rand/v2`'s package-level generator
(ChaCha8-backed, seeded from OS entropy at package init). Jitter is
not security-critical but the source is non-predictable enough to keep
synchronized retry storms from forming across replicas.

## Recipe: sign and send an outbound webhook

**When:** your service publishes an event to a customer-supplied URL
and you want their handler to be able to authenticate the call.

```go
import (
    "bytes"
    "context"
    "encoding/json"
    "net/http"
    "time"

    "github.com/velocitykode/velocity/httpclient"
    "github.com/velocitykode/velocity/webhook"
)

func deliver(ctx context.Context, c *httpclient.Client, url string, secret []byte, event any) error {
    payload, err := json.Marshal(event)
    if err != nil {
        return err
    }

    s := webhook.NewSigner(secret)
    header, err := s.Header(payload)
    if err != nil {
        return err
    }

    req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
    if err != nil {
        return err
    }
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-Webhook-Signature", header)

    p := webhook.DefaultRetryPolicy
    for attempt := 0; ; attempt++ {
        resp, err := c.Do(ctx, req)
        if err == nil && resp.StatusCode < 500 {
            resp.Body.Close()
            return nil
        }
        if resp != nil {
            resp.Body.Close()
        }
        delay, ok := p.Next(attempt)
        if !ok {
            return err
        }
        select {
        case <-time.After(delay):
        case <-ctx.Done():
            return ctx.Err()
        }
    }
}
```

**Why this shape:** the signer produces the header once per payload,
not once per retry, so identical bytes hit the wire on every attempt
and the receiver's idempotency keys work as intended. The retry policy
treats only 5xx responses (and transport errors) as retryable.

## Recipe: verify an incoming webhook with replay protection

**When:** you receive webhooks from an upstream provider and want to
reject both forged signatures and replays.

```go
import (
    "context"
    "errors"
    "io"
    "net/http"
    "time"

    "github.com/velocitykode/velocity/webhook"
    nonceMem "github.com/velocitykode/velocity/webhook/drivers/nonce"
)

var (
    secret = []byte("...")
    store  = nonceMem.NewMemory(1 * time.Minute)
)

func handle(w http.ResponseWriter, r *http.Request) {
    payload, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "read", http.StatusBadRequest)
        return
    }
    defer r.Body.Close()

    v := webhook.NewVerifier(secret)
    v.Tolerance = 5 * time.Minute
    v.Nonces = store

    err = v.VerifyContext(r.Context(), payload, r.Header.Get("X-Webhook-Signature"))
    switch {
    case errors.Is(err, webhook.ErrReplay):
        // Already processed; ack idempotently rather than 401.
        w.WriteHeader(http.StatusOK)
        return
    case err != nil:
        http.Error(w, "unauthorized", http.StatusUnauthorized)
        return
    }

    // Process the verified payload...
    w.WriteHeader(http.StatusOK)
}
```

**Why this shape:** reading the raw body before parsing is essential -
the signature is over those exact bytes. The `ErrReplay` branch returns
200 instead of 401 because a duplicate is the upstream's retry doing
its job, not an attack.

## Related

- [HTTP Client](/docs/advanced/httpclient/) - instrumented outbound
  client; pair with `Signer` for signed deliveries.
- [Queue System](/docs/advanced/queue/) - durable background workers;
  enqueue webhook deliveries so retries survive restarts.
- [Events](/docs/advanced/events/) - in-process pub/sub; a typical
  trigger for outbound webhook fan-out.


================================================================================
# Feature Flags

Source: https://vel.build/docs/advanced/flags/
Section: Advanced Topics
Summary: Minimal Driver interface, request-scoped overrides, and an in-memory driver for tests.


The `flags` package is the framework's feature-flag adapter surface.
It ships only a `Driver` interface, a top-level `Enabled` helper,
context attachment, a process-wide default slot, and a memory driver
for tests and local development. Production deployments are expected
to plug in a third-party SaaS (LaunchDarkly, Unleash, PostHog,
Statsig, Flagsmith) or a community adapter behind the same interface.

Higher-level concerns - rollout strategies, percentage hashing, cohort
targeting, registries, and admin UI - are deliberately out of scope.

Import path: `github.com/velocitykode/velocity/flags`

## Driver interface

```go
type Driver interface {
    Enabled(ctx context.Context, name string) bool
}
```

Implementations must be safe for concurrent use and should return
`false` for unknown flags.

## Package-level helpers

```go
flags.SetDefault(d)                           // install process-wide default
d := flags.Default()                          // read it back (may be nil)

ctx = flags.WithDriver(ctx, d)                // request-scoped override
on := flags.Enabled(ctx, "checkout.v2")       // resolve a flag
```

`Enabled` resolves in this order:

1. Driver attached to `ctx` via `WithDriver` - the request-scoped
   override.
2. Process-wide default installed via `SetDefault`.
3. `false` - unknown flag stays off.

`SetDefault` is safe for concurrent use; pass `nil` to clear the
default. `WithDriver` accepts a nil context and falls back to
`context.Background()`.

## MemoryDriver

`MemoryDriver` is an in-process driver backed by a map. Use it in
tests, in local development, or in small single-process apps;
production systems should sit a real SaaS adapter behind the
`Driver` interface.

```go
m := flags.NewMemoryDriver(map[string]bool{
    "checkout.v2": true,
    "new-search":  false,
})

m.Enabled(ctx, "checkout.v2") // true
m.Enabled(ctx, "missing")     // false
```

`NewMemoryDriver` copies the seed map, so later mutations to the
caller's map do not affect the driver. A nil seed is treated as
empty.

### Mutating flags

```go
m.Set("new-search", true)                       // toggle one flag
m.SetAll(map[string]bool{"checkout.v2": true})  // replace every flag
```

`SetAll` builds the replacement map and swaps it under the same write
lock that guards `Set`, so a concurrent `Set` cannot be silently
overwritten between the build and the swap. Passing `nil` to `SetAll`
clears every flag.

The driver has no `Delete` method - drop a flag by calling
`SetAll` with a map that omits it, or set it to `false`.

## Recipes

### Set up a process-wide default driver

Install one driver during boot (typically a module `Start` hook, which
runs after every module has been initialized) so every code path can
call `flags.Enabled` without threading the driver explicitly:

```go
func (m *AppModule) Start(s *velocity.Services) error {
    on, _ := strconv.ParseBool(os.Getenv("FLAGS_CHECKOUT_V2"))
    flags.SetDefault(flags.NewMemoryDriver(map[string]bool{
        "checkout.v2": on,
    }))
    return nil
}
```

Anywhere in the app:

```go
if flags.Enabled(ctx, "checkout.v2") {
    return checkoutV2(ctx, order)
}
return checkoutV1(ctx, order)
```

### Override flags per-request via middleware

Attach a request-scoped driver when a header, cookie, or user
attribute should flip flags for the duration of one request - useful
for QA overrides or staff dogfooding:

```go
func StaffOverrides() router.MiddlewareFunc {
    return func(next router.HandlerFunc) router.HandlerFunc {
        return func(ctx *router.Context) error {
            if m := auth.FromContext(ctx); m != nil {
                if user := m.User(ctx.Request); user != nil && m.Access().HasRole(user, "staff") {
                    d := flags.NewMemoryDriver(map[string]bool{
                        "checkout.v2": true,
                        "new-search":  true,
                    })
                    ctx.Request = ctx.Request.WithContext(
                        flags.WithDriver(ctx.Request.Context(), d),
                    )
                }
            }
            return next(ctx)
        }
    }
}
```

The request-scoped driver takes precedence over the process-wide
default, so handlers downstream see the staff-flipped flags without
any other code change.

## Related

- [Middleware](/docs/core/middleware/) - the natural attachment point for `WithDriver` when a header or user attribute should flip flags per request
- [Config](/docs/core/config/) - read flag seeds from the environment so the same memory driver can boot from `.env`


================================================================================
# Events

Source: https://vel.build/docs/advanced/events/
Section: Advanced Topics
Summary: Build event-driven applications with Velocity's observer pattern for decoupled, extensible architecture.


Velocity provides a powerful event system that allows you to decouple various parts of your application using the observer pattern. Events enable clean, maintainable code by separating concerns and making your application more extensible.


Every callback in the events package takes `context.Context` as its first
positional argument. Migrate your code as follows:

```text
Handle(event)         -> Handle(ctx, event)
Dispatch(event)       -> Dispatch(ctx, event)
Created(model)        -> Created(ctx, model)
SetEventDispatcher(fn func(any) error) ->
    SetEventDispatcher(fn func(context.Context, any) error)
```

The same shape applies to `DispatchNow`, `DispatchAsync`, `DispatchAfter`,
`Until`, every `ModelObserver` lifecycle method, `MiddlewareFunc`,
`HandleWithResult`, `HandleWithPropagation`, `AsyncDispatcher.Push`,
`TransactionalDispatcher.Commit` / `DispatchAfterCommit`,
`ObserverRegistry.Fire` / `FireModelEvent`, `ObservableModel.FireEvent`,
and `QueueDispatcher.Push`. Subsystems that implement
`contract.EventDispatcherAware` plumb their own ctx into the bridge instead
of dropping to `context.Background()`.



The listener queue opt-in on `contract.EventListener` (aliased as
`events.Listener`) is `Async() bool`. The old `ShouldQueue()` name is gone,
and a type that still declares it no longer satisfies the interface:

```text
func (l *MyListener) ShouldQueue() bool  ->  func (l *MyListener) Async() bool
```

The full interface is `Handle(ctx, event) error` plus `Async() bool`. The
queue-configuration methods on `events.QueuedListener` (`OnConnection`,
`OnQueue`, `WithDelay`, `Tries`) are unchanged, as is the conditional
`ShouldHandle(event) bool` hook, which is a different interface and keeps
its name.


## Quick Start




```go
import "github.com/velocitykode/velocity/events"

// Define an event
type UserRegistered struct {
    UserID int
    Email  string
}

func (e UserRegistered) Name() string {
    return "user.registered"
}

// Dispatch the event from a handler. ctx.Events() returns the
// app-wide events.Dispatcher wired up at boot. Pass the request ctx
// so listeners observe deadlines, trace IDs, and tx scopes.
func (h *AuthHandler) Register(ctx *router.Context) error {
    user := createUser(ctx.FormValue("email"), ctx.FormValue("password"))

    return ctx.Events().Dispatch(ctx.Request.Context(), UserRegistered{
        UserID: user.ID,
        Email:  user.Email,
    })
}
```



```go
// Define a listener. Handle now takes ctx as the first argument.
type SendWelcomeEmail struct{}

func (l *SendWelcomeEmail) Handle(ctx context.Context, event interface{}) error {
    e := event.(UserRegistered)

    // Send welcome email; honour ctx.Done() if the sink supports it.
    return sendEmail(ctx, e.Email, "Welcome to our platform!")
}

func (l *SendWelcomeEmail) Async() bool {
    return true // Process asynchronously
}

// Register the listener through the App.Events hook. App.Events is a
// builder method that takes a func(events.Dispatcher) callback, run at
// boot once the dispatcher is wired.
app.Events(func(d events.Dispatcher) {
    d.Listen("user.registered", &SendWelcomeEmail{})
})
```



```go
// Create a logger that handles all user events.
type UserActivityLogger struct{}

func (l *UserActivityLogger) Handle(ctx context.Context, event interface{}) error {
    log.InfoContext(ctx, "User event occurred", "event", event)
    return nil
}

func (l *UserActivityLogger) Async() bool {
    return false
}

// Listen to wildcards via the App.Events hook
app.Events(func(d events.Dispatcher) {
    // All user events
    d.Listen("user.*", &UserActivityLogger{})

    // All "created" events
    d.Listen("*.created", &AuditLogger{})

    // All events
    d.Listen("*", &GlobalLogger{})
})
```



```go
// Dispatch events asynchronously from a handler
func (h *OrderHandler) Place(ctx *router.Context, order *Order) error {
    rctx := ctx.Request.Context()

    // Save order synchronously
    if err := h.db.Create(rctx, order); err != nil {
        return err
    }

    // Dispatch asynchronously (queue when wired, else a panic-safe
    // goroutine fallback). On the no-queue fallback ctx is derived via
    // context.WithoutCancel: trace IDs flow through to listeners but
    // cancellation/deadline are stripped.
    if err := ctx.Events().DispatchAsync(rctx, OrderPlaced{
        OrderID: order.ID,
        Total:   order.Total,
    }); err != nil {
        return err
    }

    // Or dispatch after a delay
    return ctx.Events().DispatchAfter(
        rctx,
        OrderFollowUp{OrderID: order.ID},
        24*time.Hour,
    )
}
```




## Async ctx semantics

The standalone async wrappers -- `AsyncDispatcher.Push` and the
`BatchingDispatcher` / `DebouncingDispatcher` / `CoalescingDispatcher.Dispatch`
wrappers -- always derive the listener ctx from the caller via
`context.WithoutCancel`. That means:

- Request-scoped values (trace IDs, tenant IDs, anything stored via
  `context.WithValue`) propagate through to listeners.
- The caller's cancellation and deadline are **stripped** before dispatch,
  because the listener may legitimately outlive the caller (a 30s delayed
  listener kicked off from an HTTP handler keeps running long after the
  response flushed).

`Dispatcher.DispatchAsync` and `Dispatcher.DispatchAfter` follow the same
detach-from-cancellation rule **only on the no-queue fallback path**: when no
`QueueDispatcher` is wired they detach via `context.WithoutCancel` before
spawning the `async.Go` goroutine (`DispatchAsync`) or `time.AfterFunc` timer
(`DispatchAfter`). When a queue *is* wired they hand the caller's ctx straight
to `QueueDispatcher.Push`, and the cancellation contract is whatever your
queue driver implements. Either way the failure-event report runs
synchronously at the point of dispatch, before the work is queued or detached.

If you need cancellation to reach the listener, do not use the async
methods. Use `Dispatch` synchronously and let the listener spawn its own
goroutine that observes `ctx.Done()`, or push to a queue with the
cancellation contract you want.

The synchronous `Dispatch` / `DispatchNow` / `Until` paths pass ctx through
unchanged.

## Transactional dispatch buffer

Domain events that announce state changes (`OrderPlaced`, `UserRegistered`, `InvoicePaid`) should fire if-and-only-if the database transaction that produced the change actually commits. Dispatching them inside the transaction risks listeners reacting to writes that get rolled back; dispatching them after `Transaction` returns leaks transaction boundaries into every caller. The events package and `orm.Manager.Transaction` cooperate to give you commit-only semantics with no callback signature changes.

### How it fits together

Three pieces wire up the buffer:

1. `events.PrepareBuffer(ctx)` attaches a mutable holder to `ctx`. The returned `ctx` is the one you must thread into the transaction.
2. `orm.Manager.Transaction(ctx, fn)` installs a per-transaction `*events.BufferedDispatcher` into that holder for the lifetime of the call. Any `events.Buffer(ctx)` lookup inside `fn` (or any descendant call that received the same `ctx`) finds the buffer.
3. On successful `tx.Commit()` the buffer is flushed; on `fn` returning an error, the deferred panic recovery, or a commit failure, the buffer is dropped and no events fire.

`Manager.SetTxEventBus(bus)` wires the kind-aware sink the buffer drains into. The framework calls it during boot so `DispatchAsync`, `DispatchAfter`, and `Until` recorded inside the transaction route back through the matching ctx-aware method on the underlying dispatcher when the buffer flushes, so `Async`, the recorded delay, and the until-first-non-nil contract all survive the buffer boundary. The flush uses the parent transaction ctx so trace IDs, deadlines, and request-scoped values propagate all the way through to listeners. Without a tx event bus, the buffer falls back to the legacy untyped sink set by `SetEventDispatcher` (now itself ctx-aware) and every kind collapses onto `Dispatch`.

### Recipe: emit `OrderPlaced` only on tx commit

```go
func (h *OrderHandler) Place(ctx *router.Context) error {
    // Prepare the buffer holder on the request ctx ONCE, before
    // entering the transaction. The returned ctx must be the one
    // passed to Transaction.
    reqCtx := events.PrepareBuffer(ctx.Request.Context())

    return h.db.Transaction(reqCtx, func(txCtx context.Context) error {
        order, err := insertOrder(txCtx, ctx.FormValue("sku"))
        if err != nil {
            return err // buffer dropped, OrderPlaced never fires
        }

        // Recorded into the per-tx buffer; fires on commit. Use the tx
        // ctx Transaction hands the callback -- it carries the same
        // buffer holder, so events.Buffer(txCtx) finds the per-tx buffer.
        return events.Buffer(txCtx).Dispatch(txCtx, OrderPlaced{
            OrderID: order.ID,
            Total:   order.Total,
        })
    })
}
```

If `insertOrder` returns an error, `Transaction` rolls back and calls `Drop` on the buffer; `OrderPlaced` never reaches a listener. If the commit itself fails, the buffer is dropped for the same reason. Listeners on `order.placed` only ever observe orders that actually exist in the database.

### Nested transactions and savepoints

A nested `Transaction` call on the same prepared `ctx` reuses the outermost buffer with savepoint semantics. The inner scope captures a baseline at the parent's current event count, so an inner rollback truncates only events emitted past that checkpoint while the outer scope retains everything recorded before the nesting. Inner `Flush` is a no-op, so forwarding stays owned by the outermost commit and the entire transaction tree fires (or doesn't) atomically.

### Partial failure and retry

`FlushFunc` receives a `BufferedEvent` per recorded entry: `Event()` returns the user payload, `Kind()` returns the `DispatchKind` (`KindDispatch`, `KindDispatchNow`, `KindDispatchAsync`, `KindDispatchAfter`, `KindUntil`), and `Delay()` returns the requested delay for `KindDispatchAfter` (zero otherwise). If the flush callback returns an error for entry N, the failing entry plus every entry after it are swapped back into the buffer and the buffer is left in a non-flushed state. Calling `Flush` again resumes from the failed event; entries 0..N-1 are not redelivered. Re-entrant `Flush` invocations from inside a `FlushFunc` are silent no-ops so the outer drain retains control.


`events.Buffer(ctx)` returns a fresh standalone buffer when `ctx` carries no holder, and events recorded on a standalone buffer are silently discarded on flush (no underlying dispatcher is wired). Always thread the `ctx` returned by `PrepareBuffer` through to the call site that records events. A derived ctx without the holder will buffer into the void.


## DispatchAfterCommit

`TransactionalDispatcher.DispatchAfterCommit(ctx, event)` is the explicit
form for "fire this only if the current tx commits."

- Inside a tx (between `BeginTransaction` and `Commit` / `Rollback`) the
  event is queued and fires on `Commit(ctx)`.
- Outside a tx the event is dispatched immediately and any error from the
  underlying dispatcher is returned to the caller.

Both branches now return error. Previously the non-tx branch swallowed
dispatcher failures, which made the contract silently weaker outside a tx
than inside one. Wrap with `_ = dispatcher.DispatchAfterCommit(ctx, evt)`
if you genuinely want fire-and-forget semantics.

## Event Definition

### Using Structs

Define events as structs that implement the `Event` interface:

```go
type UserRegistered struct {
    UserID    int
    Email     string
    Timestamp time.Time
}

func (e UserRegistered) Name() string {
    return "user.registered"
}

type OrderPlaced struct {
    OrderID  string
    UserID   int
    Total    float64
    Items    []OrderItem
}

func (e OrderPlaced) Name() string {
    return "order.placed"
}
```

### Using Strings

For simple events, you can use strings directly. Resolve the dispatcher from the
`router.Context` (or the closure passed into `App.Events`) and call `Dispatch` on it.

```go
// Dispatch string events from a handler
ctx.Events().Dispatch(ctx.Request.Context(), "cache.cleared")
ctx.Events().Dispatch(ctx.Request.Context(), "maintenance.started")

// Listen to string events at boot
app.Events(func(d events.Dispatcher) {
    d.Listen("cache.cleared", &CacheListener{})
})
```

### Auto-Generated Names

If you don't implement the `Name()` method, Velocity will generate a name from the struct type:

```go
type UserRegistered struct {
    UserID int
    Email  string
}

// Automatically generates name: "user.registered"
// (CamelCase converted to dot.notation)
```

## Listeners

### Basic Listener

```go
type MyListener struct{}

func (l *MyListener) Handle(ctx context.Context, event interface{}) error {
    // Type assert to get event data
    e, ok := event.(UserRegistered)
    if !ok {
        return fmt.Errorf("unexpected event type")
    }

    // Process the event; honour ctx for cancellation when applicable.
    log.InfoContext(ctx, "Processing event", "user_id", e.UserID)
    return nil
}

func (l *MyListener) Async() bool {
    return false // Synchronous processing
}
```

### Queued Listener

For long-running tasks, use queued listeners:

```go
// Embedding QueuedBaseListener already supplies Async() == true plus
// default OnConnection / OnQueue / WithDelay / Tries. Override only the
// ones you want to change.
type SendWelcomeEmail struct {
    events.QueuedBaseListener
}

func (l *SendWelcomeEmail) Handle(ctx context.Context, event interface{}) error {
    e := event.(UserRegistered)

    // Send email (time-consuming operation)
    return emailService.Send(ctx, e.Email, "Welcome!")
}

func (l *SendWelcomeEmail) OnQueue() string {
    return "emails" // Queue name
}

func (l *SendWelcomeEmail) Tries() int {
    return 3 // Retry attempts
}

func (l *SendWelcomeEmail) WithDelay() time.Duration {
    return 5 * time.Second // Processing delay
}
```

### Conditional Listener

Execute listener logic only when conditions are met:

```go
type NotifyPremiumUsers struct{}

func (l *NotifyPremiumUsers) Handle(ctx context.Context, event interface{}) error {
    e := event.(FeatureReleased)
    return notificationService.NotifyPremium(ctx, e.FeatureName)
}

func (l *NotifyPremiumUsers) Async() bool {
    return true
}

func (l *NotifyPremiumUsers) ShouldHandle(event interface{}) bool {
    e, ok := event.(FeatureReleased)
    if !ok {
        return false
    }
    // Only handle premium features
    return e.IsPremium
}
```

## Event Subscribers

Subscribers let you group multiple event listeners in a single class:

```go
type UserEventSubscriber struct{}

func (s *UserEventSubscriber) Subscribe(dispatcher events.Dispatcher) {
    dispatcher.Listen("user.registered", &SendWelcomeEmail{})
    dispatcher.Listen("user.registered", &UpdateStatistics{})
    dispatcher.Listen("user.updated", &SyncUserData{})
    dispatcher.Listen("user.deleted", &CleanupUserData{})
}

// Register the subscriber via App.Events
app.Events(func(d events.Dispatcher) {
    d.Subscribe(&UserEventSubscriber{})
})
```

### Auto Subscriber

Automatically register methods as listeners based on naming convention.
Both the legacy `(event)` shape and the preferred `(ctx, event)` shape are
accepted; new code should write the ctx-aware form.

```go
type UserSubscriber struct{}

// HandleUserRegistered -> listens to "user.registered"
func (s *UserSubscriber) HandleUserRegistered(ctx context.Context, event interface{}) error {
    e := event.(UserRegistered)
    log.InfoContext(ctx, "User registered", "user_id", e.UserID)
    return nil
}

// HandleUserUpdated -> listens to "user.updated"
func (s *UserSubscriber) HandleUserUpdated(ctx context.Context, event interface{}) error {
    e := event.(UserUpdated)
    log.InfoContext(ctx, "User updated", "user_id", e.UserID)
    return nil
}

// Register auto subscriber
app.Events(func(d events.Dispatcher) {
    d.Subscribe(events.NewAutoSubscriber(&UserSubscriber{}, "Handle"))
})
```

### Mapped Subscriber

Explicitly map methods to events:

```go
type OrderSubscriber struct{}

func (s *OrderSubscriber) ProcessOrder(ctx context.Context, event interface{}) error {
    // Handle order.placed event
    return nil
}

func (s *OrderSubscriber) CancelOrder(ctx context.Context, event interface{}) error {
    // Handle order.cancelled event
    return nil
}

// Register with explicit mapping
app.Events(func(d events.Dispatcher) {
    d.Subscribe(events.NewMappedSubscriber(&OrderSubscriber{}, events.EventMap{
        "ProcessOrder": "order.placed",
        "CancelOrder":  "order.cancelled",
    }))
})
```

## Registering Listeners from a Module

`App.Events` is the inline hook used throughout this page. In a scaffolded app
the registrations usually live on a module instead, so each area of the app
owns its own listeners. A module is an `app.Module` (re-exported as
`velocity.Module`) implementing `Init(s *velocity.Services) error`,
`Start(s *velocity.Services) error`, and `Shutdown(ctx context.Context) error`.
Adding an `Events(d events.Dispatcher)` method opts the module into
`velocity.EventModule` (an alias of `chain.EventModule`) and bootstrap wires
its listeners for you.

```go
// internal/modules/billing.go
package modules

import (
    "context"

    "github.com/velocitykode/velocity"
    "github.com/velocitykode/velocity/events"
)

type BillingModule struct{}

func (m *BillingModule) Init(s *velocity.Services) error    { return nil }
func (m *BillingModule) Start(s *velocity.Services) error   { return nil }
func (m *BillingModule) Shutdown(ctx context.Context) error { return nil }

// Events satisfies velocity.EventModule. Bootstrap calls it with the
// app-wide dispatcher.
func (m *BillingModule) Events(d events.Dispatcher) {
    d.Listen("order.placed", &ChargeCard{})
    d.Listen("invoice.paid", &SendReceipt{})
    d.Subscribe(&BillingSubscriber{})
}
```

Register the module on the bootstrap chain:

```go
app.Modules(func(r *velocity.ModuleRegistry) {
    r.Add(&modules.BillingModule{})
})
```

`velocity.New(velocity.WithModules(&modules.BillingModule{}))` does the same
thing without the chain callback.

Ordering: module `Events` methods run first, in registration order, then the
`App.Events` callback. Under `velocity.WithoutEvents` no dispatcher is built,
so both are skipped and the app logs a warning rather than panicking on a nil
dispatcher.

`vel gen module Billing` scaffolds `internal/modules/billing.go` (package
`modules`, type `BillingModule`) with the `Init` / `Start` / `Shutdown`
skeleton; add the `Events` method yourself. `vel gen event OrderPlaced` writes
`internal/events/order_placed.go` with the `Name()` method already implemented,
and `vel gen listener ChargeCard` writes a starter file under
`internal/listeners`; fill it out with the `Handle(ctx, event) error` plus
`Async() bool` pair shown above so it satisfies `events.Listener`.


`velocity.EventModule` (`chain.EventModule`) is the bootstrap auto-wiring
interface and its method is `Events(d events.Dispatcher)`. The separate
`events.EventModule` used by `EventRegistry` below declares
`Register(dispatcher events.Dispatcher)`. They are different types with
different method names; a module can implement both.


### Standalone EventRegistry

`events.EventRegistry` is an opt-in collector for code that needs to gather
registration units before a dispatcher exists (a plugin host, a test harness,
a library that ships its own listeners). The framework does not construct one
during bootstrap, so you build and boot it yourself.

```go
// events.EventModule is the registry-side interface: Register(dispatcher).
type BillingEvents struct{}

func (BillingEvents) Register(d events.Dispatcher) {
    d.Listen("order.placed", &ChargeCard{})
}

registry := events.NewEventRegistry()
registry.AddModule(BillingEvents{})

// Later, once the dispatcher exists. BootModules calls Register on each
// module in registration order.
registry.BootModules(dispatcher)
```

The registry also keeps a name-level index of what is registered:
`Register(eventName, listenerName)` records a pair, `GetListeners(eventName)`
and `GetAllEvents()` read it back, `Count()` totals the registrations, and
`Clear()` resets both the index and the module list. `DiscoverFromType(subscriber)`
reflects over a subscriber's `Handle*` methods and records the event names they
imply (`HandleUserRegistered` maps to `user.registered`).

## Listening to Model Lifecycle Events

`Dispatcher` is not just for app-level domain events. The framework ships a parallel `ModelObserver` contract for per-record hooks (`Creating`, `Created`, `Updating`, `Updated`, `Saving`, `Saved`, `Deleting`, `Deleted`, `Restoring`, `Restored`) plus an `ObservableDispatcher` that owns an `ObserverRegistry` keyed by model type name. Every callback receives the caller-supplied `context.Context` so observers see request-scoped values (transactions, trace IDs, deadlines) without the model carrying them.

```go
import (
    "context"
    "github.com/velocitykode/velocity/events"
)

type User struct {
    ID    int
    Email string
}

// Implement only the hooks you need. BaseObserver no-ops the rest.
type UserObserver struct {
    events.BaseObserver
}

func (o *UserObserver) Created(ctx context.Context, model interface{}) error {
    u := model.(*User)
    log.InfoContext(ctx, "user created", "user_id", u.ID)
    return nil
}

func (o *UserObserver) Deleted(ctx context.Context, model interface{}) error {
    u := model.(*User)
    return cache.Forget(ctx, "user:"+strconv.Itoa(u.ID))
}
```

Wire it up against an `ObservableDispatcher`. The registry keys by the unqualified type name (`"User"`), so register either by name or by passing an instance:

```go
app.Events(func(d events.Dispatcher) {
    obs, ok := d.(*events.ObservableDispatcher)
    if !ok {
        return // dispatcher does not support model observers
    }

    // By type name
    obs.Observe("User", &UserObserver{})

    // Or by instance (type name extracted via reflection)
    obs.ObserveModel(&User{}, &UserObserver{})
})
```

Lifecycle hooks fire only when the calling code invokes
`obs.FireModelEvent(ctx, "created", &user)` (typically from a service-layer
wrapper around your repository writes). `FireModelEvent` runs the observers
and *also* dispatches a regular `*ModelEvent` under the name
`<modeltype>.<action>` (e.g. `user.created`) using the same ctx, so a
wildcard listener on `*.created` still sees it. Use
`events.NewConditionalObserver(observer, predicate)` -- where the
predicate is `func(ctx context.Context, event string, model interface{}) bool`
-- to gate hooks on runtime state, or `events.NewAutoObserver(instance)` to
map struct methods named `Creating` / `Created` / ... onto the contract via
reflection. `AutoObserver` accepts both the legacy `(model)` shape and the
preferred `(ctx, model)` shape.

`ObservableModel` implementations expose
`FireEvent(ctx context.Context, event string) error` so the model itself
can be the trigger when that fits the design better than a service-layer
call. `ObserverRegistry.Fire(ctx, event, model)` is the lower-level entry
point.

## Dispatching Events

All dispatch calls are methods on the `events.Dispatcher` resolved from
`ctx.Events()` (in handlers) or the `d` parameter of `App.Events`. Every
method takes `context.Context` as its first argument.

### Synchronous Dispatch

```go
// Dispatch and wait for all listeners to complete. Listeners that
// return Async() == true are pushed to the queue dispatcher instead,
// when one is wired; without a queue they still run inline.
err := ctx.Events().Dispatch(ctx.Request.Context(), UserRegistered{
    UserID: 123,
    Email:  "user@example.com",
})
if err != nil {
    log.ErrorContext(ctx.Request.Context(), "Event dispatch failed", "error", err)
}
```

### Force Synchronous

```go
// Always run synchronously, ignoring Async().
err := ctx.Events().DispatchNow(ctx.Request.Context(), OrderPlaced{
    OrderID: "ORD-123",
})
```

### Asynchronous Dispatch

```go
// Dispatch without waiting. Uses the configured QueueDispatcher when
// available, otherwise falls back to a panic-safe goroutine (async.Go).
// On the goroutine fallback listeners receive a ctx derived via
// context.WithoutCancel: values propagate, cancellation does not.
err := ctx.Events().DispatchAsync(ctx.Request.Context(), EmailSent{
    To:      "user@example.com",
    Subject: "Welcome",
})
```

### Delayed Dispatch

```go
// Dispatch after a delay. Uses the queue when available; otherwise
// schedules via time.AfterFunc with a context.WithoutCancel-derived ctx.
err := ctx.Events().DispatchAfter(
    ctx.Request.Context(),
    OrderFollowUp{OrderID: "ORD-123"},
    24*time.Hour,
)
```

### Dispatch Until Result

```go
// Dispatch until first non-nil result. Listeners that want to short-circuit
// must implement
//   HandleWithResult(ctx context.Context, event interface{}) (interface{}, error).
result, err := ctx.Events().Until(ctx.Request.Context(), ValidatePayment{
    Amount: 99.99,
    Method: "credit_card",
})

if result != nil {
    paymentResult := result.(*PaymentResult)
    // Use result
}
```

## Wildcard Patterns

Velocity supports flexible wildcard patterns for event matching:

### Prefix Matching

```go
app.Events(func(d events.Dispatcher) {
    // Listen to all user events
    d.Listen("user.*", &UserActivityLogger{})
})

// Matches:
// - user.registered
// - user.updated
// - user.deleted
// - user.anything
```

### Suffix Matching

```go
app.Events(func(d events.Dispatcher) {
    // Listen to all "created" events
    d.Listen("*.created", &CreatedLogger{})
})

// Matches:
// - user.created
// - order.created
// - product.created
```

### Match Everything

```go
app.Events(func(d events.Dispatcher) {
    // Listen to every event the dispatcher routes
    d.Listen("*", &GlobalLogger{})
})
```

### Multiple Patterns

```go
app.Events(func(d events.Dispatcher) {
    // Listen to multiple event names with one registration
    d.Listen([]string{
        "user.registered",
        "user.updated",
        "order.placed",
    }, &MultiEventListener{})
})
```

## Dispatcher API Cheat Sheet

Every operation is a method on the `events.Dispatcher` returned by
`ctx.Events()` (or passed into `App.Events`). `Listen` returns an `int` ID
that can be passed to `Off` to unregister later.

```go
app.Events(func(d events.Dispatcher) {
    // Register a listener (returns an int ID for later removal)
    id := d.Listen("user.registered", &MyListener{})

    // Register a subscriber (or auto/mapped/group)
    d.Subscribe(&MySubscriber{})

    // Remove a single listener by ID (returns true if it was found)
    d.Off(id)

    // Remove all listeners for an event (Flush == Forget)
    d.Flush("user.registered")
    d.Forget("user.registered")

    // Inspect listeners
    if d.HasListeners("user.registered") {
        listeners := d.GetListeners("user.registered")
        _ = listeners
    }
})

// Dispatch from anywhere that has access to the dispatcher and a ctx.
func (h *Handler) Do(ctx *router.Context) error {
    d := ctx.Events()
    rctx := ctx.Request.Context()

    _ = d.Dispatch(rctx, UserRegistered{UserID: 1})
    _ = d.DispatchNow(rctx, OrderPlaced{OrderID: "123"})
    _ = d.DispatchAsync(rctx, EmailSent{})
    _ = d.DispatchAfter(rctx, Reminder{}, 1*time.Hour)

    result, _ := d.Until(rctx, ValidateData{})
    _ = result
    return nil
}
```

## Common Use Cases

### User Registration Flow

```go
// Event
type UserRegistered struct {
    UserID    int
    Email     string
    Name      string
    IPAddress string
}

func (e UserRegistered) Name() string {
    return "user.registered"
}

// Listeners
type SendWelcomeEmail struct{}
func (l *SendWelcomeEmail) Handle(ctx context.Context, event interface{}) error {
    e := event.(UserRegistered)
    return emailService.SendWelcome(ctx, e.Email, e.Name)
}
func (l *SendWelcomeEmail) Async() bool { return true }

type CreateUserProfile struct{}
func (l *CreateUserProfile) Handle(ctx context.Context, event interface{}) error {
    e := event.(UserRegistered)
    return profileService.Create(ctx, e.UserID)
}
func (l *CreateUserProfile) Async() bool { return false }

type TrackRegistration struct{}
func (l *TrackRegistration) Handle(ctx context.Context, event interface{}) error {
    e := event.(UserRegistered)
    return analytics.Track(ctx, "user_registered", map[string]interface{}{
        "user_id": e.UserID,
        "ip":      e.IPAddress,
    })
}
func (l *TrackRegistration) Async() bool { return true }

// Setup
app.Events(func(d events.Dispatcher) {
    d.Listen("user.registered", &SendWelcomeEmail{})
    d.Listen("user.registered", &CreateUserProfile{})
    d.Listen("user.registered", &TrackRegistration{})
})

// Usage in handler
func (c *AuthHandler) Register(ctx *router.Context) error {
    user := createUser(email, password)

    if err := ctx.Events().Dispatch(ctx.Request.Context(), UserRegistered{
        UserID:    user.ID,
        Email:     user.Email,
        Name:      user.Name,
        IPAddress: ctx.Request.RemoteAddr,
    }); err != nil {
        return err
    }

    return ctx.JSON(user)
}
```

### Order Processing Pipeline

```go
type OrderPlaced struct {
    OrderID   string
    UserID    int
    Total     float64
    Items     []OrderItem
    CreatedAt time.Time
}

func (e OrderPlaced) Name() string {
    return "order.placed"
}

// Listeners for different responsibilities
app.Events(func(d events.Dispatcher) {
    d.Listen("order.placed", &ProcessPayment{})
    d.Listen("order.placed", &SendOrderConfirmation{})
    d.Listen("order.placed", &UpdateInventory{})
    d.Listen("order.placed", &NotifyWarehouse{})
    d.Listen("order.placed", &UpdateAnalytics{})
})
```

### Audit Logging

```go
type AuditLogger struct{}

func (l *AuditLogger) Handle(ctx context.Context, event interface{}) error {
    // Log all model changes
    return auditLog.Record(ctx, event)
}

func (l *AuditLogger) Async() bool {
    return true
}

// Register for all creation events
app.Events(func(d events.Dispatcher) {
    d.Listen("*.created", &AuditLogger{})
    d.Listen("*.updated", &AuditLogger{})
    d.Listen("*.deleted", &AuditLogger{})
})
```

### Cache Invalidation

```go
type CacheInvalidator struct{}

func (l *CacheInvalidator) Handle(ctx context.Context, event interface{}) error {
    switch e := event.(type) {
    case UserUpdated:
        cache.Forget(ctx, "user:"+strconv.Itoa(e.UserID))
    case ProductUpdated:
        cache.Forget(ctx, "product:"+e.ProductID)
    }
    return nil
}

func (l *CacheInvalidator) Async() bool {
    return false // Invalidate immediately
}

app.Events(func(d events.Dispatcher) {
    d.Listen("*.updated", &CacheInvalidator{})
})
```

## Middleware

`MiddlewareDispatcher` runs events through a pipeline of `EventMiddleware`
before they reach listeners. The ctx threads through every stage so
deadlines, cancellation, and trace context survive the chain.

```go
type EventMiddleware interface {
    Handle(ctx context.Context, event interface{},
        next func(context.Context, interface{}) error) error
}

// MiddlewareFunc adapts a plain func to the interface.
type MiddlewareFunc func(ctx context.Context, event interface{},
    next func(context.Context, interface{}) error) error
```

Built-in middleware (`LoggingMiddleware`, `TimingMiddleware`,
`RetryMiddleware`, `FilterMiddleware`, `ValidationMiddleware`,
`TransformMiddleware`) all use the ctx-aware shape. `RetryMiddleware`
honours `ctx.Done()` between attempts so a cancelled caller stops the
retry loop instead of sleeping out the configured delay.

## Testing

### Using Fake Dispatcher

`events.NewFakeDispatcher()` records dispatched events without invoking
listeners. Wire it into a test app via `velocity.WithFakeEvents(fake)` so
every `ctx.Events()` call inside the handler resolves to the fake.

```go
import (
    "context"

    "github.com/velocitykode/velocity"
    "github.com/velocitykode/velocity/events"
    "github.com/velocitykode/velocity/velocitytest"
)

func TestUserRegistration(t *testing.T) {
    // Create fake dispatcher and inject it into the test app
    fake := events.NewFakeDispatcher()
    app, _ := velocitytest.NewApp(velocity.WithFakeEvents(fake))

    // Perform action that dispatches events (using the test app)
    registerUser(app, "test@example.com", "password")

    // Assert event was dispatched
    if err := fake.AssertDispatched(UserRegistered{}, func(e interface{}) bool {
        event := e.(UserRegistered)
        return event.Email == "test@example.com"
    }); err != nil {
        t.Fatal(err)
    }

    // Assert specific number of times
    if err := fake.AssertDispatchedTimes(UserRegistered{}, 1); err != nil {
        t.Fatal(err)
    }

    // Assert not dispatched
    if err := fake.AssertNotDispatched(UserDeleted{}); err != nil {
        t.Fatal(err)
    }
}
```

### Testing Listeners

```go
func TestSendWelcomeEmail(t *testing.T) {
    listener := &SendWelcomeEmail{}

    event := UserRegistered{
        UserID: 1,
        Email:  "test@example.com",
        Name:   "Test User",
    }

    err := listener.Handle(context.Background(), event)
    assert.NoError(t, err)

    // Verify email was sent
    assert.True(t, emailService.WasSent("test@example.com"))
}
```

### Integration Tests

```go
func TestEventFlow(t *testing.T) {
    // Spin up a real dispatcher and register tracking listeners on it directly.
    dispatcher := events.NewDispatcher()

    var (
        called []string
        mu     sync.Mutex
    )

    trackingListener := func(name string) events.Listener {
        return &testListener{
            handle: func(ctx context.Context, e interface{}) error {
                mu.Lock()
                called = append(called, name)
                mu.Unlock()
                return nil
            },
        }
    }

    dispatcher.Listen("user.registered", trackingListener("email"))
    dispatcher.Listen("user.registered", trackingListener("profile"))
    dispatcher.Listen("user.registered", trackingListener("analytics"))

    // Dispatch event
    if err := dispatcher.Dispatch(context.Background(), UserRegistered{UserID: 1}); err != nil {
        t.Fatal(err)
    }

    // Verify all listeners were called
    assert.Equal(t, 3, len(called))
    assert.Contains(t, called, "email")
    assert.Contains(t, called, "profile")
    assert.Contains(t, called, "analytics")
}
```

## Best Practices

1. **Use Meaningful Event Names**: Follow dot notation (e.g., `user.registered`, `order.placed`)
2. **Include All Necessary Data**: Events should contain all data listeners need
3. **Keep Listeners Focused**: Each listener should have a single responsibility
4. **Use Queues for Heavy Tasks**: Queue emails, notifications, and API calls
5. **Make Listeners Idempotent**: Listeners should handle duplicate events gracefully
6. **Handle Errors Gracefully**: Don't let one listener failure affect others
7. **Document Your Events**: Clearly document what events exist and when they're fired
8. **Test Event Flows**: Use the fake dispatcher to test event dispatching
9. **Pass the right ctx**: Use the request ctx (or tx ctx) on dispatch so listeners observe deadlines and trace IDs; remember async paths strip cancellation.

## Performance Considerations

### Async vs Sync

```go
d := ctx.Events()
rctx := ctx.Request.Context()

// Synchronous: blocks until every listener completes
d.DispatchNow(rctx, event)

// Asynchronous: returns immediately (queue or async.Go fallback)
d.DispatchAsync(rctx, event)
```

**Use synchronous when:**
- Event handling must complete before continuing
- Order of execution matters
- Error handling is critical
- You need cancellation/deadline to reach listeners

**Use asynchronous when:**
- Event handling can happen in background
- Performance is critical
- Failures can be retried
- It is OK that ctx cancellation does NOT propagate to listeners

### Queue Integration

For high-volume applications, back queued listeners with a real queue. There are
two surfaces:

- `*events.DefaultDispatcher` (the default `Services.Events` value, built by
  `events.NewDispatcher()`) accepts a `QueueDispatcher` via
  `SetQueueDispatcher`. Implement the `QueueDispatcher` interface
  (`Push(ctx, event, listener, delay) error`) to route `Async()`
  listeners onto your own queue.
- `*events.QueueIntegratedDispatcher` (built by
  `events.NewQueueIntegratedDispatcher()`) wraps a `DefaultDispatcher` and
  binds directly to a `queue.Driver` via `SetQueueDriver`, plus
  `RegisterListenerFactory` so a separate worker process can rehydrate the
  listener from the persisted type. When you configure a queue connection,
  the framework wires this dispatcher to the app's queue driver at boot, so
  `Async()` listeners are pushed onto the queue with no extra code.

To wire a custom `QueueDispatcher` onto the default dispatcher manually:

```go
import (
    "context"
    "time"

    "github.com/velocitykode/velocity/events"
)

// QueueDispatcher.Push takes ctx as its first argument.
type QueueEventDispatcher struct {
    // ... your queue handle
}

func (q *QueueEventDispatcher) Push(ctx context.Context, event interface{},
    listener events.Listener, delay time.Duration) error {
    // ... push to your queue, propagating ctx through to the driver's
    // PushCtx / PushDelayedCtx methods
    return nil
}

dispatcher := events.NewDispatcher()
dispatcher.SetQueueDispatcher(&QueueEventDispatcher{})

// `dispatcher` now pushes Async() listeners through your queue instead
// of running them inline. Inject it as the app's events service at boot.
```

### Batching Events

```go
// Collect events and dispatch in batches
type EventBatcher struct {
    dispatcher events.Dispatcher
    pending    []interface{}
    mu         sync.Mutex
}

func (b *EventBatcher) Add(event interface{}) {
    b.mu.Lock()
    b.pending = append(b.pending, event)
    b.mu.Unlock()
}

func (b *EventBatcher) Flush(ctx context.Context) error {
    b.mu.Lock()
    defer b.mu.Unlock()

    for _, event := range b.pending {
        if err := b.dispatcher.Dispatch(ctx, event); err != nil {
            return err
        }
    }

    b.pending = nil
    return nil
}
```

The framework also ships purpose-built wrappers for this space:
`events.NewBatchingDispatcher`, `events.NewDebouncingDispatcher`,
`events.NewThrottlingDispatcher`, and `events.NewCoalescingDispatcher`
implement the same patterns without hand-rolled bookkeeping. Each `Dispatch`
captures the caller's ctx via `context.WithoutCancel` because the actual
fan-out happens on a background goroutine after the batching/debounce/coalesce
window elapses.

## Troubleshooting

### Events Not Firing

**Check:**
1. Listeners are registered before events are dispatched
2. Event names match exactly (case-sensitive)
3. Global dispatcher is initialized
4. No errors in listener registration

### Listeners Not Called

**Check:**
1. Wildcard patterns are correct
2. `ShouldHandle()` method isn't preventing execution
3. Event is being dispatched on the correct dispatcher instance
4. Listener implements the `Listener` interface correctly: `Handle(ctx, event) error` plus `Async() bool` (legacy `Handle(event)` and `ShouldQueue()` no longer satisfy the interface)

### Performance Issues

**Solutions:**
1. Use `DispatchAsync()` for non-critical events
2. Implement queue-based event handling
3. Batch events when possible
4. Profile listener execution times
5. Remove unnecessary listeners

### Listener Cancelled Mid-Dispatch (sync only)

`Dispatch` / `DispatchNow` / `Until` propagate the caller's cancellation.
A listener observing `ctx.Done()` will return early when the request ctx
is cancelled. If you don't want that, dispatch on a derived ctx:

```go
detached := context.WithoutCancel(ctx.Request.Context())
ctx.Events().Dispatch(detached, evt)
```

## Recipe: Audit every domain event with one listener

**When:** You want a single auditor to capture every event the app dispatches (`*.created`, `*.updated`, payment events, login events, anything) without enumerating them or coupling auditing to each producer.

**Code:**
```go
type AuditAll struct{ writer audit.Writer }

func (l *AuditAll) Handle(ctx context.Context, event interface{}) error {
    name, _ := event.(events.Event)
    return l.writer.Record(ctx, audit.Entry{
        Name:    name.Name(),
        Payload: event,
        At:      time.Now(),
    })
}

func (l *AuditAll) Async() bool { return true }

app.Events(func(d events.Dispatcher) {
    d.Listen("*", &AuditAll{writer: auditWriter})
})
```

**Why this shape:** The `*` pattern in `Dispatcher.Listen` matches every event the dispatcher routes, including model lifecycle events emitted via `FireModelEvent` and framework events like `query.executed` or `http.request.failed`. One listener instance is cheaper than per-event registrations and impossible to forget when a new event type is introduced. `Async() == true` keeps audit writes off the request path so a slow audit sink cannot stall handlers; the dispatcher transparently pushes the work through whatever `QueueDispatcher` is wired (memory, Redis, etc.). Make the writer idempotent on `(name, payload-hash)` so retries do not double-record.

**See also:**
- [Wildcard Patterns](#wildcard-patterns) for prefix/suffix variants when you want to scope the auditor
- [Listening to Model Lifecycle Events](#listening-to-model-lifecycle-events) for the per-record hook contract that `*.created` rides on
- [Notifications](/docs/advanced/notifications/) for fan-out patterns that pair well with auditing

## Related

- [Modules](/docs/advanced/modules/) for the full module lifecycle that `velocity.EventModule` plugs into
- [Notifications](/docs/advanced/notifications/) for turning an event into a multi-channel user notification
- [Cache](/docs/core/cache/) for invalidating cache entries from `*.updated` / `*.deleted` listeners
- [Queue](/docs/advanced/queue/) for backing queued listeners with a durable driver and picking the right primitive for long-running work


================================================================================
# Tracing

Source: https://vel.build/docs/advanced/trace/
Section: Advanced Topics
Summary: Distributed tracing primitives - trace IDs, span IDs, and parent relationships propagated through context.


The `trace` package is Velocity's distributed tracing primitive. It
generates trace and span IDs, stores them on `context.Context`, and
exposes helpers to create child spans. Events from the `httpclient`,
`bus`, and queue packages pull trace information from context via this
package.

Import path: `github.com/velocitykode/velocity/trace`

## Concepts

- **Trace ID** - identifies a distributed trace end-to-end. 32 hex
  characters. One per top-level request.
- **Span ID** - identifies a single operation within a trace. 16 hex
  characters. Multiple per trace.
- **Parent ID** - the span ID of the caller. Links child operations to
  their parent.

IDs are stored as `context.Context` values; helpers handle read/write
so callers never touch the keys directly.

## Starting a trace

At the top of a request (usually via middleware), start a fresh trace:

```go
ctx, traceID, spanID := trace.StartTrace(r.Context())
r = r.WithContext(ctx)
```

`StartTrace` generates both IDs, stores them on the context, and
returns them for logging.

### Continuing from an upstream trace

If the incoming request already carries a trace (e.g. from a
`traceparent` header), propagate it:

```go
if upstreamTrace, upstreamSpan := parseTraceHeader(r); upstreamTrace != "" {
    ctx = trace.WithTrace(r.Context(), upstreamTrace, upstreamSpan)
    ctx, _ = trace.ContinueTrace(ctx)  // start a new span under the upstream trace
} else {
    ctx, _, _ = trace.StartTrace(r.Context())
}
```

### Restoring all three fields

`WithTrace` sets only `traceID` and `spanID`; the parent slot stays as whatever
the inner ctx already carries. When all three fields were captured at the producer
side (queue payload, redis stream, gRPC frame) and need to be replayed verbatim,
use `WithFullContext`:

```go
ctx = trace.WithFullContext(ctx, payload.TraceID, payload.SpanID, payload.ParentID)
```

The queue worker and the ORM transaction manager already call this internally
when a payload carries the three fields. Reach for it manually only when writing
a new transport that persists trace state across a process boundary.

## Child spans

Any time you want to measure a sub-operation, create a child span.
The current span becomes the parent; the trace ID is preserved.

```go
ctx, spanID := trace.WithNewSpan(ctx)
defer recordDuration(spanID, time.Now())

// do work
```

`WithNewSpan` generates a new span ID and updates the context in one
call. Use `WithSpan(ctx, explicitID)` if you want to supply the ID
yourself (common when proxying from another tracing library).

## Reading trace state

```go
traceID := trace.GetTraceID(ctx)
spanID  := trace.GetSpanID(ctx)
parent  := trace.GetParentID(ctx)

// or all three:
traceID, spanID, parent := trace.GetTraceContext(ctx)
```

All getters return empty strings when the value is missing - safe to
call on any context.

## Generating IDs manually

```go
tid, err := trace.GenerateTraceID()  // 32 hex chars
if err != nil {
    // crypto/rand unavailable
}
sid, err := trace.GenerateSpanID()   // 16 hex chars
```

Backed by `crypto/rand`. `GenerateTraceID`/`GenerateSpanID` return an
error when the system entropy source is unavailable - they never
silently substitute zero bytes, which would collapse every concurrent
trace onto the same ID and break correlation.

### Infallible generation for hot paths

Request-path code (HTTP middleware, gRPC interceptors) often cannot
fail a request just because entropy is momentarily unavailable. Use the
`Must*` variants, which retry once and then fall back to a
distinguishable non-hex marker:

```go
tid := trace.MustGenerateTraceID()  // never errors
sid := trace.MustGenerateSpanID()
```

On an entropy outage these return per-call fallback IDs of the form
`velocity_trace_norand_<processStartNs>_<counter>` (and
`velocity_span_norand_...` for spans), exposed as the constants
`trace.FallbackTraceIDPrefix` and `trace.FallbackSpanIDPrefix`. The
markers are:

- non-hex, so APM tooling matching `^[0-9a-f]{32}$` filters them out
  and never conflates them with real trace IDs,
- unique per call (monotonic atomic counter) so concurrent in-flight
  traces stay correlated even during the outage,
- unique across restarts (the process-start nanosecond timestamp
  varies).

A single WARN log line is emitted (once per process) when the fallback
path first triggers. `StartTrace`, `ContinueTrace`, and `WithNewSpan`
all use the `Must*` helpers internally, so request-path callers degrade
gracefully rather than failing.

## Where trace values surface

- **APM events** - `httpclient.RequestSent`, `httpclient.RequestFailed`,
  router events (`RequestStarted`, `RequestHandled`, `RequestFailed`),
  ORM events (`QueryExecuted`, `TransactionExecuted`, `QueryFailed`),
  grpcevents, and queue events all carry `TraceID`, `SpanID`,
  and `ParentID` fields - the standard 3-field convention. Bus command
  events (`CommandDispatching`, `CommandCompleted`, `CommandFailed`,
  `CommandQueued`) instead embed the request `Context`, from which
  trace values are read. `trace.GetTraceContext(ctx)` is the read path.
- **Logs** - attach the trace fields to every log line to correlate
  request activity across systems.
- **Outbound requests** - inject the trace IDs into upstream headers
  (`traceparent`, or your own scheme) when calling other services.


================================================================================
# Modules

Source: https://vel.build/docs/advanced/modules/
Section: Advanced Topics
Summary: Modular registration of services, routes, middleware, events, and scheduled jobs with lifecycle hooks.


Modules are the modular extension point for Velocity applications. A
module bundles registration for services, routes, middleware, event
listeners, and scheduled jobs behind a single type; you install it with
one line of wiring.

Import paths: `github.com/velocitykode/velocity` (the `velocity.*`
aliases used by application code) and `github.com/velocitykode/velocity/app`
(the underlying `Module` interface and `Services` container). The
optional auto-wiring interfaces and the `ModuleRegistry` live in
`github.com/velocitykode/velocity/chain`, re-exported under the root
`velocity` package for ergonomics. Application code should import
`velocity` rather than `chain`; the two names resolve to the same Go
type, and a direct `chain` import is only for framework internals or a
third-party module that needs to reference the types outside the
`velocity` package.

## The core interface

```go
type Module interface {
    Init(s *Services) error              // bind services; called before any Start
    Start(s *Services) error             // wire cross-module dependencies
    Shutdown(ctx context.Context) error  // teardown; called in reverse order
}
```

Every module implements these three methods. `Init` runs for **all**
modules first; `Start` runs after, so a module can safely reference
services another module registered.

`velocity.Module` is a type alias for `app.Module`, so the two names
resolve to the same Go type. Generated scaffolding writes
`*velocity.Services`; a standalone package can write `*app.Services`
instead and stay compatible.

## The Services container

Modules read and mutate `*velocity.Services` (alias for
`app.Services`). It holds every core service instance, typed as
`contract` interfaces so the leaf `app` package avoids import cycles:

```go
type Services struct {
    Log        contract.Logger
    Exceptions contract.ExceptionHandler
    Crypto     contract.Encryptor
    DB         contract.Database
    Auth       contract.AuthManager
    CSRF       contract.CSRFProtector
    View       contract.ViewEngine

    Cache        contract.CacheManager
    Events       contract.Dispatcher
    Queue        contract.QueueDriver
    Storage      contract.StorageManager
    Scheduler    scheduler.TaskScheduler
    Mail         contract.Mailer
    Notification contract.Notifier
    Validator    contract.Validator

    // ... plus framework-owned fields (RedirectAllowlist,
    // InsecureFlashCookies, the component registry) not meant for
    // direct module use.
}
```

To attach your own services, use the **type-keyed component registry**
rather than mutating core fields. Register a value with `app.Register`
and retrieve it later (typically from a `From(s)` accessor) with
`app.Get`:

```go
// during Init/Start
if err := app.Register(s, m.client); err != nil {
    return err
}

// elsewhere - exact-type lookup, no string keys
client, err := app.Get[*billing.Client](s)
```

Lookup is by **exact type**: `app.Get[T]` only finds an entry registered
under that same `T`, never a value that merely satisfies it. Because a
Go type's identity includes its import path, two modules can never
collide. For multiple instances of the same type, use
`app.RegisterFor[T, Q]` / `app.GetFor[T, Q]` with an integrator-owned
marker type `Q` instead of a string key. `app.Register` returns an error
for a nil value or a duplicate key, so a module that ran twice is caught
at boot.


The registry owns teardown of registered values. A module that
registers a value into the registry MUST NOT also close that value in
its own `Shutdown` - the registry sweep during `App.Shutdown` runs
immediately after module `Shutdown` and closes anything implementing
`contract.ShutdownAware` exactly once. Closing it in both places is a
double-close.


## A minimal module

```go
package billing

import (
    "context"
    "os"

    "github.com/velocitykode/velocity/app"
)

type Module struct {
    client *Client
}

func (m *Module) Init(s *app.Services) error {
    m.client = NewClient(os.Getenv("STRIPE_KEY"))
    return app.Register(s, m.client)
}

func (m *Module) Start(s *app.Services) error {
    // every module has finished Init by now - wire cross-module hookups
    return nil
}

func (m *Module) Shutdown(ctx context.Context) error {
    // Nothing to close here: m.client went into the component registry,
    // and the registry sweep closes it (it implements
    // contract.ShutdownAware) right after this method returns.
    return nil
}
```

A module that owns a resource it did **not** hand to the registry closes
it in `Shutdown` as usual; the ownership rule only covers registered
values.

## Scaffolding a module

`vel gen module` writes the skeleton for you:

```bash
vel gen module Billing
```

That creates `internal/modules/billing.go` in `package modules`:

```go
package modules

import (
    "context"

    "github.com/velocitykode/velocity"
)

// BillingModule initializes and starts the Billing service.
type BillingModule struct{}

// Init binds services into the container.
func (m *BillingModule) Init(s *velocity.Services) error {
    return nil
}

// Start is called after all modules have been initialized.
func (m *BillingModule) Start(s *velocity.Services) error {
    return nil
}

// Shutdown gracefully tears down module resources.
func (m *BillingModule) Shutdown(ctx context.Context) error {
    return nil
}
```

The generator appends the `Module` suffix itself and strips a redundant
one from your argument, so `vel gen module Billing` and
`vel gen module BillingModule` both produce `BillingModule` in
`billing.go`. Pass `--dir` to write somewhere other than
`internal/modules`.

Other generators follow the same convention: `vel gen grpc service`
scaffolds `internal/modules/grpc_module.go` holding a `GRPCModule`
(skip it with `--no-module`). See [gRPC]().

## Installing modules

Register them via `v.Modules(...)`:

```go
v.Modules(func(r *velocity.ModuleRegistry) {
    r.Add(
        &modules.BillingModule{},
        &modules.AnalyticsModule{},
    )
})
```

`Add` accepts any number of `velocity.Module` implementations and keeps
registration order. `v.Modules(fn)` stores a single callback, so calling
it twice replaces the first callback rather than appending to it; add
every module inside one callback.

Alternatively, pass them at construction time with `WithModules`:

```go
v, err := velocity.New(velocity.WithModules(
    &modules.BillingModule{},
    &modules.AnalyticsModule{},
))
```


The two entry points are not interchangeable. `WithModules` modules run
`Init`/`Start` inside `velocity.New`, before the bootstrap chain exists,
and the optional auto-wiring interfaces below are **not** dispatched to
them. Only modules added through `v.Modules(...)` get their `Routes`,
`Middleware`, `Events`, `Schedule`, and `Commands` methods called. Use
`WithModules` for infrastructure that must exist before bootstrap (and
in tests); use `v.Modules(...)` for anything that contributes routes,
middleware, listeners, jobs, or commands.


## Optional auto-wiring interfaces

A module registered through `v.Modules(...)` can opt into additional
bootstrap hooks by implementing any of these. Implementation is
structural, so no explicit declaration is needed:

| Interface            | Method signature                          | When it runs                          |
| -------------------- | ----------------------------------------- | ------------------------------------- |
| `RouteModule`        | `Routes(r *velocity.Routing)`             | During route registration             |
| `MiddlewareModule`   | `Middleware(m *velocity.MiddlewareStack)` | During middleware registration        |
| `EventModule`        | `Events(d events.Dispatcher)`             | During event listener registration    |
| `ScheduleModule`     | `Schedule(s scheduler.TaskScheduler)`     | During scheduled job registration     |
| `CommandModule`      | `Commands(r *velocity.Commands)`          | During custom CLI command registration |

Example - a module that adds its own routes and middleware:

```go
var _ velocity.RouteModule = (*BillingModule)(nil)

func (m *BillingModule) Routes(r *velocity.Routing) {
    r.API("/billing", func(api router.Router) {
        api.Post("/webhooks/stripe", m.handleWebhook)
    })
}

func (m *BillingModule) Middleware(mw *velocity.MiddlewareStack) {
    mw.API(billing.SignedWebhookMiddleware)
}
```

`Routes`, `Middleware`, `Events`, `Schedule`, and `Commands` run
alongside the equivalent chain callbacks (`v.Routes(...)`,
`v.Middleware(...)`, etc.), and always before them - your module
contributes to the same stacks.

Under `velocity.WithoutEvents()` there is no dispatcher, so the
`Events` hooks are skipped entirely and the framework logs a warning if
any module implements `EventModule`.

## Lifecycle order

`velocity.New(...)` runs first:

1. **Init** - every `WithModules` module's `Init`
2. **Start** - every `WithModules` module's `Start`

Then `v.Run()`, `v.Serve()`, or an explicit `v.Bootstrap()` runs the
declarative chain:

1. **Modules** - the `v.Modules(...)` callback fills a
   `velocity.ModuleRegistry`; every collected module's `Init` runs, then
   every module's `Start`
2. **Middleware** - module `Middleware` callbacks, then `v.Middleware(...)`
3. **Routes** - module `Routes` callbacks, then `v.Routes(...)`
4. **Events** - module `Events` callbacks, then `v.Events(...)`
5. **Schedule** - module `Schedule` callbacks, then `v.Schedule(...)`
6. **Commands** - module `Commands` callbacks, then `v.Commands(...)`
7. **Exceptions** - `v.Exceptions(...)`
8. Serve / run

`Bootstrap()` is safe to call more than once, but only the first call
does the work: the result is sticky, so a later call returns the same
error rather than registering modules and routes twice.

### When a module fails

If `Init` returns an error, the framework unwinds: every module whose
`Init` already completed is shut down in reverse order, and the error is
returned wrapped. The failing module is excluded from that unwind, so a
failing `Init` must release anything it opened before returning.

The wrapped messages read `velocity: chain module init failed: ...` and
`velocity: chain module start failed: ...` for modules added via
`v.Modules(...)`, and `velocity: module init failed: ...` /
`velocity: module start failed: ...` for `WithModules` modules.

## Shutdown order

`App.Shutdown(ctx)` tears down in reverse initialization order. For
modules that means:

1. Chain modules (`v.Modules(...)`) in reverse registration order
2. `WithModules` modules in reverse registration order
3. The component registry sweep - every registered value implementing
   `contract.ShutdownAware`, also in reverse registration order

Modules unwind before the queue, cache, and database close, so a module
can still flush through core services during its own teardown; the
registry sweep runs after module `Shutdown` so a module can flush using
a value it registered, and before the core services close so a
registered component can still reach them.

## Event discovery modules

The `events` package has its own, separate `EventModule` interface used
by the discovery registry:

```go
// events.EventModule
type EventModule interface {
    Register(dispatcher Dispatcher)
}
```

Register one with `EventRegistry.AddModule(module)` and fire them all
with `EventRegistry.BootModules(dispatcher)`. Note the method is
`Register(dispatcher)`, not `Events(d)` - `events.EventModule` and
`velocity.EventModule` are different interfaces serving different
registries. See [Events]().

## When to write a module

Write a module when:

- You're shipping reusable functionality as a package (internal or
  public).
- A set of routes + middleware + events always travel together.
- You need to expose a service to handlers without hardcoding it in
  your app wiring.

For application-specific wiring, stick with the chain callbacks
(`v.Middleware`, `v.Routes`, etc.) - modules are for extraction and
reuse.


================================================================================
# gRPC

Source: https://vel.build/docs/advanced/grpc/
Section: Advanced Topics
Summary: gRPC server and HTTP gateway with context helpers, structured errors, and interceptor-friendly APIs.


The `grpc` package wraps `google.golang.org/grpc` with Velocity
conventions - context helpers for auth/request metadata, structured
error constructors, and a sibling HTTP gateway that exposes gRPC
services over REST via grpc-gateway.

Import path: `github.com/velocitykode/velocity/grpc`

Sub-packages:

- `grpc/interceptors` - bundled `Auth`, `Logging`, `Recovery` interceptor pairs
- `grpc/grpcevents` - request / stream / server / gateway / panic / auth event types
- `grpc/converters` - proto `Timestamp` / `Duration` and pagination helpers

## Setup

A typical layout: `.proto` files under `api/proto/<pkg>/<version>/`,
generated stubs under `api/gen/go/...`, service implementations under
`internal/grpc/services/`, server lifecycle in a module under
`internal/modules/`.


The console ships three generators that produce the layout below in one
call - proto + impl + module wiring, then `buf generate`:

```bash
vel gen grpc service Foo                   # proto + impl + module (idempotent)
vel gen grpc rpc Foo Hello                 # unary
vel gen grpc rpc Foo Tail   --stream       # server-stream
vel gen grpc rpc Foo Upload --client-stream
vel gen grpc rpc Foo Chat   --bidi
vel gen grpc gen                           # cd api/proto && buf generate
```

The first `gen grpc service` call also writes `api/proto/buf.yaml` and
`api/proto/buf.gen.yaml` when they are missing, and creates
`internal/modules/grpc_module.go`. Subsequent calls inject at the
`// vel:grpc:imports` and `// vel:grpc:services` markers in that module;
`--no-module` skips the module scaffold and wiring entirely. See
[CLI commands - vel gen grpc service](/docs/cli/commands/#vel-gen-grpc-service)
for the full reference. The rest of this page documents the runtime API that
the generated files use.


### Proto + buf

`api/proto/foo/v1/foo.proto`:

```proto
syntax = "proto3";

package foo.v1;

option go_package = "yourapp/api/gen/go/foo/v1;foov1";

service FooService {
  rpc Hello(HelloRequest) returns (HelloResponse);
}

message HelloRequest  { string name = 1; }
message HelloResponse { string greeting = 1; }
```

`api/proto/buf.yaml`:

```yaml
version: v2
modules:
  - path: .
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE
```

`api/proto/buf.gen.yaml`:

```yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go
    out: ../gen/go
    opt: paths=source_relative
  - remote: buf.build/grpc/go
    out: ../gen/go
    opt:
      - paths=source_relative
      - require_unimplemented_servers=false
```

Both files are written by the first `vel gen grpc service` call and left
untouched afterwards. Generate stubs:

```bash
vel gen grpc gen      # runs `buf generate` inside api/proto
```

### Service implementation

`internal/grpc/services/foo.go`:

```go
package services

import (
    "context"

    foopb "yourapp/api/gen/go/foo/v1"
)

type FooService struct {
    foopb.UnimplementedFooServiceServer
}

func NewFooService() *FooService { return &FooService{} }

func (s *FooService) Hello(ctx context.Context, req *foopb.HelloRequest) (*foopb.HelloResponse, error) {
    name := req.GetName()
    if name == "" {
        name = "world"
    }
    return &foopb.HelloResponse{Greeting: "hi " + name}, nil
}
```

### Module

`internal/modules/grpc_module.go`, as the generator writes it:

```go
package modules

import (
    "context"
    "os"

    // vel:grpc:imports
    foopb "yourapp/api/gen/go/foo/v1"
    "yourapp/internal/grpc/services"

    "github.com/velocitykode/velocity"
    velgrpc "github.com/velocitykode/velocity/grpc"
    googleGrpc "google.golang.org/grpc"
)

type GRPCModule struct {
    server *velgrpc.Server
}

func (p *GRPCModule) Init(s *velocity.Services) error {
    port := os.Getenv("GRPC_PORT")
    if port == "" {
        port = "50051"
    }

    p.server = velgrpc.NewServer(
        velgrpc.WithPort(port),
        velgrpc.WithLogger(s.Log),
    )
    // In production, attach transport credentials with WithCreds (see TLS
    // below) or set GRPC_INSECURE=true; otherwise Build returns an error.

    // vel:grpc:services
    foo := services.NewFooService()
    p.server.RegisterService(func(srv interface{}) {
        foopb.RegisterFooServiceServer(srv.(*googleGrpc.Server), foo)
    })

    return nil
}

func (p *GRPCModule) Start(s *velocity.Services) error {
    if err := p.server.Build(); err != nil {
        return err
    }
    return p.server.StartAsync()
}

func (p *GRPCModule) Shutdown(ctx context.Context) error {
    return p.server.Shutdown(ctx)
}
```

The two marker comments are load-bearing: every later
`vel gen grpc service` call injects the new proto import after
`// vel:grpc:imports` and the new `RegisterService` block after
`// vel:grpc:services`. Delete them and the generator prints a manual wire
snippet instead of touching the file.

Register the module alongside the rest of the app's modules:

```go
v.Modules(func(r *velocity.ModuleRegistry) {
    r.Add(&modules.GRPCModule{})
})
```

`velocity.New(velocity.WithModules(&modules.GRPCModule{}))` works too; the
gRPC module contributes no routes, listeners, or jobs, so it does not need
the bootstrap-chain auto-wiring interfaces. See
[Modules]() for the difference between the two entry
points.

`Init` binds the server and its service implementations; `Start` runs after
every module has initialised. `Build` applies interceptors and registered
services to the underlying `*google.golang.org/grpc.Server`; `StartAsync`
launches the listener in a background goroutine so the rest of the app boot
continues. `Shutdown` runs in reverse registration order and drains in-flight
RPCs with the supplied ctx deadline.

## Server

```go
srv := grpc.NewServer(
    grpc.WithPort("50051"),
    grpc.WithEnvironment("production"),   // production guards: TLS required, reflection refused
    grpc.WithReflection(true),            // enable reflection in dev (Build errors in production)
    grpc.WithMaxRecvMsgSize(4<<20),
    grpc.WithMaxSendMsgSize(4<<20),
    grpc.WithCreds(creds),                // transport credentials (see TLS below)
    grpc.WithLogger(v.Log),
)
```

`NewServer` seeds its defaults from the environment via `LoadConfig` -
`GRPC_PORT`, `GRPC_REFLECTION`, `GRPC_MAX_RECV_SIZE`, `GRPC_MAX_SEND_SIZE`
- and the explicit options above override them. `WithMaxRecvMsgSize` /
`WithMaxSendMsgSize` clamp their argument: a non-positive size (which
grpc-go reads as unlimited) falls back to the 4&nbsp;MB default, and an
oversize value is clamped to a 1&nbsp;GiB ceiling.

### TLS

Build enforces a production TLS guard. When the environment is
`production` (`APP_ENV=production` or `WithEnvironment("production")`) and
no transport credentials were attached, `Build` returns an error:

```go
srv := grpc.NewServer(
    grpc.WithEnvironment("production"),
    grpc.WithCreds(creds),  // credentials.TransportCredentials
)
```

- `WithCreds(creds)` attaches credentials (from `credentials.NewTLS`,
  `credentials.NewServerTLSFromFile`, ...) and marks the server as
  TLS-configured in one step.
- `WithServerOption(grpc.Creds(...))` routes credentials through the raw
  option hook, but the guard cannot inspect it - pair it with
  `WithExplicitTLS()` so the guard recognises the opt-in.
- Setting `GRPC_INSECURE=true` opts a deployment out of the guard for a
  known-internal mTLS mesh or sidecar-terminated mesh.

Outside production, a missing credentials configuration only logs a
one-shot warning.

### Default recovery

`Build` installs a panic-recovery interceptor outermost by default
(grpc-go does not auto-recover interceptor or handler panics, so without
it the first panic crashes the serve loop). Pass `WithoutDefaultRecovery()`
only when you wire your own outermost recovery interceptor first in the
chain.

### Interceptors

Unary and stream interceptors follow standard gRPC signatures:

```go
srv.Use(
    authInterceptor,
    loggingInterceptor,
    recoveryInterceptor,
)

srv.UseStream(streamAuthInterceptor)
```

Mixed pairs:

```go
srv.UseAll(
    grpc.InterceptorPair{Unary: authUnary, Stream: authStream},
)
```

### Bundled interceptors

`grpc/interceptors` ships paired (unary + stream) implementations for the
common middleware spine. Each returns an `InterceptorPair`, so `UseAll` wires
both sides:

```go
import (
    "github.com/velocitykode/velocity/grpc/interceptors"
    "github.com/velocitykode/velocity/grpc/grpcevents"
)

srv.UseAll(
    interceptors.Recovery(
        interceptors.WithRecoveryLogger(s.Log),
        interceptors.WithStackTrace(true),
        interceptors.WithRecoveryEventDispatcher(eventDispatcher),
    ),
    interceptors.Logging(
        interceptors.WithLoggingLogger(s.Log),
        interceptors.WithSlowThreshold(500*time.Millisecond),
        interceptors.WithSkipHealthChecks(true),
        interceptors.WithEventDispatcher(eventDispatcher),
    ),
    interceptors.Auth(validator,
        interceptors.WithPublicMethods("/foo.v1.FooService/Hello"),
        interceptors.WithAuthEventDispatcher(eventDispatcher),
    ),
)
```

`validator` implements `interceptors.AuthValidator`: given a token, return
the resolved `Claims` or an error. `WithPublicMethods` bypasses auth on
listed full-method paths. `WithTokenExtractor` overrides the default
`authorization: Bearer ...` parser.

Each constructor accepts `WithEventDispatcher` (and variants) to wire the
matching `grpcevents` event onto a domain bus. The dispatchers also start
or continue a trace span on entry, so `RequestStarted` /
`RequestCompleted` / `RequestFailed` ship `TraceID` / `SpanID` /
`ParentID` (the standard 3-field convention).

### Registering services

```go
srv.RegisterService(func(s any) {
    pb.RegisterUsersServer(s.(*googleGrpc.Server), usersImpl)
})
```

The closure receives the underlying `*grpc.Server` - use it to call
generated `Register*` functions.

### Running

```go
if err := srv.Build(); err != nil {
    return err
}

if err := srv.Start(); err != nil {  // blocks
    return err
}
```

Non-blocking:

```go
if err := srv.StartAsync(); err != nil {
    return err
}

// later
srv.GracefulStop()
```

`Shutdown(ctx)` waits for in-flight RPCs with a deadline; `Stop` is
immediate.

## RPC types

gRPC has four method shapes. The framework treats all of them uniformly:
register the service with `srv.RegisterService`, the bundled interceptors
trace both unary and stream RPCs via paired `Unary` + `Stream`
implementations.

**Three things change per shape, one thing stays the same:**

| Concern | Unary | Server stream | Client stream | Bidi stream |
|---|---|---|---|---|
| Proto `stream` keyword | none | on response | on request | on both |
| Generated handler signature | `(ctx, *Req) (*Resp, error)` | `(*Req, Stream) error` | `(Stream) error` | `(Stream) error` |
| Where ctx comes from | parameter | `stream.Context()` | `stream.Context()` | `stream.Context()` |
| How responses flow | `return resp, nil` | `stream.Send(resp)` N times | `stream.SendAndClose(resp)` | `stream.Send(resp)` N times |
| How requests arrive | parameter | parameter | `stream.Recv()` until EOF | `stream.Recv()` until EOF |
| `srv.RegisterService` wiring | identical | identical | identical | identical |

Same proto file declares all four with the `stream` keyword in the right
position:

```proto
service FooService {
  rpc Hello(HelloRequest)        returns (HelloResponse);          // unary
  rpc Tail(HelloRequest)         returns (stream HelloResponse);   // server stream
  rpc Upload(stream HelloRequest) returns (HelloResponse);         // client stream
  rpc Chat(stream HelloRequest)  returns (stream HelloResponse);   // bidi
}
```

`buf generate` produces matching server-side handler signatures; the
service impl below has one method per RPC, each with the signature shape
its row prescribes. Registration is unchanged:

```go
foopb.RegisterFooServiceServer(srv, fooImpl) // same call regardless of mix
```

### Unary

One request, one response. Standard request/response RPC.

**Use cases:**

- CRUD endpoints (`GetUser`, `CreateOrder`, `UpdateProfile`)
- Auth handshake (`Login`, `RefreshToken`)
- Internal service-to-service calls (`ChargeCard`, `SendReceipt`)
- Synchronous validation / pricing / risk-score lookups
- Anything that fits a REST `GET` / `POST` mental model

```proto
service ChatService {
  rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
}
```

```go
func (s *ChatService) SendMessage(ctx context.Context, req *pb.SendMessageRequest) (*pb.SendMessageResponse, error) {
    msg, err := s.messages.Create(ctx, req.GetBody())
    if err != nil {
        return nil, velgrpc.WrapError(err)
    }
    return &pb.SendMessageResponse{Id: msg.ID}, nil
}
```

### Server streaming

One request, many responses.

**Use cases:**

- Log / metric tailing (`TailLogs(filter)` streams new lines as they arrive)
- Server-pushed notifications (`Subscribe(topic)` for chat, alerts, presence)
- Large result sets streamed in chunks (`Export(query)` without materialising
  the full set in memory)
- Progress updates for long-running jobs (`RunBuild(jobID)` emits stage events)
- Server-Sent-Events replacement on the gRPC wire

```proto
service ChatService {
  rpc Subscribe(SubscribeRequest) returns (stream Message);
}
```

```go
func (s *ChatService) Subscribe(req *pb.SubscribeRequest, stream pb.ChatService_SubscribeServer) error {
    ctx := stream.Context()
    sub, err := s.pubsub.Subscribe(ctx, req.GetTopic())
    if err != nil {
        return velgrpc.WrapError(err)
    }
    defer sub.Close()

    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        case msg, ok := <-sub.Ch():
            if !ok {
                return nil
            }
            if err := stream.Send(&pb.Message{Body: msg.Body}); err != nil {
                return err
            }
        }
    }
}
```

Honor `stream.Context().Done()`: the client may cancel mid-stream, and
the framework's recovery interceptor will not save a handler that
ignores cancellation.

### Client streaming

Many requests, one response.

**Use cases:**

- Bulk ingestion (`UploadEvents`, `UploadMetrics`, `UploadRows`)
- File upload chunked over the wire (`PutObject` streams blob chunks,
  returns a single ack with the resolved object id)
- Telemetry batching from edge agents into a central collector
- Aggregation / reduce APIs (`ComputeStats` consumes many samples,
  returns one summary)
- Anything the client can produce incrementally but the server only needs
  to acknowledge once at the end

```proto
service IngestService {
  rpc UploadEvents(stream Event) returns (UploadEventsResponse);
}
```

```go
func (s *IngestService) UploadEvents(stream pb.IngestService_UploadEventsServer) error {
    var count int64
    for {
        evt, err := stream.Recv()
        if err == io.EOF {
            return stream.SendAndClose(&pb.UploadEventsResponse{Accepted: count})
        }
        if err != nil {
            return err
        }
        if err := s.store.Append(stream.Context(), evt); err != nil {
            return velgrpc.WrapError(err)
        }
        count++
    }
}
```

`stream.SendAndClose` ends the RPC on the success path. Returning an
error short-circuits the stream with that status.

### Bidirectional streaming

Many requests, many responses, fully interleaved.

**Use cases:**

- Chat / DMs / presence (`Connect()` carries inbound messages and
  outbound deliveries on one long-lived stream)
- Interactive shells / remote exec (`Exec()` ships stdin chunks, returns
  stdout/stderr chunks)
- Live collaboration (CRDT / OT sync, multi-cursor editors)
- Pub/sub bridges where the client both publishes and subscribes on the
  same connection
- Real-time game / robotics control loops (client sends inputs, server
  sends state updates at its own cadence)

```proto
service ChatService {
  rpc Connect(stream ClientFrame) returns (stream ServerFrame);
}
```

```go
func (s *ChatService) Connect(stream pb.ChatService_ConnectServer) error {
    ctx := stream.Context()

    // Outbound pump: server -> client
    outbound := make(chan *pb.ServerFrame, 16)
    go func() {
        defer close(outbound)
        s.fanIn(ctx, outbound) // implementation-specific
    }()

    // Inbound pump runs on the request goroutine; send loop pulls from `outbound`.
    inboundErr := make(chan error, 1)
    go func() {
        for {
            frame, err := stream.Recv()
            if err != nil {
                inboundErr <- err
                return
            }
            if err := s.handle(ctx, frame); err != nil {
                inboundErr <- err
                return
            }
        }
    }()

    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        case err := <-inboundErr:
            if err == io.EOF {
                return nil
            }
            return err
        case frame, ok := <-outbound:
            if !ok {
                return nil
            }
            if err := stream.Send(frame); err != nil {
                return err
            }
        }
    }
}
```

`stream.Recv()` and `stream.Send()` are independently safe to call from
different goroutines, but `Recv` from two goroutines or `Send` from two
goroutines is undefined; serialise each direction.


grpc-gateway proxies unary RPCs cleanly and supports server-streaming via
server-sent events / chunked responses. Client-streaming and
bidirectional-streaming RPCs are NOT exposed through the gateway by
default - mark them gateway-skip in your annotations or expose them only
on the native gRPC port.


## HTTP gateway (grpc-gateway)

Expose the same service over REST:

```go
gw := grpc.NewGateway(
    grpc.GatewayWithPort("8080"),
    grpc.GatewayWithGRPCEndpoint("localhost:50051"),
    grpc.GatewayWithInsecure(),  // or GatewayWithTLS(certFile)
    grpc.GatewayWithLogger(v.Log),
)

gw.RegisterHandler(pb.RegisterUsersHandlerFromEndpoint)

if err := gw.Build(context.Background()); err != nil {
    return err
}

// HTTP middleware chains applied to the gateway mux
gw.Use(cors.Default().Handler, requestLogger)

gw.StartAsync()
```

`gw.Mux()` returns the underlying `runtime.ServeMux` if you need to
attach custom handlers alongside the generated ones.

Like the server, the gateway enforces a production TLS guard: in
`production` it refuses to start unless dial credentials were configured
via `GatewayWithTLS(caCertFile)`, `GatewayWithTransportConfig(cfg)` (typed
mTLS config with `TLSCert` / `TLSKey` / `CACert`), or `GatewayWithInsecure()`
to opt out for a known-internal mesh. Outside production an unconfigured
gateway defaults to insecure credentials and logs a one-shot warning. The
gateway's HTTP server ships conservative read / write / idle timeouts and a
header-size bound by default; override them with `GatewayWithReadTimeout`,
`GatewayWithWriteTimeout`, `GatewayWithIdleTimeout`, and
`GatewayWithMaxHeaderBytes`. Defaults for `GatewayWithPort` /
`GatewayWithGRPCEndpoint` come from `GATEWAY_PORT` / `GRPC_ENDPOINT`.

## Context helpers

### Claims

`Claims` is an interface (`GetUserID() uint` / `GetTeamID() uint`); apps
implement it with their own claims type, or use the bundled `BasicClaims`:

```go
ctx = grpc.ContextWithClaims(ctx, &grpc.BasicClaims{UserID: 42, TeamID: 7})

claims := grpc.ClaimsFromContext(ctx)       // returns nil if absent
claims := grpc.MustClaimsFromContext(ctx)   // panics if absent - use in auth'd handlers

userID := grpc.UserIDFromContext(ctx)       // shortcut, 0 if no claims
teamID := grpc.TeamIDFromContext(ctx)
```

Attach them in an auth interceptor before the handler runs. The bundled
`interceptors.Auth` does this for you: its `AuthValidator.ValidateToken`
returns the resolved `Claims`, which the interceptor stores on the context.

### Request ID

```go
ctx = grpc.ContextWithRequestID(ctx, grpc.GenerateRequestID())
id := grpc.RequestIDFromContext(ctx)
```

### Method name

```go
ctx = grpc.ContextWithMethod(ctx, info.FullMethod)
method := grpc.MethodFromContext(ctx)
```

Useful inside logging interceptors that run below the method dispatch.

### Metadata helpers

```go
token  := grpc.ExtractBearerToken(ctx)       // from "authorization: Bearer ..."
value  := grpc.ExtractMetadata(ctx, "x-tenant-id")
values := grpc.ExtractAllMetadata(ctx, "x-forwarded-for")
```

## Errors

Typed constructors produce standard `google.golang.org/grpc/status`
errors:

```go
return nil, grpc.NotFound("user not found")
return nil, grpc.NotFoundf("user %d", id)
return nil, grpc.InvalidArgument("id required")
return nil, grpc.Unauthenticated("missing token")
return nil, grpc.PermissionDenied("not your team")
return nil, grpc.AlreadyExists("duplicate email")
return nil, grpc.FailedPrecondition("invoice already finalized")
return nil, grpc.ResourceExhausted("quota exceeded")
return nil, grpc.Unavailable("downstream timeout")
return nil, grpc.Internal("bug")
```

All wrap `codes.Code` under the hood.

### Inspecting errors

```go
if grpc.IsNotFound(err) {
    // handle
}

switch grpc.Code(err) {
case codes.NotFound:         // ...
case codes.InvalidArgument:  // ...
}

msg := grpc.Message(err)        // unwrap status message
status := grpc.FromError(err)   // raw *status.Status
```

### Wrapping existing errors

```go
if err := db.Find(&user); err != nil {
    return nil, grpc.WrapError(err)  // maps stdlib errors → grpc codes
}

return nil, grpc.WrapErrorWithCode(err, codes.FailedPrecondition)
```

## Reflection in production

When the environment is `production` (`APP_ENV=production` or
`WithEnvironment("production")`), `Build` hard-fails if reflection is
enabled - it returns an error rather than silently downgrading, so a
misconfigured deployment cannot ship thinking reflection is on while it
is off (or vice versa). Disable it (`GRPC_REFLECTION=false` or drop
`WithReflection(true)`) for production builds. `"prod"` and `"staging"`
fold into the same locked-down branch, so a typo'd `APP_ENV` cannot
re-enable introspection.

## Health checks

The package ships a standard gRPC health service. Construct one with
`grpc.NewHealthService()` and register it via the server's
`RegisterService`:

```go
health := grpc.NewHealthService()
srv.RegisterService(health.RegistrationFunc())
```

Drive the reported status with `health.SetServing(service)` /
`health.SetNotServing(service)`, or register a dynamic probe with
`health.RegisterChecker(service, func(ctx) error { ... })` that runs on
each check. Pair it with your load balancer's gRPC health probes.

## Events

`grpc/grpcevents` defines the events the bundled interceptors and the
server lifecycle dispatch. Wire a dispatcher via `Server.SetEventDispatcher`
(or pass the matching `With*EventDispatcher` option into each bundled
interceptor) and route them onto the framework event bus:

| Event | When |
|---|---|
| `ServerStarted` / `ServerStopped` | Server lifecycle |
| `GatewayStarted` / `GatewayStopped` | HTTP gateway lifecycle |
| `RequestStarted` / `RequestCompleted` / `RequestFailed` | Unary RPC lifecycle (carries `TraceID` / `SpanID` / `ParentID`) |
| `StreamStarted` / `StreamCompleted` / `StreamFailed` | Stream RPC lifecycle (same trace fields) |
| `PanicRecovered` | `Recovery` interceptor caught a panic |
| `AuthFailed` | `Auth` interceptor rejected a token (token is masked) |

```go
srv.SetEventDispatcher(func(ctx context.Context, evt any) error {
    return s.Events.Dispatch(ctx, evt)
})
```

`Protocol` ("grpc" or "http") on each request/stream event identifies
whether the call entered through the native gRPC server or the HTTP
gateway.

## Converters

`grpc/converters` ships helpers for the two most common proto <-> Go
gaps:

```go
import "github.com/velocitykode/velocity/grpc/converters"

// time.Time <-> *timestamppb.Timestamp
ts := converters.TimeValueToProto(user.CreatedAt)
t  := converters.ProtoToTimeValue(req.GetCreatedAt())

// time.Duration <-> *durationpb.Duration
d  := converters.DurationToProto(15 * time.Minute)
dur := converters.ProtoToDuration(req.GetTimeout())

// Offset pagination
page := converters.NormalizePagination(req.GetPage(), req.GetPageSize())
resp := converters.NewPaginationResponse(int32(page.Page), int32(page.Size), totalItems)

// Cursor pagination
cp := converters.NormalizeCursorPagination(req.GetCursor(), req.GetLimit())
cr := converters.NewCursorResponse(nextCursor, prevCursor, hasMore, int(cp.Limit))
```

`NormalizePagination` clamps page / page-size to sane defaults so handlers
don't have to defensively validate. `CalculateTotalPages` and the cursor
helpers cover the remaining bookkeeping.


================================================================================
# Driver Registry

Source: https://vel.build/docs/advanced/driver-registry/
Section: Advanced Topics
Summary: Pluggable driver registration across cache, queue, storage, mail, notification, log, and orm subsystems.


`driverregistry` is the single pattern every Velocity subsystem with
swappable backends uses to manage its drivers. Cache, queue, storage,
mail, notification, log, and orm each instantiate their own typed
registry and expose a `Drivers()` accessor; built-in factories
self-register from each package's `init()`, and third-party drivers
plug in through the same API without any framework code change.

Import path: `github.com/velocitykode/velocity/driverregistry`

## Why a registry

Before this package existed, every subsystem carried a hardcoded
`createDriver` switch:

```go
// old shape, no longer used
switch cfg.Driver {
case "memory": return newMemory(cfg)
case "redis":  return newRedis(cfg)
default:       return nil, fmt.Errorf("unknown driver %q", cfg.Driver)
}
```

That made third-party drivers impossible without forking the framework.
The registry replaces the switch with a typed lookup, so a custom driver
becomes a one-line registration:

```go
cache.Drivers().Register("dragonfly", newDragonflyStore)
```

`Resolve` also takes a `context.Context`, so a Redis dial, S3 endpoint
check, or DB connect honours the caller's deadline end to end.

## The Registry type

```go
type Registry[D any, C any] struct { /* unexported */ }

func New[D any, C any](subsystem string) *Registry[D, C]
```

`D` is the driver instance type the subsystem returns to callers
(`cache.Store`, `storage.Driver`, `mail.Mailer`, ...); `C` is the
driver-config shape (`cache.StoreConfig`, `storage.DiskConfig`,
`mail.MailConfig`, ...). Both stay generic so the resolution boundary
is type-safe; there is no `map[string]any` in the hot path.

You only call `New` if you are building a new subsystem. Application
and third-party code uses the per-subsystem `Drivers()` accessor.

### Public API

```go
type Factory[D any, C any] func(ctx context.Context, cfg C) (D, error)

func (r *Registry[D, C]) Register(name string, factory Factory[D, C])
func (r *Registry[D, C]) Override(name string, factory Factory[D, C]) Factory[D, C]
func (r *Registry[D, C]) Has(name string) bool
func (r *Registry[D, C]) Names() []string
func (r *Registry[D, C]) Resolve(ctx context.Context, name string, cfg C) (D, error)
```

| Method     | Purpose                                                                                                  |
|------------|----------------------------------------------------------------------------------------------------------|
| `Register` | Install a factory under `name`. Panics on empty name, nil factory, or duplicate registration.            |
| `Override` | Replace (or install) a factory; returns the previous factory so tests can defer restoration.             |
| `Has`      | Report whether a driver is registered (case-insensitive).                                                |
| `Names`    | Sorted snapshot of registered driver names. Used in `NotFoundError` for the "available" hint.            |
| `Resolve`  | Look up the factory, invoke it with `ctx` and `cfg`, return the driver instance or `*NotFoundError`.     |

Names are normalised (lower-cased and trimmed) on every call, so
`Register("Redis")` and `Resolve(..., "redis", ...)` are the same key.

All methods are safe for concurrent use; the factory map is guarded by
`sync.RWMutex`. Registration is rare (init-time); resolution is hot
and uses the read-locked fast path.


`Register` panics with `*contract.RegistrationError` on duplicate
names. That is the framework's "loud at boot" rule: a duplicate
registration is a programming bug that must surface at process start,
not at the first request. Use `Override` when you genuinely want to
replace.


## Subsystem accessors

Every subsystem with a registry exposes a `Drivers()` function that
returns its concrete `*Registry[D, C]`:

| Subsystem      | Accessor                | `D` (driver type)       | `C` (config type)              |
|----------------|-------------------------|-------------------------|--------------------------------|
| Cache          | `cache.Drivers()`       | `cache.Store`           | `cache.StoreConfig`            |
| Queue          | `queue.Drivers()`       | `queue.Driver`          | `queue.QueueConfig`            |
| Storage        | `storage.Drivers()`     | `storage.Driver`        | `storage.DiskConfig`           |
| Mail           | `mail.Drivers()`        | `mail.Mailer`           | `mail.MailConfig`              |
| Notification   | `notification.Drivers()`| `notification.Channel`  | `notification.ChannelConfig`   |
| Log            | `log.Drivers()`         | `log.Logger`            | `log.LogConfig`                |
| ORM            | `orm.Drivers()`         | `drivers.Driver`        | `drivers.ConnectionConfig`     |

Each subsystem's light built-in factories register themselves from the
package's `init()`, so they are available the moment the subsystem is
imported (no blank import required). Heavier drivers that carry their
own dependencies live in leaf packages and self-register from there:
`cache.DriverRedis` from `cache/redis`, the file/daily and `stack` log
drivers from `log/file` and `log/stack` (or the `log/standard`
aggregator). Blank-import the leaf to enable those.

## Registering a third-party driver

Two-step pattern: install the factory once at startup, then reference
the driver by name in config.

```go
package main

import (
    "context"
    "net"
    "strconv"

    "github.com/velocitykode/velocity/cache"
    "github.com/example/dragonfly"
)

func init() {
    cache.Drivers().Register("dragonfly", func(ctx context.Context, cfg cache.StoreConfig) (cache.Store, error) {
        return dragonfly.NewStore(ctx, dragonfly.Options{
            Addr:     net.JoinHostPort(cfg.Host, strconv.Itoa(cfg.Port)),
            Password: cfg.Password,
            DB:       cfg.Database,
            TLS:      cfg.TLS,
            Prefix:   cfg.Prefix,
        })
    })
}
```

Reference it from app config like any built-in:

```go
cfg := &cache.Config{
    Default: "fast",
    Stores: map[string]cache.StoreConfig{
        "fast": {Driver: "dragonfly", Host: "10.0.0.5", Port: 6380, Prefix: "app:"},
    },
}
mgr := cache.NewManager(cfg)
store, err := mgr.StoreWithContext(ctx, "fast")
```

The factory receives the same `StoreConfig` the manager uses for the
built-in Redis driver. Driver-specific fields (auth tokens, pool tuning,
TLS material) live wherever you choose to read them: environment
variables, dependency injection, or extra fields on a wrapping config
struct in your own package.


`cache.StoreConfig.Validate` no longer rejects driver names outside the
built-in set. The registry is the gate: an unknown name fails at
`Resolve` with `*driverregistry.NotFoundError`, after the driver
package's `init()` has had a chance to run. This is what makes
extensibility actually work.


### Per-subsystem registration snippets



```go
import "github.com/velocitykode/velocity/cache"

cache.Drivers().Register("dragonfly", func(ctx context.Context, cfg cache.StoreConfig) (cache.Store, error) {
    return newDragonflyStore(ctx, cfg)
})
```


```go
import "github.com/velocitykode/velocity/queue"

queue.Drivers().Register("kafka", func(ctx context.Context, cfg queue.QueueConfig) (queue.Driver, error) {
    return newKafkaDriver(ctx, cfg)
})
```


```go
import "github.com/velocitykode/velocity/storage"

storage.Drivers().Register("gcs", func(ctx context.Context, cfg storage.DiskConfig) (storage.Driver, error) {
    return newGCSDriver(ctx, cfg)
})
```


```go
import "github.com/velocitykode/velocity/mail"

mail.Drivers().Register("ses", func(ctx context.Context, cfg mail.MailConfig) (mail.Mailer, error) {
    return newSESDriver(ctx, cfg)
})
```


```go
import "github.com/velocitykode/velocity/notification"

notification.Drivers().Register("discord", func(_ context.Context, _ notification.ChannelConfig) (notification.Channel, error) {
    return newDiscordChannel(), nil
})
```


```go
import "github.com/velocitykode/velocity/log"

log.Drivers().Register("syslog", func(_ context.Context, cfg log.LogConfig) (log.Logger, error) {
    return newSyslogLogger(cfg.Config), nil
})
```


```go
import (
    "github.com/velocitykode/velocity/orm"
    "github.com/velocitykode/velocity/orm/drivers"
)

orm.Drivers().Register("clickhouse", func(_ context.Context, cfg drivers.ConnectionConfig) (drivers.Driver, error) {
    d := newClickhouseDriver()
    if err := d.Connect(cfg); err != nil {
        return nil, err
    }
    return d, nil
})
```



## Errors

```go
var ErrDriverNotFound = errors.New("driverregistry: driver not registered")

type NotFoundError struct {
    Subsystem string
    Name      string
    Available []string
}
```

`Resolve` returns `*NotFoundError` when the requested name has no
registered factory. The error includes a sorted list of registered
names so the message guides callers toward the right choice:

```
velocity/cache: driver "redus" not registered (available: database, file, memory, redis)
```

`*NotFoundError` unwraps to `ErrDriverNotFound`, so generic handling
works with `errors.Is`:

```go
store, err := cache.Drivers().Resolve(ctx, "redus", cfg)
if errors.Is(err, driverregistry.ErrDriverNotFound) {
    // fall back, or surface a typed config error
}
```

`Register` and `Override` panic with `*contract.RegistrationError`
(from the `contract` package) when the name is empty, the factory is
nil, or, for `Register`, the name is already taken. These are
boot-time conditions and intentionally noisy.

## Override semantics

`Override` is the testing entry point. It returns the previous factory
(or `nil` when none was registered) so a test can swap in a fake and
restore the original on cleanup:

```go
prev := cache.Drivers().Override("redis", func(_ context.Context, _ cache.StoreConfig) (cache.Store, error) {
    return cachetesting.NewFake(), nil
})
t.Cleanup(func() { cache.Drivers().Override("redis", prev) })
```

Passing a `nil` factory to `Override` deletes the registration. Use
`Register` in production code so duplicate names panic loudly.

## Optional driver interfaces

The registry stores factories, never long-lived driver instances.
Lifecycle for an instance is the instance's own concern through two
optional interfaces a subsystem manager may probe:

```go
type Closer interface {
    Close(ctx context.Context) error
}

type HealthChecker interface {
    Health(ctx context.Context) error
}
```

A driver can implement either, neither, or both. Subsystem managers
type-assert against these when they enumerate their owned drivers
during shutdown or `/healthz` probes. `Closer` is per-instance and
distinct from `contract.ShutdownAware`, which is for whole subsystems.

## Special case: the log stack driver

The `stack` log driver fans a single log call out to multiple child
loggers (e.g. `console` plus `daily`). It lives in its own leaf package
(`github.com/velocitykode/velocity/log/stack`); blank-import that leaf,
or the `log/standard` aggregator, to wire the factory. Its factory
resolves each child through the same `log.Drivers()` registry, and
aggregates failures with `errors.Join`:

```go
// extracted from log/stack/stack.go
for _, name := range channels {
    if name == "stack" {
        continue // prevent recursion
    }
    child, err := log.Drivers().Resolve(ctx, name, log.LogConfig{Driver: name, Config: cfg.Config})
    if err != nil {
        childErrs = append(childErrs, fmt.Errorf("velocity/log: stack driver: child %q: %w", name, err))
        continue
    }
    loggers = append(loggers, child)
}
if len(childErrs) > 0 {
    return nil, errors.Join(childErrs...)
}
```

The child set comes from the driver config's `channels` key (or the
legacy `stack` key), defaulting to `console` plus `daily` when absent.
A typo in any entry fails the whole stack at boot rather than silently
dropping that destination. Continuing with surviving children would
mask configuration errors that have to be fixed before the app keeps
running.

## Where validation lives

`StoreConfig.Validate` (and the equivalents on other subsystems' configs)
checks only that a driver name is present. Per-driver field validation,
host/port for Redis, path for file, bucket for S3, message stream for
Postmark, lives inside the factory, where the type information is
available. This is what lets a third-party driver enforce its own
invariants without the subsystem having to learn about it.

## Building a new subsystem on top

If you are adding a Velocity subsystem with swappable backends, follow
the existing shape:

1. Define the public driver interface `D` and the config struct `C`.
2. Declare a package-level registry: `var drivers = driverregistry.New[D, C]("my-subsystem")`.
3. Expose `func Drivers() *driverregistry.Registry[D, C] { return drivers }`.
4. Register the built-in factories from `init()`.
5. In your manager, call `drivers.Resolve(ctx, name, cfg)` where the old
   `createDriver` switch lived.

That is the whole pattern: no map of `any`, no type assertions on the
hot path, no per-subsystem reinvention of "did you mean?" errors.


================================================================================
# Contracts

Source: https://vel.build/docs/advanced/contract/
Section: Advanced Topics
Summary: Minimal, stdlib-only interfaces that break circular dependencies between Velocity subsystems.


The `contract` package defines the narrow interfaces that let Velocity
packages depend on each other's behavior without importing each other
directly. It is a leaf package: it declares interfaces (plus a small set
of stdlib-only environment helpers) and carries no implementations of its
own. Every signature uses only stdlib types, so the contract leaf never
pulls a heavier package into your import graph.

Import path: `github.com/velocitykode/velocity/contract`

## Cross-cutting interfaces

Two contracts are implemented across many subsystems rather than by a
single type. Bootstrap wiring threads them through every subsystem that
implements them.

```go
// EventDispatcherAware is implemented by every subsystem that emits
// framework events (cache, queue, scheduler, router, ORM, auth, view,
// mail, crypto). Bootstrap calls SetEventDispatcher to thread a single
// dispatcher through them all.
type EventDispatcherAware interface {
    SetEventDispatcher(fn func(ctx context.Context, event any) error)
}

// ShutdownAware is implemented by types that hold background resources
// (goroutines, connections, file handles). The provider registry and
// App.Shutdown call Shutdown in reverse registration order. Implementations
// must honour the context deadline and be safe to call more than once.
type ShutdownAware interface {
    Shutdown(ctx context.Context) error
}
```

## Subsystem interfaces

Each interface lists exactly the methods the consuming package needs.

```go
// Implemented by *auth.Manager.
type AuthManager interface {
    GateAllows(r *http.Request, ability string, args ...interface{}) bool
    GateAuthorize(r *http.Request, ability string, args ...interface{}) error
}

// Implemented by *csrf.CSRF.
type CSRFProtector interface {
    Middleware(next http.Handler) http.Handler
}

// Implemented by *view.Engine.
type ViewEngine interface {
    Back(w http.ResponseWriter, r *http.Request)
}

// Logger mirrors the log package's Logger interface exactly, so
// *log.StackLogger, log.NullLogger, and the redacting logger all satisfy
// it with no adapter. app.Services types its Log field as this contract.
type Logger interface {
    Debug(msg string, kvs ...any)
    Info(msg string, kvs ...any)
    Warn(msg string, kvs ...any)
    Error(msg string, kvs ...any)
    Fatal(msg string, kvs ...any)
}

// Encryptor is the symmetric-encryption contract. Encrypt* return the
// base64 envelope string; Decrypt* take it back. The *WithAAD variants
// bind additional authenticated data to the ciphertext.
type Encryptor interface {
    Encrypt(plaintext string) (string, error)
    EncryptBytes(plaintext []byte) (string, error)
    Decrypt(payload string) (string, error)
    DecryptBytes(payload string) ([]byte, error)
    EncryptBytesWithAAD(plaintext, aad []byte) (string, error)
    DecryptBytesWithAAD(payload string, aad []byte) ([]byte, error)
    GenerateKey() (string, error)
}
```

The package declares many more contracts in the same spirit - one narrow
interface per seam. The full set, with their implementers, is below.

## Who implements them

| Interface              | Implementation                            |
| ---------------------- | ----------------------------------------- |
| `EventDispatcherAware` | every event-emitting subsystem            |
| `ShutdownAware`        | every subsystem holding background resources |
| `AuthManager`          | `*auth.Manager`                           |
| `CSRFProtector`        | `*csrf.CSRF`                              |
| `CSRFTokenRotator`     | `*csrf.CSRF`                              |
| `ViewEngine`           | `*view.Engine`                            |
| `RedirectAllowlist`    | the router (`Router.RedirectAllowedHosts`) |
| `Logger`               | `*log.StackLogger`, `log.NullLogger`      |
| `Encryptor`            | `*crypto/drivers.AESDriver`, `crypto.Encryptor` |
| `Database`             | `*orm.Manager`                            |
| `LoginThrottler`       | `auth.NoopLoginThrottler` (default no-op) |
| `ExceptionHandler`     | the exceptions handler                    |
| `Cache` / `CacheManager` | the cache manager and stores            |
| `MailManager` / `Mailer` | `*mail.Manager`                         |
| `StorageManager` / `StorageDriver` | the storage manager and drivers |
| `Dispatcher` / `EventListener` | the events dispatcher             |
| `QueueDriver` / `QueueJob` | the queue manager and jobs            |
| `Validator`            | the validation engine                     |
| `Notifier` / `NotificationChannel` | the notification manager      |

## Environment helpers

The contract leaf also owns the canonical `APP_ENV` vocabulary, because
subsystems that cannot import the root `app` package (exceptions, auth,
csrf, scheduler, ...) still need to classify the environment. `app`
re-exports these as `app.Env`, `app.IsProductionEnv`, and so on.

```go
const EnvVar = "APP_ENV" // canonical env-var name

contract.GetEnv()                // normalised APP_ENV (lowercased, trimmed)
contract.NonProdEnvNames()       // []string of recognised non-prod names
contract.IsProductionEnv(env)    // "production"/"prod"/"staging"/unknown -> true
contract.IsTestingEnv(env)       // "test"/"testing" -> true
contract.IsDevelopmentEnv(env)   // "development"/"dev" -> true
contract.IsDevOrTestEnv(env)     // dev/test/local profiles -> true
```

Anything outside the recognised set is treated as production
(fail-secure): a typo in `APP_ENV` never silently disables a production gate.

## When you'd use it

- **Writing a custom auth manager, CSRF protector, or view engine** -
  satisfy the interface and Velocity will accept your implementation
  wherever the concrete type is expected.
- **Testing against Velocity internals** - use a fake that satisfies
  the contract instead of constructing the full type.

Most application code doesn't import `contract` directly; it's an
internal seam that keeps package dependency graphs acyclic.