Packages

The 70 nurago packages, grouped by what they do

Every package is imported on its own and pulls only the dependencies it reaches, so adopting one does not commit you to the rest. 40 of the 70 reach no external module at all: see /docs/dependency-footprint/.

go get github.com/tecnickcom/nurago

Each page below is the package documentation with a runnable example and the guidance on when the package is the right choice. The generated API reference for every package is on pkg.go.dev.

Service Bootstrap and Lifecycle

Wiring a service up: configuration, logging, metrics, signal handling, the HTTP server, and the health and profiling endpoints.

  • 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 : provides configuration bootstrap for Go services built on top of Viper.
  • httpserver : provides a configurable HTTP server bootstrap for Go services.
  • httputil : provides HTTP request/response primitives for Go services built on top of net/http.
  • jsendx : implements an extended JSend response envelope for HTTP APIs.
  • healthcheck : runs dependency probes concurrently and aggregates them into a single HTTP health endpoint.
  • 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.

Observability

Structured logging, the metrics contract and its backends, request-scoped trace IDs, and secret redaction before anything is emitted.

  • logutil : provides configuration-driven logging utilities built around Go’s standard log/slog package.
  • logsrv : provides a zerolog backend exposed through the standard log/slog API.
  • metrics : defines a backend-agnostic instrumentation contract for Go services.
  • opentel : implements github.com/tecnickcom/nurago/pkg/metrics.Client using OpenTelemetry for both metrics and tracing.
  • prometheus : implements github.com/tecnickcom/nurago/pkg/metrics.Client using the Prometheus client ecosystem.
  • statsd : implements github.com/tecnickcom/nurago/pkg/metrics.Client using the StatsD protocol.
  • 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 : removes secrets from log lines and HTTP dumps before they are emitted.

Outbound HTTP and Resilience

Calling other services and surviving their bad days: instrumented clients, retries, backoff, scheduling, and DNS caching.

  • httpclient : provides a configurable outbound HTTP client with trace propagation and structured request/response logging.
  • httpretrier : provides configurable retry execution for outbound HTTP requests.
  • httpreverseproxy : provides a reverse-proxy client built on top of net/http/httputil.ReverseProxy.
  • retrier : provides a configurable retry engine for executing a task function with backoff, jitter, and per-attempt timeouts.
  • backoff : computes successive retry delays with exponential growth, a bounded maximum, and random jitter.
  • periodic : schedules a task function to run repeatedly at a fixed interval, with optional random jitter and a per-invocation context timeout.
  • 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.

Security and Authentication

Password storage and breach checks, JWT authentication, and authenticated encryption.

  • 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 : 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 : 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 : encrypts and decrypts data for transport and storage using AES-GCM authenticated encryption.

SQL and Locking

Connection lifecycle, transaction control flow, query fragment quoting, and distributed locking on MySQL.

  • 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 : executes business logic inside a transaction with begin/commit/rollback control flow and consistent error handling.
  • sqlxtransaction : handles begin/commit/rollback control flow around business logic executed inside a sqlx transaction.
  • sqlutil : quotes identifiers and string literals when generating SQL query fragments dynamically.
  • mysqllock : provides process-distributed mutual exclusion using MySQL’s named lock primitives GET_LOCK and RELEASE_LOCK.

Messaging, Key/Value Stores and Object Storage

Clients for the stateful dependencies a service usually talks to.

  • redis : wraps go-redis for key/value storage, Pub/Sub messaging, typed payload encoding, and connection health checks.
  • 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.
  • kafka : provides a pure-Go API for producing and consuming Apache Kafka messages.
  • 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 : uploads, downloads, lists, and deletes S3 bucket objects through the AWS SDK v2 S3 client.

AWS Integration

Shared AWS SDK v2 configuration and a cache for Secrets Manager lookups.

  • awsopt : configures the aws-sdk-go-v2 library consistently across multiple AWS service clients.
  • awssecretcache : provides a local, thread-safe, fixed-size cache for AWS Secrets Manager lookups, with single-flight deduplication.

Local Caching

In-process caching with single-flight deduplication.

  • sfcache : provides a local, thread-safe, fixed-size cache for expensive lookups with single-flight deduplication.

Enumerations and Reference Data

Enumeration storage and encoding, plus ISO country and telephony reference data.

  • enumcache : provides thread-safe storage and lookup for enumeration name and ID mappings.
  • enumdb : loads enumeration sets from relational database tables into thread-safe enum caches.
  • enumbitmap : encodes a set of enumeration values as an integer bitmap and decodes it back.
  • countrycode : provides access to ISO-3166 country metadata.
  • countryphone : resolves international phone number prefixes into country and regional metadata.
  • 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).

Data Handling and Encoding

Serialization across system boundaries, fixed-point decimals, JSON-friendly time types, hexadecimal encoding, keys, text splitting and comparison, and random identifiers.

  • encode : serializes and deserializes values crossing system boundaries such as databases, queues, caches, and RPC payloads.
  • decint : provides utility functions to parse and represent decimal values as fixed-point integers with a defined precision.
  • timeutil : provides two JSON-friendly time types.
  • uhex : provides fixed-width, lowercase hexadecimal encoders for unsigned integers and fixed-size byte arrays.
  • stringkey : derives a stable, compact, non-cryptographic key from multiple text fields for lookup, deduplication, and idempotency-style identifiers.
  • strsplit : splits strings into bounded-size chunks without breaking Unicode characters, keeping human-readable boundaries (spaces, punctuation, and newlines).
  • stringmetric : provides string distance functions for approximate text matching, comparison, and fuzzy search.
  • random : provides utility functions for generating random bytes, numeric identifiers, UID/UUID values, hexadecimal/base36 IDs, and configurable random strings.

Collections and Generics

Generic operations on maps and slices, prefix lookup, pagination, declarative filtering, and goroutine-safe containers.

  • maputil : filters, maps, reduces, and inverts Go maps with generic functions.
  • sliceutil : filters, maps, and reduces slices with generic functions, and summarizes numeric slices with descriptive statistics.
  • 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 : 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 : provides declarative, rule-based filtering for in-memory slices.
  • threadsafe : defines lock interfaces for building reusable, goroutine-safe data structures and helpers without hard-coding a concrete lock type.
  • tsmap : reads and writes maps shared across goroutines, taking a caller-supplied lock at every call site.
  • tsslice : reads and writes slices shared across goroutines, taking a caller-supplied lock at every access.

Errors, Types and Validation

Error annotation, nil and zero-value handling through interfaces, and struct validation.

  • errutil : annotates errors with caller location, joins cleanup failures onto an existing error, and enumerates the errors inside an errors.Join value.
  • typeutil : detects nil through interfaces, obtains zero values generically, dereferences pointers safely, and converts booleans to integers without a branch.
  • validator : wraps https://github.com/go-playground/validator and adds custom validation rules, a template-based error translation engine, and a functional-options API.

Service Clients

Small typed clients for external APIs.

  • slack : provides a client for sending messages to Slack via Incoming Webhooks.
  • jirasrv : provides a typed HTTP client foundation for Jira Server REST integrations.
  • devlake : provides a Go client for the DevLake Webhook API.
  • sleuth : provides a Go client for the Sleuth.io API, covering common write-side integrations for delivery metrics and operational signal ingestion.
  • ipify : provides a small client to resolve the current instance public IP address using the ipify service (https://www.ipify.org/).

Testing

Helpers used only from tests.

  • 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.