README
¶
gorbital
Go APIs, ready for orbit.
Website · Documentation · Quickstart · Changelog · Roadmap
gorbital is a Go library and a CLI, orb, that write a production API into your repository: PostgreSQL, sign-in with 2FA and passkeys, API keys, organisations, background jobs, email, feature flags, audit logs, observability and ops endpoints. The code it writes is plain Go that you read, change and own. The parts that must stay correct, such as password hashing, sessions and OAuth, live in the library, so security fixes reach you with go get.
Your app keeps building if you uninstall orb.
Status
v0.1.0 is the first public release. Everything in the roadmap marked done is in it.
v0 carries no compatibility promise: a minor release may change the API, and when it does, the changelog and upgrade notes say what to do. The compatibility checks already run on every change. v1.0.0 freezes the API and starts the scaffold compatibility promise, and it ships only after the external security review signs off (stability).
Install
You need Go 1.26 or later and Docker.
go install gorbital.dev/cli/cmd/orb@latest
orb goes into $(go env GOPATH)/bin. If your shell says command not found: orb, add that directory to your PATH and open a new terminal.
To use the library without the CLI:
go get gorbital.dev@latest
Quickstart
orb new my-api --preset full --tenancy single
cd my-api
orb dev
orb dev starts PostgreSQL and a mail catcher in Docker, runs migrations and seed data, then starts your API and the Dev Portal. It prints the seeded administrator's password and 2FA key once. In a terminal, orb new starts orb dev for you.
| Open | What |
|---|---|
| http://localhost:8080/docs | Your API's reference, with "Try it" |
| http://127.0.0.1:3100 | The Dev Portal: requests, logs, email, jobs, database and configuration |
| http://127.0.0.1:8025 | Mailpit: every email sent in development |
The Quickstart walks through it with the real output. If something goes wrong, see Troubleshooting.
What it decided for you
- Plain Go. Standard
net/httpandlog/slog, constructors instead of a DI container, no reflection wiring. You give up the conveniences of a heavier framework. - PostgreSQL only. Jobs, sessions, rate limits, settings and audit logs live there too. There's no Redis, Kafka or SaaS to run. No MySQL, no SQLite: if that rules you out, it rules you out.
- You own the code. A layered structure with one folder per domain module.
orb upgrademerges template changes on a branch and never overwrites your edits silently. You also maintain what's generated. - Security in the library. Argon2id passwords, sessions, OAuth, TOTP and passkeys are versioned packages, not copied code. When you upgrade the library, you take on its changes.
- Operations from day one. Health and readiness checks, OpenTelemetry, Prometheus metrics, runtime settings, feature flags, maintenance mode, incidents and an ops API guarded by roles and 2FA.
Presets
| Preset | What you get |
|---|---|
| Minimal | HTTP server, configuration, structured logs, tracing, health checks, security headers, OpenAPI docs, development-only dev console APIs. No database. |
| Full | Everything in Minimal, plus PostgreSQL, background jobs, email through Resend or SMTP, sign-in with email and password, Google, Apple and GitHub, 2FA, passkeys, roles and permissions, API keys and service accounts, runtime settings, feature flags, idempotency keys, file storage, audit logs, live observability and incidents, and the ops API. With --tenancy multi: organisations, members, invitations and optional row-level security. |
Modules
The root module holds the small core. Everything that brings a dependency is its own module, so your app only downloads what it uses. All modules share one version.
| Import path | What it does |
|---|---|
gorbital.dev |
Core: httpx, config, health, actor, audit, mail, page, ratelimit, requestid, buildinfo, app |
gorbital.dev/modules/postgres |
pgx pool with tracing, transactions, migrations, row-level security context |
gorbital.dev/modules/auth |
Passwords, sessions, one-time codes, 2FA, passkeys, social sign-in, API keys |
gorbital.dev/modules/orgs |
Organisations, memberships and invitations for multi-tenant apps |
gorbital.dev/modules/jobs |
Background jobs on PostgreSQL with River |
gorbital.dev/modules/settings |
Runtime settings with defaults, bounds and per-organisation overrides |
gorbital.dev/modules/flags |
Feature flags with targeting and percentage rollouts |
gorbital.dev/modules/auditpg |
Audit events stored and queried in PostgreSQL |
gorbital.dev/modules/idempotency |
Safe retries of POST and PATCH with Idempotency-Key |
gorbital.dev/modules/ratelimitpg |
Rate limits shared across instances |
gorbital.dev/modules/observability |
Request, error and latency windows across instances, and incidents |
gorbital.dev/modules/releases |
Which build every instance runs |
gorbital.dev/modules/storage |
File storage on local disk or S3-compatible buckets, plus the log archive |
gorbital.dev/modules/telemetry |
OpenTelemetry tracing and metrics, logs correlated with traces, Prometheus |
gorbital.dev/modules/openapi |
Huma on the standard http.ServeMux, problem+json errors, API docs |
gorbital.dev/modules/devconsole |
Development-only /_dev APIs for the Dev Portal |
gorbital.dev/modules/mail/resend |
Email through Resend, with bounce and complaint webhooks |
gorbital.dev/modules/mail/smtp |
Email through any SMTP server |
gorbital.dev/modules/mail/suppressionpg |
The email suppression list in PostgreSQL |
gorbital.dev/cli |
The orb command |
API reference for every package: pkg.go.dev/gorbital.dev.
Documentation
- Start: What you need, Quickstart, Your first resource, Concepts
- Sign-in: Overview, Every key and credential
- Build and run: Architecture, Life of a request, Environment variables, Testing, Running in production
- Keep up to date: Upgrading, Upgrade notes, Stability
- Why it's built this way: Decision records, Roadmap
Everything is also at docs.gorbital.dev. The full index is docs/README.md.
Contributing
Read CONTRIBUTING.md before opening a pull request. Larger changes start with a decision record. GOVERNANCE.md explains who decides, and the Code of Conduct applies everywhere.
Security
Don't report vulnerabilities in public issues. SECURITY.md says how to report them privately and which versions get fixes. The threat model and internal security review are public.
License
gorbital is licensed under the Apache License 2.0. See NOTICE.
gorbital is provided "as is", without warranty of any kind, express or implied, including the warranties of merchantability, fitness for a particular purpose and non-infringement. You are responsible for deciding whether it suits your use, including production, security-sensitive and regulated workloads. In no event shall the authors, contributors or copyright holders be liable for any claim, damages or other liability arising from the software or its use. The License's Sections 7 and 8 govern.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package actor records who is performing an operation, in a context.Context.
|
Package actor records who is performing an operation, in a context.Context. |
|
Package app runs an application's long-running work and shuts it down in a defined order.
|
Package app runs an application's long-running work and shuts it down in a defined order. |
|
Package audit defines audit events and the Recorder contract that any module uses to record who did what to which resource, and whether it worked.
|
Package audit defines audit events and the Recorder contract that any module uses to record who did what to which resource, and whether it worked. |
|
Package buildinfo reports the version, commit and build time of the running binary, from Go build information or a version set at link time.
|
Package buildinfo reports the version, commit and build time of the running binary, from Go build information or a version set at link time. |
|
cli
module
|
|
|
Package config provides configuration helpers for the composition root of a gorbital app: a Secret type that never leaks into logs or output, and environment lookup with *_FILE support for mounted secrets.
|
Package config provides configuration helpers for the composition root of a gorbital app: a Secret type that never leaks into logs or output, and environment lookup with *_FILE support for mounted secrets. |
|
gorbital
module
|
|
|
Package health serves liveness and readiness endpoints.
|
Package health serves liveness and readiness endpoints. |
|
Package httpx provides the HTTP foundation of a gorbital app: a server that runs under app.Run with safe timeouts, security middleware, and the RFC 9457 problem+json error contract with an application-owned error mapping (ADR-0018).
|
Package httpx provides the HTTP foundation of a gorbital app: a server that runs under app.Run with safe timeouts, security middleware, and the RFC 9457 problem+json error contract with an application-owned error mapping (ADR-0018). |
|
ipfilter
Package ipfilter refuses requests by client address with 403 ip_not_allowed (ADR-0085):
|
Package ipfilter refuses requests by client address with 403 ip_not_allowed (ADR-0085): |
|
timeout
Package timeout gives each request a deadline and answers 503 request_timeout when the handler hasn't started its response by then (ADR-0085):
|
Package timeout gives each request a deadline and answers 503 request_timeout when the handler hasn't started its response by then (ADR-0085): |
|
Package mail defines email messages and the Sender contract implemented by provider modules such as mail/resend and mail/smtp (ADR-0025).
|
Package mail defines email messages and the Sender contract implemented by provider modules such as mail/resend and mail/smtp (ADR-0025). |
|
modules
|
|
|
auditpg
module
|
|
|
auth
module
|
|
|
devconsole
module
|
|
|
flags
module
|
|
|
idempotency
module
|
|
|
jobs
module
|
|
|
jwt
module
|
|
|
mail/resend
module
|
|
|
mail/smtp
module
|
|
|
mail/suppressionpg
module
|
|
|
observability
module
|
|
|
openapi
module
|
|
|
orgs
module
|
|
|
postgres
module
|
|
|
ratelimitpg
module
|
|
|
releases
module
|
|
|
settings
module
|
|
|
storage
module
|
|
|
telemetry
module
|
|
|
Package page provides cursor pagination and sorting for list endpoints: bounded limits, opaque cursors and allowlisted sort fields.
|
Package page provides cursor pagination and sorting for list endpoints: bounded limits, opaque cursors and allowlisted sort fields. |
|
Package ratelimit provides token-bucket rate limiting keyed by a string (an IP address, account or API key): the Taker interface, an in-memory Limiter, and HTTP middleware.
|
Package ratelimit provides token-bucket rate limiting keyed by a string (an IP address, account or API key): the Taker interface, an in-memory Limiter, and HTTP middleware. |
|
Package requestid generates, validates and carries request IDs in a context.Context, so HTTP middleware, logging, audit and jobs share one correlation value (ADR-0030).
|
Package requestid generates, validates and carries request IDs in a context.Context, so HTTP middleware, logging, audit and jobs share one correlation value (ADR-0030). |
|
Package webhook verifies signed webhook requests: an HMAC-SHA256 signature over the raw body, and optionally a delivery ID and a timestamp checked against a replay window (ADR-0085).
|
Package webhook verifies signed webhook requests: an HMAC-SHA256 signature over the raw body, and optionally a delivery ID and a timestamp checked against a replay window (ADR-0085). |