Skip to content

Architecture Go

mavrovde edited this page Nov 2, 2026 · 3 revisions

Architecture: Go

The recommended candidate. This page describes how the language-neutral design on Architecture Overview would be built in Go. It is a design; nothing is implemented yet. Versions are those current at the time of evaluation and will be refreshed when work starts.

In short: one static binary built from net/http + huma v2 on chi v5 + pgx v5 + sqlc, organised as a hexagon around the domain. Keys, limits, quotas, priority admission and cache are in-process. The 2 second deadline is enforced with pgx's automatic cancel request plus a per-transaction statement timeout. Estimated 25–45 MB resident memory; image target 20 MB or less.

Stack

Concern Choice Why Alternatives rejected
HTTP standard library net/http timeouts, response controller, no framework runtime fasthttp (not net/http-compatible), Gin and Echo (OpenAPI bolted on)
Router chi v5 middleware groups (public, admin, operations); huma adapter the standard mux (weaker grouping)
API and OpenAPI 3.1 huma v2 code-first 3.1 from Go types, validation from tags, RFC 9457 model, operation extensions ogen and oapi-codegen (spec-first: a second source of truth), swaggo (older OpenAPI)
Driver pgx v5 with pgxpool real cancel request on context end; statement cache; batch and pipeline; query tracer database/sql with lib/pq (maintenance mode), GORM and ent (ORMs fight "views are the contract")
Queries sqlc typed Go from .sql, checked against the contract stub at generate time squirrel (no check), jet (needs a live database)
Access-store migrations goose, embedded plain SQL simple, custom version table golang-migrate, atlas
Configuration koanf v2 + validator v10 layering, unknown keys refused, bounds in tags, docs by reflection viper (lower-cases keys, ignores unknowns), env-only libraries
Rate limiting golang.org/x/time/rate Reserve() gives an exact Retry-After Redis-shaped limiters
Admission own small package priority, reserved shares, aging, wait estimate (the standard semaphore is FIFO only) —
Cache otter v2 byte weigher, per-entry expiry, loader with single-flight golang-lru (no expiry or weigher), ristretto (may drop writes)
Compression klauspost/compress gzhttp + brotli fast, minimum size, correct ETag suffixing standard gzip
Logs standard log/slog no dependency; attribute redaction hook zap, zerolog
Tracing and metrics OpenTelemetry Go, otelhttp, otelpgx; Prometheus client standard —
Geometry go-geom polyline decoding only; heavy geometry stays in PostGIS orb
Tests testing, testify, testcontainers-go (PostGIS), native fuzzing — —
Quality golangci-lint (depguard, gosec, forbidigo), govulncheck, oasdiff, Spectral — —
Documentation Scalar (static) + Astro Starlight guide — Redoc

Repository layout (planned)

viafrei-api/
├── cmd/viafrei-api/            # serve | migrate | keys | usage | config {check,show,docs} | openapi | version
├── internal/
│   ├── domain/                 # pure: standard library + geometry type only
│   │   ├── shared/ provenance/ places/ roads/ energy/ parking/ transit/ accessibility/ weather/ rules/
│   │   └── access/             # key, plan, scope, tier, the licence decision (a pure function)
│   ├── app/                    # one package per feature; ports only
│   ├── adapters/
│   │   ├── store/              # the ONLY code that knows the read contract (sqlc output, mapping tables, deadline execution)
│   │   ├── accessstore/        # keys, plans, audit, usage + migrations
│   │   ├── cache/              # result cache, freshness versions
│   │   └── httpapi/            # operations, DTOs, problems, GeoJSON, middleware
│   └── runtime/                # config, admission, ratelimit, metering, telemetry, lifecycle
├── contract/                   # the read-contract file and stub, delivered by the version-sync pull request
├── api/openapi.json  docs/  bench/  test/
└── Dockerfile  sqlc.yaml  .golangci.yml

Dependency direction: cmd → adapters → app → domain, and adapters → runtime. A depguard rule forbids the driver, the HTTP framework and the adapters inside domain and app.

// domain/roads/ports.go
type SituationReader interface {
    InCorridor(ctx context.Context, c Corridor, w shared.TimeWindow, f Filter) ([]RoadSituation, provenance.Set, error)
    History(ctx context.Context, r RoadRef, w shared.TimeWindow, cur Cursor, n int) (Page[Observation], provenance.Set, error)
}

Deadline and cancellation

pgx is configured so that, when a request's context ends, it sends a PostgreSQL cancel request at once and gives the connection a short grace period:

cfg.ConnConfig.BuildContextWatcherHandler = func(c *pgconn.PgConn) ctxwatch.Handler {
    return &pgconn.CancelRequestContextWatcherHandler{Conn: c, CancelRequestDelay: 0, DeadlineDelay: conf.DB.CancelGrace}
}
  • Each read runs as one batch: a read-only transaction, set_config('statement_timeout', <remaining ms>, true), the query limited to the allowed source families, commit. The server therefore stops on its own even if the client-side cancel were lost.
  • After release, a connection that is not idle is destroyed instead of being returned to the pool.
  • To confirm in the benchmark: the single-round-trip batch against an explicit transaction.

