go-atlas

Production-ready Go building blocks for distributed systems — transport, caching, observability, auth, secrets, and more.

Overview

go-atlas is a modular Go toolkit for distributed services. Each package is usable on its own and covers one concern: transport (HTTP, gRPC, NATS), caching, observability, authentication, secret management, configuration, and domain utilities.

Every major component is defined by an interface, implementations are injected via functional options, and unset dependencies default to safe no-ops. Import the packages you need; applications own construction and lifecycle. See the architecture for dependency and state ownership contracts.

History. go-atlas started in 2022 as an internal company project and ran in production for several years before it was extracted and open-sourced on GitHub. As a result, the public git history begins at the point of import rather than at the project's actual inception.

On AI tooling. Yes, we use AI assistants on this project — deliberately and with purpose. Every change is reviewed, tested, and held to the same standards as hand-written code. AI accelerates well-understood work; it does not replace design decisions or engineering judgment.

Requirements

• Go 1.26+

Installation

go get github.com/altessa-s/go-atlas

Import only the packages you need:

import "github.com/altessa-s/go-atlas/data/cache"

The root go.mod declares every integration go-atlas supports (OPA, AWS, GCP, Vault, NATS, Redis, and more), so all of them appear in a consumer's go.sum. Go's build graph is per-package: only the packages you actually import are compiled and linked into your binary. Heavy integrations live behind their own subpackages, so an unused subsystem costs you go.sum entries — never build time or binary size.

Package Overview

Package	Description
auth/audit	Authorization decision audit trail — durable, structured allow/deny events with pluggable sinks
auth/denylist	Token revocation denylist (JWT ID or subject), permanent or TTL-bound, consulted by verifiers
auth/jwt	Generic JWT signing and verification toolkit shared by the auth packages
auth/mtls	Verified mTLS client certificate to authenticated principal, with pluggable validators
auth/oauth2client	OAuth2 token acquisition: client credentials, refresh, auth code, RFC 8693 exchange
auth/oidc	OIDC/JWT validation with JWKS auto-refresh, CEL rules, token revocation
auth/opa	Open Policy Agent with bundle hot-reloading
auth/principal	Canonical verified-identity type: subject, tenant, scopes, roles, raw claims
auth/scope	Deny-by-default scope authorization policy with gRPC and HTTP adapters
auth/selfjwt	Self-issued JWT minting and verification with per-subject keys and rotation
auth/spiffe	SPIFFE ID parsing from X.509 certificates for workload identity
auth/static	Static token / API-key validator for service-to-service auth
config	Configuration structs and validation for all go-atlas components
config/loader	Multi-source config loading (YAML/TOML, env vars, secrets) with validation
config/templates	Commented YAML configuration templates for the config structs
core	Collections, concurrency, errors, context, encoding, retry, WAL, scheduling, types (stdlib-first; narrow platform and semaphore dependencies)
data/audit	Async audit-event dispatcher with pluggable storage
data/cache	Multi-backend caching with singleflight, fallback, and TTL management
data/filter	CEL expression parser with translators for MongoDB, ClickHouse, MariaDB, PostgreSQL, Meilisearch, RediSearch, and Lua
data/idempotency	Idempotency key management (Redis, NATS, MongoDB, memory)
data/keyset	Signed stateless page tokens for keyset pagination (HMAC, key rotation, TTL)
data/leadelect	Leader election (NATS KV-based)
data/limiters	Token-bucket rate limiting (Redis, NATS, memory)
data/locks	Distributed locking (NATS, MongoDB, SQL)
data/meilisearch	Meilisearch SDK wrapper with context propagation and sentinel-error classification
data/mongo	MongoDB repository patterns, cursor pagination, CSFLE, migrations
data/orderby	AIP-132 order_by DSL parser with translators for MongoDB, ClickHouse, MariaDB, PostgreSQL, Meilisearch, RediSearch
data/projection	AIP-157 fields parser that pushes field selection down to storage: MongoDB projections and ClickHouse, MariaDB, PostgreSQL column lists
data/outbox	Transactional outbox (MongoDB, PostgreSQL, MySQL, MariaDB)
data/probfilter	Bloom and Cuckoo probabilistic filters
data/retryqueue	Durable retry queue: one record per key, due list, backoff, expiry, generation fencing (memory, MongoDB)
data/saga	Orchestration-based saga engine: sequential steps, compensating rollbacks, crash recovery
domain/behavior	Struct-tag field_behavior strip for Create / Update / Response payloads
domain/converter	Generic struct-to-struct conversion with codecs and lazy iterators
domain/eventbus	Synchronous, lock-free, transaction-safe in-process event bus for decoupling domains
domain/fieldtracker	Struct field change tracking
domain/money	Currency amounts with exact decimal arithmetic, minor-unit rounding, allocation without losing a minor unit, and exchange rates (normalize, invert, cross, convert)
domain/normalizer	Tag-driven data normalization with pluggable modifiers
domain/proto	Protobuf field mask, field_behavior-driven payload sanitization, enum codec (enumcodec) and google.type converters (googletype)
domain/validation	ISO 7064 MOD 11-10 check-digit computation and validation
infrastructure/clickhouse/factory	ClickHouse connection setup and lifecycle
infrastructure/meilisearch	Meilisearch client setup and lifecycle
infrastructure/mongo	MongoDB client setup and lifecycle
infrastructure/nats	NATS connection management
infrastructure/redis	Redis client setup
observability/appstats	CPU, memory, network I/O, and goroutine metrics with periodic logging
observability/health	Health check coordinator with subscriptions
observability/metrics	Prometheus metrics via interface-driven adapters
observability/slog	slog extensions: nil-safe helpers, colorized and PII-masking handlers
observability/tracing	Distributed tracing (OpenTelemetry, OTLP, console) with samplers
plugins	Dynamic .so plugin manager with signature verification and sandboxing
security/hmacsign	Webhook-style HMAC body signing and verification (Stripe/GitHub scheme) with key rotation
security/sealbox	AES-256-GCM sealing of secrets at rest with a rotating keyring and associated data
security/secrets	Generic secret manager with LRU cache, watch, and scheduler refresh
security/tlsutils	TLS helpers, OCSP stapling, Let's Encrypt (Certify), Vault-backed certs
security/vault	HashiCorp Vault client (AppRole, token, userpass auth)
service/dispatch	Generic non-blocking batching dispatch engine with optional WAL persistence
service/id	Service identity (ULID/UUID) from env, file, or static
service/scheduler	Distributed cron scheduler with priority queues and leader election
transport/broker	Message broker abstraction (NATS JetStream, outbox)
transport/broker/idempotency	Consumer deduplication middleware over at-least-once broker delivery
transport/clientip	Real client IP resolution behind trusted reverse proxies, shared by the HTTP and gRPC realip stages
transport/grpc	gRPC server, interceptors, factory, gRPC client
transport/http	HTTP server, middlewares, codec registry, HTTP client
transport/proxydial	Forward-proxy dialers (HTTP CONNECT, SOCKS5) for non-net/http clients
proto	Protobuf definitions and generated Go code for gRPC services

Command-line tools

Tool	Description
tools/codegen/optgen	Code generator for the functional options pattern
tools/codegen/goconfig	Configuration file converter (YAML, TOML, .env, Markdown)
cmd/plugin-sign	Sign and verify .so plugins with Ed25519 / ECDSA / RSA-PSS

cmd/optgen and cmd/goconfig are equivalent installable wrappers around the tools/codegen packages.

Documentation

Guide	Description
Architecture	Package structure, layering, and design principles
Coordination & Consistency	Choosing between eventbus, uow, outbox, broker, and saga; the dual-write problem; how they compose
Saga	Saga orchestration: model, status lifecycle, crash recovery, diagrams, and examples
Configuration	Multi-source config loading, env vars, secrets
Self-Issued JWT	Per-subject JWT minting and fail-closed verification, key rotation, verification-key cache
Static Tokens	API-key / pre-shared token validation, HMAC-SHA256 storage, failure-only rate limiting
OPA Authorization	Rego policy evaluation, pluggable sources (embed/fs/GitLab/S3), atomic hot-reload, events
Health	Coordinator, HTTP probes (/healthz, /readyz), gRPC grpc_health_v1
Logging (slog)	slogx helpers, context-scoped loggers, handler chain (buffered, colorized, leveled, masking, multi, prefixed)
Plugins	Dynamic plugin loading, signature verification, sandboxing
Proxy	Outbound HTTP/gRPC proxy: YAML modes, wiring, TLS to proxy
Metrics Reference	Prometheus metrics across toolkit subsystems
Field Behavior	Strip google.api.field_behavior fields (OUTPUT_ONLY / IDENTIFIER / IMMUTABLE / INPUT_ONLY) from Create / Update / Response payloads
Event Bus	In-process event bus: delivery & transaction semantics, the uow post-commit compensation companion, pluggable database backends

Engineering guides

Opinionated engineering guidance for services built on the toolkit: general practice plus the team's default choices.

Guide	Description
Concurrency and Consistency Patterns	In-process concurrency, database-level locking, distributed coordination, outbox/idempotency/saga, overload protection
Message Brokers and Queues	Choosing a broker, delivery semantics and ordering, NATS/Kafka/RabbitMQ and alternatives, reliability patterns
Observability	Correlation, metrics, logs, tracing, alerting and SLOs, dashboards, probes, new-service checklist
Performance and Profiling	Latency metrics, pprof, execution traces, benchmarks, GC tuning, PGO, load testing, investigation checklist

Full API documentation is available at pkg.go.dev.

Development

git clone https://github.com/altessa-s/go-atlas.git
cd go-atlas

Command	Description
make fmt	Format code and sort imports
make lint	Run golangci-lint with the repo config (.golangci.yml)
make test	Run root-module tests with default build tags; integration and stress tests have separate targets
make test-all	Tests with race detector, shuffle, and coverage
make test-stress	Stress tests under -race, STRESS_DURATION (default 30s) each
make bench	Run all benchmarks
make bench-gate	Fail on hot-path benchmark regressions against the local baseline (details)
make security-scan	Run govulncheck and gosec
make generate	Run go generate across all packages
make ci	Run full CI checks locally (lint, test, security, dupl)
make clean	Remove generated artifacts

Stress tests live next to the code they exercise in *_stress_test.go files behind the stress build tag, so go test ./... never runs them. Each one mixes every operation of its package concurrently for ATLAS_STRESS_DURATION (default 30s) and checks invariants as it goes; run one with ATLAS_STRESS_DURATION=10s go test -tags stress -race -run '^TestStress' ./core/io/wal. The dlock test needs the NATS broker from make integration-up (NATS_URL overrides it) and skips without one. The Stress workflow runs them nightly.

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for guidelines.

Security

Report vulnerabilities by email to security@altessa-s.com. See SECURITY.md.

License

MIT License — Copyright (c) 2021-2026 ALTESSA SOLUTIONS INC. See LICENSE.