Features

What the library provides, grouped by area, with a link to the package that covers each item. For how this compares with the alternatives, see /comparison/. For the packages themselves, grouped and described, see /packages/.

Service Lifecycle

• Context, structured logger, metrics client, OS signal handling, and bounded graceful shutdown in a single call. See /packages/bootstrap/.
• A shared shutdown channel and wait group that every component registers against, so one signal drains the whole service and the process waits for the slowest, up to a budget.
• Shutdown that exceeds its budget returns an error wrapping ErrShutdownTimeout rather than hanging.
• Configuration built from defaults, a searched local file, environment overrides, and an optional remote source, validated before the service starts. See /packages/config/.
• A file-less configuration path for containers: base64 JSON supplied through an environment variable.
• Project generation: a complete service, with packaging, containers, OpenAPI, and integration tests, from one configuration file. See /docs/service-scaffolding/.
• One worked feature in the generated service: a domain package, a database-backed repository, and public create, read, list, and delete endpoints registered only when a database is configured.

HTTP Server

• Option-driven server assembly with pluggable route binding, over httprouter. See /packages/httpserver/.
• Selectable built-in operational routes: /ping, /status, /metrics, /ip, /pprof/*option, and a generated route index.
• Startup validation: nil handlers or middleware, duplicate or malformed routes, and unknown default route identifiers are reported by the constructor as wrapped sentinel errors, not panics.
• Non-blocking start, ephemeral port discovery, context-aware shutdown with a configurable timeout, and abnormal-termination reporting.
• Global and per-route middleware, with per-route timeout override or opt-out.
• Default not-found, method-not-allowed, and panic handlers with structured logging, and net/http internal diagnostics routed to the structured logger.
• Plain TCP or TLS (HTTP/1.1 and HTTP/2 via ALPN) from certificate material or a supplied tls.Config.
• Request and response primitives: header decorators, path, query, and header extraction with defaults, no-cache and nosniff responses, full-buffer encoding with a 500 fallback on marshal failure, and a response-writer wrapper that captures status and size. See /packages/httputil/.
• RFC 9457 problem details for error responses, with not-found, method-not-allowed, and panic router fallbacks in the same format, a send helper for any other JSON-based media type, and reason phrases that fall back to the status class name for non-standard codes. See /packages/httputil/.
• An extended JSend response envelope carrying program name, version, release, RFC 3339 datetime, and Unix-nanosecond timestamp, with default handlers for the router fallbacks. See /packages/jsendx/.
• Concurrent dependency probes aggregated into one health endpoint: 200 when all pass, 503 when any fails, per-check results always in the payload, panics recovered and reported as failures. See /packages/healthcheck/.
• pprof served through a single httprouter wildcard route, without touching http.DefaultServeMux. See /packages/profiling/.
• Reverse proxying with automatic X-Forwarded-* headers, no followed redirects, a base-path boundary that rejects traversal before contacting the upstream, and 499 rather than 502 when the client disconnected first. See /packages/httpreverseproxy/.

Outbound HTTP

• A configurable client with automatic trace-ID propagation, generating a UUIDv7-based ID when the context carries none. See /packages/httpclient/.
• Structured request and response logging: summary metadata at normal levels, redacted dumps at debug level, bounded by a configurable maximum dump size.
• Query strings redacted before logging at every level, including the URL embedded in a failed request’s error.
• A private transport and connection pool per client, with MaxIdleConnsPerHost raised above the net/http default, plus hooks for a custom TLS config or a fully tuned transport.
• Per-request retry orchestration wrapping an already configured client. See /packages/httpretrier/.
• Retry policies for idempotent reads and for writes, selectable by HTTP method, with the decision function receiving both the response and the error.
• Retry-After honoured when enabled, jittered through the same helper as every other delay, and still bounded by your cap.
• Request body replay through Request.GetBody, with a clear error when the body cannot be recreated.
• A caching DNS dialer for http.Transport, with single-flight collapsing, a bounded cache, and case-insensitive host matching. See /packages/dnscache/.

Resilience

• Exponential backoff as a pure per-call calculator: no timers, no goroutines, no I/O. See /packages/backoff/.
• Three jitter strategies from the AWS taxonomy: additive, full, and equal.
• Both the exponential state and the jitter addition clamped, so no delay can overflow into a negative duration at any attempt count or configured maximum.
• A retry engine with a retry predicate, a per-attempt timeout separate from the overall deadline, and parent-context cancellation always respected. See /packages/retrier/.
• Fixed-interval scheduling with jitter, a per-invocation deadline, an eager first run, and optional initial jitter to spread a fleet’s first call. See /packages/periodic/.
• Bounded single-flight caching for expensive lookups, with TTL and failure-anchored stale windows. See /packages/sfcache/.

Observability

• log/slog handlers built from typed configuration, with JSON, text console, and discard output. See /packages/logutil/.
• Syslog-range severities (emergency through debug) extended with a trace level.
• A hook that intercepts every emitted record, used to count log lines by level as a metric.
• Bridges in both directions between the standard log package and slog.
• A zerolog backend behind the same log/slog API, with the divergences from the standard-library backend documented value shape by value shape. See /packages/logsrv/.
• A backend-agnostic metrics contract covering SQL, inbound and outbound HTTP, the metrics endpoint, and application counters, with a no-op default implementation. See /packages/metrics/.
• OpenTelemetry backend with otelhttp and otelsql instrumentation, environment-driven OTLP exporter selection, and W3C context propagation. See /packages/opentel/.
• Prometheus backend with Go runtime and process collectors, HTTP server and client metrics, SQL pool stats, and error counters. See /packages/prometheus/.
• StatsD backend pushing counters, gauges, and timers over UDP or TCP. See /packages/statsd/.
• Request-scoped trace IDs read from an inbound header, validated against injection, carried in the context, and written back onto outbound requests. See /packages/traceid/.

Secret Redaction

• Every rule matched in a single pass, so cost does not grow with the number of rules. See /packages/redact/.
• Sensitive HTTP headers, JSON keys (replacing a whole nested object or array), URL-encoded pairs, XML elements, and URL userinfo passwords in bare DSNs.
• JWT and JWE compact tokens in free text, query strings, and JSON values.
• Vendor credential literals by prefix: GitHub, Slack, Stripe, OpenAI and Anthropic, Hugging Face, SendGrid, AWS, Google, GitLab, DigitalOcean, Docker Hub, and Shopify.
• PEM private key blocks, with public blocks such as certificates left visible.
• Credit-card numbers by network prefix and length, contiguous or space- and dash-grouped, with an optional Luhn gate for fewer false positives.
• Token-exact key matching after camelCase, snake_case, kebab-case, and acronym normalisation, so monkey never matches key.
• Convergent output: re-redacting never reveals more and reaches a fixed point, so layered redaction does not keep mangling logs.
• Applied by default in the HTTP client, server, and reverse proxy, and overridable per component; disabling it requires naming InsecureNoRedaction.

Security

• Argon2id password hashing (RFC 9106) with OWASP-recommended defaults. See /packages/passwordhash/.
• Self-describing stored hashes that carry their own parameters, so cost can be raised without invalidating existing hashes, with rehash detection after a successful verification.
• An optional AES-GCM pepper layer for a secret held outside the database.
• Have I Been Pwned checks under k-anonymity: only a 5-character hash prefix leaves the process, with response padding, a size cap against decompression bombs, and malformed responses rejected rather than read as “not pwned”. See /packages/passwordpwned/.
• HMAC-only JWT (HS256, HS384, HS512) on the standard library, with the signature verified before the payload is decoded, making alg=none and asymmetric-to-HMAC confusion structurally impossible. See /packages/jwt/.
• Login, renew, and authorization handlers, middleware that injects verified claims into the request context, and token issue and verify for non-HTTP transports.
• AES-GCM authenticated encryption with a random nonce, raw and serialized (gob or JSON) helpers, and the key-rotation bound stated explicitly. See /packages/encrypt/.

SQL

• Connection lifecycle for long-running services: pool limits, connectivity verification, health check, and shutdown on a signal, a cancelled lifetime context, or a direct call. See /packages/sqlconn/.
• A <DRIVER>://<DSN> connection string form, or explicit driver and DSN.
• Transactions with begin, commit, and guarded rollback on error or panic, with rollback failures joined onto the original error. See /packages/sqltransaction/.
• The same helper for sqlx, when struct scanning inside the transaction is wanted. See /packages/sqlxtransaction/.
• Identifier and string-literal quoting for dynamically generated fragments, MySQL-like by default and replaceable per dialect. See /packages/sqlutil/.
• Process-distributed mutual exclusion on MySQL GET_LOCK and RELEASE_LOCK, with a keep-alive and a deadlock-free release. See /packages/mysqllock/.

Messaging and Storage

• Redis: key/value with expiration, typed values through pluggable codecs, Pub/Sub in raw and typed form, and a PING health check. See /packages/redis/.
• Valkey: the same surface over valkey-go. See /packages/valkey/.
• Kafka: pure Go, no CGO and no system librdkafka, with at-most-once and at-least-once consumption as an explicit choice and full in-sync-replica acknowledgment by default. See /packages/kafka/.
• SQS: send, receive, decode, acknowledge, and health-check, with FIFO rules enforced at construction and the region derived from the queue URL. See /packages/sqs/.
• S3: upload from a reader, download as a stream, list keys or objects with metadata by prefix, delete, and a health check that verifies access as well as reachability. See /packages/s3/.
• Shared AWS SDK v2 configuration composed once and handed to every AWS client. See /packages/awsopt/.
• A bounded, single-flight cache for AWS Secrets Manager lookups. See /packages/awssecretcache/.
• Serialization for values crossing system boundaries, backing the default codecs of the clients above. See /packages/encode/.
• Incoming-webhook messaging to Slack. See /packages/slack/.

Enumerations and Reference Data

• Thread-safe enumeration name and ID caches, and loading enumeration sets from database tables. See /packages/enumcache/ and /packages/enumdb/.
• Encoding a set of enumeration values as an integer bitmap, and decoding it back. See /packages/enumbitmap/.
• ISO-3166 country metadata: alpha-2, alpha-3 and numeric codes, English and French names, region, sub-region and intermediate region, assignment status, and TLD, with selection by geographic hierarchy, status, or domain. See /packages/countrycode/.
• ITU country calling code resolution by longest-prefix lookup over a trie, with an embedded default dataset and support for custom plans. See /packages/countryphone/.
• Alphabetic to numeric conversion on the ITU E.161 / T.9 telephone keypad, for vanity numbers. See /packages/phonekeypad/.

Data Handling

• Fixed-point decimals: values with up to six decimal places carried as scaled integers, so comparison, serialization, and transport stay deterministic. See /packages/decint/.
• JSON-friendly time types: a DateTime whose layout is a compile-time-checked type parameter (covering every standard library layout) and a Duration that marshals as “1h30m” rather than a nanosecond integer. See /packages/timeutil/.
• Fixed-width lowercase hexadecimal encoders for unsigned integers and byte arrays, branchless and allocation-free. See /packages/uhex/.
• Stable compact keys derived from several text fields, normalised (whitespace, case, Unicode NFC) and hashed, available as uint64, base-36, or fixed 16-character hex. See /packages/stringkey/.
• Chunking text to a byte limit without breaking runes, preferring newline, whitespace, and punctuation boundaries. See /packages/strsplit/.
• Rune-based Damerau-Levenshtein edit distance for fuzzy matching. See /packages/stringmetric/.
• Random bytes, numeric identifiers, UUIDv7, hex and base-36 identifiers, and configurable random strings, from crypto/rand by default, with unbiased sampling. See /packages/random/.

Collections and Generics

• Generic Filter, Map, and Reduce over slices, with index-aware callbacks. See /packages/sliceutil/.
• Descriptive statistics for any numeric slice: count, sum, min and max with indexes, range, mode, mean, median, entropy, variance, standard deviation, skewness, and excess kurtosis.
• Generic Filter, Map, Reduce, and Invert over maps, with the iteration-order caveats stated. See /packages/maputil/.
• A generic digit-indexed trie with O(k) longest-prefix lookup, partial matching, and vanity phone-number keys. See /packages/numtrie/.
• Pagination metadata and SQL OFFSET/LIMIT values from page number, page size, and total count, with out-of-range inputs clamped. See /packages/paging/.
• Declarative rule-based filtering of in-memory slices, with AND-of-OR rule groups, in-place filtering, and rules parseable from JSON or a URL query. See /packages/filter/.
• Lock interfaces for building goroutine-safe structures without hard-coding a lock type, plus map and slice helpers that take a caller-supplied lock at every access. See /packages/threadsafe/, /packages/tsmap/, and /packages/tsslice/.

Errors, Types and Validation

• Errors annotated with caller location, cleanup failures joined onto an existing error, and enumeration of the errors inside an errors.Join. See /packages/errutil/.
• Nil detection through interfaces (including a nil pointer in a non-nil interface), generic zero values, safe pointer dereference, and branchless bool-to-int. See /packages/typeutil/.
• Struct validation over go-playground/validator with custom rules, tag aliases, a template-based message translation engine, and typed errors carrying tag, parameter, namespace, field, and message. See /packages/validator/.

Service Clients

• Slack incoming webhooks, Jira Server REST, DevLake webhooks, Sleuth.io delivery metrics, and public IP resolution through ipify. See /packages/slack/, /packages/jirasrv/, /packages/devlake/, /packages/sleuth/, and /packages/ipify/.

Testing

• Readers and closers that fail on demand, output capture, an httprouter-backed handler bootstrap, and timestamp normalisation for golden-value assertions. See /packages/testutil/.
• An injectable client on every package that talks to a network dependency, so tests dial nothing.
• A no-op metrics implementation that still returns a working SQL connection.

Project Properties

• 70 packages in one module, each imported on its own; 40 reach no external module at all. See /docs/dependency-footprint/.
• One configuration idiom throughout: a New constructor with variadic WithXxx options.
• Errors exported as sentinels, matchable with errors.Is, rather than compared as strings.
• Semantic versioning with a stable exported API within v1.
• No CGO anywhere, including the Kafka client.
• Package documentation generated from the source, with the package READMEs and llms.txt verified in CI, so neither can drift from the code. The package pages on this site are generated from those READMEs.