nurago

Packages

Tue, 08 Sep 2026 00:00:00 +0000

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.

Documentation

Tue, 08 Sep 2026 00:00:00 +0000

One guide per topic, each linking to the package pages it covers.

Where to start

Three entry points, depending on what you are doing.

Adopting one package into an existing service. Go straight to its page under /packages/. Every package is importable on its own and pulls only the dependencies it reaches, so nothing else here has to be adopted with it.

Building a new service. /docs/getting-started/ wires the lifecycle end to end, and /docs/service-scaffolding/ generates a complete working project if you would rather start from one.

Search

Mon, 01 Jan 0001 00:00:00 +0000

Articles

Tue, 08 Sep 2026 00:00:00 +0000

One package at a time, at the depth the package page does not have room for: the failure that prompted the design, the trade-off taken, and the boundary of what the code promises.

These were first published on tecnick.com and moved here in September 2026, so that the writing sits alongside the packages it describes. The old URLs redirect.

Overview

Stop Rewriting Go Service Boilerplate : why the library exists and what a service lifecycle built on it looks like.

Reliability and Networking

Exponential Backoff with Jitter in Go, Without the Overflow Footgun : the AWS jitter strategies, and the clamps that keep exponential growth from wrapping into a negative duration. Package: backoff.
Between Two Attempts: What an HTTP Retry Loop Must Decide : judging the outcome, closing the body, replaying the request, honouring Retry-After, and knowing when to stop. Package: httpretrier.
Observing Outbound HTTP in Go Without Disturbing It : a cloned request, a timeout timer tied to the response body, three-source trace IDs, redacted logs, and bounded debug dumps. Package: httpclient.
Before the First Request and After the Last: a Go HTTP Server’s Edges : startup validation, a listener bound before serving, request contexts that survive shutdown, and the timeout lattice. Package: httpserver.
A Reverse Proxy Is Defined by What It Refuses to Do : no followed redirects, no whole-request timeout, no base-path escapes, no 502 for a client that went away. Package: httpreverseproxy.
A DNS-Caching Dialer for http.Transport in Go : ASCII-only host folding, single-flight caching, canonical dedup, family interleaving, rotation, and the attempt loop. Package: dnscache.
From singleflight to a Production Cache: a Gap Analysis : TTL caching, context provenance, failure-anchored stale windows, and bounded eviction. Package: sfcache.
A Distributed Lock in Go and MySQL, and Every Way the Session Can Betray You : a pinned connection, a bounded keep-alive, deadlock-free release, and what the lock cannot promise. Package: mysqllock.

Security

The Life of a Password: Argon2id in Production with nurago : one password followed through minting, storage, verification, and parameter migration. Package: passwordhash.
Checking Passwords Against Have I Been Pwned Without Leaking Them : what actually leaves the machine, what the padding hides, and why an unverifiable response must be an error. Package: passwordpwned.
The Classic JWT Attacks, Addressed by Construction in Go : alg=none, RSA-to-HMAC confusion, unverified JSON, weak keys, oversized tokens, immortal sessions, and the structural property that answers each. Package: jwt.
Redacting Secrets from Go Logs on a Performance Budget : a 256-entry byte-class table for speed, convergent and boundary-exact matching for safety. Package: redact.
Filtering Untrusted Client Queries in Go: Threat Model First : bounded input, RE2 linear-time matching, exact int64 comparison past 2^53, and boxing-free in-place evaluation. Package: filter.

Logging and Observability

A Production slog.Handler on Top of zerolog : extended syslog severities, open groups versus baked attributes, root trace IDs, pooled events, and the hazards of process-global state. Package: logsrv.

Data Structures and Encoding

A Longest-Prefix Trie for Numeric Keys, in Six Design Questions : the fixed 10-slot child array, the packed match status, vanity letter folding, value ownership, and what O(k) covers. Package: numtrie.
Packing an Entire Country Record into a Single uint64 : a full ISO 3166 record as a Reversible Numeric Composite Key, decoded with bit shifts. Package: countrycode.
Random IDs in Go, Trap by Trap: UUIDv7 and Unbiased Random Strings : entropy budgeting in UUIDv7, rejection sampling, reader contracts, and allocation-free formatting. Package: random.
Deriving a Fast Fixed-Width Hex Encoder in Go : from what encoding/hex does per byte to a branchless encoder on a 256-entry table. Package: uhex.

Longer form, elsewhere

Building a Production REST API in Go : twenty parts building one service end to end, from net/http and the startup path through configuration, shutdown, middleware, the request lifecycle, connection pools, one complete feature, testing and deployment. It stays on tecnick.com, because it is a Go guide that happens to use nurago rather than a nurago guide.

Features

Tue, 08 Sep 2026 00:00:00 +0000

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.

About

Sun, 20 Sep 2026 00:00:00 +0000

nurago is maintained by Nicola Asuni, trading as Tecnick.com LTD. It is MIT licensed and developed in the open at github.com/tecnickcom/nurago.

Where the library came from

The code is older than the name. Four names, in fact, and the LICENSE file records the whole chain:

From	What happened
2014	`gogen` starts at Tecnick.com as a Go service library and project generator
2020	Vonage refactors and extends gogen into gosrvlib, under the same authorship
2025-11-01	gosrvlib is merged back into gogen at Tecnick.com
2026-07-11	gogen is renamed nurago; the old module path is deprecated

The packages have been through multiple production API platforms, not only a personal repository.

Comparison

Tue, 08 Sep 2026 00:00:00 +0000

Four ways to get the infrastructure a backend service needs, each suited to a different situation. This page covers what nurago gives up along with what it provides. For the capability index, see /features/.

The Four Options

Approach	What you adopt	What it costs
Standard library only	Nothing beyond Go	Every service re-derives retries, shutdown, redaction, and health checks
A framework	An application structure and its runtime	The structure reaches into your code and is expensive to leave
An internal shared library	Your own module	You maintain, test, document, and version it
nurago	Individual packages	An external dependency per package you import

Against the Standard Library Alone

Go’s standard library covers a great deal of what a service does. net/http serves and calls, log/slog logs, database/sql handles pools and transactions, and context handles cancellation. Plenty of services need nothing more.

Sponsor

Tue, 08 Sep 2026 00:00:00 +0000

nurago is built and maintained by Nicola Asuni (Tecnick.com LTD). It is free, open-source infrastructure that backend services depend on in production.

Sponsorship pays for the unglamorous half of that: security fixes, dependency and Go version updates, vulnerability response, keeping the API stable across releases, and answering issues. If your company runs services built on these packages, it is closer to an insurance premium than to a donation.

Become a sponsor →

Legal

Mon, 01 Jan 0001 00:00:00 +0000

Trademarks

Any trademarks, service marks, collective marks, design rights, personality rights or similar rights that are mentioned, used or cited on this website are the property of their respective owners. Unless otherwise stated, this website and its owners are neither endorsed by nor affiliated with any of the holders of such rights, and cannot grant any rights to use otherwise protected materials. Your use of any such property is at your own risk.

Getting Started

Tue, 08 Sep 2026 00:00:00 +0000

nurago can be adopted one package at a time or used to wire a whole service. Both paths start from the same module.

Requirements

Go 1.26.0 or later (the minimum declared in go.mod; any newer release works).
No CGO and no system libraries.

Install

go get github.com/tecnickcom/nurago

Import the packages you need, individually. There is no root package to import and nothing to register at startup:

import (
 "github.com/tecnickcom/nurago/pkg/backoff"
 "github.com/tecnickcom/nurago/pkg/redact"
)

go mod tidy then keeps only the modules your imports actually reach. Importing one package does not pull the dependencies of the others: see /docs/dependency-footprint/.

Service Scaffolding

Tue, 08 Sep 2026 00:00:00 +0000

Besides the packages, the repository carries a working web service under examples/service and a generator that turns it into a new project with your own name, owner, and repository path. What you get is not a snippet to copy: it is a service with the lifecycle, configuration, routing, health endpoint, OpenAPI specifications, Docker build, packaging, and integration tests already wired and passing.

Generate a Project

git clone https://github.com/tecnickcom/nurago.git
cd nurago
cp project.cfg myproject.cfg

Edit myproject.cfg. The keys are the placeholders substituted throughout the generated tree:

Dependency Footprint

