go-utils

module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 18, 2026 License: MIT

README

go-utils

go get github.com/deepworx/go-utils

Shared Go utility library for services.

Installation

go get github.com/deepworx/go-utils

Packages

Package Import Description
ctxutil pkg/ctxutil Context helpers (request ID, claims, tenant, actor, correlation, causation)
shutdown pkg/shutdown Graceful shutdown orchestration
otel pkg/otel OpenTelemetry initialization
tracing pkg/tracing Manual span creation helpers
postgres pkg/postgres Database pool, transactions, and UnitOfWork
nats pkg/nats NATS/JetStream connection with tracing and metrics
grpchealth pkg/grpchealth gRPC health check aggregator
slogutil pkg/slogutil Global slog logger setup and ctx-correlated logs
koanfutil pkg/koanfutil Koanf configuration helpers
jwtauth pkg/connectrpc/jwtauth JWT authentication interceptor
recovery pkg/connectrpc/recovery Panic recovery interceptor
logging pkg/connectrpc/logging Request/response logging interceptor
requestid pkg/connectrpc/requestid Request ID propagation interceptor
errors pkg/connectrpc/errors Error mapping interceptor
deadline pkg/connectrpc/deadline Deadline enforcement interceptor
interceptor pkg/connectrpc/interceptor Default interceptor chain builder
otelconnect connectrpc.com/otelconnect OpenTelemetry tracing/metrics (external)
validate connectrpc.com/validate Request validation with protovalidate (external)

Event sourcing on Postgres (pkg/eventsourcing/..., pkg/inbox, pkg/scheduler): start with the quickstart.

Documentation

ctxutil

Store and retrieve request-scoped values: request ID and JWT claims (UserID, TenantID, Roles, Permissions).

ctx = ctxutil.WithRequestID(ctx, "req-123")
ctx = ctxutil.WithClaims(ctx, ctxutil.Claims{UserID: "user-456", TenantID: "tenant-789"})

id, ok := ctxutil.RequestID(ctx)
userID, ok := ctxutil.UserID(ctx)

Event metadata (empty strings and uuid.Nil count as absent):

ctx = ctxutil.WithTenantID(ctx, "tenant-789")      // takes precedence over Claims.TenantID
ctx = ctxutil.WithActor(ctx, "system:scheduler:daily-close")
ctx = ctxutil.WithCorrelationID(ctx, "corr-1")
ctx = ctxutil.WithCausationID(ctx, eventID)        // uuid.UUID of the causing event

tenant, ok := ctxutil.TenantID(ctx) // explicit value, then Claims.TenantID
shutdown

Graceful shutdown orchestration with LIFO handler execution and OS signal support.

shutdown.Register(otel.Shutdown)  // called 3rd
shutdown.Register(server.Stop)    // called 2nd
shutdown.Register(db.Close)       // called 1st (LIFO)

shutdown.WaitForSignal(ctx) // blocks until SIGINT/SIGTERM, 30s timeout for handlers

Custom timeout:

shutdown.WaitForSignalWithTimeout(ctx, 60*time.Second) // 60s for handlers to complete

Default: shutdown.DefaultShutdownTimeout (30s)

otel

OpenTelemetry setup for tracing, metrics, and logging. Configurable via OTEL_* env vars.

otel.Setup(ctx, otel.Config{ServiceName: "my-service", ServiceVersion: "1.0.0"})
// Shutdown is automatically registered with the shutdown orchestrator

Env vars: OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER (otlp|console|none)

  • Histograms are exported as base-2 exponential (native) histograms. Set Config.Histograms to otel.HistogramsExplicit (histograms: explicit) for explicit buckets.
  • service.instance.id is a random UUID per process; override it via OTEL_RESOURCE_ATTRIBUTES=service.instance.id=....
  • Setup wraps the slog.Default() handler in slogutil.ContextHandler, so slog.InfoContext etc. carry the ctx correlation fields.
tracing

Span wrapper with automatic error recording. Works without TracerProvider (no-op).

err := tracing.WithSpan(ctx, "operation", func(ctx context.Context) error {
    return doWork(ctx)
})

result, err := tracing.WithSpanResult(ctx, "fetch", func(ctx context.Context) (User, error) {
    return fetchUser(ctx)
})
postgres

