README
¶
go-platform-kit
Modular Go infrastructure SDK. Module path: github.com/cetrictech/go-platform-kit. License: MIT. Default branch on GitHub is main; this work lives on develop.
Status: v1.1.0 release candidate. Tagging and publication are maintainer-controlled. Go 1.26.0 minimum; the workspace toolchain is Go 1.27.3. CI matrices Go 1.26.x and 1.27.x.
The root module has no database, Kafka, gRPC, Redis, SPIFFE, JWT, OpenTelemetry, or S3 drivers. Those live in nested modules listed in go.work. integration/ is test-only and is not a consumer module.
Setup
git clone git@github.com:cetrictech/go-platform-kit.git
cd go-platform-kit
git checkout develop
Requires a patched Go 1.26+ toolchain, Git, and Make. Integration and fault tests also need Docker Compose.
make test # all modules, GOWORK=off, no infrastructure
make race
make vet
make check-fmt
make services # loopback PostgreSQL 18, MySQL 8.4, Redis 8, Redpanda v25.3.1
make integration
make services-down
Release-oriented targets in this tree: make verify, make api, make api-surface, make independent, make faults, make performance, make gates, make release-check.
Modules
| Path | Role |
|---|---|
github.com/cetrictech/go-platform-kit |
config, logger, errors, HTTP, pagination, validation, lifecycle, health, retry, resilience, ratelimit, idempotency, clock, encodingx, security, id, instrument, worker, Kafka contracts, outbox, database scan |
.../database/postgres |
pgx pool |
.../database/mysql |
database/sql MySQL |
.../cache/redis |
go-redis |
.../messaging/kafka/franz |
franz-go |
.../messaging/kafka/sarama |
IBM Sarama |
.../grpcx |
gRPC server and client |
.../spiffe |
SPIRE Workload API source and mTLS |
.../security/jwt |
JWT / JWKS |
.../observability |
OpenTelemetry |
.../storage/s3 |
S3-compatible object client |
The root release candidate is v1.1.0. Nested modules remain independently versioned and use directory-prefixed tags when published (spiffe/v1.1.0). A root tag does not release nested modules.
Consumer import (after a tag exists):
go get github.com/cetrictech/go-platform-kit@v1.1.0
go get github.com/cetrictech/go-platform-kit/spiffe@v1.1.0
Until tags exist, consume from a commit on this repository. Local replace directives in nested go.mod files are for this workspace only; consumers do not inherit them.
Repository layout
config/ logger/ errors/ httpx/ ... root packages
database/postgres mysql SQL adapters
cache/redis Redis adapter
messaging/kafka/franz sarama Kafka adapters
grpcx/ spiffe/ security/jwt RPC and identity
observability/ storage/s3 telemetry and objects
integration/ Compose fixtures and tagged tests
docs/ module documentation
release/ module manifest and API contracts
scripts/ test, API, and release gates
.github/workflows/ CI, benchmarks, release validation
Integration Compose: integration/compose.yaml. Loopback ports: PostgreSQL 127.0.0.1:15432, MySQL 13306, Redis 16379, Redpanda 19092. Fixture passwords are test-only. Generated TLS material is gitignored under integration/.runtime/.
Documentation
Start at docs/README.md. Library behavior, ownership, and SPIFFE/gRPC wiring: docs/library.md. Changelog: CHANGELOG.md.
Directories
¶
| Path | Synopsis |
|---|---|
|
cache
|
|
|
redis
module
|
|
|
Package clock supplies injectable clocks and cancellable waiting.
|
Package clock supplies injectable clocks and cancellable waiting. |
|
Package config loads explicit, typed application configuration.
|
Package config loads explicit, typed application configuration. |
|
Package database defines shared scanning, hooks and SQL value contracts without importing drivers.
|
Package database defines shared scanning, hooks and SQL value contracts without importing drivers. |
|
mysql
module
|
|
|
postgres
module
|
|
|
Package encodingx provides bounded serialization with typed errors.
|
Package encodingx provides bounded serialization with typed errors. |
|
Package errors provides safe application errors interoperable with standard Go errors.
|
Package errors provides safe application errors interoperable with standard Go errors. |
|
Package health implements independent liveness, readiness and startup registries with bounded dependency checking.
|
Package health implements independent liveness, readiness and startup registries with bounded dependency checking. |
|
httpx
|
|
|
client
Package client constructs bounded, context-aware native HTTP clients.
|
Package client constructs bounded, context-aware native HTTP clients. |
|
middleware
Package middleware supplies composable native HTTP middleware.
|
Package middleware supplies composable native HTTP middleware. |
|
Package id provides cryptographically generated UUIDs.
|
Package id provides cryptographically generated UUIDs. |
|
Package idempotency coordinates request attempts using expiring ownership leases.
|
Package idempotency coordinates request attempts using expiring ownership leases. |
|
Package instrument defines optional instrumentation hooks without a telemetry vendor dependency.
|
Package instrument defines optional instrumentation hooks without a telemetry vendor dependency. |
|
internal
|
|
|
consumerlife
Package consumerlife coordinates explicit consumer cancellation and native cleanup.
|
Package consumerlife coordinates explicit consumer cancellation and native cleanup. |
|
redact
Package redact shares structured secret handling without cryptographic dependencies.
|
Package redact shares structured secret handling without cryptographic dependencies. |
|
Package lifecycle manages explicit startup and reverse-order shutdown.
|
Package lifecycle manages explicit startup and reverse-order shutdown. |
|
Package logger configures native slog with recursive structured-field redaction.
|
Package logger configures native slog with recursive structured-field redaction. |
|
messaging
|
|
|
kafka
Package kafka defines driver-independent Kafka contracts and failure handling.
|
Package kafka defines driver-independent Kafka contracts and failure handling. |
|
outbox
Package outbox implements SQL transactional event storage and at-least-once Kafka delivery.
|
Package outbox implements SQL transactional event storage and at-least-once Kafka delivery. |
|
kafka/franz
module
|
|
|
Package pagination implements bounded offset and authenticated cursor pagination.
|
Package pagination implements bounded offset and authenticated cursor pagination. |
|
Package ratelimit implements concurrency-safe in-memory token buckets.
|
Package ratelimit implements concurrency-safe in-memory token buckets. |
|
Package resilience provides circuit breakers and bounded concurrency.
|
Package resilience provides circuit breakers and bounded concurrency. |
|
Package response writes bounded JSON envelopes using native net/http.
|
Package response writes bounded JSON envelopes using native net/http. |
|
Package retry retries explicitly classified operations with bounded backoff.
|
Package retry retries explicitly classified operations with bounded backoff. |
|
scripts
|
|
|
api-surface
command
Command api-surface checks reviewed optional-driver types in public Go signatures.
|
Command api-surface checks reviewed optional-driver types in public Go signatures. |
|
Package security provides scoped standard cryptographic utilities.
|
Package security provides scoped standard cryptographic utilities. |
|
spiffe
module
|
|
|
Package validation validates struct tags without framework dependencies.
|
Package validation validates struct tags without framework dependencies. |
|
Package worker provides registered, bounded workers with explicit retry, metrics, cancellation and draining.
|
Package worker provides registered, bounded workers with explicit retry, metrics, cancellation and draining. |