# nurago

> 70 independent Go packages for backend services. Each is imported on its
> own and pulls only its own dependencies; 40 reach no external module at all.

Install: `go get github.com/tecnickcom/nurago`
Reference documentation: https://pkg.go.dev/github.com/tecnickcom/nurago

## Documentation

- [Home](https://nurago.org/): What nurago is, how to install it, and a minimal service.
- [Packages](https://nurago.org/packages/): All 70 packages, grouped by what they do.
- [Getting started](https://nurago.org/docs/getting-started/): Installing, importing a package, and wiring a service lifecycle.
- [Service scaffolding](https://nurago.org/docs/service-scaffolding/): Generating a complete web service with make project.
- [Dependency footprint](https://nurago.org/docs/dependency-footprint/): What each import pulls into the build, and how to verify it.
- [Observability](https://nurago.org/docs/observability/): Logging, metrics backends, trace IDs, and log redaction.
- [Resilience](https://nurago.org/docs/resilience/): Retries, backoff and jitter, Retry-After, periodic work, DNS caching.
- [Security](https://nurago.org/docs/security/): Password storage, breach checks, JWT, encryption, private endpoints.
- [Data and messaging](https://nurago.org/docs/data-and-messaging/): SQL, locking, Redis, Valkey, Kafka, S3, SQS.
- [Testing](https://nurago.org/docs/testing/): Test helpers, injectable clients, mocks, and the QA pipeline.
- [Migration from gogen](https://nurago.org/docs/migration-from-gogen/): Moving off the deprecated github.com/tecnickcom/gogen module path.
- [Development](https://nurago.org/docs/development/): Makefile workflow, linting, coverage, benchmarks, Docker.
- [AI coding assistants](https://nurago.org/docs/ai-assistants/): llms.txt, MCP retrieval, project rules, and the facts to pin.
- [Features](https://nurago.org/features/): Capability index, grouped by area.
- [Comparison](https://nurago.org/comparison/): nurago next to a framework, an internal library, and the standard library.
- [Articles](https://nurago.org/articles/): In-depth articles on the design of individual packages.

## Packages

- [bootstrap](https://nurago.org/packages/bootstrap/): bootstrap wires together the core infrastructure of a Go service: context lifecycle, structured logging, metrics collection, OS signal handling, and graceful shutdown, in a single function call.
- [config](https://nurago.org/packages/config/): config provides configuration bootstrap for Go services built on top of Viper.
- [httpserver](https://nurago.org/packages/httpserver/): httpserver provides a configurable HTTP server bootstrap for Go services.
- [httputil](https://nurago.org/packages/httputil/): httputil provides HTTP request/response primitives for Go services built on top of net/http.
- [jsendx](https://nurago.org/packages/jsendx/): jsendx implements an extended JSend response envelope for HTTP APIs.
- [healthcheck](https://nurago.org/packages/healthcheck/): healthcheck runs dependency probes concurrently and aggregates them into a single HTTP health endpoint.
- [profiling](https://nurago.org/packages/profiling/): profiling bridges Go's built-in net/http/pprof profiling tool and the httprouter request router, allowing all pprof endpoints to be served through a single wildcard route without manual per-handler registration.
- [logutil](https://nurago.org/packages/logutil/): logutil provides configuration-driven logging utilities built around Go's standard log/slog package.
- [logsrv](https://nurago.org/packages/logsrv/): logsrv provides a zerolog backend exposed through the standard log/slog API.
- [metrics](https://nurago.org/packages/metrics/): metrics defines a backend-agnostic instrumentation contract for Go services.
- [opentel](https://nurago.org/packages/opentel/): opentel implements github.com/tecnickcom/nurago/pkg/metrics.Client using OpenTelemetry for both metrics and tracing.
- [prometheus](https://nurago.org/packages/prometheus/): prometheus implements github.com/tecnickcom/nurago/pkg/metrics.Client using the Prometheus client ecosystem.
- [statsd](https://nurago.org/packages/statsd/): statsd implements github.com/tecnickcom/nurago/pkg/metrics.Client using the StatsD protocol.
- [traceid](https://nurago.org/packages/traceid/): traceid captures a request-scoped trace ID at the service boundary: it reads the ID from an inbound HTTP header, propagates it through the context.Context for the lifetime of the request, and writes it back into outbound HTTP headers when calling downstream services, without coupling business logic to any particular tracing framework.
- [redact](https://nurago.org/packages/redact/): redact removes secrets from log lines and HTTP dumps before they are emitted.
- [httpclient](https://nurago.org/packages/httpclient/): httpclient provides a configurable outbound HTTP client with trace propagation and structured request/response logging.
- [httpretrier](https://nurago.org/packages/httpretrier/): httpretrier provides configurable retry execution for outbound HTTP requests.
- [httpreverseproxy](https://nurago.org/packages/httpreverseproxy/): httpreverseproxy provides a reverse-proxy client built on top of net/http/httputil.ReverseProxy.
- [retrier](https://nurago.org/packages/retrier/): retrier provides a configurable retry engine for executing a task function with backoff, jitter, and per-attempt timeouts.
- [backoff](https://nurago.org/packages/backoff/): backoff computes successive retry delays with exponential growth, a bounded maximum, and random jitter.
- [periodic](https://nurago.org/packages/periodic/): periodic schedules a task function to run repeatedly at a fixed interval, with optional random jitter and a per-invocation context timeout.
- [dnscache](https://nurago.org/packages/dnscache/): dnscache provides a local DNS cache that is safe for concurrent use, bounded in size, and uses single-flight request collapsing to avoid duplicate lookups.
- [passwordhash](https://nurago.org/packages/passwordhash/): passwordhash provides OWASP-compliant password hashing and verification using the Argon2id algorithm (RFC 9106), with an optional AES-GCM encryption layer (peppered hashing) for defense in depth.
- [passwordpwned](https://nurago.org/packages/passwordpwned/): passwordpwned checks whether a password has appeared in a known data breach, using the Have I Been Pwned (HIBP) Pwned Passwords API v3 (https://haveibeenpwned.com/API/v3#PwnedPasswords).
- [jwt](https://nurago.org/packages/jwt/): jwt provides an HTTP-oriented JWT authentication helper for username/password login flows: validate user credentials, issue short-lived signed JWTs, authorize protected endpoints from an Authorization header, and optionally renew tokens near expiration.
- [encrypt](https://nurago.org/packages/encrypt/): encrypt encrypts and decrypts data for transport and storage using AES-GCM authenticated encryption.
- [sqlconn](https://nurago.org/packages/sqlconn/): sqlconn manages a database/sql connection lifecycle in long-running Go services: applying pool limits, verifying connectivity, exposing health checks, and closing the connection on shutdown signals.
- [sqltransaction](https://nurago.org/packages/sqltransaction/): sqltransaction executes business logic inside a transaction with begin/commit/rollback control flow and consistent error handling.
- [sqlxtransaction](https://nurago.org/packages/sqlxtransaction/): sqlxtransaction handles begin/commit/rollback control flow around business logic executed inside a sqlx transaction.
- [sqlutil](https://nurago.org/packages/sqlutil/): sqlutil quotes identifiers and string literals when generating SQL query fragments dynamically.
- [mysqllock](https://nurago.org/packages/mysqllock/): mysqllock provides process-distributed mutual exclusion using MySQL's named lock primitives GET_LOCK and RELEASE_LOCK.
- [redis](https://nurago.org/packages/redis/): redis wraps go-redis for key/value storage, Pub/Sub messaging, typed payload encoding, and connection health checks.
- [valkey](https://nurago.org/packages/valkey/): valkey wraps the valkey-go client (https://github.com/valkey-io/valkey-go) for Valkey (https://valkey.io), a Redis-compatible in-memory data store. It covers key/value storage, typed data serialization, and Pub/Sub messaging behind a single Client type.
- [kafka](https://nurago.org/packages/kafka/): kafka provides a pure-Go API for producing and consuming Apache Kafka messages. It requires no CGO and no system librdkafka installation.
- [sqs](https://nurago.org/packages/sqs/): sqs wraps github.com/aws/aws-sdk-go-v2/service/sqs with an API that covers the common queue workflow: send, receive, decode, acknowledge (delete), and health-check.
- [s3](https://nurago.org/packages/s3/): s3 uploads, downloads, lists, and deletes S3 bucket objects through the AWS SDK v2 S3 client.
- [awsopt](https://nurago.org/packages/awsopt/): awsopt configures the aws-sdk-go-v2 library consistently across multiple AWS service clients. It centralizes config.LoadOptionsFunc calls into a composable Options slice that can be built once and handed to any AWS-based package in this library.
- [awssecretcache](https://nurago.org/packages/awssecretcache/): awssecretcache provides a local, thread-safe, fixed-size cache for AWS Secrets Manager lookups, with single-flight deduplication.
- [sfcache](https://nurago.org/packages/sfcache/): sfcache provides a local, thread-safe, fixed-size cache for expensive lookups with single-flight deduplication.
- [enumcache](https://nurago.org/packages/enumcache/): enumcache provides thread-safe storage and lookup for enumeration name and ID mappings.
- [enumdb](https://nurago.org/packages/enumdb/): enumdb loads enumeration sets from relational database tables into thread-safe enum caches.
- [enumbitmap](https://nurago.org/packages/enumbitmap/): enumbitmap encodes a set of enumeration values as an integer bitmap and decodes it back.
- [countrycode](https://nurago.org/packages/countrycode/): countrycode provides access to ISO-3166 country metadata.
- [countryphone](https://nurago.org/packages/countryphone/): countryphone resolves international phone number prefixes into country and regional metadata.
- [phonekeypad](https://nurago.org/packages/phonekeypad/): phonekeypad converts alphabetic strings and phone number literals to their numeric equivalents on a standard 12-key telephony keypad (ITU E.161 / ITU T.9).
- [encode](https://nurago.org/packages/encode/): encode serializes and deserializes values crossing system boundaries such as databases, queues, caches, and RPC payloads.
- [decint](https://nurago.org/packages/decint/): decint provides utility functions to parse and represent decimal values as fixed-point integers with a defined precision.
- [timeutil](https://nurago.org/packages/timeutil/): timeutil provides two JSON-friendly time types. The standard library's time.Time marshals as RFC-3339 only, and time.Duration marshals as a raw nanosecond integer, which mismatch APIs that expect human-readable strings like "1h30m" or "2023-01-02T15:04:05Z". DateTime and Duration marshal to and from such strings, and the datetime format is selected by a type parameter checked at compile time.
- [uhex](https://nurago.org/packages/uhex/): uhex provides fixed-width, lowercase hexadecimal encoders for unsigned integers and fixed-size byte arrays.
- [stringkey](https://nurago.org/packages/stringkey/): stringkey derives a stable, compact, non-cryptographic key from multiple text fields for lookup, deduplication, and idempotency-style identifiers.
- [strsplit](https://nurago.org/packages/strsplit/): strsplit splits strings into bounded-size chunks without breaking Unicode characters, keeping human-readable boundaries (spaces, punctuation, and newlines).
- [stringmetric](https://nurago.org/packages/stringmetric/): stringmetric provides string distance functions for approximate text matching, comparison, and fuzzy search.
- [random](https://nurago.org/packages/random/): random provides utility functions for generating random bytes, numeric identifiers, UID/UUID values, hexadecimal/base36 IDs, and configurable random strings.
- [maputil](https://nurago.org/packages/maputil/): maputil filters, maps, reduces, and inverts Go maps with generic functions.
- [sliceutil](https://nurago.org/packages/sliceutil/): sliceutil filters, maps, and reduces slices with generic functions, and summarizes numeric slices with descriptive statistics.
- [numtrie](https://nurago.org/packages/numtrie/): numtrie provides a generic, digit-indexed trie (prefix tree) for associating values of any type with numerical keys, with built-in support for partial/prefix matching and alphabetical (vanity) phone-number keys.
- [paging](https://nurago.org/packages/paging/): paging computes pagination metadata (current page, total pages, previous/next page numbers, and SQL OFFSET/LIMIT values) from three inputs: current page number, page size, and total item count.
- [filter](https://nurago.org/packages/filter/): filter provides declarative, rule-based filtering for in-memory slices. It evaluates structured Rule expressions against slice elements and filters the slice in place.
- [threadsafe](https://nurago.org/packages/threadsafe/): threadsafe defines lock interfaces for building reusable, goroutine-safe data structures and helpers without hard-coding a concrete lock type.
- [tsmap](https://nurago.org/packages/tsmap/): tsmap reads and writes maps shared across goroutines, taking a caller-supplied lock at every call site.
- [tsslice](https://nurago.org/packages/tsslice/): tsslice reads and writes slices shared across goroutines, taking a caller-supplied lock at every access.
- [errutil](https://nurago.org/packages/errutil/): errutil annotates errors with caller location, joins cleanup failures onto an existing error, and enumerates the errors inside an errors.Join value.
- [typeutil](https://nurago.org/packages/typeutil/): typeutil detects nil through interfaces, obtains zero values generically, dereferences pointers safely, and converts booleans to integers without a branch.
- [validator](https://nurago.org/packages/validator/): validator wraps https://github.com/go-playground/validator and adds custom validation rules, a template-based error translation engine, and a functional-options API.
- [slack](https://nurago.org/packages/slack/): slack provides a client for sending messages to Slack via Incoming Webhooks.
- [jirasrv](https://nurago.org/packages/jirasrv/): jirasrv provides a typed HTTP client foundation for Jira Server REST integrations.
- [devlake](https://nurago.org/packages/devlake/): devlake provides a Go client for the DevLake Webhook API.
- [sleuth](https://nurago.org/packages/sleuth/): sleuth provides a Go client for the Sleuth.io API, covering common write-side integrations for delivery metrics and operational signal ingestion.
- [ipify](https://nurago.org/packages/ipify/): ipify provides a small client to resolve the current instance public IP address using the ipify service (https://www.ipify.org/).
- [testutil](https://nurago.org/packages/testutil/): testutil provides test-only helpers for forcing I/O failures on demand, capturing process output, bootstrapping HTTP handlers, and normalizing time-variant values in assertions.

## Rules

- The module path is github.com/tecnickcom/nurago. The former
  github.com/tecnickcom/gogen path is deprecated and must not be used in new
  imports.
- Import individual packages under pkg/, not the module root. Each package
  pulls only the dependencies it reaches, and 40 of the 70 reach no
  external module at all.
- Packages that take configuration use variadic functional options: a New
  constructor with an opts ...Option parameter and WithXxx option functions.
- The module is at v1 and every exported symbol under pkg/ is stable within v1.
  A high patch number reflects frequent additive releases, not API churn.

## Optional

- [Reference documentation](https://pkg.go.dev/github.com/tecnickcom/nurago): generated API reference for every package, with runnable examples.
- [Source repository](https://github.com/tecnickcom/nurago): source, issues, and the repository llms.txt.
- [Context7](https://context7.com/tecnickcom/nurago): the repository indexed for MCP documentation retrieval.