go-foundation

module
v0.10.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 4, 2026 License: MIT

README

📦  go-foundation

The shared, domain-agnostic foundation kit for modern Go services


Release Go Version License


CI / CD    Build Last Commit      Quality    Coverage
Security    Scorecard Security      Community    Contributors Bitcoin


Project Navigation
🚀 Installation 🧪 Examples & Tests 📚 Documentation
🤝 Contributing 🛠️ Code Standards ⚡ Benchmarks
🤖 AI Usage ⚖️ License 👥 Maintainers

🧩 About

go-foundation is the shared, domain-agnostic foundation kit used across several Go services and projects. It exists to kill drift: instead of every service re-implementing the same configuration, HTTP, persistence, and observability plumbing, that plumbing lives here once and is consumed everywhere.

The module carries only generic building blocks — no business domain, no project-specific naming. As the kit is assembled it exposes focused sub-packages:

  • backoff — exponential retry-delay ladder (base, doubling, capped)
  • cache — generic two-tier TTL cache for validating opaque secrets (bounded, DoS-guarded, injectable clock)
  • config — application, database, logging, and AWS configuration types
  • constants — shared HTTP constants: header names, content types, CORS values, and standardized error codes and messages
  • crypto — auth primitives: HMAC/SHA-256 hashing, argon2id passwords, CSPRNG tokens (constant-time compares)
  • ctxutil — request-ID context propagation helpers
  • db — database connection helpers
  • health — health-check helpers
  • httputil — JSON response and error helpers
  • jsonpath — address values in a decoded-JSON tree via a small JSONPath subset
  • lambda — AWS Lambda (API Gateway v2) ⇄ net/http adapter
  • middleware — logging, recovery, and request-ID HTTP middleware
  • models — persistence building blocks and input validation:
    • generic BaseModel, Repository, and TemporalEdge with append-only lifecycle helpers (SupersedeEdge, EndEdge, SuppressEdge); Clock and transaction helpers; a civil Date
    • email, phone, and person-name validation that accepts the ways people write them and returns one standard form, with a ValidationError that never includes the input:
      • NormalizeEmail — the mailbox mail is delivered to, the canonical address, and the alias root; unwraps mailto:, brackets, and quotes; strictness options (StrictEmail, RejectQuotedLocal, RejectTrailingDot, RequireDottedDomain)
      • ParsePhone — validates against the region's numbering plan (libphonenumber) and returns E.164 and international forms; ignores labels, punctuation, and tel:/sms: schemes; options for a default region, numbers in use only, and keypad letters
      • NormalizePersonName — NFC normalization with character-class and shape checks
  • observability — structured logging initialization
  • pagination — cursor-based list pagination
  • ptr — generic pointer helpers (To, Deref, DerefOr)
  • recurrence — DST-correct next-occurrence calculator for weekly recurring event patterns
  • secrets — pluggable secret providers (env, AWS, mock)
  • sliceutil — generic slice helpers (order-preserving dedupe, set intersection)
  • strtmpl — safe {{name}} placeholder substitution from layered value maps
  • testutil — dependency-light generic test helpers (in-memory test database, test config, HTTP doer double, log recorder, free port); the testcontainers-backed PostgreSQL harness lives in the testutil/pgtest subpackage

Project-specific naming — environment prefixes, database names, health messages, and infrastructure constants — intentionally stays in the consuming services, never in this module.


📦 Installation

go-foundation requires a supported release of Go.

go get -u github.com/mrz1836/go-foundation

Get the MAGE-X build tool for development:

go install github.com/mrz1836/mage-x/cmd/magex@latest

📚 Documentation


Repository Features

This repository includes 25+ built-in features covering CI/CD, security, code quality, developer experience, and community tooling.

View the full Repository Features list →

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump push=true bump=patch branch=master

This process ensures consistent, repeatable releases with properly versioned artifacts and metadata.

Pre-commit Hooks

Set up the Go-Pre-commit System to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install

The system is configured via modular env files in .github/env/ and provides 17x faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.

GitHub Workflows

All workflows are driven by modular configuration in .github/env/ — no YAML editing required.

View all workflows and the control center →

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any tools managed by MAGE-X. It is the recommended way to keep your development environment and CI in sync with the latest versions.

Build Commands

View all build commands

magex help

🧪 Examples & Tests

All unit tests run via GitHub Actions and use Go version 1.26.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

⚡ Benchmarks

Every performance-sensitive path ships with a Go benchmark so changes can be measured, not guessed. Run them all:

magex bench

…or with the standard toolchain (all packages, or a single one):

go test -bench=. -benchmem ./...
go test -bench=. -benchmem ./cache/...
go test -bench=BenchmarkCache_Eviction -benchmem ./cache/...
Benchmark catalog

Every benchmark in the module, linked to its source. The name links jump straight to the function so you can see exactly what is measured.

