Examples

Runnable code, not fragments: every snippet in this section is a real file in v2/examples/ that compiles as part of the module, so it cannot drift away from the API it demonstrates.

Service skeleton

The shape of one service from boot to shutdown — building the App from the configuration that is actually set, one binary that can be an API or a worker, starting everything and stopping it in the right order, probes, configuration that fails at boot, logging that reports each incident once, and tests that exercise all of it.

• Coming up — What a process reads before it serves anything, and what it should refuse to start without.
• Roles and lifecycle — What this process is for, how everything starts, and the order it has to stop in.
• Operating it — What the service says about itself while it runs, and how the whole thing is exercised in a test.

HTTP

A tour of the HTTP layer — the server and its deadlines, binding a request and validating it in one call, the errors a client gets back, list endpoints, middleware, bearer-token auth, and files in and out.

• Serving a request — The three things every endpoint does — come up on a port, turn a request into a value you can trust, and answer a failure in a way the caller can act on.
• Shaping what comes in — Lists, guards and uploads — the three places where the request carries something the endpoint must bound before it acts on it.
• Who is calling — One middleware over a pluggable verifier: what changes between a JWT service and an API-key service is the verifier, not the routes.

Database

A tour of the SQL stack — models, the generic repository, relations and the N+1 between them, transactions, pagination, batching, and the connections underneath it all.

• Models & CRUD — What a model is, what it is not, and the four operations everything else is built out of.
• Relations & transactions — The two places where correct-looking code is wrong: a query set that grows with the number of rows, and a write that was never in the transaction it appears to be in.
• Once the table is big — Everything that was fine at a thousand rows and is not fine at ten million: deep OFFSET, unbounded FindAll, and a single pool doing all the reading.

MongoDB

A tour of the MongoDB support — connecting, the driver layer, the typed repository and its aggregation builder, indexes, change streams and transactions.

• Connecting and the driver layer — What a connection is, what a document type has to declare, and the thin helpers over the official driver that everything else is built on.
• The typed repository — mongorepo.Repo[D] is the layer most code should use: typed operators, copy-on-write chains, and a pipeline builder that composes with them.
• Schema, streams and consistency — The parts that depend on the server rather than on the code: what indexes exist, what a replica set makes possible, and what a transaction is actually for.

Cache

A tour of the cache — values and TTLs, counters and rate limits, distributed locks, cache-aside with Remember, invalidation, and what changes when there is no redis at all.

• Storing values — What goes in, what comes back, and the two operations that are not plain "store this" — a write that only happens when nothing is there, and a counter whose window is its own TTL.
• Coordination — The one thing in this section that is not about speed: making a piece of work happen once across every replica of a service.
• Patterns and testing — Cache-aside as one call, keeping the copy from going stale, and proving both in a test that needs no redis.

Jobs

A tour of the job runner — scheduled jobs, manual triggers with parameters, queueing, cancellation, concurrency limits, replay and log policies.

• Basics — Defining a job and giving it typed input — the two things every job needs before anything else applies.
• Controlling execution — What happens when runs pile up, when one has to be stopped, and when the same work needs to happen again.
• Running in production — The parts that matter once the jobs are someone else's to operate: what gets written down, what survives a restart, and what operators can see.

Message Queue

A tour of the RabbitMQ integration — publishing with confirms, topology declared at boot, consuming with the right acknowledgement, retry that actually waits, and a transactional outbox.

• Sending — What a publish guarantees, what it does not, and the topology that decides whether anybody ever reads the message.
• Receiving — The handler, the acknowledgement it implies, and what to do with a failure that will not fix itself in the next millisecond.
• When the message is money — Closing the last gap between "the row is committed" and "somebody was told about it".

Pub/Sub

A tour of redis publish/subscribe — publishing, the handler-based subscriber, raw subscriptions, and the three jobs fan-out with no acknowledgement is genuinely the right tool for.

• Both ends — Publishing something worth publishing, and the two ways to receive it.
• What it is actually for — The shapes that fit, and the line where pub/sub stops being the right answer.

Storage

A tour of object storage — structured keys, streaming uploads, reading and listing, temporary links that keep large files out of the service, and the arrangement that keeps a bucket and a database agreeing.

• Getting bytes in and out — The two halves of the job, and the decisions inside each that are much easier to make once than to fix later.
• Handing out access — A presigned URL moves the transfer out of the service entirely, and moves a security decision into a TTL.
• Keeping the bucket honest — What a bucket cannot answer on its own, and what to assert in a test that has no bucket at all.

AI

A tour of the AI capability — text generation, typed values instead of text to parse, streaming to a browser, tools the model calls, agents that run as jobs, embeddings, and how to test all of it without a provider.

• Generating — The three shapes a generation comes in: text for a person to read, a Go value for code to use, and a stream for a user who is waiting.
• Letting the model act — Tools turn a generation into something that can read and change data, which makes the ceiling and the approval gate part of the feature rather than an afterthought.
• Retrieval and tests — Vectors for search, and the fixtures that let every example above be tested without an API key.

Integrations

Everything a service talks to that is not its own database: other people's HTTP APIs, SMTP, Firebase, and the CSV files humans exchange.

• Calling other services — Outgoing HTTP carries the caller's deadline and trace, which is why it is a function of a context rather than a method on one.
• Reaching people — Mail and push are both slow, both fail, and neither degrades quietly — which is why both belong in a job and both ship with a memory implementation to assert on.
• Files people exchange — The format a spreadsheet writes, read and written without holding the whole file.