# Anetos docs

> The documentation of Anetos, a batteries-included web framework for Go. This is the documentation of Anetos main (unreleased). Every page, as Markdown, in the sidebar's order; the index is https://docs.anetos.dev/llms.txt.


# Getting started

Source: https://docs.anetos.dev/getting-started/

From nothing to an app with pages, accounts and tests, in the order
you'd do it. About fifteen minutes; the tutorial then builds a whole
app in an hour.

**Installation**

1. [Install Anetos](https://docs.anetos.dev/getting-started/install/index.md): Go and the `anetos` tool.
2. [Set up your editor](https://docs.anetos.dev/getting-started/editor/index.md) for Go and templ.
3. [Choose a database](https://docs.anetos.dev/getting-started/databases/index.md): SQLite to start, PostgreSQL or
   MySQL when you like.
4. [Build with a coding agent](https://docs.anetos.dev/getting-started/coding-agents/index.md) (optional): Claude
   Code, Codex, Cursor, Gemini CLI or GitHub Copilot.

**Your first app**

5. [Create a project](https://docs.anetos.dev/getting-started/create-a-project/index.md) and run it with live reload.
6. [Project structure](https://docs.anetos.dev/getting-started/project-structure/index.md): what each folder holds.
7. [Add pages for a model](https://docs.anetos.dev/getting-started/crud/index.md) with `make:crud`.
8. [Add accounts](https://docs.anetos.dev/getting-started/add-accounts/index.md) with `make:auth`.
9. [Test and build](https://docs.anetos.dev/getting-started/test-and-build/index.md) for production.

**[Tutorial: build an issue tracker](https://docs.anetos.dev/getting-started/tutorial/index.md)**: accounts,
pages by hand, htmx, search, events, a queue and email, step by step.

**An API instead**: a JSON API for a mobile app or a front end
built separately.

1. [Create a project](https://docs.anetos.dev/getting-started/create-a-project/index.md#an-api-instead) with
   `--stack=api`.
2. [Add accounts to an API](https://docs.anetos.dev/guides/api-accounts/index.md): log in with
   tokens.
3. [Add endpoints for a model](https://docs.anetos.dev/getting-started/crud/index.md#in-an-api-project) with
   `make:crud`.
4. **[Tutorial: build an API](https://docs.anetos.dev/getting-started/build-an-api/index.md)**: bookmarks that are
   each user's, tokens for scripts, tests and the API's OpenAPI
   description, in half an hour.

Then the [guides](https://docs.anetos.dev/guides/index.md) take one feature at a time, and the
[concepts](https://docs.anetos.dev/concepts/index.md) explain how Anetos works.


# Installation

Source: https://docs.anetos.dev/getting-started/installation/

- [Install Anetos](https://docs.anetos.dev/getting-started/install/index.md): Anetos needs Go and its command-line tool, `anetos`, which creates projects and writes code.
- [Set up your editor](https://docs.anetos.dev/getting-started/editor/index.md): An Anetos app's code is Go, and its pages are [templ](https://templ.guide) files (`.templ`): HTML with Go expressions, compiled to Go. Your editor needs to know both.
- [Choose a database](https://docs.anetos.dev/getting-started/databases/index.md): Anetos apps run on SQLite, PostgreSQL, MySQL and MariaDB. Pick one when you create the project; you can switch later.
- [Build with a coding agent](https://docs.anetos.dev/getting-started/coding-agents/index.md): Coding agents such as Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot can build an Anetos app with you. Every project `anetos new` makes is ready for them: it has instructions they read before they start, guides for the common tasks, the documentation at the project's version a command away, and one command that tells them whether a change works.


# Install Anetos

Source: https://docs.anetos.dev/getting-started/install/

Anetos needs Go and its command-line tool, `anetos`, which creates
projects and writes code.

## Go

Install Go 1.26 or later from [go.dev/dl](https://go.dev/dl/), then
check:

```sh
go version   # go version go1.26.x …
```

Nothing else is required: the default database, SQLite, is built into
the app (in pure Go, so no C compiler either), and the views' compiler,
templ, comes with each project.

## The `anetos` tool

```sh
go install anetos.dev/anetos/cli/cmd/anetos@v0.5.0-rc.1
anetos version
```

`go install` puts it in `$(go env GOPATH)/bin` (usually `~/go/bin`):
add that folder to your `PATH` if `anetos` isn't found.

v0.5.0-rc.1 is the release candidate of v0.5.0, the first public
release. Until v0.5.0 is out, name it as above: `@latest` still finds
an earlier version that can't be installed.

You use this copy once per project, for `anetos new`. Each project then
pins its own version of the tool in `go.mod`, and you run it there as
`go tool anetos`, so everyone working on the project uses the same one.

## Upgrading

`go install anetos.dev/anetos/cli/cmd/anetos@latest` again updates the
tool for new projects. A project upgrades its own copy with Anetos:
see [Upgrading](https://docs.anetos.dev/upgrade/index.md).

Next: [Set up your editor](https://docs.anetos.dev/getting-started/editor/index.md).


# Set up your editor

Source: https://docs.anetos.dev/getting-started/editor/

An Anetos app's code is Go, and its pages are [templ](https://templ.guide)
files (`.templ`): HTML with Go expressions, compiled to Go. Your editor
needs to know both.

## Go

Install your editor's Go support, which runs `gopls`, Go's language
server: the Go extension in VS Code, the Go plugin in other JetBrains
IDEs (built into GoLand), `nvim-lspconfig`'s `gopls` in Neovim.

## templ

Install templ's extension: "templ-vscode" in VS Code, the "Templ"
plugin in GoLand, the `templ` language server in Neovim. They highlight
`.templ` files, complete Go in them, and report errors as you type.

The extensions start templ's language server, `templ lsp`, from your
`PATH`. Projects use templ as a tool of their module (`go tool templ`),
so install the same version for the editor too: the version is on the
`github.com/a-h/templ` line of the project's `go.mod`.

```sh
X
```

## Formatting

`gofmt` (your editor runs it on save) formats Go; `go tool templ fmt .`
formats `.templ` files. `go tool anetos dev` regenerates the templ
code and the models' typed columns as you save, so you don't run the
generators yourself.

Next: [Choose a database](https://docs.anetos.dev/getting-started/databases/index.md).


# Choose a database

Source: https://docs.anetos.dev/getting-started/databases/

Anetos apps run on SQLite, PostgreSQL, MySQL and MariaDB. Pick one when
you create the project; you can switch later.

| Database | `anetos new` flag | Needs |
|---|---|---|
| SQLite | none (the default) | Nothing: the database is a file, `database/app.db` |
| PostgreSQL | `--db=postgres` | A server, a database and a user |
| MySQL or MariaDB | `--db=mysql` | A server, a database and a user |

Anetos is tested on SQLite, PostgreSQL 16 and 17, MySQL 8.0, and
MariaDB 10.11 and 11.8.

## SQLite: start here

SQLite needs no server, so a new project runs at once. It suits
development, tests (they use an in-memory database), and many apps in
production: one server, with the database file on its disk. Its
driver is pure Go: no C compiler, and the app stays one static binary.

## PostgreSQL or MySQL

Choose a server database for apps that run on several servers, or when
your host provides one. Install it (your system's packages, Docker, or
a hosted service), then create a database and a user for the app, and
another database for the tests:

```sh
# PostgreSQL
createdb blog
createdb blog_test
```

```sql
-- MySQL or MariaDB
CREATE DATABASE blog CHARACTER SET utf8mb4;
CREATE DATABASE blog_test CHARACTER SET utf8mb4;
CREATE USER 'blog'@'localhost' IDENTIFIED BY 'secret';
GRANT ALL ON blog.* TO 'blog'@'localhost';
GRANT ALL ON blog_test.* TO 'blog'@'localhost';
```

On MySQL and MariaDB, `utf8mb4` is the character set that stores any
text, emoji included. MySQL 8 and MariaDB 11.6+ use it by default, but
an older MariaDB may default to latin1, which refuses most non-Latin
text. The tables the schema builder creates (`s.Create` in a
migration) are utf8mb4 either way; the database's own setting applies
to tables made with SQL (SQL-file migrations, `s.Exec`), and `doctor`
warns about text columns in another character set.

`anetos new blog --db=postgres` then writes the `DB_*` settings in
`.env` (`DB_NAME=blog`) and `.env.testing` (`blog_test`): set the
user and password there.

Some features use what each database has: full-text search works on all
of them, ranked differently; search by meaning needs PostgreSQL with
pgvector or MariaDB 11.7+ (SQLite compares every row, for small data;
MySQL can't). Each guide says what it needs, and the app
tells you at startup when the database lacks it.

To switch an existing project, see [Connect to a
database](https://docs.anetos.dev/guides/database/index.md#5-switch-a-project-to-postgresql-or-mysql).

Next: [Create a project](https://docs.anetos.dev/getting-started/create-a-project/index.md); then, if you work with
a coding agent, [Build with a coding agent](https://docs.anetos.dev/getting-started/coding-agents/index.md).


# Build with a coding agent

Source: https://docs.anetos.dev/getting-started/coding-agents/

Coding agents such as Claude Code, Codex, Cursor, Gemini CLI and GitHub
Copilot can build an Anetos app with you. Every project `anetos new`
makes is ready for them: it has instructions they read before they
start, guides for the common tasks, the documentation at the project's
version a command away, and one command that tells them whether a
change works.

## Before you start

- An Anetos project ([Create a project](https://docs.anetos.dev/getting-started/create-a-project/index.md)), or an
  existing one (step 5).
- A coding agent that works in your project's folder.

## Steps

### 1. Start the agent in the project

Open the agent in the project's folder, as you would for any other
work. What `anetos new` wrote is already there, and committed with the
rest:

| File | Read by | Holds |
|---|---|---|
| `AGENTS.md` | every agent above | The project (stack, database, CSS framework), the commands, where things go, the conventions, and how to check a change |
| `CLAUDE.md`, `GEMINI.md` | Claude Code, Gemini CLI | One line, `@AGENTS.md`, importing it |
| `.agents/skills/anetos-*/SKILL.md` | Codex, Copilot, Cursor, Gemini CLI | Skills: step-by-step guides an agent loads only for a task that needs one |
| `.claude/skills/anetos-*/SKILL.md` | Claude Code (and Copilot, Cursor) | The same skills |
| `.mcp.json`, `.vscode/mcp.json`, `.cursor/mcp.json`, `.gemini/settings.json`, `.codex/config.toml` | Claude Code and Copilot; VS Code; Cursor; Gemini CLI; Codex | The project's MCP server, `go tool anetos mcp` (step 4) |

The skills cover a resource (`anetos-crud`), accounts and access
(`anetos-auth`), schema changes (`anetos-migration`), background work
(`anetos-job`), pages and forms (`anetos-page`; in an API project,
`anetos-api` for endpoints), tests (`anetos-test`), deploying
(`anetos-deploy`), upgrading (`anetos-upgrade`) and plugins
(`anetos-plugin`).

### 2. Ask for a feature

Ask for what you want, in your words: "add a blog with posts and
comments, only logged-in users can comment". `AGENTS.md` tells the agent
to use the generators first (`make:crud`, `make:auth`), Anetos's
conventions (typed handlers, typed columns, the components of
`views/ui`), and to read the docs before guessing an API.

### 3. Let it read the docs and check its work

Two commands do most of the work for an agent, and are as useful to you:

```sh
go tool anetos docs --search "comments on a post"   # which pages to read
go tool anetos docs guides/relations                # print one, as Markdown
go tool anetos check                                # generate, build, vet, test, doctor
```

The pages `docs` prints are those of the Anetos version in your
`go.mod`, built into the tool: no network, and never another version's.
`check` stops at the first failing step and prints its output; with
`--json` it prints one object an agent can read. `AGENTS.md` asks the
agent to run it before calling a change done. In a fresh clone, with no
`.env` (an agent's sandbox, CI), its doctor step checks the project's
files only and says how to write one:
`cp .env.example .env && go tool anetos key:generate`.

### 4. Let it ask the app

Rather than reading every file to learn the app, an agent asks it:

```sh
go tool anetos model:list            # the models: tables, columns, relations
go run . route:list --json           # every route: handler, types, middleware
go run . db:schema posts             # a table as the database has it
go run . about                       # versions, services, settings (secrets hidden)
```

`model:list` reads the code, so it works before the app does; the
others are the app's own commands, which need a `.env`. Each takes
`--json` (and `migrate:status`, `schedule:list`, `plugin:list` and
`help` do too).

The agent can also call them as tools: the project's MCP server,
`go tool anetos mcp`, is in each agent's MCP settings (the files in the
table above), with `docs_search`, `docs_read`, `model_list`,
`route_list`, `db_schema`, `app_about`, `check` and `doctor`. It only
reads and checks. Agents decide differently when a project's server
starts: Claude Code asks you first; VS Code, Copilot CLI and Codex
start it in a folder you trust (Workspace Trust, folder trust, a trusted
project); Gemini CLI starts it unless you turned folder trust on and
haven't trusted the folder. `about` hides what looks like a secret (by the
setting's name, and a connection string's password), but shows the
other settings, and an agent sends what it reads to its model's
provider: read it before pasting it anywhere public.

### 5. Add the files to an existing project

A project made before these files, or with `anetos new --no-agent`:

```sh
go tool anetos agent:install                        # for every agent above
go tool anetos agent:install --agent=claude,codex   # or some of them
```

`claude` writes `CLAUDE.md` and `.claude/skills`; `gemini`, `GEMINI.md`
and `.agents/skills`; `codex`, `copilot` and `cursor`, `.agents/skills`.
An existing `CLAUDE.md` or `GEMINI.md` keeps its text, with the import
added first. The files are those of exactly the agents you list:
`--agent=claude` also removes Anetos's skills from `.agents/skills`.

### 6. Keep them current

After upgrading Anetos, refresh them:

```sh
go tool anetos agent:update
```

`go tool anetos doctor` warns when they're out of date.

## Make them yours

- **Your own instructions** go in `AGENTS.md` outside its markers
  (`<!-- anetos:begin … -->` and `<!-- anetos:end -->`): `agent:update`
  rewrites only the text between them. Or in `CLAUDE.md` or
  `GEMINI.md`, after the import.
- **Your own skills** go next to Anetos's, under names that don't start
  with `anetos-`: `agent:update` leaves them alone.
- **Your own MCP servers** go in the same files: `agent:update` changes
  only the `anetos` entry. gopls has one for Go itself (`gopls mcp`).

## How it works

`AGENTS.md` is the shared instruction file most coding agents read at
the start of a session; Claude Code and Gemini CLI read their own file,
which imports it. Skills follow the Agent Skills format (a folder with a
`SKILL.md`, its `name` and `description` first): an agent sees each
skill's description, and loads the rest only when a task matches, so
they don't fill its context.

`docs` reads the pages from the package `anetos.dev/anetos/docs`, in
the core module, which holds `docs/site`'s Markdown; the tool is built from the version your
`go.mod` pins, so the pages match the code. Its search matches whole
words and ranks pages by them, rare ones counting most.

An agent that browses rather than runs commands can read the same
pages on the site: `https://docs.anetos.dev/llms.txt` lists them, each
with a link to its Markdown copy, and `llms-full.txt` holds them all.

A coding agent works on your code. `make:agent` is something else: it
writes an AI agent that runs inside your app, for your users
([Add AI to your app](https://docs.anetos.dev/guides/ai/index.md)).

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| The agent writes code for another framework (its helpers, an ORM's methods Anetos doesn't have) | It guessed instead of reading | Ask it to read `AGENTS.md` and run `go tool anetos docs --search …` first; `check` catches what doesn't compile |
| Copilot or Cursor lists each skill twice | Both folders, `.agents/skills` and `.claude/skills`, are there, and they read both | Install for the agents you use only: `go tool anetos agent:install --agent=cursor` removes Anetos's skills from `.claude/skills` |
| `doctor` warns that agent files differ | An Anetos upgrade, or an edit between `AGENTS.md`'s markers | `go tool anetos agent:update` (move your edits outside the markers first) |
| Gemini CLI doesn't follow `AGENTS.md` | No `GEMINI.md` | `go tool anetos agent:install --agent=gemini` |
| The agent has no `anetos` tools | It hasn't been allowed to start the project's MCP server, or its settings file isn't there | Approve the `anetos` server in the agent's MCP settings (Codex: trust the project); `go tool anetos agent:install --agent=<agent>` writes the file |
| The `anetos` server doesn't start: `go: no such tool "anetos"` | The agent started it outside the project (Claude's desktop app starts servers in your home folder) | Start it as `go -C <the project's path> tool anetos mcp`: in your own (user) settings, not the committed file |

## Next steps

- [Create a project](https://docs.anetos.dev/getting-started/create-a-project/index.md), then ask your agent for its
  first feature.
- [anetos tool reference](https://docs.anetos.dev/reference/cli/index.md): `docs`, `check`,
  `agent:install` and `agent:update`.


# Your first app

Source: https://docs.anetos.dev/getting-started/your-first-app/

- [Create a project](https://docs.anetos.dev/getting-started/create-a-project/index.md): One command writes a working app: a home page in a styled layout, sessions, CSRF protection, migrations, a queue, email, a test, and the files to deploy it.
- [Project structure](https://docs.anetos.dev/getting-started/project-structure/index.md): A project is a Go module. Its folders follow what each part of the app does; the generators (`make:crud`, `make:auth`…) add their files in the same places.
- [Add pages for a model](https://docs.anetos.dev/getting-started/crud/index.md): `make:crud` writes a model with its table, and the pages to list, show, create, edit and delete its rows, made of your app's UI components, with their routes and a test. You get working pages in a minute, and code you can read and change.
- [Add accounts](https://docs.anetos.dev/getting-started/add-accounts/index.md): `make:auth` writes user accounts into your app: registration, login with "remember me", login with Google and GitHub, email verification, password reset, two-factor authentication, a settings page and API tokens, with their pages, emails, routes and tests.
- [Test and build](https://docs.anetos.dev/getting-started/test-and-build/index.md): go test ./...


# Create a project

Source: https://docs.anetos.dev/getting-started/create-a-project/

One command writes a working app: a home page in a styled layout,
sessions, CSRF protection, migrations, a queue, email, a test, and the
files to deploy it.

## Create it

```sh
anetos new blog
cd blog
```

`anetos new` writes the project, downloads its dependencies and
compiles its views. Its flags:

| Flag | Default | Meaning |
|---|---|---|
| `--db` | `sqlite` | `postgres` or `mysql` for a server database ([Choose a database](https://docs.anetos.dev/getting-started/databases/index.md)) |
| `--stack` | `web` | `api` for an app that serves JSON only ([below](https://docs.anetos.dev/getting-started/create-a-project/index.md#an-api-instead)) |
| `--css` | `anetos` | The CSS framework: `anetos`, the starter theme; `none`, components without classes and an almost empty stylesheet, for your own CSS; `pico`, `bootstrap` or `bulma`, components in that framework's markup, with its files; `tailwind`, components with Tailwind CSS's classes, compiled by `anetos dev` ([Style your app](https://docs.anetos.dev/guides/styling/index.md#7-or-start-with-a-css-framework)) |
| `--module` | the folder's name | The Go module path, such as `github.com/you/blog` |

## Run it

```sh
go run . migrate     # create the tables the framework uses
go tool anetos dev   # http://localhost:8080
```

`migrate` creates the database (for SQLite, `database/app.db`) and the
tables of sessions, the cache and the queue. `anetos dev` builds and
runs the app, and rebuilds it when you save a file: the page in your
browser reloads by itself. Keep it running in a terminal of its own.

Open http://localhost:8080: a welcome page, in light or dark like your
system. Edit `views/home.templ` and save to see it change; its text is
in `locales/en/app.yaml`, ready for other languages.

## The app's commands

The app is one program with commands. `go run . help` lists them:

```sh
go run . help          # every command
go run . route:list    # the URLs and their handlers
go run .               # run: the web server, the queue's workers and the scheduler
```

In production, the built binary takes the same commands
(`./bin/blog migrate`).

## An API instead

`--stack=api` writes an app that serves JSON only, for a
mobile app or a front end built separately:

```sh
anetos new shop --stack=api
cd shop
go run . migrate
go tool anetos dev   # http://localhost:8080/api/v1
```

It has the same database, queue, mail, storage, scheduler, plugins and
deploy files, but no views, static files, sessions or CSRF protection.
Its routes are in `routes/api.go`, under `/api/v1`; `GET /api/v1`
answers:

```json
{"name":"shop","message":"Welcome to the Shop API."}
```

Every error is JSON problem details, whatever the client accepts (a
missing URL's 404 too). Browsers on other origins may call the API once
`HTTP_CORS_ORIGINS` in `.env` lists them, such as
`http://localhost:5173`. `make:handler` writes JSON handlers in such a
project, `make:auth` accounts that log in with API tokens
([Add accounts to an API](https://docs.anetos.dev/guides/api-accounts/index.md)), and `make:crud`
JSON endpoints for a model ([Add pages for a model](https://docs.anetos.dev/getting-started/crud/index.md#in-an-api-project)).

`openapi.json` describes the API in OpenAPI 3.1, for clients and tools,
and the app serves it at `/api/v1/openapi.json`. `make:auth` and
`make:crud` update it; after changing a route or a handler yourself,
run `go run . openapi`: a test in `main_test.go` fails until you do
([Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md)).

Next: [Project structure](https://docs.anetos.dev/getting-started/project-structure/index.md).


# Project structure

Source: https://docs.anetos.dev/getting-started/project-structure/

A project is a Go module. Its folders follow what each part of the app
does; the generators (`make:crud`, `make:auth`…) add their files in the
same places.

```text
blog/
├── main.go               setup: the database, cache, queue, mail, server, routes…
├── main_test.go          tests of the home page and the 404 page
├── plugins.go            the plugins (anetos add)
├── app/
│   ├── handlers/         HTTP handlers: a request in, a page or JSON out
│   └── models/           models: Go structs for tables, and their typed columns
├── database/
│   ├── migrations/       changes to the tables, in Go, in order
│   └── factories/        test data
├── routes/
│   └── web.go            URLs to handlers, with their middleware
├── views/
│   ├── layout.templ      the page shell: the header, the flash message
│   ├── home.templ        the home page
│   ├── errors.templ      error pages (404, 500…) in the layout
│   └── ui/               the components the pages are made of: cards, forms, buttons, tables…
├── locales/en/app.yaml   the pages' text
├── public/               the web root: robots.txt, served at /robots.txt
│   └── static/           CSS (app.css, the starter theme), the icon (favicon.svg) and other files, at /assets/
├── deploy/               a systemd unit and the production settings
├── Dockerfile            a container image
├── .env                  settings for your machine (not in git)
├── .env.example          the settings, without secrets (in git)
├── AGENTS.md             instructions for coding agents (CLAUDE.md and GEMINI.md import it)
└── .agents/, .claude/    skills: coding agents' guides to common tasks
```

An API project (`anetos new --stack=api`) has `routes/api.go` instead
of `routes/web.go`, `app/handlers/welcome.go` (the answer to
`GET /api/v1`) instead of the home page, and no `views/` or `public/`;
`locales/en/app.yaml` holds its messages, and `main_test.go` tests the
welcome and a 404's JSON.

## How a request flows

1. `routes/web.go` matches the URL to a handler and runs the route's
   middleware: sessions and CSRF protection for pages.
2. The handler, in `app/handlers`, reads the request (typed input,
   validated) and the database (the models of `app/models`).
3. It renders a view of `views/`, inside `Layout`, or answers JSON.
   The views call the components of `views/ui`, which hold the markup
   and the class names ([Style your app](https://docs.anetos.dev/guides/styling/index.md)).

[HTTP request lifecycle](https://docs.anetos.dev/concepts/http-request-lifecycle/index.md)
explains each step.

## Settings

Settings come from the environment, and in development from `.env`:
`APP_KEY` (made fresh for each project), `DB_*`, `MAIL_*` and the rest.
Tests read `.env.testing` instead (or nothing, for SQLite: an in-memory
database). The [configuration reference](https://docs.anetos.dev/reference/configuration/index.md)
lists every key.

## Generated files

`*_templ.go` (from the `.templ` files) and `app/models/models_gen.go`
(the models' typed columns) are written by `templ generate` and
`anetos generate`; `anetos dev` and `anetos build` run both. Commit them, but
don't edit them.

The [CLI reference](https://docs.anetos.dev/reference/cli/index.md#anetos-new-directory) describes
every file `anetos new` writes.

Next: [Add pages for a model](https://docs.anetos.dev/getting-started/crud/index.md).


# Add pages for a model

Source: https://docs.anetos.dev/getting-started/crud/

`make:crud` writes a model with its table, and the pages to list, show,
create, edit and delete its rows, made of your app's UI components, with
their routes and a test. You get working pages in a minute, and code
you can read and change.

## Generate them

```sh
go tool anetos make:crud Post title:string body:text published:bool
go run . migrate
```

Open http://localhost:8080/posts (the header links to it): an empty
list with a "New post" button. Save the form empty to see the
validation messages, then fill it in.

Each field is `name:type`, then `:optional` or `:unique` if you like:

| Type | Go | Column | Input |
|---|---|---|---|
| `string` | `string` | `VARCHAR(255)` | a text box |
| `text` | `string` | `TEXT` | a text area |
| `email` | `string` | `VARCHAR(255)` | an email box, checked with the `email` rule |
| `int` | `int64` | `BIGINT` | a number box |
| `float` | `float64` | double | a number box with decimals |
| `bool` | `bool` | boolean | a checkbox |
| `date` | `anetos.Date` | `DATE` | a date picker |

Strings, texts, emails and dates are required; `:optional` lets them be
empty. `:unique`, for required strings and emails and for dates, adds a
unique index and the `unique` rule, so the form says "The email has
already been taken." rather than failing. (An optional string is empty,
not NULL, when left blank, and a blank number is 0: only one row could
have either, so `make:crud` refuses them; add such an index by hand.)

```sh
go tool anetos make:crud Customer name:string email:email:unique notes:text:optional since:date
```

## What it writes

For `Post`:

| File | Holds |
|---|---|
| `app/models/post.go` | `Post`, with a field per column; `anetos generate` adds `PostCols` to `models_gen.go` |
| `database/migrations/…_create_posts_table.go` | The `posts` table |
| `app/handlers/posts.go` | `Posts`: `Index` (20 a page, newest first), `Show`, `New`, `Create`, `Edit`, `Update`, `Delete`; `PostInput`, the form, with its `validate` tags |
| `views/posts.templ` | The list, a post's page, and the form for new and existing posts |
| `routes/posts.go` | `routes.Posts`: the seven routes, named `posts.index`, `posts.show`… |
| `locales/en/posts.yaml` | The pages' text: titles, buttons, the fields' labels, the messages |
| `posts_test.go` | A test that creates, shows, edits and deletes a post through the pages |

It also adds `Posts(pages)` to `routes/web.go` (the page group, with
sessions and CSRF protection) and a link to the list in the layout's
header. It never overwrites a file: if one exists, it writes nothing.
In a project made before v0.5, which has no `views/ui`, it writes the
components first, and says so ([Style your
app](https://docs.anetos.dev/guides/styling/index.md#projects-made-before-v05)).

| Route | URL | Does |
|---|---|---|
| `posts.index` | `GET /posts` | The list, with pages (`?page=2`) |
| `posts.new` | `GET /posts/new` | The empty form |
| `posts.create` | `POST /posts` | Creates the post, then shows it |
| `posts.show` | `GET /posts/{id}` | The post, with Edit and Delete |
| `posts.edit` | `GET /posts/{id}/edit` | The filled form |
| `posts.update` | `PUT /posts/{id}` | Saves the changes |
| `posts.delete` | `DELETE /posts/{id}` | Deletes the post, then lists the others |

HTML forms send `PUT` and `DELETE` with a hidden `_method` field, which
the project's `web.MethodOverride` reads.

Each route is named after its handler (`h.Create` is `posts.create`).

> **Coming from another framework?** Rails and Phoenix also call the
> form `new` and saving it `create`, and Phoenix says `delete` where
> Rails says `destroy`. Laravel's resource routes say `create` for the
> form, `store` for saving it and `destroy` for deleting. Django's
> generic views are classes (`CreateView`, `DeleteView`).

## Make it yours

The code is plain Anetos code: change it as you would your own.

- **Only for logged-in users.** After [`make:auth`](https://docs.anetos.dev/getting-started/add-accounts/index.md),
  move the `Posts(pages)` call from `routes/web.go` to the `loggedIn`
  group of `routes/auth.go` (`Posts(loggedIn)`): guests then go to the
  login page. Log a user in at the start of `TestPosts`, as its comment
  shows (`make:auth` wrote `factories.Users`), and show the header's
  link to logged-in users only, in `views/layout.templ` (importing
  `anetos.dev/anetos/auth` and the app's `app/models`):

  ```templ
  // illustrative
  if _, ok := auth.User[*models.User](ctx); ok {
  	@navLink("posts.index", i18n.T(ctx, "posts.title"))
  }
  ```
- **Another column.** Add a migration (`go tool anetos make:migration
  add_slug_to_posts_table`), the field to `Post` and `PostInput`, a
  line to `fill`, and the input to `postFields` in the view.
- **Other text.** Change `locales/en/posts.yaml`; add a language with
  its own folder ([Translations](https://docs.anetos.dev/guides/translations/index.md)).
- **Look.** The pages call the components of `views/ui` (`ui.PageHeader`,
  `ui.Table`, `ui.Form`, `ui.Field`…) and have no class names. Change
  the colors in `public/static/app.css`, or a component's markup in
  `views/ui`, and every page follows ([Style your
  app](https://docs.anetos.dev/guides/styling/index.md)).

`go test ./...` runs the test it wrote; keep it passing as you change
the pages.

## In an API project

In a project made with `anetos new --stack=api`, the same
command writes JSON endpoints instead of pages: the model and its
migration, `app/handlers/posts.go`, `routes/posts.go` and
`posts_test.go`, and `Posts(api)` at the end of `Register` in
`routes/api.go`. There are no views or catalog.

| Route | URL | Answers |
|---|---|---|
| `api.posts.index` | `GET /api/v1/posts` | A page of posts |
| `api.posts.create` | `POST /api/v1/posts` | `201` with the post, and its URL in `Location` |
| `api.posts.show` | `GET /api/v1/posts/{id}` | The post |
| `api.posts.update` | `PUT /api/v1/posts/{id}` | The post, every field replaced |
| `api.posts.delete` | `DELETE /api/v1/posts/{id}` | `204` |

A post is answered as `PostResponse`, a struct of the handlers' file
(the ID, the fields, `created_at`, `updated_at`), never as the model:
a column you add later shows only once you add it there. Optional dates
are `null` when empty. The body of `POST` and `PUT` is JSON with the
fields' names, checked with the same rules as the pages' form: a 422
lists the fields' errors.

The list is `{"data": [...], "current_page": 1, "per_page": 20,
"total": 1, "last_page": 1}`. Its query:

- `?page=2`, and `?per_page=50` (20 by default, at most 100).
- `?sort=title`, or `-title` for descending: `id`, `created_at`,
  `updated_at` or a field other than a text. Newest first (`-id`) by
  default; another value is a 422. Rows with the same value come newest
  first. Where an optional date's empty value (`NULL`) sorts depends on
  the database: first ascending in SQLite and MySQL, last in PostgreSQL.
- An exact filter per field of type string, email, int, bool or date:
  `?published=true`. An empty value (`?title=`) doesn't filter. Texts
  and floats aren't filters: search and ranges are yours to add to
  `Index`.

So fields can't be named `page`, `per_page` or `sort` in an API project.

The endpoints are open to every client. After
[`make:auth`](https://docs.anetos.dev/guides/api-accounts/index.md), for clients with a token only:

1. Move the `Posts(api)` call from `routes/api.go` to `routes/auth.go`,
   in the `loggedIn` group: `Posts(loggedIn)`.
2. If tokens should need abilities, require them on the routes, in
   `routes/posts.go` (with `anetos.dev/anetos/auth` imported):

   ```go
   // illustrative
   read := r.With(auth.RequireAbilities("posts:read"))
   write := r.With(auth.RequireAbilities("posts:write"))
   read.Get("/posts", web.H(h.Index)).Name("posts.index")
   write.Post("/posts", web.H(h.Create)).Name("posts.create").Status(http.StatusCreated)
   ```

3. `posts_test.go` now gets 401: make its test sign up first, with
   `auth_test.go`'s helper, `app, _ := authRegister(t)` in place of
   `app := anetostest.New(t, setup)`.
4. `go run . openapi`, so `openapi.json` says they need a token.

[Tutorial: build an API](https://docs.anetos.dev/getting-started/build-an-api/index.md) does it step by step, with
records that belong to their user.

`make:crud` updates `openapi.json`, the API's description, with the
five operations, `PostResponse`, `PostInput` and `PagePostResponse`
([Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md)).

Number and boolean fields are never required: a request without
`price` saves 0, and a `PUT` without it sets it back to 0. Add a rule
(`validate:"required"` refuses 0, so a positive `min:1` or a pointer
field may suit better) where a value must be given.

## When to write pages by hand

`make:crud` makes the common case quick: a table, a form, plain
validation. Pages with relations, permissions or htmx start from its
code, or from scratch: the [tutorial](https://docs.anetos.dev/getting-started/tutorial/index.md) builds issue
pages by hand, step by step, and the [guides](https://docs.anetos.dev/guides/index.md) cover
[forms](https://docs.anetos.dev/guides/forms/index.md), [validation](https://docs.anetos.dev/guides/validation/index.md),
[queries](https://docs.anetos.dev/guides/queries/index.md) and [relations](https://docs.anetos.dev/guides/relations/index.md).

Next: [Add accounts](https://docs.anetos.dev/getting-started/add-accounts/index.md).


# Add accounts

Source: https://docs.anetos.dev/getting-started/add-accounts/

`make:auth` writes user accounts into your app: registration, login
with "remember me", login with Google and GitHub, email verification,
password reset, two-factor authentication, a settings page and API tokens,
with their pages, emails, routes and tests.

```sh
go tool anetos make:auth
go run . migrate
```

Open http://localhost:8080/register. The header now has links to log
in and register, and, once you're logged in, your name, the settings
and a logout button (`AccountMenu`, in `views/auth.templ`). In
development, emails go to the `anetos dev` log: open the verification
link from there.

## Where users land

After logging in, users go to the page they asked for before logging
in, or else to `/dashboard`; after registering, to `/dashboard`. To send
them elsewhere, set `AUTH_HOME_URL` in `.env` and in production:

```sh
AUTH_HOME_URL=/posts
```

or change the default in `auth.go`, which `make:auth` wrote:

```go
// illustrative
a, err := auth.New(app, models.Users, auth.WithDefaultHomeURL("/posts"))
```

The setting wins over the default, so each deployment can choose.

## Pages for logged-in users only

`routes/auth.go` has a `loggedIn` group: guests who open its pages go to
the login page and come back after logging in. Put your own routes
there, such as `make:crud`'s (`Posts(loggedIn)`), and read the user in a
handler with `auth.User[*models.User](c)`. Their tests then log a user
in first, with the factory `make:auth` wrote:

```go
// illustrative
app := anetostest.New(t, setup)
ada := anetostest.Create(app, factories.Users)
anetostest.ActingAs(app, &ada).Get("/posts").AssertOK()
```

[Add accounts with make:auth](https://docs.anetos.dev/guides/accounts/index.md) describes every
page, setting and file, and how to change them.

Next: [Test and build](https://docs.anetos.dev/getting-started/test-and-build/index.md).


# Test and build

Source: https://docs.anetos.dev/getting-started/test-and-build/

## Test

```sh
go test ./...
```

Tests boot the app with test settings and a database of their own
(SQLite in memory, or `.env.testing`'s), and send requests to it like
a browser, through `anetostest`:

```go
// illustrative
func TestHome(t *testing.T) {
	app := anetostest.New(t, setup)
	app.Get("/").AssertOK().AssertSee("Welcome")
}
```

Each test runs in a transaction that is rolled back, so tests don't see
each other's rows. `make:crud` and `make:auth` wrote tests for their
pages; add one for each page and form you write. [Test your
app](https://docs.anetos.dev/guides/testing/index.md) shows forms, logged-in users, emails and
queue jobs.

## Build

```sh
go tool anetos build   # bin/blog
./bin/blog migrate
./bin/blog             # the web server, the queue's workers and the scheduler
```

`anetos build` compiles the views and the models' columns, then builds
one static binary that holds the migrations, the views and the files
of `public/` and `locales/`. A server needs only the binary and its
settings (the environment, or a file: `deploy/production.env.example`
lists them).

[Deploy](https://docs.anetos.dev/guides/deployment/index.md) runs it on a server with systemd, in
a container (the project has a `Dockerfile`), or on Fly.io and Render.
Before going live, run `./bin/blog doctor` with the production
settings: it reports unsafe ones (`SESSION_SECURE=false`, a database
reached without TLS, the log mail driver…) and migrations that haven't
run. See [Secure your app](https://docs.anetos.dev/guides/security/index.md).

Next: the [tutorial](https://docs.anetos.dev/getting-started/tutorial/index.md) builds a whole app, step by
step.


# Tutorial: build an issue tracker

Source: https://docs.anetos.dev/getting-started/tutorial/

In this tutorial you build a small issue tracker: people sign up, open
issues, comment on them, search them, and get an email when someone
comments on theirs. Then you build it for production. Along the way you
use most of what an Anetos app is made of: models and migrations,
handlers and routes, templ views and forms, accounts, htmx, full-text
search, events, queue jobs, email, and tests.

The whole tutorial takes about an hour. Short on time? Parts 1 to 3,
then 7, take about 30 minutes and give you an app with accounts and
issues, ready to deploy.

| Part | You add |
|---|---|
| [1. Create the app](https://docs.anetos.dev/getting-started/tutorial/01-create-the-app.md) | The project, running with live reload |
| [2. Accounts](https://docs.anetos.dev/getting-started/tutorial/02-accounts.md) | Sign-up, login, email verification, settings |
| [3. Issues](https://docs.anetos.dev/getting-started/tutorial/03-issues.md) | A model, a migration, pages to list, open and edit issues, a test |
| [4. The issue page](https://docs.anetos.dev/getting-started/tutorial/04-the-issue-page.md) | Comments posted with htmx, closing issues, an event |
| [5. Search](https://docs.anetos.dev/getting-started/tutorial/05-search.md) | A full-text index and a search page |
| [6. Email the author](https://docs.anetos.dev/getting-started/tutorial/06-email-the-author.md) | A mail, and a queued listener that sends it |
| [7. Deploy](https://docs.anetos.dev/getting-started/tutorial/07-deploy.md) | The production build, as a binary and an image |

## Before you start

- Go 1.26 or later (`go version`).
- The `anetos` tool:

  ```sh
  go install anetos.dev/anetos/cli/cmd/anetos@v0.5.0-rc.1
  ```

- Some Go: structs, methods, errors. You don't need to know Anetos.

No database server is needed: the app uses SQLite, in a file.

## Reading the code

Each block shows code to put in a file, and the text says where. A new
file starts with its package line, named after its folder (`package
handlers` in `app/handlers`), then the imports the tutorial shows with
it. When a block replaces generated code, the text says which.

## The finished code

[`examples/tutorial`](https://github.com/anetos-dev/anetos/tree/main/examples/tutorial) is the app at the
end of part 6, compiled and tested with every change to Anetos. If
something doesn't work, compare your files with it.

When you're done, [`examples/tracker`](https://github.com/anetos-dev/anetos/tree/main/examples/tracker) is
a bigger version of the same app: projects with members and roles,
labels, files, an admin, a JSON API. It's there to read when you build
your own.


# 1. Create the app

Source: https://docs.anetos.dev/getting-started/tutorial/01-create-the-app/

You create the project, run it, and look around.

## Create the project

```sh
anetos new tracker
cd tracker
```

`anetos new` writes a project, downloads its dependencies and generates
its views. The project is a Go module named `tracker`; its
packages import each other as `tracker/app/models` and so on. It pins
the `anetos` tool in `go.mod`: in the project, run it as `go tool
anetos`.

## Run it

Create the database tables the framework needs (sessions, the cache, the
queue's jobs), then start the app:

```sh
go run . migrate
go tool anetos dev
```

Open http://localhost:8080. `anetos dev` rebuilds and restarts the app
when you save a file, and reloads the page in the browser. Leave it
running in a terminal of its own for the rest of the tutorial.

## Look around

| Path | Holds |
|---|---|
| `main.go` | `setup`: connects the database, then adds the migrations, cache, queue, events, mailer, storage, scheduler, web server and routes. `main` calls it, and so do the tests |
| `.env` | The settings, for your machine: `APP_KEY` (a fresh key), `DB_NAME=database/app.db`… It stays out of git; `.env.example` lists the settings |
| `routes/web.go` | The routes: URLs to handlers |
| `app/handlers/home.go` | The home page's handler |
| `views/layout.templ`, `views/home.templ` | The page shell (a header with the app's links) and the home page, as [templ](https://templ.guide) components: typed Go functions that render HTML; `views/errors.templ` shows errors (a 404…) in the same shell |
| `views/ui/` | The components the pages are made of (`ui.Card`, `ui.Field`, `ui.Button`…): their markup and classes, so the pages need none |
| `public/static/app.css` | The styles: Anetos's starter theme, light and dark, with no build step ([Style your app](https://docs.anetos.dev/guides/styling/index.md)) |
| `locales/en/app.yaml` | The home page's text |
| `database/migrations/` | Migrations: changes to the database's tables, in Go |
| `main_test.go` | Tests that request the home page and a missing page |

`go run . help` lists the app's commands: `run` (the default: the web
server, the queue's workers and the scheduler), `migrate`, `route:list`
and more. The [CLI reference](https://docs.anetos.dev/reference/cli/index.md) has the full list
of files and commands.

Run the test:

```sh
go test ./...
```

Tests boot the app with an in-memory database, so they don't touch
`database/app.db`.

Next: [2. Accounts](https://docs.anetos.dev/getting-started/tutorial/02-accounts.md).


# 2. Accounts

Source: https://docs.anetos.dev/getting-started/tutorial/02-accounts/

Issues have authors, so the app needs accounts. One command writes them.

## Add accounts

```sh
go tool anetos make:auth
go run . migrate
```

`make:auth` writes the code of accounts into your project, as files you
own and can change:

| File | Holds |
|---|---|
| `app/models/user.go` | `User`, and `models.Users`, which tells package `auth` how to find and update users |
| `app/handlers/auth.go`, `app/handlers/settings.go` | Registration, login (with a password, Google or GitHub), email verification, password reset, two-factor authentication, API tokens, the settings page |
| `views/auth.templ`, `views/settings.templ` | Their pages, and `AccountMenu`, the header's links to log in, register and log out, which `make:auth` adds to `views/layout.templ` |
| `routes/auth.go` | Their routes. Pages for logged-in users go in its `loggedIn` group |
| `auth_test.go` | Their tests |
| `database/factories/users.go` | `factories.Users`, which makes users for your own tests |

`migrate` creates the `users`, `api_tokens` and `social_accounts`
tables.

## Try it

Open http://localhost:8080/register and sign up. The app sends a link to
verify your address: in development, emails go to the log
(`MAIL_DRIVER=log`), so look in the terminal where `anetos dev` runs and
open the link. You land on `/dashboard` (`AUTH_HOME_URL` sets another
page; part 3 shows how); `/settings` changes your name, password,
language and time zone.

`go test ./...` now runs the accounts' tests too.

The [accounts guide](https://docs.anetos.dev/guides/accounts/index.md) explains what's there and
how to change it.

Next: [3. Issues](https://docs.anetos.dev/getting-started/tutorial/03-issues.md).


# 3. Issues

Source: https://docs.anetos.dev/getting-started/tutorial/03-issues/

You add the issues: a model and its table, pages to list, open and edit
them, and a test.

> **Tip:** `go tool anetos make:crud Issue title:string body:text`
> writes a model, its table, and pages to list, show, create, edit and
> delete its rows, in one command ([Add pages for a
> model](https://docs.anetos.dev/getting-started/crud/index.md)). Here you write them by hand, to see each piece
> and make issues your own: they have an author and a status.

## The model and its table

```sh
go tool anetos make:model Issue --migration
```

This writes `app/models/issue.go` and a migration,
`database/migrations/<date>_create_issues_table.go`. Give the model its
fields:

```go
// Issue is a bug or a task. `go tool anetos generate` writes its typed columns
// (IssueCols) and relations (IssueRels) to models_gen.go.
type Issue struct {
	db.Model        // id, created_at, updated_at
	Title    string `db:"title"`
	Body     string `db:"body"`
	Status   string `db:"status"` // "open" or "closed"
	AuthorID int64  `db:"author_id"`

	Author *User `rel:"belongs_to"` // by AuthorID
}
```

(Copied from [`examples/tutorial/app/models/issue.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/models/issue.go), region `model`.)

`db.Model` adds the `id`, `created_at` and `updated_at` columns. Each
field's `db` tag names its column; `Author` is a relation, loaded when
you ask for it, by the `author_id` column (the [relations
guide](https://docs.anetos.dev/guides/relations/index.md) has the others).

Then the table, in the migration's first function (the second one undoes
it):

```go
func(s *migrate.Schema) error {
	return s.Create("issues", func(t *migrate.Table) {
		t.ID()
		t.String("title", 200)
		t.Text("body")
		t.String("status", 10).Default("open")
		t.ForeignID("author_id").References("users")
		t.Timestamps()
	})
},
```

(Copied from [`examples/tutorial/database/migrations/2026_10_06_142537_create_issues_table.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/database/migrations/2026_10_06_142537_create_issues_table.go), region `migration`.)

Create the table, and the model's typed columns:

```sh
go run . migrate
go tool anetos generate
```

`anetos generate` (which `anetos dev` also runs when you save) writes the
model's typed columns and relations to `app/models/models_gen.go`, so
queries say `models.IssueCols.Title` and `models.IssueRels.Author`, and
the compiler catches a misspelled column.

## The handlers

```sh
go tool anetos make:handler Issues
```

It wrote `app/handlers/issues.go`, with the `Issues` type and an
`Index` method. The handlers below need these imports:

```go
import (
	"net/http"

	"anetos.dev/anetos/auth"
	"anetos.dev/anetos/db"
	"anetos.dev/anetos/web"

	"tracker/app/models"
	"tracker/views"
)
```

(Copied from [`examples/tutorial/app/handlers/issues.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/handlers/issues.go), region `imports`.)

Replace `Index` with the list:

```go
// IssueList is the input of GET /issues: the page number, from ?page=.
type IssueList struct {
	Page int `query:"page"`
}

// Index lists the issues, newest first, 20 a page.
func (Issues) Index(c *web.Ctx, in IssueList) (web.Responder, error) {
	page, err := db.Query[models.Issue](c).
		With(models.IssueRels.Author).
		OrderBy(models.IssueCols.ID.Desc()).
		Paginate(in.Page, 20)
	if err != nil {
		return nil, err
	}
	return web.Render(views.IssuesPage(page)), nil
}
```

(Copied from [`examples/tutorial/app/handlers/issues.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/handlers/issues.go), region `index`.)

`web.H` (in the routes below) turns a function of an input struct into a
handler: it fills `IssueList` from the request (`query:"page"`), and
renders what the function returns. `Paginate` counts the issues and
returns one page, with `With` loading their authors in one more query.

Below it, opening an issue:

```go
// IssueInput is the issue form. Its validate tags are checked before the
// handler runs: an invalid form goes back with its errors.
type IssueInput struct {
	Title string `json:"title" validate:"required|max:200"`
	Body  string `json:"body" validate:"max:10000"`
}

// New shows the form for a new issue.
func (Issues) New(c *web.Ctx) error {
	return c.Render(http.StatusOK, views.IssueForm(models.Issue{}))
}

// Create opens an issue by the logged-in user.
func (Issues) Create(c *web.Ctx, in IssueInput) (web.Responder, error) {
	u, err := auth.Current[*models.User](c)
	if err != nil {
		return nil, err
	}
	issue := models.Issue{Title: in.Title, Body: in.Body, Status: "open", AuthorID: u.ID}
	if err := db.Create(c, &issue); err != nil {
		return nil, err
	}
	c.Session().Flash("status", "Issue opened.")
	return web.RedirectRoute("issues.index"), nil
}
```

(Copied from [`examples/tutorial/app/handlers/issues.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/handlers/issues.go), region `create`.)

The form's fields fill `IssueInput` by their `json` names, and its
`validate` tags are checked first: when they fail, the browser goes back
to the form with the messages and what was typed, and `Create` doesn't
run. `auth.Current` is the logged-in user.

And editing one, which only its author may:

```go
// IssueID reads {id} from the path.
type IssueID struct {
	ID int64 `path:"id"`
}

// UpdateIssue is the input of PUT /issues/{id}: the path and the form.
type UpdateIssue struct {
	IssueID
	IssueInput
}

// own returns the issue if the logged-in user wrote it: others get a
// 403, and an issue that doesn't exist is a 404 (db.ErrNotFound).
func own(c *web.Ctx, id int64) (models.Issue, error) {
	issue, err := db.Find[models.Issue](c, id)
	if err != nil {
		return issue, err
	}
	u, err := auth.Current[*models.User](c)
	if err != nil {
		return issue, err
	}
	if issue.AuthorID != u.ID {
		return issue, web.Error(http.StatusForbidden, "Only the issue's author can change it.")
	}
	return issue, nil
}

// Edit shows the form to edit an issue.
func (Issues) Edit(c *web.Ctx, in IssueID) (web.Responder, error) {
	issue, err := own(c, in.ID)
	if err != nil {
		return nil, err
	}
	return web.Render(views.IssueForm(issue)), nil
}

// Update saves the issue.
func (Issues) Update(c *web.Ctx, in UpdateIssue) (web.Responder, error) {
	issue, err := own(c, in.ID)
	if err != nil {
		return nil, err
	}
	issue.Title, issue.Body = in.Title, in.Body
	if err := db.Update(c, &issue); err != nil {
		return nil, err
	}
	c.Session().Flash("status", "Issue saved.")
	return web.RedirectRoute("issues.index"), nil
}
```

(Copied from [`examples/tutorial/app/handlers/issues.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/handlers/issues.go), region `edit`.)

`db.Find` returns `db.ErrNotFound` for an issue that doesn't exist, which
becomes a 404; `web.Error` makes a 403.

## The pages

Create `views/issues.templ`, in package `views`, with these imports:

```templ
import (
	"fmt"

	"anetos.dev/anetos/db"
	"anetos.dev/anetos/view"
	"anetos.dev/anetos/web"

	"tracker/app/models"
	"tracker/views/ui"
)
```

(Copied from [`examples/tutorial/views/issues.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/issues.templ), region `imports`.)

The list:

```templ
// IssuesPage lists a page of issues, with links to the pages around it.
templ IssuesPage(page db.Page[models.Issue]) {
	@Layout("Issues") {
		@ui.PageHeader("Issues", "") {
			@ui.LinkButton(web.MustURL(ctx, "issues.new"), ui.Primary) {
				New issue
			}
		}
		if page.Total == 0 {
			@ui.Empty("No issues yet.")
		} else {
			@ui.Table() {
				<tbody>
					for _, issue := range page.Data {
						<tr>
							<td>
								@statusBadge(issue.Status)
							</td>
							<td><a href={ templ.URL(fmt.Sprintf("/issues/%d", issue.ID)) }>{ issue.Title }</a></td>
							<td><small>#{ issue.ID } by { issue.Author.Name }</small></td>
						</tr>
					}
				</tbody>
			}
		}
		if page.LastPage > 1 {
			@ui.Pagination(ui.PagesOf(ctx, page, "Pages", "", "Newer", "Older"))
		}
	}
}

// statusBadge shows an issue's status: green while it's open.
templ statusBadge(status string) {
	if status == "open" {
		@ui.Badge(ui.Success) {
			{ status }
		}
	} else {
		@ui.Badge(ui.Neutral) {
			{ status }
		}
	}
}
```

(Copied from [`examples/tutorial/views/issues.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/issues.templ), region `list`.)

The titles link to each issue's page, which you add in part 4. The form,
for new issues and edits:

```templ
// IssueForm opens an issue, or edits one when issue.ID is set. After a
// failed post, view.Old refills the fields and view.Errors has the
// messages.
templ IssueForm(issue models.Issue) {
	@Layout("Issue") {
		@ui.Narrow() {
			if issue.ID == 0 {
				<h1>New issue</h1>
				@ui.Card("") {
					@ui.Form(web.MustURL(ctx, "issues.create"), "POST", nil) {
						@issueFields(issue)
					}
				}
			} else {
				<h1>Edit #{ issue.ID }</h1>
				@ui.Card("") {
					@ui.Form(web.MustURL(ctx, "issues.update", issue.ID), "PUT", nil) {
						@issueFields(issue)
					}
				}
			}
		}
	}
}

templ issueFields(issue models.Issue) {
	@ui.Field("title", "Title", "") {
		@ui.Input("title", "", view.Old(ctx, "title", issue.Title), nil)
	}
	@ui.Field("body", "Description", "") {
		@ui.Textarea("body", view.Old(ctx, "body", issue.Body), templ.Attributes{"rows": "6"})
	}
	@ui.Button(ui.Primary, nil) {
		Save
	}
}
```

(Copied from [`examples/tutorial/views/issues.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/issues.templ), region `form`.)

The pages are made of the components in `views/ui`, which `anetos new`
wrote: `ui.PageHeader`, `ui.Table`, `ui.Badge`, `ui.Card`, `ui.Field`…
They carry the markup and the starter theme's classes (in
`public/static/app.css`), so the pages need none, and another design
CSS framework restyles them ([Style your app](https://docs.anetos.dev/guides/styling/index.md)).
`ui.Form` adds the token that protects forms from other sites, and,
since HTML forms can't send PUT, says the method in a field.
`ui.Field` shows the field's message when validation fails, and
`view.Old` puts back what was typed.

## The routes

The pages are for logged-in users: in `routes/auth.go`, add the routes
at the end of the `loggedIn` group, after the `/confirm-password` ones:

```go
// The tracker's pages, for logged-in users.
var issues handlers.Issues
loggedIn.Get("/issues", web.H(issues.Index)).Name("issues.index")
loggedIn.Get("/issues/new", issues.New).Name("issues.new")
loggedIn.Post("/issues", web.H(issues.Create)).Name("issues.create")
loggedIn.Get("/issues/{id}/edit", web.H(issues.Edit)).Name("issues.edit")
loggedIn.Put("/issues/{id}", web.H(issues.Update)).Name("issues.update")
```

(Copied from [`examples/tutorial/routes/auth.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/routes/auth.go), region `routes-issues`.)

Each route has a name, which `web.URL` and `web.RedirectRoute` use, so
URLs are written once. Guests who open these pages go to the login page.

Link to the list from the header: in `views/layout.templ`, add a line
to the nav, below the home page's:

```templ
@navLink("issues.index", "Issues")
```

(Copied from [`examples/tutorial/views/layout.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/layout.templ), region `nav-issues`.)

`navLink` (in the layout) marks the link as the current page on the
issue pages, whose route names start with `issues.`.

## Try it

Open http://localhost:8080/issues. Open an issue with an empty title
(the form says what's wrong), then with one. Edit it.

> **Tip:** Logging in leads to `/dashboard`. To land on the issues
> instead, add `AUTH_HOME_URL=/issues` to `.env`, or change the default
> in `auth.go`: `auth.WithDefaultHomeURL("/issues")`.

## Test it

Tests need users: `make:auth` wrote a factory for them,
`factories.Users` in `database/factories/users.go`, which makes
verified users (`User 1`, `user1@example.com`…).

Then create `issues_test.go` next to `main.go`, in package `main`:

```go
import (
	"net/url"
	"testing"

	"anetos.dev/anetos/anetostest"

	"tracker/app/models"
	"tracker/database/factories"
)
```

(Copied from [`examples/tutorial/issues_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/issues_test.go), region `imports`.)

```go
func TestIssues(t *testing.T) {
	app := anetostest.New(t, setup)
	ada := anetostest.Create(app, factories.Users)
	anetostest.ActingAs(app, &ada) // logged in for the requests that follow

	app.Get("/issues/new").AssertOK()
	// Invalid: back to the form, with the errors.
	app.PostForm("/issues", url.Values{"title": {""}}).
		AssertRedirect("/issues/new").
		AssertValidationErrors("title")
	// Valid: to the list, which shows it.
	app.PostForm("/issues", url.Values{"title": {"Login fails"}, "body": {"Since Tuesday."}}).
		AssertRedirect("/issues").
		Follow().
		AssertSee("Issue opened.", "Login fails", "by "+ada.Name)
	anetostest.AssertDatabaseHas[models.Issue](app, models.IssueCols.Title.Eq("Login fails"), models.IssueCols.AuthorID.Eq(ada.ID))

	// Only its author edits it.
	app.PutForm("/issues/1", url.Values{"title": {"Login fails on Safari"}}).AssertRedirect("/issues")
	grace := anetostest.Create(app, factories.Users)
	anetostest.ActingAs(app, &grace)
	app.Get("/issues/1/edit").AssertForbidden()
	app.Get("/issues/2/edit").AssertNotFound()

	// Guests go to the login page.
	app.PostForm("/logout", nil)
	app.Get("/issues").AssertRedirect("/login")
}
```

(Copied from [`examples/tutorial/issues_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/issues_test.go), region `test`.)

`anetostest.New` boots the app with an in-memory database, migrated, and
`ActingAs` logs a user in. The requests go through the whole app,
middleware and CSRF protection included, as a browser's would.

```sh
go test ./...
```

The [testing guide](https://docs.anetos.dev/guides/testing/index.md) has the other assertions.

Next: [4. The issue page](https://docs.anetos.dev/getting-started/tutorial/04-the-issue-page.md).


# 4. The issue page

Source: https://docs.anetos.dev/getting-started/tutorial/04-the-issue-page/

Each issue gets its page, with comments that post without reloading the
page, and a button to close it.

## Comments

```sh
go tool anetos make:model Comment --migration
```

The model, and an event the app emits when someone comments (part 6
sends an email on it):

```go
// Comment is a reply on an issue.
type Comment struct {
	db.Model
	IssueID  int64  `db:"issue_id"`
	AuthorID int64  `db:"author_id"`
	Body     string `db:"body"`

	Author *User `rel:"belongs_to"` // by AuthorID
}

// CommentAdded is an event, emitted when someone comments on an issue:
// other parts of the app can react to it (events.On).
type CommentAdded struct {
	CommentID int64
}
```

(Copied from [`examples/tutorial/app/models/comment.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/models/comment.go), region `model`.)

Its table. A comment belongs to an issue: deleting the issue deletes its
comments (`CascadeOnDelete`):

```go
func(s *migrate.Schema) error {
	return s.Create("comments", func(t *migrate.Table) {
		t.ID()
		t.ForeignID("issue_id").Constrained().CascadeOnDelete()
		t.ForeignID("author_id").References("users")
		t.Text("body")
		t.Timestamps()
	})
},
```

(Copied from [`examples/tutorial/database/migrations/2026_10_06_142838_create_comments_table.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/database/migrations/2026_10_06_142838_create_comments_table.go), region `migration`.)

```sh
go run . migrate
```

## The handlers

Create `app/handlers/issue_page.go`, in package `handlers`:

```go
import (
	"context"

	"anetos.dev/anetos/auth"
	"anetos.dev/anetos/db"
	"anetos.dev/anetos/events"
	"anetos.dev/anetos/web"

	"tracker/app/models"
	"tracker/views"
)
```

(Copied from [`examples/tutorial/app/handlers/issue_page.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/handlers/issue_page.go), region `imports`.)

The page:

```go
// Show is an issue's page: the issue and its comments, oldest first.
func (Issues) Show(c *web.Ctx, in IssueID) (web.Responder, error) {
	issue, err := db.Query[models.Issue](c).With(models.IssueRels.Author).Find(in.ID)
	if err != nil {
		return nil, err // db.ErrNotFound: 404
	}
	comments, err := db.Query[models.Comment](c).
		Where(models.CommentCols.IssueID.Eq(issue.ID)).
		With(models.CommentRels.Author).
		OrderBy(models.CommentCols.ID.Asc()).
		Get()
	if err != nil {
		return nil, err
	}
	return web.Render(views.IssuePage(issue, comments)), nil
}
```

(Copied from [`examples/tutorial/app/handlers/issue_page.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/handlers/issue_page.go), region `show`.)

Adding a comment:

```go
// CommentInput is a new comment on the issue {id}.
type CommentInput struct {
	IssueID
	Body string `json:"body" validate:"required|max:10000"`
}

// Comment adds a comment, and emits CommentAdded. With htmx, the comment
// is sent back to add to the page; otherwise the browser reloads it.
func (Issues) Comment(c *web.Ctx, in CommentInput) (web.Responder, error) {
	issue, err := db.Find[models.Issue](c, in.ID)
	if err != nil {
		return nil, err
	}
	u, err := auth.Current[*models.User](c)
	if err != nil {
		return nil, err
	}
	comment := models.Comment{IssueID: issue.ID, AuthorID: u.ID, Body: in.Body}
	err = db.Tx(c, func(ctx context.Context) error { // the comment and its event, or neither
		if err := db.Create(ctx, &comment); err != nil {
			return err
		}
		return events.Emit(ctx, models.CommentAdded{CommentID: comment.ID})
	})
	if err != nil {
		return nil, err
	}
	if c.IsHTMX() {
		comment.Author = u
		return web.Render(views.CommentItem(comment)), nil
	}
	return web.RedirectRoute("issues.show", issue.ID), nil
}
```

(Copied from [`examples/tutorial/app/handlers/issue_page.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/handlers/issue_page.go), region `comment`.)

The comment and its event are written in one transaction (`db.Tx`):
listeners that send email wait for it to commit, so nobody is told about
a comment that wasn't saved. A request from htmx (`c.IsHTMX`) gets the
new comment alone, to add to the page.

Closing and reopening, which `own` (from part 3) keeps to the author:

```go
// StatusInput closes or reopens the issue {id}.
type StatusInput struct {
	IssueID
	Status string `json:"status" validate:"required|in:open,closed"`
}

// SetStatus closes or reopens an issue (its author only), and goes back
// to its page.
func (Issues) SetStatus(c *web.Ctx, in StatusInput) (web.Responder, error) {
	issue, err := own(c, in.ID)
	if err != nil {
		return nil, err
	}
	issue.Status = in.Status
	if err := db.Update(c, &issue); err != nil {
		return nil, err
	}
	return web.RedirectRoute("issues.show", issue.ID), nil
}
```

(Copied from [`examples/tutorial/app/handlers/issue_page.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/handlers/issue_page.go), region `status`.)

## The page

Create `views/issue_page.templ`, in package `views`:

```templ
import (
	"fmt"

	"anetos.dev/anetos/auth"
	"anetos.dev/anetos/view"
	"anetos.dev/anetos/web"

	"tracker/app/models"
	"tracker/views/ui"
)
```

(Copied from [`examples/tutorial/views/issue_page.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/issue_page.templ), region `imports`.)

```templ
// IssuePage shows an issue with its comments. Its author gets the
// buttons to edit, close and reopen it.
templ IssuePage(issue models.Issue, comments []models.Comment) {
	@Layout(issue.Title) {
		<p><a href={ web.URL(ctx, "issues.index") }>← Issues</a></p>
		@ui.PageHeader(issue.Title, fmt.Sprintf("#%d, opened by %s", issue.ID, issue.Author.Name)) {
			@ui.Cluster() {
				@statusBadge(issue.Status)
				if u, ok := auth.User[*models.User](ctx); ok && u.ID == issue.AuthorID {
					@ui.LinkButton(web.MustURL(ctx, "issues.edit", issue.ID), ui.Secondary) {
						Edit
					}
					@ui.InlineForm(web.MustURL(ctx, "issues.status", issue.ID), "POST", nil) {
						if issue.Status == "open" {
							<input type="hidden" name="status" value="closed"/>
							@ui.Button(ui.Primary, nil) {
								Close
							}
						} else {
							<input type="hidden" name="status" value="open"/>
							@ui.Button(ui.Primary, nil) {
								Reopen
							}
						}
					}
				}
			}
		}
		@ui.Card("") {
			@ui.Multiline(issue.Body)
		}
		<h2>Comments</h2>
		<div id="comments">
			for _, c := range comments {
				@CommentItem(c)
			}
		</div>
		// With htmx, the form posts in the background and the new comment
		// is added to the list; without JavaScript, it posts as usual.
		@ui.Card("") {
			@ui.Form(web.MustURL(ctx, "comments.create", issue.ID), "POST", templ.Attributes{
				"hx-post":              web.MustURL(ctx, "comments.create", issue.ID),
				"hx-target":            "#comments",
				"hx-swap":              "beforeend",
				"hx-on::after-request": "if (event.detail.successful) this.reset()",
			}) {
				@ui.Field("body", "Add a comment", "") {
					@ui.Textarea("body", view.Old(ctx, "body"), templ.Attributes{"rows": "3", "required": true})
				}
				@ui.Button(ui.Primary, nil) {
					Comment
				}
			}
		}
	}
}

// CommentItem is a comment: in the list, and what htmx adds to it.
templ CommentItem(c models.Comment) {
	<article>
		@ui.Card("") {
			<strong>{ c.Author.Name }</strong>
			<div>
				@ui.Multiline(c.Body)
			</div>
		}
	</article>
}
```

(Copied from [`examples/tutorial/views/issue_page.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/issue_page.templ), region `page`.)

`ui.InlineForm` keeps the status form's hidden field and button on one
line, beside Edit. The comment form works without JavaScript. With
htmx, which the layout loads (`ui.Form` takes its attributes),
`hx-post` sends it in the background, `hx-target` and `hx-swap`
add the answer to the list, and the form clears. The CSRF token goes
along in a header the layout sets. If the server refuses a comment (a
422 for a failed validation), htmx leaves the page as it is: the
textarea's `required` stops the common case, an empty comment, in the
browser.

## The routes

In `routes/auth.go`, below the routes of part 3:

```go
loggedIn.Get("/issues/{id}", web.H(issues.Show)).Name("issues.show")
loggedIn.Post("/issues/{id}/comments", web.H(issues.Comment)).Name("comments.create")
loggedIn.Post("/issues/{id}/status", web.H(issues.SetStatus)).Name("issues.status")
```

(Copied from [`examples/tutorial/routes/auth.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/routes/auth.go), region `routes-issue-page`.)

Open an issue from the list, comment on it, close it.

## Test it

A factory for issues, in `database/factories/factories.go`: first these
imports, below the package line,

```go
import (
	"fmt"

	"anetos.dev/anetos/db/factory"

	"tracker/app/models"
)
```

(Copied from [`examples/tutorial/database/factories/factories.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/database/factories/factories.go), region `imports`.)

then the factory:

```go
// Issues are open issues. Set AuthorID:
//
//	factories.Issues.With(func(i *models.Issue) { i.AuthorID = u.ID })
var Issues = factory.New(func(n int) models.Issue {
	return models.Issue{Title: fmt.Sprintf("Issue %d", n), Body: "Steps to reproduce.", Status: "open"}
})
```

(Copied from [`examples/tutorial/database/factories/factories.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/database/factories/factories.go), region `issues`.)

And `issue_page_test.go`, in package `main`:

```go
import (
	"net/url"
	"testing"

	"anetos.dev/anetos/anetostest"

	"tracker/app/models"
	"tracker/database/factories"
)
```

(Copied from [`examples/tutorial/issue_page_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/issue_page_test.go), region `imports`.)

```go
func TestIssuePage(t *testing.T) {
	app := anetostest.New(t, setup)
	ada := anetostest.Create(app, factories.Users)
	issue := anetostest.Create(app, factories.Issues.With(func(i *models.Issue) { i.AuthorID = ada.ID }))
	anetostest.ActingAs(app, &ada)

	app.Get("/issues/1").AssertOK().AssertSee(issue.Title, "Close")
	app.PostForm("/issues/1/comments", url.Values{"body": {"Same on Firefox."}}).
		AssertRedirect("/issues/1").
		Follow().
		AssertSee("Same on Firefox.")

	// With htmx, the comment comes back alone, to add to the list.
	app.WithHeader("HX-Request", "true")
	app.PostForm("/issues/1/comments", url.Values{"body": {"Fixed."}}).
		AssertOK().
		AssertSee("<article>", "Fixed.").
		AssertDontSee("<html")
	app.WithHeader("HX-Request", "")

	app.PostForm("/issues/1/status", url.Values{"status": {"closed"}}).AssertRedirect("/issues/1")
	anetostest.AssertDatabaseHas[models.Issue](app, models.IssueCols.Status.Eq("closed"))
	app.Get("/issues/1").AssertSee("Reopen")
}
```

(Copied from [`examples/tutorial/issue_page_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/issue_page_test.go), region `test`.)

Next: [5. Search](https://docs.anetos.dev/getting-started/tutorial/05-search.md).


# 5. Search

Source: https://docs.anetos.dev/getting-started/tutorial/05-search/

You add a search box that finds issues by the words in their title and
description, best matches first, from a full-text index in the database.

## The index

```sh
go tool anetos make:migration add_search_to_issues_table
```

Fill in its two functions:

```go
func(s *migrate.Schema) error {
	return s.Alter("issues", func(t *migrate.Table) {
		t.SearchIndex("title", "body") // titles weigh more
	})
},
func(s *migrate.Schema) error {
	return s.Alter("issues", func(t *migrate.Table) {
		t.DropSearchIndex()
	})
},
```

(Copied from [`examples/tutorial/database/migrations/2026_10_06_142847_add_search_to_issues_table.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/database/migrations/2026_10_06_142847_add_search_to_issues_table.go), region `migration`.)

```sh
go run . migrate
```

`SearchIndex` builds what each database has: an FTS5 table on SQLite, a
`tsvector` column on PostgreSQL, a `FULLTEXT` index on MySQL. The index
follows the table's changes by itself.

## The page

Create `app/handlers/search.go`, in package `handlers`:

```go
import (
	"anetos.dev/anetos/db"
	"anetos.dev/anetos/web"

	"tracker/app/models"
	"tracker/views"
)
```

(Copied from [`examples/tutorial/app/handlers/search.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/handlers/search.go), region `imports`.)

```go
// SearchInput is the search box: GET /search?q=words.
type SearchInput struct {
	Q string `query:"q" validate:"max:200"`
}

// Search finds the issues whose title or description has the words,
// best matches first.
func (Issues) Search(c *web.Ctx, in SearchInput) (web.Responder, error) {
	var found []models.Issue
	if in.Q != "" {
		var err error
		found, err = db.Query[models.Issue](c).With(models.IssueRels.Author).Search(in.Q).Limit(50).Get()
		if err != nil {
			return nil, err
		}
	}
	return web.Render(views.SearchPage(in.Q, found)), nil
}
```

(Copied from [`examples/tutorial/app/handlers/search.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/handlers/search.go), region `search`.)

`Search` keeps the rows that have every word (as a word or the start of
one: `pay` finds `payment`), and orders them by how well they match.

And `views/search.templ`, in package `views`:

```templ
import (
	"fmt"

	"anetos.dev/anetos/web"

	"tracker/app/models"
	"tracker/views/ui"
)
```

(Copied from [`examples/tutorial/views/search.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/search.templ), region `imports`.)

```templ
// SearchPage shows the issues that match q.
templ SearchPage(q string, found []models.Issue) {
	@Layout("Search") {
		<h1>Search</h1>
		@ui.Form(web.MustURL(ctx, "search"), "GET", templ.Attributes{"role": "search"}) {
			@ui.Cluster() {
				@ui.Input("q", "search", q, templ.Attributes{"aria-label": "Search issues"})
				@ui.Button(ui.Primary, nil) {
					Search
				}
			}
		}
		if q != "" && len(found) == 0 {
			@ui.Empty("No issues match “" + q + "”.")
		}
		if len(found) > 0 {
			@ui.Table() {
				<tbody>
					for _, issue := range found {
						<tr>
							<td>
								@statusBadge(issue.Status)
							</td>
							<td><a href={ templ.URL(fmt.Sprintf("/issues/%d", issue.ID)) }>{ issue.Title }</a></td>
							<td><small>#{ issue.ID } by { issue.Author.Name }</small></td>
						</tr>
					}
				</tbody>
			}
		}
	}
}
```

(Copied from [`examples/tutorial/views/search.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/search.templ), region `page`.)

The route, in `routes/auth.go` below the others:

```go
loggedIn.Get("/search", web.H(issues.Search)).Name("search")
```

(Copied from [`examples/tutorial/routes/auth.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/routes/auth.go), region `routes-search`.)

Last, a search box on every page. In `views/layout.templ`, add it to
the header, below the `@ui.Nav` block (before `@AccountMenu()`):

```templ
<form method="get" action={ web.URL(ctx, "search") } role="search">
	<input type="search" name="q" placeholder="Search issues" aria-label="Search issues"/>
</form>
```

(Copied from [`examples/tutorial/views/layout.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/layout.templ), region `nav-search`.)

## Test it

`search_test.go`, in package `main`:

```go
import (
	"testing"

	"anetos.dev/anetos/anetostest"

	"tracker/app/models"
	"tracker/database/factories"
)
```

(Copied from [`examples/tutorial/search_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/search_test.go), region `imports`.)

```go
func TestSearch(t *testing.T) {
	app := anetostest.New(t, setup)
	ada := anetostest.Create(app, factories.Users)
	issues := factories.Issues.With(func(i *models.Issue) { i.AuthorID = ada.ID })
	anetostest.Create(app, issues.With(func(i *models.Issue) { i.Title, i.Body = "Checkout fails", "The payment form spins." }))
	anetostest.Create(app, issues.With(func(i *models.Issue) { i.Title = "Typo in the footer" }))
	anetostest.ActingAs(app, &ada)

	app.Get("/search?q=payment").AssertOK().AssertSee("Checkout fails").AssertDontSee("Typo in the footer")
	app.Get("/search?q=zebra").AssertSee("No issues match “zebra”.")
}
```

(Copied from [`examples/tutorial/search_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/search_test.go), region `test`.)

> **Note:** On MySQL and MariaDB, full-text indexes only see committed
> rows, and each test runs in a transaction: a search test there needs
> `anetostest.WithoutTransaction()`. The tutorial's SQLite has no such
> limit.

The [search guide](https://docs.anetos.dev/guides/search/index.md) covers languages, ranking and
the other databases.

Next: [6. Email the author](https://docs.anetos.dev/getting-started/tutorial/06-email-the-author.md).


# 6. Email the author

Source: https://docs.anetos.dev/getting-started/tutorial/06-email-the-author/

When someone comments on an issue, its author gets an email. The comment
handler of part 4 already emits `CommentAdded`; you add the email and a
listener that sends it from a queue job, so a slow mail server never
slows the page down, and a failed send is retried.

## The email

Create `app/mailers/comment.go`, in package `mailers` (where
`make:auth` put the account emails):

```go
import (
	"context"

	"anetos.dev/anetos/mailer"

	"tracker/views"
)
```

(Copied from [`examples/tutorial/app/mailers/comment.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/mailers/comment.go), region `imports`.)

```go
// NewComment tells an issue's author that someone commented on it.
type NewComment struct {
	Name, Email string // the author's
	Issue       string // the issue's title
	By, Body    string // the comment's author and text
	URL         string // the issue's page
}

// Build implements mailer.Mailable.
func (m NewComment) Build(context.Context) (*mailer.Message, error) {
	return &mailer.Message{
		To:      []mailer.Address{{Address: m.Email}},
		Subject: "New comment on " + m.Issue,
		HTML:    views.NewCommentMail(m.Name, m.Issue, m.By, m.Body, m.URL),
	}, nil
}
```

(Copied from [`examples/tutorial/app/mailers/comment.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/mailers/comment.go), region `mailable`.)

And its HTML, `views/comment_mail.templ`, in the frame of the account
emails (`authMail`, from `make:auth`):

```templ
// NewCommentMail is the email about a new comment.
templ NewCommentMail(name, issue, by, body, url string) {
	@authMail() {
		<p>Hello { name },</p>
		<p>{ by } commented on “{ issue }”:</p>
		<blockquote>{ body }</blockquote>
		<p><a href={ templ.SafeURL(url) }>See the issue</a></p>
	}
}
```

(Copied from [`examples/tutorial/views/comment_mail.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/comment_mail.templ), region `mail`.)

## The listener

Create `app/listeners/comments.go`, a new package, `listeners`:

```go
import (
	"context"
	"errors"
	"fmt"

	"anetos.dev/anetos/db"
	"anetos.dev/anetos/mailer"

	"tracker/app/mailers"
	"tracker/app/models"
)
```

(Copied from [`examples/tutorial/app/listeners/comments.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/listeners/comments.go), region `imports`.)

```go
// EmailAuthor emails an issue's author about a new comment, unless they
// wrote it. It runs as a queue job (events.OnQueued), after the comment
// is committed: retried if the mail server fails.
func EmailAuthor(ctx context.Context, e models.CommentAdded) error {
	comment, err := db.Query[models.Comment](ctx).With(models.CommentRels.Author).Find(e.CommentID)
	if errors.Is(err, db.ErrNotFound) {
		return nil // deleted since
	}
	if err != nil {
		return err
	}
	issue, err := db.Query[models.Issue](ctx).With(models.IssueRels.Author).Find(comment.IssueID)
	if err != nil {
		return err
	}
	if issue.AuthorID == comment.AuthorID {
		return nil
	}
	url, err := mailer.URL(ctx, fmt.Sprintf("/issues/%d", issue.ID)) // on APP_URL
	if err != nil {
		return err
	}
	return mailer.Send(ctx, mailers.NewComment{
		Name: issue.Author.Name, Email: issue.Author.Email, Issue: issue.Title,
		By: comment.Author.Name, Body: comment.Body, URL: url,
	})
}
```

(Copied from [`examples/tutorial/app/listeners/comments.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/app/listeners/comments.go), region `listener`.)

The listener reads the comment again rather than trusting the event's
contents: it runs later, maybe after a retry. `mailer.URL` makes the
link absolute, on `APP_URL`, since an email leaves the app.

Add it in `main.go`: import `"tracker/app/listeners"`, and where
`setup` sets up the events, replace the `events.New` lines with:

```go
bus, err := events.New(app)
if err != nil {
	return nil, err
}
// The author's email about a new comment, sent by a queue worker.
if err := events.OnQueued(bus, listeners.EmailAuthor); err != nil {
	return nil, err
}
```

(Copied from [`examples/tutorial/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/main.go), region `listeners`.)

`events.OnQueued` turns each `CommentAdded` into a job, once the
comment's transaction commits. The queue's workers run it: in
development they run in the app (`QUEUE_DRIVER=database` in `.env`); in
production, in the same binary or in processes of their own (`run
--only=worker`).

## Try it

Register a second user in another browser (or a private window),
comment on the first user's issue, and look in the `anetos dev`
terminal: the email is in the log, a moment later.

## Test it

`notify_test.go`, in package `main`:

```go
import (
	"net/url"
	"testing"

	"anetos.dev/anetos/anetostest"

	"tracker/app/mailers"
	"tracker/app/models"
	"tracker/database/factories"
)
```

(Copied from [`examples/tutorial/notify_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/notify_test.go), region `imports`.)

```go
// The author gets an email when someone else comments. In tests the
// queue runs jobs at once, and emails are kept, not sent.
func TestEmailAuthor(t *testing.T) {
	app := anetostest.New(t, setup)
	ada := anetostest.Create(app, factories.Users)
	grace := anetostest.Create(app, factories.Users)
	anetostest.Create(app, factories.Issues.With(func(i *models.Issue) { i.Title, i.AuthorID = "Login fails", ada.ID }))

	anetostest.ActingAs(app, &ada)
	app.PostForm("/issues/1/comments", url.Values{"body": {"More details."}}).AssertRedirect("/issues/1")
	anetostest.AssertMailNotSent(app, func(m mailers.NewComment) bool { return true }) // her own

	anetostest.ActingAs(app, &grace)
	app.PostForm("/issues/1/comments", url.Values{"body": {"Same here."}}).AssertRedirect("/issues/1")
	anetostest.AssertMailSent(app, func(m mailers.NewComment) bool {
		return m.Email == ada.Email && m.By == grace.Name && m.URL == "http://example.test/issues/1"
	})
}
```

(Copied from [`examples/tutorial/notify_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/notify_test.go), region `test`.)

The [events](https://docs.anetos.dev/guides/events/index.md), [queues](https://docs.anetos.dev/guides/queues/index.md)
and [mail](https://docs.anetos.dev/guides/mail/index.md) guides go further: delays, retries,
SMTP and Postmark.

Next: [7. Deploy](https://docs.anetos.dev/getting-started/tutorial/07-deploy.md).


# 7. Deploy

Source: https://docs.anetos.dev/getting-started/tutorial/07-deploy/

You build the app for production: one binary with everything in it, or
a container image.

## Build it

```sh
$ go tool anetos build
built bin/tracker (linux/amd64, 19.4 MB)
```

The binary holds the migrations, the views and the files of `public/`
and `locales/`. It needs its settings, from the environment:
`deploy/production.env.example` lists them. Try it locally with
production settings and a database of its own:

```sh
export APP_ENV=production APP_DEBUG=false APP_KEY=$(go tool anetos key:generate --show | cut -d= -f2-)
export DB_NAME=/tmp/tracker.db STORAGE_ROOT=/tmp/tracker-files HTTP_ADDR=:8081
./bin/tracker migrate
./bin/tracker run
```

`APP_DEBUG=false` overrides `.env`, which the app still reads in the
project's folder. Production cookies are HTTPS-only, so logging in needs
HTTPS: put a proxy in front, as the deploy guide shows.

## Or as an image

The project has a `Dockerfile`:

```sh
docker build -t tracker .
docker run --rm --env-file production.env tracker migrate
docker run -d -p 8080:8080 --env-file production.env -v tracker-data:/data tracker
```

`production.env` is your copy of `deploy/production.env.example`, filled
in; keep it out of git. With SQLite, the database is on the `/data`
volume.

## Where to run it

[Deploy](https://docs.anetos.dev/guides/deployment/index.md) covers a server with systemd,
Docker and Docker Compose, Fly.io and Render, HTTPS, and running the
queue's workers apart from the web server as traffic grows.

## What's next

You've built an app with accounts, pages, forms, htmx, search, events, a
queue and email, with its tests. From here:

- [`examples/tracker`](https://github.com/anetos-dev/anetos/tree/main/examples/tracker) grows this app into
  a team's tool: projects with roles, labels, files, history, a daily
  digest, an admin and a JSON API.
- The [guides](https://docs.anetos.dev/guides/index.md) take one feature at a time.
- The [concepts](https://docs.anetos.dev/concepts/index.md) explain how Anetos works underneath.


# Your first API

Source: https://docs.anetos.dev/getting-started/your-first-api/

- [Tutorial: build an API](https://docs.anetos.dev/getting-started/build-an-api/index.md): Build a JSON API for bookmarks: people sign up, get a token, and save links that only they see; a token made for a script can read them but not change them; and the API describes itself in OpenAPI for the apps that call it. About thirty minutes. The finished project is [`examples/bookmarks`](https://github.com/anetos-dev/anetos/tree/main/examples/bookmarks).


# Tutorial: build an API

Source: https://docs.anetos.dev/getting-started/build-an-api/

Build a JSON API for bookmarks: people sign up, get a token, and save
links that only they see; a token made for a script can read them but
not change them; and the API describes itself in OpenAPI for the apps
that call it. About thirty minutes. The finished project is
[`examples/bookmarks`](https://github.com/anetos-dev/anetos/tree/main/examples/bookmarks).

You need [Go and the `anetos` tool](https://docs.anetos.dev/getting-started/install/index.md). The
[issue tracker tutorial](https://docs.anetos.dev/getting-started/tutorial/index.md) builds an app with pages;
this one has none.

## 1. Create the project

```sh
anetos new bookmarks --stack=api
cd bookmarks
go run . migrate
go tool anetos dev
```

`--stack=api` writes an app that serves JSON only: no views, sessions
or CSRF protection, every error as JSON problem details, the routes
under `/api/v1` in `routes/api.go`. In another terminal:

```sh
curl http://localhost:8080/api/v1
```

```json
{"name":"bookmarks","message":"Welcome to the Bookmarks API."}
```

The project also has `openapi.json`, the API's description, which the
app serves at `/api/v1/openapi.json`. It grows with each step.
[Create a project](https://docs.anetos.dev/getting-started/create-a-project/index.md#an-api-instead) lists the files.

## 2. Accounts and tokens

```sh
go tool anetos make:auth
go run . migrate
```

`make:auth` writes registration, login, logout, email verification,
password reset, two-factor authentication and token management, as JSON
endpoints that log in with API tokens. Sign up:

```sh
curl -X POST http://localhost:8080/api/v1/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","email":"ada@example.com","password":"correct horse","password_confirmation":"correct horse"}'
```

The answer has a `token`. Send it with every request:

```sh
curl http://localhost:8080/api/v1/me -H 'Authorization: Bearer 1|q7Xw…'
```

The emails (verification, password reset) go to the log in
development, and link to your client app at `AUTH_CLIENT_URL`.
[Add accounts to an API](https://docs.anetos.dev/guides/api-accounts/index.md) lists every
endpoint.

## 3. Bookmarks

```sh
go tool anetos make:crud Bookmark url:string title:string notes:text:optional archived:bool
go run . migrate
```

`make:crud` writes the model and its migration, five endpoints in
`app/handlers/bookmarks.go` (`GET` and `POST /api/v1/bookmarks`, `GET`,
`PUT` and `DELETE /api/v1/bookmarks/{id}`), their routes in
`routes/bookmarks.go`, and a test. The list is paged, sorted with
`?sort=` and filtered by field (`?archived=true`); each bookmark is
answered as `BookmarkResponse`, a struct of the handlers' file, never
the model. [Add pages for a model](https://docs.anetos.dev/getting-started/crud/index.md#in-an-api-project) has the
details.

The endpoints are open to every client, and every bookmark is
everyone's. The next steps change that.

## 4. Each user's bookmarks

A bookmark belongs to the user who saved it: it needs a `user_id`
column. Undo the bookmarks' migration (`go run . migrate:rollback`
drops the table, with any bookmark you saved), and add the column to
it, after `t.ID()`:

```go
t.ForeignID("user_id").Constrained().CascadeOnDelete() // whose bookmark
```

(Copied from [`examples/bookmarks/database/migrations/2026_10_08_140750_create_bookmarks_table.go`](https://github.com/anetos-dev/anetos/blob/main/examples/bookmarks/database/migrations/2026_10_08_140750_create_bookmarks_table.go), region `user-id`.)

and the field to the model, `app/models/bookmark.go`:

```go
// Bookmark is a row of the bookmarks table (anetos make:crud). `go tool anetos
// gen` writes its typed columns (BookmarkCols) to models_gen.go.
type Bookmark struct {
	db.Model        // id, created_at, updated_at
	UserID   int64  `db:"user_id"` // whose bookmark
	URL      string `db:"url"`
	Title    string `db:"title"`
	Notes    string `db:"notes"`
	Archived bool   `db:"archived"`
}
```

(Copied from [`examples/bookmarks/app/models/bookmark.go`](https://github.com/anetos-dev/anetos/blob/main/examples/bookmarks/app/models/bookmark.go), region `model`.)

Then `go tool anetos generate` (the typed column `BookmarkCols.UserID`) and
`go run . migrate` again.

In `app/handlers/bookmarks.go`, two helpers (import
`anetos.dev/anetos/auth`): the logged-in user, and a bookmark of
theirs:

```go
// owner is the logged-in user's ID: a request sees their bookmarks only.
func owner(c *web.Ctx) (int64, error) {
	u, err := auth.Current[*models.User](c)
	if err != nil {
		return 0, err
	}
	return u.ID, nil
}

// find returns the user's bookmark id. Another user's is a 404, like
// one that doesn't exist (db.ErrNotFound): it isn't theirs to know of.
func find(c *web.Ctx, id int64) (models.Bookmark, error) {
	userID, err := owner(c)
	if err != nil {
		return models.Bookmark{}, err
	}
	return db.Query[models.Bookmark](c).Where(models.BookmarkCols.UserID.Eq(userID)).Find(id)
}
```

(Copied from [`examples/bookmarks/app/handlers/bookmarks.go`](https://github.com/anetos-dev/anetos/blob/main/examples/bookmarks/app/handlers/bookmarks.go), region `owner`.)

`Index` lists the user's bookmarks only; its query starts with:

```go
userID, err := owner(c)
if err != nil {
	return db.Page[BookmarkResponse]{}, err
}
q := db.Query[models.Bookmark](c).Where(models.BookmarkCols.UserID.Eq(userID))
```

(Copied from [`examples/bookmarks/app/handlers/bookmarks.go`](https://github.com/anetos-dev/anetos/blob/main/examples/bookmarks/app/handlers/bookmarks.go), region `index`.)

`Create` gives the new bookmark its owner:

```go
userID, err := owner(c)
if err != nil {
	return BookmarkResponse{}, err
}
row := models.Bookmark{UserID: userID}
```

(Copied from [`examples/bookmarks/app/handlers/bookmarks.go`](https://github.com/anetos-dev/anetos/blob/main/examples/bookmarks/app/handlers/bookmarks.go), region `create`.)

and `Show`, `Update` and `Delete` load the row with `find(c, in.ID)`
in place of `db.Find[models.Bookmark](c, in.ID)`. While you're in the
file, check that links are links: the input's `url` field gets the
`url` rule, `validate:"required|url|max:255"`.

Last, only logged-in clients may reach the bookmarks. Remove the
`Bookmarks(api)` line from `routes/api.go`, and call it from
`routes/auth.go`, in the group whose routes need a token:

```go
Bookmarks(loggedIn) // the user's bookmarks, with their token
```

(Copied from [`examples/bookmarks/routes/auth.go`](https://github.com/anetos-dev/anetos/blob/main/examples/bookmarks/routes/auth.go), region `logged-in`.)

A request without a token now gets 401, and Ada's bookmarks are hers
alone: Bob gets a 404 for them, as for a bookmark that doesn't exist,
so he can't even learn which IDs are taken.

## 5. An action of your own

Archiving a bookmark is one request with nothing to answer. The
handler returns `web.Empty`, which answers 204:

```go
// Archive marks a bookmark archived: 204, nothing to answer.
func (Bookmarks) Archive(c *web.Ctx, in BookmarkID) (web.Empty, error) {
	row, err := find(c, in.ID)
	if err != nil {
		return web.Empty{}, err
	}
	row.Archived = true
	return web.Empty{}, db.Update(c, &row)
}
```

(Copied from [`examples/bookmarks/app/handlers/bookmarks.go`](https://github.com/anetos-dev/anetos/blob/main/examples/bookmarks/app/handlers/bookmarks.go), region `archive`.)

Route it in `routes/bookmarks.go`, after the other routes:

```go
// illustrative
r.Post("/bookmarks/{id}/archive", web.H(h.Archive)).Name("bookmarks.archive")
```

`web.H` binds `{id}` into `BookmarkID` (a bad one is a 400). A
handler's signature and its route say what the request takes and
answers, which is what the API's description is made from.

## 6. Tokens for scripts

A login's token may do everything (its ability is `*`). A script that
only backs the bookmarks up shouldn't be able to delete them: give it a
token that can only read. Require abilities on the routes,
`routes/bookmarks.go` becoming (with `anetos.dev/anetos/auth` among its
imports):

```go
// Bookmarks adds the bookmarks API: routes/auth.go calls it with its me
// group, so every request has a token. Reading needs the token's
// bookmarks:read ability, changing bookmarks bookmarks:write; a login's
// token has every ability.
func Bookmarks(r *web.Router) {
	var h handlers.Bookmarks
	read := r.With(auth.RequireAbilities("bookmarks:read"))
	write := r.With(auth.RequireAbilities("bookmarks:write"))
	read.Get("/bookmarks", web.H(h.Index)).Name("bookmarks.index")
	write.Post("/bookmarks", web.H(h.Create)).Name("bookmarks.create").Status(http.StatusCreated)
	read.Get("/bookmarks/{id}", web.H(h.Show)).Name("bookmarks.show")
	write.Put("/bookmarks/{id}", web.H(h.Update)).Name("bookmarks.update")
	write.Delete("/bookmarks/{id}", web.H(h.Delete)).Name("bookmarks.delete")
	write.Post("/bookmarks/{id}/archive", web.H(h.Archive)).Name("bookmarks.archive")
}
```

(Copied from [`examples/bookmarks/routes/bookmarks.go`](https://github.com/anetos-dev/anetos/blob/main/examples/bookmarks/routes/bookmarks.go), region `routes`.)

The user makes the script's token with their password:

```sh
curl -X POST http://localhost:8080/api/v1/tokens -H 'Authorization: Bearer 1|q7Xw…' \
  -H 'Content-Type: application/json' \
  -d '{"name":"backup","abilities":["bookmarks:read"],"password":"correct horse"}'
```

With that token, `GET /api/v1/bookmarks` works, and `POST`, `PUT`,
`DELETE` and the archive answer 403.

## 7. Test it

`make:crud`'s test, `bookmarks_test.go`, calls the endpoints without a
token, and saves `"Example url"`, which the `url` rule now refuses.
Replace its `TestBookmarks` with one that signs up first
(`auth_test.go`'s `authRegister` signs Ada up and sends her token with
the requests that follow):

```go
// TestBookmarks creates, lists, shows, replaces, archives and deletes a
// bookmark through the API, with a login's token (auth_test.go's
// authRegister).
func TestBookmarks(t *testing.T) {
	app, _ := authRegister(t)
	app.GetJSON("/api/v1/bookmarks").AssertOK().AssertJSONPath("total", 0).AssertJSONPath("data", []any{})
	app.PostJSON("/api/v1/bookmarks", map[string]any{}).AssertValidationErrors("url", "title")
	app.PostJSON("/api/v1/bookmarks", map[string]any{"url": "not a link", "title": "x"}).AssertValidationErrors("url")

	body := map[string]any{"url": "https://go.dev/doc/effective_go", "title": "Effective Go", "notes": "Read again"}
	var created handlers.BookmarkResponse
	res := app.PostJSON("/api/v1/bookmarks", body).AssertCreated().JSON(&created)
	path := fmt.Sprintf("/api/v1/bookmarks/%d", created.ID)
	res.AssertHeader("Location", path).AssertJSONPath("title", "Effective Go").AssertJSONPath("archived", false)

	app.GetJSON(path).AssertOK().AssertJSONPath("id", created.ID)
	app.GetJSON("/api/v1/bookmarks?sort=title").AssertOK().AssertJSONPath("total", 1).AssertJSONPath("data.0.id", created.ID)
	app.GetJSON("/api/v1/bookmarks?sort=nonsense").AssertValidationErrors("sort")
	app.PutJSON(path, map[string]any{"url": "https://go.dev/doc/effective_go", "title": "Effective Go, again"}).
		AssertOK().AssertJSONPath("title", "Effective Go, again").AssertJSONPath("notes", "")

	// Archiving answers 204; the list filters on it.
	app.PostJSON(path+"/archive", nil).AssertNoContent()
	app.GetJSON("/api/v1/bookmarks?archived=true").AssertOK().AssertJSONPath("total", 1)
	app.GetJSON("/api/v1/bookmarks?archived=false").AssertOK().AssertJSONPath("total", 0)

	app.DeleteJSON(path).AssertNoContent()
	app.GetJSON(path).AssertNotFound()
	app.DeleteJSON(path).AssertStatus(http.StatusNotFound)
}
```

(Copied from [`examples/bookmarks/bookmarks_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/bookmarks/bookmarks_test.go), region `test-crud`.)

Add a test that one user doesn't see another's bookmarks:

```go
// A user sees their own bookmarks only: another's is a 404.
func TestBookmarksAreTheUsers(t *testing.T) {
	app, _ := authRegister(t)
	var ada handlers.BookmarkResponse
	app.PostJSON("/api/v1/bookmarks", map[string]any{"url": "https://ada.example.com", "title": "Ada's"}).
		AssertCreated().JSON(&ada)

	var bob handlers.LoginResponse
	app.PostJSON("/api/v1/register", map[string]any{
		"name": "Bob", "email": "bob@example.com", "password": "correct horse", "password_confirmation": "correct horse",
	}).AssertCreated().JSON(&bob)
	app.WithHeader("Authorization", "Bearer "+bob.Token)
	app.GetJSON("/api/v1/bookmarks").AssertOK().AssertJSONPath("total", 0)
	path := fmt.Sprintf("/api/v1/bookmarks/%d", ada.ID)
	app.GetJSON(path).AssertNotFound()
	app.PutJSON(path, map[string]any{"url": "https://bob.example.com", "title": "Bob's"}).AssertNotFound()
	app.PostJSON(path+"/archive", nil).AssertNotFound()
	app.DeleteJSON(path).AssertNotFound()
}
```

(Copied from [`examples/bookmarks/bookmarks_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/bookmarks/bookmarks_test.go), region `test-owner`.)

and that a reading token can't change them:

```go
// A token made for reading reads, and can't change bookmarks: 403.
// Without a token, 401.
func TestBookmarkAbilities(t *testing.T) {
	app, _ := authRegister(t)
	var mine handlers.BookmarkResponse
	app.PostJSON("/api/v1/bookmarks", map[string]any{"url": "https://go.dev", "title": "Go"}).AssertCreated().JSON(&mine)
	path := fmt.Sprintf("/api/v1/bookmarks/%d", mine.ID)
	var reader handlers.NewTokenResponse
	app.PostJSON("/api/v1/tokens", map[string]any{
		"name": "reader", "abilities": []string{"bookmarks:read"}, "password": "correct horse",
	}).AssertCreated().JSON(&reader)

	app.WithHeader("Authorization", "Bearer "+reader.Token)
	app.GetJSON("/api/v1/bookmarks").AssertOK()
	app.GetJSON(path).AssertOK()
	app.PostJSON("/api/v1/bookmarks", map[string]any{"url": "https://go.dev", "title": "Go"}).AssertForbidden()
	app.PutJSON(path, map[string]any{"url": "https://go.dev", "title": "Go!"}).AssertForbidden()
	app.PostJSON(path+"/archive", nil).AssertForbidden()
	app.DeleteJSON(path).AssertForbidden()

	app.WithHeader("Authorization", "")
	app.GetJSON("/api/v1/bookmarks").AssertStatus(http.StatusUnauthorized)
}
```

(Copied from [`examples/bookmarks/bookmarks_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/bookmarks/bookmarks_test.go), region `test-abilities`.)

Run them:

```sh
go test ./...
```

One test fails until the next step: `TestOpenAPI`, which checks that
`openapi.json` describes the routes as they are now.

## 8. The API's description

```sh
go run . openapi
```

`openapi.json` now has the archive operation, the `url` field's
`format: uri`, and on every bookmark operation the token it needs:

```json
"security": [
  {
    "bearer": [
      "bookmarks:write"
    ]
  }
]
```

with the 401 and 403 those routes may answer. Commit it with the code:
its diff shows reviewers how a change alters the API, and client
developers load it (from the file, or from `/api/v1/openapi.json`)
into an OpenAPI viewer or a client generator.
[Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md) explains what goes
in it.

## 9. Ship it

- **Browsers on other origins** (a front end at
  `https://app.example.com`) may call the API once `HTTP_CORS_ORIGINS`
  lists them.
- **The client app's address**, `AUTH_CLIENT_URL`, is where emails link
  to; production refuses to start without it.
- **Build and deploy** as any Anetos app: `go tool anetos build`, the
  `Dockerfile` or the systemd unit in `deploy/`
  ([Deploy](https://docs.anetos.dev/guides/deployment/index.md)).

## Next steps

- [Add accounts to an API](https://docs.anetos.dev/guides/api-accounts/index.md): every account
  endpoint, two-factor authentication, throttling.
- [Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md) and its
  [reference](https://docs.anetos.dev/reference/openapi/index.md).
- [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md): what
  users may do, with tokens' abilities as a ceiling.
- [Rate limiting](https://docs.anetos.dev/guides/rate-limiting/index.md).


# Guides

Source: https://docs.anetos.dev/guides/

How to do one thing, step by step.


## Basics

- [Routing](https://docs.anetos.dev/guides/routing/index.md): Map URLs to handlers, group routes under shared prefixes and middleware, name them, and generate URLs from names.
- [Handlers and requests](https://docs.anetos.dev/guides/handlers/index.md): Write handlers that receive typed input, return typed output, and turn errors into proper HTTP responses.
- [Render HTML with templ](https://docs.anetos.dev/guides/views/index.md): Write pages as [templ](https://templ.guide) components (typed, compiled, escaped by default), share a layout, link to routes by name, serve static files with cache-busting URLs, and add interactivity with the bundled htmx.
- [Style your app](https://docs.anetos.dev/guides/styling/index.md): A new project looks finished from the first page. Its pages are made of components in `views/ui`, a package of your app, styled by one stylesheet, `public/static/app.css`. Change the colors, change a component, add your own, start with Pico, Bootstrap or Bulma, or start without styles.
- [Handle HTML forms](https://docs.anetos.dev/guides/forms/index.md): Protect forms against cross-site request forgery, send PUT and DELETE from plain HTML, and show validation errors next to the fields with the submitted values kept.
- [Validation](https://docs.anetos.dev/guides/validation/index.md): Declare rules on an input struct, get one clear message per field, and add checks of your own.
- [Sessions and flash messages](https://docs.anetos.dev/guides/sessions/index.md): Remember things about a visitor between requests, and show a message once after a redirect.
- [Configure your application](https://docs.anetos.dev/guides/configuration/index.md): Read settings from `.env` files and the environment into typed Go structs, with defaults, required keys and validation.
- [Commands](https://docs.anetos.dev/guides/commands/index.md): Your application builds to one binary. Its first argument picks what it does: run the app (the default), run only some process types, migrate the database, list the routes, or run commands of your own.
- [Test your app](https://docs.anetos.dev/guides/testing/index.md): Boot the app in a test, send it requests like a browser or an API client, and check the responses, the session, the database, the jobs, events and email the app sent, and its files, with `anetostest`; freeze or move the app's clock.
- [Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md): Package `web/openapi` writes an OpenAPI 3.1 document of your API from its routes and its typed handlers: what each operation reads and answers, which credentials it needs and how it fails. You commit the document (`openapi.json`) beside the code, a test fails when it's out of date, and the app serves it for clients and tools.

## CSS frameworks

- [The starter theme](https://docs.anetos.dev/guides/starter-theme/index.md): The starter theme (`--css=anetos`), which `anetos new` writes unless you pick a CSS framework: Anetos's own stylesheet, about 270 lines of plain CSS, with no framework and no build step.
- [Start without styles](https://docs.anetos.dev/guides/plain-html/index.md): `--css=none`: the same components, writing plain HTML without classes, and an `app.css` that holds only a comment. For your own CSS, or a CSS framework anetos doesn't cover.
- [Style with Pico](https://docs.anetos.dev/guides/pico/index.md): `--css=pico`: [Pico CSS](https://picocss.com) 2.1.1, a framework that styles plain HTML, so its components write few classes. No build step and no JavaScript.
- [Style with Bootstrap](https://docs.anetos.dev/guides/bootstrap/index.md): `--css=bootstrap`: [Bootstrap](https://getbootstrap.com) 5.3.8's classes, its stylesheet and its JavaScript bundle, as released. No build step.
- [Style with Bulma](https://docs.anetos.dev/guides/bulma/index.md): `--css=bulma`: [Bulma](https://bulma.io) 1.0.4's classes and its stylesheet, as released, with a small script for the menu button. No build step.
- [Style with Tailwind CSS](https://docs.anetos.dev/guides/tailwind/index.md): `--css=tailwind`: components with [Tailwind CSS](https://tailwindcss.com) 4.3.3's utility classes, and a stylesheet that Tailwind compiles from them. `anetos dev` and `anetos build` run Tailwind's standalone CLI for you: no Node.js.

## Data

- [Connect to a database](https://docs.anetos.dev/guides/database/index.md): Open your app's database from configuration and use it from handlers, jobs and background tasks.
- [Define models and save data](https://docs.anetos.dev/guides/models/index.md): Map structs to tables, and create, update and delete rows with timestamps, soft deletes and hooks.
- [Migrations](https://docs.anetos.dev/guides/migrations/index.md): Create and change your database tables with versioned migrations that are compiled into your app and run with one command.
- [Query data](https://docs.anetos.dev/guides/queries/index.md): Find rows with typed conditions, sort and paginate them, aggregate, and update or delete in bulk.
- [Relations and eager loading](https://docs.anetos.dev/guides/relations/index.md): Declare how models relate (a post belongs to an author, an author has many posts, posts have many tags), load related rows in one query per relation, and filter rows by what they relate to.
- [Transactions](https://docs.anetos.dev/guides/transactions/index.md): Make several writes succeed or fail together, and run follow-up work only after they are saved.
- [Raw SQL](https://docs.anetos.dev/guides/raw-sql/index.md): Write SQL yourself and scan the results into structs, when the query builder is in the way.
- [Seed the database](https://docs.anetos.dev/guides/seeders/index.md): Fill a database with sample data for development, or with the reference data every environment needs.
- [Generate typed columns](https://docs.anetos.dev/guides/code-generation/index.md): Let `anetos generate` declare a typed column for every field of your models, and a handle for every relation, so queries say `PostCols.Title.Like("%go%")` and `With(PostRels.Author)`, and the compiler checks the column name, the value's type and the relation's model.

## Accounts and security

- [Add accounts with make:auth](https://docs.anetos.dev/guides/accounts/index.md): Give your app user accounts in one command: registration, login with "remember me" and throttling, login with Google and GitHub, two-factor authentication, account settings, logout, email verification, password reset and API tokens, with their pages, emails, routes, migration and tests. The code is written into your app, where you change it as you like; the parts that must be right (password hashing, tokens, sessions, throttling, the OAuth flow) stay in the [`auth`](https://docs.anetos.dev/guides/authentication/index.md) and [`social`](https://docs.anetos.dev/guides/social-login/index.md) packages, so fixes reach you with `go get -u`.
- [Add accounts to an API](https://docs.anetos.dev/guides/api-accounts/index.md): In a project made with `anetos new --stack=api`, `make:auth` writes accounts that log in with API tokens: registration, login (with two-factor codes for users who turn them on), logout, email verification, password reset and change, and token management, as JSON endpoints under `/api/v1`. There are no sessions or cookies: a client keeps its token and sends it in every request.
- [Authentication](https://docs.anetos.dev/guides/authentication/index.md): Let people register, log in (with "remember me"), log out, verify their email address and reset a forgotten password, and give API clients tokens. The complete app is [`examples/auth`](https://github.com/anetos-dev/anetos/tree/main/examples/auth). In an `anetos new` project, `go tool anetos make:auth` writes all of this into your app: see [Add accounts with make:auth](https://docs.anetos.dev/guides/accounts/index.md). This guide is the `auth` package underneath, step by step.
- [Social login](https://docs.anetos.dev/guides/social-login/index.md): Let users log in with Google, GitHub, or any OpenID Connect provider (Okta, Auth0, Microsoft Entra ID, Keycloak, GitLab…). The complete app is [`examples/auth`](https://github.com/anetos-dev/anetos/tree/main/examples/auth).
- [Two-factor authentication and password confirmation](https://docs.anetos.dev/guides/two-factor/index.md): Ask for more than a password: a code from an authenticator app (Google Authenticator, 1Password, Authy… : TOTP, RFC 6238) after it, with recovery codes for a lost phone; and the password again before sensitive pages. Package `auth` does the parts that must be right (secrets encrypted, codes used once, throttling); your handlers and pages call it. The complete app is [`examples/auth`](https://github.com/anetos-dev/anetos/tree/main/examples/auth).
- [Authorization](https://docs.anetos.dev/guides/authorization/index.md): Decide what a logged-in user may do, with policies the compiler checks.
- [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md): Give users roles, globally or in a team, and check what they may do, with package `auth/rbac`.
- [Rate limiting](https://docs.anetos.dev/guides/rate-limiting/index.md): Limit how often clients can call your routes, and how often they can attempt actions such as logging in.
- [Keep an audit log](https://docs.anetos.dev/guides/audit-log/index.md): Record who created, changed, deleted and restored the rows of your models, field by field, with package `audit`: for data governance, for support, and for "who changed this?".
- [Add an admin panel](https://docs.anetos.dev/guides/admin/index.md): Give your staff pages to list, search, filter, create, edit and delete the app's records, and to manage users and roles, with the admin interface of module `anetos.dev/anetos/admin`: no front-end build, permissions from [roles](https://docs.anetos.dev/guides/roles-and-permissions/index.md), and every change in the [audit log](https://docs.anetos.dev/guides/audit-log/index.md) for the models it tracks.

## Background work

- [Queues](https://docs.anetos.dev/guides/queues/index.md): Run slow or failure-prone work in the background: charge a card, send an email, build a report. A request dispatches a **job**, a typed struct, and responds at once. **Workers** run the job later, retry it when it fails, and keep a record of the jobs that failed for good. The complete app is [`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue).
- [Events](https://docs.anetos.dev/guides/events/index.md): Emit an event when something happens, and let listeners react: write an audit log, email a receipt, update a dashboard. The code that places an order then doesn't need to know about all of them. Events are typed Go values, and listeners are functions of their type. The complete app is [`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue).
- [Scheduling](https://docs.anetos.dev/guides/scheduling/index.md): Run tasks on a schedule: prune old rows every night, send a report every hour, sync with another service every five minutes. The scheduler runs in your app's binary, as a supervised component, so there is no crontab to install and nothing to run every minute. The complete app is [`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue).
- [Run background tasks](https://docs.anetos.dev/guides/background-tasks/index.md): Run long-lived work, such as a poller, a cache warmer or a heartbeat, as a supervised goroutine that restarts on failure and stops cleanly on deploy.
- [Pub/sub listeners](https://docs.anetos.dev/guides/pubsub/index.md): Listen to message streams other services publish, such as `orders.created`, and publish your own, from the same binary as your web app. Where the [queue](https://docs.anetos.dev/guides/queues/index.md) runs an app's own jobs, pub/sub connects services: each subscription gets every message of a topic. The complete app is [`examples/pubsub`](https://github.com/anetos-dev/anetos/tree/main/examples/pubsub), a billing service.

## Mail, files, search and cache

- [Send email](https://docs.anetos.dev/guides/mail/index.md): Send email from your app: a receipt, a welcome message, a password reset link. An email is a **mailable**, a type that builds its message from its fields, with an HTML body from a templ component. Send it now, or queue it so a worker sends it with retries. The complete app is [`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue), which emails a receipt for each order.
- [Store files](https://docs.anetos.dev/guides/storage/index.md): Store files your app receives or makes: uploads, avatars, exports, invoices. Files go on **disks**: a disk is a named place files are kept, which is a local directory by default, or an S3-compatible bucket (Amazon S3, Cloudflare R2, MinIO, …) or a Google Cloud Storage bucket, with the same code. Private files are read through temporary signed URLs. The complete app is [`examples/files`](https://github.com/anetos-dev/anetos/tree/main/examples/files).
- [Add full-text search](https://docs.anetos.dev/guides/search/index.md): Give users a search box that finds what they mean: every word they type, in any of the columns you choose, best matches first. Search runs on your database's own full-text engine (PostgreSQL, MySQL/MariaDB or SQLite), with an index built by a migration; there's no search server to run. The complete example is [`examples/forms`](https://github.com/anetos-dev/anetos/tree/main/examples/forms), a notes app with a search box.
- [Cache](https://docs.anetos.dev/guides/cache/index.md): Keep the results of slow work for a while, count events for rate limits, and use locks so only one instance of the app does a job at a time.

## Languages and time

- [Translations](https://docs.anetos.dev/guides/translations/index.md): Show your app, its validation messages and error pages, and its emails in each user's language. Adding a language is adding a file.
- [Numbers, dates and languages](https://docs.anetos.dev/guides/formatting/index.md): Show numbers, prices, dates and times the way each user reads them, in their language and time zone, and add the framework's translations for a language with one command.
- [Times and dates](https://docs.anetos.dev/guides/times-and-dates/index.md): Store times without thinking about time zones, keep calendar dates on their day, and choose the zone your app works in.

## Working with AI

- [Add AI to your app](https://docs.anetos.dev/guides/ai/index.md): Use a language model in your app: summarize text into a typed struct, answer questions with tools that look up the user's own data, and stream the answer as it's written. Package `ai` does the work around the model: schemas, validation, the tool loop, logging and tests that never call a model. The complete example is [`examples/ai`](https://github.com/anetos-dev/anetos/tree/main/examples/ai), a small support desk API.
- [Build an AI assistant](https://docs.anetos.dev/guides/ai-assistant/index.md): Give your users a chat with an agent that answers from your app's data: conversations stored in the database, answers streamed to the page as they're written, slow questions answered in the background, and a usage budget per user.
- [Search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md): Find records by what they mean, not only by the words they share: "how much is the team plan" finds the article on plans and billing, which never says "how much". Each record's text is split into chunks, turned into vectors (embeddings) by an embedding model, and stored next to the record; a search embeds the question and returns the nearest records, with the passage that matched. With a full-text index too, the search is *hybrid*: records that its words find rank high as well, so names, codes and rare words aren't missed. An agent can use the search as a tool, to answer from your data (retrieval-augmented generation).

## Production

- [Deploy](https://docs.anetos.dev/guides/deployment/index.md): An Anetos app is one binary: the migrations, views, translations and static files are inside it. Deploying it is building it, giving it its settings, running its migrations, and keeping it running. This guide does that on a server with systemd, in a container, and on two hosting platforms (Fly.io, Render). The examples use an app called `blog`.
- [Find N+1 queries](https://docs.anetos.dev/guides/n-plus-one/index.md): An N+1 is a query in a loop: one query for a list of posts, then one per post for its author. It works, and it's fast with three posts in development; with three hundred in production, it isn't. Anetos warns when a request (or a job, a listener, a scheduled task) runs the same query many times, and says where, so you can load the rows in one query instead. The complete example is [`examples/database`](https://github.com/anetos-dev/anetos/tree/main/examples/database).
- [Secure your app](https://docs.anetos.dev/guides/security/index.md): Anetos starts safe: CSRF protection, encrypted session cookies, parameterized queries, escaped views, security headers, throttled logins. What it can't choose for you are the settings and the deployment: a key, HTTPS, the proxies to trust, the database's connection. This guide is the checklist before you go live, with `doctor` to check what a machine can check.
- [Check your app's security](https://docs.anetos.dev/guides/security-check/index.md): `security:check` checks your app against security rules: its code (SQL built from request data, a redirect to a URL from the request, a secret written in a file), its dependencies (known vulnerabilities, with govulncheck), its routes (a form's route without CSRF protection, an admin page anyone can open) and its settings (session cookies sent over plain HTTP, mail in plain text). Each finding says where it is (a line of your code, or a setting), why it matters and how to fix it. The report comes as text, JSON, SARIF (for GitHub's code scanning) or Markdown.

## Extending

- [Use plugins](https://docs.anetos.dev/guides/plugins/index.md): Add features to your app with plugins: packages that bring their own routes, database tables, settings, commands, queue jobs, scheduled tasks or event listeners. `anetos add` installs one with one command. The complete app is [`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue), which uses the Postmark plugin to stop emailing addresses that bounced.
- [Write a plugin](https://docs.anetos.dev/guides/writing-plugins/index.md): Package a feature so any Anetos app can add it with `anetos add`: its routes, tables, settings, commands, queue jobs, scheduled tasks and event listeners. A plugin uses only the framework's public packages, as an app does. The complete plugin is [`plugins/postmark`](https://github.com/anetos-dev/anetos/tree/main/plugins/postmark), which receives Postmark's webhooks and keeps a list of the addresses Postmark stopped sending to.


# Basics

Source: https://docs.anetos.dev/guides/basics/

- [Routing](https://docs.anetos.dev/guides/routing/index.md): Map URLs to handlers, group routes under shared prefixes and middleware, name them, and generate URLs from names.
- [Handlers and requests](https://docs.anetos.dev/guides/handlers/index.md): Write handlers that receive typed input, return typed output, and turn errors into proper HTTP responses.
- [Render HTML with templ](https://docs.anetos.dev/guides/views/index.md): Write pages as [templ](https://templ.guide) components (typed, compiled, escaped by default), share a layout, link to routes by name, serve static files with cache-busting URLs, and add interactivity with the bundled htmx.
- [Style your app](https://docs.anetos.dev/guides/styling/index.md): A new project looks finished from the first page. Its pages are made of components in `views/ui`, a package of your app, styled by one stylesheet, `public/static/app.css`. Change the colors, change a component, add your own, start with Pico, Bootstrap or Bulma, or start without styles.
- [Handle HTML forms](https://docs.anetos.dev/guides/forms/index.md): Protect forms against cross-site request forgery, send PUT and DELETE from plain HTML, and show validation errors next to the fields with the submitted values kept.
- [Validation](https://docs.anetos.dev/guides/validation/index.md): Declare rules on an input struct, get one clear message per field, and add checks of your own.
- [Sessions and flash messages](https://docs.anetos.dev/guides/sessions/index.md): Remember things about a visitor between requests, and show a message once after a redirect.
- [Configure your application](https://docs.anetos.dev/guides/configuration/index.md): Read settings from `.env` files and the environment into typed Go structs, with defaults, required keys and validation.
- [Commands](https://docs.anetos.dev/guides/commands/index.md): Your application builds to one binary. Its first argument picks what it does: run the app (the default), run only some process types, migrate the database, list the routes, or run commands of your own.
- [Test your app](https://docs.anetos.dev/guides/testing/index.md): Boot the app in a test, send it requests like a browser or an API client, and check the responses, the session, the database, the jobs, events and email the app sent, and its files, with `anetostest`; freeze or move the app's clock.
- [Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md): Package `web/openapi` writes an OpenAPI 3.1 document of your API from its routes and its typed handlers: what each operation reads and answers, which credentials it needs and how it fails. You commit the document (`openapi.json`) beside the code, a test fails when it's out of date, and the app serves it for clients and tools.


# Routing

Source: https://docs.anetos.dev/guides/routing/

Map URLs to handlers, group routes under shared prefixes and middleware,
name them, and generate URLs from names.

## Before you start

You have an app from `anetos.New()`. See
[Configure your application](https://docs.anetos.dev/guides/configuration/index.md).

## Steps

### 1. Create the HTTP server

```go
func run() error {
	app, err := anetos.New()
	if err != nil {
		return err
	}
	srv, err := web.NewServer(app) // reads HTTP_*, registers the "http" component
	if err != nil {
		return err
	}
	routes(srv.Router(), &Notes{})

	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()
	return app.Run(ctx)
}
```

(Copied from [`examples/notes`](https://github.com/anetos-dev/anetos/blob/main/examples/notes/main.go), region
`main`.)

`web.NewServer` reads the `HTTP_*` settings (address, timeouts, body limit,
CORS…), installs the default middleware and adds the server to the app as
the `http` component. `app.Run` starts it, and SIGTERM shuts it down
gracefully, letting in-flight requests finish.

### 2. Register routes

```go
func routes(r *web.Router, notes *Notes) {
	r.Get("/", func(c *web.Ctx) error {
		return c.RedirectRoute("notes.index")
	}).Name("home")

	api := r.Group("/notes").As("notes.")
	api.Get("", web.H(notes.List)).Name("index")
	api.Post("", web.H(notes.Create)).Name("create").Status(http.StatusCreated)
	api.Get("/{id}", web.H(notes.Show)).Name("show")
	api.Delete("/{id}", web.H(notes.Delete)).Name("delete")
}
```

(Region `routes`.)

- `Get`, `Post`, `Put`, `Patch`, `Delete` and `Options` register a handler
  for one method. `GET` routes also answer `HEAD`. `Handle("", pattern, h)`
  matches every method.
- Handlers are `func(c *web.Ctx) error`, or typed handlers wrapped with
  `web.H`. See [Handlers and requests](https://docs.anetos.dev/guides/handlers/index.md).

### 3. Use path parameters

Patterns use Go's `net/http` syntax:

| Pattern | Matches | Read with |
|---|---|---|
| `/posts/{id}` | `/posts/42` | `c.Param("id")` or a `path:"id"` field |
| `/files/{path...}` | `/files/a/b.txt` (the rest of the path) | `c.Param("path")` → `a/b.txt` |
| `/about/` | only `/about/`; `/about` is redirected to it | |

> **Note:** Unlike raw `http.ServeMux`, a pattern ending in `/` matches
> **only** that path, not everything below it. Use a `{name...}` wildcard
> for a subtree.

### 4. Group routes

`r.Group(prefix, middleware...)` returns a router whose routes share a path
prefix and middleware. `As("prefix.")` adds a prefix to their names. Groups
nest. Inside a group, `""` and `"/"` both mean the group's own path
(`/posts`, without a trailing slash).

```go
// illustrative
admin := r.Group("/admin", requireAdmin).As("admin.")
admin.Get("/users", h.Users).Name("users") // GET /admin/users, name "admin.users"
```

Routes for one host only (an admin at `admin.example.com`) go on
`r.Host(host)`, which works like a group. A host's routes win for that
host; routes without a host answer every host. Requests match on the
host name, whatever their port. The routes' URLs are absolute, with
`APP_URL`'s scheme (`https` without one) and the port given to `Host`, if
any, since another host can't be reached with a path:

```go
// illustrative
admin := r.Host("admin.example.com").Group("", requireAdmin)
admin.Get("/", h.Dashboard).Name("admin.home") // c.URL("admin.home"): "https://admin.example.com/"
```

### 5. Name routes and generate URLs

Give routes names and build URLs from them, so paths live in one place:

```go
// illustrative
url, err := c.URL("notes.show", note.ID) // "/notes/7"
return c.RedirectRoute("notes.index")    // 303 See Other
return web.RedirectRoute("notes.show", note.ID), nil // from a typed handler
```

Arguments fill the wildcards in order and are path-escaped; a `url.Values`
after them becomes the query string
(`c.URL("notes.index", url.Values{"page": {"2"}})` is `"/notes?page=2"`).
A wrong name or argument count is an error. `r.MustURL` panics instead, which is useful for
fixed links at startup.

In views, `web.URL(ctx, name, args...)` builds the same paths from the
request's context, in the request's locale, and `web.MustURL(ctx, name,
args...)` returns the path alone for a component's argument,
panicking on a mistake as `r.MustURL` does: the router answers it with a
500 ([Render HTML with templ](https://docs.anetos.dev/guides/views/index.md#2-write-a-layout)).

### 6. Add middleware

Middleware is plain `func(http.Handler) http.Handler`, so any net/http
middleware works.

| Call | Applies to |
|---|---|
| `r.UseGlobal(mw...)` | Every request, including 404/405, before routing. Call it before the server starts |
| `r.Use(mw...)` | Routes registered on `r` (and groups created from it) **afterwards**. It panics if `r` or any of its groups already has routes, so middleware can't silently miss routes |
| `r.Group(prefix, mw...)` | Routes in the group |
| `r.With(mw...).Get(...)` | A single route |

`web.NewServer` already installs these global middleware, outermost first:
`Recover`, `RequestIDs`, `RealIP`, `AccessLog`, `SecureHeaders`, `CORS`
(when configured), the request's locale (with
[translations](https://docs.anetos.dev/guides/translations/index.md)), `BodyLimit` and `Timeout`. See the
[configuration reference](https://docs.anetos.dev/reference/configuration/index.md#http-server).
`web.ClientIP(ctx)` returns the client's address `RealIP` found
(or the peer's), from the request's context: `web.ClientIP(c)` in a
handler.
To limit how often clients call a group of routes, add
`ratelimit.Middleware` to it: see [Rate limiting](https://docs.anetos.dev/guides/rate-limiting/index.md).

`r.Routes()` lists each route's middleware, outermost first, named as
Go code names the function that makes it (`web.CSRF`,
`auth.Auth.Require`, `routes.adminOnly`), and `r.GlobalMiddleware()`
the global ones: `go run . route:list --json` prints them. A middleware
that asks for credentials or answers errors of its own can say so to
the API's description: it returns its handler through
`web.Documented(h, web.MiddlewareDoc{…})`, with a `Name` and a `Detail`
too if you like. See [Describe an API with
OpenAPI](https://docs.anetos.dev/guides/openapi/index.md#5-say-what-your-middleware-asks-for).

## How it works

The router registers your patterns on a standard `http.ServeMux`, adding
the method and making trailing-slash patterns exact. A catch-all route
handles everything else:

- A path that exists for other methods gets **405 Method Not Allowed** with
  an `Allow` header listing them (including custom methods such as
  `PURGE`), and `OPTIONS` gets **204** with `Allow`.
- Anything else gets **404**, as JSON problem details or an HTML page (see
  [Return errors](https://docs.anetos.dev/guides/handlers/index.md#4-return-errors)); always JSON when
  `web.JSONErrors` is global middleware, as in an API project.

> **Coming from another framework?** `r.Get(...).Name("x")` and
> `c.URL("x", id)` are named routes, like Django's `name=` with
> `reverse()`, Laravel's `->name()` with `route()`, or Rails' `as:` with
> its path helpers; `r.Group()` groups routes under a prefix.

## Testing it

The router is an `http.Handler`, so `httptest` works directly:

```go
// illustrative
r := web.NewRouter()
routes(r, &Notes{})
rec := httptest.NewRecorder()
r.ServeHTTP(rec, httptest.NewRequest("GET", "/notes/1", nil))
```

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| Panic: `Use called after routes were added` | `r.Use` after `r.Get(...)` | Call `Use` first, or use `r.With(mw).Get(...)` |
| Panic: `pattern "posts" must start with /` | Missing slash | Write `/posts` |
| Panic: `… conflicts with …` (from net/http) | Two routes match the same requests | Remove the duplicate or make one more specific |
| `/about` redirects to `/about/` | The route is `/about/` | Register `/about` instead |
| Panic: `duplicate route name` | Same name used twice | Names are global; use group prefixes (`As`) |

## Next steps

- [Handlers and requests](https://docs.anetos.dev/guides/handlers/index.md): typed handlers, binding, responses,
  errors
- [HTTP request lifecycle](https://docs.anetos.dev/concepts/http-request-lifecycle/index.md)


# Handlers and requests

Source: https://docs.anetos.dev/guides/handlers/

Write handlers that receive typed input, return typed output, and turn
errors into proper HTTP responses.

## Before you start

Read [Routing](https://docs.anetos.dev/guides/routing/index.md) to see how handlers are registered.

## Steps

### 1. Describe the input

An input struct says where each value comes from:

```go
// Note is what the API returns.
type Note struct {
	ID        int       `json:"id"`
	Title     string    `json:"title"`
	Body      string    `json:"body"`
	Tags      []string  `json:"tags,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

// CreateNote is the input for POST /notes. It binds from JSON or a form,
// and the validate rules run before the handler.
type CreateNote struct {
	Title string   `json:"title" validate:"required|max:200"`
	Body  string   `json:"body" validate:"max:10000"`
	Tags  []string `json:"tags" validate:"max:5|distinct|alpha_dash"`
}

// Validate runs after the tag rules pass, for checks tags can't express.
func (in CreateNote) Validate(context.Context) error {
	if strings.EqualFold(strings.TrimSpace(in.Title), "untitled") {
		return validate.Fail("title", "Please give the note a real title.")
	}
	return nil
}

// ListNotes reads its input from the query string.
type ListNotes struct {
	Limit int `query:"limit" validate:"min:0|max:100"`
}

// NoteID reads the {id} path parameter.
type NoteID struct {
	ID int `path:"id"`
}
```

(Copied from [`examples/notes`](https://github.com/anetos-dev/anetos/blob/main/examples/notes/main.go), region
`types`.)

| Tag | Source |
|---|---|
| `json:"title"` | JSON body. Also used as the form field name when there's no `form` tag |
| `form:"title"` | URL-encoded or multipart form field |
| `query:"page"` | Query string (`[]T` collects repeated values) |
| `path:"id"` | Path wildcard `{id}` |
| `header:"X-Token"` | Request header |
| `validate:"required\|max:200"` | Not a source: [validation rules](https://docs.anetos.dev/guides/validation/index.md) checked after binding |

Values are converted to the field's type: strings, numbers, booleans,
`time.Duration`, `time.Time` (RFC 3339), pointers, and any type with an
`UnmarshalText` method. Uploaded files are `*multipart.FileHeader` or
`[]*multipart.FileHeader` with a `form` tag. See the
[binding reference](https://docs.anetos.dev/reference/binding/index.md).

### 2. Write a typed handler

```go
// illustrative
func (h *Notes) Create(c *web.Ctx, in CreateNote) (Note, error) {
	return h.create(in.Title, in.Body), nil
}

func (h *Notes) Show(c *web.Ctx, in NoteID) (Note, error) {
	note, ok := h.find(in.ID)
	if !ok {
		return Note{}, web.Error(http.StatusNotFound, "note not found")
	}
	return note, nil
}
```

Register it with `web.H` (H for handler):

```go
// illustrative
api.Post("", web.H(notes.Create)).Name("create").Status(http.StatusCreated)
```

`web.H` inspects the input type **once, at startup**. It panics then if the
type can't be bound or a `validate` tag is wrong (an unknown rule, a bad
parameter), so a mistake never waits for the first request.

`web.H` has nothing to do with Gin's `gin.H` map: it adapts a typed
handler. A map is answered as JSON here too (`map[string]any`), with no
special type.

### 3. Choose the response

| Return | Response |
|---|---|
| Any value (struct, slice, map…) | JSON with the route's status: `200`, or what `Status` sets on the route; no body with `204` or `205` |
| `web.Empty{}` | `204` without a body (or the route's status, still without a body) |
| `web.Created(v)` | `201` with JSON |
| `web.JSON(status, v)` | JSON with any status |
| `web.NoContent()` or a nil `web.Responder` | `204` |
| `web.Redirect(url)` / `web.RedirectRoute(name, args...)` | `303 See Other` |
| `web.Text(status, s)` | Plain text |
| Your own type with `Respond(c *web.Ctx) error` | Whatever it writes |

For an API, return a typed value and put the status on the route:
`.Status(http.StatusCreated)` for a route that creates something,
`web.Empty` for one with nothing to answer (a deletion). The handler's
signature and the route then say what the request answers, which the
API's description reads ([Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md));
`Status` takes 2xx statuses only, and errors are written as usual.
`Status` sets what a `web.H` handler's result answers: a
`web.Responder`, a plain handler and a `web.WrapHandler` route write their
own status, and ignore it. Use `web.Responder` as the output type when
one handler returns different kinds of responses, chosen as it runs:
pages' redirects, say.

Handlers can also be plain `func(c *web.Ctx) error` and write with
`c.JSON`, `c.Text`, `c.HTML`, `c.Blob`, `c.Redirect`, `c.RedirectRoute` or
`c.NoContent`.

### 4. Return errors

Return an error and let the framework respond:

- `web.Error(status, "message")` gives that status with your message, which
  is shown to the client.
- Your own errors can implement `HTTPStatus() int` (`web.StatusCoder`) to
  pick a status, for example a repository's "not found" error returning
  404. The method is `HTTPStatus`, not go-kit's `StatusCode`.
- Anything else is a **500**, and its message is **not** shown to clients
  unless `APP_DEBUG=true`.

<a id="errors"></a>Error responses are chosen per client:

- **API clients** (sending `Accept: application/json`, a JSON body, or
  `X-Requested-With: XMLHttpRequest`), and every request under
  `web.JSONErrors` (below), get RFC 9457 problem details:

  ```json
  {
    "type": "about:blank",
    "title": "Unprocessable Entity",
    "status": 422,
    "detail": "The given data was invalid.",
    "errors": {
      "title": "The title field is required."
    },
    "request_id": "dikxmvlw5ml243cr"
  }
  ```

  Binding and validation errors fill the `errors` object, keyed by field
  name. Your own errors can do the same by implementing
  `FieldErrors() map[string]string` (`web.FieldErrorer`).
- **Browsers** get an HTML error page. With `APP_DEBUG=true` it shows the
  error chain, the stack trace for panics, and request details (with
  `Authorization` and `Cookie` headers redacted).

  A project made with `anetos new` shows its error pages in its own
  layout: `routes/web.go` passes `views.ErrorPage` (in
  `views/errors.templ`, yours to change) to the router's `ErrorPages`.
  It gets a `web.ErrorPage`: the status, its translated title, the
  error's message for the visitor if any (never a 5xx's internals), the
  field errors of a 4xx that isn't a form's redirect, and the request
  ID. With `APP_DEBUG=true`, a 5xx still shows the framework's page with
  its details. A URL that matches no route runs only the global
  middleware, so its page has no session: the header shows a guest's
  links. If the page fails to render (or panics), the framework's is
  sent and the failure logged. Another app adds it the same way:

  ```go
  // illustrative
  r.ErrorPages(func(_ *web.Ctx, e web.ErrorPage) view.Component { return views.ErrorPage(e) })
  ```

<a id="json-errors"></a>An API can't count on its clients asking for JSON: `curl`, `fetch`
without headers and many HTTP libraries send `Accept: */*` or nothing,
and would get the HTML page. Put `web.JSONErrors` on the
API's routes, and their errors are problem details whatever the client
sends, never a page or a redirect back to a form:

```go
// The API's errors are JSON problem details, whatever the client
// accepts, and a guest gets a 401, not the login page.
var api handlers.API
v1 := r.Group("/api", web.JSONErrors, a.TokenMiddleware, a.Require) // Authorization: Bearer <token>
v1.Get("/projects", web.H(api.Projects)).Name("api.projects")
v1.Get("/projects/{project}/issues", web.H(api.Issues)).Name("api.issues")
v1.Post("/projects/{project}/issues", web.H(api.CreateIssue)).Name("api.issues.create").Status(http.StatusCreated)
v1.Get("/projects/{project}/issues/{number}", web.H(api.Issue)).Name("api.issues.show")
```

(Copied from [`examples/tracker/routes/tracker.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tracker/routes/tracker.go), region `api`.)

Under it, `c.WantsJSON()` (and `web.WantsJSON(r)` in middleware) is
true, so everything that treats API clients differently does so:
`auth`'s `Require` answers 401 rather than redirecting to the login
page. In debug mode the error's details are in the problem's `debug`
member. Put it before the middleware whose answers it should change,
such as `Require`: it acts from its place in the chain on. A project
made with `anetos new --stack=api` puts it on every request
(`r.UseGlobal(web.JSONErrors)` in `routes/api.go`), so a URL that
matches no route gets a JSON 404 too, and a panic in middleware a JSON
500. On a group, only that group's routes are affected: a URL under the
group's prefix that matches none of them gets the router's usual 404.

Panics in handlers are recovered and handled like errors. Every 5xx is
logged with the request ID.

Two edge cases:

- **The response already started.** If a handler writes part of a response
  and then fails or panics, the error is logged and the connection is
  aborted, so the client sees a failed response rather than a truncated one
  that looks complete.
- **Cancellation.** If the client went away, nothing is written (logged as
  499). If a handler returns `context.Canceled` from some internal context
  while the client is still waiting, it's a 500.

## How binding works

1. The **body** is decoded: JSON (`Content-Type: application/json` or
   `+json`) into the whole struct, or a form into `form`/`json`-named fields.
   Other content types get **415**, and bodies over `HTTP_MAX_BODY` get **413**.
2. Then **query**, **header** and **path** values are applied. Fields with
   these tags can **never** be set from the body, so a client can't override
   `{id}` by sending `"ID": 999` in JSON.
3. Conversion failures give **400** with each bad field listed.
4. The `validate` tag rules run. Failures give **422** with a message per
   field. See [Validation](https://docs.anetos.dev/guides/validation/index.md).
5. If they pass and the input has `Validate(ctx) error`, it runs.
   `validate.Fail(field, message)` (or a `*validate.Errors`) gives **422**,
   an `HTTPError` keeps its own status, and any other error is a **500**.

> **Coming from another framework?** The input struct plays the role of
> a Django form, a Laravel form request, or Rails' strong parameters
> and model validations: it
> declares the input, its rules (`required|email`) and extra checks, and
> is validated before your handler runs.

## Testing it

Send requests to the app's router with `anetostest`:

```go
// illustrative
app := anetostest.New(t, setup)
app.PostJSON("/notes", map[string]string{"title": "Hi"}).
	AssertCreated().
	AssertJSONPath("title", "Hi")
```

See [Test your app](https://docs.anetos.dev/guides/testing/index.md#3-test-a-json-api). A router alone works
with `httptest` too: `r.ServeHTTP(rec, req)`.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| Panic at startup: `input type … must be a struct` | `web.H` handler takes a non-struct | Wrap inputs in a struct |
| Panic at startup: `unsupported field type` | e.g. a `map` field with a `query` tag | Use supported types or read `c.Request()` yourself |
| Panic at startup: `validate: … unknown rule` | A typo in a `validate` tag, or a custom rule registered after the route | Check the [rules reference](https://docs.anetos.dev/reference/validation-rules/index.md); register custom rules in `init` |
| Field stays empty for JSON | The field has a `path`/`query`/`header` tag, or its JSON name differs | Check tags; body can't fill those fields |
| `415 Unsupported Media Type` | Missing or wrong `Content-Type` | Send `application/json` or a form content type |
| 500 with no details | Production mode hides internal errors | Check the log line with the same `request_id`, or set `APP_DEBUG=true` locally |

## Next steps

- [Validation](https://docs.anetos.dev/guides/validation/index.md)
- [Binding reference](https://docs.anetos.dev/reference/binding/index.md)
- [HTTP request lifecycle](https://docs.anetos.dev/concepts/http-request-lifecycle/index.md)


# Render HTML with templ

Source: https://docs.anetos.dev/guides/views/

Write pages as [templ](https://templ.guide) components (typed, compiled,
escaped by default), share a layout, link to routes by name, serve
static files with cache-busting URLs, and add interactivity with the
bundled htmx.

## Before you start

[Route requests to handlers](https://docs.anetos.dev/guides/routing/index.md). Pages with forms also need
[sessions](https://docs.anetos.dev/guides/sessions/index.md).

## Steps

### 1. Add templ to your module

```sh
go get -tool github.com/a-h/templ/cmd/templ@latest
```

Components live in `.templ` files; `go tool templ generate` turns each
into a `_templ.go` file that you commit. Add
`//go:generate go tool templ generate` to one Go file so
`go generate ./...` runs it, and `go tool anetos dev` runs it on every
change.

### 2. Write a layout

A layout is a component that renders its children inside the page shell:

```templ
// Layout is the page shell. Pages pass their content as children.
templ Layout(title string) {
	<!DOCTYPE html>
	<html lang="en">
		<head>
			<meta charset="utf-8"/>
			<meta name="viewport" content="width=device-width, initial-scale=1"/>
			<title>{ title } · Notes</title>
			<link rel="stylesheet" href={ assets.URL("app.css") }/>
			<script src={ assets.URL("htmx.min.js") } defer></script>
		</head>
		<!-- htmx sends the CSRF token in a header with every request. -->
		<body hx-headers={ `{"X-CSRF-Token": "` + view.CSRFToken(ctx) + `"}` }>
			<header><a href={ web.URL(ctx, "notes.index") }>Notes</a></header>
			if msg := view.Flash(ctx, "status"); msg != "" {
				<p class="flash" role="status">{ msg }</p>
			}
			<main>
				{ children... }
			</main>
		</body>
	</html>
}
```

(Copied from [`examples/forms/layout.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/layout.templ), region `layout`.)

`ctx` is available in every component: it is the request's context, so
the helpers work inside templates. `web.URL(ctx, name, args...)` builds a
route's path; templ accepts its `(string, error)` result in attributes
and text, and a wrong route name fails the render with an error page.

A component's argument can't take a `(string, error)` pair. There,
`web.MustURL(ctx, name, args...)` returns the path alone, and
panics on a route name that doesn't exist or arguments the route
doesn't take. The router answers the panic with a 500 page, and since
rendering is buffered, the visitor never gets half a page:

```templ
// illustrative
@ui.LinkButton(web.MustURL(ctx, "posts.edit", post.ID), ui.Secondary) {
	Edit
}
```

A project made with `anetos new` has a layout like this one, built from
the components of its `views/ui` package (`ui.Header`, `ui.Nav`,
`ui.Main`, `ui.Flash`…), which hold the markup and the class names
([Style your app](https://docs.anetos.dev/guides/styling/index.md)).

### 3. Write pages and render them

A page wraps its content in the layout:

```templ
// illustrative
templ PostPage(p Post) {
	@Layout(p.Title) {
		<h1>{ p.Title }</h1>
		<p>{ p.Body }</p>
	}
}
```

In a project made with `anetos new`, pages call the components of
`views/ui` for their structure, and need no class names
([UI components reference](https://docs.anetos.dev/reference/ui/index.md)):

```templ
// illustrative
templ PostPage(p Post) {
	@Layout(p.Title) {
		@ui.PageHeader(p.Title, "") {
			@ui.LinkButton(web.MustURL(ctx, "posts.edit", p.ID), ui.Secondary) {
				Edit
			}
		}
		@ui.Card("") {
			@ui.Multiline(p.Body)
		}
	}
}
```

Render it from a handler with `c.Render`, or return `web.Render` from a
typed handler:

```go
// illustrative
// PostID binds the {id} path parameter: ID int64 `path:"id"`.
func (h Posts) Show(c *web.Ctx, in PostID) (web.Responder, error) {
	p, err := db.Find[Post](c, in.ID)
	if err != nil {
		return nil, err
	}
	return web.Render(PostPage(p)), nil
}
```

Rendering is buffered: if a component returns an error, the visitor gets
an error page, not half a page.

### 4. Serve static files

`view.NewAssets` serves the files of one or more file systems and builds
their URLs with a content hash:

```go
// public holds the files of the public directory.
//
//go:embed public
var public embed.FS

// assets serves public/ and the bundled htmx at /assets, with hashed URLs.
var assets = mustAssets()

func mustAssets() *view.Assets {
	files, err := fs.Sub(public, "public")
	if err != nil {
		panic(err)
	}
	a, err := view.NewAssets("/assets", files, htmx.FS)
	if err != nil {
		panic(err)
	}
	return a
}
```

(Copied from [`examples/forms`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main.go), region `assets`.)

`assets.URL("app.css")` is `/assets/app.css?v=3f2a9c01d4`. Requests
with the current hash may be cached for a year; a changed file gets a new
URL. Mount it with `r.Get("/assets/{path...}", web.WrapHandler(assets))`.
`htmx.FS` holds the bundled htmx (version `htmx.Version`) and its
server-sent events extension, `htmx-ext-sse.min.js` (`htmx.SSEVersion`),
for pages that show updates as they happen: a streamed AI answer (see
[Build an AI assistant](https://docs.anetos.dev/guides/ai-assistant/index.md)), or events of your own, sent
with `c.EventStream()`.

Files that need a fixed URL, such as `robots.txt` or
`.well-known/security.txt`, go in `public/` itself, the web root, which
the project's `routes/web.go` serves at `/`:

```go
// illustrative
r.Static("/", public.Files) // public/robots.txt at /robots.txt
```

`r.Static(prefix, fsys)` serves a file system's files below a prefix,
for GET and HEAD requests that no route matches: routes win. It never
serves directories, Go files, or hidden files other than those in
`.well-known/`; a missing file is the app's 404 page. `public.Files`
embeds the whole folder (`//go:embed *`), `static/` too, which
`/assets/` serves with hashed URLs: link those through `public.Assets`,
which browsers cache. A folder of `public/` that holds only hidden files
(`.gitkeep`) stops the build: embed needs a file in it.

### 5. Update parts of a page with htmx

htmx requests carry `HX-Request`; `c.IsHTMX()` tells the handler to answer
with a fragment. Deleting a note in place:

```templ
// noteItem is one note. Its delete form works without JavaScript
// (POST with _method=DELETE); with htmx it sends DELETE and removes the
// item in place.
templ noteItem(n Note) {
	<li>
		<div>
			<strong>{ n.Title }</strong>
			<p>{ n.Body }</p>
		</div>
		<div>
			<a href={ web.URL(ctx, "notes.edit", n.ID) }>Edit</a>
			<form class="inline" method="post" action={ web.URL(ctx, "notes.delete", n.ID) }
				hx-delete={ web.URL(ctx, "notes.delete", n.ID) } hx-target="closest li" hx-swap="outerHTML"
				hx-confirm="Delete this note?">
				@view.CSRFField(ctx)
				@view.MethodField("DELETE")
				<button type="submit">Delete</button>
			</form>
		</div>
	</li>
}
```

(Copied from [`examples/forms/notes.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/notes.templ), region `delete-button`.)

```go
func (Notes) Delete(c *web.Ctx, in NoteID) (web.Responder, error) {
	n, err := db.Find[Note](c, in.ID)
	if err != nil {
		return nil, err
	}
	if err := db.Delete(c, &n); err != nil {
		return nil, err
	}
	if c.IsHTMX() {
		// htmx replaces the note's list item with this empty response.
		return web.Text(http.StatusOK, ""), nil
	}
	c.Session().Flash("status", "Note deleted.")
	return web.RedirectRoute("notes.index"), nil
}
```

(Copied from [`examples/forms`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main.go), region `delete`.)

With `views/ui`, `ui.Form` writes the same form, CSRF token and
`_method` field included, and takes the htmx attributes:

```templ
// illustrative
@ui.Form(web.MustURL(ctx, "notes.delete", n.ID), "DELETE", templ.Attributes{
	"hx-delete":  web.MustURL(ctx, "notes.delete", n.ID),
	"hx-target":  "closest li",
	"hx-swap":    "outerHTML",
	"hx-confirm": "Delete this note?",
}) {
	@ui.Button(ui.Danger, nil, ui.Small) {
		Delete
	}
}
```

The layout puts the CSRF token in `hx-headers`, so every htmx request
passes [CSRF protection](https://docs.anetos.dev/guides/forms/index.md). `c.HTMX()` returns the other htmx
headers (target, trigger, boosted).

For updates the server pushes, `c.EventStream()` starts a response of
server-sent events, which the SSE extension swaps into the page:

```go
// illustrative
stream, err := c.EventStream() // no request or write timeout for this response
if err != nil {
	return err
}
for status := range updates {
	if err := stream.Send("status", html.EscapeString(status)); err != nil {
		return nil // the browser left
	}
}
return stream.Send("done", "")
```

```html
<!-- illustrative -->
<div hx-ext="sse" sse-connect="/jobs/7/events" sse-swap="status" sse-close="done"></div>
```

Close the stream with an event (`sse-close`): browsers reconnect to a
stream that ends. `stream.Comment(text)` sends a keep-alive, and
`srv.Stopping()` tells a long stream that the server is shutting down.

### 6. Or use html/template

`view.Template(t, name, data)` turns an `html/template` template into a
component, so `c.Render` works the same way.

## Complete example

[`examples/forms`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main.go) is a notes app with a
layout, forms, flash messages, assets and htmx.

## How it works

A component is anything with `Render(ctx context.Context, w io.Writer)
error`: that is templ's `templ.Component`, so the framework doesn't depend
on templ. `c.Render` renders into a pooled buffer with the `*web.Ctx` as
context and writes it with `Content-Type: text/html; charset=utf-8`.
`c.IsHTMX()` adds `Vary: HX-Request`, so caches keep fragments and full
pages apart.

> **Coming from another framework?** templ components play the role of
> Django templates, Laravel's Blade views and components, or Rails'
> views and partials; `{ children... }` is where the content goes.
> `web.URL` builds a route's URL, and `assets.URL` gives a static file's
> URL without a build step (Vite arrives in v0.6).

## Testing it

Render a component to a string with `view.String(ctx, component)`, or
request the page with `anetostest` and check it with `AssertSee`, as
[`examples/forms`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main_test.go) does.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `undefined: NotesPage` | The `.templ` file wasn't generated | Run `go generate ./...` (or `go tool templ generate`) |
| `web: unknown route name: "…"` when rendering | A typo in a route name | Use the name given with `.Name(…)` |
| A 500 page, and a panic with `web: unknown route name` in the log | The same typo, in `web.MustURL` | Use the name given with `.Name(…)`; `go run . route:list` lists them |
| `view: no session for this request` | A page uses `view.CSRFField` on a route without the session middleware | Add the middleware to the route's group |
| Browsers keep an old CSS file | A URL written by hand, without the hash | Use `assets.URL(name)` |

## Next steps

- [Style your app](https://docs.anetos.dev/guides/styling/index.md) with the components of `views/ui`
- [Handle HTML forms](https://docs.anetos.dev/guides/forms/index.md)
- [Sessions and flash messages](https://docs.anetos.dev/guides/sessions/index.md)
- [Views, sessions and forms reference](https://docs.anetos.dev/reference/views/index.md)


# Style your app

Source: https://docs.anetos.dev/guides/styling/

A new project looks finished from the first page. Its pages are made of
components in `views/ui`, a package of your app, styled by one
stylesheet, `public/static/app.css`. Change the colors, change a
component, add your own, start with Pico, Bootstrap or Bulma, or start
without styles.

## Before you start

A project made with `anetos new` v0.5 or later. (A project made before
v0.5 has no `views/ui` yet: see [below](https://docs.anetos.dev/guides/styling/index.md#projects-made-before-v05).)
There is no CDN and no build step, except with Tailwind CSS, whose build
`anetos dev` runs for you ([Tailwind CSS](https://docs.anetos.dev/guides/tailwind/index.md)). `anetos dev`
reloads the page when you save a file.

## Steps

### 1. Know what's there

The look of your app is two parts, which a *CSS framework* writes together:

| File | Holds |
|---|---|
| `views/ui/shell.templ` | The page's shell, which the layout puts together: `Head`, `Header`, `Nav`, `NavLink`, `NavEnd`, `NavItem`, `Main`, `Footer`, `Flash` |
| `views/ui/page.templ` | A page's structure: `PageHeader`, `Card`, `Narrow`, `Stack`, `Cluster`, `Empty`… |
| `views/ui/form.templ` | Forms: `Form`, `Field`, `Input`, `Textarea`, `Select`, `Checkbox`, `Button`, `LinkButton`, `PostButton`… |
| `views/ui/data.templ` | Lists and values: `Table`, `Details`, `Badge`, `Pagination`… |
| `views/ui/ui.go` | The types the components take: `Variant` (a button's kind: primary, secondary, danger, ghost), `Size` (small, full width), `Tone` (the meaning a badge's or a message's color gives: success, warning, error…), `Option`, `Pages` |
| `views/ui/classes.go` | The framework's classes for each variant, size and tone (not with `none`) |
| `public/static/app.css` | The starter theme: light and dark, about 270 lines of plain CSS |

Only `views/ui` has class names. The layout (`views/layout.templ`), the
home page and the pages of `make:crud` and `make:auth` call the
components, and use plain HTML elements, without classes, for the rest:
headings, paragraphs, links, table rows. The
[UI components reference](https://docs.anetos.dev/reference/ui/index.md) lists every component.

> **Note:** `--css` picks only the look. Accounts come from `make:auth`,
> which writes its pages with the same components.

### 2. Build pages with the components

A page calls the components for its structure. The tutorial's list of
issues:

```templ
// IssuesPage lists a page of issues, with links to the pages around it.
templ IssuesPage(page db.Page[models.Issue]) {
	@Layout("Issues") {
		@ui.PageHeader("Issues", "") {
			@ui.LinkButton(web.MustURL(ctx, "issues.new"), ui.Primary) {
				New issue
			}
		}
		if page.Total == 0 {
			@ui.Empty("No issues yet.")
		} else {
			@ui.Table() {
				<tbody>
					for _, issue := range page.Data {
						<tr>
							<td>
								@statusBadge(issue.Status)
							</td>
							<td><a href={ templ.URL(fmt.Sprintf("/issues/%d", issue.ID)) }>{ issue.Title }</a></td>
							<td><small>#{ issue.ID } by { issue.Author.Name }</small></td>
						</tr>
					}
				</tbody>
			}
		}
		if page.LastPage > 1 {
			@ui.Pagination(ui.PagesOf(ctx, page, "Pages", "", "Newer", "Older"))
		}
	}
}

// statusBadge shows an issue's status: green while it's open.
templ statusBadge(status string) {
	if status == "open" {
		@ui.Badge(ui.Success) {
			{ status }
		}
	} else {
		@ui.Badge(ui.Neutral) {
			{ status }
		}
	}
}
```

(Copied from [`examples/tutorial/views/issues.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/issues.templ), region `list`.)

- A component with content takes it as children, in `{ }`:
  `ui.PageHeader` puts its children (the buttons) beside the title.
- A button's variant is one of `ui.Primary` (the default),
  `ui.Secondary`, `ui.Danger` and `ui.Ghost`; sizes may follow it,
  `ui.Small` or `ui.FullWidth`: `@ui.LinkButton(url, ui.Secondary,
  ui.Small)`.
- A badge's or a message's tone is `ui.Neutral`, `ui.Success`,
  `ui.Warning`, `ui.Error` or `ui.Info`.
- Components take URLs as strings. `web.MustURL(ctx, name, args...)` is
  the path of a named route, as `web.URL` is, without the error: a name
  that doesn't exist is a panic, which the router answers with a 500
  page ([Render HTML with templ](https://docs.anetos.dev/guides/views/index.md#2-write-a-layout)).

### 3. Change the colors

The colors, radius, fonts and width are variables at the top of
`app.css`:

```css
/* illustrative */
:root {
	--primary: #3056d3;       /* links and buttons */
	--primary-hover: #2445b4;
	--radius: 8px;
	--font: system-ui, sans-serif;
	--width: 64rem;           /* the page's width */
}
```

Change `--primary` and `--primary-hover` for your brand. Dark mode
follows the visitor's system and has its own values below; set
`data-theme="dark"` (or `"light"`) on `<html>` in `views/layout.templ`
to force one.

### 4. Change a component

The components are yours: change the markup they write, and every page
that calls them follows. Keep each component's name and arguments:
the pages of `make:crud` and `make:auth` call them as they are. For
example, an empty list with a picture, in `views/ui/page.templ`
(which then imports your module's `public` package, as `shell.templ`
does):

```templ
// illustrative
// Empty says a list has nothing in it yet.
templ Empty(text string) {
	<div class="empty">
		<img src={ public.Assets.URL("empty.svg") } alt=""/>
		<p>{ text }</p>
	</div>
}
```

Then add the rules for it at the end of `app.css`. If a component needs
another argument, add a new component rather than change the old one's
signature; if you do change it, `go build` lists every call to update.

### 5. Add your own component

Markup you repeat belongs in a component of its own. Put it in
`views/ui`, in a file of your own, so the class names stay in one
package:

```templ
// illustrative
package ui

// Stat is a number with its label, as on a dashboard.
templ Stat(label, value string) {
	<div class="card stat">
		<p class="muted">{ label }</p>
		<p class="stat-value">{ value }</p>
	</div>
}
```

A page calls it like the others: `@ui.Stat("Open issues",
strconv.Itoa(open))`. The theme has a few classes that no component
uses yet, such as `grid` (cards side by side, wrapping), for components
of your own.

### 6. Add your own stylesheets

Add rules at the end of `app.css`, or put another file in
`public/static/` and link it from `ui.Head`, in `views/ui/shell.templ`:

```templ
// illustrative
templ Head() {
	<link rel="stylesheet" href={ public.Assets.URL("app.css") }/>
	<link rel="stylesheet" href={ public.Assets.URL("mine.css") }/>
}
```

`public.Assets.URL` adds a version to the URL, so browsers fetch the new
file after a deploy; the binary embeds `public/`.

### 7. Or start with a CSS framework

`anetos new` writes the starter theme. `--css` picks a CSS framework instead:

```sh
anetos new blog --css=bootstrap
```

| `--css` | The components' markup | `public/static/` | Guide |
|---|---|---|---|
| `anetos` (the default) | The starter theme's classes | `app.css`: the starter theme | [The starter theme](https://docs.anetos.dev/guides/starter-theme/index.md) |
| `none` | Plain HTML without classes | `app.css`: a comment, for your styles | [Start without styles](https://docs.anetos.dev/guides/plain-html/index.md) |
| `pico` | [Pico CSS](https://picocss.com) 2.1.1: mostly plain HTML, which Pico styles | `pico.min.css`, `app.css` (what Pico has no style of) | [Pico](https://docs.anetos.dev/guides/pico/index.md) |
| `bootstrap` | [Bootstrap](https://getbootstrap.com) 5.3.8's classes | `bootstrap.min.css`, `bootstrap.bundle.min.js`, `theme.js`, `app.css` | [Bootstrap](https://docs.anetos.dev/guides/bootstrap/index.md) |
| `bulma` | [Bulma](https://bulma.io) 1.0.4's classes | `bulma.min.css`, `nav.js`, `app.css` | [Bulma](https://docs.anetos.dev/guides/bulma/index.md) |
| `tailwind` | [Tailwind CSS](https://tailwindcss.com) 4.3.3's utility classes | `app.css`, compiled from `views/ui/tailwind.css` | [Tailwind CSS](https://docs.anetos.dev/guides/tailwind/index.md) |

The same page, a list that `make:crud` wrote, with each:

| `--css` | The products list |
|---|---|
| `anetos` | ![The products list with the starter theme](https://docs.anetos.dev/images/kits/anetos-list-light.webp) |
| `none` | ![The products list without styles](https://docs.anetos.dev/images/kits/none-list-light.webp) |
| `pico` | ![The products list with Pico](https://docs.anetos.dev/images/kits/pico-list-light.webp) |
| `bootstrap` | ![The products list with Bootstrap](https://docs.anetos.dev/images/kits/bootstrap-list-light.webp) |
| `bulma` | ![The products list with Bulma](https://docs.anetos.dev/images/kits/bulma-list-light.webp) |
| `tailwind` | ![The products list with Tailwind CSS](https://docs.anetos.dev/images/kits/tailwind-list-light.webp) |

Each writes the same components, with the same names and
arguments, so the layout, the home page and the pages of `make:crud` and
`make:auth` are the same with each: only `views/ui` and
`public/static/` differ. Each but `none` follows the visitor's light or
dark mode. A framework's files are as released, with its license beside
them (`pico.LICENSE.txt`: MIT, as are the others); the binary embeds
them, and serves them gzipped to browsers that accept it. Each one's
guide shows its pages in light and dark, and how to change its colors
and use more of its framework.

A CSS framework is `views/ui` with its `public/static/` files, so another
restyles every page that calls the components: [step 8](https://docs.anetos.dev/guides/styling/index.md#8-switch-css-frameworks)
switches a project's.

### 8. Switch CSS frameworks

```sh
go tool anetos css:use bulma
```

switches the project to another CSS framework. It writes its components
(`views/ui`) and stylesheets (`public/static/`), removes the old one's
files the new one hasn't (`pico.min.css`, `theme.js`, `tailwind.css`…),
and runs `templ generate` (and, for Tailwind, `css:build`). The layout,
the pages and your own files in `views/ui` stay as they are: the pages
call the components, so every one of them takes the new look.
`go tool anetos css:use` alone prints the project's.

`views/ui/css.json` records the CSS framework: its name, its version,
and the SHA-256 of each file it wrote (`anetos new` writes it, and
`css:use` updates it). With it, `css:use` knows which of those files you
changed since: a component you edited, your colors in `app.css`. It
names them and writes nothing:

```text
anetos css:use: these files changed since anetos wrote them for the starter theme, or aren't its:
  public/static/app.css
  views/ui/page.templ
Nothing was written. Run again with --force to replace them (commit first: git then shows what changed), or undo the changes.
```

`--force` replaces them; commit first, and `git diff` shows what to
carry over (your colors into the new stylesheet, say). A project
without `css.json` (or with one it can't read) needs `--force` too;
then it can't tell the old framework's static files from yours, so it lists
the files of `public/static/` it left for you to remove. A file of
`views/ui` or `public/static` that is a symbolic link counts as changed. Line endings don't: git
on Windows may check files out with CRLF.

After the switch, `css:use` builds the project: when your own code
called something only the old framework's components had (an
unexported helper of its `classes.go`), it says so and exits with status 1. It adds `nav.menu`
to `locales/en/app.yaml` when missing, and names the other locales to
translate it in.

`css:use` with the framework the project already has updates its files
to your `anetos`'s version (after `go get -tool
anetos.dev/anetos/cli/cmd/anetos@latest`: a newer Pico, fixed
components), under the same rule. Moving to or from Tailwind, it says
which cache line to add to (or remove from) your `Dockerfile`; it
doesn't edit it.

### Pages with classes of your own

A page can still use classes of its own (`<div class="hero">`), styled
by your rules in `app.css`. They keep working, but they are outside the
components: `css:use` restyles the components, not your pages' classes, and
says which of your own files in `views/ui` keep theirs. When the markup
repeats, make it a component (step 5).

## Projects made before v0.5

A project made before v0.5 has no `views/ui`: its layout and pages
carry the starter theme's classes themselves. Nothing changes until
you run a generator. The first `make:crud` or `make:auth` writes
`views/ui` before the pages that call it, and says so:

```text
views/ui has the components for the starter theme, which the new pages call: the project had none (made before v0.5).
The layout keeps its markup; the upgrade guide shows how to use them there too.
```

It picks the CSS framework from your stylesheet: `anetos` when
`public/static/app.css` has the starter theme's `.card` rule, else
`none` (classless markup, for a stylesheet of your own). It doesn't
change `app.css`, the layout or your other pages. Both kinds of layout
work with the generators: `make:crud` adds its link at the end of the
header's nav, and `make:auth` adds `@AccountMenu()` after it, whether
the nav is a `<nav>` or a `@ui.Nav` block.

To build the layout from the components too, compare it with the
`views/layout.templ` of a new project (`anetos new` in another folder):
`@ui.Head()` in `<head>`, then `ui.Header`, `ui.Nav`, `ui.Main`,
`ui.Footer` and `ui.Flash` in place of the markup with classes.

## How it works

`views/ui` is an ordinary package of your app. Nothing in the framework
imports it, and updating Anetos never changes it, or `app.css`: a newer
version's components come when you ask for them, with `css:use` and
your framework's name ([step 8](https://docs.anetos.dev/guides/styling/index.md#8-switch-css-frameworks)).

Some components read the request's context (`ctx`): `ui.Form` adds the
CSRF token, `ui.Field` shows its field's validation message, and
`ui.Input`, `ui.Textarea`, `ui.Select` and `ui.Checkbox` are marked
`aria-invalid="true"` when their field failed validation, which the
stylesheet shows with a red border. `ui.NavLink` marks the current page with
`aria-current="page"` (the layout's `navLink` asks `web.RouteIs`), which
the stylesheet highlights. A header entry that isn't a link (the logout button)
is in a `ui.NavItem`, which each CSS framework wraps as its menus need.

The theme is variables, then base styles for the elements, then the
classes. Forms and tables need no class: plain HTML looks right as it
is.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `undefined: ui.Stat` (or another component) | `views/ui` has no such component: it was renamed, deleted, or never there | Add it to `views/ui`, or copy it from a new project's |
| A generated page doesn't build after you changed a component | The pages of `make:crud` and `make:auth` call the component's old arguments | Keep the signature; add a new component for the new arguments |
| A 500 page and `web: unknown route name` in the log | `web.MustURL` was given a route name that doesn't exist | Fix the name; `go run . route:list` lists them |
| The new pages of a project made before v0.5 have no style | `app.css` has no `.card` rule, so the classless components (`none`) were written | Style the elements, or give the components your classes |

## Next steps

- [UI components reference](https://docs.anetos.dev/reference/ui/index.md): every component and
  its arguments
- [Add pages for a model](https://docs.anetos.dev/getting-started/crud/index.md) with `make:crud`
- [Render HTML with templ](https://docs.anetos.dev/guides/views/index.md)


# Handle HTML forms

Source: https://docs.anetos.dev/guides/forms/

Protect forms against cross-site request forgery, send PUT and DELETE
from plain HTML, and show validation errors next to the fields with the
submitted values kept.

## Before you start

[Sessions](https://docs.anetos.dev/guides/sessions/index.md) and [views](https://docs.anetos.dev/guides/views/index.md). Validation rules work as in
[Validation](https://docs.anetos.dev/guides/validation/index.md).

## Steps

### 1. Protect the routes

Add `web.CSRF()` after the session middleware, and `web.MethodOverride`
globally:

```go
sessions, err := session.New(app) // SESSION_* settings; needs APP_KEY
if err != nil {
	return nil, err
}
r := srv.Router()
r.UseGlobal(web.MethodOverride) // forms can send PUT and DELETE with _method
r.Get("/assets/{path...}", web.WrapHandler(assets))

var h Notes
pages := r.Group("", sessions.Middleware, web.CSRF())
pages.Get("/", func(c *web.Ctx) error { return c.RedirectRoute("notes.index") })
pages.Get("/notes", web.H(h.Index)).Name("notes.index")
pages.Get("/notes/new", h.New).Name("notes.new")
pages.Post("/notes", web.H(h.Create)).Name("notes.create")
pages.Get("/notes/{id}/edit", web.H(h.Edit)).Name("notes.edit")
pages.Put("/notes/{id}", web.H(h.Update)).Name("notes.update")
pages.Delete("/notes/{id}", web.H(h.Delete)).Name("notes.delete")
```

(Copied from [`examples/forms`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main.go), region `routes`.)

For every POST, PUT, PATCH and DELETE (any method but GET, HEAD, OPTIONS
and TRACE), `web.CSRF` rejects requests from
other sites (using the browser's `Sec-Fetch-Site` and `Origin` headers)
and requires the session's token, from the `_token` field or the
`X-CSRF-Token` header. Failures are a **403** ("The page has expired.
Reload it and try again."). APIs that authenticate with tokens in headers
don't need it: keep them in a group without it.

### 2. Write the form

```templ
// NoteFormPage creates a note, or edits one when n.ID is set. After a
// failed post, view.Old refills the fields and view.Errors has the messages.
templ NoteFormPage(n Note) {
	@Layout(formTitle(n)) {
		<h1>{ formTitle(n) }</h1>
		if errs := view.Errors(ctx); errs.Len() > 0 {
			<div class="errors" role="alert">Please fix the errors below.</div>
		}
		<form method="post" action={ formAction(ctx, n) }>
			@view.CSRFField(ctx)
			if n.ID != 0 {
				@view.MethodField("PUT")
			}
			<label for="title">Title</label>
			<input type="text" id="title" name="title" value={ view.Old(ctx, "title", n.Title) }/>
			@fieldError("title")
			<label for="body">Body</label>
			<textarea id="body" name="body" rows="6">{ view.Old(ctx, "body", n.Body) }</textarea>
			@fieldError("body")
			<p><button type="submit">Save</button></p>
		</form>
	}
}

// fieldError shows the validation message for a field, if any.
templ fieldError(field string) {
	if msg := view.Errors(ctx).Get(field); msg != "" {
		<p class="error">{ msg }</p>
	}
}
```

(Copied from [`examples/forms/notes.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/notes.templ), region `form`.)

- `view.CSRFField(ctx)` renders the hidden `_token` input.
- `view.MethodField("PUT")` renders `_method`, which `web.MethodOverride`
  turns into the request method, so the form reaches the `Put` route. It
  reads URL-encoded bodies only (parsed for binding, and restored for
  handlers that read the raw body); for a form with files
  (`multipart/form-data`), put `?_method=PUT` in the action URL instead.
- `view.Old(ctx, "title", n.Title)` is the value the visitor submitted if
  the last post failed, else the fallback.
- `view.Errors(ctx)` holds the messages of that post, keyed by field.

In a project made with `anetos new`, the components of `views/ui` do
most of this for you. The tutorial's form for an issue:

```templ
// IssueForm opens an issue, or edits one when issue.ID is set. After a
// failed post, view.Old refills the fields and view.Errors has the
// messages.
templ IssueForm(issue models.Issue) {
	@Layout("Issue") {
		@ui.Narrow() {
			if issue.ID == 0 {
				<h1>New issue</h1>
				@ui.Card("") {
					@ui.Form(web.MustURL(ctx, "issues.create"), "POST", nil) {
						@issueFields(issue)
					}
				}
			} else {
				<h1>Edit #{ issue.ID }</h1>
				@ui.Card("") {
					@ui.Form(web.MustURL(ctx, "issues.update", issue.ID), "PUT", nil) {
						@issueFields(issue)
					}
				}
			}
		}
	}
}

templ issueFields(issue models.Issue) {
	@ui.Field("title", "Title", "") {
		@ui.Input("title", "", view.Old(ctx, "title", issue.Title), nil)
	}
	@ui.Field("body", "Description", "") {
		@ui.Textarea("body", view.Old(ctx, "body", issue.Body), templ.Attributes{"rows": "6"})
	}
	@ui.Button(ui.Primary, nil) {
		Save
	}
}
```

(Copied from [`examples/tutorial/views/issues.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/tutorial/views/issues.templ), region `form`.)

- `ui.Form(action, "PUT", nil)` writes the CSRF field, and the
  `_method` field for PUT, PATCH and DELETE.
- `ui.Field` writes the label and, after a failed post, the field's
  message.
- `ui.Input`, `ui.Textarea` and `ui.Select` are marked
  `aria-invalid="true"` when their field failed; you still pass
  `view.Old` as the value.

The [UI components reference](https://docs.anetos.dev/reference/ui/index.md#forms) lists the
others: `ui.Select`, `ui.Checkbox`, `ui.Actions`, `ui.PostButton`…

### 3. Handle the post

A typed handler with validation rules:

```go
func (Notes) Create(c *web.Ctx, in NoteInput) (web.Responder, error) {
	// Invalid input never gets here: the browser is sent back to the form,
	// which shows the errors and the submitted values.
	if err := db.Create(c, &Note{Title: in.Title, Body: in.Body}); err != nil {
		return nil, err
	}
	c.Session().Flash("status", "Note created.")
	return web.RedirectRoute("notes.index"), nil
}
```

(Copied from [`examples/forms`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main.go), region `create`.)

When the rules fail on a form post from a browser, the handler doesn't
run: the errors and the submitted values (except passwords and the token)
are flashed, and the browser is redirected back (303) to the form, which
shows them. The same happens for a `validate.Fail` from a `Validate`
method or the handler, and for values that can't be converted (a letter
in a number field). JSON clients still get a 422 with the errors.

Errors are keyed by the form field name: a field with `form:"content"`
and `json:"body"` gets its message under `content` in a form post.

### 4. Redirect back yourself

`c.Back()` (or the `web.Back()` responder) redirects to the previous page:
the `Referer` if it is on your site (its host is the request's, or the
browser says the request is same-origin), else `/`.

## Complete example

[`examples/forms`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main.go) creates, edits and
deletes notes with these forms.

## How it works

When a handler returns a validation error for a POST, PUT, PATCH or
DELETE from a browser (a navigation, or `Accept: text/html`),
`web.DefaultErrorHandler` flashes the field errors (in order) and
`r.PostForm`, and redirects to the page the form was on (its `Referer`).
On the next request `view.Errors` and `view.Old` read them from the
session; after that they're gone. A custom error handler
(`web.WithErrorHandler`) keeps this only if it passes validation errors
on to `web.DefaultErrorHandler`.

htmx requests are the exception: they get the 422, because htmx swaps
fragments rather than following the redirect to a page. Boosted forms
(`hx-boost`) are page loads, so they are redirected back like the others.

The CSRF token is random, stored in the session, and masked differently
every time it is rendered, so compressed pages don't leak it. Checking
`Sec-Fetch-Site` and `Origin` (Go's `http.CrossOriginProtection`) stops
cross-site posts even before the token is compared. `web.WithTrustedOrigins`
allows other origins of yours.

> **Coming from another framework?** `@view.CSRFField(ctx)` is the
> field Django's `{% csrf_token %}`, Laravel's `@csrf` and Rails' form
> helpers add; `@view.MethodField("PUT")` is the hidden `_method` field
> Laravel and Rails use too; `view.Old(ctx, "title", post.Title)` and
> `view.Errors(ctx)` give back the submitted values and the errors. A
> token mismatch is a 403.

## Testing it

`anetostest` posts forms like a browser: it keeps the session cookie,
sends the CSRF token and the `Referer`, so a failed form redirects back:

```go
// illustrative
app.Get("/notes/new")
app.PostForm("/notes", url.Values{"title": {""}}).
	AssertRedirect("/notes/new").
	AssertValidationErrors("title")
```

See [Test your app](https://docs.anetos.dev/guides/testing/index.md#2-test-a-form).

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| 403 "The page has expired" | No `_token` field, the session expired, or the session cookie isn't sent back | Add `@view.CSRFField(ctx)`; check `SESSION_SECURE` over plain HTTP |
| 403 "Cross-origin request rejected" | The form is on another origin (a different port counts) | `web.CSRF(web.WithTrustedOrigins("https://admin.example.com"))` |
| htmx requests get 403 | The token isn't sent | Put `view.CSRFToken(ctx)` in `hx-headers`, as the layout does |
| A 422 page instead of the form with errors | The route has no session middleware, or the client asked for JSON | Add the middleware; browsers send `Accept: text/html` |
| The form is empty after an error | `view.Old` not used, or the input was larger than the cookie allows | Use `view.Old(ctx, field, fallback)`; long text may not be kept (logged) |
| 405 for a form with `_method=PUT` | `web.MethodOverride` not added, or added with `Use`; or a form with files | `r.UseGlobal(web.MethodOverride)`; for files, `action="/posts/1?_method=PUT"` |
| Redirected to `/` after a failed post | The browser sent no `Referer` (a `Referrer-Policy` of `no-referrer`) | Keep the default policy (`strict-origin-when-cross-origin`) |
| An htmx form gets a 422 page | htmx requests aren't redirected back | Use a regular or boosted form, or render the errors yourself |
| curl or a script gets a 422 page instead of a redirect | It sends `Accept: */*`, so it isn't treated as a browser navigation | Send `Accept: text/html` to test the browser flow |
| A checkbox is checked again after a failed post | `view.Old` can't tell an unchecked box (not sent) from no post | `checked?={ view.OldChecked(ctx, "publish", post.Published) }`, or `ui.Checkbox("publish", "Publish", view.OldChecked(ctx, "publish", post.Published), nil)` |

## Next steps

- [Validation rules reference](https://docs.anetos.dev/reference/validation-rules/index.md)
- [Views, sessions and forms reference](https://docs.anetos.dev/reference/views/index.md)
- [UI components reference](https://docs.anetos.dev/reference/ui/index.md)


# Validation

Source: https://docs.anetos.dev/guides/validation/

Declare rules on an input struct, get one clear message per field, and add
checks of your own.

## Before you start

Read [Handlers and requests](https://docs.anetos.dev/guides/handlers/index.md): rules live on the same input
structs that `web.H` binds.

## Steps

### 1. Add rules to the input

Write rules in a `validate` tag: rules separated by `|`, parameters
after `:` and separated by commas.

```go
// SignUp is the input for POST /signup.
type SignUp struct {
	Name     string `json:"name" validate:"required|max:100"`
	Email    string `json:"email" validate:"required|email"`
	Username string `json:"username" validate:"required|between:3,20|slug"`
	Password string `json:"password" validate:"required|min:12|confirmed"`
	// PasswordConfirmation is compared by the "confirmed" rule on Password.
	PasswordConfirmation string `json:"password_confirmation"`

	Plan    string   `json:"plan" validate:"required|in:free,pro,team"`
	Company string   `json:"company" validate:"required_if:plan,team"`
	Seats   *int     `json:"seats" validate:"min:1|max:500"`
	Website string   `json:"website" label:"web site" validate:"url:https"`
	Tags    []string `json:"tags" validate:"max:5|distinct"`
	Terms   bool     `json:"terms" validate:"accepted"`
}
```

(Copied from [`examples/validation`](https://github.com/anetos-dev/anetos/blob/main/examples/validation/main.go), region `input`.)

`web.H` checks the rules after binding and before your handler. If any fail,
the handler doesn't run and the client gets a **422**:

```json
{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The given data was invalid.",
  "errors": {
    "email": "The email field must be a valid email address.",
    "password": "Use at least 12 characters for your password."
  }
}
```

A browser posting an HTML form gets no 422: on routes with sessions, it
is redirected back to the form, and the page shows the messages and the
submitted values ([Handle HTML forms](https://docs.anetos.dev/guides/forms/index.md)).

Rules run in order and stop at the first failure, so each field gets one
message. Every rule is listed in the
[rules reference](https://docs.anetos.dev/reference/validation-rules/index.md).

### 2. Decide what is optional

Only the `required` family and `accepted` run on an empty field. Every
other rule skips it, so `validate:"url:https"` means "optional, but an HTTPS
URL if given", and `max:5` on an empty list passes (add `required` to
demand at least one item).

"Empty" means a nil pointer, a blank string, an empty slice or map, or a
zero struct or array value, such as a zero `time.Time` or UUID. Numbers and
booleans are **never** empty, because zero may be a real answer. To make a
number optional, use a pointer: `Seats *int` with `min:1|max:500` accepts a
missing value but rejects `0`.

`required` also rejects `0` and `false` in non-pointer fields. For a
checkbox that must be ticked, use `accepted`.

### 3. Name fields in messages

Messages use the field's key (its `json` name, else its `form`, `query`,
`path` or `header` name), turned into words: `first_name` becomes "first
name". Set a `label` tag to choose the words, as `Website` does above ("The
web site field must be a valid URL."). When an HTML form posts the input,
errors are keyed by the `form` name if it differs from the `json` name, so
each message matches its input.

Nested structs, slices and maps of structs are validated too. Their errors
use dotted keys: `address.city`, `items.0.name`. Embedded structs are
flattened the way `encoding/json` flattens them.

### 4. Change messages

Add a `ValidationMessages` method to the input. Keys are `field.rule` for
one field or `rule` for the whole struct:

```go
// ValidationMessages replaces default messages for SignUp. Keys are
// "field.rule" or just "rule".
func (SignUp) ValidationMessages() map[string]string {
	return map[string]string{
		"terms.accepted": "Please accept the terms to continue.",
		"password.min":   "Use at least {0} characters for your password.",
	}
}
```

(Region `messages`.)

Messages can use `{label}`, the rule's parameters `{0}`, `{1}`, … and
`{list}` (all parameters, comma-separated). A key that matches no rule is
a startup error, so typos don't go unnoticed.

Messages are in the request's language. The defaults, the labels and a
`ValidationMessages` value that is a catalog key come from the
translation catalogs (`validation.required`,
`validation.attributes.email`): change them for every struct there, and
translate them, as [Translations](https://docs.anetos.dev/guides/translations/index.md#6-translate-the-frameworks-messages)
shows.

### 5. Add a custom rule

Register named rules in an `init` function, so they exist before routes are
added:

```go
var slugPattern = regexp.MustCompile(`^[a-z0-9]+(?:-[a-z0-9]+)*$`)

func init() {
	validate.Register("slug", "The {label} field may only contain lowercase letters, numbers and single dashes.",
		func(ctx context.Context, f validate.Field) (bool, error) {
			s, _ := f.Value.(string)
			return slugPattern.MatchString(s), nil
		})
}
```

(Region `custom-rule`.)

The rule receives the field's key, label, value (pointers already followed),
the tag parameters and the parent struct. Return an error only when the
check itself failed (a lookup service was down); that becomes a 500, not a
validation message.

### 6. Check what tags can't

Some checks need a database or several fields at once. Do them in the
handler, or in a `Validate(ctx) error` method on the input, which runs after
the tag rules pass. Report a problem with `validate.Fail` (or several with a
`validate.Errors`) so the client gets the same 422 shape:

```go
// Users is a stand-in for a user repository.
type Users interface {
	UsernameTaken(ctx context.Context, username string) (bool, error)
}

// SignedUp is the answer to a sign-up.
type SignedUp struct {
	Username string `json:"username"`
}

// signUpHandler checks what tags can't: whether the username is free.
func signUpHandler(users Users) func(c *web.Ctx, in SignUp) (SignedUp, error) {
	return func(c *web.Ctx, in SignUp) (SignedUp, error) {
		taken, err := users.UsernameTaken(c, in.Username)
		if err != nil {
			return SignedUp{}, err // a 500: the check itself failed
		}
		if taken {
			return SignedUp{}, validate.Fail("username", "This username is already taken.") // a 422, like the tag rules
		}
		return SignedUp{Username: in.Username}, nil // 201: the route's Status
	}
}
```

(Region `handler-check`.)

Any other error is a **500** and its text stays out of the response, so a
failed database call never leaks connection details to clients.

### 7. Validate outside HTTP

`validate.Struct` works on any struct, for example a job payload or a CLI
command's input. It returns nil, a `*validate.Errors`, or the error of a
custom rule that couldn't run:

```go
in := SignUp{
	Name:     "Sam",
	Email:    "sam@example",
	Username: "Sam_H",
	Password: "short",
	Plan:     "team",
}
err := validate.Struct(context.Background(), &in)
if errs, ok := errors.AsType[*validate.Errors](err); ok {
	for _, key := range errs.Keys() {
		fmt.Printf("%-10s %s\n", key, errs.Get(key))
	}
}
```

(Region `standalone`.)

## How it works

The first time a struct type is validated (for `web.H`, when the route is
added), its tags are parsed into a plan that is cached for the life of the
process. Tag mistakes (an unknown rule, `min:abc`, `email` on an `int`,
`required_if` naming a missing field, a message key with a typo) are
reported then, so `web.H` panics at startup rather than on the first
request.

Per request only the plan runs. With the built-in rules, valid input is
checked without allocating memory, except for maps of structs and file
rules (which open the upload); messages are built only when a rule fails.

> **Coming from another framework?** The input struct does the job of a
> Django form, a Laravel form request or Rails' model validations. Rules
> live on the struct; `nullable`, `bail` and `sometimes` aren't needed
> (the startup error says why); `min`/`max` on uploads count files, and
> file size uses `max_size:2MB`; `unique` and `exists` come from the db
> package (see the [rules reference](https://docs.anetos.dev/reference/validation-rules/index.md#database-rules)).

## Testing it

```go
// illustrative
func TestSignUpRules(t *testing.T) {
	err := validate.Struct(context.Background(), &SignUp{Email: "nope"})
	errs, ok := errors.AsType[*validate.Errors](err)
	if !ok || !errs.Has("email") {
		t.Fatalf("got %v, want an email error", err)
	}
}
```

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| Panic at startup: `unknown rule "emial"` | A typo, or a custom rule registered after the route was added | Check the [rules reference](https://docs.anetos.dev/reference/validation-rules/index.md); call `validate.Register` in `init` |
| Panic at startup: `malformed rule "required,email"` | go-playground style tags, possibly on a type from another library | Separate rules with `\|` and parameters with `:`: `required\|max:10`. For a third-party type, add `validate:"-"` to the field that holds it |
| Panic at startup: `rule "email" does not apply to int fields` | The rule doesn't fit the field's type | Use a rule for that type, or change the type |
| `min:1` never fails on an optional number or list | The field wasn't sent or the list is empty, so only `required` runs | Add `required`, or keep it optional on purpose |
| `required` fails for `0` or `false` | Non-pointer numbers and booleans treat zero as missing | Use `*int` / `*bool`, or `accepted` for checkboxes |
| `required` fails for a zero amount of a decimal type | Struct values count as empty when zero | Use a pointer (`*decimal.Decimal`) |
| A `Validate` method's error comes back as a 500 | Plain errors are treated as failures, not messages | Return `validate.Fail(field, message)` |

## Next steps

- [Handle HTML forms](https://docs.anetos.dev/guides/forms/index.md)
- [Validation rules reference](https://docs.anetos.dev/reference/validation-rules/index.md)
- [Handlers and requests](https://docs.anetos.dev/guides/handlers/index.md)
- [Store files](https://docs.anetos.dev/guides/storage/index.md): store the uploads you validated


# Sessions and flash messages

Source: https://docs.anetos.dev/guides/sessions/

Remember things about a visitor between requests, and show a message
once after a redirect.

## Before you start

Set `APP_KEY`: sessions are encrypted with it.

```sh
go tool anetos key:generate
```

(`go get -tool anetos.dev/anetos/cli/cmd/anetos@v0.5.0-rc.1` adds
the tool.) Keep the key secret and the same across instances and
restarts; see [Rotate the key](https://docs.anetos.dev/guides/sessions/index.md#rotate-the-key).

## Steps

### 1. Add the session middleware

Create the manager from the app's configuration and add its middleware
to the routes that serve pages:

```go
sessions, err := session.New(app) // SESSION_* settings; needs APP_KEY
if err != nil {
	return nil, err
}
r := srv.Router()
r.UseGlobal(web.MethodOverride) // forms can send PUT and DELETE with _method
r.Get("/assets/{path...}", web.WrapHandler(assets))

var h Notes
pages := r.Group("", sessions.Middleware, web.CSRF())
pages.Get("/", func(c *web.Ctx) error { return c.RedirectRoute("notes.index") })
pages.Get("/notes", web.H(h.Index)).Name("notes.index")
pages.Get("/notes/new", h.New).Name("notes.new")
pages.Post("/notes", web.H(h.Create)).Name("notes.create")
pages.Get("/notes/{id}/edit", web.H(h.Edit)).Name("notes.edit")
pages.Put("/notes/{id}", web.H(h.Update)).Name("notes.update")
pages.Delete("/notes/{id}", web.H(h.Delete)).Name("notes.delete")
```

(Copied from [`examples/forms`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main.go), region `routes`.)

`session.New` reads the `SESSION_*` settings
([configuration reference](https://docs.anetos.dev/reference/configuration/index.md#sessions)) and
fails at startup, suggesting a key, when `APP_KEY` is missing.

### 2. Store and read values

```go
// illustrative
s := c.Session() // panics if the route has no session middleware

s.Put("theme", "dark")          // any value encoding/json can encode
theme := s.GetString("theme")   // "dark"
cart, ok := session.Value[[]int64](s, "cart")
s.Delete("theme")
```

`session.From(ctx)` returns the session (or nil) from any request
context, for code outside handlers.

### 3. Flash a message for the next page

```go
func (Notes) Create(c *web.Ctx, in NoteInput) (web.Responder, error) {
	// Invalid input never gets here: the browser is sent back to the form,
	// which shows the errors and the submitted values.
	if err := db.Create(c, &Note{Title: in.Title, Body: in.Body}); err != nil {
		return nil, err
	}
	c.Session().Flash("status", "Note created.")
	return web.RedirectRoute("notes.index"), nil
}
```

(Copied from [`examples/forms`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main.go), region `create`.)

A flashed value is there for this request and the next one, then gone.
The layout shows it with `view.Flash(ctx, "status")`. `s.Keep(keys...)`
and `s.Reflash()` keep flashed values for one more request.

### 4. Log in and out safely

```go
// illustrative
s.Regenerate()  // after login: new session ID and CSRF token
s.Invalidate()  // on logout: everything removed, new ID
```

[Authentication](https://docs.anetos.dev/guides/authentication/index.md) calls these for you (`a.Login` and
`a.Logout`); call them yourself if you log users in another way. With a
server-side driver it matters more: a session cookie planted in a
victim's browser before they log in would otherwise share their
logged-in session. With the default cookie
driver, `Invalidate` empties the session in this browser only: the session
lives in the cookie, so a copy of an earlier cookie (stolen, or saved
before logout) keeps working until it expires, after `SESSION_TTL`
without use and in any case `SESSION_MAX_TTL` (7 days by default)
after it started or was last regenerated. With a server-side driver (next
step), `Invalidate` and `Regenerate` remove the old session from the
store, so every copy of the old cookie stops working, and a request that
was still running with the old session (a slow form post with a stolen
cookie) doesn't bring it back when it ends.

### 5. Keep sessions on the server

Set `SESSION_DRIVER` to keep sessions in the database or Redis instead of
the cookie. The cookie then holds only the encrypted session ID: sessions
can be revoked, and hold more than 4 KB.

For the database, add the sessions table to the migrations and run
`migrate`:

```go
// session.Migrations creates the sessions table, for SESSION_DRIVER=database.
if _, err := migrate.New(app, []*migrate.Set{Migrations, session.Migrations("")}, migrate.WithSeeders(Seeders...)); err != nil {
	return nil, err
}
```

(Copied from [`examples/forms`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main.go), region `runner`.)

```env
SESSION_DRIVER=database
```

For Redis, add the `drivers/redis` module and pass its driver
(`REDIS_URL` says where the server is):

```go
// illustrative
sessions, err := session.New(app, redis.SessionDriver()) // SESSION_DRIVER=redis
```

Changing the driver ends every current session: visitors log in again.

### Rotate the key

Move the current key to `APP_PREVIOUS_KEYS` and set a new `APP_KEY`.
Sessions encrypted with the old key keep working and are re-encrypted with
the new one the next time their cookie is written; remove the old key after
`SESSION_TTL`.

## How it works

The whole session is in the cookie, encrypted and authenticated with
AES-256-GCM under a key derived from `APP_KEY` for each cookie value, so there is
nothing to store on the server and a visitor can neither read nor change
it. The cookie is `HttpOnly`, `SameSite=Lax` and, outside development,
`Secure`; a Secure cookie is named `__Host-anetos_session`, so no other
site, subdomains included, can set it. The cookie holds the times the
session started and was last used: after `SESSION_TTL` without a
request, or `SESSION_MAX_TTL` in all, the session is empty, whatever
the browser sends. Responses to requests with a session get
`Cache-Control: private` (unless the handler sets `Cache-Control`) and
`Vary: Cookie`, so shared caches don't store them.

A new visitor gets no cookie until something is stored. After that the
cookie is written when the session changes, and at most every tenth of
the lifetime to keep it alive. Changes made after the response has
started (streaming) aren't saved.

Browsers limit cookies to about 4 KB. Store IDs, not records. If a failed
form's input doesn't fit, it is dropped (the errors are kept) and a warning
is logged; a session that doesn't fit isn't saved and an error is logged.

With a server-side driver, the cookie holds the session ID, encrypted
like a cookie session. The store holds the session encrypted with
`APP_KEY`, under a hash of the ID and without the ID itself, so reading
the store (or a database backup) gives no one a usable session or its
contents. It expires after `SESSION_TTL` without use. Keys start
with `SESSION_PREFIX` (default `APP_NAME:session:`), which `cache:clear`
leaves alone unless `CACHE_PREFIX` is set to a start of it. A saved
session is only replaced while it exists: a session ended meanwhile (by a
logout) stays ended.

A server-side session keeps a failed form's input up to 64 KB (larger
input is dropped, the errors are kept) and holds at most 1 MB; a larger
session isn't saved and an error is logged. If the store can't be read,
the request gets 503 Service Unavailable (through the app's error pages)
rather than an empty session, which would log the visitor out; if it
can't be written, the response goes out and an error is logged. If
removing a session at logout fails, it is logged, and copies of its cookie
keep working until it expires. Two requests of one visitor running at the
same time each save their own changes: the last one wins.

> **Coming from another framework?** `Put`, `Get`/`Value`, `Flash`,
> `Regenerate` and `Invalidate` are the session operations you know.
> The default keeps the session in an encrypted cookie, like Rails'
> default; `database` and `redis` keep it on the server, as Django's and
> Laravel's database and Redis sessions do.

## Testing it

Give a handler a session without the middleware:

```go
// illustrative
s := session.NewSession()
ctx := session.WithSession(context.Background(), s)
```

Across requests, an `anetostest` app keeps the session cookie: check the
session after a response with `res.AssertSessionHas("status", "Saved.")`,
and set values before a request with `app.WithSession(func(s
*session.Session) { … })`. See [Test your app](https://docs.anetos.dev/guides/testing/index.md#2-test-a-form).

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `APP_KEY is not set` at startup | No key configured | `go tool anetos key:generate` |
| Everyone was logged out after a deploy | `APP_KEY` changed; or `SESSION_COOKIE` or `SESSION_SECURE` changed, which renames the cookie | Keep the old key in `APP_PREVIOUS_KEYS`; use the same key and session settings on every instance |
| The session is empty on every request in development | `SESSION_SECURE=true` over plain HTTP, or a custom dev hostname | Leave `SESSION_SECURE` unset in development, or use HTTPS |
| `session too large for its cookie` in the logs | More than about 4 KB stored | Store less: IDs instead of records |
| `web: no session for this request` | `c.Session()` on a route without the middleware | Add `sessions.Middleware` to the route's group |
| Every page answers 503, with `the session store failed` in the logs | The database or Redis server isn't reachable | Check the server; `SESSION_DRIVER=cookie` needs none |
| `SESSION_DRIVER is "redis", but the drivers are [cookie, database]` | The Redis driver wasn't passed | `session.New(app, redis.SessionDriver())` |
| `no such table: sessions` | The sessions migration didn't run | Add `session.Migrations("")` to the runner and run `migrate` |

## Next steps

- [Authentication](https://docs.anetos.dev/guides/authentication/index.md)
- [Handle HTML forms](https://docs.anetos.dev/guides/forms/index.md)
- [Views, sessions and forms reference](https://docs.anetos.dev/reference/views/index.md)


# Configure your application

Source: https://docs.anetos.dev/guides/configuration/

Read settings from `.env` files and the environment into typed Go structs,
with defaults, required keys and validation.

## Before you start

- The framework's own settings (`APP_*`, `LOG_*`) are listed in the
  [configuration reference](https://docs.anetos.dev/reference/configuration/index.md).
- `anetos.New()` loads configuration for you. This guide shows how to add
  your own settings.

## Steps

### 1. Put settings in `.env`

```bash
# .env: local development only; never commit real secrets
APP_NAME=blog
APP_ENV=development

HEARTBEAT_INTERVAL=500ms
DB_URL=postgres://app:secret@localhost:5432/blog
REDIS_URL="redis://${REDIS_HOST}:6379"   # ${NAME} uses the environment, else earlier keys
```

Commit a `.env.example` with every key and safe placeholder values, and keep
`.env` itself out of git (the generated `.gitignore` already does).

### 2. Describe them with a struct

```go
// HeartbeatConfig is this app's own configuration, bound from the environment.
type HeartbeatConfig struct {
	Interval time.Duration `env:"HEARTBEAT_INTERVAL" default:"2s"`
	FailAt   int           `env:"HEARTBEAT_FAIL_AT"` // simulate a crash after N beats (0 = never)
}

func (c HeartbeatConfig) Validate() error {
	if c.Interval < 10*time.Millisecond {
		return errors.New("HEARTBEAT_INTERVAL must be at least 10ms")
	}
	return nil
}
```

(Copied from [`examples/lifecycle`](https://github.com/anetos-dev/anetos/blob/main/examples/lifecycle/main.go),
region `config`.)

- `env:"KEY"` names the variable; `env:"KEY,required"` makes it mandatory.
- `default:"…"` applies when the key is missing **or empty**.
- A `Validate() error` method runs after binding, for rules that tags can't
  express.

### 3. Bind it at startup

```go
// illustrative
app, err := anetos.New()
if err != nil {
	return err
}
cfg, err := config.Get[HeartbeatConfig](app.Source())
if err != nil {
	return err // lists every missing or invalid key at once
}
```

Pass `cfg` (or the fields you need) to the code that uses it. Don't look up
keys by string elsewhere in the app.

### 4. Group related settings with prefixes

```go
// illustrative
type DatabaseConfig struct {
	URL     string `env:"URL,required"`
	MaxOpen int    `env:"MAX_OPEN" default:"20"`
}

type Config struct {
	Primary DatabaseConfig `prefix:"DB_"`         // DB_URL, DB_MAX_OPEN
	Replica DatabaseConfig `prefix:"DB_REPLICA_"` // DB_REPLICA_URL, …
}
```

## How it works

Values are looked up in three layers, highest priority first:

1. **Process environment**: what production deployments normally use.
2. **`.env.<APP_ENV>`**, e.g. `.env.testing`, if it exists.
3. **`.env`**, if it exists.

Missing files are fine. A file with a syntax error stops startup with the
file name and line number. Binding runs once at startup, and the rest of your
app only sees typed structs.

> **Coming from another framework?** The struct takes the place of a
> settings file (Django's `settings.py`, Laravel's `config/*.php`,
> Rails' `config/`), read at startup, so there's no config cache to
> clear.

## Testing it

Pass a `config.Map` instead of reading real files or the environment:

```go
// illustrative
cfg, err := config.Get[HeartbeatConfig](config.Map{"HEARTBEAT_INTERVAL": "1s"})

app, err := anetos.New(anetos.WithSource(config.Map{"APP_ENV": "testing"}))
```

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `invalid duration "5"` | Durations need a unit | Use `5s`, `500ms`, `2m` |
| `required but not set` although the key is in `.env` | The value is empty | Empty counts as unset; give it a value |
| `APP_DEBUG=true is not allowed when APP_ENV=production` | Debug mode in production | Set `APP_ENV=development` locally |
| A value from `.env` is ignored | The same variable is set in your shell or container, even to `""` | The process environment wins, and an empty value there hides `.env` (the default applies); unset it there |
| Password with `$` is mangled | Written as `${...}` | Only `${NAME}` expands; use single quotes for literal values |

## Next steps

- [Configuration reference](https://docs.anetos.dev/reference/configuration/index.md): every framework
  key and the full tag syntax.
- [Application lifecycle](https://docs.anetos.dev/concepts/application-lifecycle/index.md): where
  configuration fits in startup.


# Commands

Source: https://docs.anetos.dev/guides/commands/

Your application builds to one binary. Its first argument picks what it
does: run the app (the default), run only some process types, migrate the
database, list the routes, or run commands of your own.

## Before you start

The app calls `app.Execute()` at the end of `main`, as projects made by
`anetos new` do:

```go
// illustrative
func main() {
	app, err := anetos.New()
	if err != nil {
		log.Fatal(err)
	}
	// connect the database, add the server and routes, …
	app.Execute()
}
```

## Steps

### 1. Run the app

```sh
./blog                      # the default: run every component
./blog run --only=web      # only the components of these process types
./blog serve                # the same as run --only=web
./blog help                 # every command
./blog help migrate         # one command's arguments
```

`run` starts the components and stops them gracefully on Ctrl-C or
`SIGTERM`. Components without a process type run in every process (see
[the runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md)).

### 2. Use the built-in commands

| Command | Added by |
|---|---|
| `run [--only=type,…]` | Every app |
| `serve`, `route:list` | `web.NewServer` |
| `openapi` | `openapi.Register` ([Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md)) |
| `migrate`, `migrate:rollback`, `migrate:reset`, `migrate:fresh`, `migrate:status`, `db:seed`, `search:reindex` | `migrate.New` ([Migrations](https://docs.anetos.dev/guides/migrations/index.md), [Search](https://docs.anetos.dev/guides/search/index.md)) |
| `cache:clear` | `cache.New` ([Cache](https://docs.anetos.dev/guides/cache/index.md)) |
| `ai:embed` | `ai.EmbeddingsFor` ([Search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md)) |
| `queue:work`, `queue:failed`, `queue:retry`, `queue:forget`, `queue:flush`, `queue:clear` | `queue.New` ([Queues](https://docs.anetos.dev/guides/queues/index.md)) |
| `pubsub:publish` | `pubsub.New` ([Pub/sub listeners](https://docs.anetos.dev/guides/pubsub/index.md)) |
| `schedule:list`, `schedule:run`, `schedule:test`, `schedule:work` | `schedule.New` ([Scheduling](https://docs.anetos.dev/guides/scheduling/index.md)) |

A name may be shortened, each part between colons, while it stays
unique among the commands with as many parts: `./app r:l` is
`route:list`, `./app mi` is `migrate`, `./app m:s` is
`migrate:status`. An ambiguous one lists what it could be and exits
with status 2. In scripts and deploy files, write the whole name: a
command added later can make a short one ambiguous, or change what it
runs.

### 3. Add your own

```go
app.Command("blog:stats", "Print how many authors and posts there are", func(ctx context.Context, args *cmd.Args) error {
	authors, err := db.Query[Author](ctx).Count()
	if err != nil {
		return err
	}
	posts, err := db.Query[Post](ctx).Count()
	if err != nil {
		return err
	}
	fmt.Fprintf(args.Stdout, "%d authors, %d posts\n", authors, posts)
	return nil
})
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `custom-command`.)

A command runs with the app booted: its context carries what the app
provides (the database here), and the app is closed afterwards, so
shutdown hooks run. The context is canceled on Ctrl-C.

For flags, parse `args.Args` with a `flag.FlagSet` through `args.Parse`,
which reports bad flags as usage errors (the binary prints them with the
command's usage and exits with status 2):

```go
// illustrative
app.Command("reports:send", "Email the weekly report", func(ctx context.Context, args *cmd.Args) error {
	fs := flag.NewFlagSet("reports:send", flag.ContinueOnError)
	dryRun := fs.Bool("dry-run", false, "print the report instead of sending it")
	if err := args.Parse(fs); err != nil {
		return err
	}
	if fs.NArg() > 0 {
		return cmd.Usagef("unexpected argument %q", fs.Arg(0))
	}
	return reports.Send(ctx, *dryRun)
})
```

`app.AddCommand(cmd.Command{…})` takes a `Usage` line for help (list the
flags there) and returns an error instead of panicking. `-h` or `--help`
right after the command's name never reaches it: the binary prints its
usage and description. Later in the arguments, `args.Parse` handles it
and prints the flags.

## How it works

`app.Execute()` reads `os.Args`: no arguments (or only flags) means
`run`; `help`, `-h` and `--help` list the commands. It exits with status
0 on success, 1 when the command fails (also when a signal interrupts it
before it finishes), and 2 for usage errors (an unknown command, a bad
flag, a `cmd.Usagef` error). `run` and `serve` exit with 0 when a signal
stops the app, since that is how they end. A second Ctrl-C ends the
program at once. Commands that manage the app themselves (`run`,
`serve`: `ManagesApp` in `cmd.Command`) boot, run and stop it; the others
run between `app.Boot` and `app.Close`, which also runs if the command
panics. `help` doesn't boot the app, so it works without a database;
commands that boot it (`route:list` too) need the database reachable.

> **Coming from another framework?** This is the job of Django's
> `manage.py`, Laravel's `artisan` or Rails' `bin/rails`, built into your
> binary: `./blog migrate`, and custom commands are functions registered
> on the app instead of classes. Code generators (`make:*`) live in the
> `anetos` tool instead, since they write source.

## Testing it

`app.ExecuteArgs(ctx, args, stdout, stderr)` runs a command without
exiting and returns the exit status, as
[`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main_test.go) does. An
app runs one command: create a new one per call.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `unknown command "migrate"` | `migrate.New` wasn't called before `Execute` | Call it while setting up the app |
| `"m:r" could be migrate:reset, migrate:rollback` | A short name that fits several commands | Write more of it, or the whole name |
| `command "x" registered twice` | Two commands with one name (`app.Command` panics, `app.AddCommand`, `migrate.New` and `web.NewServer` return the error) | Register each once |
| `unknown process type "…"` | `--only` names a process type no background component has and no package declared (the error lists the known ones) | Check `help run` and the process types of your background components (`web`, `worker`, `scheduler`, `listener`; before v0.5, `http`, `workers`, `listeners`) |

## Next steps

- [`anetos` tool reference](https://docs.anetos.dev/reference/cli/index.md)
- [Migrations](https://docs.anetos.dev/guides/migrations/index.md)


# Test your app

Source: https://docs.anetos.dev/guides/testing/

Boot the app in a test, send it requests like a browser or an API
client, and check the responses, the session, the database, the jobs,
events and email the app sent, and its files, with `anetostest`; freeze
or move the app's clock.

## Before you start

Give your app a `setup` function that connects the database and adds the
server and routes, and call it from `main`, as `anetos new` projects do:

```go
// illustrative
func setup(app *anetos.App) (*web.Server, error) {
	if _, err := db.Connect(context.Background(), app, sqlite.Driver()); err != nil {
		return nil, err
	}
	if _, err := migrate.New(app, []*migrate.Set{migrations.All}); err != nil {
		return nil, err
	}
	srv, err := web.NewServer(app)
	…
	return srv, nil
}
```

Tests then build the same app as production, with test settings.

## Steps

### 1. Start the app in a test

```go
// illustrative
func TestHome(t *testing.T) {
	app := anetostest.New(t, setup)
	app.Get("/").AssertOK().AssertSee("Welcome")
}
```

`anetostest.New` builds the app with `setup`, boots it, runs its
migrations (when `setup` called `migrate.New`) and closes it when the
test ends. The settings, from highest priority:

1. `anetostest.Env(map[string]string{…})` options;
2. `APP_ENV=testing`, a random `APP_KEY`, and a `CACHE_PREFIX`,
   `SESSION_PREFIX`, `QUEUE_PREFIX` and `PUBSUB_PREFIX` of the app's own,
   so tests sharing a store don't see each other's items, sessions, Redis
   jobs or streams (they are removed when the app shuts down);
   `MAIL_DRIVER=memory`, so emails are kept, not sent (see
   [Send email](https://docs.anetos.dev/guides/mail/index.md#6-test)); and `STORAGE_DRIVER=memory`, so files
   are kept in memory (see [Store files](https://docs.anetos.dev/guides/storage/index.md#7-test));
3. the process environment;
4. `.env.testing` next to `go.mod`, if there is one (for PostgreSQL or
   MySQL, all the `DB_*` settings: see
   [Switch a project to PostgreSQL or MySQL](https://docs.anetos.dev/guides/database/index.md#5-switch-a-project-to-postgresql-or-mysql));
5. `HTTP_ACCESS_LOG=false`, `APP_URL=http://example.test` (the test client's site) and
   `MAIL_FROM_ADDRESS=test@example.com`.

`.env` isn't read, and with SQLite and neither `DB_NAME` nor `DB_URL`
set (or set to `""`), the database is in memory: a test never touches
your development database.

The app's logs go to the test's log, shown when a test fails or with
`go test -v`. Make one app per test or subtest (it reports to the `t` it
was made with). Tests can call `t.Parallel()` with in-memory SQLite and
with PostgreSQL or MySQL, but not with a SQLite file, where each test's
transaction holds the database's only write lock.

### 2. Test a form

The app works like a browser: it keeps cookies (so the session), sends
the session's CSRF token with every `POST`, `PUT`, `PATCH` and `DELETE`,
and sends the last HTML page it loaded as the `Referer`, so a failed form
goes back to that page:

```go
func TestCreateNote(t *testing.T) {
	app := anetostest.New(t, setup)

	app.Get("/").AssertRedirect("/notes")
	app.Get("/notes/new").
		AssertOK().
		AssertSee("<title>New note · Notes</title>", "/assets/htmx.min.js?v=")

	// Invalid: back to the form, with the errors and the input kept.
	app.PostForm("/notes", url.Values{"title": {"<Groceries>"}, "body": {""}}).
		AssertRedirect("/notes/new").
		AssertValidationErrors("body").
		Follow().
		AssertSee(`value="&lt;Groceries&gt;"`, "The body field is required.", "Please fix the errors below.")

	// Valid: to the list, with a flash message shown once.
	app.PostForm("/notes", url.Values{"title": {"Groceries"}, "body": {"Milk"}}).
		AssertRedirectRoute("notes.index").
		AssertSessionHas("status", "Note created.").
		Follow().
		AssertSee("Note created.", "<strong>Groceries</strong>")
	app.Get("/notes").AssertDontSee("Note created.")
}
```

(Copied from [`examples/forms/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main_test.go), region `test-forms`.)

Assertions report a failure with the request and the start of the body,
and return the response, so they chain. `Follow` loads the redirect's
target (on the test site only). `AssertSee` finds text as it is or
HTML-escaped, as templates write it.

Log a user in with `anetostest.ActingAs`, for the requests that follow:
it writes the session a password login would, so the test
needn't post the login form. Call it again to switch users:

```go
// illustrative
ada := anetostest.Create(app, factories.Users)
anetostest.ActingAs(app, &ada).Get("/dashboard").AssertOK()
```

Put other things in the session before a request, such as a cart, with
`WithSession`:

```go
// illustrative
app.WithSession(func(s *session.Session) { s.Put("cart", "42") }).
	Get("/checkout").
	AssertOK()
```

### 3. Test a JSON API

`GetJSON`, `PostJSON`, `PutJSON`, `PatchJSON` and `DeleteJSON` send and
accept JSON:

```go
func TestCreatePost(t *testing.T) {
	app := anetostest.New(t, setup) // a migrated database; the test leaves no rows behind
	author := anetostest.Create(app, Authors)

	app.PostJSON("/posts", map[string]any{"author_id": author.ID, "title": "Hello Go", "body": "a", "publish": true}).
		AssertCreated().
		AssertJSONPath("title", "Hello Go")
	anetostest.AssertDatabaseHas[Post](app, PostCols.Title.Eq("Hello Go"), PostCols.AuthorID.Eq(author.ID))

	app.PostJSON("/posts", map[string]any{"author_id": author.ID + 1, "title": "x", "body": "y"}).
		AssertUnprocessable().
		AssertValidationErrors("author_id")
	anetostest.AssertDatabaseCount[Post](app, 1)
}
```

(Copied from [`examples/database/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main_test.go), region `test-api`.)

`AssertJSONPath("data.0.title", "Hello")` checks one value (keys and
array indexes separated by dots); `AssertJSON(v)` the whole body; and
`res.JSON(&v)` decodes it. Values are compared as JSON, so `2` matches
`2.0` (exactly, however large) and a struct matches an object. `AssertValidationErrors` reads a 422
problem's `errors` for an API client, and the session's errors after a
form's redirect.

### 4. Make rows with factories

A factory (package `anetos.dev/anetos/db/factory`; a project keeps them
in `database/factories`, where `make:auth` writes `Users`) makes valid
model values, with a sequence number for values that must differ:

```go
// Authors makes valid authors, each with its own email.
var Authors = factory.New(func(n int) Author {
	return Author{Name: fmt.Sprintf("Author %d", n), Email: fmt.Sprintf("author%d@example.com", n)}
})

// Posts makes drafts; set AuthorID with With.
var Posts = factory.New(func(n int) Post {
	return Post{Title: fmt.Sprintf("Post %d", n), Body: "Text.", Tags: []string{}}
})
```

(Copied from [`examples/database/factories_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/database/factories_test.go), region `factories`.)

Create rows in the test's database, changing what the test cares about
with `With` (which returns a new factory, so the base stays shared):

```go
// illustrative
ada := anetostest.Create(app, Authors)
published := Posts.With(func(p *Post) { p.AuthorID, p.PublishedAt = ada.ID, &now })
anetostest.CreateMany(app, published, 3)
draft := Posts.Make() // a value, not saved
```

Put factories where both tests and seeders can import them: projects made
with `anetos new` have a `database/factories` package for them (the
examples keep theirs in package `main`). A seeder calls
`factories.Posts.CreateMany(ctx, 50)`; see [Seed the database](https://docs.anetos.dev/guides/seeders/index.md).

The sequence number counts up for the whole test binary and never
resets, so a test's rows aren't numbered from 1: check the values
`Create` and `CreateMany` return, not "Post 1".

### 5. Check the database

```go
// illustrative
anetostest.AssertDatabaseHas[Post](app, PostCols.Title.Eq("Hello"))
anetostest.AssertDatabaseMissing[Post](app, PostCols.ID.Eq(id))
anetostest.AssertDatabaseCount[Post](app, 3, PostCols.AuthorID.Eq(ada.ID))
anetostest.AssertSoftDeleted[Post](app, PostCols.ID.Eq(id))
```

The conditions are the query builder's, and rows are counted as
`db.Query[T]` sees them: soft-deleted rows only count for
`AssertSoftDeleted`. To call your own code with the test's database, pass
`app.Context()`:

```go
// illustrative
post, err := posts.Publish(app.Context(), id)
```

### 6. Check jobs, events, emails and messages

`anetostest` records what the app dispatches to the queue, emits as
events, sends or queues as email, and publishes to pub/sub, and checks
it with typed assertions. By default these still happen as usual (with
`QUEUE_DRIVER=sync`, jobs run at once); fake them to only record:

| Option | Then |
|---|---|
| `anetostest.FakeQueue()` | Dispatched jobs are recorded, not run or stored (queued email and queued listeners too) |
| `anetostest.FakeEvents(OrderPlaced{}, …)` | Those events (all, with no arguments) are recorded and don't reach their listeners |
| `anetostest.FakePubSub()` | Published messages are recorded, not sent to the broker |

Email is never sent in tests (`MAIL_DRIVER=memory`), so it needs no
fake. For login with Google or GitHub, `anetostest.FakeSocial()` puts
a stand-in provider in their place and `app.SocialLogin` logs in with
the account you give (see [Social login](https://docs.anetos.dev/guides/social-login/index.md#3-test)).
Models are never called either (`AI_PROVIDER=fake`):
`anetostest.FakeAI(…)` scripts their answers, and `app.AssertPrompted`
checks what the app asked (see [Add AI to your app](https://docs.anetos.dev/guides/ai/index.md#6-test-it)).

```go
// With the queue and the OrderPlaced event faked, placing an order only
// records the charge job and the event: the test checks they were
// dispatched and emitted, and nothing ran.
func TestPlaceOrderFaked(t *testing.T) {
	g := &FakeGateway{}
	fakeGateway(t, g)
	app := anetostest.New(t, setup, anetostest.FakeQueue(), anetostest.FakeEvents(OrderPlaced{}))

	id := placeOrder(t, app, "Book", 1500)
	anetostest.AssertDispatched(app, func(j ChargeOrder) bool { return j.OrderID == id })
	anetostest.AssertEmitted(app, func(e OrderPlaced) bool { return e.OrderID == id && e.Cents == 1500 })
	anetostest.AssertMailNotSent[ReceiptMail](app, nil) // its listener didn't run
	if orderStatus(t, app, id) != "pending" || g.Charges() != 0 {
		t.Error("the charge ran")
	}
}
```

(Copied from [`examples/queue/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main_test.go), region `test-fakes`.)

Each assertion takes the type and a `match` function (`nil` for any):

| Check | Assertions | Values |
|---|---|---|
| Jobs | `AssertDispatched[J]`, `AssertNotDispatched[J]`, `app.AssertNothingDispatched()` | `Jobs[J](app)`; `app.Dispatched()`, function jobs included |
| Events | `AssertEmitted[E]`, `AssertNotEmitted[E]`, `app.AssertNothingEmitted()` | `Events[E](app)`, `app.Emitted()` |
| Email | `AssertMailSent[M]` (`mailer.Send`), `AssertMailQueued[M]` (`mailer.Queue`), `AssertMailNotSent[M]`, `app.AssertNoMail()` | `Mailables[M](app)`, `app.Mail()` |
| Pub/sub | `AssertPublished[T](app, topic, match)`, `AssertNotPublished[T]` | `Messages[T](app, topic)`, `app.Published()` |

### 7. Check files

Disks keep their files in memory in tests (`STORAGE_DRIVER=memory`), so
each test starts with empty disks. `app.Disk()` (the default disk) and
`app.Disk("avatars")` check them; the clock ([step 8](https://docs.anetos.dev/guides/testing/index.md#8-control-the-clock))
lets a test go past a link's expiry:

```go
// The upload is on the default disk, and its temporary URL stops working
// after 15 minutes: the test travels in time instead of waiting.
func TestDocumentLink(t *testing.T) {
	app := anetostest.New(t, setup, env)
	uploaded := app.Freeze(time.Time{})

	var doc Document
	app.PostMultipart("/documents", nil, anetostest.Upload{Field: "file", Filename: "q3.pdf", Content: pdf}).
		AssertStatus(http.StatusCreated).
		JSON(&doc)
	app.Disk().AssertContent("documents/"+doc.Name, string(pdf))
	app.Disk("avatars").AssertMissing("documents/" + doc.Name)
	if !doc.UploadedAt.Equal(uploaded) {
		t.Errorf("uploaded at %v, want %v", doc.UploadedAt, uploaded)
	}

	app.Travel(14 * time.Minute)
	app.Get(doc.URL).AssertOK()
	app.Travel(2 * time.Minute)
	app.Get(doc.URL).AssertStatus(http.StatusForbidden)
}
```

(Copied from [`examples/files/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/files/main_test.go), region `test-disk`.)

`AssertExists`, `AssertMissing` and `AssertContent` chain; `Files(prefix)`
lists paths.

### 8. Control the clock

`app.Freeze(t)` stops the app's clock (at the current time, for the zero
time) and returns the time; `app.Travel(d)` moves it; `app.Unfreeze()`
returns to the real time. The framework reads the time from that clock:
timestamps, the expiry of sessions, cookies, tokens, signed URLs and
cached items, `after:now` rules. Read it in your code with
`anetos.Now(ctx)` instead of `time.Now()`, so tests control it too.

```go
// With the clock frozen, timestamps are known: created_at, published_at
// (set by the handler from anetos.Now), and deleted_at an hour later.
func TestTimestamps(t *testing.T) {
	app := anetostest.New(t, setup)
	now := app.Freeze(time.Time{})
	author := anetostest.Create(app, Authors)

	var p Post
	app.PostJSON("/posts", map[string]any{"author_id": author.ID, "title": "Hello", "body": "x", "publish": true}).
		AssertCreated().
		JSON(&p)
	anetostest.AssertDatabaseHas[Post](app, PostCols.ID.Eq(p.ID), PostCols.CreatedAt.Eq(now), PostCols.PublishedAt.Eq(&now))

	app.Travel(time.Hour)
	app.Delete("/posts/" + strconv.FormatInt(p.ID, 10)).AssertNoContent()
	later := now.Add(time.Hour)
	anetostest.AssertSoftDeleted[Post](app, PostCols.ID.Eq(p.ID), PostCols.DeletedAt.Eq(&later))
}
```

(Copied from [`examples/database/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main_test.go), region `test-clock`.)

Travel past an expiry instead of waiting for it:

```go
// The reset link works for AUTH_RESET_TTL (60 minutes): travel past it.
func TestResetLinkExpires(t *testing.T) {
	app := anetostest.New(t, setup)
	createUser(t, app, "Ada", "ada@example.com", false)
	app.Get("/forgot-password")
	app.PostForm("/forgot-password", url.Values{"email": {"ada@example.com"}})
	q, _ := url.ParseQuery(emailedLink(t, app, "Reset your password")[len("/reset-password?"):])

	app.Travel(61 * time.Minute)
	app.Get("/reset-password?" + q.Encode())
	app.PostForm("/reset-password", url.Values{"token": {q.Get("token")}, "password": {"new password"}, "password_confirmation": {"new password"}}).
		AssertValidationErrors("password")
}
```

(Copied from [`examples/auth/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main_test.go), region `test-clock`.)

The clock doesn't move time kept elsewhere: database and Redis servers
(items in the database and Redis cache stores expire, and those queues'
delayed jobs become due, on their server's clock), timeouts, and the
scheduler's and workers' loops. The [testing reference](https://docs.anetos.dev/reference/anetostest/index.md#clock-anetostest-anetos)
lists what reads the app's clock.

## Complete example

- [`examples/forms/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main_test.go):
  forms, validation, flash messages, htmx requests.
- [`examples/database/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main_test.go):
  a JSON API with factories, database assertions and a frozen clock.
- [`examples/queue/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main_test.go):
  jobs, events and email, run or faked.
- [`examples/files/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/files/main_test.go):
  uploads, disks and expiring links.

## How it works

Everything a test does runs on the test's context (`app.Context()`),
which carries the app's database. With SQLite and no `DB_NAME`, each
test gets its own in-memory database, migrated from scratch. With a
database server (or a SQLite file), migrations run once and each test runs
in a transaction that is rolled back when it ends, so tests leave nothing
behind and don't see each other's rows. Each request runs in a savepoint
inside it, so a failed statement (which aborts a PostgreSQL transaction)
doesn't break the rest of the test: the request's writes are undone
instead.

This differs from production in a few ways. Work done directly in the
test's transaction counts as committed: `db.AfterCommit` callbacks run
when a `db.Tx` inside it (a request's, say) commits, or at once outside
one. Code with its own connections (queue workers, `db.WithoutTx`)
doesn't see the test's rows. On PostgreSQL, a request that catches a failed
statement and goes on querying fails (production, without the
surrounding transaction, would carry on). A query canceled by a timeout
closes the connection holding the transaction on PostgreSQL and MySQL, and
MySQL commits it on any schema change. Test those paths with
`anetostest.WithoutTransaction()`.

Requests go straight to the router, without a network: `httptest`
requests to `http://example.test`, with a cookie jar. They carry no
`Origin` or `Sec-Fetch-Site` header, like a client that isn't a browser,
so `web.CSRF` checks only the token; its cross-origin check is covered by
the framework's own tests. `app.Do(req)`
sends a request you build, with extra headers:

```go
// illustrative
req := httptest.NewRequest(http.MethodDelete, "/notes/1", nil)
req.Header.Set("HX-Request", "true")
app.Do(req).AssertOK()
```

Every method is listed in the [anetostest reference](https://docs.anetos.dev/reference/anetostest/index.md).

## Testing it

Run `go test ./...`, and `go test -race ./...` in CI. For PostgreSQL or
MySQL in CI, set `DB_*` (or `DB_URL`) in the job's environment: it wins
over `.env.testing`.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `connection refused` or `database "…_test" does not exist` | The test database from `.env.testing` isn't there | Create it, or set `DB_*` for the test run |
| `database is locked` | Two apps on one SQLite file: parallel tests, or an app made in a test and another in its subtest | Don't run those in parallel, or use in-memory SQLite |
| A request hangs until the test times out | Code opened its own connection (or `db.Tx` on a new context) and waits for the test's transaction's locks; or two parallel tests insert the same unique value | Use the request's context; `anetostest.WithoutTransaction()` and clean up yourself; unique values from factories |
| `current transaction is aborted` (PostgreSQL) | A handler went on after a failed statement | Test that path with `anetostest.WithoutTransaction()` |
| `The request left the test's transaction unusable` | A timeout canceled a query, or a schema change on MySQL | `anetostest.WithoutTransaction()` for that test |
| A queue worker doesn't find the test's rows | Workers use their own connections, outside the test's transaction | `QUEUE_DRIVER=sync`, or `anetostest.WithoutTransaction()` for that test |
| 403 "The page has expired" | The form sent a `_token` field (it wins over the automatic token), or the route has no session middleware | Drop the field; add `sessions.Middleware` |
| `subtest may have called FailNow on a parent test` | An app made in a test used in its subtest | Make the app in the subtest |
| `setup returned no server` | `setup` returns a nil `*web.Server` | Return the server |
| A redirect back goes to `/` | No HTML page loaded first, so there's no `Referer` | `app.Get` the form's page before posting |
| `app.Freeze` doesn't change a time your code sets | The code reads `time.Now()` | Use `anetos.Now(ctx)` |
| An item in the database or Redis cache doesn't expire after `app.Travel` | Those stores use their server's clock | Use `CACHE_DRIVER=memory` in tests, or test expiry another way |
| `anetostest: FakeQueue: the app has no queue` | `setup` doesn't call `queue.New` (or `events.New`, `pubsub.New` for the other fakes) | Drop the option, or set the service up |
| `job type … isn't registered` from `Jobs[J]` or `AssertDispatched[J]` | `J` isn't registered with `queue.Register` | Register it in `setup`; check function jobs with `app.Dispatched()` |
| `Search` finds nothing on MySQL or MariaDB in a test | Their full-text indexes only see committed rows, and the test runs in a transaction | `anetostest.WithoutTransaction()` for that test, or test search on SQLite or PostgreSQL |
| The app doesn't start: a search index doesn't match `DB_SEARCH_LANGUAGE` | The test database was migrated with other search settings | Run `search:reindex` (or `migrate:fresh`) on it with the test settings |

> **Coming from another framework?** `anetostest.New` gives each test a
> fresh database, like Django's `TestCase`, Laravel's `RefreshDatabase`
> or Rails' transactional tests. `app.PostForm(…).AssertRedirect(…)`
> and the other assertions work on whole requests; factories are
> functions returning structs, and `Posts.With(…)` is a factory with
> overrides.
> `anetostest.FakeQueue()`, `FakeEvents(…)` and `FakePubSub()` record
> instead of sending, with typed assertions
> (`AssertDispatched[ChargeOrder]`); mail needs no fake, since tests
> never send it. `app.Freeze` and `app.Travel` move the clock that
> `anetos.Now(ctx)` reads, and `app.Disk()` gives each test its own
> disk.

## Next steps

- [Handle forms](https://docs.anetos.dev/guides/forms/index.md)
- [Validate input](https://docs.anetos.dev/guides/validation/index.md)
- [Seed the database](https://docs.anetos.dev/guides/seeders/index.md): factories work in seeders too.


# Describe an API with OpenAPI

Source: https://docs.anetos.dev/guides/openapi/

Package `web/openapi` writes an OpenAPI 3.1 document of your API from
its routes and its typed handlers: what each operation reads and
answers, which credentials it needs and how it fails. You commit the
document (`openapi.json`) beside the code, a test fails when it's out of
date, and the app serves it for clients and tools.

## Before you start

- Handlers routed with `web.H` (typed handlers: [Handlers](https://docs.anetos.dev/guides/handlers/index.md)).
  The document describes only those: a plain `func(c *web.Ctx) error`
  says nothing about what it reads or writes.
- A project made with `anetos new --stack=api` has all of this already:
  `routes.OpenAPI` in `routes/api.go`, `openapi.Register` in `main.go`,
  `openapi.json` and its test. `make:auth` and `make:crud` update the
  file.

## Steps

### 1. Describe the API

A `Config` names the API and says which routes it covers. The tracker
example's:

```go
// OpenAPI describes the API from its typed handlers: `go run . openapi`
// writes openapi.json, which api_test.go checks is up to date, and the
// app serves it at /api/openapi.json.
var OpenAPI = openapi.Config{
	Title:       "Tracker",
	Version:     "1.0.0",
	Description: "Projects and issues, for clients with an API token: create one on the tokens page.",
	Prefix:      "/api",
	Path:        "/api/openapi.json",
}
```

(Copied from [`examples/tracker/routes/tracker.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tracker/routes/tracker.go), region `openapi`.)

| Field | Means |
|---|---|
| `Title` | The API's name (required) |
| `Version` | The document's version, `1.0.0` if empty: yours, not Anetos's |
| `Description` | An introduction, in Markdown |
| `Prefix` | Only the routes at or below this path (`/api/v1`); empty: every typed route |
| `File` | Where `openapi` writes and `Check` reads, `openapi.json` if empty |
| `Path` | Where the app serves the document; empty: not served |
| `Servers` | The API's base URLs; none: `/`, the document's own host |
| `SecuritySchemes` | Schemes your middleware names besides `bearer` (step 5) |

### 2. Add the command and the route

In `setup`, after the routes:

```go
// The API's description: `go run . openapi`, GET /api/openapi.json.
if err := openapi.Register(app, srv, routes.OpenAPI); err != nil {
	return nil, err
}
```

(Copied from [`examples/tracker/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tracker/main.go), region `openapi`.)

### 3. Write the document

```sh
go run . openapi            # writes openapi.json
go run . openapi --check    # exits 1 if openapi.json is out of date
go run . openapi --out=-    # prints it
```

The command builds the document from the routes alone: it doesn't boot
the app, so it needs no database. It warns about what it can't describe
(below). The same routes always give the same bytes, so the file's diff
shows how a change alters the API.

### 4. Check it in a test

```go
// openapi.json describes the API as it is: after changing a route or a
// handler's types, update it with `go run . openapi`.
func TestOpenAPI(t *testing.T) {
	app := anetostest.New(t, setup)
	if err := openapi.Check(app.Router(), routes.OpenAPI); err != nil {
		t.Fatal(err)
	}
	app.Get("/api/openapi.json").AssertOK().AssertJSONPath("info.title", "Tracker")
}
```

(Copied from [`examples/tracker/api_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/tracker/api_test.go), region `openapi-test`.)

`Check` fails with the first line that differs and the command to run,
and when a route under `Prefix` is one the document can't describe. CI
runs your tests, so a pull request can't change the API without the
document.

### 5. Say what your middleware asks for

The document can't look inside a middleware: a middleware tells it, by
returning its handler through `web.Documented`. Package `auth`'s
`Require` says its routes need a bearer token (and may answer 401),
`RequireAbilities("bookmarks:write")` that the token needs those
abilities (its scopes, and 403), `TokenMiddleware` that a bad token is a
401, `rbac.Require` 401 and 403, `ratelimit.Middleware` 429. Your own,
for a key partners send in a header:

```go
// illustrative
func partnerKey(next http.Handler) http.Handler {
	return web.Documented(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if !validPartnerKey(r.Header.Get("X-Partner-Key")) {
			web.WriteError(w, r, web.Error(http.StatusUnauthorized, "A partner key is needed."))
			return
		}
		next.ServeHTTP(w, r)
	}), web.MiddlewareDoc{Security: "partnerKey",
		Responses: map[int]string{http.StatusUnauthorized: "No valid partner key."}})
}
```

`Security` names a scheme: `bearer` is built in; give others in
`Config.SecuritySchemes`:

```go
// illustrative
var OpenAPI = openapi.Config{
	Title: "Shop", Prefix: "/api/v1",
	SecuritySchemes: map[string]openapi.SecurityScheme{
		"partnerKey": {Type: "apiKey", In: "header", Name: "X-Partner-Key"},
	},
}
```

`Scopes` are what the credentials must allow (a token's abilities).
Only the middleware of the route's groups and `With` is seen, not
`UseGlobal`'s.

## How it works

Each typed route under the prefix is an operation, named by the route's
name (`operationId`), grouped by its handler's type (`tags`: the
`Bookmarks` of `h.Index`).

- **Inputs**, as `web.H` binds them: `path`, `query` and `header`
  fields are parameters; the other fields are the JSON body (a
  `multipart/form-data` body when the input has files; none for GET).
  The `validate` rules become what JSON Schema can say: `required`,
  lengths and bounds, `enum`, formats. A field that isn't required may
  also be blank, as `validate` lets it be.
- **Results**, as `encoding/json` writes them: the route's status
  (`Status`, 200 by default) with the result's schema; `web.Empty` and
  204 without a body. Fields without `omitempty` are required, pointers
  nullable; slices and maps aren't, so answer empty ones, not nil.
- **Schemas** of named structs are components named after the Go type
  (`BookmarkResponse`; `PageBookmarkResponse` for
  `db.Page[BookmarkResponse]`).
- **Errors** are problem details (the `Problem` schema): 400 when the
  input has values to read, 422 when it has validate rules or a
  `Validate` method, the middleware's, and `default` for any other.
- **Security** comes from the middleware (step 5); when some operations
  need credentials, the others say they don't (`security: []`).

The [OpenAPI reference](https://docs.anetos.dev/reference/openapi/index.md) has every rule: the
types' schemas, the validation rules' keywords, the names, the
warnings.

## Testing it

The test of step 4 is the check. To look at the document as clients
get it, `go tool anetos dev` and open `/api/openapi.json`, or load
`openapi.json` into an OpenAPI viewer or validator.

## Common problems

- **"not a typed handler: left out".** The route's handler is a plain
  `func(c *web.Ctx) error`, or `web.H`'s handler wrapped in another
  function before it was registered. Route `web.H(…)` as it returns it.
  Under `Prefix`, `Check` fails on it ("the document can't describe
  GET /api/v1/…"); serve such a route outside the prefix.
- **"its result is a web.Responder".** A handler returning
  `web.Responder` chooses its status and body as it runs: the document
  says only "2XX". Return a struct and put the status on the route
  (`.Status(http.StatusCreated)`).
- **"has its own MarshalJSON".** The type writes its own JSON: the
  document says "any value". Answer with a plain struct.
- **A list is `null` in responses.** The schema says array; a nil slice
  is written as `null`. Make empty slices (`[]T{}`).
- **"its result is an interface".** The result type is `any` or
  another interface: the document can't say what it is. Return a
  concrete type.
- **The test fails after a change.** Run `go run . openapi` and commit
  the file with the change.

## Next steps

- [OpenAPI reference](https://docs.anetos.dev/reference/openapi/index.md): every rule of the
  document.
- [Tutorial: build an API](https://docs.anetos.dev/getting-started/build-an-api/index.md): an API
  whose document grows step by step.
- [Handlers](https://docs.anetos.dev/guides/handlers/index.md): typed handlers, `Status` and `web.Empty`.
- [Add accounts to an API](https://docs.anetos.dev/guides/api-accounts/index.md): the bearer tokens the
  document describes.
- [Validation](https://docs.anetos.dev/guides/validation/index.md): the rules the schemas come from.


# CSS frameworks

Source: https://docs.anetos.dev/guides/css-frameworks/

- [The starter theme](https://docs.anetos.dev/guides/starter-theme/index.md): The starter theme (`--css=anetos`), which `anetos new` writes unless you pick a CSS framework: Anetos's own stylesheet, about 270 lines of plain CSS, with no framework and no build step.
- [Start without styles](https://docs.anetos.dev/guides/plain-html/index.md): `--css=none`: the same components, writing plain HTML without classes, and an `app.css` that holds only a comment. For your own CSS, or a CSS framework anetos doesn't cover.
- [Style with Pico](https://docs.anetos.dev/guides/pico/index.md): `--css=pico`: [Pico CSS](https://picocss.com) 2.1.1, a framework that styles plain HTML, so its components write few classes. No build step and no JavaScript.
- [Style with Bootstrap](https://docs.anetos.dev/guides/bootstrap/index.md): `--css=bootstrap`: [Bootstrap](https://getbootstrap.com) 5.3.8's classes, its stylesheet and its JavaScript bundle, as released. No build step.
- [Style with Bulma](https://docs.anetos.dev/guides/bulma/index.md): `--css=bulma`: [Bulma](https://bulma.io) 1.0.4's classes and its stylesheet, as released, with a small script for the menu button. No build step.
- [Style with Tailwind CSS](https://docs.anetos.dev/guides/tailwind/index.md): `--css=tailwind`: components with [Tailwind CSS](https://tailwindcss.com) 4.3.3's utility classes, and a stylesheet that Tailwind compiles from them. `anetos dev` and `anetos build` run Tailwind's standalone CLI for you: no Node.js.


# The starter theme

Source: https://docs.anetos.dev/guides/starter-theme/

The starter theme (`--css=anetos`), which `anetos new` writes unless you pick a CSS framework:
Anetos's own stylesheet, about 270 lines of plain CSS, with no
framework and no build step.

![The products list with the starter theme, light](https://docs.anetos.dev/images/kits/anetos-list-light.webp)

![The products list with the starter theme, dark](https://docs.anetos.dev/images/kits/anetos-list-dark.webp)

## Before you start

A project made with `anetos new` (or `--css=anetos`), or switched to it
with `go tool anetos css:use anetos` ([Style your app](https://docs.anetos.dev/guides/styling/index.md#8-switch-css-frameworks)).

## Steps

### 1. Know its files

| File | Holds |
|---|---|
| `views/ui/*.templ` | The components, with the theme's classes (`card`, `field`, `badge success`…) |
| `views/ui/classes.go` | The classes of each variant and size (`button secondary small`) and tone |
| `public/static/app.css` | The theme: color variables, light and dark, base styles for plain HTML, then the classes |

Forms and tables need no class: plain HTML looks right as it is. A form
with its errors:

![The new-product form with its errors, starter theme](https://docs.anetos.dev/images/kits/anetos-form-light.webp)

![The new-product form with its errors, starter theme, dark](https://docs.anetos.dev/images/kits/anetos-form-dark.webp)

### 2. Change its colors

The variables at the top of `app.css` are the theme's colors, radius,
fonts and width; the dark ones follow twice, in a `prefers-color-scheme`
block and for `data-theme="dark"`. For a brand color, change them in
all three:

```css
/* illustrative */
:root {
	--primary: #7c3aed;
	--primary-hover: #6d28d9;
}
@media (prefers-color-scheme: dark) {
	:root:not([data-theme="light"]) {
		--primary: #a78bfa;
		--primary-hover: #c4b5fd;
	}
}
:root[data-theme="dark"] {
	--primary: #a78bfa;
	--primary-hover: #c4b5fd;
}
```

Edit the values in place rather than adding rules after them. Dark mode
follows the visitor's system; `data-theme="dark"` (or `"light"`) on
`<html>`, in `views/layout.templ`, forces one.

### 3. Use its other classes

`grid` (cards side by side, wrapping) is a class no component uses
yet, for components of your own; `muted`, `stack` and `cluster`, the
classes of `Note`, `Stack` and `Cluster`, are yours to use too. Put the markup in a component
of `views/ui` ([Style your app](https://docs.anetos.dev/guides/styling/index.md#5-add-your-own-component)),
so its classes stay in one package.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| A color change shows in light but not in dark | The dark blocks set the variable too | Change it in the `prefers-color-scheme: dark` block and the `data-theme="dark"` one as well |
| `css:use` refuses to switch: `public/static/app.css` changed | You edited the theme | Commit, run it with `--force`, and carry your colors over to the new stylesheet ([Style your app](https://docs.anetos.dev/guides/styling/index.md#8-switch-css-frameworks)) |

## Next steps

- [Style your app](https://docs.anetos.dev/guides/styling/index.md): the components, and the CSS frameworks
- [UI components reference](https://docs.anetos.dev/reference/ui/index.md)


# Start without styles

Source: https://docs.anetos.dev/guides/plain-html/

`--css=none`: the same components, writing plain HTML without
classes, and an `app.css` that holds only a comment. For your own CSS,
or a CSS framework anetos doesn't cover.

![The products list without styles](https://docs.anetos.dev/images/kits/none-list-light.webp)

## Before you start

A project made with `anetos new blog --css=none`, or switched to it
with `go tool anetos css:use none`.

## Steps

### 1. Know what it writes

The components write elements only: `<header>`, `<nav>`, `<main>`,
`<section>` for a card, `<label>` and `<input>` for a field,
`<table>`. The browser's default styles show them:

![The new-product form with its errors, without styles](https://docs.anetos.dev/images/kits/none-form-light.webp)

A few things change nothing without styles: a button's look, a
message's or a badge's tone, the table's scrolling box. The [UI
components reference](https://docs.anetos.dev/reference/ui/index.md#none-plain-html) lists how its
components differ from the others'. There is no `classes.go`.

### 2. Style the elements

Write your rules for the elements in `public/static/app.css`; every
page calls the same components, so the elements are the same
everywhere:

```css
/* illustrative */
body { font-family: system-ui, sans-serif; max-width: 60rem; margin: 0 auto; padding: 1rem; }
header nav a { margin-right: 1rem; }
table { border-collapse: collapse; width: 100%; }
td, th { border-bottom: 1px solid #ddd; padding: .5rem; text-align: left; }
input, select, textarea { display: block; width: 100%; margin-bottom: 1rem; }
[aria-invalid="true"] { border-color: #c00; }
```

### 3. Or give the components your classes

For a framework of your own choice, edit the components in `views/ui`
to write its classes, put its stylesheet in `public/static/`, and link
it from `ui.Head` in `views/ui/shell.templ`. Keep the components' names
and arguments: the pages of `make:crud` and `make:auth` call them.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| Buttons all look alike, badges have no color | `none` has no styles: variants, sizes and tones write nothing | Style them by element, or switch to a CSS framework that has them |

## Next steps

- [Style your app](https://docs.anetos.dev/guides/styling/index.md)
- [UI components reference](https://docs.anetos.dev/reference/ui/index.md)


# Style with Pico

Source: https://docs.anetos.dev/guides/pico/

`--css=pico`: [Pico CSS](https://picocss.com) 2.1.1, a framework that
styles plain HTML, so its components write few classes. No build step
and no JavaScript.

![The products list with Pico, light](https://docs.anetos.dev/images/kits/pico-list-light.webp)

![The products list with Pico, dark](https://docs.anetos.dev/images/kits/pico-list-dark.webp)

## Before you start

A project made with `anetos new blog --css=pico`, or switched to it
with `go tool anetos css:use pico`.

## Steps

### 1. Know its files

| File | Holds |
|---|---|
| `public/static/pico.min.css` | Pico as released, with `pico.LICENSE.txt` (MIT) |
| `public/static/app.css` | What Pico has no style of: the header's layout, badges, colored messages, the danger, ghost, small and full buttons |
| `views/ui/*.templ` | The components: `<article>` for a card, `<small>` for a field's message and hint, `<a role="button">` for a link button |
| `views/ui/classes.go` | The classes of each variant and size (`secondary`; `danger`, `ghost`, `small`, `full` from `app.css`) and tone |

The header's links wrap on a small screen; there is no menu button. A
form with its errors (Pico marks the control and colors its message):

![The new-product form with its errors, Pico](https://docs.anetos.dev/images/kits/pico-form-light.webp)

![The new-product form with its errors, Pico, dark](https://docs.anetos.dev/images/kits/pico-form-dark.webp)

### 2. Change its colors

Pico's colors are CSS variables. Set them in `app.css`, which comes
after `pico.min.css`, with Pico's own selectors (a plain `:root` loses
to them):

```css
/* illustrative */
:root:not([data-theme=dark]), [data-theme=light] {
	--pico-primary: #6d28d9;
	--pico-primary-background: #6d28d9;
	--pico-primary-underline: rgba(109, 40, 217, .5);
	--pico-primary-hover: #5b21b6;
	--pico-primary-hover-background: #5b21b6;
	--pico-primary-focus: rgba(109, 40, 217, .25);
}
@media (prefers-color-scheme: dark) {
	:root:not([data-theme]) {
		--pico-primary: #a78bfa;
		--pico-primary-background: #7c3aed;
		--pico-primary-underline: rgba(167, 139, 250, .5);
		--pico-primary-hover: #c4b5fd;
		--pico-primary-hover-background: #6d28d9;
		--pico-primary-focus: rgba(167, 139, 250, .375);
	}
}
[data-theme=dark] {
	--pico-primary: #a78bfa;
	--pico-primary-background: #7c3aed;
	--pico-primary-underline: rgba(167, 139, 250, .5);
	--pico-primary-hover: #c4b5fd;
	--pico-primary-hover-background: #6d28d9;
	--pico-primary-focus: rgba(167, 139, 250, .375);
}
```

[Pico's docs](https://picocss.com/docs/css-variables) list the
others: spacing, radius, font. Pico's other color themes
(`pico.violet.min.css`…) are other files of its release: to use one,
put it in `public/static/` and link it from `ui.Head` in
`views/ui/shell.templ` instead.

### 3. Use more of Pico

Pico styles HTML by its elements and roles, so your own components can
use them without classes: `<div role="group">` for buttons side by
side, `<details class="dropdown">` for a menu without JavaScript,
`<article>` with a `<header>` for a card, `<progress>`, `<dialog>`.
Put them in components of `views/ui` ([Style your
app](https://docs.anetos.dev/guides/styling/index.md#5-add-your-own-component)).

## How it works

Dark mode is Pico's: it follows the visitor's system, or
`data-theme="dark"` (or `"light"`) on `<html>`. `css:use pico` with the
in a project that has it brings a newer Pico when a newer `anetos` carries
one ([Style your app](https://docs.anetos.dev/guides/styling/index.md#8-switch-css-frameworks)).

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| A variable set on `:root` changes nothing | Pico sets it with a more specific selector | Use Pico's selectors, as above |
| A link button doesn't respond to the space bar | It's a link (`<a role="button">`), Pico's way to style one: links follow on Enter | Use a `ui.Button` in a form for actions |

## Next steps

- [Style your app](https://docs.anetos.dev/guides/styling/index.md)
- [Pico's documentation](https://picocss.com/docs)


# Style with Bootstrap

Source: https://docs.anetos.dev/guides/bootstrap/

`--css=bootstrap`: [Bootstrap](https://getbootstrap.com) 5.3.8's
classes, its stylesheet and its JavaScript bundle, as released. No
build step.

![The products list with Bootstrap, light](https://docs.anetos.dev/images/kits/bootstrap-list-light.webp)

![The products list with Bootstrap, dark](https://docs.anetos.dev/images/kits/bootstrap-list-dark.webp)

## Before you start

A project made with `anetos new blog --css=bootstrap`, or switched to it
with `go tool anetos css:use bootstrap`.

## Steps

### 1. Know its files

| File | Holds |
|---|---|
| `public/static/bootstrap.min.css`, `bootstrap.bundle.min.js` | Bootstrap as released (the bundle includes Popper), with `bootstrap.LICENSE.txt` and `popper.LICENSE.txt` (MIT) |
| `public/static/theme.js` | Sets `data-bs-theme` on `<html>` from the visitor's light or dark mode, and follows its changes |
| `public/static/app.css` | The few rules Bootstrap has no class for (a narrow column, the login card's width) |
| `views/ui/*.templ` | The components: `navbar`, `card`, `form-control`, `alert`, `badge`, `pagination`… |
| `views/ui/classes.go` | The classes of each variant and size (`btn btn-primary`, `btn-outline-secondary`, `btn-danger`, `btn-link`, `btn-sm`, `w-100`) and tone |

A form with its errors:

![The new-product form with its errors, Bootstrap](https://docs.anetos.dev/images/kits/bootstrap-form-light.webp)

![The new-product form with its errors, Bootstrap, dark](https://docs.anetos.dev/images/kits/bootstrap-form-dark.webp)

On a small screen, a menu button opens the header's links. Its name for
screen readers is `nav.menu` in `locales/<locale>/app.yaml` ("Menu"):

![The header's menu open on a phone, Bootstrap](https://docs.anetos.dev/images/kits/bootstrap-menu.webp)

### 2. Change its colors

Bootstrap compiles its colors into each component with Sass; without a
build step, set the CSS variables the components read, in `app.css`:

```css
/* illustrative */
:root, [data-bs-theme=light] {
	--bs-primary: #6f42c1;
	--bs-primary-rgb: 111, 66, 193;
	--bs-link-color: #6f42c1;
	--bs-link-color-rgb: 111, 66, 193;
	--bs-link-hover-color: #59359a;
	--bs-link-hover-color-rgb: 89, 53, 154;
}
[data-bs-theme=dark] {
	--bs-link-color: #a385db;
	--bs-link-color-rgb: 163, 133, 219;
	--bs-link-hover-color: #c2aeea;
	--bs-link-hover-color-rgb: 194, 174, 234;
}
.btn-primary {
	--bs-btn-bg: #6f42c1;
	--bs-btn-border-color: #6f42c1;
	--bs-btn-hover-bg: #59359a;
	--bs-btn-hover-border-color: #59359a;
	--bs-btn-active-bg: #59359a;
	--bs-btn-active-border-color: #59359a;
}
```

[Bootstrap's docs](https://getbootstrap.com/docs/5.3/customize/css-variables/)
list each component's variables. Some colors are compiled in, the
focus ring of the form controls among them: for a full theme (another
palette, fonts, spacing), compile Bootstrap with Sass yourself and replace
`bootstrap.min.css` with the result.

### 3. Use more of Bootstrap

Its JavaScript bundle is loaded on every page (deferred), so its
components work in yours: dropdowns, modals, collapses (tooltips and
popovers need a line of script to start them, as Bootstrap's docs
show). A
dropdown, as a component of `views/ui`:

```templ
// illustrative
templ Dropdown(label string) {
	<div class="dropdown">
		<button class="btn btn-outline-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">{ label }</button>
		<ul class="dropdown-menu">
			{ children... }
		</ul>
	</div>
}
```

Its grid (`row`, `col-md-6`) and utilities (`mb-3`, `d-flex`) work in
your own pages too; a component keeps them in one place ([Style your
app](https://docs.anetos.dev/guides/styling/index.md#5-add-your-own-component)).

## How it works

Bootstrap's dark mode is `data-bs-theme="dark"` on `<html>`, which
`theme.js` sets from the visitor's system before the page shows. The
menu button is Bootstrap's collapse, from its bundle. `css:use
bootstrap` in a project that has it brings a newer Bootstrap when a
newer `anetos` carries one ([Style your app](https://docs.anetos.dev/guides/styling/index.md#8-switch-css-frameworks)).

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `--bs-primary` changes nothing on buttons | Each button's color is its own variables | Set `.btn-primary`'s, as above |
| The menu button does nothing | `bootstrap.bundle.min.js` isn't loaded (a `ui.Head` you changed), or JavaScript is off | Link the bundle from `ui.Head`; without JavaScript, the links stay hidden on small screens |
| The browser's console reports a missing `.map` file | The released files name their source maps, which anetos doesn't carry | Harmless: only the developer tools ask for it |

## Next steps

- [Style your app](https://docs.anetos.dev/guides/styling/index.md)
- [Bootstrap's documentation](https://getbootstrap.com/docs/5.3/)


# Style with Bulma

Source: https://docs.anetos.dev/guides/bulma/

`--css=bulma`: [Bulma](https://bulma.io) 1.0.4's classes and its
stylesheet, as released, with a small script for the menu button. No
build step.

![The products list with Bulma, light](https://docs.anetos.dev/images/kits/bulma-list-light.webp)

![The products list with Bulma, dark](https://docs.anetos.dev/images/kits/bulma-list-dark.webp)

## Before you start

A project made with `anetos new blog --css=bulma`, or switched to it
with `go tool anetos css:use bulma`.

## Steps

### 1. Know its files

| File | Holds |
|---|---|
| `public/static/bulma.min.css` | Bulma as released, with `bulma.LICENSE.txt` (MIT) |
| `public/static/nav.js` | Opens and closes the header's links on a small screen (Bulma has no JavaScript of its own) |
| `public/static/app.css` | The few rules Bulma has no class for (a narrow column, the details' grid, the current page in the header) |
| `views/ui/*.templ` | The components: `navbar`, `box`, `field` and `control`, `notification`, `tag`, `pagination`…; `ui.Main` wraps the page in Bulma's `content`, which styles the pages' plain HTML (headings, lists) |
| `views/ui/classes.go` | The classes of each variant and size (`button is-primary`, `is-danger`, `is-ghost`, `is-small`, `is-fullwidth`) and tone |

A form with its errors:

![The new-product form with its errors, Bulma](https://docs.anetos.dev/images/kits/bulma-form-light.webp)

![The new-product form with its errors, Bulma, dark](https://docs.anetos.dev/images/kits/bulma-form-dark.webp)

On a small screen, a menu button opens the header's links. Its name for
screen readers is `nav.menu` in `locales/<locale>/app.yaml` ("Menu"):

![The header's menu open on a phone, Bulma](https://docs.anetos.dev/images/kits/bulma-menu.webp)

### 2. Change its colors

Bulma's colors are CSS variables in hue, saturation and lightness. Set
them in `app.css`, which comes after `bulma.min.css`:

```css
/* illustrative */
:root {
	--bulma-primary-h: 262deg;
	--bulma-primary-s: 83%;
	--bulma-primary-l: 58%;
	--bulma-link-h: 262deg;
	--bulma-link-s: 83%;
	--bulma-link-l: 58%;
}
```

Bulma derives the hover and the hue of the light and dark variants
from them, but keeps its own lightness for the variants and for the
text on the color: for a dark brand color, set
`--bulma-primary-invert-l: 100%;` too, for white text. [Bulma's docs](https://bulma.io/documentation/features/css-variables/)
list the others.

### 3. Use more of Bulma

Its layout (`columns`, `column is-half`), elements (`tags`, `level`,
`media`) and components work in your own components and pages. Bulma's
interactive components (a dropdown, a modal) need a script to open
them, as `nav.js` does for the menu: add yours to `public/static/` and
link it from `ui.Head` in `views/ui/shell.templ`. Keep repeated markup
in a component of `views/ui` ([Style your
app](https://docs.anetos.dev/guides/styling/index.md#5-add-your-own-component)).

## How it works

Bulma's dark mode follows the visitor's system. `css:use bulma` with
in a project that has it brings a newer Bulma when a newer `anetos`
carries one ([Style your app](https://docs.anetos.dev/guides/styling/index.md#8-switch-css-frameworks)).

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| A page's own `<h1>` or list has no style | Outside `ui.Main`'s `content`, Bulma resets plain HTML | Put it in the page's content, or give it Bulma's classes (`title`) |
| The menu button does nothing | `nav.js` isn't loaded (a `ui.Head` you changed), or JavaScript is off | Link `nav.js` from `ui.Head`; without JavaScript, the links stay hidden on small screens |

## Next steps

- [Style your app](https://docs.anetos.dev/guides/styling/index.md)
- [Bulma's documentation](https://bulma.io/documentation/)


# Style with Tailwind CSS

Source: https://docs.anetos.dev/guides/tailwind/

`--css=tailwind`: components with [Tailwind CSS](https://tailwindcss.com)
4.3.3's utility classes, and a stylesheet that Tailwind compiles from
them. `anetos dev` and `anetos build` run Tailwind's standalone CLI for
you: no Node.js.

![The products list with Tailwind CSS, light](https://docs.anetos.dev/images/kits/tailwind-list-light.webp)

![The products list with Tailwind CSS, dark](https://docs.anetos.dev/images/kits/tailwind-list-dark.webp)

## Before you start

A project made with `anetos new blog --css=tailwind`, or switched to it
with `go tool anetos css:use tailwind`. The first compile downloads
Tailwind CSS (80 to 112 MB, once): see [How it works](https://docs.anetos.dev/guides/tailwind/index.md#how-it-works).

## Steps

### 1. Know its files

| File | Holds |
|---|---|
| `views/ui/tailwind.css` | The source: `@import "tailwindcss" source("..")` (Tailwind looks for classes in `views/`), the accent color in `@theme`, and the look of the pages' plain HTML (headings, lists, table cells) |
| `public/static/app.css` | What Tailwind compiles from it, minified: the stylesheet the pages link. Commit it, as the `_templ.go` files: `go build`, `go test` and the `Dockerfile` use it as it is |
| `public/static/tailwind.LICENSE.txt` | Tailwind's license (MIT): `app.css` carries its code |
| `views/ui/*.templ` | The components, with utility classes |
| `views/ui/classes.go` | The classes of each variant, size and tone, and of the form controls |

A new project's `app.css` comes compiled: it has every class of the
components, and the pages of `make:crud` and `make:auth` add none, so
they look right before Tailwind ever runs. A form with its errors:

![The new-product form with its errors, Tailwind CSS](https://docs.anetos.dev/images/kits/tailwind-form-light.webp)

![The new-product form with its errors, Tailwind CSS, dark](https://docs.anetos.dev/images/kits/tailwind-form-dark.webp)

### 2. Add classes, and let Tailwind compile them

When you add a class to a page or a component, Tailwind writes its
rule:

- `go tool anetos dev` compiles `app.css` before each rebuild, when a
  templ file, a Go file or `tailwind.css` changes (about 0.2 s);
- `go tool anetos build` compiles it before building the binary;
- `go tool anetos css:build` compiles it alone, and `css:build --check`
  fails when it's out of date (for CI).

A class must be written whole in a file of `views/`: Tailwind finds
`bg-red-600` in `"bg-red-600"`, not in `"bg-" + color`.

### 3. Change its colors

The accent (links, the primary button, focus rings) is `@theme`'s
`--color-accent` in `tailwind.css`, with its dark values below it:

```css
/* illustrative */
@theme {
	--color-accent: #7c3aed;
	--color-accent-hover: #6d28d9;
	--color-on-accent: #ffffff;
}
```

The grays are Tailwind's `zinc`, with `dark:` variants in the
components; change them there. Dark mode follows the visitor's system.

## How it works

`anetos` runs Tailwind's standalone CLI. The first run downloads
Tailwind CSS 4.3.3 for your computer (Linux, macOS or Windows) from its
GitHub releases into your user cache directory
(`~/Library/Caches/anetos/tailwindcss/` on macOS,
`~/.cache/anetos/tailwindcss/` on Linux,
`%LocalAppData%\anetos\tailwindcss\` on Windows), and checks its
SHA-256 against the one written in `anetos`, then again before each
run. On Alpine Linux, the musl build it downloads needs `apk add
libstdc++ libgcc`. Offline, or on another platform, download a
`tailwindcss` binary yourself and set `ANETOS_TAILWIND` to its path.
When Tailwind can't run, `anetos dev` says why and keeps the `app.css`
there is until you restart it, so new classes aren't styled yet;
`anetos build` and `css:build` fail. A Tailwind project's `Dockerfile`
keeps the download in BuildKit's cache ([Deploy](https://docs.anetos.dev/guides/deployment/index.md)).

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| A class you added has no effect | `app.css` wasn't compiled since (no `anetos dev` running, or Tailwind couldn't run: its message says why), or the class is built from pieces | Run `go tool anetos css:build`; write the class whole |
| `anetos dev` says it can't download Tailwind CSS | Offline, a proxy, or a platform without a standalone CLI | Download the binary the message names, and set `ANETOS_TAILWIND` to its path |
| `tailwind: tailwindcss-… has SHA-256 …, not …` | The download isn't the release `anetos` was made for (altered, or cut off) | Nothing is run; try again, or use `ANETOS_TAILWIND` with a binary you trust |
| CI fails `css:build --check` | `app.css` wasn't compiled after a change of classes | Run `go tool anetos css:build` and commit `app.css` |

## Next steps

- [Style your app](https://docs.anetos.dev/guides/styling/index.md)
- [Tailwind's documentation](https://tailwindcss.com/docs)


# Data

Source: https://docs.anetos.dev/guides/data/

- [Connect to a database](https://docs.anetos.dev/guides/database/index.md): Open your app's database from configuration and use it from handlers, jobs and background tasks.
- [Define models and save data](https://docs.anetos.dev/guides/models/index.md): Map structs to tables, and create, update and delete rows with timestamps, soft deletes and hooks.
- [Migrations](https://docs.anetos.dev/guides/migrations/index.md): Create and change your database tables with versioned migrations that are compiled into your app and run with one command.
- [Query data](https://docs.anetos.dev/guides/queries/index.md): Find rows with typed conditions, sort and paginate them, aggregate, and update or delete in bulk.
- [Relations and eager loading](https://docs.anetos.dev/guides/relations/index.md): Declare how models relate (a post belongs to an author, an author has many posts, posts have many tags), load related rows in one query per relation, and filter rows by what they relate to.
- [Transactions](https://docs.anetos.dev/guides/transactions/index.md): Make several writes succeed or fail together, and run follow-up work only after they are saved.
- [Raw SQL](https://docs.anetos.dev/guides/raw-sql/index.md): Write SQL yourself and scan the results into structs, when the query builder is in the way.
- [Seed the database](https://docs.anetos.dev/guides/seeders/index.md): Fill a database with sample data for development, or with the reference data every environment needs.
- [Generate typed columns](https://docs.anetos.dev/guides/code-generation/index.md): Let `anetos generate` declare a typed column for every field of your models, and a handle for every relation, so queries say `PostCols.Title.Like("%go%")` and `With(PostRels.Author)`, and the compiler checks the column name, the value's type and the relation's model.


# Connect to a database

Source: https://docs.anetos.dev/guides/database/

Open your app's database from configuration and use it from handlers, jobs
and background tasks.

## Before you start

Pick a driver module. Each is a separate Go module, so your binary only
contains the drivers you use:

| Database | Module | `DB_DRIVER` |
|---|---|---|
| SQLite (pure Go, no C compiler) | `anetos.dev/anetos/drivers/sqlite` | `sqlite` |
| PostgreSQL | `anetos.dev/anetos/drivers/postgres` | `postgres` |
| MySQL, MariaDB | `anetos.dev/anetos/drivers/mysql` | `mysql` |

```sh
go get anetos.dev/anetos/drivers/sqlite
```

## Steps

### 1. Configure the connection

```sh
# .env
DB_DRIVER=postgres
DB_HOST=127.0.0.1
DB_NAME=blog
DB_USER=blog
DB_PASSWORD=secret
```

For SQLite, `DB_NAME` is a file path (default `database/app.db`).
A database on another machine is reached over TLS that checks its
certificate (`DB_TLS=verify`, the default for any host but `localhost`
or a loopback address); `DB_TLS_CA` names a PEM file of your provider's
certificate authority when the system doesn't know it, and
`DB_TLS=none` turns TLS off for a private network you trust. Put other
driver options in `DB_URL`, which replaces the individual settings
(TLS included). Every key is in the
[configuration reference](https://docs.anetos.dev/reference/configuration/index.md#database).

### 2. Connect at startup

```go
// DB_DRIVER (default sqlite) picks one of the drivers passed here.
if _, err := db.Connect(context.Background(), app, sqlite.Driver()); err != nil {
	return nil, err
}
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `connect`.)

Pass every driver the app may use: `DB_DRIVER` picks one, so you can
develop on SQLite and deploy on PostgreSQL with the same binary.

`db.Connect` pings the database when the app boots, so a wrong password
stops the app (or a command such as `migrate`) at startup instead of on
the first request, while `./app help` works without a database. It also:

- adds the connection to every context the app creates (HTTP requests,
  `app.Go` tasks, components, shutdown hooks);
- provides it as a `*db.DB` service (`anetos.Resolve[*db.DB](app)`);
- closes it in a shutdown hook, after the components stop.

### 3. Query with the request context

Any function with the request's context can query, with no database field
to pass around:

```go
// illustrative
func (h *Posts) Show(c *web.Ctx, in PostID) (Post, error) {
	return db.Find[Post](c, in.ID) // c is a context.Context
}
```

Code outside a request, such as a CLI command, gets the same values from
`app.Context(ctx)`.

### 4. Add more connections (optional)

Read another set of keys with a prefix and put that database in the
context when you need it:

```go
// illustrative
cfg, err := db.LoadConfig(app.Source(), "ANALYTICS_") // ANALYTICS_DB_DRIVER, ANALYTICS_DB_HOST, …
analytics, err := db.Open(postgres.Driver(), cfg, db.WithLogger(app.Logger()))
app.OnShutdown("analytics-db", func(context.Context) error { return analytics.Close() })

events, err := db.Query[Event](db.WithDB(ctx, analytics)).Get()
```

### 5. Switch a project to PostgreSQL or MySQL

A project made with `anetos new` uses SQLite unless you passed
`--db postgres` or `--db mysql`. To switch later:

1. Add the driver: `go get anetos.dev/anetos/drivers/postgres`,
   and pass `postgres.Driver()` to `db.Connect` in `main.go` (keep
   `sqlite.Driver()` too if you still want SQLite anywhere).
2. Set `DB_DRIVER=postgres` and the other `DB_*` settings in `.env`
   (and `.env.example`), as in step 1.
3. Create a test database and write `.env.testing` with **all** its
   settings: tests don't read `.env`, so nothing is inherited from it.

   ```sh
   # .env.testing
   DB_DRIVER=postgres
   DB_HOST=127.0.0.1
   DB_NAME=blog_test
   DB_USER=blog
   DB_PASSWORD=secret
   ```

   Without `DB_DRIVER` there (or without the file), tests would
   use SQLite; `anetostest` stops them with a message when `.env` has
   another `DB_DRIVER`.
4. `go run . migrate`, then `go test ./...`.
5. The deploy files still say SQLite: in `deploy/production.env.example`,
   put `DB_DRIVER` and `DB_URL` in place of SQLite's settings; in
   the `Dockerfile`, drop `DB_NAME` and `DB_MIGRATE_ON_START` (run
   `migrate` on each deploy instead); in `deploy/<name>.service`, drop
   `DB_NAME`; the README's "nothing to set up" is SQLite's too. A
   project made with `--db postgres` shows the server versions of these
   files.

Migrations written with the schema builder run on every database; raw
SQL in migrations may need changes.

## How it works

A `*db.DB` wraps a `database/sql` pool and the database's dialect. Queries
look it up in their context with `db.From`, and use a transaction instead
if the context carries one (see [Transactions](https://docs.anetos.dev/guides/transactions/index.md)). The
[data layer concept](https://docs.anetos.dev/concepts/data-layer/index.md) explains why.

In development, every query is logged at debug level with its duration.
Queries slower than `DB_SLOW_QUERY` (default 500ms) are logged as warnings
in every environment. In development and tests, a request (or job, …)
that runs the same query five times or more is logged as a warning: see
[Find N+1 queries](https://docs.anetos.dev/guides/n-plus-one/index.md).

When the app starts, it also checks that the database can serve what the
app asks of it (the `DB_SEARCH_*` settings, features' requirements), and
stops with a clear message if it can't: see
[Add full-text search](https://docs.anetos.dev/guides/search/index.md#choose-the-settings).

> **Note:** `DB_CONNECTION`, `DB_DATABASE` and `DB_USERNAME`, the names
> before v0.5, are read too, with a warning, until v0.6. There is no
> database config file: extra connections use prefixed keys.

## Testing it

`anetostest.New(t, setup)` boots the app with an in-memory SQLite
database (or, with `DB_*` set, your test database inside a transaction
rolled back at the end) and runs the migrations; pass `app.Context()` to
code that queries. See [Test your app](https://docs.anetos.dev/guides/testing/index.md#5-check-the-database).

To test code without the app, open a database and put it in a context:

```go
// illustrative
d, err := db.Open(sqlite.Driver(), db.Config{Name: ":memory:"})
if err != nil {
	t.Fatal(err)
}
t.Cleanup(func() { d.Close() })
ctx := db.WithDB(t.Context(), d)
```

An in-memory database has a single connection, so a query that waits for
a second one (on the outer context inside `db.Tx`, or inside an `All()`
loop) blocks. A file in `t.TempDir()` behaves like production instead.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `db: DB_DRIVER is "postgres", but the drivers passed to Connect are [sqlite]` | The driver isn't passed to `Connect` | Import the driver module and pass its `Driver()` |
| `db: no database in context` | The context didn't come from the app | Use the request's `c`, a context from `app.Context`, or `db.WithDB` |
| `connect to postgres: … connection refused` at startup | Wrong host or port, or the server isn't running | Check `DB_HOST`/`DB_PORT`; the error comes from the ping in `Connect` |
| `… certificate signed by unknown authority`, `server does not support SSL`, `TLS requested but server does not support TLS` | A remote `DB_HOST` gets verified TLS by default | Set `DB_TLS_CA` to your provider's CA file, or `DB_TLS=none` on a private network (a Compose service, say) |
| `database is locked` on SQLite | A write took longer than the 5s busy timeout | Keep transactions short; SQLite allows one writer at a time |

## Next steps

- [Migrations](https://docs.anetos.dev/guides/migrations/index.md)
- [Define models and save data](https://docs.anetos.dev/guides/models/index.md)
- [Query data](https://docs.anetos.dev/guides/queries/index.md)


# Define models and save data

Source: https://docs.anetos.dev/guides/models/

Map structs to tables, and create, update and delete rows with
timestamps, soft deletes and hooks.

## Before you start

[Connect to a database](https://docs.anetos.dev/guides/database/index.md) and create the tables with
[migrations](https://docs.anetos.dev/guides/migrations/index.md).

## Steps

### 1. Define the models

```go
// Author writes posts.
type Author struct {
	db.Model        // id, created_at, updated_at
	Name     string `db:"name" json:"name"`
	Email    string `db:"email" json:"email"`

	Posts []Post `rel:"has_many" json:"posts,omitzero"` // posts.author_id; loaded with With or Load
}

// Post is a blog post. Deleting one only marks it deleted.
type Post struct {
	db.Model
	db.SoftDeletes            // deleted_at
	AuthorID       int64      `db:"author_id" json:"author_id"`
	Title          string     `db:"title" json:"title"`
	Body           string     `db:"body" json:"body"`
	Tags           []string   `db:"tags,json" json:"tags"` // stored as JSON text
	Views          int        `db:"views" json:"views"`
	PublishedAt    *time.Time `db:"published_at" json:"published_at"` // nullable

	Author *Author `rel:"belongs_to" json:"author,omitzero"` // by AuthorID
}

// AuthorCols and PostCols, the typed columns of the models, and
// AuthorRels and PostRels, their relations, are in models_gen.go, written
// by `go tool anetos generate` (or go generate).
//
//go:generate go tool anetos generate
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `models`.)

- `db.Model` adds an auto-increment `id` and the `created_at` and
  `updated_at` timestamps. Embed `db.Timestamps` alone if the key is
  something else.
- `db.SoftDeletes` adds `deleted_at`: deleting sets it, and queries skip
  those rows.
- Columns are the `db` tags; untagged fields use their snake_case names
  (`AuthorID` → `author_id`). Fields with a `rel` tag are
  [relations](https://docs.anetos.dev/guides/relations/index.md), not columns; other struct, pointer-to-struct
  and slice-of-struct fields without a tag are skipped.
- The table is the snake_case plural of the type name (`Post` → `posts`,
  `Category` → `categories`). Add a `TableName() string` method to choose
  another.
- Use pointers (or `sql.Null[T]`) for nullable columns, and
  `db:"name,json"` to store a value as JSON.
- `go tool anetos generate` writes the typed columns (`PostCols.Title`) that
  queries use; see [Generate typed columns](https://docs.anetos.dev/guides/code-generation/index.md).

All the tag options and naming rules are in the
[models reference](https://docs.anetos.dev/reference/models/index.md).

### 2. Create, read, update, delete

```go
// illustrative
post := Post{AuthorID: 1, Title: "Hello"}
err := db.Create(ctx, &post)      // sets post.ID, CreatedAt, UpdatedAt

post, err = db.Find[Post](ctx, 1) // db.ErrNotFound if there is no row

post.Title = "Hello, world"
err = db.Update(ctx, &post)       // writes every column; sets UpdatedAt

err = db.Save(ctx, &post)         // Create if ID is zero, else Update

err = db.Delete(ctx, &post)       // soft delete: sets DeletedAt
err = db.Restore(ctx, &post)
err = db.ForceDelete(ctx, &post)  // really deletes the row
```

Handlers can return `db.ErrNotFound` as it is: it becomes a **404**.

### 3. Insert many rows, or upsert

```go
// illustrative
err := db.CreateMany(ctx, posts) // one INSERT per batch; IDs set on PostgreSQL and SQLite

// Insert, or update price for SKUs that already exist (sku needs a unique index).
err = db.Upsert(ctx, prices, []string{"sku"}, "price")
```

### 4. Run code around saves (optional)

Implement hook methods on the model's pointer type:

```go
// illustrative
func (p *Post) BeforeSave(ctx context.Context) error {
	p.Title = strings.TrimSpace(p.Title)
	if p.Title == "" {
		return validate.Fail("title", "The title can't be blank.")
	}
	return nil
}
```

Hooks run for `Create`, `Update`, `Save`, `Delete` and (create hooks)
`CreateMany`. A hook error stops the operation. Mass updates and deletes
on a query don't run hooks.

## Complete example

[`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go) is a small blog
API using everything on this page.

## How it works

The first use of a model type reads its fields and tags once and caches
the result; later calls only copy values. Timestamps are set in UTC with
microsecond precision, so what you get back from the database equals what
you saved. See the [data layer concept](https://docs.anetos.dev/concepts/data-layer/index.md).

> **Coming from another framework?** `db.Model` and `db.SoftDeletes`
> play the role of a base model class (Django's `Model`, Eloquent's
> `Model`, Rails' `ApplicationRecord`) and a soft-delete mixin. Models
> don't track dirty attributes: `Update` writes every column, as
> Django's `save()` does, and mass updates set exactly the columns you
> name.

## Testing it

Make rows with [factories](https://docs.anetos.dev/guides/testing/index.md#4-make-rows-with-factories) in a
`anetostest` app, call your functions with `app.Context()`, and check the
table with `anetostest.AssertDatabaseHas[T]`.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `converting NULL to string is unsupported` | A nullable column mapped to a non-pointer field | Use `*string` or `sql.Null[string]` |
| `db: Post has a zero primary key; Create it first` | `Update` or `Delete` on a row without an ID | Load the row first, or use `Save` |
| Wrong table name (`persons` for `Person`… it's `people`) | The pluralizer's guess | Add a `TableName()` method |
| A field is never saved | It's a struct or slice of structs without a `db` tag | Tag it (`db:"meta,json"` for JSON) |
| IDs are zero after `CreateMany` on MySQL | MySQL can't report keys for multi-row inserts | Reload the rows, or use `Create` per row (tracked models get their IDs: the audit log inserts them one by one) |
| A new row can't reuse the email of a soft-deleted one | The unique index counts deleted rows | `UniqueWithoutTrashed` and `unique_without_trashed` on PostgreSQL and SQLite ([Keep an audit log](https://docs.anetos.dev/guides/audit-log/index.md#soft-deletes-that-play-well-with-the-log)) |

## Next steps

- [Generate typed columns](https://docs.anetos.dev/guides/code-generation/index.md)
- [Query data](https://docs.anetos.dev/guides/queries/index.md)
- [Transactions](https://docs.anetos.dev/guides/transactions/index.md)
- [Keep an audit log](https://docs.anetos.dev/guides/audit-log/index.md): who changed what, and pruning
  soft-deleted rows
- [Models reference](https://docs.anetos.dev/reference/models/index.md)


# Migrations

Source: https://docs.anetos.dev/guides/migrations/

Create and change your database tables with versioned migrations that are
compiled into your app and run with one command.

## Before you start

[Connect to a database](https://docs.anetos.dev/guides/database/index.md).

## Steps

### 1. Create a migration set

A set is the list of your app's migrations. Each migration has an ID that
starts with a timestamp, which decides the order:

```go
// Migrations is the app's migration set. In a larger app it lives in its
// own package (database/migrations), with one file per migration.
var Migrations = migrate.NewSet("app")

func init() {
	Migrations.Add("2026_10_01_120000_create_authors", createAuthors{})
	Migrations.Add("2026_10_01_120100_create_posts", createPosts{})
	Migrations.AddFunc("2026_10_02_090000_add_posts_views_index",
		func(s *migrate.Schema) error {
			return s.Alter("posts", func(t *migrate.Table) { t.Index("views") })
		},
		func(s *migrate.Schema) error {
			return s.Alter("posts", func(t *migrate.Table) { t.DropIndex("views") })
		})
}
```

(Copied from [`examples/database/migrations.go`](https://github.com/anetos-dev/anetos/blob/main/examples/database/migrations.go), region `set`.)

In a larger app, put the set in its own package (`database/migrations`)
with one file per migration, each adding itself in `init`, as projects
made by `anetos new` do; `go tool anetos make:migration create_posts_table`
writes such a file.

### 2. Write the migration

`Up` makes the change and `Down` undoes it. The schema builder writes the
right SQL for PostgreSQL, MySQL and SQLite:

```go
type createPosts struct{}

func (createPosts) Up(s *migrate.Schema) error {
	return s.Create("posts", func(t *migrate.Table) {
		t.ID()
		t.ForeignID("author_id").Constrained().CascadeOnDelete() // references authors(id)
		t.String("title", 200)
		t.Text("body")
		t.JSON("tags").Nullable()
		t.Integer("views").Default(0)
		t.Timestamp("published_at").Nullable()
		t.Timestamps()
		t.SoftDeletes()
		t.Index("author_id", "published_at")
	})
}

func (createPosts) Down(s *migrate.Schema) error { return s.Drop("posts") }
```

(Region `create-posts`.)

`t.ID()`, `t.Timestamps()` and `t.SoftDeletes()` create exactly the
columns `db.Model`, `db.Timestamps` and `db.SoftDeletes` expect.
`ForeignID(...).Constrained()` references the table named after the
column (`author_id` → `authors`). Every column type and option is in the
[migrations reference](https://docs.anetos.dev/reference/migrations/index.md).

To change an existing table, use `s.Alter`:

```go
// illustrative
func (addSubtitle) Up(s *migrate.Schema) error {
	return s.Alter("posts", func(t *migrate.Table) {
		t.String("subtitle", 200).Nullable()
		t.RenameColumn("body", "content")
		t.Index("subtitle")
	})
}
```

For anything the builder doesn't cover, write SQL with `s.Exec`, and use
`s.Dialect()` if it differs per database. SQL without arguments is sent
as written (a `?` is just a `?`), statements separated by `;` run one by
one, and trigger and function bodies (`BEGIN … END`, `$$ … $$`) stay
whole.

A column added to an existing table must be `Nullable()` or have a
`Default`: PostgreSQL and SQLite refuse a NOT NULL column without one on
a table with rows, and MySQL would silently fill in zeros, so the builder
refuses on every database.

### 3. Connect the runner

```go
if _, err := migrate.New(app, []*migrate.Set{Migrations, cache.Migrations("")}, migrate.WithSeeders(Seeders...)); err != nil {
	return nil, err
}
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `runner`.)

Pass one set per source: your app's, and one for each package or plugin
that ships migrations (here `cache.Migrations`, the table of the
database cache store). They run in ID order across all sets.

### 4. Run the commands

`migrate.New` registers the migration commands on the app, and
`app.Execute()` runs the one named on the command line:

```go
// go run .                 run the app (the default command)
// go run . migrate         and migrate:rollback, migrate:status, migrate:fresh --seed, db:seed
// go run . route:list     every route
// go run . blog:stats      a custom command (addCommands)
// go run . cache:clear     empty the cache
// go run . help            every command
app.Execute()
```

(Region `commands`.)

| Command | Does |
|---|---|
| `migrate [--seed]` | Applies pending migrations, as one batch (then runs the seeders) |
| `migrate:status` | Lists migrations: `Ran` (with batch), `Pending`, or `Missing` (applied but no longer in any set) |
| `migrate:rollback [--step=N]` | Undoes the last N batches (default 1: the last `migrate` run) |
| `migrate:reset` | Undoes every migration |
| `migrate:fresh [--seed]` | Drops **every table** and migrates from scratch; development and testing only |
| `db:seed [--seeder=NAME]` | Runs seeders (see [Seed the database](https://docs.anetos.dev/guides/seeders/index.md)) |

In production (any `APP_ENV` but `development`, `testing` and `staging`),
`migrate:rollback`, `migrate:reset`, `db:seed` and `migrate --seed` also
need `--force`; plain `migrate`, the normal deploy step, doesn't.
`migrate:fresh` runs only in development and testing. A flag a
command doesn't take is an error, and `-h` lists a command's flags.

### 5. Migrate when you deploy

Run `./app migrate` before the new version starts serving. Instances
starting at the same time are safe: on PostgreSQL and MySQL the runner
holds a lock in the database, so one instance migrates and the others
wait and find nothing left to do. The lock needs its own connection, so
the runner requires `DB_MAX_OPEN_CONNS` of at least 2 there.
[Deploy](https://docs.anetos.dev/guides/deployment/index.md#3-run-the-migrations-on-each-deploy) shows it
with systemd, containers and hosting platforms.

## SQL migrations (optional)

If you prefer SQL files, embed them and add them to the set; `ID.up.sql`
applies and `ID.down.sql` (optional) undoes. They are sent as written and
split at `;` like `s.Exec`; a first line `-- anetos:no-transaction` runs
the file outside a transaction, and `-- anetos:no-split` sends it as one
statement:

```go
// illustrative
//go:embed sql/*.sql
var sqlFiles embed.FS

func init() {
	if err := Migrations.AddFS(sqlFiles, "sql"); err != nil {
		panic(err)
	}
}
```

## How it works

Applied migrations are recorded in the `migrations` table with their set,
their ID and the batch they ran in. On PostgreSQL and SQLite each
migration and its record run in one transaction, so a migration that
fails leaves nothing behind and can simply be fixed and re-run. MySQL
commits every schema change immediately: a migration that fails halfway
leaves its first changes in place, so keep MySQL migrations small.
Data changes in a MySQL migration aren't transactional either. For a
migration that must not run in a transaction (PostgreSQL's `CREATE INDEX
CONCURRENTLY`), implement `WithoutTransaction()`, or add it with
`set.Add(id, migrate.NoTransaction(migrate.Func(up, down)))`.

On SQLite, foreign key enforcement is off while a migration runs (and
`PRAGMA foreign_key_check` must pass before it commits). That makes the
usual way to change a column safe: create the new table, copy the rows,
drop the old table, rename the new one. The drop doesn't cascade to the
tables that reference it.

Migrations are Go code compiled into the binary, so a deploy ships exactly
the migrations its code expects, and no migration files need to be copied
to the server.

> **Coming from another framework?** `s.Create` and `s.Alter` are
> Laravel's `Schema::create` and `Schema::table`, or Rails'
> `create_table` and `change_table`, and
> `t.ForeignID("user_id").Constrained()` adds a foreign key, as
> `foreignId('user_id')->constrained()` and
> `t.references :user, foreign_key: true` do. Django writes migrations
> from the models instead. Migrations are registered in a set instead of
> discovered from a directory.

## Testing it

`anetostest.New(t, setup)` runs the migrations `migrate.New`
registered before each test (see [Test your app](https://docs.anetos.dev/guides/testing/index.md)). To check
that every `Down` works, roll back in a test, outside the test's
transaction (MySQL commits on every schema change):

```go
// illustrative
app := anetostest.New(t, setup, anetostest.WithoutTransaction())
runner, _ := anetos.Resolve[*migrate.Runner](app.App)
if _, err := runner.Reset(app.Context()); err != nil {
	t.Fatal(err)
}
```

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `SQLite can't change columns` | SQLite's `ALTER TABLE` can't modify a column | Create the new table, copy the rows with `s.Exec`, drop the old one, rename (foreign keys are off during the migration) |
| `a column added to an existing table needs Nullable() or a Default` | NOT NULL without a default fails (or is silently zero-filled) on existing rows | Add `Nullable()` or `Default(…)`; backfill, then `Change()` it to NOT NULL |
| `the runner needs at least 2 connections` | `DB_MAX_OPEN_CONNS=1` on PostgreSQL or MySQL | Allow 2 or more |
| `cannot be cast automatically` from a PostgreSQL `Change()` | The type change needs a conversion | Add `.Using("code::integer")` |
| `relation … already exists` for an index | Two long index names were cut to the same prefix by an older tool | Name them: `t.IndexNamed(name, cols...)` |
| `SQLite can't add a column defaulting to the current time` | SQLite only allows constant defaults in `ADD COLUMN` | Add it `Nullable()` and fill it with `s.Exec("UPDATE …")` |
| `… is applied but not registered, so it can't be rolled back` | A migration was removed from the set after it ran | Put it back, or leave that batch alone |
| `fresh drops every table and only runs in development and testing` | `APP_ENV` is production or staging | Use `migrate:rollback`/`migrate` there |
| A MySQL migration failed and re-running it says a table exists | MySQL doesn't roll back schema changes | Undo the partial change by hand, then re-run |
| Migrations run in the wrong order | IDs don't start with a sortable timestamp | Name them `YYYY_MM_DD_HHMMSS_description` |

## Next steps

- [Deploy](https://docs.anetos.dev/guides/deployment/index.md)
- [Seed the database](https://docs.anetos.dev/guides/seeders/index.md)
- [Migrations reference](https://docs.anetos.dev/reference/migrations/index.md)
- [Define models and save data](https://docs.anetos.dev/guides/models/index.md)


# Query data

Source: https://docs.anetos.dev/guides/queries/

Find rows with typed conditions, sort and paginate them, aggregate, and
update or delete in bulk.

## Before you start

[Define your models](https://docs.anetos.dev/guides/models/index.md).

## Steps

### 1. Build a query

`db.Query[T](ctx)` starts a query on `T`'s table. Conditions use the
typed columns that [`anetos generate`](https://docs.anetos.dev/guides/code-generation/index.md) writes for each
model, so `PostCols.Views.Eq("ten")` doesn't compile:

```go
// illustrative
posts, err := db.Query[Post](ctx).
	Where(PostCols.Title.Like("%go%"), PostCols.Views.Gte(100)). // AND
	Where(db.Or(PostCols.AuthorID.Eq(1), PostCols.AuthorID.Eq(2))).
	OrderBy(PostCols.Views.Desc()).
	Limit(20).
	Get()
```

A column has its field's type: compare a nullable `*time.Time` column
with `new(t)`. For a quick query, `db.C("views")` is an untyped column,
and `db.Col[int]("views")` declares a typed one by hand.

Columns have `Eq`, `Ne`, `Gt`, `Gte`, `Lt`, `Lte`, `In`, `NotIn`,
`Between`, `Like`, `NotLike`, `IsNull` and `NotNull`. Combine conditions
with `db.And`, `db.Or` and `db.Not`, and write anything else in SQL with
`db.SQL("lower(email) = ?", email)` or `WhereRaw`.

Every method returns a new query, so a base query can be shared (a query
keeps the context it was started with; `WithContext` changes it):

```go
// illustrative
published := db.Query[Post](ctx).Where(PostCols.PublishedAt.NotNull())
latest, err := published.Latest().Limit(5).Get()
total, err := published.Count()
```

### 2. Get results

| Call | Returns |
|---|---|
| `Get()` | `[]T` (empty, not nil, when nothing matches) |
| `First()` | the first row, or `db.ErrNotFound` (add `OrderBy` to choose which) |
| `Find(id)` | the row with that primary key, or `db.ErrNotFound` |
| `All()` | an iterator: `for p, err := range q.All()`, for large results |
| `Count()`, `Exists()` | how many rows match; whether any does |
| `db.Pluck(q, col)` | one column's values |
| `db.Sum`, `db.Avg`, `db.Min`, `db.Max` | aggregates of a column |

### 3. Paginate

```go
// illustrative
page, err := db.Query[Post](ctx).Latest().Paginate(in.Page, 20)
```

Pages are 1-based; 0 or a negative page (a missing `?page=`) is the
first page, and a page past the end is empty. `perPage` often comes from
the request: bound it with `validate:"max:100"`. Order by a unique column
last (`PostCols.ID.Desc()` after `Latest()`), or rows created in the same
instant can move between pages.

A `db.Page[T]` has `Data`, `CurrentPage`, `PerPage`, `Total` and
`LastPage`, with `HasPrev()` and `HasNext()`. It encodes as JSON with
those fields, so an API handler returns it as it is:
`{"data": […], "current_page": 2, "per_page": 20, "total": 57, "last_page": 3}`.

For an HTML list, pass the page to the view (`ListNotes` binds
``Page int `query:"page"` ``):

```go
func (Notes) Index(c *web.Ctx, in ListNotes) (web.Responder, error) {
	// Newest first; the ID breaks ties between notes created in the same
	// instant, so no note shows on two pages. With search words, the
	// best matches come first, then the newest. Search of no words
	// changes nothing.
	page, err := db.Query[Note](c).OrderBy(NoteCols.CreatedAt.Desc(), NoteCols.ID.Desc()).
		Search(in.Q).
		Paginate(in.Page, 10)
	if err != nil {
		return nil, err
	}
	return web.Render(NotesPage(page, in.Q)), nil
}
```

(Copied from [`examples/forms`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main.go), region `index`.)

and link to the pages around it with `web.PageURL(ctx, n)`: a relative
link (`?q=go&page=2`) that keeps the other query parameters (a search, a
filter). Past the end, the "Newer" link goes back to the last page:

```templ
// NotesPage lists one page of notes, with links to the pages around it
// (they keep the search words, q) and a search box.
templ NotesPage(page db.Page[Note], q string) {
	@Layout("All notes") {
		<h1>Notes</h1>
		<p><a href={ web.URL(ctx, "notes.new") }>New note</a></p>
		<form method="get" action={ web.URL(ctx, "notes.index") } role="search">
			<input type="search" name="q" value={ q } aria-label="Search notes"/>
			<button type="submit">Search</button>
		</form>
		if page.Total == 0 && q != "" {
			<p>No notes match “{ q }”.</p>
		} else if page.Total == 0 {
			<p>No notes yet.</p>
		}
		<ul class="notes">
			for _, n := range page.Data {
				@noteItem(n)
			}
		</ul>
		<nav class="pages">
			if page.HasPrev() {
				<a href={ web.PageURL(ctx, min(page.CurrentPage-1, page.LastPage)) } rel="prev">Newer</a>
			}
			if page.LastPage > 1 {
				<span>Page { page.CurrentPage } of { page.LastPage }</span>
			}
			if page.HasNext() {
				<a href={ web.PageURL(ctx, page.CurrentPage+1) } rel="next">Older</a>
			}
		</nav>
	}
}
```

(Copied from [`examples/forms/notes.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/notes.templ), region `list`.)

In a project made with `anetos new`, `views/ui` writes these links for
you: `ui.PagesOf` makes them with `web.PageURL`, and `ui.Pagination`
shows them ([UI components reference](https://docs.anetos.dev/reference/ui/index.md#types)):

```templ
// illustrative
if page.LastPage > 1 {
	@ui.Pagination(ui.PagesOf(ctx, page, "Pages", fmt.Sprintf("Page %d of %d", page.CurrentPage, page.LastPage), "Newer", "Older"))
}
```

For long lists and infinite scroll, cursor pagination stays fast at any
depth and never repeats or skips rows as new ones arrive:

```go
// illustrative
page, err := db.Query[Post](ctx).OrderBy(PostCols.CreatedAt.Desc()).CursorPaginate(in.Cursor, 20)
// page.NextCursor and page.PrevCursor go back to the client
```

An invalid cursor returns `db.ErrInvalidCursor`, a **400**.

### 4. Group and aggregate

Scan grouped results into a struct of your own:

```go
// illustrative
type authorStats struct {
	AuthorID int64 `db:"author_id"`
	Posts    int64 `db:"posts"`
}
stats, err := db.Select[authorStats](
	db.Query[Post](ctx).GroupBy("author_id").Having(db.SQL("COUNT(*) > ?", 5)),
	"author_id", "COUNT(*) AS posts")
```

With a `Join`, qualify columns that both tables have:
`PostCols.ID.Of("posts")` is `posts.id`. For joins across several tables,
[raw SQL](https://docs.anetos.dev/guides/raw-sql/index.md) is often clearer.

### 5. Update or delete many rows

```go
// illustrative
n, err := db.Query[Post](ctx).Where(PostCols.AuthorID.Eq(id)).Update(
	PostCols.Title.Set("[removed]"),
	PostCols.Views.SetRaw("views + ?", 1))

n, err = db.Query[Post](ctx).Where(PostCols.Views.Eq(0)).Delete() // soft delete for SoftDeletes models
```

Mass updates set `updated_at`; they don't run model hooks.

### 6. Reuse conditions as scopes

```go
// illustrative
func Popular(q *db.Q[Post]) *db.Q[Post] { return q.Where(PostCols.Views.Gte(1000)) }

posts, err := db.Query[Post](ctx).Scope(Popular).Get()
```

## Complete example

`ListPosts` in [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go)
combines filters from the query string with pagination.

## How it works

The query builder writes SQL for the database's dialect (placeholders,
quoting, `LIMIT` forms) and sends values as parameters, never inside the
SQL text. Soft-deleted rows are excluded unless you call `WithTrashed()`
or `OnlyTrashed()`. Every method is listed in the
[query builder reference](https://docs.anetos.dev/reference/query-builder/index.md).

> **Coming from another framework?** `Where(PostCols.Title.Like(…))` is
> a condition on a typed column, where Django, Laravel and Rails take a
> string or a keyword (`filter(title__contains=…)`,
> `where('title', 'like', …)`). Scopes are plain functions instead of
> methods. There is no lazy loading: load relations with `With`
> ([Relations and eager loading](https://docs.anetos.dev/guides/relations/index.md)).

## Testing it

Create the rows a query should (and shouldn't) find with
[factories](https://docs.anetos.dev/guides/testing/index.md#4-make-rows-with-factories), then run it on
`app.Context()` of an `anetostest` app.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `Update and Delete only support Where conditions` | `Join`, `OrderBy`, `Limit` and friends don't work the same on every database | Filter with `Where`, or write the statement for your database with `db.Exec` |
| `ambiguous column` after a `Join` | Both tables have the column | Qualify it: `db.C("posts.id")` |
| `First` returns a different row each time | No `OrderBy` | Add one |
| `LIKE` matches differently between databases | PostgreSQL is case-sensitive | Use `db.SQL("lower(title) LIKE ?", …)` or a database-specific operator |

## Next steps

- [Transactions](https://docs.anetos.dev/guides/transactions/index.md)
- [Raw SQL](https://docs.anetos.dev/guides/raw-sql/index.md)
- [Query builder reference](https://docs.anetos.dev/reference/query-builder/index.md)


# Relations and eager loading

Source: https://docs.anetos.dev/guides/relations/

Declare how models relate (a post belongs to an author, an author has many
posts, posts have many tags), load related rows in one query per relation,
and filter rows by what they relate to.

## Before you start

[Define your models](https://docs.anetos.dev/guides/models/index.md) and generate their typed columns with
[`anetos generate`](https://docs.anetos.dev/guides/code-generation/index.md). The foreign key columns must exist in
your tables ([migrations](https://docs.anetos.dev/guides/migrations/index.md)).

## Steps

### 1. Declare the relations

A relation is a field with a `rel` tag: a pointer for `belongs_to` and
`has_one`, a slice for `has_many` and `many_to_many`:

```go
// Author writes posts.
type Author struct {
	db.Model        // id, created_at, updated_at
	Name     string `db:"name" json:"name"`
	Email    string `db:"email" json:"email"`

	Posts []Post `rel:"has_many" json:"posts,omitzero"` // posts.author_id; loaded with With or Load
}

// Post is a blog post. Deleting one only marks it deleted.
type Post struct {
	db.Model
	db.SoftDeletes            // deleted_at
	AuthorID       int64      `db:"author_id" json:"author_id"`
	Title          string     `db:"title" json:"title"`
	Body           string     `db:"body" json:"body"`
	Tags           []string   `db:"tags,json" json:"tags"` // stored as JSON text
	Views          int        `db:"views" json:"views"`
	PublishedAt    *time.Time `db:"published_at" json:"published_at"` // nullable

	Author *Author `rel:"belongs_to" json:"author,omitzero"` // by AuthorID
}

// AuthorCols and PostCols, the typed columns of the models, and
// AuthorRels and PostRels, their relations, are in models_gen.go, written
// by `go tool anetos generate` (or go generate).
//
//go:generate go tool anetos generate
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `models`.)

The keys follow conventions, which tag options override:

| Kind | Field | Keys by default | Options |
|---|---|---|---|
| `belongs_to` | `Author *Author` | this model's `author_id` → the author's primary key | `fk=writer_id`, `references=uuid` |
| `has_one` | `Profile *Profile` | `profiles.author_id` → this model's primary key | `fk=`, `local=` |
| `has_many` | `Posts []Post` | `posts.author_id` → this model's primary key | `fk=`, `local=` |
| `many_to_many` | `Tags []Tag` | pivot table `post_tag` (both names, sorted) with `post_id` and `tag_id` | `pivot=post_tags`, `fk=post_id`, `related_fk=tag_id` |

A many-to-many relation needs its pivot table, created in a migration,
with a primary key (or unique index) on the two columns, which `Attach`
relies on:

```go
// illustrative
type Post struct {
	db.Model
	Tags []Tag `rel:"many_to_many"` // post_tag (post_id, tag_id)
}

return s.Create("post_tag", func(t *migrate.Table) {
	t.ForeignID("post_id").Constrained().CascadeOnDelete()
	t.ForeignID("tag_id").Constrained().CascadeOnDelete()
	t.Primary("post_id", "tag_id")
})
```

Run `go tool anetos generate` (or `go generate ./...`): next to `PostCols`, it
writes `PostRels`, one handle per relation field (`PostRels.Author`,
`AuthorRels.Posts`).

### 2. Load them with the query

`With` loads relations of the rows a query returns, with one extra query
per relation however many rows there are:

```go
func (Blog) ListPosts(c *web.Ctx, in ListPosts) (db.Page[Post], error) {
	q := db.Query[Post](c).Where(PostCols.PublishedAt.NotNull())
	if in.Search != "" {
		q = q.Where(PostCols.Title.Contains(in.Search)) // % and _ match themselves
	}
	if in.Author != nil {
		q = q.Where(PostCols.AuthorID.Eq(*in.Author))
	}
	return q.With(PostRels.Author).Latest().Paginate(in.Page, in.PerPage) // one query for all the authors
}
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `list-posts`.)

`Get`, `First`, `Find`, `Paginate` and `CursorPaginate` load relations.
Load several at once, and relations of the related rows with `With` on
the handle:

```go
// illustrative
posts, err := db.Query[Post](ctx).
	With(PostRels.Author, PostRels.Comments.With(CommentRels.Author), PostRels.Tags).
	Get()
```

A relation that finds nothing is `nil` (pointers) or an empty slice
(slices). A field that wasn't loaded stays `nil`. With `json:",omitzero"`,
as in the models above, an unloaded relation is left out of JSON while a
loaded empty list encodes as `[]`.

### 3. Or load them afterwards

`db.Load` loads relations of one row, `db.LoadMany` of a slice, in place:

```go
// illustrative
post, err := db.Find[Post](ctx, id)
err = db.Load(ctx, &post, PostRels.Author, PostRels.Tags)

posts, err := db.Query[Post](ctx).Get()
err = db.LoadMany(ctx, posts, PostRels.Author)
```

### 4. Limit and order the related rows

`Where`, `OrderBy` and `WithTrashed` on a handle apply to the relation's
query. Without `OrderBy`, related rows come in primary key order (and a
`has_one` gets the first match); soft-deleted related rows are left out
unless `WithTrashed`. A many-to-many query joins the pivot table, so
qualify columns the pivot also has: `TagCols.Name.Of("tags")`.

```go
// illustrative
db.Query[Post](ctx).With(
	PostRels.Comments.Where(CommentCols.Approved.Eq(true)).OrderBy(CommentCols.CreatedAt.Desc()),
)
```

### 5. Filter by relations

`WhereHas` keeps the rows that have a related row matching the conditions,
`WhereDoesntHave` those that don't. Combined with `With`:

```go
// ListAuthors returns the authors with a published post, with those posts.
func (Blog) ListAuthors(c *web.Ctx, _ struct{}) ([]Author, error) {
	published := PostCols.PublishedAt.NotNull()
	return db.Query[Author](c).
		WhereHas(AuthorRels.Posts, published).
		With(AuthorRels.Posts.Where(published).OrderBy(PostCols.PublishedAt.Desc())).
		OrderBy(AuthorCols.Name.Asc()).
		Get()
}
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `where-has`.)

The conditions use the related model's columns. `WhereHas` is an
`EXISTS` subquery, so it adds no rows and needs no `Distinct`.

### 6. Link many-to-many rows

`db.Attach`, `db.Detach`, `db.DetachAll` and `db.Sync` write the pivot
table of a `many_to_many` relation, by the related rows' primary keys:

```go
// illustrative
err := db.Attach(ctx, &post, PostRels.Tags, goTag.ID, webTag.ID) // adds missing links
err = db.Detach(ctx, &post, PostRels.Tags, webTag.ID)           // no ids: nothing to do
err = db.DetachAll(ctx, &post, PostRels.Tags)                   // every link of the post
err = db.Sync(ctx, &post, PostRels.Tags, goTag.ID)              // exactly these (none: none)
```

Each runs in a transaction (joining yours, if the context has one).
`Attach` skips links that exist, also ones another request adds at the
same moment.

## Complete example

[`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go) loads each
post's author (`GET /posts`, `GET /posts/{id}`) and lists the authors with
published posts (`GET /authors`).

## How it works

Relations are loaded **only when you ask**: there is no lazy loading, so
reading `post.Author` never runs a query behind your back, and the N+1
pattern (one query per row) has to be written out to happen, and then
it is [reported](https://docs.anetos.dev/guides/n-plus-one/index.md) in development and tests. `With`
collects the keys of the rows it got, runs one `WHERE key IN (…)` query per
relation (in chunks of 1,000 keys), and hands out the results; a
many-to-many relation reads the pivot table first. Rows that belong to the
same parent share one value: posts by the same author get the same
`*Author`.

Handles are typed: `PostRels.Author` is a `db.Rel[Post, Author]`, and
`With` on a `Post` query only takes `Post` relations. Handles written by
hand (`db.RelOf[Post, Author]("Author")`) are checked when used: a wrong
field or type is an error from the query.

> **Coming from another framework?** `rel:"has_many"`, `With` and
> `WhereHas` do what Django's `ForeignKey` and `prefetch_related`,
> Laravel's `hasMany`, `with()` and `whereHas()`, or Rails' `has_many`
> and `includes` do, and `Attach`/`Detach`/`Sync` manage many-to-many
> rows. Nested loads chain handles
> (`PostRels.Comments.With(CommentRels.Author)`) instead of dotted
> strings, and there are no dynamic properties: an unloaded relation is
> `nil`, never a hidden query.

## Testing it

Create rows with [factories](https://docs.anetos.dev/guides/testing/index.md#4-make-rows-with-factories) and
check what a page or API returns:

```go
func TestAuthorsWithPublishedPosts(t *testing.T) {
	app := anetostest.New(t, setup)
	now := time.Now().UTC()
	ada := anetostest.Create(app, Authors.With(func(a *Author) { a.Name = "Ada" }))
	grace := anetostest.Create(app, Authors.With(func(a *Author) { a.Name = "Grace" }))
	anetostest.Create(app, Posts.With(func(p *Post) { p.AuthorID, p.Title, p.PublishedAt = ada.ID, "Published", &now }))
	anetostest.Create(app, Posts.With(func(p *Post) { p.AuthorID, p.Title = ada.ID, "Draft" }))
	anetostest.Create(app, Posts.With(func(p *Post) { p.AuthorID = grace.ID })) // Grace has drafts only

	app.GetJSON("/authors").
		AssertOK().
		AssertJSONPath("0.name", "Ada").
		AssertJSONPath("0.posts.0.title", "Published").
		AssertDontSee("Grace", "Draft")
}
```

(Copied from [`examples/database/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main_test.go), region `test-relations`.)

To check that a page loads its relations without an N+1, call
`app.AssertNoRepeatedQueries()` after its requests: see
[Find N+1 queries](https://docs.anetos.dev/guides/n-plus-one/index.md#3-keep-it-fixed-with-a-test).

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `has no column "author_id"` | The key column's name differs from the convention | Name it in the tag: `rel:"belongs_to,fk=writer_id"` |
| `has no column "blog_post_id" (fk)` | A `has_many` or `has_one` looks for `<type>_id` on the related model | `rel:"has_many,fk=post_id"` |
| `no such table: post_tag` | The pivot table has another name, or no migration | `rel:"many_to_many,pivot=post_tags"`, and create it |
| `All can't load relations` | Streaming can't batch rows | Use `Get` or `Paginate`, or `db.LoadMany` on batches |
| `a relation is a pointer to a model` / `a slice of models` | The field's type doesn't match the kind | `*Author` for `belongs_to`/`has_one`, `[]Post` for `has_many`/`many_to_many` |
| Changing `post.Author` changes other posts' authors | Posts by one author share the loaded `*Author` | Copy the value before changing it |
| An API returns `"author": null` for unloaded rows | The field isn't loaded | Load it, or add `omitzero` to its json tag |
| `relation … is loaded twice` | The same relation passed twice to `With` | Pass it once, with all its nested relations |
| A `repeated query: an N+1?` warning | A query in a loop, one per row | Load the relation with `With` or `db.LoadMany`: [Find N+1 queries](https://docs.anetos.dev/guides/n-plus-one/index.md) |
| `both pivot columns are "user_id"` | A many-to-many from a model to itself | Name them: `rel:"many_to_many,pivot=friendships,fk=user_id,related_fk=friend_id"` |
| An `ON CONFLICT` error from `Attach` (no matching unique constraint) | The pivot table has no primary key or unique index on its two columns | Add one in a migration |
| MySQL error 1093 from `Update` or `Delete` with `WhereHas` | MySQL can't read a table it writes in a subquery (a relation to the same table) | Select the keys first, then update `WhereIn` them |

## Next steps

- [Query the database](https://docs.anetos.dev/guides/queries/index.md)
- [Models reference](https://docs.anetos.dev/reference/models/index.md#relations)
- [Code generation](https://docs.anetos.dev/guides/code-generation/index.md)


# Transactions

Source: https://docs.anetos.dev/guides/transactions/

Make several writes succeed or fail together, and run follow-up work only
after they are saved.

## Before you start

[Connect to a database](https://docs.anetos.dev/guides/database/index.md).

## Steps

### 1. Wrap the work in `db.Tx`

```go
// illustrative
err := db.Tx(ctx, func(ctx context.Context) error {
	if err := db.Create(ctx, &order); err != nil {
		return err // rolls back
	}
	return db.Create(ctx, &payment) // nil commits
})
```

Use the `ctx` passed to the function: the transaction travels in it, so
every query made with it (including in functions you call) joins the
transaction. An error or a panic rolls everything back.

### 2. Nest freely

Calling `db.Tx` inside a transaction starts a nested one with a
savepoint. If it fails, only its own work is undone, and the outer
function decides what to do:

```go
// illustrative
err := db.Tx(ctx, func(ctx context.Context) error {
	if err := db.Create(ctx, &order); err != nil {
		return err
	}
	if err := db.Tx(ctx, applyCoupon); err != nil {
		log.Warn("coupon not applied", "error", err) // the order still commits
	}
	return nil
})
```

### 3. Run side effects after commit

Emails, jobs and cache updates must not happen if the data is rolled
back. (For jobs, `queue.Dispatch` has the option `queue.AfterCommit()`;
see [Queues](https://docs.anetos.dev/guides/queues/index.md#3-dispatch-jobs).)

```go
// illustrative
db.AfterCommit(ctx, func(ctx context.Context) {
	mailer.Send(ctx, OrderConfirmation{Order: order})
})
```

Outside a transaction, the function runs immediately. If the (nested)
transaction it was registered in rolls back, it never runs.

Delete cached values the same way, so no request caches the old data
again between the delete and the commit:

```go
// illustrative
db.AfterCommit(ctx, func(ctx context.Context) {
	_ = cache.Delete(ctx, "stats")
})
```

### 4. Lock rows you are about to change

```go
// illustrative
err := db.Tx(ctx, func(ctx context.Context) error {
	acct, err := db.Query[Account](ctx).Where(id.Eq(in.ID)).ForUpdate().First()
	if err != nil {
		return err
	}
	acct.Balance -= in.Amount
	return db.Update(ctx, &acct)
})
```

`ForUpdate` (and `ForShare`) lock the selected rows until the transaction
ends. SQLite has no row locks; its transactions take the database's write
lock when they start.

Use `db.TxWithOptions(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable}, fn)`
for another isolation level or a read-only transaction.

### 5. Write outside the transaction

A record that must stay even if the transaction rolls back, such as an
audit entry for the attempt, is written with `db.WithoutTx(ctx)`, which
uses another connection:

```go
// illustrative
err := db.Tx(ctx, func(ctx context.Context) error {
	if err := db.Create(db.WithoutTx(ctx), &Audit{Action: "refund", OrderID: order.ID}); err != nil {
		return err
	}
	return refund(ctx, order)
})
```

With SQLite, whose transactions take the database's write lock when
they start, such a write waits for the transaction and fails after the
busy timeout: don't use `WithoutTx` there.

## Complete example

`ShowPost` in [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go)
counts a view and reads the post in one transaction.

## How it works

`db.Tx` begins a `database/sql` transaction and returns a context holding
it. If the function panics or calls `runtime.Goexit` (as `t.Fatal` does),
the transaction is rolled back and its connection released. If the
context is canceled before the commit, the returned error wraps
`context.Canceled`. Queries on that context's database use the transaction instead of the
pool. Nested calls issue `SAVEPOINT`, `ROLLBACK TO SAVEPOINT` and `RELEASE
SAVEPOINT`, which PostgreSQL, MySQL and SQLite all support. See the
[data layer concept](https://docs.anetos.dev/concepts/data-layer/index.md).

> **Coming from another framework?** `db.Tx` is Django's
> `transaction.atomic()`, Laravel's `DB::transaction()` or Rails'
> `transaction` block. A nested `db.Tx` uses a savepoint, as nested
> `atomic()` and `DB::transaction()` do (Rails needs
> `requires_new: true`). `db.AfterCommit` is `transaction.on_commit()`,
> `DB::afterCommit()` or `ActiveRecord.after_all_transactions_commit`.

## Testing it

Call the function under test with a context from an in-memory database and
check the rows afterwards; `db.InTx(ctx)` reports whether code runs in a
transaction.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| Writes inside `Tx` are visible to other requests before commit | The code used the outer `ctx`, not the one passed to the function | Use the function's `ctx`; a query built earlier joins with `q.WithContext(ctx)` |
| A test hangs on an in-memory SQLite database | It has a single connection, and something waited for a second one (a query on the outer `ctx` inside `Tx`, or inside an `All()` loop) | Use the transaction's `ctx`; finish the loop first; or use a temporary database file |
| `conn busy` or a deadlock while iterating `All()` in a transaction | The transaction's single connection is still reading rows | Finish the loop (or use `Get`) before other queries |
| Queries from several goroutines in one transaction fail | A transaction is one connection | Run them one after another |

## Next steps

- [Query data](https://docs.anetos.dev/guides/queries/index.md)
- [Raw SQL](https://docs.anetos.dev/guides/raw-sql/index.md)


# Raw SQL

Source: https://docs.anetos.dev/guides/raw-sql/

Write SQL yourself and scan the results into structs, when the query
builder is in the way.

## Before you start

[Connect to a database](https://docs.anetos.dev/guides/database/index.md).

## Steps

### 1. Scan rows into a struct

```go
// AuthorStats is one row of GET /stats.
type AuthorStats struct {
	Name  string `db:"name" json:"name"`
	Posts int64  `db:"posts" json:"posts"`
	Views int64  `db:"views" json:"views"`
}

func authorStats(ctx context.Context) ([]AuthorStats, error) {
	return db.Raw[AuthorStats](ctx, `
		SELECT a.name, COUNT(p.id) AS posts, COALESCE(SUM(p.views), 0) AS views
		FROM authors a LEFT JOIN posts p ON p.author_id = a.id AND p.deleted_at IS NULL
		GROUP BY a.id, a.name
		ORDER BY views DESC`)
}
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `raw`.)

Columns match the struct's `db` tags (or snake_case field names). Columns
without a field are ignored, and fields without a column keep their zero
values, so one struct can serve several queries.

### 2. Pass parameters

Write `?` on every database; it becomes `$1`, `$2`… on PostgreSQL:

```go
// illustrative
posts, err := db.Raw[Post](ctx, "SELECT * FROM posts WHERE author_id = ? AND views > ?", id, 100)
```

Or name them with `db.Named`:

```go
// illustrative
n, err := db.RawFirst[int64](ctx,
	"SELECT COUNT(*) FROM posts WHERE author_id = :author AND created_at > :since",
	db.Named{"author": id, "since": since})
```

`?` inside quotes and comments is left alone. SQL without arguments is
sent exactly as written. With arguments on PostgreSQL, write `??` for a
literal `?`, such as the JSON operators (`tags ??| array['go']`). A whole
query without `?` is also sent unchanged, so native `$1` placeholders
work; SQL fragments in the query builder (`db.SQL`, `WhereRaw`) must use
`?`.

### 3. Read one row or one value

`db.RawFirst[T]` returns the first row, or `db.ErrNotFound`. `T` can be a
single value such as `int64`, `string` or `time.Time` for one-column
results.

### 4. Run statements

```go
// illustrative
res, err := db.Exec(ctx, "UPDATE posts SET views = 0 WHERE author_id = ?", id)
n, _ := res.RowsAffected()
```

Raw queries and statements join the context's transaction like any other
query.

## Complete example

`authorStats` in [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), which the `GET /stats` handler caches ([Cache](https://docs.anetos.dev/guides/cache/index.md)).

## How it works

`db.Raw` rewrites placeholders for the dialect, runs the query, and scans
with a column-to-field plan cached per struct type and column list. SQL is
passed through otherwise: you choose the dialect-specific syntax.

## Testing it

Seed an in-memory SQLite database and compare the scanned structs.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `the SQL has 2 ? placeholders but 1 arguments were given` | Placeholder count mismatch, or a `?` operator | Pass every argument; write `??` for a literal `?` |
| `scanning into int64 needs exactly one column` | A scalar `T` with several columns | Select one column, or scan into a struct |
| `converting NULL to …` | A NULL (often from a `LEFT JOIN`) in a non-pointer field | Use a pointer field or `COALESCE` |
| A column is always zero | Its name doesn't match a tag | Alias it: `COUNT(*) AS posts` |

## Next steps

- [Query data](https://docs.anetos.dev/guides/queries/index.md)
- [Transactions](https://docs.anetos.dev/guides/transactions/index.md)


# Seed the database

Source: https://docs.anetos.dev/guides/seeders/

Fill a database with sample data for development, or with the reference
data every environment needs.

## Before you start

[Create your tables with migrations](https://docs.anetos.dev/guides/migrations/index.md).

## Steps

### 1. Write seeders

A seeder is a name and a function. Use the db package inside it:

```go
// Seeders fill a development database with sample data: go run . db:seed
var Seeders = []migrate.Seeder{
	{Name: "authors", Run: func(ctx context.Context) error {
		return db.CreateMany(ctx, []Author{
			{Name: "Ada", Email: "ada@example.com"},
			{Name: "Grace", Email: "grace@example.com"},
		})
	}},
	{Name: "posts", Run: func(ctx context.Context) error {
		ada, err := db.Query[Author](ctx).Where(AuthorCols.Email.Eq("ada@example.com")).First()
		if err != nil {
			return err
		}
		now := anetos.Now(ctx).UTC()
		return db.CreateMany(ctx, []Post{
			{AuthorID: ada.ID, Title: "Hello, Anetos", Body: "The first post.", PublishedAt: &now},
			{AuthorID: ada.ID, Title: "A draft", Body: "Not published yet."},
		})
	}},
}
```

(Copied from [`examples/database/migrations.go`](https://github.com/anetos-dev/anetos/blob/main/examples/database/migrations.go), region `seeders`.)

`AuthorCols` holds the model's typed columns, written by
[`anetos generate`](https://docs.anetos.dev/guides/code-generation/index.md).

For many rows, use a [factory](https://docs.anetos.dev/guides/testing/index.md#4-make-rows-with-factories),
the same one the tests use:

```go
// Seeders add sample notes: go run . db:seed
var Seeders = []migrate.Seeder{
	{Name: "notes", Run: func(ctx context.Context) error {
		_, err := NoteFactory.CreateMany(ctx, 25) // see factories.go
		return err
	}},
}
```

(Copied from [`examples/forms/models.go`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/models.go), region `seeders`.)

In a project made with `anetos new`, factories go in `database/factories`
and seeders in `database/migrations`.

### 2. Give them to the runner

```go
// illustrative
runner, err := migrate.New(app, []*migrate.Set{Migrations}, migrate.WithSeeders(Seeders...))
```

### 3. Run them

```sh
./app db:seed                 # every seeder, in order
./app db:seed --seeder=posts  # one of them
./app migrate:fresh --seed    # rebuild the database and seed it (development and testing only)
```

In production, `db:seed` needs `--force`.

## How it works

Seeders run in the order they are listed, each in its own transaction:
if one fails, its changes are rolled back and the ones before it stay.
Order them so data exists before other data refers to it.

> **Coming from another framework?** Seeders play the role of Django's
> fixtures, Laravel's seeders or Rails' `db/seeds.rb`, and the list
> passed to the runner is the order they run in. Factories are values
> made with `factory.New`, as factory_boy, Laravel's factories and
> FactoryBot make them.

## Testing it

`runner.Seed(ctx)` in a test fills a fresh in-memory database, which is a
quick way to test code against realistic data.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `no seeder named "users"` | Not in the list passed with `WithSeeders` | Add it |
| A seeder fails with a unique-constraint error on the second run | Seeders insert again each time | Use `db.Upsert`, or check with `Exists` first |

## Next steps

- [Migrations](https://docs.anetos.dev/guides/migrations/index.md)


# Generate typed columns

Source: https://docs.anetos.dev/guides/code-generation/

Let `anetos generate` declare a typed column for every field of your models,
and a handle for every relation, so queries say
`PostCols.Title.Like("%go%")` and `With(PostRels.Author)`, and the compiler
checks the column name, the value's type and the relation's model.

## Before you start

[Define your models](https://docs.anetos.dev/guides/models/index.md). You need Go 1.26 or later.

## Steps

### 1. Add the anetos tool to your module

```sh
go get -tool anetos.dev/anetos/cli/cmd/anetos@v0.5.0-rc.1
```

This records the tool in `go.mod` (a `tool` line), so everyone on the
project runs the same version with `go tool anetos`. It adds nothing to
your application binary.

### 2. Generate

```sh
go tool anetos generate
```

For every package with models under the current directory, this writes
`models_gen.go` next to them:

```go
// illustrative (an excerpt of examples/database/models_gen.go)
// Code generated by anetos generate. DO NOT EDIT.

package main

import (
	"time"

	"anetos.dev/anetos/db"
)

// AuthorCols are the columns of [Author].
var AuthorCols = struct {
	ID        db.Column[int64]
	CreatedAt db.Column[time.Time]
	UpdatedAt db.Column[time.Time]
	Name      db.Column[string]
	Email     db.Column[string]
}{
	ID:        db.Col[int64]("id"),
	CreatedAt: db.Col[time.Time]("created_at"),
	UpdatedAt: db.Col[time.Time]("updated_at"),
	Name:      db.Col[string]("name"),
	Email:     db.Col[string]("email"),
}
```

Each model `Post` gets `PostCols` (an unexported `post` gets `postCols`),
with one field per column, named like the struct field and typed like it.
Commit the file: it is plain Go, and *go to definition* works on it.

A **model** is a struct that:

- embeds `db.Model`, `db.Timestamps` or `db.SoftDeletes` (directly, or
  through another embedded struct), or
- has a `TableName() string` method, or
- has a `//anetos:model` line in its doc comment.

Add `//anetos:skip` to leave one out, such as a base struct you only
embed:

```go
// illustrative
// Base is embedded by the models of this package.
//
//anetos:skip
type Base struct {
	db.Model
	TenantID int64
}
```

To regenerate with `go generate ./...`, add this line to one file of the
module, as [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go) does:

```go
// illustrative
//go:generate go tool anetos generate
```

Regenerate after changing a model. `go tool anetos dev` does it for you
on every rebuild, and `make:model` right away.

### 3. Query with the columns

```go
func (Blog) ListPosts(c *web.Ctx, in ListPosts) (db.Page[Post], error) {
	q := db.Query[Post](c).Where(PostCols.PublishedAt.NotNull())
	if in.Search != "" {
		q = q.Where(PostCols.Title.Contains(in.Search)) // % and _ match themselves
	}
	if in.Author != nil {
		q = q.Where(PostCols.AuthorID.Eq(*in.Author))
	}
	return q.With(PostRels.Author).Latest().Paginate(in.Page, in.PerPage) // one query for all the authors
}
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `list-posts`.)

A column's type is its field's type, so:

- **Nullable columns** are pointers: compare with `new(t)`, and set
  `NULL` with `nil`:

  ```go
  // illustrative
  recent := db.Query[Post](ctx).Where(PostCols.PublishedAt.Gt(new(since)))
  _, err := recent.Update(PostCols.PublishedAt.Set(nil)) // unpublish
  ```

- **JSON columns** (`db:"tags,json"`) encode the values you pass as JSON,
  and `db.Pluck` decodes them. Equality on JSON follows the database
  (PostgreSQL's `jsonb` compares documents, its `json` type has no `=`,
  and MySQL and SQLite compare text), so prefer `db.SQL` with the
  database's JSON functions for conditions inside documents.
- **Joins** need qualified names: `PostCols.ID.Of("posts")` is
  `posts.id`.

### 4. Check it in CI (optional)

```sh
go tool anetos generate --check
```

exits with status 1 and names the files that are out of date, without
writing anything.

## How it works

`anetos generate` loads your packages with the Go type checker (no code runs),
finds the models, and applies the same column rules as the `db` package
at runtime: `db` tags, snake_case names for untagged fields, embedded
structs flattened, `rel` fields as relations, other struct fields skipped. A test in the framework
compares the two on a fixture of every kind of field. Mistakes the runtime
would report on first use, such as two fields mapping to one column or an
unknown `db` or `rel` tag option, are reported by `anetos generate` instead.
Key columns of relations are checked when a relation is first used
(`PostRels.Author.Err()` in a test checks them early).

It only replaces files that start with its `// Code generated by anetos
gen. DO NOT EDIT.` header, and removes `models_gen.go` from a package that
no longer has models. A stale `models_gen.go`, or code that uses a column
you haven't generated yet, doesn't stop it.

> **Coming from another framework?** Django's ORM, Eloquent and Active
> Record resolve column names given as strings or keywords when the
> query runs. Here the names are generated Go values, so a typo or a
> renamed column breaks the build, not a request. Strings still work
> where you want them: `db.C("title")`.

## Testing it

Nothing to test in your app: the generated code is declarations only. Run
`go tool anetos generate --check` in CI so a model change without regeneration
fails the build.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `undefined: PostCols` | Not generated yet, or `Post` isn't detected as a model | Run `go tool anetos generate`; mark a plain struct `//anetos:model` |
| `PostCols is already declared` | Your code declares that name | Rename it, or mark `Post` `//anetos:skip` |
| `columns "name" and "inner_name" both come from fields named Name` | An embedded struct and the model have fields with the same name | Rename one field |
| `models_gen.go was not written by anetos generate` | A file of yours has that name | Rename your file |
| `field types must compile` | A model field's type has an error | Fix the compile error first |
| `go: no such tool "anetos"` | The tool isn't in `go.mod` | Run step 1 |

## Next steps

- [Query data](https://docs.anetos.dev/guides/queries/index.md)
- [`anetos generate` reference](https://docs.anetos.dev/reference/anetos-generate/index.md)


# Accounts and security

Source: https://docs.anetos.dev/guides/accounts-and-security/

- [Add accounts with make:auth](https://docs.anetos.dev/guides/accounts/index.md): Give your app user accounts in one command: registration, login with "remember me" and throttling, login with Google and GitHub, two-factor authentication, account settings, logout, email verification, password reset and API tokens, with their pages, emails, routes, migration and tests. The code is written into your app, where you change it as you like; the parts that must be right (password hashing, tokens, sessions, throttling, the OAuth flow) stay in the [`auth`](https://docs.anetos.dev/guides/authentication/index.md) and [`social`](https://docs.anetos.dev/guides/social-login/index.md) packages, so fixes reach you with `go get -u`.
- [Add accounts to an API](https://docs.anetos.dev/guides/api-accounts/index.md): In a project made with `anetos new --stack=api`, `make:auth` writes accounts that log in with API tokens: registration, login (with two-factor codes for users who turn them on), logout, email verification, password reset and change, and token management, as JSON endpoints under `/api/v1`. There are no sessions or cookies: a client keeps its token and sends it in every request.
- [Authentication](https://docs.anetos.dev/guides/authentication/index.md): Let people register, log in (with "remember me"), log out, verify their email address and reset a forgotten password, and give API clients tokens. The complete app is [`examples/auth`](https://github.com/anetos-dev/anetos/tree/main/examples/auth). In an `anetos new` project, `go tool anetos make:auth` writes all of this into your app: see [Add accounts with make:auth](https://docs.anetos.dev/guides/accounts/index.md). This guide is the `auth` package underneath, step by step.
- [Social login](https://docs.anetos.dev/guides/social-login/index.md): Let users log in with Google, GitHub, or any OpenID Connect provider (Okta, Auth0, Microsoft Entra ID, Keycloak, GitLab…). The complete app is [`examples/auth`](https://github.com/anetos-dev/anetos/tree/main/examples/auth).
- [Two-factor authentication and password confirmation](https://docs.anetos.dev/guides/two-factor/index.md): Ask for more than a password: a code from an authenticator app (Google Authenticator, 1Password, Authy… : TOTP, RFC 6238) after it, with recovery codes for a lost phone; and the password again before sensitive pages. Package `auth` does the parts that must be right (secrets encrypted, codes used once, throttling); your handlers and pages call it. The complete app is [`examples/auth`](https://github.com/anetos-dev/anetos/tree/main/examples/auth).
- [Authorization](https://docs.anetos.dev/guides/authorization/index.md): Decide what a logged-in user may do, with policies the compiler checks.
- [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md): Give users roles, globally or in a team, and check what they may do, with package `auth/rbac`.
- [Rate limiting](https://docs.anetos.dev/guides/rate-limiting/index.md): Limit how often clients can call your routes, and how often they can attempt actions such as logging in.
- [Keep an audit log](https://docs.anetos.dev/guides/audit-log/index.md): Record who created, changed, deleted and restored the rows of your models, field by field, with package `audit`: for data governance, for support, and for "who changed this?".
- [Add an admin panel](https://docs.anetos.dev/guides/admin/index.md): Give your staff pages to list, search, filter, create, edit and delete the app's records, and to manage users and roles, with the admin interface of module `anetos.dev/anetos/admin`: no front-end build, permissions from [roles](https://docs.anetos.dev/guides/roles-and-permissions/index.md), and every change in the [audit log](https://docs.anetos.dev/guides/audit-log/index.md) for the models it tracks.


# Add accounts with make:auth

Source: https://docs.anetos.dev/guides/accounts/

Give your app user accounts in one command: registration, login with
"remember me" and throttling, login with Google and GitHub,
two-factor authentication, account settings, logout, email verification,
password reset and API tokens, with their pages,
emails, routes, migration and tests. The code is written into your app, where you change it as you
like; the parts that must be right (password hashing, tokens, sessions,
throttling, the OAuth flow) stay in the [`auth`](https://docs.anetos.dev/guides/authentication/index.md) and
[`social`](https://docs.anetos.dev/guides/social-login/index.md) packages, so fixes reach you with `go get -u`.

## Before you start

You have a project made with `anetos new` (it has sessions, the cache,
the queue and the mailer that accounts use), and no `User` model yet.

## Steps

### 1. Generate the accounts

From the project's directory:

```bash
go tool anetos make:auth
```

```text
created app/models/user.go
created app/handlers/auth.go
created app/handlers/settings.go
created app/mailers/auth.go
created views/auth.templ
created views/settings.templ
created views/auth_mail.templ
created routes/auth.go
created auth.go
created auth_test.go
created locales/en/auth.yaml
created database/factories/users.go
created database/migrations/2026_10_02_090000_create_users_table.go
updated .env: SOCIAL_* settings
updated .env.example: SOCIAL_* settings
updated deploy/production.env.example: SOCIAL_* settings
updated main.go: setup calls setupAuth
updated views/layout.templ: the header shows AccountMenu
wrote app/models/models_gen.go
```

`make:auth` writes nothing if one of these files exists, or if a name
they declare (`User`, `Accounts`, `Login`, …) is taken in its package;
if writing fails midway, it removes what it wrote. It runs `go mod
tidy`, `anetos generate` (the `User` model's typed columns) and `templ
generate` (the pages), checks that the project builds, and adds a call
to `setupAuth` to `setup` in `main.go`, after `routes.Register`:

```go
// illustrative: main.go after make:auth
routes.Register(srv.Router(), sessions)
// Accounts (anetos make:auth): registration, login with a password,
// Google or GitHub, two-factor authentication, account settings, email
// verification, password reset and API tokens.
if _, err := setupAuth(app, srv.Router(), sessions); err != nil {
	return nil, err
}
```

If your `setup` no longer has that statement, `make:auth` says so and
you add the call yourself.

It also adds `@AccountMenu()` to the layout's header, after its nav
(the `@ui.Nav` block, or the `</nav>` line in a layout made before
v0.5): links to log in and register for guests; the user's name
(to the dashboard), the settings and a logout button for logged-in
users. `setupAuth` calls `sessions.Use(a.Middleware)`, so every page
with a session knows who is logged in, the home page of `routes/web.go`
included. A layout without that nav gets nothing, and `make:auth` prints
the line to add where you like.

The pages are made of the components of `views/ui` ([Style your
app](https://docs.anetos.dev/guides/styling/index.md)): `ui.AuthCard`, a small centered card, for the forms,
and `ui.Card`s on the dashboard and the settings page. `AccountMenu`
is a `ui.NavEnd` with `ui.NavLink`s, and its buttons in `ui.NavItem`s.
In a project made before v0.5, which has no `views/ui`, `make:auth`
writes it first and says so ([Projects made before v0.5](https://docs.anetos.dev/guides/styling/index.md#projects-made-before-v05)).

### 2. Migrate and try it

```bash
go run . migrate     # the users, api_tokens and social_accounts tables
go tool anetos dev
```

Open `/register`. In development, emails go to the log
(`MAIL_DRIVER=log`), with their links; with `QUEUE_DRIVER=database`, the
app's workers send them, so they appear a moment later.

### 3. Turn on login with Google or GitHub

Each provider is on once its client ID and secret are set; until then
its button doesn't show and its routes answer 404. Create an OAuth app
at the provider (the [Google Cloud console](https://console.cloud.google.com/apis/credentials):
"OAuth client ID", type "Web application"; [GitHub](https://github.com/settings/developers):
"New OAuth App"), register `APP_URL/auth/google/callback` (or
`/auth/github/callback`) as its callback URL, and fill in the settings
`make:auth` added to `.env`:

```env
APP_URL=http://localhost:8080
SOCIAL_GOOGLE_CLIENT_ID=1234-abc.apps.googleusercontent.com
SOCIAL_GOOGLE_CLIENT_SECRET=…
```

The login and registration pages then show "Log in with Google". A
first login creates a user, with the address verified and no password
(they can set one with "Forgot your password?"); an account whose
address both the provider and your app have verified is linked to the
existing user. [Social login](https://docs.anetos.dev/guides/social-login/index.md) explains the rules and
how to add another provider (Okta, Auth0, any OpenID Connect provider).

### 4. Run the tests

`auth_test.go` registers, verifies the address by following the
emailed link, logs in and out, turns on two-factor authentication and logs in
with a recovery code, changes the name, password, language, time zone
and email address in the settings, resets the password, uses an API token,
and logs in with Google and GitHub through a stand-in provider
(`anetostest.FakeSocial`):

```bash
go test ./...
```

Keep these tests as you change the code: they cover the flows that
matter.

### 5. Make it yours

| File | Holds |
|---|---|
| `app/models/user.go` | `User`, and `models.Users`: how `auth` finds users, which are disabled (`disabled_at`), and stores their tokens, session keys (`session_key`, replaced to log them out everywhere) and two-factor state (`two_factor`, encrypted); the language and time zone they chose (`locale`, `time_zone`: `PreferredLocale`, `PreferredTimeZone`) and a new address waiting for its link (`pending_email`). Add columns here and in a migration |
| `app/handlers/auth.go` | `handlers.Accounts`: each page and form. Validation messages, redirects and what happens after registration are here; `SocialUser` finds or creates the user of a Google or GitHub account; `SendVerification` and `SendPasswordReset` email the links (the admin's buttons use them too) |
| `app/handlers/settings.go`, `views/settings.templ` | The settings page and its forms: add your own fields here |
| `views/auth.templ` | The pages, inside your `Layout` |
| `app/mailers/auth.go`, `views/auth_mail.templ` | The verification, reset and change-of-address emails |
| `routes/auth.go` | The routes and their names (`login`, `register`, `dashboard`, `settings`, …), the rate limits of the forgotten-password and verification forms, and what the settings allow (`AllowEmailChange`, `AllowAccountDeletion`) |
| `auth.go` | `setupAuth`: the `api_tokens` and `social_accounts` migrations, `auth.New`, `social.New` with the providers, and the routes |
| `database/migrations/…_create_users_table.go` | The users table |

The routes:

| Route | For |
|---|---|
| `GET`, `POST /register` | Guests: create an account, email the verification link, log in (10 posts a minute per client IP address) |
| `GET`, `POST /login` | Guests: log in (`AUTH_THROTTLE` limits failures) |
| `GET`, `POST /two-factor-challenge` | Guests whose login waits for a two-factor code: the authenticator app's, or a recovery code |
| `GET`, `POST /forgot-password` | Guests: email a reset link (5 posts a minute per client IP address; 3 links an hour per address, the same answer after) |
| `GET`, `POST /reset-password` | Guests: choose a new password with the link. A reset logs the user out everywhere and revokes their API tokens; for an address never verified, the link verifies it and turns off the two-factor authentication and Google and GitHub links that whoever registered it first may have set up. Two uses of the link at once change the password once |
| `GET /auth/{provider}/redirect`, `GET /auth/{provider}/callback` | Guests: log in with Google or GitHub (404 for a provider whose settings aren't set) |
| `GET /verify-email` | Anyone with the link: verify the address (400 if the link is bad, expired, or for an address the user has since changed) |
| `GET /dashboard` | Logged-in users: the account and its API tokens |
| `POST /logout` | Logged-in users |
| `POST /email/verification-notification` | Logged-in users: email the link again (3 a minute per client IP address, 6 an hour per account) |
| `POST /tokens` | Logged-in users who confirmed their password lately: create an API token (shown once); refused while an admin impersonates the user |
| `POST /tokens/{id}/delete` | Logged-in users: revoke an API token |
| `GET /settings`; `POST /settings/profile`, `/settings/password`, `/settings/preferences` | Logged-in users: their settings (below) |
| `POST /settings/email` | Logged-in users who confirmed their password lately: a new email address (with `AllowEmailChange`; 5 tries an hour per account) |
| `POST /settings/email/cancel` | Logged-in users: drop the change |
| `GET /settings/email/verify` | Anyone with the link emailed to the new address: make it the account's |
| `GET`, `POST /settings/email/revert` | Anyone with the link emailed to the old address: undo the change and secure the account (10 posts a minute per client IP address) |
| `POST /settings/delete` | Logged-in users who confirmed their password lately: delete the account (with `AllowAccountDeletion`) |
| `GET`, `POST /confirm-password` | Logged-in users: type the password again before a sensitive page (`a.RequireConfirmed`), then go back |
| `GET`, `POST /two-factor`, `POST /two-factor/confirm`, `/recovery-codes`, `/disable` | Logged-in users who confirmed their password lately: turn two-factor authentication on (a QR code, then a code), get new recovery codes, turn it off. See [Two-factor authentication](https://docs.anetos.dev/guides/two-factor/index.md) |
| `GET /api/me` | API clients, with `Authorization: Bearer <token>` |

Logging in, registering and logging in with a provider lead to the page
the user asked for before logging in, or else to `AUTH_HOME_URL`:
`/dashboard`, the default `setupAuth` gives in `auth.go`
(`auth.WithDefaultHomeURL("/dashboard")`). To send users elsewhere, set
`AUTH_HOME_URL=/projects` in the environment, or change the default in
`auth.go`; the setting wins, so each deployment can choose. Logged-in
users who open a guest page go there too; guests who open a member page
go to `AUTH_LOGIN_URL` and come back after logging in. To protect your own pages, put them in a group with
`a.Middleware` and `a.Require`, as `routes/auth.go` does: `setupAuth`
returns the `*auth.Auth`.

Disabled users (`disabled_at` set, as the [admin](https://docs.anetos.dev/guides/admin/index.md) does) are
logged out at their next request and see "This account is disabled."
when they log in with the right password; their API tokens stop
working.

#### The settings page

`/settings` (`AUTH_SETTINGS_URL`; the dashboard and the
[admin](https://docs.anetos.dev/guides/admin/index.md) link to it) lets a logged-in user change:

- **Their name.**
- **Their password**, with the current one; their other browsers and
  devices are logged out, and this one stays logged in (and remembered,
  if it was) (`auth.ChangePassword`). A user who logs in with Google or
  GitHub has no password: they set one within a few minutes of logging
  in.
- **Their language and time zone**, from the app's languages and
  `i18n.TimeZones()`; pages and emails use them
  ([translations](https://docs.anetos.dev/guides/translations/index.md)). "Your browser's" language forgets
  the one chosen on this browser (`c.ForgetLocale`).
- **Their email address**, after typing their password again: that is
  what keeps someone with a stolen session from taking the account's
  login and reset channel. The new address gets a link, and becomes
  theirs (verified) once it is followed, so a typo can't lock them out;
  until then they log in with the old one. Once it is made, their other
  sessions and the reset links sent to the old address stop working
  (`auth.LogoutOthers`). The old address, if it was verified, is told
  of the change, with a link that undoes it, for `AUTH_REVERT_TTL` (7
  days), even once it is made: if the change wasn't theirs, someone has
  their password, so undoing it also secures the account. The address
  goes back (verified), the password is cleared, two-factor authentication
  turned off, API tokens and links to Google and GitHub removed,
  everyone logged out, and the old address gets a link to choose a new
  password. The link opens a page with a button, as mail scanners
  follow links. Turn it off with
  `AllowEmailChange: false` in `routes/auth.go`, for apps whose
  addresses come from an organisation.
- **Delete their account**, after typing their password again: the user,
  their API tokens and Google or GitHub links go, and they're logged
  out. Off by default: `AllowAccountDeletion: true` turns it on. If the
  app gives users roles, remove them in `DeleteAccount` too
  (`rbac.RemoveUser`); other data of theirs is the app's to delete or
  keep.

It links to two-factor authentication. To add a field (a phone number, a
newsletter choice), add a column and a migration, the field to
`User`, a form to `views/settings.templ` and a handler to
`app/handlers/settings.go`, as `UpdateProfile` does.

Apps that ran `make:auth` before have no settings page. To add it, take
from a new project's `make:auth`: the `pending_email`, `locale` and
`time_zone` columns (a migration) and `User` fields, with
`PreferredLocale` and `PreferredTimeZone`; `app/handlers/settings.go`,
`views/settings.templ`, the `ChangeEmail` and `EmailChanging` mailables
and their views; the `AllowEmailChange` and `AllowAccountDeletion` fields
of `Accounts` and the settings routes; the `auth.settings`, `auth.mail`
and other new keys of `locales/en/auth.yaml`. Then run `go tool anetos
gen` and `go tool templ generate`.

To do more when someone signs up (a welcome email, a trial), change
`Register` and `SocialUser` in `app/handlers/auth.go`, which create
users. [`examples/saas`](https://github.com/anetos-dev/anetos/tree/main/examples/saas), a `make:auth` app,
queues a welcome job in the transaction that creates the user, so the
job runs only if the user is committed:

```go
// welcome queues the welcome email of a new user, once the transaction
// that creates them commits: a worker sends it (jobs.SendWelcome).
func welcome(ctx context.Context, u *models.User) error {
	return queue.Dispatch(ctx, jobs.SendWelcome{UserID: u.ID}, queue.AfterCommit())
}
```

(Copied from [`examples/saas/app/handlers/auth.go`](https://github.com/anetos-dev/anetos/blob/main/examples/saas/app/handlers/auth.go), region `dispatch`.)

```go
// SendWelcome emails a new user the welcome email. Registration and the
// first login with Google or GitHub dispatch it once the user is
// committed; a worker runs it, with the queue's retries.
type SendWelcome struct {
	UserID int64 `json:"user_id"`
}

// Handle sends the email.
func (j SendWelcome) Handle(ctx context.Context) error {
	u, err := db.Find[models.User](ctx, j.UserID)
	if errors.Is(err, db.ErrNotFound) {
		return queue.Permanent(err) // deleted since: retrying won't help
	}
	if err != nil {
		return err
	}
	url, err := mailer.URL(ctx, "/dashboard")
	if err != nil {
		return err
	}
	m := mailers.Welcome{Name: u.Name, Email: u.Email, URL: url}
	if u.TrialEndsAt != nil {
		m.TrialEnds = *u.TrialEndsAt
	}
	return mailer.Send(ctx, m)
}
```

(Copied from [`examples/saas/app/jobs/welcome.go`](https://github.com/anetos-dev/anetos/blob/main/examples/saas/app/jobs/welcome.go), region `job`.)

`setup` registers the job type, `queue.Register[jobs.SendWelcome](q,
queue.Tries(5))`, where `anetos new` left a comment for it; see
[Queues](https://docs.anetos.dev/guides/queues/index.md).

## How it works

The generated code is the same kind of code as
[`examples/auth`](https://github.com/anetos-dev/anetos/tree/main/examples/auth), which the
[Authentication](https://docs.anetos.dev/guides/authentication/index.md) guide walks through, adapted to a
`anetos new` project: templ pages in `views`, typed columns, the mailer
for the links (`mailer.Queue`, so a slow mail server doesn't slow the
request), and route names. Links in emails are absolute, on `APP_URL`.
Reset and verification tokens are signed, not stored: a reset link
works for `AUTH_RESET_TTL` and once, a verification link for
`AUTH_VERIFY_TTL`. Registration creates the user and renders the email
in one transaction, so an email that can't be rendered leaves no
account behind; the queue sends it after the commit. Names are kept on
one line (control characters dropped), and emails go to the address
alone, the name only in their body.

The forgotten-password form answers the same whether or not the address
has an account, but takes a little longer when it does (it renders and
queues the email): someone measuring response times could tell. The
registration form says when an address is taken, as most sites do.

Logging in with a provider follows the rules of
[Social login](https://docs.anetos.dev/guides/social-login/index.md): accounts are linked to users by the
provider's account ID, not by email, and an address finds an existing
user only when both the provider and your app have verified it, and the
user has no other account of that provider linked.

`make:auth` doesn't add authorization policies: see
[Authorization](https://docs.anetos.dev/guides/authorization/index.md).

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| `…_create_users_table.go exists` or `app/models/user.go exists` | The app has users already, or `make:auth` ran before | Rename yours, or add accounts by hand from [Authentication](https://docs.anetos.dev/guides/authentication/index.md) |
| `app/models already declares User` (or another name) | A name the generated files declare is taken in that package | Rename yours |
| `the project doesn't build` after the files are written | Your code and the generated code clash, or a tool failed | Fix it, then run the commands it prints |
| `no app/models directory` | Not an `anetos new` project | Start from [`examples/auth`](https://github.com/anetos-dev/anetos/tree/main/examples/auth) |
| `main.go doesn't have the routes.Register call` | `setup` was changed | Add the `setupAuth` call it prints |
| `no such table: users` | The migrations haven't run | `go run . migrate` |
| `URL needs the app's public URL` when registering | `APP_URL` isn't set | Set it in `.env` |
| No email in the log | `QUEUE_DRIVER=database` and the workers aren't running | Run the app with `go tool anetos dev` or `go run .`, or use `QUEUE_DRIVER=sync` |
| No "Log in with Google" button | Its `SOCIAL_GOOGLE_*` settings are empty | Set both in `.env` |
| `redirect_uri_mismatch` at Google | The callback URL registered there isn't `APP_URL/auth/google/callback` | Fix `APP_URL` or the URL at Google |

## Next steps

- [Authentication](https://docs.anetos.dev/guides/authentication/index.md): the `auth` package.
- [Social login](https://docs.anetos.dev/guides/social-login/index.md): providers, linking and testing.
- [Two-factor authentication and password confirmation](https://docs.anetos.dev/guides/two-factor/index.md).
- [Send email](https://docs.anetos.dev/guides/mail/index.md): send the emails with SMTP or Postmark.
- [Authorization](https://docs.anetos.dev/guides/authorization/index.md): policies.

> **Coming from another framework?** `anetos make:auth` writes the
> handlers, views and routes into your app, as Laravel's starter kits
> and Rails' authentication generator do, where Django's
> `django.contrib.auth` keeps its views in the library. Hashing,
> remember-me, throttling and tokens stay in the library here, and so
> does the OAuth flow.


# Add accounts to an API

Source: https://docs.anetos.dev/guides/api-accounts/

In a project made with `anetos new --stack=api`, `make:auth` writes
accounts that log in with API tokens: registration, login (with
two-factor codes for users who turn them on), logout, email
verification, password reset and change, and token management, as JSON
endpoints under `/api/v1`. There are no sessions or cookies: a client
keeps its token and sends it in every request.

## Before you start

- An API project: [Create a project](https://docs.anetos.dev/getting-started/create-a-project/index.md#an-api-instead).
  In a project with pages, `make:auth` writes the pages instead
  ([Add accounts with make:auth](https://docs.anetos.dev/guides/accounts/index.md)).
- A client app with pages for two emailed links: `/verify-email` and
  `/reset-password`, at the address in `AUTH_CLIENT_URL`.

## Steps

### 1. Generate the accounts

```sh
go tool anetos make:auth
go run . migrate
```

`make:auth` writes the `User` model and its migration,
`app/handlers/auth.go` (the handlers), `routes/auth.go` (the routes),
`app/mailers/` (the emails), `auth.go` (`setupAuth`, which `main.go`
now calls), `locales/en/auth.yaml` (the messages) and `auth_test.go`.
It adds `AUTH_CLIENT_URL` to `.env`, `.env.example` and
`deploy/production.env.example`. The code is yours: change the
handlers, the responses and the emails as your app needs.

### 2. Set the client app's address

The verification and password reset emails link to the client app,
not to the API:

```sh
AUTH_CLIENT_URL=http://localhost:5173
```

A link reads `http://localhost:5173/reset-password?token=…`. The
client app's page shows a form, and posts the token to the API. In
production and staging, the app refuses to start without
`AUTH_CLIENT_URL`, since no one could register.

### 3. Register and log in

```sh
curl -X POST http://localhost:8080/api/v1/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","email":"ada@example.com","password":"correct horse","password_confirmation":"correct horse","device_name":"Ada'"'"'s phone"}'
```

The answer, `201 Created`, has a token and the user:

```json
{"token":"1|q7Xw…","user":{"id":1,"name":"Ada","email":"ada@example.com","email_verified_at":null,"created_at":"2026-10-08T09:00:00Z"}}
```

`POST /api/v1/login` with `email`, `password` and an optional
`device_name` answers the same way, with `200 OK`. Send the token in
every request:

```sh
curl http://localhost:8080/api/v1/me -H 'Authorization: Bearer 1|q7Xw…'
```

A login's token has every ability (`*`) and lasts 30 days; it's named
after `device_name` (`API` without one). `POST /api/v1/logout` revokes
it.

### 4. Two-factor authentication

A user turns it on in three requests, with their token:

1. `POST /api/v1/two-factor` with their `password`: the key for the
   authenticator app, as `secret`, `uri` (`otpauth://`) and `qr_code`
   (an SVG image to show).
2. `POST /api/v1/two-factor/confirm` with a `code` of the app: it's on,
   and the answer has eight `recovery_codes` to show once. The user's
   other tokens are revoked: they were made with the password alone.
3. `GET /api/v1/two-factor` reports it: `enabled`, `started`,
   `recovery_codes` left.

From then on, the login answers a challenge instead of a token:

```json
{"two_factor":true,"challenge":"AQx…"}
```

The client asks for a code, and sends both to
`POST /api/v1/login/two-factor` (`challenge`, `code`, optional
`device_name`), which answers with the token. A recovery code works in
place of the app's code, once. The challenge works for 10 minutes; a
422 on the `challenge` field means it expired, and the user logs in
again.

`POST /api/v1/two-factor/recovery-codes` makes new recovery codes, and
`POST /api/v1/two-factor/disable` turns it off. Both take the
`password`.

### 5. Tokens for programs

`POST /api/v1/tokens` makes a token for a script or another service:
a `name`, the `abilities` it may use (every one, `*`, if none; up to
20 names of 1 to 100 characters, without spaces) and the user's
`password`. The answer, `201`, shows the token once; it lasts 90 days.
A token with narrower abilities than `*` uses your API but not the
account: `/password`, `/tokens` and `/two-factor` answer it 403, so a
leaked integration token can't make more tokens or revoke the user's
others. `GET /api/v1/tokens` lists the user's tokens (`current` marks
the request's), and `DELETE /api/v1/tokens/{id}` revokes one. Require
abilities on routes with `auth.RequireAbilities` (a token without them
gets 403, and `openapi.json` lists them), or check one in a handler with
`auth.TokenCan`:

```go
// illustrative
loggedIn.With(auth.RequireAbilities("orders:write")).Post("/orders", web.H(h.Create))

if !auth.TokenCan(c, "orders:write") {
	return nil, web.Error(http.StatusForbidden, "")
}
```

## The endpoints

| Method and path | With a token | Body | Answer |
|---|---|---|---|
| `POST /register` | no | `name`, `email`, `password`, `password_confirmation`, `device_name` | 201: `token`, `user` |
| `POST /login` | no | `email`, `password`, `device_name` | `token`, `user`; or `two_factor`, `challenge` |
| `POST /login/two-factor` | no | `challenge`, `code`, `device_name` | `token`, `user` |
| `POST /forgot-password` | no | `email` | 204, whether or not the address has an account |
| `POST /reset-password` | no | `token` (from the link), `password`, `password_confirmation` | 204; every token of the user is revoked |
| `POST /verify-email` | no | `token` (from the link) | 204 |
| `GET /me` | yes | | the user |
| `POST /logout` | yes | | 204; the token is revoked |
| `POST /email/verification-notification` | yes | | 204; the link again, unless verified |
| `PUT /password` | yes | `current_password`, `password`, `password_confirmation` | 204; the user's other tokens are revoked |
| `GET /tokens` | yes | | the tokens, newest first |
| `POST /tokens` | yes | `name`, `abilities`, `password` | 201: `token` and the token's fields |
| `DELETE /tokens/{id}` | yes | | 204 |
| `GET /two-factor` | yes | | `enabled`, `started`, `recovery_codes` |
| `POST /two-factor` | yes | `password` | `secret`, `uri`, `qr_code` |
| `POST /two-factor/confirm` | yes | `code` | `recovery_codes` |
| `POST /two-factor/recovery-codes` | yes | `password` | `recovery_codes` |
| `POST /two-factor/disable` | yes | `password` | 204 |

All paths are under `/api/v1`. The routes from `PUT /password` on need
a token with every ability (`*`). Errors are [problem details](https://docs.anetos.dev/guides/handlers/index.md#errors):

- 422 with `errors` for the fields: a wrong password or a disabled
  account is an error of the `email` field at login (of `challenge` at
  `/login/two-factor`), of `password` or `current_password` elsewhere;
  a used or expired reset link, of `token`.
- 400 for a verification link that is malformed, expired, or for an
  address the user no longer has: the client app says so and offers a
  new one.
- 401 without a valid token, with `WWW-Authenticate: Bearer`; 403 for a
  token without the `*` ability on the account's routes.
- 409 when two-factor authentication is on already (`POST /two-factor`) or off
  (`/two-factor/confirm` without a started setup,
  `/two-factor/recovery-codes`).
- 429 with `Retry-After` after too many tries.

## How it works

The handlers call package `auth` without a session:
`AttemptCredentials` checks the password with the same throttling as
the pages' login, and for a user with two-factor authentication on returns a
`*auth.TwoFactorChallenge`, an encrypted note of the user and a
fingerprint of their password; `AttemptTwoFactorChallenge` checks it
and the code, each code working once. `CheckPassword` asks for the
password again where the pages use `RequireConfirmed`: a stolen token
alone can't make more tokens or change two-factor authentication.
[Authentication](https://docs.anetos.dev/guides/authentication/index.md) explains tokens and the rest.

The responses are structs of `app/handlers/auth.go`
(`UserResponse`, `LoginResponse`, `TokenResponse`…), never the
`User` model, so a new column never shows by accident. The emails are
`app/mailers/auth.html`, an `html/template` file, with their text in
`locales/en/auth.yaml`: `anetos locale:add` brings the same keys'
translations as the pages' ([Translations](https://docs.anetos.dev/guides/translations/index.md)).

Throttling: registration 10 a minute per client address, reset
requests 5 a minute per client address and 3 links an hour per email
address, verification links 3 a minute per client address and 6 an
hour per user, logins and codes as `AUTH_THROTTLE` and
`AUTH_THROTTLE_IP` say.

> **Note:** Logging in with Google or GitHub, changing the email
> address and deleting the account are the pages' features: an API
> project's `make:auth` leaves them out. Add the endpoints you need to
> the generated handlers.

`make:auth` updates `openapi.json`, the API's description
([Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md)): the account's operations,
their inputs and responses, and the bearer token the `loggedIn` routes need
(`auth.Require` says so, and `auth.RequireAbilities("*")` on the
account's routes adds the `*` ability).

## Testing it

`auth_test.go` tests every endpoint through HTTP: registering,
verifying, logging in and out, two-factor authentication, resets, password
changes and tokens. It sets `AUTH_CLIENT_URL` with `anetostest.Env`,
reads the emails' links with `anetostest.Mailables`, and signs requests
with `app.WithHeader("Authorization", "Bearer "+token)`. Run it with
`go test ./...`.

## Common problems

- **Registration answers 500 "AUTH_CLIENT_URL isn't set".** The emails
  need the client app's address: set `AUTH_CLIENT_URL` (in tests, with
  `anetostest.Env`).
- **Every request answers 401 after a password reset.** A reset
  revokes every token of the user, and a new password every other
  token: log in again.
- **A browser app can't call the API.** List its address in
  `HTTP_CORS_ORIGINS` ([Configuration](https://docs.anetos.dev/reference/configuration/index.md)).

## Next steps

- [Authentication](https://docs.anetos.dev/guides/authentication/index.md): package `auth`, tokens and
  abilities.
- [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md): what users may do,
  with tokens' abilities as a ceiling.
- [Rate limiting](https://docs.anetos.dev/guides/rate-limiting/index.md).


# Authentication

Source: https://docs.anetos.dev/guides/authentication/

Let people register, log in (with "remember me"), log out, verify their
email address and reset a forgotten password, and give API clients
tokens. The complete app is [`examples/auth`](https://github.com/anetos-dev/anetos/tree/main/examples/auth).
In an `anetos new` project, `go tool anetos make:auth` writes all of this
into your app: see [Add accounts with make:auth](https://docs.anetos.dev/guides/accounts/index.md). This
guide is the `auth` package underneath, step by step.

## Before you start

You need sessions ([Sessions and flash messages](https://docs.anetos.dev/guides/sessions/index.md)), the
cache (login throttling counts failures in it, see
[Cache](https://docs.anetos.dev/guides/cache/index.md)) and a users table. Passwords are hashed with
`auth/password` (argon2id).

## Steps

### 1. Describe your users

Your user model implements two methods:

```go
// User is an account. The two Auth methods are what package auth needs.
type User struct {
	db.Model
	Name            string     `db:"name" json:"name"`
	Email           string     `db:"email" json:"email"` // stored in lower case
	Password        string     `db:"password" json:"-"`  // password.Hash
	RememberToken   string     `db:"remember_token" json:"-"`
	EmailVerifiedAt *time.Time `db:"email_verified_at" json:"email_verified_at"`
	Admin           bool       `db:"admin" json:"admin"`
	TwoFactor       string     `db:"two_factor" json:"-"` // two-factor authentication, encrypted by package auth
}

// AuthID implements auth.Authenticatable.
func (u *User) AuthID() string { return strconv.FormatInt(u.ID, 10) }

// AuthPassword implements auth.Authenticatable.
func (u *User) AuthPassword() string { return u.Password }
```

(Copied from [`examples/auth/users.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/users.go), region `user`.)

`auth.Users` tells the package how to find users, and, optionally, how
to store remember-me tokens and upgraded password hashes:

```go
// users tells package auth how to find and update users.
var users = auth.Users[*User]{
	ByID: func(ctx context.Context, id string) (*User, error) {
		n, err := strconv.ParseInt(id, 10, 64)
		if err != nil {
			return nil, auth.ErrUserNotFound
		}
		u, err := db.Find[User](ctx, n) // db.ErrNotFound: no such user
		return &u, err
	},
	ByLogin: func(ctx context.Context, email string) (*User, error) {
		u, err := db.Query[User](ctx).Where(colEmail.Eq(strings.ToLower(email))).First()
		return &u, err
	},
	RememberToken: func(u *User) string { return u.RememberToken },
	SetRememberToken: func(ctx context.Context, u *User, token string) error {
		_, err := db.Query[User](ctx).Where(colID.Eq(u.ID)).Update(colRemember.Set(token))
		return err
	},
	SetPassword: func(ctx context.Context, u *User, hash string) error {
		_, err := db.Query[User](ctx).Where(colID.Eq(u.ID)).Update(colPassword.Set(hash))
		return err
	},
	// Two-factor authentication: package auth stores its state (the secret
	// encrypted with APP_KEY, the recovery codes hashed) in a column.
	TwoFactor: func(u *User) string { return u.TwoFactor },
	SetTwoFactor: func(ctx context.Context, u *User, state string) error {
		u.TwoFactor = state
		_, err := db.Query[User](ctx).Where(colID.Eq(u.ID)).Update(colTwoF.Set(state))
		return err
	},
}
```

(Copied from [`examples/auth/users.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/users.go), region `users`.)

`ByID` and `ByLogin` return `db.ErrNotFound` (or `auth.ErrUserNotFound`) when
there is no such user. Store email addresses in lower case, and look them
up the same way.

### 2. Set up auth and protect routes

```go
// AUTH_* settings. Logging in leads to /dashboard, unless
// AUTH_HOME_URL names another page.
a, err := auth.New(app, users, auth.WithDefaultHomeURL("/dashboard"))
if err != nil {
	return nil, err
}
```

(Copied from [`examples/auth`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `setup`.)

Add `a.Middleware` after the session middleware, then `a.Require` on the
routes for logged-in users and `a.Guest` on the login and registration
pages:

```go
pages := r.Group("", sessions.Middleware, web.CSRF(), a.Middleware)
pages.Get("/", func(c *web.Ctx) error { return c.Redirect(http.StatusSeeOther, "/dashboard") })
pages.Get("/verify-email", web.H(h.VerifyEmail))

guests := pages.Group("", a.Guest) // logged-in users go to AUTH_HOME_URL
guests.Get("/register", h.page("register"))
guests.Post("/register", web.H(h.Register))
guests.Get("/login", h.page("login"))
guests.Post("/login", web.H(h.Login))
guests.Get("/forgot-password", h.page("forgot"))
guests.With(ratelimit.Middleware("forgot-password", ratelimit.PerMinute(5))).Post("/forgot-password", web.H(h.SendReset))
guests.Get("/reset-password", h.page("reset"))
guests.Post("/reset-password", web.H(h.Reset))
guests.Get("/auth/{provider}/redirect", s.Redirect) // "Log in with …" links here
guests.Get("/auth/{provider}/callback", s.Callback)
guests.Get("/two-factor-challenge", h.page("challenge")) // AUTH_CHALLENGE_URL
guests.Post("/two-factor-challenge", web.H(h.Challenge))

loggedIn := pages.Group("", a.Require) // guests go to AUTH_LOGIN_URL
loggedIn.Get("/dashboard", h.Dashboard)
loggedIn.Post("/logout", h.Logout)
loggedIn.Post("/tokens/{id}/delete", web.H(h.RevokeToken))
loggedIn.Get("/users/{id}", web.H(h.ShowUser))
loggedIn.Get("/admin", h.Admin)
loggedIn.Post("/password", web.H(h.ChangePassword))
loggedIn.Get("/confirm-password", h.page("confirm")) // AUTH_CONFIRM_URL
loggedIn.Post("/confirm-password", web.H(h.ConfirmPassword))

// Two-factor authentication (AUTH_TWO_FACTOR_URL) and API tokens (they work
// without the browser): the password again first.
secure := loggedIn.Group("", a.RequireConfirmed)
secure.Post("/tokens", web.H(h.CreateToken))
secure.Get("/two-factor", h.TwoFactor)
secure.Post("/two-factor", h.StartTwoFactor)
secure.Post("/two-factor/confirm", web.H(h.ConfirmTwoFactor))
secure.Post("/two-factor/disable", h.DisableTwoFactor)

api := r.Group("/api", a.TokenMiddleware, a.Require) // Authorization: Bearer <token>
api.Get("/me", h.Me)
```

(Copied from [`examples/auth`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `routes`.)

`Require` sends guests asking for a page to `AUTH_LOGIN_URL` (remembering
the page for `auth.Intended`), and answers other requests (JSON, htmx)
with 401. `Guest` sends logged-in users to `AUTH_HOME_URL`.

Read the current user in a handler with `auth.User` or `auth.Current`:

```go
// illustrative
u, ok := auth.User[*User](c)    // pages that show a guest something else
u, err := auth.Current[*User](c) // handlers that need the user: return err
```

`auth.User` answers whether there is a user: a guest and a user who
couldn't be loaded (the database is down; it's logged) are both "no".
Use it in views and pages that change for guests. `auth.Current` returns
`auth.ErrUnauthenticated` (401) for a guest, or the error that kept the
user from loading, which a handler returns as it is: use it behind
`Require`, and anywhere a failure must not pass for a guest.

The user is loaded from the database when first asked for, once per
request.

### 3. Register

Hash the password, create the user and log them in:

```go
func (h Accounts) Register(c *web.Ctx, in RegisterInput) (web.Responder, error) {
	email := strings.ToLower(in.Email) // stored and looked up in lower case
	taken, err := db.Query[User](c).Where(colEmail.Eq(email)).Exists()
	if err != nil {
		return nil, err
	}
	if taken {
		return nil, validate.Fail("email", "The email has already been taken.")
	}
	hash, err := password.Hash(in.Password)
	if err != nil {
		return nil, err
	}
	u := &User{Name: in.Name, Email: email, Password: hash}
	if err := db.Create(c, u); err != nil {
		return nil, err
	}
	// The account exists now: a mail server that fails doesn't undo it
	// (an app with a queue sends with mailer.Queue, which retries).
	if err := sendLink(c, u.Email, "Verify your email address", "/verify-email?token="+url.QueryEscape(h.auth.VerificationToken(u, u.Email))); err != nil {
		c.Logger().Error("send the verification link", "error", err)
	}
	if err := h.auth.Login(c, u, false); err != nil {
		return nil, err
	}
	return web.Redirect("/dashboard"), nil
}
```

(Copied from [`examples/auth`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `register`.)

### 4. Log in and out

`Attempt` checks the password and logs the user in; turn its errors
into a form error:

```go
func (h Accounts) Login(c *web.Ctx, in LoginInput) (web.Responder, error) {
	_, err := h.auth.Attempt(c, in.Email, in.Password, in.Remember)
	var throttled *auth.ThrottledError
	switch {
	case errors.Is(err, auth.ErrInvalidCredentials):
		return nil, validate.Fail("email", "These credentials don't match our records.")
	case errors.As(err, &throttled):
		return nil, validate.Fail("email", "Too many login attempts. Try again in a minute.")
	case errors.Is(err, auth.ErrTwoFactorRequired):
		return web.Redirect("/two-factor-challenge"), nil // the password was right: now the code
	case err != nil:
		return nil, err
	}
	return web.Redirect(auth.Intended(c, h.auth.Config().HomeURL)), nil // the page they wanted, or AUTH_HOME_URL
}

func (h Accounts) Logout(c *web.Ctx) error {
	if err := h.auth.Logout(c); err != nil {
		return err
	}
	return c.Redirect(http.StatusSeeOther, "/login")
}
```

(Copied from [`examples/auth`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `login`.)

A failed login gives the same error whether the address has no account
or the password is wrong, and takes about as long (users with an old
bcrypt hash, until they next log in, can take longer). After
`AUTH_THROTTLE` attempts (5 by default) in a minute for one login, or
one account, from one IP address, and after `AUTH_THROTTLE_IP` failures
(50) from one address whatever the login, `Attempt` returns a
`*auth.ThrottledError` without checking the password. Users whose hash is
stronger than the defaults (made with `password.HashWith`) also take
longer to check than unknown logins. `Login` (and so `Attempt`) gives the
session a new ID; `Logout` empties it and logs the user out of every
browser where they chose "remember me". With the default cookie
sessions, a copy of the session cookie taken before the logout keeps
working until it expires; use a server-side `SESSION_DRIVER` to revoke
sessions at logout.

### 5. Verify email addresses

Send a link with a verification token, and check it when it's followed:

```go
func (h Accounts) VerifyEmail(c *web.Ctx, in TokenQuery) (web.Responder, error) {
	u, email, err := h.auth.CheckVerificationToken(c, in.Token)
	if err != nil {
		return nil, err // 400 for a bad or expired link
	}
	if email == u.Email && u.EmailVerifiedAt == nil {
		now := anetos.Now(c).UTC()
		if _, err := db.Query[User](c).Where(colID.Eq(u.ID)).Update(colVerified.Set(&now)); err != nil {
			return nil, err
		}
	}
	c.Session().Flash("status", "Your email address is verified.")
	return web.Redirect("/dashboard"), nil
}
```

(Copied from [`examples/auth`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `verify`.)

`sendLink` emails the link with the [mailer](https://docs.anetos.dev/guides/mail/index.md), as an absolute URL
on `APP_URL` (`mailer.URL`); in tests, `anetostest` records the email,
and the test follows its link.

### 6. Reset forgotten passwords

```go
func (h Accounts) SendReset(c *web.Ctx, in ForgotInput) (web.Responder, error) {
	u, err := users.ByLogin(c, in.Email)
	switch {
	case err == nil:
		if err := sendLink(c, u.Email, "Reset your password", "/reset-password?token="+url.QueryEscape(h.auth.PasswordResetToken(u))); err != nil {
			return nil, err
		}
	case !errors.Is(err, db.ErrNotFound):
		return nil, err
	}
	// The same answer either way, so the form doesn't reveal who has an
	// account.
	c.Session().Flash("status", "If that address has an account, we've emailed it a link.")
	return web.Redirect("/login"), nil
}

func (h Accounts) Reset(c *web.Ctx, in ResetInput) (web.Responder, error) {
	u, err := h.auth.CheckPasswordResetToken(c, in.Token)
	if errors.Is(err, auth.ErrInvalidToken) {
		return nil, validate.Fail("password", "This reset link is invalid or has expired. Ask for a new one.")
	}
	if err != nil {
		return nil, err
	}
	hash, err := password.Hash(in.Password)
	if err != nil {
		return nil, err
	}
	// Only if the password is still the one the link was made for: two
	// uses of the link at once change it once.
	n, err := db.Query[User](c).Where(colID.Eq(u.ID), colPassword.Eq(u.Password)).Update(colPassword.Set(hash))
	if err != nil {
		return nil, err
	}
	if n == 0 {
		return nil, validate.Fail("password", "This reset link is invalid or has expired. Ask for a new one.")
	}
	// The new password logs out every session and remembered browser
	// (their password fingerprint no longer matches); API tokens are
	// revoked too.
	if err := h.auth.RevokeAllTokens(c, u); err != nil {
		return nil, err
	}
	c.Session().Flash("status", "Your password has been reset. You can log in now.")
	return web.Redirect("/login"), nil
}
```

(Copied from [`examples/auth`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `reset`.)

A reset token works for `AUTH_RESET_TTL` (an hour) and only until the
password changes, so it works once; the update is conditional on the old
hash, so two uses at the same moment change it once. Changing the
password logs the user out of every other session (cookie sessions:
when they're next used, as the password fingerprint no longer matches)
and remembered browser; `a.RevokeAllTokens` removes their API tokens.
Throttle the form that sends links, as the example does, so it can't be
used to flood someone's inbox.

### 7. Let users change their password

`a.ChangePassword(ctx, u, current, new)` checks the current password
(throttled, `AUTH_THROTTLE` tries a minute), stores the new one hashed,
and logs the user out of their other sessions and remembered browsers
(`a.LogoutOthers`), keeping the one they're using: it gets a new
session ID, and stays remembered if it was. A user without a password (who logs in
with Google, say) sets one without `current`, if they logged in within the
last `AUTH_CONFIRM_TTL`.

```go
// ChangePassword changes the logged-in user's password. Their other
// browsers and devices are logged out; this one stays logged in.
func (h Accounts) ChangePassword(c *web.Ctx, in NewPasswordInput) (web.Responder, error) {
	u, err := auth.Current[*User](c)
	if err != nil {
		return nil, err
	}
	switch err := h.auth.ChangePassword(c, u, in.CurrentPassword, in.Password); {
	case errors.Is(err, auth.ErrInvalidCredentials):
		return nil, validate.Fail("current_password", "That isn't your password.")
	case err != nil:
		return nil, err
	}
	c.Session().Flash("status", "Password changed.")
	return web.Redirect("/dashboard"), nil
}
```

(Copied from [`examples/auth`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `change-password`.)

[`make:auth`](https://docs.anetos.dev/guides/accounts/index.md)'s settings page has it, with the user's name,
email address, language and time zone.

### 8. Give API clients tokens

Add `auth.Migrations()` to your migrations for the `api_tokens` table.
Tokens are created for a user with abilities, and shown once:

```go
func (h Accounts) CreateToken(c *web.Ctx, in NewTokenInput) (web.Responder, error) {
	u, err := auth.Current[*User](c)
	if err != nil {
		return nil, err
	}
	plain, _, err := h.auth.CreateToken(c, u, in.Name, []string{"profile:read"}, 90*24*time.Hour)
	if err != nil {
		return nil, err
	}
	c.Session().Flash("token", plain) // shown once
	return web.Redirect("/dashboard"), nil
}

// Me is GET /api/me, for API clients with a token.
func (Accounts) Me(c *web.Ctx) error {
	if !auth.TokenCan(c, "profile:read") {
		return auth.ErrForbidden
	}
	u, err := auth.Current[*User](c)
	if err != nil {
		return err
	}
	return c.JSON(http.StatusOK, u)
}
```

(Copied from [`examples/auth`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `api-tokens`.)

Clients send `Authorization: Bearer <token>` to routes with
`a.TokenMiddleware` (see the routes above). Keep those routes in their
own group, without the session middleware and `web.CSRF`: a CSRF check
would refuse API clients' posts, and without sessions `a.Require`
answers 401 instead of redirecting. Other `Authorization` schemes are
ignored (the request is a guest). `auth.TokenCan` checks a
token's abilities, and `auth.RequireAbilities(…)` is middleware
answering 403 to a token without them; a user logged in with a session
(your own pages and front end) may do anything. `a.Tokens` lists a user's tokens and
`a.RevokeToken` deletes one.

Put the route that creates tokens behind `a.RequireConfirmed`, as the
example does: a token outlives the session, so someone holding a stolen
session shouldn't be able to make one without the password. `CreateToken`
refuses while an admin impersonates the user (403), for the same reason.

An API whose clients log in with tokens, without sessions,
uses `a.AttemptCredentials(ctx, login, password)`: `Attempt`'s
check and throttling, returning the user to give a token to. For a user
with two-factor authentication on, it fails with a `*auth.TwoFactorChallenge`
whose `Token` the client sends back with a code to
`a.AttemptTwoFactorChallenge`. Where pages use `RequireConfirmed`, an
API asks for the password in the request: `a.CheckPassword(ctx, u,
password)`. `make:auth` in an API project writes all of this:
[Add accounts to an API](https://docs.anetos.dev/guides/api-accounts/index.md).

### 9. Test

```go
func TestRegisterAndLogin(t *testing.T) {
	app := anetostest.New(t, setup)

	app.Get("/register").AssertOK()
	app.PostForm("/register", url.Values{"name": {"Ada"}, "email": {"Ada@Example.com"},
		"password": {"password1"}, "password_confirmation": {"password1"}}).
		AssertRedirect("/dashboard").
		Follow().
		AssertSee("Hello, Ada", "Please verify your email address")

	// The emailed link verifies the address.
	app.Get(emailedLink(t, app, "Verify your email address")).AssertRedirect("/dashboard").Follow().
		AssertSee("Your email address is verified.").
		AssertDontSee("Please verify")

	app.PostForm("/logout", nil).AssertRedirect("/login")
	app.Get("/dashboard").AssertRedirect("/login") // guests go to the login page

	app.PostForm("/login", url.Values{"email": {"ada@example.com"}, "password": {"wrong"}}).
		AssertValidationErrors("email")
	app.PostForm("/login", url.Values{"email": {"ada@example.com"}, "password": {"password1"}}).
		AssertRedirect("/dashboard") // the page asked for before logging in
}
```

(Copied from [`examples/auth/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main_test.go), region `test-auth`.)

Tests that need a logged-in user can log in through the form, as above,
or create the user and post to your login route. API tokens work in tests
like in production:

```go
func TestAPIToken(t *testing.T) {
	app := anetostest.New(t, setup)
	createUser(t, app, "Ada", "ada@example.com", false)
	app.Get("/login")
	app.PostForm("/login", url.Values{"email": {"ada@example.com"}, "password": {"password1"}})
	app.PostForm("/confirm-password", url.Values{"password": {"password1"}}) // tokens need it
	app.PostForm("/tokens", url.Values{"name": {"cli"}}).AssertRedirect("/dashboard")
	token := app.Session().GetString("token") // flashed to show once

	// The API routes don't use the session: only the token counts.
	app.GetJSON("/api/me").AssertStatus(http.StatusUnauthorized)
	app.WithHeader("Authorization", "Bearer "+token).GetJSON("/api/me").
		AssertOK().
		AssertJSONPath("email", "ada@example.com")
}
```

(Copied from [`examples/auth/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main_test.go), region `test-api-token`.)

## How it works

The session holds the user's ID and a fingerprint of their password hash:
when the password changes, other sessions no longer match and are logged
out. "Remember me" sets a second cookie, encrypted with `APP_KEY`, holding
the user's ID and remember token (a column of your users table): when the
session has ended, the cookie logs the user back in to a new session.
`Logout` replaces the token, which invalidates every remembered browser.

Verification and reset tokens aren't stored: they are encrypted with
`APP_KEY` and hold the user's ID, an expiry and (for resets) the password
fingerprint. API tokens are `<id>|<secret>`; only a SHA-256 hash of the
secret is stored, and the use is recorded at most once a minute.

Password hashes are argon2id with OWASP's recommended parameters
(19 MiB, 2 passes); at most a few run at once (as many as there are
CPUs), so a burst of logins waits rather than exhausting memory. Existing
bcrypt hashes (from an existing app, say) still work (bcrypt only checks a
password's first 72 bytes), and `Attempt` replaces them, and argon2id
hashes weaker than the defaults, after the next login when you set
`Users.SetPassword`. The new hash changes the password fingerprint, so
the user's other sessions are logged out once.

> **Coming from another framework?** `a.Attempt`, `a.Login`, `a.Logout`
> and `auth.User` do what Django's `authenticate()`, `login()`,
> `logout()` and `request.user`, Laravel's `Auth::attempt()`,
> `Auth::login()`, `Auth::logout()` and `auth()->user()`, or the
> `authenticate_by`, `start_new_session_for`, `terminate_session` and
> `Current.user` of Rails' authentication generator do. `a.Require` and
> `a.Guest` let only logged-in users, or only guests, through. API
> tokens with abilities are built in (`a.CreateToken`,
> `auth.TokenCan`). `anetos make:auth` writes the pages
> ([Add accounts with make:auth](https://docs.anetos.dev/guides/accounts/index.md)), and
> [Social login](https://docs.anetos.dev/guides/social-login/index.md) adds Google, GitHub and any OpenID
> Connect provider.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `auth: login throttling needs the app's cache` at startup | `cache.New` isn't called, or is called after `auth.New` | Set up the cache first |
| `auth: no auth state in the context` | The route lacks `a.Middleware` | Add it after the session middleware |
| `auth: New called twice for one app` | Two `auth.New` calls | An app has one Auth, for one user type |
| `the current user was asked for while it was being loaded` | `Users.ByID` calls `auth.User` or `auth.Check` (through a query scope, say) | Don't ask for the current user while finding it |
| Every page redirects to the login page after logging in | `a.Middleware` runs before the session middleware | Put the session middleware first |
| Users are logged out when they change their password | By design: other sessions end | Use `a.ChangePassword`, or call `a.LogoutOthers(ctx, u)` after storing the new hash: it keeps the current session, bound to the new password |
| "Remember me" returns an error | `Users.RememberToken`/`SetRememberToken` are unset | Add a `remember_token` column and set both |
| API requests get 401 with a valid token | The route uses the session middleware and `a.Middleware` but not `a.TokenMiddleware` | Put API routes in a group with `a.TokenMiddleware` |

## Next steps

- [Authorization](https://docs.anetos.dev/guides/authorization/index.md)
- [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md)
- [Social login](https://docs.anetos.dev/guides/social-login/index.md)
- [Two-factor authentication and password confirmation](https://docs.anetos.dev/guides/two-factor/index.md)
- [Rate limiting](https://docs.anetos.dev/guides/rate-limiting/index.md)
- [Sessions and flash messages](https://docs.anetos.dev/guides/sessions/index.md)


# Social login

Source: https://docs.anetos.dev/guides/social-login/

Let users log in with Google, GitHub, or any OpenID Connect provider
(Okta, Auth0, Microsoft Entra ID, Keycloak, GitLab…). The complete app is
[`examples/auth`](https://github.com/anetos-dev/anetos/tree/main/examples/auth).

An app made with [`make:auth`](https://docs.anetos.dev/guides/accounts/index.md) has Google and GitHub set up
already: set their settings (below) and the buttons appear. This guide
explains what that code does, and how to add social login to an app of
your own.

## Before you start

Set up [authentication](https://docs.anetos.dev/guides/authentication/index.md) first: social login finds or
creates your user and logs them in with `auth`. You also need:

- `APP_URL`, the app's public URL (`https://example.com`, or
  `http://localhost:8080` in development). Providers send users back to
  `APP_URL/auth/<provider>/callback`.
- An OAuth app at each provider, with that callback URL registered: the
  [Google Cloud console](https://console.cloud.google.com/apis/credentials)
  ("OAuth client ID", type "Web application") or
  [GitHub](https://github.com/settings/developers) ("New OAuth App").
  Put its client ID and secret in `SOCIAL_<NAME>_CLIENT_ID` and
  `SOCIAL_<NAME>_CLIENT_SECRET`:

```env
APP_URL=https://example.com
SOCIAL_GOOGLE_CLIENT_ID=1234-abc.apps.googleusercontent.com
SOCIAL_GOOGLE_CLIENT_SECRET=…
SOCIAL_GITHUB_CLIENT_ID=Iv1.abc
SOCIAL_GITHUB_CLIENT_SECRET=…
```

## Steps

### 1. Link accounts to users

Add `social.Migrations()` to your migrations, for the `social_accounts`
table that links provider accounts to users. Then write the function
that finds the user for a provider account:

```go
// findOrCreate returns the user of a provider account: the one it is
// linked to; else the user with its verified email address (who then
// logs in with either); else a new user. An address the provider hasn't
// verified can't be trusted to find anyone, and nor can one the user
// hasn't verified here: someone could have registered it first, with a
// password, to take over the account of whoever logs in with it later.
func findOrCreate(ctx context.Context, p social.Profile) (*User, error) {
	id, linked, err := social.FindLink(ctx, p)
	if err != nil {
		return nil, err
	}
	if linked {
		u, err := users.ByID(ctx, id)
		if !errors.Is(err, db.ErrNotFound) {
			return u, err
		}
		// The user was deleted: forget the link and start again.
		if err := social.Unlink(ctx, id, p.Provider); err != nil {
			return nil, err
		}
	}
	if p.Email == "" || !p.EmailVerified {
		return nil, &social.NoAccountError{Message: "Your " + p.Provider + " account has no verified email address."}
	}
	var u *User
	err = db.Tx(ctx, func(ctx context.Context) error { // the user and the link, or neither
		u, err = users.ByLogin(ctx, p.Email)
		if errors.Is(err, db.ErrNotFound) {
			now := anetos.Now(ctx).UTC()
			name := p.Name
			if name == "" {
				name = p.Email
			}
			u = &User{Name: name, Email: strings.ToLower(p.Email), EmailVerifiedAt: &now} // no password
			err = db.Create(ctx, u)
		}
		if err != nil {
			return err
		}
		if u.EmailVerifiedAt == nil {
			return &social.NoAccountError{Message: "An account with this email address exists. Log in with your password and verify the address, then log in with " + p.Provider + "."}
		}
		// Linked already to another account at the provider: the address
		// was reused, not the same person.
		links, err := social.Links(ctx, u.AuthID())
		if err != nil {
			return err
		}
		if slices.ContainsFunc(links, func(l social.Account) bool { return l.Provider == p.Provider }) {
			return &social.NoAccountError{Message: "The account with this email address logs in with another " + p.Provider + " account."}
		}
		return social.Link(ctx, p, u.AuthID())
	})
	return u, err
}
```

(Copied from [`examples/auth/users.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/users.go), region `social`.)

Link users by the account (`FindLink`, `Link`), not by email: addresses
change, and can be reused. When you delete a user, delete their links
(`social.Unlink`); the example also forgets a link whose user is gone. Only use an email address to find an existing
user when both the provider and your app have verified it; otherwise
someone could register the address first, with a password, and take over
the account of whoever later logs in with it. Nor does the example link
a second account of the same provider to a user by email: an address
the provider gave to someone new (a closed account, a reused work
address) isn't the same person. Return `*social.NoAccountError` to refuse
with a message on the login page.

### 2. Set up the providers and routes

```go
// Providers with SOCIAL_<NAME>_CLIENT_ID and _CLIENT_SECRET set; their
// callbacks are APP_URL/auth/<name>/callback.
s, err := social.New(app, a, findOrCreate, social.Configured(app, social.Google(), social.GitHub()))
if err != nil {
	return nil, err
}
```

(Copied from [`examples/auth`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `social-setup`.)

`social.Configured` keeps the providers whose credentials are set, so a
provider is enabled by its settings; with none, the routes answer 404.
For another OpenID Connect provider, add
`social.OIDC("okta", "https://example.okta.com")`: its endpoints are read
from the issuer's discovery document. Give the issuer exactly as the
provider writes it, trailing slash included (Auth0:
`https://TENANT.auth0.com/`), and a tenant's own issuer rather than a
multi-tenant one (Microsoft Entra ID's `/common`). Microsoft Entra ID
doesn't send `email_verified` by default, so its addresses count as
unverified. Every URL of a provider must be `https`.

Add the redirect and callback routes to the guest pages (see the routes in
[Authentication](https://docs.anetos.dev/guides/authentication/index.md#2-set-up-auth-and-protect-routes)):

```go
// illustrative
guests.Get("/auth/{provider}/redirect", s.Redirect)
guests.Get("/auth/{provider}/callback", s.Callback)
```

and a link per provider on the login page, from `s.Providers()` (their
names, in URLs) and `s.Title(name)` (their names for people, "Google"):

```html
<a href="/auth/github/redirect">Log in with GitHub</a>
<a href="/auth/google/redirect?remember=1">Log in with Google (remember me)</a>
```

A failed or canceled login returns to `AUTH_LOGIN_URL` with an error on
the `social` field (`view.Errors(ctx).Get("social")`); a successful one
goes to the page the user wanted, or `AUTH_HOME_URL`, as a login does
(`social.WithHomeURL("/welcome")` sets another for social logins).

### 3. Test

With the `anetostest.FakeSocial` option, every provider logs in through a
stand-in provider the test controls (nothing reaches Google or GitHub,
and no settings are needed). `app.SocialLogin` follows the redirect
route, plays the provider's page for the account you give, and returns
the app's answer to the callback:

```go
func TestSocialLogin(t *testing.T) {
	// FakeSocial: Google and GitHub log in through a stand-in provider.
	app := anetostest.New(t, setup, anetostest.FakeSocial())
	app.Get("/login").AssertSee(`href="/auth/google/redirect"`, "Log in with Google")

	// A new account: a user is created, with the address verified.
	grace := anetostest.SocialAccount{ID: "g-1", Email: "grace@example.com", EmailVerified: true, Name: "Grace"}
	app.SocialLogin("/auth/google/redirect", grace).AssertRedirect("/dashboard") // AUTH_HOME_URL
	app.Get("/dashboard").AssertSee("Hello, Grace").AssertDontSee("Please verify")
	app.PostForm("/logout", nil)

	// The same account again, with a new address: the linked user.
	grace.Email = "grace@new.example"
	app.SocialLogin("/auth/google/redirect", grace).AssertRedirect("/dashboard")
	n, err := db.RawFirst[int64](app.Context(), "SELECT COUNT(*) FROM users")
	if err != nil || n != 1 {
		t.Errorf("users: %d, %v", n, err)
	}
}
```

(Copied from [`examples/auth/social_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/social_test.go), region `test-social`.)

## How it works

`Redirect` sends the browser to the provider with a random `state`, a
PKCE code challenge and, for OpenID Connect, a `nonce`, and keeps them in
the session. `Callback` accepts the provider's answer only with that
state, once, within ten minutes; exchanges the code for tokens with the
PKCE verifier; and reads the profile. For OpenID Connect providers the
profile comes from the ID token, whose issuer, audience, expiry and nonce
are checked; its signature isn't, because it came straight from the
provider's token endpoint over TLS (which OpenID Connect allows, and
which is why endpoints must be `https`). For GitHub, it comes from the
API: the account's primary address, and whether GitHub verified it.

Requests to providers refuse redirects to anything but `https`, and a
provider's discovery document is fetched in the background (a failure
is retried after 30 seconds, and the document is refreshed daily, keeping
the old endpoints if that fails), so a slow provider doesn't hold up
requests past their deadline. A fetch in progress at shutdown may run for
up to 10 more seconds.

`anetostest.FakeSocial` runs a stand-in OpenID Connect provider on a
local TLS server and hands it to the app (through an internal hook,
honored only with `APP_ENV=testing`) before `setup` runs:
`social.New` then points every provider at it (keeping their names,
titles and scopes), and `social.Configured` keeps every provider. The
flow is the real one, state, PKCE and ID token checks included, with
one difference: every provider logs in as an OpenID Connect provider,
so a provider that reads the profile from its API (GitHub's
`/user/emails`, a `Provider.Profile` of your own) doesn't run that code
in these tests.

`Profile.Token` holds the provider's tokens, for calling its API with the
scopes asked for; change `Provider.Scopes` to ask for more.

A user with [two-factor authentication](https://docs.anetos.dev/guides/two-factor/index.md) on isn't logged in by
the callback: it logs in with `a.Login`, which asks for the code, and sends them to
`AUTH_CHALLENGE_URL` for their code.

> **Coming from another framework?** This does what django-allauth,
> Laravel Socialite or OmniAuth in Rails do: the redirect and the
> callback are two handlers, and finding or creating the user is your
> function.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `social: APP_URL "" must be the app's public URL` | `APP_URL` isn't set | Set it; it must match the callback URL registered with the provider |
| The provider says `redirect_uri_mismatch` | The registered callback URL differs from `APP_URL/auth/<name>/callback` | Register exactly that URL (scheme, host, port) |
| Every login returns to the login page with "didn't complete" | The session cookie isn't sent back from the provider (a `SameSite=Strict` cookie, or another host) | Keep `SESSION_SAME_SITE=lax` and use the same host as `APP_URL` |
| `social: set SOCIAL_GOOGLE_CLIENT_ID and SOCIAL_GOOGLE_CLIENT_SECRET` | A provider was passed without credentials | Set them, or pass the providers through `social.Configured` |
| "has no verified email address" | The account's address isn't verified at the provider | Verify it there, or link accounts another way |

## Next steps

- [Authentication](https://docs.anetos.dev/guides/authentication/index.md)
- [Authentication reference](https://docs.anetos.dev/reference/auth/index.md#social-login)


# Two-factor authentication and password confirmation

Source: https://docs.anetos.dev/guides/two-factor/

Ask for more than a password: a code from an authenticator app (Google
Authenticator, 1Password, Authy… : TOTP, RFC 6238) after it, with
recovery codes for a lost phone; and the password again before
sensitive pages. Package `auth` does the parts that must be right
(secrets encrypted, codes used once, throttling); your handlers and
pages call it. The complete app is
[`examples/auth`](https://github.com/anetos-dev/anetos/tree/main/examples/auth).

An app made with [`make:auth`](https://docs.anetos.dev/guides/accounts/index.md) has all of this already: a
"Two-factor authentication" link on the dashboard, the code after the password,
and the password asked again before turning it on or off. This guide
explains that code, and how to add it to an app of your own.

## Before you start

Set up [authentication](https://docs.anetos.dev/guides/authentication/index.md) first. Two-factor authentication
keeps its state in the users table: add a column for it (text, up to
1,024 characters, empty by default):

```go
// illustrative: in the users table's migration
t.String("two_factor", 1024).Default("")
```

## Steps

### 1. Store the state

`auth.Users` gets two functions: `TwoFactor` returns the stored state
of a user, `SetTwoFactor` stores a new one. Package `auth` writes it:
the secret encrypted with `APP_KEY` (for that user only), the recovery
codes hashed.

```go
// users tells package auth how to find and update users.
var users = auth.Users[*User]{
	ByID: func(ctx context.Context, id string) (*User, error) {
		n, err := strconv.ParseInt(id, 10, 64)
		if err != nil {
			return nil, auth.ErrUserNotFound
		}
		u, err := db.Find[User](ctx, n) // db.ErrNotFound: no such user
		return &u, err
	},
	ByLogin: func(ctx context.Context, email string) (*User, error) {
		u, err := db.Query[User](ctx).Where(colEmail.Eq(strings.ToLower(email))).First()
		return &u, err
	},
	RememberToken: func(u *User) string { return u.RememberToken },
	SetRememberToken: func(ctx context.Context, u *User, token string) error {
		_, err := db.Query[User](ctx).Where(colID.Eq(u.ID)).Update(colRemember.Set(token))
		return err
	},
	SetPassword: func(ctx context.Context, u *User, hash string) error {
		_, err := db.Query[User](ctx).Where(colID.Eq(u.ID)).Update(colPassword.Set(hash))
		return err
	},
	// Two-factor authentication: package auth stores its state (the secret
	// encrypted with APP_KEY, the recovery codes hashed) in a column.
	TwoFactor: func(u *User) string { return u.TwoFactor },
	SetTwoFactor: func(ctx context.Context, u *User, state string) error {
		u.TwoFactor = state
		_, err := db.Query[User](ctx).Where(colID.Eq(u.ID)).Update(colTwoF.Set(state))
		return err
	},
}
```

(Copied from [`examples/auth/users.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/users.go), region `users`.)

### 2. Let users turn it on

Turning it on takes two steps. `a.StartTwoFactor(ctx, u, account)`
stores a new secret and returns it, with its `otpauth://` URI: the user
scans it as a QR code (package [`qr`](https://pkg.go.dev/anetos.dev/anetos/qr) draws
one as SVG) or types the key. `a.ConfirmTwoFactor(ctx, u, code)` turns
it on once the user types the code their app shows, and returns eight
recovery codes, to show once. Until then, `a.StartedTwoFactor` shows the
same setup again; `a.TwoFactor(u)` says where it stands.

```go
// TwoFactor shows two-factor authentication: off, being set up (a QR code for
// the authenticator app), or on; and the recovery codes, once.
func (h Accounts) TwoFactor(c *web.Ctx) error {
	u, err := auth.Current[*User](c)
	if err != nil {
		return err
	}
	st, err := h.auth.TwoFactor(u)
	if err != nil {
		return err
	}
	data := map[string]any{"On": st.On, "Left": st.RecoveryCodes, "Codes": strings.Fields(view.Flash(c, "codes"))}
	if st.Started {
		setup, err := h.auth.StartedTwoFactor(u, u.Email)
		if err != nil {
			return err
		}
		svg, err := qr.SVG(setup.URI, qr.M, 200) // otpauth://totp/…
		if err != nil {
			return err
		}
		data["Secret"], data["QR"] = setup.Secret, template.HTML(svg) //nolint:gosec // package qr's markup
	}
	return render(c, "two-factor", data)
}

// StartTwoFactor makes a new secret, shown by TwoFactor until confirmed.
func (h Accounts) StartTwoFactor(c *web.Ctx) error {
	u, err := auth.Current[*User](c)
	if err != nil {
		return err
	}
	if _, err := h.auth.StartTwoFactor(c, u, u.Email); err != nil && !errors.Is(err, auth.ErrTwoFactorOn) {
		return err
	}
	return c.Redirect(http.StatusSeeOther, "/two-factor")
}

// ConfirmTwoFactor turns it on with a code of the app, and shows the
// recovery codes, once.
func (h Accounts) ConfirmTwoFactor(c *web.Ctx, in CodeInput) (web.Responder, error) {
	u, err := auth.Current[*User](c)
	if err != nil {
		return nil, err
	}
	codes, err := h.auth.ConfirmTwoFactor(c, u, in.Code)
	switch {
	case errors.Is(err, auth.ErrInvalidCode):
		return nil, validate.Fail("code", "That code isn't right.")
	case err != nil:
		return nil, err
	}
	c.Session().Flash("codes", strings.Join(codes, " "))
	return web.Redirect("/two-factor"), nil
}

// DisableTwoFactor turns it off.
func (h Accounts) DisableTwoFactor(c *web.Ctx) error {
	u, err := auth.Current[*User](c)
	if err != nil {
		return err
	}
	if err := h.auth.DisableTwoFactor(c, u); err != nil {
		return err
	}
	return c.Redirect(http.StatusSeeOther, "/two-factor")
}
```

(Copied from [`examples/auth/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `two-factor`.)

The issuer the app shows is `APP_NAME`. `a.NewRecoveryCodes(ctx, u)`
replaces the recovery codes; `a.DisableTwoFactor(ctx, u)` turns it off
(the admin's users pages can too, for someone who lost their phone).

### 3. Ask for the code at login

For a user with it on, `a.Attempt` checks the password, then stops:
it returns `auth.ErrTwoFactorRequired`, and the login waits, in the
session, for 10 minutes. Send the user to the code page
(`AUTH_CHALLENGE_URL`, default `/two-factor-challenge`):

```go
func (h Accounts) Login(c *web.Ctx, in LoginInput) (web.Responder, error) {
	_, err := h.auth.Attempt(c, in.Email, in.Password, in.Remember)
	var throttled *auth.ThrottledError
	switch {
	case errors.Is(err, auth.ErrInvalidCredentials):
		return nil, validate.Fail("email", "These credentials don't match our records.")
	case errors.As(err, &throttled):
		return nil, validate.Fail("email", "Too many login attempts. Try again in a minute.")
	case errors.Is(err, auth.ErrTwoFactorRequired):
		return web.Redirect("/two-factor-challenge"), nil // the password was right: now the code
	case err != nil:
		return nil, err
	}
	return web.Redirect(auth.Intended(c, h.auth.Config().HomeURL)), nil // the page they wanted, or AUTH_HOME_URL
}

func (h Accounts) Logout(c *web.Ctx) error {
	if err := h.auth.Logout(c); err != nil {
		return err
	}
	return c.Redirect(http.StatusSeeOther, "/login")
}
```

(Copied from [`examples/auth/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `login`.)

There, `a.AttemptTwoFactor(ctx, code)` finishes the login with the
app's code or a recovery code, which is then used up:

```go
// Challenge finishes a login waiting for a code (after Login).
func (h Accounts) Challenge(c *web.Ctx, in CodeInput) (web.Responder, error) {
	_, err := h.auth.AttemptTwoFactor(c, in.Code)
	var throttled *auth.ThrottledError
	switch {
	case errors.Is(err, auth.ErrInvalidCode):
		return nil, validate.Fail("code", "That code isn't right.")
	case errors.As(err, &throttled):
		return nil, validate.Fail("code", "Too many tries. Try again in a minute.")
	case errors.Is(err, auth.ErrNoPendingLogin): // none, or it expired
		return web.Redirect("/login"), nil
	case err != nil:
		return nil, err
	}
	return web.Redirect(auth.Intended(c, h.auth.Config().HomeURL)), nil
}
```

(Copied from [`examples/auth/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `challenge`.)

Other ways of logging in ask for the code too: login with Google or
GitHub ([social login](https://docs.anetos.dev/guides/social-login/index.md)) sends users with it on to
`AUTH_CHALLENGE_URL`. In your own login code, `a.Login(ctx, u,
remember)` does the same: it answers `auth.ErrTwoFactorRequired` for a
user who has turned it on. A remember-me cookie, given after the code,
keeps the user logged in without it.

An API without sessions gets the code in a second request:
`a.AttemptCredentials` answers a `*auth.TwoFactorChallenge`, whose
`Token` the client sends back with the code to
`a.AttemptTwoFactorChallenge`, under the same limits
([Add accounts to an API](https://docs.anetos.dev/guides/api-accounts/index.md#4-two-factor-login)).

### 4. Ask for the password again

Before sensitive pages (turning two-factor authentication on or off, changing
the email address, deleting the account), ask for the password again
with the `a.RequireConfirmed` middleware: users who haven't confirmed it
in the last `AUTH_CONFIRM_TTL` (15 minutes) go to `AUTH_CONFIRM_URL`
(`/confirm-password`), then back. API clients and htmx requests get 423.

```go
// ConfirmPassword checks the password again (it holds for
// AUTH_CONFIRM_TTL), then goes back to the page that asked for it.
func (h Accounts) ConfirmPassword(c *web.Ctx, in PasswordInput) (web.Responder, error) {
	switch err := h.auth.ConfirmPassword(c, in.Password); {
	case errors.Is(err, auth.ErrInvalidCredentials):
		return nil, validate.Fail("password", "That isn't your password.")
	case err != nil:
		return nil, err
	}
	return web.Redirect(auth.Intended(c, h.auth.Config().HomeURL)), nil
}
```

(Copied from [`examples/auth/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `confirm`.)

The routes:

```go
pages := r.Group("", sessions.Middleware, web.CSRF(), a.Middleware)
pages.Get("/", func(c *web.Ctx) error { return c.Redirect(http.StatusSeeOther, "/dashboard") })
pages.Get("/verify-email", web.H(h.VerifyEmail))

guests := pages.Group("", a.Guest) // logged-in users go to AUTH_HOME_URL
guests.Get("/register", h.page("register"))
guests.Post("/register", web.H(h.Register))
guests.Get("/login", h.page("login"))
guests.Post("/login", web.H(h.Login))
guests.Get("/forgot-password", h.page("forgot"))
guests.With(ratelimit.Middleware("forgot-password", ratelimit.PerMinute(5))).Post("/forgot-password", web.H(h.SendReset))
guests.Get("/reset-password", h.page("reset"))
guests.Post("/reset-password", web.H(h.Reset))
guests.Get("/auth/{provider}/redirect", s.Redirect) // "Log in with …" links here
guests.Get("/auth/{provider}/callback", s.Callback)
guests.Get("/two-factor-challenge", h.page("challenge")) // AUTH_CHALLENGE_URL
guests.Post("/two-factor-challenge", web.H(h.Challenge))

loggedIn := pages.Group("", a.Require) // guests go to AUTH_LOGIN_URL
loggedIn.Get("/dashboard", h.Dashboard)
loggedIn.Post("/logout", h.Logout)
loggedIn.Post("/tokens/{id}/delete", web.H(h.RevokeToken))
loggedIn.Get("/users/{id}", web.H(h.ShowUser))
loggedIn.Get("/admin", h.Admin)
loggedIn.Post("/password", web.H(h.ChangePassword))
loggedIn.Get("/confirm-password", h.page("confirm")) // AUTH_CONFIRM_URL
loggedIn.Post("/confirm-password", web.H(h.ConfirmPassword))

// Two-factor authentication (AUTH_TWO_FACTOR_URL) and API tokens (they work
// without the browser): the password again first.
secure := loggedIn.Group("", a.RequireConfirmed)
secure.Post("/tokens", web.H(h.CreateToken))
secure.Get("/two-factor", h.TwoFactor)
secure.Post("/two-factor", h.StartTwoFactor)
secure.Post("/two-factor/confirm", web.H(h.ConfirmTwoFactor))
secure.Post("/two-factor/disable", h.DisableTwoFactor)

api := r.Group("/api", a.TokenMiddleware, a.Require) // Authorization: Bearer <token>
api.Get("/me", h.Me)
```

(Copied from [`examples/auth/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `routes`.)

The [admin](https://docs.anetos.dev/guides/admin/index.md) asks for the password before its dangerous
actions too, and with `ADMIN_TWO_FACTOR=required` lets in only users
with two-factor authentication on.

## How it works

Codes are TOTP (RFC 6238): HMAC-SHA-1 of a 160-bit secret and the time
in 30-second steps, six digits, as authenticator apps expect. A code is
accepted for its step and the one either side (a phone's clock a little
off), and only for a step later than the last one used, so a code seen
over someone's shoulder can't be used again. Recovery codes are ten
letters and digits (50 bits; a 0 or 1 typed for o or l is read as
them), stored as SHA-256 hashes, each used once.

The state is one encrypted value: `APP_KEY` encrypts it for that user
alone, so it can't be copied to another; rotate keys with
`APP_PREVIOUS_KEYS`, as for everything `APP_KEY` encrypts. If it can't
be read (the key was lost), logging in fails rather than skipping the
code; turn it off for the user (`DisableTwoFactor`, or the admin).

Codes, like passwords, are throttled: `AUTH_THROTTLE` tries a minute
for a user, from any address, while logging in, confirming a setup or a
password; and at login, 50 wrong codes a day for a user, after which
codes are refused until the day is over (someone who has the password
gets very few guesses; the warnings in the log say so, and the user
should change their password). A login waiting for its code ends
after 10 minutes, at a password change, and when another login
starts in the session. Turning two-factor authentication on logs the user out
of their other sessions (with `Users.SessionKey`) and remember-me
cookies, which were logged in without a code.

Confirming the password lasts `AUTH_CONFIRM_TTL`; logging in or out, and
impersonating another user, forget it. Users without a password (they log
in with Google or GitHub) can't type one: for them, a login through
`a.Login` (social login's) counts as a confirmation for
`AUTH_CONFIRM_TTL`, so they confirm by logging out and in again.

| Setting | Default | |
|---|---|---|
| `AUTH_CHALLENGE_URL` | `/two-factor-challenge` | Where a login asks for its code |
| `AUTH_TWO_FACTOR_URL` | `/two-factor` | Where users turn it on and off (the admin links there) |
| `AUTH_CONFIRM_URL` | `/confirm-password` | Where `RequireConfirmed` sends users |
| `AUTH_CONFIRM_TTL` | `15m` | How long a confirmed password holds |

## Testing it

`auth.TwoFactorCode(secret, t)` is the code an app shows at `t`:

```go
// Two-factor authentication: turned on with a code of the authenticator app
// (auth.TwoFactorCode computes it), then asked for after the password.
func TestTwoFactor(t *testing.T) {
	app := anetostest.New(t, setup)
	ada := createUser(t, app, "Ada", "ada@example.com", false)
	app.Get("/login")
	app.PostForm("/login", url.Values{"email": {"ada@example.com"}, "password": {"password1"}})

	app.Get("/two-factor").AssertRedirect("/confirm-password") // the password again first
	app.PostForm("/confirm-password", url.Values{"password": {"password1"}}).AssertRedirect("/two-factor")
	app.PostForm("/two-factor", nil).AssertRedirect("/two-factor").Follow().AssertSee("<svg", "Or type this key")

	ada, _ = users.ByID(app.Context(), ada.AuthID()) // with the secret stored
	setup, err := anetos.MustResolve[*auth.Auth[*User]](app.App).StartedTwoFactor(ada, ada.Email)
	if err != nil {
		t.Fatal(err)
	}
	code, _ := auth.TwoFactorCode(setup.Secret, app.Now())
	app.PostForm("/two-factor/confirm", url.Values{"code": {code}}).AssertRedirect("/two-factor").
		Follow().AssertSee("Your recovery codes", "On: 8 recovery codes left.")

	app.PostForm("/logout", nil)
	app.Get("/login")
	app.PostForm("/login", url.Values{"email": {"ada@example.com"}, "password": {"password1"}}).AssertRedirect("/two-factor-challenge")
	app.Get("/dashboard").AssertRedirect("/login") // not logged in yet
	app.Get("/two-factor-challenge")
	app.PostForm("/two-factor-challenge", url.Values{"code": {code}}).AssertValidationErrors("code") // used already
	app.Travel(30 * time.Second)
	code, _ = auth.TwoFactorCode(setup.Secret, app.Now())
	app.PostForm("/two-factor-challenge", url.Values{"code": {code}}).AssertRedirect("/dashboard")
}
```

(Copied from [`examples/auth/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main_test.go), region `test-two-factor`.)

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| "That code isn't right" with a fresh code | The phone's clock is off by more than 30 seconds | Set its time automatically |
| Every code refused with 429 for hours | 50 wrong codes in a day for that user | Wait, and change the password: someone may have it |
| A user who logs in with Google is sent to confirm a password | Users without a password confirm by logging in again | Log out and in again, then go back within `AUTH_CONFIRM_TTL` |
| The code is refused right after turning it on | That code was used to turn it on: each is used once | Wait for the next one |
| `the user's two-factor state can't be read` | `APP_KEY` changed without the old key in `APP_PREVIOUS_KEYS` | Put the old key back in `APP_PREVIOUS_KEYS`, or turn it off for the user |
| `two-factor authentication needs Users.TwoFactor and Users.SetTwoFactor` | `auth.Users` lacks them | Add them (step 1) |

## Next steps

- [Add an admin panel](https://docs.anetos.dev/guides/admin/index.md), which can require it.
- [Authentication](https://docs.anetos.dev/guides/authentication/index.md): passwords, sessions, remember me.
- [Social login](https://docs.anetos.dev/guides/social-login/index.md).


# Authorization

Source: https://docs.anetos.dev/guides/authorization/

Decide what a logged-in user may do, with policies the compiler checks.

## Before you start

Set up [authentication](https://docs.anetos.dev/guides/authentication/index.md): policies check the request's
logged-in user.

Policies decide from the user and the thing acted on ("authors edit
their own posts"). For roles stored per user, globally or in a team
("Ada is an owner of Acme"), use [roles and
permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md); a policy can check those too,
with `rbac.CanIn`.

## Steps

### 1. Write policies

A policy is a function of the context, the user and (usually) the thing
acted on, returning whether the action is allowed. Group them as methods
of a type:

```go
// ManageUsers is for the admin page.
func (Policies) ManageUsers(_ context.Context, u *User) bool { return u.Admin }

// ViewUser lets users see their own profile, and admins everyone's.
func (Policies) ViewUser(_ context.Context, u *User, other *User) bool {
	return u.Admin || u.ID == other.ID
}
```

(Copied from [`examples/auth/users.go`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/users.go), region `policy`.)

### 2. Check them in handlers

```go
func (Accounts) ShowUser(c *web.Ctx, in UserID) (*User, error) {
	other, err := db.Find[User](c, in.ID)
	if err != nil {
		return nil, err
	}
	if err := auth.Authorize(c, policies.ViewUser, &other); err != nil {
		return nil, err // 403 unless it's you, or you're an admin
	}
	return &other, nil
}

func (Accounts) Admin(c *web.Ctx) error {
	if err := auth.AuthorizeUser(c, policies.ManageUsers); err != nil {
		return err
	}
	all, err := db.Query[User](c).OrderBy(colID.Asc()).Get()
	if err != nil {
		return err
	}
	return render(c, "admin", map[string]any{"Users": all})
}
```

(Copied from [`examples/auth`](https://github.com/anetos-dev/anetos/blob/main/examples/auth/main.go), region `authorize`.)

`auth.Authorize` returns nil if the policy allows the action,
`auth.ErrUnauthenticated` (401) for a guest and `auth.ErrForbidden` (403)
otherwise, so a handler can return the error as it is.
`auth.AuthorizeUser` does the same for policies about the user alone.

### 3. Show or hide actions

`auth.Allows` and `auth.AllowsUser` report the answer as a boolean,
false for a guest:

```go
// illustrative
canEdit := auth.Allows(c, policies.UpdatePost, &post)
```

## How it works

Policies are plain Go functions: `Authorize[U, T]` infers the user type
`U` and the subject type `T` from the policy, finds the user with
`auth.Current[U]`, and calls it. A policy for posts can't be called with
a comment, and there are no ability names to misspell.

> **Coming from another framework?** Policy methods and
> `auth.Authorize(c, policies.Update, post)` play the part of Django's
> `has_perm` checks, Laravel's policies and `authorize()`, or Pundit's
> policies in Rails; `auth.Allows` is the check in a template. There
> are no permission checks by name string.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| Every check returns 401 | The route lacks the auth middleware, or no one is logged in | Add `a.Middleware` (or `a.Require`) to the route |
| `the logged-in user isn't of the type asked for` | The policy's user type differs from the one given to `auth.New` | Use the same type (`*User` in both) |

## Next steps

- [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md)
- [Authentication](https://docs.anetos.dev/guides/authentication/index.md)


# Roles and permissions

Source: https://docs.anetos.dev/guides/roles-and-permissions/

Give users roles, globally or in a team, and check what they may do,
with package `auth/rbac`.

## Before you start

- Set up [authentication](https://docs.anetos.dev/guides/authentication/index.md): permissions are checked
  for the request's logged-in user, logged in with a session or an API
  token.
- Run the migrations of `rbac.Migrations()` (the `rbac_grants` and
  `rbac_roles` tables) with your own.

The code here comes from [`examples/teams`](https://github.com/anetos-dev/anetos/tree/main/examples/teams), a
JSON API where users work in teams.

## Steps

### 1. Declare permissions and roles

A permission is something a user may do. Declare each as a constant of
type `rbac.Permission`, and the roles as sets of them:

```go
// The app's permissions: what a user may do. Each is also the API token
// ability that allows it.
const (
	ViewProjects   rbac.Permission = "projects.view"
	CreateProjects rbac.Permission = "projects.create"
	DeleteProjects rbac.Permission = "projects.delete"
	ManageMembers  rbac.Permission = "members.manage"
	DeleteTeams    rbac.Permission = "teams.delete"
	ManageRoles    rbac.Permission = "roles.manage"   // roles of the database
	ViewAllTeams   rbac.Permission = "teams.view-all" // support staff
)

// permissions are all of them, for rbac.New.
var permissions = []rbac.Permission{ViewProjects, CreateProjects, DeleteProjects, ManageMembers, DeleteTeams, ManageRoles, ViewAllTeams}

// roles are the roles declared in code. Owners, members and guests are
// given in a team; admins and support staff globally, so they apply in
// every team.
var roles = []rbac.Role{
	{Name: "admin", Title: "Administrator", Super: true},
	{Name: "support", Title: "Support", Permissions: []rbac.Permission{ViewAllTeams, ViewProjects}},
	{Name: "owner", Title: "Owner", Permissions: []rbac.Permission{ViewProjects, CreateProjects, DeleteProjects, ManageMembers, DeleteTeams}},
	{Name: "member", Title: "Member", Permissions: []rbac.Permission{ViewProjects, CreateProjects}},
	{Name: "guest", Title: "Guest", Permissions: []rbac.Permission{ViewProjects}},
}

// teamScope is a team's scope: "team:42".
func teamScope(id int64) rbac.Scope { return rbac.ScopeOf("team", id) }
```

(Copied from [`examples/teams/permissions.go`](https://github.com/anetos-dev/anetos/blob/main/examples/teams/permissions.go), region `permissions`.)

Permission and role names are lowercase letters, digits and `. _ : -`.
A super role (`Super: true`) has every permission. `teamScope` makes the
scope a team's roles are given in: grants apply globally (`rbac.Global`)
or in one scope, such as a team, a project or an organization.

### 2. Set them up

```go
if _, err := rbac.New(app, permissions, roles...); err != nil {
	return nil, err
}
```

(Copied from [`examples/teams`](https://github.com/anetos-dev/anetos/blob/main/examples/teams/main.go), region `setup`.)

`rbac.New` checks them (a role can only hold declared permissions)
and adds the `rbac:*` commands. Pass `rbac.Migrations()` to
`migrate.New` with the app's own sets:

```go
// illustrative
sets := []*migrate.Set{Migrations, auth.Migrations(), rbac.Migrations()}
```

Packages with permissions of their own, such as the
[admin](https://docs.anetos.dev/guides/admin/index.md), declare them at setup with `Registry.Declare`
(idempotent, before the app serves), so roles stored in the database can
grant them. A role declared in code can only hold permissions declared
when `rbac.New` runs, so list such permissions with the app's.

### 3. Give users roles

`rbac.Assign` gives a user (by `AuthID`) roles in a scope. Here, the
user who creates a team owns it:

```go
// CreateTeam creates a team, owned by the user who creates it.
func (Handlers) CreateTeam(c *web.Ctx, in NewTeam) (Team, error) {
	userID, err := auth.CurrentID(c)
	if err != nil {
		return Team{}, err
	}
	team := Team{Name: in.Name}
	err = db.Tx(c, func(ctx context.Context) error { // the team and its owner, or neither
		if err := db.Create(ctx, &team); err != nil {
			return err
		}
		return rbac.Assign(ctx, userID, teamScope(team.ID), "owner")
	})
	if err != nil {
		return Team{}, err
	}
	return team, nil
}
```

(Copied from [`examples/teams`](https://github.com/anetos-dev/anetos/blob/main/examples/teams/main.go), region `create-team`.)

`rbac.Sync` makes a list the user's only roles in a scope (an empty list
removes them from it), `rbac.Unassign` takes one away, and
`rbac.Grant` and `rbac.Revoke` give single permissions without a role.
From the command line:

```sh
go run . rbac:assign 1 admin                  # globally
go run . rbac:assign --scope=team:42 7 member # in team 42
go run . rbac:user 7                          # what user 7 has, by scope
```

### 4. Check them on routes

`rbac.Require` lets through users with permissions globally;
`rbac.RequireIn` in the scope it finds for the request, such as
`rbac.PathScope`'s, from a path parameter. Put them after the auth
middleware:

```go
api := r.Group("/api", a.TokenMiddleware, a.Require) // Authorization: Bearer <token>
inTeam := rbac.PathScope("team", "team")             // /teams/42/… is "team:42"

api.Get("/teams", web.H(h.Teams))
api.Post("/teams", web.H(h.CreateTeam)).Status(http.StatusCreated)
api.Get("/teams/{team}/permissions", web.H(h.MyPermissions))
api.With(rbac.RequireIn(inTeam, DeleteTeams)).Delete("/teams/{team}", web.H(h.DeleteTeam))
api.With(rbac.RequireIn(inTeam, ViewProjects)).Get("/teams/{team}/projects", web.H(h.Projects))
api.With(rbac.RequireIn(inTeam, CreateProjects)).Post("/teams/{team}/projects", web.H(h.CreateProject)).Status(http.StatusCreated)
api.With(rbac.RequireIn(inTeam, DeleteProjects)).Delete("/teams/{team}/projects/{id}", web.H(h.DeleteProject))

members := api.With(rbac.RequireIn(inTeam, ManageMembers))
members.Get("/teams/{team}/members", web.H(h.Members))
members.Put("/teams/{team}/members/{user}", web.H(h.SetMember))
members.Delete("/teams/{team}/members/{user}", web.H(h.RemoveMember))

api.Get("/roles", web.H(h.Roles))
api.With(rbac.Require(ManageRoles)).Post("/roles", web.H(h.CreateRole)).Status(http.StatusCreated)
```

(Copied from [`examples/teams`](https://github.com/anetos-dev/anetos/blob/main/examples/teams/main.go), region `routes`.)

A guest gets 401 and a user without the permission 403. A global grant
applies in every scope: an administrator passes every team's checks,
whether the team exists or not, so handlers still find the team (404).

### 5. Check them in handlers and pages

`rbac.Authorize` and `rbac.AuthorizeIn` return nil, `auth.ErrUnauthenticated`
(401) or `auth.ErrForbidden` (403), which a handler returns as they are;
`rbac.Can` and `rbac.CanIn` return a boolean, false for a guest, to show
or hide a button:

```go
// illustrative
if err := rbac.AuthorizeIn(c, teamScope(team.ID), DeleteProjects); err != nil {
	return nil, err
}
data["CanInvite"] = rbac.CanIn(c, teamScope(team.ID), ManageMembers)
```

`rbac.Current` returns the user's grants, read once per request, to ask
more: their roles and permissions in a scope, or their scopes of a kind,
such as their teams:

```go
// Teams lists the user's teams: those where they have a role, or every
// team for support staff.
func (Handlers) Teams(c *web.Ctx, _ struct{}) ([]Team, error) {
	q := db.Query[Team](c).OrderBy(colID.Asc())
	if !rbac.Can(c, ViewAllTeams) {
		g, err := rbac.Current(c)
		if err != nil {
			return nil, err
		}
		var ids []int64
		for _, s := range g.Scopes("team") {
			if id, err := strconv.ParseInt(s.ID(), 10, 64); err == nil {
				ids = append(ids, id)
			}
		}
		q = q.Where(colID.In(ids...))
	}
	return q.Get()
}
```

(Copied from [`examples/teams`](https://github.com/anetos-dev/anetos/blob/main/examples/teams/main.go), region `list-teams`.)

### 6. Let users manage members

A team's members are the users with a role in its scope:
`rbac.Assignments(ctx, scope)` lists them. Before giving a role, check
that the user giving it has every permission it allows in the scope,
with `rbac.AuthorizeRole`, so no one gives more than they have, and,
before changing or taking away a user's roles, that they could give
those too, with `rbac.AuthorizeRolesOf`, so no one demotes someone who
has more:

```go
// SetMember makes a user a member of the team with a role, replacing the
// role they had there.
func (Handlers) SetMember(c *web.Ctx, in SetMemberInput) (web.Empty, error) {
	// Grants in a team that doesn't exist would apply to the next team
	// given its ID.
	if _, err := findTeam(c, in.Team); err != nil {
		return web.Empty{}, err
	}
	u, err := db.Find[User](c, in.User)
	if err != nil {
		return web.Empty{}, err
	}
	team := teamScope(in.Team)
	// No one gives more than they have, or changes the roles of someone
	// who has more: an owner can make owners, not administrators.
	if err := rbac.AuthorizeRole(c, team, in.Role); err != nil {
		return web.Empty{}, err
	}
	if err := rbac.AuthorizeRolesOf(c, team, u.AuthID()); err != nil {
		return web.Empty{}, err
	}
	if err := rbac.Sync(c, u.AuthID(), team, in.Role); err != nil {
		return web.Empty{}, err
	}
	return web.Empty{}, nil
}
```

(Copied from [`examples/teams`](https://github.com/anetos-dev/anetos/blob/main/examples/teams/main.go), region `set-member`.)

Give roles only in scopes that exist: a grant in team 7 before team 7
exists would apply to the team that later gets that ID. For the same
reason, when a team is deleted, `rbac.RemoveScope` takes every role in it
away (also when a cascade deletes it); when a user is, `rbac.RemoveUser`.

`rbac.AuthorizeRole` compares permissions, not names: a role with no
permissions is anyone's to give. Gate actions with permissions
(`rbac.Authorize`) rather than role names (`rbac.HasRole`).

### 7. Let administrators add roles

Roles declared in code change with the code. Administrators can add
their own, stored in the database and made of the declared permissions:

```go
// CreateRole adds a role made of the app's permissions: an "auditor" who
// may view every team's projects, say.
func (Handlers) CreateRole(c *web.Ctx, in NewRole) (rbac.Role, error) {
	role := rbac.Role{Name: in.Name, Title: in.Title, Permissions: in.Permissions}
	if err := rbac.CreateRole(c, role); err != nil {
		return rbac.Role{}, err // 422 for an unknown permission, 409 for a name taken
	}
	return role, nil
}
```

(Copied from [`examples/teams`](https://github.com/anetos-dev/anetos/blob/main/examples/teams/main.go), region `create-role`.)

`rbac.UpdateRole` changes one, `rbac.DeleteRole` deletes it and takes it
from everyone, and `rbac.Roles` lists them all, after the code's.

## How it works

A grant is a role or a permission of a user in a scope, a row of
`rbac_grants`. A user's grants are read in one query the first time a
request (or a job, or a tool call) checks them, and kept for the rest of
it; changes made with the package's functions are seen at once. A
request logged in with an API token may use only the permissions among
the token's abilities, so a token for reading can't delete, whatever
its user's roles. See [Roles and permissions](https://docs.anetos.dev/concepts/roles-and-permissions/index.md).

> **Coming from another framework?** This is the model of Django's
> groups and permissions, Laravel's spatie/laravel-permission, or
> Rails' Rolify with CanCanCan or Pundit: `rbac.Assign(ctx, id, rbac.Global, "writer")` gives a role,
> `rbac.Can(ctx, EditArticles)` checks a permission, `rbac.Require`
> guards routes, and teams are scopes. Permissions are constants in code
> rather than rows: a misspelled constant doesn't compile, and checking
> a permission that isn't declared is an error.

## Testing it

Give users roles in the test's database, then make requests as them.
`examples/teams` logs in with API tokens:

```go
// newUser creates a user with a role (none for "") and returns them with
// an API token having the abilities ("*" if none).
func newUser(t *testing.T, app *anetostest.App, name string, scope rbac.Scope, role string, abilities ...string) (*User, string) {
	t.Helper()
	u := &User{Name: name, Email: strings.ToLower(name) + "@example.com"}
	if err := db.Create(app.Context(), u); err != nil {
		t.Fatal(err)
	}
	if role != "" {
		if err := rbac.Assign(app.Context(), u.AuthID(), scope, role); err != nil {
			t.Fatal(err)
		}
	}
	if len(abilities) == 0 {
		abilities = []string{"*"}
	}
	a := anetos.MustResolve[*auth.Auth[*User]](app.App)
	token, _, err := a.CreateToken(app.Context(), u, "test", abilities, 0)
	if err != nil {
		t.Fatal(err)
	}
	return u, token
}

// as makes later requests with the token.
func as(app *anetostest.App, token string) *anetostest.App {
	return app.WithHeader("Authorization", "Bearer "+token)
}
```

(Copied from [`examples/teams/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/teams/main_test.go), region `test-helpers`.)

```go
func TestTeamRoles(t *testing.T) {
	app := anetostest.New(t, setup)
	acme, globex := newTeam(t, app, "Acme"), newTeam(t, app, "Globex")
	_, owner := newUser(t, app, "Bob", teamScope(acme.ID), "owner")
	_, guest := newUser(t, app, "Gus", teamScope(acme.ID), "guest")
	acmeProjects := fmt.Sprintf("/api/teams/%d/projects", acme.ID)

	as(app, owner).PostJSON(acmeProjects, NewProject{Name: "Rocket"}).AssertCreated()
	as(app, guest).GetJSON(acmeProjects).AssertOK().AssertJSONPath("0.name", "Rocket")
	as(app, guest).PostJSON(acmeProjects, NewProject{Name: "Anvil"}).AssertForbidden()
	// A role in Acme says nothing about Globex.
	as(app, owner).GetJSON(fmt.Sprintf("/api/teams/%d/projects", globex.ID)).AssertForbidden()
	app.WithHeader("Authorization", "").GetJSON(acmeProjects).AssertStatus(http.StatusUnauthorized)
}
```

(Copied from [`examples/teams/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/teams/main_test.go), region `test-roles`.)

A token's abilities narrow its user's permissions:

```go
func TestTokenAbilities(t *testing.T) {
	app := anetostest.New(t, setup)
	acme := newTeam(t, app, "Acme")
	// Bob owns Acme, but this token may only view projects.
	_, token := newUser(t, app, "Bob", teamScope(acme.ID), "owner", "projects.view")
	projects := fmt.Sprintf("/api/teams/%d/projects", acme.ID)

	as(app, token).GetJSON(projects).AssertOK()
	as(app, token).PostJSON(projects, NewProject{Name: "Rocket"}).AssertForbidden()
}
```

(Copied from [`examples/teams/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/teams/main_test.go), region `test-tokens`.)

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `rbac: permission "…" isn't declared` (500) | A check of a permission not passed to `rbac.New` | Add it to the permissions |
| `rbac: no permissions in the context` | `rbac.New` wasn't called, or the context isn't the app's | Call it in setup; use the request's or the job's context |
| Every check returns 401 | The route lacks the auth middleware | Put `a.Middleware` or `a.TokenMiddleware` before `rbac.Require` |
| A user's role allows nothing | The role is no longer declared, or was deleted | `rbac:roles` lists such roles; declare it again, or `rbac:unassign` it |
| An API client gets 403 though its user has the role | The token lacks the permission's ability | Create the token with the permission's name among its abilities, or `"*"` |
| A team's owner can't give a role | They don't have every permission it allows there (`AuthorizeRole`) | Give that role from an account that has them |
| A new team has members already | Roles were given in its scope before it existed, or a deleted team's weren't removed | Check that the team exists before giving roles; call `rbac.RemoveScope` when deleting it |

## Next steps

- [Authorization](https://docs.anetos.dev/guides/authorization/index.md): typed policies, for rules about
  the thing acted on ("authors edit their own posts")
- [Add an admin panel](https://docs.anetos.dev/guides/admin/index.md): pages for staff, with a permission per
  resource and action
- [Roles and permissions reference](https://docs.anetos.dev/reference/auth/index.md#roles-and-permissions)
- [API tokens](https://docs.anetos.dev/guides/authentication/index.md#8-give-api-clients-tokens)


# Rate limiting

Source: https://docs.anetos.dev/guides/rate-limiting/

Limit how often clients can call your routes, and how often they can
attempt actions such as logging in.

## Before you start

Rate limits count hits in the app's cache, so set it up with
`cache.New` (see [Cache](https://docs.anetos.dev/guides/cache/index.md)). With the memory store each
instance counts on its own; with several instances, use the database or
Redis store so a limit holds across all of them.

Behind a load balancer or reverse proxy, set `HTTP_TRUSTED_PROXIES` to
your proxies' networks, so the server's `RealIP` middleware finds the
client's address; otherwise every request seems to come from the proxy,
and all clients share one limit.

## Steps

### 1. Limit a group of routes

```go
// 120 requests a minute per client IP, counted in the app's cache.
r = r.Group("", ratelimit.Middleware("api", ratelimit.PerMinute(120)))
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `ratelimit`.)

The name (`"api"`) keeps these counts apart from other limits': give each
`Middleware` its own. A request over the limit gets `429 Too Many
Requests` through the app's error handler, with a `Retry-After` header in
seconds. Every limited response carries `X-RateLimit-Limit` and
`X-RateLimit-Remaining`.

Pass several limits to enforce them all. They are counted from the
shortest window to the longest, and a request over one isn't counted
against the longer ones, so a client retrying too fast doesn't use up its
daily quota:

```go
// illustrative
api := r.Group("/api", ratelimit.Middleware("api", ratelimit.PerMinute(60), ratelimit.PerDay(5000)))
```

The limits are `ratelimit.PerSecond`, `PerMinute`, `PerHour`, `PerDay`,
and `ratelimit.Per(n, window)` for any window.

### 2. Count per user or token

By default, hits are counted per client IP address (per `/64` network for
IPv6). Count per something else with `By`, such as the logged-in user:

```go
// illustrative
perUser := ratelimit.PerMinute(600).By(func(r *http.Request) string {
	return userID(r) // the user an authentication middleware found; "" if none
})
perGuest := ratelimit.PerMinute(60).By(func(r *http.Request) string {
	if userID(r) != "" {
		return "" // logged in: perUser applies
	}
	return ratelimit.IP(r)
})
api := r.Group("/api", auth, ratelimit.Middleware("api", perUser, perGuest))
```

Returning `""` leaves the request unlimited by that limit. Key only by
something the server has verified: a key the client chooses (a header, a
token that isn't checked yet) can change with every request, and gets it
a fresh count each time. Make sure every request has some limit, as the
per-IP limit for guests does above. Keys are stored as hashes, so they
may be secrets.

### 3. Limit an action in a handler

For attempts that aren't whole requests, such as logins, count them with
`ratelimit.Allow` and clear the count when the attempt succeeds:

```go
// illustrative
key := "login:" + strings.ToLower(in.Email) + "|" + ratelimit.IP(c.Request())
limit := ratelimit.PerMinute(5)
res, err := ratelimit.Allow(c, key, limit)
if err != nil {
	return nil, err
}
if !res.Allowed {
	return nil, web.Errorf(http.StatusTooManyRequests, "Too many attempts. Try again in %d seconds.", int(res.RetryAfter().Seconds())+1)
}
// … check the password; on success:
_ = ratelimit.Clear(c, key, limit)
```

To count only some attempts (failures), check first with
`ratelimit.Check`, which doesn't count, and count with `ratelimit.Hit`
when the attempt fails.

To limit an amount rather than a number of events (bytes uploaded,
a model's tokens), count it with `ratelimit.AllowN(ctx, key, n, limit)`:
`ratelimit.PerDay(100_000)` then allows 100,000 a day. AI budgets
(`ai.Budget`) work this way.

### 4. Test

Each `anetostest` app has its own cache, so tests don't share counts. To
see a limit trip, send more requests than it allows:

```go
// illustrative
for range 120 {
	app.GetJSON("/stats").AssertOK()
}
app.GetJSON("/stats").AssertStatus(http.StatusTooManyRequests)
```

A test can start a new window partway through; the example's
`TestRateLimit` sends up to two windows' worth of requests to allow for that.

## How it works

Each limit counts hits in fixed windows aligned to the clock: a
per-minute limit starts a new count at every minute. A client can
therefore make up to twice the limit around the end of a window, which is
the usual trade-off for one cache operation per request. A hit is one
atomic `cache.Increment` of a key made of a hash of the middleware's
name, the kind of key and the client's key (or of your `Allow` key),
the limit and the window; it expires after its window, plus up to a minute
for clocks that differ between instances. Hits over a limit count against
it too, and the window's end is the same for every client.

If the cache fails, the request fails with its error (a 500) rather than
go through unlimited.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| Every request fails with `ratelimit: cache: no cache in context` | `cache.New` wasn't called | Set up the cache in `setup` |
| All clients share one limit in production | The app sees the proxy's address | Set `HTTP_TRUSTED_PROXIES` to your proxies' networks |
| A limit allows more than expected with several instances | The memory store counts per instance | `CACHE_DRIVER=database` or `redis` |
| Two routes' limits share a count | Their `Middleware` calls have the same name | Give each its own name |

## Next steps

- [Cache](https://docs.anetos.dev/guides/cache/index.md)
- [Handlers and middleware](https://docs.anetos.dev/guides/handlers/index.md)


# Keep an audit log

Source: https://docs.anetos.dev/guides/audit-log/

Record who created, changed, deleted and restored the rows of your
models, field by field, with package `audit`: for data governance, for
support, and for "who changed this?".

## Before you start

- [Connect to a database](https://docs.anetos.dev/guides/database/index.md) and run your
  [migrations](https://docs.anetos.dev/guides/migrations/index.md) with `migrate.New`.
- To record *who*, set up [authentication](https://docs.anetos.dev/guides/authentication/index.md): changes
  are attributed to the logged-in user. Without it, they are attributed
  to the system.

The code here comes from [`examples/audit`](https://github.com/anetos-dev/anetos/tree/main/examples/audit), a
JSON API of documents.

## Steps

### 1. Add the log's tables

Add `audit.Migrations()` to your migration sets. It creates three tables:
`audit_log` (one entry per change of one row, or per event you record),
`audit_bulk` (one entry per write to many rows) and `audit_bulk_items`
(the key of every row a bulk write touched).

```go
// illustrative
sets := []*migrate.Set{Migrations, auth.Migrations(), audit.Migrations()}
if _, err := migrate.New(app, sets); err != nil {
	return nil, err
}
```

### 2. Track your models

Create the app's log after `db.Connect`, and name the models it tracks:

```go
trail, err := audit.New(app) // after db.Connect
if err != nil {
	return nil, err
}
if err := audit.Track[Document](trail, audit.Except("view_count")); err != nil {
	return nil, err
}
// Documents deleted more than 30 days ago go for good: db:prune-trashed.
if err := db.Prunable[Document](app, 30*24*time.Hour); err != nil {
	return nil, err
}
```

(Copied from [`examples/audit/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/audit/main.go), region `setup`.)

From now on, every `db.Create`, `db.Update`, `db.Save`, `db.Delete`,
`db.ForceDelete` and `db.Restore` of a `Document` writes an entry. The
model needs nothing special:

```go
// Document is what the log tracks. Deleting one soft-deletes it; its
// slug is unique among the documents that aren't deleted.
type Document struct {
	db.Model
	db.SoftDeletes
	OwnerID    int64  `db:"owner_id" json:"owner_id"`
	Slug       string `db:"slug" json:"slug"`
	Title      string `db:"title" json:"title"`
	Body       string `db:"body" json:"body"`
	Status     string `db:"status" json:"status"`    // draft, published, archived
	ShareToken string `db:"share_token" json:"-"`    // redacted in the log: its name says token
	Views      int    `db:"view_count" json:"views"` // left out of the log: audit.Except
}
```

(Copied from [`examples/audit/models.go`](https://github.com/anetos-dev/anetos/blob/main/examples/audit/models.go), region `model`.)

Choose what each model's entries keep with options of `Track`:

| Option | Effect |
|---|---|
| `audit.Except("view_count")` | The column is left out entirely: an update that changes only it isn't logged. Use it for counters and caches. |
| `audit.Redact("diagnosis")` | The log records that the column changed, as `"[redacted]"`, not its values. |
| `audit.Reveal("token_count")` | Columns whose names say they hold a secret (`password`, `secret`, `token`, `credential`, an API, private or session key, a recovery code, an OTP) are redacted by default; this shows one. |

### 3. Change rows as usual

Nothing changes in your handlers. An update records the fields that
changed, from what to what, and who changed them:

```go
// UpdateDocument changes a document. The log records the fields that
// changed, from what to what, and who changed them.
func (Handlers) UpdateDocument(c *web.Ctx, in DocumentChanges) (web.Responder, error) {
	d, err := db.Find[Document](c, in.ID)
	if err != nil {
		return nil, err
	}
	if in.Title != nil {
		d.Title = *in.Title
	}
	if in.Body != nil {
		d.Body = *in.Body
	}
	if in.Status != nil {
		d.Status = *in.Status
	}
	if err := db.Update(c, &d); err != nil {
		return nil, err
	}
	return web.JSON(http.StatusOK, d), nil
}
```

(Copied from [`examples/audit/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/audit/main.go), region `update`.)

The entry for that update holds:

```json
{
  "action": "updated",
  "actor_type": "user", "actor_id": "7",
  "subject_type": "documents", "subject_id": "42",
  "changes": {"old": {"title": "Plan"}, "new": {"title": "The plan"}},
  "via_kind": "request", "via_name": "PATCH /api/documents/42",
  "request_id": "b6f1…"
}
```

The actions are `created` (with the new values), `updated` (the changed
columns' old and new values; an update that changes nothing but
timestamps isn't logged), `deleted` (soft-deleted: the row is still
there), `restored`, and `force_deleted` (gone from the database, by
`ForceDelete` or by `Delete` on a model without soft deletes: the entry
keeps the values the row had).

### 4. Write many rows at once

A query's `Update`, `Delete`, `ForceDelete` or `Restore`, `CreateMany`
and `Upsert` write one **bulk entry** each, however many rows they touch:

```go
// Archive archives the user's published documents in one statement: one
// bulk entry in the log, with every document's key.
func (Handlers) Archive(c *web.Ctx) error {
	u, err := auth.Current[*User](c)
	if err != nil {
		return err
	}
	n, err := db.Query[Document](c).
		Where(colOwnerID.Eq(u.ID), colStatus.Eq("published")).
		Update(colStatus.Set("archived"))
	if err != nil {
		return err
	}
	return c.JSON(http.StatusOK, map[string]int64{"archived": n})
}
```

(Copied from [`examples/audit/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/audit/main.go), region `archive`.)

A bulk entry (`audit.BulkOp`) keeps the condition and its arguments, the
assignments, the number of rows, the values the rows had before (up to
`AUDIT_BULK_MAX_VALUES` rows, 10,000 by default, with a flag saying
whether it kept them all), and the key of **every** row in
`audit_bulk_items`. Deleting a thousand posts reads as one event, and
"who deleted post 42?" still has an answer.

If the condition names a column the log hides or redacts
(`Where(apiToken.Eq(t))`), its arguments are stored as `"[redacted]"`.
Values you write into the SQL itself (`WhereRaw("token = 'abc'")`) are
stored as written: pass them as arguments.

On a tracked model, `Upsert` needs a value in every conflict column: a
NULL, or a zero generated key, never conflicts, and the log couldn't find
the row again, so it is refused.

### 5. Show a row's history

`audit.History` returns a row's events, newest first: its own entries
and the bulk writes that touched it.

```go
// History returns what happened to a document, newest first: its own
// entries and the bulk writes that touched it.
func (Handlers) History(c *web.Ctx, in HistoryQuery) (web.Responder, error) {
	d, err := db.Query[Document](c).WithTrashed().Find(in.ID)
	if err != nil {
		return nil, err
	}
	subject, err := audit.SubjectOf(&d)
	if err != nil {
		return nil, err
	}
	events, next, err := audit.History(c, subject, 50, in.Cursor)
	if err != nil {
		return nil, err
	}
	out := make([]Event, len(events))
	for i, e := range events {
		out[i] = Event{At: e.At(), Actor: e.Actor().String(), Action: e.Action()}
		if e.Entry != nil {
			out[i].Via = e.Entry.ViaName
			out[i].Changes = &e.Entry.Changes
		} else {
			out[i].Via = e.Bulk.ViaName
			out[i].Rows = e.Bulk.RowCount
		}
	}
	return web.JSON(http.StatusOK, HistoryPage{out, next}), nil
}
```

(Copied from [`examples/audit/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/audit/main.go), region `history`.)

`History` also returns a cursor: pass it back for the next (older) page;
it is `""` after the last one. For anything else, query the tables like
any model: `db.Query[audit.Entry]`, `db.Query[audit.BulkOp]`.

> **Warning:** the log is as sensitive as the data it describes. Check
> permissions before showing it, as you would for the rows themselves.

### 6. Record your own events

Not everything worth recording is a write: an export, a download, a
failed permission check. `audit.Record` adds an entry with the same
actor and operation, and your details as JSON:

```go
// Export returns the user's documents, and records that they did: an
// event of the app's own, not a write.
func (Handlers) Export(c *web.Ctx) error {
	u, err := auth.Current[*User](c)
	if err != nil {
		return err
	}
	docs, err := db.Query[Document](c).Where(colOwnerID.Eq(u.ID)).Get()
	if err != nil {
		return err
	}
	err = audit.Record(c, "documents.exported", audit.Subject{Type: "users", ID: u.AuthID()},
		map[string]any{"documents": len(docs)})
	if err != nil {
		return err
	}
	return c.JSON(http.StatusOK, docs)
}
```

(Copied from [`examples/audit/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/audit/main.go), region `export`.)

Code that records events only in apps that keep a log, such as a
package of its own, checks `audit.Enabled(ctx)` first: `Record` fails
without one. `audit.Tracked(ctx, table)` says whether the log tracks a
table.

### 7. Name who acts when it isn't a user

Changes are attributed, in order, to:

1. the actor you set with `audit.WithActor`;
2. the logged-in user, or the one a job acts as (`auth.WithUser`); while
   someone impersonates a user (`auth.Impersonate`, the admin's
   "Impersonate"), that someone, with the user in the entry's `ActingAs`
   (`"user:42"`; jobs dispatched meanwhile carry that someone alone);
3. in a queue job or an async event listener, the actor of the work that
   started it: a job a user's request dispatched is attributed to that
   user (dispatching loads the logged-in user, once per request, to know
   who; if that fails, the job's tracked writes fail rather than guess);
4. otherwise `system` (commands, scheduled tasks).

A webhook's handler names its sender:

```go
// illustrative
ctx := audit.WithActor(c, audit.Actor{Type: "service", ID: "stripe"})
```

If the logged-in user can't be loaded (the database is down), the write
fails: the log doesn't guess who did it.

### 8. Keep entries for as long as you must, and no longer

- **Retention:** set `AUDIT_RETENTION_DAYS` and run `audit:prune` daily
  (or `audit.Prune` in a [scheduled task](https://docs.anetos.dev/guides/scheduling/index.md)). It deletes
  older entries in batches, and records that it did; with the default of
  0 it keeps everything.
- **Client IP addresses:** off by default. `AUDIT_IP=masked` keeps
  `203.0.113.0` for `203.0.113.77` (an IPv6 address to its /48);
  `AUDIT_IP=full` keeps it whole. An IP address is personal data under
  the GDPR, so decide, and say so in your privacy notice.
- **Erasure requests:** `audit:anonymize user 42` (or `audit.Anonymize`)
  replaces the user with `erased` in every entry, as the actor and as the
  user someone impersonated, and drops the IP addresses of the entries they
  made. Entries *about* the person's own rows keep their values:
  delete those with `db.Query[audit.Entry]` if the request covers them.

## How it works

`audit.Track` asks the `db` package to watch the model's table
(`DB.Watch`). Every write the `db` package makes to a watched table then
runs in a transaction (a savepoint, inside one you opened), and the log
writes its entry **in that transaction**, after the write:

- a committed change always has its entry, and a rolled-back one never
  does;
- an update first reads the row `FOR UPDATE`, so "before" is what the
  database held, not what your handler loaded earlier;
- a bulk write first selects the matching rows' keys `FOR UPDATE`, then
  writes in chunks of 1,000 keys and fails if a chunk changes fewer rows
  than it selected, so the entry lists exactly the rows written.

The cost falls only on tracked models: a transaction, one read and one
insert per single-row write; a read of the keys and one insert per
1,000 rows for a bulk write. A bulk update of only `Except`ed columns
isn't logged, but still pays for the read.

> **Warning:** the log sees what goes through the `db` package. Raw SQL
> (`db.Exec`), pivot writes (`db.Attach`, `db.Sync`) and the database's
> own `ON DELETE CASCADE` aren't recorded.

## Soft deletes that play well with the log

Two things help models with `db.SoftDeletes`:

**Unique among live rows.** A soft-deleted row keeps its values, so a
deleted user's email would block a new sign-up with a plain unique
index. `UniqueWithoutTrashed` makes the index ignore deleted rows, and the
`unique_without_trashed` validation rule checks the same:

```go
return s.Create("documents", func(t *migrate.Table) {
	t.ID()
	t.ForeignID("owner_id").References("users")
	t.String("slug", 100).UniqueWithoutTrashed() // PostgreSQL and SQLite
	t.String("title", 255)
	t.Text("body")
	t.String("status", 20).Default("draft")
	t.String("share_token", 64)
	t.Integer("view_count").Default(0)
	t.Timestamps()
	t.SoftDeletes()
})
```

(Copied from [`examples/audit/models.go`](https://github.com/anetos-dev/anetos/blob/main/examples/audit/models.go), region `migration`.)

```go
// illustrative
Slug string `json:"slug" validate:"required|unique_without_trashed:documents,slug"`
```

MySQL and MariaDB have no partial indexes, so `UniqueWithoutTrashed` fails there
with the reason; use `Unique`, or a generated column that is `NULL` for
deleted rows with a unique index on it.

**Pruning.** `db.Prunable[Document](app, 30*24*time.Hour)` (step 2)
registers the model; `db:prune-trashed` (or `db.PruneAllTrashed` in a
scheduled task) then deletes for good the rows deleted more than 30 days
ago, 1,000 per transaction. On a tracked model, each batch is a bulk
`force_deleted` entry, with the rows' values, by `system` when the
command or a scheduled task runs it.

## Testing it

Entries are written in your tests too, in the test's transaction. Check
them through the API or with `db.Query[audit.Entry]`:

```go
app := anetostest.New(t, setup)
ada, token := newUser(t, app, "Ada")
api := as(app, token)

var doc Document
api.PostJSON("/api/documents", NewDocument{Slug: "plan", Title: "Plan"}).AssertCreated().JSON(&doc)
path := fmt.Sprintf("/api/documents/%d", doc.ID)
api.PatchJSON(path, map[string]string{"title": "The plan", "status": "published"}).AssertOK()
api.GetJSON(path).AssertOK() // a view: not in the log
api.PostJSON("/api/documents/archive", nil).AssertOK().AssertJSONPath("archived", float64(1))
api.Delete(path).AssertNoContent()
api.PostJSON(path+"/restore", nil).AssertOK()

var page HistoryPage
api.GetJSON(path + "/history").AssertOK().JSON(&page)
events := page.Events
var actions []string
for _, e := range events {
	actions = append(actions, e.Action)
	if e.Actor != "user:"+ada.AuthID() {
		t.Errorf("%s by %s", e.Action, e.Actor)
	}
}
want := []string{audit.Restored, audit.Deleted, audit.Updated, audit.Updated, audit.Created}
if strings.Join(actions, " ") != strings.Join(want, " ") {
	t.Fatalf("history: %v, want %v", actions, want)
}
```

(Copied from [`examples/audit/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/audit/main_test.go), region `test-history`.)

Use `app.Travel` to test retention and pruning.

## Common problems

- **`audit: New needs the app's database`**: call `db.Connect` before
  `audit.New`.
- **`audit: … is tracked already`**: a table is tracked once per
  database; call `Track` once, at setup.
- **`audit: a key of N bytes is longer than the log keeps`**: entries
  keep keys of up to 255 bytes and actor IDs of up to 100.
- **`db: … is watched, so its model … needs a primary key`**: tracked
  models need one, to name the rows in entries.
- **No entry for an update**: only timestamps or `Except`ed columns
  changed, or the change was made with `db.Exec`.
- **`a watched bulk write changed N of the M rows it selected`**: the
  rows changed between the read and the write, which the lock should
  prevent; the write was rolled back. Retry it.
- **The log grows fast**: leave counters out with `Except`, and set
  `AUDIT_RETENTION_DAYS`.
- **A big bulk write fails on MySQL with `max_allowed_packet`**: its
  entry keeps the values of up to `AUDIT_BULK_MAX_VALUES` rows in one
  JSON value; lower the setting, or raise the server's limit.
- **A hook hangs once its model is tracked**: hooks now run inside the
  write's transaction, which holds the row's lock. A hook that writes
  outside it (`db.WithoutTx`) waits for that lock; on SQLite with one
  connection it waits forever. Do the work in the hook's context, or
  after the commit (`db.AfterCommit`).
- **`Upsert` fails on a `UniqueWithoutTrashed` index**: PostgreSQL and SQLite only
  take a partial index as the conflict target with its `WHERE`, which
  `Upsert` doesn't write. Use `Create` and `Update`, or a plain `Unique`
  index.

## Next steps

- [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md), to decide who may
  read the log.
- [Transactions](https://docs.anetos.dev/guides/transactions/index.md): entries join yours.
- [Scheduling](https://docs.anetos.dev/guides/scheduling/index.md), for `audit.Prune` and
  `db.PruneAllTrashed`.
- [Configuration reference](https://docs.anetos.dev/reference/configuration/index.md#audit-log):
  `AUDIT_*`.


# Add an admin panel

Source: https://docs.anetos.dev/guides/admin/

Give your staff pages to list, search, filter, create, edit and delete
the app's records, and to manage users and roles, with the admin
interface of module `anetos.dev/anetos/admin`: no front-end build,
permissions from [roles](https://docs.anetos.dev/guides/roles-and-permissions/index.md), and every change in
the [audit log](https://docs.anetos.dev/guides/audit-log/index.md) for the models it tracks.

## Before you start

- Users who log in with a session: [accounts with make:auth](https://docs.anetos.dev/guides/accounts/index.md)
  or [authentication](https://docs.anetos.dev/guides/authentication/index.md) of your own.
- [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md) (`rbac.New`):
  `make:admin` sets them up when the app doesn't.

The code here comes from [`examples/admin`](https://github.com/anetos-dev/anetos/tree/main/examples/admin), a
shop's back office.

## Steps

### 1. Add the admin

In a project made with `anetos new` and `anetos make:auth`:

```sh
go tool anetos make:admin
go run . migrate      # the roles tables
```

It adds the module to `go.mod` and writes `admin.go`, with `setupAdmin`,
which `setup` now calls after `setupAuth`: it sets up roles with an
`admin` role that may do everything, creates the admin for the app's
users, adds the users (`app/admin/users.go`), the roles and the resources
of `app/admin`, and mounts it at `/admin` with the middleware of the
app's pages. By hand, it looks like this:

```go
// setupAdmin adds the admin, after the routes of the app's pages, with
// their middleware.
func setupAdmin(app *anetos.App, r *web.Router, sessions *session.Manager, a *auth.Auth[*User]) error {
	p, err := admin.New(app, a, admin.WithDefaultTitle("Shop admin"))
	if err != nil {
		return err
	}
	if err := admin.Add(p, products()); err != nil {
		return err
	}
	if err := admin.Add(p, categories()); err != nil {
		return err
	}
	// The staff and the roles (roles.assign gives roles).
	if err := addUsers(p, a); err != nil {
		return err
	}
	if err := admin.Roles(p); err != nil {
		return err
	}
	// The dashboard, and who did what (the audit log).
	if err := admin.Activity(p); err != nil {
		return err
	}
	err = p.Dashboard(lowStock(), admin.SignUps[Product]("New products", "created_at"), admin.RecentActivity(8))
	if err != nil {
		return err
	}
	return p.Mount(r, sessions.Middleware, web.CSRF(), a.Middleware)
}
```

(Copied from [`examples/admin`](https://github.com/anetos-dev/anetos/blob/main/examples/admin/main.go), region `setup-admin`.)

Only logged-in users with the permission `admin.access` get in: guests
are sent to log in (`AUTH_LOGIN_URL`), others get 403. Let a user in
with the `admin` role:

```sh
go run . rbac:assign 1 admin
```

### 2. Add a resource per model

```sh
go tool anetos make:admin-resource Product
```

It writes `app/admin/products.go`, the resource for `models.Product`, from
the model's fields, and adds it to `app/admin/admin.go`. It's yours to
change. A resource's form is a struct of its own: only its fields can
be changed, its `validate` tags check them (see [validation](https://docs.anetos.dev/guides/validation/index.md)),
and `Apply` copies them into the record before it is saved:

```go
// ProductForm is what the admin edits of a product: only these fields
// can be changed, checked by their validate tags.
type ProductForm struct {
	Name       string  `json:"name" validate:"required|max:255"`
	SKU        string  `json:"sku" label:"SKU" validate:"required|max:50|alpha_dash"`
	CategoryID int64   `json:"category_id" label:"Category" admin:"select" validate:"required"`
	Price      float64 `json:"price" validate:"required|min:0" admin:"help=In dollars."`
	Stock      int     `json:"stock" validate:"min:0"`
	Status     string  `json:"status" admin:"select=draft|active|archived" validate:"required|in:draft,active,archived"`
}
```

(Copied from [`examples/admin/admin.go`](https://github.com/anetos-dev/anetos/blob/main/examples/admin/admin.go), region `form`.)

Fields are rendered by their Go type: text for strings, numbers, a
checkbox for bools, `admin.DateTime` for a date and time, `anetos.Date`
for a date. Each needs a `json` tag (or a `form` tag): the name it is
posted under. The `admin` tag changes that: `textarea`, `password`,
`select=a|b|c` (fixed choices) or `select` (choices from
`Resource.Choices`), `help=…`, and `-` to leave a field out; `label`
names it. A select's value must be one of its choices; a field left out
keeps the value `Edit` gave it, whatever a request sends.

The resource says what the list shows and how records are edited:

```go
// products is the admin's resource for products, at /admin/products.
func products() admin.Resource[Product, ProductForm] {
	return admin.Resource[Product, ProductForm]{
		Name: "products",
		Columns: []admin.Column[Product]{
			admin.TextColumn[Product]("name", "Name"),
			admin.TextColumn[Product]("sku", "SKU"),
			{Label: "Price", Column: "price", Sortable: true, Value: func(p Product) any { return dollars(p.Price) }},
			admin.TextColumn[Product]("stock", "Stock"),
			admin.TextColumn[Product]("status", "Status"),
		},
		Search:      []string{"name", "sku"},
		Filters:     []admin.Filter[Product]{admin.Equals[Product]("status", "Status", admin.Choices("draft", "active", "archived")...)},
		RecordTitle: func(p Product) string { return p.Name },
		Edit: func(p Product) ProductForm {
			return ProductForm{Name: p.Name, SKU: p.SKU, CategoryID: p.CategoryID,
				Price: float64(p.Price) / 100, Stock: p.Stock, Status: p.Status}
		},
		Apply: func(ctx context.Context, in ProductForm, p *Product) error {
			// Checks that need the database are done here.
			taken, err := db.Query[Product](ctx).WithTrashed().
				Where(db.C("sku").Eq(in.SKU), db.C("id").Ne(p.ID)).Exists()
			if err != nil {
				return err
			}
			if taken {
				return validate.Fail("sku", "Another product has this SKU.")
			}
			p.Name, p.SKU, p.CategoryID = in.Name, in.SKU, in.CategoryID
			p.Price, p.Stock, p.Status = int64(in.Price*100+0.5), in.Stock, in.Status
			return nil
		},
		// The categories to choose from, from the database.
		Choices: map[string]func(ctx context.Context) ([]admin.Choice, error){
			"category_id": categoryChoices,
		},
		Actions: []admin.Action[Product]{{
			Name: "archive", Label: "Archive", Confirm: "Archive this product?",
			When: func(p Product) bool { return p.Status != "archived" },
			Run: func(ctx context.Context, p *Product) error {
				p.Status = "archived"
				return db.Update(ctx, p)
			},
		}},
		BulkActions: []admin.BulkAction[Product]{{
			Name: "activate", Label: "Activate",
			Run: func(_ context.Context, q *db.Q[Product]) (int64, error) {
				return q.Update(db.C("status").Set("active"))
			},
		}},
	}
}
```

(Copied from [`examples/admin/admin.go`](https://github.com/anetos-dev/anetos/blob/main/examples/admin/admin.go), region `products`.)

- `Columns` are the list's; `admin.TextColumn(column, label)` shows a
  column of the model, sortable. A column with
  `Value` shows what the function returns: text,
  a number, a time (in `APP_TIMEZONE`), or a `view.Component` or
  `template.HTML` for markup. `Details` are the lines of a record's page,
  `Columns` by default.
- `Search` are the text columns the search box looks in (`LIKE`,
  ignoring case; on SQLite, only for ASCII letters); `Filters` narrow the list (`admin.Equals` for a column's value);
  `Sort` is the default order (newest first otherwise).
- `Query` scopes everything the admin sees and changes of the model:
  `func(q *db.Q[Order]) *db.Q[Order] { return q.Where(…) }`. A record that
  `Apply` would put outside it isn't saved.
- `Edit` and `Apply` make records editable; without them, the resource is
  only listed and shown. `NoCreate` and `NoDelete` hide creating and
  deleting.
- `Actions` are buttons on a record's page; `BulkActions` act on the
  records selected in the list (always within `Query`). `Run` may return
  `validate.Fail`, which is shown to the user.

Models with `db.SoftDeletes` get a trash: deleting moves records there,
where they can be restored or deleted for good.

### 3. Give staff roles

Each resource has four permissions, `admin.<name>.view`, `.create`,
`.update` and `.delete`, which `admin.New` and `admin.Add` declare, so
roles stored in the database can grant them. Roles declared in code
name them with `admin.PermissionsOf`, among the app's permissions:

```go
// editor are the permissions of editors: they manage products, and may
// only look at categories. The admin declares its permissions too
// (admin.New, admin.Add); roles in code name them in the app's list.
var editor = slices.Concat(
	[]rbac.Permission{admin.Access},
	admin.PermissionsOf("products"),
	admin.PermissionsOf("categories", "view"),
)

// support are the permissions of support staff: they look after the
// staff's accounts, and may impersonate them to see what they see.
var support = slices.Concat(
	[]rbac.Permission{admin.Access, "admin.users.impersonate"},
	admin.PermissionsOf("users", "view", "update"),
)

// roles are the staff's roles: administrators may do everything.
var roles = []rbac.Role{
	{Name: "admin", Title: "Administrator", Super: true},
	{Name: "editor", Title: "Editor", Permissions: editor},
	{Name: "support", Title: "Support", Permissions: support},
}

// permissions are those of the roles, each once.
var permissions = slices.Compact(slices.Sorted(slices.Values(slices.Concat(editor, support))))
```

(Copied from [`examples/admin`](https://github.com/anetos-dev/anetos/blob/main/examples/admin/main.go), region `roles`.)

Users see only the resources they may view, and only the buttons of
what they may do; the routes check the permissions too. An action needs
`update` unless its `Permission` names another one: `"view"`,
`"create"`, `"delete"`, or a permission of the app's own (with a dot).

### 4. Manage users

`make:admin` writes `app/admin/users.go`, which adds the app's users with
`admin.Users`: a resource as any other (its columns, search and form),
and account management on each user's page. By hand:

```go
// UserForm is what the admin edits of a member of staff.
type UserForm struct {
	Name  string `json:"name" validate:"required|max:255"`
	Email string `json:"email" validate:"required|email|max:255"`
}

// addUsers adds the staff to the admin, with their accounts: disabling,
// logging out, API tokens, roles, impersonating them.
func addUsers(p *admin.Panel, a *auth.Auth[*User]) error {
	return admin.Users(p, admin.Resource[User, UserForm]{
		Name:        "users",
		PluralLabel: "Staff",
		Label:       "Member",
		Columns: []admin.Column[User]{
			admin.TextColumn[User]("name", "Name"),
			admin.TextColumn[User]("email", "Email"),
		},
		Search:      []string{"name", "email"},
		RecordTitle: func(u User) string { return u.Name },
		NoCreate:    true, // seed creates them; this shop has no sign-up
		Edit:        func(u User) UserForm { return UserForm{Name: u.Name, Email: u.Email} },
		Apply: func(_ context.Context, in UserForm, u *User) error {
			u.Name, u.Email = in.Name, strings.ToLower(in.Email)
			return nil
		},
	}, admin.Accounts[*User]{Auth: a, DisabledAt: "disabled_at"})
}
```

(Copied from [`examples/admin/admin.go`](https://github.com/anetos-dev/anetos/blob/main/examples/admin/admin.go), region `users-resource`.)

On a user's page, as the `Accounts` allow:

- **Disable and enable.** Package `auth` refuses disabled users (its
  `Users.Disabled`): they are logged out at their next request, can't
  log in, and their API tokens stop working.
- **Verification:** mark the address verified, or email the link again;
  email a password-reset link (`SendVerification`, `SendPasswordReset`,
  which `make:auth` exports from `app/handlers`).
- **Log out everywhere:** every browser and device, at once. It replaces
  the user's session key (`Users.SessionKey`, `SetSessionKey`).
- **API tokens:** listed (name, abilities, last use), revoked one by one
  or all at once.
- **Roles and permissions,** by scope: given and taken away, by those
  with `admin.roles.assign`, and only roles they could hold themselves.
- **Impersonate,** below.

Disabling and logging out everywhere need two columns of the users table,
which `make:auth` makes, and the `auth.Users` that read them:

```go
// users tells package auth how to find users, which are disabled, and
// how to log them out everywhere.
var users = auth.Users[*User]{
	ByID: func(ctx context.Context, id string) (*User, error) {
		n, err := strconv.ParseInt(id, 10, 64)
		if err != nil {
			return nil, auth.ErrUserNotFound
		}
		return found(db.Find[User](ctx, n))
	},
	ByLogin: func(ctx context.Context, email string) (*User, error) {
		return found(db.Query[User](ctx).Where(db.C("email").Eq(strings.ToLower(email))).First())
	},
	Disabled:   func(u *User) bool { return u.DisabledAt != nil },
	SessionKey: func(u *User) string { return u.SessionKey },
	SetSessionKey: func(ctx context.Context, u *User, key string) error {
		_, err := db.Query[User](ctx).WhereKeys(u.ID).Update(db.C("session_key").Set(key))
		return err
	},
}
```

(Copied from [`examples/admin/models.go`](https://github.com/anetos-dev/anetos/blob/main/examples/admin/models.go), region `users`.)

An app made with an older `make:auth` adds `disabled_at` (a nullable
timestamp) and `session_key` (a string) with a migration, the fields to
`User`, and those three functions to `models.Users`.

Changing a user needs every permission they have, in every scope: support
staff can't edit, disable or impersonate an administrator. No one disables,
deletes, impersonates or changes the roles of themselves here. Each of these
is recorded in the [audit log](https://docs.anetos.dev/guides/audit-log/index.md) (`user.disabled`,
`rbac.role_assigned`, …), when the app keeps one.

### 5. Manage roles

`admin.Roles(p)` adds the roles pages: every role, with its permissions
and who has it. Roles declared in code are shown; roles stored in the
database are created, edited and deleted here, from the permissions the
admin has (no one makes a role with more than they have). Permissions:
`admin.roles.view`, `.create`, `.update` and `.delete`.

### 6. Impersonate a user

To see what a user sees, an admin with `admin.users.impersonate` presses
**Impersonate**: they are logged in as the user, and the app's pages show
a banner with a button that stops it. `make:admin` puts the banner in
`views/layout.templ`; in your own layout, put it first in `<body>`:

```templ
// illustrative
<body>
	@admin.Banner()
```

While it lasts, the audit log attributes what is done to the admin,
impersonating the user (`ActingAs`); jobs it dispatches are attributed to the
admin alone. Its start and its stop are logged (`user.impersonated`,
`user.impersonation_ended`); logging out ends it too, unlogged. The admin
can't impersonate disabled users, those with permissions they lack, or
anyone while already impersonating someone. Each request checks that the
admin may still log in (not that they still have
`admin.users.impersonate`: taking it away ends nothing under way). The
admin's remember-me cookie goes when it starts. An admin at a host of
its own (`ADMIN_HOST`) doesn't offer it: the app's pages are on another
host, with another session.

### 7. Put widgets on the dashboard

The admin's first page shows widgets above the resources:
`p.Dashboard(widgets...)`, before `Mount`. A widget loads its content
when the page is shown: figures, a bar chart (drawn as SVG), a table
whose rows link to the admin's pages, any `view.Component`, and a link.
A widget that fails (or panics) says so in its place, the error is
logged, and the rest of the page works. A widget's `Permission` must be
declared, as a resource's are; the built-in ones' are declared for you.

```go
// lowStock is a dashboard widget: the active products running out.
func lowStock() admin.Widget {
	return admin.Widget{Title: "Low stock", Permission: "admin.products.view", Load: func(ctx context.Context) (admin.Content, error) {
		low, err := db.Query[Product](ctx).Where(db.C("status").Eq("active"), db.C("stock").Lt(5)).
			OrderBy(db.C("stock").Asc()).Limit(10).Get()
		if err != nil {
			return admin.Content{}, err
		}
		t := &admin.Table{Headers: []string{"Product", "In stock"}}
		for _, p := range low {
			t.Rows = append(t.Rows, []string{p.Name, strconv.Itoa(p.Stock)})
			t.Links = append(t.Links, fmt.Sprintf("products/%d", p.ID)) // the admin's page
		}
		return admin.Content{
			Stats: []admin.Stat{{Label: "Running out", Value: strconv.Itoa(len(low)), Warn: len(low) > 0}},
			Table: t,
			Link:  &admin.Link{Label: "Every active product", URL: "products?status=active&sort=stock"},
		}, nil
	}}
}
```

(Copied from [`examples/admin/admin.go`](https://github.com/anetos-dev/anetos/blob/main/examples/admin/admin.go), region `widget`.)

Links and table rows without a leading `/` lead to the admin's own pages
(`products/7`), and are left out if there is no such page. Built in:

| Widget | Shows | Permission |
|---|---|---|
| `admin.SignUps[T](title, column)` | Model `T`'s records: in all, new in 7 and 30 days, and a bar a day for 30 days (UTC), by `column` (`"created_at"`) | `admin.access` |
| `admin.QueueHealth(q, queues...)` | The jobs waiting on the default queue and on `queues`, and the failed ones | `admin.jobs.view` |
| `admin.AIUsage()` | Tokens and cost of the app's AI calls in 24 hours and 30 days, and tokens a day (recorded by the AI client's `TrackUsage`) | `admin.access` |
| `admin.RecentActivity(n)` | The audit log's latest `n` entries | `admin.activity.view` |

### 8. See who did what

`admin.Activity(p)` adds the activity pages, over the app's
[audit log](https://docs.anetos.dev/guides/audit-log/index.md): its entries and bulk writes, newest first,
filtered by who (`user:42`), what (`updated`), which kind of record
(`posts`) and which one, and when. An entry's page shows its changes,
field by field. The pages of a resource whose model the log tracks show
a record's latest history. Permission: `admin.activity.view`: it shows
what the log keeps, changed values included (fields the log leaves out,
such as passwords, aren't there), so give it to those who may see them.

`make:admin` adds `admin.Activity` and the `RecentActivity` widget to
`admin.go` when the app keeps an audit log. If you add the log later, add
them to `setupAdmin` yourself, before `p.Dashboard`:

```go
// illustrative
widgets = append(widgets, admin.RecentActivity(10))
if err := admin.Activity(p); err != nil {
	return err
}
```

### 9. Watch jobs and scheduled tasks

`admin.Jobs(p, q)` adds the jobs page: the queues' sizes, and the failed
jobs with their error and payload, to retry or forget one by one or all
at once (`admin.jobs.view`, `.update`). `admin.Schedule(p, s)` adds the
scheduled tasks: each one's schedule, next run and last run (kept in the
cache; see [Scheduling](https://docs.anetos.dev/guides/scheduling/index.md#4-check-and-run-tasks)), and
**Run now**, which runs the task in the background, as the scheduler
does (`admin.schedule.view`, `.run`): a task running from this process
isn't started again until it ends, and the app's shutdown waits for it
until its deadline. Retrying, forgetting and running are recorded in the
audit log. A failed job's page shows its payload, so `admin.jobs.view`
is for those who may see what jobs carry.

`make:admin` adds these when the app has them: the queue and the
scheduler of `anetos new`, and the activity when the app keeps an audit
log.

### 10. Protect it

The admin asks for the password again before dangerous actions:
deleting, disabling, giving and taking roles and permissions, editing
roles, impersonating a user, forgetting every failed job, and actions marked
`Danger`. After it, the user does the action again; the password holds
for `AUTH_CONFIRM_TTL` (15 minutes). Users who log in without a
password (Google, GitHub) confirm by logging out and in again; set
`ADMIN_CONFIRM=false` to not ask at all.

```env
ADMIN_TWO_FACTOR=required          # only users with two-factor authentication on
ADMIN_ALLOW_IPS=10.0.0.0/8,203.0.113.7   # only these addresses; others get 404
```

With `ADMIN_TWO_FACTOR=required`, users without
[two-factor authentication](https://docs.anetos.dev/guides/two-factor/index.md) are told to turn it on, at
`AUTH_TWO_FACTOR_URL` (`make:auth`'s page). With `ADMIN_ALLOW_IPS`, the
client's address is read behind trusted proxies only
(`HTTP_TRUSTED_PROXIES`). A user's page shows whether they have
two-factor authentication on, and **Turn off two-factor authentication** helps someone
who lost their phone (not oneself).

The user's name, at the top of every page, links to their account
settings in the app (`AUTH_SETTINGS_URL`, [`make:auth`](https://docs.anetos.dev/guides/accounts/index.md)'s
`/settings`), when the app has that page: their password, two-factor
authentication, language and time zone.

## How it works

The admin is a library, not a plugin: its pages need the app's own types
(the user type, the models), which code in the app can name. Its pages
are `html/template`, embedded in the module, with htmx and a stylesheet
of their own, so there is nothing to build; they are served with a
strict Content-Security-Policy, kept out of frames and caches. Forms are
bound and validated as [forms](https://docs.anetos.dev/guides/forms/index.md) are: a failed post goes back to
the form with the errors and what was typed. Writes go through package
`db`, so models tracked by the [audit log](https://docs.anetos.dev/guides/audit-log/index.md) record who did
what. Routes are named `admin.*` (`admin.products.edit`).

To serve the admin on a host of its own, set `ADMIN_HOST`
(`admin.example.com`): it answers only there, at the root unless
`ADMIN_PATH` is set. Settings: [`ADMIN_*`](https://docs.anetos.dev/reference/configuration/index.md#admin).

## Testing it

Log in as the app's tests do, then use the admin's pages:

```go
func TestEditorManagesProducts(t *testing.T) {
	app := login(t, "editor@example.com")
	books, err := db.Query[Category](app.Context()).Where(db.C("name").Eq("Books")).First()
	if err != nil {
		t.Fatal(err)
	}
	app.Get("/admin").AssertOK().AssertSee("Shop admin", "Eve", "Products", "Categories")
	app.Get("/admin/products/new").AssertOK().AssertSee(`<option value="` + strconv.FormatInt(books.ID, 10) + `"`)

	form := url.Values{"name": {"Go in Action"}, "sku": {"go-1"}, "category_id": {strconv.FormatInt(books.ID, 10)},
		"price": {"39.99"}, "stock": {"12"}, "status": {"draft"}}
	app.PostForm("/admin/products", form).Follow().AssertSee("Product created.", "$39.99")
	p, err := db.Query[Product](app.Context()).Where(db.C("sku").Eq("go-1")).First()
	if err != nil || p.Price != 3999 || p.CategoryID != books.ID {
		t.Fatalf("created %+v, %v", p, err)
	}
	app.Get("/admin/products/new")
	app.PostForm("/admin/products", form).AssertValidationErrors("sku") // taken

	path := fmt.Sprintf("/admin/products/%d", p.ID)
	form.Set("price", "35")
	app.PostForm(path, form).Follow().AssertSee("Saved.", "$35.00")
	app.PostForm(path+"/actions/archive", nil).Follow().AssertSee("Archive: done.", "archived")
	app.Get("/admin/products?status=archived&q=GO").AssertSee("Go in Action")
	// Deleting asks for the password again first (ADMIN_CONFIRM).
	app.PostForm(path+"/delete", nil).AssertRedirect("/admin/confirm?back=" + url.QueryEscape("/admin/products?status=archived&q=GO"))
	app.PostForm("/admin/confirm", url.Values{"password": {"secret password"}, "back": {path}}).AssertRedirect(path)
	app.PostForm(path+"/delete", nil).Follow().AssertSee("Go in Action moved to the trash.")

	// Every change is in the audit log, by Eve.
	events, _, err := audit.History(app.Context(), audit.Subject{Type: "products", ID: strconv.FormatInt(p.ID, 10)}, 10, "")
	if err != nil {
		t.Fatal(err)
	}
	var actions []string
	for _, e := range events {
		if e.Entry != nil {
			actions = append(actions, e.Entry.Action)
		}
	}
	if fmt.Sprint(actions) != "[deleted updated updated created]" {
		t.Errorf("history %v", actions)
	}

	// Categories: editors may look, not change.
	app.Get("/admin/categories").AssertOK().AssertSee("Books", "Games").AssertDontSee(`href="/admin/categories/new"`)
	app.PostForm("/admin/categories", url.Values{"name": {"Music"}}).AssertForbidden()
}
```

(Copied from [`examples/admin/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/admin/main_test.go), region `test-products`.)

And the accounts:

```go
func TestStaffAccounts(t *testing.T) {
	app := login(t, "admin@example.com")
	eve, err := db.Query[User](app.Context()).Where(db.C("email").Eq("editor@example.com")).First()
	if err != nil {
		t.Fatal(err)
	}
	page := fmt.Sprintf("/admin/users/%d", eve.ID)

	// Impersonating Eve: the app as she sees it, with the banner, once Ada
	// confirmed her password.
	app.PostForm("/admin/confirm", url.Values{"password": {"secret password"}}).AssertRedirect("/admin")
	app.PostForm(page+"/actions/impersonate", nil).AssertRedirect("/")
	app.Get("/").AssertSee("Hello, Eve", "impersonating <strong>Eve</strong>")
	app.PostForm("/admin/impersonation/stop", nil).AssertRedirect(page)
	app.Get("/").AssertSee("Hello, Ada").AssertDontSee("impersonating")

	// Disabled, Eve can't log in. Back as herself, Ada confirms her
	// password again.
	app.PostForm("/admin/confirm", url.Values{"password": {"secret password"}})
	app.PostForm(page+"/actions/disable", nil).Follow().AssertSee("Account disabled.")
	app.PostForm("/logout", nil)
	app.Get("/login")
	app.PostForm("/login", url.Values{"email": {"editor@example.com"}, "password": {"secret password"}}).AssertValidationErrors("email")

	// Support staff look after accounts, but not those with permissions
	// they don't have, such as Eve's.
	app.PostForm("/login", url.Values{"email": {"support@example.com"}, "password": {"secret password"}}).AssertRedirect("/admin")
	app.PostForm(page+"/actions/enable", nil).Follow().AssertSee("You may not manage Eve")
}
```

(Copied from [`examples/admin/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/admin/main_test.go), region `test-users`.)

`make:admin` writes `admin_test.go`, which checks who gets in.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `admin: New needs the app's roles and permissions` | `rbac.New` wasn't called before `admin.New` | Set up roles first (`make:admin` does) |
| `rbac: unknown permission "admin.posts.view", in role "editor"` | A role in code names an admin permission the app's list lacks | Add `admin.PermissionsOf("posts")` to the permissions passed to `rbac.New` |
| 403 on every admin page | The user lacks `admin.access` | `go run . rbac:assign <user-id> admin`, or a role with `admin.Access` |
| A resource isn't in the menu | The user lacks its `view` permission | Give `admin.<name>.view` |
| `admin: Users: auth.Users.Disabled doesn't report users whose disabled_at is set` | `Accounts.DisabledAt` names a column `auth` doesn't read | Add `Disabled` to the app's `auth.Users` |
| "You may not manage X: they have permissions you don't." | X has a permission the admin lacks somewhere | Have someone with more permissions do it |
| No "Disable" or "Log out everywhere" on a user's page | The users table or `auth.Users` lack `disabled_at` or the session key | Add them (step 4) |
| `admin: resource posts: column "titel" is not a column of posts` | A column, search, or sort names a column the model doesn't have | Use the database's column name |
| `form field X: a … can't be edited in a form` | The form struct has a field of a type forms don't render | Use a string, number, bool, `admin.DateTime` or `anetos.Date`, or tag it `admin:"-"` |

## Next steps

- [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md)
- [Accounts with make:auth](https://docs.anetos.dev/guides/accounts/index.md)
- [Keep an audit log](https://docs.anetos.dev/guides/audit-log/index.md): who changed what in the admin
- [CLI reference](https://docs.anetos.dev/reference/cli/index.md#anetos-make): `make:admin` and
  `make:admin-resource`


# Background work

Source: https://docs.anetos.dev/guides/background-work/

- [Queues](https://docs.anetos.dev/guides/queues/index.md): Run slow or failure-prone work in the background: charge a card, send an email, build a report. A request dispatches a **job**, a typed struct, and responds at once. **Workers** run the job later, retry it when it fails, and keep a record of the jobs that failed for good. The complete app is [`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue).
- [Events](https://docs.anetos.dev/guides/events/index.md): Emit an event when something happens, and let listeners react: write an audit log, email a receipt, update a dashboard. The code that places an order then doesn't need to know about all of them. Events are typed Go values, and listeners are functions of their type. The complete app is [`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue).
- [Scheduling](https://docs.anetos.dev/guides/scheduling/index.md): Run tasks on a schedule: prune old rows every night, send a report every hour, sync with another service every five minutes. The scheduler runs in your app's binary, as a supervised component, so there is no crontab to install and nothing to run every minute. The complete app is [`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue).
- [Run background tasks](https://docs.anetos.dev/guides/background-tasks/index.md): Run long-lived work, such as a poller, a cache warmer or a heartbeat, as a supervised goroutine that restarts on failure and stops cleanly on deploy.
- [Pub/sub listeners](https://docs.anetos.dev/guides/pubsub/index.md): Listen to message streams other services publish, such as `orders.created`, and publish your own, from the same binary as your web app. Where the [queue](https://docs.anetos.dev/guides/queues/index.md) runs an app's own jobs, pub/sub connects services: each subscription gets every message of a topic. The complete app is [`examples/pubsub`](https://github.com/anetos-dev/anetos/tree/main/examples/pubsub), a billing service.


# Queues

Source: https://docs.anetos.dev/guides/queues/

Run slow or failure-prone work in the background: charge a card, send an
email, build a report. A request dispatches a **job**, a typed struct, and
responds at once. **Workers** run the job later, retry it when it fails,
and keep a record of the jobs that failed for good. The complete app is
[`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue).

## Before you start

Choose where jobs are kept with `QUEUE_DRIVER`:

| Driver | Jobs are kept | Use it for |
|---|---|---|
| `sync` (default) | Nowhere: each job runs when it is dispatched, and `Dispatch` returns its error | Development and tests |
| `memory` | In the process: lost when it stops | Development and tests with workers |
| `database` | In the app's database, tables `jobs` and `failed_jobs` | Production without another server |
| `redis` | In Redis 5 or later (`drivers/redis`, `REDIS_URL`) | Production with many jobs |

The database driver needs PostgreSQL, MySQL 8.0, MariaDB 10.6 or later, or
SQLite. Create its tables with the `queue.Migrations("", "")` migration
(new projects have it).

## Steps

### 1. Write a job

A job is a struct with a `Handle` method:

```go
// ChargeOrder charges an order. Its fields are what the worker gets: the
// order's ID, not the order.
type ChargeOrder struct {
	OrderID int64 `json:"order_id"`
}

// Handle charges the order. A job may run more than once, so it is
// idempotent: the job's ID is the gateway's idempotency key, and a paid
// order isn't charged again.
func (j ChargeOrder) Handle(ctx context.Context) error {
	o, err := db.Find[Order](ctx, j.OrderID)
	if errors.Is(err, db.ErrNotFound) {
		return queue.Permanent(err) // retrying won't make it appear
	}
	if err != nil {
		return err
	}
	if o.Status != "pending" {
		return nil
	}
	job, _ := queue.Current(ctx)
	switch err := gateway(ctx).Charge(ctx, job.ID, o.Cents); {
	case errors.Is(err, ErrDeclined):
		return queue.Permanent(err) // fail now: Failed marks the order
	case err != nil:
		return fmt.Errorf("charge order %d: %w", o.ID, err) // retried later
	}
	return setStatus(ctx, o.ID, "paid")
}

// Failed runs when the job fails for good: declined, or out of tries.
func (j ChargeOrder) Failed(ctx context.Context, err error) {
	anetos.Logger(ctx).InfoContext(ctx, "order not charged", "order", j.OrderID, "error", err)
	if err := setStatus(ctx, j.OrderID, "failed"); err != nil {
		anetos.Logger(ctx).ErrorContext(ctx, "mark the order failed", "order", j.OrderID, "error", err)
	}
}
```

(Copied from [`examples/queue/orders.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/orders.go), region `job`.)

The rules:

- **Fields are stored as JSON** when the job is dispatched. Keep them
  small: IDs, not records, which may have changed by the time the job
  runs.
- **`ctx` has what the app provides**: the database, the cache, the queue,
  and values you add with `app.AddContextValue` (the example's payment
  gateway). It also has the job's `queue.Info` (`queue.Current(ctx)`:
  its ID, attempt and tries) and its timeout.
- **Return an error to retry** the job later. Wrap it with
  `queue.Permanent` to fail the job at once, for errors that retrying
  won't fix.
- **A `Failed` method**, if the job has one, runs once when the job fails
  for good.

> **Warning:** A job can run more than once: delivery is
> **at-least-once**. A worker can die after the work but before it records
> it, and a job still running when its lease ends (the longest timeout of
> the job types, plus 30 seconds) can be picked up again. Make
> jobs idempotent: check whether the work is done, and give outside
> services an idempotency key (`queue.Current(ctx).ID` is the same for
> every attempt).

### 2. Set up the queue and its workers

In `setup`, after `db.Connect`, set up the queue, register each job
type, and add the workers:

```go
q, err := queue.New(app, redis.QueueDriver()) // QUEUE_DRIVER: sync, memory, database or redis
if err != nil {
	return nil, err
}
if err := queue.Register[ChargeOrder](q, queue.Tries(5), queue.Timeout(30*time.Second)); err != nil {
	return nil, err
}
// Workers for the payments queue first, then the default one.
if err := q.Work(queue.Queues("payments", "default"), queue.Concurrency(4)); err != nil {
	return nil, err
}
```

(Copied from [`examples/queue`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main.go), region `setup`.)

`queue.New` reads the `QUEUE_*` settings (see the
[configuration reference](https://docs.anetos.dev/reference/configuration/index.md#queue)). Pass
`redis.QueueDriver()` only if you use Redis; the other drivers are built
in.

`queue.Register` options set a job type's behavior:

| Option | Default | |
|---|---|---|
| `queue.Tries(n)` | `QUEUE_TRIES` (3) | Attempts before the job fails for good; 1 for no retries |
| `queue.Timeout(d)` | `QUEUE_TIMEOUT` (1m) | How long an attempt may run before its context is canceled |
| `queue.Backoff(d1, d2, …)` | `QUEUE_BACKOFF` (10s), doubling up to `QUEUE_BACKOFF_MAX` (10m) | Waits before the retries; the last repeats. Each varies by up to 20% |
| `queue.Name(s)` | The Go type, `main.ChargeOrder` | The name jobs are stored under: set it before renaming or moving the type |

`q.Work` adds the workers to the app, of the process type `worker`:

| Option | Default | |
|---|---|---|
| `queue.Queues(names…)` | `QUEUE_DEFAULT` (`default`) | The queues to take jobs from, highest priority first |
| `queue.Concurrency(n)` | 1 | Jobs that run at once |
| `queue.ShutdownGrace(d)` | Half of `APP_SHUTDOWN_TIMEOUT` | How long running jobs may finish at shutdown |

`go run .` (the `run` command) runs the workers with the HTTP server. In
production, you can run them apart, from the same binary:

```bash
./app serve                # web servers (run --only=web)
./app queue:work           # workers, as many as you need (run --only=worker)
```

### 3. Dispatch jobs

Call `queue.Dispatch` with a request's context (or a job's):

```go
// PlaceOrder saves the order and dispatches the job that charges it.
func PlaceOrder(c *web.Ctx, in OrderInput) (web.Responder, error) {
	o := &Order{Item: in.Item, Cents: in.Cents, Email: in.Email, Status: "pending"}
	err := db.Tx(c, func(ctx context.Context) error {
		if err := db.Create(ctx, o); err != nil {
			return err
		}
		if err := events.Emit(ctx, OrderPlaced{OrderID: o.ID, Item: o.Item, Cents: o.Cents, Email: o.Email}); err != nil {
			return err // an On listener failed: no order
		}
		// AfterCommit: no charge for an order that isn't saved. (The
		// database driver writes the job in the transaction instead.)
		return queue.Dispatch(ctx, ChargeOrder{OrderID: o.ID}, queue.OnQueue("payments"), queue.AfterCommit())
	})
	if err != nil {
		return nil, err
	}
	return web.JSON(http.StatusAccepted, o), nil // 202: it is being charged
}
```

(Copied from [`examples/queue`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main.go), region `dispatch`.)

| Option | |
|---|---|
| `queue.OnQueue(name)` | The queue (default `QUEUE_DEFAULT`). Names are lower-case letters, digits and `. _ : -` |
| `queue.Delay(d)` | Run the job after `d` |
| `queue.AfterCommit()` | Dispatch the job only once the transaction in the context commits; never if it rolls back |
| `queue.OnDispatched(fn)` | Call `fn(ctx, queue.Dispatched)` once the job is dispatched (after the commit with `AfterCommit`; not if the store refuses it or the transaction rolls back; with the sync driver, before it runs) |

Inside a transaction, a job must not run before the transaction commits,
or it may look for rows that aren't there yet:

- The **database** driver writes the job in the transaction, so the job is
  dispatched if and only if the transaction commits, with or without
  `queue.AfterCommit()`.
- With the other drivers, use `queue.AfterCommit()`. `Dispatch` then
  returns before the job is dispatched, so a failure to dispatch it is
  logged, not returned. (Outside a transaction, the job is dispatched at
  once, and `Dispatch` returns the error.)

Dispatching a type that isn't registered is an error, so a forgotten
`queue.Register` shows up at the first dispatch.

A job can also be a function, for work that needs dependencies a struct's
fields can't carry (the function can be a closure). Register it under a
name, with the type of its payload, and dispatch it by that name:

```go
// illustrative
err := queue.RegisterFunc(q, "reports.send", func(ctx context.Context, r ReportRequest) error {
	return reports.Send(ctx, r.Month)
}, queue.Tries(5))

err = queue.DispatchFunc(ctx, "reports.send", ReportRequest{Month: "2026-09"})
```

The name is stored with each job, like a struct job's type name, so it
must stay the same across deploys. [Queued event listeners](https://docs.anetos.dev/guides/events/index.md)
are function jobs.

A job runs in the locale and time zone of the context that dispatched it
(`i18n.Locale`, `i18n.TimeZone`), so text it writes, such as an email,
is in the language of the request, or of the user (`i18n.ForUser`), that
caused it. See [Translations](https://docs.anetos.dev/guides/translations/index.md).

### 4. Handle failed jobs

A job that fails is retried after its backoff until it has used its
tries. Then it fails for good: its `Failed` method runs, and it is kept as
a failed job, with its last error. A job whose last try didn't record its
outcome (its worker died, or it ran past its lease) fails the same way,
without running again, so a job that crashes its worker can't crash
workers forever. Its work may have been done, so make `Failed`
idempotent too. Commands manage failed jobs:

| Command | |
|---|---|
| `queue:failed [--limit=N]` | List failed jobs, the latest first |
| `queue:retry <id>…` or `queue:retry all` | Put failed jobs back on their queues, with all their tries (`all`: those that had failed when it started) |
| `queue:forget <id>…` | Delete failed jobs |
| `queue:flush` | Delete every failed job |
| `queue:clear [queue]` | Delete every job waiting on a queue (default `QUEUE_DEFAULT`) |

```console
$ ./app queue:failed
ID                                    FAILED AT            QUEUE     JOB               ATTEMPTS  ERROR
01a0f614-9a28-7025-93a7-b8b88ecb37d0  2026-10-01 06:09:00  payments  main.ChargeOrder  1         card declined
$ ./app queue:retry 01a0f614-9a28-7025-93a7-b8b88ecb37d0
```

In production, `queue:flush` and `queue:clear` need `--force`. In code,
`q.Store().Failed(ctx, offset, limit)` lists them, and
`queue.CountFailed(ctx, q.Store())` and `queue.FindFailed(ctx, q.Store(), id)`
count them and find one (at once with the built-in stores; a store of
your own may implement `queue.FailedCounter` and `queue.FailedFinder`).
The [admin](https://docs.anetos.dev/guides/admin/index.md#9-watch-jobs-and-scheduled-tasks) shows them too.

### 5. Test

With `QUEUE_DRIVER=sync` (the default, so what tests get unless
`.env.testing` or the test says otherwise), jobs run when they are
dispatched, so a test sees their effects when the request returns:

```go
// With QUEUE_DRIVER=sync, jobs run when they are dispatched: a test sees
// their effects as soon as the request returns.
func TestChargeOrder(t *testing.T) {
	g := &FakeGateway{}
	fakeGateway(t, g)
	app := anetostest.New(t, setup, anetostest.Env(map[string]string{"QUEUE_DRIVER": "sync"}))

	paid := placeOrder(t, app, "Book", 1500)
	app.Get("/orders/"+strconv.FormatInt(paid, 10)).AssertOK().AssertJSONPath("status", "paid")

	declined := placeOrder(t, app, "Piano", 500_000)
	app.Get("/orders/"+strconv.FormatInt(declined, 10)).AssertOK().AssertJSONPath("status", "failed")

	if n := g.Charges(); n != 1 {
		t.Errorf("%d charges, want 1", n)
	}
}
```

(Copied from [`examples/queue/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main_test.go), region `test-sync`.)

The sync driver runs each job once, without its delay, and `Dispatch`
returns its error. To test retries and backoff, run the workers:

```go
// With QUEUE_DRIVER=database, workers run the jobs: the test runs them
// with app.Run, and waits for the outcome.
func TestWorkersRetry(t *testing.T) {
	g := &FakeGateway{Flaky: true} // each charge fails once
	fakeGateway(t, g)
	app := anetostest.New(t, setup, anetostest.Env(map[string]string{
		"QUEUE_DRIVER": "database", "QUEUE_POLL_INTERVAL": "10ms", "QUEUE_BACKOFF": "10ms",
	}))
	ctx, stop := context.WithCancel(context.Background())
	done := make(chan error, 1)
	go func() { done <- app.Run(ctx, "worker") }()
	t.Cleanup(func() {
		stop()
		if err := <-done; err != nil {
			t.Error(err)
		}
	})

	paid := placeOrder(t, app, "Book", 1500)
	declined := placeOrder(t, app, "Piano", 500_000)
	waitFor(t, func() bool { return orderStatus(t, app, paid) == "paid" && orderStatus(t, app, declined) == "failed" })

	q := anetos.MustResolve[*queue.Queue](app.App)
	failed, err := q.Store().Failed(app.Context(), 0, 10)
	if err != nil {
		t.Fatal(err)
	}
	if len(failed) != 1 || failed[0].Error != "card declined" || failed[0].Attempts != 1 {
		t.Errorf("failed jobs = %+v", failed)
	}
	if n := g.Charges(); n != 1 {
		t.Errorf("%d charges, want 1", n)
	}
}
```

(Copied from [`examples/queue/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main_test.go), region `test-workers`.)

Workers use their own database connections, so they don't see rows
written in the test's transaction. This test uses in-memory SQLite, which
has none; with a SQLite file, PostgreSQL or MySQL, pass
`anetostest.WithoutTransaction()` to such a test.

`anetostest` gives each test app its own `QUEUE_PREFIX`, and removes its
Redis jobs when the test ends. `queue.AfterCommit()` jobs are dispatched
when a `db.Tx` inside the test's transaction commits, as they would be
without it.

To check that a job was dispatched without running it, fake the queue
and assert on the recorded jobs:

```go
// illustrative
app := anetostest.New(t, setup, anetostest.FakeQueue())
id := placeOrder(t, app, "Book", 1500)
anetostest.AssertDispatched(app, func(j ChargeOrder) bool { return j.OrderID == id })
```

[Test your app](https://docs.anetos.dev/guides/testing/index.md#6-check-jobs-events-emails-and-messages) has
the complete test and every assertion.

## How it works

**Leases.** A worker that takes a job **reserves** it: the job is hidden
from other workers for its lease, the longest timeout of the registered
job types plus 30 seconds. If the worker dies, the job becomes available
again when the lease ends, and counts that attempt. Each reservation has
its own token, and a worker records a job's outcome only with its token,
so a worker whose lease ran out can't delete the job from under the next.

**Order.** Workers take jobs from their queues in the order given, and
from each queue in the order the jobs became available. With concurrency
above 1, or several workers, jobs run in parallel and can finish in any
order.

**Shutdown.** Workers stop after the HTTP server, so they can still take
the jobs its last requests dispatched. They stop taking jobs,
then give running jobs the shutdown grace period (never more than the
shutdown budget leaves, less 2 seconds to put jobs back: keep
`APP_SHUTDOWN_TIMEOUT` well above that). Then they cancel the jobs' contexts: a job that
returns because of it goes back on its queue, without the attempt
counting, unless it returns a `queue.Permanent` error.

**Unknown jobs.** A worker that takes a job whose type its app doesn't
register counts a failed attempt. When you add a job type, deploy the
workers before the code that dispatches it.

**The drivers.** The database driver reserves jobs with
`SELECT … FOR UPDATE SKIP LOCKED`, so workers don't wait for each other.
The Redis driver keeps each queue in a sorted set and runs every change as
a Lua script; in a Redis Cluster, put a hash tag in the prefix
(`QUEUE_PREFIX={blog}:queue:`) so its keys share a slot. Both use the
server's clock for delays and leases.

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| `job type … isn't registered` | `queue.Register` wasn't called for it | Register every job type in `setup` |
| Jobs are never run | No workers: they run with `run` or `run --only=worker`, not with other commands | Run the app (`go run .`) or a worker process |
| `unknown job "…"` in failed jobs | The worker's app doesn't register that type (an older deploy, or a renamed type) | Deploy workers first; keep old names with `queue.Name` |
| A job runs twice | At-least-once delivery: a worker stopped, or the job ran past its timeout | Make the job idempotent |
| `no such table: jobs` | The queue's migration hasn't run | Add `queue.Migrations("", "")` to `migrate.New`, then `migrate` |
| A job finds no row it should | It ran before the transaction that wrote the row committed | Use `queue.AfterCommit()` (or the database driver) |

## Next steps

- [Run background tasks](https://docs.anetos.dev/guides/background-tasks/index.md) for work that isn't a job:
  pollers and heartbeats.
- [Scheduling](https://docs.anetos.dev/guides/scheduling/index.md): dispatch a job every hour or night with
  `schedule.Dispatch`.
- [Send email](https://docs.anetos.dev/guides/mail/index.md): `mailer.Queue` sends email from a queue job.
- [Runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md): process types, stages
  and shutdown.

> **Coming from another framework?** A job is what a Django app runs as
> a Celery task, Laravel as a queued job and Rails as an Active Job:
> `queue.Dispatch(ctx, job, queue.OnQueue("x"), queue.Delay(d))` sends
> it, `queue.Tries`, `queue.Backoff` and `queue.Timeout` set its
> retries, and `queue.Permanent(err)` fails it at once. Workers run
> inside the app, supervised, and `queue:work` (`run --only=worker`)
> runs only them; the queues and concurrency are the app's `Work`
> call's, not flags. Dependencies come from the context, not from the
> job's parameters.


# Events

Source: https://docs.anetos.dev/guides/events/

Emit an event when something happens, and let listeners react: write an
audit log, email a receipt, update a dashboard. The code that places an
order then doesn't need to know about all of them. Events are typed Go
values, and listeners are functions of their type. The complete app is
[`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue).

## Before you start

You have an app created with `anetos.New()`. Listeners that run as queue
jobs need the [queue](https://docs.anetos.dev/guides/queues/index.md) set up first.

## Steps

### 1. Define an event

An event is any type, usually a struct with what listeners need to know:

```go
// OrderPlaced is emitted when an order is saved. Each listener gets the
// value (queued listeners, as JSON), so keep it free of pointers they
// could change.
type OrderPlaced struct {
	OrderID int64  `json:"order_id"`
	Item    string `json:"item"`
	Cents   int64  `json:"cents"`
	Email   string `json:"email"`
}
```

(Copied from [`examples/queue/events.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/events.go), region `event`.)

### 2. Write listeners

A listener is a function of the event (or a method value):

```go
// recordAudit writes to the audit log in the order's transaction: if it
// fails, the order isn't placed.
func recordAudit(ctx context.Context, e OrderPlaced) error {
	return db.Create(ctx, &AuditEntry{OrderID: e.OrderID, Message: "placed: " + e.Item})
}

// countSale updates the sales counts in the background, once the order
// is committed. If the process stops first, the count is lost: fine for
// a dashboard.
func (s *Sales) countSale(_ context.Context, e OrderPlaced) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	s.Orders++
	s.Cents += e.Cents
	return nil
}

// emailReceipt sends the receipt, as a queue job: retried if the mail
// server fails, and not lost if the process stops. It skips addresses
// Postmark stopped sending to (the postmark plugin's list).
func emailReceipt(ctx context.Context, e OrderPlaced) error {
	if bad, err := postmark.Suppressed(ctx, e.Email); err != nil || bad {
		return err
	}
	return mailer.Send(ctx, ReceiptMail{Order: e})
}
```

(Copied from [`examples/queue/events.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/events.go), region `listeners`.)

### 3. Add the listeners

In `setup`, after the services listeners use (`db.Connect`,
`queue.New`, …), so the bus is closed before them at shutdown:

```go
bus, err := events.New(app) // after queue.New: queued listeners use the app's queue
if err != nil {
	return nil, err
}
if err := events.On(bus, recordAudit); err != nil {
	return nil, err
}
if err := events.OnAsync(bus, sales.countSale, events.Name("count-sale")); err != nil {
	return nil, err
}
if err := events.OnQueued(bus, emailReceipt, events.Job(queue.Tries(10))); err != nil {
	return nil, err
}
```

(Copied from [`examples/queue`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main.go), region `events-setup`.)

Choose how each listener runs:

| | `events.On` | `events.OnAsync` | `events.OnQueued` |
|---|---|---|---|
| Runs | In `Emit`, with its context | In the background, in a pool of goroutines of its own | As a queue job, in a worker |
| Transaction | Emit's: its writes commit or roll back with it | After Emit's transaction commits; never if it rolls back | Dispatched after the commit (with the queue's database driver, written in the transaction) |
| Its error | Stops the other `On` listeners; `Emit` returns it | Logged | Retried, then a failed job (with the sync driver, outside a transaction, returned by `Emit`) |
| If the process stops | — | Events not yet handled are lost | Kept; the job runs later |
| Its context | Emit's | The app's values, and its timeout; nothing of the request | A job's: the app's values and `queue.Current` |
| Use it for | Work that must succeed with the change | Quick, optional work: metrics, cache warming | Work that must happen, maybe slowly: email, other services |

Options:

| Option | For | |
|---|---|---|
| `events.Name(s)` | All | The listener's name in logs. A queued listener's job is `event:<name>`: anonymous and generic functions must have one, and it must stay the same across deploys. Default: the function's name, `main.emailReceipt` |
| `events.Concurrency(n)` | `OnAsync` | Events handled at once (default 1) |
| `events.Buffer(n)` | `OnAsync` | Events that wait for the listener (default 1000). When it is full, `Emit` waits for room, until its context ends (a listener emitting to itself: until its timeout) |
| `events.Timeout(d)` | `OnAsync` | How long one event may take (default 1m) |
| `events.Job(opts…)` | `OnQueued` | `queue.Tries`, `queue.Timeout`, `queue.Backoff` |
| `events.Dispatch(opts…)` | `OnQueued` | `queue.OnQueue`, `queue.Delay` |

> **Warning:** Async listeners are **not durable**: events they haven't
> handled when the process stops (after the shutdown budget) or crashes
> are lost. Use `OnQueued` for anything that must happen.

### 4. Emit events

Call `events.Emit` with a request's (or a job's) context:

```go
// PlaceOrder saves the order and dispatches the job that charges it.
func PlaceOrder(c *web.Ctx, in OrderInput) (web.Responder, error) {
	o := &Order{Item: in.Item, Cents: in.Cents, Email: in.Email, Status: "pending"}
	err := db.Tx(c, func(ctx context.Context) error {
		if err := db.Create(ctx, o); err != nil {
			return err
		}
		if err := events.Emit(ctx, OrderPlaced{OrderID: o.ID, Item: o.Item, Cents: o.Cents, Email: o.Email}); err != nil {
			return err // an On listener failed: no order
		}
		// AfterCommit: no charge for an order that isn't saved. (The
		// database driver writes the job in the transaction instead.)
		return queue.Dispatch(ctx, ChargeOrder{OrderID: o.ID}, queue.OnQueue("payments"), queue.AfterCommit())
	})
	if err != nil {
		return nil, err
	}
	return web.JSON(http.StatusAccepted, o), nil // 202: it is being charged
}
```

(Copied from [`examples/queue`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main.go), region `dispatch`.)

Listeners are found by the event's exact type: emitting `&OrderPlaced{}`
doesn't reach `OrderPlaced` listeners, and interface types can't be
listened to. An event nobody listens to is fine. Every listener gets the
same value: don't change what its pointer, slice or map fields point to,
since async listeners may be reading them.

Async and queued listeners wait for the transaction `Emit` runs in to
commit. A transaction you began yourself and passed in with `db.WithTx`
commits out of the db package's sight: async listeners (and queued ones,
except with the queue's database driver) never get events emitted in it.

`Emit` returns an `On` listener's error, or an error handing the event to
the others, such as an async listener's full buffer. Inside a
transaction, those happen after the commit, so they are logged instead.

### 5. Test

`On` listeners have run when `Emit` returns, and so have queued ones with
`QUEUE_DRIVER=sync`. Async ones run in the background: wait for them with
`bus.Wait`:

```go
// Each kind of listener: the audit entry is written with the order, the
// receipt sent by the queued listener (the sync driver runs it at once),
// and the sales counted in the background: bus.Wait waits for that.
func TestOrderEvents(t *testing.T) {
	fakeGateway(t, &FakeGateway{})
	app := anetostest.New(t, setup, anetostest.Env(map[string]string{"QUEUE_DRIVER": "sync"}))
	ordersBefore, _ := sales.Snapshot()

	id := placeOrder(t, app, "Lamp", 4250)

	anetostest.AssertDatabaseHas[AuditEntry](app, db.Col[int64]("order_id").Eq(id))
	if sent := sentMail(app); len(sent) != 1 || sent[0].Subject != fmt.Sprintf("Your receipt for order %d", id) {
		t.Errorf("emails: %+v", sent)
	}
	bus := anetos.MustResolve[*events.Bus](app.App)
	if err := bus.Wait(app.Context()); err != nil {
		t.Fatal(err)
	}
	if orders, _ := sales.Snapshot(); orders != ordersBefore+1 {
		t.Errorf("sales: %d orders, want %d", orders, ordersBefore+1)
	}
	app.Get("/stats").AssertOK()
}
```

(Copied from [`examples/queue/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main_test.go), region `test-events`.)

In a test's transaction (`anetostest` with a SQLite file, PostgreSQL or
MySQL), async and queued listeners get events when the request's
transaction commits, as they would in production. But async listeners
use their own connections, outside the test's transaction: they don't
see its rows (and, with a SQLite file, their writes wait for it and
fail). Test async listeners that use the database with in-memory SQLite
or `anetostest.WithoutTransaction()`. Queued listeners run by the sync
driver are in the test's transaction.

To check that an event was emitted without running its listeners, fake
it: `anetostest.New(t, setup, anetostest.FakeEvents(OrderPlaced{}))`,
then `anetostest.AssertEmitted(app, func(e OrderPlaced) bool { … })`;
see [Test your app](https://docs.anetos.dev/guides/testing/index.md#6-check-jobs-events-emails-and-messages).

## How it works

`events.On`, `OnAsync` and `OnQueued` add the listener to a map from the
event's type to its listeners; `Emit` looks the type up there. Listeners
are generic functions, so the compiler checks their event type, and
nothing is reflective at `Emit` but that lookup.

Each async listener has its own buffer and goroutines, started the first
time it gets an event, so a slow listener doesn't slow the others' work
(until its buffer is full: then `Emit` waits for it).

At shutdown, after the app's components have stopped, the bus stops
taking events (except from its async listeners, which may emit while they
finish) and gives the async listeners the rest of the shutdown budget;
then the events still waiting are dropped and the listeners' contexts
canceled. `bus.Close` does the same for a bus made with `events.NewBus`.

A queued listener is a queue job registered with `queue.RegisterFunc`,
named `event:<listener name>`, whose payload is the event as JSON. The
workers' app must add the same listeners, as with any job type.

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| `no bus in the context` | `events.New` wasn't called, or the context isn't the app's | Call `events.New` in `setup`; emit with a request's or job's context |
| A listener never runs | It listens to another type: `OrderPlaced` vs `*OrderPlaced`, or another package's type of the same name | Emit the type the listener takes |
| `the queued listener … is an anonymous or generic function` | Queued listeners' job names come from their names | Pass `events.Name("…")` |
| `queued listeners need the queue` | `events.OnQueued` before `queue.New` | Set up the queue first |
| Async work missing after a deploy or crash | Async events are lost when the process stops | Use `OnQueued` for work that must happen |
| `has 1000 events waiting` | An async listener can't keep up | Raise `events.Concurrency` or `events.Buffer`, or make it queued |

## Next steps

- [Queues](https://docs.anetos.dev/guides/queues/index.md): workers, retries and failed jobs, for queued
  listeners.
- [Transactions](https://docs.anetos.dev/guides/transactions/index.md): `db.AfterCommit`, which async and
  queued listeners use.
- [Send email](https://docs.anetos.dev/guides/mail/index.md): the receipt `emailReceipt` sends.

> **Coming from another framework?** Events and listeners play the part
> of Django's signals, Laravel's events and listeners, or Rails'
> `ActiveSupport::Notifications` (or a gem such as Wisper), and they
> are registered in code, never discovered. `On` is a plain listener, `OnQueued` a queued one that
> waits for the commit, and `OnAsync` works in the background, in the
> same process, without a queue. A subscriber is a function that calls
> `On` several times.


# Scheduling

Source: https://docs.anetos.dev/guides/scheduling/

Run tasks on a schedule: prune old rows every night, send a report every
hour, sync with another service every five minutes. The scheduler runs
in your app's binary, as a supervised component, so there is no crontab
to install and nothing to run every minute. The complete app is
[`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue).

## Before you start

You have an app created with `anetos.New()`. Tasks that use locks
(`WithoutOverlapping`, `OnOneServer`) need the [cache](https://docs.anetos.dev/guides/cache/index.md) set up,
and tasks that dispatch jobs need the [queue](https://docs.anetos.dev/guides/queues/index.md).

## Steps

### 1. Write a task

A task is a function of a context that returns an error:

```go
// pruneAuditLog deletes the audit log's entries older than 90 days. It
// runs every night (see setup) on one instance, and is safe to run again:
// it deletes what is old when it runs.
func pruneAuditLog(ctx context.Context) error {
	n, err := db.Query[AuditEntry](ctx).Where(colCreatedAt.Lt(anetos.Now(ctx).AddDate(0, 0, -90))).Delete()
	if err != nil {
		return err
	}
	anetos.Logger(ctx).InfoContext(ctx, "audit log pruned", "deleted", n)
	return nil
}
```

(Copied from [`examples/queue/schedule.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/schedule.go), region `task`.)

The rules for the function:

- **Watch `ctx`.** It has the app's values (the database, the cache, …)
  and is canceled at shutdown, after a grace period, or when the task's
  `schedule.Timeout` runs out.
- **Return an error to report a failure.** It is logged, and the task
  runs again at its next time: the scheduler doesn't retry. For work that
  must succeed, dispatch a queue job (step 2).
- Panics are recovered, logged with their stack, and count as failures.
- Make it safe to run twice, or late: a deploy, a clock change or a
  `schedule:run` can do either.

### 2. Add it to the scheduler

In `setup`, after `cache.New` (and `queue.New`, for jobs):

```go
// The scheduler's locks (WithoutOverlapping, OnOneServer) are in the
// cache: with several instances, use a store they share.
if _, err := cache.New(app, redis.CacheDriver()); err != nil { // CACHE_DRIVER: memory, database or redis
	return nil, err
}
s, err := schedule.New(app) // SCHEDULE_TIMEZONE, default APP_TIMEZONE (UTC)
if err != nil {
	return nil, err
}
if err := s.Add(schedule.DailyAt("03:00"), "prune-audit-log", pruneAuditLog,
	schedule.WithoutOverlapping(), schedule.OnOneServer(), schedule.Timeout(10*time.Minute)); err != nil {
	return nil, err
}
// Hourly, the scheduler dispatches a job; a worker runs it.
if err := queue.Register[SalesReport](q, queue.Tries(3)); err != nil {
	return nil, err
}
if err := s.Add(schedule.Hourly(), "sales-report", schedule.Dispatch(SalesReport{}), schedule.OnOneServer()); err != nil {
	return nil, err
}
```

(Copied from [`examples/queue`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main.go), region `schedule-setup`.)

`schedule.Dispatch(job)` is a task that dispatches a queue job, so a
worker runs it with the queue's retries, timeouts and failed jobs:

```go
// SalesReport is a queue job that reports the orders paid in the hour
// before it runs. The scheduler dispatches it every hour; a worker runs
// it, with the queue's retries.
type SalesReport struct{}

// Handle counts the orders and sends the report.
func (SalesReport) Handle(ctx context.Context) error {
	n, err := db.Query[Order](ctx).Where(colStatus.Eq("paid"), colCreatedAt.Gte(anetos.Now(ctx).Add(-time.Hour))).Count()
	if err != nil {
		return err
	}
	salesReports.mu.Lock()
	defer salesReports.mu.Unlock()
	salesReports.sent = append(salesReports.sent, fmt.Sprintf("Sales report: orders paid in the last hour: %d", n))
	return nil
}
```

(Copied from [`examples/queue/schedule.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/schedule.go), region `report-job`.)

Task names are lower-case letters, digits and `. _ : -`; they name the
task in logs, locks and commands, so keep them the same across deploys.

**Schedules:**

| Schedule | Runs |
|---|---|
| `schedule.EveryMinute()` | Every minute |
| `schedule.Every(d)` | Every `d`, counted from midnight: whole minutes dividing an hour (`5*time.Minute` at :00, :05, …) or whole hours dividing a day (`6*time.Hour` at 00:00, 06:00, …) |
| `schedule.Hourly()`, `schedule.HourlyAt(m)` | Every hour, at minute 0 or `m` |
| `schedule.Daily()`, `schedule.DailyAt("15:04")` | Every day, at midnight or the time |
| `schedule.WeeklyOn(time.Monday, "08:00")` | Every week, on the day at the time |
| `schedule.MonthlyOn(1, "08:00")` | Every month, on the day (1 to 28) at the time |
| `schedule.Cron("*/15 9-17 * * MON-FRI")` | A cron expression: minute, hour, day of month, month, day of week; numbers, `*`, ranges, lists, steps and names; or `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly` |

As in cron, when a `Cron` expression restricts both the day of month
and the day of week, a day matching either runs: `0 0 1 * MON` is the 1st
of the month and every Monday. A field starting with `*` (`*/2` too)
isn't restricted, so `0 0 */2 * MON` is odd days that are Mondays.

**Options:**

| Option | Does |
|---|---|
| `schedule.WithoutOverlapping()` | Skips a run while the previous one is still going, on any instance sharing the cache |
| `schedule.OnOneServer()` | Runs each run on one instance only, when several run the scheduler |
| `schedule.Timeout(d)` | Cancels a run's context after `d` |

**Time zones.** Schedules are in `SCHEDULE_TIMEZONE` (default the app's
zone, `APP_TIMEZONE`, itself `UTC` by default), or
in the zone `.In("Asia/Dhaka")` gives one schedule. In a zone with
daylight saving time, a time that the clock change skips doesn't run that
day, and a time it repeats runs twice: schedule tasks that matter away
from the zone's clock changes (usually between midnight and 03:00; some
zones change at midnight), or in UTC.

### 3. Run the scheduler

The scheduler runs with the app's other components:

```bash
go run .                         # the web server, the workers and the scheduler
go run . schedule:work           # only the scheduler (run --only=scheduler)
```

Or, where a cron daemon or a Kubernetes CronJob is the scheduler, start
`schedule:run` every minute instead of a long-running scheduler: it runs
the tasks due in the minute it started, once, with their locks, and
exits (status 1 if one failed):

```text
* * * * * cd /srv/app && ./app schedule:run >> /var/log/app-schedule.log 2>&1
```

Then run the app without its scheduler (`./app run --only=web,worker`,
or `serve` and `queue:work`), or every task runs twice. Each
`schedule:run` is a process of its own, so `WithoutOverlapping` and
`OnOneServer` need a cache store the processes share
(`CACHE_DRIVER=database` or `redis`); with `memory`, `schedule:run`
warns.

With several instances (several web servers, say), each one runs the
scheduler unless you split it out with `--only`. Either run it in one
process, or give the tasks `OnOneServer` and a cache store the instances
share (`CACHE_DRIVER=database` or `redis`): then the first instance to
take a run's lock runs it, and the others skip it. With the memory store,
the locks hold only within a process, and the scheduler warns at start.

Runs that should have happened while no scheduler was running (during a
deploy, say) are skipped, as with cron. A scheduler that wakes up late
runs each task it missed once, not once per missed time.

At shutdown, the scheduler stops starting runs before the listeners and
workers stop, and gives the runs still going half of
`APP_SHUTDOWN_TIMEOUT`; then their contexts are canceled. That time comes
out of the listeners' and workers' share, so put long work in a queue
job with `schedule.Dispatch`.

### 4. Check and run tasks

`schedule:list` shows the tasks and when they run next:

```text
$ go run . schedule:list
TASK             SCHEDULE   NEXT RUN                       OPTIONS
prune-audit-log  0 3 * * *  2026-10-02 03:00 +06 (in 11h)  without overlapping, on one server, timeout 10m
sales-report     0 * * * *  2026-10-01 17:00 +06 (in 1h)   on one server
```

`schedule:test <task>` runs a task now, whatever its schedule, and fails
with its error. `WithoutOverlapping` applies (it fails if the task is
running), but only sees runs in other processes with a shared cache
store; `OnOneServer` doesn't apply.

Each run, scheduled or not, is kept in the cache as the task's last run:
when it started, how long it took, its error, or that it was skipped
because the previous run was still going. `s.LastRun(ctx, name)` returns
it, and the [admin](https://docs.anetos.dev/guides/admin/index.md)'s scheduled tasks page shows it. Processes
see each other's runs with a shared cache store (`CACHE_DRIVER=database`
or `redis`).

### 5. Test

Test a task by running it with `RunTask`, as `schedule:test` does:

```go
// RunTask runs a task now, as `go run . schedule:test <task>` does.
func TestScheduledTasks(t *testing.T) {
	fakeGateway(t, &FakeGateway{})
	app := anetostest.New(t, setup, anetostest.Env(map[string]string{"QUEUE_DRIVER": "sync"}))
	old := &AuditEntry{OrderID: 1, Message: "placed: Kettle"}
	if err := db.Create(app.Context(), old); err != nil {
		t.Fatal(err)
	}
	_, err := db.Query[AuditEntry](app.Context()).Where(colID.Eq(old.ID)).Update(colCreatedAt.Set(time.Now().AddDate(0, 0, -100)))
	if err != nil {
		t.Fatal(err)
	}
	recent := placeOrder(t, app, "Mug", 900)

	s := anetos.MustResolve[*schedule.Scheduler](app.App)
	if err := s.RunTask(app.Context(), "prune-audit-log"); err != nil {
		t.Fatal(err)
	}
	anetostest.AssertDatabaseMissing[AuditEntry](app, colID.Eq(old.ID))
	anetostest.AssertDatabaseHas[AuditEntry](app, db.Col[int64]("order_id").Eq(recent))

	if err := s.RunTask(app.Context(), "sales-report"); err != nil { // the sync queue runs the job at once
		t.Fatal(err)
	}
	if r := salesReports.Sent(); len(r) == 0 || r[len(r)-1] != "Sales report: orders paid in the last hour: 1" {
		t.Errorf("reports: %q", r)
	}
}
```

(Copied from [`examples/queue/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main_test.go), region `test-schedule`.)

To check a schedule, `Next` returns when it runs after a time:

```go
// illustrative
next := schedule.WeeklyOn(time.Monday, "08:00").In("Asia/Dhaka").Next(time.Now())
```

## How it works

`schedule.New` provides the `*schedule.Scheduler` to the app and, once
it has tasks, adds it as a component of the process type `scheduler` and the
stage `StageScheduler`, which stops right after the HTTP server. Its loop
computes each task's next run, sleeps until the earliest, and starts the
runs that are due, each in its own goroutine, so a slow task doesn't
delay the others.

`OnOneServer` takes a cache lock named after the task and the run's
minute (`schedule:<task>:<UTC time>`), kept for an hour: instances whose
clocks differ by less than that agree on who runs it. `WithoutOverlapping`
takes the lock `schedule:<task>:running` while a run goes, released when
it ends: it lasts three minutes and the run extends it every minute, so
if the process dies, the next run after that can start. Both are cache
locks, so they need the store to be shared to work across instances.

Cron expressions are parsed when the task is added, and an expression
that never matches (`0 0 30 2 *`) is an error then.

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| `uses a lock … call cache.New` | A task has `WithoutOverlapping` or `OnOneServer` but the app has no cache | Call `cache.New` in `setup` |
| A task runs on every instance | `OnOneServer` is missing, or the cache store is `memory` | Add `OnOneServer` and use `CACHE_DRIVER=database` or `redis`, or run the scheduler in one process (`--only=scheduler`) |
| A task never runs | Its process doesn't run the `scheduler` process type (`--only=web`), or it's running in another time zone than you think | Check `schedule:list`, and `SCHEDULE_TIMEZONE` |
| `skipped: the previous run is still going` | A `WithoutOverlapping` run takes longer than the time between runs | Run it less often, or make it faster |
| A failed run isn't retried | The scheduler doesn't retry | Dispatch a queue job with `schedule.Dispatch` |
| A task ran twice, or not at all, one night | A daylight saving time change | Schedule it away from the zone's clock changes, or in UTC |

## Next steps

- [Queues](https://docs.anetos.dev/guides/queues/index.md): workers and retries, for the jobs tasks dispatch.
- [Cache](https://docs.anetos.dev/guides/cache/index.md): stores and locks.
- [Runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md): process types and
  staged shutdown.

> **Coming from another framework?** `s.Add(schedule.DailyAt("02:00"),
> "prune", prune)` schedules what Celery beat (Django), Laravel's
> scheduler or a recurring job (Rails) would run. `WithoutOverlapping`,
> `OnOneServer` and `schedule.Dispatch` keep a task to one run at a
> time, to one server, or send it to the queue. `schedule:work`,
> `schedule:run` (for a crontab entry every minute) and `schedule:list`
> are there too, and `go run .` also runs the scheduler, in your binary.
> Every task needs a name.


# Run background tasks

Source: https://docs.anetos.dev/guides/background-tasks/

Run long-lived work, such as a poller, a cache warmer or a heartbeat, as a
supervised goroutine that restarts on failure and stops cleanly on deploy.

## Before you start

You have an app created with `anetos.New()`. See
[Configure your application](https://docs.anetos.dev/guides/configuration/index.md).

## Steps

### 1. Start the task with `app.Go`

```go
	err = app.Go("heartbeat", func(ctx context.Context) error {
		counter := anetos.MustResolve[*Counter](app)
		ticker := time.NewTicker(cfg.Interval)
		defer ticker.Stop()
		for {
			select {
			case <-ctx.Done():
				return nil
			case <-ticker.C:
				n := counter.n.Add(1)
				app.Logger().Info("beat", "n", n)
				if cfg.FailAt > 0 && n%int64(cfg.FailAt) == 0 {
					return errors.New("simulated failure")
				}
			}
		}
	},
		anetos.ProcessTypes("worker"),
		anetos.Restart(supervisor.RestartOnFailure),
		anetos.Backoff(supervisor.Backoff{Initial: time.Second, Max: 10 * time.Second}),
	)
	if err != nil {
		return err
	}
```

(Copied from [`examples/lifecycle`](https://github.com/anetos-dev/anetos/blob/main/examples/lifecycle/main.go),
region `task`.)

The rules for the function:

- **Watch `ctx`.** Return soon after `ctx.Done()` closes. That's how
  shutdown reaches your task.
- **Return an error to report a failure.** The restart policy decides what
  happens next. Returning `nil` means "finished", and the task is not
  restarted.
- Panics are recovered and treated as failures.

### 2. Run the app with signal handling

```go
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()
	return app.Run(ctx)
```

(Region `run`.)

### 3. Try it

```bash
HEARTBEAT_INTERVAL=200ms HEARTBEAT_FAIL_AT=3 APP_ENV=development go run ./examples/lifecycle
```

Every third beat the task fails and restarts after a growing delay. Press
Ctrl+C: the task stops, then the shutdown hook reports the total.

## Options

| Option | Default | Purpose |
|---|---|---|
| `anetos.ProcessTypes("worker")` | none (runs in every process) | Select with `app.Run(ctx, "worker")` / `--only` |
| `anetos.Restart(policy)` | `RestartNever` | `RestartOnFailure`, `StopOnFailure` |
| `anetos.Backoff(b)` | 1s initial, 30s max, unlimited | Restart delays and limit |
| `anetos.Stage(s)` | `StageBackground` | Shutdown order |

## Starting tasks while the app runs

`app.Go` also works after `Run` has started, for example from a request
handler. Task names must be unique, so include an ID:

```go
// illustrative
err := app.Go("export-"+job.ID, func(ctx context.Context) error {
	return exportReport(ctx, job)
})
```

> **Warning:** Tasks started this way are **not durable**. If the process
> crashes or is killed, they are lost. For work that must survive a restart,
> use a [queue job](https://docs.anetos.dev/guides/queues/index.md).

## Testing it

Run the app with a cancelable context and check its status:

```go
// illustrative
ctx, cancel := context.WithCancel(context.Background())
go app.Run(ctx)
// … wait for the task to do something …
cancel()
for _, st := range app.Supervisor().Status() {
	t.Log(st.Name, st.State, st.Restarts, st.LastError)
}
```

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `shutdown timed out; still running: my-task` | The task ignores `ctx` | Select on `ctx.Done()` in loops; pass `ctx` to blocking calls |
| `duplicate component name` | Two tasks share a name | Make names unique, e.g. append an ID |
| `supervisor: shutting down` | `app.Go` called during shutdown, or after every other component finished | Expected; don't start new work while stopping |
| Task never restarts | Default policy is `RestartNever` | Add `anetos.Restart(supervisor.RestartOnFailure)` |

## Next steps

- [Scheduling](https://docs.anetos.dev/guides/scheduling/index.md) for work that runs at set times (every
  night, every hour) rather than all the time.
- [Runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md): process types, policies,
  staged shutdown
- [Application lifecycle](https://docs.anetos.dev/concepts/application-lifecycle/index.md)


# Pub/sub listeners

Source: https://docs.anetos.dev/guides/pubsub/

Listen to message streams other services publish, such as
`orders.created`, and publish your own, from the same binary as your web
app. Where the [queue](https://docs.anetos.dev/guides/queues/index.md) runs an app's own jobs, pub/sub
connects services: each subscription gets every message of a topic. The
complete app is [`examples/pubsub`](https://github.com/anetos-dev/anetos/tree/main/examples/pubsub), a billing
service.

## Before you start

Choose the broker with `PUBSUB_DRIVER`:

| Driver | Broker | Use it for |
|---|---|---|
| `memory` (default) | In the process | Development and tests |
| `redis` | Redis Streams, Redis 7 or later (`drivers/redis`, `REDIS_URL`) | Services sharing a Redis server |
| `gcp` | Google Cloud Pub/Sub (`drivers/gcppubsub`, `PUBSUB_GCP_PROJECT`) | Services on Google Cloud |

Words used here:

- A **topic** is a named stream of messages: `orders.created`.
- A **subscription** is a named reader of a topic. Every subscription gets
  every message published after it was created; the processes listening
  with one subscription share its messages. By default a listener's
  subscription is named after the topic and your app (`APP_NAME`):
  `orders.created.billing`.

## Steps

### 1. Define the messages

Messages are JSON. Define a struct for each topic you read or write:

```go
// OrderCreated is what the shop publishes to "orders.created".
type OrderCreated struct {
	OrderID  int64  `json:"order_id"`
	Customer string `json:"customer"`
	Cents    int64  `json:"cents"`
}

// InvoiceCreated is what billing publishes to "invoices.created".
type InvoiceCreated struct {
	InvoiceID int64 `json:"invoice_id"`
	OrderID   int64 `json:"order_id"`
}
```

(Copied from [`examples/pubsub/billing.go`](https://github.com/anetos-dev/anetos/blob/main/examples/pubsub/billing.go), region `messages`.)

### 2. Write a listener

A listener is a function of the message:

```go
// CreateInvoice bills an order. A message may arrive more than once, so
// an order that has its invoice is skipped.
func CreateInvoice(ctx context.Context, o OrderCreated) error {
	if o.OrderID <= 0 || o.Cents <= 0 {
		return pubsub.Permanent(fmt.Errorf("invalid order: %+v", o)) // straight to the dead-letter topic
	}
	return db.Tx(ctx, func(ctx context.Context) error {
		billed, err := db.Query[Invoice](ctx).Where(colOrderID.Eq(o.OrderID)).Exists()
		if err != nil || billed {
			return err
		}
		inv := &Invoice{OrderID: o.OrderID, Customer: o.Customer, Cents: o.Cents}
		if err := db.Create(ctx, inv); err != nil {
			return err // another delivery won the race: retried, then skipped
		}
		return pubsub.Publish(ctx, "invoices.created", InvoiceCreated{InvoiceID: inv.ID, OrderID: o.OrderID}, pubsub.AfterCommit())
	})
}
```

(Copied from [`examples/pubsub/billing.go`](https://github.com/anetos-dev/anetos/blob/main/examples/pubsub/billing.go), region `listener`.)

- **Return nil** to acknowledge the message: it's done.
- **Return an error** to have it delivered again, after a backoff.
- **Return `pubsub.Permanent(err)`** to give up on it at once, for
  messages that will never work, such as malformed ones. A message that
  isn't valid JSON for the type fails this way too.
- **`ctx`** has the app's values (the database, the queue…), and
  `pubsub.Current(ctx)` returns the message: its ID, attributes and
  attempt.
- Take `[]byte` (or `json.RawMessage`) instead of a struct to get the
  body as it is.
- `queue.Permanent` works too, for code shared with queue jobs.

> **Warning:** Delivery is **at-least-once**: a message can arrive twice,
> for example if a listener stops after handling it but before
> acknowledging it. Make listeners idempotent, as the example does with a
> unique index and a check.

### 3. Listen

In `setup`:

```go
ps, err := pubsub.New(app, redis.PubSubDriver(), gcppubsub.Driver()) // PUBSUB_DRIVER: memory, redis or gcp
if err != nil {
	return nil, err
}
err = pubsub.Listen(ps, "orders.created", CreateInvoice,
	pubsub.Concurrency(8),                   // messages at once, in each process
	pubsub.Tries(5),                         // then...
	pubsub.DeadLetter("orders.created.dlq"), // ...to this topic
)
if err != nil {
	return nil, err
}
```

(Copied from [`examples/pubsub`](https://github.com/anetos-dev/anetos/blob/main/examples/pubsub/main.go), region `setup`.)

Pass only the drivers you use: each is a module with its own
dependencies.

| Option | Default | |
|---|---|---|
| `pubsub.Subscription(name)` | `<topic>.<APP_NAME>` | The subscription's name |
| `pubsub.Concurrency(n)` | 1 | Messages handled at once, in each process. The listener stops taking messages while that many are being handled |
| `pubsub.Timeout(d)` | 1m | How long one message may take. The broker may deliver it again 30s after that |
| `pubsub.Tries(n)` | 0: no limit | Deliveries before giving up on a message |
| `pubsub.Backoff(d1, d2, …)` | 10s, doubling up to 10m | Waits before deliveries after failures; the last repeats. Each varies by up to 20% |
| `pubsub.DeadLetter(topic)` | none | Where messages given up on go. Without one, they are dropped and logged |
| `pubsub.ShutdownGrace(d)` | Half of `APP_SHUTDOWN_TIMEOUT` | How long messages being handled may finish at shutdown |

If publishing to the dead-letter topic fails, the listener tries again
for a few seconds, then leaves the message to be delivered again. A
message sent to the dead-letter topic keeps its body and attributes,
plus `anetos.topic`, `anetos.subscription`, `anetos.error` and
`anetos.attempts`. Listen to the dead-letter topic like any other to
inspect or replay them.

The listener runs with the app (`go run .`) as a component of the process
type `listener`. You can run it apart:

```bash
./billing run --only=listener
```

The subscription is created when the app boots (for Redis and the
memory broker, and for Google with `PUBSUB_GCP_CREATE=true`), so messages
published after the first deploy are kept even before a listener runs.

### 4. Publish

```go
// illustrative
err := pubsub.Publish(ctx, "invoices.created", InvoiceCreated{InvoiceID: inv.ID})
```

The message is encoded as JSON; byte slices (`[]byte`, `json.RawMessage`)
are sent as they are. `pubsub.Attributes(map[string]string{…})` sends string pairs
with it. Inside a transaction, pass `pubsub.AfterCommit()`, as the
listener above does, so that the message is published only once the
transaction commits. Publish has returned by then, so if publishing
fails then, the failure is only logged: when a message must not be lost,
publish it from a [queue job](https://docs.anetos.dev/guides/queues/index.md) (retried) dispatched in the
transaction.

To publish by hand (or replay a dead letter), with a broker other than
`memory` (whose messages never leave their process):

```bash
./billing pubsub:publish orders.created '{"order_id":1,"customer":"Ada","cents":1500}'
```

### 5. Test

With the memory broker, run the listeners with `app.Run` and publish:

```go
// The listener runs with app.Run, as in production, with the memory
// broker (PUBSUB_DRIVER's default). The test publishes what the shop
// would, and checks what billing did.
func TestCreateInvoice(t *testing.T) {
	app := anetostest.New(t, setup)
	ps := anetos.MustResolve[*pubsub.PubSub](app.App)
	invoices := listen(t, ps, "invoices.created")
	dead := listen(t, ps, "orders.created.dlq")

	ctx, stop := context.WithCancel(context.Background())
	done := make(chan error, 1)
	go func() { done <- app.Run(ctx, "listener") }()
	t.Cleanup(func() {
		stop()
		if err := <-done; err != nil {
			t.Error(err)
		}
	})

	order := OrderCreated{OrderID: 1, Customer: "Ada", Cents: 1500}
	for _, o := range []OrderCreated{order, order, {OrderID: 2}} { // a duplicate, and an invalid order
		if err := pubsub.Publish(app.Context(), "orders.created", o); err != nil {
			t.Fatal(err)
		}
	}
	waitFor(t, func() bool { return len(invoices()) == 1 && len(dead()) == 1 })

	var created InvoiceCreated
	if err := json.Unmarshal(invoices()[0].Data, &created); err != nil || created.OrderID != 1 {
		t.Errorf("invoices.created: %+v, %v", created, err)
	}
	if got := dead()[0].Attributes["anetos.error"]; got != "invalid order: {OrderID:2 Customer: Cents:0}" {
		t.Errorf("dead letter error: %q", got)
	}
	app.Get("/invoices").AssertOK().AssertJSONPath("0.customer", "Ada")
	anetostest.AssertDatabaseCount[Invoice](app, 1)
}
```

(Copied from [`examples/pubsub/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/pubsub/main_test.go), region `test`.)

Listeners use their own database connections, outside the test's
transaction: test them with in-memory SQLite (as here) or
`anetostest.WithoutTransaction()`. With Redis, `anetostest` gives each
test app its own `PUBSUB_PREFIX` and removes its streams when the test
ends.

To check what the app publishes, `anetostest` records every message:
`anetostest.AssertPublished(app, "orders.created", func(m OrderCreated) bool { … })`.
With `anetostest.FakePubSub()`, messages are only recorded, not sent to
the broker; see [Test your app](https://docs.anetos.dev/guides/testing/index.md#6-check-jobs-events-emails-and-messages).

## How it works

**Redis Streams.** A topic is a stream (key `PUBSUB_PREFIX` + topic) and a
subscription a consumer group, created at the stream's end. A listener
reads new messages with `XREADGROUP`. A message it fails stays pending,
with its retry time in a sorted set next to the stream, and is claimed
again (`XAUTOCLAIM`) once that time has come; those of a listener that
stopped are claimed once their ack timeout (the listener's timeout plus
30s) has passed. `Message.Attempt` is the group's delivery count.
Streams are capped at about `PUBSUB_REDIS_MAXLEN` messages (default
1,000,000): older ones are trimmed even if a slow subscription hasn't read
them, or is retrying them. In a Redis
Cluster, a stream and its retry sets must share a slot: put a hash tag in
`PUBSUB_PREFIX` (`{billing}:`).

**Google Cloud Pub/Sub.** Topic and subscription IDs are the names with
`PUBSUB_PREFIX`, with `%` and the characters Pub/Sub doesn't allow (such
as `:`) escaped as `%XX`; IDs must start with a letter and have 3 to 255
characters. In production, create topics and subscriptions with your
infrastructure tools: the app then needs only to publish and consume
(`roles/pubsub.publisher` and `roles/pubsub.subscriber`), and a missing
subscription shows when its listener starts, in the logs. With
`PUBSUB_GCP_CREATE=true` (development, the emulator), the driver creates
missing ones when the app boots, with a retry policy backing off from 10s
to 10m (that needs the `pubsub.topics.create`, `pubsub.subscriptions.get`
and `pubsub.subscriptions.create` permissions). The client extends a message's deadline while it is
being handled, up to the listener's ack timeout. Two things differ from
Redis:

- A failed message is redelivered as the **subscription's retry policy**
  says, not as `pubsub.Backoff` does.
- Pub/Sub counts deliveries only for subscriptions with a **dead-letter
  policy**: `pubsub.Tries` needs one. Without one, `Attempt` is 0,
  failed messages are retried until they expire, and the listener logs a
  warning. With one, Pub/Sub's own dead-letter topic also catches messages
  that crash listeners.

Credentials come from Application Default Credentials;
`PUBSUB_EMULATOR_HOST` points the client at the emulator.

**Shutdown.** Listeners stop after the HTTP server and before the queue's
workers. They stop taking messages, give those being handled the grace
period, then cancel them. Those messages aren't given up on, whatever
`Tries` says: they are delivered again later (and the broker counts
that delivery).

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| Messages published before the first deploy never arrive | A subscription gets the messages published after it was created | Deploy the listener (or create the subscription) before publishing |
| A message is handled twice | At-least-once delivery | Make the listener idempotent |
| The same message keeps failing forever | No `Tries` (or Google without a dead-letter policy) | Set `Tries` and a `DeadLetter` topic |
| `NotFound … subscription projects/…` in the listener's logs (Google) | It wasn't created | Create it, or set `PUBSUB_GCP_CREATE=true` in development |
| `NOGROUP` errors (Redis) | The stream was deleted | The listener recreates its group; messages from before are gone |
| Two services share messages instead of each getting all | They use the same subscription name | Give each app its own `APP_NAME`, or `pubsub.Subscription` |

## Next steps

- [Queues](https://docs.anetos.dev/guides/queues/index.md): background jobs within one app.
- [Events](https://docs.anetos.dev/guides/events/index.md): in-process events, which can publish to a topic
  from a listener.
- [Runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md): process types and
  shutdown stages.

> **Coming from another framework?** Django, Laravel and Rails have no
> built-in consumer for a message broker: this replaces a separate
> worker process or a library running a read loop. A listener is like a
> queued job handler that other services dispatch to;
> `pubsub.Publish` sends an event to other services.


# Mail, files, search and cache

Source: https://docs.anetos.dev/guides/mail-files-search-and-cache/

- [Send email](https://docs.anetos.dev/guides/mail/index.md): Send email from your app: a receipt, a welcome message, a password reset link. An email is a **mailable**, a type that builds its message from its fields, with an HTML body from a templ component. Send it now, or queue it so a worker sends it with retries. The complete app is [`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue), which emails a receipt for each order.
- [Store files](https://docs.anetos.dev/guides/storage/index.md): Store files your app receives or makes: uploads, avatars, exports, invoices. Files go on **disks**: a disk is a named place files are kept, which is a local directory by default, or an S3-compatible bucket (Amazon S3, Cloudflare R2, MinIO, …) or a Google Cloud Storage bucket, with the same code. Private files are read through temporary signed URLs. The complete app is [`examples/files`](https://github.com/anetos-dev/anetos/tree/main/examples/files).
- [Add full-text search](https://docs.anetos.dev/guides/search/index.md): Give users a search box that finds what they mean: every word they type, in any of the columns you choose, best matches first. Search runs on your database's own full-text engine (PostgreSQL, MySQL/MariaDB or SQLite), with an index built by a migration; there's no search server to run. The complete example is [`examples/forms`](https://github.com/anetos-dev/anetos/tree/main/examples/forms), a notes app with a search box.
- [Cache](https://docs.anetos.dev/guides/cache/index.md): Keep the results of slow work for a while, count events for rate limits, and use locks so only one instance of the app does a job at a time.


# Send email

Source: https://docs.anetos.dev/guides/mail/

Send email from your app: a receipt, a welcome message, a password reset
link. An email is a **mailable**, a type that builds its message from its
fields, with an HTML body from a templ component. Send it now, or queue
it so a worker sends it with retries. The complete app is
[`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue), which emails a receipt for
each order.

## Before you start

You have an app created with `anetos.New()`. For queued email, set up the
[queue](https://docs.anetos.dev/guides/queues/index.md) first.

Choose how emails are sent with `MAIL_DRIVER`:

| Driver | Emails are | Use it for |
|---|---|---|
| `log` (default) | Written to the app's log, with their text body: not sent | Development |
| `smtp` | Sent to the SMTP server of `MAIL_SMTP_URL` | Production with any provider; development with Mailpit |
| `memory` | Kept in the process | Tests (`anetostest` sets it) |
| `postmark` | Sent with Postmark's API (`plugins/postmark`, `MAIL_POSTMARK_TOKEN`) | Production with Postmark |

Set the sender of your emails with `MAIL_FROM_ADDRESS` (and
`MAIL_FROM_NAME`, which defaults to `APP_NAME`), and `APP_URL`, the
app's public URL, for links in emails:

```env
MAIL_DRIVER=smtp
MAIL_SMTP_URL=smtps://apikey:secret@smtp.example.com:465
MAIL_FROM_ADDRESS=orders@shop.example.com
APP_URL=https://shop.example.com
```

To see emails in development without sending them anywhere, run
[Mailpit](https://mailpit.axllent.org) and set `MAIL_DRIVER=smtp`: the
default `MAIL_SMTP_URL` is Mailpit's, `smtp://127.0.0.1:1025`.
`MAIL_SMTP_URL` holds the host, port, user, password and TLS mode in
one URL: there are no separate `MAIL_HOST` or `MAIL_PORT` keys.

## Steps

### 1. Write the email's template

The HTML body is a templ component. Mail clients ignore most CSS, so use
inline styles and a simple layout:

```templ
// ReceiptEmail is the receipt's HTML body. Mail clients ignore most CSS,
// so the styles are inline and the layout is one column. Links leave the
// app: mailer.URL makes them absolute, with APP_URL.
templ ReceiptEmail(e OrderPlaced) {
	<!DOCTYPE html>
	<html>
		<body style="margin:0;padding:24px;background:#f4f4f5;font-family:Arial,sans-serif;color:#18181b">
			<div style="max-width:560px;margin:0 auto;padding:24px;background:#ffffff;border-radius:8px">
				<h1 style="margin:0 0 16px;font-size:20px">Thanks for your order</h1>
				<p>Order { strconv.FormatInt(e.OrderID, 10) }: { e.Item }, { price(e.Cents) }.</p>
				<p>We'll charge your card shortly.</p>
				<p><a href={ mailer.URL(ctx, "/orders/"+strconv.FormatInt(e.OrderID, 10)) } style="color:#2563eb">See your order</a></p>
			</div>
		</body>
	</html>
}
```

(Copied from [`examples/queue/receipt.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/receipt.templ), region `template`.)

`mailer.URL(ctx, path)` returns the absolute URL of a path on `APP_URL`,
or an error without it, which fails the send. Links in emails leave the
app, so relative links don't work.

### 2. Write a mailable

A mailable is a type with a `Build` method that returns the message:

```go
// ReceiptMail is the email of an order's receipt. Its fields are what it
// needs; Build turns them into the message, with the HTML body from the
// ReceiptEmail templ component (receipt.templ). The text body is made
// from the HTML.
type ReceiptMail struct {
	Order OrderPlaced
}

// Build implements mailer.Mailable.
func (m ReceiptMail) Build(ctx context.Context) (*mailer.Message, error) {
	return &mailer.Message{
		To:       []mailer.Address{{Address: m.Order.Email}},
		Subject:  fmt.Sprintf("Your receipt for order %d", m.Order.OrderID),
		HTML:     ReceiptEmail(m.Order),
		Tag:      "receipt",
		Metadata: map[string]string{"order_id": strconv.FormatInt(m.Order.OrderID, 10)},
	}, nil
}
```

(Copied from [`examples/queue/mail.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/mail.go), region `mailable`.)

`Build` gets the context of the send, with the app's values: it can read
the database. The message's fields:

| Field | |
|---|---|
| `To`, `Cc`, `Bcc` | Recipients, `mailer.Address{Name, Address}`: at least one in all |
| `From`, `ReplyTo` | The sender (default `MAIL_FROM_ADDRESS`), and where replies go |
| `Subject` | The subject line |
| `HTML` | The HTML body, a templ component (or any `view.Component`) |
| `Text` | The plain-text body, a string (build it with `fmt` or `text/template`; templ would HTML-escape it). Without it, the text of the HTML: paragraphs, lists, and links followed by their URL |
| `Attachments` | Files: `mailer.Attachment{Filename, Data}` (the content type comes from the name); with a `ContentID`, inline, shown by `<img src="cid:…">` |
| `Headers` | Extra headers, such as `List-Unsubscribe` (not those the message sets: `From`, `Subject`, `Content-Type`, …) |
| `Tag`, `Metadata` | Labels that API drivers keep with the email (Postmark) |

A `*mailer.Message` is a mailable too, for one-off emails.

### 3. Set up the mailer

In `setup`; with `queue.New` too, before or after it, for queued email:

```go
// With the queue, mailer.Queue sends from a queue job.
if _, err := mailer.New(app, postmark.Driver()); err != nil { // MAIL_DRIVER: log, smtp, memory or postmark
	return nil, err
}
```

(Copied from [`examples/queue`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main.go), region `mail-setup`.)

Drivers in other modules, such as `postmark.Driver()`, are passed to
`mailer.New`; `MAIL_DRIVER` picks one. Postmark's comes with the
[plugin](https://docs.anetos.dev/guides/plugins/index.md) `anetos.dev/anetos/plugins/postmark`
(`anetos add anetos.dev/anetos/plugins/postmark`), which also
records the addresses Postmark stopped sending to, from its webhooks:
check them with `postmark.Suppressed(ctx, email)` before sending.

### 4. Send or queue

`mailer.Send(ctx, mailable)` sends now and returns the transport's error.
In a queue job, that error makes the job retry:

```go
// recordAudit writes to the audit log in the order's transaction: if it
// fails, the order isn't placed.
func recordAudit(ctx context.Context, e OrderPlaced) error {
	return db.Create(ctx, &AuditEntry{OrderID: e.OrderID, Message: "placed: " + e.Item})
}

// countSale updates the sales counts in the background, once the order
// is committed. If the process stops first, the count is lost: fine for
// a dashboard.
func (s *Sales) countSale(_ context.Context, e OrderPlaced) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	s.Orders++
	s.Cents += e.Cents
	return nil
}

// emailReceipt sends the receipt, as a queue job: retried if the mail
// server fails, and not lost if the process stops. It skips addresses
// Postmark stopped sending to (the postmark plugin's list).
func emailReceipt(ctx context.Context, e OrderPlaced) error {
	if bad, err := postmark.Suppressed(ctx, e.Email); err != nil || bad {
		return err
	}
	return mailer.Send(ctx, ReceiptMail{Order: e})
}
```

(Copied from [`examples/queue/events.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/events.go), region `listeners`.)

In a request, queue the email instead: `mailer.Queue` renders it now
and dispatches a job that sends it, so the request doesn't wait for the
mail server, and a failure is retried:

```go
// ResendReceipt emails an order's receipt again. mailer.Queue renders the
// email now and sends it from a queue job: the request doesn't wait for
// the mail server, and a failure is retried.
func ResendReceipt(c *web.Ctx, in OrderID) (web.Responder, error) {
	o, err := db.Find[Order](c, in.ID)
	if err != nil {
		return nil, err
	}
	e := OrderPlaced{OrderID: o.ID, Item: o.Item, Cents: o.Cents, Email: o.Email}
	if err := mailer.Queue(c, ReceiptMail{Order: e}); err != nil {
		return nil, err
	}
	return web.JSON(http.StatusAccepted, map[string]string{"receipt": "queued"}), nil
}
```

(Copied from [`examples/queue/mail.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/mail.go), region `queue`.)

`mailer.Queue` takes the dispatch's options: `queue.OnQueue("emails")`,
`queue.Delay(d)`, `queue.AfterCommit()`. The email's `Date` is when the
job sends it. Errors that retrying won't fix, such as an address the
server rejects, fail the job at once.

The job carries the rendered email, attachments included, and a job
that fails for good keeps it in the failed jobs (`queue:failed`): think
of that for emails with password reset links.

**Language.** An email is built and rendered in the language of the
context it is sent or queued with: a request's, at first. To write in the
recipient's language (and show times in their zone), pass
`i18n.ForUser(ctx, user)`: it uses the user's `PreferredMailLocale`, else
their `PreferredLocale` ([Translations](https://docs.anetos.dev/guides/translations/index.md#5-respect-users-preferences)). For big attachments,
dispatch a job of your own that builds the email and calls
`mailer.Send`.

### 5. Preview emails

`mailer.Preview` returns a handler that shows a mailable's HTML body in
the browser. Serve it only in development:

```go
if app.Config().Env.IsDevelopment() {
	r.Get("/dev/mail/receipt", web.WrapHandler(mailer.Preview(previewReceipt)))
}
```

(Copied from [`examples/queue`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main.go), region `preview`.)

`previewReceipt` is a `func(*http.Request) mailer.Mailable` that returns
the email with made-up values.

### 6. Test

`anetostest` sets `MAIL_DRIVER=memory`: emails are kept, not sent. It
records each mailable sent with `mailer.Send` or queued with
`mailer.Queue`, for `anetostest.AssertMailSent`, `AssertMailQueued`
and `AssertMailNotSent`, which check its type and fields. The rendered
emails are the mailer's transport's, a `*mailer.MemoryTransport` whose
`Sent` returns them:

```go
// The receipt is queued (the sync driver sends it at once) and kept by
// the memory transport: the test checks its recipient, subject and body.
func TestResendReceipt(t *testing.T) {
	fakeGateway(t, &FakeGateway{})
	app := anetostest.New(t, setup, anetostest.Env(map[string]string{"QUEUE_DRIVER": "sync"}))
	id := placeOrder(t, app, "Lamp", 4250)

	app.PostJSON(fmt.Sprintf("/orders/%d/receipt", id), nil).AssertStatus(http.StatusAccepted)
	anetostest.AssertMailSent(app, func(m ReceiptMail) bool { return m.Order.OrderID == id })   // by the listener
	anetostest.AssertMailQueued(app, func(m ReceiptMail) bool { return m.Order.OrderID == id }) // again

	sent := sentMail(app)
	if len(sent) != 2 { // when placed, and again
		t.Fatalf("%d emails", len(sent))
	}
	m := sent[1]
	if m.To[0].Address != "ada@example.com" || m.Subject != fmt.Sprintf("Your receipt for order %d", id) {
		t.Errorf("email %+v", m)
	}
	for _, want := range []string{"Lamp, $42.50", fmt.Sprintf("See your order (http://example.test/orders/%d)", id)} {
		if !strings.Contains(m.Text, want) {
			t.Errorf("the text lacks %q:\n%s", want, m.Text)
		}
	}
	app.PostJSON("/orders/999/receipt", nil).AssertNotFound()
}
```

(Copied from [`examples/queue/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main_test.go), region `test-mail`.)

Each sent email is a `*mailer.Outgoing`: `To`, `Subject`, `HTML`,
`Text`, `Attachments`, … To test a mailable alone, render it with
`m.Render(ctx, mailable)`.

## SMTP settings

`MAIL_SMTP_URL` is the server, with the user and password URL-encoded:

| URL | Connection |
|---|---|
| `smtp://user:pass@smtp.example.com:587` | Upgraded with STARTTLS, which the server must offer (default port 587) |
| `smtps://user:pass@smtp.example.com:465` | TLS from the start (default port 465) |
| `smtp://127.0.0.1:1025` | A local server (127.0.0.1, ::1, localhost): STARTTLS if offered |
| `smtp://relay.internal:25?tls=none` | No TLS, for a relay on a private network; it can't take a password (an error at startup) |

The password is sent only over TLS or to a local server, with AUTH PLAIN
(or LOGIN when the server offers only that). Other parameters:
`timeout=30s` bounds each email (default 30 seconds), and
`local_name=app.example.com` is the name sent in EHLO (default: the
machine's). Each email opens its own connection.

A recipient the server refuses fails the whole email, for every
recipient: permanently for replies in the 500s, except 552 (a full
mailbox), which is retried. Addresses with non-ASCII characters
(`zoë@example.com`) need a server that offers SMTPUTF8.

## How it works

`Send` calls the mailable's `Build`, renders the HTML (and text)
components with the context, generates the text body from the HTML if
there is none, fills in the sender and a `Message-ID`, and checks the
result: valid addresses, at least one recipient, no line breaks in the
subject, names or headers, and no header line over the standard's
length (long values are folded, non-ASCII ones encoded). The rendered
email, a `mailer.Outgoing`, goes to the transport, which checks it
again.

`Queue` does the same, then dispatches the `mail:send` queue job with the
`Outgoing` as its JSON payload; `mailer.New` registers that job when
the app has a queue. The job keeps its `Message-ID` across retries
(Postmark gives each email its own).

SMTP builds the message itself (multipart text and HTML, inline files,
attachments, encoded headers), with the standard library: Bcc recipients
are in the SMTP envelope only. Postmark gets the same fields as JSON.
Transports report errors that retrying won't fix (SMTP replies in the
500s; Postmark's 422, 401, 403 and 413, except "not allowed to send",
error code 405, such as an account out of credits) as permanent, so the
queue fails the job at once.

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| Emails appear in the log instead of being sent | `MAIL_DRIVER` is `log`, the default | Set `MAIL_DRIVER=smtp` (or `postmark`) |
| `the message has no sender` | `MAIL_FROM_ADDRESS` isn't set | Set it, or the message's `From` |
| `URL needs the app's public URL` | `APP_URL` isn't set | Set `APP_URL=https://…` |
| `Queue needs the app's queue` | The app has no queue, or got it after booting | Call `queue.New` in `setup` |
| `doesn't offer SMTPUTF8` | An address with non-ASCII characters, and a server that can't take them | Use the address's ASCII form, or a server with SMTPUTF8 |
| `doesn't offer STARTTLS` | The server has no TLS on that port | Use `smtps://` (port 465), or `tls=none` for a private relay |
| `unencrypted connection` | A password without TLS to a remote server | Use TLS; passwords aren't sent in the clear |
| Links in emails are wrong | `APP_URL` is the development URL in production | Set `APP_URL` per environment |
| The email looks different in Gmail or Outlook | Mail clients drop `<style>` and most CSS | Inline styles, tables or single columns, no scripts |

## Next steps

- [Queues](https://docs.anetos.dev/guides/queues/index.md): workers and retries, for queued email.
- [Events](https://docs.anetos.dev/guides/events/index.md): send email from a queued event listener.
- [Use plugins](https://docs.anetos.dev/guides/plugins/index.md): the Postmark plugin's webhook and
  suppression list.
- [Configuration reference](https://docs.anetos.dev/reference/configuration/index.md#mail): the
  `MAIL_*` settings.

> **Coming from another framework?** A mailable is what Laravel calls a
> mailable and Rails a mailer method, and what a Django app builds as an
> `EmailMessage`: `Build` returns the subject, the content and the
> attachments, and the view is a templ component. `mailer.Send(ctx, m)`
> sends it to the mailable's recipients, and `mailer.Queue` sends it
> from the queue, rendered when queued. There are no Markdown mailables
> or notifications yet.


# Store files

Source: https://docs.anetos.dev/guides/storage/

Store files your app receives or makes: uploads, avatars, exports,
invoices. Files go on **disks**: a disk is a named place files are kept,
which is a local directory by default, or an S3-compatible bucket
(Amazon S3, Cloudflare R2, MinIO, …) or a Google Cloud Storage bucket,
with the same code. Private files are read through temporary signed URLs. The complete
app is [`examples/files`](https://github.com/anetos-dev/anetos/tree/main/examples/files).

## Before you start

You have an app created with `anetos.New()`. Choose where files are kept
with `STORAGE_DRIVER`:

| Driver | Files are kept | Use it for |
|---|---|---|
| `local` (default) | In the directory `STORAGE_ROOT` (default `storage/app`) | One server, development |
| `s3` | In an S3-compatible bucket (`drivers/s3`, `STORAGE_S3_*`) | Several servers, production |
| `gcs` | In a Google Cloud Storage bucket (`drivers/gcs`, `STORAGE_GCS_*`) | Apps on Google Cloud |
| `memory` | In the process | Tests (`anetostest` sets it) |

A disk can also have a URL its files are served at, `STORAGE_URL`, and be
**public** (`STORAGE_PUBLIC=true`: anyone can read its files at that URL)
or private (the default: files are read through temporary URLs only).

```env
STORAGE_DRIVER=local
STORAGE_URL=https://example.com/files
```

## Steps

### 1. Set up storage

In `setup`:

```go
st, err := storage.New(app, s3.Driver()) // STORAGE_DRIVER: local, memory or s3
if err != nil {
	return nil, err
}
avatars, err := st.Disk("avatars") // STORAGE_DISKS=avatars, STORAGE_AVATARS_*
if err != nil {
	return nil, err
}
```

(Copied from [`examples/files`](https://github.com/anetos-dev/anetos/blob/main/examples/files/main.go), region `setup`.)

Pass the drivers of the stores you use: `s3.Driver()` for S3,
`gcs.Driver()` for Google Cloud Storage (step 6), or both.

The default disk is configured with `STORAGE_*`. Name more disks in
`STORAGE_DISKS`, and configure each with `STORAGE_<NAME>_*`: the example's
public avatars disk is

```env
STORAGE_DISKS=avatars
STORAGE_AVATARS_URL=https://example.com/avatars
STORAGE_AVATARS_PUBLIC=true
```

A named disk takes the default disk's driver unless it sets its own, and
its S3 connection (region, endpoint, keys, path style) or GCS
credentials and signer unless it sets any of them; its directory defaults to `storage/<name>`, and its bucket must
be set.

### 2. Store uploads

Bind the upload to a `*multipart.FileHeader` field, validate it, and
store it with `PutUpload`:

```go
// UploadInput is a document to store: a PDF, PNG or JPEG of at most 5 MB.
// mimetypes checks the file's content, extensions its name.
type UploadInput struct {
	File *multipart.FileHeader `form:"file" validate:"required|max_size:5MB|mimetypes:application/pdf,image/png,image/jpeg|extensions:pdf,png,jpg,jpeg"`
}

// UploadDocument stores the file under a name of its own: a random one,
// with the upload's extension. The client's file name isn't used in the
// path.
func UploadDocument(c *web.Ctx, in UploadInput) (web.Responder, error) {
	disk, err := storage.From(c)
	if err != nil {
		return nil, err
	}
	name := randomName() + strings.ToLower(path.Ext(in.File.Filename))
	if err := disk.PutUpload(c, "documents/"+name, in.File); err != nil {
		return nil, err
	}
	doc, err := document(c, disk, name)
	if err != nil {
		return nil, err
	}
	return web.JSON(http.StatusCreated, doc), nil
}
```

(Copied from [`examples/files/documents.go`](https://github.com/anetos-dev/anetos/blob/main/examples/files/documents.go), region `upload`.)

`storage.From(ctx)` returns the default disk; `storage.DiskFrom(ctx, "avatars")`
a named one. Choose the path yourself: the file name an upload comes with
is the client's, so it may be anything.

Paths are relative and slash-separated: `documents/42.pdf`. A path with
`..`, a leading `/`, a backslash or a control character is an error
(`storage.ErrInvalidPath`), not cleaned, so a path built from user input
can't reach outside the disk. Other ways to store:

| Method | Stores |
|---|---|
| `disk.Put(ctx, path, r)` | What an `io.Reader` reads |
| `disk.PutBytes(ctx, path, data)` | A byte slice |
| `disk.PutUpload(ctx, path, fileHeader)` | An upload |
| `disk.Copy(ctx, src, dst)`, `disk.Move(ctx, src, dst)` | Another file's content |

A file is replaced whole: readers see the old content or the new, never
part. The content type comes from the path's extension (or, without one,
the content, never as HTML or another type a browser would run);
`storage.ContentType("…")` sets it on S3 and memory disks. Local disks
keep no content types: they give the extension's, so give files the
right extension.

### 3. Read and list files

```go
// ListDocuments lists the documents, in order of name.
func ListDocuments(c *web.Ctx) error {
	disk, err := storage.From(c)
	if err != nil {
		return err
	}
	docs := []Document{}
	for info, err := range disk.List(c, "documents/") {
		if err != nil {
			return err
		}
		url, err := disk.TemporaryURL(c, info.Path, 15*time.Minute)
		if err != nil {
			return err
		}
		docs = append(docs, Document{Name: strings.TrimPrefix(info.Path, "documents/"), Size: info.Size, UploadedAt: info.ModTime, URL: url})
	}
	return c.JSON(http.StatusOK, docs)
}
```

(Copied from [`examples/files/documents.go`](https://github.com/anetos-dev/anetos/blob/main/examples/files/documents.go), region `list`.)

| Method | Returns |
|---|---|
| `disk.Get(ctx, path)` | The content, `[]byte` |
| `disk.Open(ctx, path)` | A `storage.File` to read (and `Close`), with its `Info()` |
| `disk.Stat(ctx, path)` | A `storage.FileInfo`: `Path`, `Size`, `ModTime`, `ContentType`, `ETag` |
| `disk.Exists(ctx, path)` | Whether there is a file |
| `disk.List(ctx, prefix)` | The files whose paths start with `prefix`, in order of path (`"documents/"`: a directory and its subdirectories) |
| `disk.Delete(ctx, paths…)`, `disk.DeleteAll(ctx, "dir/")` | Removes files (`DeleteAll`: a directory's, recursively); a missing file is no error |

A missing file is `storage.ErrNotFound`, which a handler can return: it
becomes a 404, as does an invalid path.

### 4. Give out URLs

A private file is read through a temporary URL:

```go
// document describes the stored document name, with a URL that reads it
// for 15 minutes: signed by the app for a local disk, presigned by the
// bucket on S3.
func document(c *web.Ctx, disk *storage.Disk, name string) (Document, error) {
	info, err := disk.Stat(c, "documents/"+name)
	if err != nil {
		return Document{}, err // 404 if there is no such document
	}
	url, err := disk.TemporaryURL(c, info.Path, 15*time.Minute)
	if err != nil {
		return Document{}, err
	}
	return Document{Name: name, Size: info.Size, UploadedAt: info.ModTime, URL: url}, nil
}
```

(Copied from [`examples/files/documents.go`](https://github.com/anetos-dev/anetos/blob/main/examples/files/documents.go), region `temporary-url`.)

On S3, `TemporaryURL` is a URL presigned by the bucket (up to 7 days).
On a local disk, it is `STORAGE_URL` with the path and a token signed
with `APP_KEY`, which the disk's handler checks: mount it at
`STORAGE_URL`'s path.

```go
// Local disks' files, at their STORAGE_URL. The default disk isn't
// public: its handler serves only temporary URLs. (Files on S3 are
// served by the bucket.)
r.Get("/files/{path...}", web.WrapHandler(st.Default().Handler()))
r.Get("/avatars/{path...}", web.WrapHandler(avatars.Handler()))
```

(Copied from [`examples/files`](https://github.com/anetos-dev/anetos/blob/main/examples/files/main.go), region `serve`.)

The handler serves a file with its content type, length, `ETag` and
modification time, and answers conditional requests and requests for one
range (a request for several gets the whole file). Files a browser would
run (`storage.IsActive`: HTML, SVG and other XML, JavaScript, CSS) are
sent as `application/octet-stream` downloads in a sandbox, so an
uploaded file can't run on your site, not even through `<script src>`.
Without a valid token, a private disk's handler answers 403; tokens
expire, and work only for their file and disk.

A public disk's files have permanent URLs, `disk.URL(path)`:

```go
// AvatarInput is an image of at most 1 MB. extensions matters: the
// stored file's type comes from its extension.
type AvatarInput struct {
	Avatar *multipart.FileHeader `form:"avatar" validate:"required|image|extensions:png,jpg,jpeg,gif,webp|max_size:1MB"`
}

// UploadAvatar stores the image on the public avatars disk and returns
// its permanent URL.
func UploadAvatar(c *web.Ctx, in AvatarInput) (web.Responder, error) {
	avatars, err := storage.DiskFrom(c, "avatars")
	if err != nil {
		return nil, err
	}
	p := randomName() + strings.ToLower(path.Ext(in.Avatar.Filename))
	if err := avatars.PutUpload(c, p, in.Avatar); err != nil {
		return nil, err
	}
	url, err := avatars.URL(p)
	if err != nil {
		return nil, err
	}
	return web.JSON(http.StatusCreated, map[string]string{"url": url}), nil
}
```

(Copied from [`examples/files/documents.go`](https://github.com/anetos-dev/anetos/blob/main/examples/files/documents.go), region `avatar`.)

To check who may read a file before sending it, serve it from your own
handler with `disk.Serve(c.Writer(), c.Request(), path)`.

### 5. Use S3

Pass `s3.Driver()` to `storage.New` (from `drivers/s3`) and set:

```env
STORAGE_DRIVER=s3
STORAGE_S3_BUCKET=example-uploads
STORAGE_S3_REGION=eu-west-1
STORAGE_S3_ACCESS_KEY=AKIA…
STORAGE_S3_SECRET_KEY=…
```

For other S3-compatible stores, set the endpoint:

| Store | Settings |
|---|---|
| Cloudflare R2 | `STORAGE_S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com`, `STORAGE_S3_REGION=auto` |
| MinIO | `STORAGE_S3_ENDPOINT=http://127.0.0.1:9000`, `STORAGE_S3_PATH_STYLE=true` |
| Backblaze B2, DigitalOcean Spaces, … | Their S3 endpoint and region |

Without keys, the AWS environment variables, shared credentials file or
the instance's role are used. `STORAGE_S3_PREFIX` (a directory, ending
in `/`) puts the disk's files under a prefix of the bucket, so disks can
share one. For a public disk on S3, make the bucket (or the prefix)
readable with a bucket policy, or put a CDN in front, and set
`STORAGE_URL` to the URL of the disk's files (the prefix included:
`https://cdn.example.com/avatars`).

The bucket serves files itself, so the S3 driver stores the types a
browser would run with `Content-Disposition: attachment`. A missing
bucket is an error, not a missing file.

### 6. Use Google Cloud Storage

Pass `gcs.Driver()` to `storage.New` (from `drivers/gcs`) and set:

```env
STORAGE_DRIVER=gcs
STORAGE_GCS_BUCKET=example-uploads
```

On Cloud Run, GKE or Compute Engine that is all: the service account of
the service or instance is used (Application Default Credentials).
Elsewhere:

- On your machine, `gcloud auth application-default login`, or
- a service account key: `STORAGE_GCS_CREDENTIALS_FILE=/secrets/key.json`,
  or its JSON in `STORAGE_GCS_CREDENTIALS` for platforms that keep
  secrets in the environment. These two take service account keys only;
  other credentials (workload identity federation, impersonation) go
  through `GOOGLE_APPLICATION_CREDENTIALS`.

The account needs the Storage Object Admin role on the bucket (Storage
Object Viewer for a read-only disk).

Temporary URLs are V4 signed URLs (up to 7 days). A service account key
signs them itself, with no network call. Without one (Cloud Run, gcloud
credentials), each URL is signed by a call to the IAM API (enable the
IAM Service Account Credentials API, `iamcredentials.googleapis.com`), as
the service's account or `STORAGE_GCS_SIGNER`:

- On Cloud Run, give the service's account the Service Account Token
  Creator role on itself.
- With your gcloud credentials, set `STORAGE_GCS_SIGNER` to a service
  account's email, on which *you* need that role.

A page that links many files makes as many calls: sign links when they
are clicked (a route that redirects to `TemporaryURL`) rather than for
every row.

`STORAGE_GCS_PREFIX` (a directory, ending in `/`) puts the disk's files
under a prefix of the bucket, as with S3: a disk can read a folder of a
bucket other tools write to (`STORAGE_REPORTS_GCS_PREFIX=exports/`).

For local development without Google Cloud, run
[fake-gcs-server](https://github.com/fsouza/fake-gcs-server) over HTTP
and point the client at it; a service account key (any, even one of a
test project) signs temporary URLs on the emulator:

```sh
fake-gcs-server -scheme http -port 4443 -external-url http://localhost:4443
export STORAGE_EMULATOR_HOST=localhost:4443
```

Like S3, the bucket serves files itself: active types are stored with
`Content-Disposition: attachment`, and a missing bucket is an error
(when a file is read or listed). Objects other tools stored compressed
(`Content-Encoding: gzip`, from `gsutil -z` or
`gcloud storage cp --gzip-local`) are read decompressed, without range
requests. The Cloud Storage client is large: the driver adds about
40 MB to a binary, which matters for container images.

### 7. Test

`anetostest` sets `STORAGE_DRIVER=memory`: each test app's files are in
memory. `app.PostMultipart` uploads files, and the temporary URLs are on
the test client's site (`http://example.test`), so the test can fetch
them:

```go
// Upload a document, then read it through its temporary URL, which the
// default disk's handler serves.
func TestDocuments(t *testing.T) {
	app := anetostest.New(t, setup, env)

	var doc Document
	app.PostMultipart("/documents", nil, anetostest.Upload{Field: "file", Filename: "Invoice.PDF", Content: pdf}).
		AssertStatus(http.StatusCreated).
		JSON(&doc)
	if !strings.HasSuffix(doc.Name, ".pdf") || doc.Size != int64(len(pdf)) {
		t.Errorf("document %+v", doc)
	}
	app.Get(doc.URL).AssertOK().AssertHeader("Content-Type", "application/pdf").AssertSee("a tiny document")
	app.Get("/files/documents/" + doc.Name).AssertStatus(http.StatusForbidden) // no token

	var docs []Document
	app.GetJSON("/documents").AssertOK().JSON(&docs)
	if len(docs) != 1 || docs[0].Name != doc.Name {
		t.Errorf("documents %+v", docs)
	}
	app.Delete("/documents/" + doc.Name).AssertNoContent()
	app.Get(doc.URL).AssertNotFound()
}
```

(Copied from [`examples/files/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/files/main_test.go), region `test`.)

`app.Disk()` and `app.Disk("avatars")` check the disks' files, and
`app.Travel` moves the clock past a temporary URL's expiry:

```go
// The upload is on the default disk, and its temporary URL stops working
// after 15 minutes: the test travels in time instead of waiting.
func TestDocumentLink(t *testing.T) {
	app := anetostest.New(t, setup, env)
	uploaded := app.Freeze(time.Time{})

	var doc Document
	app.PostMultipart("/documents", nil, anetostest.Upload{Field: "file", Filename: "q3.pdf", Content: pdf}).
		AssertStatus(http.StatusCreated).
		JSON(&doc)
	app.Disk().AssertContent("documents/"+doc.Name, string(pdf))
	app.Disk("avatars").AssertMissing("documents/" + doc.Name)
	if !doc.UploadedAt.Equal(uploaded) {
		t.Errorf("uploaded at %v, want %v", doc.UploadedAt, uploaded)
	}

	app.Travel(14 * time.Minute)
	app.Get(doc.URL).AssertOK()
	app.Travel(2 * time.Minute)
	app.Get(doc.URL).AssertStatus(http.StatusForbidden)
}
```

(Region `test-disk`.)

## How it works

A `storage.Disk` checks paths, sets content types and builds URLs; its
`storage.Backend` keeps the files. Backends implement `Put`, `Open`,
`Stat`, `Delete`, `List` and `Copy`, and `storage/storagetest` is the
conformance suite each runs.

- **Local** files are opened through an `os.Root`, so neither a path nor
  a symbolic link reaches outside `STORAGE_ROOT`. `Put` writes a
  temporary file, syncs it, renames it over the old one and syncs the
  directory; if the process dies meanwhile, the temporary file
  (`.anetos-tmp-…`) stays behind, unlisted. Content types come from
  extensions; empty directories are left after deletes. A local disk
  can't hold both a file `a` and a file `a/b`.
- **S3** reads an object in one request (a read after a `Seek` asks for
  a range, and fails if the object was replaced since); a reader whose
  size is known is uploaded in one request (or parts, when large, up to
  S3's 5 TB), others in 8 MB parts (up to 78 GB). An upload canceled
  midway removes its parts. `List` doesn't give content types.
- **Temporary URLs** of local and memory disks carry the disk's name, the
  path and the expiry, encrypted with `APP_KEY` (so rotating it, with
  `APP_PREVIOUS_KEYS`, keeps them working).

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| `the disk has no URL (set STORAGE_URL)` | `TemporaryURL` or `URL` on a disk without a URL | Set `STORAGE_URL` (or `STORAGE_<NAME>_URL`), and mount the disk's handler there |
| `isn't public: use TemporaryURL` | `URL` on a private disk | Use `TemporaryURL`, or make the disk public |
| 403 from the handler | No token, an expired one, or one for another file | Use a fresh `TemporaryURL` |
| `invalid path` | `..`, a leading `/`, `//`, a backslash or a control character | Build paths from IDs and random names |
| Files missing after a deploy | A local disk on a server whose disk is replaced | Use a persistent volume, or S3 |
| Files differ between servers | A local disk on each server | Use S3 when several servers run the app |
| `no disk named …` | `From(ctx, name)` for a disk not in `STORAGE_DISKS` | Add it to `STORAGE_DISKS` |
| `gcs: signing a URL: …` | GCS credentials without a private key, and no account allowed to sign | Give the service account the Service Account Token Creator role on itself, or set `STORAGE_GCS_SIGNER` |
| `could not find default credentials` (GCS) | No credentials outside Google Cloud | `gcloud auth application-default login`, or `STORAGE_GCS_CREDENTIALS_FILE` |
| A stylesheet, script or SVG from a disk downloads instead of loading | Disks serve active types as downloads | Serve your own assets with `view.NewAssets`; disks are for files users give you |

## Next steps

- [Validation](https://docs.anetos.dev/guides/validation/index.md): `max_size`, `mimetypes`, `extensions` and
  `image` for uploads.
- [Configuration reference](https://docs.anetos.dev/reference/configuration/index.md#storage): the
  `STORAGE_*` settings.

> **Coming from another framework?** A disk is what Django calls a
> storage, Laravel a filesystem disk and Rails an Active Storage
> service: `storage.From(ctx)` is the default one, and `STORAGE_DISKS`
> with `STORAGE_<NAME>_*` replaces a config file. `PutUpload` stores an
> upload, and `TemporaryURL` gives a signed URL (for local disks too).
> No public directory or symlink is needed: the disk's handler serves
> local files. Visibility is per disk (`STORAGE_PUBLIC`), not per file, since
> S3 buckets now block per-object ACLs by default.


# Add full-text search

Source: https://docs.anetos.dev/guides/search/

Give users a search box that finds what they mean: every word they type,
in any of the columns you choose, best matches first. Search runs on
your database's own full-text engine (PostgreSQL, MySQL/MariaDB or
SQLite), with an index built by a migration; there's no search server to
run. The complete example is [`examples/forms`](https://github.com/anetos-dev/anetos/tree/main/examples/forms),
a notes app with a search box.

## Before you start

You have an app with a database (`db.Connect`) and migrations
(`migrate.New`), as `anetos new` makes it. The columns to search hold
text.

## Steps

### 1. Add a search index

In a migration, list the columns to search, most important first:
matches in earlier columns weigh more.

```go
Migrations.AddFunc("2026_10_02_120000_add_search_to_notes",
	func(s *migrate.Schema) error {
		return s.Alter("notes", func(t *migrate.Table) {
			t.SearchIndex("title", "body") // titles weigh more
		})
	},
	func(s *migrate.Schema) error {
		return s.Alter("notes", func(t *migrate.Table) { t.DropSearchIndex() })
	})
```

(Copied from [`examples/forms/models.go`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/models.go), region `search-index`.)

`t.SearchIndex` works in `Create` too. In `Alter`, the rows already in
the table are indexed. Run it:

```bash
go run . migrate
```

### 2. Search

`Search` keeps the rows that match every word of the text and orders them
by relevance, best first:

```go
func (Notes) Index(c *web.Ctx, in ListNotes) (web.Responder, error) {
	// Newest first; the ID breaks ties between notes created in the same
	// instant, so no note shows on two pages. With search words, the
	// best matches come first, then the newest. Search of no words
	// changes nothing.
	page, err := db.Query[Note](c).OrderBy(NoteCols.CreatedAt.Desc(), NoteCols.ID.Desc()).
		Search(in.Q).
		Paginate(in.Page, 10)
	if err != nil {
		return nil, err
	}
	return web.Render(NotesPage(page, in.Q)), nil
}
```

(Copied from [`examples/forms/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main.go), region `index`.)

Each word of three letters or more matches as a prefix ("tea" finds
"teas", "gree tea" finds "green tea"), in any of the indexed columns;
shorter words match whole words only ("go" finds "go", not "golang"),
and only the first ten words count (so that a search box can't be
made to scan most of the index). Punctuation is ignored, and
text without words (an empty search box) leaves the query as it was.
`Search` combines with `Where`, soft deletes, `Paginate`, `Count`,
`Pluck` and the aggregates. Its ranking comes first; `OrderBy` terms,
before or after it, break ties. A `Distinct` or `GroupBy` query still
searches, but has no relevance order (its rows aren't the rows the
ranking scores), only its `OrderBy`.

### 3. Add the search box

A `GET` form with a `q` field is enough; the page links keep `q`
(`web.PageURL` keeps the query string):

```templ
// NotesPage lists one page of notes, with links to the pages around it
// (they keep the search words, q) and a search box.
templ NotesPage(page db.Page[Note], q string) {
	@Layout("All notes") {
		<h1>Notes</h1>
		<p><a href={ web.URL(ctx, "notes.new") }>New note</a></p>
		<form method="get" action={ web.URL(ctx, "notes.index") } role="search">
			<input type="search" name="q" value={ q } aria-label="Search notes"/>
			<button type="submit">Search</button>
		</form>
		if page.Total == 0 && q != "" {
			<p>No notes match “{ q }”.</p>
		} else if page.Total == 0 {
			<p>No notes yet.</p>
		}
		<ul class="notes">
			for _, n := range page.Data {
				@noteItem(n)
			}
		</ul>
		<nav class="pages">
			if page.HasPrev() {
				<a href={ web.PageURL(ctx, min(page.CurrentPage-1, page.LastPage)) } rel="prev">Newer</a>
			}
			if page.LastPage > 1 {
				<span>Page { page.CurrentPage } of { page.LastPage }</span>
			}
			if page.HasNext() {
				<a href={ web.PageURL(ctx, page.CurrentPage+1) } rel="next">Older</a>
			}
		</nav>
	}
}
```

(Copied from [`examples/forms/notes.templ`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/notes.templ), region `list`.)

The notes app writes its own markup. In a project made with
`anetos new`, build the box from the components of `views/ui`
(`ui.Form` with `"GET"`, `ui.Input`, `ui.Button`), as the
[tutorial's search page](https://docs.anetos.dev/getting-started/tutorial/05-search.md) does,
or as [below](https://docs.anetos.dev/guides/search/index.md#search-a-list-made-with-makecrud).

Bound the input (`validate:"max:200"` on `Q`): a search box shouldn't
accept a novel.

### 4. Test it

```go
func TestSearch(t *testing.T) {
	app := anetostest.New(t, setup)
	anetostest.Create(app, NoteFactory.With(func(n *Note) { n.Title, n.Body = "Groceries", "Rice, lentils and green tea" }))
	anetostest.Create(app, NoteFactory.With(func(n *Note) { n.Title, n.Body = "Tea tasting", "Darjeeling first flush" }))
	anetostest.Create(app, NoteFactory.With(func(n *Note) { n.Title, n.Body = "Ideas", "A blog about Go" }))

	// Every word must match, as a prefix from 3 letters; title matches
	// rank first.
	app.Get("/notes?q=tea").AssertOK().
		AssertSee("<strong>Tea tasting</strong>", "<strong>Groceries</strong>", `value="tea"`).
		AssertDontSee("<strong>Ideas</strong>")
	if page := app.Get("/notes?q=tea").Text(); strings.Index(page, "Tea tasting") > strings.Index(page, "Groceries") {
		t.Error("the title match isn't first")
	}
	app.Get("/notes?q=green+lent").AssertSee("<strong>Groceries</strong>").AssertDontSee("<strong>Tea tasting</strong>")
	app.Get("/notes?q=coffee").AssertSee("No notes match “coffee”.")
}
```

(Copied from [`examples/forms/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/forms/main_test.go), region `test-search`.)

Tests use an in-memory SQLite database by default. On MySQL and MariaDB,
full-text indexes only see committed rows, so a search test there needs
`anetostest.WithoutTransaction()`: its rows are committed, so the test
deletes them itself:

```go
// illustrative
app := anetostest.New(t, setup, anetostest.WithoutTransaction())
t.Cleanup(func() {
	if _, err := db.Query[models.Post](app.Context()).ForceDelete(); err != nil {
		t.Error(err)
	}
})
```

### Search a list made with make:crud

The pages `make:crud` writes take a search box in three changes, with
the components of `views/ui` and with their text in the locale file.
For `posts`, after the migration of step 1:

1. The list's input takes the words, in `app/handlers/posts.go`, and the
   query searches them:

   ```go
   // illustrative
   type PostList struct {
   	Page int    `query:"page"`
   	Q    string `query:"q" validate:"max:200"`
   }

   page, err := db.Query[models.Post](c).OrderBy(models.PostCols.ID.Desc()).
   	Search(in.Q).
   	Paginate(in.Page, 20)
   if err != nil {
   	return nil, err
   }
   return web.Render(views.PostsPage(page, in.Q)), nil
   ```

2. The page shows the box under its header, in `views/posts.templ`
   (`PostsPage(page db.Page[models.Post], q string)`), and says when
   nothing matches. In place of the `if page.Total == 0 {` line and its
   `ui.Empty`:

   ```templ
   // illustrative
   @ui.Form(web.MustURL(ctx, "posts.index"), "GET", templ.Attributes{"role": "search"}) {
   	@ui.Cluster() {
   		@ui.Input("q", "search", q, templ.Attributes{"aria-label": i18n.T(ctx, "posts.search")})
   		@ui.Button(ui.Secondary, nil) {
   			{ i18n.T(ctx, "posts.search") }
   		}
   	}
   }
   if page.Total == 0 && q != "" {
   	@ui.Empty(i18n.T(ctx, "posts.no_match", "q", q))
   } else if page.Total == 0 {
   	@ui.Empty(i18n.T(ctx, "posts.empty"))
   } else {
   ```

   The `else` block, the table and the page links, stays as it was.

3. Its text goes in `locales/en/posts.yaml`, under `posts:`:

   ```yaml
   search: "Search"
   no_match: "No posts match “{q}”."
   ```

The page links keep `q` (`web.PageURL` keeps the query string).

## Choose the settings

Two settings, in `.env`, decide how every search index is built and
queried:

| Setting | Values | Default |
|---|---|---|
| `DB_SEARCH_LANGUAGE` | `simple`: words as written, in any language. `english` (PostgreSQL, SQLite): also their other forms ("runs" finds "running"). On PostgreSQL, any text search configuration: `german`, `french`, `spanish`… | `simple` |
| `DB_SEARCH_RANKING` | `default`: the database's own ranking. `bm25`: BM25, which weighs rare words more and long texts less | `default` |

`simple` with prefix matching is the default because it's right for
every language (Bangla, Hindi and mixed content included) and behaves
the same on every database; pick a language when all your content is in
it. Changing either setting needs the indexes rebuilt:

```bash
go run . search:reindex          # all of them; or name the tables
```

### What each database can do

| | PostgreSQL | SQLite | MySQL, MariaDB |
|---|---|---|---|
| `DB_SEARCH_LANGUAGE` | `simple`, `english` and the server's other text search configurations | `simple`, `english` | `simple` only |
| `DB_SEARCH_RANKING=bm25` | PostgreSQL 17+ with the [pg_textsearch](https://github.com/timescale/pg_textsearch) extension (in `shared_preload_libraries`, then `CREATE EXTENSION pg_textsearch`) | built in | not available |
| Column weights | yes | yes | no: columns count alike |
| Common words ("the", "and") | ignored with a language other than `simple`; a search of only those finds nothing | searched | not indexed (stop words), like words shorter than 3 characters (`innodb_ft_min_token_size`): they only find longer words they start, and are optional next to other words |
| Accents ("cafe" finds "Café") | no | yes | yes, with the default accent-insensitive collation |
| Scripts with combining marks (Bangla, Hindi…) | yes | yes | yes |

These are checked when the app starts: a setting the database can't
serve stops the app with a message saying which setting, which database,
and what to do:

```text
blog serve: anetos: provider "db.Connect(mysql)": boot: db: DB_SEARCH_RANKING=bm25 needs BM25 ranking, which this MySQL/MariaDB database doesn't have: MySQL and MariaDB don't have it; use SQLite, or PostgreSQL with pg_textsearch
blog serve: anetos: provider "db.Connect(sqlite)": boot: db: the search indexes of notes (built for DB_SEARCH_LANGUAGE=simple, DB_SEARCH_RANKING=default) don't match DB_SEARCH_LANGUAGE=english, DB_SEARCH_RANKING=default: rebuild them with the search:reindex command, or set the settings back
```

`migrate` and `search:reindex` still run when only the indexes are out of
date (they're how you fix it). Your own features can declare what they
need from the database the same way: `d.Require("my feature", db.BM25)`,
checked at boot.

## How it works

`t.SearchIndex` builds the database's own index, and records it (columns,
language, ranking) in the `search_indexes` table:

- **PostgreSQL**: a generated `search_vector` column (`tsvector`, the
  columns weighted A, B, C, D) with a GIN index. `Search` matches
  `search_vector @@ to_tsquery(…)` and ranks with `ts_rank_cd`; with BM25,
  a generated `search_text` column with a `bm25` index ranks first.
- **MySQL, MariaDB**: a generated `search_text` column with a `FULLTEXT`
  index, matched in boolean mode with every word required. Words the
  index skips (short words, stop words) are optional prefixes instead,
  or required ones when the search has no other words.
- **SQLite**: an FTS5 table, `<table>_search`, kept in sync by triggers
  on the table, ranked with its `bm25()`.

The generated columns are the database's, not your model's: your structs
don't change. Search words are reduced to letters, digits and marks
before they reach the database, and travel as parameters.

The index follows inserts, updates and deletes in the same transaction
(on MySQL, at commit). Database search serves most apps: it is exact,
needs no extra service, and stays consistent with the data. For typo
tolerance, facets or very large collections, a search engine
(Meilisearch, Typesense, OpenSearch) is the next step; it's on the
roadmap behind the same `Search` method.

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| `… (does notes have a search index? …)` | No `t.SearchIndex` for the model's table, or the migration hasn't run | Add it in a migration; `go run . migrate` |
| The app doesn't start: `the search indexes of … don't match` | `DB_SEARCH_LANGUAGE` or `DB_SEARCH_RANKING` changed since the indexes were built | `go run . search:reindex` |
| The app doesn't start: `DB_SEARCH_LANGUAGE=english isn't available on MySQL/MariaDB` | MySQL can't stem words | `DB_SEARCH_LANGUAGE=simple`, or PostgreSQL or SQLite |
| The app doesn't start: `needs BM25 ranking` | The database has no BM25 | `DB_SEARCH_RANKING=default`, or install pg_textsearch on PostgreSQL 17+ |
| "Go" or "the" doesn't find "Go" or "the" on MySQL | MySQL doesn't index words shorter than 3 characters, or stop words; they only find longer words they start | Expected; lower `innodb_ft_min_token_size` on the server and rebuild, or use PostgreSQL or SQLite |
| Results of a `Distinct` or `GroupBy` search aren't best first | Those queries have no relevance order | Order them with `OrderBy`, or drop `Distinct` |
| `CursorPaginate can't page through Search results` | Results are ordered by relevance, which has no cursor | Use `Paginate` |
| `Rename … has a search index` | Renaming a searchable table | `DropSearchIndex`, rename, `SearchIndex` again |
| `… is in the search index` when dropping or renaming a column | The index is built from it | In the same `Alter`: `DropSearchIndex`, the change, then `SearchIndex` with the new columns |
| `search:reindex`: `its indexed column … is gone` | The column was dropped outside a migration's `Alter` | `DropSearchIndex` and `SearchIndex` again in a migration |

## Next steps

- [Query data](https://docs.anetos.dev/guides/queries/index.md): conditions, ordering and pagination that
  combine with `Search`.
- [Search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md): embeddings, and hybrid search
  that combines them with this index.
- [Migrations reference](https://docs.anetos.dev/reference/migrations/index.md#search-indexes): the
  objects each database gets.
- [Configuration reference](https://docs.anetos.dev/reference/configuration/index.md#search):
  `DB_SEARCH_LANGUAGE`, `DB_SEARCH_RANKING`.

> **Coming from another framework?** This is full-text search in the
> database, as Django's `django.contrib.postgres.search`, Laravel
> Scout's database engine or Rails' pg_search give: the migration
> declares what's searchable, and the database's full-text index (not
> `LIKE`) does the matching and ranking. Search engines (Meilisearch,
> Algolia, Typesense) are on the roadmap as drivers behind the same
> `Search`.


# Cache

Source: https://docs.anetos.dev/guides/cache/

Keep the results of slow work for a while, count events for rate limits,
and use locks so only one instance of the app does a job at a time.

## Before you start

Choose a store with `CACHE_DRIVER`:

| Store | `CACHE_DRIVER` | Shared between instances | Needs |
|---|---|---|---|
| Memory | `memory` (default) | No: each process has its own | Nothing |
| Database | `database` | Yes | `db.Connect`, and the table from `cache.Migrations` |
| Redis | `redis` | Yes | A Redis (or Valkey) server, and the `drivers/redis` module |

The memory store suits one instance and development. With several
instances, use the database or Redis store: otherwise each instance
caches its own copy, and locks only work within one process.

## Steps

### 1. Set up the cache

Call `cache.New` while setting up the app, after `db.Connect`:

```go
// CACHE_DRIVER (default memory) picks the store; database uses the
// cache table from cache.Migrations.
if _, err := cache.New(app); err != nil {
	return nil, err
}
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `cache`.)

It adds the cache to every context the app creates (handlers, commands,
components), closes the store at shutdown and adds the `cache:clear`
command.

For the database store, add the table's migration to the runner:

```go
if _, err := migrate.New(app, []*migrate.Set{Migrations, cache.Migrations("")}, migrate.WithSeeders(Seeders...)); err != nil {
	return nil, err
}
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `runner`.)

`cache.Migrations("")` creates the table `cache`; pass the name if you
set `CACHE_TABLE`.

For Redis, add the driver module and pass its driver:

```sh
go get anetos.dev/anetos/drivers/redis
```

```go
// illustrative
if _, err := cache.New(app, redis.CacheDriver()); err != nil { // CACHE_DRIVER=redis, REDIS_URL
	return nil, err
}
```

### 2. Remember a value

`cache.Remember` returns the cached value, or calls the function, stores
its result for the ttl and returns it:

```go
// Stats serves the totals from the cache, computing them at most once a
// minute (and after a post is created or deleted).
func (Blog) Stats(c *web.Ctx, _ struct{}) ([]AuthorStats, error) {
	return cache.Remember(c, "stats", time.Minute, authorStats)
}
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `remember`.)

Values are stored as JSON, so any type that encodes and decodes with
`encoding/json` works: structs (exported fields), slices, maps, numbers.

If several requests miss the cache at once, the function runs once in
each process and the others wait for its result. If it returns an error,
nothing is stored and the error is returned.

### 3. Delete a value when its data changes

```go
// GET /stats counts the new post. The post is saved either way: a
// cache failure only delays that, so log it rather than fail.
if err := cache.Delete(c, "stats"); err != nil {
	c.Logger().Warn("forget the cached stats", "error", err)
}
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `forget`.)

Inside a transaction, forget in `db.AfterCommit` instead: otherwise a
request between the forget and the commit caches the old data again (see
[Transactions](https://docs.anetos.dev/guides/transactions/index.md#3-run-side-effects-after-commit)). Choose
the ttl as the staleness you accept if a write forgets to forget.

### 4. Read and write values directly

```go
// illustrative
err := cache.Set(ctx, "profile:7", profile, time.Hour) // cache.Forever: no expiry
profile, ok, err := cache.Get[Profile](ctx, "profile:7")
added, err := cache.Add(ctx, "welcome-mail:7", true, 24*time.Hour) // only if absent
ok, err := cache.Has(ctx, "profile:7")
err = cache.Delete(ctx, "profile:7")
err = cache.Flush(ctx) // every key of this app's cache
```

`Get` returns `ok == false` for a missing or expired key, and an error if
the stored value doesn't decode as the type you ask for.

Keys are UTF-8 text of up to 250 bytes, including the prefix
(`CACHE_PREFIX`, by default the app's name and `:cache:`), and compare
exactly (case, accents and spaces count). Build them from parts with a
separator, such as `"profile:" + id`.

### 5. Count events

`cache.Increment` adds to a counter atomically and returns the new
value. A new counter expires after the ttl, and increments don't extend
it, which makes a fixed window:

```go
// illustrative
n, err := cache.Increment(ctx, "logins:"+ip, 1, time.Minute)
if err != nil {
	return nil, err
}
if n > 5 {
	return nil, web.Error(http.StatusTooManyRequests, "Too many attempts; try again in a minute.")
}
```

For request limits, [Rate limiting](https://docs.anetos.dev/guides/rate-limiting/index.md) builds on this.
Pass a negative delta to decrement. Read a counter with
`cache.Get[int64]`. Incrementing a key that holds something other than
an integer, or past the range of `int64`, is an error.

### 6. Run work under a lock

A lock is held by one owner at a time, across every instance that shares
the store. `cache.TryWithLock` runs the function only if the lock is
free, which suits work one instance should do:

```go
// illustrative
err := cache.TryWithLock(ctx, "reports:monthly", 10*time.Minute, func(ctx context.Context) error {
	return buildMonthlyReport(ctx)
})
if errors.Is(err, cache.ErrLockHeld) {
	return nil // another instance is on it
}
```

`cache.WithLock` waits for the lock instead (until the context ends).
The ttl is how long a crashed holder can keep the lock: make it longer
than the work, or extend it as you go with `cache.NewLock`:

```go
// illustrative
lock := cache.NewLock(ctx, "import:"+name, time.Minute)
if err := lock.Acquire(ctx); err != nil {
	return err
}
defer lock.Release(context.WithoutCancel(ctx))
for batch := range batches {
	if ok, err := lock.Extend(ctx, time.Minute); err != nil {
		return err
	} else if !ok {
		return errors.New("the import took too long and lost its lock")
	}
	// ...
}
```

Locks are released only by their owner: after the ttl has passed,
another owner may hold the lock, and `Release` and `Extend` return
false.

### 7. Test

`anetostest.New` gives each test app a cache prefix of its own and
removes its items when the test ends, so tests don't see each other's
cached values:

```go
func TestStatsCache(t *testing.T) {
	app := anetostest.New(t, setup)
	ada := anetostest.Create(app, Authors.With(func(a *Author) { a.Name = "Ada" }))
	app.GetJSON("/stats").AssertJSONPath("0.posts", 0) // computed and cached

	// A post written behind the handlers' back isn't counted yet...
	anetostest.Create(app, Posts.With(func(p *Post) { p.AuthorID = ada.ID }))
	app.GetJSON("/stats").AssertJSONPath("0.posts", 0)

	// ...until a handler forgets the cached totals.
	app.PostJSON("/posts", map[string]any{"author_id": ada.ID, "title": "Hello", "body": "First post"}).AssertCreated()
	app.GetJSON("/stats").AssertJSONPath("0.posts", 2)
}
```

(Copied from [`examples/database/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main_test.go), region `test-cache`.)

## Clear the cache

```sh
go run . cache:clear
```

It removes the keys with the app's prefix, locks included, and leaves
other apps' keys in a shared store alone. Run it after a deploy that
changes the type of a cached value, or let `Remember` replace such values
as they are read (it logs a warning and recomputes them).

## Stores in detail

- **Memory**: expired items are removed when read, and the rest about
  once a minute. Items are gone when the process stops.
- **Database**: one row per key in the `cache` table, with the expiry
  in Unix milliseconds by the database server's clock, so instances
  whose clocks drift still agree. Expired rows are deleted every few
  minutes while the app writes to the cache. With PostgreSQL and MySQL,
  the store uses its own connections, not the request's transaction: a
  value cached or a lock taken inside a transaction stays if the
  transaction rolls back, and each cache call made inside a transaction
  needs a second connection from the pool, so keep `DB_MAX_OPEN_CONNS`
  above the number of transactions that run at once. SQLite allows one
  writer at a time, so there the store joins the transaction, and its
  writes roll back with it.
- **Redis**: items expire in Redis. `cache:clear` finds keys with
  `SCAN` and removes them with `UNLINK`, without blocking the server. The
  app shares one client, made by `redis.Connect`, between the cache and
  other Redis features. See [Redis settings](https://docs.anetos.dev/reference/configuration/index.md#redis).

A cache made by hand with `cache.NewWithStore(store, "")` has no prefix: its
`cache.Flush` empties the whole store, in Redis everything in the
database, sessions and queues included. `cache.New` always sets a
prefix.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `cache: no cache in context` | `cache.New` wasn't called, or the context didn't come from the app | Call it in setup; in code outside the app, use `cache.WithCache(ctx, c)` |
| `CACHE_DRIVER is "redis", but the drivers are [memory, database]` | The driver wasn't passed | `cache.New(app, redis.CacheDriver())` |
| `the database store needs the app's database` | `cache.New` ran before `db.Connect` | Connect the database first |
| `no such table: cache` / `relation "cache" does not exist` | The migration didn't run | Add `cache.Migrations("")` to the runner and run `migrate` |
| `holds something that isn't a …` | The cached value was stored as another type | `cache:clear`, or change the key when you change the type |
| Instances see different values; a lock doesn't exclude other instances | The memory store is per process | Use the database or Redis store |
| `redis: connect to …` at startup | The server isn't reachable at `REDIS_URL` | Check the URL, password and network |

## Next steps

- [Configuration reference: cache](https://docs.anetos.dev/reference/configuration/index.md#cache)
- [Rate limiting](https://docs.anetos.dev/guides/rate-limiting/index.md)
- [Background tasks](https://docs.anetos.dev/guides/background-tasks/index.md)
- [Transactions](https://docs.anetos.dev/guides/transactions/index.md)


# Languages and time

Source: https://docs.anetos.dev/guides/languages-and-time/

- [Translations](https://docs.anetos.dev/guides/translations/index.md): Show your app, its validation messages and error pages, and its emails in each user's language. Adding a language is adding a file.
- [Numbers, dates and languages](https://docs.anetos.dev/guides/formatting/index.md): Show numbers, prices, dates and times the way each user reads them, in their language and time zone, and add the framework's translations for a language with one command.
- [Times and dates](https://docs.anetos.dev/guides/times-and-dates/index.md): Store times without thinking about time zones, keep calendar dates on their day, and choose the zone your app works in.


# Translations

Source: https://docs.anetos.dev/guides/translations/

Show your app, its validation messages and error pages, and its emails
in each user's language. Adding a language is adding a file.

## Before you start

- An app made with `anetos new` has translations set up: `locales/` holds
  the English text and `main.go` loads it. For an older app, see step 2.
- Settings: `APP_LOCALE` (default `en`), `APP_FALLBACK_LOCALE` (default
  `en`), `APP_LOCALES`, `APP_LOCALE_STRATEGY` ([reference](https://docs.anetos.dev/reference/configuration/index.md)).

## Steps

### 1. Write the catalogs

A catalog is a YAML file in `locales/`, one per locale (`locales/en.yaml`)
or a folder of files (`locales/bn/app.yaml`, `locales/bn/auth.yaml`).
Nested keys join with dots: `home.welcome` below.

```yaml
# locales/en.yaml
app:
  title: "Greenhouse"
home:
  welcome: "Welcome, {name}!"
  plants:
    one: "You have {count} plant."
    other: "You have {count} plants."
```

```yaml
# locales/bn/app.yaml
app:
  title: "গ্রিনহাউস"
home:
  welcome: "স্বাগতম, {name}!"
  plants:
    one: "আপনার {count}টি গাছ আছে।"
    other: "আপনার {count}টি গাছ আছে।"
```

- `{name}` is a placeholder, filled when the message is used.
- A map of plural categories (`zero`, `one`, `two`, `few`, `many`,
  `other`) is a plural message. `other` is required; each language uses
  the categories its grammar has (English `one` and `other`, Arabic all
  six).
- A locale's folder may have subfolders (`locales/bn/admin/users.yaml`).
- Locale names are BCP 47 tags: `en`, `bn`, `pt-BR`. A key missing from
  `bn-BD` comes from `bn`, then from `APP_FALLBACK_LOCALE`, so a regional
  file only needs what differs.
- A plural form is also a key: `home.plants.one`. English never uses
  `zero` (0 is `other`); `locale:check` notes forms a language doesn't use.
- Quote values: `count: 3` is a number, not text, and is refused.

### 2. Load them

Embed the folder and give it to `i18n.New`, before the web server:

```go
// illustrative (locales/locales.go)
package locales

import "embed"

// FS holds the catalogs, for i18n.New.
//
//go:embed *
var FS embed.FS
```

```go
// setup loads the catalogs and adds the routes. The HTTP server finds
// each request's locale with the app's translator.
func setup(app *anetos.App) (*web.Server, error) {
	// locales.FS embeds locales/: en.yaml and bn/*.yaml.
	if _, err := i18n.New(app, locales.FS); err != nil {
		return nil, err
	}
	srv, err := web.NewServer(app)
	if err != nil {
		return nil, err
	}
	r := srv.Router()
	r.Get("/", home).Name("home")
	r.Post("/signup", web.H(signUp)).Name("signup")
	return srv, nil
}
```

(Copied from [`examples/i18n/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/i18n/main.go), region `setup`.)

The supported locales are `APP_LOCALE` and every locale with a catalog,
unless `APP_LOCALES` lists them. In development, `anetos dev` rebuilds
when a catalog changes, and keys missing from every catalog are logged
once.

### 3. Translate in code and templates

`i18n.T` returns a message in the request's language; `i18n.Plural`
picks the form for a number and fills `{count}`:

```go
// home greets the visitor in their language: ?name= and ?plants= fill
// the messages. Dates, prices and times follow the language too.
func home(c *web.Ctx) error {
	name := c.Query("name")
	if name == "" {
		name = "Ada"
	}
	plants, _ := strconv.Atoi(c.Query("plants"))
	now := anetos.Now(c)
	return c.Render(http.StatusOK, view.ComponentFunc(func(ctx context.Context, w io.Writer) error {
		_, err := fmt.Fprintf(w, `<!doctype html><html lang="%s" dir="%s"><title>%s</title><h1>%s</h1><p>%s</p><p>%s</p><p>%s</p><p>%s</p>%s`,
			i18n.Locale(ctx), i18n.Dir(ctx),
			html.EscapeString(i18n.T(ctx, "app.title")),
			html.EscapeString(i18n.T(ctx, "home.welcome", "name", name)),
			html.EscapeString(i18n.Plural(ctx, "home.plants", plants)),
			html.EscapeString(i18n.T(ctx, "home.today", "date", i18n.Date(ctx, now, i18n.Full))),
			html.EscapeString(i18n.T(ctx, "home.price", "price", i18n.Currency(ctx, 1250, "BDT"))),
			html.EscapeString(i18n.T(ctx, "home.watered", "when", i18n.Ago(ctx, now.Add(-3*time.Hour)))),
			switcher(ctx))
		return err
	}))
}

// switcher links to this page in each language the app supports, by the
// language's own name.
func switcher(ctx context.Context) string {
	var b strings.Builder
	b.WriteString("<nav>" + html.EscapeString(i18n.T(ctx, "nav.language")) + ":")
	for _, l := range i18n.From(ctx).Supported() {
		fmt.Fprintf(&b, ` <a href="%s" hreflang="%s">%s</a>`, html.EscapeString(web.LocaleURL(ctx, l)), l, html.EscapeString(i18n.LanguageName(ctx, l)))
	}
	b.WriteString("</nav>")
	return b.String()
}
```

(Copied from [`examples/i18n/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/i18n/main.go), region `home`.)

In templ, `ctx` is there already:

```go
// illustrative (views/layout.templ)
<html lang={ i18n.Locale(ctx) } dir={ i18n.Dir(ctx) }>
	<h1>{ i18n.T(ctx, "home.welcome", "name", user.Name) }</h1>
```

Arguments are pairs of names and values. A key no catalog has shows the
key itself, so a mistake is visible on the page; `locale:check` (step 7)
finds them before users do.

### 4. Choose how visitors get their language

A request's locale is worked out the first time something asks for it.
`APP_LOCALE_STRATEGY` decides how:

| `APP_LOCALE_STRATEGY` | URLs | A visitor who prefers Bangla |
|---|---|---|
| `none` (default) | `/about` in every language | sees `/about` in Bangla |
| `prefix` | `/about` (English, the default), `/bn/about` | opening `/about` is redirected to `/bn/about` |
| `subdomain` | `example.com/about`, `bn.example.com/about` (needs `APP_URL`) | opening `example.com` is redirected to `bn.example.com` |

With `none`, the locale is the first supported one of:

1. the `locale` cookie, set when the visitor chose a language on this
   device;
2. the session's `locale`;
3. the logged-in user's preference (step 5);
4. the browser's `Accept-Language`;
5. `APP_LOCALE`.

With `prefix` and `subdomain` the URL decides; an address without a
locale is in `APP_LOCALE`, so an unprefixed JSON API answers in it. The
redirect to the visitor's language only happens for pages (GET requests
for HTML, not API calls or htmx), and visiting a language's URL remembers
it in the cookie. Route URLs (`web.URL`, `c.URL`, `web.RedirectRoute`)
keep the current locale; for a literal path, use
`web.LocalePath(ctx, "/dashboard")`.

A language switcher links to `web.LocaleURL(ctx, locale)`, the current
page in that language: `/bn/about` with `prefix`, `bn.example.com/about`
with `subdomain`, `/about?locale=bn` with `none` (handled for pages only,
and only for a supported locale; other `locale` parameters reach your
routes). Following one remembers the choice. A settings form can call
`c.SetLocale(locale)` instead, which stores it in the cookie and the
session; `c.ForgetLocale()` drops them, back to the user's preference or
the browser's language.

A locale matches itself or its nearest supported parent (`bn-BD` →
`bn`), else a close regional variant (`fr-CH` → `fr-CA`).

### 5. Respect users' preferences

A user model can carry the language they read the site in, the one their
email and notifications should be in, and their time zone. Implement any
of these methods:

```go
// illustrative
type User struct {
	db.Model
	Locale     string `db:"locale"`      // the site's language
	MailLocale string `db:"mail_locale"` // email; empty: the site's
	TimeZone   string `db:"time_zone"`   // an IANA name: Asia/Dhaka
}

func (u *User) PreferredLocale() string     { return u.Locale }     // i18n.LocalePreference
func (u *User) PreferredMailLocale() string { return u.MailLocale } // i18n.MailLocalePreference
func (u *User) PreferredTimeZone() string   { return u.TimeZone }   // i18n.TimeZonePreference
```

With `auth.New`, a logged-in user's `PreferredLocale` is the request's
with `APP_LOCALE_STRATEGY=none` (unless they chose another on this device), and
`i18n.TimeZone(ctx)` is their zone, which `i18n.Date` and `i18n.Time`
show times in ([Numbers, dates and languages](https://docs.anetos.dev/guides/formatting/index.md)). A settings
page that saves their
language should also call `c.SetLocale`, so the cookie follows;
`i18n.TimeZones()` lists the zones to choose from (UTC, then one per
region of each country), as `make:auth`'s settings page does. To write
to a user, switch to their communication language first:

```go
// illustrative
err := mailer.Queue(i18n.ForUser(ctx, u), mails.Receipt{Order: o})
```

Mail is rendered when it is sent or queued, in the language of its
context. Queue jobs run in the locale and time zone of the context that
dispatched them, so a job dispatched by a Bangla page, or with
`i18n.ForUser`, writes Bangla.

### 6. Translate the framework's messages

The framework's own text (validation messages, error pages, login
messages, month names) is in its English catalog. For Bangla, French and
Spanish, copy the community's translations into your catalogs, with
`make:auth`'s pages and emails if you have them:

```sh
go tool anetos locale:add bn
```

([Numbers, dates and languages](https://docs.anetos.dev/guides/formatting/index.md#1-add-a-languages-formats-and-messages).)
It leaves out the keys your catalogs for the locale already define. For
another language, or to change a message, define the same keys in a
locale's catalog (or edit the copied file), or in `en` to change the
English:

```yaml
# locales/bn/validation.yaml
validation:
  required: "{label} দিতে হবে।"
  email: "{label} একটি সঠিক ইমেইল ঠিকানা হতে হবে।"
  min:
    numeric: "{label} কমপক্ষে {0} হতে হবে।"
  attributes:
    name: "নাম"
    email: "ইমেইল"
    plant_count: "গাছের সংখ্যা"
```

- `validation.<rule>` (and `validation.<rule>.string|numeric|array` for
  size rules) are the messages; the keys are listed in the
  [validation rules](https://docs.anetos.dev/reference/validation-rules/index.md#messages).
- `validation.attributes.<field>` is a field's label in messages; without
  it, the `label` tag (itself a key, if a catalog has it) or the field's
  name is used.
- `http.status.<code>` titles error pages; `http.csrf`,
  `http.invalid_data`, `binding.*` and `auth.*` are the other messages.
- A struct's `ValidationMessages` may give catalog keys instead of text,
  and a `web.HTTPError` its `Key` (and `Args` for its placeholders): they
  are translated.

`anetos make:auth` writes its pages' and emails' text to
`locales/en/auth.yaml`: `locale:add` brings its translation, or copy it to
`locales/bn/auth.yaml` and translate.

### 7. Check the catalogs

```sh
go run . locale:check
```

It reports, for each supported locale, the keys the fallback locale has
that it lacks, placeholders that differ, plural forms its language needs,
and keys the `.go` and `.templ` files use that no catalog has. A key the
code completes at run time, `i18n.T(ctx, "issues.status."+s)`, counts as
a prefix: some key must start with `issues.status.`. It exits
with status 1 when there is a problem, so it can run in CI, and it notes
the framework messages a locale leaves in English.

## Complete example

[`examples/i18n`](https://github.com/anetos-dev/anetos/tree/main/examples/i18n) has English and Bangla
catalogs, a switcher and translated validation:

```sh
go run ./examples/i18n
APP_LOCALE_STRATEGY=prefix go run ./examples/i18n
```

## How it works

Catalogs are read once, at startup. A key is looked up in the request's
locale, its parents, the fallback locale and its parents, then the
framework's English catalog. The request's locale is resolved when first
asked for, so routes that never translate don't pay for it. See
[internationalization](https://docs.anetos.dev/concepts/internationalization/index.md).

## Testing it

Send `Accept-Language` (or follow a `?locale=` link), then check the
text:

```go
func TestLanguages(t *testing.T) {
	app := anetostest.New(t, setup)
	app.Freeze(time.Date(2026, time.January, 15, 12, 0, 0, 0, time.UTC))

	// English by default; plurals follow the count.
	app.Get("/?plants=1").AssertOK().AssertSee(`lang="en"`, "Welcome, Ada!", "You have 1 plant.",
		"Today is Thursday, January 15, 2026.", "A seed pack costs BDT 1,250.00.", "Last watered 3 hours ago.")
	app.Get("/?plants=3").AssertSee("You have 3 plants.")

	// The browser's languages: words, digits, dates and prices in Bangla.
	app.WithHeader("Accept-Language", "bn-BD, en;q=0.8")
	app.Get("/?name=Rafi&plants=2").AssertSee(`lang="bn"`, "স্বাগতম, Rafi!", "আপনার ২টি গাছ আছে।",
		"আজ বৃহস্পতিবার, ১৫ জানুয়ারী, ২০২৬।", "১,২৫০.০০৳", "৩ ঘণ্টা আগে")

	// Validation messages and labels in the visitor's language.
	app.PostJSON("/signup", map[string]any{"email": "nope", "plant_count": 0}).AssertUnprocessable().
		AssertJSONPath("errors.name", "নাম দিতে হবে।").
		AssertJSONPath("errors.email", "ইমেইল একটি সঠিক ইমেইল ঠিকানা হতে হবে।").
		AssertJSONPath("errors.plant_count", "গাছের সংখ্যা কমপক্ষে ১ হতে হবে।")

	// A chosen language (?locale=, the switcher's links) beats the
	// browser's, and is remembered. The switcher names each language in
	// itself.
	app.Get("/?locale=en").AssertRedirect("/")
	app.Get("/").AssertSee(`lang="en"`, "Welcome, Ada!", `href="/?locale=bn" hreflang="bn">বাংলা</a>`)
}
```

(Copied from [`examples/i18n/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/i18n/main_test.go), region `test`.)

`i18n.WithLocale(ctx, "bn")` puts any other code in a locale, and the
translator's `Check` method runs `locale:check`'s checks in a test.

## Troubleshooting

| Problem | Cause | Fix |
|---|---|---|
| A page shows `home.welcome` | No catalog has the key, or it's misspelled | `go run . locale:check` |
| A language is never chosen | It isn't supported | Add its catalog, or list it in `APP_LOCALES` |
| `… is not a locale` at startup | A catalog file's name isn't a locale (`english.yaml`) | Name it `en.yaml`, or the folder `en/` |
| `… is 3, not text; quote it` | A number or `true` as a message | Quote it: `"3"` |
| `APP_LOCALE_STRATEGY=subdomain needs APP_URL` | The default locale's host is unknown | Set `APP_URL=https://example.com` |
| Email in the site's language, not the user's | The mail was built with the request's context | `mailer.Send(i18n.ForUser(ctx, u), …)` |


# Numbers, dates and languages

Source: https://docs.anetos.dev/guides/formatting/

Show numbers, prices, dates and times the way each user reads them, in
their language and time zone, and add the framework's translations for
a language with one command.

## Before you start

- Translations set up with `i18n.New` ([Translations](https://docs.anetos.dev/guides/translations/index.md)):
  an app made with `anetos new` has them.
- Everything below follows the request's locale (`i18n.Locale(ctx)`) and
  time zone (`i18n.TimeZone(ctx)`: the logged-in user's, or
  `APP_TIMEZONE`).

## Steps

### 1. Add a language's formats and messages

The framework's English catalog has its validation messages, error pages,
month and day names and date patterns. For another language, copy its
translations from [anetos.dev/locales](https://github.com/anetos-dev/locales):

```sh
go tool anetos locale:add bn fr
```

It writes `locales/bn/framework.yaml` (and `locales/bn/auth.yaml` if
your app has `make:auth`'s pages). The files are then yours: change any
message there.

- Keys your catalogs for the locale already define (a
  `locales/bn/validation.yaml` of your own) are left out, since a locale
  can't define a key twice; it lists them.
- A regional locale gets its language's translations: `bn-BD` writes
  `locales/bn/`.
- Without a locale it lists the languages available; `--force` replaces
  files you already have with the latest.
- Visitors can choose the language at once (unless `APP_LOCALES` lists
  the supported locales), and your own text shows in
  `APP_FALLBACK_LOCALE` until you translate it: `go run . locale:check`
  lists what's missing.

### 2. Format numbers and prices

```go
// illustrative
i18n.Number(ctx, 1234567.891)       // en: 1,234,567.891   bn: ১২,৩৪,৫৬৭.৮৯১   fr: 1 234 567,891
i18n.Fixed(ctx, 2.5, 2)             // en: 2.50
i18n.Percent(ctx, 0.256)            // en: 26%   fr: 26 %
i18n.Currency(ctx, 1234.5, "USD")   // en: $1,234.50   fr: 1 234,50 $US   bn: ১,২৩৪.৫০ US$
i18n.Currency(ctx, 1250, "BDT")     // en: BDT 1,250.00   bn: ১,২৫০.০০৳
```

- Grouping, separators and digits come from CLDR through
  `golang.org/x/text`: Indian grouping and Bangla digits for `bn`,
  Arabic-Indic digits for `ar`.
- `Currency` takes the amount in the currency's main unit (divide cents
  by 100) and an ISO 4217 code, rounds to the currency's usual decimals
  (none for JPY), and places the symbol with the catalog's
  `format.currency` pattern (`"{symbol}{amount}"` in English).
- `i18n.Plural` formats `{count}` the same way: "1,234 posts".
- Prefer Latin digits for a language? Set its numbering in the catalog:

  ```yaml
  # locales/bn/framework.yaml
  format:
    numbering: "latn"
  ```

### 3. Format dates and times

```go
// illustrative
i18n.Date(ctx, order.PlacedAt)               // en: Jan 15, 2026   bn: ১৫ জানু, ২০২৬
i18n.Date(ctx, user.Birthday, i18n.Long)     // an anetos.Date: January 15, 2026
i18n.Time(ctx, order.PlacedAt, i18n.Short)   // en: 8:04 PM   fr: 20:04
i18n.DateTime(ctx, order.PlacedAt)           // en: Jan 15, 2026, 8:04:05 PM
i18n.Format(ctx, order.PlacedAt, "EEE d MMM") // en: Thu 15 Jan   fr: jeu. 15 janv.
```

- A `time.Time` is shown in the user's zone, so "today" is their today:
  a time stored at 20:00 UTC is the next morning in Dhaka. An
  `anetos.Date` is a day and is shown as it is.
- The styles are `i18n.Short`, `i18n.Medium` (the default), `i18n.Long`
  and `i18n.Full`; each language's catalog has its patterns
  (`format.date.medium: "MMM d, y"`).
- `i18n.Format` takes a [CLDR pattern](https://docs.anetos.dev/reference/i18n-formats/index.md)
  for a layout of your own, with the language's names and digits.
- A zero time or date, or a nil `*time.Time` or `*anetos.Date`, gives an
  empty string.
- Month names, patterns and relative times come from the locale's own
  catalogs, else English: never from a fallback locale in another
  language.

### 4. Say how long ago

```go
// illustrative
i18n.Ago(ctx, comment.CreatedAt)      // just now, 3 minutes ago, in 2 days
i18n.Duration(ctx, 80*time.Minute)    // 1 hour
i18n.DurationUp(ctx, 80*time.Minute)  // 2 hours: for "try again in …"
```

`Ago` measures from the app's clock (`anetos.Now`), so tests can freeze
it; a zero time gives "". Amounts are in their largest unit, from
seconds to years: `Duration` rounds to the nearest, `DurationUp` up, so
a wait is never understated.

### 5. Mark up the page's language and direction

Set `lang` and `dir` on `<html>`, so browsers pick fonts and lay out
right-to-left languages (Arabic, Hebrew, Persian, Urdu) from the right:

```go
// illustrative (views/layout.templ)
<html lang={ i18n.Locale(ctx) } dir={ i18n.Dir(ctx) }>
	<head>
		for _, a := range web.Alternates(ctx) {
			<link rel="alternate" hreflang={ a.Locale } href={ a.URL }/>
		}
	</head>
```

`web.Alternates` lists the page's address in each language, and
`x-default`, for search engines, when `APP_LOCALE_STRATEGY` is `prefix` or
`subdomain` (with `none` a page has one address, and it returns nothing).
Set `APP_URL` so the addresses are absolute. A language switcher can name
each language in itself with `i18n.LanguageName(ctx, "bn")` ("বাংলা"),
from the catalog's `format.language`.

`anetos new` writes this layout.

### 6. Answer in the user's language from an AI model

Tell the model which language to use; the user's message alone may not
say:

```go
// illustrative
system := "Answer in " + i18n.LanguageName(ctx, i18n.Locale(ctx)) + "."
```

## Complete example

[`examples/i18n`](https://github.com/anetos-dev/anetos/tree/main/examples/i18n) shows a date, a price and a
relative time in English and Bangla:

```go
// home greets the visitor in their language: ?name= and ?plants= fill
// the messages. Dates, prices and times follow the language too.
func home(c *web.Ctx) error {
	name := c.Query("name")
	if name == "" {
		name = "Ada"
	}
	plants, _ := strconv.Atoi(c.Query("plants"))
	now := anetos.Now(c)
	return c.Render(http.StatusOK, view.ComponentFunc(func(ctx context.Context, w io.Writer) error {
		_, err := fmt.Fprintf(w, `<!doctype html><html lang="%s" dir="%s"><title>%s</title><h1>%s</h1><p>%s</p><p>%s</p><p>%s</p><p>%s</p>%s`,
			i18n.Locale(ctx), i18n.Dir(ctx),
			html.EscapeString(i18n.T(ctx, "app.title")),
			html.EscapeString(i18n.T(ctx, "home.welcome", "name", name)),
			html.EscapeString(i18n.Plural(ctx, "home.plants", plants)),
			html.EscapeString(i18n.T(ctx, "home.today", "date", i18n.Date(ctx, now, i18n.Full))),
			html.EscapeString(i18n.T(ctx, "home.price", "price", i18n.Currency(ctx, 1250, "BDT"))),
			html.EscapeString(i18n.T(ctx, "home.watered", "when", i18n.Ago(ctx, now.Add(-3*time.Hour)))),
			switcher(ctx))
		return err
	}))
}

// switcher links to this page in each language the app supports, by the
// language's own name.
func switcher(ctx context.Context) string {
	var b strings.Builder
	b.WriteString("<nav>" + html.EscapeString(i18n.T(ctx, "nav.language")) + ":")
	for _, l := range i18n.From(ctx).Supported() {
		fmt.Fprintf(&b, ` <a href="%s" hreflang="%s">%s</a>`, html.EscapeString(web.LocaleURL(ctx, l)), l, html.EscapeString(i18n.LanguageName(ctx, l)))
	}
	b.WriteString("</nav>")
	return b.String()
}
```

(Copied from [`examples/i18n/main.go`](https://github.com/anetos-dev/anetos/blob/main/examples/i18n/main.go), region `home`.)

## How it works

Numbers, percentages and currency symbols come from `golang.org/x/text`,
which carries CLDR's number data for every language. Dates don't: their
month and day names and patterns live in the catalogs' `format` section,
so a language brings its own and the framework needs no date library.
Relative times are plural messages (`relative.units.hour`). Formatters
are made once per locale. See
[internationalization](https://docs.anetos.dev/concepts/internationalization/index.md).

## Testing it

Freeze the clock, choose a language, and check the page:

```go
// illustrative
app.Freeze(time.Date(2026, time.January, 15, 12, 0, 0, 0, time.UTC))
app.WithHeader("Accept-Language", "bn")
app.Get("/").AssertSee("১৫ জানুয়ারী, ২০২৬", "১,২৫০.০০৳", "৩ ঘণ্টা আগে")
```

In a unit test, put a context in a locale and zone:
`i18n.WithTimeZone(i18n.WithLocale(ctx, "bn"), dhaka)`.

## Troubleshooting

| Problem | Cause | Fix |
|---|---|---|
| English month names on a Bangla page | The locale's catalog has no `format` section | `go tool anetos locale:add bn`, or add `format.months` and the rest |
| `format.months needs 12 names` from `locale:check` | A list of the wrong length (it is ignored) | Twelve months, seven days (Sunday first), two periods |
| A date is a day off | A `time.Time` shown in another zone, or a date kept in a `time.Time` | Use `anetos.Date` for days; check the user's `PreferredTimeZone` |
| `downloading anetos.dev/locales` fails | No network, or a proxy that blocks it | `locale:add --from <checkout of anetos-dev/locales>` |
| Digits you didn't expect | CLDR's digits for the language | `format.numbering: "latn"` in the catalog |


# Times and dates

Source: https://docs.anetos.dev/guides/times-and-dates/

Store times without thinking about time zones, keep calendar dates on
their day, and choose the zone your app works in.

## Before you start

- A database set up with `db.Connect` ([database guide](https://docs.anetos.dev/guides/database/index.md)).
- Nothing to configure: times are stored in UTC by default, and the app
  won't start against a database session in another zone.

## Steps

### 1. Store times as they are

Write `time.Time` values from any zone. The framework converts every
time it sends to the database to UTC (the query builder, `db.Create`,
raw SQL), opens database sessions in UTC and reads times back in UTC:

```go
// illustrative
order.PaidAt = anetos.Now(ctx) // in the app's zone (APP_TIMEZONE)
err := db.Save(ctx, &order)    // stored in UTC
```

A time in Dhaka and the same instant in UTC are stored alike, and
`created_at`/`updated_at` are set in UTC. There is no setting to forget at
the start of a project.

### 2. Keep dates in an `anetos.Date`

A birthday or a due date is a day, not an instant. In a `time.Time` it is
a midnight somewhere, and midnight in Dhaka is 18:00 the day before in
UTC, so it would be stored a day early. `anetos.Date` holds a year, month
and day with no zone:

```go
// illustrative
type Task struct {
	db.Model
	Title string      `db:"title"`
	Due   anetos.Date `db:"due"` // a DATE column: t.Date("due")
}

due := anetos.NewDate(2026, time.October, 3)
tasks, err := db.Query[Task](ctx).Where(TaskCols.Due.Lte(anetos.Today(ctx))).Get()
```

- Create the column with `t.Date("due")` in a migration. It is written as
  `2026-10-03` and read back on every database as the same day.
- `anetos.Today(ctx)` is today's date in the app's zone, on the app's
  clock. `anetos.DateOf(t)` is the date of a time in that time's own zone:
  convert first to see it elsewhere (`anetos.DateOf(t.In(loc))`).
- The zero `Date` is "no date": it is written as NULL and shown as an
  empty string. Use `*anetos.Date` where you need to tell them apart. A
  date that isn't on the calendar (February 30) is an error when written.
- Switching an existing `time.Time` field of a `DATE` column to
  `anetos.Date`? On SQLite the old rows hold `2026-03-15 00:00:00` and new
  ones `2026-03-15`, which compare as text: convert the old rows once,
  `UPDATE tasks SET due = date(due) WHERE due IS NOT NULL`. PostgreSQL and
  MySQL need nothing.

### 3. Take dates from forms and JSON

A `Date` field binds from `<input type="date">` (which sends
`2026-10-03`), from query strings and from JSON strings. The date rules
compare dates; `now` is today in the app's zone:

```go
// illustrative
type BookInput struct {
	CheckIn  anetos.Date `form:"check_in" validate:"required|after_or_equal:now"`
	CheckOut anetos.Date `form:"check_out" validate:"required|after:CheckIn"`
}
```

A value that isn't a date (`03/10/2026`) is rejected before validation,
as for other typed fields.

### 4. Choose the app's time zone

`APP_TIMEZONE` (an IANA name, default `UTC`) is the zone your app works
in:

```sh
APP_TIMEZONE=Asia/Dhaka
```

- It is the process's local zone, so `time.Now()`, log lines and
  formatted times agree on your laptop and on the server.
- `anetos.Now(ctx)` returns times in it and `anetos.Location(ctx)` returns
  it.
- Schedules use it unless `SCHEDULE_TIMEZONE` says otherwise
  ([scheduling](https://docs.anetos.dev/guides/scheduling/index.md)).

Storage doesn't change: times are UTC in the database whatever the app's
zone. Keep `UTC` unless your app serves one region and you want its
times in logs and schedules in local time. To show a time to a user in
their own zone and language, format it with `i18n.Date`, `i18n.Time` or
`i18n.DateTime` ([Numbers, dates and languages](https://docs.anetos.dev/guides/formatting/index.md)); to
convert it yourself, `t.In(i18n.TimeZone(ctx))`.

The zone database is built into the framework, so zone names work in
containers without one (`FROM scratch`, distroless).

## How it works

The rule is UTC in storage and the user's zone on display; the framework
enforces the first half. When the app boots, `db.Connect` checks the
database session's time zone: if `DB_URL` sets one other than UTC
(`timezone=` for PostgreSQL, `time_zone=` for MySQL), the app stops,
because `CURRENT_TIMESTAMP` and `NOW()` would then write local times next
to the app's UTC ones. See [the data layer](https://docs.anetos.dev/concepts/data-layer/index.md#times-are-utc).

## Testing it

`app.Freeze(at)` stops the app's clock at `at`; `anetos.Now` and
`anetos.Today` follow it, in the app's zone:

```go
// illustrative
app := anetostest.New(t, setup, anetostest.Env(map[string]string{"APP_TIMEZONE": "Asia/Dhaka"}))
app.Freeze(time.Date(2026, 3, 15, 20, 0, 0, 0, time.UTC))
anetos.Today(app.Context()) // 2026-03-16: it's already the 16th in Dhaka
```

In a test binary the process's local zone comes from `APP_TIMEZONE` in
the environment (UTC when unset), not from `.env` files, so tests that
run in parallel never change it; each app's `anetos.Now` is still in its
own zone. Export `APP_TIMEZONE` in CI if your app sets it in a `.env`
file and tests format times with `time.Now()`.

## Troubleshooting

| Problem | Cause | Fix |
|---|---|---|
| `the database session's time zone is …, not UTC` at startup | `DB_URL` sets a session time zone | Remove `timezone=`/`time_zone=` from `DB_URL`; for a legacy database whose times are local, set `DB_ALLOW_LOCAL_TIMEZONE=true` |
| A date is a day early | It was stored as a `time.Time` at a local midnight | Use `anetos.Date` for dates |
| `APP_TIMEZONE "…" is not an IANA time zone` | A name like `BST` or `GMT+6` | Use a region name: `Asia/Dhaka`, `Europe/London` |
| Logs show another zone than `APP_TIMEZONE` | Two apps with different zones in one process | A process has one local zone, the first app's; set the same `APP_TIMEZONE` |


# Working with AI

Source: https://docs.anetos.dev/guides/working-with-ai/

- [Add AI to your app](https://docs.anetos.dev/guides/ai/index.md): Use a language model in your app: summarize text into a typed struct, answer questions with tools that look up the user's own data, and stream the answer as it's written. Package `ai` does the work around the model: schemas, validation, the tool loop, logging and tests that never call a model. The complete example is [`examples/ai`](https://github.com/anetos-dev/anetos/tree/main/examples/ai), a small support desk API.
- [Build an AI assistant](https://docs.anetos.dev/guides/ai-assistant/index.md): Give your users a chat with an agent that answers from your app's data: conversations stored in the database, answers streamed to the page as they're written, slow questions answered in the background, and a usage budget per user.
- [Search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md): Find records by what they mean, not only by the words they share: "how much is the team plan" finds the article on plans and billing, which never says "how much". Each record's text is split into chunks, turned into vectors (embeddings) by an embedding model, and stored next to the record; a search embeds the question and returns the nearest records, with the passage that matched. With a full-text index too, the search is *hybrid*: records that its words find rank high as well, so names, codes and rare words aren't missed. An agent can use the search as a tool, to answer from your data (retrieval-augmented generation).


# Add AI to your app

Source: https://docs.anetos.dev/guides/ai/

Use a language model in your app: summarize text into a typed struct,
answer questions with tools that look up the user's own data, and stream
the answer as it's written. Package `ai` does the work around the model:
schemas, validation, the tool loop, logging and tests that never call a
model. The complete example is [`examples/ai`](https://github.com/anetos-dev/anetos/tree/main/examples/ai), a
small support desk API.

## Before you start

You have an app created with `anetos.New()`. Choose the provider with
`AI_PROVIDER`, and the model with `AI_MODEL`. Each provider is a driver
module, on the provider's official Go SDK, so your app depends only on
the SDKs it uses:

| `AI_PROVIDER` | Driver | Settings |
|---|---|---|
| `anthropic` | `anetos.dev/anetos/drivers/anthropic` | `ANTHROPIC_API_KEY` |
| `openai` | `anetos.dev/anetos/drivers/openai` | `OPENAI_API_KEY` |
| `openai-compatible` | the same, `openai.CompatibleDriver()`: Ollama, vLLM, LM Studio, OpenRouter, Groq… | `OPENAI_COMPATIBLE_URL`, and `OPENAI_COMPATIBLE_KEY` if the server needs one |
| `gemini` | `anetos.dev/anetos/drivers/gemini` | `GEMINI_API_KEY` |
| `fake` | built in: no model is called, requests get scripted replies | Tests (`anetostest` sets it) |

```env
AI_PROVIDER=anthropic
AI_MODEL=claude-haiku-4-5
ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
```

For a local model, run [Ollama](https://ollama.com) and point the
compatible driver at it: `AI_PROVIDER=openai-compatible`,
`OPENAI_COMPATIBLE_URL=http://localhost:11434/v1`, `AI_MODEL=llama3.2`.

`AI_MAX_TOKENS` (default 4096) bounds each answer's length, and
`AI_TIMEOUT` (default 10 minutes) each request's time. See
[Configuration](https://docs.anetos.dev/reference/configuration/index.md#ai). The app doesn't
start if the provider's key or `AI_MODEL` is missing.

## Steps

### 1. Set up the client

In your setup function, after `anetos.New()`, call `ai.New` with
the drivers of the providers your app may use (`AI_PROVIDER` picks one):

```go
// AI_PROVIDER picks one of these, AI_MODEL the model.
if _, err := ai.New(app, anthropic.Driver(), openai.Driver(), openai.CompatibleDriver(), gemini.Driver()); err != nil {
	return nil, err
}
```

(Copied from [`examples/ai`](https://github.com/anetos-dev/anetos/tree/main/examples/ai), region `setup`.)

`ai.New` puts the client in every context the app creates: requests,
jobs, listeners, commands. Calls find it there.

### 2. Generate text

`ai.Generate` sends a prompt and returns the answer, with the tokens it
used:

```go
// illustrative
res, err := ai.Generate(ctx, "Summarize in one sentence: "+post.Body,
	ai.System("You write for a general audience."))
if err != nil {
	return err
}
fmt.Println(res.Text(), res.Usage.InputTokens, res.Usage.OutputTokens)
```

In a request handler, a call runs within the server's limits:
`HTTP_REQUEST_TIMEOUT` (30 seconds by default) cancels the request's
context, and with it the call (a 503). An agent that calls a few tools,
or a long answer, can take longer: raise it for your app (`0` disables
it), or keep model calls short.

Options shape the call: `ai.System` (instructions), `ai.Model`,
`ai.MaxTokens`, `ai.Temperature`, `ai.Timeout`. To continue a
conversation, pass the previous result's messages:
`ai.Generate(ctx, "And in French?", ai.Messages(res.Messages...))`.
Messages marshal to JSON, so you can store a conversation and continue it
in a later request. Continue only from a successful call: after an error,
the conversation can end with tool calls that have no results, which
providers refuse. (An answer cut off at the token limit doesn't run its
tool calls: they get error results, so the conversation stays valid.)

### 3. Get a typed answer

Describe the answer as a struct. `ai.GenerateObject` gives the model its
JSON schema, built from the `json`, `description` and `validate` tags,
and checks the answer with the `validate` rules:

```go
// Summary is a customer message, summarized. The model is given its
// schema, built from the json, description and validate tags, and its
// answer is checked with the validate rules.
type Summary struct {
	Topic     string   `json:"topic" description:"What the message is about, in a few words" validate:"required|max:60"`
	Sentiment string   `json:"sentiment" validate:"required|in:positive,neutral,negative"`
	Urgent    bool     `json:"urgent" description:"Whether the customer needs an answer today"`
	Tags      []string `json:"tags" description:"Lower-case keywords" validate:"max:5"`
}

// SummarizeInput is a customer's message.
type SummarizeInput struct {
	Text string `json:"text" validate:"required|max:5000"`
}

// Summarize summarizes a customer's message.
func Summarize(c *web.Ctx, in SummarizeInput) (Summary, error) {
	sum, _, err := ai.GenerateObject[Summary](c, "Summarize this customer message:\n\n"+in.Text,
		ai.System("You triage a support inbox."))
	return sum, err
}
```

(Copied from [`examples/ai`](https://github.com/anetos-dev/anetos/tree/main/examples/ai), region `summary`.)

If the answer isn't valid JSON of that shape, or breaks a rule
(`sentiment` isn't one of the three), it goes back to the model once,
with what's wrong: a second call, with the same options and its own
step limit. A second failure returns an `*ai.OutputError`, which a
handler turns into a 502 response. An answer cut off at the token limit,
or a refusal, isn't retried.

### 4. Give the model tools

A tool is a Go function the model can call. Its input is a struct, with
the same tags; the model's input is checked before the function runs:

```go
// FindOrderInput is the find_order tool's input, as the model writes it.
type FindOrderInput struct {
	Number int `json:"number" description:"The order's number" validate:"required|min:1"`
}

// findOrder looks up an order of the current customer. It runs with the
// request's context: another customer's order is "not found", as it would
// be in the customer's own browser, and the model is told so.
var findOrder = ai.NewTool("find_order", "Look up one of the customer's orders by its number",
	func(ctx context.Context, in FindOrderInput) (Order, error) {
		i := slices.IndexFunc(orders, func(o Order) bool { return o.Number == in.Number && o.Customer == customer(ctx) })
		if i < 0 {
			return Order{}, web.Error(http.StatusNotFound, "The customer has no such order.")
		}
		return orders[i], nil
	})

// support answers customers' questions about their orders.
var support = ai.Agent{
	Name:         "support",
	Instructions: "You answer the customer's questions about their orders, briefly. Look orders up; never guess.",
	Tools:        []ai.Tool{findOrder},
	MaxSteps:     5,
}
```

(Copied from [`examples/ai`](https://github.com/anetos-dev/anetos/tree/main/examples/ai), region `tool`.)

An `ai.Agent` bundles instructions, tools and options to reuse. Prompt it
from a handler:

```go
// Question is a customer's question; the header stands in for
// authentication.
type Question struct {
	Customer string `header:"X-Customer" validate:"required"`
	Question string `json:"question" validate:"required|max:500"`
}

// Answer is the agent's answer, with the tokens it took.
type Answer struct {
	Answer       string `json:"answer"`
	InputTokens  int64  `json:"input_tokens"`
	OutputTokens int64  `json:"output_tokens"`
}

// Ask answers a question with the support agent.
func Ask(c *web.Ctx, in Question) (Answer, error) {
	ctx := context.WithValue(c, customerKey{}, in.Customer) // what the tool sees
	res, err := support.Prompt(ctx, in.Question)
	if err != nil {
		return Answer{}, err
	}
	return Answer{Answer: res.Text(), InputTokens: res.Usage.InputTokens, OutputTokens: res.Usage.OutputTokens}, nil
}
```

(Copied from [`examples/ai`](https://github.com/anetos-dev/anetos/tree/main/examples/ai), region `ask`.)

The model calls tools, they run, the model gets their results and goes
on, until it answers or reaches `MaxSteps` (10 by default; then
`ai.ErrMaxSteps`). `res.Usage` adds up every step.

Tools run with the context of the call, so they act as the current
user: in your app, `auth.Current`, your policies and permissions
(`rbac.Authorize`) apply inside them.
How a tool's error reaches the model:

| The tool returns | The model is told | The call |
|---|---|---|
| Invalid input (`validate` rules, a field of the wrong JSON type) | Each field's message, or which field has the wrong type | Goes on: the model can correct it |
| An error with a 4xx status (`web.Error`, `auth.ErrForbidden`, `db.ErrNotFound`) | What a web client would see: the status text and the error's message, never its internal cause | Goes on |
| Any other error | Nothing | Stops, and returns the error |

A panicking tool isn't recovered: the panic ends the call, as it would
a handler (the web layer answers 500). A tool's output goes to the model
whole, so return what it needs, not whole tables.

> **Warning:** Text the model reads can contain instructions (a
> customer's message, a web page, a document): "ignore your instructions
> and…". Don't rely on instructions for security. Give tools only what
> the user may do, check permissions inside them, and keep actions that
> can't be undone behind a confirmation the user makes, not the model.

### 5. Stream the answer

`Stream` yields the answer as it's written. Write each piece and flush:

```go
// StreamQuestion is a question in the query string.
type StreamQuestion struct {
	Customer string `header:"X-Customer" validate:"required"`
	Question string `query:"question" validate:"required|max:500"`
}

// AskStream answers a question as plain text, sent as the model writes
// it.
func AskStream(c *web.Ctx, in StreamQuestion) (web.Responder, error) {
	// A long answer outlasts HTTP_REQUEST_TIMEOUT and HTTP_WRITE_TIMEOUT:
	// lift both for this response. (Leaving the page still stops it.)
	ctx := context.WithValue(web.WithoutTimeout(c), customerKey{}, in.Customer)
	w := c.Writer()
	rc := http.NewResponseController(w)
	if err := rc.SetWriteDeadline(time.Time{}); err != nil && !errors.Is(err, http.ErrNotSupported) {
		return nil, err
	}
	for ev, err := range support.Stream(ctx, in.Question) {
		if err != nil {
			return nil, err // before any text, an error response; after, only logged
		}
		if ev.Kind != ai.EventText {
			continue
		}
		if w.Header().Get("Content-Type") == "" {
			w.Header().Set("Content-Type", "text/plain; charset=utf-8")
		}
		if _, err := io.WriteString(w, ev.Text); err != nil {
			return nil, err // the client left: breaking out stops the model
		}
		if err := rc.Flush(); err != nil && !errors.Is(err, http.ErrNotSupported) {
			return nil, err
		}
	}
	return nil, nil
}
```

(Copied from [`examples/ai`](https://github.com/anetos-dev/anetos/tree/main/examples/ai), region `stream`.)

Besides text, the stream has `ai.EventToolCall` and `ai.EventToolResult`
for each tool call, `ai.EventResponse` when a model response is complete,
and last `ai.EventDone`, whose `Result` holds the conversation and usage.
Leaving the loop early stops the generation. A request's timeout
(`AI_TIMEOUT`) counts the time your loop takes too, so a slow reader
makes the request last longer. A stream also outlasts the server's
limits: the example lifts `HTTP_REQUEST_TIMEOUT` for its request
(`web.WithoutTimeout`, keeping the cancellation when the client leaves)
and `HTTP_WRITE_TIMEOUT` for its response (`SetWriteDeadline`). For
browsers, `ai.SSE` sends the answer as server-sent events and does both:
see [Build an AI assistant](https://docs.anetos.dev/guides/ai-assistant/index.md).

### 6. Test it

Tests don't call a model: `anetostest` sets `AI_PROVIDER=fake`, and
`anetostest.FakeAI` scripts the answers, one per request:

```go
func TestAsk(t *testing.T) {
	app := anetostest.New(t, setup, anetostest.FakeAI(
		ai.FakeToolCall("find_order", FindOrderInput{Number: 1042}), // the model looks the order up
		ai.FakeText("Your kettle shipped yesterday."),               // then answers
	))
	app.WithHeader("X-Customer", "ada") // a logged-in customer, in a real app
	app.PostJSON("/questions", map[string]string{"question": "Where is order 1042?"}).
		AssertOK().AssertJSONPath("answer", "Your kettle shipped yesterday.")

	// The model got the tool's result, and the prompt.
	reqs := app.AI().Requests()
	result := reqs[1].Messages[2].Parts[0].(ai.ToolResult)
	if result.IsError || !strings.Contains(result.Content, `"status":"shipped yesterday"`) {
		t.Errorf("tool result: %+v", result)
	}
	app.AssertPrompted(func(r ai.Request) bool { return r.Prompt() == "Where is order 1042?" })
}
```

(Copied from [`examples/ai/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/ai/main_test.go), region `test-ask`.)

The tool really runs: the fake only plays the model. `app.AI().Requests()`
shows what the model was sent: prompts, instructions, tools, tool
results. `ai.FakeObject(v)` answers `GenerateObject`, and `ai.FakeError`
makes a request fail.

## How it works

Each call builds a request (instructions, messages, tool definitions,
the output schema) and sends it to the provider through its driver.
Every request is logged with the provider, model, tokens and time, never
the prompt or the answer. Each tool call is an operation, like a
request or a job, so [N+1 detection](https://docs.anetos.dev/guides/n-plus-one/index.md) covers it. See
[AI](https://docs.anetos.dev/concepts/ai/index.md) for the design, and the
[AI reference](https://docs.anetos.dev/reference/ai/index.md) for every option.

Providers differ, and the drivers smooth what they can:

- **Typed answers** use each provider's structured output. Each accepts
  a different part of JSON Schema: rules it doesn't take (lengths,
  ranges) are written into the fields' descriptions for the model, and
  the answer is validated either way. OpenAI's strict mode is used when
  the struct allows it (no maps, no `any` fields). Claude's structured
  output takes no maps or `any` fields at all (the call fails before
  sending), and at most 24 optional and 16 nullable fields.
- **Reasoning:** models that think (Claude with extended thinking,
  Gemini's thinking models) need their earlier reasoning back when they
  get tool results. It's kept in the conversation as `ai.Reasoning`
  parts, which marshal to JSON with the rest, and other providers
  leave out. Claude with extended thinking can't continue a tool call
  another provider made.
- **A provider's own features** go through `ai.ProviderOptions` with the
  driver's `Options`: `anthropic.Options{ThinkingBudget: 4096}`,
  `openai.Options{ReasoningEffort: "low"}`, `gemini.Options{ThinkingBudget: &budget}`;
  each also has `Params`, a function to change the SDK's request
  parameters directly. A call can carry several drivers' options
  (`ai.ProviderOptions(anthropic.Options{…}, openai.Options{…})`), and
  each provider uses only its own, so switching `AI_PROVIDER` keeps
  them. `Response.Raw` holds the SDK's response.

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| `ai: AI_PROVIDER isn't set` | No provider chosen | Set `AI_PROVIDER`, and pass its driver to `ai.New` |
| `ai: open the anthropic provider: ANTHROPIC_API_KEY isn't set` (or `AI_MODEL isn't set`) | The provider's key, or the model, is missing | Set it; the provider's names for its models are in its documentation |
| `openai: authenticated requests require HTTPS` | `OPENAI_COMPATIBLE_KEY` is set and `OPENAI_COMPATIBLE_URL` is plain HTTP to another machine | Use https, or no key; on your own machine, HTTP works |
| A local model's typed answers fail twice | Small models follow schemas poorly | Use a larger model, or simpler structs |
| `ai: no AI client in the context` | `ai.New` wasn't called, or the context isn't the app's | Call it in setup; use the request's or job's context |
| `ai: fake: no reply scripted for request N` in a test | The app made more requests than `FakeAI` scripted | Add replies (`FakeAI`, `app.AI().Add`); `app.AI().Requests()` shows them |
| `ai: the model's answer isn't a valid …` (502) | The answer broke the struct's shape or rules twice | Loosen the rules, describe fields better (`description` tags), or use a stronger model |
| `… was cut off at the token limit` | The answer reached `AI_MAX_TOKENS` | Raise it, or `ai.MaxTokens` on the call |
| `ai.ErrMaxSteps` | The model kept calling tools | Raise `MaxSteps`, or make tools return what the model needs in fewer calls |
| A panic: `ai: tool name …` or `isn't a struct` at startup | `ai.NewTool` checks its name and input type when it's made | Use letters, digits, `_` and `-`; make the input a struct (`struct{}` for none) |

## Next steps

- [Build an AI assistant](https://docs.anetos.dev/guides/ai-assistant/index.md): stored conversations,
  answers streamed to the page, replies from queue jobs, usage budgets.
- [Search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md): embeddings, vector and hybrid
  search, and a search tool for agents.
- [AI concepts](https://docs.anetos.dev/concepts/ai/index.md): what the package does, and doesn't.
- [AI reference](https://docs.anetos.dev/reference/ai/index.md): options, events, errors, schemas.
- [Authorization](https://docs.anetos.dev/guides/authorization/index.md) and [Roles and
  permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md): what tools should check.


# Build an AI assistant

Source: https://docs.anetos.dev/guides/ai-assistant/

Give your users a chat with an agent that answers from your app's data:
conversations stored in the database, answers streamed to the page as
they're written, slow questions answered in the background, and a usage
budget per user.

## Before you start

- [Add AI to your app](https://docs.anetos.dev/guides/ai/index.md): the client, agents and tools.
- [Authentication](https://docs.anetos.dev/guides/authentication/index.md): conversations belong to users.
- A [queue](https://docs.anetos.dev/guides/queues/index.md), for answers in the background, and the
  [cache](https://docs.anetos.dev/guides/cache/index.md), where budgets are counted.

The code here comes from [`examples/assistant`](https://github.com/anetos-dev/anetos/tree/main/examples/assistant),
a help center whose assistant searches and reads its articles (a
[search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md), with the articles' full-text
index).

## Steps

### 1. Write the agent

The agent's tools query the app's data. They run as the logged-in user,
so a tool sees only what the user may see. Here, one searches the
articles by their embeddings and words (`articles.Tool`, from
[Search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md)), and one reads an article:

```go
// newHelpdesk returns the agent that answers questions about Tidy from
// the help center, with two tools over the articles: a hybrid search
// (their meaning and their words), and reading one.
func newHelpdesk(articles *ai.Embeddings[Article]) ai.Agent {
	return ai.Agent{
		Name: "helpdesk",
		Instructions: "You answer questions about Tidy, a to-do app, from its help-center articles. " +
			"Search the articles, read the best match if its passage isn't enough, and answer briefly, naming the article. " +
			"If the articles don't say, say you don't know.",
		Tools: []ai.Tool{
			articles.Tool("search_articles", "Search the help center by meaning and words; returns the best articles' IDs, titles and passages", 3),
			readArticle,
		},
		MaxSteps: 6,
	}
}

// ReadInput is what the model sends to read_article.
type ReadInput struct {
	ID int64 `json:"id" description:"The article's ID, from search_articles" validate:"required"`
}

var readArticle = ai.NewTool("read_article", "Read a help-center article",
	func(ctx context.Context, in ReadInput) (Article, error) {
		return db.Find[Article](ctx, in.ID) // not found: 404, told to the model
	})
```

(Copied from [`examples/assistant/agent.go`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/agent.go), region `agent`.)

`anetos make:agent Support` writes a starting point in `app/agents`.

### 2. Set up the client

Add `ai.Migrations()` to your migration sets: the tables of
conversations (`ai_conversations`, `ai_messages`) and of usage records
(`ai_usage`). Then, after the cache, auth and the queue:

```go
client, err := ai.New(app, anthropic.Driver(), openai.Driver(), openai.CompatibleDriver())
if err != nil {
	return nil, err
}
client.TrackUsage(ai.UsageConfig{ // the ai_usage table, and budgets
	Budget: func(context.Context, string) (ai.Budget, error) {
		return ai.Budget{Tokens: settings.DailyTokens, Per: 24 * time.Hour}, nil
	},
	// Prices: map[string]ai.Price{"model-name": {Input: …, Output: …}}, // per million tokens
})
articles, err := ai.EmbeddingsFor(app, articleEmbeddings) // articles_embeddings; ai:embed
if err != nil {
	return nil, err
}
anetos.Provide(app, articles)
helpdesk := newHelpdesk(articles)
if err := ai.QueueAgents(app, helpdesk); err != nil { // answers in the background
	return nil, err
}
```

(Copied from [`examples/assistant`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/main.go), region `setup`.)

`TrackUsage` records each model response's tokens and cost for its user,
and refuses calls once the user's budget for the period is spent.
`EmbeddingsFor` keeps the articles' embeddings, for the search tool.
`QueueAgents` lets the agent answer from queue jobs.

### 3. Store conversations

`ai.StartConversation` stores a conversation of a user, and
`conv.Add` adds the user's question, without calling the model yet:

```go
// Start stores a new conversation with the question, and shows it: the
// page streams the answer.
func (Handlers) Start(c *web.Ctx, in NewChat) (web.Responder, error) {
	userID, err := auth.CurrentID(c)
	if err != nil {
		return nil, err
	}
	conv, err := ai.StartConversation(c, userID, truncate(in.Prompt, 60))
	if err != nil {
		return nil, err
	}
	if err := conv.Add(c, ai.UserMessage(in.Prompt)); err != nil {
		return nil, err
	}
	return web.Redirect(fmt.Sprintf("/chat/%d", conv.ID)), nil
}
```

(Copied from [`examples/assistant`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/main.go), region `start`.)

`ai.FindConversation(ctx, userID, id)` finds one only if it's the
user's (else 404), and `ai.Conversations(ctx, userID)` lists them, the
latest first. `conv.Prompt(ctx, question, agent)` asks and stores the
answer in one call, for code that doesn't stream.

### 4. Stream the answer to the page

The page asks a question with an htmx form, and gets back the question
and a place for the answer, which connects to a stream of server-sent
events:

```go
// Send stores the question and returns it, with a place for the answer
// that streams it from Reply.
func (Handlers) Send(c *web.Ctx, in Question) (web.Responder, error) {
	conv, err := conversation(c, in.ID)
	if err != nil {
		return nil, err
	}
	if err := conv.Add(c, ai.UserMessage(in.Prompt)); err != nil {
		return nil, err
	}
	return page("exchange", map[string]any{"Conversation": conv, "Prompt": in.Prompt}), nil
}

// Reply streams the answer to the conversation's last question, and
// stores it.
func (h Handlers) Reply(c *web.Ctx, in ChatPath) (web.Responder, error) {
	conv, err := conversation(c, in.ID)
	if err != nil {
		return nil, err
	}
	msgs, err := conv.Messages(c)
	if err != nil {
		return nil, err
	}
	answer := conv.StreamReply(c, h.helpdesk)
	if len(msgs) == 0 || msgs[len(msgs)-1].Role != ai.RoleUser || conv.Status == ai.StatusQueued {
		answer = func(func(ai.Event, error) bool) {} // answered already: a browser that reconnected
	}
	return web.ResponderFunc(func(c *web.Ctx) error { return ai.SSE(c, answer) }), nil
}
```

(Copied from [`examples/assistant`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/main.go), region `send`.)

`conv.StreamReply` sends the conversation to the model, and stores the
answer when it's complete. `ai.SSE` writes it as events: `text` for each
piece (HTML-escaped), `tool` when the model calls a tool, `error` with a
message for the user, and `done` at the end. htmx's SSE extension,
bundled with htmx in `view/htmx`, appends the pieces:

```html
<!-- illustrative -->
<script src="{{call .Asset "htmx.min.js"}}"></script>
<script src="{{call .Asset "htmx-ext-sse.min.js"}}"></script>

<div class="msg assistant" hx-ext="sse" sse-connect="/chat/7/reply" sse-close="done">
  <p class="tool" sse-swap="tool"></p>
  <p sse-swap="text" hx-swap="beforeend"></p>
  <p class="error" sse-swap="error"></p>
</div>
```

`msg`, `tool` and `error` are the example's own classes: its pages are
`html/template`, with their own styles. In a project made with
`anetos new`, make a chat message a component of your own in
`views/ui`, next to the others, so its class names stay in one place
([Style your app](https://docs.anetos.dev/guides/styling/index.md#5-add-your-own-component)).

`sse-close="done"` matters: browsers reconnect to a stream that ends,
which would ask the model again. The reply handler also answers a
reconnecting browser with an empty stream when the question is answered
already.

An answer takes as long as it takes: `ai.SSE` (through `c.EventStream()`)
lifts `HTTP_REQUEST_TIMEOUT` and `HTTP_WRITE_TIMEOUT` for the stream,
which still stops when the browser goes away.

Only one call at a time can add to a conversation: a question asked while
an answer is written would change the conversation under it, and that
answer would fail with `ai.ErrConversationChanged` (409) rather than be
stored out of order. The example's page disables its form while a stream
is open.

### 5. Answer in the background

For slow questions, or answers that should survive the user leaving,
`conv.QueueReply` answers from a queue job, as the conversation's user;
the conversation's `Status` is `ai.StatusQueued` until the answer is
stored, or `ai.StatusFailed`, with `Error`, if it fails for good:

```go
// Later stores the question for a queue job to answer, and returns a
// placeholder that polls Status.
func (h Handlers) Later(c *web.Ctx, in Question) (web.Responder, error) {
	conv, err := conversation(c, in.ID)
	if err != nil {
		return nil, err
	}
	if err := conv.Add(c, ai.UserMessage(in.Prompt)); err != nil {
		return nil, err
	}
	if err := conv.QueueReply(c, h.helpdesk); err != nil {
		return nil, err
	}
	return page("queued", map[string]any{"Conversation": conv, "Prompt": in.Prompt}), nil
}

// Status returns the queued answer when it's there, else the placeholder
// again. If the job left the question unanswered (a question asked in
// the meantime), the answer streams instead.
func (Handlers) Status(c *web.Ctx, in ChatPath) (web.Responder, error) {
	conv, err := conversation(c, in.ID)
	if err != nil {
		return nil, err
	}
	switch conv.Status {
	case ai.StatusQueued:
		return page("waiting", map[string]any{"Conversation": conv}), nil
	case ai.StatusFailed:
		return page("failed", map[string]any{"Error": conv.Error}), nil
	}
	msgs, err := conv.Messages(c)
	if err != nil {
		return nil, err
	}
	if n := len(msgs); n > 0 && msgs[n-1].Role == ai.RoleUser {
		return page("answer", map[string]any{"Conversation": conv}), nil
	}
	all := bubbles(msgs)
	return page("bubbles", all[max(len(all)-1, 0):]), nil
}
```

(Copied from [`examples/assistant`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/main.go), region `later`.)

The job runs the agent as the user (`auth.WithUser`): its tools see them as
in a request. A job retried after it answered, or that finds a newer
question, does nothing, so each question gets one answer. A failed
attempt is retried from the start, tools included: make tools that
change things safe to repeat.

With the default `QUEUE_DRIVER=sync`, the job runs in the request that
queued it, once it commits, so it's bound by that request's timeout:
use the `database` or `redis` driver, with workers, for real background
work. A queued reply's own limit is `AI_QUEUE_TIMEOUT` (15 minutes).

### 6. Show the user their usage

Each model response is a row of `ai_usage` (`ai.UsageRecord`), with its
user, conversation, agent, model, tokens and cost. `ai.TotalUsage` adds
them up:

```go
today := anetos.Now(c).UTC().Truncate(24 * time.Hour)
usage, err := ai.TotalUsage(c, userID, today)
if err != nil {
	return err
}
```

(Copied from [`examples/assistant`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/main.go), region `usage`.)

With `UsageConfig.Prices` (per million tokens, by model name), records
have a cost, and budgets can limit it (`ai.Budget{Cost: 2, Per: 24 *
time.Hour}`). A call over budget fails with an `*ai.BudgetError`, a 429
whose message tells the user when they can try again; `ai.SSE` shows it
as the `error` event.

## How it works

A call on a conversation loads its messages, sends them with the new
question, and, once the answer is complete, stores the question, the
model's messages and the tools' results in one transaction, checking
that no other call added messages since. A failed call stores nothing
(the question added with `Add` stays, for a retry). Messages are stored
as JSON, with the reasoning some models need back. See
[AI](https://docs.anetos.dev/concepts/ai/index.md#conversations).

Conversations, budgets and queued replies are part of package `ai`, so
the app doesn't build its own storage or streaming for them: `ai.SSE`
streams a reply as server-sent events.

## Testing it

`anetostest.FakeAI` scripts the model's replies, at the start or later
with `app.AI().Add`; the tools, the storage, the stream and the queue
run for real. `startChat` posts the first question and returns the
conversation's path, so the test doesn't assume IDs, which differ on
PostgreSQL and MySQL (their sequences aren't rolled back with a test):

```go
func TestAssistant(t *testing.T) {
	app := anetostest.New(t, setup, anetostest.FakeAI())
	export := addArticles(t, app)[0] // "Export your lists"
	// The model's replies, scripted: search, read, answer.
	app.AI().Add(
		ai.FakeToolCall("search_articles", map[string]string{"query": "How do I export my lists?"}),
		ai.FakeToolCall("read_article", ReadInput{ID: export.ID}),
		ai.FakeText("Open Settings, then Data, and choose Export (Export your lists)."),
	)
	login(t, app, "Ada")

	chat := startChat(t, app, "How do I export my lists?")
	app.Get(chat).AssertSee("How do I export my lists?", `sse-connect="`+chat+`/reply"`)
	// The answer streams as server-sent events, and is stored.
	app.Get(chat+"/reply").AssertOK().
		AssertSee("event: tool\ndata: search_articles", "event: tool\ndata: read_article",
			"event: text\ndata: Open ", "event: done")
	app.Get(chat).AssertSee("Used: search_articles, read_article", "Open Settings, then Data, and choose Export").
		AssertDontSee("sse-connect")

	// The tools ran for real: the search found the article, with its
	// passage, which the model read.
	reqs := app.AI().Requests()
	want := fmt.Sprintf(`[{"id":%d,"title":"Export your lists","text":"Export your lists\n\nOpen Settings`, export.ID)
	if got := reqs[1].Messages[2].Parts[0].(ai.ToolResult).Content; !strings.HasPrefix(got, want) {
		t.Errorf("search results: %s", got)
	}
	app.AssertPrompted(func(r ai.Request) bool { return strings.Contains(r.System, "help-center articles") })

	// A browser that reconnects gets no second answer.
	app.Get(chat + "/reply").AssertOK().AssertDontSee("event: text")
}
```

(Copied from [`examples/assistant/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/main_test.go), region `test`.)

With the default `QUEUE_DRIVER=sync`, a queued reply runs as soon as
its transaction commits, so a test sees the answer at once:

```go
func TestAnswerLater(t *testing.T) {
	// QUEUE_DRIVER is sync by default: the job runs at once.
	app := anetostest.New(t, setup, anetostest.FakeAI(ai.FakeText("Hello!"), ai.FakeText("Shared lists need a Team plan.")))
	login(t, app, "Ada")
	chat := startChat(t, app, "Hi")
	app.Get(chat + "/reply")

	app.PostForm(chat+"/later", url.Values{"prompt": {"Can I share a list?"}}).
		AssertSee("Can I share a list?", `hx-get="`+chat+`/status"`)
	app.Get(chat + "/status").AssertSee("Shared lists need a Team plan.").AssertDontSee("Working on it")
}
```

(Copied from [`examples/assistant/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/main_test.go), region `test-queue`.)

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| The same question is answered again and again | The page doesn't close the stream on `done`, and the browser reconnects | Add `sse-close="done"` (or close the `EventSource` on `done`) |
| A stream stops after 30 seconds | The stream doesn't go through `c.EventStream()` (or `ai.SSE`), so the request's timeout applies | Use `ai.SSE`, or `web.WithoutTimeout` for other streaming |
| `The conversation changed while the answer was written` | Two questions at once in one conversation | Let one answer finish before the next question |
| `ai: agent "…" can't answer queued replies` | The agent wasn't passed to `ai.QueueAgents`, or has no `Name` | Pass it at setup |
| A queued reply stays `queued` | No worker runs the queue (with `QUEUE_DRIVER=database` or `redis`) | Run `./app run --only=worker`, or everything |
| `You've reached your AI usage limit` | The user's budget is spent | Raise the budget, or wait for the period to start again |
| No cost in `ai_usage` | No price for the model's name | Add it to `Prices`, by the name responses report (`Model`) |
| Usage records vanish | The call ran inside a transaction that rolled back | Call models outside transactions |
| "The reply failed" for long background answers with the sync driver | The reply ran within the queuing request's `HTTP_REQUEST_TIMEOUT` | Use a real queue driver and workers |

## Next steps

- [AI reference](https://docs.anetos.dev/reference/ai/index.md#conversations): every function and
  option.
- [Queues](https://docs.anetos.dev/guides/queues/index.md): workers, retries and failed jobs.
- [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md): what the agent's
  tools may do, for whom.


# Search by meaning

Source: https://docs.anetos.dev/guides/semantic-search/

Find records by what they mean, not only by the words they share: "how
much is the team plan" finds the article on plans and billing, which
never says "how much". Each record's text is split into chunks, turned
into vectors (embeddings) by an embedding model, and stored next to the
record; a search embeds the question and returns the nearest records,
with the passage that matched. With a full-text index too, the search is
*hybrid*: records that its words find rank high as well, so names, codes
and rare words aren't missed. An agent can use the search as a tool, to
answer from your data (retrieval-augmented generation).

The code here comes from [`examples/assistant`](https://github.com/anetos-dev/anetos/tree/main/examples/assistant),
a help center whose assistant searches its articles.

## Before you start

- [Add AI to your app](https://docs.anetos.dev/guides/ai/index.md): `ai.New`, and a provider with an
  embedding model (OpenAI, Gemini, or an OpenAI-compatible server).
  Anthropic has none: use another provider for the embeddings.
- A database that stores vectors: SQLite, PostgreSQL with
  [pgvector](https://github.com/pgvector/pgvector), or MariaDB 11.7+
  (see [what each database can do](https://docs.anetos.dev/guides/semantic-search/index.md#what-each-database-can-do)).
- A [queue](https://docs.anetos.dev/guides/queues/index.md), to embed in the background (optional).

## Steps

### 1. Choose the embedding model

Two settings name the model, and the provider if it isn't your chat
provider's:

```bash
AI_EMBEDDING_MODEL=text-embedding-3-small   # OpenAI; gemini-embedding-001 for Gemini
AI_EMBEDDING_PROVIDER=openai                # when AI_PROVIDER has no embeddings (anthropic)
OPENAI_API_KEY=…
```

Pass the provider's driver to `ai.New`, as for chat. Tests use the
fake, which embeds without a model.

### 2. Add an embeddings table

In a migration, `CreateEmbeddings` creates `<table>_embeddings`: a row
per chunk of a record, with its text and vector, and an index for the
search where the database has one. The size of the vectors is the
model's:

```go
Migrations.AddFunc("2026_10_02_140000_create_articles_embeddings",
	func(s *migrate.Schema) error {
		return s.CreateEmbeddings("articles", embeddingDims) // articles_embeddings
	},
	func(s *migrate.Schema) error { return s.DropEmbeddings("articles") })
```

(Copied from [`examples/assistant/models.go`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/models.go), region `migration`.)

OpenAI's `text-embedding-3` models and Gemini's `gemini-embedding-001`
can shorten their vectors to the size you ask for; other models make one
size (768 for `nomic-embed-text`, 1536 for `text-embedding-ada-002`) and
refuse to be asked: set `FixedSize` in the next step. The table's size
must be the vectors'.

On PostgreSQL, the migration creates the `vector` extension if it isn't
there, which takes a superuser: if the app's user isn't one, have one run
`CREATE EXTENSION vector` once.

### 3. Say what to embed

An `ai.EmbeddingsConfig` gives the record's text, the vectors' size and,
for the agent's tool, its title:

```go
// embeddingDims is the size of the articles' vectors: the embeddings
// table's (the migration), and what the embedding model makes. 1536 suits
// OpenAI's text-embedding-3-small and Gemini's gemini-embedding-001; for
// another model, change both (and set FixedSize if it can't shorten its
// vectors).
const embeddingDims = 1536

// articleEmbeddings is how the articles are embedded: their title and
// body, split into chunks.
var articleEmbeddings = ai.EmbeddingsConfig[Article]{
	Text:       func(a Article) string { return a.Title + "\n\n" + a.Body },
	Title:      func(a Article) string { return a.Title },
	Dimensions: embeddingDims,
}
```

(Copied from [`examples/assistant/agent.go`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/agent.go), region `embeddings`.)

`ai.EmbeddingsFor(app, articleEmbeddings)`, at setup after `ai.New`
(and `queue.New`), returns the `*ai.Embeddings[Article]` that keeps
and searches them. `FixedSize: true` is for a model that makes one size
of vector: the size isn't asked for, only checked. `Scope` limits every
search to what the user may see:

```go
// illustrative
notes, err := ai.EmbeddingsFor(app, ai.EmbeddingsConfig[Note]{
	Text:       func(n Note) string { return n.Body },
	Dimensions: 1536,
	Scope: func(ctx context.Context, q *db.Q[Note]) *db.Q[Note] {
		user, _ := auth.Current[*User](ctx)
		return q.Where(NoteCols.TeamID.Eq(user.TeamID))
	},
})
```

### 4. Keep the embeddings up to date

Call `Sync` after creating or changing records:

```go
// seed adds the articles, embedded, and a user.
func seed(ctx context.Context, args *cmd.Args, embeddings *ai.Embeddings[Article]) error {
	articles := append([]Article(nil), helpCenter...)
	if err := db.CreateMany(ctx, articles); err != nil {
		return err
	}
	if err := embeddings.Sync(ctx, articles...); err != nil { // a queue job; with QUEUE_DRIVER=sync, now
		return err
	}
```

(Copied from [`examples/assistant`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/main.go), region `seed`.)

With the app's queue, `Sync` dispatches a job (`ai.embed:articles`) when
the transaction commits, so a request doesn't wait for the model;
without one, it embeds right away. Only chunks whose text changed are
embedded again. Deleting a record deletes its chunks (on MariaDB, a
record deleted by another table's cascading foreign key leaves them
until `ai:embed`; searches skip them).

For records that exist already, and after changing the model or `Text`,
run the command, which also deletes chunks left by deleted records:

```bash
go run . ai:embed            # every table's records; or name the tables
```

### 5. Search

`Search` embeds the question and returns the nearest records, best
first, with the chunk nearest the question:

```go
// illustrative
found, err := articles.Search(c, in.Q, 5)
for _, p := range found {
	fmt.Println(p.Record.Title, p.Text, p.Distance) // the passage, and how far it is (0: same meaning)
}
```

Extra scopes narrow one search: `articles.Search(ctx, q, 5,
func(q *db.Q[Article]) *db.Q[Article] { return q.Where(…) })`.

For an agent, `Tool` makes the search a tool that returns the best
records' IDs, titles and passages:

```go
// newHelpdesk returns the agent that answers questions about Tidy from
// the help center, with two tools over the articles: a hybrid search
// (their meaning and their words), and reading one.
func newHelpdesk(articles *ai.Embeddings[Article]) ai.Agent {
	return ai.Agent{
		Name: "helpdesk",
		Instructions: "You answer questions about Tidy, a to-do app, from its help-center articles. " +
			"Search the articles, read the best match if its passage isn't enough, and answer briefly, naming the article. " +
			"If the articles don't say, say you don't know.",
		Tools: []ai.Tool{
			articles.Tool("search_articles", "Search the help center by meaning and words; returns the best articles' IDs, titles and passages", 3),
			readArticle,
		},
		MaxSteps: 6,
	}
}

// ReadInput is what the model sends to read_article.
type ReadInput struct {
	ID int64 `json:"id" description:"The article's ID, from search_articles" validate:"required"`
}

var readArticle = ai.NewTool("read_article", "Read a help-center article",
	func(ctx context.Context, in ReadInput) (Article, error) {
		return db.Find[Article](ctx, in.ID) // not found: 404, told to the model
	})
```

(Copied from [`examples/assistant/agent.go`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/agent.go), region `agent`.)

The tool runs with the context of the conversation, so `Scope` sees the
user the agent answers.

### 6. Test it

The fake embeds texts by their words, so texts sharing words are near,
and no model is called:

```go
func TestSearchArticles(t *testing.T) {
	app := anetostest.New(t, setup)
	addArticles(t, app)
	embeddings, err := anetos.Resolve[*ai.Embeddings[Article]](app.App)
	if err != nil {
		t.Fatal(err)
	}
	// Each article was embedded once, as a document.
	if reqs := app.AI().EmbedRequests(); len(reqs) != 1 || len(reqs[0].Inputs) != len(helpCenter) || reqs[0].Dimensions != embeddingDims {
		t.Fatalf("embedding requests: %+v", reqs)
	}
	found, err := embeddings.Search(app.Context(), "what does the team plan cost", 2)
	if err != nil {
		t.Fatal(err)
	}
	if len(found) != 2 || found[0].Record.Title != "Plans and billing" {
		t.Errorf("found %+v", found)
	}
}
```

(Copied from [`examples/assistant/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/assistant/main_test.go), region `test-search`.)

## Search without package ai

The query builder searches vectors you made yourself:
`db.Query[Article](ctx).Similar(model, v)` orders the records by their
nearest chunk of that model, and `Hybrid(text, model, v)` merges that
order with full-text search's by reciprocal rank fusion. Both combine
with `Where`, `Limit`, `Count` and `Paginate`. `db.ReplaceChunks`,
`db.Chunks` and `db.NearestChunks` read and write the chunks; `ai.Embed`
and `ai.EmbedQuery` make vectors with the app's model. See the
[query builder reference](https://docs.anetos.dev/reference/query-builder/index.md#vector-search).

## What each database can do

| | SQLite | PostgreSQL | MariaDB | MySQL |
|---|---|---|---|---|
| Vector search | built in: the driver compares every chunk | with [pgvector](https://github.com/pgvector/pgvector) (`CREATE EXTENSION vector`: the migration runs it, as a superuser) | 11.7 and later | not supported |
| Index | none: fine for thousands of chunks | HNSW, up to 2000 dimensions; above, every chunk is compared | its vector index (HNSW) | |
| Hybrid search | yes | yes | yes | |

Without vector search, the app refuses to start once it calls
`ai.EmbeddingsFor` (with the database from `db.Connect`), and
`CreateEmbeddings` stops the migration, each with a message naming the
database and what it needs; `Similar`'s error says which databases
have it. Indexes find the nearest
chunks approximately: the best 200 chunks are the candidates of each
search, so a record with many chunks near the question takes more of
them. The PostgreSQL driver sets pgvector's `hnsw.ef_search` to 200
and, with pgvector 0.8+, `hnsw.iterative_scan` for each session, so the
index returns that many after the query's conditions, in order (by
default it stops at 40). The MySQL driver sets MariaDB's
`mhnsw_ef_search` to 1000 (its default is 20) for the same reason. They
apply to the app's own vector queries too; a connection pooler that
refuses them keeps the defaults.

## How it works

`CreateEmbeddings` makes `<table>_embeddings`: `record_id` (the
record's ID, deleted with it: by a foreign key, or on MariaDB by a
trigger), `chunk` (the chunk's position), `content`, `content_hash`,
`model`, `embedding` and timestamps. `Sync` splits the text into chunks
of at most 2000 characters (`ChunkSize`): whole paragraphs while they
fit, then sentences (after `.`, `!` or `?` and a space, or a full-width
`。！？`), then words. It embeds the chunks whose text (`content_hash`)
or model changed, and replaces the record's chunks in one transaction
that locks the record, so two workers take turns. With the queue, `Sync`
dispatches a job per hundred records.

A search embeds the question as a query (Gemini embeds queries and
documents differently), takes the 200 chunks nearest it by cosine
distance, of the current model only, and ranks each record by its
nearest chunk. A hybrid search ranks the full-text matches too, and
orders the records by the sum of `1/(60 + rank)` over the two lists:
records both find come first, without comparing their scores. The
embedding requests count in `ai_usage` (agent `embed`) and against
budgets, as model calls do.

Chunks of another model are ignored, so changing `AI_EMBEDDING_MODEL`
doesn't mix vectors that can't be compared; until `ai:embed` has run,
searches find only what was embedded since. A model with another vector
size needs a new migration (`DropEmbeddings`, then `CreateEmbeddings`).

There is no search server to run: the migration declares the table,
`Sync` keeps the vectors current, and the database (pgvector, MariaDB or
SQLite) does the search.

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| `ai: the AI provider has no embeddings` | `AI_PROVIDER` is `anthropic`, and `AI_EMBEDDING_PROVIDER` isn't set | Set `AI_EMBEDDING_PROVIDER` and `AI_EMBEDDING_MODEL`, and pass its driver to `ai.New` |
| `the model made vectors of 768 dimensions, not the 1536 asked for` | The model can't shorten its vectors to the table's size | Choose a model that can, or recreate the table with its size and set `FixedSize` |
| The provider refuses `dimensions` | The model makes one size (`text-embedding-ada-002`, models of compatible servers) | `FixedSize: true`, with `Dimensions` its size |
| `permission denied to create extension "vector"` | pgvector isn't a trusted extension | Have a superuser run `CREATE EXTENSION vector` |
| `… needs vector search, which this … database doesn't have` | MySQL, MariaDB before 11.7, or PostgreSQL without pgvector | Install pgvector, upgrade MariaDB, or use SQLite |
| A search finds nothing after changing the model | The chunks are the old model's | `go run . ai:embed` |
| New records aren't found | `Sync` wasn't called, or the queue's workers aren't running | Call `Sync` after saving; run the workers |
| `a vector of 768 dimensions for articles_embeddings, whose vectors have 1536` | A query vector from another model | Embed with the app's model (`ai.EmbedQuery`) |
| `CREATE TRIGGER` is refused on MariaDB | The migration's trigger needs the `TRIGGER` privilege (and, with binary logging, `SUPER` or `log_bin_trust_function_creators`) | Grant it to the migrating user |

## Next steps

- [Build an AI assistant](https://docs.anetos.dev/guides/ai-assistant/index.md): the agent that uses the
  search, in a chat.
- [Add full-text search](https://docs.anetos.dev/guides/search/index.md): the index a hybrid search uses.
- [AI reference](https://docs.anetos.dev/reference/ai/index.md#embeddings): every function and
  setting.


# Production

Source: https://docs.anetos.dev/guides/production/

- [Deploy](https://docs.anetos.dev/guides/deployment/index.md): An Anetos app is one binary: the migrations, views, translations and static files are inside it. Deploying it is building it, giving it its settings, running its migrations, and keeping it running. This guide does that on a server with systemd, in a container, and on two hosting platforms (Fly.io, Render). The examples use an app called `blog`.
- [Find N+1 queries](https://docs.anetos.dev/guides/n-plus-one/index.md): An N+1 is a query in a loop: one query for a list of posts, then one per post for its author. It works, and it's fast with three posts in development; with three hundred in production, it isn't. Anetos warns when a request (or a job, a listener, a scheduled task) runs the same query many times, and says where, so you can load the rows in one query instead. The complete example is [`examples/database`](https://github.com/anetos-dev/anetos/tree/main/examples/database).
- [Secure your app](https://docs.anetos.dev/guides/security/index.md): Anetos starts safe: CSRF protection, encrypted session cookies, parameterized queries, escaped views, security headers, throttled logins. What it can't choose for you are the settings and the deployment: a key, HTTPS, the proxies to trust, the database's connection. This guide is the checklist before you go live, with `doctor` to check what a machine can check.
- [Check your app's security](https://docs.anetos.dev/guides/security-check/index.md): `security:check` checks your app against security rules: its code (SQL built from request data, a redirect to a URL from the request, a secret written in a file), its dependencies (known vulnerabilities, with govulncheck), its routes (a form's route without CSRF protection, an admin page anyone can open) and its settings (session cookies sent over plain HTTP, mail in plain text). Each finding says where it is (a line of your code, or a setting), why it matters and how to fix it. The report comes as text, JSON, SARIF (for GitHub's code scanning) or Markdown.


# Deploy

Source: https://docs.anetos.dev/guides/deployment/

An Anetos app is one binary: the migrations, views, translations and
static files are inside it. Deploying it is building it, giving it its
settings, running its migrations, and keeping it running. This guide
does that on a server with systemd, in a container, and on two hosting
platforms (Fly.io, Render). The examples use an app called `blog`.

Projects made by `anetos new` have the files this guide uses: a
`Dockerfile`, `deploy/blog.service` and `deploy/production.env.example`.
For a project without them, run `anetos new` in an empty directory and copy
them over.

## Before you start

- The app's tests pass (`go test ./...`).
- A production database (PostgreSQL or MySQL), unless the app uses
  SQLite on one machine.
- For accounts and password resets: an email service (SMTP or a driver
  like Postmark). See [Mail](https://docs.anetos.dev/guides/mail/index.md).

## Steps

### 1. Build

```sh
$ go tool anetos build
built bin/blog (linux/amd64, 18.3 MB)
```

`anetos build` generates the templ views and typed columns, then builds
a static binary (`CGO_ENABLED=0`, `-trimpath`, without debug symbols).
`--target` builds for another system, a Linux server from a Mac say:

```sh
go tool anetos build --target=linux/arm64 -o bin/blog-arm64
```

Build in the git repository: Go records the commit, and the tag if the
commit has one (`git tag v1.2.0`), and `blog version` prints them.
Where there is no repository (in a container), pass the version:

```sh
$ go tool anetos build --version=v1.2.0
$ ./bin/blog version
blog v1.2.0 (commit 1a2b3c4d5e6f, 2026-10-06T10:00:00Z)
Anetos v0.5.0
go1.26.9 linux/amd64
```

### 2. Prepare the settings

The app reads its settings from the environment; in production there is
no `.env` file. `deploy/production.env.example` lists the ones to set:

| Setting | Why |
|---|---|
| `APP_ENV=production` | The default when unset; JSON logs, secure cookies, `APP_DEBUG` refused |
| `APP_KEY` | A new key for production (`go tool anetos key:generate --show`), never the one in `.env`. Keep it secret: it encrypts sessions and two-factor secrets. When you change it, put the old one in `APP_PREVIOUS_KEYS` |
| `APP_URL` | The public URL (`https://blog.example.com`), for links in emails and social login |
| `DB_DRIVER`, `DB_URL` | The database, with TLS that checks the server (`sslmode=verify-full`, `tls=true`). With `DB_HOST` and the others instead of `DB_URL`, TLS is on and verified for any host but `localhost` (`DB_TLS`; `DB_TLS_CA` for a provider's own CA) |
| `CACHE_DRIVER`, `SESSION_DRIVER`, `QUEUE_DRIVER` | `database` (or `redis`) so that every process shares them: with `memory`, a second process has its own cache and queue |
| `MAIL_DRIVER`, `MAIL_FROM_ADDRESS` | `log` sends nothing (the app warns at start); in production it logs who an email is for and its subject, never its body, which may hold login links |
| `HTTP_TRUSTED_PROXIES` | The address of the proxy in front of the app, so client IPs (rate limits, logs, the audit log) are the visitors' (step 5) |
| `STORAGE_ROOT` or `STORAGE_DRIVER` | Uploaded files: a directory that survives deploys, or `s3`/`gcs` |

On a platform that gives the app `PORT` and `DATABASE_URL` (Heroku,
Render, Railway, Fly, Cloud Run), the app listens on that port when
`HTTP_ADDR` isn't set, and connects to a `postgres://` `DATABASE_URL`
when nothing else says where the database is (no `DB_URL`, `DB_HOST` or
`DB_NAME`, and `DB_DRIVER` unset or `postgres`); it logs that it does.

An API project (`anetos new --stack=api`) has no sessions, so
`SESSION_*` don't apply; it adds:

| Setting | Why |
|---|---|
| `AUTH_CLIENT_URL` | After `make:auth`: the client app's address (`https://app.example.com`), which the verification and password reset emails link to. The app refuses to start without it in production |
| `HTTP_CORS_ORIGINS` | The origins of browser apps that call the API (`https://app.example.com`), comma-separated; empty, none may. Server-side clients and mobile apps don't need it |

The app serves its API's description at `/api/v1/openapi.json`, made
from its routes; commit `openapi.json` with the code, for reviewers and
client developers ([Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md)).

The app checks them when it starts, for any command: a missing or
wrong one stops it with a message naming the setting. Only `version`
runs without them. Settings that work but are unsafe
(`SESSION_SECURE=false`, a database reached without verified TLS, the
`log` mail driver) don't stop it: `blog doctor` reports them (see
[Secure your app](https://docs.anetos.dev/guides/security/index.md)).

### 3. Run the migrations on each deploy

```sh
./blog migrate
```

Run it before starting the new version. In production, `migrate` runs
without `--force` (`migrate:rollback`, `migrate:reset` and `db:seed`
need it), and takes a lock in PostgreSQL and MySQL, so two servers
deploying at once run each migration once.

While the migrations run, the old version is still serving. Write them
so that it keeps working: add a column in one release and use it in the
next; stop using a column in one release and drop it in the next.

### 4. Run it

Pick one of the three ways below.

#### Run it on a server with systemd

`deploy/blog.service` runs the app as a user of its own, with
`/var/lib/blog` to write to, runs the migrations before each start, and
restarts it if it stops. Build for the server
(`--target=linux/amd64`), copy the binary, the unit and your settings
there, then:

```sh
sudo install -D bin/blog /opt/blog/blog
sudo install -D -m 600 production.env /etc/blog/env
sudo cp deploy/blog.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now blog
journalctl -u blog -f      # the logs
```

To deploy a new version, copy the binary over and restart:

```sh
sudo install bin/blog /opt/blog/blog && sudo systemctl restart blog
```

The restart stops the old process (it finishes its requests and jobs
within `APP_SHUTDOWN_TIMEOUT`; the unit kills it after 45 seconds),
migrates and starts the new one: requests wait a moment or fail during
it. For no gap, run two instances on different `HTTP_ADDR` behind the
proxy and restart them one at a time.

#### Run it in a container

```sh
docker build -t blog --build-arg VERSION=v1.2.0 .
docker run --rm --env-file production.env -v blog-data:/data blog migrate
docker run -d --name blog -p 8080:8080 --env-file production.env -v blog-data:/data blog
```

The `migrate` step needs the same volume as the server when the
database is SQLite (in `/data`). A SQLite project's image doesn't need
the step at all: its `Dockerfile` sets `DB_MIGRATE_ON_START=true`, so the
server migrates when it starts. Run one container on a SQLite volume
that way; a second one on the same volume (the workers below) gets
`-e DB_MIGRATE_ON_START=false`, since two starting at once could both
migrate. Until the migrations have run, the
server reports itself unavailable (`health:check`, `/health/ready`) and
logs which ones are pending, so a forgotten step shows as `unhealthy`.

The `Dockerfile` builds with `anetos build` in the Go image and copies
the binary alone into a distroless image (about 25 MB), run as user
65532. In a project that uses Tailwind CSS, `anetos build` compiles the
stylesheet first, with Tailwind CSS downloaded once into BuildKit's
cache, so the build needs to reach GitHub's releases the first time
([Tailwind CSS](https://docs.anetos.dev/guides/tailwind/index.md)). The image sets
`APP_ENV=production` and `STORAGE_ROOT=/data/storage` (and
`DB_NAME=/data/app.db` and `DB_MIGRATE_ON_START=true` for SQLite), and
listens on port 8080, or a platform's `PORT`: mount a volume on `/data`. Its `HEALTHCHECK` runs
`blog health:check`, which asks the server for `/health/ready`;
`docker ps` shows `healthy`.

`docker stop` sends SIGTERM and waits 10 seconds before killing; give
it the time the app may take: `docker stop -t 35 blog`, or
`stop_grace_period: 35s` in Compose.

To run the background work in its own container, override the command,
and turn the health check off (it doesn't serve HTTP):

```sh
docker run -d --name blog-worker --env-file production.env --no-healthcheck blog run --only=worker,scheduler
```

The [complete example](https://docs.anetos.dev/guides/deployment/index.md#complete-example) runs the web server, the
workers and PostgreSQL with Docker Compose.

#### Run it on a hosting platform

Platforms build the image from the `Dockerfile`, run it, and route
HTTPS to it. Two examples:

**Fly.io**: `fly launch` finds the `Dockerfile`; edit the `fly.toml` it
writes:

```toml
app = "blog"
primary_region = "ams"
# Fly sends SIGINT and waits 5 seconds by default.
kill_signal = "SIGTERM"
kill_timeout = 35

# Runs in a temporary machine before each deploy (no volumes there).
[deploy]
  release_command = "migrate"

# Each value replaces the image's CMD; the binary stays the entrypoint.
[processes]
  web = "run --only=web"
  worker = "run --only=worker,scheduler"

[env]
  APP_URL = "https://blog.fly.dev"
  CACHE_DRIVER = "database"
  SESSION_DRIVER = "database"
  QUEUE_DRIVER = "database"

[http_service]
  internal_port = 8080
  force_https = true
  processes = ["web"]

  [[http_service.checks]]
    grace_period = "15s"
    interval = "30s"
    method = "GET"
    timeout = "5s"
    path = "/health/ready"
```

Set the secrets with `fly secrets set APP_KEY=base64:… DB_URL=…`, then
`fly deploy`. The release command has no volume, so this suits
PostgreSQL or MySQL. For SQLite, run one machine of a single process
(no `[processes]`), with a volume (`[[mounts]] source = "blog_data"`,
`destination = "/data"`) and without `release_command`: the image
migrates when it starts (`DB_MIGRATE_ON_START=true`, set by the
`Dockerfile`), and the health check passes once it has.

**Render**: a `render.yaml` blueprint with a PostgreSQL database; the
web service and the worker share their settings through an environment
group (except `APP_KEY` and `DB_URL`, which a group can't hold):

```yaml
services:
  - type: web
    name: blog
    runtime: docker
    plan: starter
    healthCheckPath: /health/ready
    # Render's commands replace the image's entrypoint: give the binary's path.
    preDeployCommand: /app/blog migrate
    dockerCommand: /app/blog run --only=web
    envVars:
      - fromGroup: blog
      - key: APP_KEY
        sync: false            # asked for on the first deploy: the same key for both
      - key: DB_URL
        fromDatabase:
          name: blog-db
          property: connectionString
  - type: worker
    name: blog-worker
    runtime: docker
    plan: starter
    dockerCommand: /app/blog run --only=worker,scheduler
    envVars:
      - fromGroup: blog
      - key: APP_KEY
        sync: false            # asked for on the first deploy: the same key for both
      - key: DB_URL
        fromDatabase:
          name: blog-db
          property: connectionString

envVarGroups:
  - name: blog
    envVars:
      - key: APP_URL
        value: https://blog.onrender.com
      - key: DB_DRIVER
        value: postgres
      - key: CACHE_DRIVER
        value: database
      - key: SESSION_DRIVER
        value: database
      - key: QUEUE_DRIVER
        value: database

databases:
  - name: blog-db
```

`APP_KEY` must be `base64:` and 32 bytes, so don't let Render generate
it (`generateValue`). The pre-deploy command needs a paid instance
type.

### 5. Put HTTPS in front

The app serves plain HTTP. On a server, put a proxy in front for HTTPS.
With [Caddy](https://caddyserver.com), which gets the certificate
itself:

```text
blog.example.com {
	reverse_proxy 127.0.0.1:8080
}
```

Then, in the settings:

```sh
HTTP_ADDR=127.0.0.1:8080        # reachable only through the proxy
HTTP_TRUSTED_PROXIES=127.0.0.1
```

`HTTP_TRUSTED_PROXIES` lets the app take the client's IP from
`X-Forwarded-For`, but only on connections from those addresses. Caddy
sets it; with nginx, add `proxy_set_header X-Forwarded-For
$proxy_add_x_forwarded_for;` (the app doesn't read `X-Real-IP`, which a
proxy that doesn't set it passes through from the client). With
`docker run -p`, connections come from the Docker network's gateway
(`172.17.0.1` by default); on a platform, from its proxy: trust its
network. The request log's `ip` field shows the address while it isn't
trusted.

> **Warning:** Trust only addresses that nothing but your proxy uses. If
> the app can be reached directly from a trusted address, anyone can
> claim any IP, and rate limits, the audit log and `ADMIN_ALLOW_IPS`
> believe them.

### 6. Split the process types as you grow

`run` starts every background component: the web server, queue workers, event
listeners, the scheduler. With more traffic, run them in separate
processes or machines (`run --only=web`, `run --only=worker`;
[the runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md) explains
process types):

| Process type | How many |
|---|---|
| `web` | As many as you need, behind the load balancer |
| `worker`, `listener` | As many as the jobs need; they share the queue (`QUEUE_DRIVER=database` or `redis`) and the broker |
| `scheduler` | One; or several, with tasks marked `schedule.OnOneServer()` and a shared cache (`CACHE_DRIVER=database` or `redis`) |

Make sure some process runs each process type the app has: a scheduler
that no process runs never runs its tasks. `run --only=` with a type the app
doesn't have fails and lists those it has. `scheduler` is known as soon
as `schedule.New` is called, so `--only=worker,scheduler` works
before the app has a task; add `listener` once it uses
[pub/sub](https://docs.anetos.dev/guides/pubsub/index.md).

Every process stops gracefully on SIGTERM: the server stops accepting
requests and finishes those in flight, workers finish their jobs, then
the app closes the database. Give it `APP_SHUTDOWN_TIMEOUT` (30 seconds)
before your platform kills it, or lower the setting to fit.

## Complete example

The web server, the background work and PostgreSQL on one Docker host
with Docker Compose. The migrations run first, in a container that
stops when they are done; the others start after it. Put the
`compose.yaml` next to the `Dockerfile`, with `production.env` (without
`DB_*`: they are set here):

```yaml
# compose.yaml. The database password goes in compose.env (chmod 600,
# out of git), not on the command line:
#   echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" > compose.env
#   docker compose --env-file compose.env up -d --build
x-app: &app
  build: .
  image: blog
  env_file: production.env
  environment:
    DB_DRIVER: postgres
    # Plain text on the hosts' own network, with nothing else on it.
    DB_URL: postgres://blog:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/blog?sslmode=disable
  volumes:
    - app-data:/data
  stop_grace_period: 35s # APP_SHUTDOWN_TIMEOUT and a margin

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: blog
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
      POSTGRES_DB: blog
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "blog"]
      interval: 5s

  # Runs the migrations, then stops; the others start after it.
  migrate:
    <<: *app
    command: migrate
    healthcheck:
      disable: true
    depends_on:
      db:
        condition: service_healthy

  web:
    <<: *app
    command: run --only=web
    ports:
      - "127.0.0.1:8080:8080" # for the HTTPS proxy on the host
    restart: unless-stopped
    depends_on:
      migrate:
        condition: service_completed_successfully

  worker:
    <<: *app
    command: run --only=worker,scheduler
    healthcheck:
      disable: true # no HTTP server here
    restart: unless-stopped
    depends_on:
      migrate:
        condition: service_completed_successfully

volumes:
  db-data:
  app-data:
```

The database is reached over Compose's private network, hence
`sslmode=disable`. Set `HTTP_TRUSTED_PROXIES` to the Compose network's
gateway (`docker network inspect blog_default`) for the proxy on the
host. To deploy a new version, run the same command: Compose rebuilds,
migrates, and replaces the containers that changed.

## How it works

- `anetos build` runs `go build` with `-trimpath -ldflags="-s -w"`, and
  `-X anetos.dev/anetos.buildVersion=…` for `--version`. Without cgo,
  the binary needs nothing on the machine, not even its C library, so
  it runs on a distroless or `scratch` image. SQLite works without cgo.
- The binary embeds `public/`, `locales/` and the migrations with
  `go:embed`; templ views are Go code. Nothing is read from the
  project's directory at run time, except `.env` files if present
  (`.dockerignore` keeps them out of the image).
- `/health/live` answers 200 while the process runs; `/health/ready`
  answers 200 while it runs, isn't shutting down, and its components
  are ready, so a load balancer stops sending requests as soon as
  shutdown starts. With `migrate.New`, it also answers 503 while the
  database has migrations the app hasn't run (checked every 5 seconds;
  `DB_MIGRATE_READINESS=false` turns that off, for a platform that waits
  for readiness before a later migration step). `health:check` asks the server on `HTTP_ADDR` (on
  `127.0.0.1` when the address has no host, `0.0.0.0` or `[::]`) and
  exits 1 if it isn't ready.

## Testing it

Before the first deploy, run the production build locally:

```sh
go tool anetos build
export APP_ENV=production APP_DEBUG=false APP_KEY=$(go tool anetos key:generate --show | cut -d= -f2-)
export DB_NAME=/tmp/blog.db STORAGE_ROOT=/tmp/blog-storage   # SQLite; DB_URL for the others
./bin/blog migrate
./bin/blog run
```

`APP_DEBUG=false` overrides the `.env` of development, which the app
still reads in the project's directory. In another terminal, with the
same `HTTP_ADDR`:

```sh
$ ./bin/blog health:check
ok
```

`./bin/blog doctor` with the same settings checks them, and says
which migrations haven't run. After a deploy, `blog version` (on the
server, or `docker run --rm blog version`) tells which version runs.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| `APP_DEBUG=true is not allowed when APP_ENV=production` | `APP_DEBUG=true` copied from `.env` | Remove it |
| `session: encryption: APP_KEY is not set` | The key isn't in the environment (the image has no `.env`) | Set it from your secrets |
| Logging in doesn't stick over plain HTTP | Production cookies are HTTPS-only (`SESSION_SECURE`) | Serve over HTTPS (step 5) |
| Every visitor has the same IP, rate limits hit everyone | The proxy's address is the client IP | Set `HTTP_TRUSTED_PROXIES` (step 5) |
| Jobs dispatched by the web process never run | `QUEUE_DRIVER=sync` or `memory` with workers in another process | `QUEUE_DRIVER=database` or `redis` |
| `permission denied` writing files in the container | The volume isn't writable by user 65532 | Mount on `/data` (the image prepares it), or `chown 65532` the host directory |
| The container stays `unhealthy` | It doesn't serve HTTP (`run --only=worker`), it isn't ready (`/health/ready` answers 503 while a background component restarts or migrations haven't run: the log says which), or `HTTP_HEALTH_ROUTES=false` | Turn the check off for workers (`--no-healthcheck`, `healthcheck: disable: true`); read the logs; keep the health routes on |
| `unknown process type "scheduler"` (or `listener`) | The app has none: no `schedule.New` (or `pubsub.New`) | Leave it out of `--only`; the error lists the app's process types |
| Jobs cut off at each deploy | The platform kills the process before it finishes | Raise its grace period (`docker stop -t`, `kill_timeout`, `TimeoutStopSec`) or lower `APP_SHUTDOWN_TIMEOUT` |
| `blog version` prints `(devel)` | Built outside a git repository without `--version` | `anetos build --version=v1.2.0` (the `Dockerfile` takes `--build-arg VERSION`) |

## Next steps

- [Secure your app](https://docs.anetos.dev/guides/security/index.md): the checklist before going live.
- [Configuration](https://docs.anetos.dev/guides/configuration/index.md) and the [settings reference](https://docs.anetos.dev/reference/configuration/index.md).
- [Migrations](https://docs.anetos.dev/guides/migrations/index.md).
- [The runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md): process types and graceful shutdown.
- [`anetos build`](https://docs.anetos.dev/reference/cli/index.md#anetos-build).


# Find N+1 queries

Source: https://docs.anetos.dev/guides/n-plus-one/

An N+1 is a query in a loop: one query for a list of posts, then one per
post for its author. It works, and it's fast with three posts in
development; with three hundred in production, it isn't. Anetos warns
when a request (or a job, a listener, a scheduled task) runs the same
query many times, and says where, so you can load the rows in one query
instead. The complete example is
[`examples/database`](https://github.com/anetos-dev/anetos/tree/main/examples/database).

## Before you start

You have an app with a database (`db.Connect`). Detection is on in
development and in tests, and off in production: nothing to set up.

## Steps

### 1. Read the warning

Run the app (`go tool anetos dev`) and use it. When a request runs the
same SQL five times or more, with whatever arguments, its end is logged
as a warning:

```text
level=WARN msg="repeated query: an N+1? Load related rows with With or a single query" component=db operation="request GET /slow-posts" count=6 sql="SELECT \"authors\".\"id\", … FROM \"authors\" WHERE \"authors\".\"id\" = ? LIMIT 1" at=handlers/posts.go:42
```

`operation` is what ran the queries: `request GET /slow-posts`, `job
SendDigest`, `listener emailReceipt`, `message orders.created
(billing)`, `task prune-audit-log`, `tool find_order` (a model's call
of an [AI tool](https://docs.anetos.dev/guides/ai/index.md)). `count` is how many times it ran
the query, and `at` is the line of your code that ran it (the fifth
time).

### 2. Fix it

Load the related rows with the query, in one query for all the rows:

```go
func (Blog) ListPosts(c *web.Ctx, in ListPosts) (db.Page[Post], error) {
	q := db.Query[Post](c).Where(PostCols.PublishedAt.NotNull())
	if in.Search != "" {
		q = q.Where(PostCols.Title.Contains(in.Search)) // % and _ match themselves
	}
	if in.Author != nil {
		q = q.Where(PostCols.AuthorID.Eq(*in.Author))
	}
	return q.With(PostRels.Author).Latest().Paginate(in.Page, in.PerPage) // one query for all the authors
}
```

(Copied from [`examples/database`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main.go), region `list-posts`.)

Without a relation, collect the keys and query them once with
`WhereIn`, or write a join. Rows you have already loaded take their
relations with `db.Load` and `db.LoadMany` ([Relations](https://docs.anetos.dev/guides/relations/index.md#3-or-load-them-afterwards)).

### 3. Keep it fixed with a test

`anetostest` records the repeated queries of the test's requests (they
are in the test's log too). `app.AssertNoRepeatedQueries()` fails the
test if there is one:

```go
// The posts page loads the authors with one query (With), so no request
// repeats a query. The handler below is the N+1 that avoids, a query per
// post: anetostest reports it, with the line it runs from.
func TestNoNPlusOne(t *testing.T) {
	app := anetostest.New(t, setup)
	ada := anetostest.Create(app, Authors)
	now := time.Now().UTC()
	anetostest.CreateMany(app, Posts.With(func(p *Post) { p.AuthorID, p.PublishedAt = ada.ID, &now }), 6)

	app.GetJSON("/posts").AssertOK()
	app.AssertNoRepeatedQueries()

	app.Router().Get("/slow-posts", func(c *web.Ctx) error {
		posts, err := db.Query[Post](c).Get()
		if err != nil {
			return err
		}
		for i := range posts {
			author, err := db.Find[Author](c, posts[i].AuthorID) // one query per post
			if err != nil {
				return err
			}
			posts[i].Author = &author
		}
		return c.JSON(http.StatusOK, posts)
	})
	app.GetJSON("/slow-posts").AssertOK()
	if q := app.RepeatedQueries(); len(q) != 1 || q[0].Count != 6 || q[0].Operation.Name != "GET /slow-posts" ||
		!strings.HasPrefix(q[0].Caller, "database/main_test.go:") {
		t.Errorf("repeated queries: %v", q)
	}
}
```

(Copied from [`examples/database/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/database/main_test.go), region `test-n-plus-one`.)

Create enough rows for a loop to cross the threshold: an N+1 over two
posts runs its query twice, under it.

### 4. Tune it

`DB_REPEATED_QUERIES` is the threshold: the number of runs of one query
in one operation that triggers the warning.

| Value | Then |
|---|---|
| unset | 5 in development and testing, off in staging and production |
| `0` | Off |
| `2` or more | That threshold, in any environment |

A loop that has to repeat a query (it is bounded and small, or each run
depends on the last) can opt out: queries made with
`db.AllowRepeatedQueries(ctx)`'s context aren't counted.

```go
// illustrative
ctx := db.AllowRepeatedQueries(ctx)
for _, id := range ids { … }
```

## How it works

Every operation of the app (a request, a queue job, an async or
queued event listener, a pub/sub message, a scheduled task, an AI tool
call) starts with
`app.StartOperation`, which runs the functions added with
`app.AroundOperations`.
`db.Connect` adds one that gives the operation a counter in its context, when
detection is on. Each query made with that context counts its SQL text,
which the query builder writes the same way every time, placeholders
for values; when a count reaches the threshold, the call stack is read
once to find the first frame outside the framework. When the operation ends,
each query at or over the threshold is logged, and passed to the
functions added with `d.OnRepeatedQuery`. An operation inside another (a job
the sync queue driver runs in a request, a tool call in a request)
counts its own queries.

Queries of the framework's database stores (the database cache, queue
and session stores) aren't counted: a cache read per key or a job per
item is by design. Neither are the queries of validation rules
(`exists`, `unique`), which run once per element of a slice before the
handler. An operation the framework splits into chunks (`With` over
more than 1,000 keys, `CreateMany` of many rows) counts once. An operation
started inside `db.AllowRepeatedQueries` (a job the sync driver runs) is tracked
again. Code outside an operation (a command, `migrate`, a seeder, a factory in
a test) isn't tracked; `d.Track(ctx, op)` tracks it. The caller is
the first frame of the stack in neither the framework's modules nor the
standard library, told apart by the binary's build information; a
first-party plugin's code counts as the app's.

`db.Connect`'s database is tracked. Another one, opened with `db.Open`
(and `Config.RepeatedQueries` set), is tracked once the app has its
operations tracked: `app.AroundOperations(analytics.Track)`.

Counting costs a map lookup per query while detection is on; with it
off, no operation function is added, so requests skip starting operations, and
queries skip counting.

## Common problems

| Symptom | Cause | Fix |
|---|---|---|
| A warning for queries that must repeat | A loop over a few items, by design | Use `db.AllowRepeatedQueries(ctx)` for that loop, or raise `DB_REPEATED_QUERIES` |
| No warning for a loop over three rows | Under the threshold (5) | Test with more rows, or set `DB_REPEATED_QUERIES=2` in development |
| `at` is empty | Every frame of the stack is the framework's or the standard library's (a query from the framework itself) | Look at the operation and the SQL |
| A warning when a streaming handler (server-sent events, a WebSocket) ends | It polls the same query for as long as the client stays: by design | Poll with `db.AllowRepeatedQueries(ctx)` |
| A goroutine's queries are missing from the report | It ran them after the request ended, which reports its queries | Expected: the operation was over |
| No warnings in production | Off there by default | Set `DB_REPEATED_QUERIES` in staging to try it with real data |

## Next steps

- [Relations](https://docs.anetos.dev/guides/relations/index.md): `With`, `db.Load`, `WhereHas`.
- [Queries](https://docs.anetos.dev/guides/queries/index.md): `WhereIn` and aggregates.
- [Performance](https://docs.anetos.dev/concepts/performance/index.md): where a page's time goes.
- [Configuration reference](https://docs.anetos.dev/reference/configuration/index.md#database):
  `DB_REPEATED_QUERIES`.

> **Coming from another framework?** Laravel's `preventLazyLoading()`
> and Rails' `strict_loading` raise when a relation is lazy-loaded;
> Anetos has no lazy loading, so an N+1 can only be a query you wrote in
> a loop. Detection counts the same query's text per request, job or
> task, and logs it rather than showing it in the page.


# Secure your app

Source: https://docs.anetos.dev/guides/security/

Anetos starts safe: CSRF protection, encrypted session cookies,
parameterized queries, escaped views, security headers, throttled
logins. What it can't choose for you are the settings and the
deployment: a key, HTTPS, the proxies to trust, the database's
connection. This guide is the checklist before you go live, with
`doctor` to check what a machine can check.

## Before you start

An app made with `anetos new`, ready to deploy: see
[Deploy](https://docs.anetos.dev/guides/deployment/index.md) first.

## Steps

### 1. Run the doctor

In the project:

```bash
go tool anetos doctor
```

```text
Checking the project (Anetos v0.5.0, go1.26.9).
  ok  .env
  ok  git

Checking blog (APP_ENV=development).
The checks of deployment settings apply to production and staging: run doctor with those settings too (on the server: ./blog doctor).
  ok       app
  ok       db
  ok       session
  ok       http
  warning  migrations: 1 migration(s) haven't run (2026_10_07_090000_create_posts_table): run migrate
0 problems, 1 warning.
```

It checks the project (`.env` readable only by you, no file of secrets
in git), then builds the app and runs its own `doctor` command, which
checks the settings: each feature adds its checks as it is set up. A
**problem** is unsafe or broken, and the command exits 1; a **warning**
is often a mistake; a **note** is a choice worth knowing about.
`--strict` fails on warnings too, for CI; `--vuln` runs `govulncheck`.

Your machine has development settings, where most checks don't apply.
Run the binary's `doctor` where the production settings are, after
each change to them. With the systemd unit `anetos new` writes, run it
as the unit runs the app, with the same user, directory and settings:

```bash
sudo systemd-run --pipe --wait --collect --quiet \
  -p DynamicUser=yes -p StateDirectory=blog --working-directory=/var/lib/blog \
  -E APP_ENV=production -E STORAGE_ROOT=/var/lib/blog/storage \
  -p EnvironmentFile=/etc/blog/env \
  /opt/blog/blog doctor
```

(add `-E DB_NAME=/var/lib/blog/app.db` for SQLite, as the unit
does). In a container, `docker compose run --rm web doctor`. The
[reference](https://docs.anetos.dev/reference/cli/index.md#the-doctor-command) lists every check.

Then run the security check, which reads the routes and the code too
(a form's route without CSRF protection, SQL built from request data, a
key written in a file), runs govulncheck, and writes a report for CI's
code scanning:
[Check your app's security](https://docs.anetos.dev/guides/security-check/index.md).

```bash
go tool anetos security:check
```

### 2. Keep the secrets secret

- Make a new `APP_KEY` for production (`go tool anetos key:generate --show`):
  it encrypts sessions, two-factor secrets and the links in emails.
  Never reuse the one in `.env`. To change it, move the old one to
  `APP_PREVIOUS_KEYS`, so sessions survive
  ([Rotate the key](https://docs.anetos.dev/guides/sessions/index.md#rotate-the-key)).
- Keep settings in files only the app's user reads: `.env` is 0600, and
  the deploy files read `/etc/blog/env`. Never commit them;
  `anetos doctor` fails when git tracks one. If one was committed,
  change every secret in it: the history keeps them.
- Give the database user the rights the app needs, not a superuser.

### 3. Serve it over HTTPS only

- Put HTTPS in front ([Deploy](https://docs.anetos.dev/guides/deployment/index.md#5-put-https-in-front)) and
  set `APP_URL=https://…`. Session cookies are `Secure` outside
  development: don't set `SESSION_SECURE=false`.
- `HSTS` is sent in production, for two years, subdomains included:
  serve every subdomain over HTTPS before you go live.
- Behind a proxy, set `HTTP_TRUSTED_PROXIES` to its address only. Then
  the app takes the client's address from the proxy's
  `X-Forwarded-For`; rate limits, throttling and logs depend on it.
  Never trust `0.0.0.0/0`: any client could pick its address.

### 4. Encrypt the database's connection

A remote `DB_HOST` is reached over TLS, with the server's certificate
checked (`DB_TLS=verify`, the default for any host but this machine).
A managed database usually signs with its own authority: download its
certificate and set `DB_TLS_CA=/etc/blog/db-ca.pem`. Use
`DB_TLS=skip-verify` or `none` only on a private network you trust.
With `DB_URL`, the URL's own options decide (`sslmode=verify-full`,
`tls=true`); `doctor` reads them.

### 5. Add a Content-Security-Policy

A Content-Security-Policy tells browsers which scripts may run, so an
injected `<script>` doesn't. Anetos doesn't set one for your pages (the
admin has its own): a policy has to fit your scripts. For the pages
`anetos new` and the generators write, which load their scripts from
`/assets/`, this one fits:

```go
// illustrative: in setup, after web.NewServer
if app.Config().Env.IsProduction() { // the dev server's reload script is inline
	srv.Router().UseGlobal(func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			w.Header().Set("Content-Security-Policy", "default-src 'self'; script-src 'self'; "+
				"style-src 'self' 'unsafe-inline'; img-src 'self' data:; object-src 'none'; "+
				"base-uri 'none'; form-action 'self'; frame-ancestors 'self'")
			next.ServeHTTP(w, r)
		})
	})
}
```

`'unsafe-inline'` for styles lets htmx's indicator styles and the
admin's banner work; inline scripts stay blocked. Add the hosts of
anything else your pages load (`script-src 'self' https://cdn.example.com`),
and check the browser's console for blocked resources before you ship.

### 6. Protect the accounts

With [`make:auth`](https://docs.anetos.dev/guides/accounts/index.md):

- Offer [two-factor authentication](https://docs.anetos.dev/guides/two-factor/index.md), and require it for
  admins.
- Put sensitive pages behind `a.RequireConfirmed` (the password typed
  again): the generated code does for two-factor settings, API tokens
  and account deletion.
- Give [API tokens](https://docs.anetos.dev/guides/authentication/index.md#8-give-api-clients-tokens) the abilities they need, not
  `*`, and an expiry.
- Check permissions in every handler and AI tool that changes data
  ([Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md)): hiding a button
  isn't a check, and a model's tool call is a request like any other.

### 7. Keep up to date

- Run `govulncheck ./...` (or `go tool anetos doctor --vuln`, or the
  security check, which runs it) in CI: it
  reports the known vulnerabilities in the code your app calls, Go's
  standard library included. Run it with the Go you build with: CI that
  installs go.mod's `go` line exactly (`go 1.26.0`, as `setup-go`'s
  `go-version-file` does) reports standard library advisories fixed
  since; ask for the release's latest patch (`1.26.x`) instead.
- Update Anetos when a release fixes a vulnerability; read the
  [upgrade guide](https://docs.anetos.dev/upgrade/index.md) of each release. Security fixes go
  into the latest minor release ([SECURITY.md](https://github.com/anetos-dev/anetos/blob/main/SECURITY.md)).
- Rebuild the binary or image for each Go security release, which fixes
  the standard library you compiled in.

## How it works

What Anetos does without settings, and where to change it:

| Defence | Where |
|---|---|
| CSRF: unsafe requests need a same-origin `Origin` (or `Sec-Fetch-Site`) and a token from the session | `web.CSRF`, on the `pages` group ([Forms](https://docs.anetos.dev/guides/forms/index.md)) |
| Sessions: AES-256-GCM cookies, `HttpOnly`, `Secure` outside development, `SameSite=Lax` | `session.New` ([Sessions](https://docs.anetos.dev/guides/sessions/index.md)) |
| Logged-in pages aren't cached: `Cache-Control: no-store` | `auth.Require` |
| Headers: `X-Content-Type-Options`, `X-Frame-Options: SAMEORIGIN`, `Referrer-Policy`, `Cross-Origin-Opener-Policy`; HSTS in production | `web.NewServer` |
| Limits: 10 MB bodies, 30 s requests, 10 s for headers | `HTTP_MAX_BODY`, `HTTP_REQUEST_TIMEOUT`, `HTTP_READ_HEADER_TIMEOUT` |
| Queries are parameterized; `Contains` and `StartsWith` escape `LIKE` wildcards | [Query builder](https://docs.anetos.dev/reference/query-builder/index.md) |
| Views escape what they print | templ |
| Passwords: argon2id; logins throttled per login and address, and per address | `AUTH_THROTTLE`, `AUTH_THROTTLE_IP` |
| `APP_DEBUG=true` is refused in production | `APP_ENV` |
| The database's connection is verified for a remote host | `DB_TLS` |

`doctor` checks the settings these depend on; it can't see your code,
your proxy or your firewall. The framework's own security review, with
the risks it accepts, is in the repository's
[docs/security/checklist.md](https://github.com/anetos-dev/anetos/blob/main/docs/security/checklist.md).

To add a check of your own settings to `doctor`, for a feature of
yours or a plugin:

```go
// illustrative
app.AddCheck(anetos.Check{Name: "billing", Run: func(ctx context.Context) []anetos.Finding {
	if cfg.TestMode && app.Config().Env.IsProduction() {
		return []anetos.Finding{{Severity: anetos.Problem, Message: "BILLING_TEST_MODE=true in production: nobody pays; remove it"}}
	}
	return nil
}})
```

## Testing it

Run `go tool anetos doctor --strict` in CI, and the binary's `doctor`
in your deploy script before the new version starts: a problem stops the
deploy. Test your own checks by running the command:

```go
// illustrative
var out bytes.Buffer
code := app.ExecuteArgs(ctx, []string{"doctor"}, &out, &out)
```

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| `doctor` on the server says `APP_ENV=development`, or reports settings the service doesn't have | It didn't get the service's settings | Run it as the service runs: `systemd-run` with the unit's settings (step 1), or `docker compose run --rm web doctor` |
| `the app doesn't boot, so 1 check(s) didn't run` | The database is unreachable, or a feature refuses its settings | Read the error after it; `doctor` reports the other checks anyway |
| `x509: certificate signed by unknown authority` connecting to the database | The server's certificate is signed by its provider's own authority | `DB_TLS_CA` with the provider's certificate |
| Pages break after adding the policy | It blocks something they load | The browser's console names the resource; add its host to the policy |

## Next steps

- [Deploy](https://docs.anetos.dev/guides/deployment/index.md)
- [Add two-factor authentication](https://docs.anetos.dev/guides/two-factor/index.md)
- [Check your app's security](https://docs.anetos.dev/guides/security-check/index.md): the security check and its rules.
- [CLI reference: doctor](https://docs.anetos.dev/reference/cli/index.md#anetos-doctor---strict---vuln)


# Check your app's security

Source: https://docs.anetos.dev/guides/security-check/

`security:check` checks your app against security rules: its code
(SQL built from request data, a redirect to a URL from the request, a
secret written in a file), its dependencies (known vulnerabilities, with
govulncheck), its routes (a form's route without CSRF protection, an
admin page anyone can open) and its settings (session cookies sent over
plain HTTP, mail in plain text). Each finding says where it is (a line
of your code, or a setting), why it matters and how to fix it. The
report comes as text, JSON, SARIF (for GitHub's code scanning) or
Markdown.

## Before you start

An app made with `anetos new`, with its settings (`.env`): the check
boots the app, as other commands do. The settings' rules apply where
the app is deployed, so run the check with the production settings too
(step 4).

## Steps

### 1. Run the check

In the project:

```bash
go tool anetos security:check
```

```text
Security check of blog (APP_ENV=development, level basic).
The settings' rules apply to production and staging: run it with those settings too (on the server, or APP_ENV=production with them).

problem  route.csrf  POST /posts/import  routes/web.go:31
         it changes data with the session's user and has no CSRF protection: another site's page can send it as the logged-in user; add web.CSRF() to its group, after the session middleware
         A01:2025 Broken Access Control · https://docs.anetos.dev/guides/security-check/#routecsrf

problem  source.sql  app/handlers.Posts.Search  app/handlers/posts.go:48
         Raw gets SQL built from request data: a client can change the query (SQL injection); pass values as arguments (?), and choose column names from a list
         A05:2025 Injection · https://docs.anetos.dev/guides/security-check/#sourcesql

2 problems, 0 warnings, 0 notes.
None of these rules finding anything doesn't make the app secure: who may read or change whose records, business logic and the code itself need tests and review.
```

The tool builds the app, checks the code and runs govulncheck (built
in; it needs the network for vuln.go.dev, and `--no-vuln` skips it),
then runs the app's `security:check` command, as `doctor` does, which
adds its own findings: one report. `--out` and `--ignore` name files relative to
the folder you're in. A **problem** is almost always a hole, and the command
exits 1; a **warning** is often a mistake; a **note** is worth knowing.
`--strict` fails on warnings too.

### 2. Fix, or say why it's fine

Each finding names its rule and its fix ([the rules](https://docs.anetos.dev/guides/security-check/index.md#the-rules)
below). A route that is open to everyone on purpose says so in the
code, with a reason, and the rules about logins (`route.login`,
`route.api-auth`) leave it out:

```go
// illustrative
r.Post("/webhooks/stripe", h.Stripe).Public("Stripe signs its webhooks: the handler checks the signature")
```

Any other finding you decide to keep goes in `security-ignore.yaml`, at
the project's root, with the reason (required) and, if you like, a date
after which it's reported again:

```yaml
- rule: route.csrf
  where: POST /import
  reason: the importer's form posts from our own extension, with a token of its own
  expires: 2027-03-31
- rule: setting.log-level   # every place of the rule
  reason: we're looking into a bug this week
  expires: 2026-11-07
```

`where` is the place as the report shows it: a route (`POST /import`),
a setting, a function with its package's path in the module
(`app/handlers.Posts.Search`; a function literal counts as the function
it's in), a file (for
`source.secret`) or a vulnerability (`GO-2026-6612
golang.org/x/net/http2`). An entry without `where` ignores every place
of its rule. It expires at
the end of its day in the app's time zone (`APP_TIMEZONE`); a key the
check doesn't know (`wher:`) is an error, since a typo would ignore
more, for longer. The report lists what it ignored. An entry that
expired while its finding is still there is a warning, and one that
matches nothing (fixed, or expired and fixed) a note. Commit the file:
it is where a reviewer sees what was let through, and why.

### 3. Look further

The basic level (the default) has the rules that find mistakes with
few false alarms. `--level=advanced` adds those that find what needs a
look and may be on purpose: an API route that changes data without a
login, a handler that loads a record by ID without an access check,
SQL built from strings that aren't constants, debug logs in production.

```bash
go tool anetos security:check --level=advanced
```

### 4. Check the production settings

Your machine has development settings, where most of the settings'
rules don't apply. Run the binary's command where the production
settings are, as you run [doctor](https://docs.anetos.dev/guides/security/index.md#1-run-the-doctor). It
checks the settings and the routes; the code and the dependencies are
the tool's, in the project:

```bash
./blog security:check
```

### 5. Run it in CI

The SARIF report puts each finding on its line in a pull request, with
GitHub's code scanning:

```yaml
# illustrative: a GitHub Actions job
security:
  runs-on: ubuntu-latest
  permissions:
    contents: read
    security-events: write # to upload the report
  steps:
    - uses: actions/checkout@v7
    - uses: actions/setup-go@v7
      with:
        go-version: stable # the Go you build with: govulncheck checks its standard library
    # The app boots with development settings: the route rules apply.
    - run: cp .env.example .env && go tool anetos key:generate
    - run: go tool anetos security:check --format=sarif --out=security.sarif
    - uses: github/codeql-action/upload-sarif@v4
      if: always() # the report too when the check fails
      with:
        sarif_file: security.sarif
```

The job fails on a problem, and the findings show in the pull request.
Files in the report are relative to the repository's root, also when
`go.mod` is in a folder of it. `--format=json` gives one object to read
in a script, and `--format=markdown` a table for an issue or a review.
`--out=FILE` writes the report to a file (`-`: the standard output).

## The rules

### `route.csrf`

A route that changes data (POST, PUT, PATCH, DELETE, or any method)
behind the session middleware, without `web.CSRF`: another site's page
can send it with the visitor's session. **Fix:** add `web.CSRF()` to
the route's group, after `sessions.Middleware`, as `anetos new`'s
`pages` group has it. Problem; A01:2025 Broken Access Control.

### `route.login`

A route under `/admin` (or named `admin.…`, or on an `admin.` host)
without a login: auth's `Require`, `rbac.Require`, `rbac.RequireIn` or
`auth.RequireAbilities`. **Fix:** put it in a group with them; or
`.Public("why")` if it's open on purpose. Problem; A01:2025.

### `route.debug`

A route that serves Go's debug endpoints (`/debug/pprof/`,
`/debug/vars`) without a login, for GET or any method: `/debug/pprof/…`
itself, or a mount such as `Handle("", "/debug/{path...}",
web.WrapHandler(http.DefaultServeMux))`. They show the app's memory and settings, and a
profile slows it down. `Public` doesn't excuse them. **Fix:** leave
them out of production builds, or behind a login and `rbac.Require`.
Problem; A02:2025 Security Misconfiguration.

### `route.rate-limit`

A POST route that creates accounts or sends email (`/register`,
`/forgot-password`, `/email/verification-notification`) without
`ratelimit.Middleware`: a script can fill the database or send mail in
your name. **Fix:** add a limit, as `make:auth`'s routes have. Logging
in isn't one of them: auth limits login attempts itself
(`AUTH_THROTTLE`). Warning; A07:2025 Authentication Failures.

### `route.api-auth`

Advanced. An API route (under `/api/`, or behind `web.JSONErrors`)
that changes data without a login, other than `make:auth`'s routes for
guests (register, log in, reset a password). **Fix:** put it behind
auth's `Require`, or `.Public("why")`. Warning; A01:2025.

### `setting.debug`

`APP_DEBUG=true` in staging (production refuses it): error pages show
stack traces and settings. Warning; A02:2025.

### `setting.app-key`

No `APP_KEY` where the app is deployed. Warning; A04:2025
Cryptographic Failures.

### `setting.app-url`

An `http://` `APP_URL` where the app is deployed: links in emails and
OAuth callbacks go over plain HTTP. Problem in production, warning in
staging; A04:2025.

### `setting.session-secure`

`SESSION_SECURE=false` where the app is deployed: the session cookie
goes over plain HTTP too. Problem; A07:2025.

### `setting.session-same-site`

`SESSION_SAME_SITE=none`: other sites' requests carry the session
cookie. Warning; A01:2025.

### `setting.session-domain`

`SESSION_DOMAIN` set: every subdomain gets the session cookie. Note;
A07:2025.

### `setting.trusted-proxies`

`HTTP_TRUSTED_PROXIES` trusting everyone, or a very wide range: clients
choose the IP address the app sees. Problem or warning; A02:2025.

### `setting.cors`

`HTTP_CORS_ORIGINS="*"`: scripts on any site may call the app. Warning;
A02:2025.

### `setting.body-limit`

`HTTP_MAX_BODY=0` where the app is deployed: one client can fill the
memory with a request's body. Warning; A02:2025.

### `setting.request-timeout`

`HTTP_REQUEST_TIMEOUT=0` where the app is deployed: slow requests hold
connections and memory for as long as they like. Warning; A02:2025.

### `setting.header-timeout`

`HTTP_READ_HEADER_TIMEOUT=0` where the app is deployed: a client that
sends its headers slowly holds a connection (Slowloris). Warning;
A02:2025.

### `setting.mail-tls`

`MAIL_SMTP_URL` with `tls=none` for a server off the machine: emails,
with their reset and login links, cross the network in plain text.
Warning; A04:2025.

### `setting.db-tls`

A database off the machine without TLS, or without checking the
server's certificate. Warning; A04:2025.

### `setting.db-log-queries`

`DB_LOG_QUERIES=true` where the app is deployed: the log gets every
query with its values. Warning; A09:2025 Security Logging and Alerting
Failures.

### `setting.log-level`

Advanced. `LOG_LEVEL=debug` where the app is deployed. Warning;
A09:2025.

### `source.sql`

SQL built from request data (with `+`, `fmt.Sprintf`, a
`strings.Builder`) given to `db.Raw`, `db.Exec`, `db.SQL`,
`db.OrderRaw`, `WhereRaw`, `Join`, `GroupBy`, `db.Select`, `SetRaw`, a
migration's `Exec` or the methods of `database/sql`'s `DB`, `Tx` and
`Conn`: a client can change the query. **Fix:** pass values as
arguments (`?`), and choose a column or a sort order from a list: a
value checked in the same function against constants (a `switch` whose
`default` replaces it or returns, `if !slices.Contains(list, v)`, `if
!allowed[v]`, `if _, ok := allowed[v]; !ok`, `v != "a" && v != "b"`)
isn't the client's anymore. Problem; A05:2025 Injection. At the advanced
level, SQL built from strings that aren't constants, wherever they come
from, is a warning: look at where they come from.

The rules follow request data (`c.Param`, `c.Query`, `c.Header`,
`http.Request`'s form, URL, headers and body, and a typed handler's
input) through one function, not into the functions it calls: a helper
that builds SQL from its parameters shows at the advanced level only.

### `source.xss`

Request data given to `templ.Raw`, `c.HTML`, or made
`template.HTML` (or `JS`, `URL`, `CSS`…), which aren't escaped:
anyone can put a script in the page. **Fix:** let templ or
html/template escape it; sanitize HTML you must keep. Problem;
A05:2025. In `.templ` files, the finding is at the `.templ` line; the
rule sees request data a view reads itself, not what a handler passes
to a component's parameters, nor text written to an
`http.ResponseWriter`.

### `source.redirect`

A redirect (`c.Redirect`, `web.Redirect`, `http.Redirect`) to a URL
from the request: a link to your site can send visitors anywhere. Not
when the URL starts with a constant that keeps it on a known site
(`"/posts/"+id`, `"https://example.com/"+path`), or when the function
checks it first: `strings.HasPrefix(next, "//")` (with the leading `/`),
or `url.Parse` and a look at the result's `Host`, `Scheme` or
`IsAbs`. **Fix:** allow your own paths only (a leading `/`, not
`//`), or redirect to a route by name. Problem; A01:2025.

### `source.exec`

`exec.Command` with request data: as the program, or in a shell's
command line (`sh -c`), a problem (a client can run any command); as
another argument, a warning (a value starting with `-` becomes an
option). **Fix:** choose the program from a list, pass the value as one
argument, after `--`. A05:2025.

### `source.tls`

`tls.Config{InsecureSkipVerify: true}`: TLS connections accept any
certificate, so anyone on the network can read and change them.
**Fix:** give the server's authority (`RootCAs`). Problem; A04:2025.

### `source.rand`

`math/rand` (or `math/rand/v2`) for a value whose name says it's a
secret (`token`, `password`, `salt`, `otp`, `sessionID`, `resetCode`…;
not `sessionCount`), returned by a function named so (`NewToken`), or
`math/rand.Read` anywhere: its numbers can be predicted. **Fix:** `crypto/rand` (`rand.Text()` for a token). Warning;
A04:2025.

### `source.secret`

A secret written in the project's files (Go, templ, YAML, JSON, TOML,
scripts; not `.env` and the other files of settings, nor tests): a key
recognized by its form (AWS, Stripe, GitHub, Slack, Google, Anthropic,
OpenAI, SendGrid, a private key) is a problem; a value that looks
random given to a name like `password`, `secret`, `token` or `api_key`
(not `passwordHash`), a warning: in code, a string literal; in
settings files, any value. Files that say they're generated aren't
searched. The report shows the secret's start only. **Fix:** revoke
it, and read it from a setting. A04:2025.

### `source.path`

Advanced. A file path from the request given to `os.Open`,
`os.ReadFile`, `os.WriteFile`, `os.Remove`… or `http.ServeFile`: `../`
reaches any file the app can read. **Fix:** keep the name only
(`filepath.Base`) in a known folder, or open it with `os.Root`.
Warning; A01:2025.

### `source.ssrf`

Advanced. An HTTP request (`http.Get`, `http.NewRequest`, a client's
`Get`…) to a URL from the request: a client can make the app call
internal services. **Fix:** allow only the hosts you expect. Warning;
A01:2025.

### `source.mass-assign`

Advanced. `web.H` with a handler whose input is a model: a client can
set any of its fields (ID, owner, role). **Fix:** bind into a struct
with the fields a form may change, and copy them. Warning; A08:2025
Software or Data Integrity Failures.

### `source.owner`

Advanced. A handler that loads a record by an ID from the request
(`db.Find`, a query's `Find` without a `Where`) and checks nobody's
access: no `rbac` call, no `auth.Authorize…` or `Allows…`, nothing
named like a check (`CanEdit`, `authorizeOwner`, `postPolicy`), and no
comparison of an owner field (`note.UserID != user.ID`). Getting the
current user isn't a check. Any logged-in user can open any record by
changing the ID. Fine when every user may see every record, as `make:crud`'s
handlers assume. **Fix:** check access, or scope the query to
the user. Warning; A01:2025.

### `dependency.vuln`

A known vulnerability (govulncheck, from vuln.go.dev) in a module or
in Go's standard library: in a function the app calls, a problem, at
the line of your code nearest the vulnerable call; in a package it
imports without calling the vulnerable code, a note, at the module's
line in `go.mod` (the standard library's: the `go` or `toolchain`
line). **Fix:** update the module (`go get module@version`, the report
says which), or build with the Go release that fixed it. When
govulncheck can't reach the database, or doesn't finish in 5 minutes,
a note says so; when it fails otherwise, a warning. A03:2025 Software Supply Chain Failures.

### Other findings

- `check.<name>`: a finding of a doctor check marked `Security: true`
  (an app's or a plugin's), with its severity; A02:2025 unless it says.
- `check.panic`: a check or a rule panicked, so it didn't check
  anything. Problem.
- `ignore.expired`, `ignore.unused`: an entry of the ignore file that
  expired while its finding is there (warning), or that matches nothing
  (note).

## Add your own rules

An app or a plugin adds rules of its own. A rule about routes sees each
route with its middleware, the global ones first:

```go
// illustrative
app.AddSecurityRule(web.RouteRule(anetos.SecurityRule{ID: "billing.webhook-signature",
	Summary: "Payment webhooks without the signature check", OWASP: anetos.OWASPAccessControl},
	func(rt web.RouteInfo) []anetos.SecurityFinding {
		if strings.HasPrefix(rt.Pattern, "/webhooks/") && !rt.Uses("billing.VerifySignature") {
			return []anetos.SecurityFinding{{Severity: anetos.Problem,
				Message: "a webhook without the signature check: anyone can post it; add billing.VerifySignature"}}
		}
		return nil
	}))
```

Other rules implement `Run(ctx, app)` themselves (`anetos.SecurityRule`),
and a doctor check marked `Security: true` has its findings in the
report too (as `check.<name>`). A rule's `Level` is
`anetos.SecurityBasic` (the default) or `anetos.SecurityAdvanced`. Name
your rules after your app or plugin (`billing.…`): `route.`, `setting.`,
`source.`, `dependency.`, `check.` and `ignore.` are the framework's.
See the [CLI reference](https://docs.anetos.dev/reference/cli/index.md#app-binary-commands).

## How it works

The tool builds the app, loads the project's packages (not their
tests) with their types, and runs its rules about the code, as an
analyzer on each function; it searches the project's files for
secrets, and runs govulncheck. It writes what it found to a file, which
the app's `security:check` reads (`--findings`). The app's command boots the app, as other commands do, then runs the
doctor's checks and keeps their findings about security (those with a
rule), and runs the security rules: web's about routes read
`route:list`'s information, each middleware by name
([Routing](https://docs.anetos.dev/guides/routing/index.md)), and each route's file and line, which the
router records when the route is registered: the line of your code
that registered it, or that called the module that did (the admin's
`Mount`). The report sorts the
findings by severity, applies `security-ignore.yaml`, and gives each
its OWASP Top 10:2025 category.

A clean report means none of these rules found anything, not that the
app is secure: the rules follow request data within a function, not
across functions or through the database, and can't know who may read
or change whose records; business logic and the code itself need tests
and review.

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| Nothing is found about the settings | `APP_ENV` isn't production or staging, where those rules apply | Run `./<app> security:check` with the production settings |
| `route.csrf` on a webhook | The route is in a group with the session middleware | Move it to a group of its own, without sessions (and check the sender's signature) |
| A finding at a line in the module cache | A plugin registered the route from code your app doesn't call (its own `init`, say) | Look at the plugin's settings for the fix; report it to its authors, or ignore it with a reason |
| `the project doesn't build` | The code rules need the project's packages to type-check | Fix the build (`go build ./...`) |
| `the known vulnerabilities weren't checked` | govulncheck couldn't reach vuln.go.dev | Run it where it has the network; `--no-vuln` to skip it |
| A finding on code that is safe | The rule can't see the check: it's in another function, or not one of the forms it knows | Check in the same function (a `switch` or `slices.Contains` against constants, a map of allowed values), or ignore it in `security-ignore.yaml` with the reason |
| `there's no .env` | The tool needs the app's settings to boot it | `cp .env.example .env && go tool anetos key:generate`, or set `APP_ENV` and `APP_KEY` |
| `field wher not found` | A key of `security-ignore.yaml` misspelled | Use `rule`, `where`, `reason` and `expires` |
| `has no reason` | An entry of `security-ignore.yaml` without `reason:` | Say why the finding is safe to leave |

## Next steps

- [Secure your app](https://docs.anetos.dev/guides/security/index.md): the checklist before you go live.
- [Rate limiting](https://docs.anetos.dev/guides/rate-limiting/index.md), [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md).


# Extending

Source: https://docs.anetos.dev/guides/extending/

- [Use plugins](https://docs.anetos.dev/guides/plugins/index.md): Add features to your app with plugins: packages that bring their own routes, database tables, settings, commands, queue jobs, scheduled tasks or event listeners. `anetos add` installs one with one command. The complete app is [`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue), which uses the Postmark plugin to stop emailing addresses that bounced.
- [Write a plugin](https://docs.anetos.dev/guides/writing-plugins/index.md): Package a feature so any Anetos app can add it with `anetos add`: its routes, tables, settings, commands, queue jobs, scheduled tasks and event listeners. A plugin uses only the framework's public packages, as an app does. The complete plugin is [`plugins/postmark`](https://github.com/anetos-dev/anetos/tree/main/plugins/postmark), which receives Postmark's webhooks and keeps a list of the addresses Postmark stopped sending to.


# Use plugins

Source: https://docs.anetos.dev/guides/plugins/

Add features to your app with plugins: packages that bring their own
routes, database tables, settings, commands, queue jobs, scheduled tasks
or event listeners. `anetos add` installs one with one command. The
complete app is [`examples/queue`](https://github.com/anetos-dev/anetos/tree/main/examples/queue), which uses
the Postmark plugin to stop emailing addresses that bounced.

> **Warning:** A plugin is Go code compiled into your app, with the
> app's privileges: its database, its secrets, its network. There is no
> sandbox. Add only plugins you trust, as you would any dependency.

## Before you start

You have a project made with `anetos new`, with the
`anetos` tool installed in it (`go get -tool
anetos.dev/anetos/cli/cmd/anetos`). Its `main.go` loads the
plugins listed in `plugins.go` at the end of `setup` ([step 1](https://docs.anetos.dev/guides/plugins/index.md#1-load-plugins-in-setup)).

## Steps

### 1. Load plugins in setup

Projects made with `anetos new` already do this. At the end of `setup`,
after the services plugins add to (`web.NewServer`, `migrate.New`,
`queue.New`, `schedule.New`, `events.New`):

```go
// The plugins in plugins.go (anetos add), last: they use the services
// above. The postmark plugin's webhook is POST /postmark/webhook.
if err := ext.Load(app, plugins()); err != nil {
	return nil, err
}
```

(Copied from [`examples/queue`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main.go), region `plugins`.)

`plugins()` is in `plugins.go`, which `anetos add` and `anetos remove`
write; don't edit it. If your project has none (`anetos add` says
so), create it with an empty list, as `anetos new` writes it:

```go
// Code generated by anetos add. DO NOT EDIT.

package main

import (
	"anetos.dev/anetos/ext"
)

// plugins returns the app's plugins, in the order they were added:
// anetos add and anetos remove rewrite this file. setup loads them with
// ext.Load.
func plugins() []ext.Plugin {
	return []ext.Plugin{}
}
```

If a plugin needs a service your app doesn't set up, `ext.Load` says
which call is missing: `plugin postmark: it has jobs: call queue.New
before ext.Load`.

### 2. Add a plugin

From the project's directory:

```bash
go tool anetos add anetos.dev/anetos/plugins/postmark
```

```text
Adding anetos.dev/anetos/plugins/postmark@v0.5.0. A plugin is code compiled into your app, with its privileges, and anetos add runs it once to read its settings: add only code you trust.
Installed anetos.dev/anetos/plugins/postmark v0.5.0.
To read its settings, the app now runs with anetos.dev/anetos/plugins/postmark's code, with your environment and .env. Go on? [y/N] y
Listed it in plugins.go.
Added its settings to .env.example: POSTMARK_WEBHOOK_USER, POSTMARK_WEBHOOK_PASSWORD. Set them in .env.
Next:
  go run . plugin:list   what it adds
  go run . migrate        if it adds migrations
```

`anetos add` runs `go get`, lists the plugin in `plugins.go`, tidies
`go.mod`, builds the app, loads the plugin as the app does (its `plugin:env` command, which
doesn't boot the app), and adds the plugin's settings to `.env.example`.
If the plugin isn't a plugin, doesn't compile, or the app refuses it
(it requires another version of Anetos, or its name is taken), `go.mod`,
`go.sum` and `plugins.go` are left as they were. If the plugin needs a
newer Anetos than your app had, `go get` upgrades it, and `anetos add`
says so. Without a version, a plugin of Anetos's own
(`anetos.dev/anetos/plugins/…`) comes at the version of your `anetos`
tool, released with it, and any other at its latest; add `@v1.2.3` to the
module for another. Before the app runs with the plugin, `anetos add` asks (in a
terminal; `--yes` skips the question). (A project made with `anetos new --replace` takes Anetos's
first-party plugins from that checkout.)

### 3. Configure and migrate

Set the plugin's settings in `.env` (and in production's environment).
Every setting starts with the plugin's name in capitals; list them, with
their defaults, with:

```bash
go run . plugin:env
```

A plugin whose required settings are missing stops the app from
booting, with an error that names them. Then run its migrations, which
never run by themselves:

```bash
go run . migrate
```

### 4. Check what it adds

```bash
go run . plugin:list
```

```text
PLUGIN    REQUIRES             ROUTES     ADDS
postmark  >= v0.2.0, < v0.6.0  /postmark  config, migrations, commands, jobs, routes
```

A plugin's routes are under `/<name>` and named `<name>.…`
(`route:list` shows them); its commands are named `<name>:…` (`help`
lists them); its jobs run on your app's workers. To serve its routes
somewhere else, mount it in `setup`:

```go
// illustrative
if err := ext.Load(app, plugins(), ext.Mount("postmark", "/hooks/postmark")); err != nil {
	return nil, err
}
```

### 5. Use it from your code

A plugin's package can export functions for your code. The Postmark
plugin records the addresses Postmark stopped sending to (hard bounces,
spam complaints, unsubscribes), and `postmark.Suppressed` checks one;
the receipt listener of [`examples/queue/events.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/events.go)
skips them:

```go
// illustrative: in a listener with ctx and the order event e
if bad, err := postmark.Suppressed(ctx, e.Email); err != nil || bad {
	return err // nil for a suppressed address: nothing to send
}
```

### 6. Test

`anetostest.New` runs your `setup`, so tests get the plugins too, and
their migrations. Set their settings with `anetostest.Env`:

```go
// The postmark plugin's webhook records a hard bounce; the receipt to
// that address isn't sent.
func TestBouncedAddress(t *testing.T) {
	fakeGateway(t, &FakeGateway{})
	app := anetostest.New(t, setup, anetostest.Env(map[string]string{
		"QUEUE_DRIVER":              "sync",
		"POSTMARK_WEBHOOK_USER":     "postmark",
		"POSTMARK_WEBHOOK_PASSWORD": "s3cret",
	}))
	req := httptest.NewRequest(http.MethodPost, "/postmark/webhook",
		strings.NewReader(`{"RecordType":"Bounce","Type":"HardBounce","Email":"ada@example.com","Inactive":true}`))
	req.SetBasicAuth("postmark", "s3cret")
	app.Do(req).AssertNoContent()

	placeOrder(t, app, "Lamp", 4250)
	if sent := sentMail(app); len(sent) != 0 {
		t.Errorf("%d emails to a bounced address", len(sent))
	}
}
```

(Copied from [`examples/queue/main_test.go`](https://github.com/anetos-dev/anetos/blob/main/examples/queue/main_test.go), region `test-plugin`.)

### 7. Remove a plugin

```bash
go tool anetos remove anetos.dev/anetos/plugins/postmark
```

This takes it out of `plugins.go`, runs `go mod tidy` and builds the
app. Its settings stay in `.env` and `.env.example`, and its tables in
the database. To drop the tables, add a migration of your own that drops
them (`go tool anetos make:migration drop_postmark_suppressions`), and
forgets that the plugin's migrations ran, so that adding the plugin
again later creates them again:

```go
// illustrative: the up function of drop_postmark_suppressions
func(s *migrate.Schema) error {
	if err := s.DropIfExists("postmark_suppressions"); err != nil {
		return err
	}
	return s.Exec("DELETE FROM migrations WHERE source = ?", "postmark")
}
```

Don't use `migrate:rollback` for this: it rolls back the last batch,
which holds your app's migrations too if they ran with the plugin's.

## The Postmark plugin

`anetos.dev/anetos/plugins/postmark` is the first first-party
plugin. Besides the Postmark mail transport ([Send email](https://docs.anetos.dev/guides/mail/index.md)), it
adds:

| What | Name |
|---|---|
| Settings | `POSTMARK_WEBHOOK_USER`, `POSTMARK_WEBHOOK_PASSWORD`: the webhook's basic auth |
| Route | `POST /postmark/webhook` (`postmark.webhook`): checks the credentials, queues Bounce, SpamComplaint and SubscriptionChange events, answers 204 |
| Job | `postmark:webhook`: adds the address to the list when Postmark deactivated it (a hard bounce, a complaint) or an unsubscribe suppresses it; removes it when a subscription change resumes sending. Soft bounces change nothing |
| Table | `postmark_suppressions` (migration set `postmark`) |
| Commands | `postmark:suppressions` lists the addresses; `postmark:unsuppress <email>` removes one |
| Function | `postmark.Suppressed(ctx, email)` |

In Postmark, add a webhook to your stream with the URL
`https://USER:PASSWORD@example.com/postmark/webhook` and the Bounce,
Spam Complaint and Subscription Change events. Without both settings,
the webhook refuses every request.

## How it works

Go has no runtime plugin discovery: plugins are packages compiled into
your app. `anetos add` is code generation: it writes `plugins.go`, a
list of each plugin package's `Plugin()`, and `setup` passes the list
to `ext.Load`. For each plugin, in order, `Load` checks its name and the
Anetos versions it supports (`anetos.Version()`), fills its settings,
and adds its migrations, commands, jobs, routes, scheduled tasks,
listeners and boot work to your app, each in the plugin's namespace.
Nothing else is wired in, and nothing runs until the app does.

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| `plugins.go is missing` | The file was deleted, or the project wasn't made with `anetos new` | Create it and call `ext.Load`: [step 1](https://docs.anetos.dev/guides/plugins/index.md#1-load-plugins-in-setup) |
| `the app doesn't build with …` | The module has no `Plugin() ext.Plugin` function, or doesn't compile with your version of Anetos | Check the module's docs and the version you asked for |
| `requires Anetos >= v0.3.0, but this is v0.2.1` | The plugin supports other versions of Anetos (`anetos add` refuses it; an update of Anetos can bring this up later) | Add a version of the plugin that supports yours, or update Anetos |
| `call queue.New before ext.Load` | The plugin adds to a service your app doesn't set up, or sets up after `ext.Load` | Set it up in `setup`, before `ext.Load` |
| `plugin postmark: settings: …` when the app starts | A setting is missing or invalid | `go run . plugin:env postmark` lists them; set them in `.env` |
| A plugin's route conflicts with yours | Both use the same path | Mount the plugin elsewhere with `ext.Mount` |

## Next steps

- [Write a plugin](https://docs.anetos.dev/guides/writing-plugins/index.md): build your own.
- [CLI reference](https://docs.anetos.dev/reference/cli/index.md#anetos-add-moduleversion-and-anetos-remove-module):
  `anetos add`, `anetos remove`, `plugin:list`, `plugin:env`.
- [Configuration reference](https://docs.anetos.dev/reference/configuration/index.md#plugins): the
  plugins' settings.

> **Coming from another framework?** `anetos add` does what
> `pip install` plus `INSTALLED_APPS` (Django), `composer require` with
> package discovery (Laravel) or `bundle add` (Rails) do: it adds the
> module and writes it into the app's `plugins.go`, the list the app
> loads. A plugin's
> settings are environment variables read into its own struct, with no
> config files to publish, and its migrations run from the plugin with
> yours instead of being copied into your app.


# Write a plugin

Source: https://docs.anetos.dev/guides/writing-plugins/

Package a feature so any Anetos app can add it with `anetos add`: its
routes, tables, settings, commands, queue jobs, scheduled tasks and
event listeners. A plugin uses only the framework's public packages, as
an app does. The complete plugin is
[`plugins/postmark`](https://github.com/anetos-dev/anetos/tree/main/plugins/postmark), which receives
Postmark's webhooks and keeps a list of the addresses Postmark stopped
sending to.

## Before you start

You know how to [use plugins](https://docs.anetos.dev/guides/plugins/index.md). A plugin is a Go module with
a package that exports a constructor:

```go
// illustrative
func Plugin() ext.Plugin
```

`anetos add` lists `yourpkg.Plugin()` in the app's `plugins.go`, so the
function must have that name and signature, in the module's root
package (or the package path users add).

## Steps

### 1. Name it and declare what it supports

`ext.Plugin` has one method, `Name`. Everything else is optional
interfaces for what the plugin adds. The name namespaces all of it:
lower-case letters, digits and `-`, starting with a letter, up to 40
characters.

```go
// Settings are the plugin's settings.
type Settings struct {
	// WebhookUser is the user name of the basic auth Postmark sends with
	// webhooks (set in the webhook's URL). Without it and the password,
	// the webhook endpoint refuses every request.
	WebhookUser string `env:"POSTMARK_WEBHOOK_USER"`
	// WebhookPassword is the webhook's password.
	WebhookPassword anetos.Secret `env:"POSTMARK_WEBHOOK_PASSWORD"`
}

type plugin struct{ cfg Settings }

func (p *plugin) Name() string     { return "postmark" }
func (p *plugin) Requires() string { return ">= v0.2.0, < v0.6.0" }
func (p *plugin) Config() any      { return &p.cfg }
```

(Copied from [`plugins/postmark/plugin.go`](https://github.com/anetos-dev/anetos/blob/main/plugins/postmark/plugin.go), region `plugin`.)

- `Requires` (`ext.Compat`) lists the Anetos versions the plugin works
  with: comparisons (`>=`, `>`, `<=`, `<`, `=`) of `vX.Y.Z` versions,
  joined by commas. Before v1, minor versions may break APIs, so
  allow one minor series. A pre-release (`v0.2.0-rc.1`) counts as its
  release, and an app built from an untagged commit or a local
  checkout of Anetos has the version that source is heading for
  (`v0.5.0-dev`).
- `Config` (`ext.HasConfig`) returns a pointer to the settings struct,
  with `env` tags as for [`config.Get`](https://docs.anetos.dev/guides/configuration/index.md): defaults,
  `required`, typed fields, `anetos.Secret` for secrets. Every key must
  start with the name in capitals (`POSTMARK_`). `ext.Load` fills it
  before calling the other methods, so they can use it.

### 2. Add tables

`ext.HasMigrations` returns a migration set named after the plugin. Its
migrations run with the app's (`migrate`), and are tracked under that
name:

```go
// Migrations implements ext.HasMigrations.
func (p *plugin) Migrations() *migrate.Set {
	s := migrate.NewSet("postmark")
	s.AddFunc("2026_10_02_000000_create_postmark_suppressions",
		func(s *migrate.Schema) error {
			return s.Create("postmark_suppressions", func(t *migrate.Table) {
				t.ID()
				t.String("email", 254)
				t.String("record_type", 40)
				t.String("reason", 255)
				t.String("message_id", 64)
				t.Timestamps()
				t.Unique("email")
			})
		},
		func(s *migrate.Schema) error { return s.Drop("postmark_suppressions") })
	return s
}
```

(Region `migrations`.)

Prefix your tables with the plugin's name, so they don't collide with
the app's. Never change a released migration: add a new one.

### 3. Add routes

`ext.HasRoutes` gets a router under the plugin's prefix, `/<name>` by
default (the app can move it with `ext.Mount`), whose route names start
with `<name>.`. Use relative paths and route names, never the full path:

```go
// Routes implements ext.HasRoutes: POST /webhook under the plugin's
// prefix.
func (p *plugin) Routes(r *web.Router) error {
	r.Post("/webhook", p.webhook).Name("webhook")
	return nil
}

// webhook checks the credentials and queues the event: Postmark retries
// a webhook that doesn't get a 2xx quickly.
func (p *plugin) webhook(c *web.Ctx) error {
	if !p.authorized(c.Request()) {
		c.Writer().Header().Set("WWW-Authenticate", `Basic realm="postmark"`)
		return web.Error(http.StatusUnauthorized, "unauthorized")
	}
	var e event
	body := http.MaxBytesReader(c.Writer(), c.Request().Body, 1<<20) // events are a few KB
	if err := json.NewDecoder(body).Decode(&e); err != nil {
		if _, ok := errors.AsType[*http.MaxBytesError](err); ok {
			return web.Error(http.StatusRequestEntityTooLarge, "too large")
		}
		return web.Error(http.StatusBadRequest, "invalid JSON")
	}
	switch e.RecordType {
	case "Bounce", "SpamComplaint", "SubscriptionChange":
		if a := e.address(); a != "" && len(a) <= 254 {
			if err := queue.DispatchFunc(c, "postmark:webhook", e); err != nil {
				return err
			}
		}
	}
	return c.NoContent() // other events, and events without an address: acknowledged, ignored
}
```

(Region `routes`.)

The routes get the app's global middleware, and middleware the app adds
to its root router with `Use` (CSRF there would refuse a webhook: apps
put it on a group). The router is the app's, so `UseGlobal` would wrap
every request of the app: don't. For pages, render templ components from
the plugin's package: they are Go code, compiled with it.

### 4. Add jobs, tasks, listeners and commands

Each capability gets the app's service to add to:

| Interface | Method | Name what it adds |
|---|---|---|
| `ext.HasJobs` | `Jobs(q *queue.Queue) error`: `queue.Register`, `queue.RegisterFunc`; `q.Work` for workers of its own | `<name>:…` |
| `ext.HasSchedule` | `Schedule(s *schedule.Scheduler) error`: `s.Add` | `<name>:…` |
| `ext.HasListeners` | `Listeners(bus *events.Bus) error` (`Listen` before v0.5, still called with a warning until v0.6): `events.On`, `OnAsync`, `OnQueued` | |
| `ext.HasCommands` | `Commands() []cmd.Command` | `<name>:…` (checked) |
| `ext.HasBoot` | `Boot(ctx, app) error`: runs when the app boots, after the app's own providers | |

```go
// Jobs implements ext.HasJobs: the job postmark:webhook, run by the
// app's workers.
func (p *plugin) Jobs(q *queue.Queue) error {
	return queue.RegisterFunc(q, "postmark:webhook", record)
}
```

(Region `jobs`.)

Jobs run on the app's workers, and use the app's database, cache and
mailer through their context, like the app's own jobs.

A value your plugin keeps in the context can follow the work it hands
off: add a carrier, and queue jobs and async event listeners get it from
the code that dispatched or emitted them (carried values are stored as
text with the job: no secrets):

```go
// illustrative
app.AddCarrier(anetos.Carrier{
	Name:    "acme.tenant",
	Capture: func(ctx context.Context) string { return tenantOf(ctx) },
	Restore: func(ctx context.Context, v string) context.Context { return withTenant(ctx, v) },
})
```

The audit log carries its actor this way.

### 5. Test it

Test the plugin in a small app: a `setup` that sets up what the plugin
needs, then loads it, run by [`anetostest`](https://docs.anetos.dev/guides/testing/index.md):

```go
func setup(app *anetos.App) (*web.Server, error) {
	if _, err := db.Connect(context.Background(), app, sqlite.Driver()); err != nil {
		return nil, err
	}
	if _, err := migrate.New(app, nil); err != nil {
		return nil, err
	}
	if _, err := queue.New(app); err != nil {
		return nil, err
	}
	srv, err := web.NewServer(app)
	if err != nil {
		return nil, err
	}
	return srv, ext.Load(app, []ext.Plugin{postmark.Plugin()})
}
```

(Copied from [`plugins/postmark/plugin_test.go`](https://github.com/anetos-dev/anetos/blob/main/plugins/postmark/plugin_test.go), region `test-setup`.)

`anetostest.New(t, setup, anetostest.Env(…))` runs the plugin's
migrations on an in-memory database; requests go to `/postmark/…`.
Then try it in a real app: `go mod edit -replace` your module to its
directory, and `anetos add` it with any version.

### 6. Publish it

Tag the module (`v0.1.0`) and push it: `anetos add
example.com/you/yourplugin` gets it through the Go module proxy. Say in
its README what it adds (`plugin:list` shows it too), its settings,
and the Anetos versions it supports.

## Rules

`ext.Load` refuses a plugin that breaks them, naming the rule:

- The name is valid, isn't one the framework uses (`app`, `auth`,
  `cache`, `db`, `events`, `ext`, `health`, `help`, `http`, `log`, `mail`,
  `mailer`, `migrate`, `plugins`, `pubsub`, `queue`, `redis`, `routes`,
  `run`, `schedule`, `anetos`, `serve`, `session`, `social`, `storage`,
  `web`), and no other plugin has it.
- `Requires` is satisfied by the app's Anetos version
  (`anetos.Version()`).
- `Config` returns a pointer to a struct, whose settings start with
  `<NAME>_` (`-` becomes `_`), in upper-case letters, digits and `_`,
  and aren't in another plugin's namespace (`stripe` can't have
  `STRIPE_CONNECT_KEY` next to a `stripe-connect` plugin).
- The migration set is named after the plugin.
- Commands are named `<name>:…`.
- The services the plugin adds to are set up before `ext.Load`
  (`call queue.New before ext.Load`).
- `ext.Mount` names a loaded plugin with routes, and a clean path like
  `/billing/stripe` (no trailing `/`, `.` or `..` segments, or wildcards).

A plugin whose settings are missing or invalid isn't wired in, and the
app doesn't boot, with an error naming them; commands that don't boot
the app (`plugin:env`, `help`) still work.

## Next steps

- [Use plugins](https://docs.anetos.dev/guides/plugins/index.md): `anetos add`, `ext.Load`, `ext.Mount`.
- [Migrations](https://docs.anetos.dev/guides/migrations/index.md), [Queues](https://docs.anetos.dev/guides/queues/index.md),
  [Scheduling](https://docs.anetos.dev/guides/scheduling/index.md), [Events](https://docs.anetos.dev/guides/events/index.md),
  [Commands](https://docs.anetos.dev/guides/commands/index.md): what plugins add.

> **Coming from another framework?** A plugin plays the part of a
> Django app's `AppConfig`, a Laravel package's service provider or a
> Rails engine: `Name` and the `Has…` interfaces say what it adds,
> `Config` its settings, `Migrations` its tables and `Commands` its
> commands. Nothing is discovered automatically: `anetos add` writes the
> app's `plugins.go`, and the app calls `ext.Load`.


# Concepts

Source: https://docs.anetos.dev/concepts/

How Anetos works, and why.


## The app

- [Glossary](https://docs.anetos.dev/concepts/glossary/index.md): The words these pages use, what each means in Anetos, and the words other frameworks use for the same thing when they differ. Anetos uses the word Go developers already know for Go-shaped things, and the word web frameworks share for framework concepts. A new word appears only for a new idea, and is listed here.
- [Application lifecycle](https://docs.anetos.dev/concepts/application-lifecycle/index.md): An Anetos application goes through five phases: **New → Register → Boot → Run → Shutdown**. Knowing which code runs in which phase tells you where to put configuration, wiring, connections and cleanup.
- [Runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md): Every Anetos application runs its long-lived work (HTTP servers, queue workers, pub/sub listeners, the scheduler, background tasks) as goroutines inside one process, managed by a **supervisor**. It decides what runs, what happens when something fails, and how everything stops.
- [Commands and the app binary](https://docs.anetos.dev/concepts/commands/index.md): Your app builds to one binary that is both the server and its maintenance tool. `app.Execute()` reads the first argument and runs that command: `run` by default, or `serve`, `migrate`, `route:list` and commands of your own. Code generation lives elsewhere, in the `anetos` developer tool, because it writes source code rather than running the app.
- [Configuration](https://docs.anetos.dev/concepts/configuration/index.md): Where settings come from, how they become typed Go structs, and why a bad setting stops the app before it serves a single request.
- [Code generation](https://docs.anetos.dev/concepts/code-generation/index.md): Queries in Anetos name columns with typed Go values, such as `PostCols.Title`, that `anetos generate` writes from your model structs. The compiler checks every column name and every value's type, and nothing has to look a column up at query time.
- [How testing works](https://docs.anetos.dev/concepts/testing/index.md): What `anetostest` builds for a test, how it keeps tests from seeing each other's data, how its client imitates a browser, and where a test run differs from production.
- [Performance](https://docs.anetos.dev/concepts/performance/index.md): What a request costs in Anetos, where the time goes in a real page, and how the framework is kept from getting slower. The numbers come from the repository's benchmarks, with their method and code: [docs/benchmarks/v0.3.md](https://github.com/anetos-dev/anetos/blob/main/docs/benchmarks/v0.3.md).

## Web

- [HTTP request lifecycle](https://docs.anetos.dev/concepts/http-request-lifecycle/index.md): What happens between a request arriving and a response leaving, and where your code can hook in.
- [Server-rendered HTML](https://docs.anetos.dev/concepts/server-rendered-html/index.md): How pages are rendered, how a visitor's state travels in an encrypted cookie, and how a failed form finds its way back to the page it came from.
- [Validation](https://docs.anetos.dev/concepts/validation/index.md): How rules in struct tags become a cached plan, what `web.H` does with the result, and why validation works the way it does.
- [Internationalization](https://docs.anetos.dev/concepts/internationalization/index.md): How Anetos finds the words to show a user: where messages come from, how a request's language is chosen, and how the language travels with work done for the user later.

## Data

- [The data layer](https://docs.anetos.dev/concepts/data-layer/index.md): How the db package finds its connection, turns method calls into SQL, and why it works the way it does.
- [Migrations](https://docs.anetos.dev/concepts/migrations/index.md): Migrations are Go values compiled into your binary. The runner applies them in ID order, records each one in the `migrations` table with the batch it ran in, and wraps each in a transaction where the database allows it. A database lock keeps two instances from migrating at once.

## Accounts and security

- [Authentication and authorization](https://docs.anetos.dev/concepts/authentication/index.md): How Anetos knows who is making a request, and what they may do.
- [Roles and permissions](https://docs.anetos.dev/concepts/roles-and-permissions/index.md): How package `auth/rbac` decides what a user may do, and where it keeps what it needs.
- [The audit log](https://docs.anetos.dev/concepts/audit-log/index.md): How package `audit` records every change of the models an app tracks, and why its entries can be trusted to match the data.

## Working with AI

- [AI](https://docs.anetos.dev/concepts/ai/index.md): How package `ai` connects language models to the app, and what it leaves to the providers.


# The app

Source: https://docs.anetos.dev/concepts/the-app/

- [Glossary](https://docs.anetos.dev/concepts/glossary/index.md): The words these pages use, what each means in Anetos, and the words other frameworks use for the same thing when they differ. Anetos uses the word Go developers already know for Go-shaped things, and the word web frameworks share for framework concepts. A new word appears only for a new idea, and is listed here.
- [Application lifecycle](https://docs.anetos.dev/concepts/application-lifecycle/index.md): An Anetos application goes through five phases: **New → Register → Boot → Run → Shutdown**. Knowing which code runs in which phase tells you where to put configuration, wiring, connections and cleanup.
- [Runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md): Every Anetos application runs its long-lived work (HTTP servers, queue workers, pub/sub listeners, the scheduler, background tasks) as goroutines inside one process, managed by a **supervisor**. It decides what runs, what happens when something fails, and how everything stops.
- [Commands and the app binary](https://docs.anetos.dev/concepts/commands/index.md): Your app builds to one binary that is both the server and its maintenance tool. `app.Execute()` reads the first argument and runs that command: `run` by default, or `serve`, `migrate`, `route:list` and commands of your own. Code generation lives elsewhere, in the `anetos` developer tool, because it writes source code rather than running the app.
- [Configuration](https://docs.anetos.dev/concepts/configuration/index.md): Where settings come from, how they become typed Go structs, and why a bad setting stops the app before it serves a single request.
- [Code generation](https://docs.anetos.dev/concepts/code-generation/index.md): Queries in Anetos name columns with typed Go values, such as `PostCols.Title`, that `anetos generate` writes from your model structs. The compiler checks every column name and every value's type, and nothing has to look a column up at query time.
- [How testing works](https://docs.anetos.dev/concepts/testing/index.md): What `anetostest` builds for a test, how it keeps tests from seeing each other's data, how its client imitates a browser, and where a test run differs from production.
- [Performance](https://docs.anetos.dev/concepts/performance/index.md): What a request costs in Anetos, where the time goes in a real page, and how the framework is kept from getting slower. The numbers come from the repository's benchmarks, with their method and code: [docs/benchmarks/v0.3.md](https://github.com/anetos-dev/anetos/blob/main/docs/benchmarks/v0.3.md).


# Glossary

Source: https://docs.anetos.dev/concepts/glossary/

The words these pages use, what each means in Anetos, and the words
other frameworks use for the same thing when they differ. Anetos uses
the word Go developers already know for Go-shaped things, and the word
web frameworks share for framework concepts. A new word appears only for
a new idea, and is listed here.

## The app

| Word | In Anetos | Elsewhere |
|---|---|---|
| **App** | The `*anetos.App` that `anetos.New()` returns. It holds the settings, the logger, the services, the commands and the background components | Django's project, Laravel's application, Rails' application |
| **`setup`** | The function in your `main.go` that builds the app's services in order (`db.Connect`, `cache.New`, `queue.New`… `web.NewServer`) and registers routes and plugins. See [Application lifecycle](https://docs.anetos.dev/concepts/application-lifecycle/index.md#setting-up-the-services) | Django's settings and `AppConfig.ready()`, Laravel's service providers, Rails' initializers |
| **Service** | Something `setup` builds from the settings, such as the cache, the queue or the mailer. `New(app)` builds one, and `Connect` builds a connection to a server (`db.Connect`, `redis.Connect`). Handlers and jobs get a service from their context: `cache.From(ctx)` | A service in a dependency-injection container |
| **Setting** | A value read from `.env` or the environment, named after its area: `DB_DRIVER`, `CACHE_PREFIX`. See the [configuration reference](https://docs.anetos.dev/reference/configuration/index.md) | Environment variables, read into Django's `settings.py`, Laravel's `config/` files or Rails' `config/` |
| **Operation** | One request, queue job, async or queued event listener call, pub/sub message, scheduled task or AI tool call (`anetos.Operation`). Per-operation things, such as repeated-query detection, are counted within one. See [Operations](https://docs.anetos.dev/concepts/application-lifecycle/index.md#operations) | "Per request or per job" |
| **Background component** | Long-running work that the supervisor runs inside the app's process: the HTTP server, queue workers, pub/sub listeners, the scheduler, and tasks started with `app.Go`. It is not a UI component (see Views). See [Runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md#components) | The worker, scheduler and listener processes other frameworks run as separate programs |
| **Supervisor** | The part of the app that starts, restarts and stops the background components | A process manager (systemd, Supervisor), inside the binary |
| **Process type** | `web`, `worker`, `scheduler` or `listener`: which background components a process runs (`./app run --only=worker`). A process runs all of them by default. See [Runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md#process-types-one-binary-many-shapes) | Heroku's process types (a Procfile's `web` and `worker`) |
| **Carrier** | A context value that moves with a queued job or an async event listener, such as the audit log's actor (who asked for the work): an `anetos.Carrier` with `Capture` and `Restore`. See [Write a plugin](https://docs.anetos.dev/guides/writing-plugins/index.md#4-add-jobs-tasks-listeners-and-commands) | Context propagated into jobs; OpenTelemetry calls it a propagator |
| **Doctor, finding** | `doctor` checks the settings and the project. Each result is a finding with a severity: note, warning or problem. See [the doctor command](https://docs.anetos.dev/reference/cli/index.md#the-doctor-command) | |
| **Security check, security rule** | `security:check` checks the app's code, dependencies, routes and settings against security rules (`source.sql`, `route.csrf`, `setting.session-secure`), each finding with its OWASP Top 10 category; findings kept on purpose go in `security-ignore.yaml` with a reason. See [Check your app's security](https://docs.anetos.dev/guides/security-check/index.md) | Django's `check --deploy`; Brakeman (Rails) and gosec read the code instead |
| **Coding agent** | A tool that writes code in your project with you: Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot. Not an AI agent of your app (see Agent, under AI). See [Build with a coding agent](https://docs.anetos.dev/getting-started/coding-agents/index.md) | |
| **Agent files, skill** | What coding agents read in a project: `AGENTS.md`, the instructions, and skills, task guides (`SKILL.md`) an agent loads only when a task needs one. `anetos new` and `agent:install` write them | AGENTS.md and Agent Skills are open formats many agents share |
| **MCP server** | A program a coding agent starts to call its tools, through the Model Context Protocol. `go tool anetos mcp` is the project's: the docs, the app's routes, models and schema, and `check`, as tools. See the [reference](https://docs.anetos.dev/reference/cli/index.md#anetos-mcp---dirproject) | An open protocol most coding agents speak |
| **llms.txt** | A site's list of its pages for language models and coding agents, linking to each page's Markdown. docs.anetos.dev has one per version, and `llms-full.txt` with every page. See [Build with a coding agent](https://docs.anetos.dev/getting-started/coding-agents/index.md#how-it-works) | An open proposal many documentation sites follow |
| **Check** | `go tool anetos check`: generate, build, vet, test and doctor, stopping at the first failure; what you or an agent runs before calling a change done. See the [reference](https://docs.anetos.dev/reference/cli/index.md#anetos-check---short---json) | |
| **Provider** | A piece of your own functionality with a `Register` and a `Boot` phase (`anetos.Provider`), added with `app.Use`. The framework's services don't need one: `setup` builds them. See [Providers](https://docs.anetos.dev/concepts/application-lifecycle/index.md#providers) | Django's `AppConfig`, Laravel's service provider, Rails' initializers |

## Web

| Word | In Anetos | Elsewhere |
|---|---|---|
| **Handler** | A function that answers a route. It can be a plain handler, `func(c *web.Ctx) error`; a typed handler; or any `http.Handler`, through `web.WrapHandler`. See [Handlers and requests](https://docs.anetos.dev/guides/handlers/index.md) | A view (Django) or a controller action (Laravel, Rails) |
| **Typed handler, `web.H`** | A handler that takes its input as a struct and returns its output: `func(c *web.Ctx, in CreateNote) (Note, error)`. `web.H` (H for handler) turns it into a route's handler and binds and validates the input. It has nothing to do with Gin's `gin.H` map. See [Write a typed handler](https://docs.anetos.dev/guides/handlers/index.md#2-write-a-typed-handler) | A view or controller action with a form or form request |
| **Responder** | A value that writes its own response (`web.Responder`): `web.Created(v)`, `web.Redirect(url)`, `web.Render(page)` | A response object (Django's `HttpResponse`, Laravel's `Responsable`) |
| **Route name** | `.Name("notes.show")`, used to build URLs (`web.URL`, `web.RedirectRoute`) | Named routes: Django's `name=`, Laravel's `->name()`, Rails' `as:` |
| **CRUD actions** | `index`, `new`, `create`, `show`, `edit`, `update`, `delete`. The route name and the handler match: `notes.create` is `Create`, which saves the form that `New` shows | Rails' and Phoenix's names, except Rails' `destroy`; Laravel says `create` for the form, `store` and `destroy` |
| **Stack** | What `anetos new` writes: `web` (pages, sessions, CSRF; the default) or `api` (JSON only). See [`anetos new`](https://docs.anetos.dev/reference/cli/index.md#anetos-new-directory) | Laravel's starter kits' stacks; Rails' `--api` |
| **Middleware** | `func(http.Handler) http.Handler`, on a router or a group | The same idea in Django, Laravel and Rails |
| **Rule** | A named check in a `validate` tag (`validate:"required\|max:200"`); your own are added with `validate.Register`. See the [validation rules reference](https://docs.anetos.dev/reference/validation-rules/index.md) | Validators (Django), validation rules (Laravel), validations (Rails) |

## Data

| Word | In Anetos | Elsewhere |
|---|---|---|
| **Model** | A struct mapped to a table, embedding `db.Model`. You save it with functions such as `db.Create(ctx, &post)`, not with methods on the model | Django's `Model`, Eloquent, Active Record |
| **Typed columns** | The values `anetos generate` writes for each model (`PostCols.Title`), which conditions are built from, so the compiler checks column names and types. They aren't SQL's generated columns. See [Generate typed columns](https://docs.anetos.dev/guides/code-generation/index.md) | |
| **Scope (query)** | A reusable `func(*db.Q[T]) *db.Q[T]`, applied with `.Scope(Popular)` | Django's custom querysets, Laravel's local scopes, Rails' scopes |
| **Dialect** | The SQL flavor of a database: placeholders, quoting, upserts | A database backend (Django), a grammar (Laravel), an adapter (Rails) |
| **Soft deletes, trashed** | `db.SoftDeletes` adds `deleted_at`. A deleted row is trashed: queries skip it unless you call `WithTrashed`. `Restore` brings it back and `ForceDelete` removes it | Laravel's soft deletes; Rails' discard and paranoia gems |
| **Prunable** | `db.Prunable[T](app, after)` registers a soft-deleting model: `db:prune-trashed` then deletes for good its rows trashed more than `after` ago | A cleanup task run on a schedule (Laravel's `Prunable` takes any query; Django and Rails leave it to a command or a recurring job) |
| **Repeated queries** | The same query run again and again in one operation, which is likely an N+1. The app warns about it unless `db.AllowRepeatedQueries(ctx)` allows it. See [Find N+1 queries](https://docs.anetos.dev/guides/n-plus-one/index.md) | Django's nplusone, Laravel's `preventLazyLoading`, Rails' `strict_loading` and Bullet |

## Services and their drivers

| Word | In Anetos | Elsewhere |
|---|---|---|
| **Driver** | The backend a service uses, picked with the area's `_DRIVER` setting (`CACHE_DRIVER=redis`), and the Go value that provides it (`cache.DatabaseDriver()`, `redis.CacheDriver()`). The AI's is `AI_PROVIDER` | A backend: Django's `CACHES` backends, Laravel's stores and connections, Rails' cache stores and adapters |
| **Store, backend, transport, broker** | The interface a driver implements: `cache.Store` and `queue.Store`, `storage.Backend`, `mailer.Transport`, `pubsub.Broker`, `ai.Provider` | Contracts, adapters or backends |
| **Disk** | A named place files are kept, such as a folder or an S3 or Google Cloud Storage bucket. `storage.From(ctx)` is the default disk and `storage.DiskFrom(ctx, name)` another. See [Store files](https://docs.anetos.dev/guides/storage/index.md) | Django's storages, Laravel's disks, Rails' Active Storage services |
| **Job, worker** | A typed piece of work sent to a queue, and the background component that runs jobs. See [Queues](https://docs.anetos.dev/guides/queues/index.md) | A Celery task and worker (Django), a queued job (Laravel), an Active Job (Rails) |
| **Event, event listener** | A typed message inside the app (`events.Emit`), and a function that handles it, run right away, asynchronously or queued. See [Events](https://docs.anetos.dev/guides/events/index.md) | Django's signals and receivers, Laravel's events and listeners, Rails' notifications and subscribers |
| **Pub/sub listener** | A background component that reads a topic of an external broker. See [Pub/sub listeners](https://docs.anetos.dev/guides/pubsub/index.md) | |

## Accounts and security

| Word | In Anetos | Elsewhere |
|---|---|---|
| **Log in, log out** | The one pair of words, in code (`Login`, `/login`) and in the pages | Django's and Laravel's words, and Devise's pages'; Rails' authentication generator (and Devise's helpers) say sign in |
| **Permission, role** | A permission names something a user may do (`posts.edit`). A role is a named set of permissions. You assign a role to a user, or grant a permission directly. See [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md) | Django's permissions and groups; spatie/laravel-permission's words; Rolify's roles (Rails) |
| **Scope (roles)** | Where a role or a permission applies, such as one team (`rbac.ScopeOf("team", id)`), or everywhere (`rbac.Global`) | Teams or resources in role libraries (spatie/laravel-permission's teams, Rolify's resource roles) |
| **Ability** | What an API token may do (names such as `posts:read`; `*` for all), checked with `auth.TokenCan` | A token's scopes or abilities (OAuth scopes, Sanctum's abilities) |
| **Impersonate** | An admin using the app as another user, from the admin panel. See [Impersonate a user](https://docs.anetos.dev/guides/admin/index.md#6-impersonate-a-user) | Impersonation in admin panels (Filament, Nova, django-hijack) |
| **`ActingAs`** | In tests, `anetostest.ActingAs(app, u)` logs `u` in for the requests that follow | Django's `force_login`, Laravel's `actingAs`, Devise's `sign_in` (Rails) |
| **Audit log** | The record of who did what (`audit.Trail`). See [Keep an audit log](https://docs.anetos.dev/guides/audit-log/index.md) | |

## Views

| Word | In Anetos | Elsewhere |
|---|---|---|
| **templ** | The template language of the pages: `.templ` files compiled to Go functions, type-checked like the rest of the app. See [Render HTML with templ](https://docs.anetos.dev/guides/views/index.md) | Django templates, Blade, ERB |
| **Component (UI)** | A templ component (`view.Component`): a page, or a piece of one. The shared ones, which the CSS framework styles, are in your project's `views/ui` (`@ui.Button(…)`). See the [UI components reference](https://docs.anetos.dev/reference/ui/index.md) | Template components (Blade components, ViewComponent) |
| **CSS framework** | What `--css` picks: the starter theme, `none`, Pico, Bootstrap, Bulma or Tailwind CSS, with the matching `views/ui` components. `css:use` switches. See [Style your app](https://docs.anetos.dev/guides/styling/index.md) | A `--css` option when creating a project; not a starter kit, which scaffolds accounts |
| **Starter theme** | The default CSS framework (`--css=anetos`): light and dark, no build step. See [The starter theme](https://docs.anetos.dev/guides/starter-theme/index.md) | |
| **Variant, size, tone** | A component's options: a variant is its kind (`ui.Primary`, `ui.Secondary`), a size changes it (`ui.Small`, `ui.FullWidth`), and a tone is the color meaning of a badge or a message (`ui.Success`, `ui.Error`) | Bootstrap's and shadcn's variant and size; Polaris' tone |
| **Catalog** | One locale's translations, in YAML files under `locales/`. See [Translations](https://docs.anetos.dev/guides/translations/index.md) | Message files: Django's `.po` files, Laravel's `lang/`, Rails' `config/locales` |

## Plugins

| Word | In Anetos | Elsewhere |
|---|---|---|
| **Plugin** | A Go module that adds routes, tables, jobs, commands or settings to an app (`anetos add`). Its package is `ext`, because Go's standard library has a package named `plugin`. See [Use plugins](https://docs.anetos.dev/guides/plugins/index.md) | A Django app, a Laravel package, a Rails engine or gem |

## AI

| Word | In Anetos | Elsewhere |
|---|---|---|
| **Provider** (AI) | The AI service a client calls: Anthropic, OpenAI or Gemini, picked with `AI_PROVIDER` | The AI SDKs' word |
| **Tool** | A function the model may ask the app to run (`ai.NewTool`), which runs as the user who asked. See [Give the model tools](https://docs.anetos.dev/guides/ai/index.md#4-give-the-model-tools) | The AI SDKs' word |
| **Agent** | Instructions, a model and tools kept together (`ai.Agent`), for an assistant in your app (`make:agent`); not a coding agent. See [Build an AI assistant](https://docs.anetos.dev/guides/ai-assistant/index.md) | The AI SDKs' word |
| **Embedding** | A vector of numbers that stands for a text's meaning (`ai.Embed`), stored with the rows to search by meaning. See [Search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md) | The same in every RAG library |


# Application lifecycle

Source: https://docs.anetos.dev/concepts/application-lifecycle/

An Anetos application goes through five phases: **New → Register → Boot →
Run → Shutdown**. Knowing which code runs in which phase tells you where to
put configuration, wiring, connections and cleanup.

```mermaid
flowchart LR
    New["New<br/>load config<br/>build logger"] --> Register["Register<br/>providers provide services<br/>(no I/O)"]
    Register --> Boot["Boot<br/>providers open connections,<br/>add components, hooks"]
    Boot --> Run["Run<br/>supervisor runs components"]
    Run --> Shutdown["Shutdown<br/>stop components by stage,<br/>then run hooks in reverse"]
```

## The phases

| Phase | Triggered by | What happens | Your code |
|---|---|---|---|
| **New** | `anetos.New()` | Loads configuration (environment, `.env.<APP_ENV>`, `.env`), binds and validates `AppConfig`, builds the logger | Options such as `WithSource`, `WithLogger` |
| **Register** | `app.Boot` / `app.Run` | Each provider's `Register`, in `Use` order | Provide services, read config. No I/O, no goroutines |
| **Boot** | `app.Boot` / `app.Run` | Each provider's `Boot`, in `Use` order | Open connections, add components, register shutdown hooks |
| **Run** | `app.Run(ctx, types...)` | The supervisor starts the selected components | Components do their work |
| **Shutdown** | `ctx` canceled (e.g. SIGTERM) or a fatal component failure | Components stop stage by stage, then hooks run in reverse order | Components return promptly; hooks release resources |

Because **every** Register runs before **any** Boot, a provider's Boot can
use services provided by providers added after it. Order still matters for
Boot itself and for shutdown hooks.

## Setting up the services

A new project's `main.go` builds its services in one function, `setup`,
which runs after `anetos.New` and before `Register`. Each service is built from
the app's settings by its package's `New`, and `db.Connect` connects to
the database:

```go
// illustrative (the start of a new project's setup)
func setup(app *anetos.App) (*web.Server, error) {
	if _, err := db.Connect(context.Background(), app, sqlite.Driver()); err != nil {
		return nil, err
	}
	if _, err := cache.New(app); err != nil { // CACHE_DRIVER
		return nil, err
	}
	q, err := queue.New(app) // QUEUE_DRIVER
	if err != nil {
		return nil, err
	}
	// … the mailer, storage, the scheduler, sessions
	return web.NewServer(app)
}
```

Each `New(app, …)`:

- reads its settings (`CACHE_*`, `QUEUE_*`…) and fails, naming the
  setting, when one is wrong;
- puts the service in the app's contexts and container, so a handler or a
  job reaches it with `cache.From(ctx)` and other packages with
  `anetos.Resolve[*cache.Cache](app)`;
- adds what goes with it: its commands (`migrate`, `queue:failed`,
  `cache:clear`…), a shutdown hook that closes its connection, doctor
  checks.

A service is built once per app: a second `New` for the same app is an
error. Order matters only where one service uses another (the mailer
queues mail when the queue exists; plugins come last), and the generated
`setup` is already in that order. Outside an app (a test, a tool),
each package has a constructor from explicit parts, such as
`cache.NewWithStore(store, prefix)` or `events.NewBus()`.

## Providers

A provider packages a piece of your own functionality with the two
phases above:

```go
// illustrative (from app.go)
type Provider interface {
	Name() string
	Register(a *App) error
	Boot(ctx context.Context, a *App) error
}
```

`app.Use(provider)` adds one; its `Register` and `Boot` run with the
others'. The framework's services don't need it (they're built in
`setup`), and plugins use their own interface ([Plugins](https://docs.anetos.dev/guides/plugins/index.md)).
A complete provider is in
[`examples/lifecycle`](https://github.com/anetos-dev/anetos/blob/main/examples/lifecycle/main.go) (region
`provider`).

## The service container

`anetos.Provide[T](app, v)` stores a value under its **static type** `T`;
`anetos.Resolve[T](app)` gets it back. It's a map, not a dependency-injection
engine: there's no autowiring and no reflection over constructors.

Use it to hand services from one provider to another at boot. Inside your
application code, prefer ordinary constructor parameters:

```go
// illustrative
d := anetos.MustResolve[*db.DB](app) // at boot
posts := handlers.NewPosts(d)        // plain Go from here on
```

Resolving from the container on every request works, but it hides
dependencies and costs a map lookup each time.

## Context values

A few services are needed by nearly every function that has a context: the
database connection is the main one. `app.AddContextValue(key, value)`
(called while providers register or boot) adds a value to every context
the app hands out: providers' Boot, components and `app.Go` tasks, HTTP
requests, and shutdown hooks. `app.Context(ctx)` adds the same values to a
context the app didn't create, such as in a CLI command or a test.

`db.Connect` uses this, which is why `db.Query[Post](c)` works in a handler
with nothing but the request context. Keep it for such cross-cutting
services; ordinary dependencies still belong in constructors.

The app's own context values are its clock and its logger:
`anetos.Now(ctx)` reads the time tests can freeze, and
`anetos.Logger(ctx)` returns the app's logger (`LOG_LEVEL`, `LOG_FORMAT`,
with the app's name and environment), so jobs, listeners and scheduled
tasks log like the rest of the app:

```go
// illustrative
anetos.Logger(ctx).InfoContext(ctx, "invoice sent", "invoice", inv.ID)
```

Plain `slog.Info` writes through Go's default logger instead, which the
app leaves alone. In handlers, `c.Logger()` adds the request ID and
route.

## Operations

An **operation** is one piece of work the app runs, start to end: an HTTP request, a queue job, an async or queued event listener, a
pub/sub message, a scheduled task, or an AI tool call. Each one gets its
own context from `app.StartOperation`, described by an `anetos.Operation`
(`Kind` such as `"request"` or `"job"`, and a `Name` such as
`"GET /posts/7"`). That context is how per-operation things stay apart:
repeated-query detection counts the queries of one operation, and the
roles and permissions are cached for one operation. The repeated-query
warning names it (`operation="request GET /posts"`).

`app.AroundOperations(fn)` wraps every operation from then on;
`db.Connect` uses it for [repeated queries](https://docs.anetos.dev/guides/n-plus-one/index.md).

## Failures during startup

- `anetos.New` returns an error that lists **every** invalid or missing setting.
- If a provider's Register or Boot fails, Boot stops, **runs the shutdown
  hooks registered so far** (so connections opened by earlier providers are
  closed), and returns the error. The app can't be started again after that.

## Shutdown

1. The supervisor cancels components **stage by stage**: HTTP first, then
   the scheduler, listeners, workers and background tasks, each stage
   draining before the next is canceled. See the
   [runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md).
2. Shutdown hooks (`app.OnShutdown`) run in **reverse** registration order,
   so a pool opened first is closed last. Every hook runs even if an
   earlier one fails; failures and panics are collected into `Run`'s error.

`APP_SHUTDOWN_TIMEOUT` (default 30s) is the **total** budget. Components use
it first, but hooks always keep the smaller of 5s and a fifth of it, so
cleanup still happens if a component hangs. Hooks run even then, so a stuck
component may briefly outlive the resources it uses; the error returned by
`Run` names it.

## Boot without Run

One-off programs (a migration, a report) can call `app.Boot(ctx)`, use the
services, then `app.Close()` to run the shutdown hooks. `Close` refuses to run
while `Run` is in progress; cancel `Run`'s context instead.

> **Coming from another framework?** `setup` is where Django's settings
> and `AppConfig.ready()`, Laravel's service providers and config files,
> or Rails' initializers would be: each `New(app)` reads its `.env` keys
> and registers the service. There's no global container: the `App` is
> passed explicitly, and a handler gets a service from its context
> (`cache.From(c)`). Your own providers add a `Register` and a `Boot`
> phase of their own.

## Related

- [Configure your application](https://docs.anetos.dev/guides/configuration/index.md)
- [Run background tasks](https://docs.anetos.dev/guides/background-tasks/index.md)
- [Runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md)


# Runtime supervisor

Source: https://docs.anetos.dev/concepts/runtime-supervisor/

Every Anetos application runs its long-lived work (HTTP servers, queue
workers, pub/sub listeners, the scheduler, background tasks) as goroutines
inside one process, managed by a **supervisor**. It decides what runs, what
happens when something fails, and how everything stops.

## Components

Anything long-running is a **background component** ("component" for
short on this page; the pieces of a page in `views/ui` are UI
components, another thing):

```go
// illustrative (from supervisor/component.go)
type Component interface {
	Name() string
	Run(ctx context.Context) error
}
```

`Run` blocks until the work is done or `ctx` is canceled. On cancellation,
the component stops taking new work, finishes or hands back what's in
flight, and returns. `app.Go(name, fn)` wraps a function as a component;
`app.Component(c)` adds your own type.

## Process types: one binary, many shapes

Components declare **process types** (Heroku's word, from the
`Procfile`: `web`, `worker`). A process can run all of them or only
some:

```bash
./blog run                            # everything: dev and small deployments
./blog run --only=web                 # web machines
./blog run --only=worker              # background machines
./blog run --only=scheduler           # one machine, or several with OnOneServer
```

The built-in components with process types are the web server (`web`),
the queue's workers (`worker`, from `q.Work`; see
[Queues](https://docs.anetos.dev/guides/queues/index.md)), pub/sub listeners (`listener`, from
`pubsub.Listen`; see [Pub/sub listeners](https://docs.anetos.dev/guides/pubsub/index.md)) and the
scheduler (`scheduler`,
from `schedule.New` once it has tasks; see
[Scheduling](https://docs.anetos.dev/guides/scheduling/index.md)). Your own components choose
theirs with `anetos.ProcessTypes("worker")`.

`run` is the binary's default command (`app.Execute`; see
[Commands](https://docs.anetos.dev/guides/commands/index.md)); in code, pass process types to
`app.Run(ctx, "web")`. Before v0.5 they were "roles" named `http`,
`workers` and `listeners`; those names still work, with a warning,
until v0.6.

- Components **without** process types run in every process.
- Asking for a process type nothing declares is an error, so typos in `--only`
  fail loudly. `schedule.New` and `pubsub.New` declare theirs
  (`Supervisor.Declare`) before their components exist, so
  `run --only=worker,scheduler` works in an app that has no task yet
  and keeps working once it has one.

Split processes share work through shared stores: the database or Redis
for the queue, the cache (database or Redis) for the scheduler's
`OnOneServer` locks, and a broker (Redis, Google Pub/Sub) for pub/sub;
the `memory` drivers stay inside one process.
[`examples/saas`](https://github.com/anetos-dev/anetos/tree/main/examples/saas) runs one binary as four
processes, `web`, `worker`, `listener` and `scheduler`, and its
`process_types_test.go` follows a sign-up from one to the other.

## Failure policies

| Policy | On error or panic | Use for |
|---|---|---|
| `RestartNever` (default) | Logged; component stays stopped; app keeps running | One-off background tasks |
| `RestartOnFailure` | Restarted after exponential backoff with jitter | Workers, listeners, pollers |
| `StopOnFailure` | Whole app shuts down; `Run` returns the error | Components the app can't live without, e.g. the HTTP server |

Panics are recovered and treated as failures, with the stack trace logged.

**Backoff** starts at `Initial` (default 1s), doubles each consecutive
failure up to `Max` (default 30s), and varies by ±20% so many instances
don't restart in lockstep. A component that ran longer than `Max` before
failing counts as healthy again, and its delay resets. If
`MaxRestarts` (default unlimited) is exceeded, the failure escalates like
`StopOnFailure`, so a crash-looping process exits and your orchestrator
(systemd, Kubernetes…) can take over.

## Staged shutdown

When the run context is canceled (usually by SIGINT or SIGTERM) or a
component escalates a failure, the supervisor stops components in **stages**.
Each stage is canceled only after the previous one has fully drained:

| Order | Stage | Why this order |
|---|---|---|
| 1 | `StageIngress` (HTTP) | Stop accepting requests; finish in-flight ones |
| 2 | `StageScheduler` | Stop starting scheduled runs, which produce jobs |
| 3 | `StageListeners` | Stop pulling external messages, which also produce jobs |
| 4 | `StageWorkers` | Finish in-flight jobs, including ones just produced above |
| 5 | `StageBackground` | Ad-hoc tasks (`app.Go`) |

The rule is **producers stop before consumers**, so work already accepted
gets done. All stages share one deadline (in an app, `APP_SHUTDOWN_TIMEOUT`
minus the part reserved for shutdown hooks). If it passes, the remaining
stages are canceled together with a short grace period, and `Run` returns an
error naming only the components that are still running, so the process
can exit anyway.

If every component finishes on its own, `Run` returns too. From that moment
new components are refused with `ErrStopping` rather than being started and
immediately canceled.

> **Warning:** A component that ignores `ctx` can't be stopped gracefully. It
> will be reported as stuck when the deadline passes.

## Health

- `app.Supervisor().Ready()` is true while running and not shutting down,
  and every component that implements `Ready() bool` is ready. Such a
  component that is waiting to restart or has failed counts as not ready.
  It backs the server's `GET /health/ready` and `health:check`;
  `migrate.New` adds one (`migrations`) that isn't ready while
  migrations are pending.
- `app.Supervisor().ShutdownDeadline()` is when the components' share of
  `APP_SHUTDOWN_TIMEOUT` runs out, once shutdown has begun: queue workers
  use it to stop their jobs in time.
- `app.Supervisor().Status()` lists each component's state (`pending`,
  `starting`, `running`, `backoff`, `done`, `failed`, `stopped`), restart
  count and last error.

> **Coming from another framework?** This replaces running the queue
> workers and the scheduler as separate programs under a process
> manager: a Celery worker and Celery beat beside a Django app,
> `queue:work` and `schedule:work` beside a Laravel one, or a Sidekiq or
> Solid Queue process (or Solid Queue's Puma plugin) beside a Rails
> one. Everything runs in your app's
> own binary, and `--only` splits it apart when you need to scale.
> `./app queue:work` and `./app schedule:work` exist too: they are
> `run --only=worker` and `run --only=scheduler`.

## Related

- [Run background tasks](https://docs.anetos.dev/guides/background-tasks/index.md)
- [Deploy](https://docs.anetos.dev/guides/deployment/index.md): process types in processes and containers
- [Application lifecycle](https://docs.anetos.dev/concepts/application-lifecycle/index.md)
- Package docs: `supervisor`


# Commands and the app binary

Source: https://docs.anetos.dev/concepts/commands/

Your app builds to one binary that is both the server and its
maintenance tool. `app.Execute()` reads the first argument and runs that
command: `run` by default, or `serve`, `migrate`, `route:list` and
commands of your own. Code generation lives elsewhere, in the `anetos`
developer tool, because it writes source code rather than running the app.

```mermaid
flowchart LR
    A["./blog args"] --> D{"first argument"}
    D -->|"none, or only flags"| R["run"]
    D -->|"help, -h, cmd -h"| H["print usage<br/>(no boot)"]
    D -->|unknown| E["exit 2"]
    D -->|a command| K{"ManagesApp?"}
    R --> K
    K -->|"yes: run, serve"| AR["app.Run<br/>boot, run components,<br/>shut down"]
    K -->|no| B["app.Boot → Run(ctx) → app.Close"]
```

## Where commands come from

There is no global registry. Commands are registered on the `App`, by the
code that wires the part they belong to:

| Command | Registered by |
|---|---|
| `run [--only=type,…]` (the default), `help`, `version`, `doctor`, `about` | Every app |
| `serve`, `route:list` | `web.NewServer` |
| `openapi` | `openapi.Register` ([Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md)) |
| `migrate`, `migrate:rollback`, `migrate:reset`, `migrate:fresh`, `migrate:status`, `db:seed`, `db:schema`, `search:reindex` | `migrate.New` ([Migrations](https://docs.anetos.dev/guides/migrations/index.md), [Search](https://docs.anetos.dev/guides/search/index.md)) |
| `cache:clear` | `cache.New` ([Cache](https://docs.anetos.dev/guides/cache/index.md)) |
| `queue:work`, `queue:failed`, `queue:retry`, `queue:forget`, `queue:flush`, `queue:clear` | `queue.New` ([Queues](https://docs.anetos.dev/guides/queues/index.md)) |
| `pubsub:publish` | `pubsub.New` ([Pub/sub listeners](https://docs.anetos.dev/guides/pubsub/index.md)) |
| `schedule:list`, `schedule:run`, `schedule:test`, `schedule:work` | `schedule.New` ([Scheduling](https://docs.anetos.dev/guides/scheduling/index.md)) |
| `rbac:roles`, `rbac:user`, `rbac:assign`, `rbac:unassign` | `rbac.New` ([Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md)) |
| Your own | `app.Command` or `app.AddCommand` |

So a binary only offers commands for what it actually set up: without
`migrate.New`, `./blog migrate` is an unknown command. Registering one
name twice is an error.

```go
// illustrative
app.Command("reports:send", "Email the weekly report", func(ctx context.Context, args *cmd.Args) error {
	return reports.Send(ctx, args.Stdout)
})
```

## How a command boots and closes the app

There are two kinds of commands:

- **Commands that manage the app** (`ManagesApp: true`): `run` and
  `serve`. They call `app.Run`, which boots the app, runs the selected
  components until a signal, and shuts down in stages.
- **All others** run between `app.Boot` and `app.Close`. Their context
  comes from `app.Context`, so it carries what the app provides, such as
  the database. `app.Close` runs the shutdown hooks afterwards, even if
  the command panics, so connections are closed.

`help`, `-h`, `<command> -h` and unknown commands are answered before
anything boots. Because `db.Connect` pings the database at boot, not
when it is called, `./blog help` works with no database. Every command
that boots, `route:list` included, needs the database reachable.

An app runs one command: afterwards it is stopped and can't boot again,
so tests call `app.ExecuteArgs` on a new app each time.

## Signals and exit codes

The command's context is canceled on the first SIGINT or SIGTERM; a
second signal ends the program at once.

| Exit status | When |
|---|---|
| 0 | Success; `help`; `run` or `serve` stopped by a signal (that is how they end) |
| 1 | The command returned an error, including a command other than `run`/`serve` cut short by a signal |
| 2 | Usage errors: an unknown command, a bad flag, an error from `cmd.Usagef` |

Scripts and orchestrators can rely on these codes: a failed
`./blog migrate` in a deploy step exits 1.

## Process types: one binary, several shapes

`run --only=web` runs the components of the `web` process type plus
those without one; `serve` is the same as `run --only=web`. Your own
components get process types with `anetos.ProcessTypes`. A process type
no component has and no
package declared is an error, so a typo in `--only` fails at startup. The same binary can run
the web tier on some machines and background work on others. See
[the runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md).

## The developer tool is a different program

`anetos` (module `anetos.dev/anetos/cli`) runs on your machine,
not on servers. It writes your project's source files and runs the
development loop:

| `anetos` command | Does |
|---|---|
| `new` | Creates a project |
| `dev` | Regenerates, rebuilds and restarts the app on every change |
| `make:handler`, `make:model`, `make:migration`, `make:middleware` | Write new source files; never overwrite |
| `generate` | Writes typed model columns ([Code generation](https://docs.anetos.dev/concepts/code-generation/index.md)) |
| `key:generate` | Sets a new `APP_KEY` in `.env` when it has none (`--show` prints one; `--force` replaces a set key, keeping the old one in `APP_PREVIOUS_KEYS`) |

The split follows what each needs. The app binary carries your compiled
code, which is what migrating and listing routes need. The tool reads and
writes your source, which only exists on your machine. Added
with `go get -tool`, it is pinned in `go.mod` and adds nothing to the app
binary. `anetos dev` runs the app binary with `run`, or with the
arguments you give after `--`.

> **Coming from another framework?** What Django's `manage.py`,
> Laravel's `artisan` or Rails' `bin/rails` do is split in two here.
> `./blog migrate` is built into your app's binary and runs in
> production; `go tool anetos make:model` writes source, so it runs only
> on your machine. Custom commands are functions registered on the app,
> not classes.

## Related

- [Commands](https://docs.anetos.dev/guides/commands/index.md), [Migrations](https://docs.anetos.dev/guides/migrations/index.md)
- [`anetos` tool and app commands reference](https://docs.anetos.dev/reference/cli/index.md)
- [Application lifecycle](https://docs.anetos.dev/concepts/application-lifecycle/index.md), [Runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md)
- Package docs: `cmd`


# Configuration

Source: https://docs.anetos.dev/concepts/configuration/

Where settings come from, how they become typed Go structs, and why a bad
setting stops the app before it serves a single request.

```mermaid
flowchart LR
    E["Process environment"] --> S["config.Source<br/>(first layer with the key wins)"]
    F[".env.(APP_ENV)"] --> S
    D[".env"] --> S
    S --> B["Bind: tags, defaults,<br/>every bad key listed"]
    B --> V["Validate() hooks"]
    V --> T["Typed structs<br/>AppConfig, web.Config, yours"]
```

## One source, three layers

A `config.Source` answers one question: what is the value of this key?
`anetos.New` builds it with `config.Load`, which consults, highest priority
first, the process environment, then `.env.<APP_ENV>` (such as
`.env.development`), then `.env`. `APP_ENV` itself comes from the
environment, else from `.env`. Missing files are fine, so production can
rely on the environment alone; a file that can't be parsed stops startup
with its name and line. `app.Source()` hands the same source to every
package; `anetos.WithSource` replaces it.

`anetostest.New` doesn't use the settings in `.env`, so your development
database can't leak into tests (it only looks at `.env`'s `DB_DRIVER`,
to stop a test that would use SQLite by mistake). It forces `APP_ENV=testing` and a random `APP_KEY` over
the process environment, and reads `.env.testing` below it.

## From strings to typed structs

`config.Get[T]` (or `config.Bind`) reads a struct's tags at startup and
converts each value to the field's type: numbers, booleans, durations,
comma-separated slices, pointers, and types with an `UnmarshalText` method.

```go
// illustrative
type MailConfig struct {
	Host    string        `env:"HOST,required"`
	Port    int           `env:"PORT" default:"587"`
	Timeout time.Duration `env:"TIMEOUT" default:"10s"`
}

type Config struct {
	Mail    MailConfig  `prefix:"MAIL_"`         // MAIL_HOST, MAIL_PORT, MAIL_TIMEOUT
	Archive *MailConfig `prefix:"ARCHIVE_MAIL_"` // stays nil unless an ARCHIVE_MAIL_* key is set
}

cfg, err := config.Get[Config](app.Source())
```

A key set to the **empty string counts as unset**: the default applies and
`required` fails, so a blank line copied from `.env.example` can't break a
number. An empty value still hides the layers below it: an empty
`MAIL_PORT` in the environment means `587`, not the value in `.env`.

## Validation at startup

Binding collects **every** missing required key and every value that
doesn't parse, one `*config.FieldError` each
(`config: DB_PORT (Config.Port): invalid integer "abc"`), and returns them
together. If binding succeeded, structs that implement `config.Validator`
check what tags can't express, such as ranges and combinations: nested
structs first, the outer one only if they passed. The framework's own
hooks also report all their problems at once, but a parse error hides hook
problems until the next run.

## Each package reads its own keys

Framework settings are ordinary structs bound from `app.Source()`, each
when you call its constructor:

| Constructor | Loader | Keys |
|---|---|---|
| `anetos.New` | (built in) | `APP_*`, `LOG_*` into `anetos.AppConfig` |
| `web.NewServer` | `web.LoadConfig(src)` | `HTTP_*` |
| `db.Connect` | `db.LoadConfig(src, "")` | `DB_*` |
| `session.New` | `session.LoadConfig(src)` | `SESSION_*` |

So an `HTTP_*` mistake is reported by `web.NewServer`, still before
`app.Run`. `db.LoadConfig(app.Source(), "ANALYTICS_")` reads
`ANALYTICS_DB_URL` and friends for a second connection.

## Secrets

`APP_KEY` is 32 random bytes written as `base64:…`; it encrypts session
cookies. A malformed key fails `anetos.New`; a missing one fails
`session.New`. `APP_PREVIOUS_KEYS` lists old keys that still decrypt,
so you can rotate the key without logging everyone out. Both have the type
`anetos.Secret`, which prints, logs and encodes as `[redacted]`: logging
`app.Config()` doesn't leak the key, and `string(cfg.Key)` gets the value.

`db.Config` keeps `DB_PASSWORD` and `DB_URL` in plain strings (drivers
need them as they are), but its `String` and `LogValue` methods mask the
password in both, so printing or logging the struct doesn't leak them. Your own
secrets belong in `anetos.Secret` fields.

## Environments

`APP_ENV` is `development`, `testing`, `staging` or `production`; anything
else stops startup. It defaults to **`production`**, so a forgotten
setting gets the strictest behavior.

| Behavior | Depends on `APP_ENV` |
|---|---|
| Log format, when `LOG_FORMAT` is empty | JSON in production, text elsewhere |
| `APP_DEBUG=true` | Rejected in production |
| HSTS header | Production only |
| Secure session cookies, when `SESSION_SECURE` is unset | Off in development and testing |
| Query log, when `DB_LOG_QUERIES` is unset | On in development only |
| Repeated-query (N+1) warnings, when `DB_REPEATED_QUERIES` is unset | On in development and testing |
| `migrate:fresh` | Development and testing only |

## Design notes

- **No `config("app.name")` lookups.** A misspelled key fails at compile
  time or startup, never as a silent empty string. The cost is wiring: you
  pass config values to the code that needs them.
- **Environment variables first.** Platforms set them and secrets stay out
  of the repository; `.env` is a local convenience. The limit is a flat
  namespace of strings, with comma-separated lists and no maps.
- **Fail fast.** A wrong value shows up at deploy time, not when a rarely
  used code path first reads it. The cost: one invalid setting stops the
  whole app, and a new value needs a restart.

> **Coming from another framework?** The struct takes the place of
> Django's `settings.py`, Laravel's `config/*.php` files or Rails'
> `config/`, and it's read at startup, so there's no config cache to
> clear. `APP_KEY` is the
> app's secret key, and `APP_PREVIOUS_KEYS` lets you rotate it.

## Related

- [Configure your application](https://docs.anetos.dev/guides/configuration/index.md)
- [Configuration reference](https://docs.anetos.dev/reference/configuration/index.md), including
  [struct tags](https://docs.anetos.dev/reference/configuration/index.md#struct-tags) and
  [load order](https://docs.anetos.dev/reference/configuration/index.md#load-order)
- [Test settings](https://docs.anetos.dev/reference/anetostest/index.md#settings),
  [rotating the key](https://docs.anetos.dev/guides/sessions/index.md#rotate-the-key)
- [Application lifecycle](https://docs.anetos.dev/concepts/application-lifecycle/index.md)


# Code generation

Source: https://docs.anetos.dev/concepts/code-generation/

Queries in Anetos name columns with typed Go values, such as
`PostCols.Title`, that `anetos generate` writes from your model structs. The
compiler checks every column name and every value's type, and nothing
has to look a column up at query time.

```mermaid
flowchart LR
    M["model structs<br/>(your .go files)"] --> T["Go type checker<br/>(no code runs)"]
    T --> R["column rules<br/>(same as the db package)"]
    R --> G["models_gen.go<br/>PostCols, AuthorCols…"]
    G --> Q["your queries<br/>checked by the compiler"]
```

## Why generate columns

A query builder has to know which column a condition is about. There are
three ways to say it:

- **Strings**, `db.C("title")`: a typo or a renamed column shows up only
  when the query runs, and nothing checks the value's type.
- **Reflection at query time**: inspect a struct or a field pointer on
  every call to find the column. That costs time on every query, and
  Anetos inspects types only at startup, never per query or request.
- **Generated values**: `PostCols.Title` is a `db.Column[string]`, so
  `PostCols.Title.Eq(42)` doesn't compile, a renamed field breaks the
  build, and *go to definition* works.

Go can't refer to a struct field as a value, so these values have to be
written out. `anetos generate` writes them, so you don't. Strings remain
available (`db.C`), as do hand-declared columns (`db.Col[int]("views")`).

The typed columns don't replace the `db` package's own model metadata.
That package still reads each model's fields and tags once per type,
caches them, and uses them to scan rows. The generator and the runtime
apply the same column rules, and a test in the framework checks that
they agree on a fixture with every kind of field.

## What `anetos generate` reads

`anetos generate` loads your packages with the Go type checker
(`golang.org/x/tools/go/packages`). It never runs your code, and it
lives in the `cli` module, so the core module doesn't depend on it.

It only type-checks packages that could have models: those that import
`db` (directly or not), mention `TableName` or a `//anetos:` directive,
or already have a `models_gen.go`. It reads the package as if its
current `models_gen.go` were empty, so a stale file can't get in the
way. Compile errors elsewhere, such as code using a column you haven't
generated yet, don't stop it. Syntax errors and errors in a model's field
types do.

## What counts as a model

A package-level struct is a model when it:

- embeds `db.Model`, `db.Timestamps` or `db.SoftDeletes`, at any depth;
- has a `TableName() string` method; or
- has `//anetos:model` in its doc comment.

`//anetos:skip` leaves a struct out. These rules cover the usual models
without annotations, while request structs and other DTOs next to them
aren't picked up. Models must be in files without build constraints, so
the output is the same whichever platform runs the generator.

## What it writes

One `models_gen.go` per package, declaring `<Model>Cols` for each model
(`postCols` for an unexported `post`). It is an anonymous struct with one
`db.Column[T]` per column, where `T` is the field's type, pointers
included:

```go
// illustrative (an excerpt of examples/database/models_gen.go)
var PostCols = struct {
	ID          db.Column[int64]
	Tags        db.Column[[]string]
	PublishedAt db.Column[*time.Time]
}{
	ID:          db.Col[int64]("id"),
	Tags:        db.JSONCol[[]string]("tags"),
	PublishedAt: db.Col[*time.Time]("published_at"),
}
```

A nullable column is a `Column[*time.Time]`: compare with `new(t)`, and
`Set(nil)` writes NULL. A field tagged `db:"tags,json"` gets
`db.JSONCol`, which encodes the values you pass as JSON; `db.Pluck`
decodes them. `Of(table)` qualifies a column for joins.

The generator only replaces or removes files that start with its
`// Code generated by anetos generate. DO NOT EDIT.` header, and removes
`models_gen.go` from a package with no models left.

## Plain Go that you commit

The generated file is ordinary Go: declarations only, readable, with no
license header, because it belongs to your app. Commit it. The `anetos` tool is a Go tool dependency
(`go get -tool`), so each project pins the generator version in
`go.mod`, and the tool adds nothing to your binary.

You rarely run it by hand: `anetos dev` runs it before every build,
`make:model` right after writing the model, and a
`//go:generate go tool anetos generate` line runs it with `go generate`. In
CI, `anetos generate --check` writes nothing and exits with status 1 if any
file is out of date, so a model change without regeneration fails the
build.

## What is deliberately not generated

- **No query or repository code.** `db.Query[Post]`, `db.Find` and the
  rest are generic functions; the generator adds only column values.
- **No scanning code.** The `db` package scans with its cached metadata.
- **No migrations.** Tables come from migrations you write with the
  schema builder; `anetos make:migration` gives you a starting file.
- **No loading code.** `PostRels` holds one handle per relation field
  (`db.RelOf[Post, User]("Author")`); `With` and `db.Load` do the loading
  at runtime.

> **Coming from another framework?** Django's ORM, Eloquent and Active
> Record resolve column names given as strings or keywords when the
> query runs. Here the names are generated Go values, so a typo breaks
> the build instead of a request.

## Related

- [Generate typed columns](https://docs.anetos.dev/guides/code-generation/index.md)
- [`anetos generate` reference](https://docs.anetos.dev/reference/anetos-generate/index.md), [Models reference](https://docs.anetos.dev/reference/models/index.md)
- [The data layer](https://docs.anetos.dev/concepts/data-layer/index.md), [Commands and the app binary](https://docs.anetos.dev/concepts/commands/index.md)


# How testing works

Source: https://docs.anetos.dev/concepts/testing/

What `anetostest` builds for a test, how it keeps tests from seeing each
other's data, how its client imitates a browser, and where a test run
differs from production.

```mermaid
flowchart LR
    T["test"] --> C["anetostest.App client<br/>cookie jar, CSRF token, Referer"]
    C -->|"SAVEPOINT per request"| R["the app's router<br/>(global middleware, sessions, CSRF, handlers)"]
    R --> X["app.Context()<br/>database + test transaction"]
    T -->|"assertions, factories"| X
    X -->|"rolled back when the test ends"| D[("test database")]
```

## The app under test is your app

`anetostest.New(t, setup)` calls the same `setup` function `main` uses to
connect the database and add the server and routes. It then boots the app
(providers run; components such as the HTTP server and workers don't
start), runs the migrations `migrate.New` registered, and closes the app
when the test ends. There is no test-only wiring: `session.New` and
`migrate.New` provide their manager and runner to the app, and
`anetostest` finds them there.

Settings come from these sources, highest priority first: `anetostest.Env`
options; `APP_ENV=testing`, a random `APP_KEY`, and a `CACHE_PREFIX`,
`SESSION_PREFIX`, `QUEUE_PREFIX` and `PUBSUB_PREFIX` of the app's own, and
`MAIL_DRIVER=memory` and `STORAGE_DRIVER=memory`, so emails are kept
rather than sent and files kept in memory; the process
environment; `.env.testing` next to `go.mod`; then `HTTP_ACCESS_LOG=false`,
`APP_URL=http://example.test` (the test client's site) and `MAIL_FROM_ADDRESS=test@example.com`.
Settings in `.env` are never used. With SQLite and no `DB_NAME` or
`DB_URL`, the database is `:memory:`, never the default `database/app.db`.
If the test settings name a database without `DB_DRIVER` while `.env`
sets another `DB_DRIVER`, the test fails rather than create a SQLite
file of that name. The app's logs go to the test's log.

## Database isolation

| Database | Each test gets |
|---|---|
| SQLite in memory (the default) | Its own database, migrated from scratch. No transaction |
| SQLite file, PostgreSQL, MySQL | The shared database, migrated, and a transaction begun in `New` and rolled back when the test ends |

Whether the database is in memory is asked of SQLite after connecting.
The transaction rides in `app.Context()`, and every test request runs with
that context, so handlers, assertions and factories all join it (see
[The data layer](https://docs.anetos.dev/concepts/data-layer/index.md)). Each request also runs inside a
savepoint, `anetostest_request`. If releasing it fails, because a statement
failed and PostgreSQL aborted the transaction, the client rolls back to the
savepoint: that request's writes are undone and the test can go on.

Tests can call `t.Parallel()` with in-memory SQLite and with a database
server. They can't with a SQLite file, where each test's transaction holds
the only write lock. An `App` handles one request at a time: make one per
test or subtest.

## A client that behaves like a browser

Requests go straight to the router with `httptest`, as
`http://example.test/…`, through every global and route middleware.
Nothing listens on a port. The client keeps what a browser keeps:

- **Cookies.** Its jar honors `Path` and expiry, and ignores `Secure` and
  `Domain`, so `SESSION_SECURE` and `__Host-` cookies work over the
  in-process HTTP.
- **The CSRF token.** For every method but GET, HEAD, OPTIONS and TRACE, it
  asks the app's `session.Manager` for a token with `Edit`, which changes
  the session in the jar without counting as a request (flash data stays
  for the real next request), and sends it as `X-CSRF-Token`. An
  `X-CSRF-Token` you set, or a `_token` field in a form sent with the form
  methods, is sent instead. CSRF stays on: tests pass the same checks as
  users.
- **The `Referer`.** The last page it loaded (a GET answered 200 with
  HTML, not an htmx fragment) is sent with the next request, so a failed
  form is redirected back to it, as in
  [Server-rendered HTML](https://docs.anetos.dev/concepts/server-rendered-html/index.md#the-form-round-trip).

Form methods send `Accept: text/html` and JSON methods `application/json`,
so on a route with sessions the same failed validation is a redirect back
for one and a 422 for the other.

## Assertions and factories

Response assertions are methods that report with `t.Errorf` and return
the response, so one request's checks chain and every failure shows at
once, with the start of the body. Session assertions read the session the
next request will carry. Database assertions and `anetostest.Create` are
generic functions (`AssertDatabaseHas[T](app, conds...)`) because Go has
no generic methods; they take the query builder's typed conditions.

Factories (`db/factory`) are values: `factory.New(func(n int) T)`, where
`n` is a sequence number for values that must differ. `With` returns a new
factory, so a shared base can't be changed by one test. Rows are inserted
with `db.Create`, so hooks run. Sequence numbers never reset within a test
binary: check the rows `Create` returns, not "Post 1".

## Where tests differ from production

- **`db.AfterCommit`** callbacks run as if the test's transaction weren't
  there: at once when registered directly in it, and when a `db.Tx`
  inside it commits (a request's, say). With in-memory SQLite there is no
  test transaction, so this is how they always work.
- **Queue workers** use their own connections, so they don't see the
  test's rows. With `QUEUE_DRIVER=sync` (the default) jobs run at once,
  in the request; to run workers, use `WithoutTransaction()`.
- **PostgreSQL errors inside a request.** The savepoint only helps between
  requests. A handler that catches a failed statement and keeps querying
  fails in a test, where production would carry on.
- **Timeouts.** A query canceled by a timeout closes the connection that
  holds the test's transaction (PostgreSQL, MySQL); the test fails.
- **MySQL DDL** commits the test's transaction; the test fails.
- **Other connections.** Code that opens its own connection, or starts
  `db.Tx` on a new context, doesn't see the test's rows and can wait on its
  locks until the test times out.

For these paths, pass `anetostest.WithoutTransaction()`: the test's writes
are committed, and the test cleans up after itself.

```go
// illustrative
app := anetostest.New(t, setup, anetostest.WithoutTransaction())
t.Cleanup(func() { _, _ = db.Exec(app.Context(), "DELETE FROM notes") })
```

## Recording and fakes

A test checks what the app did besides answering: the jobs it
dispatched, the events it emitted, the email it sent and the messages it
published. Rather than swapping these services for test doubles,
`anetostest` watches the real ones: the queue, the event bus, the
mailer and the pub/sub each have an `Observe` hook, which `anetostest.New`
uses at the end of `setup` to record everything. The app runs as it
does in production, so a test of a job's effect and a test of its
dispatch use the same setup.

When a test only wants to know that something was asked for, a fake
stops the side effect: `FakeQueue` keeps jobs from being stored or run,
`FakeEvents` keeps events from reaching their listeners, `FakePubSub`
keeps messages from the broker. Each is a switch on the real service
(`Fake`), so nothing else about the app changes. Email has no fake:
tests never send it (`MAIL_DRIVER=memory`). Language models are the
exception: a test uses the AI client's fake provider
(`AI_PROVIDER=fake`, unless the test sets another), since a model's
answers vary and cost money;
`FakeAI` scripts them, and everything around the model (schemas,
validation, tools) runs for real. Assertions are typed:
`AssertDispatched[ChargeOrder]` decodes the recorded jobs as a worker
would, so it checks what the worker will get.

Async event listeners still use their own connections, like queue
workers: wait for them with `bus.Wait`; see [Queues](https://docs.anetos.dev/guides/queues/index.md#5-test)
and [Events](https://docs.anetos.dev/guides/events/index.md#5-test).

## Time

The framework reads the time an app can observe from the app's clock
(`anetos.Now(ctx)`, `app.Now()`) rather than `time.Now`: timestamps,
lifetimes and expiries. In production it is the system clock; a test
freezes it (`app.Freeze`) or moves it (`app.Travel`), and everything
that reads it follows, the test client's cookies included. Time kept by
database and Redis servers, timeouts and the loops of workers and the
scheduler are real: a test can't fast-forward a server.

> **Coming from another framework?** `anetostest.New` gives each test a
> fresh in-memory database, or migrations plus a transaction per test,
> like Django's `TestCase`, Laravel's `RefreshDatabase` or Rails'
> transactional tests. Unlike in those, CSRF protection stays on in
> tests: the client sends the token.

## Related

- [Test your app](https://docs.anetos.dev/guides/testing/index.md), [Seed the database](https://docs.anetos.dev/guides/seeders/index.md)
- [Testing reference](https://docs.anetos.dev/reference/anetostest/index.md)
- [The data layer](https://docs.anetos.dev/concepts/data-layer/index.md), [Server-rendered HTML](https://docs.anetos.dev/concepts/server-rendered-html/index.md)
- [Transactions](https://docs.anetos.dev/guides/transactions/index.md)


# Performance

Source: https://docs.anetos.dev/concepts/performance/

What a request costs in Anetos, where the time goes in a real page, and
how the framework is kept from getting slower. The numbers come from
the repository's benchmarks, with their method and code:
[docs/benchmarks/v0.3.md](https://github.com/anetos-dev/anetos/blob/main/docs/benchmarks/v0.3.md).

## What a request costs

The reference is the same work written by hand with `net/http` and
`database/sql`. Measured in-process (no network), on a 2-vCPU cloud
machine, Go 1.27:

| Work | By hand | Anetos router | Anetos server (default middleware) |
|---|---|---|---|
| Hello world | 4.0µs | +0.6µs | +3.0µs |
| JSON in, bound and validated, JSON out | 6.7µs | +1.3µs | +4.1µs |
| One row by key from SQLite, as JSON | 19.1µs | +6.3µs | +13.7µs |

The router and typed handlers ([`web.H`](https://docs.anetos.dev/guides/handlers/index.md)) cost
about a microsecond, as much as chi, Gin or Echo doing the same work.
The server's middleware (recover, request IDs, client IP, security
headers, body limit, timeout) costs about 3µs; with a database the
timeout's context costs more, since `database/sql` watches it with a
goroutine per query. `db.Find` costs about 5µs over a hand-written
query and scan, and a list of 20 rows the same few microseconds.

## Where a page's time goes

The page an app made with `anetos new` and `make:auth` serves to a
logged-in user, with 20 rows from SQLite:

```mermaid
flowchart LR
    A["Middleware, access log,<br/>locale: +9.5µs"] --> B["Session cookie<br/>opened: +10.7µs"]
    B --> C["CSRF<br/>(a GET): ~0"]
    C --> D["The user loaded<br/>from the database: +31.9µs"]
    D --> E["20 rows and the HTML:<br/>+105.5µs"]
```

Each step is what that part adds to the one before (a hello route
served with more and more of the stack, then the page). The page takes
about 160µs in all, most of it in the two queries: the list's query
alone takes 72µs and writing its HTML 3.6µs. That is on SQLite in
memory, the fastest database a request can reach; with PostgreSQL or
MySQL over a network, each query also waits a round trip, often 100µs
or more, and the framework's share shrinks further. What helps most:

- **Make fewer, simpler queries.** Load related rows with `With` rather
  than in a loop ([Find N+1 queries](https://docs.anetos.dev/guides/n-plus-one/index.md)), select a
  page of rows, index what you filter and sort by.
- **Cache what many requests read** ([Cache](https://docs.anetos.dev/guides/cache/index.md)).
- **Do slow work after the response:** emails, reports and calls to
  other services belong in [queue jobs](https://docs.anetos.dev/guides/queues/index.md).
- **Measure your own app** before optimizing it: Go's benchmarks and
  profiler work on handlers served in-process, as `bench/` does, and on
  tests made with [anetostest](https://docs.anetos.dev/concepts/testing/index.md).

## How Anetos stays fast

The rules the code follows:

- **No reflection per request.** Binding plans, validation rules, routes
  and models' columns are worked out once, at boot or first use.
- **One context value per request** for the router's state, which
  holds the request ID, the client's address and the locale, rather
  than a context and a copy of the request per middleware.
- **Nothing done twice.** A session notes its changes as they happen
  and is written back only if something changed; the keys of recent
  encrypted messages (a session cookie the browser sends again) are
  cached; row scanners are reused from row to row.
- **No pooling where it would bite.** Render buffers are pooled;
  `web.Ctx` isn't, so a handler that keeps one never sees another
  request's.

And the checks that keep them:

- **Allocation budgets.** The allocations a request or query makes
  beyond the hand-written work are counted by a test
  (`bench/budget_test.go`) in every CI run: growing them fails it, so a
  change that needs more must say why. (The page's parts are counted in
  all, with some headroom for differences between Go releases.)
  Allocations, unlike times, are the same on every run.
- **Pull requests are compared with their base.** The CI builds the
  benchmarks of both and runs them in turns on one machine; more
  allocations, or a median more than 20% slower with every sample
  slower, fail the check (`make bench-compare` does it locally); the
  label `benchmark-ok` accepts a regression that is worth it.

## Related

- [Benchmarks: results, method and analysis](https://github.com/anetos-dev/anetos/blob/main/docs/benchmarks/v0.3.md)
- [HTTP request lifecycle](https://docs.anetos.dev/concepts/http-request-lifecycle/index.md)
- [Data layer](https://docs.anetos.dev/concepts/data-layer/index.md)
- [Find N+1 queries](https://docs.anetos.dev/guides/n-plus-one/index.md)


# Web

Source: https://docs.anetos.dev/concepts/web/

- [HTTP request lifecycle](https://docs.anetos.dev/concepts/http-request-lifecycle/index.md): What happens between a request arriving and a response leaving, and where your code can hook in.
- [Server-rendered HTML](https://docs.anetos.dev/concepts/server-rendered-html/index.md): How pages are rendered, how a visitor's state travels in an encrypted cookie, and how a failed form finds its way back to the page it came from.
- [Validation](https://docs.anetos.dev/concepts/validation/index.md): How rules in struct tags become a cached plan, what `web.H` does with the result, and why validation works the way it does.
- [Internationalization](https://docs.anetos.dev/concepts/internationalization/index.md): How Anetos finds the words to show a user: where messages come from, how a request's language is chosen, and how the language travels with work done for the user later.


# HTTP request lifecycle

Source: https://docs.anetos.dev/concepts/http-request-lifecycle/

What happens between a request arriving and a response leaving, and where
your code can hook in.

```mermaid
flowchart TB
    A["http.Server<br/>(the http component)"] --> G["Global middleware<br/>Recover → RequestIDs → RealIP → AccessLog →<br/>SecureHeaders → CORS → locale → BodyLimit → Timeout"]
    G --> M["ServeMux routing"]
    M -->|match| R["Route middleware<br/>(Use / Group / With)"]
    M -->|no match| F["404 / 405 / OPTIONS"]
    R --> H["Adapter: build Ctx, recover panics"]
    H --> B["web.H: bind → validate rules → Validate → your handler"]
    B --> O["Responder / JSON"]
    B -->|error| E["Error handler<br/>problem JSON or HTML page"]
    F --> E
```

## 1. The server

`web.NewServer(app)` creates an `http.Server` wrapped as a supervised
component (process type `web`, stage `StageIngress`, `StopOnFailure`). It listens
when `app.Run` starts and is **ready** once the port is bound; `/health/ready`
reports the whole app's readiness.

On shutdown the server is canceled **first** (see
[Runtime supervisor](https://docs.anetos.dev/concepts/runtime-supervisor/index.md)). It stops accepting
connections and gives in-flight requests a **grace period**
(`HTTP_SHUTDOWN_GRACE`, at most half of `APP_SHUTDOWN_TIMEOUT`). Request
contexts stay alive during the grace period; afterwards they are canceled
and the remaining connections are closed, so a stuck request can't eat the
time workers and hooks need. Long-lived handlers (server-sent events) should
also watch `srv.Stopping()` and end right away.

## 2. Global middleware

Every request, matched or not, passes through the global middleware:

| Middleware | Does |
|---|---|
| `Recover` | Last-resort panic catcher for middleware (handler panics are handled later, with more context) |
| `RequestIDs` | Reuses a safe incoming `X-Request-ID` or generates one; returned in the response and attached to logs |
| `RealIP` | Determines the client IP, trusting forwarding headers only from `HTTP_TRUSTED_PROXIES` |
| `AccessLog` | One structured log line per request (`health.*` routes at debug level) |
| `SecureHeaders` | `nosniff`, frame and referrer policies; HSTS in production |
| `CORS` | Only if `HTTP_CORS_ORIGINS` is set; answers preflights |
| `BodyLimit` | Caps the body at `HTTP_MAX_BODY` |
| `Timeout` | Puts a deadline of `HTTP_REQUEST_TIMEOUT` on the request context; a streaming handler lifts it with `web.WithoutTimeout` (as `c.EventStream()` does), keeping the cancellation when the client leaves |

## 3. Routing

Routes live on a standard `http.ServeMux`, so matching follows Go's rules:
the most specific pattern wins, and conflicting patterns panic at
registration. A catch-all route produces 404, 405 (with `Allow`) and
automatic `OPTIONS` responses.

## 4. Handler

The router builds a `*web.Ctx`, which is also a `context.Context`, and runs
your handler. `web.H` handlers first **bind** the input (body, then query,
header and path), then check its **validation rules** and run its
**Validate** method. The bind and validation plans are computed at startup,
so each request only copies and checks values; tags are never parsed per
request.

## 5. Response or error

A typed handler's result is written by its `Responder` or as JSON. An error
(or a panic) goes to the **error handler**. By default it logs 5xx errors
with the request ID and writes problem JSON or an HTML page, hiding internal
details unless `APP_DEBUG=true`. The HTML page can be the app's own, in
its layout (`Router.ErrorPages`, which `anetos new` sets up); under the
`web.JSONErrors` middleware every error is problem JSON, whatever the
client accepts (an API project has it on every request). Replace the
whole handler with `web.WithErrorHandler`, and reuse
`web.DefaultErrorHandler` for the cases you don't customize.

If a handler already started writing, an error can only be logged. The
response can't be changed any more.

## Design notes

- **net/http all the way down.** The router is an `http.Handler`, routes
  can serve any `http.Handler` (`web.WrapHandler`), and middleware is
  `func(http.Handler) http.Handler`, so you can leave the framework at any
  layer.
- **`Ctx` is a `context.Context`.** Pass `c` straight to the database or
  queue. It belongs to one request: don't keep it after the handler returns.
- **No reflection per request** beyond setting field values; see design
  principle 4.

## Related

- [Routing](https://docs.anetos.dev/guides/routing/index.md)
- [Performance](https://docs.anetos.dev/concepts/performance/index.md): what each step costs
- [Handlers and requests](https://docs.anetos.dev/guides/handlers/index.md)
- [Configuration reference](https://docs.anetos.dev/reference/configuration/index.md#http-server)


# Server-rendered HTML

Source: https://docs.anetos.dev/concepts/server-rendered-html/

How pages are rendered, how a visitor's state travels in an encrypted
cookie, and how a failed form finds its way back to the page it came from.

## Pages are components

A component is anything with `Render(ctx context.Context, w io.Writer)
error` (`view.Component`). templ generates that method, so the core
doesn't depend on templ. `view.Template` adapts `html/template`, and
`view.ComponentFunc` a function:

```go
// illustrative
hello := view.ComponentFunc(func(ctx context.Context, w io.Writer) error {
	_, err := io.WriteString(w, "<p>Hello</p>")
	return err
})
return c.Render(http.StatusOK, hello)
```

`c.Render` (and `web.Render`) renders into a buffer with the `*web.Ctx` as
`ctx`, and writes the page only when the component has finished. So a
render error, such as an unknown route name in `web.URL`, becomes an error
page, never half a page. And because the session is saved when the
response starts, a CSRF token that `view.CSRFField` creates during the
render still reaches the cookie. Helpers read the router and the session
from `ctx`; `view.Template` gets no context, so pass what it needs in data.

## The session is the cookie

The session middleware decrypts the cookie when a request arrives and
writes it back when the response starts. The cookie holds a random ID, the
CSRF token, when the session started and was last used, your values (as
JSON), and the flash data. It is sealed with AES-256-GCM under a key
derived from `APP_KEY` for every write (HKDF-SHA256, random salt), with the
cookie name authenticated alongside. A cookie that doesn't decrypt, or has
expired, starts an empty session.

- **Lifetime.** Expiry is checked against the times inside the cookie, so
  a replayed cookie can't outlive it: `SESSION_TTL` (2h) idle, and
  `SESSION_MAX_TTL` (7 days) in all, restarted by `Regenerate` and
  `Invalidate`.
- **Writes.** No cookie until something is stored; then a write when the
  session changes, and at most every tenth of `SESSION_TTL` to keep
  it alive.
- **Attributes.** `HttpOnly`, `SameSite=Lax`, and `Secure` outside
  development and testing. A Secure cookie without `SESSION_DOMAIN` and
  with path `/` is named `__Host-anetos_session`, so a subdomain can't
  plant one.
- **Key rotation.** Each cookie records its key. Old keys in
  `APP_PREVIOUS_KEYS` still decrypt, and the cookie is re-encrypted with
  `APP_KEY` on its next write. Renaming the cookie, or switching Secure
  (which adds or drops `__Host-`), ends every session.

**Flash data.** `s.Flash(key, v)` is readable for the rest of this request
and during the next one; saving that request drops it (`Keep` and
`Reflash` extend it). Field errors and old input are stricter:
`view.Errors` and `view.Old` return only what the *previous* request
flashed, for one request.

## The form round trip

```mermaid
sequenceDiagram
    participant B as Browser
    participant M as Session + CSRF middleware
    participant H as web.H
    participant E as DefaultErrorHandler
    B->>M: GET /notes/new
    M-->>B: 200 form with _token (Set-Cookie)
    B->>M: POST /notes (Referer: /notes/new)
    M->>M: origin and token checks (403 on failure)
    M->>H: bind and validate
    H-->>E: validation error (your handler doesn't run)
    E-->>B: 303 to /notes/new, errors and input flashed
    B->>M: GET /notes/new
    M-->>B: 200 form with view.Errors and view.Old
```

When a request other than GET or HEAD fails validation (422, or 400 with
field errors), `web.DefaultErrorHandler` redirects back if the request
comes from a browser (`Sec-Fetch-Mode: navigate`, or `Accept` listing
`text/html`), isn't htmx (unless boosted), and has a session. It flashes
the errors in order and the posted values, minus `_method` and fields whose
names contain `password`, `secret` or `token`. The 303 goes to the
`Referer` if it is on this site, else `/`: the session doesn't track pages.
JSON clients and htmx get the 422.

## CSRF protection

`web.CSRF` checks every method except GET, HEAD, OPTIONS and TRACE in two
layers. First, Go's `http.CrossOriginProtection` rejects requests the
browser marks as cross-site (`Sec-Fetch-Site`, or an `Origin` that isn't
this host); requests with neither header pass. Then the `_token` field or
`X-CSRF-Token` header must match the session's token, which is masked with
a fresh random pad at every render so compressed pages never repeat it
(BREACH). Both failures are **403**. `Regenerate` replaces the token.

## Method override, assets and htmx

- **`web.MethodOverride`** runs globally, before routing picks a route by
  method: a POST with `_method` of PUT, PATCH or DELETE, in the query or a
  URL-encoded body (restored afterwards), is routed with that method.
  Multipart bodies aren't read; put `?_method=PUT` in the action.
- **`view.NewAssets`** hashes every file once, at startup. `assets.URL`
  adds `?v=<hash>`; the current hash is cacheable for a year, anything else
  revalidates (`no-cache`, `ETag`).
- **htmx** is bundled (`htmx.FS`), so there's no JavaScript build step.
  `c.IsHTMX()` adds `Vary: HX-Request`, and a layout sends the token with
  `hx-headers` and `view.CSRFToken`.

## Guarantees and trade-offs

- **Unreadable and unforgeable**, as long as every instance shares `APP_KEY`.
- **Not revocable.** `Invalidate` empties the session in this browser; a
  copied cookie works until its idle or absolute expiry.
- **About 4 KB.** If the session doesn't fit, a failed form's input is
  dropped first (logged; errors stay), then the save is skipped (logged).
  Store IDs, not records.
- **Changes after the response starts are lost**, as when streaming.
- **Kept out of shared caches:** `Cache-Control: private` (unless you set
  one) and `Vary: Cookie`.
- **Why cookies by default:** no store to run, configure or clean up, and
  any instance serves any request. Server-side stores, which can revoke
  sessions, are a setting away (`SESSION_DRIVER`).

> **Coming from another framework?** This is a cookie session, always
> encrypted, like Rails' default. `view.CSRFField`, `view.Old` and
> `view.Errors` do what Django's `{% csrf_token %}` and form errors,
> Laravel's `@csrf`, `old()` and `$errors`, or Rails' form helpers do,
> and a token mismatch is a 403.

## Related

- [Render HTML with templ](https://docs.anetos.dev/guides/views/index.md)
- [Sessions and flash messages](https://docs.anetos.dev/guides/sessions/index.md), [Handle HTML forms](https://docs.anetos.dev/guides/forms/index.md)
- [HTTP request lifecycle](https://docs.anetos.dev/concepts/http-request-lifecycle/index.md)
- [Views, sessions and forms reference](https://docs.anetos.dev/reference/views/index.md), [Session settings](https://docs.anetos.dev/reference/configuration/index.md#sessions)


# Validation

Source: https://docs.anetos.dev/concepts/validation/

How rules in struct tags become a cached plan, what `web.H` does with the
result, and why validation works the way it does.

```mermaid
flowchart TB
    R["Request"] --> B["Bind<br/>(bind plan)"]
    B -->|value can't be converted| E1["400 + errors"]
    B --> T["Tag rules<br/>(cached validation plan)"]
    T -->|a rule fails| E2["422 + errors"]
    T --> M["Validate(ctx), if the input has it"]
    M -->|validate.Fail or *validate.Errors| E2
    M -->|any other error| E3["500, details hidden"]
    M --> H["Your handler"]
    E1 --> X["Error handler: problem JSON,<br/>or redirect back for a browser form"]
    E2 --> X
```

## Rules are compiled once

Rules are separated by `|`: `validate:"required|max:200|in:a,b"`. The first
time a struct type is validated, its tags are parsed into a
`validate.Plan` and cached for the life of the process. For `web.H`, that
happens when the route is added, so tag mistakes are **startup errors**,
not per-request ones: an unknown rule, `min:abc`, `email` on an `int`, a
rule naming a missing field, or a `ValidationMessages` key that matches
nothing. `web.H` panics with the message.

Per request, only the plan runs: messages are built only when a rule
fails, and with the built-in rules valid input is checked without
allocating (maps of structs and file rules excepted). `validate.Struct`
uses the same cache for input that doesn't come from HTTP, such as job
payloads.

## Empty means "not sent"

Only the `required` family (`required`, `required_if`, `required_unless`,
`required_with`, `required_without`) and `accepted` run on an empty field.
Every other rule, custom rules included, passes it. Empty means a nil
pointer, a blank string, an empty slice or map, or a zero struct or array
such as a zero `time.Time`. So a field is optional unless you say
`required`, and needs no `nullable` marker.

Numbers and booleans are **never** empty, because zero can be a real
answer; `required` rejects `0` and `false` in them. A pointer expresses
"not sent":

```go
// illustrative
type UpdateProfile struct {
	Name    string `json:"name" validate:"required|max:100"`
	Website string `json:"website" validate:"url:https"` // optional; checked only when sent
	Age     *int   `json:"age" validate:"min:13"`        // nil passes, 0 fails
	Terms   bool   `json:"terms" validate:"accepted"`
}
```

## The order inside web.H

1. **Bind.** A value that can't be converted (`page=abc`) is a **400**
   listing each bad field. The rules don't run.
2. **Tag rules.** Failures are collected into a `*validate.Errors`, one
   message per field (the first failing rule wins), and returned as a
   **422**. The handler isn't called.
3. **`Validate(ctx)`**, only if the input implements `web.Validator` and
   the tags passed, so it can rely on well-formed input. Use it for checks
   that need the database or several fields. `validate.Fail` or a
   `*validate.Errors` gives the same 422; a `web.HTTPError` keeps its status.
4. **Your handler.**

**Any other error** from `Validate`, or from a custom rule, is a **500**
whose text stays out of the response. A failing database check never
reaches a client as a "validation message".

## One error, two responses

`*validate.Errors` reports status 422 and implements `web.FieldErrorer`.
`web.DefaultErrorHandler` turns it into one of two responses:

- **API clients** get RFC 9457 problem JSON with an `errors` object keyed
  by the request key: the `json` name, else `form`, `query`, `path` or
  `header`, with dotted keys for nested data (`items.0.name`).
- **Browser form posts** (a navigation or `Accept: text/html`, not GET)
  on a route with a session are redirected back to the form's page. The
  errors, keyed by `form` name, and the submitted input are flashed;
  `view.Errors` and `view.Old` read them on the next page. Fields whose
  name contains `password`, `secret` or `token` aren't flashed. A 400 from
  binding with field errors is redirected the same way. htmx requests
  (except boosted ones) get the 422.

A custom error handler keeps the redirect only if it calls
`web.DefaultErrorHandler` for these errors.

## Custom rules and messages

Tags can only name rules, so custom rules live in a registry filled from
`init`, like `sql.Register`:

```go
// illustrative
func init() {
	validate.Register("even", "The {label} field must be even.",
		func(ctx context.Context, f validate.Field) (bool, error) {
			n, ok := f.Value.(int)
			return ok && n%2 == 0, nil
		})
}
```

A rule gets the request context and the field's key, label, value
(pointers followed), parameters and parent struct. Registering a
duplicate or built-in name panics, and so does a route that uses a rule
before it is registered ("unknown rule"). The `db` package registers
`unique` and `exists` this way.

Messages are in English. The label comes from the key
(`first_name` becomes "first name") or a `label` tag. A
`ValidationMessages() map[string]string` method replaces templates by
`key.rule` or `rule`; it is read once, when the plan compiles.

## What it deliberately doesn't do

- **No `nullable`, `sometimes` or `bail`.** Empty fields already skip
  non-required rules, and a field stops at its first failure. Using them
  is a startup error that says so.
- **No go-playground syntax.** `required,email` fails at startup.
- **No changes to the input.** Values aren't trimmed; a blank string
  counts as empty but stays as sent.
- **No translations yet.** Messages are English only.

> **Coming from another framework?** The input struct does the job of a
> Django form, a Laravel form request, or Rails' strong parameters and
> model validations, and `view.Errors` and `view.Old` give the errors
> and the submitted values back to the form. A typo in a rule stops the
> app at startup instead of failing a request.

## Related

- [Validation](https://docs.anetos.dev/guides/validation/index.md), [Handle HTML forms](https://docs.anetos.dev/guides/forms/index.md)
- [Handlers and requests](https://docs.anetos.dev/guides/handlers/index.md)
- [Validation rules reference](https://docs.anetos.dev/reference/validation-rules/index.md)
- [Request binding reference](https://docs.anetos.dev/reference/binding/index.md#error-statuses)
- [HTTP request lifecycle](https://docs.anetos.dev/concepts/http-request-lifecycle/index.md)


# Internationalization

Source: https://docs.anetos.dev/concepts/internationalization/

How Anetos finds the words to show a user: where messages come from, how
a request's language is chosen, and how the language travels with work
done for the user later.

## Catalogs and lookup

Messages live in YAML catalogs embedded in the binary: the app's
(`locales/`), and the framework's own English one, which holds its
validation messages, error pages and login messages. They are read once,
when the app starts; a broken file stops it there, not on a user's page.

A key is looked up in a chain of catalogs, the first that has it wins:

1. the locale's (`bn-BD`),
2. its parents' (`bn`),
3. `APP_FALLBACK_LOCALE`'s and its parents' (`en`),
4. the framework's English catalog.

For an English locale the framework's catalog comes right after the app's
English one, so an app whose fallback is Bangla still shows English
visitors English validation messages.

So a language can be translated a little at a time: what it lacks shows
in the fallback language, and `locale:check` lists it. An app changes a
framework message by defining its key; there is no separate mechanism
for overrides.

Placeholders are `{name}`, the style of validation messages. Plural
messages are keyed by CLDR plural categories, and the category a number
falls in comes from the CLDR rules of the message's language
(`golang.org/x/text`), so Arabic gets six forms and Bangla two without
the app knowing the rules, and an English message shown in place of a
missing Japanese one still says "1 post".

## The request's language

Package `i18n` keeps a locale in the context. The HTTP server gives every
request a resolver that runs the first time something asks
(`i18n.Locale`, `i18n.T`, a validation message, the error page), and
keeps its answer for the request. Resolving lazily means a route that
never shows text never loads the user to find their language.

With a URL strategy (`APP_LOCALE_STRATEGY=prefix` or `subdomain`) the URL is
authoritative, so a page has one language per address, which search
engines and shared links need: the locale is the URL's, or `APP_LOCALE`
for an address without one. The cookie and the browser only decide where
a visitor asking for a page without a locale is sent.

Without one (`none`), the same address shows each visitor their language,
the first supported locale of: the `locale` cookie, the session, the
logged-in user's preference, `Accept-Language`, `APP_LOCALE`. The cookie
and session hold a choice made on this device, which beats the account's
default: someone who usually reads Bangla can switch to English on a
shared computer. Responses say they vary by `Accept-Language` and
`Cookie`, so caches keep one copy per language.

A locale matches itself or its nearest supported parent (`bn-BD` →
`bn`), else a supported locale close enough to read (`fr-CH` → `fr-CA`);
a Chinese visitor is never shown Traditional Chinese for Simplified.

## Language that outlives the request

Work done for a user often happens elsewhere: in a queue job, an email,
an AI agent's reply. The context carries the locale and the time zone, so:

- a queue job records them when dispatched and runs in them;
- an email is rendered in the context it is sent with, and
  `i18n.ForUser` switches that context to the recipient's communication
  language and zone, which can differ from the site's;
- anything that receives the context (a validation in a job, a message
  in a listener) speaks the same language.

## Numbers, dates and languages

Numbers, percentages and currency symbols come from `golang.org/x/text`,
which carries CLDR's number data for every language: grouping (Indian
lakhs for Bangla), separators, digits. The digits follow CLDR's choice
for the language (Bangla digits for `bn`), and a catalog can ask for
another numbering system; a plural's `{count}` and the numbers of size
rules' validation messages are formatted the same way, so a sentence
never mixes digit systems.

x/text has no localized dates, and the date libraries that do are large.
So a catalog's `format` section holds what dates need: month and day
names and CLDR patterns for four styles. A language's file brings them,
the core needs only its English, and a project fixes a pattern in its
own catalog like any message. Times are shown in the context's zone, the
logged-in user's, which is what makes "today" theirs; `anetos.Date`
values have no zone and are shown as they are.

The framework ships English only. Other languages' translations of its
messages live apart, in `anetos.dev/locales`, where native speakers can
improve them without waiting for a release. `anetos locale:add` copies a
language into the project, through the Go module proxy (versioned and
checksummed like any dependency), and from then on the files are the
project's: no runtime dependency, nothing replaced behind its back.

## What it deliberately doesn't do

- **No generated message functions.** Keys are strings, so a catalog is
  the only thing to edit; `locale:check` reads the source for the keys it
  uses and reports undefined ones.
- **No translated model content** (a post's title in several languages)
  yet: that is the app's data, and a search index has one language.


# Data

Source: https://docs.anetos.dev/concepts/data/

- [The data layer](https://docs.anetos.dev/concepts/data-layer/index.md): How the db package finds its connection, turns method calls into SQL, and why it works the way it does.
- [Migrations](https://docs.anetos.dev/concepts/migrations/index.md): Migrations are Go values compiled into your binary. The runner applies them in ID order, records each one in the `migrations` table with the batch it ran in, and wraps each in a transaction where the database allows it. A database lock keeps two instances from migrating at once.


# The data layer

Source: https://docs.anetos.dev/concepts/data-layer/

How the db package finds its connection, turns method calls into SQL, and
why it works the way it does.

```mermaid
flowchart LR
    C["db.Query[Post](ctx)"] --> M["model metadata<br/>(cached per type)"]
    C --> K{"ctx"}
    K -->|"transaction for this DB?"| T["*sql.Tx"]
    K -->|otherwise| P["*sql.DB pool"]
    M --> S["SQL for the dialect<br/>(placeholders, quoting, LIMIT)"]
    S --> T
    S --> P
    T --> R["rows → scan plan<br/>(cached per type + columns)"]
    P --> R
    R --> O["[]Post"]
```

## The connection travels in the context

`db.Connect` puts the `*db.DB` in every context the app creates, and
`db.Tx` returns a context that also carries a transaction. Every query
function takes a `context.Context` and looks both up:

- no database in the context: `db.ErrNoDB`;
- a transaction for that database: the query runs in it;
- otherwise: the connection pool.

This is why a handler can call `db.Find[Post](c, id)` with only its
request context, and why a function called inside `db.Tx` joins the
transaction without being told. The context already had to be passed for
cancellation and deadlines; the database rides along. For a second
database, `db.WithDB(ctx, other)` switches the target explicitly.

## Types in, SQL out

Models are plain structs. The first time the package sees a type, it reads
its fields and tags once (columns, key, timestamps, soft deletes) and
caches the result; the same happens for each combination of result type
and result columns when scanning. Per query, only values are copied: no
tag parsing and no type inspection.

Conditions are values built from typed columns (`PostCols.Views`,
generated by `anetos generate` from the struct), so `PostCols.Views.Eq("ten")`
is a compile error. The builder writes SQL for the
database's **dialect**: `$1` or `?` placeholders, `"quoted"` or
`` `quoted` `` identifiers, `RETURNING` or `LastInsertId`, `ON CONFLICT`
or `ON DUPLICATE KEY`. Values always travel as parameters, never inside
the SQL text.

Queries are immutable: every method returns a new query, so a base query
can be shared and extended without surprises.

## Drivers are separate modules

The dialects live in the core `db` package; the driver modules
(`drivers/sqlite`, `drivers/postgres`, `drivers/mysql`) only pair a
dialect with a `database/sql` driver and build connection strings. An app
downloads and compiles only the drivers it imports. The SQLite driver is
pure Go, so the single binary still cross-compiles without a C toolchain.

Every driver module runs the same conformance suite (`db/dbtest`) against
a real database in CI.

## One API, each database's own search

Full-text search (`q.Search(text)`) is one method over three different
engines: PostgreSQL's `tsvector` and GIN indexes, MySQL's `FULLTEXT`
indexes, SQLite's FTS5. A migration builds the database's own index
(`t.SearchIndex`), and the query builder writes that database's match and
ranking SQL. The engines don't agree on everything (which words they
stem, skip or weigh, and how they score), so the [Search](https://docs.anetos.dev/guides/search/index.md)
guide lists the differences instead of hiding them.

## The database is checked when the app boots

`db.Connect` pings the database when the app boots, then checks that it
can serve what the app asks of it: `DB_SEARCH_LANGUAGE` and `DB_SEARCH_RANKING`,
the capabilities features declared with `d.Require(feature, caps...)`
(`db.FullText`, `db.BM25`), and that the search indexes were built for the
current settings. A mismatch stops the app (and its commands) at once,
naming the setting, the database and the way out, rather than failing on
a user's first search or silently ranking differently. Commands that fix
the schema (`migrate…`, `search:reindex`) skip the last check, so they
can run.

## Times are UTC

Timestamps are written in UTC with microsecond precision, and times are
read back in UTC on every database, so a value round-trips exactly and
compares the same way everywhere. Every time argument is converted to UTC
before it is sent, and the drivers run their sessions in UTC (PostgreSQL
`timezone`, MySQL `time_zone`), so `CURRENT_TIMESTAMP` defaults and
`timestamp`/`DATETIME` columns without time zone agree with the app. On
SQLite, which stores times as text, times are written in the format of
its own `CURRENT_TIMESTAMP`, so text comparison and sorting match time
order.

The app can't drift into local time by a forgotten setting: when it
boots, it checks the session's time zone and stops if a connection string
set another one (unless `DB_ALLOW_LOCAL_TIMEZONE=true`). Calendar dates
are `anetos.Date` values, which have no zone and so can't change day on
the way to UTC. `APP_TIMEZONE` changes the zone the app works in (logs,
schedules, `anetos.Now`), never the one it stores in. See
[times and dates](https://docs.anetos.dev/guides/times-and-dates/index.md).

## What it deliberately doesn't do

- **No lazy loading.** Go can't intercept field access, and hidden queries
  are how N+1 bugs happen. Relations load only when asked, with `With`
  or `db.Load`, one query per relation whatever the number of rows
  ([Relations and eager loading](https://docs.anetos.dev/guides/relations/index.md)).
- **No dirty tracking.** `db.Update` writes every column; mass updates set
  exactly the columns you name. The [audit log](https://docs.anetos.dev/concepts/audit-log/index.md), which must
  know what changed, reads the row again in the write's transaction
  instead.
- **No magic zero values.** A NULL in a non-pointer field is an error, not
  a silent empty string.
- **No hidden SQL dialect.** Raw SQL is sent as written (apart from
  placeholders), so you can use each database's features.

## Guarantees

- Nested `db.Tx` calls use savepoints: an inner failure undoes only the
  inner work.
- `db.AfterCommit` callbacks run once, after the outermost commit, and
  never for rolled-back work.
- A `*db.DB` is safe for concurrent use. A transaction is one connection:
  run its queries one at a time.
- Writes to a table watched by `DB.Watch` (the audit log) run in a
  transaction with the watcher, which sees exactly what was written.

## Related

- [Connect to a database](https://docs.anetos.dev/guides/database/index.md), [Migrations](https://docs.anetos.dev/guides/migrations/index.md)
- [Define models and save data](https://docs.anetos.dev/guides/models/index.md)
- [Query data](https://docs.anetos.dev/guides/queries/index.md), [Search](https://docs.anetos.dev/guides/search/index.md)
- [Transactions](https://docs.anetos.dev/guides/transactions/index.md)
- [The audit log](https://docs.anetos.dev/concepts/audit-log/index.md)
- [Raw SQL](https://docs.anetos.dev/guides/raw-sql/index.md)
- [Performance](https://docs.anetos.dev/concepts/performance/index.md): what queries cost
- [Models reference](https://docs.anetos.dev/reference/models/index.md), [Query builder reference](https://docs.anetos.dev/reference/query-builder/index.md)


# Migrations

Source: https://docs.anetos.dev/concepts/migrations/

Migrations are Go values compiled into your binary. The runner applies
them in ID order, records each one in the `migrations` table with the
batch it ran in, and wraps each in a transaction where the database
allows it. A database lock keeps two instances from migrating at once.

```mermaid
flowchart LR
    S["sets: app, plugins"] --> O["one list,<br/>sorted by ID"]
    O --> L["take the lock"]
    L --> T["create migrations table<br/>if missing"]
    T --> P["pending = list minus<br/>recorded rows"]
    P --> M["each pending migration:<br/>Up + insert its row<br/>(one transaction)"]
    M --> U["release the lock"]
```

## Sets and IDs

A **set** (`migrate.NewSet("app")`) is a named list of migrations. Your
app has one; a plugin that ships tables has its own, named after it.
There is no global registry: `migrate.New` receives the sets
explicitly, and two sets with the same name are an error.

Each migration is added under an explicit **ID**, such as
`2026_10_01_120000_create_posts`. The runner merges all sets into one
list sorted by ID as a string, so IDs start with a timestamp, and a
plugin's migrations interleave with yours by date, not by set.

Migrations are Go code, or SQL files embedded with `set.AddFS`, so they
are part of the binary. A deploy ships exactly the migrations its code
expects, and there is no migrations directory to copy to the server.

## The migrations table and batches

Each applied migration is a row in the `migrations` table: its set
(`source`), its ID, its **batch**, and when it ran (UTC). One `migrate`
run applies every pending migration as one batch, so a batch is "what the
last deploy changed". `migrate:rollback` undoes the last batch (or
`--step=N` batches), newest first; `migrate:reset` undoes all of them.

`Up` stops at the first failure. The migrations before it stay applied,
in that batch. A row whose migration is no longer in any set shows as
`Missing` in `migrate:status`, and rollback refuses a batch that contains
one before it undoes anything.

## One transaction per migration

On PostgreSQL and SQLite, a migration's `Up` (or `Down`) and the write to
its row run in one transaction. A migration that fails leaves nothing
behind: fix it and run `migrate` again. There are two exceptions:

- **MySQL** commits every DDL statement immediately, so the runner uses
  no transaction there. A migration that fails halfway leaves its first
  changes in place, and its data changes aren't transactional either.
  Keep MySQL migrations small.
- **Opt-outs.** Some statements can't run in a transaction, such as
  PostgreSQL's `CREATE INDEX CONCURRENTLY`. A migration with a
  `WithoutTransaction()` method, one wrapped in `migrate.NoTransaction`,
  or an SQL file whose first line is `-- anetos:no-transaction` runs
  without one.

## Concurrent runs are safe

During a deploy, several instances may run `./app migrate` at once. `Up`,
`Rollback`, `Reset` and `Fresh` take a lock first:

| Database | Lock | While waiting |
|---|---|---|
| PostgreSQL | `pg_advisory_lock` (advisory locks are per database) | Waits until it is free or the context is canceled |
| MySQL | `GET_LOCK`, named after the database and table | Waits up to 600 seconds, then fails |
| SQLite | A mutex in the process | One server uses the file |

On PostgreSQL and MySQL the lock is held on a dedicated connection, so
the runner refuses a pool of one (`DB_MAX_OPEN_CONNS=1`) there. One instance migrates; the others wait,
then find nothing pending. `migrate:status` and seeders don't take it.

## SQLite and foreign keys

SQLite can't change a column in place. The usual recipe is to create a
new table, copy the rows, drop the old table and rename the new one. With
foreign keys on, that drop would cascade to child tables. So each SQLite
migration runs on a dedicated connection with `PRAGMA foreign_keys = OFF`,
and `PRAGMA foreign_key_check` must pass before it commits.

## The schema builder refuses non-portable changes

A migration that passes on SQLite in development must not fail on
PostgreSQL in production. So the builder returns an error, on every
database, for a NOT NULL column added to an existing table without a
default, `Default(nil)` on a NOT NULL column, and schema-qualified table
names. Operations SQLite can't do (`Change()`, adding or dropping foreign
keys on an existing table) are errors on SQLite, not silent no-ops. Index
names longer than 63 bytes are shortened with a hash, the same way when
created and dropped. `s.Exec` and `s.Dialect()` cover everything else.

## Seeders and the production guard

A seeder (`migrate.Seeder`) is a name and a function, passed with
`migrate.WithSeeders`. Seeders run in the order listed, each in its own
transaction, so a failing seeder rolls back only its own work.

The runner knows `APP_ENV`. In production, `migrate:rollback`,
`migrate:reset`, `db:seed` and `migrate --seed` refuse to run without
`--force`; plain `migrate`, the deploy step, runs as it is, and staging
doesn't need `--force`. `migrate:fresh` drops every table and view, so it runs
only in development and testing, with no override. A runner built with
`migrate.NewRunner` and no `WithEnvironment` option assumes production.

## How `migrate.New` wires it up

`migrate.New(app, sets, opts...)` resolves the `*db.DB` that
`db.Connect` provided (so call `db.Connect` first), builds a runner with
the app's environment and logger, registers the `migrate*` and `db:seed`
[commands](https://docs.anetos.dev/concepts/commands/index.md) on the app, and provides the runner as a
`*migrate.Runner` service, which `anetostest` uses to migrate test
databases.

> **Coming from another framework?** `migrate:rollback` undoes the last
> batch, or `--step` migrations, as Rails' `db:rollback STEP=n` does or
> Django's `migrate` back to a named migration. The difference is
> discovery: migrations are added to a set in code, not found in a
> directory at runtime as Django, Laravel and Rails do.

## Related

- [Migrations](https://docs.anetos.dev/guides/migrations/index.md), [Seed the database](https://docs.anetos.dev/guides/seeders/index.md)
- [Migrations reference](https://docs.anetos.dev/reference/migrations/index.md)
- [Commands and the app binary](https://docs.anetos.dev/concepts/commands/index.md), [The data layer](https://docs.anetos.dev/concepts/data-layer/index.md)
- Package docs: `db/migrate`


# Accounts and security

Source: https://docs.anetos.dev/concepts/accounts-and-security/

- [Authentication and authorization](https://docs.anetos.dev/concepts/authentication/index.md): How Anetos knows who is making a request, and what they may do.
- [Roles and permissions](https://docs.anetos.dev/concepts/roles-and-permissions/index.md): How package `auth/rbac` decides what a user may do, and where it keeps what it needs.
- [The audit log](https://docs.anetos.dev/concepts/audit-log/index.md): How package `audit` records every change of the models an app tracks, and why its entries can be trusted to match the data.


# Authentication and authorization

Source: https://docs.anetos.dev/concepts/authentication/

How Anetos knows who is making a request, and what they may do.

## Who is logged in

A logged-in browser carries the session cookie; the session holds the
user's ID and a fingerprint of their password hash. `a.Middleware` puts
a small record in the request's context, and the user is loaded from the
database the first time a handler (or `a.Require`) asks for it. If the
fingerprint no longer matches, the password has changed since this
session logged in, and the session is logged out: changing a password
ends every other session.

Logging in gives the session a new ID, so an ID that was known before
(planted by an attacker, or seen on a shared computer) is useless
afterwards. Logging out empties the session and, with a server-side
session driver, removes it from the store. With cookie sessions there is
nothing on the server to remove: a copy of the cookie taken before the
logout works until it expires.

"Remember me" adds a second, long-lived cookie, encrypted with
`APP_KEY`, holding the user's ID, a random remember token stored with the
user, the password fingerprint and an expiry checked on the server. When the session has ended, the cookie logs the user in to a
new one. Logging out replaces the token, which logs the user out of every
remembered browser at once.

API clients don't use cookies: they send `Authorization: Bearer
<id>|<secret>`. The database holds only a SHA-256 hash of the secret,
with the token's abilities and expiry.

Social login logs users in with an account elsewhere: the app sends
the browser to the provider with a one-time state and a PKCE challenge,
checks what comes back, and asks your code which user the account
belongs to (links are kept in `social_accounts`), then logs that user in
like a password login.

Two-factor authentication adds a second step after either: the session holds a
login waiting for a code (not a logged-in user) for ten minutes, until
the code of the user's authenticator app, or a recovery code, finishes
it. The app's secret for that user is stored encrypted with `APP_KEY`;
recovery codes, like API tokens, only as hashes. Before sensitive pages,
the app can ask for the password again: the session remembers when it
was last confirmed.

## What is stored, and what isn't

Password-reset and email-verification links carry tokens that are
encrypted with `APP_KEY` rather than stored: the user's ID, an expiry
and, for resets, the password fingerprint. A reset token therefore stops
working as soon as the password changes, so it can be used once, and
there is no table of pending resets to clean up.

Passwords are hashed with argon2id, which makes guessing slow and
memory-hungry for an attacker; only a few hashes are computed at once, so
a flood of logins waits instead of exhausting memory. Failed logins are
counted in the cache per login and per account (from one IP address), and
per IP address, and refused past their limits.

## What a user may do

Authorization uses typed policies: functions that take the user and the
thing acted on and return a boolean. `auth.Authorize` finds the logged-in
user and calls the policy; its errors carry the HTTP status (401 for no
user, 403 for a refusal), so handlers return them as they are. Because
policies are Go functions, the compiler checks that the user and subject
types match, and there are no ability names to misspell.

Roles say what a user may do from who they are rather than from the
thing acted on: package `auth/rbac` gives users roles, globally or in a
scope such as a team, made of permissions declared in code. See [Roles
and permissions](https://docs.anetos.dev/concepts/roles-and-permissions/index.md).

## Related

- [Authentication](https://docs.anetos.dev/guides/authentication/index.md), [Authorization](https://docs.anetos.dev/guides/authorization/index.md), [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md), [Social login](https://docs.anetos.dev/guides/social-login/index.md), [Two-factor authentication](https://docs.anetos.dev/guides/two-factor/index.md)
- [Authentication reference](https://docs.anetos.dev/reference/auth/index.md)
- [Sessions and flash messages](https://docs.anetos.dev/guides/sessions/index.md)


# Roles and permissions

Source: https://docs.anetos.dev/concepts/roles-and-permissions/

How package `auth/rbac` decides what a user may do, and where it keeps
what it needs.

```mermaid
flowchart LR
    C["code<br/>permissions (constants)<br/>roles"] --> R["Registry<br/>(rbac.New)"]
    D["database<br/>rbac_grants: user, scope, role or permission<br/>rbac_roles: roles administrators add"] -->|"one query per user<br/>per operation"| G["the user's grants"]
    R --> G
    T["API token's abilities"] -->|narrows| G
    G --> Q{"rbac.CanIn(ctx, team:42, projects.create)"}
```

## Permissions in code, grants in the database

Permissions are what the code checks, so they live in the code: typed
constants, declared once and passed to `rbac.New`. A misspelled
constant doesn't compile, and checking a permission that isn't declared
(a string, say) is reported as a bug (an error, a 500), never as a quiet
"no".

Roles are sets of permissions. Those the app is built around (owner,
member, admin) are declared in code too, and need no syncing: they're
not in the database. Administrators can add their own at run time,
stored in `rbac_roles`, but only from declared permissions: a role of
the database can't invent a permission the code doesn't check, and only
code can declare a super role, which has every permission. A role
removed from the code allows nothing to those who still have it
(`rbac:roles` lists them), and creating a role of the database with its
name takes it from them first, so it doesn't come back to life. A role
declared in code replaces a stored one of the same name.

Who has what is data: `rbac_grants` holds one row per user, scope and
role (or single permission). A user is identified by the `AuthID` of
package `auth`, so any user type works, and the tables don't reference
the users table. User IDs and scopes compare exactly on every database:
on MySQL and MariaDB, whose text comparisons ignore case, accents and
trailing spaces, the columns are binary.

## Scopes

Every grant has a scope: global, or one such as `team:42`, made by
`rbac.ScopeOf(kind, id)`. A grant applies in its scope only, except a
global one, which applies in every scope: an administrator is an
administrator in every team. There is no hierarchy of scopes (an
organization above its teams); give the role in each scope, or globally.

A scope is just a key, so a team's members need no table of their own:
they're the users with a role in its scope, and a user's teams are the
scopes of kind `team` they have a grant in. Nor does it know whether the
team exists: grants in a team's scope apply to whichever team has its
ID, so give them only in existing teams, and remove them
(`rbac.RemoveScope`) when a team is deleted.

## When grants are read

A user's grants (every scope's) are read in one query, two when they
have roles of the database, the first time a request, a job, a listener
or a tool call checks them, and kept until it ends: a page that checks a
dozen permissions in a dozen teams queries once. An operation started inside
another (a tool call in a request, a job run synchronously) shares them.
Changes made through the package in that operation are seen at once;
others are seen by the next one. What a transaction reads is kept only
once it commits, so a rolled-back grant never lingers; checks inside a
transaction read each time, so check before a loop that runs in one. Outside an operation (a
command, a test's own context), every check reads again. This suits users with grants in up to a few thousand
scopes; staff who see everything get a global role instead of one in
each team.

## Who asks

The package functions (`rbac.Can`, `rbac.AuthorizeIn`, `rbac.Require`…)
check the request's logged-in user, as package `auth` finds them, in the
context. Anything that has the request's context can ask: handlers,
templates, policies, and the tools an AI model calls, which run with the
context of the call, so a model can't do more than its user. Jobs and
other code without a logged-in user check a user by ID: `rbac.Of(ctx,
id)`.

A request logged in with an API token may use only the permissions that
are also the token's abilities (a token with `*` has its user's). A
permission's name is the ability, so a token made with
`projects.view` can view projects, whatever roles its user has. Role
checks (`rbac.HasRole`, `Grants.Roles`) see no roles for a token without
`*`, since a role says nothing about what the token was given; gate
actions with permissions.

## Giving roles safely

A user who may manage a team's members could give a role with more than
they have. `rbac.AuthorizeRole(ctx, scope, role)` refuses unless the
logged-in user has, in that scope, every permission the role allows (and
is super there, for a super role): an owner can make owners, not
administrators. `rbac.AuthorizeRolesOf(ctx, scope, userID)` applies the
same rule to the roles someone has, before changing or removing them, so
a user who may manage members can't demote an owner unless they could
make one. Neither replaces the check that the user may manage members at
all, which is one of the app's permissions. Both compare permissions,
not names: a role without permissions is anyone's to give, so gate
actions with permissions, not role names.

## Roles or policies

Policies (`auth.Authorize`) decide from the thing acted on: an author
edits their own posts. Roles decide from who the user is: an editor
edits every post in the team. Apps use both, and a policy can ask about
roles: `return p.AuthorID == u.ID || rbac.CanIn(ctx, teamScope(p.TeamID), EditPosts)`.

## Not in scope

Hierarchies of scopes, roles inheriting from roles, permissions with
wildcards, roles that one team defines for itself, and denying a
permission a role allows are out of scope.

## See also

- [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md)
- [Authentication and authorization](https://docs.anetos.dev/concepts/authentication/index.md)
- [Authentication reference](https://docs.anetos.dev/reference/auth/index.md#roles-and-permissions)


# The audit log

Source: https://docs.anetos.dev/concepts/audit-log/

How package `audit` records every change of the models an app tracks,
and why its entries can be trusted to match the data.

```mermaid
flowchart LR
    H["handler, job, command<br/>db.Update(ctx, &doc)"] --> W{"table watched?<br/>(db.DB.Watch)"}
    W -->|no| S["the write, as before"]
    W -->|yes| T["transaction (or savepoint)"]
    T --> R["read the row FOR UPDATE"]
    R --> U["UPDATE"]
    U --> A["audit: diff, actor, operation<br/>INSERT INTO audit_log"]
    A --> C["commit: change and entry together"]
```

## The data layer is watched, not changed

`db` knows nothing about auditing. It lets a package watch the writes to
a table (`DB.Watch`), and tells the watcher about each one: the kind of
write, the row's key, its values before and after, or, for a write to
many rows, the condition, the assignments and every row's key.
`audit.Track` is such a watcher, and so could be a cache or a search
index that must follow the data.

Every write the `db` package makes goes through this: `Create`,
`CreateMany`, `Upsert`, `Update`, `Save`, `Delete`, `ForceDelete`,
`Restore`, and a query's `Update`, `Delete`, `ForceDelete` and
`Restore`. Raw SQL (`db.Exec`), pivot writes and the database's own
cascades don't, and aren't recorded.

## One transaction, so the log can't drift

The entry is written in the transaction of the change, after it. If the
change commits, its entry commits with it; if anything fails (the write,
the entry, a hook, your own code later in the same transaction), both
roll back. There is no window in which a change exists without its
entry, and no entry describes something that didn't happen. A log
written by a queue job after the commit couldn't promise either.

Watched writes always run in a transaction: a savepoint inside one you
opened (`db.Tx`), or one of their own. Model hooks then run inside it.

## "Before" comes from the database

`db.Update` writes every column of the struct and keeps no snapshot of
what was loaded, so the values before are read again, `FOR UPDATE`, in
the transaction, just before the write. They are what the database
held, even if another request changed the row after your handler loaded
it, and the lock keeps anyone else from changing it until the commit.
The watcher compares before and after; only the columns that differ are
recorded, and an update that changes nothing but timestamps isn't.

## Bulk writes: one entry, every key

A write to many rows is one bulk entry (`audit_bulk`), so deleting a
thousand rows reads as one event. Every row's key goes to
`audit_bulk_items`, a table of two short columns with an index, so a
row's history finds the bulk writes that touched it on every database.
The rows' values before are kept up to `AUDIT_BULK_MAX_VALUES` rows:
values are what would make a huge write's entry huge.

To list exactly the rows written, a watched bulk write first selects the
matching rows' keys `FOR UPDATE`, then writes in chunks of 1,000 keys,
each `WHERE <your condition> AND key IN (…)`. If a chunk changes fewer
rows than it selected, the write fails and rolls back. A plain `UPDATE …
WHERE` could also touch rows inserted between a read and the write; this
can't.

## Who did it

The actor is found from the context, in order: one set with
`audit.WithActor`; the logged-in user, or the one a job acts as (and
while someone impersonates a user, `auth.Impersonate`, that someone, with
the user in `acting_as`: the person who did it is the actor); the actor
carried from the work that dispatched a queue job or emitted an
event for an async listener (the app's [carriers](https://docs.anetos.dev/concepts/glossary/index.md) move it
with the job); else `system`. If the user can't be loaded, the write
fails rather than being attributed to no one.

The operation (request, job, listener, task, or the command) and the
request ID come with it, and the client's IP address if `AUDIT_IP` asks:
an IP address is personal data, so keeping it is a decision.

## Costs

- Untracked models: a check per write (a flag, then a map lookup once any
  table is watched).
- Tracked models, one row: a transaction (or savepoint), one read and one
  insert.
- Tracked models, many rows: a read of the keys (and some values), the
  writes in chunks of 1,000, one insert for the entry and one per batch of
  item rows.

Counters and caches don't belong in the log: leave them out with
`audit.Except`, or keep them in an untracked table.

## Guarantees

- A committed change made through the `db` package to a tracked table has
  exactly one entry (or is part of exactly one bulk entry), committed with
  it. (An `Upsert` that could break this, with a NULL or generated-key
  conflict value, is refused.)
- An entry's "before" values are the database's at the time of the change.
- An entry names an actor; if none can be determined it is `system`, and if
  the logged-in user can't be loaded the change doesn't happen.
- Writes that bypass the `db` package are not recorded.

## Related

- [Keep an audit log](https://docs.anetos.dev/guides/audit-log/index.md)
- [The data layer](https://docs.anetos.dev/concepts/data-layer/index.md)
- [Configuration: audit log](https://docs.anetos.dev/reference/configuration/index.md#audit-log)


# Working with AI

Source: https://docs.anetos.dev/concepts/working-with-ai/

- [AI](https://docs.anetos.dev/concepts/ai/index.md): How package `ai` connects language models to the app, and what it leaves to the providers.


# AI

Source: https://docs.anetos.dev/concepts/ai/

How package `ai` connects language models to the app, and what it
leaves to the providers.

```mermaid
flowchart LR
    H["handler, job, command"] -->|"ai.Generate / GenerateObject / Stream<br/>agent.Prompt"| L["the call<br/>(options, schema, tools)"]
    L -->|Request| P["Provider<br/>(driver module, or the fake)"]
    P -->|Response| L
    L -->|"tool calls"| T["tools<br/>(the caller's context: user, permissions)"]
    T -->|"results"| L
    L --> R["Result<br/>(text or a T, messages, usage)"]
```

## Integration, not a framework

Go has capable libraries for models: the providers' official SDKs, and
frameworks such as Genkit, Eino and LangChainGo. What none has is the
rest of a web app. Package `ai` is thin: a provider contract, messages,
the tool loop, typed outputs and a fake. Providers are driver modules
that wrap the official SDKs (Anthropic, OpenAI and OpenAI-compatible
servers, Gemini), so the core module depends on none of them, and an
app depends only on the SDKs it uses.

Providers add features every month (reasoning, prompt caching,
citations, their own hosted tools). The common contract covers what
apps need everywhere: text, tools, structured output, streaming and
usage. The rest stays reachable: `ai.ProviderOptions` passes drivers'
own request options (each provider takes its own), `Response.Raw` holds the provider's own response,
and `Client.Provider()` leads to the driver's SDK client.

## Providers

The drivers (`drivers/anthropic`, `drivers/openai` with its
OpenAI-compatible mode, `drivers/gemini`) translate the common request
to their API and back. Three things don't map one to one, and the
drivers handle them the same way:

- **Structured output** has a JSON Schema dialect per provider. A
  struct's schema is adapted to it (`Schema.Map`): rules the provider
  doesn't take become words in the field's description, so the model
  still sees them, and validation enforces them on the answer.
- **Reasoning state:** models that think must see their earlier
  reasoning when they continue after tool calls (Claude's thinking
  blocks, Gemini's thought signatures). It's an `ai.Reasoning` part in
  the model's message, kept with the conversation like any part, and
  left out by other providers. A conversation can mostly change
  provider: Gemini takes another model's tool calls with a placeholder
  signature, which the driver adds, but Claude with extended thinking
  can't continue a tool call it didn't make.
- **Errors** are the SDKs' own, wrapped with the provider's name. Rate
  limits and server errors are retried twice first.

Every driver passes one conformance suite (`ai/aitest`). It runs
against recordings of the provider's HTTP exchanges, so it's fast and
needs no key, and it checks the requests the driver sends as well as how
it reads the answers. With a key, it records the exchanges again from
the live API.

## A call

Every call (`ai.Generate`, `ai.GenerateObject`, `ai.Stream`, an agent's
`Prompt` or `Stream`) runs the same loop:

1. The options are applied: the client's defaults (`AI_MODEL`,
   `AI_MAX_TOKENS`, `AI_TIMEOUT`), then an agent's, then the call's own.
2. A request goes to the provider: instructions, the conversation, the
   tools' definitions, and for `GenerateObject` the output schema.
3. If the model called tools, each runs, in order, and their results go
   back to the model in the next request. This repeats until the model
   answers without calling a tool, or `MaxSteps` is reached.
4. The result holds the answer, every response (one per step), the
   total usage and the whole conversation, which marshals to JSON.

Each request has its own timeout (in a stream, the reader's time
counts); the caller's context bounds the whole call, and canceling it
stops the call between requests, and during one as far as the provider
honors it.

## Typed outputs and tools

Typed outputs and tool inputs are structs. Their JSON schema comes from
the same tags as the rest of the app: `json` names, `description` for
what a field means, and `validate` rules (`required`, `max`, `in`,
`email`…) where JSON Schema can say them. Schemas are built once per type.

What the model sends is then checked with the same rules a request's
input would be. A tool's invalid input goes back to the model, which can
correct it; a typed answer that fails goes back once, with the problems,
and a second failure is an `*ai.OutputError` (a 502 for the web: the
model, upstream, failed).

## Tools act as the user

A tool runs with the context of the call: the request's, with its
logged-in user. Inside, `auth.Current`, policies, permissions
(`rbac.Authorize`) and scoped queries work as in a handler, so a model
can do no more than the user could, whatever text it read. Within that,
text the model reads (a page, an email, a document) can steer it into
calling the user's tools against their wishes (prompt injection): give
an agent the tools its task needs, read-only where you can, and confirm
with the user before tools that change or send things. A tool's error with a 4xx status (not allowed, not found,
invalid) is told to the model as a web client would see it, never with
its internal cause; any other error stops the call and is returned, as
it would end a request.

Each tool call is an operation (`anetos.Operation`, kind `tool`): repeated
queries in it are reported as in a request or a job.

## Logs

Each request to a model is logged at Info level with the provider,
model, step, stop reason, input and output tokens and duration; each
tool call with its name, duration and error. Prompts and answers are
never logged: they are the users' data.

## Conversations

A stored conversation (`ai.Conversation`) is a row of
`ai_conversations` with its messages in `ai_messages`, one row each, as
JSON: text, tool calls and results, and the reasoning some models need
back. It belongs to a user, and `ai.FindConversation` finds it only for
that user, so an ID in a URL can't reach another's.

A call on a conversation (`Prompt`, `Stream`, `Reply`, `StreamReply`)
loads its messages, sends them with the new question, and, once the
answer is complete, stores everything new in one transaction: the
question, the model's messages, the tools' results. It stores nothing
if the call fails, and refuses to store if another call added messages
in the meantime (`ErrConversationChanged`), since an answer belongs after
the question it answers. A page can store the question first (`Add`)
and stream the answer from another request (`StreamReply`): the question
is kept if the answer fails, and can be answered again.

## Streaming to the browser

`ai.SSE` writes a streamed answer as server-sent events (`text`,
`tool`, `error`, `done`), HTML-escaped for htmx's SSE extension, which
`view/htmx` bundles. The stream goes through `c.EventStream()`, which lifts
the request's timeout and the server's write timeout for that response:
an answer can take minutes, and still stops when the browser leaves,
which stops the model. A comment every 15 seconds keeps proxies from
closing a stream while the model thinks or a tool runs. Errors become an `error` event, with the
message of a 4xx error (a spent budget) or a general one (others are
logged), followed by `done`, so the page closes the stream instead of
reconnecting.

## Queued replies

`conv.QueueReply` answers from a queue job (`ai.QueueAgents` registers
the job type, with the agents it may run, found by name: a job carries
the name, not the agent). The job acts as the conversation's user
(`auth.WithUser`), so the agent's tools see the same user as in a request,
limited to the abilities of the API token the reply was queued with, if
any. Retries follow the queue's settings, and start the reply over: the
tools run again, so tools that change things must be safe to repeat. The conversation's `Status`
says where it stands (`queued`, or `failed` with a message for the
user). A job remembers how many messages the conversation had: if that
changed (the reply was stored by an earlier attempt, or the user asked
something else), it does nothing, so a question gets one answer however
often the job runs.

## Usage and budgets

With `client.TrackUsage`, every model response is recorded in
`ai_usage` for its user (the logged-in user, or `ai.ForUser`'s), with
its conversation, agent, model, tokens and cost at the app's prices. A
budget (tokens or cost per period, per user, from a function of the
user, so plans can differ) is counted on the rate limiter, in the app's
cache, and checked before each request to the model: a call over
budget fails with a 429 before it spends more. A single response can
go past the budget, since its length isn't known beforehand. A stream
the reader leaves partway (a closed tab), or a request cut off by a
timeout or a cancellation, has spent tokens too, which the provider
never reports: it's recorded and counted with an estimate, about four
bytes a token for its input and what it yielded (reasoning a model did
without showing it can't be counted). Records are
written even if the client has gone, but in the call's transaction, if
any: one that rolls back takes them with it, so models aren't called
inside transactions (on SQLite, the transaction would also hold the
write lock for the whole call).

## Embeddings and retrieval

An agent answers from the app's data through its tools; for text that
is searched by meaning (help articles, documents, notes), `ai.Embeddings`
keeps each record's chunks and their vectors in a table next to the
record's, in the app's own database (pgvector, MariaDB's vectors, or
SQLite), not in a separate vector store: the chunks commit and roll
back with the data, deleting a record deletes them, and a search joins
them with the record's table, so its conditions, scopes and soft deletes
apply. A search is hybrid when the table has a full-text index too: the
two rankings are merged by rank (reciprocal rank fusion), so a rare word
or a product code still finds its record when its meaning is vague.

Embeddings depend on the model that made them: vectors of two models
can't be compared. Each chunk records its model, searches use only the
current model's chunks, and `ai:embed` re-embeds after a change. The
embedding provider can differ from the chat provider
(`AI_EMBEDDING_PROVIDER`): Anthropic has no embeddings. See
[Search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md).

## Testing

Model output varies and costs money, so tests don't call a model:
`anetostest` sets `AI_PROVIDER=fake`, and `anetostest.FakeAI` scripts
the answers, one per request. Everything around the model runs for real:
schemas, validation, retries, tools, the loop. The fake records each
request, for assertions on what the model was sent. It makes embeddings
too, from the texts' words (texts that share words are near), so a
search works in tests without a model.

## Not in scope

Multi-agent orchestration graphs, prompt template languages and a
vector database of its own are out of scope: embeddings live in the
app's database. Vertex AI, Bedrock and Azure OpenAI's own
authentication are planned (their APIs work through a proxy URL until
then), as are files (images, documents) as inputs.

## See also

- [Add AI to your app](https://docs.anetos.dev/guides/ai/index.md)
- [Build an AI assistant](https://docs.anetos.dev/guides/ai-assistant/index.md)
- [Search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md)
- [AI reference](https://docs.anetos.dev/reference/ai/index.md)
- [Testing](https://docs.anetos.dev/concepts/testing/index.md)


# Reference

Source: https://docs.anetos.dev/reference/

Settings, commands, tags and rules, to look things up.


## Commands and settings

- [anetos tool and app commands reference](https://docs.anetos.dev/reference/cli/index.md): Two command lines: the `anetos` developer tool (module `anetos.dev/anetos/cli`), which creates projects and writes code, and your application's binary, which runs the app and its commands. See [Commands](https://docs.anetos.dev/guides/commands/index.md) and [Getting started](https://docs.anetos.dev/getting-started/index.md) for walkthroughs.
- [anetos generate reference](https://docs.anetos.dev/reference/anetos-generate/index.md): `anetos generate` writes the typed columns of your models. It is part of the `anetos` developer tool (module `anetos.dev/anetos/cli`). See [Generate typed columns](https://docs.anetos.dev/guides/code-generation/index.md) for a walkthrough.
- [Configuration reference](https://docs.anetos.dev/reference/configuration/index.md): Every key starts with its area's prefix (`DB_`, `CACHE_`, `QUEUE_`…). The key that picks a backend is `<AREA>_DRIVER` in every area (`DB_DRIVER`, `CACHE_DRIVER`, `MAIL_DRIVER`, `STORAGE_DRIVER`), except `AI_PROVIDER`.

## Web

- [Request binding reference](https://docs.anetos.dev/reference/binding/index.md): Rules used by `web.H` to fill a handler's input struct.
- [Views, sessions and forms reference](https://docs.anetos.dev/reference/views/index.md): The APIs of packages `view`, `session` and `encryption`, and the HTML helpers of package `web`. See [Render HTML with templ](https://docs.anetos.dev/guides/views/index.md), [Sessions and flash messages](https://docs.anetos.dev/guides/sessions/index.md) and [Handle HTML forms](https://docs.anetos.dev/guides/forms/index.md) for walkthroughs. The components of a project's `views/ui` are in the [UI components reference](https://docs.anetos.dev/reference/ui/index.md).
- [Validation rules reference](https://docs.anetos.dev/reference/validation-rules/index.md): Rules for the `validate` struct tag, used by `validate.Struct` and `web.H`. See the [validation guide](https://docs.anetos.dev/guides/validation/index.md) for how to use them.
- [Translation file formats](https://docs.anetos.dev/reference/i18n-formats/index.md): The `format` and `relative` sections of a catalog, which `i18n.Date`, `Time`, `DateTime`, `Format`, `Currency`, `Ago`, `Duration` and `LanguageName` use, and the date pattern fields. The framework's English values are in [`i18n/locales/en.yaml`](https://github.com/anetos-dev/anetos/blob/main/i18n/locales/en.yaml); a language's come from `anetos locale:add` ([Numbers, dates and languages](https://docs.anetos.dev/guides/formatting/index.md)). A key a locale lacks comes from its parents, then English (the app's `en` catalogs, then the framework's), never from a fallback locale in another language.
- [OpenAPI reference](https://docs.anetos.dev/reference/openapi/index.md): Package `web/openapi` and what it writes. How to use it: [Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md).
- [UI components reference](https://docs.anetos.dev/reference/ui/index.md): The components of `views/ui`, the package `anetos new` writes into a web project, which the layout and the pages of `make:crud` and `make:auth` call. The package is your app's: this page describes it as `anetos new` writes it. See [Style your app](https://docs.anetos.dev/guides/styling/index.md) for changing it.

## Data

- [Models reference](https://docs.anetos.dev/reference/models/index.md): How the db package maps a struct to a table. See [Define models and save data](https://docs.anetos.dev/guides/models/index.md) for a walkthrough.
- [Query builder reference](https://docs.anetos.dev/reference/query-builder/index.md): Everything available on `db.Q[T]`, the query started by `db.Query[T](ctx)`. See [Query data](https://docs.anetos.dev/guides/queries/index.md) for a walkthrough.
- [Migrations reference](https://docs.anetos.dev/reference/migrations/index.md): The schema builder, the migration runner and the commands in package `anetos.dev/anetos/db/migrate`. See [Migrations](https://docs.anetos.dev/guides/migrations/index.md) and [Seed the database](https://docs.anetos.dev/guides/seeders/index.md) for walkthroughs.

## Packages

- [Authentication reference](https://docs.anetos.dev/reference/auth/index.md): Packages `auth`, `auth/password`, `auth/social` and `auth/rbac`. How-to: [Authentication](https://docs.anetos.dev/guides/authentication/index.md), [Authorization](https://docs.anetos.dev/guides/authorization/index.md), [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md). Settings: [configuration reference](https://docs.anetos.dev/reference/configuration/index.md#authentication).
- [AI reference](https://docs.anetos.dev/reference/ai/index.md): The API of package `ai`. See [Add AI to your app](https://docs.anetos.dev/guides/ai/index.md) for a walkthrough, [AI](https://docs.anetos.dev/concepts/ai/index.md) for the design, and [Configuration](https://docs.anetos.dev/reference/configuration/index.md#ai) for the `AI_*` settings.
- [Testing reference](https://docs.anetos.dev/reference/anetostest/index.md): The APIs of packages `anetostest` and `db/factory`, and the hooks they use. See [Test your app](https://docs.anetos.dev/guides/testing/index.md) for a walkthrough.


# Commands and settings

Source: https://docs.anetos.dev/reference/commands-and-settings/

- [anetos tool and app commands reference](https://docs.anetos.dev/reference/cli/index.md): Two command lines: the `anetos` developer tool (module `anetos.dev/anetos/cli`), which creates projects and writes code, and your application's binary, which runs the app and its commands. See [Commands](https://docs.anetos.dev/guides/commands/index.md) and [Getting started](https://docs.anetos.dev/getting-started/index.md) for walkthroughs.
- [anetos generate reference](https://docs.anetos.dev/reference/anetos-generate/index.md): `anetos generate` writes the typed columns of your models. It is part of the `anetos` developer tool (module `anetos.dev/anetos/cli`). See [Generate typed columns](https://docs.anetos.dev/guides/code-generation/index.md) for a walkthrough.
- [Configuration reference](https://docs.anetos.dev/reference/configuration/index.md): Every key starts with its area's prefix (`DB_`, `CACHE_`, `QUEUE_`…). The key that picks a backend is `<AREA>_DRIVER` in every area (`DB_DRIVER`, `CACHE_DRIVER`, `MAIL_DRIVER`, `STORAGE_DRIVER`), except `AI_PROVIDER`.


# anetos tool and app commands reference

Source: https://docs.anetos.dev/reference/cli/

Two command lines: the `anetos` developer tool (module
`anetos.dev/anetos/cli`), which creates projects and writes
code, and your application's binary, which runs the app and its
commands. See [Commands](https://docs.anetos.dev/guides/commands/index.md) and
[Getting started](https://docs.anetos.dev/getting-started/index.md) for walkthroughs.

## Installing the tool

| Command | Use |
|---|---|
| `go install anetos.dev/anetos/cli/cmd/anetos@v0.5.0-rc.1` | For `anetos new`, before you have a project |
| `go get -tool anetos.dev/anetos/cli/cmd/anetos@v0.5.0-rc.1` | In a project: pins the version in `go.mod`; run it as `go tool anetos` (projects made by `anetos new` have it) |

Flags may come before or after the other arguments. `anetos help
<command>` (or `anetos <command> -h`) shows a command's usage. Exit
status: 0 on success, 1 on errors, 2 for bad usage.

## `anetos new <directory>`

| Flag | Default | Meaning |
|---|---|---|
| `--module` | the directory's name | Go module path |
| `--db` | `sqlite` | `sqlite`, `postgres` or `mysql`: the driver in `main.go` and the `DB_*` settings in `.env` |
| `--stack` | `web` | `web`: pages rendered on the server, with sessions and CSRF protection; `api`: JSON only, no views, static files or sessions ([the API project](https://docs.anetos.dev/reference/cli/index.md#the-api-project)) |
| `--css` | `anetos` | The web stack's CSS framework: the components of `views/ui` and the stylesheet, `public/static/app.css`. `anetos`: the starter theme (light and dark, no build step) and components writing its classes; `none`: components writing plain HTML without classes, and a stylesheet holding only a comment, for your own CSS or a CSS framework; `pico`, `bootstrap`, `bulma`: components writing Pico 2.1.1's, Bootstrap 5.3.8's or Bulma 1.0.4's markup, with the framework's files as released in `public/static/` (and its license), and an `app.css` for the rest; `tailwind`: components with Tailwind CSS 4.3.3's classes, `views/ui/tailwind.css` and the `app.css` Tailwind compiles from it (`css:build`). See [Style your app](https://docs.anetos.dev/guides/styling/index.md). Refused with `--stack=api` |
| `--no-agent` | `false` | Don't write the files coding agents read (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, the skills); see [`agent:install`](https://docs.anetos.dev/reference/cli/index.md#anetos-agentinstall-and-agentupdate) |
| `--skip-install` | `false` | Only write the files |
| `--replace` | | A local Anetos checkout, used through `replace` directives (framework development): the core, the tool, and every driver and plugin module of the checkout, so `go get` and `anetos add` take them from it too |

The directory must not exist or be empty; its name (letters, digits, `-`
and `_`, starting with a letter) becomes the app's name. `anetos new .`
uses the current directory. It writes the project, then runs `go get` for
Anetos, the driver and the `anetos` tool, all at the tool's own version
(every Anetos module is released with the same version; a development
build of the tool takes the latest), pinned as tools with templ, then `go tool templ generate` and
`go mod tidy` (the api stack has no templ, and runs `go run . openapi`
last, writing `openapi.json`). With `--db=postgres` or
`mysql`, create the database before `migrate`.

The web stack's files:

| Path | Holds |
|---|---|
| `main.go` | `anetos.New`, `i18n.New` (the catalogs in `locales/`), `db.Connect`, `migrate.New`, `cache.New`, `queue.New` (with workers), `events.New`, `mailer.New`, `storage.New`, `schedule.New`, `web.NewServer`, `session.New`, `routes.Register`, then `ext.Load(app, plugins())`, and `app.Execute()`; `//go:generate` lines for templ and `anetos generate` |
| `plugins.go` | The plugins, written by `anetos add` and `anetos remove` (an empty list at first) |
| `main_test.go` | Tests requesting the home page and a missing page with `anetostest` |
| `.env`, `.env.example` | Settings; `.env` has a fresh `APP_KEY` (file mode 0600) and stays out of git |
| `.env.testing` | PostgreSQL and MySQL projects: the test database's settings (`<name>_test`) |
| `README.md`, `.gitignore` | How to run it; what stays out of git |
| `routes/web.go` | Routes: the error pages (`ErrorPages` with `views.ErrorPage`), assets, and the page group with sessions and CSRF (`pages`), which `make:crud` adds its routes to |
| `app/handlers/home.go` | The home page handler |
| `app/models/` | Models (empty at first) |
| `database/migrations/migrations.go` | The `All` migration set and `Seeders` |
| `database/factories/factories.go` | The package for model factories (empty at first) |
| `views/layout.templ`, `views/home.templ` | templ layout (`<html lang dir>` in the request's locale, `hreflang` links with `APP_LOCALE_STRATEGY=prefix` or `subdomain`, the header with the app's name and its nav (`ui.Header`, `ui.Nav`, and `navLink`, which marks the current page with `web.RouteIs`), flash messages, CSRF header for htmx) and home page, its text from the catalog; `views/errors.templ`: error pages (404, 500…) in the layout |
| `views/ui/` | The CSS framework's components, which the layout and the pages of `make:crud` and `make:auth` call: `ui.go` (the types: `Variant`, `Size`, `Tone`, `Option`, `Pages`), `shell.templ`, `page.templ`, `form.templ`, `data.templ`, and with every CSS framework but `none`, `classes.go` (the classes of each variant, size and tone), and `css.json`, the framework's record (`css:use`). See the [UI components reference](https://docs.anetos.dev/reference/ui/index.md) |
| `locales/locales.go`, `locales/en/app.yaml` | The translations, embedded: the home page's English text. Add a language with its folder (`locales/bn/app.yaml`); see [Translations](https://docs.anetos.dev/guides/translations/index.md) |
| `public/public.go`, `public/robots.txt`, `public/static/app.css`, `public/static/favicon.svg` | `public.Files`, the web root, served at `/` by `r.Static` (`robots.txt`, allowing every page); `public.Assets`: the static files and htmx under `/assets`; the stylesheet (`--css`; a CSS framework adds the framework's files); the icon browsers show |
| `Dockerfile`, `.dockerignore` | A container image: `anetos build` in `golang:<go version>`, the binary alone in `gcr.io/distroless/static-debian12:nonroot` (user 65532), `/data` for the files (and the SQLite database, migrated when the server starts: `DB_MIGRATE_ON_START=true`), `HEALTHCHECK` with `health:check`. See [Deploy](https://docs.anetos.dev/guides/deployment/index.md#run-it-in-a-container) |
| `deploy/<name>.service`, `deploy/production.env.example` | A systemd unit (migrations before start, restart on failure, sandboxed) and the production settings to fill in. See [Deploy](https://docs.anetos.dev/guides/deployment/index.md#run-it-on-a-server-with-systemd) |
| `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.agents/skills/anetos-*/SKILL.md`, `.claude/skills/anetos-*/SKILL.md` | The files coding agents read: instructions and task guides (skills), as [`agent:install`](https://docs.anetos.dev/reference/cli/index.md#anetos-agentinstall-and-agentupdate) writes them for every agent; not with `--no-agent` |

### The API project

`--stack=api` writes the same `main.go` without sessions or
templ, `plugins.go`, `.env` files, `README.md`, `.gitignore`,
`app/models/`, `database/`, `Dockerfile`, `.dockerignore` and
`deploy/`, and in place of the web stack's routes, handlers, views and
static files:

| Path | Holds |
|---|---|
| `routes/api.go` | `Register(r)`: `r.UseGlobal(web.JSONErrors)` (every error is problem JSON, whatever the client accepts; [Return errors](https://docs.anetos.dev/guides/handlers/index.md#json-errors)) and the group `api`, `/api/v1` with route names `api.…`, where `make:handler` suggests routing its handlers; `OpenAPI`, the API's description's `openapi.Config` |
| `app/handlers/welcome.go` | `GET /api/v1` (`api.welcome`): a typed handler (`web.H`) answering `WelcomeResponse`, `{"name", "message"}`, the message from the catalog in the request's language |
| `locales/en/app.yaml` | The API's English messages |
| `main_test.go` | Tests of `GET /api/v1`, of a missing URL's problem details, and that `openapi.json` is up to date (`openapi.Check`) |
| `openapi.json` | The API's OpenAPI 3.1 description, written by `go run . openapi` (not with `--skip-install`) and served at `/api/v1/openapi.json`; `main.go` calls `openapi.Register`. See [Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md) |

`.env`, `.env.example` and `deploy/production.env.example` have
`HTTP_CORS_ORIGINS=` (empty: no browser on another origin may call the
API; [configuration](https://docs.anetos.dev/reference/configuration/index.md)) and no `SESSION_DRIVER` or
`APP_LOCALE_STRATEGY`. In an API project (`routes/api.go` and no `routes/web.go`),
`make:handler` (a typed handler, routed with `web.H`, answering a struct),
`make:middleware`, `make:auth` (accounts logging in with API tokens)
and `make:crud` (JSON endpoints) write for the API, and
`make:admin`, which writes pages, refuses.

## `anetos dev`

| Flag | Default | Meaning |
|---|---|---|
| `--addr` | `HTTP_ADDR` from `.env`, else `:8080`; without a host, on `127.0.0.1` only | Where to browse the app (`--addr=0.0.0.0:8080` to reach it from other machines, with a warning: the dev server shows build errors and your code's paths) |
| `--host` | `localhost`, `*.localhost`, IP addresses and `APP_URL`'s host | Another host name browsers may use (repeat the flag for more); requests for other names get 403, which stops DNS-rebinding pages from reading the app |
| `-- args…` | `run` | Arguments for the app binary |

Run it in the project (any directory under `go.mod`). On start and on
every change it:

1. runs `go tool templ generate` (if there are `.templ` files) and `anetos generate`,
   and in a project that uses Tailwind CSS compiles `public/static/app.css`
   as `css:build` does (when Tailwind can't run, it says why and
   keeps the `app.css` there is until it's restarted),
2. builds the app into `tmp/anetos-dev/`,
3. stops the previous app (interrupt, then kill after 10 s) and starts the
   new one with `HTTP_ADDR` set to a free local port,
4. once the app accepts connections, tells open pages to reload.

Watched: `.go` (not tests or generated files), `.templ`, `go.mod`,
`go.sum`, `.env*`, everything under `public/` and `views/ui/tailwind.css`
(but not a Tailwind project's `public/static/app.css`, which the build
writes); directories starting
with a dot, `node_modules` and `testdata`, and `tmp`, `vendor`, `bin` and
`storage` at the project's root are skipped. Requests during a restart
wait for the new version. The proxy adds a small script to HTML pages
(not htmx responses, HEAD requests or empty responses) that reloads them;
build errors, and an app that stops or doesn't start, show as an error
page until the next change. On Linux the app is stopped even if
`anetos dev` is killed.

## `anetos build`

`anetos build [-o file] [--target=os/arch] [--version=v1.2.0] [--cgo] [-- go build flags]`

| Flag | Default | Meaning |
|---|---|---|
| `-o` | `bin/<name>`: the module path's last element, or the one before a `/v2` suffix (`.exe` for Windows) | The binary to write |
| `--target` | `go env GOOS`/`GOARCH` | The system to build for: `linux/amd64`, `linux/arm64`, `windows/amd64`… The generators still run on this one |
| `--version` | the version Go records from git: the tag of the commit (`v1.2.0`), else a pseudo-version (`v0.0.0-20261006100000-1a2b3c4d5e6f`); `(devel)` outside a repository | The app's version, for its `version` command: letters, digits and `. + - _ ~ /` |
| `--cgo` | `false` | Build with `CGO_ENABLED=1` (only for a driver or package that needs cgo; SQLite doesn't) |
| `-- flags…` | | More `go build` flags (`-tags=…`); an `-ldflags` is added to the build's own |

Run it in the project. It runs `go tool templ generate` (if there are
`.templ` files), `anetos generate` and, in a project that uses Tailwind CSS,
Tailwind as `css:build` does (failing if it can't run), then `go build -trimpath
-ldflags="-s -w" .` with `CGO_ENABLED=0`, and prints the binary, its
system and size (`built bin/blog (linux/amd64, 18.3 MB)`). Use
`--target` rather than `GOOS` and `GOARCH`: with those set, `go tool`
builds the tool itself for the other system, which then can't run. The
binary holds the migrations, views, `public/` and `locales/`: copy it
alone. Built in a git repository, it records the commit (and whether
files were changed) for `version`.

## `anetos make:*`

Run anywhere in a project. Existing files are never overwritten
(`make:auth` adds one call to `setup` in `main.go` and one line to
`views/layout.templ`; `make:crud` adds one line to `routes/web.go` and
one to `views/layout.templ`; `make:admin` changes `setup` and adds a
line to `views/layout.templ`; `make:admin-resource` adds a line to
`app/admin/admin.go`).

| Command | Writes |
|---|---|
| `make:handler <Name>` | `app/handlers/<name>.go`: a handler type with an `Index` method; in an API project, a typed `Index` (for `web.H`) answering `<Name>Response` as JSON, its comment routing it in `routes/api.go` |
| `make:model <Name> [--migration]` | `app/models/<name>.go`: a model embedding `db.Model`, then its typed columns (`anetos generate`); with `--migration`, also `create_<table>_table` |
| `make:migration <name>` | `database/migrations/<YYYY_MM_DD_HHMMSS>_<name>.go`: `create_posts_table` creates a table; `add_x_to_posts_table` (the last `to`, `from`, `in` or `on`) gets commented `Alter` code for that table; other names get empty functions. The timestamp is always after the newest migration's, so migrations made in the same second keep their order |
| `make:middleware <Name>` | `app/middleware/<name>.go`: a `func(http.Handler) http.Handler` |
| `make:crud <Model> <field:type[:optional\|:unique]>...` | A model with its table and the pages to list, show, create, edit and delete its rows: `app/models/<model>.go`, a `create_<table>_table` migration, `app/handlers/<table>.go` (`handlers.<Models>`: `Index` with 20 rows a page, `Show`, `New`, `Create`, `Edit`, `Update`, `Delete`; the form `<Model>Input` with its validate tags), `views/<table>.templ` (the list, the page, the form, calling the components of `views/ui`), `routes/<table>.go` (`routes.<Models>(r)`: `/<path>`, the table with `-` for `_`, named `<path>.index`, `.new`, `.create`, `.show`, `.edit`, `.update`, `.delete`, as the handlers), `locales/en/<table>.yaml` (the pages' text) and `<table>_test.go` (its comment shows how to log a user in for pages in `make:auth`'s `loggedIn` group); then `anetos generate`, `templ generate` and `go build ./...`. Types: `string` (255), `text`, `email`, `int` (`int64`), `float` (`float64`), `bool`, `date` (`anetos.Date`). Strings, emails, texts and dates are required unless `:optional`; `:unique` (required strings and emails, dates) adds a unique index and the `unique` rule. Refused: a plural that is the name (`News`), the tables of the framework and `make:auth` (`users`, `api_tokens`…), the field `model`, and two fields with one Go name (`a_1` and `a1`). Adds `<Models>(pages)` at the end of `Register` in `routes/web.go` and a `navLink` to the list at the end of the header's nav in `views/layout.templ`: the `@ui.Nav` block, or before the `</nav>` of a layout made earlier (else it prints what to add). In a web project without `views/ui` (made before v0.5), it first writes the components of the CSS framework closest to `public/static/app.css` (`anetos` if it has the starter theme's `.card` rule, else `none`), and says so; the stylesheet and the layout are left as they are. Writes nothing if a file or the migration exists or a name is taken. See [Add pages for a model](https://docs.anetos.dev/getting-started/crud/index.md). In an API project: JSON endpoints instead, with the model and migration, `app/handlers/<table>.go` (`<Model>Response`, the output struct; `<Model>Input`; `<Model>List`, the query: `page`, `per_page` ≤ 100, `sort` from a list of columns, exact filters on string, email, int, bool and date fields, so no field may be named `page`, `per_page` or `sort`; `Index` answering `db.Page[<Model>Response]`, `Show`, `Create` with `Location`, `Update` (PUT), `Delete`), `routes/<table>.go` (`/api/v1/<path>`, named `api.<path>.index`…; the create route `.Status(201)`) and `<table>_test.go`; `<Models>(api)` added to `Register` in `routes/api.go` (else it prints the call); no views or catalog; then `go run . openapi`, updating `openapi.json` (a failure is reported, not fatal). See [Add pages for a model](https://docs.anetos.dev/getting-started/crud/index.md#in-an-api-project) |
| `make:agent <Name>` | `app/agents/<name>.go`: an `ai.Agent` with a typed tool; prints how to set up `ai.New` if `main.go` doesn't call it |
| `make:auth` | Accounts, with Google and GitHub login: `app/models/user.go` (`User` with `disabled_at` and `session_key`, `models.Users`), `app/handlers/auth.go` (`handlers.Accounts`, `handlers.SocialUser`, `handlers.SendVerification` and `SendPasswordReset`), `app/mailers/auth.go` and `views/auth_mail.templ` (verification and reset emails), `views/auth.templ` (pages, and `AccountMenu`, the header's account links), `routes/auth.go` (`routes.Auth`), `auth.go` (`setupAuth`: `auth.WithDefaultHomeURL("/dashboard")` and `sessions.Use(a.Middleware)`), `auth_test.go`, `locales/en/auth.yaml`, `database/factories/users.go` (`factories.Users`, verified users whose password is `factories.UserPassword`, for tests with `anetostest.ActingAs`), and a `create_users_table` migration; the empty `SOCIAL_GOOGLE_*` and `SOCIAL_GITHUB_*` settings appended to `.env`, `.env.example` and `deploy/production.env.example` (unless there); then `go mod tidy`, `anetos generate`, `templ generate` and `go build ./...`, and a `setupAuth` call in `setup` after its `routes.Register(srv.Router(), sessions)` statement (else it prints the call to add), and `@AccountMenu()` after the layout header's nav: the `@ui.Nav` block, or the `</nav>` line of a layout made earlier (else it prints the line to add). In a web project without `views/ui` (made before v0.5), it first writes the components, as `make:crud` does. Writes nothing if one of the files or a `create_users_table` migration exists, or a name the files declare is taken in its package; removes what it wrote if a write fails. See [Add accounts with make:auth](https://docs.anetos.dev/guides/accounts/index.md). In an API project, JSON endpoints under `/api/v1` logging in with API tokens instead: `app/models/user.go` (without `remember_token`, `pending_email` and the preferences), `app/handlers/auth.go` (`handlers.Accounts`, typed handlers answering `UserResponse`, `LoginResponse`, `TokenResponse`…), `app/mailers/auth.go` and `app/mailers/auth.html` (the emails, an `html/template` file), `routes/auth.go` (`routes.Auth(r, a)`, with `TokenMiddleware`; the account's routes need a token with every ability, `auth.RequireAbilities("*")`), `auth.go` (`setupAuth(app, r)`; refuses to boot without `AUTH_CLIENT_URL` in production and staging), `auth_test.go`, `locales/en/auth.yaml`, `database/factories/users.go` and the migration; `AUTH_CLIENT_URL` appended to the settings files; the call after `routes.Register(srv.Router())`; no templ; then `go run . openapi`, updating `openapi.json`. See [Add accounts to an API](https://docs.anetos.dev/guides/api-accounts/index.md) |
| `make:admin` | The admin interface, after `make:auth`; refused in an API project: adds the module `anetos.dev/anetos/admin` (`go get`; in a project whose core module is replaced by a checkout, from the checkout), writes `admin.go` (`setupAdmin`: roles and permissions with `rbac.New` and an `admin` role, unless a Go file of the project already calls `rbac.New`; then `admin.New`, the users, `admin.Roles`, the dashboard (`admin.SignUps` of the users, `admin.QueueHealth`, `admin.AIUsage` if the project tracks AI usage, `admin.RecentActivity` if it keeps an audit log), `admin.Jobs` and `admin.Schedule` (for the app's queue and scheduler), `admin.Activity` (with an audit log), the resources of `app/admin`, and `Mount` with the pages' middleware), `app/admin/admin.go` (`Resources`, empty), `app/admin/users.go` (`Users`: `admin.Users` for `models.User`, with the columns and `handlers.SendVerification` and `SendPasswordReset` the model and handlers have) and `admin_test.go` (with `rbac.New` and `make:auth`'s tests); adds `@admin.Banner()` after `<body>` in `views/layout.templ` (else it prints the line to add); appends the empty `ADMIN_PATH` and `ADMIN_HOST` to `.env` and `.env.example`; replaces `make:auth`'s `setupAuth` call in `setup` with one that keeps its `*auth.Auth` and calls `setupAdmin` (else it prints the calls to add); then `go mod tidy`, `templ generate` and `go build ./...`. Restores `go.mod` and `go.sum` if it fails before writing. See [Add an admin panel](https://docs.anetos.dev/guides/admin/index.md) |
| `make:admin-resource <Model>` | `app/admin/<models>.go`: the admin's resource for a model of `app/models`, named after the type (`Post`: `posts` at `/admin/posts`, function `Posts`): columns (the ID and the first four fields the form edits, or the first five without `db.Model`; `created_at`), search over its first three string fields, and a form struct `<Model>Form` with the fields of types a form can edit (strings, numbers, bools, `time.Time` as `admin.DateTime`, `anetos.Date`, and pointers to them), leaving out the key, the timestamps, JSON and read-only columns and names like password, token or secret; adds the function to `Resources` in `app/admin/admin.go` |

Names may be `BlogPost`, `blog_post` or `blog-post`; files use snake case.

## `anetos add <module>[@version]` and `anetos remove <module>`

Install and uninstall [plugins](https://docs.anetos.dev/guides/plugins/index.md), from the project's
directory or below. Both rewrite `plugins.go` (generated: `DO NOT EDIT`),
which `setup` passes to `ext.Load`.

`anetos add [--yes] <module>[@version]` (version default `latest`; for
Anetos's own plugins, `anetos.dev/anetos/plugins/…`, the tool's version):

1. Prints the module and the version, and that a plugin is code that
   runs with the app's privileges; runs `go get <module>@<version>`.
2. Adds the package's `Plugin()` to `plugins.go`, after the others, and
   runs `go mod tidy` (the module becomes a direct requirement).
3. Runs `go build`, so a module without a `Plugin() ext.Plugin`
   function, or one that doesn't compile against this version of
   Anetos, is refused.
4. In a terminal, asks before going on (`--yes`, or a stdin that
   isn't a terminal, doesn't ask): the next step runs the plugin's
   code on your machine, with your environment and `.env`.
   Then runs the built app's `plugin:env` (stopped after 2 minutes), which loads the
   plugins without booting the app: if `ext.Load` refuses the plugin
   (its `Requires()`, its name, its settings' names), so does `anetos
   add`. Otherwise it appends the settings `.env.example` doesn't have
   yet (commented and `export` keys count as present) under a
   `# <name> plugin` line; if the app fails for another reason, it
   prints the error and keeps the plugin.
5. Prints the next steps: `plugin:list`, and `migrate` if it adds
   migrations. Migrations never run by themselves.

If step 1 to 4 refuses the plugin, `go.mod`, `go.sum` and `plugins.go`
are put back as they were (exit 1). When `go get` upgrades Anetos itself
(the plugin requires a newer version), `anetos add` says so. Adding a
module that `plugins.go` already lists is an error (exit 1). Import
names in `plugins.go` avoid the names `package main` declares.

`anetos remove` takes the module out of `plugins.go`, runs `go mod tidy`
and `go build` (putting the three files back if one fails, for example
because your code still imports the plugin). The plugin's settings stay
in `.env` and `.env.example`, and its tables in the database: drop them
with a migration of your own if you want them gone (`migrate:rollback`
rolls back a whole batch, your app's migrations included). Anetos stays
at the version `anetos add` left it at.

## `anetos locale:add [--from dir] [--version v] [--force] <locale>...`

Copies the translations of the framework's messages for each locale
from the module `anetos.dev/locales`
([anetos-dev/locales](https://github.com/anetos-dev/locales)) into the
project's `locales/<locale>/`, from the project's directory or below
(`lang:add` before v0.5).

1. Downloads the module (`go mod download`, version `--version`, default
   `latest`), or uses the checkout `--from` names. The project's `go.mod`
   doesn't change.
2. Writes `framework.yaml` (validation messages, error pages, login
   messages, `format` and `relative`), and `auth.yaml` when the project
   has `locales/en/auth.yaml` (`make:auth`'s pages and emails), without
   the keys the project's other catalogs for the locale define (it lists
   them). A file the project already has is kept, unless `--force`; an
   identical one is reported as up to date.
3. Prints the next step: `go run . locale:check`.

Locale names match the module's folders regardless of case, and a
regional locale matches its language's folder (`bn-BD` writes
`locales/bn/`). With no locale, it lists those available. It fails
(exit 1), before downloading or writing anything, without a `locales`
folder or for a locale the module doesn't have. The download runs with
`GOWORK=off`; without network, pass `--from`.

## `anetos doctor [--strict] [--vuln]`

Checks the project, then builds the app and runs its
[`doctor` command](https://docs.anetos.dev/reference/cli/index.md#the-doctor-command). Run it in the project.
The project's checks:

| Check | Finds |
|---|---|
| `.env` | a warning when the file is readable by other users of the machine (`chmod 600 .env`; Unix) |
| `agents` | with agent files: a warning when they differ from this tool's (an older Anetos's, or edited between `AGENTS.md`'s markers): `anetos agent:update` |
| `git` | a problem for each tracked file of settings with secrets (`.env`, `.env.*`, `*.env`, not `*.example`, `*.sample`, `*.dist`, nor the `.env.testing` that `anetos new` writes to be committed); a warning when an untracked `.env` isn't ignored. Skipped outside a git repository |

`--vuln` also runs `govulncheck ./...` (built in, from
`golang.org/x/vuln`; it needs the network for vuln.go.dev); its findings fail the
command. `--strict` makes warnings fail it too, and is passed to the
app's `doctor`. Exit 1 when a check finds a problem, the app doesn't
build, or the app's `doctor` fails. A project that doesn't use Anetos
gets the project's checks only, with a note. The app's checks use the settings
of this machine (`.env` and the environment): run `./<app> doctor` with
the production settings too, on the server.

## `anetos security:check [flags] [--no-vuln]`

Checks the project's code and dependencies, then builds the app and
runs its [`security:check` command](https://docs.anetos.dev/reference/cli/index.md#the-security-check) in the
project, with the same flags and what the tool found (`--findings`),
and exits with its status: one report of the code, the dependencies,
the routes and the settings. The tool's part:

| Layer | Checks |
|---|---|
| Code | The project's packages (not their tests), type-checked, one function at a time: request data (`c.Param`, `c.Query`, `c.Header`, `http.Request`'s form, URL, headers and body, a typed handler's input) reaching SQL (`source.sql`), unescaped HTML (`source.xss`, at the `.templ` line for views), a redirect (`source.redirect`), a command (`source.exec`); `InsecureSkipVerify` (`source.tls`); `math/rand` for secrets (`source.rand`); advanced: file paths (`source.path`) and URLs requested (`source.ssrf`) from the request, `web.H` with a model as input (`source.mass-assign`), records loaded by an ID from the request without an access check (`source.owner`), SQL built from non-constant strings (`source.sql`, warning) |
| Files | Secrets written in the project's files (`source.secret`): keys recognized by their form (problem), random-looking values given to secret names (warning); not `.env` and other files of settings, tests, generated code, `node_modules`, `vendor` |
| Dependencies | `govulncheck ./...`, built in (`dependency.vuln`): a vulnerable function the app calls (problem, at the app's line nearest the call), a vulnerable package it imports without calling it (note, at its `go.mod` line); without the network or after 5 minutes, a note; another failure, a warning. `--no-vuln` skips it (`--no-vuln=false` doesn't) |

A finding of the code names its function with its package's path in
the module (`app/handlers.Posts.Search`), as `where` in the ignore
file. A project that doesn't build is an error (exit 1); so is
`--findings`, which is the tool's. `--out` and `--ignore` name files
relative to the current folder. The settings are
this machine's, as doctor's: without a `.env` (and no `APP_KEY` in the
environment) it exits 1 saying how to write one; run `./<app>
security:check` with the production settings too. See [Check your app's security](https://docs.anetos.dev/guides/security-check/index.md).

## `anetos check [--short] [--json]`

Checks that the project works, for you or a coding agent before calling
a change done. In order, stopping at the first failure:

| Step | Runs |
|---|---|
| `generate` | templ's views (`go tool templ generate`, when the project has `.templ` files), the models' typed columns (`anetos generate`), and in a project with Tailwind CSS its stylesheet (downloading the `tailwindcss` binary on first use, as [`css:build`](https://docs.anetos.dev/reference/cli/index.md#other-commands) does; offline, a note) |
| `build` | `go build ./...` |
| `vet` | `go vet ./...` |
| `test` | `go test ./...` (`--short`: `go test -short ./...`) |
| `doctor` | [`anetos doctor`](https://docs.anetos.dev/reference/cli/index.md#anetos-doctor---strict---vuln): the project's checks and the app's; without a `.env` (a fresh clone, an agent's sandbox, CI) the project's only, with a note saying how to write one (`cp .env.example .env && go tool anetos key:generate`) |

It writes generated code, as `anetos dev` does, and nothing else. It
prints one line per step, a failed step's output, and doctor's warnings;
`--json` prints one object, `{"ok": …, "steps": [{"step", "ok",
"seconds", "output"}…]}` (each step's output, its last 16 KB), with an
`error` when check can't start (outside a project). Exit 1 when a step
fails.

## `anetos docs [<page>] [--search <words>]`

Prints Anetos's documentation as Markdown, at the version of Anetos the
project uses: the pages (`docs/site`) are built into the tool, which the
project's `go.mod` pins.

| Form | Prints |
|---|---|
| `anetos docs` | Every page: its name and title, by section |
| `anetos docs <page>` | One page. `<page>` is its path without `.md` (`guides/queues`), the end of it (`queues`) or a word of its title; when several match, it lists them and exits 2 |
| `anetos docs --search <words> [-n 5]` | The pages that best match the words, each with its lines that match: whole words, plurals aside (`ai` isn't in `email`); rare words count most, the title more than the text, and the words in a row (`log in`) more than apart. `-n` is 1 or more |

A page's relative links name pages this command prints:
`anetos docs ../guides/mail.md` is `anetos docs guides/mail`, and
`upgrade/README.md` is `upgrade`.

## `anetos agent:install` and `agent:update`

`agent:install [--agent=claude,codex,copilot,cursor,gemini]` writes the
files coding agents read, for the agents listed (all by default), as
`anetos new` does unless `--no-agent`. See [Build with a coding
agent](https://docs.anetos.dev/getting-started/coding-agents/index.md).

| File | For | Holds |
|---|---|---|
| `AGENTS.md` | every agent | The project (stack, database, CSS framework), the commands, where things go, the conventions, the skills, and "run `go tool anetos check`" |
| `CLAUDE.md` | `claude` | `@AGENTS.md`: Claude Code imports it |
| `GEMINI.md` | `gemini` | `@AGENTS.md`: Gemini CLI imports it |
| `.claude/skills/anetos-*/SKILL.md` | `claude` | The skills: `anetos-crud`, `-auth`, `-migration`, `-job`, `-page` (web) or `-api` (API), `-test`, `-deploy`, `-upgrade`, `-plugin` |
| `.agents/skills/anetos-*/SKILL.md` | `codex`, `copilot`, `cursor`, `gemini` | The same skills |
| `.mcp.json` | `claude`, `copilot` | The MCP server `anetos` (`go tool anetos mcp`) in `mcpServers`: Claude Code's project servers, and Copilot CLI's |
| `.vscode/mcp.json` | `copilot` | The same in `servers`, with `"type": "stdio"` and `"cwd": "${workspaceFolder}"`: VS Code's |
| `.cursor/mcp.json` | `cursor` | The same in `mcpServers`, as `go -C ${workspaceFolder} tool anetos mcp` |
| `.gemini/settings.json` | `gemini` | The same in `mcpServers`, with a 15-minute `timeout` (`check` runs the tests) |
| `.codex/config.toml` | `codex` | The table `[mcp_servers.anetos]`, with `startup_timeout_sec = 120` and `tool_timeout_sec = 900` (Codex reads a project's file once you trust the project) |

The MCP files are shared with your own servers and settings: the
`anetos` entry is added when the file has none, and the rest kept. An
entry named `anetos` is left as it is, the tool's (which you may have
edited, adding an `env` or `--dir`) or your own. A JSON file is
rewritten with its keys sorted (JSON doesn't keep their order), its
numbers as written; one with comments is refused, with the entry to add
yourself, and the other files are still written (exit 1). The files are those of exactly the agents listed: Anetos's skills in a
folder none of them reads are removed (`--agent=claude` removes
`.agents/skills/anetos-*`), and so is the tool's `anetos` entry from the
others' MCP files (with its subtables in TOML; a file left empty goes); `CLAUDE.md` and `GEMINI.md` stay, being
partly yours. It keeps what you wrote: in `AGENTS.md`, the text outside the markers
`<!-- anetos:begin … -->` and `<!-- anetos:end -->` (a file without
them gets Anetos's text first, then its own); in `CLAUDE.md` and
`GEMINI.md`, everything, with the import added first when missing;
skills not named `anetos-*`. Running it again changes only what differs.

`agent:update` rewrites them for this version of Anetos, for the agents
whose files the project has (`.claude/skills/anetos-*` for `claude`;
with `.agents/skills/anetos-*`, `codex`, `copilot` and `cursor` by
their MCP files' `anetos` entry, or `codex` without any; `gemini` by
`GEMINI.md`'s import and `.gemini/settings.json`'s entry), and removes nothing: run it after an upgrade (`doctor` warns
when they differ, line endings aside). It fails in a project without
agent files. The project's name in the files is its binary's
(`deploy/<name>.service`, else the module's last part), not its
folder's, so a clone or worktree under another name doesn't change them.

## `anetos mcp [--dir=<project>]`

An [MCP](https://modelcontextprotocol.io) server on the standard input
and output, which coding agents start from the files `agent:install`
writes (`go tool anetos mcp`, so it's the project's version of Anetos).
Its tools read the project and the documentation, and check changes.
None changes your code or data: `check` writes generated code, as
`anetos dev` does, and the app's commands create what the app creates
when it starts (`storage/`, an empty SQLite database):

| Tool | Does |
|---|---|
| `docs_list`, `docs_read`, `docs_search` | `anetos docs`: the pages, one page, a search |
| `model_list` | `model:list --json` |
| `app_about`, `route_list`, `db_schema`, `migrate_status`, `command_list` | The app's `about`, `route:list`, `db:schema`, `migrate:status` and `help`, with `--json`: it builds the app (`go build`, cached) and runs the command in the project, which needs a `.env` |
| `check` | `check --json`; an error result when a step fails |
| `doctor` | `doctor`'s report; an error result on a problem |

The project is `--dir`'s, else the one around the directory the agent
starts it in. `go tool` itself needs to start in the project (outside
it, `go tool anetos` isn't found): an agent that starts its servers
elsewhere runs `go -C <project> tool anetos mcp`, as Cursor's entry
does. One `check` runs at a time; the app is built into a temporary
folder, removed when the server stops. Its instructions tell the agent to search the docs before
guessing an API and to run `check` before calling a change done.
[gopls](https://go.dev/gopls) has an MCP server of its own for Go
itself (`gopls mcp`): add it to the same files if you have gopls.

## Other commands

| Command | Does |
|---|---|
| `anetos generate [--check] [packages]` | Typed model columns ([reference](https://docs.anetos.dev/reference/anetos-generate/index.md)) |
| `anetos model:list [--json] [packages]` | The models, read from the code as `generate` reads it, so the app needn't run: each one's package, file and table (its `TableName` method's string, else the plural of its name in snake case), its columns (the column, the typed column's field in `<Model>Cols`, the Go type, `json`) and its relations (the field, `belongs_to`, `has_one`, `has_many` or `many_to_many`, the related model). `--json` prints a list of `{"package", "name", "table", "table_method", "file", "columns", "relations"}`. Packages default to `./...` |
| `anetos css:build [--check]` | In a project that uses Tailwind CSS: compiles `views/ui/tailwind.css` into `public/static/app.css` with Tailwind CSS's standalone CLI (`--input views/ui/tailwind.css --minify`), writing it only when it changes. The first run downloads Tailwind CSS 4.3.3 for the platform from its GitHub releases into the user cache directory (`<cache>/anetos/tailwindcss/v4.3.3/`), checking the SHA-256 written in `anetos` then and before each run (a download that sends nothing for 30 s stops); `ANETOS_TAILWIND=<path>` runs that binary instead (its version is checked, and a different one warned about). `--check` writes nothing and exits 1 when `app.css` is out of date. Exits 1 in a project without `views/ui/tailwind.css` ([Tailwind CSS](https://docs.anetos.dev/guides/tailwind/index.md)) |
| `anetos css:use [<framework>] [--force]` | Switches a web project's CSS framework: writes its files in `views/ui` and `public/static/`, removes the old one's files the new one lacks (and their `_templ.go`), records the framework in `views/ui/css.json` (its name and version, the SHA-256 of each file), adds `nav.menu` to `locales/en/app.yaml` if missing (or says what to add, when it can't edit the file safely; and names the other locales without it), runs `templ generate`, and for `tailwind` `css:build` (going on without Tailwind: the `app.css` anetos ships is compiled for the components). Exits 1, writing nothing, when a recorded file changed since (line endings aside) or is a symbolic link, when a file in the new framework's way isn't the old one's (it lists them), or when the project has no usable `css.json` (missing, not JSON, or naming a file outside `views/ui` and `public/static`): `--force` replaces them (without a record, it lists `public/static`'s files that aren't the new framework's instead of removing them). Each file is written through a temporary file, the record last. Then runs `go build ./...`, exiting 1 when the project doesn't build with the new framework. With the project's own, updates its files to this version's. Lists your own files in `views/ui`, which keep their classes, and the `Dockerfile` cache line to add or remove when moving to or from Tailwind. Without `<framework>`, prints the project's. Refused in a project without `views/ui` (an API project, or one made before v0.5) ([Style your app](https://docs.anetos.dev/guides/styling/index.md#8-switch-css-frameworks)) |
| `anetos key:generate [--show] [--force]` | Sets `APP_KEY` in `.env` to a new key when it is missing or empty (it used to print it); refuses when it is set, unless `--force`, which moves the old key to the front of `APP_PREVIOUS_KEYS`. `--show` prints `APP_KEY=base64:…` on stdout instead, for a server's environment; the other messages go to stderr |
| `anetos version` | Prints the tool's version |

A command's name may be shortened, each part between colons, while it
stays unique, among the commands with as many parts: `anetos
g` is `generate`, `anetos k:g` `key:generate`, `anetos m:admin`
`make:admin` (the part written whole wins over `make:admin-resource`);
an ambiguous one (`anetos d`: `dev`, `docs` or `doctor`) lists the candidates
and exits with status 2. Before v0.5, `locale:add` was `lang:add` (or
`add lang`) and `make:admin-resource` was `make:admin:resource`: the
old names still run, with a warning, until v0.6. `generate` was `gen`,
which is one of its short forms.

## App binary commands

`app.Execute()` runs the command named by the first argument, which may
be shortened, each part between colons, while it stays unique among
the commands with as many parts: `./app r:l` is `route:list`,
`./app mi` `migrate`. (`version` is handled before the app is set up
only when written whole.) Before
v0.5, `route:list` was `routes:list`, `plugin:list` and `plugin:env`
were `plugins:list` and `plugins:env`, and `locale:check` was
`lang:check`: the old names still run, with a warning, until v0.6
(`cmd.Command.Former`).

| Command | Added by | Does |
|---|---|---|
| (none), `run [--only=type,…]` | every app | Runs the background components (all, or those of the process types `web`, `worker`, `scheduler`, `listener`, plus those without one) until SIGINT/SIGTERM (exit 0) |
| `serve` | `web.NewServer` | `run --only=web` |
| `route:list [--json]` | `web.NewServer` | Method, path and name of every route. `--json`: `{"middleware": […], "routes": [{"method", "host", "path", "name", "handler", "input", "output", "status", "file", "line", "public", "middleware": […]}]}`, the global middleware first; `file` and `line` are where the route was registered (relative to the module's folder), `public` the reason given to `Public` (both omitted when empty); each middleware is `{"name", "detail", "security", "scopes", "responses"}`, named as Go code names it (`web.CSRF`, `session.Manager.Middleware`, `auth.Auth.Require`, `rbac.Require` with its permissions as `detail`, `ratelimit.Middleware` with its limit's name), what it said with `web.Documented` (`web.MiddlewareDoc`), outermost first. `security` is what an API description shows: `auth.Auth.Require` says `bearer` on pages too, where the user comes from the session. Login attempts are limited inside `auth`'s login (`AUTH_THROTTLE`), not by a middleware, so `POST /login` lists none |
| `openapi [--check] [--out=FILE]` | `openapi.Register` | Writes the API's OpenAPI 3.1 description to `openapi.json` (`Config.File`; `--out=-`: the standard output), warning about routes it leaves out; `--check` exits 1 if the file differs. Doesn't boot the app. See [Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md) |
| `health:check [--live] [--timeout=5s]` | `web.NewServer` | Asks the server running on `HTTP_ADDR` (on `127.0.0.1` when its host is empty, `0.0.0.0` or `[::]`) for `/health/ready` (`--live`: `/health/live`), for container health checks: prints `ok`, or exits 1. An error with `HTTP_HEALTH_ROUTES=false` |
| `migrate`, `migrate:rollback`, `migrate:reset`, `migrate:fresh`, `migrate:status [--json]`, `db:seed`, `db:schema [--json] [table…]` | `migrate.New` | See the [migrations reference](https://docs.anetos.dev/reference/migrations/index.md#commands); `db:schema` describes the tables: columns, indexes, foreign keys |
| `search:reindex [table…]` | `migrate.New` | Rebuilds the search indexes (all, or the tables') for `DB_SEARCH_LANGUAGE` and `DB_SEARCH_RANKING`. See [Search](https://docs.anetos.dev/guides/search/index.md) |
| `ai:embed [table…]` | `ai.EmbeddingsFor` | Embeds the records whose text or embedding model changed (all tables', or the named ones), a hundred at a time; unchanged chunks aren't embedded again. See [Search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md) |
| `cache:clear` | `cache.New` | Removes the app's cache items (keys with `CACHE_PREFIX`), locks included |
| `queue:work` | `queue.New` | Runs only the workers, as `run --only=worker`; the queues and concurrency are those the app's `Work` call sets |
| `queue:failed [--limit=N]`, `queue:retry <id>…\|all`, `queue:forget <id>…`, `queue:flush [--force]`, `queue:clear [--force] [queue]` | `queue.New` | List, retry and delete failed jobs; delete the jobs waiting on a queue. `flush` and `clear` need `--force` in production. See [Queues](https://docs.anetos.dev/guides/queues/index.md#4-handle-failed-jobs) |
| `pubsub:publish <topic> <message>` | `pubsub.New` | Publishes a message (its body as given) to a topic. See [Pub/sub listeners](https://docs.anetos.dev/guides/pubsub/index.md#4-publish) |
| `locale:check [dir]` | `i18n.New` | Reports keys a supported locale lacks (against `APP_FALLBACK_LOCALE`'s), placeholders that differ, plural forms a language needs, and keys the `.go` and `.templ` files under `dir` (default `.`) use that no catalog has (a literal followed by `+` is a prefix some key must start with); notes the framework's messages a locale leaves in English. Exits 1 on a problem; doesn't boot the app. See [Translations](https://docs.anetos.dev/guides/translations/index.md#7-check-the-catalogs) |
| `schedule:list [--json]` | `schedule.New` | Each task, its schedule, its next run and options (`--json`: `name`, `schedule`, `next`, `without_overlapping`, `on_one_server`, `timeout`). See [Scheduling](https://docs.anetos.dev/guides/scheduling/index.md#4-check-and-run-tasks) |
| `schedule:run` | `schedule.New` | Runs the tasks due this minute, once, with their locks, and exits: for cron or a Kubernetes CronJob every minute (with a task's name it runs that task, as `schedule:test`, with a warning, until v0.6) |
| `schedule:test <task>` | `schedule.New` | Runs a task now, whatever its schedule (`WithoutOverlapping` applies, across processes only with a shared cache store; `OnOneServer` doesn't) |
| `schedule:work` | `schedule.New` | Runs only the scheduler, as `run --only=scheduler` |
| `rbac:roles`, `rbac:user <user-id>`, `rbac:assign [--scope=kind:id] <user-id> <role>`, `rbac:unassign …` | `rbac.New` | List the roles and their users; show a user's grants; give or take a role. See [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md) |
| `db:prune-trashed [--dry-run]` | `db.Prunable` | Deletes for good the rows of the registered models soft-deleted longer ago than their duration; `--dry-run` counts them. See [Keep an audit log](https://docs.anetos.dev/guides/audit-log/index.md#soft-deletes-that-play-well-with-the-log) |
| `audit:prune` | `audit.New` | Deletes the audit entries older than `AUDIT_RETENTION_DAYS`, and records that it did |
| `audit:anonymize <actor-type> <actor-id>` | `audit.New` | Replaces an actor (`user 42`) with `erased` in the audit log, as the actor and as the user someone impersonated, and drops the IP addresses of their entries, for erasure requests. See [Keep an audit log](https://docs.anetos.dev/guides/audit-log/index.md#8-keep-entries-for-as-long-as-you-must-and-no-longer) |
| `plugin:list [--json]` | `ext.Load` | Each plugin, its version constraint, its route prefix and what it adds (or that its settings are missing); `--json` adds its settings (`name`, `default`, `required`); doesn't boot the app. See [Use plugins](https://docs.anetos.dev/guides/plugins/index.md) |
| `plugin:env [plugin]` | `ext.Load` | The plugins' settings as `.env` lines with their defaults (double-quoted when they need it; `# required` after required ones); doesn't boot the app, so it works before they are set |
| `about [--json]` | every app | Describes the app: its name, environment, URL, time zone, module, the Anetos and Go versions, process types, the services provided (`*db.DB`, `*queue.Queue`…), its components, and the settings it read while booting with their values (`<value> (default)` for a default; `(not set)` without one, listed only by `--json`). A secret is `(set)` (a name with `KEY`, `SECRET`, `PASSWORD`, `PASS`, `TOKEN`, `CREDENTIAL`, `PRIVATE`, `DSN` or `WEBHOOK`), and in the other values a connection string's password and a URL's secret parameters and user are `xxxxx` (a URL that doesn't parse is `xxxxx` whole); a value read under its former name is `<value> (from <former>)`. It can't know every secret a value may hold: read it before you share it. It boots the app, as other commands do |
| `doctor [--strict]` | every app | Runs the app's checks of its settings and prints what they find (see [below](https://docs.anetos.dev/reference/cli/index.md#the-doctor-command)). Exit 1 on a problem (`--strict`: on a warning too) |
| `security:check [--level=basic\|advanced] [--format=text\|json\|sarif\|markdown] [--out=FILE] [--ignore=FILE] [--strict] [--findings=FILE]` | every app | Checks the app's settings and routes against security rules and reports what they find, with the `anetos` tool's findings about the code (see [below](https://docs.anetos.dev/reference/cli/index.md#the-security-check)). Exit 1 on a problem (`--strict`: on a warning too) |
| `version` | every app | The app's version (`--version` of `anetos build`, else the git tag Go recorded), commit, commit time and `modified` if the files differed from it; the Anetos version; the Go version and system. Doesn't boot the app; the `main.go` of `anetos new` prints it before `setup`, so it needs no settings (`anetos.VersionText`) |
| `help [--json] [command]`, `-h`, `--help` | every app | The command list (`--json`: each command's `name`, `usage` and `description`), or a command's usage (`<command> -h` too, as the first argument); doesn't boot the app |

| API | Does |
|---|---|
| `app.Command(name, description, run)` | Adds a command; panics if the name is invalid (lowercase words joined by `:` or `-`) or taken |
| `app.AddCommand(cmd.Command{Name, Usage, Description, Run, ManagesApp, ChangesSchema, Former})` | The same, returning an error. `Former`: the command's former names, still run (with a warning) but not listed. `ChangesSchema`: the command changes the database's structure, so boot checks that the schema matches the settings (search indexes) don't stop it |
| `cmd.Running(ctx)` | The command the app is booting or running for, in boot code (`cmd.WithCommand` sets it) |
| `app.Commands()` | Every command, sorted |
| `app.Execute()` | Runs `os.Args[1:]` with a context canceled by SIGINT/SIGTERM, then exits |
| `app.ExecuteArgs(ctx, args, stdout, stderr)` | Runs and returns the exit status (tests) |
| `args.Parse(fs)` | Parses `args.Args` with a `flag.FlagSet`; bad flags give an error matching `cmd.ErrUsage` (exit 2) |
| `cmd.Usagef(format, …)` | A usage error (exit 2) |

### The doctor command

`doctor` runs every check added with `app.AddCheck`, the ones
features add as they are set up included, and prints one line per
finding (`ok` for a check with none), then the counts. Checks that
don't need services run first, without booting the app; then it boots
the app (connecting to the database…), reporting a failed boot as a
problem, and runs the others, with those added while it booted. An app
that was booted already (in a test) stays open. Checks of deployment settings apply with `APP_ENV`
production or staging only.

```text
Checking blog (APP_ENV=production).
  ok       app
  ok       db
  warning  mail: MAIL_DRIVER=log in production: emails aren't sent; set MAIL_DRIVER=smtp (with MAIL_SMTP_URL) or a plugin's driver
  ok       session
  ok       http
  note     cache: CACHE_DRIVER=memory: each instance of the app has its own cache, rate limits and locks (cache.WithLock); with more than one instance, use redis or database
  ok       migrations
0 problems, 1 warning, 1 note.
```

| Check | Added by | Finds |
|---|---|---|
| `app` | every app | In production and staging: `APP_KEY` not set (warning), `APP_URL` not set (warning), `http://` for a host other than this machine (problem in production, warning in staging), or an example's domain (`example.com`, `.test`: warning), `APP_DEBUG=true` in staging (warning; production refuses it) |
| `db` | `db.Connect` | In production and staging: `DB_LOG_QUERIES=true` (warning); for PostgreSQL and MySQL, a server other than this machine reached without verifying its certificate (warning), from `DB_TLS` (`none`, `skip-verify`) or from `DB_URL`: PostgreSQL's `sslmode` must be `verify-full`, or `verify-ca` or `require` with an `sslrootcert` file (the server's own authority); MySQL's `tls` must be `true` or a registered configuration that checks certificates, without `allowFallbackToPlaintext`. With several hosts, the worst one counts. A `DB_URL` the driver can't read is a warning |
| `migrations` | `migrate.New` | After booting: migrations that haven't run (warning), applied ones the app no longer has (note); on MySQL and MariaDB, tables (not views) with text columns in a character set other than utf8mb4 or ascii (warning, with the `ALTER TABLE … CONVERT TO CHARACTER SET utf8mb4` that fixes them) |
| `session` | `session.New` | `SESSION_SECURE=false` in production or staging (problem); `SESSION_SAME_SITE=none` (warning); `SESSION_DOMAIN` set (note) |
| `http` | `web.NewServer` | `HTTP_TRUSTED_PROXIES` with `0.0.0.0/0` or `::/0` (problem) or a range wider than /8 (IPv4) or /16 (IPv6) (warning); `HTTP_CORS_ORIGINS=*` (warning); in production and staging, `HTTP_MAX_BODY`, `HTTP_REQUEST_TIMEOUT` or `HTTP_READ_HEADER_TIMEOUT` set to 0 (warning) |
| `mail` | `mailer.New` | `MAIL_DRIVER` `log` or `memory` in production or staging (warning); no `MAIL_FROM_ADDRESS` for a driver that sends (warning); `tls=none` in `MAIL_SMTP_URL` for a server other than this machine (warning); in production and staging, an example's domain (`example.com`, `.test`) as `MAIL_SMTP_URL`'s server or `MAIL_FROM_ADDRESS`'s (warning) |
| `cache` | `cache.New` | `CACHE_DRIVER=memory` in production or staging (note) |
| `queue` | `queue.New` | In production and staging: `QUEUE_DRIVER=memory` (warning), `sync` (note) |

| API | Does |
|---|---|
| `app.AddCheck(anetos.Check{Name, Booted, Security, Run})` | Adds a check: `Run(ctx) []anetos.Finding`, nothing when all is well; `Booted` runs it after the app boots (for checks that need a service); `Security` puts all its findings in [`security:check`](https://docs.anetos.dev/reference/cli/index.md#the-security-check)'s report too. Checks run in the order added, the booted ones last; a panic is reported as a problem. Panics without a name or `Run` |
| `anetos.Finding{Severity, Message, Rule}` | What a check found; the message names the setting and says what to do. `Rule`, for a finding about security, is its rule in `security:check`'s report (`setting.session-secure`) |
| `anetos.Note`, `anetos.Warning`, `anetos.Problem` | The severities: information; often a mistake; unsafe or broken (exit 1) |
| `env.Deployed()` | Whether an `anetos.Environment` is production or staging |
| `db.Driver.InspectURL` | For drivers: reads a `DB_URL`'s host and TLS mode (`db.TLSVerify`, `TLSSkipVerify`, `TLSNone`), for the `db` check |

### The security check

`security:check` boots the app, runs the doctor's checks and keeps
their findings about security (a finding with a `Rule`, or every
finding of a check marked `Security`, as `check.<name>`), then runs the security rules
the features and the app added, at the level asked for. It reads
`security-ignore.yaml` at the project's root (`--ignore` names another
file), and sorts the findings by severity. The rules and the ignore
file: [Check your app's security](https://docs.anetos.dev/guides/security-check/index.md#the-rules).

| Flag | Default | Meaning |
|---|---|---|
| `--level` | `basic` | `basic`: the rules with few false alarms; `advanced` adds those that find what may be on purpose |
| `--format` | `text` | `text`; `json`, one object (`app`, `env`, `level`, `findings` and `ignored`, each with `rule`, `severity`, `where`, `file`, `line`, `message`, `owasp`, and `docs` or `reason`; `summary`; `limits`); `sarif`, SARIF 2.1.0 for GitHub's code scanning (a route's finding at the line that registered it, a setting's at its line in `.env.example`, else `go.mod`'s first); `markdown`, a table |
| `--out` | the standard output | Writes the report to a file and prints the counts; `-` is the standard output |
| `--ignore` | `security-ignore.yaml` | The file of ignored findings: a list of `rule`, `where` (every place when empty), `reason` (required), `expires` (`2027-03-31`, through the end of that day in `APP_TIMEZONE`); another key is an error. A file named here must exist |
| `--strict` | off | Exit 1 on a warning too |
| `--findings` | none | A file of findings to add, as JSON: `{"rules": [{"id", "summary", "owasp", "docs"}], "findings": [{"rule", "severity", "where", "file", "line", "message"}]}`; the `anetos` tool writes it with its findings about the code |

A finding is ignored by the first entry that matches it and hasn't
expired. An expired entry whose finding is reported is a warning
(`ignore.expired`), and an entry that ignores nothing a note
(`ignore.unused`). A check or rule that panics is a problem
(`check.panic`). In SARIF, files are relative to the git repository's
root (`%SRCROOT%`), each rule has a `security-severity` (the worst of
its findings: 8.0, 5.0, 2.0), and each result a fingerprint of its
rule, place and file.

| API | Does |
|---|---|
| `app.AddSecurityRule(anetos.SecurityRule{ID, Level, Summary, OWASP, Docs, Run})` | Adds a rule: `Run(ctx, app) []anetos.SecurityFinding`, called after the app boots. `Level`: `anetos.SecurityBasic` (default) or `anetos.SecurityAdvanced`. Panics without a dotted lower-case ID (`billing.webhook-signature`; `route.`, `setting.`, `check.` and `ignore.` are the framework's) or `Run`, or with an ID already added |
| `anetos.SecurityFinding{Rule, Severity, Where, File, Line, Message, OWASP}` | What a rule found: `Where` names the place (a route, a setting); `File` and `Line` the code; `Rule` and `OWASP` default to the rule's. Its JSON is the report's (`anetos.Severity` marshals as its name) |
| `web.RouteRule(rule, func(web.RouteInfo) []anetos.SecurityFinding)` | A rule that checks each route of the app's server, its global middleware first; a finding's `Where` defaults to the route (`POST /posts`), its `File` and `Line` to where it was registered: the app's line that registered it, or that called the module that did (the admin's `Mount`) |
| `RouteInfo.Uses(name)`, `RouteInfo.String()` | Whether a route has a middleware ([`MiddlewareDoc.Name`](https://docs.anetos.dev/guides/routing/index.md)); the route as reports name it |
| `route.Public(reason)` | Marks a route open to everyone on purpose: `route.login` and `route.api-auth` leave it out, and `route:list --json` shows the reason (`public`). Panics on an empty reason |
| `anetos.OWASPAccessControl`, `OWASPMisconfiguration`, `OWASPCryptographic`, `OWASPAuthentication`, `OWASPLogging` | OWASP Top 10:2025 categories, for `OWASP` |

A command other than `run` and `serve` runs after `app.Boot`, with a
context from `app.Context`; `app.Close` follows, also after a panic. The
context is canceled by the first SIGINT/SIGTERM (the command fails with
exit 1 if it stops early); the second ends the program. An app runs one
command.


# anetos generate reference

Source: https://docs.anetos.dev/reference/anetos-generate/

`anetos generate` writes the typed columns of your models. It is part of the
`anetos` developer tool (module `anetos.dev/anetos/cli`). See
[Generate typed columns](https://docs.anetos.dev/guides/code-generation/index.md) for a walkthrough.

## Installing and running

| Command | Does |
|---|---|
| `go get -tool anetos.dev/anetos/cli/cmd/anetos@v0.5.0-rc.1` | Adds the tool to your module's `go.mod` |
| `go tool anetos generate [packages]` | Generates for the packages (default `./...`, relative to the current directory) |
| `go tool anetos generate --check [packages]` | Writes nothing; exits with status 1 and lists the out-of-date files |
| `go tool anetos version` | Prints the tool's version |
| `//go:generate go tool anetos generate` | Runs it from `go generate ./...` |

Package patterns are the ones `go build` takes. Exit status: 0 on
success, 1 on errors (or out-of-date files with `--check`), 2 for bad
usage.

## Which structs are models

A named, non-generic struct type declared at package level (in a non-test
file) is a model when it:

| Rule | Example |
|---|---|
| Embeds `db.Model`, `db.Timestamps` or `db.SoftDeletes`, directly or through embedded structs | `type Post struct { db.Model; … }` |
| Has a `TableName() string` method (value or pointer receiver) | `func (Setting) TableName() string` |
| Has `//anetos:model` in its doc comment | a plain struct |

Models, and the structs of their package they embed, must be in files
without build constraints (no `//go:build` line, no `_linux.go`-style
name), so the generated file is the same on every platform. `//anetos:skip` in the doc comment excludes a struct. Any other
`//anetos:` directive is an error. Structs that scan themselves
(`sql.Scanner`, `driver.Valuer`, `time.Time`) are values, not models.

## What is generated

One file per package, `models_gen.go`, starting with
`// Code generated by anetos generate. DO NOT EDIT.` For each model `Name` in
source order:

```go
// illustrative
// NameCols are the columns of [Name].
var NameCols = struct {
	Field db.Column[FieldType]
	…
}{
	Field: db.Col[FieldType]("column"),
	…
}
```

| Field | Generated |
|---|---|
| `Title string` | `Title db.Column[string]`, column `title` |
| `AuthorID int64 \`db:"author"\`` | `AuthorID db.Column[int64]`, column `author` |
| `PublishedAt *time.Time` | `db.Column[*time.Time]` (compare with `new(t)`, set `NULL` with `nil`) |
| `Tags []string \`db:"tags,json"\`` | `db.Column[[]string]` made with `db.JSONCol` |
| Fields of embedded structs (`db.Model`: `ID`, `CreatedAt`, `UpdatedAt`) | Flattened in place, like the runtime |
| `Author *User \`rel:"belongs_to"\``, `Comments []Comment \`rel:"has_many"\`` | A relation handle in `PostRels`: `Author db.Rel[Post, User]`, made with `db.RelOf[Post, User]("Author")` |
| Untagged struct, pointer-to-struct and slice-of-struct fields | Nothing |
| `db:"-"` and unexported fields | Nothing |

The column rules are the `db` package's
([models reference](https://docs.anetos.dev/reference/models/index.md)). The generated names are the struct
field names; an unexported model `post` gets `postCols`. Imports get
another name (`time2`) when the package already declares that name in
any of its files (in-package tests and other platforms' files included).

## Files it manages

- It only overwrites or removes a `models_gen.go` that starts with its
  header (Unix or Windows line endings); any other file with that name is
  an error, even one excluded from the build.
- It removes `models_gen.go` from a package with no models left.
- It ignores the current `models_gen.go` while reading the package, and
  compile errors outside model fields (such as code using a column not
  generated yet). Syntax errors, and type errors in a model's fields,
  stop it.
- Packages are only type-checked when they import the `db` package
  (directly or not), mention `TableName` or a `//anetos:` directive, or
  already have a `models_gen.go`.

## Errors

| Message | Meaning |
|---|---|
| `two fields map to column "x"` | Two fields have the same column name |
| `unknown db tag option "x" (known: pk, json, readonly)` | A typo in a `db` tag |
| `more than one pk field` | Composite keys aren't supported by models |
| `columns "a" and "b" both come from fields named X` | Two fields (one embedded) share a Go name; rename one |
| `XCols is already declared`, `XRels is already declared` | The package declares a name anetos generate needs |
| `unknown relation "x"`, `bad has_many option "x"` | A typo in a `rel` tag |
| `a has_many relation is a slice of models`, `… a pointer to a model` | The field's type doesn't fit the relation kind |
| `field X has a db tag and a rel tag` | A field is a column or a relation, not both |
| `field X has …, which package … can't name` | An embedded struct from another package has a field of an unexported type, a type from an `internal` package yours can't import, or an anonymous struct with unexported fields; tag it `db:"-"` or change the embedded struct |
| `models in files with build constraints aren't supported`, `embeds X, declared in a file with build constraints` | The model, or a struct of the package it embeds, is in a `_linux.go`-style file or one with a `//go:build` line: the generated file would differ per platform |
| `embeds itself` | A struct embeds itself through a pointer |
| `generic types and aliases can't be models` | `//anetos:model` on a generic type or alias |
| `is marked //anetos:model but is not a model struct` | The type isn't a struct, or scans itself |
| `models_gen.go was not written by anetos generate` | Rename your file |


# Configuration reference

Source: https://docs.anetos.dev/reference/configuration/

Every key starts with its area's prefix (`DB_`, `CACHE_`, `QUEUE_`…). The
key that picks a backend is `<AREA>_DRIVER` in every area (`DB_DRIVER`,
`CACHE_DRIVER`, `MAIL_DRIVER`, `STORAGE_DRIVER`), except `AI_PROVIDER`.

> **Note:** `doctor` warns about keys in your `.env` that look like
> these settings but aren't read (`CACHE_STORE`, `QUEUE_CONNECTION`,
> `MAIL_MAILER`, `FILESYSTEM_DISK`…), and names the key to use.

## Framework settings

Read by `anetos.New` into `anetos.AppConfig`.

| Key | Type | Default | Description |
|---|---|---|---|
| `APP_NAME` | string | `anetos` | Application name, added to every log line as `app` |
| `APP_ENV` | `development` \| `testing` \| `staging` \| `production` | `production` | Deployment environment; also selects `.env.<APP_ENV>` |
| `APP_URL` | URL | empty | The app's public URL (`https://example.com`, no path), for links that leave the app: OAuth callbacks (social login), links in emails (`mailer.URL`) |
| `APP_DEBUG` | bool | `false` | Enables debugging aids. **Rejected when `APP_ENV=production`** |
| `APP_SHUTDOWN_TIMEOUT` | duration | `30s` | Total graceful-shutdown budget: components first, then shutdown hooks. Hooks always keep the smaller of 5s and a fifth of it. Keep it at or below your platform's grace period (Kubernetes default: 30s) |
| `APP_KEY` | `base64:…` (32 bytes) | empty | Encrypts and authenticates session cookies. Required by sessions, which fail at startup without it. Generate one with `go tool anetos key:generate`. Keep it secret |
| `APP_PREVIOUS_KEYS` | list of keys | empty | Old keys that still decrypt, so `APP_KEY` can be rotated without logging everyone out |
| `APP_TIMEZONE` | IANA time zone (`Asia/Dhaka`) | `UTC` | The app's zone: the process's local zone (so `time.Now`, logs and formatting agree on every machine), the zone of `anetos.Now` and the default of `SCHEDULE_TIMEZONE`. Times are stored in UTC whatever it is. `Local` isn't allowed. See [Times and dates](https://docs.anetos.dev/guides/times-and-dates/index.md) |
| `APP_LOCALE` | locale (`en`, `bn`, `pt-BR`) | `en` | The default locale: of requests that ask for no supported one, and of code outside requests. Read by `i18n.New` |
| `APP_FALLBACK_LOCALE` | locale | `en` | Where a locale's missing messages come from, after its parents (`bn-BD`, then `bn`); the framework's English messages come last |
| `APP_LOCALES` | list of locales | `APP_LOCALE` and every locale with a catalog | The locales requests can ask for. `APP_LOCALE` must be one of them |
| `APP_LOCALE_STRATEGY` | `none` \| `prefix` \| `subdomain` | `none` | Where a request's locale is in its URL: nowhere (the `locale` cookie, the session, the logged-in user's preference, `Accept-Language`), a path prefix (`/bn/about`; the default locale has none), or a subdomain (`bn.example.com`; needs `APP_URL`). See [Translations](https://docs.anetos.dev/guides/translations/index.md#4-choose-how-visitors-get-their-language) |
| `LOG_LEVEL` | `debug` \| `info` \| `warn` \| `error` | `info` | Minimum log level |
| `LOG_FORMAT` | `text` \| `json` \| empty | empty | Log format; empty means JSON in production, text elsewhere |

`APP_ENV` defaults to `production` so that a missing setting fails safe
(debug off, JSON logs). The keys have type `anetos.Secret`, which prints,
logs and encodes as `[redacted]`; use `string(cfg.Key)` for the value.

## Struct tags

Used by `config.Bind` and `config.Get`.

| Tag | Example | Meaning |
|---|---|---|
| `env:"KEY"` | `env:"DB_PORT"` | Read the field from `KEY` |
| `env:"KEY,required"` | `env:"DB_URL,required"` | Error if `KEY` is missing or empty and there is no default |
| `env:"-"` | | Ignore the field |
| `default:"value"` | `default:"5432"` | Used when the key is missing or empty |
| `prefix:"P_"` | `prefix:"DB_"` | On a nested struct (or pointer to struct) without `env`: prepend `P_` to its keys |
| `was:"OLD"` | `was:"DB_USERNAME"` | The key's former name (with the same prefix), read when the key is unset; the app logs a warning and `doctor` lists it |

Untagged nested structs are bound recursively, without a prefix unless one is
given. Unexported fields are ignored.

## Supported field types

| Go type | Accepted values |
|---|---|
| `string` | Anything |
| `bool` | `true`/`false`, `1`/`0`, `t`/`f`, `yes`/`no`, `on`/`off` (any case) |
| `int`, `int8` … `int64` | Base-10 integers within range |
| `uint`, `uint8` … `uint64` | Base-10 non-negative integers within range |
| `float32`, `float64` | Decimal numbers |
| `time.Duration` | Go durations: `300ms`, `30s`, `5m`, `1h30m` |
| `[]T` of the above | Comma-separated; blanks trimmed; empty items dropped |
| `*T` of the above | Allocated only when a value is present |
| Types whose pointer implements `encoding.TextUnmarshaler` | Whatever `UnmarshalText` accepts, e.g. `slog.Level` |

Any other type is a binding error.

## `.env` syntax

| Form | Result |
|---|---|
| `KEY=value` | `value` (trailing spaces trimmed) |
| `KEY=value # comment` | `value`; a `#` preceded by a space starts a comment |
| `KEY=a#b` | `a#b` |
| `export KEY=value` | `value`; the `export ` prefix is ignored |
| `KEY=` or `KEY= # comment` | empty (treated as unset when binding) |
| `KEY="a\nb ${OTHER}"` | Double quotes: escapes `\n \r \t \" \\ \$`, `${VAR}` expansion, may span lines |
| `KEY='raw ${OTHER}'` | Single quotes: literal, may span lines |
| `KEY=${OTHER}-x` | Unquoted values also expand `${VAR}` |
| `# …` | Comment line |

`${NAME}` resolves with the same priority as the final configuration: the
process environment first, then keys defined earlier in the same file, then
lower layers (for `.env.<APP_ENV>`, that's `.env`). So a reference always sees
the value the application sees. Unknown names become empty; a malformed
reference such as `${` or `${A:-default}` is an error. `$NAME` without
braces is **not** expanded. If a key repeats, the last value wins. A UTF-8
byte order mark and CRLF line endings are handled.

## Load order

`config.Load` (called by `anetos.New`) layers sources, highest priority first:

1. Process environment
2. `.env.<APP_ENV>`: `APP_ENV` is taken from the process environment, else
   from `.env`
3. `.env`

`anetos.WithConfigDir(dir)` changes where the files are read from, and
`anetos.WithSource(src)` replaces the whole mechanism (useful in tests).

Every key of an area starts with its prefix (`DB_`, `CACHE_`, `MAIL_`…),
and the key that picks a backend is `<AREA>_DRIVER`. A few keys keep the
name a whole ecosystem uses: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
`GEMINI_API_KEY`, `REDIS_URL`, and the hosting platforms' `PORT` (when
`HTTP_ADDR` isn't set) and `DATABASE_URL` (see `DB_URL`).
`go run . doctor` points at a key in a `.env` file that is another
framework's name for a setting (`QUEUE_CONNECTION`), a former name left
beside its new one, or a typo of a setting.

### Former names

Projects made before v0.5 used other names for these settings. The former
names are still read, with a warning, until v0.6.

| Former name | Name |
|---|---|
| `DB_CONNECTION` | `DB_DRIVER` |
| `DB_DATABASE` | `DB_NAME` |
| `DB_USERNAME` | `DB_USER` |
| `MIGRATE_ON_RUN` | `DB_MIGRATE_ON_START` |
| `MIGRATE_READINESS` | `DB_MIGRATE_READINESS` |
| `SEARCH_LANGUAGE` | `DB_SEARCH_LANGUAGE` |
| `SEARCH_RANKING` | `DB_SEARCH_RANKING` |
| `CACHE_STORE` | `CACHE_DRIVER` |
| `SESSION_LIFETIME` | `SESSION_TTL` |
| `SESSION_MAX_LIFETIME` | `SESSION_MAX_TTL` |
| `AUTH_REMEMBER_LIFETIME` | `AUTH_REMEMBER_TTL` |
| `QUEUE_POLL` | `QUEUE_POLL_INTERVAL` |
| `LOCALE_URL` | `APP_LOCALE_STRATEGY` |

## HTTP server

Read by `web.NewServer` (or `web.LoadConfig`) into `web.Config`.

| Key | Type | Default | Description |
|---|---|---|---|
| `HTTP_ADDR` | string | `:8080`, or `:$PORT` when the platform sets `PORT` | Listen address. `127.0.0.1:0` picks a free port (tests) |
| `HTTP_READ_HEADER_TIMEOUT` | duration | `10s` | Time to read request headers (slowloris protection) |
| `HTTP_READ_TIMEOUT` | duration | `30s` | Time to read the whole request |
| `HTTP_WRITE_TIMEOUT` | duration | `30s` | Time to write the response |
| `HTTP_IDLE_TIMEOUT` | duration | `2m` | Keep-alive idle time |
| `HTTP_SHUTDOWN_GRACE` | duration | `15s` | On shutdown, how long in-flight requests may finish before their contexts are canceled and connections closed. Capped at half of `APP_SHUTDOWN_TIMEOUT`, so later stages keep time to drain |
| `HTTP_REQUEST_TIMEOUT` | duration | `30s` | Deadline on each request's context; expiry gives 503. `0` disables |
| `HTTP_MAX_BODY` | size | `10MB` | Maximum request body (`512KB`, `10MB`, `1GB`; units are powers of 1024); larger gives 413. `0` disables |
| `HTTP_TRUSTED_PROXIES` | list of IPs/CIDRs | empty | Peers whose `X-Forwarded-For` is trusted for the client IP (`X-Real-IP` isn't read) |
| `HTTP_ACCESS_LOG` | bool | `true` | One log line per request |
| `HTTP_HEALTH_ROUTES` | bool | `true` | Serve `GET /health/live` and `GET /health/ready` |
| `HTTP_CORS_ORIGINS` | list | empty (CORS off) | Allowed origins; `*` for any; `https://*.example.com` for subdomains |
| `HTTP_CORS_METHODS` | list | `GET,HEAD,POST,PUT,PATCH,DELETE` | Allowed methods for preflights |
| `HTTP_CORS_HEADERS` | list | `Accept,Authorization,Content-Type,X-Requested-With,X-Request-ID` | Allowed request headers |
| `HTTP_CORS_EXPOSE` | list | `X-Request-ID,Location,Retry-After,X-RateLimit-Limit,X-RateLimit-Remaining` | Response headers readable by browsers (`Location` and the rate limit's) |
| `HTTP_CORS_CREDENTIALS` | bool | `false` | Allow cookies; can't be combined with `*` |
| `HTTP_CORS_MAX_AGE` | duration | `10m` | How long browsers cache preflights |

Streaming responses lift `HTTP_REQUEST_TIMEOUT` and `HTTP_WRITE_TIMEOUT`
for themselves: `c.EventStream()` (server-sent events, and `ai.SSE`) does both;
other streams use `web.WithoutTimeout(ctx)` for the request's context and
`http.ResponseController`'s `SetWriteDeadline` for the response. They
should end when `srv.Stopping()` is closed, so shutdown doesn't wait for
the grace period.

HSTS (`Strict-Transport-Security`) is sent automatically when
`APP_ENV=production`; serve production over HTTPS (usually at your proxy or
load balancer).

## Sessions

Read by `session.New` (or `session.LoadConfig`) into `session.Config`.

| Key | Type | Default | Description |
|---|---|---|---|
| `SESSION_COOKIE` | string | `anetos_session` | Cookie name. A Secure cookie without `SESSION_DOMAIN` and with path `/` gets the `__Host-` prefix. A name you give with `__Host-` or `__Secure-` must meet the browser's rules for it |
| `SESSION_TTL` | duration | `2h` | The session ends after this long without a request (at least `1m`) |
| `SESSION_MAX_TTL` | duration | `168h` | The session ends this long after it started or was regenerated (login), however active. `0` disables |
| `SESSION_EXPIRE_ON_CLOSE` | bool | `false` | Browser-session cookie: dropped when the browser closes |
| `SESSION_DOMAIN` | string | empty (this host only) | Cookie domain; set it to share the session with subdomains |
| `SESSION_PATH` | string | `/` | Cookie path |
| `SESSION_SECURE` | bool | `true`, except `development` and `testing` | Send the cookie over HTTPS only |
| `SESSION_SAME_SITE` | `lax` \| `strict` \| `none` | `lax` | Cookie SameSite mode; `none` requires `SESSION_SECURE=true` |
| `SESSION_DRIVER` | `cookie` \| `database` \| a driver's name (`redis`) | `cookie` | Where sessions are kept: the encrypted cookie, or a server-side store (the cookie then holds the encrypted session ID); `redis` needs `redis.SessionDriver()` passed to `session.New` |
| `SESSION_TABLE` | string | `sessions` | The database driver's table; pass the same name to `session.Migrations` |
| `SESSION_PREFIX` | string | `APP_NAME` + `:session:` | Starts the store keys of server-side sessions. `anetostest` sets one per test app |

The cookie is always `HttpOnly`. Its content is encrypted with `APP_KEY`;
with the cookie driver it holds the whole session, limited to about 4 KB.
Server-side sessions are stored, encrypted, under keys starting with `SESSION_PREFIX`.

## Database

Read by `db.Connect` (or `db.LoadConfig(src, prefix)`, which reads the same
keys with a prefix, e.g. `ANALYTICS_DB_HOST`) into `db.Config`.

| Key | Type | Default | Description |
|---|---|---|---|
| `DB_DRIVER` | `sqlite` \| `postgres` \| `mysql` | `sqlite` | Selects one of the drivers passed to `db.Connect` |
| `DB_URL` | string | empty | Complete connection string in the driver's format; when set, the five keys below are ignored. Use it for TLS and driver options. Without it, `DB_HOST` and `DB_NAME`, and with `DB_DRIVER` unset or `postgres`, a `postgres://` `DATABASE_URL` (a hosting platform's) is used, with the postgres driver |
| `DB_HOST` | string | `127.0.0.1` | Server host (PostgreSQL, MySQL) |
| `DB_PORT` | int | driver default (5432, 3306) | Server port |
| `DB_NAME` | string | empty; SQLite: `database/app.db` | Database name, or the SQLite file (`:memory:` for an in-memory database) |
| `DB_USER` | string | empty | User |
| `DB_PASSWORD` | string | empty | Password |
| `DB_TLS` | `verify` \| `skip-verify` \| `none` | `verify` with `DB_TLS_CA` set or a remote host; `none` for a local host (localhost, loopback, Unix socket) | TLS of the connection built from `DB_HOST` (PostgreSQL `sslmode=verify-full`/`require`/`disable`, MySQL `tls=true`/`skip-verify`/`false`). With `DB_URL`, set it in the URL instead (setting both is refused) |
| `DB_TLS_CA` | path | empty | PEM file of the CAs that sign the server's certificate, for `verify` when they aren't the system's; setting it means `verify` (also through a tunnel on localhost), and it is refused with `skip-verify` or `none` |
| `DB_MAX_OPEN_CONNS` | int | `25` | Maximum open connections (in-memory SQLite always uses 1) |
| `DB_MAX_IDLE_CONNS` | int | `25` | Maximum idle connections kept for reuse |
| `DB_CONN_MAX_LIFETIME` | duration | `30m` | Connections are replaced after this long |
| `DB_CONN_MAX_IDLE_TIME` | duration | `5m` | Idle connections are closed after this long |
| `DB_LOG_QUERIES` | bool | on when `APP_ENV=development` | Log every query, with its arguments and duration, at debug level |
| `DB_SLOW_QUERY` | duration | `500ms` | Log queries taking at least this long as warnings (without arguments). `0` disables |
| `DB_REPEATED_QUERIES` | int | `5` when `APP_ENV` is `development` or `testing`, off elsewhere | Warn when an operation (a request, a job, a listener, a task) runs the same query this many times or more: an N+1. `0` disables; otherwise at least 2. See [Find N+1 queries](https://docs.anetos.dev/guides/n-plus-one/index.md) |
| `DB_MIGRATE_ON_START` | bool | `false` | With `migrate.New`: run the pending migrations when the app starts with `run` (the default command) or `serve`, before its components. For one instance on SQLite in a container; the `Dockerfile` of a SQLite project sets it |
| `DB_MIGRATE_READINESS` | bool | `true` | With `migrate.New`: the server isn't ready (`/health/ready` answers 503, `health:check` exits 1) while the database has migrations the app hasn't run, rechecked every 5 seconds. Turn it off where the migrations run after the new version starts and the platform waits for it to be ready |
| `DB_ALLOW_LOCAL_TIMEZONE` | bool | `false` | Accept a database session time zone other than UTC (set in `DB_URL`), which the app otherwise refuses at boot so the database never writes local times next to the app's UTC ones. For a legacy database whose times are local; the app still writes UTC |

### Search

| Key | Type | Default | Description |
|---|---|---|---|
| `DB_SEARCH_LANGUAGE` | `simple` \| a language | `simple` | How search matches words: `simple` as written, in any language; `english` (PostgreSQL, SQLite) also matches their other forms; on PostgreSQL any text search configuration (`german`, `french`…). MySQL has `simple` only. Search indexes are built for it: change it, then run `search:reindex` |
| `DB_SEARCH_RANKING` | `default` \| `bm25` | `default` | Order of search results: the database's own ranking, or BM25 (SQLite; PostgreSQL 17+ with the pg_textsearch extension; not MySQL). PostgreSQL needs `search:reindex` after a change |

The app refuses to start when the database can't serve these settings,
or when a search index was built for other ones (except for `migrate…`
and `search:reindex`); see [Search](https://docs.anetos.dev/guides/search/index.md).

Driver specifics:

- **SQLite** connections use WAL journaling, a 5s busy timeout, foreign
  keys and immediate transactions. The file's directory is created if
  missing.
- **SQLite** stores times as UTC text in the format of its own
  `CURRENT_TIMESTAMP` (`2026-09-30 12:00:00.5`), so column defaults and
  values written by the app compare correctly.
- **PostgreSQL** sessions use the UTC time zone unless `DB_URL` sets
  `timezone`, which the app then refuses at boot (see
  `DB_ALLOW_LOCAL_TIMEZONE`).
- **MySQL** connections always read times as UTC `time.Time`
  (`parseTime=true`, `loc=UTC`) and report matched rows for updates
  (`clientFoundRows=true`), also when `DB_URL` says otherwise; sessions use
  `time_zone='+00:00'` unless `DB_URL` sets it, which the app then refuses
  at boot (see `DB_ALLOW_LOCAL_TIMEZONE`).

## Cache

Read by `cache.New` (or `cache.LoadConfig`) into `cache.Config`.

| Key | Type | Default | Description |
|---|---|---|---|
| `CACHE_DRIVER` | `memory` \| `database` \| a driver's name (`redis`) | `memory` | Selects the store; `redis` needs `redis.CacheDriver()` passed to `cache.New` |
| `CACHE_PREFIX` | string | `APP_NAME` + `:cache:` | Starts every key, so apps (and other features in Redis) can share a store; `cache:clear` removes only these keys. `anetostest` sets one per test app |
| `CACHE_TABLE` | string | `cache` | The database store's table; pass the same name to `cache.Migrations` |

## Queue

Read by `queue.New` (or `queue.LoadConfig`) into `queue.Config`. See
[Queues](https://docs.anetos.dev/guides/queues/index.md).

| Key | Type | Default | Description |
|---|---|---|---|
| `QUEUE_DRIVER` | `sync` \| `memory` \| `database` \| a driver's name (`redis`) | `sync` | Where jobs are kept; `sync` runs each job when it is dispatched. `redis` needs `redis.QueueDriver()` passed to `queue.New` |
| `QUEUE_DEFAULT` | queue name | `default` | The queue of jobs dispatched without `queue.OnQueue`, and of workers without `queue.Queues`. Lower-case letters, digits and `. _ : -`, up to 100 |
| `QUEUE_TRIES` | int ≥ 1 | `3` | Attempts per job, unless its type sets `queue.Tries` |
| `QUEUE_TIMEOUT` | duration | `1m` | How long an attempt may run, unless its type sets `queue.Timeout` |
| `QUEUE_BACKOFF` | duration | `10s` | The wait before the first retry, doubling for each later one, unless the type sets `queue.Backoff` |
| `QUEUE_BACKOFF_MAX` | duration | `10m` | Caps the doubling |
| `QUEUE_POLL_INTERVAL` | duration | `1s` | How long an idle worker waits before looking for jobs again |
| `QUEUE_TABLE`, `QUEUE_FAILED_TABLE` | string | `jobs`, `failed_jobs` | The database driver's tables; pass the same names to `queue.Migrations` |
| `QUEUE_PREFIX` | string | `APP_NAME` + `:queue:` | Starts the Redis driver's keys (Redis 5 or later). In a Redis Cluster, put a hash tag in it (`{blog}:queue:`). `anetostest` sets one per test app |

## Pub/sub

Read by `pubsub.New` (or `pubsub.LoadConfig`) into `pubsub.Config`,
and by the drivers. See [Pub/sub listeners](https://docs.anetos.dev/guides/pubsub/index.md).

| Key | Type | Default | Description |
|---|---|---|---|
| `PUBSUB_DRIVER` | `memory` \| a driver's name (`redis`, `gcp`) | `memory` | The broker; `redis` needs `redis.PubSubDriver()` and `gcp` needs `gcppubsub.Driver()` passed to `pubsub.New` |
| `PUBSUB_PREFIX` | string | none | Starts topic names in the broker (Redis keys, Google IDs). Topics are shared with the other services using the broker, so leave it empty unless you need to separate them (or, in a Redis Cluster, need a hash tag: `{events}:`). `anetostest` sets one per test app |
| `PUBSUB_REDIS_MAXLEN` | int ≥ 0 | `1000000` | About how many messages each Redis stream keeps; 0 for no limit |
| `PUBSUB_GCP_PROJECT` | string | none (required with `gcp`) | The Google Cloud project's ID |
| `PUBSUB_GCP_CREATE` | bool | `false` | Create missing Google topics and subscriptions (development, the emulator) |

## Scheduler

Read by `schedule.New` (or `schedule.LoadConfig`) into
`schedule.Config`. See [Scheduling](https://docs.anetos.dev/guides/scheduling/index.md).

| Key | Type | Default | Description |
|---|---|---|---|
| `SCHEDULE_TIMEZONE` | IANA time zone (`Asia/Dhaka`) | `APP_TIMEZONE` | The time zone of schedules without `.In(tz)`. Times that clock changes skip don't run that day; times they repeat run twice (see [Scheduling](https://docs.anetos.dev/guides/scheduling/index.md#2-add-it-to-the-scheduler)) |

## Mail

Read by `mailer.New` (or `mailer.LoadConfig`) into `mailer.Config`,
and by the drivers. See [Send email](https://docs.anetos.dev/guides/mail/index.md).

| Key | Type | Default | Description |
|---|---|---|---|
| `MAIL_DRIVER` | `log` \| `smtp` \| `memory` \| a driver's name (`postmark`) | `log` | How emails are sent: `log` writes them to the app's log (a warning in production), `memory` keeps them (tests; `anetostest` sets it); `postmark` needs `postmark.Driver()` passed to `mailer.New` |
| `MAIL_FROM_ADDRESS` | email address | none | The sender of messages without one; sending fails without either |
| `MAIL_FROM_NAME` | string | `APP_NAME` | The sender's name |
| `MAIL_SMTP_URL` | URL | `smtp://127.0.0.1:1025` | The SMTP server: `smtp://user:pass@host:587` (STARTTLS, required unless the host is local) or `smtps://…:465` (TLS); parameters `tls=none`, `timeout` (default `30s`), `local_name`. See [SMTP settings](https://docs.anetos.dev/guides/mail/index.md#smtp-settings) |
| `MAIL_POSTMARK_TOKEN` | string | none (required with `postmark`) | The Postmark server's API token (`POSTMARK_API_TEST` checks requests without sending) |
| `MAIL_POSTMARK_STREAM` | string | `outbound` | The Postmark message stream |

## AI

Read by `ai.New` (or `ai.LoadConfig`) into `ai.Config`, and by the
drivers. See [Add AI to your app](https://docs.anetos.dev/guides/ai/index.md).

| Key | Type | Default | Description |
|---|---|---|---|
| `AI_PROVIDER` | `anthropic` \| `openai` \| `openai-compatible` \| `gemini` \| `fake` \| another driver's name | none (required) | The provider that runs the models; its driver must be passed to `ai.New` (`fake` is built in: it answers with scripted replies and never calls a model, a warning in production; `anetostest` sets it) |
| `AI_MODEL` | string | none (required by the drivers) | The model calls use unless they set `ai.Model`, by the provider's name for it |
| `AI_MAX_TOKENS` | int ≥ 1 | `4096` | The longest answer, in tokens, unless a call sets `ai.MaxTokens`; a longer one is cut off |
| `AI_TIMEOUT` | duration > 0 | `10m` | How long each request to the model may take, unless a call sets `ai.Timeout`; for a stream, including the time the reader's loop takes |
| `AI_EMBEDDING_PROVIDER` | a driver's name | `AI_PROVIDER` | The provider of embeddings (`ai.Embed`, `ai.Embeddings`), when `AI_PROVIDER`'s has none (`anthropic`): `openai`, `gemini`, `openai-compatible` or `fake`; its driver is passed to `ai.New`, and reads its own settings. `anetostest` clears it |
| `AI_EMBEDDING_MODEL` | string | none; `fake-embedding` with the fake | The embedding model, by the provider's name for it (`text-embedding-3-small`, `gemini-embedding-001`); stored with each chunk, and searches use only its chunks. Required for embeddings, and with `AI_EMBEDDING_PROVIDER` |
| `AI_QUEUE_TIMEOUT` | duration > 0 | `15m` | How long a queued reply (`conv.QueueReply`) may take, all its requests and tool calls. Also how long the queue's workers wait before taking back a job of any type whose worker died (the queue's lease is its longest job timeout) |
| `ANTHROPIC_API_KEY` | secret | none (required with `anthropic`) | The Anthropic API key |
| `ANTHROPIC_BASE_URL` | URL | Anthropic's | Another URL for the API (a proxy, a gateway) |
| `OPENAI_API_KEY` | secret | none (required with `openai`) | The OpenAI API key |
| `OPENAI_BASE_URL` | URL | OpenAI's | Another URL for OpenAI's API (a proxy, a gateway) |
| `OPENAI_COMPATIBLE_URL` | URL | none (required with `openai-compatible`) | The API URL of an OpenAI-compatible server, up to `/v1`: `http://localhost:11434/v1` for Ollama |
| `OPENAI_COMPATIBLE_KEY` | secret | none | Its API key, if it needs one (then the URL must be https, or on this machine) |
| `GEMINI_API_KEY` | secret | none (required with `gemini`) | The Gemini API key, from Google AI Studio |
| `GEMINI_BASE_URL` | URL | Google's | Another URL for the Gemini API |

The OpenAI and Anthropic SDKs also read their own variables from the
process environment (`OPENAI_ORG_ID`, `OPENAI_PROJECT_ID`,
`ANTHROPIC_AUTH_TOKEN`…): the OpenAI driver uses them, the Anthropic
and compatible drivers don't.

## Storage

Read by `storage.New` (or `storage.LoadConfig`) into `storage.Config`
for each disk, and by the drivers. The default disk reads `STORAGE_*`; a
disk named in `STORAGE_DISKS`, say `avatars`, reads `STORAGE_AVATARS_*`
(`STORAGE_AVATARS_DRIVER`, `STORAGE_AVATARS_S3_BUCKET`, …). See
[Store files](https://docs.anetos.dev/guides/storage/index.md).

| Key | Type | Default | Description |
|---|---|---|---|
| `STORAGE_DISKS` | comma-separated names | none | More disks: lower-case letters, digits and `_`, starting with a letter |
| `STORAGE_DRIVER` | `local` \| `memory` \| a driver's name (`s3`, `gcs`) | `local` | Where the disk's files are; `s3` needs `s3.Driver()` passed to `storage.New`, `gcs` `gcs.Driver()`. Named disks default to the default disk's |
| `STORAGE_ROOT` | directory | `storage/app` (`storage/<name>` for a named disk) | The local driver's directory |
| `STORAGE_URL` | URL | none | Where the disk's files are served: a CDN, a public bucket, or the route of the disk's handler. Needed for `URL`, and for `TemporaryURL` on local disks |
| `STORAGE_PUBLIC` | bool | `false` | Anyone may read the files at `STORAGE_URL`, so `URL` works; otherwise only signed temporary URLs do |
| `STORAGE_S3_BUCKET` | string | none (required with `s3`) | The bucket |
| `STORAGE_S3_REGION` | string | `us-east-1` | The bucket's region (`auto` for R2). Named disks take the default disk's region, endpoint, keys and path style if they set none of them |
| `STORAGE_S3_ENDPOINT` | URL | AWS | The store's URL, for S3-compatible stores (R2, MinIO, …). Named disks take the default disk's region, endpoint, keys and path style if they set none of them |
| `STORAGE_S3_ACCESS_KEY`, `STORAGE_S3_SECRET_KEY` | string | none | The credentials; without them, the AWS environment variables, shared credentials file or instance role. Named disks take the default disk's region, endpoint, keys and path style if they set none of them |
| `STORAGE_S3_PATH_STYLE` | bool | `false` | The bucket in the URL's path (MinIO). Named disks take the default disk's region, endpoint, keys and path style if they set none of them |
| `STORAGE_S3_PREFIX` | string ending in `/` | none | A prefix for the disk's keys in the bucket (`uploads/`) |
| `STORAGE_GCS_BUCKET` | string | none (required with `gcs`) | The Cloud Storage bucket |
| `STORAGE_GCS_PREFIX` | string ending in `/` | none | A prefix for the disk's objects in the bucket (`uploads/`) |
| `STORAGE_GCS_CREDENTIALS_FILE` | path | none | A service account key file (JSON); without it or `STORAGE_GCS_CREDENTIALS`, Application Default Credentials (the service's account on Google Cloud, `GOOGLE_APPLICATION_CREDENTIALS`, gcloud). Named disks take the default disk's credentials and signer if they set none of them |
| `STORAGE_GCS_CREDENTIALS` | secret (JSON) | none | A service account key's JSON, instead of a file. Both settings take service account keys only: other credentials go through `GOOGLE_APPLICATION_CREDENTIALS` |
| `STORAGE_GCS_SIGNER` | email | the credentials' account | The service account that signs temporary URLs through the IAM API when the credentials have no private key (an error with a key, which signs for its own account) |
| `STORAGE_EMULATOR_HOST` | host:port | none | Read by the Cloud Storage client: talk to an emulator (fake-gcs-server) without credentials |

## Redis

Read by `redis.Connect` (module `drivers/redis`, also used by
`redis.CacheDriver()`, `redis.SessionDriver()`, `redis.QueueDriver()` and
`redis.PubSubDriver()`) into `redis.Config`.

| Key | Type | Default | Description |
|---|---|---|---|
| `REDIS_URL` | URL | `redis://127.0.0.1:6379/0` | The server, with its user, password and database: `redis://:secret@cache.internal:6379/2`; `rediss://` for TLS. Options go in the query string (`?dial_timeout=3s`) |

The server is pinged when the app boots, so the app and commands that
boot it fail fast when Redis is unreachable.

## Authentication

Read by `auth.New` (or `auth.LoadConfig`) into `auth.Config`.

| Key | Type | Default | Description |
|---|---|---|---|
| `AUTH_LOGIN_URL` | path | `/login` | Where `Require` sends guests asking for a page |
| `AUTH_HOME_URL` | path | `/` (`auth.WithDefaultHomeURL` sets another; `make:auth`'s is `/dashboard`) | The page for logged-in users: where logging in or registering leads when there's no page they asked for, and where `Guest` sends them |
| `AUTH_REMEMBER_TTL` | duration | `720h` | How long "remember me" lasts |
| `AUTH_THROTTLE` | int | `5` | Login attempts allowed per minute for one login, or one account, from one IP address (cleared by a success) |
| `AUTH_THROTTLE_IP` | int | `50` | Failed logins allowed per minute from one IP address (IPv6: its /64), whatever the login |
| `AUTH_RESET_TTL` | duration | `60m` | How long a password-reset token works |
| `AUTH_VERIFY_TTL` | duration | `24h` | How long an email-verification token works |
| `AUTH_REVERT_TTL` | duration | `168h` | How long the link that undoes a change of email address works |
| `AUTH_CHALLENGE_URL` | path | `/two-factor-challenge` | Where a login waiting for a two-factor code asks for it (social login sends users there) |
| `AUTH_TWO_FACTOR_URL` | path | `/two-factor` | Where users turn two-factor authentication on and off (the admin links there) |
| `AUTH_SETTINGS_URL` | path | `/settings` | The account settings page (`make:auth`'s); the admin links the user's name to it when the app has it |
| `AUTH_CONFIRM_URL` | path | `/confirm-password` | Where `RequireConfirmed` sends users to confirm their password |
| `AUTH_CONFIRM_TTL` | duration | `15m` | How long a confirmed password holds |
| `AUTH_CLIENT_URL` | URL | none | The client app of an API (`https://app.example.com`: http or https, no query): where emailed links lead (`Auth.ClientLink`); `make:auth` in an API project sets it, and its `setupAuth` refuses to boot without it in production and staging |

The remember-me cookie is `HttpOnly`, `SameSite=Lax` and Secure like the
session cookie; a Secure one is named `__Host-anetos_remember`.

## Audit log

Read by `audit.New` into `audit.Config`. See
[Keep an audit log](https://docs.anetos.dev/guides/audit-log/index.md).

| Key | Type | Default | Description |
|---|---|---|---|
| `AUDIT_IP` | `none`, `masked`, `full` | `none` | Whether entries keep the client's IP address: not at all, masked (IPv4 to its /24, IPv6 to its /48), or whole |
| `AUDIT_BULK_MAX_VALUES` | int | `10000` | How many rows' values a bulk entry keeps (every row's key is kept), set when a model is tracked |
| `AUDIT_RETENTION_DAYS` | int | `0` | How long `audit:prune` and `audit.Prune` keep entries; 0 keeps them forever |

## Admin

Read by `admin.New` into `admin.Config` (module `anetos.dev/anetos/admin`).
See [Add an admin panel](https://docs.anetos.dev/guides/admin/index.md).

| Key | Type | Default | Description |
|---|---|---|---|
| `ADMIN_PATH` | string | `/admin` | Where the admin is mounted; starts with `/`. With `ADMIN_HOST`, the admin is at that host's root unless this is set; `/` needs `ADMIN_HOST` |
| `ADMIN_HOST` | string | empty | A host the admin answers on alone (`admin.example.com`, on any port; a port given here goes into its URLs); empty for every host |
| `ADMIN_TITLE` | string | `APP_NAME` | The admin's name in its pages (overrides `admin.WithDefaultTitle`) |
| `ADMIN_PER_PAGE` | int | `25` | How many records a list shows, 1 to 500 (a resource's `PerPage` overrides it) |
| `ADMIN_CONFIRM` | bool | `true` | Ask for the password again (`AUTH_CONFIRM_TTL`) before dangerous actions: deleting, disabling, roles and permissions, impersonating a user, forgetting every failed job, actions marked `Danger` |
| `ADMIN_TWO_FACTOR` | `optional`, `required` | `optional` | `required` lets in only users with two-factor authentication on; the others are told to turn it on (`AUTH_TWO_FACTOR_URL`) |
| `ADMIN_ALLOW_IPS` | list | empty | Addresses or networks (`10.0.0.0/8`), comma-separated, the admin answers; others get 404. The client's address is read behind trusted proxies only (`HTTP_TRUSTED_PROXIES`). Empty for every address |

## Social login

Read by `social.New` and `social.Configured`, for each provider name
(`GOOGLE`, `GITHUB`, or the upper-cased name given to `social.OIDC`, with
`-` as `_`).

| Key | Type | Default | Description |
|---|---|---|---|
| `SOCIAL_<NAME>_CLIENT_ID` | string | empty | The client ID of the app registered with the provider |
| `SOCIAL_<NAME>_CLIENT_SECRET` | string | empty | Its client secret |

Callback URLs are `APP_URL` followed by `/auth/<name>/callback`
(`social.WithCallbackPath` changes the path).


## Plugins

Each plugin's settings start with its name in capitals (`STRIPE_…`),
and are read by `ext.Load` into the plugin's own settings struct. `go
run . plugin:env` prints them with their defaults; `anetos add` adds
them to `.env.example`. Missing or invalid ones stop the app from
booting, with an error naming them. See [Use plugins](https://docs.anetos.dev/guides/plugins/index.md).

### `postmark`

Read by the plugin of `plugins/postmark` (its mail transport reads
`MAIL_POSTMARK_*`: [Mail](https://docs.anetos.dev/reference/configuration/index.md#mail)).

| Key | Type | Default | Description |
|---|---|---|---|
| `POSTMARK_WEBHOOK_USER` | string | empty | The user name of the webhook's basic auth, set in the webhook's URL in Postmark (`https://USER:PASSWORD@example.com/postmark/webhook`). Without it or the password, the webhook refuses every request (401) |
| `POSTMARK_WEBHOOK_PASSWORD` | secret | empty | The webhook's password |


# Web

Source: https://docs.anetos.dev/reference/web/

- [Request binding reference](https://docs.anetos.dev/reference/binding/index.md): Rules used by `web.H` to fill a handler's input struct.
- [Views, sessions and forms reference](https://docs.anetos.dev/reference/views/index.md): The APIs of packages `view`, `session` and `encryption`, and the HTML helpers of package `web`. See [Render HTML with templ](https://docs.anetos.dev/guides/views/index.md), [Sessions and flash messages](https://docs.anetos.dev/guides/sessions/index.md) and [Handle HTML forms](https://docs.anetos.dev/guides/forms/index.md) for walkthroughs. The components of a project's `views/ui` are in the [UI components reference](https://docs.anetos.dev/reference/ui/index.md).
- [Validation rules reference](https://docs.anetos.dev/reference/validation-rules/index.md): Rules for the `validate` struct tag, used by `validate.Struct` and `web.H`. See the [validation guide](https://docs.anetos.dev/guides/validation/index.md) for how to use them.
- [Translation file formats](https://docs.anetos.dev/reference/i18n-formats/index.md): The `format` and `relative` sections of a catalog, which `i18n.Date`, `Time`, `DateTime`, `Format`, `Currency`, `Ago`, `Duration` and `LanguageName` use, and the date pattern fields. The framework's English values are in [`i18n/locales/en.yaml`](https://github.com/anetos-dev/anetos/blob/main/i18n/locales/en.yaml); a language's come from `anetos locale:add` ([Numbers, dates and languages](https://docs.anetos.dev/guides/formatting/index.md)). A key a locale lacks comes from its parents, then English (the app's `en` catalogs, then the framework's), never from a fallback locale in another language.
- [OpenAPI reference](https://docs.anetos.dev/reference/openapi/index.md): Package `web/openapi` and what it writes. How to use it: [Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md).
- [UI components reference](https://docs.anetos.dev/reference/ui/index.md): The components of `views/ui`, the package `anetos new` writes into a web project, which the layout and the pages of `make:crud` and `make:auth` call. The package is your app's: this page describes it as `anetos new` writes it. See [Style your app](https://docs.anetos.dev/guides/styling/index.md) for changing it.


# Request binding reference

Source: https://docs.anetos.dev/reference/binding/

Rules used by `web.H` to fill a handler's input struct.

## Tags

| Tag | Source | Notes |
|---|---|---|
| `json:"name"` | JSON body | Standard `encoding/json` rules. Also the form field name when no `form` tag is present, if the type can come from a form value (structs, maps and `json.RawMessage` stay JSON-only) |
| `form:"name"` | Form body (`application/x-www-form-urlencoded`, `multipart/form-data`) | Query-string values are **not** read as form values |
| `query:"name"` | URL query | `[]T` receives every value of a repeated parameter |
| `path:"name"` | Path wildcard `{name}` or `{name...}` | Can't be a slice |
| `header:"Name"` | Request header | `[]T` receives every value |
| `form:"-"`, `query:"-"`, … | | Not bound from that source. `form:"-"` does **not** stop JSON; use `json:"-"` for that |

A field with a `path`, `query` or `header` tag (and no `form` tag) is
**never** set from the body. File fields are never set from JSON.

> **Warning:** Like any JSON binding, every exported field without
> `json:"-"` can be set by the client. Keep input structs to the fields a
> client may send (don't bind straight into database models with an
> `IsAdmin` field).

Embedded structs without tags are flattened, so a shared `Pagination`
struct can be embedded in many inputs. Embed them **by value**: an embedded
*pointer* whose struct has `path`, `query`, `header` or `form` tags is
rejected at startup, because JSON decoding could fill it from the body.

## Order

1. Body (JSON or form). Skipped for `GET` and `HEAD` requests and when the
   struct has no body fields. A JSON body must be a single value; trailing
   data is a 400.
2. Query, header and path values, overwriting the corresponding fields
   (also for a field tagged with both `form` and `path`: the path wins).
3. The `validate` tag rules ([rules reference](https://docs.anetos.dev/reference/validation-rules/index.md)); failures
   stop here with a 422.
4. `Validate(ctx context.Context) error`, if the input type implements it.

## Field types

| Go type | Accepted text |
|---|---|
| `string` | Anything |
| `bool` | `true`/`false`, `1`/`0`, `t`/`f`, `yes`/`no`, `on`/`off` (checkboxes), any case |
| `int…`, `uint…`, `float…` | Decimal numbers within range |
| `time.Duration` | Go durations: `30s`, `5m` |
| `time.Time`, `anetos.Date`, `netip.Addr`, any `encoding.TextUnmarshaler` | Whatever `UnmarshalText` accepts (RFC 3339 for `time.Time`, `2026-10-03` for `anetos.Date`, as `<input type="date">` sends; empty is the zero `Date`) |
| `*T` of the above | Set only when a value is present |
| `[]T` of the above | Repeated query/header/form values |
| `*multipart.FileHeader`, `[]*multipart.FileHeader` | Uploaded files (`form` tag only) |

JSON bodies use `encoding/json`'s own conversions for `json` fields.

Empty form and query values (`age=`) count as absent for non-string fields,
so optional inputs stay unset instead of failing to parse.

## Error statuses

| Situation | Status |
|---|---|
| Value can't be converted (`page=abc`), JSON type mismatch | 400, with `errors` per field: the catalog's `binding.<kind>` message in the request's language (`binding.integer`: "must be an integer"; also `bool`, `number`, `date`, `time`, `duration`, `string`, `list`, `object`, `value`) |
| Malformed JSON or form | 400 |
| Content type other than JSON or form, with a body | 415 |
| Body larger than `HTTP_MAX_BODY` | 413 |
| A `validate` tag rule fails | 422, with `errors` per field |
| `Validate` returns `validate.Fail(…)` or a `*validate.Errors` | 422, with `errors` per field |
| `Validate` returns a `*web.HTTPError` or an error with `HTTPStatus() int` | That status |
| `Validate` returns any other error | Handled like a handler error: 500 without details (503 for deadlines; nothing sent if the client left) |

## Startup checks

`web.H` panics when it is called (at route registration) if the input type
is not a struct, a tag is empty (`query:""`), a field type is unsupported,
a `path` field is a slice, a file field lacks a `form` tag, an embedded
pointer struct has source tags, or a `validate` tag is invalid (see the
[rules reference](https://docs.anetos.dev/reference/validation-rules/index.md)).


# Views, sessions and forms reference

Source: https://docs.anetos.dev/reference/views/

The APIs of packages `view`, `session` and `encryption`, and the HTML
helpers of package `web`. See [Render HTML with templ](https://docs.anetos.dev/guides/views/index.md),
[Sessions and flash messages](https://docs.anetos.dev/guides/sessions/index.md) and
[Handle HTML forms](https://docs.anetos.dev/guides/forms/index.md) for walkthroughs. The components
of a project's `views/ui` are in the [UI components reference](https://docs.anetos.dev/reference/ui/index.md).

## Rendering (`web`)

| API | Does |
|---|---|
| `c.Render(status, component)` | Renders a component (templ or `view.Component`) into a buffer and writes it as `text/html; charset=utf-8`; a render error becomes an error response |
| `web.Render(component)` | Responder rendering the component with 200 |
| `web.URL(ctx, name, args...)` | `(string, error)`: path of a named route, from any request context (use in components); a trailing `url.Values` argument becomes the query string |
| `web.MustURL(ctx, name, args...)` | The path of `web.URL` alone, for a component's string argument (`@ui.LinkButton(web.MustURL(ctx, "posts.edit", post.ID), ui.Secondary)`); panics on an unknown route name or arguments the route doesn't take, which the router answers with a 500 |
| `web.RouteIs(ctx, names...)` | Whether the request's route has one of the names; `"issues.*"` matches the names starting with `issues.`. False outside a request or for an unnamed route. The layout of `anetos new` marks the current page's link with it |
| `web.PageURL(ctx, page)` | A relative link (`?…&page=N`) to page N of the current list, keeping the request's other query parameters as written; `?page=N` outside a request |
| `c.IsHTMX()` | Whether `HX-Request: true`; adds `Vary: HX-Request` |
| `c.HTMX()` | `web.HTMX`: `Request`, `Boosted`, `HistoryRestore`, `Target`, `Trigger`, `TriggerName`, `CurrentURL`; adds `Vary: HX-Request` |
| `c.Back()`, `web.Back()` | 303 to the `Referer` if it is on this site, else `/` |
| `c.Session()` | The request's `*session.Session`; panics without the session middleware |
| `web.WriteError(w, r, err)` | Sends err through the router's error handler, for middleware |

## Form protection (`web`)

| API | Does |
|---|---|
| `web.CSRF(opts...)` | Middleware: for every method but GET, HEAD, OPTIONS and TRACE, rejects cross-site requests (`web.ErrCrossOrigin`, 403) and requires the session token from `_token` or `X-CSRF-Token` (`web.ErrCSRF`, 403). Needs the session middleware first |
| `web.WithTrustedOrigins(origins...)` | CSRF option: allow these origins (`https://admin.example.com`) |
| `web.MethodOverride` | Global middleware: a POST with `_method` of PUT, PATCH or DELETE (in a URL-encoded body of at most 10 MB, which is parsed into `r.PostForm` and restored, or in the query string) is routed with that method |

Validation failures (422, or 400 with field errors) of a non-GET request
from a browser (a navigation or `Accept: text/html`; not htmx unless
boosted), on a route with a session, are redirected back to the `Referer`
by `web.DefaultErrorHandler` with the errors and `r.PostForm` flashed.
Form posts key errors by `form` name where it differs from the `json` name.

## View helpers (`view`)

| Helper | Returns |
|---|---|
| `view.CSRFField(ctx)` | Component: `<input type="hidden" name="_token" value="…">`; render error `view.ErrNoSession` without a session |
| `view.CSRFToken(ctx)` | A token for the `X-CSRF-Token` header (`""` without a session) |
| `view.MethodField(method)` | Component: `<input type="hidden" name="_method" value="PUT">`; PUT, PATCH or DELETE |
| `view.Errors(ctx)` | `*validate.Errors` flashed by the previous request (never nil): `Has`, `Get`, `Keys`, `Len` |
| `view.Old(ctx, field, fallback...)` | The value submitted for field by the previous request, else the fallback or `""` |
| `view.OldChecked(ctx, field, fallback)` | For a checkbox: after a post that redirected back, whether field was sent (and not `0`, `false`, `off`); else fallback |
| `view.Flash(ctx, key)` | The flashed string under key, or `""` |
| `view.String(ctx, component)` | The rendered HTML, for tests and emails |
| `view.Template(t, name, data)` | An `html/template` template as a component (without the request context: pass what it needs in data) |
| `view.ComponentFunc` | A function as a component |

## Static files (`view.Assets`)

| API | Does |
|---|---|
| `view.NewAssets(prefix, fsys...)` | Hashes every file (first file system wins; dot files skipped) |
| `a.URL(name)` | `prefix/name?v=<hash>`; no hash for a missing file |
| `a.Has(name)` | Whether the file exists |
| `a` as `http.Handler` | GET/HEAD; `Cache-Control: public, max-age=31536000, immutable` with the current hash, else `no-cache`; `ETag`. A text file of 1 KiB or more (`text/*` such as CSS, JavaScript, JSON, SVG, XML, wasm) is gzipped once, the first time it's requested, and served gzipped to a client that accepts it (`Content-Encoding: gzip`, `Vary: Accept-Encoding`, its own `ETag`), unless gzip saves less than a tenth |
| `htmx.FS`, `htmx.Version` | The bundled `htmx.min.js` (package `view/htmx`) |

## Sessions (`session`)

| API | Does |
|---|---|
| `session.New(app, drivers...)` | Manager from `SESSION_*` and `APP_KEY` ([settings](https://docs.anetos.dev/reference/configuration/index.md#sessions)); `SESSION_DRIVER` picks cookie, database or a passed driver (`redis.SessionDriver()`) |
| `session.Migrations(table)` | The database driver's table, for `migrate.New` |
| `session.NewManager(cfg, enc, opts...)` | Manager from a `session.Config` and an `*encryption.Encrypter`; `session.WithLogger`, `session.WithStore(store, prefix)` (any `cache.Store`) |
| `m.Middleware` | Loads the session into the request context and saves it when the response starts; adds `Cache-Control: private` (if unset) and `Vary: Cookie` for requests with a session. Does nothing if the same manager already runs for the request |
| `m.Use(mw...)` | Middleware that run inside `m.Middleware`, wherever it runs (every group with sessions), after the session is loaded and before the group's other middleware, in order; for routes registered before and after. Call it at setup. `make:auth`'s `setupAuth` calls `sessions.Use(a.Middleware)`, so every page knows the logged-in user |
| `m.CookieName()` | `SESSION_COOKIE`, with the `__Host-` prefix when Secure, without Domain, with Path `/` |
| `session.From(ctx)` | The session, or nil |
| `session.NewSession()`, `session.WithSession(ctx, s)` | A session for tests |
| `s.Put(key, v)`, `s.Get(key, &dst)`, `session.Value[T](s, key)`, `s.GetString(key)` | Store (as JSON) and read values |
| `s.Has`, `s.Delete`, `s.Pull`, `s.Clear` | Check, remove, read-and-remove, remove all |
| `s.Flash(key, v)`, `s.Keep(keys...)`, `s.Reflash()` | Values for the next request only |
| `s.Regenerate()`, `s.Invalidate()` | New ID and token, restarting the maximum lifetime (login); remove everything (logout, in this browser only) |
| `s.Token()`, `s.VerifyToken(t)`, `s.RegenerateToken()` | Masked CSRF token |
| `s.FlashErrors(...)`, `s.Errors()`, `s.FlashInput(values)`, `s.OldInput()`, `s.Old(field)` | Form errors and input for the next request; `FlashInput` leaves out `_method` and fields whose name contains `password`, `secret` or `token` |
| `s.ID()` | Random session ID |

`Put` panics for values `encoding/json` can't encode. Session methods are
safe for concurrent use.

## Encryption (`encryption`)

| API | Does |
|---|---|
| `encryption.New(app)` | Encrypter from `APP_KEY` and `APP_PREVIOUS_KEYS`; the error for a missing key suggests one |
| `encryption.NewEncrypter(current, previous...)` | Encrypter from 32-byte keys |
| `e.Encrypt(plain, context)`, `e.Decrypt(ct, context)` | AES-256-GCM with a per-message key (HKDF-SHA256, random salt); context is authenticated. `encryption.ErrInvalid` for tampered, foreign-context or unknown-key messages |
| `e.EncryptString`, `e.DecryptString` | Same, as URL-safe base64 |
| `encryption.GenerateKey()`, `encryption.ParseKey(s)` | `base64:…` keys |
| `go tool anetos key:generate` | Sets a new `APP_KEY` in `.env` (`--show` prints one) |


# Validation rules reference

Source: https://docs.anetos.dev/reference/validation-rules/

Rules for the `validate` struct tag, used by `validate.Struct` and `web.H`.
See the [validation guide](https://docs.anetos.dev/guides/validation/index.md) for how to use them.

## Syntax

```go
// illustrative
Name  string `json:"name" validate:"required|max:100"`
Role  string `json:"role" validate:"in:reader,editor"`
Skip  Inner  `json:"skip" validate:"-"`
```

- Rules are separated by `|` and run left to right; the first failure is
  the field's message.
- Parameters follow `:` and are separated by commas. Spaces around rules and
  parameters are ignored; parameters can't contain `|` or `,`.
- A rule that names another field (`required_if:plan,team`, `same:email`)
  accepts its Go name or its request key. It must be a field of the same
  struct (including fields promoted from embedded structs).
- Rule names are letters, digits and underscores. A few rules other
  validators have that aren't needed here (`nullable`, `sometimes`,
  `bail`, `string`, …) give a startup error explaining what to do
  instead.
- `validate:"-"` skips the field and anything nested in it.
- Other tags: `label:"web site"` sets the name used in messages. The
  request key comes from `json`, then `form`, `query`, `path`, `header`, then
  the Go field name.
- Fields are resolved like `encoding/json`: embedded structs (or pointers to
  them) without a json name are flattened, a field shadowed by a shallower
  one with the same key is ignored, and a field inside a nil embedded
  pointer counts as empty. Startup errors: rules on an embedded struct
  itself, rules on a field `encoding/json` ignores as ambiguous (two
  embedded structs at the same depth providing the same name), and two
  fields with rules reporting under the same key (`path:"id"` and
  `json:"id"`).

**Empty fields.** Only the rules marked *implicit* run on empty fields; the
others pass. Empty means: nil pointer or interface, a string of only
whitespace, an empty slice or map, or a zero struct or array value (a zero
`time.Time`, `netip.Addr`, UUID or nested struct). Non-pointer numbers and
booleans are never empty. Struct-based numbers, like decimal types, count
as empty at zero; use a pointer if zero is a valid answer.

**Kinds.** Rules apply to kinds of field, following pointers:

| Kind | Go types |
|---|---|
| string | `string` and named string types |
| numeric | `int…`, `uint…`, `float…` |
| array | slices, arrays and maps, except types with an `UnmarshalText` method (UUIDs, `net.IP`), which are values |
| bool | `bool` |
| time | `time.Time` |
| file | `multipart.FileHeader` (usually `*multipart.FileHeader`) |

A rule on the wrong kind is a startup error. Rules marked *each* also accept
a slice of their kind and check every element; empty elements (nil, blank
strings) are skipped.

## Presence

| Rule | Applies to | Passes when | Default message |
|---|---|---|---|
| `required` | any, implicit | Not empty; for non-pointer numbers and booleans, not zero/`false` | The {label} field is required. |
| `required_if:field,v1,v2…` | any, implicit | `required`, but only when *field* equals one of the values | The {label} field is required when {0} is {1}. |
| `required_unless:field,v1,v2…` | any, implicit | `required`, unless *field* equals one of the values | The {label} field is required unless {0} is {1}. |
| `required_with:f1,f2…` | any, implicit | `required`, when any of the fields is not empty | The {label} field is required when {list} is present. |
| `required_without:f1,f2…` | any, implicit | `required`, when any of the fields is empty | The {label} field is required when {list} is not present. |
| `accepted` | string, numeric, bool; implicit | `true`, `1`, or a string `yes`, `on`, `1`, `true` (any case) | The {label} field must be accepted. |

`required_if` and `required_unless` compare against a string, number or
bool field: numbers compare by value, exactly (`3` matches `3.0`; large
integers are never rounded) and booleans accept
`true`/`false`/`1`/`0`. In their messages, `{0}` is the other field's label
and `{1}` the listed values; in `required_with`/`required_without`, `{list}`
is the other fields' labels.

## Size

| Rule | Applies to | Passes when |
|---|---|---|
| `min:n` | string, numeric, array | length / value / item count ≥ n |
| `max:n` | string, numeric, array | ≤ n |
| `size:n` | string, numeric, array | = n |
| `between:a,b` | string, numeric, array | a ≤ … ≤ b |

Strings are measured in characters (runes), not bytes. For strings and
arrays the parameters must be whole numbers; for numbers they can be
decimals, and integer fields are compared exactly. Messages depend on the kind, e.g. "must be at least 3
characters", "must be at least 3", "must have at least 3 items". For
uploads, `min`/`max` count files; use `max_size` for bytes.

## String formats

All of these apply to strings and are *each*.

| Rule | Passes when |
|---|---|
| `email` | A plain address like `name@example.com`: no display name, dotted domain. Non-ASCII letters allowed; quoted local parts and IP domains are not |
| `url` | An absolute `http` or `https` URL with a host |
| `url:https,ftp,…` | An absolute URL with one of these schemes. Other schemes (`javascript:`, `data:`) are never accepted by default, since URLs often end up in `href` attributes |
| `uuid` | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` in hex, any case |
| `alpha` | Letters only (any script) |
| `alpha_num` | Letters and digits |
| `alpha_dash` | Letters, digits, `-` and `_` |
| `ascii` | ASCII characters only |
| `numeric` | A decimal number, e.g. `-1.5`, `1e3` |
| `integer` | A base-10 integer |
| `lowercase` / `uppercase` | Has no upper-case / lower-case letters |
| `starts_with:a,b…` / `ends_with:a,b…` | Starts / ends with one of the values |
| `ip` / `ipv4` / `ipv6` | An IP address (of that version), without a zone like `%eth0` |
| `json` | Valid JSON |
| `date` | `YYYY-MM-DD` and a real date |
| `datetime` | RFC 3339, e.g. `2026-09-30T10:00:00Z` |

For typed values, prefer typed fields: an `int`, a `time.Time`, a
`netip.Addr` or any type with `UnmarshalText` is converted during binding,
and bad input is rejected there with a 400.

## Choice

| Rule | Applies to | Passes when | Default message |
|---|---|---|---|
| `in:a,b…` | string, numeric, bool; each | The value is one of the parameters (numbers by value; a fractional parameter on an integer field is a startup error) | The selected {label} is invalid. |
| `not_in:a,b…` | string, numeric, bool; each | The value is none of them | The selected {label} is invalid. |
| `distinct` | slices and arrays whose elements contain no interfaces, slices, maps or funcs | No two elements are equal | The {label} field has a duplicate value. |

## Comparison

| Rule | Applies to | Passes when |
|---|---|---|
| `same:field` | any | Equal to *field* (same type required) |
| `different:field` | any | Not equal to *field* |
| `confirmed` | any | Equal to the field named `<Name>Confirmation` or keyed `<key>_confirmation` |
| `after:now` / `after:field` | `time.Time`, `anetos.Date` | Later than now / than *field* |
| `after_or_equal:…`, `before:…`, `before_or_equal:…` | `time.Time`, `anetos.Date` | As named |

`now` is the app's clock (`anetos.Now`); for an `anetos.Date` it is today
in the app's zone (`APP_TIMEZONE`). *field* must have the same type: a
date compares with a date, a time with a time. If the other field of a
date comparison is empty, the rule passes; give that field its own
`required` rule.

## Files

For `*multipart.FileHeader` fields, and *each* for
`[]*multipart.FileHeader`.

| Rule | Passes when |
|---|---|
| `max_size:2MB` / `min_size:1KB` | Size within the limit. Units as in config: `B`, `KB`, `MB`, `GB` (powers of 1024) |
| `mimetypes:image/png,application/pdf` | The type **detected from the content** matches; `image/*` matches any detectable image type |
| `extensions:jpg,png,tar.gz` | The file name ends with one of the extensions (any case). The name comes from the client, so pair it with `mimetypes` or `image` |
| `image` | Detected as PNG, JPEG, GIF or WebP. SVG is not accepted, since it can contain scripts |

Content is detected from the first 512 bytes with
`net/http.DetectContentType`; the client's `Content-Type` is ignored. Only
types it can detect are accepted in `mimetypes` (others are a startup
error): `application/pdf`, `application/zip` (also Office files),
`application/x-gzip`, `application/x-rar-compressed`, `application/wasm`,
`application/ogg`, `application/postscript`,
`application/vnd.ms-fontobject`, `application/octet-stream` (unknown),
`audio/aiff`, `audio/midi`, `audio/mpeg`, `audio/wave`, `font/collection`,
`font/otf`, `font/ttf`, `font/woff`, `font/woff2`, `image/bmp`,
`image/gif`, `image/jpeg`, `image/png`, `image/webp`, `image/x-icon`,
`image/vnd.microsoft.icon`, `text/html`, `text/plain`, `text/xml`,
`video/avi`, `video/mp4`, `video/webm`. CSV and JSON files are
`text/plain`; SVG is `text/xml` or `text/plain`.

## Database rules

Registered by the `db` package (importing it is enough); they query the
database in the validation context, which in `web.H` is the request's.

| Rule | Passes when | Default message |
|---|---|---|
| `unique:table[,column[,exceptField[,idColumn]]]` | No row in *table* has this value in *column* (default: the field's key). With *exceptField*, the row whose *idColumn* (default `id`) equals that field's value is ignored, for edit forms | The {label} has already been taken. |
| `unique_without_trashed:table[,column[,exceptField[,idColumn]]]` | As `unique`, among the rows whose `deleted_at` is NULL: pair it with `migrate.Table.UniqueWithoutTrashed` (`unique_live` before v0.5, until v0.6) | The {label} has already been taken. |
| `exists:table[,column]` | A row in *table* has this value in *column* | The selected {label} is invalid. |

```go
// illustrative
type UpdateUser struct {
	ID    int64  `path:"id"` // from the URL: the body can't change it
	Email string `json:"email" validate:"required|email|unique:users,email,ID"`
	Owner int64  `json:"owner_id" validate:"required|exists:users,id"`
}
```

Take the *exceptField* from the path (or set it in code), never from a
body field: a client could otherwise name another user's ID and skip the
check.

`unique` and `exists` count soft-deleted rows, as a unique index would; `unique_without_trashed` doesn't. Without a database
in the context they fail with `db.ErrNoDB` (a 500). Like every custom rule,
they skip empty fields.

## Custom rules

```go
// illustrative
validate.Register("slug", "The {label} field must be a slug.", func(ctx context.Context, f validate.Field) (bool, error) {
	s, _ := f.Value.(string)
	return slugPattern.MatchString(s), nil
})
```

- Register from `init`, before routes are added. Names are ASCII letters,
  digits and underscores, and can't reuse a built-in or registered name
  (`Register` panics).
- Custom rules apply to any kind and skip empty fields.
- `f.Value` has pointers followed (nil for a nil pointer); `f.Params` holds
  the tag parameters; `f.Parent` is the struct holding the field.
- Returning an error aborts validation with that error (a 500 in `web.H`).

## Messages

Messages come from the translation catalogs (package `i18n`), in the
request's language: the framework's English ones unless a catalog defines
the key. See [Translations](https://docs.anetos.dev/guides/translations/index.md#6-translate-the-frameworks-messages).

| Key | Is |
|---|---|
| `validation.<rule>` | A rule's message: `validation.required`, `validation.email` |
| `validation.<rule>.string`, `.numeric`, `.array` | A size rule's message (`min`, `max`, `size`, `between`) for the field's kind |
| `validation.<name>` | A custom rule's message, instead of the one given to `Register` |
| `validation.custom` | A custom rule registered without a message |
| `validation.attributes.<key>` | A field's label in messages (`email: "email address"`); else the `label` tag (translated if a catalog has it as a key), else the key humanized |
| `validation.values.<parameter>` | A rule parameter shown in messages (`now`) |

Templates can use `{label}`, `{0}`, `{1}`, … for parameters and `{list}` for
all parameters joined with ", ". For rules that name other fields, the
arguments are those fields' labels. Override per struct with:

```go
// illustrative
func (SignUp) ValidationMessages() map[string]string {
	return map[string]string{"email.required": "…", "min": "…"}
}
```

Keys are `key.rule` (one field) or `rule` (every field of this struct, not
nested ones). A value that is a catalog key is translated. A size rule's override key is the rule name (`min`), whatever
the field's kind. A key naming an unknown rule, or a field and rule that
don't exist on this struct, is a startup error.

## Result

`validate.Struct` returns `nil`, a `*validate.Errors`, or an error from a
custom rule (or for structs nested more than 10,000 levels deep, the same
limit `encoding/json` has, which in practice means cyclic data). `*validate.Errors` offers `Has`, `Get`, `Keys` (in field order),
`Len`, `FieldErrors()` (a map copy), `Add` (keeps the first message per
field), `Err()` (a copy, or nil when empty) and JSON encoding as an object
in field order. `validate.Fail(field, message)` builds one with a single
message. It reports status 422 to `web`, which renders it as problem JSON
with an `errors` object or as the HTML error page.


# Translation file formats

Source: https://docs.anetos.dev/reference/i18n-formats/

The `format` and `relative` sections of a catalog, which `i18n.Date`,
`Time`, `DateTime`, `Format`, `Currency`, `Ago`, `Duration` and
`LanguageName` use, and the date pattern fields. The framework's English
values are in
[`i18n/locales/en.yaml`](https://github.com/anetos-dev/anetos/blob/main/i18n/locales/en.yaml); a language's come
from `anetos locale:add` ([Numbers, dates and languages](https://docs.anetos.dev/guides/formatting/index.md)).
A key a locale lacks comes from its parents, then English (the app's
`en` catalogs, then the framework's), never from a fallback locale in
another language.

## `format`

| Key | Value | English |
|---|---|---|
| `format.language` | The language's name in itself | `English` |
| `format.months` | 12 month names, January first, as in dates (`MMMM`) | `[January, …]` |
| `format.months_short` | 12 abbreviations (`MMM`) | `[Jan, …]` |
| `format.months_standalone` | Optional: 12 names on their own (`LLLL`), for languages whose month names change in a date (Russian `марта`, `март`) | — |
| `format.days` | 7 day names, Sunday first (`EEEE`) | `[Sunday, …]` |
| `format.days_short` | 7 abbreviations (`EEE`) | `[Sun, …]` |
| `format.periods` | Before and after noon (`a`) | `[AM, PM]` |
| `format.date.short` … `full` | Date patterns of the four styles | `M/d/yy`, `MMM d, y`, `MMMM d, y`, `EEEE, MMMM d, y` |
| `format.time.short` … `full` | Time patterns | `h:mm a`, `h:mm:ss a`, `h:mm:ss a z`, `h:mm:ss a zzzz` |
| `format.datetime.short` … `full` | How `DateTime` joins them: `{date}`, `{time}` | `{date}, {time}`; `{date} at {time}` (long, full) |
| `format.currency` | Where `Currency` puts `{symbol}` and `{amount}` (`{code}`: the ISO code) | `{symbol}{amount}` |
| `format.numbering` | Optional: a CLDR numbering system for numbers and dates, instead of the language's (`latn` for 0–9) | — |

A symbol of letters next to the amount gets a no-break space
(`BDT 1,250.00`), as CLDR does; a negative amount gets a minus sign in
front.

## Date pattern fields

Patterns follow [CLDR's date format patterns](https://unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table),
the subset below. Numbers use the locale's digits.

| Field | Shows | Example (Friday 16 January 2026, 02:04:05 in Dhaka) |
|---|---|---|
| `y`, `yyyy` | Year | `2026` |
| `yy` | Two-digit year | `26` |
| `M`, `MM` | Month number | `1`, `01` |
| `MMM`, `MMMM` | Month name, short and full | `Jan`, `January` |
| `MMMMM` | Its first letter | `J` |
| `LLL`, `LLLL`, `LLLLL` | The same, standalone forms | `Jan`, `January`, `J` |
| `d`, `dd` | Day of the month | `16`, `16` |
| `E`, `EE`, `EEE` | Short day name | `Fri` |
| `EEEE` | Day name | `Friday` |
| `EEEEE` | Its first letter | `F` |
| `a` | Period | `AM` |
| `h`, `hh` | Hour, 1–12 | `2`, `02` |
| `H`, `HH` | Hour, 0–23 | `2`, `02` |
| `m`, `mm` | Minute | `4`, `04` |
| `s`, `ss` | Second | `5`, `05` |
| `z` | Zone abbreviation | `+06` |
| `zzzz` | Zone's IANA name (the abbreviation for a zone without one) | `Asia/Dhaka` |
| `'text'` | Literal text | `'at'` |
| `''` | A single quote, in quoted text too | `h 'o''clock'` → `2 o'clock` |

Other letters are shown as they are: `Y` (week year), `G`, `Q`, `w`, `k`
and the rest of CLDR's fields aren't supported.

## `relative`

| Key | Value | English |
|---|---|---|
| `relative.now` | Under 45 seconds | `just now` |
| `relative.past` | A past time; `{time}` is the duration | `{time} ago` |
| `relative.future` | A future time | `in {time}` |
| `relative.units.second` … `year` | Plural messages for `{count}` units: `second`, `minute`, `hour`, `day`, `month`, `year` | `{one: "{count} hour", other: "{count} hours"}` |

`Duration` shows the largest unit, rounded to the nearest: from 45
seconds a minute, from 45 minutes an hour, from 22 hours a day, from 26
days a month (30 days), from 345 days a year (365 days). `DurationUp`
rounds up, for waits. `Ago` of a zero time is "".

## Limits

Numbers follow the CLDR data in `golang.org/x/text`, which lags CLDR
in places: Spanish groups four-digit numbers (`1.234`, CLDR `1234`),
French groups with a no-break space (U+00A0, CLDR U+202F), and the
`many` plural category of French and Spanish (`1 000 000 de jours`)
isn't used.


# OpenAPI reference

Source: https://docs.anetos.dev/reference/openapi/

Package `web/openapi` and what it writes. How to use it:
[Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md).

## API

| Name | Does |
|---|---|
| `openapi.Spec(r, cfg)` | The OpenAPI 3.1.0 document of `r`'s typed routes, as indented JSON (the same routes and `Config` give the same bytes), and warnings about what it left out or couldn't describe |
| `openapi.Check(r, cfg)` | An error unless `cfg.File` holds `Spec`'s document (Windows line ends allowed); the error names the first line that differs and says to run `go run . openapi`. Also an error when a route under `cfg.Prefix` is one the document leaves out (not a typed handler, or every method) |
| `openapi.Register(app, srv, cfg)` | Adds the `openapi` command, and serves the document at `cfg.Path` if set (built on the first request). Call it after adding the routes. An error without `cfg.Title` |
| `web.Documented(h, web.MiddlewareDoc{…})` | The handler a middleware returns, with what the middleware asks for and may answer (`Security`, `Scopes`, `Responses`), which the routes it wraps report; `Name` and `Detail` name it in `route:list --json` |
| `web.RouteInfo.Input`, `.Output`, `.Status` | A typed route's input and result types and its `Status` (0 unless set) |
| `web.RouteInfo.Handler` | A typed route's function, without its package path: `handlers.Bookmarks.Index` |
| `web.RouteInfo.Middleware` | A `MiddlewareDoc` for each of the route's middleware, outermost first (read-only): its `Name` (the function that makes it, as Go code names it, unless `Documented` gives one) and, for the documented ones, what they said |
| `r.GlobalMiddleware()` | The same for the router's global middleware (`UseGlobal`) |
| `auth.RequireAbilities(abilities…)` | Middleware: a token needs the abilities (403), a guest is refused (401, `WWW-Authenticate: Bearer`); documents them as the bearer token's scopes. Put it after `Require` |

## Config

| Field | Default | Meaning |
|---|---|---|
| `Title` | (required) | `info.title` |
| `Version` | `1.0.0` | `info.version`: the API's version, not Anetos's |
| `Description` | | `info.description`, Markdown |
| `Prefix` | every typed route | Only the routes at or below this path (a trailing `/` is ignored) |
| `File` | `openapi.json` | Where the command writes and `Check` reads, relative to the working directory |
| `Path` | not served | The route serving the document; it isn't described in it |
| `Servers` | `/` | `servers`' URLs |
| `SecuritySchemes` | `bearer` only | Schemes middleware may name: `openapi.SecurityScheme{Type, Scheme, BearerFormat, In, Name, Description}`, `Type` `http` or `apiKey` |

## The command

`openapi [--check] [--out=FILE]`, added by `openapi.Register`.

| Flag | Default | Meaning |
|---|---|---|
| `--out` | `Config.File` | The file to write or check; `-` writes to the standard output |
| `--check` | `false` | Exit 1 if the file isn't the document of the routes, instead of writing it |

It prints a warning per route it leaves out or can't fully describe.
It doesn't boot the app, so it needs no database.

## Operations

| What | From |
|---|---|
| Which routes | Typed routes (`web.H`, registered as it returns them) at or below `Prefix`; other routes and any-method routes are left out with a warning |
| `operationId` | The route's name; else the handler's (`Bookmarks.Index`, a function's `welcome`); else the method and path. Unique (a number is added) |
| `tags` | The handler's receiver type (`Bookmarks`); none for functions |
| `parameters` | The path's wildcards (`{path...}` is `{path}`), then the input's `query` and `header` fields |
| `requestBody` | The input's other fields as `application/json`, or `multipart/form-data` (the fields a form binds, by their form names, and the files) when it has files; none for GET and HEAD. Required when a field is |
| Success | The route's `Status` (200 by default) with the result's schema; `web.Empty`, 204 and 205 without content; a `web.Responder` result: `2XX` without content, with a warning |
| Errors | 400 (`InvalidValues`) when there are values to bind; 422 (`InvalidInput`) with `validate` rules or a `Validate` method; each documented middleware's statuses; `default` (`Error`). All `application/problem+json`, the `Problem` schema |
| `security` | The documented middleware's schemes, with their scopes merged; `[]` on the others when some operations have any |

Two routes OpenAPI can't tell apart (`GET /a/{id}` and `DELETE
/a/{key}`; one method and path on two hosts) are an error.

## Schemas

Types are described as `encoding/json` writes (results) and reads
(bodies) them: names from `json` tags, embedded structs' fields
promoted, `json:",string"` numbers as strings.

| Go | Schema |
|---|---|
| `string`, `bool` | `string`, `boolean` |
| `int`, `int8`, `int16` / `int32`, `int64` | `integer` / with `format` `int32`, `int64` |
| unsigned integers | `integer`, `minimum` 0 |
| `float32`, `float64` | `number`, `format` `float`, `double` |
| `time.Time`, `anetos.Date` | `string`, `format` `date-time`, `date`; in a body, an optional `anetos.Date` (not a pointer) is `anyOf` that and an empty string, which binds as no date |
| `[]byte` | `string`, `contentEncoding` `base64` |
| `*multipart.FileHeader` | `string`, `format` `binary` |
| `time.Duration` parameter | `string` (`30s`, as the binding reads it); in a body, an `integer` (nanoseconds) |
| slices, arrays | `array` with `items` |
| maps | `object` with `additionalProperties` |
| a pointer | its type, nullable (`["string", "null"]`; `anyOf` a `$ref` and `null`) |
| a named struct | a component, `$ref: "#/components/schemas/Name"` |
| an anonymous struct | an inline `object` |
| an `encoding.TextMarshaler` | `string` |
| an interface, `json.RawMessage`, a `json.Marshaler` | any value (`{}`); a `json.Marshaler` with a warning |

| In a result | In a body |
|---|---|
| Every field without `omitempty` or `omitzero` is `required`, except those promoted through an embedded pointer | `required` comes from the `validate` rule |
| Slices and maps aren't nullable: answer empty ones, not nil | `path`, `query` and `header` fields aren't in the body |

**Components' names:** the Go type's (`BookmarkResponse`); a generic
type's with its type arguments' names (`db.Page[BookmarkResponse]` is
`PageBookmarkResponse`); the package's name first when two types share
a name (`handlers.Order`); `…Input` for a type's body schema when it's
a result too; a number after a name still taken. `Problem` is the
problem details'.

## Validation rules

What a `validate` tag says that JSON Schema can, in bodies and
parameters:

| Rule | Schema |
|---|---|
| `required` | `required`; a string `minLength` 1, an array `minItems` 1, a map `minProperties` 1; in a non-pointer field, a number `not: {const: 0}`, a bool `const: true` |
| `min`, `max`, `size`, `between` | `minLength`/`maxLength` (strings), `minimum`/`maximum` (numbers), `minItems`/`maxItems` (slices), `minProperties`/`maxProperties` (maps) |
| `in` | `enum` (with `null` for a pointer) |
| `email`, `url`, `uuid`, `date`, `datetime`, `ipv4`, `ipv6` | `format` `email`, `uri`, `uuid`, `date`, `date-time`, `ipv4`, `ipv6`; `url` also a `pattern` of its schemes (`http` and `https` unless it names others), as `uri` allows any |
| `distinct` | `uniqueItems` |
| others (`unique`, `confirmed`, `after`, custom rules…) | not shown; still checked |

A field that isn't `required` may be blank whatever its other rules (as
`validate` skips them): its schema is `anyOf` the constrained schema and
a blank one (`{"type": "string", "pattern": "^\\s*$"}`, an empty array
or map).

## Middleware

| Middleware | Documents |
|---|---|
| `auth.Auth.Require` | `bearer`; 401 |
| `auth.Auth.TokenMiddleware` | 401 (a bad token) |
| `auth.RequireAbilities(abilities…)` | `bearer` with the abilities as scopes; 401, 403 |
| `rbac.Require`, `rbac.RequireIn` | 401, 403 |
| `ratelimit.Middleware` | 429 |
| your own | `web.Documented(h, web.MiddlewareDoc{Security, Scopes, Responses})` |

Global middleware (`UseGlobal`) isn't seen.

## Warnings

| Warning | Means |
|---|---|
| `not a typed handler (web.H, registered as web.H returns it): left out` | A plain handler, or `web.H`'s handler wrapped in another function |
| `a route for every method isn't described` | `Handle("", …)` |
| `its result is a web.Responder…: described as any 2XX` | The handler chooses its status and body as it runs |
| `its result is an interface…: described as any value` | `any` or another interface type |
| `… has its own MarshalJSON: described as any value` | The type writes its own JSON |
| `… can't be written in JSON` | A channel, a function… |


# UI components reference

Source: https://docs.anetos.dev/reference/ui/

The components of `views/ui`, the package `anetos new` writes into a
web project, which the layout and the pages of `make:crud`
and `make:auth` call. The package is your app's: this page describes it
as `anetos new` writes it. See [Style your app](https://docs.anetos.dev/guides/styling/index.md)
for changing it.

Every component exists for every CSS framework, with the same name and arguments.
The tables show what the starter theme (`anetos`) writes;
[`none`](https://docs.anetos.dev/reference/ui/index.md#none-plain-html) writes the same elements without
classes, and [Pico, Bootstrap and Bulma](https://docs.anetos.dev/reference/ui/index.md#pico-bootstrap-and-bulma)
(and [Tailwind CSS](https://docs.anetos.dev/reference/ui/index.md#tailwind-css)) write their framework's markup.

```templ
// illustrative
@ui.Card("Profile") {
	@ui.Form(web.MustURL(ctx, "settings.profile"), "POST", nil) {
		@ui.Field("name", "Name", "As others see it") {
			@ui.Input("name", "", view.Old(ctx, "name", user.Name), templ.Attributes{"autocomplete": "name"})
		}
		@ui.Actions() {
			@ui.Button(ui.Primary, nil) {
				Save
			}
		}
	}
}
```

A component marked *children* takes content in `{ }`. An `attrs`
argument (`templ.Attributes`, or `nil`) adds attributes to the element,
such as `templ.Attributes{"autocomplete": "email"}` or htmx's
`hx-post`; it shouldn't repeat one the component writes.

## The page's shell

`views/ui/shell.templ`. The layout (`views/layout.templ`) puts these
together.

| Component | Children | Writes |
|---|---|---|
| `Head()` | | `<link rel="stylesheet">` to `app.css` (`public.Assets.URL`), for the layout's `<head>` |
| `Header(brand, home string)` | the `Nav` and `NavEnd` | `<header class="topbar">` with the app's name, `brand`, linking to `home` |
| `Nav(label string)` | `NavLink`s | `<nav class="nav">`, named `label` for screen readers (`aria-label`) |
| `NavLink(href, label string, current bool)` | | A link of the header; `aria-current="page"` when `current` |
| `NavEnd()` | `NavLink`s and `NavItem`s | `<div class="nav-end">`: the end of the header, for the account's links (`make:auth`'s `AccountMenu`) |
| `NavItem()` | a button, a form | An entry of a `Nav` or `NavEnd` that isn't a `NavLink`, such as the logout button. The starter theme writes the children alone; a framework wraps them as its menus need (`<li>`, `navbar-item`) |
| `Main()` | the page | `<main class="container">` |
| `Footer()` | its content | `<footer class="site-footer">` |
| `Flash(tone Tone)` | the message, and any buttons | `<div class="flash cluster …" role="status">` in the tone's color |

## A page's structure

`views/ui/page.templ`.

| Component | Children | Writes |
|---|---|---|
| `PageHeader(title, lead string)` | the page's actions | `<div class="page-header">`: the title in an `<h1>`, then `lead` in a paragraph when it isn't `""`, and the children at the end |
| `Narrow()` | content | `<div class="narrow">`: a column of a readable width (42rem), for forms and text |
| `Stack()` | content | `<div class="stack">`: its children one under the other, evenly spaced |
| `Cluster()` | content | `<div class="cluster">`: its children side by side, wrapping (buttons, a search field and its button) |
| `Card(title string)` | content | `<section class="card">`, with the title in an `<h2>` when it isn't `""` |
| `CardHeader(title string)` | the card's actions | `<div class="card-header">`: an `<h2>` with the children beside it, at the top of a `Card("")` |
| `AuthCard(title string)` | content | `<div class="card auth-card">`: a small centered card under an `<h1>`, as the login pages are |
| `Empty(text string)` | | `<p class="empty">`: what a list shows when it has nothing |
| `Note()` | text | `<p class="muted">`: secondary text |
| `SROnly(text string)` | | `<span class="sr-only">`: text for screen readers only, such as a column's heading |

## Forms

`views/ui/form.templ`. A control (`Input`, `Textarea`, `Select`,
`Checkbox`) is named after its field, which is its `id` too (two
controls of one name on a page would share an id: give one form's
field another name). Pass `view.Old(ctx, name, current)` as its value,
so it shows what was typed when validation failed.

| Component | Children | Writes |
|---|---|---|
| `Form(action, method string, attrs templ.Attributes)` | the fields | For `"POST"`: `<form method="post">` with the CSRF token (`view.CSRFField`). For `"PUT"`, `"PATCH"` or `"DELETE"`: the same, with the method in a `_method` field (`view.MethodField`). For `"GET"`: `<form method="get">`, without either. Upper or lower case |
| `InlineForm(action, method string, attrs templ.Attributes)` | the controls | `<form method="post" class="inline">` with the CSRF token, and `_method` for PUT, PATCH or DELETE: controls in a line, such as a hidden field and its button; `attrs` adds others (htmx's). It always posts |
| `Field(name, label, hint string)` | a control | `<div class="field">`: a `<label for={ name }>` (none when `label` is `""`), the control, the hint (`<p class="hint">`) when it isn't `""`, and the field's message (`FieldError`) |
| `Input(name, typ, value string, attrs templ.Attributes)` | | `<input>`, of type `typ` (none, so text, when `""`), with `value` unless it is `""` |
| `Textarea(name, value string, attrs templ.Attributes)` | | `<textarea>` holding `value` |
| `Select(name string, options []Option, value string, attrs templ.Attributes)` | | `<select>` with an `<option>` per `Option`, the one whose `Value` is `value` selected |
| `Checkbox(name, label string, checked bool, attrs templ.Attributes)` | | `<label class="check">` around a checkbox sending `1`, then `label`. It has its own label: wrap it in `Field(name, "", "")` for the field's message. Pass `view.OldChecked(ctx, name, current)` as `checked` |
| `FieldError(name string)` | | `<p class="error" id="name-error">` with the field's validation message, or nothing; the control is described by it (`aria-describedby`) |
| `Actions()` | buttons and links | `<div class="form-actions">`: a form's buttons, after its fields |
| `Button(variant Variant, attrs templ.Attributes, size ...Size)` | its text | `<button type="submit">`, with the variant's and sizes' classes |
| `LinkButton(href string, variant Variant, size ...Size)` | its text | `<a class="button …">`: a link that looks like a button |
| `PostButton(action, method string, variant Variant, size ...Size)` | its text | A `Button` in an `InlineForm` of its own: sends `method` (`"POST"`, or `"PUT"`, `"PATCH"`, `"DELETE"`) to `action` with the CSRF token, to delete something or log out |

## Lists and values

`views/ui/data.templ`.

| Component | Children | Writes |
|---|---|---|
| `Table()` | `<thead>` and `<tbody>` | `<table>` in a `<div class="table-wrap">`, which scrolls sideways when the table is too wide |
| `ActionsCell()` | buttons | `<td class="actions">`: a row's cell of buttons, at its end |
| `Details()` | `Detail`s | `<dl class="details">`: terms and their values, in two columns |
| `Detail(term string)` | the value | `<dt>` with `term`, then `<dd>` with the children |
| `Multiline(text string)` | | `<span class="prewrap">`: text shown with its line breaks |
| `Badge(tone Tone)` | its text | `<span class="badge …">`: a short label (a status, a count) in the tone's color |
| `Pagination(p Pages)` | | `<nav class="pagination">` named `p.Label`: a link to `p.Prev` (`rel="prev"`) unless it is `""`, `p.Status` unless it is `""`, and a link to `p.Next` (`rel="next"`) unless it is `""` |

## Variants and sizes

`Button`, `LinkButton` and `PostButton` take a variant (`ui.Variant`),
then any sizes (`ui.Size`), as Bootstrap and shadcn/ui name them:
`@ui.LinkButton(url, ui.Secondary, ui.Small)`.

| Constant | For | Classes (starter theme) |
|---|---|---|
| `ui.Primary` | The page's main action; the default (zero) variant | `button` on a link; none on a `<button>`, which looks primary as it is |
| `ui.Secondary` | Another action | `secondary` |
| `ui.Danger` | An action that deletes, or can't be undone | `danger` |
| `ui.Ghost` | A quiet action, as in the header | `ghost` |
| `ui.Small` (a size) | Smaller, as in a table's row | `small` |
| `ui.FullWidth` (a size) | As wide as its container | `full` |

## Tones

What a color means (`ui.Tone`), for `Badge` and `Flash`.

| Constant | Classes (starter theme) |
|---|---|
| `ui.Neutral` | none (gray) |
| `ui.Success` | `success` |
| `ui.Warning` | `warning` |
| `ui.Error` | `danger` (a `Flash`: `error`) |
| `ui.Info` | `info` |

## Types

In `views/ui/ui.go`, shared by every CSS framework.

| Type | Holds |
|---|---|
| `ui.Option` | An option of a `Select`: `Value` (sent), `Label` (shown) |
| `ui.Pages` | What `Pagination` shows: `Label` (the links' name for screen readers), `Status` (`"Page 2 of 5"`), `Prev` and `Next` (the URLs of the pages around it, `""` at the ends), `PrevLabel` and `NextLabel` (their links' text) |
| `ui.PagesOf(ctx, page, label, status, prev, next)` | The `Pages` of a `db.Page[T]`, with those texts: `Prev` when `page.HasPrev()` (the last page when the page is past it), `Next` when `page.HasNext()`, built with `web.PageURL`, so the links keep the query's other parameters (a search, a filter) |

```templ
// illustrative
if page.LastPage > 1 {
	@ui.Pagination(ui.PagesOf(ctx, page, "Pages", fmt.Sprintf("Page %d of %d", page.CurrentPage, page.LastPage), "Previous", "Next"))
}
```

## What reads the request

Some components read the request's context (`ctx`), so they need a page
rendered for a request (`c.Render`, `web.Render`):

| Component | Reads |
|---|---|
| `Form` (but GET), `InlineForm`, `PostButton` | The session's CSRF token (`view.CSRFField`): rendering fails with `view.ErrNoSession` on a route without the session middleware |
| `Field`, `FieldError` | The field's validation message (`view.Errors`) |
| `Input`, `Textarea`, `Select`, `Checkbox` | Whether their field failed validation: then `aria-invalid="true"`, which the theme shows with a red border, and `aria-describedby` naming the message |
| `ui.PagesOf` | The request's URL, for the page links (`web.PageURL`) |

The others write only their arguments. Arguments made with
`web.MustURL` need a request too: rendering a page outside one (with
`context.Background()` in a test) panics where `web.URL` returned an
error.

## Helpers for the components' arguments

These are the framework's, not `views/ui`'s; the
[views reference](https://docs.anetos.dev/reference/views/index.md) has the rest.

| Function | Does |
|---|---|
| `web.MustURL(ctx, name, args...)` | The path of a named route, as `web.URL`, for a component's string arguments (`ui.LinkButton(web.MustURL(ctx, "posts.edit", post.ID), ui.Secondary)`). A name or arguments the route doesn't take is a panic, which the router answers with a 500 page |
| `web.RouteIs(ctx, names...)` | Whether the request's route has one of the names, for `NavLink`'s `current` (the layout's `navLink` uses it) |
| `view.Old(ctx, field, fallback...)` | A control's value: what was typed, after a failed post, else the fallback |
| `view.OldChecked(ctx, field, fallback)` | A `Checkbox`'s `checked`, the same way |

## `none`: plain HTML

`anetos new --css=none` writes the same components, with plain HTML
and no classes. The differences:

| Component | With `none` |
|---|---|
| `Header`, `Footer` | No inner `<div class="container">` |
| `Main` | `<main>` without its class |
| `Field` | A `<br/>` after the label, so the control is under it |
| `Button`, `LinkButton`, `NavLink`, `Badge` | Followed by a space, so side by side they don't touch |
| `AuthCard` | A `<section>` with its `<h1>` |
| `Table` | The `<table>` alone, without the scrolling box |
| `Button`, `LinkButton`, `PostButton` | The variant and sizes change nothing |
| `Badge`, `Flash` | The tone changes nothing |
| `SROnly`, `Multiline` | An inline `style` hides the text visually, or keeps its line breaks (a Content-Security-Policy without `'unsafe-inline'` for styles blocks it: give them classes then) |

Its `app.css` holds only a comment, and there is no `classes.go`.

## Pico, Bootstrap and Bulma

`anetos new --css=pico`, `--css=bootstrap` and `--css=bulma` write the
same components in their framework's markup, its stylesheet (and
JavaScript) as released into `public/static/` with its license, and an
`app.css` for the rest:

| | `pico` (2.1.1) | `bootstrap` (5.3.8) | `bulma` (1.0.4) |
|---|---|---|---|
| `Head` | `pico.min.css`, `app.css` | `bootstrap.min.css`, `app.css`, `theme.js`, `bootstrap.bundle.min.js` | `bulma.min.css`, `app.css`, `nav.js` |
| `Header` | The links wrap on a small screen | `navbar`, with a menu button on a small screen | `navbar`, with a menu button on a small screen |
| `Nav`, `NavEnd`, `NavItem` | `<ul>`, each entry an `<li>` | `navbar-nav`, each entry a `nav-item` | `navbar-start`, `navbar-end`, `navbar-item` |
| `Card`, `AuthCard` | `<article>`, the title in its `<header>` | `card` | `box` |
| `Field` | Its message, then its hint, in `<small>` under the control | `form-control`, `invalid-feedback`, `form-text` | `field`, `control`, `help` |
| `Button`, `LinkButton` | Pico's buttons (`secondary`); `danger`, `ghost`, `small`, `full` from `app.css`; a link is `role="button"` | `btn` and `btn-primary`, `btn-outline-secondary`, `btn-danger`, `btn-link`, `btn-sm`, `w-100` | `button` and `is-primary`, `is-danger`, `is-ghost`, `is-small`, `is-fullwidth` |
| `Badge`, `Flash` | `badge`, `flash` and the tone from `app.css` | `badge`, `alert` | `tag`, `notification` |
| `Table`, `Pagination` | `overflow-auto`; `<nav>` with a `<ul>` | `table-responsive`; `pagination` | `table-container`; `pagination` |
| Dark mode | Pico's, from the system | `theme.js` sets `data-bs-theme` from the system | Bulma's, from the system |

The menu button's name is `nav.menu` in `locales/<locale>/app.yaml`
("Menu"). Each version of the CLI writes the framework releases above;
a newer release of a framework comes with a newer CLI, or replace its
files in `public/static/` yourself.

## Tailwind CSS

`anetos new --css=tailwind` writes the components with Tailwind CSS
4.3.3's utility classes, the source stylesheet `views/ui/tailwind.css`
and `public/static/app.css`, which Tailwind compiles from it (`anetos
dev`, `anetos build` and `anetos css:build` run Tailwind; [Tailwind
CSS](https://docs.anetos.dev/guides/tailwind/index.md)). `classes.go` holds the classes of
each variant and size (`Variant.class`) and tone (`Tone.badge`,
`Tone.flash`) and of
the form controls (`control`).

| Component | Writes |
|---|---|
| `Head` | `app.css` |
| `Header`, `Nav`, `NavEnd` | Flex rows that wrap on a small screen; `NavLink` is darker and of medium weight when `aria-current="page"` |
| `Card`, `AuthCard` | A white (dark: zinc-900) box with a border, rounded, and a light shadow |
| `Field`, `Input`, `Textarea`, `Select` | A block label; full-width controls with a red border when `aria-invalid`; the message and the hint in small text under them |
| `Button`, `LinkButton` | The accent color (`bg-accent`, `--color-accent` in `tailwind.css`), white with a border (`Secondary`), red (`Danger`), or text only (`Ghost`) |
| `Badge`, `Flash` | A pill, a bordered box, in the tone's color (green, amber, red, blue) |
| `Table` | A bordered box that scrolls sideways; `tailwind.css` styles the cells |

`tailwind.css` also styles the pages' plain HTML, which Tailwind's
reset leaves bare: the body, links, `h1`, `h2`, lists and paragraphs in
`<main>`, `code`, `small`, `th` and `td`.


# Data

Source: https://docs.anetos.dev/reference/data/

- [Models reference](https://docs.anetos.dev/reference/models/index.md): How the db package maps a struct to a table. See [Define models and save data](https://docs.anetos.dev/guides/models/index.md) for a walkthrough.
- [Query builder reference](https://docs.anetos.dev/reference/query-builder/index.md): Everything available on `db.Q[T]`, the query started by `db.Query[T](ctx)`. See [Query data](https://docs.anetos.dev/guides/queries/index.md) for a walkthrough.
- [Migrations reference](https://docs.anetos.dev/reference/migrations/index.md): The schema builder, the migration runner and the commands in package `anetos.dev/anetos/db/migrate`. See [Migrations](https://docs.anetos.dev/guides/migrations/index.md) and [Seed the database](https://docs.anetos.dev/guides/seeders/index.md) for walkthroughs.


# Models reference

Source: https://docs.anetos.dev/reference/models/

How the db package maps a struct to a table. See
[Define models and save data](https://docs.anetos.dev/guides/models/index.md) for a walkthrough.

## Tags

| Tag | Meaning |
|---|---|
| `db:"title"` | Column name |
| `db:"-"` | Not a column |
| `db:"code,pk"` | Primary key (otherwise the `id` column, if there is one). One per model: composite keys work only through raw SQL |
| `db:"meta,json"` | Stored as JSON text: encoded on write, decoded on read. A nil map, slice or pointer is stored as NULL |
| `db:"total,readonly"` | Read but never written (generated columns, database defaults) |
| `db:",pk"` | Options with the default column name |

## Columns

| Field | Column |
|---|---|
| Exported field with a `db` tag | The tag's name |
| Exported field without a tag | snake_case of the field name: `AuthorID` → `author_id`, `HTTPStatus` → `http_status`, `UserIDs` → `user_ids` |
| Field with a `rel` tag | A relation, not a column (see [Relations](https://docs.anetos.dev/reference/models/index.md#relations)) |
| Untagged struct, pointer-to-struct or slice-of-struct field | Not a column. Types that scan themselves (`time.Time`, `sql.Null[T]`, anything implementing `sql.Scanner`) are columns |
| Embedded struct without a `db` name | Its fields are flattened into the model (`db.Model`, `db.Timestamps`, your own mixins). Embedded pointers are allocated when scanning |
| Unexported field | Not a column |

Two fields mapping to the same column is an error.
`db.Columns[T]()` lists a model's columns in this order, and
[`anetos generate`](https://docs.anetos.dev/reference/anetos-generate/index.md) declares a typed column for each.

## Tables

The table is the snake_case plural of the type name, pluralizing the last
word: `Post` → `posts`, `BlogPost` → `blog_posts`, `Category` →
`categories`, `Box` → `boxes`, `Person` → `people`. Anything else:

```go
// illustrative
func (Tag) TableName() string { return "tag_catalog" }
```

## Embeddable types

| Type | Columns | Effect |
|---|---|---|
| `db.Model` | `id` (int64, primary key), `created_at`, `updated_at` | Auto-increment key plus `db.Timestamps` |
| `db.Timestamps` | `created_at`, `updated_at` (`time.Time`) | Set by `Create` (if zero), `Update`, `Save`, mass `Update`, soft deletes and `Upsert` |
| `db.SoftDeletes` | `deleted_at` (`*time.Time`) | `Delete` sets it; queries exclude those rows unless `WithTrashed`/`OnlyTrashed`; `Restore` clears it; `Trashed()` reports it |

Timestamps are only managed when `db.Timestamps` (or `db.Model`) is
embedded; a plain `CreatedAt` field is an ordinary column. Timestamps are
written in UTC with microsecond precision (use `TIMESTAMPTZ` or
`TIMESTAMP(6)` on PostgreSQL, `DATETIME(6)` on MySQL). `Update` never
writes `deleted_at`, so saving an old copy of a row can't undelete it.

## Primary keys

An integer primary key that is zero on `Create` is generated by the
database and set on the struct (`RETURNING` on PostgreSQL and SQLite,
`LastInsertId` on MySQL). A non-zero integer key, or a key of another type
(a UUID string, say), is inserted as given. `Save` needs an integer key.

## Field types

Anything `database/sql` and the driver can read and write: strings,
numbers, bools, `[]byte`, `time.Time`, pointers to those (for nullable
columns), `sql.Null[T]`, and types implementing `sql.Scanner` and
`driver.Valuer`. Times are always returned in UTC. NULL in a non-pointer
field is an error that names the fix.

Time arguments are converted to UTC before they are sent. Use
`anetos.Date` for `DATE` columns: it is written as `2026-03-15` text and
read back as the same day, while a `time.Time` at a local midnight east
of Greenwich becomes the previous day in UTC. NULL reads as the zero
`Date`. See [times and dates](https://docs.anetos.dev/guides/times-and-dates/index.md).

## Hooks

Methods on the model's pointer type, all `func(ctx context.Context) error`:

| Method | Runs |
|---|---|
| `BeforeSave`, `AfterSave` | Around `Create`, `Update` and `Save` (outside the create/update hooks) |
| `BeforeCreate`, `AfterCreate` | Around `Create`, `Save` of a new row, and each row of `CreateMany` |
| `BeforeUpdate`, `AfterUpdate` | Around `Update` and `Save` of an existing row |
| `BeforeDelete`, `AfterDelete` | Around `Delete` and `ForceDelete` |

A hook's error stops the operation and is returned. Mass updates and
deletes on a query, `Restore` and `Upsert` run no hooks. On a table
watched by the audit log, hooks run inside the write's transaction.

## Relations

A relation field has a `rel` tag, `rel:"kind"` or
`rel:"kind,option=value,…"`, and no `db` tag. See
[Relations and eager loading](https://docs.anetos.dev/guides/relations/index.md).

| Kind | Field type | Keys | Options (defaults) |
|---|---|---|---|
| `belongs_to` | `*R` | This model's `fk` → R's `references` | `fk` (the field's name in snake_case + `_id`), `references` (R's primary key) |
| `has_one` | `*R` | R's `fk` → this model's `local` | `fk` (this type's name in snake_case + `_id`), `local` (the primary key) |
| `has_many` | `[]R` | R's `fk` → this model's `local` | as `has_one` |
| `many_to_many` | `[]R` | `pivot`.`fk` → this model's primary key, `pivot`.`related_fk` → R's primary key | `pivot` (both type names in snake_case, sorted, joined with `_`), `fk` (this type + `_id`), `related_fk` (R's type + `_id`) |

| API | Does |
|---|---|
| `db.RelOf[T, R](field)` | `db.Rel[T, R]`, the handle of a relation field (`anetos generate` writes them in `TRels`). Nothing is checked until use; `Err()` reports a wrong field or type, a bad tag or missing key columns, as queries do before running |
| `rel.With(nested...)` | Also load relations of the related rows |
| `rel.Where(conds...)`, `rel.OrderBy(orders...)` | Conditions and order of the relation's query (default order: R's primary key; a `has_one` gets the first row). Many-to-many queries join the pivot: qualify columns it also has |
| `rel.WithTrashed()` | Include soft-deleted related rows |
| `q.With(rels...)` | Load relations of the query's rows: one query per relation (keys in chunks of 1,000) in `Get`, `First`, `Find`, `Paginate` and `CursorPaginate`; `All` returns an error |
| `db.Load(ctx, &row, rels...)`, `db.LoadMany(ctx, rows, rels...)` | The same for rows you have; loading again replaces the fields |
| `q.WhereHas(rel, conds...)`, `q.WhereDoesntHave(rel, conds...)` | `EXISTS` / `NOT EXISTS` subquery on the related rows (soft-deleted ones excluded unless `rel.WithTrashed()`); no nested relations |
| `db.Attach(ctx, &row, rel, ids...)` | Insert the missing pivot rows (`many_to_many` only); needs a primary key or unique index on the two pivot columns |
| `db.Detach(ctx, &row, rel, ids...)` | Delete those pivot rows; no ids: nothing |
| `db.DetachAll(ctx, &row, rel)` | Delete all of the row's pivot rows |
| `db.Sync(ctx, &row, rel, ids...)` | Make the pivot rows exactly ids |

A loaded pointer relation with no match is `nil`; a loaded slice relation
with none is empty, not `nil`. Parents with the same key share one loaded
`*R` (and the same slice contents, clipped so appending to one doesn't
change another). Passing one relation twice to `With` is an error.

## Functions

| Function | Does | Errors |
|---|---|---|
| `db.Create(ctx, &row)` | INSERT; sets the generated key and timestamps | Hook errors, driver errors |
| `db.CreateMany(ctx, rows)` | Multi-row INSERT in batches; sets keys on PostgreSQL and SQLite | Mixed rows (some with keys set, some without) |
| `db.Update(ctx, &row)` | UPDATE of every column except the key, `created_at` and `deleted_at`, by key | Zero key; `db.ErrNotFound` if the row doesn't exist |
| `db.Save(ctx, &row)` | `Create` if the integer key is zero, else `Update` | Non-integer key; `db.ErrNotFound` as for `Update` |
| `db.Delete(ctx, &row)` | Soft delete for `SoftDeletes` models, else DELETE | `db.ErrNotFound` if no (non-deleted) row matched |
| `db.ForceDelete(ctx, &row)` | DELETE, even for `SoftDeletes` models | `db.ErrNotFound` |
| `db.Restore(ctx, &row)` | Clears `deleted_at` | Model without `SoftDeletes` |
| `db.Upsert(ctx, rows, conflict, update...)` | INSERT … ON CONFLICT / ON DUPLICATE KEY UPDATE; no update columns means "keep the existing row" | Unknown column names |
| `db.Find[T](ctx, id)` | SELECT by key | `db.ErrNotFound` (a 404 in handlers) |
| `db.KeyOf(row)` | The row's table and primary key | No primary key |
| `db.Prunable[T](app, after)` | Registers a `SoftDeletes` model whose rows deleted longer than *after* ago `db:prune-trashed` and `db.PruneAllTrashed(ctx)` delete for good, 1,000 per transaction | No `SoftDeletes`, no key, registered twice |


# Query builder reference

Source: https://docs.anetos.dev/reference/query-builder/

Everything available on `db.Q[T]`, the query started by
`db.Query[T](ctx)`. See [Query data](https://docs.anetos.dev/guides/queries/index.md) for a walkthrough.

Each method returns a new query; the original is unchanged.

## Conditions and clauses

| Method | SQL |
|---|---|
| `Where(conds...)` | `WHERE … AND …`; repeated calls add more conditions |
| `WhereRaw(sql, args...)` | A condition in SQL with `?` placeholders |
| `Join(sql, args...)` | A join clause in SQL (`JOIN users ON …`); only `T`'s columns are selected |
| `OrderBy(orders...)` | `ORDER BY`, from `col.Asc()`, `col.Desc()` or `db.OrderRaw(sql)` |
| `Latest()`, `Oldest()` | `ORDER BY created_at DESC` / `ASC` |
| `Limit(n)`, `Offset(n)` | `LIMIT` / `OFFSET` |
| `GroupBy(cols...)`, `Having(conds...)` | `GROUP BY` / `HAVING` (read the groups with `db.Select`) |
| `Distinct()` | `SELECT DISTINCT` |
| `Scope(fns...)` | Applies `func(*db.Q[T]) *db.Q[T]` modifiers |
| `WithTrashed()`, `OnlyTrashed()` | Include / only soft-deleted rows |
| `WhereKeys(ids...)` | `WHERE <primary key> IN (…)`; none matches nothing |
| `Similar(embeddingModel, v)`, `Hybrid(text, embeddingModel, v)` | Vector search: records nearest `v` by their chunks of `embeddingModel`; hybrid also ranks the full-text matches of `text` ([vector search](https://docs.anetos.dev/reference/query-builder/index.md#vector-search)) |
| `Search(text)` | Full-text search: rows matching every word of `text` (as prefixes from three letters, whole below; ten words at most), best first, then `OrderBy`'s order; needs a search index ([search](https://docs.anetos.dev/guides/search/index.md)). Text without words changes nothing; `Distinct` and `GroupBy` queries search without the relevance order; Update, Delete and `CursorPaginate` refuse it. It replaces a `Similar` or `Hybrid`, and they replace it |
| `WhereHas(rel, conds...)`, `WhereDoesntHave(rel, conds...)` | `EXISTS (…)` / `NOT EXISTS (…)` on a relation's rows ([relations](https://docs.anetos.dev/reference/models/index.md#relations)) |
| `With(rels...)` | Loads relations of the rows, one query per relation ([relations](https://docs.anetos.dev/reference/models/index.md#relations)) |
| `ForUpdate()`, `ForShare()` | Row locks until the transaction ends (nothing on SQLite) |

## Conditions

| Expression | SQL |
|---|---|
| `col.Eq(v)`, `Ne`, `Gt`, `Gte`, `Lt`, `Lte` | `=`, `<>`, `>`, `>=`, `<`, `<=`. `Eq(nil)` / `Ne(nil)` become `IS NULL` / `IS NOT NULL` |
| `col.In(vs...)`, `col.NotIn(vs...)` | `IN (…)`; an empty `In` matches nothing, an empty `NotIn` everything |
| `col.Between(lo, hi)` | `BETWEEN lo AND hi` |
| `col.Like(p)`, `col.NotLike(p)` | `LIKE` (case sensitivity depends on the database); `p` is a pattern: `%` and `_` in text from users widen it |
| `col.Contains(s)`, `col.StartsWith(s)` | `LIKE` with `s` taken literally (`%`, `_` and `!` escaped, `ESCAPE '!'`): for search boxes. `db.EscapeLike(s)` escapes for a raw `LIKE ? ESCAPE '!'` |
| `col.IsNull()`, `col.NotNull()` | `IS NULL`, `IS NOT NULL` |
| `db.And(...)`, `db.Or(...)`, `db.Not(c)` | Grouped with parentheses; `And()` is true, `Or()` is false |
| `db.SQL(sql, args...)` | Any SQL, with `?` or `:name` placeholders |

## Columns

`go tool anetos generate` declares `PostCols` with a typed column per field of
model `Post` ([Generate typed columns](https://docs.anetos.dev/guides/code-generation/index.md)). By
hand:

| Function or method | Makes |
|---|---|
| `db.Col[T]("name")` | A typed column; `"table.name"` qualifies it. `T` is the Go field's type (`*time.Time` for a nullable timestamp) |
| `db.JSONCol[T]("name")` | A column stored as JSON: values passed to its methods are encoded as JSON (nil stays `NULL`), and `db.Pluck` decodes them |
| `db.C("name")` | An untyped column (`Column[any]`) |
| `col.Of("posts")` | The same column qualified with a table (`posts.name`); `Of("")` removes the qualifier |
| `col.Name()` | The column name |
| `db.Columns[T]()` | Model `T`'s column names in field order, or an error if `T` isn't a model struct |
| `db.SoftDeleting[T]()` | Whether model `T` embeds `db.SoftDeletes` (a `deleted_at` column alone isn't enough) |

## Reading

| Method or function | Returns |
|---|---|
| `Get()` | `[]T`, empty (not nil) when nothing matches |
| `First()` | First row or `db.ErrNotFound` |
| `Find(id)`, `db.Find[T](ctx, id)` | Row by primary key or `db.ErrNotFound` |
| `All()` | `iter.Seq2[T, error]`, streaming rows |
| `Count()` | `int64` |
| `Exists()` | `bool` |
| `Paginate(page, perPage)` | `db.Page[T]`: `Data`, `CurrentPage`, `PerPage`, `Total`, `LastPage` (JSON: `data`, `current_page`, …); `HasPrev()`, `HasNext()`. A page below 1 is page 1; past the end, empty. `db.MapPage(page, fn)` turns its rows into an API's responses, keeping the counts |
| `CursorPaginate(cursor, perPage)` | `db.CursorPage[T]`: `data`, `per_page`, `next_cursor`, `prev_cursor`; `db.ErrInvalidCursor` (400) for malformed cursors |
| `db.Pluck(q, col)` | `[]V`, one column (decoded from JSON for a `db.JSONCol`) |
| `db.Sum(q, col)`, `db.Min`, `db.Max` | `V`; zero if no rows match. `Limit` and `Offset` are respected, `Distinct` is ignored (write `SUM(DISTINCT x)` with `db.Select`); with `GroupBy`, use `db.Select` |
| `db.Avg(q, col)` | `float64` |
| `db.Select[R](q, terms...)` | `[]R`, for custom SELECT terms (`"COUNT(*) AS posts"`) |

`perPage` below 1 means `db.DefaultPerPage` (15). Cursor pagination orders
by the query's column orderings plus the primary key; it rejects
`OrderRaw`, and the ordering columns shouldn't contain NULLs. Cursors are
encoded, not signed: a client can craft one, which only moves where its
own page starts.

## Vector search

For records with an embeddings table (`migrate.Schema.CreateEmbeddings`),
usually kept by [`ai.Embeddings`](https://docs.anetos.dev/guides/semantic-search/index.md).

| Method or function | Does |
|---|---|
| `Similar(embeddingModel, v)` | Joins the records' chunks of `embeddingModel` (all models' for `""`), keeps the `db.SimilarCandidates` (200) chunks nearest `v` by cosine distance, and orders the records by their nearest chunk, then `OrderBy`'s order, then the primary key (ties never make pages overlap). `v` must have the table's size |
| `Hybrid(text, embeddingModel, v)` | `Similar`'s list and `Search(text)`'s (200 each), merged by reciprocal rank fusion: a record scores `1/(60 + rank)` in each list it's in, so records both find come first. Needs a search index; text without words makes it `Similar` |
| `db.Vector` | `[]float32`; scans a string as pgvector's text (`[1,2,3]`, what the PostgreSQL driver returns), and bytes as little-endian float32s (MariaDB, SQLite) |
| `db.CosineDistance(a, b)` | `1 - cos`: 0 for the same direction, 1 unrelated, 2 opposite; an error for vectors of different sizes |
| `db.Chunks[T](ctx, ids...)` | `[]db.Chunk{RecordID, Position, Content, ContentHash, EmbeddingModel, Embedding}` of the records (all, for none), by record and position |
| `db.ReplaceChunks[T](ctx, id, chunks)` | Makes them the record's chunks, in one transaction that locks the record's row (positions from the slice's order); for a deleted record, removes its chunks. Outside a transaction, retried on deadlocks |
| `db.PruneChunks[T](ctx)` | Deletes the chunks of records that no longer exist, and returns how many (MariaDB: those another table's cascade left) |
| `db.NearestChunks[T](ctx, embeddingModel, v, ids...)` | `[]db.ChunkMatch{Chunk, Distance}` of the records, nearest first |
| `db.RecordID(row)`, `db.TableOf[T]()` | A record's integer primary key; `T`'s table |
| `db.EmbeddingsTable(table)` | `table + "_embeddings"` |
| `d.Supports(ctx, db.VectorSearch)`, `d.CheckCapabilities(ctx, feature, caps...)` | Whether the database has vector search: SQLite (the driver registers `anetos_vec_distance_cosine`), PostgreSQL with the `vector` extension available, MariaDB 11.7+; MySQL Community doesn't. `CheckCapabilities` returns an error naming the feature and what to install |

`Similar` and `Hybrid` combine with `Where`, scopes, soft deletes,
`Limit`, `Count` and `Paginate`; `Distinct` and `GroupBy` queries lose
their order; Update, Delete and `CursorPaginate` refuse them. Vector
indexes find nearest chunks approximately (HNSW on PostgreSQL and
MariaDB): a record outside the candidates isn't returned, and a record
with many near chunks takes more of them. The PostgreSQL driver sets
`hnsw.ef_search` to 200 and `hnsw.iterative_scan` to `strict_order`
(pgvector 0.8+) for each session, so the index returns 200 candidates
after `model`'s filter (by default it stops at 40); they apply to the
app's own pgvector queries too. The MySQL driver sets MariaDB's
`mhnsw_ef_search` to 1000 per session (default 20), for the same reason.
On MariaDB, the candidates are chunks of
existing records (its embeddings tables have no foreign key). Zero vectors differ
by database (SQLite: distance 1; MariaDB: 0; PostgreSQL: NaN): don't
store them. On MariaDB,
vectors travel as text (`VEC_FromText(?)`); raw SQL with a `db.Vector`
argument must write that too.

## Writing

| Method | Does |
|---|---|
| `Update(assignments...)` | `UPDATE … SET` from `col.Set(v)` or `col.SetRaw(sql, args...)`; adds `updated_at` for models with timestamps; returns the rows matched. Columns may be qualified with the model's own table |
| `Delete()` | Soft delete for `SoftDeletes` models (rows already deleted keep their `deleted_at`; with `OnlyTrashed` it does nothing), else `DELETE` |
| `ForceDelete()` | `DELETE` |
| `Restore()` | Clears `deleted_at` on matching trashed rows |

Mass writes don't run model hooks and accept only `Where` conditions:
`Join`, `OrderBy`, `Limit`, `Offset`, `GroupBy`, `Having`, `Distinct` and
locks are refused, because they don't work alike across databases. For
those, write the statement with `db.Exec`.

## Raw SQL

| Function | Does |
|---|---|
| `db.Raw[T](ctx, sql, args...)` | `[]T` from any query; `T` a struct or a single value |
| `db.RawFirst[T](ctx, sql, args...)` | First row or `db.ErrNotFound` |
| `db.Exec(ctx, sql, args...)` | `sql.Result` |

Placeholders: `?` everywhere (`??` for a literal `?` on PostgreSQL), or
`:name` with one `db.Named` argument. SQL without arguments is sent as
written. A whole `Raw` or `Exec` query
without `?` is sent as written, so native `$1` works there; fragments
(`db.SQL`, `WhereRaw`, `SetRaw`, `Join`) must use `?`.

## Transactions

| Function | Does |
|---|---|
| `db.Tx(ctx, fn)` | Runs `fn` in a transaction (a savepoint when nested) |
| `db.TxWithOptions(ctx, opts, fn)` | With `*sql.TxOptions` |
| `db.AfterCommit(ctx, fn)` | Runs `fn` after the commit (or now, outside a transaction) |
| `db.InTx(ctx)` | Whether `ctx` has a transaction |
| `db.WithTx(ctx, tx)` | Queries on the returned context use a `*sql.Tx` you began (and commit) yourself; `AfterCommit` callbacks on it never run |
| `db.WithoutTx(ctx)` | Queries on the returned context leave the transaction: their writes stay after a rollback (SQLite: they wait for it) |
| `q.WithContext(ctx)` | The query with another context, e.g. a base query run inside `Tx` |

## Errors

| Error | Status in handlers | When |
|---|---|---|
| `db.ErrNotFound` | 404 | `First`, `Find`, `RawFirst`, `Delete` found no row |
| `db.ErrInvalidCursor` | 400 | `CursorPaginate` got a cursor it didn't produce |
| `db.ErrNoDB` | 500 | The context has no database |


# Migrations reference

Source: https://docs.anetos.dev/reference/migrations/

The schema builder, the migration runner and the commands in package
`anetos.dev/anetos/db/migrate`. See [Migrations](https://docs.anetos.dev/guides/migrations/index.md)
and [Seed the database](https://docs.anetos.dev/guides/seeders/index.md) for walkthroughs.

## Column types

| Method | PostgreSQL | MySQL / MariaDB | SQLite | Go field |
|---|---|---|---|---|
| `t.ID()` | `BIGSERIAL PRIMARY KEY` | `BIGINT AUTO_INCREMENT PRIMARY KEY` | `INTEGER PRIMARY KEY AUTOINCREMENT` | `int64` (`db.Model`) |
| `t.String(name, n)` | `VARCHAR(n)` | `VARCHAR(n)` | `VARCHAR(n)` | `string`; `n = 0` means 255 |
| `t.Text(name)` | `TEXT` | `TEXT` (64KB) | `TEXT` | `string` |
| `t.LongText(name)` | `TEXT` | `LONGTEXT` | `TEXT` | `string` |
| `t.Integer(name)` | `INTEGER` | `INT` | `INTEGER` | `int32`, `int` |
| `t.BigInteger(name)` | `BIGINT` | `BIGINT` | `BIGINT` | `int64` |
| `t.SmallInteger(name)` | `SMALLINT` | `SMALLINT` | `SMALLINT` | `int16` |
| `t.Boolean(name)` | `BOOLEAN` | `BOOLEAN` (TINYINT(1)) | `BOOLEAN` | `bool` |
| `t.Float(name)` | `DOUBLE PRECISION` | `DOUBLE` | `REAL` | `float64` |
| `t.Decimal(name, p, s)` | `NUMERIC(p, s)` | `DECIMAL(p, s)` | `TEXT` (exact, compares as text) | `string` or a decimal type (not `float64`) |
| `t.Date(name)` | `DATE` | `DATE` | `DATE` | `anetos.Date` (see [times and dates](https://docs.anetos.dev/guides/times-and-dates/index.md)) |
| `t.Timestamp(name)` | `TIMESTAMPTZ` | `DATETIME(6)` | `DATETIME` | `time.Time` |
| `t.JSON(name)` | `JSONB` | `JSON` | `TEXT` | any, with `db:"name,json"` |
| `t.Binary(name)` | `BYTEA` | `LONGBLOB` | `BLOB` | `[]byte` |
| `t.UUID(name)` | `UUID` | `CHAR(36)` | `TEXT` | `string` |
| `t.ForeignID(name)` | `BIGINT` | `BIGINT` | `BIGINT` | `int64` |
| `t.Vector(name, dims)` | `vector(dims)` (pgvector) | `VECTOR(dims)` (MariaDB 11.7+) | `BLOB` (little-endian float32s) | `db.Vector` |
| `t.Timestamps()` | `created_at`, `updated_at`: timestamps defaulting to now | | | `db.Timestamps` |
| `t.SoftDeletes()` | `deleted_at`: nullable timestamp | | | `db.SoftDeletes` |

## Column modifiers

| Modifier | Effect |
|---|---|
| `.Nullable()` | Allows NULL (columns are `NOT NULL` otherwise) |
| `.Default(v)` | Default value: string, number, bool or nil |
| `.DefaultRaw(sql)` | Default written in SQL, e.g. `"gen_random_uuid()"` |
| `.UseCurrent()` | Defaults a timestamp to the current time |
| `.Unique()`, `.Index()` | Index on this column (see names below) |
| `.UniqueWithoutTrashed()` | Unique index over the rows that aren't soft-deleted (`WHERE deleted_at IS NULL`); PostgreSQL and SQLite, an error on MySQL and MariaDB |
| `.Primary()` | This column is the primary key |
| `.References(table, col...)` | Foreign key to *table* (`id` if no column given) |
| `.Constrained()` | Foreign key to the table named after the column: `author_id` → `authors(id)` |
| `.Change()` | In `Alter`: change this existing column's type, NULL-ness and default (PostgreSQL, MySQL) |
| `.Using(sql)` | With `Change()` on PostgreSQL: the conversion, e.g. `"code::integer"` |

Foreign keys continue with `.OnDelete(migrate.Cascade)` (also `SetNull`,
`Restrict`, `NoAction`, `SetDefault`), `.OnUpdate(...)`,
`.CascadeOnDelete()`, `.NullOnDelete()` and `.Named(name)`. `References`
and `Constrained` return the foreign key, so put column modifiers such as
`Nullable()` before them.

A NOT NULL column can't `Default(nil)`, and a column added in `Alter`
must be `Nullable()` or have a default: the builder reports both.

## Table methods

| Method | In | Effect |
|---|---|---|
| `t.Index(cols...)`, `t.Unique(cols...)` | Create, Alter | Index or unique index |
| `t.UniqueWithoutTrashed(cols...)` | Create, Alter | Unique index over live rows, named like `Unique` (so `DropUnique` removes it); PostgreSQL and SQLite |
| `t.Primary(cols...)` | Create | Composite primary key (not with `ID()`) |
| `t.Foreign(cols...).References(...)` | Create, Alter (not SQLite) | Foreign key on existing columns |
| `t.DropColumn(names...)` | Alter | Removes columns |
| `t.RenameColumn(from, to)` | Alter | Renames a column |
| `t.DropIndex(cols...)`, `t.DropUnique(cols...)` | Alter | Removes the index made by `Index`/`Unique` on those columns |
| `t.DropForeign(cols...)` | Alter (not SQLite) | Removes the foreign key on those columns |
| `t.IndexNamed(name, cols...)`, `t.UniqueNamed(name, cols...)` | Create, Alter | Index with your own name |
| `t.DropIndexNamed(name)`, `t.DropForeignNamed(name)` | Alter | Drop by name (after `Rename`, or for older schemas) |
| `t.SearchIndex(cols...)` | Create, Alter | Full-text search index over text columns, most important first ([search](https://docs.anetos.dev/reference/migrations/index.md#search-indexes)); one per table |
| `t.DropSearchIndex()` | Alter | Removes the table's search index |

Index names are `<table>_<columns>_<kind>`: `posts_author_id_created_at_index`,
`posts_slug_unique`, `posts_author_id_foreign`. A name longer than 63
bytes is shortened to 54 bytes plus a hash of the full name, the same way
for create and drop. Renaming a table keeps its index names.

Table names can't be schema-qualified (`audit.logs`): connect to that
schema or database instead.

## Schema methods

| Method | Effect |
|---|---|
| `s.Create(table, fn)` | `CREATE TABLE` plus its indexes |
| `s.Alter(table, fn)` | Adds, changes, renames and drops columns, indexes and foreign keys |
| `s.Drop(table)`, `s.DropIfExists(table)` | Drops a table, and its search index |
| `s.Rename(from, to)` | Renames a table; refused when it has a search index (drop it first, add it again after) |
| `s.HasTable(table)`, `s.HasColumn(table, col)` | Whether they exist |
| `s.CreateEmbeddings(table, dims)`, `s.DropEmbeddings(table)` | The table of `table`'s embeddings: see [Embeddings tables](https://docs.anetos.dev/reference/migrations/index.md#embeddings-tables) |
| `s.Exec(sql, args...)` | Raw SQL. Without arguments: sent as written, split at `;` (trigger and function bodies stay whole). With arguments: one statement with `?` placeholders |
| `s.Context()` | The migration's context (database and transaction), for the db package |
| `s.Dialect()` | `"postgres"`, `"mysql"` or `"sqlite"` |

`migrate.NewSchema(ctx)` gives a Schema outside migrations (for tests).

On MySQL and MariaDB, the tables `Create` makes (and the migrations
and search index tables) are utf8mb4: when the database's default
character set is another one (`@@character_set_database`, latin1 on an
older MariaDB), `CREATE TABLE` ends with `DEFAULT CHARSET=utf8mb4`;
otherwise the table takes the database's collation. Tables made with
`s.Exec` or SQL-file migrations take whatever their SQL says, or the
database's default.

## SQLite limits

SQLite's `ALTER TABLE` can add, rename and drop columns, but can't change
them, add or drop foreign keys, add primary keys, or add a column whose
default is the current time. The builder returns an error for those; the
usual fix is a new table, a copy of the rows, a drop and a rename.
Foreign key enforcement is off during SQLite migrations (checked with
`PRAGMA foreign_key_check` before commit), so the drop doesn't cascade.

## Sets and migrations

| API | Does |
|---|---|
| `migrate.NewSet(name)` | A set of migrations: `"app"`, or a plugin's name |
| `set.Add(id, m)` | Adds a `Migration` (`Up(*Schema) error`, `Down(*Schema) error`); panics on a bad or duplicate ID |
| `set.AddFunc(id, up, down)` | Adds two functions; a nil `down` makes it irreversible |
| `set.AddFS(fsys, dir)` | Adds `ID.up.sql` / `ID.down.sql` files; first-line directives `-- anetos:no-transaction`, `-- anetos:no-split` |
| `migrate.Func(up, down)` | A migration from two functions |
| `migrate.NoTransaction(m)`, or a `WithoutTransaction()` method | Runs that migration outside a transaction |
| `migrate.ErrIrreversible` | Returned by `Down` of a migration that can't be undone |

IDs are ASCII letters, digits, `_`, `-` and `.`, up to 255 characters, and
are sorted as strings: start them with `YYYY_MM_DD_HHMMSS`.

## Runner

| API | Does |
|---|---|
| `migrate.New(app, sets, opts...)` | Runner on the app's database, environment and logger; adds the migration commands, the `doctor` check, a readiness gate (the server's `/health/ready` answers 503 while migrations are pending, rechecked every 5 seconds; `DB_MIGRATE_READINESS=false` turns it off) and, with `DB_MIGRATE_ON_START=true`, migrating when the app starts with `run` or `serve` |
| `migrate.NewRunner(d, sets, opts...)` | Runner on any `*db.DB` |
| `WithSeeders(...)`, `WithTable(name)`, `WithEnvironment(env)`, `WithLogger(l)` | Options; the default table is `migrations`, the default environment production |
| `Up(ctx)` | Applies pending migrations as one batch; returns them |
| `Rollback(ctx, n)` | Undoes the last *n* batches |
| `Reset(ctx)` | Undoes everything |
| `Fresh(ctx)` | Drops every table and view (PostgreSQL: also materialized views and enum types; extension objects stay), then `Up`; `migrate.ErrNotAllowed` outside development and testing. Procedures and functions are not dropped |
| `Status(ctx)` | Every migration: applied (batch, time), pending, or missing |
| `Seed(ctx, names...)` | Runs seeders, each in a transaction |
| `Command(ctx, args, out)` | The commands below, for programs without `app.Execute`; `handled` is false for other arguments |
| `AppCommands()` | The commands below as app binary commands; `migrate.New` registers them |

## Commands

Registered on the app by `migrate.New`, so the binary runs them
(`./app migrate`). Bad flags exit with status 2.

| Command | Flags | Production |
|---|---|---|
| `migrate` | `--seed`, `--force` | Allowed; `--seed` needs `--force` |
| `migrate:status` | `--json`: each migration's `source`, `id`, `applied`, `batch`, `applied_at`, `missing` | Allowed |
| `migrate:rollback` | `--step=N` (default 1) | Needs `--force` |
| `migrate:reset` | | Needs `--force` |
| `migrate:fresh` | `--seed` | Refused (also in staging) |
| `db:seed` | `--seeder=NAME` | Needs `--force` |
| `db:schema` | table names (default: all); `--json` | Allowed |
| `search:reindex` | table names (default: all) | Allowed |

`db:schema` describes the tables (and views) as the database has them,
from its catalog: each column's name, the database's type, `null` and
default, and the primary key; the indexes, the primary key's included;
the foreign keys with their `on delete`. SQLite's search indexes are
`(virtual)`, their internal tables left out. `--json` prints a list of
`{"name", "kind", "columns": [{"name", "type", "nullable", "default",
"primary_key", "generated", "identity"}], "indexes": [{"name", "columns", "unique", "primary", "where"}],
"foreign_keys": [{"columns", "table", "references", "on_delete"}]}`;
`Runner.Inspect(ctx, tables…)` returns the same as `[]TableInfo`.
An index's `columns` are its key's columns or expressions
(`lower(email)`; not the columns a PostgreSQL index `INCLUDE`s), and
`where` a partial index's condition; a column has `generated` (its
expression; `(generated)` on SQLite) and `identity` (an identity or
`AUTO_INCREMENT` column). Flags may come after the table names.

Every command but `db:seed` changes the schema (`cmd.Command.ChangesSchema`),
so it runs even when the search indexes don't match `DB_SEARCH_LANGUAGE` and
`DB_SEARCH_RANKING`, which stops the app and other commands at boot
(`db:schema` changes nothing, but runs then too, to describe them).

On PostgreSQL and MySQL, runs are serialized with an advisory or named
lock (per database) held on its own connection: the pool needs at least
2 connections.

## Search indexes

`t.SearchIndex("title", "body")` builds, for `DB_SEARCH_LANGUAGE` and
`DB_SEARCH_RANKING` (which the database must support, or the migration
fails):

| Database | Objects |
|---|---|
| PostgreSQL | `search_vector`, a stored generated `tsvector` column (columns weighted A, B, C, D in order), and its GIN index `<table>_search_index`; with `DB_SEARCH_RANKING=bm25`, also `search_text`, a generated text column, and its `bm25` index `<table>_search_bm25` (pg_textsearch) |
| MySQL, MariaDB | `search_text`, a stored generated `LONGTEXT` column (the columns joined), and its `FULLTEXT` index `<table>_search_index` |
| SQLite | `<table>_search`, an FTS5 table on the table's rows (tokenizer `unicode61`, with `porter` for english; column weights 1, 0.4, 0.2, 0.1), and the triggers `<table>_search_insert`, `_delete` and `_update` that keep it current |

In `Alter`, rows already in the table are indexed. Each index is
recorded in the `search_indexes` table (`db.SearchIndexes(ctx)` reads
it): its columns, language and ranking. `search:reindex` rebuilds
indexes from those records for the current settings, after checking
that every indexed column still exists. On MySQL and MariaDB, whose
schema changes aren't transactional, a rebuild that fails midway (a lock
timeout, a full disk) leaves the table without its index: run
`search:reindex` again. Columns must hold
text. `Alter` refuses to drop or rename an indexed column unless the
same `Alter` drops the index (`t.DropSearchIndex()`, the change, then
`t.SearchIndex` with the new columns). Object names longer than 63
bytes are shortened like index names.

## Embeddings tables

`s.CreateEmbeddings("articles", 1536)` creates `articles_embeddings`,
which [package `ai`](https://docs.anetos.dev/guides/semantic-search/index.md) fills, and needs the
database's vector search (`db.VectorSearch`): SQLite, PostgreSQL with
pgvector, MariaDB 11.7+. Dimensions run from 1 to 16000.

| Column | Type |
|---|---|
| `id` | `t.ID()` |
| `record_id` | the record's ID, a foreign key to `articles.id` (not on MariaDB); the chunks are deleted with the record |
| `chunk` | the chunk's position, from 0; unique with `record_id` |
| `content`, `content_hash` | the chunk's text, and its SHA-256 |
| `model` | the embedding model's name, up to 100 characters |
| `embedding` | `t.Vector("embedding", dims)` |
| `created_at`, `updated_at` | `t.Timestamps()` |

| Database | Also |
|---|---|
| PostgreSQL | `CREATE EXTENSION IF NOT EXISTS vector` (a superuser's: pgvector isn't trusted, so create it beforehand otherwise); an HNSW index with `vector_cosine_ops`, up to 2000 dimensions (above, searches compare every chunk); `ON DELETE CASCADE` |
| MariaDB | `VECTOR INDEX … DISTANCE=cosine`; no foreign key: an `AFTER DELETE` trigger on `articles`, `articles_embeddings_delete_trigger`, deletes a record's chunks, since InnoDB's cascading deletes skip the vector index, which then misses rows. A record deleted by another table's cascade doesn't fire it: its chunks stay until `db.PruneChunks` (`ai:embed`), and searches skip them (the candidates are chunks of existing records). Creating the trigger needs the `TRIGGER` privilege, and with binary logging `SUPER` or `log_bin_trust_function_creators`; if it fails, the table is dropped again |
| SQLite | no index (the driver's `anetos_vec_distance_cosine` compares every chunk); `ON DELETE CASCADE` |

`s.DropEmbeddings("articles")` drops the table (and the trigger).

## The migrations table

| Column | Content |
|---|---|
| `id` | Order applied |
| `source` | The set's name |
| `migration` | The migration's ID (unique per source) |
| `batch` | Which `migrate` run applied it |
| `applied_at` | When (UTC) |


# Packages

Source: https://docs.anetos.dev/reference/packages/

- [Authentication reference](https://docs.anetos.dev/reference/auth/index.md): Packages `auth`, `auth/password`, `auth/social` and `auth/rbac`. How-to: [Authentication](https://docs.anetos.dev/guides/authentication/index.md), [Authorization](https://docs.anetos.dev/guides/authorization/index.md), [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md). Settings: [configuration reference](https://docs.anetos.dev/reference/configuration/index.md#authentication).
- [AI reference](https://docs.anetos.dev/reference/ai/index.md): The API of package `ai`. See [Add AI to your app](https://docs.anetos.dev/guides/ai/index.md) for a walkthrough, [AI](https://docs.anetos.dev/concepts/ai/index.md) for the design, and [Configuration](https://docs.anetos.dev/reference/configuration/index.md#ai) for the `AI_*` settings.
- [Testing reference](https://docs.anetos.dev/reference/anetostest/index.md): The APIs of packages `anetostest` and `db/factory`, and the hooks they use. See [Test your app](https://docs.anetos.dev/guides/testing/index.md) for a walkthrough.


# Authentication reference

Source: https://docs.anetos.dev/reference/auth/

Packages `auth`, `auth/password`, `auth/social` and `auth/rbac`. How-to: [Authentication](https://docs.anetos.dev/guides/authentication/index.md),
[Authorization](https://docs.anetos.dev/guides/authorization/index.md), [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md). Settings: [configuration reference](https://docs.anetos.dev/reference/configuration/index.md#authentication).

## Setup

| API | Does |
|---|---|
| `auth.Authenticatable` | `AuthID() string` and `AuthPassword() string`, implemented by the app's user type |
| `auth.Users[U]{ByID, ByLogin, RememberToken, SetRememberToken, SetPassword, Disabled, SessionKey, SetSessionKey, TwoFactor, SetTwoFactor}` | How to find users (required: `ByID`, `ByLogin`; they return `db.ErrNotFound` or `auth.ErrUserNotFound`), store remember-me tokens and upgraded hashes; which accounts are disabled (`Disabled`); the session key sessions are bound to (`SessionKey` and `SetSessionKey`, both or neither); the two-factor state, stored encrypted (`TwoFactor` and `SetTwoFactor`, both or neither) |
| `auth.New(app, users, opts...)` | `*auth.Auth[U]` from `AUTH_*` and `APP_KEY`; needs `cache.New` first; provided to the app; once per app. Options as `NewWithConfig`'s, after its own, and `auth.WithDefaultHomeURL(path)`: `AUTH_HOME_URL`'s default |
| `auth.NewWithConfig(cfg, users, enc, opts...)` | Without an app; `auth.WithLogger`, `auth.WithInsecureCookies`, `auth.WithIssuer(name)` (two-factor setups' issuer; `auth.New` uses `APP_NAME`) |
| `auth.Migrations()` | The `api_tokens` table, for `migrate.New` |

## Middleware

| API | Does |
|---|---|
| `a.Middleware` | Makes the request's user available (from the session or a remember-me cookie); after the session middleware |
| `a.Require` | Logged-in users only: guests asking for a page are redirected to `AUTH_LOGIN_URL`; others, and every request on routes without sessions, get 401, with `WWW-Authenticate: Bearer` on routes without sessions or behind `TokenMiddleware`. Responses to logged-in users get `Cache-Control: no-store` unless the handler sets another |
| `a.Guest` | Guests only: logged-in users are redirected to `AUTH_HOME_URL` |
| `a.TokenMiddleware` | Logs in the user of a `Bearer` API token; invalid tokens get 401; no token (or another scheme) passes as a guest |
| `a.RequireConfirmed` | Users who confirmed their password in the last `AUTH_CONFIRM_TTL` only: others are sent to `AUTH_CONFIRM_URL`, to come back after (to the page for GET, else to the page the form was on); API clients and htmx requests get `auth.ErrPasswordNotConfirmed` (423). After `Require` |

## Logging in and out

| API | Does |
|---|---|
| `a.Attempt(ctx, login, password, remember)` | Checks the password and logs in; `auth.ErrInvalidCredentials` (401), `*auth.ThrottledError` (429) past `AUTH_THROTTLE` attempts a minute per login or account and IP, or `AUTH_THROTTLE_IP` failures per IP; for a user with two-factor authentication on, the user and `auth.ErrTwoFactorRequired` (401): the login waits for a code |
| `a.Login(ctx, u, remember)` | Logs `u` in: new session ID; with `remember`, the remember-me cookie. For a user with two-factor authentication on, `auth.ErrTwoFactorRequired` instead, and a login waiting for a code (10 minutes). For logging in after registration and by other means than a password (it used to skip the code; `SignIn`, which asked for it, is deprecated) |
| `a.RememberCookie()` | The remember-me cookie's name (`__Host-anetos_remember`, `anetos_remember` with `WithInsecureCookies`) |
| `a.LoginSession(s, u)` | Writes a logged-in session for `u` into the `*session.Session` without a request, as `Login` without remember-me would, without asking for a two-factor code: for tests (`anetostest.ActingAs`) and tools; `auth.ErrDisabled` for a disabled user |
| `a.AttemptTwoFactor(ctx, code)` | Finishes the waiting login with the authenticator app's code (each used once) or a recovery code (used up); `auth.ErrInvalidCode` (422), `auth.ErrNoPendingLogin` (401: none, expired, or the password changed), `*auth.ThrottledError` past `AUTH_THROTTLE` a minute or 50 wrong codes a day (UTC) for the user; `auth.ErrDisabled` |
| `a.TwoFactorPending(ctx)` | Whether a login waits for a code in the session |
| `a.AttemptCredentials(ctx, login, password)` | `Attempt`'s check (its errors, throttling and rehashing) without a session: returns the user, for an API's login to give a token; `auth.ErrDisabled` (403); for a user with two-factor authentication on, a `*auth.TwoFactorChallenge` (401, `errors.Is` `auth.ErrTwoFactorRequired`) whose `Token` the client sends back with a code. The route needs `TokenMiddleware` or `Middleware` |
| `a.AttemptTwoFactorChallenge(ctx, challenge, code)` | Finishes such a login: checks the challenge (10 minutes, until the password or session key changes) and the code as `AttemptTwoFactor` does (its lock, limits and errors; `auth.ErrNoPendingLogin` for a bad, expired or outdated challenge) and returns the user; no session. A challenge works again within its 10 minutes, with a new code |
| `a.CheckPassword(ctx, u, password)` | Checks `u`'s password with `ConfirmPassword`'s budget (`AUTH_THROTTLE` a minute, 50 wrong a day), without a session: for an API, before what pages put behind `RequireConfirmed`; `auth.ErrInvalidCredentials`, `*auth.ThrottledError` |
| `a.ConfirmPassword(ctx, password)`, `a.PasswordConfirmed(ctx)` | Checks the logged-in user's password again, which holds for `AUTH_CONFIRM_TTL`; `auth.ErrInvalidCredentials` (also without a password); `AUTH_THROTTLE` tries a minute for the user, from any address, and 50 wrong passwords a day (UTC, shared with `ChangePassword`); not while impersonating another user. For a user without a password, a login through `Login` counts. Logging in or out, and impersonating someone, forget it; never for API tokens |
| `a.SupportsRemember()` | Whether "remember me" is available (`Users.RememberToken` set) |
| `a.Logout(ctx)` | Empties the session, removes the cookie, replaces the remember token |
| `auth.User[U](ctx)` | The logged-in user, and whether there is one |
| `auth.Current[U](ctx)` | The logged-in user, `auth.ErrUnauthenticated`, or the load error |
| `auth.Check(ctx)` | Whether a user is logged in |
| `auth.CurrentID(ctx)` | The logged-in user's `AuthID`, `auth.ErrUnauthenticated`, or the load error, for code that works with any user type |
| `a.WithUser(ctx, userID, opts...)`, `auth.WithUser(ctx, userID, opts...)` | A context whose logged-in user is that user (loaded with `Users.ByID` when asked for; none if it doesn't exist), for queue jobs and commands working for a user; no session (`Attempt`, `Login` and `Logout` refuse) and no token, unless `auth.WithAbilities(abilities)` gives it a token's limits. The function finds the app's Auth in ctx |
| `auth.Intended(ctx, fallback)` | The page a guest asked for before logging in, or `fallback` |

## Accounts

| API | Does |
|---|---|
| `Users.Disabled`, `a.Disabled(u)` | A disabled user is logged out on their next request; `Attempt` (once the password checks out) and `Login` return `auth.ErrDisabled` (403); their remember-me cookies and API tokens stop working; `WithUser` treats them as a guest |
| `a.ChangePassword(ctx, u, current, new)` | Changes `u`'s password (needs `Users.SetPassword`), logging them out of their other sessions and remember-me cookies (`LogoutOthers`); `auth.ErrInvalidCredentials` for a wrong `current`; a user without a password sets one without `current` within `AUTH_CONFIRM_TTL` of logging in (`auth.ErrPasswordNotConfirmed` after); `AUTH_THROTTLE` tries a minute, and 50 wrong passwords a day (UTC, shared with `ConfirmPassword`); not while impersonating someone |
| `a.LogoutOthers(ctx, u)` | Ends `u`'s other sessions (with `Users.SessionKey`), remember-me cookies and password-reset links, keeping the request's session if it is `u`'s (with a new session ID, and a new remember-me cookie if it had one) |
| `a.LogoutEverywhere(ctx, u)`, `a.SupportsLogoutEverywhere()` | Ends every session and remember-me cookie of `u` by giving them a new session key (`Users.SetSessionKey`) and remember token; API tokens stay |
| `a.Impersonate(ctx, u)` | Logs the current user in as `u`, keeping who they are in the session; not through API tokens, not nested, not for a disabled `u` (`ErrDisabled`) or oneself. Each request checks that the impersonator may still log in; `Logout` ends both (leaving `u`'s remember-me token alone). The impersonator's remember-me cookie is removed. Check who may first (`rbac.AuthorizeOver`) |
| `a.StopImpersonating(ctx)` | Logs the impersonator back in and returns them; `auth.ErrNotImpersonating` (409) without impersonation; if they can't log in any more, logs out and returns why |
| `auth.Impersonator(ctx)` | The ID of the user impersonating the logged-in one, and whether there is one |

## Two-factor authentication

TOTP (RFC 6238: six digits, 30 seconds, HMAC-SHA-1) and recovery codes;
see [Two-factor authentication](https://docs.anetos.dev/guides/two-factor/index.md). Needs
`Users.TwoFactor` and `SetTwoFactor`.

| API | Does |
|---|---|
| `a.SupportsTwoFactor()` | Whether two-factor authentication is available |
| `a.TwoFactor(u)` | `auth.TwoFactorStatus{On, Started, RecoveryCodes}`; an error if the state can't be read (`APP_KEY` changed) |
| `a.StartTwoFactor(ctx, u, account)` | Stores a new secret, replacing a started setup; returns `auth.TwoFactorSetup{Secret, URI}` (base32 key, `otpauth://` URI with `APP_NAME` as issuer); `auth.ErrTwoFactorOn` (409) if on |
| `a.StartedTwoFactor(u, account)` | The started setup again; `auth.ErrTwoFactorOff` if none, `ErrTwoFactorOn` once on |
| `a.ConfirmTwoFactor(ctx, u, code)` | Turns it on with a current code; returns 8 recovery codes (`abcde-fghij`), to show once; ends `u`'s other sessions and remember-me cookies (`LogoutOthers`); `auth.ErrInvalidCode`, `ErrTwoFactorOff`, `ErrTwoFactorOn`; throttled |
| `a.NewRecoveryCodes(ctx, u)` | Replaces the recovery codes; `auth.ErrTwoFactorOff` if off |
| `a.DisableTwoFactor(ctx, u)` | Turns it off (or drops a started setup) |
| `auth.TwoFactorCode(secret, t)` | The code an app shows at `t`, for tests |

## Tokens

| API | Does |
|---|---|
| `a.PasswordResetToken(u)`, `a.CheckPasswordResetToken(ctx, token)` | Reset tokens: `AUTH_RESET_TTL`, until the password or the session key changes; `auth.ErrInvalidToken` (400) |
| `a.VerificationToken(u, email)`, `a.CheckVerificationToken(ctx, token)` | Email-verification tokens: `AUTH_VERIFY_TTL`; returns the user and the address |
| `a.EmailRevertToken(u, old, new)`, `a.CheckEmailRevertToken(ctx, token)` | Tokens for the link, sent to the old address, that undoes a change of email address: `AUTH_REVERT_TTL`; returns the user and both addresses |
| `a.CreateToken(ctx, u, name, abilities, ttl)` | An API token (`<id>\|<secret>`, shown once) and its stored `auth.Token`; 403 while impersonating another user. Put the route behind `RequireConfirmed` |
| `a.Tokens(ctx, u)`, `a.RevokeToken(ctx, u, id)`, `a.RevokeAllTokens(ctx, u)` | A user's API tokens; delete one, or all |
| `a.RevokeOtherTokens(ctx, u, keep)` | Deletes `u`'s API tokens but `keep` (the request's, after a password change through the API) |
| `a.ClientLink(path, query)` | `AUTH_CLIENT_URL` joined with `path` and `query`: the link an API's emails give to the client app; an error naming the setting when it isn't set |
| `auth.CurrentToken(ctx)`, `auth.TokenCan(ctx, ability)` | The request's API token; whether it (or a session user) may do `ability` (`"*"`: all) |
| `auth.RequireAbilities(abilities...)` | Middleware: a token needs every one of the abilities (403 without them, 401 for a guest); a session user may do anything. Its routes' OpenAPI security lists them as scopes |

## Authorization

| API | Does |
|---|---|
| `auth.Authorize(ctx, policy, subject)` | nil, `auth.ErrUnauthenticated` (401) or `auth.ErrForbidden` (403); `policy` is `func(context.Context, U, T) bool` |
| `auth.AuthorizeUser(ctx, policy)` | The same for `func(context.Context, U) bool` |
| `auth.Allows`, `auth.AllowsUser` | The answer as a boolean (false for a guest) |
| `auth.IsDenied(err)` | Whether `err` is `ErrUnauthenticated` or `ErrForbidden` |

## Passwords

| API | Does |
|---|---|
| `password.Hash(pw)` | argon2id hash (19 MiB, 2 passes, 1 thread), as a PHC string; `password.ErrTooLong` over 1024 bytes |
| `password.Verify(pw, hash)` | Checks against argon2id or bcrypt (`$2a$`, `$2b$`, `$2y$`) hashes |
| `password.NeedsRehash(hash)` | bcrypt, or argon2id weaker than the defaults |
| `password.HashWith(pw, params)`, `password.Defaults()` | Other parameters (at most 256 MiB and 10 passes) |
| `password.IsBcrypt(hash)` | Whether the hash is bcrypt, which checks only a password's first 72 bytes |
| `password.Dummy(pw)` | Spends the time of a check, for unknown users |
| `password.VerifyContext(ctx, pw, hash)`, `password.DummyContext(ctx, pw)` | The same, giving up with ctx's error while waiting for a free slot (a few hashes are computed at once) |

## Social login

| API | Does |
|---|---|
| `social.Google()`, `social.GitHub()`, `social.GitHubAt(web, api)`, `social.OIDC(name, issuer)` | Providers; their `Scopes`, `Title` ("Google", for buttons; `OIDC`'s defaults to its name) and other fields can be changed |
| `social.Configured(app, providers...)` | The providers whose `SOCIAL_<NAME>_CLIENT_ID` and `_CLIENT_SECRET` are set |
| `social.New(app, a, resolve, providers, opts...)` | `*social.Social[U]`; needs `APP_URL` (https in production); with no providers, its routes answer 404; `social.WithHTTPClient`, `social.WithLogger`, `social.WithCallbackPath`, `social.WithHomeURL(path)` (where users go without an intended page; default `AUTH_HOME_URL`) |
| `social.NewWithConfig(a, resolve, baseURL, creds, providers, opts...)` | Without an app |
| `s.Redirect`, `s.Callback` | Handlers for `/auth/{provider}/redirect` (`?remember=1`) and `/auth/{provider}/callback` |
| `s.Providers()`, `s.CallbackURL(name)` | Provider names, in the order given; a provider's callback URL to register |
| `social.Resolver[U]`, `social.Profile` | `func(ctx, Profile) (U, error)`: finds or creates the user; the profile has `Provider`, `Subject`, `Email`, `EmailVerified`, `Name`, `AvatarURL`, `Token` |
| `social.NoAccountError{Message}` | Refuses a login with a message on the login page (`social` field) |
| `s.Providers()`, `s.Title(name)` | The providers' names, in the order given, and their titles, for login buttons |
| `social.Migrations()` | The `social_accounts` table |
| `social.FindLink(ctx, p)`, `social.Link(ctx, p, userID)`, `social.Links(ctx, userID)`, `social.Unlink(ctx, userID, provider)` | Links between provider accounts and users |

## Roles and permissions

Package `auth/rbac`. Concepts: [Roles and permissions](https://docs.anetos.dev/concepts/roles-and-permissions/index.md).

### Declaring

| API | Does |
|---|---|
| `rbac.Permission` | A string type: `const EditPosts rbac.Permission = "posts.edit"`; lowercase letters, digits and `. _ : -`, up to 100 characters; also the API token ability that allows it |
| `rbac.Role{Name, Title, Permissions, Super, Custom}` | A role; `Super` has every permission (code only); `Custom` is set for roles of the database. `r.Allows(p)`, `r.DisplayName()` (the title, or the name) |
| `rbac.New(app, permissions, roles...)` | `*rbac.Registry`, checked (unique names, roles of declared permissions); provided to the app and its contexts; caches grants per operation; adds the commands below; once per app |
| `rbac.NewRegistry(permissions, roles...)`, `rbac.WithRegistry(ctx, reg)`, `rbac.From(ctx)` | Without an app; `rbac.ErrNoRegistry` when the context has none |
| `reg.Declare(permissions...)` | Adds permissions to the registry, for packages that bring their own (the admin); idempotent; call it at setup, before the app serves |
| `rbac.AuthorizeOver(ctx, userID)` | nil if the logged-in user has every permission `userID` has in every scope (and a super role wherever they have one), else `auth.ErrForbidden`: for managing their account |
| `rbac.GivenTo(ctx, userID)` | The roles and permissions given to a user, as stored (`rbac.Given{Scope, Role, Permission}`), by scope and name |
| `rbac.RoleCounts(ctx)`, `rbac.Holders(ctx, role, limit)` | How many users have each role; who has a role, and where (`rbac.Holder{UserID, Scope}`) |
| `reg.Permissions()`, `reg.Declared(p)`, `reg.Roles()`, `reg.Role(name)` | What was declared |
| `rbac.Migrations()` | The `rbac_grants` and `rbac_roles` tables |

### Scopes

| API | Does |
|---|---|
| `rbac.Scope`, `rbac.Global` | Where a grant applies: `rbac.Global` (`""`) everywhere, or one scope |
| `rbac.ScopeOf(kind, id)` | `"team:42"`; `kind` is lowercase letters, digits, `_` and `-` (panics otherwise); IDs compare exactly (`ABC` isn't `abc`, on every database); stored scopes are up to 100 bytes (`rbac.ErrInvalidScope`, 422) |
| `s.Kind()`, `s.ID()`, `s.String()` | `"team"`, `"42"`; `"global"` for `rbac.Global` |

### Checking the logged-in user

A global grant applies in every scope. For a request logged in with an
API token, a permission must also be among the token's abilities (or
the token has `*`), and role checks are false unless it has `*`.

| API | Does |
|---|---|
| `rbac.Authorize(ctx, p)`, `rbac.AuthorizeIn(ctx, scope, p)` | nil, `auth.ErrUnauthenticated` (401), `auth.ErrForbidden` (403), or another error (the database; an undeclared permission, 500) |
| `rbac.Can(ctx, p)`, `rbac.CanIn(ctx, scope, p)` | The answer as a boolean: false for a guest; other errors are logged |
| `rbac.HasRole(ctx, role)`, `rbac.HasRoleIn(ctx, scope, role)` | Whether the user has the role in scope or globally |
| `rbac.AuthorizeRole(ctx, scope, role)` | nil if the user may give the role in scope: they have every permission it allows there (super there, with a `*` token, for a super role); else 401, 403 or `rbac.ErrUnknownRole`. Compares permissions, not names |
| `rbac.AuthorizeRolesOf(ctx, scope, userID)` | nil if the user may give every role `userID` has in exactly `scope`, so may change or remove them; else 401 or 403 |
| `rbac.Require(perms...)`, `rbac.RequireIn(scopeFn, perms...)` | Middleware: every permission, globally or in `scopeFn(r)`'s scope; the error of `Authorize` otherwise. After the auth middleware |
| `rbac.PathScope(kind, param)` | A `scopeFn` from a path parameter: `PathScope("team", "team")` on `/teams/{team}`; 404 without it |
| `rbac.Current(ctx)` | The logged-in user's `*rbac.Grants` (token limits applied), or `auth.ErrUnauthenticated` |

### Any user's grants

| API | Does |
|---|---|
| `rbac.Of(ctx, userID)` | The user's `*rbac.Grants`, read in one query (two with roles of the database) once per operation (request, job, listener, task, tool call) |
| `g.Can(p)`, `g.CanIn(scope, p)` | Whether a grant in scope, or a global one, allows `p` |
| `g.HasRole(role)`, `g.HasRoleIn(scope, role)` | Whether the user has the role in scope or globally (declared or stored roles only; none for a token without `*`) |
| `g.Roles(scope)` | The roles assigned in exactly `scope`, by name (the same rules) |
| `g.Permissions(scope)` | The permissions allowed in `scope` (with global grants), in declaration order |
| `g.Scopes(kind)` | The scopes of `kind` where the user has a role or a declared permission, sorted: their teams |

### Changing grants

| API | Does |
|---|---|
| `rbac.Assign(ctx, userID, scope, roles...)` | Adds roles (declared, or of the database: `rbac.ErrUnknownRole`, 422); user IDs are up to 100 bytes |
| `rbac.Unassign(ctx, userID, scope, roles...)` | Takes roles away in exactly `scope` |
| `rbac.Sync(ctx, userID, scope, roles...)` | Makes `roles` the user's only roles in `scope` (none: removes them all) |
| `rbac.Grant(ctx, userID, scope, perms...)`, `rbac.Revoke(…)` | Single permissions without a role (`rbac.ErrUnknownPermission`, 422) |
| `rbac.RemoveUser(ctx, userID)` | Every grant of the user, in every scope |
| `rbac.RemoveScope(ctx, scope)` | Every grant in the scope (not `rbac.Global`) |
| `rbac.Assignments(ctx, scope)` | `[]rbac.Assignment{UserID, Role}` in exactly `scope`, by user and role: its members |
| `rbac.UsersWith(ctx, scope, p)` | IDs of the users allowed `p` in `scope` (with global grants), sorted |

### Roles of the database

| API | Does |
|---|---|
| `rbac.CreateRole(ctx, role)` | Stores a role of declared permissions; `rbac.ErrRoleExists` (409), `rbac.ErrInvalidRole` (422: invalid name or title, a code role's name, super); users still holding a removed code role of the name lose it |
| `rbac.UpdateRole(ctx, role)` | Replaces its title and permissions; `rbac.ErrUnknownRole`, `rbac.ErrInvalidRole` for a code role |
| `rbac.DeleteRole(ctx, name)` | Deletes it and its assignments |
| `rbac.Roles(ctx)`, `rbac.FindRole(ctx, name)` | Every role, code's first; one role, code's or the database's |

### Commands

| Command | Does |
|---|---|
| `rbac:roles` | The roles, where they're defined, their users and permissions; warns of assigned roles that are neither declared nor stored, and of stored roles a code role replaces |
| `rbac:user <user-id>` | A user's roles and permissions by scope |
| `rbac:assign [--scope=team:42] <user-id> <role>` | Gives a role, globally without `--scope` |
| `rbac:unassign [--scope=team:42] <user-id> <role>` | Takes it away |


# AI reference

Source: https://docs.anetos.dev/reference/ai/

The API of package `ai`. See [Add AI to your app](https://docs.anetos.dev/guides/ai/index.md) for a
walkthrough, [AI](https://docs.anetos.dev/concepts/ai/index.md) for the design, and
[Configuration](https://docs.anetos.dev/reference/configuration/index.md#ai) for the `AI_*` settings.

## Setup

| API | Does |
|---|---|
| `ai.New(app, drivers...)` | `*ai.Client` from the `AI_*` settings, with the driver `AI_PROVIDER` names (`fake` is built in), in every context the app creates. Each tool call becomes an operation (`anetos.Operation{Kind: "tool"}`) |
| `ai.NewWithProvider(provider, defaults...)` | A client by hand; `defaults` (options) apply before each call's own. Logs to `slog.Default()` |
| `ai.WithClient(ctx, c)`, `ai.From(ctx)` | Put a client in a context; get it (`ai.ErrNoClient` if absent) |
| `c.Provider()` | The client's `ai.Provider` |
| `c.Fake(replies...)` | Replace the provider with an `*ai.Fake` (or add replies to it); for tests |
| `ai.Driver{Name, Open}` | A provider's driver: `Open(app, cfg) (ai.Provider, error)` reads its own settings; a provider that is an `io.Closer` is closed at shutdown |

## Calls

| API | Returns |
|---|---|
| `ai.Generate(ctx, prompt, opts...)` | `*ai.Result`: the answer after any tool calls |
| `ai.GenerateObject[T](ctx, prompt, opts...)` | `T, *ai.Result`: the answer decoded into T (a struct) and checked with its `validate` tags; one retry with the problems, then `*ai.OutputError` |
| `ai.Stream(ctx, prompt, opts...)` | `iter.Seq2[ai.Event, error]`: the call's events; breaking out stops it |
| `agent.Prompt(ctx, prompt, opts...)`, `agent.Stream(…)` | `Generate` and `Stream` with the agent's settings |

The prompt may be empty when `ai.Messages` gives the conversation.

## Options

Applied in order: the client's defaults, an agent's, the call's.

| Option | Does | Default |
|---|---|---|
| `ai.System(text)` | Adds system instructions; several are joined by blank lines, in the order the options come (an agent's `Instructions` where the agent is) | none |
| `ai.Model(name)` | The model, by the provider's name for it | `AI_MODEL` |
| `ai.MaxTokens(n)` | The longest answer, in tokens | `AI_MAX_TOKENS` |
| `ai.Temperature(t)` | Sampling temperature | the provider's |
| `ai.Timeout(d)` | Each request's timeout (in a stream, including the reader's time) | `AI_TIMEOUT` |
| `ai.Messages(msgs...)` | Adds the conversation before the prompt (a `Result`'s `Messages`) | none |
| `ai.Tools(tools...)` | Adds tools | none |
| `ai.MaxSteps(n)` | The most requests in a call with tools; then `ai.ErrMaxSteps`. `GenerateObject`'s retry is a second call, with its own limit | `ai.DefaultMaxSteps` (10) |
| `ai.ProviderOptions(v...)` | Drivers' own request options (types they define), added to the call's; each provider uses its own and ignores the others, so one call can carry options for each provider `AI_PROVIDER` may name (`Request.Options`, a `[]any`) | none |
| `ai.ForUser(userID)` | The user the call is for: its usage records and budget (`TrackUsage`) | the logged-in user, if any; a conversation's user |
| `ai.Using(c)` | Use client c, not the context's | the context's |
| an `ai.Agent` | Its settings | |

## `ai.Agent`

| Field | Type | Does |
|---|---|---|
| `Name` | `string` | Names it in logs (`agent=`) |
| `Instructions` | `string` | Its system instructions |
| `Tools` | `[]ai.Tool` | Its tools |
| `Model` | `string` | Its model; empty: the default |
| `MaxSteps` | `int` | 0: `ai.DefaultMaxSteps` |
| `Options` | `[]ai.Option` | More options, before each call's |

## Results

| Type | Fields and methods |
|---|---|
| `ai.Result` | `Messages` (the whole conversation: given messages, prompt, answers, tool results; after an error it can end with tool calls without results, which providers refuse to continue from), `Steps` (`[]*ai.Response`), `Usage` (the total); `Text()` (the last response's), `Response()` (the last) |
| `ai.Response` | `Message`, `Stop`, `Usage`, `Model` (that answered), `Raw` (the provider's own response); `Text()`, `ToolCalls()` |
| `ai.Usage` | `InputTokens` (including cached), `OutputTokens`, `CacheReadTokens`, `CacheWriteTokens`; `Add(u)` |
| `ai.Message` | `Role` (`ai.RoleUser`, `RoleAssistant`, `RoleTool`), `Parts` (`ai.Text`, `ai.ToolCall{ID, Name, Input}`, `ai.ToolResult{CallID, Name, Content, IsError}`, `ai.Reasoning{Provider, Text, Data}`: a model's reasoning its provider needs back, before the part it belongs to; other providers leave it out); `Text()` (the text parts only), `ToolCalls()`; JSON `{"role", "parts": [{"type": "text" \| "tool_call" \| "tool_result" \| "reasoning", …}]}`. `ai.UserMessage(text)`, `ai.AssistantMessage(text)` |

| `Stop` | Means |
|---|---|
| `ai.StopEnd` | The answer is complete |
| `ai.StopToolCalls` | It called tools |
| `ai.StopMaxTokens` | Cut off at `MaxTokens` (not an error for `Generate`; an `OutputError` for `GenerateObject`) |
| `ai.StopRefusal` | The model declined (an `OutputError` for `GenerateObject`, not retried) |
| `ai.StopOther` | A provider-specific reason (see `Raw`) |

## Stream events

| `Kind` | Field | When |
|---|---|---|
| `ai.EventText` | `Text` | A piece of the answer |
| `ai.EventToolCall` | `ToolCall` | The model called a tool |
| `ai.EventToolResult` | `ToolResult` | The tool's result |
| `ai.EventResponse` | `Response` | A model response is complete (one per step) |
| `ai.EventDone` | `Result` | Last, after a successful call |

An error is yielded once, and ends the stream.

## Tools

| API | Does |
|---|---|
| `ai.NewTool(name, description, fn)` | A tool running `fn func(ctx, In) (Out, error)`. In is a struct: its schema is the tool's input; the model's input is decoded (`*ai.InputError` if it doesn't fit) and validated before fn runs. Out is sent as JSON (a string type as is). Panics on a bad name (1–64 letters, digits, `_`, `-`), a non-struct In or bad tags. A panic in fn isn't recovered |
| `ai.Tool` | The interface: `Definition() ai.ToolSpec{Name, Description, Input}`, `Call(ctx, json.RawMessage) (string, error)` |

| A tool's error | The model gets | The call |
|---|---|---|
| A 4xx status (`web.StatusCoder`): `*ai.InputError`, `web.Error`, `auth.ErrForbidden`, `db.ErrNotFound`… | `IsError` result, what a web client would see: the status text; the message and fields of the `HTTPError` that has the status, or which input field has the wrong JSON type; else the field messages of a validation error in the chain | Continues |
| Any other | Nothing | Stops; returns `ai: tool <name>: <error>` |
| A name no tool has | `IsError`: "There is no tool named …" | Continues |

## Schemas

`ai.SchemaFor[T]()` builds `*ai.Schema` (JSON Schema, properties in field
order) from struct T, once per type:

| Go | JSON Schema |
|---|---|
| struct | `object` of its exported fields by `json` name, resolved as encoding/json does (`json:"-"` skips; embedded structs flatten, a shallower or tagged field hides others of its name, ambiguous ones are left out); `additionalProperties: false` |
| `string`, `bool` | `string`, `boolean` |
| integers, floats | `integer` (unsigned: `minimum: 0`), `number`; with `json:",string"`, `string` |
| slice, array | `array` of the element; `[]byte`: `string` |
| `map[K]V` (string, integer or text keys) | `object` with `additionalProperties` V |
| pointer | the element's type, or `null` |
| `time.Time` | `string`, `date-time`; other `encoding.TextMarshaler`s: `string` (their rules aren't in the schema) |
| `json.Number` | `number` |
| interface, `json.RawMessage` | any value |
| a type with its own `MarshalJSON` or `UnmarshalJSON` | an error: its shape can't be known |

| Tag | Adds |
|---|---|
| `description:"…"` | `description` |
| `validate:"required"` | the field to `required`, not `null`, and at least one character, item or key |
| `min`, `max`, `size`, `between` | `minLength`/`maxLength` (strings), `minimum`/`maximum` (numbers), `minItems`/`maxItems` (slices), `minProperties`/`maxProperties` (maps) |
| `in:a,b` | `enum` (of each element, on slices) |
| `email`, `url`, `uuid`, `date`, `datetime`, `ipv4`, `ipv6` | `format` (`email`, `uri`, `uuid`, `date`, `date-time`, `ipv4`, `ipv6`) |

Other rules aren't in the schema, but are checked on the answer.
Recursive types are an error.

## Errors

| Error | When | Web status |
|---|---|---|
| `ai.ErrNoClient` | No client in the context and no `ai.Using` | 500 |
| `ai.ErrMaxSteps` | The model still called tools at the last step | 500 |
| `*ai.BudgetError` (`UserID`, `RetryAfter`) | The call's user spent their budget; wrapped in a `*web.HTTPError` whose message tells them when to try again | 429 |
| `ai.ErrConversationChanged` | Another call added to the conversation during this one; nothing was stored | 409 |
| `*ai.OutputError` (`Type`, `Text`, `Stop`, `Err`) | `GenerateObject`'s answer was invalid twice, cut off, or refused; `Err` is a `*validate.Errors` for broken rules | 502 |
| `ai: <provider>: <error>` | The provider failed (wraps its error) | 500; 503 on a timeout |

## Conversations

| API | Does |
|---|---|
| `ai.Migrations()` | The `ai_conversations`, `ai_messages` and `ai_usage` tables, for `migrate.New` |
| `ai.StartConversation(ctx, userID, title)` | Stores a new `*ai.Conversation` of the user (an `AuthID`, up to 100 bytes) |
| `ai.FindConversation(ctx, userID, id)` | The user's conversation, else `db.ErrNotFound` (404) |
| `ai.Conversations(ctx, userID)` | The user's conversations, the latest changed first, without messages |
| `conv.Messages(ctx)` | Its messages, oldest first |
| `conv.Add(ctx, msgs...)` | Stores messages at the end, without calling a model (the user's question) |
| `conv.Prompt(ctx, prompt, opts...)`, `conv.Stream(…)` | `Generate` and `Stream` after its messages; the prompt and answers are stored if the call succeeds (before `EventDone`) |
| `conv.Reply(ctx, opts...)`, `conv.StreamReply(…)` | Answer its last message (the user's); stored the same way |
| `conv.QueueReply(ctx, agent)` | Answers its last message from a queue job, with the agent registered under `agent.Name`, as its user (`auth.WithUser`, with the abilities of the API token ctx was logged in with, if any); `Status` is `ai.StatusQueued`, then `""`, or `ai.StatusFailed` with `Error`. A retry runs the tools again; a job that finds the conversation changed does nothing. With the sync queue driver, it runs in the calling request, after its commit |
| `conv.Delete(ctx)` | Deletes it and its messages (its usage records stay) |
| `ai.QueueAgents(app, agents...)` | Registers the `ai.reply` job type on the app's queue, with the agents queued replies may use (by `Name`); needs `queue.New` first. Jobs time out after `AI_QUEUE_TIMEOUT` |

`ai.Conversation` fields: `ID`, `UserID`, `Title` (cut at 255 bytes), `Status`, `Error`,
`CreatedAt`, `UpdatedAt`. Calls on a conversation are for its user
(`ForUser`), and their usage records name it; `ai.Messages` options are
ignored.

## Streaming to the browser

| API | Does |
|---|---|
| `ai.SSE(c, events)` | Writes a stream (`ai.Stream`, `conv.StreamReply`…) as server-sent events, through `c.EventStream()` (no request or write timeout): `text` (a piece, HTML-escaped), `tool` (a tool's name), `error` (a 4xx error's message, else a general one; others are logged), then `done`, always last; a comment every 15 seconds keeps proxies from closing a quiet stream |

## Usage and budgets

| API | Does |
|---|---|
| `c.TrackUsage(ai.UsageConfig{Prices, Budget})` | Records each response in `ai_usage` and enforces budgets; call at startup. Budgets need the app's cache. Records are written with the call's context: inside a transaction that rolls back they go with it, so don't call models inside transactions |
| `ai.Price{Input, Output, CacheRead, CacheWrite}` | Per million tokens; cache prices of 0 charge `Input`. `p.Cost(usage)` |
| `UsageConfig.Prices` | `map[string]ai.Price` by model name: the response's model, else the requested one |
| `UsageConfig.Budget` | `func(ctx, userID) (ai.Budget, error)`, once per call with a user |
| `ai.Budget{Tokens, Cost, Per}` | Input and output tokens, or cost, per period (aligned to the clock: a day starts at midnight UTC); 0 for no limit. Checked before each request; a response can go past it, and so can requests running at the same moment, which each pass the check before any is charged. Changing a user's limit starts their count for the period over |
| `ai.UsageRecord` | A row of `ai_usage`: `UserID`, `ConversationID`, `Agent`, `Provider`, `Model`, the four token counts, `Cost`, `Estimated`, `CreatedAt`. A stream the reader left partway, or a request cut off by a timeout or a cancellation, is recorded and counted too, estimated at about four bytes a token for its input and the output it yielded (`Estimated`) |
| `ai.TotalUsage(ctx, userID, since)` | `ai.UsageTotal{Usage, Cost, Responses}` since a time |

## Embeddings

See [Search by meaning](https://docs.anetos.dev/guides/semantic-search/index.md).

| API | Does |
|---|---|
| `ai.Embed(ctx, texts, opts...)` | `[]ai.Vector`: the texts' embeddings as documents, with the client's embedding model (`AI_EMBEDDING_MODEL`), in requests of at most 96 texts. `ai.Dimensions(n)` asks for vectors of that size (the model's by default), and vectors of another size are an error; `ai.Using`, `ai.ForUser` and `ai.Timeout` apply as to `Generate`. Each request's usage is recorded (agent `embed`) and counts against budgets |
| `ai.EmbedQuery(ctx, text, opts...)` | The embedding of a query (what to find documents with), with `Embed`'s options |
| `ai.Vector` | `db.Vector`, a `[]float32` |
| `ai.Embedder` | `Embed(ctx, *ai.EmbedRequest) (*ai.EmbedResponse, error)`: the OpenAI (and compatible), Gemini and fake providers have it; Anthropic's doesn't. `EmbedRequest{Model, Inputs, Dimensions, Purpose}` (`ai.EmbedForDocument`, `ai.EmbedForQuery`); `EmbedResponse{Vectors, Usage, Model, Estimated}` |
| `ai.ErrNoEmbedder` | The client has no embeddings provider |
| `client.EmbeddingModel()`, `client.SetEmbedder(e, model)` | The embedding model's name; set the embeddings provider of a client made with `ai.NewWithProvider` |
| `ai.EmbeddingsFor(app, ai.EmbeddingsConfig[T]{Text, Dimensions, FixedSize, ChunkSize, Title, Scope})` | `*ai.Embeddings[T]`, which keeps the embeddings of `T`'s records in `<table>_embeddings` (`migrate.Schema.CreateEmbeddings`). `Text` is a record's text, `Dimensions` the vectors' size (the table's, which the model is asked for; with `FixedSize`, for models that make one size, only checked), `ChunkSize` the most characters in a chunk (2000), `Title` names records in the tool's results, `Scope` narrows every search (with the search's context). After `ai.New`; with the app's queue (`queue.New` first), registers the job `ai.embed:<table>`. Adds the command `ai:embed [table…]` |
| `e.Sync(ctx, rows...)` | Updates the rows' embeddings: in queue jobs of a hundred rows dispatched after the transaction commits, or right away without a queue (after the commit, inside a transaction) |
| `e.SyncNow(ctx, rows...)` | Updates them now: splits the text into chunks (paragraphs, sentences, words), embeds those whose text or model changed, and replaces the record's chunks. Not inside a transaction |
| `e.SyncAll(ctx)` | Deletes the chunks of deleted records (`db.PruneChunks`), then syncs every record, a hundred at a time (what `ai:embed` runs) |
| `e.Search(ctx, query, limit, scopes...)` | `[]ai.Passage[T]{Record, Text, Position, Distance}`: the records nearest the query, best first (at most `limit`; 10 for 0), with their nearest chunk; hybrid (`db.Q.Hybrid`) when the table has a search index, else `db.Q.Similar`; a blank query finds nothing. A record found only by its words has `Position` -1, the start of its text, and `Distance` 1 |
| `e.Tool(name, description, limit)` | An `ai.Tool` that searches: the model sends `{"query": …}` and gets a JSON array of `{"id", "title", "text"}` |

## Providers

| Package | `AI_PROVIDER` | Constructor | `Options` (for `ai.ProviderOptions`) | `Response.Raw` |
|---|---|---|---|---|
| `drivers/anthropic` | `anthropic` | `anthropic.Driver()`, `anthropic.New(key, opts...)` | `ThinkingBudget` (extended thinking), `Params func(*anthropic.MessageNewParams)` | `*anthropic.Message` |
| `drivers/openai` | `openai` | `openai.Driver()`, `openai.New(key, opts...)` | `ReasoningEffort`, `Params func(*openai.ChatCompletionNewParams)` | `*openai.ChatCompletion` (streams: `[]openai.ChatCompletionChunk`) |
| `drivers/openai` | `openai-compatible` | `openai.CompatibleDriver()`, `openai.NewCompatible(url, key, opts...)` | the same | the same |
| `drivers/gemini` | `gemini` | `gemini.Driver()`, `gemini.New(ctx, genai.ClientConfig{APIKey: key, …})` | `ThinkingBudget *int32`, `Params func(*genai.GenerateContentConfig)` (was `Config`, deprecated until v0.6) | `*genai.GenerateContentResponse` (streams: a slice of them) |

Each provider's `Client()` returns its SDK client. All use their API's
chat endpoint (OpenAI's: Chat Completions, which compatible servers
have) and the provider's structured output; the compatible provider
sends `max_tokens`, OpenAI's `max_completion_tokens`. Rate limits and
server errors are retried twice (by the Anthropic and OpenAI SDKs; the
Gemini driver turns the SDK's retries on). The Anthropic and compatible
providers send nothing from the SDKs' environment variables; OpenAI's
reads `OPENAI_ORG_ID`, `OPENAI_PROJECT_ID` and the like, which are
yours.

| Provider | JSON Schema it takes for structured output | Other rules |
|---|---|---|
| Anthropic (no maps or `any` fields: refused before sending; at most 24 optional fields and 16 nullable or union ones) | types, `enum`, `format`; nullable as `anyOf` | In the description |
| OpenAI (strict mode, when no maps or `any` fields) | types, `enum`; every property required, optional ones nullable | In the description |
| Gemini | types, `enum`, `format` (date-time, date, time), `minimum`, `maximum`, `minItems`, `maxItems`; nullable as `anyOf` | In the description |

Tool inputs get all of JSON Schema, except on Gemini (its dialect, as
above).

Embeddings: OpenAI's and compatible servers' Embeddings API
(`dimensions` when asked), and Gemini's (`RETRIEVAL_DOCUMENT` or
`RETRIEVAL_QUERY`, `outputDimensionality`; Gemini doesn't count tokens,
so its usage is estimated at four bytes a token). Anthropic has no
embeddings API: set `AI_EMBEDDING_PROVIDER`.

## Writing a provider

| API | Does |
|---|---|
| `ai.Provider` | `Name()`, `Generate(ctx, *ai.Request) (*ai.Response, error)`, `Stream(ctx, *ai.Request) iter.Seq2[ai.Event, error]` (`EventText`s and `EventToolCall`s, then one `EventResponse` with the whole response) |
| `schema.Map(ai.SchemaOptions{Keywords, Formats, AllRequired, NullableAnyOf})` | The schema as a `map[string]any` in the provider's dialect: the constraint keywords it takes (of `ai.ConstraintKeywords()`) and the string formats (all, if `Formats` is empty), the others in words in the description; every property required (optional ones nullable); nullable as `anyOf`. Properties keep their order when marshaled (a provider may still reorder them: Anthropic puts required ones first) |
| `aitest.Run(t, aitest.Config{Name, Model, KeyEnv, New, Dir, Skip, EmbeddingModel})` | The conformance suite (package `ai/aitest`): text, streams, a conversation, tool calls and their results (streamed too), structured output, the token limit, errors, and, with `EmbeddingModel`, embeddings (`Embed`). It replays recorded HTTP exchanges (`testdata/aitest/<Test>.json`) and checks the requests match; `ANETOS_AI_RECORD=1` records them from the provider (its key in `KeyEnv`; headers are never saved), `ANETOS_AI_LIVE=1` calls it without recording, `ANETOS_AI_UPDATE_REQUESTS=1` rewrites the recorded requests. `ANETOS_TEST_<NAME>_MODEL` (and `_EMBEDDING_MODEL`) picks the model to record with |
| `ai.Request` | `Model` (the drivers refuse an empty one), `System`, `Messages`, `Tools` (`[]ai.ToolSpec`), `Output` (`*ai.OutputSpec{Name, Schema}`: structured output), `MaxTokens`, `Temperature` (`*float64`), `Options` (`[]any`: drivers' own option values; a driver uses those of its types and ignores the others); `Prompt()` |
| `ai.Fake`, `ai.NewFake(replies...)` | The scripted provider, safe for concurrent use: `Add`, `Requests`, `Remaining`, `EmbedRequests` (its embedding requests: it embeds texts by their words, without replies); replies `ai.FakeText`, `FakeObject`, `FakeToolCall`, `FakeError`, or an `ai.FakeReply` function |
| `ai.FakeDriver()` | `AI_PROVIDER=fake` |


# Testing reference

Source: https://docs.anetos.dev/reference/anetostest/

The APIs of packages `anetostest` and `db/factory`, and the hooks
they use. See [Test your app](https://docs.anetos.dev/guides/testing/index.md) for a
walkthrough.

## Starting the app (`anetostest`)

| API | Does |
|---|---|
| `anetostest.New(t, setup, opts...)` | `*anetostest.App`: builds the app with `setup` (`func(*anetos.App) (*web.Server, error)`, or nil), boots it, runs its migrations, starts the test's transaction; closes the app when the test ends. Fails the test on any error. One per test or subtest: it reports to t |
| `anetostest.Env(map[string]string)` | Option: settings over everything else |
| `anetostest.WithoutMigrations()` | Option: don't run the migrations |
| `anetostest.WithoutTransaction()` | Option: don't wrap the test in a transaction; its writes are committed |
| `anetostest.LogLevel(level)` | Option: minimum level of the app's logs in the test's log. Default Info |
| `anetostest.FakeQueue()` | Option: dispatched jobs are recorded only (`queue.Queue.Fake`): not stored or run. Fails the test if `setup` has no queue |
| `anetostest.FakeEvents(events...)` | Option: events of the types of the values (all, with none) are recorded only (`events.Bus.Fake`): their listeners don't run. Fails the test if `setup` has no bus |
| `anetostest.FakePubSub()` | Option: published messages are recorded only (`pubsub.PubSub.Fake`): the broker doesn't get them. Fails the test if `setup` has no pub/sub |
| `anetostest.FakeAI(replies...)` | Option: the model's answers, one per request to the app's AI client, in order (`ai.FakeText`, `ai.FakeObject`, `ai.FakeToolCall`, `ai.FakeError`, or an `ai.FakeReply` function). Options add up. Fails the test if `setup` has no AI client (`ai.New`). See [AI](https://docs.anetos.dev/reference/anetostest/index.md#ai-anetostest) |
| `anetostest.FakeSocial()` | Option: social login (`auth/social`) logs in through a stand-in OpenID Connect provider on a local TLS server, for every provider (GitHub's API and other `Provider.Profile` functions aren't called); `social.Configured` keeps every provider, with test credentials where settings are missing. Log in with `app.SocialLogin` |
| `app.Context()` | The context of the test's requests: the app's services, the database and the test's transaction. Pass it to your own code. (It hides the embedded `anetos.App.Context(parent)`; call `app.App.Context` for that) |
| `app.Router()` | The app's `*web.Router`, or nil |
| `app.App` | The embedded `*anetos.App`: `app.Config()`, `anetos.Resolve[T](app.App)`, … |

### Settings

Highest priority first. `.env` is never read.

| Source | Holds |
|---|---|
| `anetostest.Env` | Whatever the test passes |
| Forced | `APP_ENV=testing`, a random `APP_KEY`, a `CACHE_PREFIX`, `SESSION_PREFIX`, `QUEUE_PREFIX` and `PUBSUB_PREFIX` of the app's own (its items, server-side sessions, Redis jobs and streams are removed by shutdown hooks when the app stops: at the end of the test, or when the test's `app.Run` returns); `MAIL_DRIVER=memory` (emails are kept in the mailer's `*mailer.MemoryTransport`, not sent); `STORAGE_DRIVER=memory` (files are kept in memory, on every disk without a driver of its own); `AI_PROVIDER=fake` (no model is called: `FakeAI` scripts the answers; `anetostest.Env` can set another) and an empty `AI_EMBEDDING_PROVIDER` (embeddings are `AI_PROVIDER`'s: the fake's) |
| Process environment | `DB_*` in CI, … |
| `.env.testing` | Next to the test's `go.mod`; optional |
| Defaults | `HTTP_ACCESS_LOG=false`, `APP_URL=http://example.test` (the test client's site), `MAIL_FROM_ADDRESS=test@example.com` |

With `DB_DRIVER` unset or `sqlite`, and `DB_NAME` and `DB_URL`
unset or empty in every source, `DB_NAME=:memory:` wins over all of
them: never the default `database/app.db`.

### Database

| Database | Each test gets |
|---|---|
| SQLite in memory (the default; checked with SQLite after connecting) | Its own database, migrated; no transaction, so `db.AfterCommit` callbacks run at once |
| SQLite file, PostgreSQL, MySQL | The migrated database, and a transaction rolled back when the test ends (`AfterCommit` callbacks run when a `db.Tx` inside it commits, or at once outside one). Each request runs in a savepoint (`anetostest_request`), rolled back if the request left the transaction failed. With `WithoutTransaction()`, neither |

## Requests (`anetostest`)

Every method returns a `*anetostest.Response`. Paths may have a query;
an URL on another site fails the test. Requests go to the router as
`http://example.test/…`, with:

- the jar's cookies (Path and expiry honored; Secure and Domain ignored);
- the headers set with `WithHeader`, which replace the method's `Accept`
  and `Content-Type`;
- as `Referer`, the last HTML page: a `GET` answered 200 with
  `text/html`, not an htmx fragment (`HX-Request` without `HX-Boosted`);
- for methods other than GET, HEAD, OPTIONS and TRACE, the session's
  CSRF token in `X-CSRF-Token`, unless the request has the header or
  (forms) a `_token` field.

| API | Sends | `Accept` |
|---|---|---|
| `app.Get(path)`, `app.Head(path)`, `app.Delete(path)` | No body | `text/html` |
| `app.PostForm(path, url.Values)`, `PutForm`, `PatchForm`, `DeleteForm` | URL-encoded form | `text/html` |
| `app.PostMultipart(path, url.Values, anetostest.Upload{Field, Filename, Content, ContentType}…)` | Multipart form: the fields, then the files | `text/html` |
| `app.GetJSON(path)`, `app.DeleteJSON(path)` | No body | `application/json` |
| `app.PostJSON(path, v)`, `PutJSON`, `PatchJSON` | v encoded as JSON | `application/json` |
| `app.Do(req)` | req (from `httptest.NewRequest` with a path), adding the jar's cookies it doesn't have, headers it doesn't have, `Referer` and token | req's |
| `res.Follow()` | GET to the redirect's `Location`; fails the test for another site | the request's |
| `app.WithHeader(name, value)` | Sets a header on every later request; returns app | |
| `app.WithSession(func(*session.Session))` | Changes the session later requests carry; returns app. Needs `session.New` in setup | |
| `anetostest.ActingAs(app, u)` | Logs u in for later requests, as a password login without remember-me would, without asking for a two-factor code (`auth.Auth.LoginSession`), replacing whoever was logged in (and dropping a remember-me cookie); returns app. U is the type given to `auth.New` (`*models.User`); needs `session.New` and `auth.New` in setup; a disabled user fails the test | |
| `app.Session()` | The `*session.Session` the next request will carry (flash values and errors from the last response included), to read | |
| `app.SocialLogin(redirect, anetostest.SocialAccount{ID, Email, EmailVerified, Name, AvatarURL})` | GET redirect (the app's route to the provider, such as `/auth/google/redirect`), the stand-in provider's login as the account, then GET the app's callback; returns the callback's response. Needs `FakeSocial`; `ID` is required | `text/html` |

## Responses (`anetostest.Response`)

Fields: `StatusCode`, `Header`, `Body []byte`, `Request`. Assertions
report failures with `t.Errorf` (naming the request, with the start of the
body) and return the response.

| API | Checks |
|---|---|
| `AssertStatus(code)` | The status |
| `AssertOK()`, `AssertCreated()`, `AssertNoContent()` | 200, 201, 204 |
| `AssertNotFound()`, `AssertForbidden()`, `AssertUnprocessable()` | 404, 403, 422 |
| `AssertRedirect(path)` | A 3xx to path (`http://example.test` dropped from `Location`) |
| `AssertRedirectRoute(name, args...)` | A 3xx to the named route |
| `AssertHeader(name, value)` | One of the header's values is value |
| `AssertSee(texts...)`, `AssertDontSee(texts...)` | The body contains (none of) the texts, as they are or HTML-escaped (`html.EscapeString`, or html/template's, which also escapes `+`) |
| `AssertJSON(v)` | The body is JSON equal to v, compared as JSON (numbers exactly, by value) |
| `AssertJSONPath(path, v)` | The value at path (`"data.0.title"`; `""` for the whole body) equals v, compared as JSON |
| `AssertValidationErrors(fields...)` | A 422 (or 400) problem JSON with the fields in `errors`, or a redirect with the fields' errors flashed to the session. No fields: any error. Send JSON requests to check a 422 |
| `AssertNoValidationErrors()` | Not a 422, not a 400 with field errors, no errors flashed |
| `AssertSessionHas(key, value?)` | The next request's session has key (holding value, compared as JSON) |
| `AssertSessionMissing(key)` | It doesn't |
| `JSON(&v)` | Decodes the body; fails the test if it can't |
| `Text()` | The body as a string |

## Database (`anetostest`)

Generic functions, run on `app.Context()`. Conditions are
`db.Expr`s: `PostCols.Title.Eq("Hello")`.

| API | Does |
|---|---|
| `anetostest.AssertDatabaseHas[T](app, conds...)` | A T row matches (soft-deleted rows excluded) |
| `anetostest.AssertDatabaseMissing[T](app, conds...)` | No T row matches |
| `anetostest.AssertDatabaseCount[T](app, n, conds...)` | n T rows match |
| `anetostest.AssertSoftDeleted[T](app, conds...)` | A soft-deleted T row matches; T embeds `db.SoftDeletes` |
| `anetostest.Create(app, factory)` | Inserts a row made by the factory; returns it |
| `anetostest.CreateMany(app, factory, n)` | Inserts n rows |

## Jobs, events, email and messages (`anetostest`)

`anetostest.New` records, from the end of `setup` on, what the app
dispatches, emits, mails and publishes, through the services' `Observe`
hooks, whether or not they are faked. `match` is a `func(T) bool`;
`nil` matches any. Assertions report with `t.Errorf` and list what was
recorded.

| API | Does |
|---|---|
| `app.Dispatched()` | `[]queue.Dispatched` (`ID`, `Job`, `Queue`, `Delay`, `Data`; `Decode(&v)`), every job, function jobs (`mail:send`, `event:…`) included, oldest first. A job is recorded once dispatched: when the store has it (the database driver writes it in the request's transaction: once that commits), with `AfterCommit` after the commit, with the sync driver before it runs; a dispatch that fails or is rolled back isn't recorded |
| `anetostest.Jobs[J](app)` | The `J` jobs dispatched, decoded. J must be registered (`queue.Register`); fails the test otherwise |
| `anetostest.AssertDispatched[J](app, match)` | A `J` job matches |
| `anetostest.AssertNotDispatched[J](app, match)` | None matches |
| `app.AssertNothingDispatched()` | No job of any type |
| `app.Emitted()` | `[]any`: every event, oldest first, recorded when `Emit` is called, before its listeners |
| `anetostest.Events[E](app)` | The events of type E (or implementing E, an interface) |
| `anetostest.AssertEmitted[E](app, match)`, `AssertNotEmitted[E]`, `app.AssertNothingEmitted()` | As for jobs |
| `app.Mail()` | `[]mailer.Record` (`Mailable`, rendered `Message`, `Queued`): emails sent with `mailer.Send` (once the transport took them) or queued with `mailer.Queue` (once the job is dispatched; with the sync driver, once the job sent it) |
| `anetostest.Mailables[M](app)` | The mailables of type M, sent or queued |
| `anetostest.AssertMailSent[M](app, match)` | An M sent with `mailer.Send` matches |
| `anetostest.AssertMailQueued[M](app, match)` | An M queued with `mailer.Queue` matches |
| `anetostest.AssertMailNotSent[M](app, match)` | No M sent or queued matches |
| `app.AssertNoMail()` | Nothing sent or queued |
| `app.Published()` | `[]pubsub.Published` (`Topic`, `Data`, `Attributes`; `Decode(&v)`), oldest first |
| `anetostest.Messages[T](app, topic)` | The messages of topic, decoded from JSON as T |
| `anetostest.AssertPublished[T](app, topic, match)`, `AssertNotPublished[T]` | A message of topic matches; none does |

The emails the transport got (queued ones the queue ran included) stay
available from the mailer: `anetos.MustResolve[*mailer.Mailer](app.App).Transport().(*mailer.MemoryTransport).Sent()`.

## AI (`anetostest`)

The app's AI client (`ai.New`) uses the fake provider in tests
(`*ai.Fake`): requests get the replies `FakeAI` scripted, in order, and a
request with no reply left fails with an error saying so. A test that
sets another `AI_PROVIDER` with `anetostest.Env` uses that provider,
unless it also uses `FakeAI`, which puts the fake in its place. The
fake makes embeddings too (`ai.Embed`, `ai.Embeddings`), without
replies: vectors of the texts' words, so texts sharing words are near,
of the size asked for (or, for a `FixedSize` model, the size expected).

| API | Does |
|---|---|
| `app.AI()` | The `*ai.Fake`: `Requests()` (`[]ai.Request`, oldest first: `Prompt()`, `System`, `Messages`, `Tools`, `Output`, `Model`…), `Add(replies...)` for more replies, `Remaining()`, `EmbedRequests()` (`[]ai.EmbedRequest`: `Model`, `Inputs`, `Dimensions`, `Purpose`). Fails the test if the app has no AI client, or its provider isn't the fake |
| `app.AssertPrompted(match)` | A request matched (`func(ai.Request) bool`; nil matches any); otherwise reports the last prompt |
| `app.AssertNotPrompted()` | No request was made |
| `ai.FakeText(text)` | Reply: text |
| `ai.FakeObject(v)` | Reply: v as JSON, the answer to `ai.GenerateObject` |
| `ai.FakeToolCall(name, input)` | Reply: a call of tool name with input (encoded as JSON); its result goes to the next request |
| `ai.FakeError(err)` | Reply: the request fails with err |

Replies' usage counts words, as a stand-in for tokens.

## Repeated queries (`anetostest`)

| API | Does |
|---|---|
| `app.RepeatedQueries()` | `[]db.RepeatedQuery` (`Operation`, `SQL`, `Count`, `Caller`; `String()`): the queries a request, job, listener, task or AI tool call of the test ran `DB_REPEATED_QUERIES` times or more (5 by default in tests), oldest first. Also logged as warnings |
| `app.AssertNoRepeatedQueries()` | None: no N+1. See [Find N+1 queries](https://docs.anetos.dev/guides/n-plus-one/index.md) |

## Files (`anetostest`)

| API | Does |
|---|---|
| `app.Disk(name...)` | `*anetostest.Disk`: the default disk, or the named one (`STORAGE_DISKS`). Fails the test without `storage.New`, for an unknown disk, or with more than one name |
| `d.AssertExists(paths...)` | The files exist |
| `d.AssertMissing(paths...)` | They don't |
| `d.AssertContent(path, want)` | The file exists with that content |
| `d.Files(prefix)` | The paths under prefix (`""`: all), in order |
| `d.Storage()` | The `*storage.Disk`, to add or read files |

## Clock (`anetostest`, `anetos`)

| API | Does |
|---|---|
| `app.Freeze(t)` | Stops the app's clock at t (now, for the zero time), truncated to microseconds; returns it |
| `app.Travel(d)` | Moves the clock by d (back if negative): a frozen clock stays frozen, a running one runs d ahead |
| `app.Unfreeze()` | Back to the system's time |
| `app.Now()`, `anetos.Now(ctx)` | The time on the app's clock (`anetos.Now` without an app in ctx: `time.Now()`) |
| `app.App.SetClock(fn)` | The hook underneath: the app reads the time from fn (nil: the system's clock) |
| `anetos.WithClock(ctx, fn)` | A context with its own clock, for code without an app |

Read from the app's clock: model timestamps (`created_at`, `updated_at`,
`deleted_at`); session lifetimes (whatever the store); the expiry of
the test client's cookies, password reset, verification and
remember-me tokens, API tokens (and their `last_used_at`), temporary
URLs signed with `APP_KEY`, social login state, and the memory cache's
items and locks; rate-limit windows; `after:now`-style validation
rules; emails' `Date`; memory disks' modification times. Not affected:
the clocks of database and Redis servers, which expire the items of the
database and Redis cache stores (rate-limit counters there included)
and time their queues; the clock of a store that signs its own URLs
(S3, which checks them in real time); queue delays and leases, in every
driver; timeouts and durations; the scheduler's and workers' loops;
log timestamps.

## Factories (`db/factory`)

| API | Does |
|---|---|
| `factory.New(func(n int) T)` | `*factory.Factory[T]`; n is a sequence number from 1, unique per factory (shared by the factories `With` derives) |
| `f.With(fns...)` | A new factory that also applies `func(*T)`s to every value |
| `f.Make()`, `f.MakeMany(n)` | Values, not saved |
| `f.Create(ctx)`, `f.CreateMany(ctx, n)` | Inserted with `db.Create` (hooks run), one row at a time; stops at the first error |

## Sessions (`session`)

| API | Does |
|---|---|
| `m.Load(r)` | The request's `*session.Session` as the session middleware would load it (a new one if the cookie is missing or invalid) |
| `m.Edit(r, fn)` | `(*http.Cookie, error)`: the cookie of the request's session after fn changed it. fn sees the session as a handler would; what was flashed for the next request is kept for it (`Reflash`) |
| `session.New`, `migrate.New` | Also provide the manager and the runner to the app (`anetos.Resolve`), which is how `anetostest` finds them |


# Upgrade guides

Source: https://docs.anetos.dev/upgrade/

One page per minor version before 1.0 (`v0.N.md`), listing every breaking
change with migration steps, newest first.

- [v0.5](https://docs.anetos.dev/upgrade/v0.5.md) (in progress), the first public release

## Before the first public release

v0.3 and v0.4 were tagged while Anetos wasn't yet announced. Their guides
stay for the few projects made with them:

- [v0.4](https://docs.anetos.dev/upgrade/v0.4.md)
- [v0.3](https://docs.anetos.dev/upgrade/v0.3.md)


# Upgrading to v0.5

Source: https://docs.anetos.dev/upgrade/v0.5/

v0.5 is in progress; this page lists its changes so far.

## Services are built with New

The services an app builds from its settings in `setup` are now made by
their package's `New`, the word Go uses for it; `ForApp` is gone from the
docs and stays only as a deprecated name until v0.6. `db.Connect` and
`redis.Connect` keep their names: they connect to a server.

| v0.4 | v0.5 |
|---|---|
| `cache.ForApp(app)`, `queue.ForApp(app)`, `session.ForApp(app)`… | `cache.New(app)`, `queue.New(app)`, `session.New(app)`… |
| `openapi.ForApp(app, srv, cfg)` | `openapi.Register(app, srv, cfg)` |

With Go 1.26 or later, `go fix ./...` rewrites these calls for you:

```sh
go fix ./...
```

It leaves `auth.ForApp` and `social.ForApp` alone (Go's inliner doesn't
yet rewrite calls to generic functions): change those two to `auth.New`
and `social.New` by hand.

`New` was already the name of each package's constructor from explicit
parts, without the app, which apps mostly use in tests. Those are
renamed, and `go fix` can't rewrite them: the compiler points at each
call.

| v0.4 | v0.5 |
|---|---|
| `cache.New(store, prefix)` | `cache.NewWithStore(store, prefix)` |
| `queue.New(store, cfg, …)` | `queue.NewWithStore(store, cfg, …)` |
| `pubsub.New(broker, …)` | `pubsub.NewWithBroker(broker, …)` |
| `mailer.New(transport, …)` | `mailer.NewWithTransport(transport, …)` |
| `storage.New(disk, …)` | `storage.NewWithDisks(disk, …)` |
| `ai.New(provider, …)` | `ai.NewWithProvider(provider, …)` |
| `events.New(…)` | `events.NewBus(…)` |
| `schedule.New(…)` | `schedule.NewScheduler(…)` |
| `i18n.New(cfg, …)` | `i18n.NewTranslator(cfg, …)` |
| `rbac.New(perms, roles…)` | `rbac.NewRegistry(perms, roles…)` |
| `encryption.New(key, previous…)` | `encryption.NewEncrypter(key, previous…)` |
| `auth.New(cfg, users, enc, …)` | `auth.NewWithConfig(cfg, users, enc, …)` |
| `social.New(a, resolve, url, creds, providers, …)` | `social.NewWithConfig(…)` |
| `session.New()` (an empty session, in tests) | `session.NewSession()` |

`go fix` needs code that compiles, tests included: rename the calls
`go vet ./...` reports first, then run `go fix ./...`. A project made by `anetos new`
calls only `ForApp`, so `go fix` and the two `auth`/`social` edits do
it.

A second `New` (or `db.Connect`) for the same app is now an error
(`cache: New called twice for one app`) where some packages used to open
a second connection or replace the first service. Code that needs a
service built elsewhere asks the app for it:
`anetos.Resolve[*cache.Cache](app)`. `encryption.New(app)` returns the
same encrypter every time.

## Settings with one name per idea

Every setting now starts with its area, and the one that picks a
backend is `<AREA>_DRIVER`. The former names are still read, with a
warning at startup and in `go run . doctor`, until v0.6:

| Before v0.5 | Since |
|---|---|
| `DB_CONNECTION` | `DB_DRIVER` |
| `DB_DATABASE` | `DB_NAME` |
| `DB_USERNAME` | `DB_USER` |
| `MIGRATE_ON_RUN` | `DB_MIGRATE_ON_START` |
| `MIGRATE_READINESS` | `DB_MIGRATE_READINESS` |
| `SEARCH_LANGUAGE`, `SEARCH_RANKING` | `DB_SEARCH_LANGUAGE`, `DB_SEARCH_RANKING` |
| `CACHE_STORE` | `CACHE_DRIVER` |
| `SESSION_LIFETIME`, `SESSION_MAX_LIFETIME` | `SESSION_TTL`, `SESSION_MAX_TTL` |
| `AUTH_REMEMBER_LIFETIME` | `AUTH_REMEMBER_TTL` |
| `QUEUE_POLL` | `QUEUE_POLL_INTERVAL` |
| `LOCALE_URL` | `APP_LOCALE_STRATEGY` |

Rename them in your `.env` files, the server's environment and the
deploy files (`deploy/production.env.example`, the systemd unit, the
Dockerfile, a Render or Fly file). In the project's folder:

```sh
for f in .env .env.example .env.testing Dockerfile deploy/*; do
  [ -f "$f" ] && sed -i.bak \
    -e 's/\bDB_CONNECTION\b/DB_DRIVER/g' -e 's/\bDB_DATABASE\b/DB_NAME/g' \
    -e 's/\bDB_USERNAME\b/DB_USER/g' -e 's/\bCACHE_STORE\b/CACHE_DRIVER/g' \
    -e 's/\bMIGRATE_ON_RUN\b/DB_MIGRATE_ON_START/g' \
    -e 's/\bMIGRATE_READINESS\b/DB_MIGRATE_READINESS/g' \
    -e 's/\bSEARCH_LANGUAGE\b/DB_SEARCH_LANGUAGE/g' \
    -e 's/\bSEARCH_RANKING\b/DB_SEARCH_RANKING/g' \
    -e 's/\bSESSION_MAX_LIFETIME\b/SESSION_MAX_TTL/g' \
    -e 's/\bSESSION_LIFETIME\b/SESSION_TTL/g' \
    -e 's/\bAUTH_REMEMBER_LIFETIME\b/AUTH_REMEMBER_TTL/g' \
    -e 's/\bQUEUE_POLL\b/QUEUE_POLL_INTERVAL/g' \
    -e 's/\bLOCALE_URL\b/APP_LOCALE_STRATEGY/g' "$f"
done
```

(`\b` needs GNU sed; on macOS, `brew install gnu-sed` and use `gsed`,
or rename them in your editor. `_` counts as a letter for `\b`, so
`QUEUE_POLL_INTERVAL` and `DB_SEARCH_LANGUAGE` aren't renamed twice.) The
image's `HTTP_ADDR=:8080` line can go too: the port is the default, and
a platform's `PORT` is used when `HTTP_ADDR` isn't set. The
fields of the config structs follow: `db.Config`'s `Connection`,
`Database` and `Username` are `Driver`, `Name` and `User`;
`cache.Config.Store` is `Driver`; `session.Config`'s `Lifetime` and
`MaxLifetime` are `TTL` and `MaxTTL`; `auth.Config.RememberLifetime` is
`RememberTTL`; `queue.Config.Poll` is `PollInterval`;
`migrate.Config.OnRun` is `OnStart`; `i18n.Config.URL` is `Strategy`, and
`i18n.URLNone`, `URLPrefix` and `URLSubdomain` are `StrategyNone`,
`StrategyPrefix` and `StrategySubdomain` (`go fix` rewrites those). Apps
rarely set these fields: the compiler points at any that do.

`go run . doctor` also points at a key in your `.env` files that is
another framework's name for a setting (`QUEUE_CONNECTION`,
`MAIL_MAILER`), a former name left beside its new one, or a typo of a
setting.

`app.Source()` now returns the app's own source, which records the keys
read: code that type-asserted it (to a `config.Map`, in a test) should
pass the map to `anetos.WithSource` and keep it instead.

## Logging in

The framework says "log in" and "log out" everywhere now, in its API,
the pages `make:auth` writes and the messages, where it used to say
"sign in" in some places. The old names stay, deprecated, until v0.6.

| v0.4 | v0.5 |
|---|---|
| `a.SignIn(ctx, u, remember)` | `a.Login(ctx, u, remember)` (see below) |
| `a.SignOutOthers(ctx, u)`, `a.SignOutEverywhere(ctx, u)` | `a.LogoutOthers(ctx, u)`, `a.LogoutEverywhere(ctx, u)` |
| `a.CanTwoFactor()`, `a.CanRemember()`, `a.CanSignOutEverywhere()` | `a.SupportsTwoFactor()`, `a.SupportsRemember()`, `a.SupportsLogoutEverywhere()` |
| `a.ActAs(ctx, id)`, `auth.ActAs(ctx, id)`, `auth.ActOption` | `a.WithUser(ctx, id)`, `auth.WithUser(ctx, id)`, `auth.UserOption` |
| `auth.ErrNoPendingSignIn`, `auth.ErrNoUser` | `auth.ErrNoPendingLogin`, `auth.ErrUserNotFound` |
| `*social.ErrNoAccount` | `*social.NoAccountError` |
| `app.SocialSignIn(redirect, account)` (anetostest) | `app.SocialLogin(redirect, account)` |

`go fix ./...` rewrites `auth.ActAs`, `auth.ActOption`,
`social.ErrNoAccount` and `app.SocialSignIn`. It doesn't rewrite the
methods of `*auth.Auth[U]` (a generic type, which Go's inliner leaves
alone so far) or the error variables; the linters flag them. In the
project's folder:

```sh
grep -rlE --include='*.go' 'SignIn\(|SignOut(Others|Everywhere)|Can(TwoFactor|Remember|SignOutEverywhere)\(|\.ActAs\(|ErrNoPendingSignIn|ErrNoUser\b' . |
  xargs -r sed -i.bak -E \
    -e 's/\.SignIn\(/.Login(/g' \
    -e 's/\.CanSignOutEverywhere\(/.SupportsLogoutEverywhere(/g' \
    -e 's/\.SignOut(Others|Everywhere)\(/.Logout\1(/g' \
    -e 's/\.Can(TwoFactor|Remember)\(/.Supports\1(/g' -e 's/\.ActAs\(/.WithUser(/g' \
    -e 's/ErrNoPendingSignIn/ErrNoPendingLogin/g' -e 's/ErrNoUser\b/ErrUserNotFound/g'
find . -name '*.go.bak' -delete   # once the diff looks right
```

(GNU sed and xargs; on macOS, `gsed` and `gxargs`.) Its `\.SignIn\(` also
matches a method of your own called `SignIn`: check the diff.

**`Login` now asks for the two-factor code.** For a user with two-factor
authentication on, `a.Login` returns `auth.ErrTwoFactorRequired` and the
login waits for a code at `AUTH_CHALLENGE_URL`, as `SignIn` did; it used
to log them in without one. The pages `make:auth` wrote call `Login`
only after registration, when no one has the code on, so they behave as
before. If your code calls `Login` for a user who may have it on, handle
the error as the login page does, or send them to the challenge page. A
user without a password who logs in through `Login` counts as having
confirmed their password lately, as with `SignIn`.

**The admin** says "Impersonate" where it said "Act as user", and
"Log out everywhere" where it said "Sign out everywhere"; that action's
URL is `…/actions/logout` (was `…/actions/sign-out`), and the audit log
records it as `user.logged_out_everywhere` (was
`user.signed_out_everywhere`): search for both in older entries.

**Messages.** Errors that tests compare by text say "log in" and
"impersonate" too: `auth: not logged in` (`ErrUnauthenticated`, was `auth:
not signed in`), `auth: user not found` (was `auth: no such user`),
`auth: no login waits for a code`, `auth: two-factor authentication is
on already` and `isn't on` (`ErrTwoFactorOn`, `ErrTwoFactorOff`), `auth:
not impersonating another user` (`ErrNotImpersonating`). The framework's messages (`i18n/locales/en.yaml`, the
`social_*` errors) say "log in". In a project, `make:auth`'s pages and
`locales/*/auth.yaml` are yours: they keep working as they are. To match
v0.5's pages and the translations of
[anetos.dev/locales](https://github.com/anetos-dev/locales), whose keys
changed, rename three keys, in the YAML files and the code that uses
them:

```sh
grep -rlE 'sign_in_(with|again|first)' app views locales |
  xargs -r sed -i.bak -E 's/sign_in_(with|again|first)/login_\1/g'
find app views locales -name '*.bak' -delete   # once the diff looks right
```

(`locales/` is embedded whole, `.bak` files included, so delete them.)

and replace "Sign in", "sign in" and "two-factor sign-in" in your pages
and `locales/en/auth.yaml` as you like. An API project's
`handlers.SignInResponse` is `LoginResponse` in new projects; yours can
keep its name.

## Commands and the project

**Command names.** The app's and the `anetos` tool's commands use one
form, `<group>:<action>` with a singular group, and an existing tool's
name where one has the command (`route:list`, `queue:work`). The old names still run, with a warning, until
v0.6: change them in scripts, CI and deploy files. (`gen` runs without
one: names may now be shortened while they stay unique, and `gen` is
`generate` shortened.)

| Before v0.5 | Since |
|---|---|
| `./app routes:list` | `./app route:list` |
| `./app plugins:list`, `./app plugins:env` | `./app plugin:list`, `./app plugin:env` |
| `./app lang:check` | `./app locale:check` |
| `./app schedule:run <task>` | `./app schedule:test <task>` |
| `go tool anetos gen [-check]` | `go tool anetos generate [--check]` |
| `go tool anetos lang:add`, `add lang` | `go tool anetos locale:add` |
| `go tool anetos make:admin:resource` | `go tool anetos make:admin-resource` |

`schedule:run` without a task is new: it runs the tasks due this minute,
once, for a crontab entry or a Kubernetes CronJob in place of a
long-running scheduler. `queue:work` and `schedule:work` are new names
for `run --only=worker` and `run --only=scheduler`. An app whose own
command has one of the new names (`queue:work`, `schedule:test`,
`schedule:work`, or a former name such as `routes:list`) now fails to
register it: rename yours.

`anetos generate` writes `Code generated by anetos generate` at the top
of `models_gen.go`: run it once after upgrading the tool, or
`generate --check` (in CI) reports the files as out of date. Change
`//go:generate go tool anetos gen` in `main.go` to `generate` (the old
line still works).

**`key:generate` writes `.env`.** It sets `APP_KEY` there when it is
missing or empty, and prints what it did on stderr, so the old
`go tool anetos key:generate >> .env` still works. A key that is set is
kept unless `--force`, which moves it to `APP_PREVIOUS_KEYS`. To print a
key for a server's environment, use `--show`:
`APP_KEY=$(go tool anetos key:generate --show | cut -d= -f2-)`.

**Route names.** `make:crud` names a resource's routes after its
handlers: `posts.create` and `posts.delete`, where it wrote
`posts.store` and `posts.destroy`, and `make:auth` names the token
routes `tokens.create` and `tokens.delete`. Routes you generated keep
their names: they are your code. Rename them only with every
`web.URL`, `web.MustURL` and `web.RouteIs` call that uses them; in an
API project, the route name is the OpenAPI operation ID, which clients
generated from `openapi.json` may use. The admin's own routes changed
the same way: its form is `admin.<resource>.new` (it was `.create`),
saving is `.create` (was `.store`), deleting `.delete` (was `.destroy`),
and its password confirmation's form posts to `admin.confirm.check`
(was `admin.confirm.store`). A link of yours to `admin.<resource>.create`
still resolves, to the list's URL: point it at `.new`.

**`make:auth`'s group of logged-in routes** is `loggedIn` in new
projects, in both stacks (it was `members` in a web project and `me` in
an API one). Yours keeps its name; the guides say `loggedIn`.

**`public/` is the web root.** New web projects serve the files of
`public/` at `/` (`public/robots.txt` at `/robots.txt`,
`.well-known/` too), after the routes; `public/static/` stays at
`/assets/`. In a project made before v0.5, embed the folder and add the
route:

```go
// illustrative
// public/public.go: replace "//go:embed static" and "var files embed.FS" with
//go:embed *
var Files embed.FS
// and use Files where it used files (fs.Sub(Files, "static")).

// routes/web.go, after the /assets route:
r.Static("/", public.Files)
```

`//go:embed *` embeds every file of `public/`, the top-level dotfiles
too (not served), and fails to build when a folder of it holds only
hidden files (a `uploads/.gitkeep`): give it a file, or keep it out of
`public/`.

**Commands that describe the app.** Every app has `about` and
`security:check`, and `migrate.New` adds `db:schema`: an app's own
command by one of these names is now refused at startup ("taken"); rename it. `route:list`,
`migrate:status`, `schedule:list`, `plugin:list` and `help` take
`--json`. `web.RouteInfo.Middleware` now has an entry for every
middleware of the route, each with its `Name`, not only those that
called `web.Documented`: code that counted its entries, or read the
first one as the first documented middleware, filters on `Security` or
`Responses` instead. `web.RouteInfo` also has `File`, `Line` and
`Public`: a test that compares `Routes()` with `reflect.DeepEqual`
clears `File` and `Line` first. `anetos.Finding` has a `Rule`, so
unkeyed literals (`anetos.Finding{anetos.Warning, "…"}`, which `go vet`
warns about) need the field names.

## Names across the API

The rest of the API now uses the words Go and web developers already
know. The old names stay, deprecated, until v0.6, and `go fix ./...` (Go 1.26 or
later) rewrites the calls to them:

| Before v0.5 | Since |
|---|---|
| `auth.DefaultHomeURL`, `mailer.BaseURL`, `mailer.DefaultFrom`, `i18n.WarnMissing` | `auth.WithDefaultHomeURL`, `mailer.WithAppURL`, `mailer.WithDefaultFrom`, `i18n.WithWarnMissing` |
| `storage.BaseURL`, `storage.Public`, `storage.SignWith` | `storage.WithBaseURL`, `storage.WithPublic`, `storage.WithSigner` |
| `admin.Title`, `admin.UserName` | `admin.WithDefaultTitle`, `admin.WithUserName` |
| `web.TrustedOrigins`, `gcs.ClientOptions`, `s3.Transport` | `web.WithTrustedOrigins`, `gcs.WithClientOptions`, `s3.WithTransport` |
| `postmark.BaseURL`, `HTTPClient`, `Stream` | `postmark.WithBaseURL`, `WithHTTPClient`, `WithStream` |
| `events.BusOption`, `audit.Option` | `events.Option`, `audit.TrackOption` |
| `session.NewContext`, `web.RouteFromContext`, `web.ClientIPFrom` | `session.WithSession`, `web.CurrentRoute`, `web.ClientIP` |
| `anetos.Unit`, `UnitFunc`, `app.StartUnit`, `AroundUnits`, `HasAroundUnits` | `anetos.Operation`, `OperationFunc`, `app.StartOperation`, `AroundOperations`, `HasAroundOperations` |
| `anetos.Roles`, `app.Supervisor().Roles()` | `anetos.ProcessTypes`, `ProcessTypes()` |
| `db.Untracked`, `db.TxWith`, `db.PruneTrashed`, `page.HasMore()` | `db.AllowRepeatedQueries`, `db.TxWithOptions`, `db.Prunable`, `page.HasNext()` |
| `t.UniqueLive(…)`, `.UniqueLive()` (migrations) | `UniqueWithoutTrashed` |
| `pubsub.MaxAttempts`, `cache.Forget` | `pubsub.Tries`, `cache.Delete` |
| `c.Events()`, `web.View(…)`, `s.String(key)` (a session) | `c.EventStream()`, `web.Render(…)`, `s.GetString(key)` |
| `r.HandleStd(method, pattern, h)` | `r.Get(pattern, web.WrapHandler(h))` (`go fix` writes `r.Handle(method, pattern, web.WrapHandler(h))`) |
| `ai.Func(name, description, fn)` | `ai.NewTool(name, description, fn)` |
| `admin.Field[T](title, column)` | `admin.TextColumn[T](column, label)`: the arguments the other way round: the column first, then its label |

`go fix` leaves calls whose type arguments Go infers, `ai.Func(…)` and
`admin.UserName(fn)`, and `page.HasMore()` (a method of a generic
type): rename those by hand. The validation rule `unique_live` is
`unique_without_trashed`: change it in your `validate` tags (the old
name works, with a warning, until v0.6), and rename a translation of
its message (`validation.unique_live`) with it.

**Interfaces you implement.** A user model's
`CommunicationLocale() string` (`i18n.CommunicationPreference`) is
`PreferredMailLocale() string` (`i18n.MailLocalePreference`), as
`PreferredLocale` and `PreferredTimeZone`; a storage backend's
`SignedURL` is `TemporaryURL` (`storage.TemporaryURLBackend`), as
`Disk.TemporaryURL`, and `storagetest.Features.SignedURLs` is
`TemporaryURLs`. The old methods are still used, with a warning, until
v0.6: rename them.

**Process types.** What `run --only` selects is a *process type*, the
word of Heroku's `Procfile`; "role" is left to roles and permissions.
Three changed names:

| Before v0.5 | Since |
|---|---|
| `run --only=http` | `run --only=web` (`serve` is unchanged) |
| `run --only=workers` | `run --only=worker` |
| `run --only=listeners` | `run --only=listener` |

`scheduler` stays. The old names still work, with a warning in the log,
until v0.6: change them in your `Dockerfile`, `fly.toml`, `Procfile`,
Compose and Kubernetes files, and your own components'
`anetos.ProcessTypes("workers")`. The supervisor's log line says
`process_types=` (it said `roles=`).

**Changes the compiler points at.** These have no deprecated copy:

- `web.ClientIP(r)` takes the request's context: `web.ClientIP(r.Context())`,
  or `web.ClientIP(c)` in a handler. Outside a `web.Router` (a handler
  of your own wrapping it), it returns "" without `RealIP`: use
  `r.RemoteAddr` there.
- `storage.From(ctx)` returns the default disk; a named one is
  `storage.DiskFrom(ctx, "avatars")` (was `storage.From(ctx, "avatars")`).
- An admin resource's fields take the usual admin-panel names:
  `PluralLabel` (was `Title`), `Label` (was `Singular`) and `RecordTitle` (was the function
  `Label`); a column's, action's, bulk action's, filter's and dashboard
  link's `Title` is `Label`.
- `db.Chunk.Model` is `EmbeddingModel`, `db.RepeatedQuery.Unit` is
  `Operation`, `schedule.Config.Timezone` is `TimeZone`, and
  `supervisor.Spec.Roles` and `ComponentStatus.Roles` are
  `ProcessTypes`.
- `gcppubsub.Driver(opts...)` takes its own options:
  `gcppubsub.Driver(gcppubsub.WithClientOptions(opts...))`. An `s3.Option`
  no longer changes the MinIO client's options: `s3.WithTransport` is
  the one there is.
- If you register a listener's options in a variable typed
  `events.Option`, it is now `events.ListenOption`.

The repeated-query warning's attribute is `operation=` (it was
`unit=`): update log queries that look for it.

## Shapes that changed

These changes have no deprecated copy: the compiler points at each.

| Before v0.5 | Since |
|---|---|
| `ai.Embed(ctx, 0, texts...)`, `ai.Embed(ctx, 768, texts...)` | `ai.Embed(ctx, texts)`, `ai.Embed(ctx, texts, ai.Dimensions(768))` |
| `ai.EmbedQuery(ctx, dims, text)` | `ai.EmbedQuery(ctx, text)` (with `ai.Dimensions(dims)` if it wasn't 0) |
| `ai.ConstraintKeywords` | `ai.ConstraintKeywords()` |
| `d.Watch(table, w, n)` | `d.Watch(table, w, db.WatchBulkValues(n))` |
| `ai.Request.Options` (`any`, in a provider of your own) | a `[]any`: range over it and take the values of your types |

`ai.Embed` and `EmbedQuery` now apply `ai.Using`, `ai.ForUser` and
`ai.Timeout`, which they ignored, so `AI_TIMEOUT` bounds each request
for embeddings too. In tests, `app.AI().Embeddings()` is
`EmbedRequests()` (`go fix` rewrites it). `ai.ProviderOptions` adds to the
call's options rather than replacing them, so the options of several
drivers can travel together. In the gemini driver, `Options.Config` is
`Params` (the old field works until v0.6).

**Behaviour.** `r.As("api.")` returns a router of its own, as `Group`
does, and leaves `r`'s route names alone: code that called `As` on a
router and then registered on that same router (not on `As`'s result)
must use the result. `HTTPError.Wrap` returns a copy instead of
changing the error (and the copy still matches it with `errors.Is`).
A plugin's `Listen(bus)` is `Listeners(bus)` (`Listen` is still called,
with a warning, until v0.6, but a `var _ ext.HasListeners =
(*Plugin)(nil)` check stops compiling until you rename it). A
`web.CSRFOption` of your own, written against
`*http.CrossOriginProtection`, no longer compiles: use
`web.WithTrustedOrigins`.

**Storage backends of your own** with temporary URLs
(`storage.TemporaryURLBackend`) must have their store serve HTML, SVG
and JavaScript as attachments (`Content-Disposition: attachment`, set
when `Put` stores such a file), as the s3 and gcs drivers do;
`storagetest` with `TemporaryURLs` now checks it.

**Removed** (nothing an app was meant to use): `db.WithTestTx`,
`db.SQLiteTimeFormat`, `db.SearchIndexesTable`, `db.Plural`,
`migrate.Runner.Command` and `migrate.Commands` (run `./app migrate`
and the other commands through `app.Execute`), the database drivers'
`DSN`, `storage.DiskSource`, `storage.AppConfig`, `ai.SearchResult`,
`ext.Info` and `postmark.Event`. `db.Dialect` can no longer be
implemented outside package db.

## Generated pages call views/ui

Since v0.5, `anetos new` writes `views/ui`, a package of components
(`ui.Card`, `ui.Field`, `ui.Button`…) that carries the markup and the
CSS framework's classes, and the layout and the pages that `make:crud` and
`make:auth` write call it instead of writing class names ([Style your
app](https://docs.anetos.dev/guides/styling/index.md)).

**A project made before v0.5** has no `views/ui`, and nothing changes
until a generator runs. The first `make:crud` or `make:auth` writes
`views/ui` before its pages, and says so: the starter theme's
components when `public/static/app.css` has the theme's `.card` rule,
else plain HTML without classes. Your stylesheet, layout and other
pages are left as they are, and the generators still find the header's
nav (`</nav>`) to add their links.

To build the layout from the components too (optional), compare
`views/layout.templ` with a new project's (`anetos new` in another
folder):

1. In `<head>`, replace the stylesheet's `<link>` with `@ui.Head()`.
2. Replace `<header class="topbar">…</header>` with
   `@ui.Header("Name", web.MustURL(ctx, "home")) { … }`, its nav with
   `@ui.Nav(label) { … }`, and keep `@AccountMenu()` after the nav's
   block.
3. Make `navLink` call
   `@ui.NavLink(web.MustURL(ctx, route), label, web.RouteIs(…))`.
4. Replace `<main class="container">` with `@ui.Main() { … }`, the
   flash's `<p class="flash">` with `@ui.Flash(ui.Success) { … }`, and
   the footer with `@ui.Footer() { … }`.

The theme's stylesheet from a new project styles `.flash` neutral and
adds `.flash.success` and `.info`: copy it too, or add those rules, if
your layout or pages use `ui.Flash`.

The generator also writes `views/ui/css.json`, which records the
components it wrote. Once the layout calls the components,
`anetos css:use <framework>` can switch the project to another CSS framework ([Style
your app](https://docs.anetos.dev/guides/styling/index.md#8-switch-css-frameworks)); it asks for `--force`
the first time, since your `app.css` isn't the one anetos wrote. It adds the menu
button's name, `nav.menu`, to `locales/en/app.yaml`.

## --css=none writes plain HTML

`anetos new --css=none` used to keep the starter theme's class names in
the markup, with an empty stylesheet. Its `views/ui` now writes plain
HTML without classes: add your own classes in `views/ui`'s components.
Projects made before are unchanged.


# Upgrading to v0.4

Source: https://docs.anetos.dev/upgrade/v0.4/

v0.4 adds the API stack. Most apps upgrade without code changes: update
the modules (`go get anetos.dev/anetos@v0.4.0`, and `cli`, `admin` and
the drivers you use to their v0.4.0), run the tests, and read the
changes below that apply.

## Routes can't be compared with ==

`web.RouteInfo` has a slice field (`Middleware`) and `web.Route` an
unexported one, so neither compiles in an `==` comparison. Compare the
fields you need:

```go
// illustrative
// before
routes[0] == web.RouteInfo{Method: "GET", Pattern: "/posts", Name: "posts.index"}
// after
routes[0].Method == "GET" && routes[0].Pattern == "/posts" && routes[0].Name == "posts.index"
```

## Middleware that returns a documented handler

`auth.Auth.Require`, `TokenMiddleware`, `rbac.Require`, `rbac.RequireIn`
and `ratelimit.Middleware` return the handler `web.Documented` makes,
which carries what the middleware asks for and may answer, rather than
an `http.HandlerFunc`. They serve the same; only code that asserts the
handler's type fails (`h.(http.HandlerFunc)` panics, the two-value form
is false). Use the `http.Handler` instead.

## JSON bodies with values of the wrong type

A JSON body whose values have the wrong type (`"title": 5`), or that a
field's type refuses (`"due": "tomorrow"` for an `anetos.Date`), is
answered with 400 "The request has invalid values." and every such
field in `errors`, under the key the client sent:

```json
{"type": "about:blank", "title": "Bad Request", "status": 400,
 "detail": "The request has invalid values.",
 "errors": {"due": "must be a date", "title": "must be text"}}
```

A bad date was "The request body is not valid JSON." without `errors`,
and only the first wrong type was listed. Body that isn't JSON at all
keeps "The request body is not valid JSON.". Update tests and clients
that expect the old answers.

## Tests stop when .env.testing is missing

`anetostest.New` stops a test when `.env` names a database server
(`DB_CONNECTION=postgres` or `mysql`) and the test settings name no
`DB_CONNECTION`, with no database named either: such tests ran on an
in-memory SQLite database, not the app's. Add `.env.testing` next to
`go.mod`:

```sh
DB_CONNECTION=postgres
DB_URL=postgres://app@localhost/app_test?sslmode=disable
```

or `DB_CONNECTION=sqlite` to keep testing on SQLite. See
[Use PostgreSQL or MySQL](https://docs.anetos.dev/guides/database/index.md).

## Smaller changes

| Change | What to do |
|---|---|
| `HTTP_CORS_EXPOSE` defaults to `X-Request-ID,Location,Retry-After,X-RateLimit-Limit,X-RateLimit-Remaining` (was `X-Request-ID`) | Nothing, unless browsers must not read those headers: set `HTTP_CORS_EXPOSE` |
| `auth.Require` sends `WWW-Authenticate: Bearer` with its 401 behind `TokenMiddleware` on routes that also have sessions | Nothing, unless tests expect no header |
| `plugins/postmark` v0.4.0 requires Anetos `>= v0.2.0, < v0.5.0` | Update it with Anetos |
| `anetos new` pins templ v0.3.1070 (was v0.3.1020) | Optional in existing apps: `go get -tool github.com/a-h/templ/cmd/templ@v0.3.1070`, then `go generate ./...` |

## Describing an existing API

Nothing in v0.4's API stack is required of an app made before it; to
use it on an existing API:

1. Put `web.JSONErrors` on the API's group (or `r.UseGlobal` in an app
   serving only JSON), so its errors are problem details whatever the
   client accepts ([Handlers](https://docs.anetos.dev/guides/handlers/index.md)).
2. Make the API's handlers typed (`web.H`) and give each route the
   status it answers: `.Status(http.StatusCreated)` on the ones that
   create, `web.Empty` for answers without a body
   ([Routing](https://docs.anetos.dev/guides/routing/index.md)).
3. Add an `openapi.Config` and `openapi.ForApp`, run `go run . openapi`,
   commit `openapi.json`, and add a test calling `openapi.Check`
   ([Describe an API with OpenAPI](https://docs.anetos.dev/guides/openapi/index.md)).

`make:auth` in an existing web app writes what it wrote in v0.3; its
API version is for projects made with `anetos new --stack=api`.


# Upgrading to v0.3

Source: https://docs.anetos.dev/upgrade/v0.3/

The breaking changes of v0.3, with what to do.

## A database session in local time stops the app

Times are stored in UTC, and the app now checks at startup that the
database session is in UTC too, so the database never writes local times
(`CURRENT_TIMESTAMP`, `NOW()`) next to the app's UTC ones.

**Before:** a `DB_URL` with a session time zone started:

```sh
DB_URL=postgres://app@db/app?timezone=Asia/Dhaka
```

**After:** the app and its commands stop with "the database session's
time zone is Asia/Dhaka, not UTC". Remove `timezone=` (PostgreSQL) or
`time_zone=` (MySQL) from `DB_URL`. For a legacy database whose times are
local, keep it and set:

```sh
DB_ALLOW_LOCAL_TIMEZONE=true
```

## The process's local zone is the app's

Importing Anetos sets Go's local zone (`time.Local`) to `APP_TIMEZONE`,
UTC when unset, whatever the machine's zone or `TZ`. `time.Now()`, log
lines and formatted times on a developer's machine in another zone now
show UTC. Set `APP_TIMEZONE` to keep a local zone; times are stored in
UTC either way. See [times and dates](https://docs.anetos.dev/guides/times-and-dates/index.md).

## Binding messages

A value that can't be converted to its field's type (`page=abc`) is
reported with the catalog's `binding.<kind>` message, in the request's
language, instead of the converter's text:

| Before | After |
|---|---|
| `"page": "invalid integer \"abc\""` | `"page": "must be an integer"` |
| `"draft": "must be a boolean"` (JSON) | `"draft": "must be true or false"` |

Clients that match these strings need the new ones; change them for
your app in a catalog (`binding.integer`).

## Translations in projects made before v0.3

`anetos make:auth` writes its text to `locales/en/auth.yaml` and needs a
`locales` folder. In a project made by an earlier `anetos new`, add it as
[Translations](https://docs.anetos.dev/guides/translations/index.md#2-load-them) shows: a
`locales/locales.go` embedding the folder, and
`i18n.ForApp(app, locales.FS)` at the start of `setup` in `main.go`.

Once `i18n.ForApp` is called, the HTTP server handles a `locale` query
parameter on page requests (a GET for HTML, not htmx) that names a
supported locale: it stores the choice in a cookie and redirects without
the parameter. A page route that reads its own `locale` parameter (a
filter of content by language) should use another name. API requests and
unsupported values reach your routes as before.

## A remote database is reached over verified TLS

Connections built from `DB_HOST` (PostgreSQL, MySQL) now use TLS and
check the server's certificate unless the host is this machine
(`DB_TLS=verify`). PostgreSQL connected with `sslmode=prefer` before,
which falls back to plain text; MySQL without TLS.

**After:** a server without TLS, or with a certificate signed by its
provider's own authority, refuses the connection (`x509: certificate
signed by unknown authority`). Set `DB_TLS_CA` to the provider's
certificate, or, on a private network you trust, `DB_TLS=skip-verify`
(encrypted) or `DB_TLS=none`. `DB_URL` is unchanged: its own options
decide. The production settings `anetos new` writes use
`sslmode=verify-full` for PostgreSQL's `DB_URL`.

## Security fixes that change behaviour

From the security review ([docs/security/checklist.md](https://github.com/anetos-dev/anetos/blob/main/docs/security/checklist.md)):

| Change | What to do |
|---|---|
| `X-Real-IP` is no longer read; the client's address comes from `X-Forwarded-For` sent by a proxy in `HTTP_TRUSTED_PROXIES` | A proxy that only sets `X-Real-IP` (nginx's `proxy_set_header X-Real-IP`): add `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;` |
| `web.MethodOverride` overrides only form posts (urlencoded or multipart), and never a cross-site one (`Sec-Fetch-Site`, or else an `Origin` other than the host) | A client that sent `_method` with another body: send the real method |
| Every app has a `doctor` command | An app command of your own named `doctor` panics at startup (`registered twice`): rename it |
| Search: at most 10 terms; a term matches as a prefix from 3 letters (`go` matches the word "go", not "golang"); on MySQL, short words InnoDB skips are dropped unless every word is | Nothing, unless tests expect the old matches |
| SQLite: double quotes are identifiers only (`_dqs=0`): `WHERE name = "ada"` fails | Use single quotes for strings in raw SQL |
| `auth.Require` sets `Cache-Control: no-store` on what it lets through | A route that set its own `Cache-Control` before the middleware: set it in the handler, after |
| The `log` mail driver leaves out the bodies in production | Use a real driver in production (`doctor` warns) |
| Local storage writes files 0640 and folders 0750 (were 0644 and 0755) | Another user that must read the files (a web server serving them directly): run the app with a group they share. The systemd unit `anetos new` writes keeps them to the app (`UMask=0077`, a dynamic user): serve files through the app |
| `anetos add` asks before running a plugin's code, in a terminal | Scripts are unaffected (no terminal); `--yes` skips the question |
| `anetos dev` answers 403 to host names other than localhost, IP addresses and `APP_URL`'s host | Another name (`myapp.test`): `anetos dev --host=myapp.test` |

## MySQL and MariaDB tables are utf8mb4

The tables the schema builder creates (`s.Create`) are now utf8mb4
even when the database's default character set isn't (MariaDB before
11.6 may default to latin1, which refuses most non-Latin text with
`Error 1366: Incorrect string value`). Tables created before v0.3 keep
their character set: `doctor` lists the ones with text columns in
another. Convert them before a new migration adds a string foreign key
to one of them (a utf8mb4 column can't reference a latin1 one: errno
150 on MariaDB, error 3780 on MySQL). Tables linked by string foreign
keys are converted together, with the checks off for the session:

```sql
SET FOREIGN_KEY_CHECKS = 0;
ALTER TABLE tags CONVERT TO CHARACTER SET utf8mb4;
ALTER TABLE post_tags CONVERT TO CHARACTER SET utf8mb4;
SET FOREIGN_KEY_CHECKS = 1;
ALTER DATABASE blog CHARACTER SET utf8mb4; -- for tables made with SQL later
```

Converting rewrites each table: on a large one, do it at a quiet time.
An indexed `VARCHAR` longer than 768 characters is too long for an
index in utf8mb4 (error 1071): shorten it first.

## The server waits for its migrations

With `migrate.ForApp`, the server reports itself unavailable
(`/health/ready` answers 503, `health:check` exits 1) while the
database has migrations the app hasn't run, and logs which; it becomes
ready within 5 seconds of `migrate`. A deploy that migrates before
starting the new version (systemd's unit, a release command, Render's
`preDeployCommand`) sees no change. One that starts the new version,
waits for it to be ready, and only then migrates would wait forever:
migrate first, or set `MIGRATE_READINESS=false`.

## Code that make:auth wrote before v0.3

Apps own the code `make:auth` writes, so the fixes to it don't reach
existing apps. Compare yours with a new project's (`anetos new` in a
scratch folder, then `make:auth`), and apply:

- **API tokens need a confirmed password.** In `routes/auth.go`, move
  `POST /tokens` (`tokens.store`) into the group with
  `a.RequireConfirmed`, and confirm the password in tests that create
  tokens (`/confirm-password`).
- **A reset revokes more.** `Reset` in `app/handlers/auth.go` changes
  the password only if it is still the one the link was made for (two
  uses at once change it once), revokes the API tokens, and, for an
  address never verified, verifies it and turns off two-factor sign-in
  and the Google and GitHub links. Copy the new function.
- `locales/en/auth.yaml`'s `password_changed` message says that API
  tokens keep working after a password change.

The library side needs nothing: `CreateToken` refuses while an admin
acts as the user, and two-factor codes and password confirmations are
checked safely, whatever your code.