Package Benchmark Measures
backoff Exponential ladder Retry delay at attempts 1 / 5 / 30
cache Cache hit Revalidating an already-cached secret (fast path)
cache Cache miss Validating an unknown secret (loader + match scan)
cache Parallel reads Concurrent cache hits under the read lock
cache Parallel mixed Concurrent hits + occasional costly-scan miss (lock-free scan)
cache Eviction Evicting the oldest ~10% of a full cache
config Load from env Reflection-based env binding into a config struct
crypto SHA-256 hex Deriving a cache key from an opaque token (16 / 256 / 4096 B)
crypto HMAC hex Keyed hash of a high-entropy secret (16 / 256 / 4096 B)
crypto HMAC compare Constant-time hex-tag comparison (equal path)
crypto Hash password argon2id hashing at cheap / default OWASP params (deliberately costly)
crypto Verify password argon2id decode + derive + constant-time compare
crypto Random token CSPRNG opaque-token mint (16 / 32 / 64 B)
ctxutil Request ID → metadata JSON merge + marshal on the request-id stamping path
ctxutil Request ID ← metadata JSON unmarshal on the request-id extraction path
httputil Write JSON Marshal + write of a JSON response body
jsonpath Eval path Addressing a value by dotted / indexed / bracketed path
lambda API Gateway → net/http Full request/response adapter round-trip
middleware Logging · large 200 Logging a large successful response body
middleware Logging · request path Request/response log pair on the happy path
middleware Logging · error response Capturing + logging a 4xx/5xx body
models Normalize email Email parse + normalization
models Normalize email · strict Email parse + normalization with StrictEmail
models Normalize phone Regex-only E.164 normalization (deprecated)
models Parse phone Sanitizing + numbering-plan parse of a formatted national number
models Normalize person name NFC normalization + character-class and shape checks
models Generate slug URL-slug transform (package-scoped regexes)
pagination Encode cursor Encoding a timestamp cursor
pagination Decode cursor Decoding a cursor string
ptr To Boxing a value into a pointer (stack-allocated when it does not escape)
ptr Deref Nil-safe dereference on the non-nil path
recurrence Parse HH:MM Hand-rolled start-time parse (hot path)
recurrence Parse pattern JSON decode of a recurrence pattern
recurrence Next occurrence Full parse + next-occurrence computation
sliceutil Dedupe Order-preserving dedupe at 16 / 256 / 4096 elements
sliceutil Intersect Set intersection (full overlap) at 16 / 256 / 4096 elements
strtmpl Render {{placeholder}} substitution at 3 / 24 / 192 placeholders
Benchmark results

To measure the impact of a change, capture a baseline before and after and compare with benchstat — it reports the delta and whether it is statistically significant, so you are not chasing noise:

go install golang.org/x/perf/cmd/benchstat@latest

# 1) baseline (e.g. on master), several runs for a stable distribution
go test -bench=. -benchmem -count=6 ./... > old.txt

# 2) after your change, from the same machine
go test -bench=. -benchmem -count=6 ./... > new.txt

# 3) compare
benchstat old.txt new.txt

Absolute ns/op depends on the host, so treat the numbers below as a point-in-time reference, not a contract — the durable signal is the benchstat delta between two runs on the same machine.

Reference snapshot — Go 1.27.1 · Apple M1 Max · 2026-09-24
Benchmark ns/op B/op allocs/op
Exponential ladder (attempt=1) 0.63 0 0
Exponential ladder (attempt=5) 4.99 0 0
Exponential ladder (attempt=30) 6.57 0 0
Cache hit 174 160 3
Cache miss 188 152 3
Parallel reads 154 160 3
Parallel mixed 2,833 167 3
Eviction 500,684 122,880 1
Load from env 3,901 1,320 37
SHA-256 hex (16 B) 106 128 2
SHA-256 hex (4096 B) 2,195 4,224 3
HMAC hex (16 B) 379 656 9
HMAC hex (4096 B) 2,466 4,736 9
HMAC compare 87.0 64 2
Hash password (cheap) 5,281,773 8,391,656 25
Hash password (default OWASP) 25,606,054 19,926,923 34
Verify password (cheap) 5,044,210 8,391,575 27
Random token (32 B) 309 128 3
Request ID → metadata 903 593 16
Request ID ← metadata 278 16 1
Write JSON 783 1,129 15
Eval (dotted path) 84.3 192 2
Eval (bracketed path) 112 224 3
API Gateway → net/http 688 1,448 15
Logging · large 200 510,092 10,493,183 22
Logging · request path 3,234 6,295 24
Logging · error response 3,656 6,402 29
Normalize email ² 850 256 10
Normalize email · strict ² 760 264 11
Normalize phone 195 32 2
Parse phone ¹ 21,700 11,250 165
Normalize person name 240 56 2
Generate slug 1,812 518 15
Encode cursor 16.8 16 1
Decode cursor 22.8 16 1
Ptr.To 0.32 0 0
Ptr.Deref 0.32 0 0
Parse HH:MM 24.0 0 0
Parse pattern 329 48 1
Next occurrence 395 48 1
Dedupe (16 elems) 268 744 4
Dedupe (4096 elems) 49,729 180,544 18
Intersect (16 elems) 319 744 4
Intersect (4096 elems) 72,090 180,544 18
Render (3 placeholders) 457 32 3
Render (192 placeholders) 28,526 1,551 9

¹ Measured on 2026-10-04, on the same machine and Go version. ² Measured on 2026-10-04 with Mailbox, on the same machine and Go version. The benchmark's address is on an aliased domain (googlemail.com), which costs the one allocation more; an unaliased one doesn't.


🛠️ Code Standards

Read more about this Go project's code standards.


🤖 AI Usage & Assistant Guidelines

Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with the AI assistants.


👥 Maintainers

MrZ
MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

Stars


📝 License

License

Directories

Path Synopsis
Package backoff computes retry delay ladders shared across services.
Package backoff computes retry delay ladders shared across services.
Package cache provides a generic, thread-safe, two-tier TTL cache for validating opaque secrets (API keys, tokens) against a loaded set, using a caller-supplied match function so the package stays dependency-free.
Package cache provides a generic, thread-safe, two-tier TTL cache for validating opaque secrets (API keys, tokens) against a loaded set, using a caller-supplied match function so the package stays dependency-free.
Package config provides a lightweight, type-safe configuration layer for serverless and HTTP services.
Package config provides a lightweight, type-safe configuration layer for serverless and HTTP services.
Package constants provides shared, domain-agnostic HTTP constants — header names, content types, CORS values, and standardized error codes and messages — used by the foundation HTTP, Lambda, and response helpers.
Package constants provides shared, domain-agnostic HTTP constants — header names, content types, CORS values, and standardized error codes and messages — used by the foundation HTTP, Lambda, and response helpers.
Package crypto provides a small, opinionated set of cryptographic primitives for building authentication systems.
Package crypto provides a small, opinionated set of cryptographic primitives for building authentication systems.
Package ctxutil provides small, domain-agnostic helpers for threading values through context.Context.
Package ctxutil provides small, domain-agnostic helpers for threading values through context.Context.
Package db provides GORM database connection management for serverless and HTTP services.
Package db provides GORM database connection management for serverless and HTTP services.
Package health provides health check services for database connections.
Package health provides health check services for database connections.
Package httputil provides shared HTTP response helpers.
Package httputil provides shared HTTP response helpers.
Package jsonpath addresses values inside a decoded-JSON tree (map[string]any / []any, as produced by encoding/json into an any) using a small, dependency-free subset of JSONPath.
Package jsonpath addresses values inside a decoded-JSON tree (map[string]any / []any, as produced by encoding/json into an any) using a small, dependency-free subset of JSONPath.
Package lambda provides a lightweight AWS API Gateway v2 ↔ net/http adapter.
Package lambda provides a lightweight AWS API Gateway v2 ↔ net/http adapter.
Package middleware provides production-ready HTTP middleware for serverless Lambda functions and local HTTP servers.
Package middleware provides production-ready HTTP middleware for serverless Lambda functions and local HTTP servers.
Package models provides core infrastructure for GORM-based domain models.
Package models provides core infrastructure for GORM-based domain models.
Package observability centralizes log/metric/trace setup so every binary (local server, Lambda, daemon, snapshot tool, build tooling) configures slog the same way.
Package observability centralizes log/metric/trace setup so every binary (local server, Lambda, daemon, snapshot tool, build tooling) configures slog the same way.
Package pagination provides cursor-based pagination utilities.
Package pagination provides cursor-based pagination utilities.
Package ptr provides tiny generic helpers for working with pointers, so callers stop writing one-off "address of a literal" locals or nil-checking deref blocks.
Package ptr provides tiny generic helpers for working with pointers, so callers stop writing one-off "address of a literal" locals or nil-checking deref blocks.
Package recurrence computes next occurrences of weekly recurring event patterns expressed as JSON.
Package recurrence computes next occurrences of weekly recurring event patterns expressed as JSON.
Package secrets provides a unified interface for retrieving secrets from various sources.
Package secrets provides a unified interface for retrieving secrets from various sources.
Package sliceutil provides small, dependency-free generic slice helpers that the standard library's slices package does not cover — notably order-preserving deduplication of an unsorted slice and set intersection.
Package sliceutil provides small, dependency-free generic slice helpers that the standard library's slices package does not cover — notably order-preserving deduplication of an unsorted slice and set intersection.
Package strtmpl renders {{name}} placeholders in a string from one or more value maps.
Package strtmpl renders {{name}} placeholders in a string from one or more value maps.
Package testutil provides generic, domain-agnostic test helpers for services built on go-foundation: in-memory SQLite databases, ready-made test configurations, a programmable HTTP doer double, a log-recording slog handler, and a free-port helper.
Package testutil provides generic, domain-agnostic test helpers for services built on go-foundation: in-memory SQLite databases, ready-made test configurations, a programmable HTTP doer double, a log-recording slog handler, and a free-port helper.
pgtest
Package pgtest provides a testcontainers-backed PostgreSQL harness for integration tests built on go-foundation.
Package pgtest provides a testcontainers-backed PostgreSQL harness for integration tests built on go-foundation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL