README
¶
Gobox
A curated collection of reusable Go packages for common infrastructure concerns.
Gobox is a Go module that centralizes shared libraries reused across multiple projects. The goal is to keep common building blocks in one place so teams can reduce code duplication, standardize recurring infrastructure concerns, and move faster when starting or evolving services.
Each package is independently importable, has zero knowledge of the others, and ships with its own README and godoc.
Installation
go get github.com/raykavin/gobox
Then import only the packages you need:
import "github.com/raykavin/gobox/log"
import "github.com/raykavin/gobox/retry"
Packages
Observability
| Package | Description |
|---|---|
log |
Structured logger built on zerolog with colored console output, JSON mode, and HTTP request logging |
telemetry |
OpenTelemetry bootstrap: OTLP tracing, Prometheus metrics, and pluggable custom collectors |
healthcheck |
Health snapshot with concurrent database probes and Go runtime diagnostics |
HTTP
| Package | Description |
|---|---|
httpclient |
Thin HTTP client wrapper with header presets, query params, and response decompression (gzip, br, zstd) |
httpserver |
Gin-based HTTP server with TLS, HTTP/2, timeouts, payload limits, and graceful shutdown |
Database
| Package | Description |
|---|---|
database/gorm |
GORM connection factory with pooling, structured logging, and retry support |
database/migrate |
Schema migration and seed execution via golang-migrate (postgres, mysql, sqlite3) |
database/sql |
Generic database/sql connector with a caller-supplied row scanner |
Configuration and resilience
| Package | Description |
|---|---|
config |
Configuration loading with Viper: env expansion, validation, hot-reload, and typed change events |
retry |
Context-aware retry with exponential backoff and caller-defined retry policy |
Workflows
| Package | Description |
|---|---|
temporal |
Temporal client factory and activity options builder with sensible retry defaults |
Security
| Package | Description |
|---|---|
oidcauth |
OIDC token verification with optional in-memory cache and Keycloak role helpers |
Utilities
| Package | Description |
|---|---|
spreadsheet |
CSV and XLSX writer with multi-sheet support and configurable header styling |
cli |
Terminal helpers: ASCII art banner, colored system header, and concurrent progress display |
Integrations
| Package | Description |
|---|---|
integration/prest |
Generic OAuth2-authenticated HTTP client for pREST APIs with typed JSON responses |
When to add a package
A good rule of thumb: move code here when it appears in more than one service, represents generic infrastructure logic, and carries no business-domain coupling. Keep domain rules in the application.
Contributing
Contributions to gobox are welcome! Here are some ways you can help:
- Report bugs and suggest features by opening issues on GitHub
- Submit pull requests with bug fixes or new features
- Improve documentation to help other users and developers
License
gobox is distributed under the MIT License.
For complete license terms and conditions, see the LICENSE file in the repository.
Contact
For support, collaboration, or questions about gobox:
Email: raykavin.meireles@gmail.com
GitHub: @raykavin
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cli provides terminal output helpers for CLI applications.
|
Package cli provides terminal output helpers for CLI applications. |
|
Package config provides configuration loading built on top of Viper.
|
Package config provides configuration loading built on top of Viper. |
|
database
|
|
|
gorm
Package gorm provides a GORM database connection factory with connection pooling, structured logging, and retry support.
|
Package gorm provides a GORM database connection factory with connection pooling, structured logging, and retry support. |
|
migrate
Package migrate provides schema migration and seed data execution using golang-migrate.
|
Package migrate provides schema migration and seed data execution using golang-migrate. |
|
sql
Package sql provides a generic database connector that pairs a standard database/sql connection with a caller-supplied row scanner.
|
Package sql provides a generic database connector that pairs a standard database/sql connection with a caller-supplied row scanner. |
|
Package healthcheck probes registered database connections and collects Go runtime diagnostics, returning a structured snapshot suitable for a health-check endpoint.
|
Package healthcheck probes registered database connections and collects Go runtime diagnostics, returning a structured snapshot suitable for a health-check endpoint. |
|
Package httpclient provides a thin HTTP client wrapper with helpers for common header presets, query parameter encoding, and response decompression.
|
Package httpclient provides a thin HTTP client wrapper with helpers for common header presets, query parameter encoding, and response decompression. |
|
Package httpserver provides a Gin-based HTTP server with TLS, HTTP/2, configurable timeouts, trusted proxies, payload size limits, and graceful shutdown.
|
Package httpserver provides a Gin-based HTTP server with TLS, HTTP/2, configurable timeouts, trusted proxies, payload size limits, and graceful shutdown. |
|
integration
|
|
|
prest
Package prest provides a generic HTTP client for pREST APIs that authenticates automatically via OAuth2 client credentials.
|
Package prest provides a generic HTTP client for pREST APIs that authenticates automatically via OAuth2 client credentials. |
|
Package log provides a structured logger built on top of zerolog with colored console output, JSON mode, API request logging, and field helpers.
|
Package log provides a structured logger built on top of zerolog with colored console output, JSON mode, API request logging, and field helpers. |
|
Package oidcauth provides OpenID Connect token verification with optional in-memory caching and authorization helpers for roles, scopes, and authorized parties.
|
Package oidcauth provides OpenID Connect token verification with optional in-memory caching and authorization helpers for roles, scopes, and authorized parties. |
|
Package pagination provides building blocks for cursor-free, offset-based pagination with filtering and sorting, designed to work seamlessly with GORM.
|
Package pagination provides building blocks for cursor-free, offset-based pagination with filtering and sorting, designed to work seamlessly with GORM. |
|
Package retry provides a small helper for retrying operations that may fail transiently, with exponential backoff and context-aware waiting.
|
Package retry provides a small helper for retrying operations that may fail transiently, with exponential backoff and context-aware waiting. |
|
Package spreadsheet provides a lightweight writer for generating CSV and XLSX files as raw bytes.
|
Package spreadsheet provides a lightweight writer for generating CSV and XLSX files as raw bytes. |
|
Package telemetry initialises OpenTelemetry tracing and metrics for a service in a single call, exposing a Prometheus /metrics endpoint and sending traces to an OTLP/gRPC collector.
|
Package telemetry initialises OpenTelemetry tracing and metrics for a service in a single call, exposing a Prometheus /metrics endpoint and sending traces to an OTLP/gRPC collector. |
|
Package temporal provides a thin wrapper around the Temporal Go SDK for dialling a client and building activity options with sensible defaults.
|
Package temporal provides a thin wrapper around the Temporal Go SDK for dialling a client and building activity options with sensible defaults. |
Click to show internal directories.
Click to hide internal directories.