Tue, 08 Sep 2026 00:00:00 +0000

nurago is one Go module containing 70 packages, several of which wrap large third-party SDKs. The obvious worry is that importing one package drags all of that into the binary. It does not.

How It Works

Go resolves dependencies per package. The require list in a module’s go.mod is the set of modules that some package in it may need. What ends up in your build is what your own imports reach, transitively, and go mod tidy then prunes your go.sum and module graph to that set.

Observability

Tue, 08 Sep 2026 00:00:00 +0000

These concerns stay in separate packages so each can be adopted alone: what the service writes (logging), what it counts (metrics), what correlates a request’s records (trace IDs), and what must never reach the output (redaction).

Logging

Application code depends on the standard log/slog and nothing else. The handler behind it comes from either logutil or logsrv.

logutil is the configuration-driven path, on the standard library alone. Config and its options build handlers and loggers from typed settings; ParseLevel, ParseFormat, ValidLevel, and ValidFormat turn runtime configuration strings into those settings and reject the invalid ones. Output is JSON, text console, or discard. The severity model extends the syslog levels (emergency through debug) with a trace level, so a service can log at severities the standard slog levels do not name.

Resilience

Tue, 08 Sep 2026 00:00:00 +0000

Every dependency a service calls will fail sometimes. These packages decide when to try again and how long to wait. They share one delay calculator, so a single retry policy applies to HTTP and non-HTTP work alike.

The Delay Schedule

backoff is a pure calculator: no timing, no sleeping, no goroutines, no I/O. Given a base delay, a growth factor, a jitter ceiling, and a maximum, each call to Schedule.Next returns the next delay and advances the progression. You own the loop and the timer.

Security

Tue, 08 Sep 2026 00:00:00 +0000

The security-relevant packages, and the operational defaults worth checking before a service faces the internet.

Password Storage

passwordhash implements Argon2id (RFC 9106) following the OWASP Password Storage Cheat Sheet, with New() returning the RFC 9106 §4 defaults.

p := passwordhash.New()

hash, err := p.PasswordHash(plaintext) // store this
ok, err := p.PasswordVerify(plaintext, hash) // on login
upgrade, err := p.PasswordNeedsRehash(hash) // after a successful verify

By default the stored value is a base64-encoded JSON object of about 200 bytes that describes itself: algorithm name, Argon2id version, key and salt lengths, time and memory cost, parallelism, the random salt, and the derived key.

Data and Messaging

Tue, 08 Sep 2026 00:00:00 +0000

The stateful dependencies a backend service talks to. Every client here exposes a HealthCheck(ctx) error method that satisfies the healthcheck interface directly, so registering a dependency in the readiness endpoint needs no adapter.

SQL Connections

sqlconn manages a database/sql pool through the lifetime of a long-running service: applying pool limits, verifying connectivity, exposing a health check, and closing on shutdown. It reaches no external module (you supply the driver).

c, err := sqlconn.Connect(
 ctx,
 "mysql://user:pass@tcp(localhost:3306)/appdb",
 sqlconn.WithDefaultDriver("mysql"),
 sqlconn.WithShutdownSignalChan(shutdownCh),
 sqlconn.WithShutdownWaitGroup(&shutdownWG),
)

Connect accepts a <DRIVER>://<DSN> string; New takes the driver and DSN separately.

Testing

Tue, 08 Sep 2026 00:00:00 +0000

How to test code that uses nurago, and how nurago tests itself.

Test Helpers

testutil collects the helpers that make otherwise awkward branches testable. It is intended for use in tests only.

reader := testutil.NewErrorReader("read failed") // Read always fails
closer := testutil.NewErrorCloser("close failed") // Close always fails

output := testutil.CaptureOutput(t, func() {
 fmt.Println("hello")
})

h := testutil.RouterWithHandler(http.MethodGet, "/health", handler)

normalized := testutil.ReplaceDateTime(responseBody, "<DATETIME>")
normalized = testutil.ReplaceUnixTimestamp(normalized, "<UNIX_TS>")

The error reader and closer exercise I/O failure paths that are hard to trigger otherwise. CaptureOutput redirects stdout, stderr, and the default logger for the duration of a call. RouterWithHandler builds a real httprouter-backed handler, which is what a handler reading path parameters needs. ReplaceDateTime and ReplaceUnixTimestamp normalise generated timestamps so a JSON response can be compared against a fixed golden value.

Migration from gogen

Tue, 08 Sep 2026 00:00:00 +0000

This project was previously named gogen. Same library, same packages, new name.

The github.com/tecnickcom/gogen module path is deprecated. A build pinned to v1.145.0 or earlier keeps working, because those versions still declare module github.com/tecnickcom/gogen in their go.mod. From v1.146.0 onwards the tags declare the new module path, so the old import path no longer resolves at all:

go: github.com/tecnickcom/gogen@latest (v1.154.3) requires
	github.com/tecnickcom/gogen@v1.154.3: parsing go.mod:
	module declares its path as: github.com/tecnickcom/nurago
	 but was required as: github.com/tecnickcom/gogen

An old pin therefore keeps building until you try to update it, at which point the migration below is the only way forward.

Development

Tue, 08 Sep 2026 00:00:00 +0000

Working on nurago itself, or on a project generated from it.

Clone and Validate

git clone https://github.com/tecnickcom/nurago.git
cd nurago
make x

make x runs the whole flow from scratch: update the library version in the examples, format, clean, download and get dependencies, generate code, regenerate the documentation, run the QA pipeline, then build and test the service example. All artifacts and reports land in target/.

Requirements: Go 1.26.0 or later. No CGO.

AI Coding Assistants

Tue, 08 Sep 2026 00:00:00 +0000

Some of the readers of this documentation are language models writing code on someone’s behalf. This page collects what nurago publishes for them, and what to tell an assistant so its output compiles.

Machine-Readable Indexes

/llms.txt: the condensed index of this site and of all 70 packages, in the llms.txt format. One entry per package with its one-line description and its page URL, so an assistant can find the right package without crawling.
llms.txt in the repository: the same index pointing at the reference documentation on pkg.go.dev. It is generated from the package source by make gendoc and checked in CI, so it cannot drift from the code.
pkg.go.dev: the full generated API reference, including every runnable example.
Per-package pages on this site, each carrying the complete package documentation, its runnable example, and its exact dependency footprint: /packages/.

Every one of those is plain text or plain HTML, reachable without JavaScript. robots.txt allows every crawler, AI and assistant retrieval agents included.

bootstrap

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/bootstrap"

One call that builds the context, logger and metrics client, hands them to your wiring function, then blocks until a shutdown signal and waits for registered workers to finish.

err := bootstrap.Bootstrap(bind,
 bootstrap.WithLogConfig(logutil.DefaultConfig()),
 bootstrap.WithShutdownTimeout(30*time.Second),
 bootstrap.WithShutdownWaitGroup(shutdownWG),
 bootstrap.WithShutdownSignalChan(shutdownCh),
)

The sequence

A cancellable context is created and threaded through everything.
A metrics.Client is created.
A *slog.Logger is created.
Your BindFunc is called with all three. This is where servers, database connections and workers are registered.
Bootstrap blocks until SIGINT, SIGTERM, or external context cancellation.
The shutdown signal is broadcast on the shared channel and the context is cancelled.
It waits on the shared sync.WaitGroup, bounded by a timeout.

Your code appears once, at step 4, and receives the three things every component needs rather than constructing them itself or reaching for globals.

config

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/config"

Loads configuration from defaults, a file, the environment and optionally a remote source, in a fixed order, then validates the result. Built on Viper.

An application implements two methods:

SetDefaults(v Viper) // register application defaults
Validate() error // enforce final constraints

The load order

Later steps override earlier ones:

Built-in defaults from this package (log and shutdown settings), plus your SetDefaults.
A local config file, config.json by default, searched in an explicit configDir first, then ./, $HOME/.<cmdName>/, /etc/<cmdName>/.
Environment overrides.
An optional remote source through WithRemoteLoader.
Validate.

Fixing the order is the point. The common alternative, each service resolving precedence in its own main, produces subtly different behaviour per service, and the difference is only discovered when an environment variable that works in one service is ignored in another.

httpserver

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/httpserver"

Builds and runs the HTTP server: your routes from a Binder, the operational routes from a built-in set, middleware, and a shutdown path that waits for in-flight work.

