utils

package module
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Jul 27, 2026 License: MIT Imports: 0 Imported by: 0

README

egl-utils-go

Production-ready Go utilities for concurrency, resilience, HTTP middleware, configuration, and observability.

Status

Part of the Enterprise-Grade Libraries series. A library written in Go 1.25+, built and governed to an enterprise quality bar: full CI matrix, static analysis, sanitizers, documented design decisions, and SemVer releases.

What it is

Provide a production-ready Go utilities module — advanced concurrency primitives, resilience patterns, high-performance HTTP middleware, and API-development helpers — that removes boilerplate and correctness risk (goroutine leaks, GC pressure, unsafe shutdown) from Go backend services. Design philosophy (imported from the brief): idiomatic Go throughout (channels, context.Context, the error interface); zero goroutine leaks — every internal goroutine stops deterministically via context or close(done); allocation-conscious hot paths via pointer discipline and sync.Pool object reuse.

The frozen specification is in docs/specs/01_spec_utils.md.

Build, test, run

go build ./...
go test ./...
  • Toolchain: go build (go modules), go test (+ testify; rapid for property tests), gofumpt (gofmt superset), golangci-lint (govet, staticcheck, errcheck, revive, gosec).
  • Supported platforms: Linux / Windows / macOS on Go 1.25 & 1.26 (module floor 1.25).
  • Consumers import the public surface via: import "github.com/danielPoloWork/egl-utils-go/workerpool".
  • contrib/ holds separate modules, each with its own go.mod — driver-backed health.Check probes for Redis and PostgreSQL, kept out of this module so a consumer inherits no driver dependencies. ./... does not descend into a nested module, so they are built and tested from their own directories (cd contrib/redishealth && go test ./...) and version independently. See contrib/README.md and ADR-0040.

See docs/development/local-build.md for the full local setup.

How this project is run

Document Purpose
AGENTS.md How AI agents (and humans) work in this repo — the contract.
ROADMAP.md The numbered plan and what is done.
docs/adr/ Why it is built the way it is (Architecture Decision Records).
docs/patterns/ Design patterns adopted, rejected, or considered.
docs/workflow/ Git, documentation, release, and maintenance conventions.
CHANGELOG.md User-visible changes per release.
SECURITY.md How to report a vulnerability.

Milestones

# Title Status
1 Project bootstrap & CI ✅ done
2 Concurrency primitives ✅ done
3 Resilience patterns ✅ done
4 HTTP middleware ✅ done
5 Configuration & environment ✅ done
6 Structured logging ✅ done
7 Caching & data helpers ✅ done
8 Validation & security ✅ done
9 Diagnostics & lifecycle ✅ done
10 Spec v2 reconciliation (v1.x additive) ✅ done
11 Governance: namespace contract & spec reconciliation ✅ done
12 Public-interface reconciliation ✅ done

License

MIT © 2026 Daniel Polo. See LICENSE.

Documentation

Overview

Package utils is the root of the egl-utils-go module: production-ready Go utilities for concurrency, resilience, HTTP middleware, configuration, and observability, delivered as small, orthogonal feature packages that compose through standard-library contracts (context.Context, net/http.Handler, error) only.

The root package carries module-wide metadata such as Version. Feature packages live in their own directories at the module root and are imported individually, e.g. 

import "github.com/danielPoloWork/egl-utils-go/workerpool"

The layout is decided in ADR-0003 (docs/adr/0003-adopt-idiomatic-go-root-layout.md).

Index

Constants

View Source 
const Version = "1.1.1"

Version is the module's current Semantic Version. It is the source of truth the README status badge and release tags must stay in lockstep with (enforced by tools/consistency_lint.py; release protocol in AGENTS.md §11).

Variables

This section is empty.

Functions

This section is empty.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
Package cache provides a generic in-memory key-value cache with per-cache TTL expiry and a periodic cleanup goroutine.
 Package cache provides a generic in-memory key-value cache with per-cache TTL expiry and a periodic cleanup goroutine.
Package circuitbreaker provides a concurrency-safe circuit breaker guarding calls to an unreliable dependency: a closed/open/half-open state machine that fails fast with ErrOpen while the dependency recovers, then re-admits a bounded number of probe calls before closing again.
 Package circuitbreaker provides a concurrency-safe circuit breaker guarding calls to an unreliable dependency: a closed/open/half-open state machine that fails fast with ErrOpen while the dependency recovers, then re-admits a bounded number of probe calls before closing again.
Package config loads typed configuration from a JSON or YAML file, with optional environment-variable expansion and post-load validation.
 Package config loads typed configuration from a JSON or YAML file, with optional environment-variable expansion and post-load validation.
contrib
pgxhealth module
redishealth module
Package db provides a transaction helper that runs a function inside a SQL transaction, committing on success and rolling back on error or panic.
 Package db provides a transaction helper that runs a function inside a SQL transaction, committing on success and rolling back on error or panic.
Package env reads environment variables with safe typed fallbacks.
 Package env reads environment variables with safe typed fallbacks.
Package errors adds a context message and a one-time captured call stack to an error, while staying fully interoperable with the standard library's errors package (errors.Is, errors.As, errors.Unwrap).
 Package errors adds a context message and a one-time captured call stack to an error, while staying fully interoperable with the standard library's errors package (errors.Is, errors.As, errors.Unwrap).
Package fanin merges multiple input channels into a single output channel — the fan-in half of the Go pipelines vocabulary (the fan-out half is package fanout).
 Package fanin merges multiple input channels into a single output channel — the fan-in half of the Go pipelines vocabulary (the fan-out half is package fanout).
Package fanout distributes values from one input channel across multiple output channels — the fan-out half of the Go pipelines vocabulary (the fan-in half is package fanin).
 Package fanout distributes values from one input channel across multiple output channels — the fan-out half of the Go pipelines vocabulary (the fan-in half is package fanin).
Package hash hashes and verifies passwords with bcrypt.
 Package hash hashes and verifies passwords with bcrypt.
Package health provides a preconfigured HTTP health-check handler that runs a set of dependency probes and reports readiness.
 Package health provides a preconfigured HTTP health-check handler that runs a set of dependency probes and reports readiness.
Package lifecycle coordinates the ordered shutdown of a process's resources — HTTP servers, database pools, queues — when a termination signal arrives or Shutdown is called.
 Package lifecycle coordinates the ordered shutdown of a process's resources — HTTP servers, database pools, queues — when a termination signal arrives or Shutdown is called.
Package logger builds structured slog loggers tuned for log aggregation and carries per-request logger fields through a context.Context.
 Package logger builds structured slog loggers tuned for log aggregation and carries per-request logger fields through a context.Context.
Package metrics provides Prometheus instrumentation for HTTP handlers.
 Package metrics provides Prometheus instrumentation for HTTP handlers.
Package middleware provides composable net/http middleware as standard decorators.
 Package middleware provides composable net/http middleware as standard decorators.
Package pubsub provides a minimal in-memory publish-subscribe broker over Go channels with per-subscription filters.
 Package pubsub provides a minimal in-memory publish-subscribe broker over Go channels with per-subscription filters.
Package ratelimit provides a token-bucket rate limiter: a bucket of burst tokens refills continuously at rate tokens per second, each admitted call costs one token, and callers choose between failing fast (Allow) and queueing for the next token (Wait).
 Package ratelimit provides a token-bucket rate limiter: a bucket of burst tokens refills continuously at rate tokens per second, each admitted call costs one token, and callers choose between failing fast (Allow) and queueing for the next token (Wait).
Package retry provides function execution with retry, exponential backoff, and random jitter: Backoff runs a call until it succeeds, its attempt budget is spent, or its context ends, sleeping between attempts with exponentially growing, jittered, hard-capped delays.
 Package retry provides function execution with retry, exponential backoff, and random jitter: Backoff runs a call until it succeeds, its attempt budget is spent, or its context ends, sleeping between attempts with exponentially growing, jittered, hard-capped delays.
Package semaphore provides Weighted, a weighted counting semaphore for admission control: a caller Acquires some weight before doing work and Releases it afterward, bounding the total concurrent weight to a fixed capacity.
 Package semaphore provides Weighted, a weighted counting semaphore for admission control: a caller Acquires some weight before doing work and Releases it afterward, bounding the total concurrent weight to a fixed capacity.
Package syncpool provides a pool of reusable *bytes.Buffer values to relieve GC pressure on temporary-buffer hot paths (serialization, string building).
 Package syncpool provides a pool of reusable *bytes.Buffer values to relieve GC pressure on temporary-buffer hot paths (serialization, string building).
Package validator validates struct values against rules declared in `validate:"..."` struct tags.
 Package validator validates struct values against rules declared in `validate:"..."` struct tags.
Package workerpool provides a bounded, context-aware goroutine pool: a fixed set of worker goroutines consumes tasks from a bounded queue, giving callers backpressure — block until space frees (default) or fail fast with ErrQueueFull (WithNonBlockingSubmit) — instead of unbounded goroutine growth.
 Package workerpool provides a bounded, context-aware goroutine pool: a fixed set of worker goroutines consumes tasks from a bounded queue, giving callers backpressure — block until space frees (default) or fail fast with ErrQueueFull (WithNonBlockingSubmit) — instead of unbounded goroutine growth.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.