README
¶
go-devkit
Go developer kit for multipurpose applications.
go get github.com/diegodesousas/go-devkit
The reference documentation lives on pkg.go.dev — every package has an overview and runnable examples. The table below is a map of what is in the box.
Packages
| Package | What it does |
|---|---|
httpserver |
HTTP server from a route list, middleware chain and error handler. Graceful shutdown, request logging and metrics per route |
httpserver/httpservertest |
Test helpers for handlers that read path parameters |
stream/consumer |
Typed Kafka consumer with retry, dead letter topic and graceful shutdown |
stream/dispatcher |
Kafka producer with synchronous delivery confirmation |
stream |
Message payloads exchanged over Kafka, JSON and text |
log |
Leveled logger with structured fields, carried through the context |
database/sql |
PostgreSQL connection with context-scoped transactions and typed errors |
database/sql/upsert |
Builder for INSERT ... ON CONFLICT statements |
cache |
Redis cache, raw strings or JSON-encoded values through a generic repository |
metrics |
StatsD metrics emitted through a client carried in the context |
validator |
Composable validation rules with machine-readable error codes |
gen |
String generators: UUID, ULID and sequence |
shutdown |
Ordered, deadline-bound release of resources (HTTP server, database, ...) on shutdown |
mapper |
Generic registry keyed by a string-like type |
encoding |
JSON serializer behind an interface |
httpclient |
*http.Client behind a one-method interface, with a mock |
Runnable examples
The examples/ directory holds end-to-end programs, one package main per feature. They need the services they talk to — Kafka, Redis, PostgreSQL — running locally.
Shorter, self-contained snippets are the Example functions in each package, rendered on pkg.go.dev.
Development
The toolchain runs in a container: the only local requirement is Docker. Every make target below builds the dev image from the Dockerfile (Go, golangci-lint and librdkafka) and runs inside it through compose.yaml. For one-off commands, use docker compose run --rm dev go ....
| Command | What it does |
|---|---|
make test |
Unit tests with -race |
make test-integration |
pkg/database/sql only, with -tags=integration. Starts Postgres as a sibling container |
make test-all |
Both |
make lint |
gofmt -l, go vet and golangci-lint |
make fmt |
gofmt -w over ./pkg and ./examples |
make shell |
Interactive shell in the dev container |
make release [BUMP=patch|minor|major] |
Cuts a version: validates, tests, tags, pushes and opens the GitHub release |
License
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
cache
command
|
|
|
db
command
|
|
|
httpserver
command
|
|
|
log
command
|
|
|
stream/consumer
command
|
|
|
stream/dispatcher
command
|
|
|
pkg
|
|
|
cache
Package cache stores values in Redis, either as raw strings or as JSON-encoded Go values.
|
Package cache stores values in Redis, either as raw strings or as JSON-encoded Go values. |
|
database/sql
Package sql wraps a PostgreSQL connection with context-scoped transactions, Datadog tracing and typed errors.
|
Package sql wraps a PostgreSQL connection with context-scoped transactions, Datadog tracing and typed errors. |
|
database/sql/upsert
Package upsert builds PostgreSQL INSERT ...
|
Package upsert builds PostgreSQL INSERT ... |
|
encoding
Package encoding puts a JSON serializer behind an interface.
|
Package encoding puts a JSON serializer behind an interface. |
|
gen
Package gen provides string generators, used across the devkit wherever an identifier has to be produced.
|
Package gen provides string generators, used across the devkit wherever an identifier has to be produced. |
|
httpclient
Package httpclient puts *http.Client behind a one-method interface so that outbound calls can be faked in tests.
|
Package httpclient puts *http.Client behind a one-method interface so that outbound calls can be faked in tests. |
|
httpserver
Package httpserver builds an HTTP server out of a route list, a middleware chain and an error handler.
|
Package httpserver builds an HTTP server out of a route list, a middleware chain and an error handler. |
|
httpserver/httpservertest
Package httpservertest holds helpers for testing handlers written against pkg/httpserver.
|
Package httpservertest holds helpers for testing handlers written against pkg/httpserver. |
|
log
Package log provides a leveled, field-oriented logger that travels through the request context.
|
Package log provides a leveled, field-oriented logger that travels through the request context. |
|
mapper
Package mapper is a small generic registry keyed by a string-like type.
|
Package mapper is a small generic registry keyed by a string-like type. |
|
metrics
Package metrics emits StatsD metrics through a client carried in the context.
|
Package metrics emits StatsD metrics through a client carried in the context. |
|
shutdown
Package shutdown releases an application's resources in order when it stops.
|
Package shutdown releases an application's resources in order when it stops. |
|
stream
Package stream defines the message payloads exchanged over Kafka by the consumer and dispatcher packages.
|
Package stream defines the message payloads exchanged over Kafka by the consumer and dispatcher packages. |
|
stream/consumer
Package consumer runs a typed Kafka consumer loop around a user-supplied handler.
|
Package consumer runs a typed Kafka consumer loop around a user-supplied handler. |
|
stream/dispatcher
Package dispatcher publishes messages to Kafka and waits for the broker to confirm each one.
|
Package dispatcher publishes messages to Kafka and waits for the broker to confirm each one. |
|
validator
Package validator composes validation rules over a typed payload.
|
Package validator composes validation rules over a typed payload. |
Click to show internal directories.
Click to hide internal directories.