srv, err := httpserver.New(ctx, &binder{},
 httpserver.WithServerAddr(":8080"),
 httpserver.WithEnableDefaultRoutes(httpserver.PingRoute, httpserver.StatusRoute),
 httpserver.WithRequestTimeout(30*time.Second),
 httpserver.WithShutdownTimeout(10*time.Second),
)

srv.StartServer()

Misconfiguration is an error from New, not a panic

Nil handlers, nil middleware, duplicate routes, malformed routes and unknown default-route identifiers are all reported by New as wrapped sentinel errors.

httputil

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/httputil"

Request and response primitives for net/http handlers: header decorators, query and path extraction with defaults, buffered JSON/XML/text responses, RFC 9457 problem documents, and a ResponseWriter wrapper that captures status and size.

No framework, no router of its own, no interface your handlers must implement.

Reading a request

Header decorators for outbound requests:

httputil.AddJSONHeaders(r)
httputil.AddBearerToken(token, r)
httputil.AddBasicAuth(apiKey, apiSecret, r)
httputil.AddAuthorizationHeader(auth, r)

Extraction with defaults for inbound ones:

jsendx

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/httputil/jsendx"

One response shape for every endpoint in a service, whether it succeeded, failed, or panicked.

What the envelope adds to JSend

JSend is a minimal convention: a status of success, fail or error, and a data payload. It says nothing about anything else.

Response extends it with fields that answer operational questions from the response body alone:

healthcheck

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/healthcheck"

Turns a list of dependency probes into one HTTP endpoint that reports whether the service can do its job.

h := healthcheck.NewHandler([]healthcheck.HealthCheck{
 healthcheck.New("database", db),
 healthcheck.New("redis", redisClient),
 healthcheck.New("s3", s3Client),
})

One method, and the clients already have it

The contract is HealthCheck(context.Context) error. Every client in this module implements it directly, so registration needs no adapter: redis, valkey, sqs, s3, sqlconn, ipify and slack.

profiling

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/profiling"

Exposes Go’s net/http/pprof profiles through httprouter, as one handler on one wildcard route.

router.HandlerFunc(http.MethodGet, "/pprof/*option", profiling.PProfHandler)

The problem with importing net/http/pprof

The standard package registers its handlers on http.DefaultServeMux as an import side effect. That is convenient for a program serving from the default mux and a nuisance otherwise: it mutates global state on import, binds the paths to /debug/pprof/, and does not help at all with a router that is not the default mux.

logutil

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/logutil"

Builds log/slog loggers from typed configuration: format, level, common attributes, trace-ID injection and an optional hook, with parsing and validation for values that arrive as strings from a config file.

Two slog encoding faults it repairs

The handlers from Config.SlogHandler write through the standard library’s JSON or text handler, but filter the record first. Two of the differences are corrections to output the standard library gets wrong.

logsrv

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/logsrv"

A slog.Handler implemented on zerolog. Application code calls log/slog; zerolog does the encoding.

logger := logsrv.NewLogger(cfg)

It reuses the configuration model from logutil, so format selection, common attributes, trace-ID injection, hooks and the full syslog level names work identically across both backends.

Native handler, not an adapter

The distinction matters for what it costs. A naive bridge formats the slog record into a string or a map and hands that to zerolog, paying for an intermediate representation on every line.

metrics

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/metrics"

Defines the Client interface that service code instruments against, so the choice of metrics backend stays in main. Ships one no-op implementation; the real backends are opentel, prometheus and statsd.

The interface

Client covers the instrumentation points a service actually has, rather than exposing a generic counter/gauge/histogram vocabulary:

SqlOpen(driverName, dsn string) (*sql.DB, error)
InstrumentDB(name string, db *sql.DB) error
InstrumentHandler(path string, handler http.HandlerFunc) http.Handler
InstrumentRoundTripper(next http.RoundTripper) http.RoundTripper
MetricsHandlerFunc() http.HandlerFunc
IncLogLevelCounter(level string)
IncErrorCounter(task, operation, code string)
Close() error

Naming the integration points rather than the primitives is what makes the abstraction hold. A generic Counter(name string) interface leaks immediately, because Prometheus wants label dimensions declared up front, StatsD wants a dotted name, and OpenTelemetry wants attributes on an instrument. Wrapping an http.Handler is the same operation in all three.

opentel

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/metrics/opentel"

A metrics.Client backed by OpenTelemetry, covering metrics and distributed tracing through one client.

m, err := opentel.New(ctx, "myservice", "1.4.2")
defer m.Close()

Both signals, one construction

This is what separates it from the other two backends. prometheus and statsd do metrics. This one also produces spans, and the instrumentation points are shared: wrapping an HTTP handler records a duration histogram and starts a server span; wrapping a round tripper does the same on the client side and injects trace context into the outbound request.

prometheus

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/metrics/prometheus"

A metrics.Client backed by prometheus/client_golang.

m, err := prometheus.New()

What you get without defining a metric

The default registration is the reason to use this rather than wiring client_golang yourself. Out of New you have:

Go runtime and process collectors: goroutine count, heap, GC pause, open file descriptors, CPU.
Inbound HTTP: request count, in-flight gauge, duration histogram, request size histogram, response size histogram.
Outbound HTTP: request count, in-flight gauge, duration histogram.
SQL connection pool stats, through dlmiddlecote/sqlstats.
Error counters by log level and by task, operation and code.

That set answers most of what a service dashboard asks, and defining it by hand is a few hundred lines that every service repeats.

statsd

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/metrics/statsd"

A metrics.Client that pushes to a StatsD daemon, which aggregates and forwards to whatever sits behind it. Built on github.com/tecnickcom/statsd.

m, err := statsd.New(
 statsd.WithPrefix("myservice"),
 statsd.WithNetwork("udp"),
 statsd.WithAddress("127.0.0.1:8125"),
 statsd.WithFlushPeriod(time.Second),
)

Push, and what UDP buys

The process sends metrics out rather than waiting to be scraped, normally to an agent on the same host or in the same pod.

traceid

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/traceid"

Read an ID off an inbound request, carry it in the context, write it onto outbound requests. That is the whole loop, and it works without adopting OpenTelemetry or any other tracing framework.

// inbound, in middleware
id := traceid.FromHTTPRequestHeader(r, traceid.DefaultHeader, traceid.DefaultValue)
ctx := traceid.NewContext(r.Context(), id)

// outbound, before calling a downstream service
traceid.SetHTTPRequestHeaderFromContext(ctx, req, traceid.DefaultHeader, traceid.DefaultValue)

The header is untrusted input, and this package treats it that way

Validation happens at ingest.

redact

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/redact"

Replaces secrets in text with a marker, before it reaches a log.

safe := redact.Default().String(rawPayload)

One pass, whatever the pattern count

Every pattern is matched in a single pass over the input. Enabling more patterns does not make redaction slower.

That property is what makes it usable on the logging path at all. The obvious implementation, a slice of regular expressions applied in sequence, costs one full scan per pattern, so a realistic set of twenty patterns scans the input twenty times. On a request dump of a few kilobytes, in a service logging every request, that becomes measurable and people start disabling redaction for performance.

httpclient

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/httpclient"

An outbound HTTP client that carries the trace ID onward and logs each call in a structured, redacted form.

c := httpclient.New(httpclient.WithTimeout(10 * time.Second))

resp, err := c.Do(req)

Defaults: a 1-minute timeout, the standard transport, and the traceid default header.

Trace propagation, including when there is nothing to propagate

Do reads the trace ID from the context and sets it on the outbound request. When the context has none, it generates a UUIDv7 and attaches it to both the context and the request headers.

httpretrier

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/httpretrier"

Adds retries to an HTTP client you already have.

r, err := httpretrier.New(client, httpretrier.WithAttempts(3))

resp, err := r.Do(req)

It wraps, rather than replaces

Retries are applied per request, around an existing HTTPClient, so a client that is already instrumented, authenticated, or both keeps everything it had.

The alternative shape, a retrying client that you construct instead of yours, forces a choice between retries and whatever the other client was doing. Here httpclient provides tracing, logging and redaction, and this wraps it.

httpreverseproxy

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/httpreverseproxy"

Forwards an inbound request to a configured upstream, on top of net/http/httputil.ReverseProxy.