Database pool with OpenTelemetry tracing and health checking.

pool, _ := postgres.NewPool(ctx, postgres.Config{DSN: "postgres://localhost/db"})

// Health check for grpchealth aggregator
checker := postgres.NewHealthChecker(pool)

// UnitOfWork keeps the transaction in ctx; nested Execute calls join it.
uow := postgres.NewUnitOfWork(pool, postgres.SetLocalTenant())
uow.Execute(ctx, func(ctx context.Context) error {
    // Conn returns the open transaction, or the pool outside one (sqlc DBTX).
    return db.New(postgres.Conn(ctx, pool)).SaveOrder(ctx, params)
})

// In-memory prototypes: Stage buffers writes until the transaction commits.
memUoW := postgres.NewInMemoryUnitOfWork()
memUoW.Execute(ctx, func(ctx context.Context) error {
    postgres.Stage(ctx, func() { orders[id] = order })
    return nil
})
nats

NATS and JetStream connection with TLS/mTLS support, health checks, tracing, and metrics.

conn, _ := nats.Connect(ctx, nats.Config{URL: "nats://localhost:4222"})

// Health check for grpchealth aggregator
checker := nats.NewHealthChecker(conn)

Publish with trace context:

nats.Publish(ctx, conn, nats.PublishInput{
    Subject: "orders.created",
    Data:    payload,
})

// JetStream with deduplication
js, _ := jetstream.New(conn)
nats.JetStreamPublish(ctx, js, nats.JetStreamPublishInput{
    Subject: "orders.created",
    Data:    payload,
    MsgID:   "order-123", // optional deduplication
})

Consume with automatic trace extraction (pull and push):

// Pull consumer
nats.PullConsumeWithTracing(ctx, nats.PullConsumeInput{
    Consumer: consumer,
    Handler: func(ctx context.Context, msg jetstream.Msg) error {
        // ctx contains extracted trace context
        return processOrder(ctx, msg)
    },
})

// Push consumer
nats.PushConsumeWithTracing(ctx, nats.PushConsumeInput{
    Consumer: pushConsumer,
    Handler: func(ctx context.Context, msg jetstream.Msg) error {
        return processOrder(ctx, msg)
    },
})
grpchealth

Health check aggregator for connectrpc.com/grpchealth/v2. Probes checkers in parallel, sets StatusServing only if all pass. Automatically registers with shutdown for graceful termination.

aggregator := grpchealth.NewAggregator(ctx, grpchealth.DefaultConfig()).
    Register("postgres", postgres.NewHealthChecker(pool)).
    Register("redis", redisChecker)

aggregator.RegisterService(server) // server is a *connect.Server
// Background goroutine runs automatically, stopped by shutdown.WaitForSignal()
slogutil

Configure the global slog logger with level and format.

slogutil.Setup(slogutil.Config{Level: "debug", Format: "json"})
// or with defaults (level: info, format: text)
slogutil.Setup(slogutil.DefaultConfig())

Setup wraps the handler in slogutil.ContextHandler, which adds request_id, tenant_id, user_id, correlation_id, trace_id and span_id from the ctx to every record logged with a *Context method. Wrap a custom handler with slogutil.NewContextHandler(h).

koanfutil

Helpers for koanf configuration loading.

k := koanf.New(".")
k.Load(koanfutil.WithDefaults(postgres.DefaultConfig()), nil) // load defaults
k.Load(file.Provider("config.toml"), toml.Parser())           // override with file
k.Load(koanfutil.FileResolver(k), nil)                        // resolve file:// URIs
  • WithDefaults(T) - Load struct as default values (uses koanf tags)
  • FileResolver(k) - Resolve file:///path URIs to file contents

All packages provide DefaultConfig() with sensible defaults (see godoc).

connectrpc/jwtauth

JWT authentication interceptor with JWKS support. IDP-independent, configurable claims mapping.

auth, _ := jwtauth.NewAuthenticator(ctx, jwtauth.Config{
    JWKSURL:  "https://auth.example.com/.well-known/jwks.json",
    Issuer:   "https://auth.example.com",
    Audience: "my-api",
    ClaimsMapping: &jwtauth.ClaimsMapping{
        UserID:   "sub",
        TenantID: "tenant_id",
        Roles:    "realm_access.roles",
    },
})

