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, and ships with its own README and godoc. Packages are deliberately kept free of cross-dependencies, with the few documented exceptions noted below.
go get github.com/raykavin/goboxThen import only the packages you need:
import "github.com/raykavin/gobox/logger"
import "github.com/raykavin/gobox/retry"| Package | Description |
|---|---|
logger |
Structured logger built on zerolog with colored console output, JSON mode, HTTP request logging, and runtime level control |
telemetry |
OpenTelemetry bootstrap: OTLP tracing, Prometheus metrics, and pluggable custom collectors |
healthcheck |
Health snapshot with concurrent database probes and Go runtime diagnostics |
| Package | Description |
|---|---|
httpclient |
Thin HTTP client wrapper with header presets, query params, and response decompression (gzip, deflate, br, zstd) |
httpserver |
Gin-based HTTP server with TLS, HTTP/2, timeouts, payload limits, and graceful shutdown |
httpserver/middlewares |
Gin middleware for authorization, roles, CORS, CSRF, per-IP rate limiting, and a full OIDC login flow |
httpserver/respond |
A single JSON response envelope, plus sentinel-error to HTTP status mapping |
| Package | Description |
|---|---|
database/gorm |
GORM connection factory with pooling, structured logging, and startup retry |
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 |
pagination |
Offset pagination for GORM with a fluent filter and sort builder, and a generic result envelope |
| Package | Description |
|---|---|
config |
Configuration loading with Viper: env expansion, validation, hot-reload, and typed change events |
retry |
Context-aware retry with exponential backoff and a caller-defined retry policy |
| Package | Description |
|---|---|
temporal |
Temporal client factory and activity options builder with sensible retry defaults |
| Package | Description |
|---|---|
oidcauth |
OIDC token verification, RFC 7662 introspection, the Authorization Code + PKCE flow, and server-side sessions |
oauth2 |
Client-side OAuth 2.0 token manager with per-scope caching for outbound calls |
secure |
Authenticated encryption (AES-256-GCM) for opaque byte payloads |
totp |
RFC 6238 time-based one-time passwords: secrets, codes, validation, and enrollment URIs |
| 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 |
database groups the three database packages above and holds only their shared README. logger/zerolog is a legacy copy of logger, kept so existing imports keep compiling; new code should use logger.
Packages are independent, with these exceptions:
| Package | Imports | For |
|---|---|---|
httpserver/middlewares |
oidcauth |
Token verification, the login flow, and sessions |
httpserver/middlewares |
httpserver/respond |
Writing error responses in the shared envelope |
oauth2 |
httpclient |
Its token requests |
Everything else depends only on the standard library and third-party modules.
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.
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
gobox is distributed under the MIT License.
For complete license terms and conditions, see the LICENSE file in the repository.
For support, collaboration, or questions about gobox:
Email: raykavin.meireles@gmail.com
GitHub: @raykavin