c, err := httpreverseproxy.New(upstreamURL)

router.Handle("GET", "/api/*path", c.ForwardRequest)

Redirects are forwarded, never followed

The default upstream client does not follow redirects. A 3xx is passed back to the client verbatim.

This closes an SSRF vector. A proxy that follows redirects will fetch whatever the upstream points it at, and the upstream can point it at 169.254.169.254, at an internal service, or at a host the proxy can reach and the original client cannot. The proxy’s network position is the privilege being borrowed.

retrier

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/retrier"

Runs a function until it succeeds, gives up, or the context is cancelled, waiting a growing jittered delay between attempts.

r, err := retrier.New(retrier.WithAttempts(5))

err = r.Run(ctx, func(ctx context.Context) error {
 return doSomething(ctx)
})

The loop

Run the task with a per-attempt timeout context.
Evaluate the result with the retry predicate.
Stop when attempts are exhausted or the predicate says no.
Otherwise wait the delay plus jitter.
Multiply the delay by the factor and go again.

Parent context cancellation is honoured throughout, including while waiting between attempts. A cancelled request does not sit out a five-second backoff before noticing.

backoff

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/backoff"

Computes the delay before the next retry attempt. Schedule.Next returns a duration and advances the progression.

It performs no timing, no scheduling, no goroutines and no I/O. You own the loop and the timer; this answers how long to wait.

s := backoff.New(backoff.Config{...})

for {
 if err := do(); err == nil {
 break
 }
 time.Sleep(s.Next())
}

Three jitter strategies

Without jitter, a fleet of clients that all failed at the same instant retries at the same instant, and again at the same instant, hammering a recovering service in synchronised waves.

periodic

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/periodic"

Runs a function repeatedly on a schedule, in its own goroutine, with a deadline on each call.

p, err := periodic.New(
 30*time.Second, // interval
 5*time.Second, // jitter ceiling
 10*time.Second, // per-call timeout
 myTask,
)

p.Start(ctx)
defer p.Stop()

What it adds to time.Ticker

A time.Ticker and a for loop is four lines. The four properties below are what the four lines leave out, and each one is a production incident in its own right.

dnscache

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/dnscache"

Caches host resolution and dials through it. Cache.DialContext drops straight into an http.Transport:

c := dnscache.New(nil, 1024, 30*time.Second)

transport := &http.Transport{DialContext: c.DialContext}

Why Go programs need this

Go’s resolver does not cache. Every LookupHost goes to the configured DNS servers, and in a container that usually means a cluster DNS service a network hop away, sometimes with a search-domain list that turns one lookup into four or five queries.

passwordhash

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/passwordhash"

Hashes and verifies passwords with Argon2id, following RFC 9106 and the OWASP Password Storage Cheat Sheet.

p := passwordhash.New() // RFC 9106 §4 defaults

hash, err := p.PasswordHash(plaintext)
ok, err := p.PasswordVerify(plaintext, hash)
upgrade, err := p.PasswordNeedsRehash(hash)

Argon2id, and what the defaults cost

Argon2id is memory-hard by design: it forces an attacker to commit RAM per guess. That removes the advantage of the GPU and ASIC hardware that bcrypt and PBKDF2 no longer hold back well.

passwordpwned

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/passwordpwned"

Checks whether a password appears in a known breach, through the Have I Been Pwned Pwned Passwords API v3.

c, err := passwordpwned.New()

pwned, err := c.IsPwnedPassword(ctx, password)
if pwned {
 return errors.New("password has been compromised in a data breach, please choose another")
}

What actually leaves the process

This is the question anyone sensible asks before sending passwords to a third party, and the answer is: five hexadecimal characters.

jwt

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/jwt"

Method	Purpose
`LoginHandler`	validates credentials, issues a token
`RenewHandler`	renews a valid token near expiry
`IsAuthorized`	validates a bearer token for a protected handler
`Middleware`	wraps a handler, injects verified claims into the context
`Authenticate`	validates a bearer token, returns claims, for custom middleware
`IssueToken`	mints a token outside the HTTP login flow
`VerifyToken`	validates a raw token from any transport

IssueToken and VerifyToken are the ones for non-HTTP paths: a WebSocket message, a queue payload, gRPC metadata.

encrypt

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/encrypt"

AES-GCM encryption for payloads moving between systems: a database column, a queue message, a cache entry, a cookie.

Raw byte APIs, plus helpers that serialise a Go value first with gob (ByteEncryptAny) or JSON (*SerializeAny).

Authenticated, which is the part that matters

AES-GCM provides confidentiality and authenticity. Tampering with a ciphertext makes decryption fail rather than producing plausible-looking garbage.

sqlconn

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/sqlconn"

Opens a database/sql pool, applies limits, verifies it works, exposes a health check, and closes it on shutdown.

c, err := sqlconn.Connect(ctx, "mysql://user:pass@tcp(host:3306)/db")
defer c.Shutdown()

New takes driver and DSN separately; Connect takes a <DRIVER>://<DSN> string, with WithDefaultDriver for a bare DSN.

The context bounds connection, not the pool

This is the distinction the package documents most carefully, and the one that causes the most confusion.

sqltransaction

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/sqltransaction"

Runs your function inside a transaction. Return nil and it commits; return an error and it rolls back.

err := sqltransaction.Exec(ctx, db, func(ctx context.Context, tx *sql.Tx) error {
 if _, err := tx.ExecContext(ctx, q1); err != nil {
 return err
 }

 _, err := tx.ExecContext(ctx, q2)

 return err
})

The control flow it removes

Written by hand, a transaction is this:

sqlxtransaction

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/sqlxtransaction"

The sqltransaction pattern against jmoiron/sqlx, so the callback receives a *sqlx.Tx.

err := sqlxtransaction.Exec(ctx, db, func(ctx context.Context, tx *sqlx.Tx) error {
 return tx.SelectContext(ctx, &users, query, arg)
})

Why a separate package

sqlx.Tx embeds sql.Tx but is a distinct type, and its extra methods are the reason to be using sqlx at all. A callback typed func(context.Context, *sql.Tx) error cannot call SelectContext, GetContext, NamedExecContext or StructScan, which is most of what sqlx is for.

sqlutil

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/sqlutil"

Quotes identifiers and literals when a query has to be assembled rather than parameterised, and builds IN and NOT IN clauses from typed slices.

s := sqlutil.New()

s.QuoteID("myschema.users.name") // `myschema`.`users`.`name`
s.BuildInClauseInt64("id", []int64{1,2,3}) // id IN (1,2,3)

Placeholders cannot quote an identifier

A prepared statement binds values. It cannot bind a table name, a column name, or an ORDER BY direction, because those are parsed before the plan exists.

mysqllock

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/mysqllock"

A named lock shared across processes, built on MySQL’s GET_LOCK and RELEASE_LOCK.

locker := mysqllock.New(db)

release, err := locker.Acquire(ctx, "daily-reconciliation", 10*time.Second)
if err != nil {
 if errors.Is(err, mysqllock.ErrTimeout) {
 return // another instance holds it
 }
 return err
}
defer release()

When a database you already have is the right lock

Running three replicas means a scheduled job runs three times. A cron-style task, a reconciliation, a report, a cleanup sweep: each needs exactly one instance to do the work.

redis

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/redis"

Key/value operations, typed payloads and Pub/Sub over go-redis.

c, err := redis.New(ctx, &redis.SrvOptions{Addr: "localhost:6379"})
defer c.Close()

err = c.SetData(ctx, "key", value, time.Hour)
err = c.GetData(ctx, "key", &value)

Typed payloads

SetData and GetData serialise and deserialise around the raw string operations, so a struct goes in and comes back out without the call site handling encoding.

DefaultMessageEncodeFunc and DefaultMessageDecodeFunc are replaceable, which matters when the data has to be readable by something that is not this service. A shared cache populated by a Go service and read by a Python one needs an encoding both understand, and that choice belongs at construction rather than at each call.

valkey

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/valkey"

Key/value storage, typed payloads and Pub/Sub over valkey-go, the client for Valkey.

c, err := valkey.New(ctx, &valkey.SrvOptions{InitAddress: []string{"localhost:6379"}})
defer c.Close()

Why a separate package from redis

Valkey is the Linux Foundation fork of Redis, created after Redis moved off its BSD licence in 2024. It remains protocol-compatible, so most operations behave identically.