Keys

crypto/hmac with SHA-256 and constant-time hmac.Equal; secrets from crypto/rand; a small, fuzzed base62 codec. The key cache is an otter cache whose loader collapses concurrent first lookups into one. Revocations arrive through a PostgreSQL notification on a dedicated connection and evict the key at once.

Limits and admission

  • Rate limit: one rate.Limiter per key, held in a cache with idle expiry. If Reserve() reports a delay, the reservation is cancelled and the answer is 429 with Retry-After rounded up from the delay.
  • Admission: a mutex-guarded structure with three queues of waiters. Acquire grants, enqueues and waits on a channel or the context (removing itself on cancel), or refuses by estimate. Release runs the dispatch loop and updates the moving average of service time. Tested with the race detector and with a deterministic simulation on a fake clock.
  • Composed features: errgroup with a concurrency limit equal to the permits granted; each part has its own sub-deadline, and its error becomes the part's status.
  • Metering: atomic counters in a map, swapped and flushed by a ticker as one batched upsert.

Caching

otter with a byte weigher and per-entry expiry; xxh3 for ETag hashing; gzhttp suffixes ETags of compressed variants correctly.

Memory item (estimate) Size
Runtime and binary ~10–14 MB idle
Result cache 16 MiB (configurable)
Key cache a few MB
Connections about 1 MB each, client side

Estimated steady state 25–45 MB; container limit 128 MiB, with the Go soft memory limit set below it so the garbage collector tightens before the kernel intervenes.

OpenAPI and errors

  • huma generates OpenAPI 3.1, served at /openapi.json. Every operation is registered with its id, summary, description, tags, security requirement and the extensions for scope, source families and MCP counterpart.
  • A project problem type implements huma's status-error interface and emits application/problem+json with the project's type URIs.
  • Geometry passes through as raw JSON while the schema is still declared from DTO types.
  • application/geo+json is registered as a second response content type.

Configuration

The configuration struct is the declaration: tags carry the key, default, bounds and description. Defaults, then a YAML file, then environment variables; every loaded key is checked against the set reflected from the struct; all violations are printed together. Secret fields use a type whose string, JSON and log forms are <redacted>. config docs generates the reference by reflection. See Configuration.

Testing and CI specifics

  • testcontainers-go with PostGIS for mapping, role, cancellation and query-plan tests; httptest and humatest for handlers; libopenapi-validator on every recorded response; Schemathesis against the booted container.
  • Native go test -fuzz for cursors, keys, polylines, parameters and the YAML loader.
  • go test -race -shuffle=on; -coverpkg=./... in the unit and integration runs, and a boot smoke (go build -cover, GOCOVERDIR, go tool covdata textfmt) for every main; the three profiles are merged by internal/testkit/covergate, which fails any package below 100 % (TST-001). Branches that cannot fail by construction go through internal/invariant (Must, Check) instead of an unreachable error return.
  • golangci-lint, govulncheck, CodeQL for Go.
  • release-please with the Go release type.

Container image

Multi-stage build, CGO_ENABLED=0, trimmed and stripped, version information injected at build time; final stage distroless/static as a non-root user, pinned by digest. Image target 20 MB or less compressed; CI scans the layers for secrets.

Risks

Risk Mitigation
A second toolchain beside the platform self-contained repository with its own CI; the contract file is the only coupling
AI-agent fluency high for Go; strict linting, small packages, generated plumbing (sqlc, huma)
huma has a small maintainer team standard OpenAPI output and plain handler functions make a move mechanical
Garbage collection under a tight limit Go soft memory limit, byte-bounded cache, verified in the benchmark
Licence matrix not yet signed off the gate defaults to deny; families are enabled one at a time

Relative effort

Estimated somewhat less than the Rust design and close to the TypeScript design, which is faster for the first features and slower for the store adapter's cancellation path. See Stack Comparison.

Sources

huma https://huma.rocks · chi https://pkg.go.dev/github.com/go-chi/chi/v5 · pgx https://pkg.go.dev/github.com/jackc/pgx/v5 · sqlc https://docs.sqlc.dev · goose https://pressly.github.io/goose/ · koanf https://github.com/knadh/koanf · validator https://pkg.go.dev/github.com/go-playground/validator/v10 · rate https://pkg.go.dev/golang.org/x/time/rate · otter https://maypok86.github.io/otter/ · gzhttp https://pkg.go.dev/github.com/klauspost/compress/gzhttp · OpenTelemetry Go https://opentelemetry.io/docs/languages/go/ · otelpgx https://github.com/exaring/otelpgx · testcontainers-go https://golang.testcontainers.org/modules/postgres/ · Go fuzzing https://go.dev/doc/security/fuzz/ · libopenapi-validator https://github.com/pb33f/libopenapi-validator · golangci-lint https://golangci-lint.run · govulncheck https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck · distroless https://github.com/GoogleContainerTools/distroless · PostgreSQL cancel protocol https://www.postgresql.org/docs/16/protocol-flow.html#PROTOCOL-FLOW-CANCELING-REQUESTS

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally