Recipes

Practical solutions for common API development tasks using ergo. Each recipe follows a Problem → Solution → Explanation structure with working code examples for both standalone composition and declarative ergo-router configuration.

Available Recipes

Recipe	Problem
Pagination	Offset and cursor pagination with RFC 8288 Link headers
Testing Patterns	Reliable HTTP testing with ephemeral ports, auth, validation, rate limiting, conditional requests, and graceful shutdown
Custom Headers	Adding response headers from middleware and execute handlers
Error Handling	Custom error responses, extension members, and correlation IDs
File Upload	Handling multipart file uploads with size limits and parsed content
Multi-Auth Strategies	Per-route auth overrides, optional auth, and API key authentication
PATCH Semantics	RFC 7386 merge-patch and RFC 6902 JSON Patch with strict enforcement
Sub-Routers	Organizing routes into sub-routers with per-group middleware and auth
Graceful Shutdown	Server lifecycle with database connections and resource cleanup
Debug Tracing	Finding which middleware rejected a request using pipeline debug mode
Mixed-Auth CORS & CSRF	Configuring CORS and CSRF together for browser and token-based clients
Custom Middleware	Writing middleware that fits ergo’s accumulator-based return-value contract
Structured Logging	Integrating pino or winston with ergo’s logger() and graceful() log surfaces
OpenAPI Serving	Serving the OpenAPI spec and mounting an interactive API explorer

When to Use Recipes vs. Middleware Guides

• Middleware guides document individual middleware — options, return values, error responses, and per-middleware usage examples.
• Recipes solve cross-cutting problems that involve multiple middleware or patterns that don’t belong to a single middleware page.