The clients are not the same library, though. valkey-go is a different implementation with a different option type and a different command-building model, built around client-side caching and pipelining. Wrapping both behind one type would mean either exposing the lowest common denominator or leaking whichever client was underneath.

kafka

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/kafka"

Producer and consumer for Apache Kafka, built on segmentio/kafka-go.

p, err := kafka.NewProducer(urls, topic)
err = p.SendData(ctx, key, payload)

c, err := kafka.NewConsumer(urls, topic, groupID)
msg, err := c.Receive(ctx)

Pure Go, no CGO

No librdkafka to install, no CGO, so CGO_ENABLED=0 still builds.

The practical consequences are all about deployment. A statically linked binary runs in a scratch or distroless container with nothing else in it. Cross-compiling for another platform is GOOS=linux GOARCH=arm64 go build rather than a toolchain and a C library for the target. And go test needs no system package installed on the machine or in CI.

sqs

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/sqs"

Send, receive, decode and delete against an SQS queue, on aws-sdk-go-v2.

c, err := sqs.New(ctx, queueURL, "")

err = c.SendData(ctx, payload)
msg, err := c.Receive(ctx)
err = c.Delete(ctx, msg.ReceiptHandle)

FIFO constraints are checked at construction

New takes a queue URL and a message-group ID, and validates the combination before any AWS configuration is loaded:

The queue URL must be a valid absolute URL.
A FIFO queue, whose URL ends in .fifo, requires a message-group ID.
A standard queue requires the group ID to be empty; a non-empty value is rejected with ErrUnexpectedMessageGroupID.

Validating first means a misconfiguration fails immediately with a specific error, rather than surfacing later as an AWS API rejection whose message does not name the actual problem.

s3

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/s3"

Object operations against one bucket.

c, err := s3.New(ctx, "my-bucket")

err = c.Put(ctx, "path/to/key", reader)
obj, err := c.Get(ctx, "path/to/key")
keys, err := c.ListKeys(ctx, "prefix/")
err = c.Delete(ctx, "path/to/key")

Bucket-scoped, and streaming

The Client is bound to a bucket at construction, so the bucket name is not repeated at every call site and cannot be got wrong on one of them. A service using two buckets constructs two clients, which also keeps their configurations independently visible.

awsopt

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/awsopt"

Accumulates aws-sdk-go-v2 load options into a reusable slice, then materialises them into an aws.Config.

var opts awsopt.Options

opts.WithRegion("eu-west-1")

cfg, err := opts.LoadDefaultConfig(ctx)

The zero value is ready to use.

One configuration, several clients

A service using S3, SQS and Secrets Manager constructs three SDK clients. Each needs region, credentials, endpoint resolution and retry behaviour, and the SDK’s own pattern is to pass load options at each construction site.

awssecretcache

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/awssecretcache"

Wraps an aws-sdk-go-v2 Secrets Manager client in an sfcache, so repeated lookups of the same secret hit memory rather than the API.

cache, err := awssecretcache.New(
 ctx,
 128, // maximum cached secrets
 5*time.Minute, // TTL per entry
)

Three reasons the cache is not optional

Secrets Manager GetSecretValue is metered, rate limited, and on the network.

sfcache

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/sfcache"

Caches the result of an expensive lookup, collapses concurrent requests for the same key into one call, and can keep serving the last good value while the upstream is down.

cache := sfcache.New(func(ctx context.Context, key string) (*Customer, error) {
 return fetchCustomer(ctx, key)
}, sfcache.Config{Size: 256, TTL: 5 * time.Minute})

customer, err := cache.Lookup(ctx, "customer:123")

The value type is inferred from the lookup function, so Lookup returns *Customer with no type assertion.

enumcache

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/enumcache"

A two-way map between small integer IDs and names, held in memory and safe for concurrent reads.

ec := enumcache.New()
ec.SetAllNameByID(enumcache.NameByID{1: "ACTIVE", 2: "SUSPENDED"})

id, err := ec.ID("ACTIVE") // 1
name, err := ec.Name(2) // "SUSPENDED"

What it replaces

Reference data is the least interesting part of a service and one of the most repeated. A status table with twenty rows, a country table, a channel table: the database owns the values, the code needs them in both directions, and the lookup happens on every request.

enumdb

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/enumdb"

Reads reference tables into memory at startup, producing populated enumcache instances.

db, err := enumdb.New(ctx, sqlDB, queries)

One call, at startup, after which every lookup is a map read.

The table shape it expects

Rows scannable into (id int, name string). In practice a numeric primary key called id and a unique string column called name:

CREATE TABLE IF NOT EXISTS `example` (
 `id` SMALLINT UNSIGNED NOT NULL,
 `name` VARCHAR(50) NOT NULL,
 `disabled` TINYINT NOT NULL DEFAULT 0,
 PRIMARY KEY (`id`),
 UNIQUE INDEX `id_UNIQUE` (`id` ASC),
 UNIQUE INDEX `name_UNIQUE` (`name` ASC))
ENGINE = InnoDB;

Both uniqueness constraints matter, because the cache is bidirectional. A duplicate name makes the name-to-ID direction ambiguous, and the database is the only place that can enforce it.

enumbitmap

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/enumbitmap"

Two functions. StringsToBitMap packs a set of names into one integer; BitMapToStrings unpacks it.

00000001 = 1 = FIRST
00000010 = 2 = SECOND
00000100 = 4 = THIRD
00001000 = 8 = FOURTH

00001001 = 9 = FIRST + FOURTH

When one integer beats a join table

A set of flags on a record has two standard storage shapes. A separate table with a row per flag per record, which is correct and normalised and costs a join on every read. Or a single integer column, which is denormalised and costs nothing.

countrycode

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/countrycode"

ISO-3166 country records, compiled in, queryable by code or by geography.

d, err := countrycode.New(nil)
c, err := d.CountryByAlpha2Code("IT")

What a record holds

Each CountryData carries all three ISO-3166 code forms (alpha-2, alpha-3, numeric), English and French names, the full UN M49 geographic hierarchy (region, sub-region, intermediate region, each with both name and code), an assignment status, and the country-code top-level domain.

countryphone

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/countryphone"

Give it a number or a prefix, get back the country and the numbering-plan metadata that prefix belongs to. It follows the ITU-T E.123 and E.164 recommendations.

d := countryphone.New(nil) // embedded dataset
info, err := d.NumberInfo("442071234567")

Longest-prefix, because prefixes overlap

A hash map keyed on the calling code does not work for this, and the reason is that E.164 prefixes are not a flat namespace.

phonekeypad

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/phonekeypad"

Turns 1-800-FLOWERS into 18003569377, following the ITU E.161 keypad layout.

+-----+-----+-----+
| 1 | 2 | 3 |
| | ABC | DEF |
+-----+-----+-----+
| 4 | 5 | 6 |
| GHI | JKL | MNO |
+-----+-----+-----+
| 7 | 8 | 9 |
| PQRS| TUV | WXYZ|
+-----+-----+-----+
| | 0 | |
+-----+-----+-----+

Why this is a package and not four lines

The mapping is trivial. The edge cases are where inline implementations diverge from each other.

encode

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/encode"

Turns a Go value into a string safe to put in a database column, a queue message, or a cache key, and turns it back.

Two families do that here. Encode/Decode use encoding/gob wrapped in Base64. Serialize/Deserialize use encoding/json wrapped in Base64. There are also the bare Base64EncodeString, Base64DecodeString, and streaming Base64Encoder/Base64Decoder.

Measure before assuming gob is faster

Gob has a reputation as the fast binary option and JSON as the slow interoperable one. On this package’s own benchmarks, over the same value, that is backwards:

decint

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/decint"

Stores a decimal with up to six fractional digits as an int64 scaled by 1e6, and converts to and from float64 and string.

The problem it refuses to have

0.1 + 0.2 != 0.3 in binary floating point, and every language with IEEE 754 doubles inherits it. For a rendering coordinate nobody cares. For money, a quantity that must reconcile, or anything that gets compared for equality after a round trip through a database and a JSON payload, the accumulated error is a defect.

timeutil

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/timeutil"

Two types that serialise to human-readable strings where the standard library does not: DateTime[T] for timestamps in a layout chosen at compile time, and Duration for "1h30m" instead of a nanosecond integer.

The two mismatches

time.Duration marshals to JSON as a bare nanosecond integer. A thirty-minute timeout leaves your service as 1800000000000, which no human reads correctly and no other language parses back into a duration without knowing the unit. timeutil.Duration marshals as "30m0s", the same string time.Duration.String() produces and time.ParseDuration accepts.

uhex

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/uhex"

Encodes unsigned integers and fixed-size byte arrays as zero-padded lowercase hexadecimal, at widths known at compile time.

id := uhex.Hex64(traceID) // 16 bytes
sum := uhex.Hex32(checksum) // 8 bytes

var dst [16]byte
uhex.Hex64UB(traceID, &dst) // no allocation

The naming pattern

Four suffixes, orthogonal along two axes:

Suffix	Input	Output
none	unsigned integer	returns `[]byte`
`UB`	unsigned integer	writes into a caller buffer
`B`	fixed-size byte array	returns `[]byte`
`BB`	fixed-size byte array	writes into a caller buffer

Integer helpers always zero-pad to the full width of the type: Hex64 gives 16 characters, Hex32 8, Hex16 4, Hex8 2. Byte-array helpers encode each input byte in order, two characters per byte.

stringkey

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/stringkey"

Takes several text fields and produces one uint64 that is the same every time for inputs that differ only in ways you do not care about.

sk := stringkey.New(" John Doe ", "LONDON")
sk.Key() // uint64
sk.Hex() // fixed 16-character hex
sk.String() // base-36, shorter and variable length

The pipeline is the product

The hash is the boring part. What makes this a package rather than a call to a hash function is the six-step normalisation in front of it, applied identically every time:

strsplit

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/strsplit"

ChunkLine splits one line into pieces of at most size bytes. Chunk splits a block of text, treating newlines as the first-choice boundary and handing long lines to ChunkLine. Both take an optional chunk limit.

The use case is anything with a hard payload ceiling: an SMS segment, a log field, a message body, a column width, an embedding window.

stringmetric

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/stringmetric"

One function. DLDistance returns the Damerau-Levenshtein edit distance between two strings: the fewest insertions, deletions, substitutions and adjacent transpositions needed to turn one into the other.

Why Damerau and not plain Levenshtein

Transposition is the fourth operation. Plain Levenshtein scores teh against the as distance 2, reading it as a deletion plus an insertion. Damerau-Levenshtein scores it 1, because swapping two adjacent characters counts as one edit.

random

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/random"

Random bytes, unsigned integers, UUIDv7, 64- and 128-bit UIDs, hexadecimal and base-36 IDs, and configurable random strings.

r := random.New(nil) // crypto/rand.Reader

id := r.UUIDv7()
s, err := r.RandString(16)

The fallback, stated plainly

This is the part of the package that deserves the most attention, and the doc comment does not soften it.

Some helpers have error-free signatures: RandUint32, RandUint64, UUIDv7, and the RandHex64, RandString64, UID64 and UID128 built on them. They cannot return an error, so when the reader fails they fall back to math/rand/v2.

maputil

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/maputil"

Four functions over Go maps: Filter, Map, Reduce, Invert. None of them mutate the input.

The gap this fills

Go’s standard maps package covers copying and comparison (Clone, Copy, DeleteFunc, Equal, EqualFunc) and, since the iterator work landed, traversal (All, Keys, Values, Insert, Collect). It stops short of the transforms. There is no maps.Filter, no maps.Map, no maps.Reduce, and no inverse.

sliceutil

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/sliceutil"

Filter, map and reduce over slices, plus Stats, which summarises a numeric slice with seventeen descriptive statistics in one call.

Stats

Stats takes a numeric slice and returns seventeen descriptive statistics:

data := []int{53, 83, 13, 79, 13, 37, 83, 29, 37, 13, 83, 83}

ds, err := sliceutil.Stats(data)

// ds.Count, ds.Sum, ds.Min, ds.MinID, ds.Max, ds.MaxID, ds.Range,
// ds.Mean, ds.Median, ds.Mode, ds.ModeFreq, ds.MeanDev, ds.Variance,
// ds.StdDev, ds.Skewness, ds.ExKurtosis, ds.Entropy

Most of that list is routine. Four entries are less common in a Go statistics helper:

numtrie

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/numtrie"

A prefix tree indexed by digits, holding a value of any type, answering longest-prefix queries.

root := numtrie.New[Route]()
root.Add("1", &defaultUSRoute)
root.Add("1212", &newYorkRoute)
root.Add("44", &ukRoute)
root.Add("44207", &londonRoute)

val, status := root.Get("+1-212-555-0100")
// val == &newYorkRoute, the longest matching prefix "1212"

Longest-prefix, which a map cannot do

A map[string]Route answers exact-match questions. Numbering plans are not exact-match problems.

paging

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/paging"

Computes pagination metadata from a current page, a page size and a total item count: total pages, previous and next page, and the OFFSET/LIMIT pair for a SQL query.

Three numbers in, a filled-in struct out:

p := paging.New(3, 5, 17) // page 3, 5 per page, 17 items total

// p.TotalPages == 4
// p.PreviousPage == 2
// p.NextPage == 4
// p.Offset == 10
// p.HasPreviousPage == true
// p.HasNextPage == true

The arithmetic is three lines. The edge cases are where the implementations differ.

filter

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/filter"

Filters a slice against structured rules supplied by the caller, or parsed from JSON or a query parameter.

Rules are [][]Rule, with the outer slice AND and the inner slice OR:

[[A], [B, C], [D]] evaluates as A AND (B OR C) AND D

Built for untrusted rules

A filter expression that arrives from a client is code someone else wrote, running in your process. The package treats it that way, and the bounds are the substance of the design.

threadsafe

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/threadsafe"

Two interfaces and no implementation. Locker is Lock/Unlock; RLocker is RLock/RUnlock. That is the entire package.

Why an interface and not a mutex

A concurrent container normally embeds its lock:

type Cache struct {
 mu sync.RWMutex
 m map[string]entry
}

The lock type is then fixed for every caller. None of them can supply an existing lock that already guards a wider critical section, substitute an instrumented lock that records contention, or drop to a plain sync.Mutex where the read/write split costs more than it saves.

tsmap

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/threadsafe/tsmap"

Concurrent access to a shared map: read, write, delete and transform, each taking a caller-supplied lock so the access is serialised.

Every function takes the lock as its first argument:

var (
 mu sync.RWMutex
 m = map[string]int{"a": 1, "b": 2}
)

tsmap.Set(&mu, m, "c", 3)
v, ok := tsmap.GetOK(&mu, m, "a")

Writes (Set, Delete, Do) want a threadsafe.Locker; reads and pure transforms (Get, GetOK, Len, Snapshot, Filter, Map, Reduce, Invert, RDo) want an RLocker and take the read lock.

tsslice

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/threadsafe/tsslice"

Concurrent access to a shared slice: read, write, append, delete and transform, each taking a lock so the access is serialised.

This package exposes two APIs where its sibling tsmap exposes one.

Two APIs, one of them safer

The function API mirrors tsmap: pass a threadsafe.Locker or RLocker at each call.

var (
 mu sync.RWMutex
 s = []int{1, 2, 3}
)

tsslice.Append(&mu, &s, 4)
v, ok := tsslice.GetOK(&mu, &s, 0)

Guarded[E] bundles the slice with its own sync.RWMutex instead:

errutil

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/errutil"

Three functions, each answering a question the standard errors package leaves open: where did this error come from, how do I report a cleanup failure without losing the real one, and what is actually inside this joined error.

Trace, and what caller capture costs

Trace wraps an error with the file, line and function of its call site, using %w so errors.Is and errors.As still see through it.

typeutil

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/typeutil"

Nil detection through an interface, zero values for a type parameter, safe pointer dereference, and branch-free bool-to-integer conversion, plus a set of numeric type constraints.

Four of the five helpers are conveniences. IsNil exists because of a Go language trap.

The typed nil

The trap:

var p *MyStruct // nil pointer
var i any = p // non-nil interface holding a nil pointer

i == nil // false
typeutil.IsNil(i) // true

An interface value carries two words, a type and a pointer. Assigning a nil *MyStruct to an any fills in the type word, so the interface is no longer nil even though what it points at is. The comparison i == nil asks about the interface, not about the pointer inside it.

validator

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/validator"

Struct-tag validation on go-playground/validator, with the error handling and message rendering that library leaves to the caller.

v, err := validator.New()

err = v.ValidateStruct(req)

Errors come back joined and typed

Upstream returns vt.ValidationErrors, a slice you type-assert and loop over, formatting each entry yourself. Every service that uses it writes that loop, and they all format differently.

slack

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/slack"

Posts text to a Slack Incoming Webhook.

c, err := slack.New(webhookURL, "my-bot", ":rocket:", "", "#alerts")
err = c.Send(ctx, "deploy finished", "", "", "", "")

The webhook URL is a credential, and it appears in error messages

This is the part that separates the package from an inline http.Post.

A Slack Incoming Webhook URL contains the secret. Anyone holding https://hooks.slack.com/services/T00.../B00.../XXXX can post to that channel; there is no separate token.

jirasrv

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/jirasrv"

A client foundation for the Jira Server REST API, with typed models for the common payloads: issues, transitions, comments, users, visibility, properties and metadata.

c, err := jirasrv.New(addr, token)

err = c.SendRequest(ctx, method, path, body, &result)

A foundation, not a wrapper for every endpoint

The Jira REST API is large, and versions differ between deployments. Rather than modelling every endpoint, the package handles the plumbing and exposes SendRequest as a generic typed entry point.

devlake

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/devlake"

A client for the Apache DevLake Webhook API, covering the deployment and incident events that feed DORA metrics.

c, err := devlake.New(addr, apiKey)

err = c.SendDeployment(ctx, &devlake.DeploymentRequest{...})
err = c.SendIncident(ctx, &devlake.IncidentRequest{...})
err = c.SendIncidentClose(ctx, &devlake.IncidentRequestClose{...})

What DevLake wants and why the events are split

DevLake computes the four DORA metrics: deployment frequency, lead time for changes, change failure rate, and time to restore service. Two of the four are durations, which is why incidents are reported twice.

sleuth

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/sleuth"

Write-side client for the Sleuth.io API, covering four registration workflows.

c, err := sleuth.New(addr, org, apiKey)

err = c.SendDeployRegistration(ctx, &sleuth.DeployRegistrationRequest{...})
err = c.SendManualChange(ctx, &sleuth.ManualChangeRequest{...})
err = c.SendCustomIncidentImpactRegistration(ctx, &sleuth.CustomIncidentImpactRegistrationRequest{...})
err = c.SendCustomMetricImpactRegistration(ctx, &sleuth.CustomMetricImpactRegistrationRequest{...})

Four workflows, and what separates them

Deploy registration reports a code deployment: the ordinary case, where a pipeline ships a build.

Manual change reports something that changed production without going through a deployment. A feature flag flipped, a configuration value edited, a database migration run by hand. These cause incidents at a rate comparable to deployments and are invisible to a tool that only watches your pipeline, which makes change failure rate look better than it is.

ipify

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/ipify"

Asks ipify.org what address the outside world sees this process as having.

c, err := ipify.New()
ip, err := c.GetPublicIP(ctx)

Defaults: endpoint https://api.ipify.org, timeout 4 seconds.

Why a process cannot answer this itself

A service behind NAT, in a container, on a cloud instance, or behind a load balancer has local interface addresses that bear no relation to the address its outbound traffic appears to come from. Reading net.Interfaces() gives you 10.0.x.x or 172.17.x.x, which is not the answer to “what should I tell a partner to allowlist”.

testutil

Tue, 08 Sep 2026 00:00:00 +0000

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/testutil"

Test-only helpers: readers and closers that always fail, capture of stdout, stderr and the default logger, a pre-routed HTTP handler, and substitution of time-variant values in expected output.

Failing I/O on demand

reader := testutil.NewErrorReader("read failed")
closer := testutil.NewErrorCloser("close failed")

ErrorReader.Read always returns the error. ErrorCloser.Close always returns the error, on an io.ReadCloser whose read side works normally.

Stop Rewriting Go Service Boilerplate: Ship Production Go APIs Faster with nurago

Sun, 29 Mar 2026 00:00:00 +0000

Every backend team says the same thing when starting a new service:

“This one will be lean.”

Then the infrastructure checklist arrives.

Configuration loading. Structured logging. Metrics. Retries. Health checks. Graceful shutdown. Validation. Cache layers. Cloud clients. Test utilities.

None of it is core business logic. All of it is essential in production.

After watching that pattern repeat across teams and projects, I consolidated the building blocks I kept rewriting into one open-source project: nurago.

Exponential Backoff with Jitter in Go, Without the Overflow Footgun

Sat, 18 Jul 2026 00:00:00 +0000

Exponential backoff is the usual first response when a downstream call starts failing: wait a bit, then wait longer, then longer still. It looks trivial. It hides two real bugs.

The first is the thundering herd. Without jitter, a fleet of clients that all failed at the same instant will all retry at the same instant, hammering the recovering service in synchronised waves.

The second is that the delay arithmetic can overflow. Signed integer arithmetic in Go wraps around, so a time.Duration that grows past math.MaxInt64 nanoseconds does not saturate. It comes back negative. Delays only get that large after many consecutive failures, so the wrap fires in the middle of your worst outage.

Between Two Attempts: What an HTTP Retry Loop Must Decide

Sat, 18 Jul 2026 00:00:00 +0000

A retry loop looks like the simplest code you will write all week: try, and if it failed, wait and try again. The hard questions live in the gap between one attempt and the next. Was that outcome worth retrying at all? What has to be released before another attempt is safe? Can the request even be sent a second time? How long is the wait, and who has the final say on it?

Observing Outbound HTTP in Go Without Disturbing It

Sat, 18 Jul 2026 00:00:00 +0000

Instrumentation has an observer problem. The moment you wrap an HTTP client to log requests, propagate trace IDs, and dump payloads for debugging, you have added code that can mutate the caller’s request, leak timers, buffer streams that were meant to flow, and write secrets to disk. The wrapper meant to explain production behaviour becomes part of it.

The httpclient package in nurago wraps net/http with trace ID propagation and structured request/response logging, and most of its design is about exactly this tension. Each section below is one place where observing a request could disturb it, and what the code does there instead.

Before the First Request and After the Last: a Go HTTP Server's Edges

Sat, 18 Jul 2026 00:00:00 +0000

Serving HTTP is the easy middle of a server’s life. net/http handles it well, and it is rarely where the trouble starts. The places where a server can embarrass itself are the edges: the startup that half-works until the first request finds the misconfiguration, and the shutdown that drops in-flight requests, leaks a goroutine, or hangs the deploy. The httpserver package in nurago is a bootstrap around net/http (routing, middleware, operational endpoints, TLS, graceful shutdown), and its most interesting engineering lives at those edges, so that is where this post stays.

A Reverse Proxy Is Defined by What It Refuses to Do

Sat, 18 Jul 2026 00:00:00 +0000

Every Go reverse proxy runs on net/http/httputil.ReverseProxy, and it is a good engine. What distinguishes one proxy deployment from another is almost entirely policy: what gets forwarded, what gets rewritten, what gets timed out, what gets logged.

In a proxy the characteristic failure mode is helpfulness. Following a redirect is helpful, and it is also a request-forgery vector. A whole-request timeout looks like a safety net until it truncates a long download. Logging everything drowns the one entry that mattered.

A DNS-Caching Dialer for http.Transport in Go

Sat, 18 Jul 2026 00:00:00 +0000

Go’s standard http.Transport resolves the destination host on every new connection and does not cache the result. For a client that talks to the same handful of hosts thousands of times a minute, that is a steady drip of Domain Name System (DNS) queries, each adding latency to connection setup and load on the resolver. The dnscache package in nurago sits in that gap: a bounded, concurrency-safe DNS cache with a DialContext you can drop straight into a transport.

From singleflight to a Production Cache: a Gap Analysis

Sat, 18 Jul 2026 00:00:00 +0000

Some lookups are too expensive to run on every request: a Domain Name System (DNS) resolution, a secret from a vault, slow remote metadata. Caching them is the natural move, and it brings a well-known hazard: when a hot value expires, a crowd of goroutines can rush the upstream at once, the cache stampede. In Go, the usual remedy is golang.org/x/sync/singleflight, which lets one goroutine do the work while the other forty-nine wait for its result.

A Distributed Lock in Go and MySQL, and Every Way the Session Can Betray You

Sat, 18 Jul 2026 00:00:00 +0000

Some work must happen at most once across an entire fleet: a nightly reconciliation, an idempotent migration, a cache rebuild. When several instances of a service could each try to run it, you need a lock that spans processes, and an in-memory mutex does not.

If MySQL is already in the stack, its built-in named locks are the tempting answer. GET_LOCK('key', timeout) grants a server-wide lock, RELEASE_LOCK('key') frees it, and you have avoided standing up a separate coordination service. The mysqllock package in nurago is under six hundred lines built on that primitive.

The Life of a Password: Argon2id in Production with nurago

Sat, 18 Jul 2026 00:00:00 +0000

Password storage is one of the more consequential things a service does, and it has a long record of being botched. General-purpose hashes like MD5 and SHA-1 are the classic mistake: fast, and trivially parallelised on a GPU, which is precisely backwards.

What the job calls for is a hash that is deliberately slow and memory-hard, needing a large tunable amount of RAM per guess. That is what neutralises the massively parallel GPU and Application-Specific Integrated Circuit (ASIC) rigs used to crack leaked password databases. Bcrypt is slow but uses a fixed, tiny amount of memory, so those rigs still scale against it. Password-Based Key Derivation Function 2 (PBKDF2), the usual choice when Federal Information Processing Standards (FIPS) compliance is required, iterates a cheap hash and is not memory-hard at all. Scrypt is memory-hard, but ties memory and CPU cost to a single knob. Argon2, the Password Hashing Competition (PHC) winner standardised as RFC 9106, lets you dial time, memory, and parallelism independently, and its id variant adds resistance to side-channel attacks. Hence its place at the top of the Open Worldwide Application Security Project (OWASP) Password Storage Cheat Sheet.

Checking Passwords Against Have I Been Pwned Without Leaking Them

Sat, 18 Jul 2026 00:00:00 +0000

Rejecting passwords that have appeared in known data breaches is a high-value check for a registration flow, and the best-known source is Troy Hunt’s Have I Been Pwned (HIBP) Pwned Passwords database. The obvious objection: sending a user’s password, or even its full hash, to a third-party service to ask “have you seen this?” would itself be a security incident.

The passwordpwned package in nurago implements the check in a way that answers that objection. Following the exchange as a network observer would is the quickest way to see how: what leaves the machine, what comes back, and what happens when the answer cannot be trusted.

The Classic JWT Attacks, Addressed by Construction in Go

Sat, 18 Jul 2026 00:00:00 +0000

JSON Web Tokens (JWTs) have a reputation for being dangerous, and the reputation is earned. The danger is almost never in the cryptography; it is in the flexibility of the format. A token header announces how it was signed, and a naive verifier believes the announcement. Many published JWT exploits are variations on that single act of misplaced trust.

The jwt package in nurago takes a stricter stance. Each of the classic attacks is closed by how the package is built, rather than by a runtime check someone could forget to call or misconfigure away. Here is the list, one attack at a time.

Redacting Secrets from Go Logs on a Performance Budget

Sat, 18 Jul 2026 00:00:00 +0000

Services leak secrets into their own logs all the time. Someone dumps an inbound HTTP request to debug a flaky integration and the Authorization header goes straight to disk. A JSON body with a password field lands in an error log. A connection string with the database password ends up in a stack trace. Nobody did anything reckless. They logged what they needed to see when something broke, and the credentials came along for the ride.

Filtering Untrusted Client Queries in Go: Threat Model First

Sat, 18 Jul 2026 00:00:00 +0000

A filter= query parameter is a common way to let clients narrow down a list endpoint. The client asks for “users named Doe, at most 42 years old, in England or France”, and the server turns that into a predicate over an in-memory slice. It looks like a small convenience. It is also a little expression language exposed to the open internet, which makes the hostile client the right place to start designing from. The filter package in nurago is built that way, so the threat model comes first here and the machinery second.

A Production slog.Handler on Top of zerolog

Sat, 18 Jul 2026 00:00:00 +0000

Go’s log/slog gave the ecosystem a standard structured-logging interface to code against: your libraries speak slog and stay portable. Teams that care about logging overhead often reach for zerolog, whose reputation is allocation-free structured output.

The logsrv package in nurago takes both. It implements a native slog.Handler that writes each record’s attributes directly onto zerolog events. The work is all in the disagreements between the two APIs: what a level is, where attributes may nest, who owns rendering decisions, and who reports errors. Every heading below names one of those mismatches and answers it in three parts: what the slog contract requires, how a naive bridge gets it wrong, and what this handler does instead.

A Longest-Prefix Trie for Numeric Keys, in Six Design Questions

Sat, 18 Jul 2026 00:00:00 +0000

Some lookups are not “does this key exist” but “what is the most specific rule that applies to this key”. Telephone routing is the canonical example: a dialled number matches the longest stored prefix, so +1 212 555 0100 should resolve to a New York rule (1212) if one exists, and fall back to a broader North American rule (1) if it does not. A hash map answers only exact-key questions, so longest-prefix matching would need a separate probe for every shrinking prefix; a linear scan over a sorted list degrades as the table grows. The numtrie package in nurago is a small generic trie built for exactly this question:

Packing an Entire Country Record into a Single uint64

Sat, 18 Jul 2026 00:00:00 +0000

Country metadata is one of those unglamorous needs that turns up in most backends. Translate US to USA to 840. Find which region a country belongs to. Validate a country top-level domain (TLD). The usual answer is a pile of maps, one per lookup direction, each holding strings, and it works well enough that nobody looks twice at it.

The countrycode package in nurago does something else. Internally, an entire International Organization for Standardization (ISO) 3166 country record is encoded into a single 64-bit integer, and every lookup is a handful of shifts away from that one number.

Random IDs in Go, Trap by Trap: UUIDv7 and Unbiased Random Strings

Sat, 18 Jul 2026 00:00:00 +0000

Generating random identifiers looks trivial and hides several traps. Reach for math/rand out of habit and your “secure” token is predictable. Map random bytes onto an alphabet with a naive % len and you skew the distribution. Accept whatever a custom entropy reader hands you and you can end up with truncated randomness, or a call that never returns.

The random package in nurago centralises these patterns behind one small API. New(nil) draws from crypto/rand.Reader, the right default for anything security-sensitive, and a custom io.Reader can be supplied for testing or specialised entropy sources:

Deriving a Fast Fixed-Width Hex Encoder in Go

Sat, 18 Jul 2026 00:00:00 +0000

Hexadecimal encoding is a solved problem. The standard library has encoding/hex, and if you just want a string there is always fmt.Sprintf("%x", v). So why does nurago ship a dedicated uhex package?

Because the places where hex encoding runs hottest, trace IDs, hashes, log fields, protocol framing, share a property the general tools cannot exploit: the width is fixed and known at compile time. Derive uhex from the standard library by removing one cost at a time, and you can see exactly what that constraint buys.

nurago

Packages

Documentation

Where to start

Search

Articles

Overview

Reliability and Networking

Security

Logging and Observability

Data Structures and Encoding

Longer form, elsewhere

Features

Table of contents

Service Lifecycle

HTTP Server

Outbound HTTP

Resilience

Observability

Secret Redaction

Security

SQL

Messaging and Storage

Enumerations and Reference Data

Data Handling

Collections and Generics

Errors, Types and Validation

Service Clients

Testing

Project Properties

About

Where the library came from

Comparison

Table of contents

The Four Options

Against the Standard Library Alone

Sponsor

Legal

Trademarks

Getting Started

Requirements

Install

Service Scaffolding

Generate a Project

Dependency Footprint

How It Works

Observability

Logging

Resilience

The Delay Schedule

Security

Password Storage

Data and Messaging

SQL Connections

Testing

Test Helpers

Migration from gogen

Development

Clone and Validate

AI Coding Assistants

Machine-Readable Indexes

bootstrap

The sequence

config

The load order

httpserver

Misconfiguration is an error from New, not a panic

httputil

Reading a request

jsendx

What the envelope adds to JSend

healthcheck

One method, and the clients already have it

profiling

The problem with importing net/http/pprof

logutil

Two slog encoding faults it repairs

logsrv

Native handler, not an adapter

metrics