How-To Guides
How-To Guides
Section titled “How-To Guides”These guides are practical recipes. Each one targets a single task, shows the minimum code needed to accomplish it, and links to the relevant module primer when you need the boundary rationale behind the pattern.
They assume you have already completed Getting Started and can run the reference service. If you are new to the project, finish the first-day path on Docs Home before choosing a guide.
Available guides
Section titled “Available guides”Stable-root patterns
Section titled “Stable-root patterns”| Guide | What it shows |
|---|---|
| Add JWT Auth | Wire security/jwt + middleware/auth for token-protected routes |
| Write Custom Middleware | Implement a middleware.Middleware constructor with explicit deps |
| Connect a Database | Inject a store primitive into handlers without app-level globals |
| Handle Errors | Use contract.WriteError and NewErrorBuilder for structured responses |
| Graceful Shutdown | Wire OS signal handling with Prepare / Server / Shutdown |
| Health and Readiness | Implement ComponentChecker and wire /healthz + /readyz |
| Structured Logging | Use log.NewLogger, WithFields, and Fields in handlers |
| Testing Handlers | Test http.HandlerFunc handlers with httptest.NewRecorder |
Extension capabilities
Section titled “Extension capabilities”| Guide | What it shows |
|---|---|
| Integrate AI | Wire x/ai provider, manage sessions, and stream completions via SSE |
| Build a REST Resource | Use x/rest for full CRUD with pagination, filtering, and a SQL repository |
| Multi-Tenancy | Resolve tenant identity, enforce policy, and scope queries with x/tenant |
| Real-Time with WebSockets | Upgrade connections, manage rooms and hubs, broadcast messages with x/websocket |
| File Uploads and Downloads | Wire x/fileapi handlers for multipart upload, streaming download, and file metadata |
Operations and lifecycle
Section titled “Operations and lifecycle”| Guide | What it shows |
|---|---|
| Deploy with Docker | Multi-stage Dockerfile, env-var configuration, Kubernetes health probes |
| Observability Integration | Prometheus metrics, structured logging, distributed tracing via x/observability |
| Migration and Upgrades | Stable root upgrade path, tracking experimental-to-stable promotion |
How these guides are scoped
Section titled “How these guides are scoped”Each guide shows one correct pattern and stops there. They do not try to cover every option or configuration knob — the module primers and module.yaml files in the source tree do that. If a guide’s code and a module’s module.yaml ever disagree, the module.yaml is the authoritative source.
Stable-root guides do not introduce x/* extensions into the canonical service path. Operations guides reference x/observability where it is the correct home for the capability — each such reference links to the extension primer for the boundary rationale.