Forge Idiomatic Engineer

# API Reference

This reference provides a comprehensive guide to Forge macros, context types, configuration options, and error variants.

## Macro Attributes

Forge handlers are defined using Rust macros that generate necessary structs and registration logic.

> Scaffold a new handler with `forge new <kind> <name>` (e.g. `forge new query list_invoices`). It writes the file with sane defaults, appends `pub mod <name>;` to `src/functions/mod.rs`, and inserts `mod functions;` in `src/main.rs` if missing. Kinds: `query`, `mutation`, `job`, `cron`, `workflow`, `daemon`, `webhook`, `mcp_tool`, `model`, `enum`.

### `#[forge::query]`
Defines a read-only operation. The macro generates a `{PascalCase}Query` struct and implements the `ForgeQuery` trait. All private queries must explicitly filter results by the current user or owner unless the `unscoped` attribute is used.

| Attribute | Description and Rationale |
|---|---|
| `name = "x"` | Overrides the default wire name (derived from the function name). |
| `public` | Skips JWT validation entirely — anonymous callers allowed. `ctx.auth.user_id()` returns `None`. Use for login pages, public APIs, landing data. |
| `unscoped` | JWT still required; skips the compile-time `user_id`/`owner_id` filter rule. Use for admin or shared data that any authenticated user may read. |
| `consistent` | Forces the query to read from the primary database to ensure data consistency after a recent write. |
| `require_role("x")` | Returns a 403 Forbidden error if the user lacks the specified role. |
| `cache = "30s"` | Enables a per-identity cache with the specified TTL to reduce database load. |
| `timeout = "30s"` | Sets the maximum execution time. Accepts duration strings: `"30s"`, `"5m"`, `"1h"`. |
| `rate_limit(requests = N, per = "1m", key = "user")` | Configures rate limiting. `key` values: `"user"`, `"ip"`, `"global"`, `"tenant"`, `"user_action"`, `"custom(claim_name)"`. |
| `description = "..."` | Adds a human-readable description to the function metadata. |
| `log = "info"` | Sets the log level for handler execution. |
| `tables("foo", "bar")` | Manually specifies table dependencies to trigger reactive cache invalidation. |

### `#[forge::mutation]`
Defines a data-modifying operation. The macro generates a `{PascalCase}Mutation` struct and implements the `ForgeMutation` trait.

| Attribute | Description and Rationale |
|---|---|
| `name = "x"` | Overrides the default wire name (derived from the function name). |
| `public` | Skips JWT validation entirely — anonymous callers allowed. Use for login endpoints and unauthenticated signups. |
| `unscoped` | JWT still required; skips the compile-time `user_id`/`owner_id` filter rule. Use for admin mutations that operate across all users. |
| `require_role("x")` | Restricts access to users with the specified role. |
| `transactional` | Wraps the entire operation in a PostgreSQL transaction. **Default: on.** Opt out with `transactional = false` for high-throughput writes that don't need atomicity. Cannot be disabled when using `dispatch_job()` or `start_workflow()`. |
| `timeout = "30s"` | Sets the handler timeout. Accepts duration strings: `"30s"`, `"5m"`, `"1h"`. |
| `max_size = "200mb"` | Defines the maximum allowable request body size for this mutation. |
| `rate_limit(requests = N, per = "1m", key = "user")` | Configures rate limiting. `key` values: `"user"`, `"ip"`, `"global"`, `"tenant"`, `"user_action"`, `"custom(claim_name)"`. |
| `description = "..."` | Adds a human-readable description to the function metadata. |
| `allow_http` | Permits `ctx.http()` calls inside a transactional mutation (normally a compile error). |

### `#[forge::job]`
Defines an asynchronous background task. These tasks are durable and automatically retried upon failure.

**Queue model**: PG-backed (`forge_jobs` table). Workers claim with `FOR UPDATE SKIP LOCKED`, ordered `priority DESC, scheduled_at ASC`. Concurrency bounded by a semaphore (`max_concurrent`, default 8). Sy