server := connect.NewServer(jwtauth.NewInterceptor(auth))
servicepb.RegisterServiceHandler(server, &Server{})
connecthttp.Mount(mux, server)

Claims available via ctxutil.UserID(ctx), ctxutil.Roles(ctx), etc.

connectrpc/recovery

Panic recovery interceptor. Catches panics, logs with stack trace, returns CodeInternal.

server := connect.NewServer(
    recovery.NewInterceptor(),
    // ... other interceptors
)
servicepb.RegisterServiceHandler(server, &Server{})
connecthttp.Mount(mux, server)

Logs include: procedure, panic value, stack trace. Request fields come from slogutil.ContextHandler.

connectrpc/logging

Structured request/response logging. Success at Info, errors at Warn.

server := connect.NewServer(logging.NewInterceptor())
servicepb.RegisterServiceHandler(server, &Server{})
connecthttp.Mount(mux, server)

Log attributes: procedure, status, error (on failure). Request fields come from slogutil.ContextHandler.

connectrpc/requestid

Propagates or generates request IDs. Stores in context via ctxutil.WithRequestID.

server := connect.NewServer(requestid.NewInterceptor(requestid.Config{
    HeaderName: "X-Request-ID", // default
}))
servicepb.RegisterServiceHandler(server, &Server{})
connecthttp.Mount(mux, server)

Generated IDs are UUID v4 without hyphens (32 characters).

connectrpc/errors

Maps errors to Connect RPC codes. Unmapped errors return CodeInternal with sanitized message.

server := connect.NewServer(errors.NewInterceptor())
servicepb.RegisterServiceHandler(server, &Server{})
connecthttp.Mount(mux, server)

Implement ConnectCoder on errors:

type ErrNotFound struct{ ID string }

func (e *ErrNotFound) Error() string {
    return fmt.Sprintf("resource %s not found", e.ID)
}

func (e *ErrNotFound) ConnectCode() connect.Code {
    return connect.CodeNotFound
}

Error mapping priority:

  1. context.Canceled → CodeCanceled
  2. context.DeadlineExceeded → CodeDeadlineExceeded
  3. ConnectCoder interface → custom code
  4. *connect.Error → preserved
  5. Other errors → CodeInternal (message: "internal error")

Mapped errors (1-4) preserve original message. Unmapped errors (5) hide details; the original error stays available server-side as the cause (errors.Is/errors.As).

connectrpc/deadline

Enforces deadlines on unary calls; streaming calls pass through. Applies a default timeout when none exists, and caps existing deadlines to a maximum.

server := connect.NewServer(deadline.NewInterceptor(deadline.Config{
    DefaultTimeout: 30 * time.Second, // applied when no deadline exists
    MaxTimeout:     60 * time.Second, // caps existing deadlines (0 = no cap)
}))
servicepb.RegisterServiceHandler(server, &Server{})
connecthttp.Mount(mux, server)
connectrpc/interceptor

All connectrpc interceptors target connect-go v2 and are connect.ServerInterceptors. connect-go v2 limits messages to 4 MiB by default; raise it with connecthttp.WithReadMaxBytes on connecthttp.Mount.

Default interceptor chain builder. Order: recovery → deadline → requestid → otel → logging → [jwtauth] → validate → errors.

interceptors, _ := interceptor.BuildDefault()                      // 7 interceptors
interceptors, _ := interceptor.BuildDefaultWithAuth(auth)          // 8 interceptors (with JWT)
interceptors, _ := interceptor.BuildDefault(                       // with options
    interceptor.WithDeadline(deadline.Config{DefaultTimeout: 60 * time.Second}),
)

server := connect.NewServer(interceptors...)
servicepb.RegisterServiceHandler(server, &Server{})
connecthttp.Mount(mux, server)
connectrpc/tracing (via otelconnect)

For OpenTelemetry tracing and metrics, use the official otelconnect library:

go get connectrpc.com/otelconnect
import "connectrpc.com/otelconnect"

otelInterceptor, _ := otelconnect.NewServerInterceptor()

server := connect.NewServer(otelInterceptor)
servicepb.RegisterServiceHandler(server, &Server{})
connecthttp.Mount(mux, server)

Options:

  • WithTrustRemote() - Trust incoming trace context (internal services)
  • WithServerPeerAttributes() - Add peer address/port to server spans (off by default, high cardinality)
connectrpc/validation (via validate)

For request validation using protovalidate rules, use the official validate library:

go get connectrpc.com/validate
import "connectrpc.com/validate"

validateInterceptor := validate.NewServerInterceptor()

server := connect.NewServer(validateInterceptor)
servicepb.RegisterServiceHandler(server, &Server{})
connecthttp.Mount(mux, server)

Returns CodeInvalidArgument with field-level violation details on validation failure.

Directories

Path Synopsis
internal
aggregateaccess
Package aggregateaccess is the infrastructure side of package aggregate.
Package aggregateaccess is the infrastructure side of package aggregate.
aggregateaccess/hook
Package hook lets package aggregate hand its bookkeeping to internal/aggregateaccess without exporting it.
Package hook lets package aggregate hand its bookkeeping to internal/aggregateaccess without exporting it.
backoff
Package backoff computes jittered retry delays, fixed step schedules and poll intervals for the event-sourcing, scheduler and inbox runtimes.
Package backoff computes jittered retry delays, fixed step schedules and poll intervals for the event-sourcing, scheduler and inbox runtimes.
connecttest
Package connecttest serves single RPCs through a connect.Server so server interceptors can be tested without a transport.
Package connecttest serves single RPCs through a connect.Server so server interceptors can be tested without a transport.
consumerhook
Package consumerhook lets package consumer hand a Reactor and a Projection what they need from a Runtime and its runner without exporting it.
Package consumerhook lets package consumer hand a Reactor and a Projection what they need from a Runtime and its runner without exporting it.
consumertest
Package consumertest is the contract suite that every consumer Runtime (Pg and in-memory) must pass.
Package consumertest is the contract suite that every consumer Runtime (Pg and in-memory) must pass.
eventstoretest
Package eventstoretest is the write-side contract suite that every eventstore backend (Pg and in-memory) must pass.
Package eventstoretest is the write-side contract suite that every eventstore backend (Pg and in-memory) must pass.
pgtest
Package pgtest runs Postgres-backed tests against one shared testcontainers Postgres per test binary.
Package pgtest runs Postgres-backed tests against one shared testcontainers Postgres per test binary.
quickstart/app
Package app is the application layer of the quickstart service: its commands, its queries, the task_list Projection and the notify_assignee Reactor.
Package app is the application layer of the quickstart service: its commands, its queries, the task_list Projection and the notify_assignee Reactor.
quickstart/server command
Command server is the Postgres main of the quickstart service.
Command server is the Postgres main of the quickstart service.
quickstart/todo
Package todo is the domain of the quickstart service.
Package todo is the domain of the quickstart service.
reactortest
Package reactortest is the contract suite that every Reactor backend (Pg and in-memory consumer Runtimes) must pass.
Package reactortest is the contract suite that every Reactor backend (Pg and in-memory consumer Runtimes) must pass.
safecall
Package safecall runs user callbacks (handlers, reactions, jobs) under a timeout and turns their panics into errors, the same way for every runner.
Package safecall runs user callbacks (handlers, reactions, jobs) under a timeout and turns their panics into errors, the same way for every runner.
safeid
Package safeid checks identifiers taken from untrusted input, such as a client's request ID, before they are logged or stored.
Package safeid checks identifiers taken from untrusted input, such as a client's request ID, before they are logged or stored.
storehook
Package storehook lets eventstore hand the read side of its stores to the consumer runtimes without exporting it.
Package storehook lets eventstore hand the read side of its stores to the consumer runtimes without exporting it.
telemetry
Package telemetry is the single registry of span names, metric instruments, attribute keys, log keys and histogram boundaries used by the event-sourcing, scheduler, inbox, notify and lease packages.
Package telemetry is the single registry of span names, metric instruments, attribute keys, log keys and histogram boundaries used by the event-sourcing, scheduler, inbox, notify and lease packages.
pkg
connectrpc
Package connectrpc provides interceptors for Connect RPC services.
Package connectrpc provides interceptors for Connect RPC services.
connectrpc/deadline
Package deadline provides deadline enforcement for Connect RPC handlers.
Package deadline provides deadline enforcement for Connect RPC handlers.
connectrpc/errors
Package errors provides error mapping for Connect RPC handlers.
Package errors provides error mapping for Connect RPC handlers.
connectrpc/interceptor
Package interceptor provides default interceptor chain builders for Connect RPC services.
Package interceptor provides default interceptor chain builders for Connect RPC services.
connectrpc/jwtauth
Package jwtauth provides JWT authentication for Connect RPC services.
Package jwtauth provides JWT authentication for Connect RPC services.
connectrpc/logging
Package logging provides structured request/response logging for Connect RPC handlers.
Package logging provides structured request/response logging for Connect RPC handlers.
connectrpc/recovery
Package recovery provides panic recovery for Connect RPC handlers.
Package recovery provides panic recovery for Connect RPC handlers.
connectrpc/requestid
Package requestid provides request ID propagation for Connect RPC handlers.
Package requestid provides request ID propagation for Connect RPC handlers.
ctxutil
Package ctxutil provides utility functions for storing and retrieving request-scoped values in context.Context.
Package ctxutil provides utility functions for storing and retrieving request-scoped values in context.Context.
eventsourcing/aggregate
Package aggregate is the domain-facing side of event sourcing.
Package aggregate is the domain-facing side of event sourcing.
eventsourcing/aggregate/aggregatetest
Package aggregatetest builds Aggregates from a history of events for domain unit tests, without a Repository, Codec or database.
Package aggregatetest builds Aggregates from a history of events for domain unit tests, without a Repository, Codec or database.
eventsourcing/consumer
Package consumer runs Consumers: named, Cursor-tracked readers of the event log.
Package consumer runs Consumers: named, Cursor-tracked readers of the event log.
eventsourcing/eventstore
Package eventstore stores domain events in the event log.
Package eventstore stores domain events in the event log.
eventsourcing/projection
Package projection runs versioned read models (ADR-0005).
Package projection runs versioned read models (ADR-0005).
eventsourcing/reactor
Package reactor turns events into commands (ADR-0007).
Package reactor turns events into commands (ADR-0007).
grpchealth
Package grpchealth provides a health check aggregator for connectrpc.com/grpchealth/v2.
Package grpchealth provides a health check aggregator for connectrpc.com/grpchealth/v2.
inbox
Package inbox is a durable, deduplicated, leased work queue in Postgres for incoming external messages such as webhooks.
Package inbox is a durable, deduplicated, leased work queue in Postgres for incoming external messages such as webhooks.
koanfutil
Package koanfutil provides utilities for koanf configuration loading.
Package koanfutil provides utilities for koanf configuration loading.
nats
Package nats provides NATS and JetStream connection utilities with tracing integration.
Package nats provides NATS and JetStream connection utilities with tracing integration.
otel
Package otel provides OpenTelemetry initialization for tracing, metrics, and logging.
Package otel provides OpenTelemetry initialization for tracing, metrics, and logging.
postgres
Package postgres provides database access utilities with tracing integration.
Package postgres provides database access utilities with tracing integration.
postgres/guard
Package guard enforces tenant-scoped uniqueness rules, such as "one user per e-mail address".
Package guard enforces tenant-scoped uniqueness rules, such as "one user per e-mail address".
postgres/lease
Package lease grants mutual exclusion between processes through Postgres session advisory locks, all held on one connection per process.
Package lease grants mutual exclusion between processes through Postgres session advisory locks, all held on one connection per process.
postgres/notify
Package notify multiplexes Postgres LISTEN/NOTIFY over one connection per process.
Package notify multiplexes Postgres LISTEN/NOTIFY over one connection per process.
postgres/numbering
Package numbering hands out gapless numbers per (tenant, context, name), such as invoice numbers.
Package numbering hands out gapless numbers per (tenant, context, name), such as invoice numbers.
scheduler
Package scheduler runs jobs that are due at most once and never catches up on missed runs (ADR-0008).
Package scheduler runs jobs that are due at most once and never catches up on missed runs (ADR-0008).
shutdown
Package shutdown provides graceful shutdown orchestration for services.
Package shutdown provides graceful shutdown orchestration for services.
slogutil
Package slogutil provides configuration and setup utilities for slog.
Package slogutil provides configuration and setup utilities for slog.
tracing
Package tracing provides utility functions for manual span creation.
Package tracing provides utility functions for manual span creation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL