go-lib

Personal toolkit for Go microservices
Opinionated, reusable building blocks extracted from real projects.

This is a personal library built to capture patterns I've used across multiple Go microservices. Instead of copying boilerplate between projects, I've extracted common components into a shared toolkit.

What it provides:

• Configuration loading with validation (env vars, files, defaults)
• Structured logging (logrus-based with context support)
• Health checks and liveness probes
• Metrics (Prometheus-compatible) and distributed tracing (OTLP)
• HTTP and gRPC server scaffolding
• JWT authentication and role-based authorization
• Database connection management (PostgreSQL-focused)
• Audit logging for mutation tracking

Not a public library. This is a learning project and personal toolbox. APIs may change without notice. If you find it useful, feel free to fork or take inspiration—but expect rough edges.

The fastest way to start a new service is with the scaffold generator. It creates a fully wired, compilable skeleton in one command:

go run github.com/nojyerac/go-lib/scaffold \
  --name orders \
  --module github.com/acme/orders

cd orders
go mod tidy
make run   # no TLS, port 8080, stdout tracing

The generated service ships with:

• Signal-aware entry-point with clean shutdown
• Config loading from env vars (prefixed ORDERS_)
• Structured JSON logging, Prometheus metrics, and OpenTelemetry tracing
• /livez, /healthz, /metrics, and /version endpoints
• Multi-stage Dockerfile, Makefile, and a GitHub Actions CI workflow

See the scaffold README for the full flag reference, generated layout, and how to add routes or gRPC services.

Each package is documented in its own README with usage examples.

scaffold - One-command generator that creates a production-ready service skeleton wired to go-lib.

go run github.com/nojyerac/go-lib/scaffold --name orders --module github.com/acme/orders

config - Load and validate configuration from environment variables, files, and defaults.

import "github.com/nojyerac/go-lib/config"

cfg := &MyConfig{}
loader := config.NewConfigLoader("myapp")
loader.RegisterConfig(cfg)
loader.InitAndValidate()

log - Structured logging with context support (logrus-based).

import "github.com/nojyerac/go-lib/log"

logger := log.NewLogger(log.NewConfiguration())
logger.Info("service started")

ctx := log.WithFields(context.Background(), log.Fields{"user_id": "123"})
log.FromContext(ctx).Info("user action")

health - Readiness and liveness probes for Kubernetes deployments.

import "github.com/nojyerac/go-lib/health"

checker := health.NewChecker(health.NewConfiguration())
checker.RegisterCheck("database", dbHealthCheck)
go checker.Start(context.Background())

// Serves /health endpoint automatically

metrics - Prometheus-compatible metrics collection.

import "github.com/nojyerac/go-lib/metrics"

provider, handler, _ := metrics.NewMetricProvider()
metrics.SetGlobal(provider)

counter := provider.Counter("requests_total", "Total requests")
counter.Inc()

// handler serves /metrics endpoint

tracing - Distributed tracing with OpenTelemetry (OTLP exporter).

import "github.com/nojyerac/go-lib/tracing"

cfg := &tracing.Configuration{
  ExporterType: "otlp",
  OtlpEndpoint: "localhost:4317",
}
provider := tracing.NewTracerProvider(cfg)
tracing.SetGlobal(provider)

transport/http - HTTP server with middleware, auth, and observability built-in.

import transporthttp "github.com/nojyerac/go-lib/transport/http"

server := transporthttp.NewServer(
  transporthttp.NewConfiguration(),
  transporthttp.WithLogger(logger),
  transporthttp.WithHealthChecker(checker),
)
server.HandleFunc("GET /api/users", handleUsers)

transport/grpc - gRPC server with interceptors for auth, logging, and metrics.

import transportgrpc "github.com/nojyerac/go-lib/transport/grpc"

server := transportgrpc.NewServer(
  transportgrpc.NewConfiguration(),
  transportgrpc.WithLogger(logger),
)
// Register your gRPC services...

auth - JWT validation with HMAC and RSA support.

import "github.com/nojyerac/go-lib/auth"

validator := auth.NewJWTValidator(&auth.Config{
  Issuer:     "myapp",
  Audience:   "api",
  HMACSecret: "secret-key",
})

claims, err := validator.ValidateToken(tokenString)

authz - Role-based access control with policy enforcement.

import "github.com/nojyerac/go-lib/authz"

policies := map[string]authz.Policy{
  "/api/admin": {RequiredRoles: []string{"admin"}},
}

enforcer := authz.NewEnforcer(policies)
allowed := enforcer.Enforce("/api/admin", userRoles)

db - PostgreSQL connection management with health checks.

import "github.com/nojyerac/go-lib/db"

dbConn := db.NewConnection(&db.Config{
  Host:     "localhost",
  Port:     5432,
  Database: "myapp",
})
conn, _ := dbConn.Connect(context.Background())

audit - Transaction-safe audit trail for mutations.

import "github.com/nojyerac/go-lib/audit"

logger := audit.NewLogger(db, "users")
logger.Log(ctx, tx, "UPDATE", userID, oldValue, newValue)

version - Build metadata injection for version tracking.

import "github.com/nojyerac/go-lib/version"

version.SetServiceName("myapp")
version.SetVersion("1.2.3")
info := version.GetInfo()

See ROADMAP.md for planned features and improvements.

• Go 1.25+
• Tooling: ginkgo, golangci-lint, mockery

From go-lib/:

go test ./...             # Run all tests
ginkgo -r                 # Run tests with Ginkgo runner
golangci-lint run         # Lint codebase
./scripts/generate.sh     # Generate mocks and codegen

1. Keep package APIs small and interface-first (similar to existing packages).
2. Add/update tests for behavior and integration points.
3. Document defaults, options, and usage in a package README.
4. Add the package link in this README when it is ready for use.

MIT License - This is personal code, use at your own risk.