nurago

https://github.com/tecnickcom/nurago
Admin
70 independent Go packages for backend services (formerly gogen): HTTP client and server, retries,...
Tokens:77,744
Snippets:668
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- The module path is github.com/tecnickcom/nurago. The former github.com/tecnickcom/gogen path is deprecated and must not be used in new imports.
- Import individual packages under pkg/, not the module root. Each package pulls only the dependencies it reaches, and 40 of the 70 reach no external module at all.
- Packages that take configuration use variadic functional options: a New constructor with an opts ...Option parameter and WithXxx option functions.
- The module is at v1 and every exported symbol under pkg/ is stable within v1. A high patch number reflects frequent additive releases, not API churn.
- Guides and per-package pages are published at https://nurago.org, with a machine-readable index at https://nurago.org/llms.txt.

================
CODE SNIPPETS
================
### Install Nurago via go get

Source: https://github.com/tecnickcom/nurago/blob/main/README.md

Use the standard Go toolchain to fetch the library.

```bash
go get github.com/tecnickcom/nurago
```

--------------------------------

### Initialize and use jirasrv Client

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/jirasrv/README.md

This example demonstrates creating a new Jira client, configuring a request with query parameters, and executing it using SendRequest. It includes a mock server setup to illustrate how the client handles authentication and base path application.

```go
// A stand-in for a Jira Server instance. Real code passes the Jira base
// address and a personal access token.
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	fmt.Println(r.Method, r.URL.Path, r.URL.RawQuery)
	fmt.Println("auth:", r.Header.Get("Authorization"))

	w.Header().Set("Content-Type", "application/json")

	_, _ = w.Write([]byte(`{"key":"PROJ-42","fields":{"summary":"login fails"}}`))
}))

defer srv.Close()

client, err := jirasrv.New(srv.URL, "personal-access-token")
if err != nil {
	fmt.Println(err)

	return
}

query := url.Values{}
query.Set("fields", "summary")

// SendRequest covers any Jira REST endpoint, so the package does not
// have to model the whole API surface.
resp, err := client.SendRequest(
	context.TODO(),
	http.MethodGet,
	"/issue/PROJ-42",
	&query,
	nil,
)
if err != nil {
	fmt.Println(err)

	return
}

// The base path (/rest/api/2) is applied by the client, so endpoints are
// given relative to it. The caller owns the response body.
defer func() { _ = resp.Body.Close() }()

body, _ := io.ReadAll(resp.Body)

var issue struct {
	Key    string `json:"key"`
	Fields struct {
		Summary string `json:"summary"`
	} `json:"fields"`
}

err = json.Unmarshal(body, &issue)

fmt.Println(issue.Key, issue.Fields.Summary, err)

// Output:
// GET /rest/api/2/issue/PROJ-42 fields=summary
// auth: Bearer personal-access-token
// PROJ-42 login fails <nil>
```

--------------------------------

### Initialize and Start an HTTP Server

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/httpserver/README.md

Demonstrates how to create a new server instance with custom options, start it in the background, and perform a graceful shutdown.

```go
ctx := context.Background()

srv, err := httpserver.New(
	ctx,
	&exampleBinder{},
	httpserver.WithServerAddr(":0"), // ephemeral port; see srv.Addr() for the actual address
	httpserver.WithEnableDefaultRoutes(httpserver.PingRoute, httpserver.StatusRoute),
	httpserver.WithRequestTimeout(30*time.Second),
	httpserver.WithShutdownTimeout(5*time.Second),
	httpserver.WithLogger(slog.New(slog.DiscardHandler)),
)
if err != nil {
	fmt.Println(err)
	return
}

// The server runs in the background; canceling ctx or calling Shutdown
// stops it gracefully.
srv.StartServer()

// ... serve traffic ...

err = srv.Shutdown(ctx)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Println("server stopped")

// Output:
// server stopped
```

--------------------------------

### Full Paging Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/paging/README.md

A complete example demonstrating the calculation of paging parameters and printing the result.

```go
var (
	currentPage uint = 3
	pageSize    uint = 5
	totalItems  uint = 17
)

// calculate new paging parameters
p := paging.New(currentPage, pageSize, totalItems)

fmt.Println(p)

// Output:
// {3 5 17 4 2 4 10 true true}
```

--------------------------------

### Bootstrap Lifecycle Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/bootstrap/README.md

A complete example showing how to use Bootstrap to manage application components and handle graceful shutdown, including the expected output.

```go
// A real service lets Bootstrap block on SIGINT or SIGTERM. The example
// cancels the context from inside the bind function so it terminates.
ctx, cancel := context.WithCancel(context.TODO())
defer cancel()

var wg sync.WaitGroup

shutdown := make(chan struct{})

// BindFunc is where the application registers its own components: HTTP
// servers, database connections, background workers. It receives the
// application context, logger, and metrics client already wired.
bindFn := func(ctx context.Context, _ *slog.Logger, mtr metrics.Client) error {
	worker(ctx, &wg, shutdown)

	mtr.IncErrorCounter("startup", "bind", "0")

	fmt.Println("application wired")

	// Stand-in for the signal that would normally end the process.
	cancel()

	return nil
}

// Bootstrap returns once every registered dependant has finished, or
// with an error wrapping ErrShutdownTimeout if they exceed the budget.
err := bootstrap.Bootstrap(
	bindFn,
	bootstrap.WithContext(ctx),
	bootstrap.WithShutdownSignalChan(shutdown),
	bootstrap.WithShutdownWaitGroup(&wg),
	bootstrap.WithShutdownTimeout(5*time.Second),
	bootstrap.WithCreateMetricsClientFunc(func() (metrics.Client, error) {
		return &metrics.Default{}, nil
	}),
)

fmt.Println("bootstrap returned:", err)

// Output:
// application wired
// worker stopped
// bootstrap returned: <nil>
```

--------------------------------

### Slack Client Integration Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/slack/README.md

A complete example showing how to mock a Slack webhook endpoint, initialize the client, and send a message with default metadata.

```go
// A stand-in for a Slack Incoming Webhook endpoint. Real code passes the
// https://hooks.slack.com/services/... address issued by Slack.
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)
	fmt.Println(string(body))

	_, _ = w.Write([]byte("ok"))
}))

defer srv.Close()

// The constructor takes the defaults applied to every message: sender
// name, icon emoji, icon URL, and channel.
client, err := slack.New(srv.URL, "deploybot", ":rocket:", "", "#releases")
if err != nil {
	fmt.Println(err)

	return
}

// Empty metadata arguments fall back to the client defaults.
err = client.Send(context.TODO(), "release v1.2.3 is live", "", "", "", "")

fmt.Println("err:", err)

// Output:
// {"text":"release v1.2.3 is live","username":"deploybot","icon_emoji":":rocket:","channel":"#releases"}
// err: <nil>
```

--------------------------------

### Configure and execute a retriable HTTP request

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/httpretrier/README.md

This example demonstrates setting up a retrier with a custom policy and executing a GET request against a test server that fails twice before succeeding.

```go
// A server that fails twice before succeeding.
attempts := 0
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
	attempts++

	if attempts < 3 {
		w.WriteHeader(http.StatusServiceUnavailable)

		return
	}

	w.WriteHeader(http.StatusOK)
}))

defer srv.Close()

retrier, err := httpretrier.New(
	srv.Client(),
	httpretrier.WithAttempts(4),
	httpretrier.WithDelay(time.Millisecond),
	httpretrier.WithJitter(time.Microsecond), // kept tiny so the example runs quickly
	httpretrier.WithRetryIfFn(httpretrier.RetryIfForReadRequests),
)
if err != nil {
	fmt.Println(err)

	return
}

req, err := http.NewRequestWithContext(context.TODO(), http.MethodGet, srv.URL, nil)
if err != nil {
	fmt.Println(err)

	return
}

resp, err := retrier.Do(req)
if err != nil {
	fmt.Println(err)

	return
}

defer func() { _ = resp.Body.Close() }()

fmt.Println(resp.StatusCode, "after", attempts, "attempts")

// Output:
// 200 after 3 attempts
```

--------------------------------

### Construct and Start a Periodic Scheduler

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/periodic/README.md

Demonstrates how to initialize a Periodic scheduler using periodic.New and manage its lifecycle with Start and Stop.

```go
p, err := periodic.New(
	30*time.Second,  // run every 30 s
	5*time.Second,   // add up to 5 s of random jitter
	10*time.Second,  // each call gets a 10 s deadline
	myTask,
)
if err != nil {
	log.Fatal(err)
}

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

--------------------------------

### Example of configuring awsopt.Options

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/awsopt/README.md

Shows the full workflow of creating an Options instance, adding a region and custom credentials, and loading the configuration.

```go
// The zero value is ready to use.
var opts awsopt.Options

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

// Any config.LoadOptionsFunc from the SDK can be appended, so nothing in
// the SDK is out of reach. Static credentials keep the example offline;
// real code relies on the default credential chain.
opts.WithAWSOption(config.WithCredentialsProvider(
	credentials.NewStaticCredentialsProvider("AKID", "SECRET", ""),
))

awsCfg, err := opts.LoadDefaultConfig(context.TODO())
if err != nil {
	fmt.Println(err)

	return
}

// awsCfg is passed directly to any aws-sdk-go-v2 service constructor,
// for example s3.NewFromConfig or secretsmanager.NewFromConfig.
fmt.Println(awsCfg.Region)

// Output:
// eu-west-1
```

--------------------------------

### IsNil Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/typeutil/README.md

Example showing the use of IsNil to detect a nil channel.

```go
var nilChan chan int

v := typeutil.IsNil(nilChan)
fmt.Println(v)

// Output:
// true
```

--------------------------------

### Example usage of IsPwnedPassword

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/passwordpwned/README.md

A complete example demonstrating client initialization with a custom URL and checking multiple passwords.

```go
srv := rangeServer()
defer srv.Close()

// Real code omits WithURL and uses the default HIBP endpoint.
client, err := passwordpwned.New(passwordpwned.WithURL(srv.URL))
if err != nil {
	fmt.Println(err)

	return
}

pwned, err := client.IsPwnedPassword(context.TODO(), "password")
fmt.Println("password:", pwned, err)

pwned, err = client.IsPwnedPassword(context.TODO(), "correct horse battery staple")
fmt.Println("passphrase:", pwned, err)

// Output:
// password: true <nil>
// passphrase: false <nil>
```

--------------------------------

### Example usage with sqlmock

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/sqlxtransaction/README.md

A self-contained example demonstrating transaction execution and commit verification using sqlmock.

```go
// A real program would use a *sqlx.DB from sqlx.Connect. The mock keeps
// the example self-contained and its output deterministic.
mockDB, mock, err := sqlmock.New()
if err != nil {
	fmt.Println(err)

	return
}

db := sqlx.NewDb(mockDB, "sqlmock")

defer func() { _ = db.Close() }()

mock.ExpectBegin()
mock.ExpectExec("INSERT INTO audit").WillReturnResult(sqlmock.NewResult(1, 1))
mock.ExpectCommit()

// The transaction is committed when run returns nil, and rolled back
// when it returns an error or panics.
err = sqlxtransaction.Exec(
	context.TODO(),
	db,
	func(ctx context.Context, tx *sqlx.Tx) error {
		_, err := tx.ExecContext(ctx, "INSERT INTO audit (event) VALUES ('login')")
		if err != nil {
			return fmt.Errorf("writing audit row: %w", err)
		}

		return nil
	},
)

fmt.Println("committed:", err)

// Output:
// committed: <nil>
```

--------------------------------

### Clone and Initialize Project

Source: https://github.com/tecnickcom/nurago/blob/main/examples/service/README.md

Commands to clone the repository, enter the directory, and install dependencies for local development.

```bash
git clone https://github.com/nuragoexampleowner/nuragoexample.git
cd nuragoexample
DEVMODE=LOCAL make x
```

--------------------------------

### Password Hashing and Verification Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/passwordhash/README.md

Demonstrates how to initialize the passwordhash provider with custom options, hash a password, and verify both correct and incorrect passwords.

```go
opts := []passwordhash.Option{
	passwordhash.WithKeyLen(32),
	passwordhash.WithSaltLen(16),
	passwordhash.WithTime(3),
	passwordhash.WithMemory(16_384),
	passwordhash.WithThreads(1),
	passwordhash.WithMinPasswordLength(16),
	passwordhash.WithMaxPasswordLength(128),
}

p := passwordhash.New(opts...)

secret := "Example-Password-01"

hash, err := p.PasswordHash(secret)
if err != nil {
	log.Fatal(err)
}

ok, err := p.PasswordVerify(secret, hash)
if err != nil {
	log.Fatal(err)
}

fmt.Println(ok)

ok, err = p.PasswordVerify("Example-Wrong-Password-01", hash)
if err != nil {
	log.Fatal(err)
}

fmt.Println(ok)

// Output:
// true
// false
```

--------------------------------

### Initialize logutil Config and Logger

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/logutil/README.md

Demonstrates creating a configuration with string-based options and initializing a slog logger. The example shows how to set the format, level, and common attributes before retrieving the logger instance.

```go
// Configuration usually comes from environment variables or a config
// file, so the string-based options accept the raw values directly.
cfg, err := logutil.NewConfig(
	logutil.WithFormatStr("json"),
	logutil.WithLevelStr("warning"),
	logutil.WithCommonAttr(slog.String("service", "payments"),
)
if err != nil {
	fmt.Println(err)

	return
}

// SlogLogger returns a *slog.Logger writing in the configured format.
// SlogDefaultLogger additionally installs it as the slog default.
logger := cfg.SlogLogger()

fmt.Println(logutil.LevelName(cfg.Level), logger != nil)

// Output:
// warning true
```

--------------------------------

### Example of Chunk usage

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/strsplit/README.md

A complete example showing how to split a string into chunks of a specific size with a limit on the number of chunks returned.

```go
str := "helloworld\nbellaciao"
d := strsplit.Chunk(str, 5, 3)

fmt.Println(d)

// Output:
// [hello world bella]
```

--------------------------------

### Example usage of PProfHandler

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/profiling/README.md

Demonstrates setting up a router with PProfHandler and making a request to a pprof endpoint.

```go
router := httprouter.New()

// One wildcard route serves every pprof endpoint. The mount prefix is
// arbitrary, as the handler reads the endpoint from the wildcard
// parameter rather than from the request path.
router.HandlerFunc(
	http.MethodGet,
	"/pprof/*"+profiling.WildcardParamName,
	profiling.PProfHandler,
)

srv := httptest.NewServer(router)
defer srv.Close()

// The goroutine profile is a named runtime profile forwarded to
// pprof.Handler, so it needs no explicit registration.
req, err := http.NewRequestWithContext(
	context.TODO(),
	http.MethodGet,
	srv.URL+"/pprof/goroutine?debug=1",
	nil,
)
if err != nil {
	fmt.Println(err)

	return
}

resp, err := srv.Client().Do(req)
if err != nil {
	fmt.Println(err)

	return
}

defer func() { _ = resp.Body.Close() }()

fmt.Println(resp.StatusCode)

// Output:
// 200
```

--------------------------------

### Full Validator Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/validator/README.md

A complete example showing the instantiation of a validator and the validation of a complex nested data structure.

```go
// data structure to check
validObj := RootStruct{
	BoolField: true,
	SubStr: SubStruct{
		URLField: "http://first.test.invalid",
		IntField: 3,
	},
	SubStrPtr: &SubStruct{
		URLField: "http://second.test.invalid",
		IntField: 123,
	},
	StringField: "hello world",
	NoNameField: "test",
}

// instantiate the validator object
v, err := validator.New(
	validator.WithFieldNameTag(fieldTagName),
	validator.WithCustomValidationTags(validator.CustomValidationTags()),
	validator.WithErrorTemplates(validator.ErrorTemplates()),
)
if err != nil {
	log.Fatal(err)
}

// check the data structure
err = v.ValidateStruct(validObj)
if err != nil {
	log.Fatal(err)
}

fmt.Println("OK")

// Output:
// OK
```

--------------------------------

### Install PPROF Tool

Source: https://github.com/tecnickcom/nurago/blob/main/examples/service/README.md

Command to install the pprof tool for analyzing profiling data.

```bash
go install github.com/google/pprof@latest
```

--------------------------------

### Register Deployment with Mock Server

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/sleuth/README.md

An example showing how to use a test server to verify deployment registration requests, including payload validation.

```go
// A stand-in for https://app.sleuth.io. Real code passes the Sleuth
// base address.
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	fmt.Println(r.Method, r.URL.Path)

	w.WriteHeader(http.StatusOK)
}))

defer srv.Close()

client, err := sleuth.New(srv.URL, "example-org", "api-key")
if err != nil {
	fmt.Println(err)

	return
}

// Requests are validated before being sent, so a malformed payload
// fails locally rather than at the API.
err = client.SendDeployRegistration(context.TODO(), &sleuth.DeployRegistrationRequest{
	Deployment:        "payments-production",
	Sha:               "9f8c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b",
	Environment:       "production",
	IgnoreIfDuplicate: true,
	Tags:              []string{"#payments", "#backend"},
})

fmt.Println("err:", err)

// Output:
// POST /deployments/example-org/payments-production/register_deploy
// err: <nil>
```

--------------------------------

### Kafka Producer and Consumer Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/kafka/README.md

Demonstrates initializing a producer and consumer, sending a raw payload, and receiving it using the kafka package.

```go
queue := &exampleQueue{}

producer, err := kafka.NewProducer(
	[]string{"127.0.0.1:9092"},
	"events",
	kafka.WithKafkaWriter(queue),
)
if err != nil {
	fmt.Println(err)

	return
}

defer func() { _ = producer.Close() }()

ctx := context.TODO()

err = producer.Send(ctx, []byte("raw payload"))
if err != nil {
	fmt.Println(err)

	return
}

consumer, err := kafka.NewConsumer(
	[]string{"127.0.0.1:9092"},
	"events",
	"example-group",
	kafka.WithKafkaReader(queue),
)
if err != nil {
	fmt.Println(err)

	return
}

defer func() { _ = consumer.Close() }()

msg, err := consumer.Receive(ctx)

fmt.Println(string(msg), err)

// Output:
// raw payload <nil>
```

--------------------------------

### Initialize and use the OpenTelemetry client

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/metrics/opentel/README.md

This example demonstrates initializing the client with custom provider functions and using it to instrument an HTTP handler and record metrics. The provided meter and tracer functions are configured to discard output, suitable for testing environments.

```go
// The default providers export over OTLP. The example substitutes
// providers that discard their output, so it needs no collector.
// Production code omits both options and configures the exporter through
// the standard OTEL_EXPORTER_OTLP_* environment variables.
meterFn := func(_ context.Context, res *sdkresource.Resource) (*sdkmetric.MeterProvider, error) {
	return sdkmetric.NewMeterProvider(
		sdkmetric.WithResource(res),
		sdkmetric.WithReader(sdkmetric.NewManualReader()),
	), nil
}

tracerFn := func(_ context.Context, res *sdkresource.Resource) (*sdktrace.TracerProvider, error) {
	return sdktrace.NewTracerProvider(sdktrace.WithResource(res)), nil
}

// The returned Client satisfies metrics.Client, so application code
// depends on the contract rather than on OpenTelemetry.
var client metrics.Client

client, err := opentel.New(
	context.TODO(),
	"payments",
	"v1.2.3",
	opentel.WithMeterProviderFn(meterFn),
	opentel.WithTracerProviderFn(tracerFn),
)
if err != nil {
	fmt.Println(err)

	return
}

defer func() { _ = client.Close() }()

// The path label must be a low-cardinality route template, never a raw
// request URI containing identifiers.
handler := client.InstrumentHandler("/users/{id}", func(w http.ResponseWriter, _ *http.Request) {
	w.WriteHeader(http.StatusOK)
})

rec := httptest.NewRecorder()
handler.ServeHTTP(rec, httptest.NewRequestWithContext(
	context.TODO(), http.MethodGet, "/users/42", nil,
))

client.IncErrorCounter("user", "read", "404")

// OpenTelemetry is push-based, so the metrics endpoint exposes no
// scrape payload and answers with a health-style 200.
scrape := httptest.NewRecorder()
client.MetricsHandlerFunc()(scrape, httptest.NewRequestWithContext(
	context.TODO(), http.MethodGet, "/metrics", nil,
))

fmt.Println(rec.Code, scrape.Code)

// Output:
// 200 200
```

--------------------------------

### Periodic Job Execution Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/periodic/README.md

A complete example showing the creation, execution, and stopping of a periodic job, including the expected output.

```go
count := make(chan int, 1)

count <- 0

// example task to execute periodically
task := func(_ context.Context) {
	v := <-count
	count <- (v + 1)
}

interval := 20 * time.Millisecond
jitter := 2 * time.Millisecond
timeout := 2 * time.Millisecond

// create a new periodic job
p, err := periodic.New(interval, jitter, timeout, task)
if err != nil {
	close(count)
	log.Fatal(err)
}

// start the periodic job
p.Start(context.TODO())

// wait for 3 times the interval
wait := 3 * interval
time.Sleep(wait)

// stop the periodic job
p.Stop()

fmt.Println(<-count)

close(count)

// Output:
// 3
```

--------------------------------

### JWT Authentication and Middleware Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/jwt/README.md

Demonstrates setting up password verification, initializing the JWT handler, logging in to receive a token, and protecting an endpoint with middleware.

```go
ph := passwordhash.New()

// Pre-computed password hashes, as they would be stored in a user database.
aliceHash, err := ph.PasswordHash("s3cr3t-pw")
if err != nil {
	fmt.Println(err)

	return
}

users := map[string]string{"alice": aliceHash}

// A decoy hash to verify against for unknown users, so response timing does
// not reveal whether an account exists.
decoyHash, err := ph.PasswordHash("decoy-pw")
if err != nil {
	fmt.Println(err)

	return
}

verify := func(username, password string) (bool, error) {
	hash, ok := users[username]
	if !ok {
		_, _ = ph.PasswordVerify(password, decoyHash)

		return false, nil
	}

	return ph.PasswordVerify(password, hash)
}

auth, err := jwt.New([]byte("0123456789abcdef0123456789abcdef"), verify)
if err != nil {
	fmt.Println(err)

	return
}

ctx := context.Background()

// Log in with valid credentials and capture the issued token.
loginRec := httptest.NewRecorder()
loginReq := httptest.NewRequestWithContext(ctx, http.MethodPost, "/login", strings.NewReader(`{"username":"alice","password":"s3cr3t-pw"}`))
auth.LoginHandler(loginRec, loginReq)

fmt.Println("login status:", loginRec.Code)

token, _ := io.ReadAll(loginRec.Result().Body)

// Protect an endpoint with the middleware: the verified claims are available
// from the request context, identifying the caller.
protected := auth.Middleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	claims, _ := jwt.ClaimsFromContext(r.Context())
	fmt.Fprintln(w, "hello", claims.Subject)
}))

authRec := httptest.NewRecorder()
authReq := httptest.NewRequestWithContext(ctx, http.MethodGet, "/protected", nil)
authReq.Header.Set(httputil.HeaderAuthorization, httputil.HeaderAuthBearer+string(token))
protected.ServeHTTP(authRec, authReq)

fmt.Println("protected status:", authRec.Code)
fmt.Print(authRec.Body.String())

// Output:
// login status: 200
// protected status: 200
// hello alice
```

--------------------------------

### Forwarding requests with httpreverseproxy

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/httpreverseproxy/README.md

This example demonstrates setting up an upstream server, initializing the proxy with a base path, and using httprouter to forward requests.

```go
// Stand-in upstream service that echoes the path it received.
upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	// The example intentionally reflects the request path to show how it is
	// rewritten; a real upstream would not echo untrusted input.
	fmt.Fprintf(w, "upstream received %s", r.URL.Path) //nolint:gosec // G705: illustrative echo
}))
defer upstream.Close()

client, err := httpreverseproxy.New(upstream.URL + "/v2")
if err != nil {
	panic(err)
}

// Register the proxy under a catch-all route; httprouter injects the matched
// parameters into the request context that the default rewrite reads.
router := httprouter.New()
router.HandlerFunc(http.MethodGet, "/proxy/*path", client.ForwardRequest)

edge := httptest.NewServer(router)
defer edge.Close()

req, err := http.NewRequestWithContext(context.Background(), http.MethodGet, edge.URL+"/proxy/users", nil)
if err != nil {
	panic(err)
}

resp, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer func() { _ = resp.Body.Close() }()

body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

// Output: upstream received /v2/users
```

--------------------------------

### Redis Client Example with Injected Client

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/redis/README.md

Demonstrates using a custom client implementation for testing purposes and performing basic CRUD operations.

```go
client, err := redis.New(
	context.TODO(),
	nil,
	redis.WithRedisClient(&exampleRClient{data: make(map[string]string)}),
)
if err != nil {
	fmt.Println(err)

	return
}

defer func() { _ = client.Close() }()

ctx := context.TODO()

err = client.Set(ctx, "greeting", "hello", time.Minute)
if err != nil {
	fmt.Println(err)

	return
}

var value string

err = client.Get(ctx, "greeting", &value)

fmt.Println(value, err)

fmt.Println(client.Del(ctx, "greeting"))

// Output:
// hello <nil>
// <nil>
```

--------------------------------

### Basic S3 Client Usage

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/s3/README.md

Demonstrates initializing an S3 client and performing standard operations like Put, Get, ListKeys, Delete, and HealthCheck.

```go
c, err := s3.New(ctx, "my-bucket")
if err != nil {
    return err
}

if err := c.Put(ctx, "reports/latest.json", reader); err != nil {
    return err
}

obj, err := c.Get(ctx, "reports/latest.json")
if err != nil {
    return err
}
_ = obj

keys, err := c.ListKeys(ctx, "reports/")
if err != nil {
    return err
}
_ = keys

if err := c.Delete(ctx, "reports/old.json"); err != nil {
    return err
}

if err := c.HealthCheck(ctx); err != nil {
    return err
}
```

--------------------------------

### Usage of awsopt.Options

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/awsopt/README.md

Demonstrates how to initialize options, set a region from a URL, and load the default configuration.

```go
var opts awsopt.Options
opts.WithRegionFromURL("https://s3.eu-west-1.amazonaws.com", "")

awsCfg, err := opts.LoadDefaultConfig(ctx)
if err != nil {
    return err
}

// awsCfg is ready for any aws-sdk-go-v2 service client:
// s3.NewFromConfig(awsCfg), secretsmanager.NewFromConfig(awsCfg), …
```

--------------------------------

### Initialize and use Valkey client

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/valkey/README.md

Demonstrates how to initialize a client with server options and channels, then perform typed data operations.

```go
srvOpts := valkey.SrvOptions{InitAddress: []string{"localhost:6379"}}

client, err := valkey.New(
    ctx,
    srvOpts,
    valkey.WithChannels("events", "notifications"),
)
if err != nil {
    return err
}
defer client.Close()

// Store and retrieve a typed value:
type Payload struct{ Message string }

if err := client.SetData(ctx, "my-key", Payload{"hello"}, time.Hour); err != nil {
    return err
}

var p Payload
if err := client.GetData(ctx, "my-key", &p); err != nil {
    return err
}

// Publish and consume a typed message:
if err := client.SendData(ctx, "events", Payload{"fired"}); err != nil {
    return err
}

var event Payload
channel, err := client.ReceiveData(ctx, &event)
```

--------------------------------

### Loading Configuration with Defaults and Overrides

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/config/README.md

Demonstrates setting up a temporary configuration file, applying environment variable overrides, and loading the final configuration into a struct.

```go
// A real service ships config.json alongside the binary, or relies on
// the search path: ./, $HOME/.<cmdName>/, /etc/<cmdName>/.
dir, err := os.MkdirTemp("", "nurago-config-example")
if err != nil {
	fmt.Println(err)

	return
}

defer func() { _ = os.RemoveAll(dir) }()

file := `{"server_address":":9090","max_workers":8}`

err = os.WriteFile(filepath.Join(dir, "config.json"), []byte(file), 0o600)
if err != nil {
	fmt.Println(err)

	return
}

// Environment variables override the file, which overrides the
// defaults. The prefix keeps the service's variables namespaced.
_ = os.Setenv("EXAMPLESRV_MAX_WORKERS", "16")

defer func() { _ = os.Unsetenv("EXAMPLESRV_MAX_WORKERS") }()

cfg := &appConfig{}

err = config.Load("examplesrv", dir, "EXAMPLESRV", cfg)
if err != nil {
	fmt.Println(err)

	return
}

fmt.Println(cfg.ServerAddress, cfg.MaxWorkers, cfg.Log.Level)

// Output:
// :9090 16 info
```

--------------------------------

### Filter Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/sliceutil/README.md

Example showing how to filter a slice of strings based on a predicate function.

```go
s := []string{"Hello", "World", "Extra"}

filterFn := func(_ int, v string) bool { return v == "World" }

s2 := sliceutil.Filter(s, filterFn)

fmt.Println(s2)

// Output:
// [World]
```

--------------------------------

### Deterministic backoff example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/backoff/README.md

A deterministic example showing the progression of delays with jitter disabled.

```go
s := backoff.New(backoff.Config{
	Base:     100 * time.Millisecond,
	Factor:   2,
	Jitter:   0, // disabled so the example output is deterministic
	MaxDelay: 350 * time.Millisecond,
})

for range 4 {
	fmt.Println(s.Next())
}

// Output:
// 100ms
// 200ms
// 350ms
// 350ms
```

--------------------------------

### Initialize and Use Sleuth Client

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/sleuth/README.md

Demonstrates how to initialize the client, perform a health check, and register a deployment.

```go
c, err := sleuth.New("https://app.sleuth.io/api/1", "my-org", apiKey)
if err != nil {
    return err
}

if err := c.HealthCheck(ctx); err != nil {
    return err
}

err = c.SendDeployRegistration(ctx, &sleuth.DeployRegistrationRequest{
    Deployment: "my-service",
    Sha:        "abcdef1234567890abcdef1234567890abcdef12",
})
if err != nil {
    return err
}
```

--------------------------------

### DateTime marshaling example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/timeutil/README.md

A complete example showing the marshaling of a DateTime object to a JSON string.

```go
dt := timeutil.DateTime[timeutil.TRFC3339](time.Date(2023, 1, 2, 15, 4, 5, 0, time.UTC))

b, err := json.Marshal(dt)
if err != nil {
	log.Fatal(err)
}

fmt.Println(string(b))

// Output: "2023-01-02T15:04:05Z"
```

--------------------------------

### Install jv validator

Source: https://github.com/tecnickcom/nurago/blob/main/examples/service/doc/CONFIG.md

Install the jv program to validate configuration files against JSON schemas.

```bash
go install github.com/santhosh-tekuri/jsonschema/cmd/jv@latest
```

--------------------------------

### Translate vanity phone numbers

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/phonekeypad/README.md

Use KeypadNumberString to get a dialable string or KeypadNumber to get a slice of integers.

```go
numStr := phonekeypad.KeypadNumberString("1-800-FLOWERS")
// numStr == "18003569377"

digits := phonekeypad.KeypadNumber("1-800-FLOWERS")
// digits == []int{1, 8, 0, 0, 3, 5, 6, 9, 3, 7, 7}
```

--------------------------------

### Retrier Execution Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/retrier/README.md

A complete example showing a task that succeeds on the third attempt using specific retry options.

```go
var count int

// example function that returns nil only at the third attempt.
task := func(_ context.Context) error {
	if count == 2 {
		return nil
	}

	count++

	return errors.New("ERROR")
}

opts := []retrier.Option{
	retrier.WithRetryIfFn(retrier.DefaultRetryIf),
	retrier.WithAttempts(5),
	retrier.WithDelay(10 * time.Millisecond),
	retrier.WithDelayFactor(1.1),
	retrier.WithJitter(5 * time.Millisecond),
	retrier.WithTimeout(2 * time.Millisecond),
}

r, err := retrier.New(opts...)
if err != nil {
	log.Fatal(err)
}

timeout := 1 * time.Second

ctx, cancel := context.WithTimeout(context.TODO(), timeout)

err = r.Run(ctx, task)

cancel()

if err != nil {
	log.Fatal(err)
}

fmt.Println(count)

// Output:
// 2
```

--------------------------------

### sqlconn.New with Mock Database

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/sqlconn/README.md

Demonstrates initializing a connection with custom pool settings and a mock SQL open function for testing purposes.

```go
// A real program registers a driver (for example go-sql-driver/mysql)
// and lets sqlconn call sql.Open. WithSQLOpenFunc substitutes a mock so
// the example needs no database.
mockDB, mock, err := sqlmock.New()
if err != nil {
	fmt.Println(err)

	return
}

// The connection check runs the validation query, and Shutdown closes
// the pool.
mock.ExpectQuery("SELECT 1").WillReturnRows(sqlmock.NewRows([]string{"1"}).AddRow(1))
mock.ExpectClose()

conn, err := sqlconn.New(
	context.TODO(),
	"mysql",
	"user:pass@tcp(127.0.0.1:3306)/testdb",
	sqlconn.WithConnMaxOpen(25),
	sqlconn.WithConnMaxIdleCount(5),
	sqlconn.WithConnMaxLifetime(5*time.Minute),
	sqlconn.WithPingTimeout(2*time.Second),
	sqlconn.WithSQLOpenFunc(func(_, _ string) (*sql.DB, error) {
		return mockDB, nil
	}),
)
if err != nil {
	fmt.Println(err)

	return
}

defer func() { _ = conn.Shutdown(context.TODO()) }()

// DB returns the pooled *sql.DB for normal query execution.
fmt.Println(conn.DB() != nil)

// Output:
// true
```

--------------------------------

### Self-Contained SQS Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/sqs/README.md

A complete example using an injected SQS client to send, receive, and delete a message, including the expected output.

```go
// A caller would normally configure a real client via options such as
// WithAWSOptions or WithEndpointMutable (and the region would be derived from
// the queue URL); here an injected client keeps the example self-contained, so
// no AWS configuration is loaded.
c, err := sqs.New(
	context.TODO(),
	"https://sqs.us-east-1.amazonaws.com/123456789012/my-queue",
	"", // standard (non-FIFO) queue: no message group ID
	sqs.WithSQSClient(&exampleSQSClient{}),
)
if err != nil {
	fmt.Println("error:", err)

	return
}

err = c.Send(context.TODO(), "hello world")
if err != nil {
	fmt.Println("error:", err)

	return
}

msg, err := c.Receive(context.TODO())
if err != nil {
	fmt.Println("error:", err)

	return
}

fmt.Println(msg.Body)

// After processing, acknowledge the message by deleting it.
err = c.Delete(context.TODO(), msg.ReceiptHandle)
if err != nil {
	fmt.Println("error:", err)

	return
}

// Output:
// hello world
```

--------------------------------

### Initialize and Query enumdb

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/enumdb/README.md

Demonstrates initializing enumdb with a database connection and queries, followed by performing ID and name lookups.

```go
// A real program would use a *sql.DB from sql.Open. The mock keeps the
// example self-contained and its output deterministic.
db, mock, err := sqlmock.New()
if err != nil {
	fmt.Println(err)

	return
}

defer func() { _ = db.Close() }()

mock.ExpectQuery("SELECT id, name FROM status").WillReturnRows(
	sqlmock.NewRows([]string{"id", "name"}).
		AddRow(1, "pending").
		AddRow(2, "active").
		AddRow(3, "archived"),
)

// One query per enumeration table, each returning (id int, name string).
queries := enumdb.EnumTableQuery{
	"status": "SELECT id, name FROM status WHERE disabled = 0 ORDER BY id",
}

enum, err := enumdb.New(context.TODO(), db, queries)
if err != nil {
	fmt.Println(err)

	return
}

// The result is keyed by table name and each value is a thread-safe
// bidirectional cache, ready for lookups without further database access.
name, err := enum["status"].Name(2)
fmt.Println(name, err)

id, err := enum["status"].ID("archived")
fmt.Println(id, err)

fmt.Println(enum["status"].SortNames())

// Output:
// active <nil>
// 3 <nil>
// [active archived pending]
```

--------------------------------

### MySQL Example Table Schema

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/enumdb/README.md

An example of a MySQL database table structure compatible with the enumdb package, featuring id and name columns.

```sql
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
COMMENT = 'Example enumeration table';
```

--------------------------------

### Initialize and use sfcache

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/sfcache/README.md

Demonstrates creating a new cache instance with a lookup function and performing a lookup operation.

```go
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")
```

--------------------------------

### Initialize and use enumcache

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/enumcache/README.md

Demonstrates creating a new cache, adding an entry, and performing bidirectional lookups for IDs and names.

```go
// create a new cache
ec := enumcache.New()

// add an entry
ec.Set(1, "alpha")

// get the numerical ID associated to a string
id, err := ec.ID("alpha")
if err != nil {
	log.Fatal(err)
}

fmt.Println(id)

// get the string name associated to a numerical ID
name, err := ec.Name(1)
if err != nil {
	log.Fatal(err)
}

fmt.Println(name)

// Output:
// 1
// alpha
```

--------------------------------

### S3 Client Example with Injected Client

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/s3/README.md

A self-contained example using an injected S3 client to perform operations without loading real AWS configuration.

```go
// A caller would normally configure a real client via options such as
// WithAWSOptions or WithEndpointMutable; here an injected client keeps the
// example self-contained, so no AWS configuration is loaded.
c, err := s3.New(
	context.TODO(),
	"my-bucket",
	s3.WithS3Client(&exampleS3Client{objects: map[string][]byte{}}),
)
if err != nil {
	fmt.Println("error:", err)

	return
}

err = c.Put(context.TODO(), "reports/latest.json", strings.NewReader(`{"ok":true}`))
if err != nil {
	fmt.Println("error:", err)

	return
}

obj, err := c.Get(context.TODO(), "reports/latest.json")
if err != nil {
	fmt.Println("error:", err)

	return
}

data, err := io.ReadAll(obj.Body())
if err != nil {
	fmt.Println("error:", err)

	return
}

err = obj.Close()
if err != nil {
	fmt.Println("error:", err)

	return
}

fmt.Println(obj.ContentType())
fmt.Println(obj.ContentLength())
fmt.Println(string(data))

keys, err := c.ListKeys(context.TODO(), "reports/")
if err != nil {
	fmt.Println("error:", err)

	return
}

fmt.Println(keys)

err = c.Delete(context.TODO(), "reports/latest.json")
if err != nil {
	fmt.Println("error:", err)

	return
}

// Output:
// application/json
// 11
// {"ok":true}
// [reports/latest.json]
```

--------------------------------

### QuoteID Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/sqlutil/README.md

Shows how to use QuoteID to wrap an identifier in backticks.

```go
q, err := sqlutil.New()
if err != nil {
	log.Fatal(err)
}

o := q.QuoteID("7919")

fmt.Println(o)

// Output:
// `7919`
```

--------------------------------

### Initialize and Use SQS Client

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/sqs/README.md

Demonstrates how to initialize an SQS client with specific wait time and visibility timeout, send a typed payload, and receive/delete messages.

```go
c, err := sqs.New(ctx,
    "https://sqs.us-east-1.amazonaws.com/123456789012/my-queue",
    "", // non-FIFO queue
    sqs.WithWaitTimeSeconds(20),
    sqs.WithVisibilityTimeout(300),
)
if err != nil {
    return err
}

// Send typed payload
if err := c.SendData(ctx, event); err != nil {
    return err
}

// Receive typed payload
var msg Event
receiptHandle, err := c.ReceiveData(ctx, &msg)
if err != nil {
    return err
}
if receiptHandle != "" {
    _ = c.Delete(ctx, receiptHandle)
}
```

--------------------------------

### Basic Usage of SQLUtil

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/sqlutil/README.md

Demonstrates initializing a new SQLUtil instance and using QuoteID and QuoteValue to construct a query string.

```go
u, err := sqlutil.New()
if err != nil {
    return err
}

col := u.QuoteID("users.email")      // `users`.`email`
val := u.QuoteValue("o'reilly")      // 'o''reilly'
query := "SELECT " + col + " FROM " + u.QuoteID("users") + " WHERE " + col + " = " + val
_ = query
```

--------------------------------

### JSON Storage Format Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/passwordhash/README.md

The internal structure of the hashed password before base64 encoding.

```json
{
  "P": {
    "A": "argon2id",  // algorithm name (always "argon2id")
    "V": 19,          // Argon2id version (0x13)
    "K": 32,          // derived key length in bytes
    "S": 16,          // salt length in bytes
    "T": 3,           // time cost (passes over memory)
    "M": 65536,       // memory cost in KiB
    "P": 4            // parallelism (threads)
  },
  "S": "wQYm4bfktbHq2omIwFu+4Q==",                       // base64 random salt
  "K": "aU8hO900Odq6aKtWiWz3RW9ygn734liJaPtM6ynvkYI="   // base64 Argon2id hash
}
```

--------------------------------

### Initialize and Run Retrier

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/retrier/README.md

Demonstrates creating a new Retrier instance with custom options and executing a task function.

```go
r, err := retrier.New(
    retrier.WithAttempts(5),
    retrier.WithDelay(200*time.Millisecond),
    retrier.WithDelayFactor(2),
    retrier.WithJitter(25*time.Millisecond),
)
if err != nil {
    return err
}

err = r.Run(ctx, func(ctx context.Context) error {
    return callExternalService(ctx)
})
if err != nil {
    return err
}
```

--------------------------------

### Hex64 Encoding Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/uhex/README.md

Encodes a 64-bit unsigned integer to a hexadecimal string and prints the result.

```go
h := uhex.Hex64(uint64(0x0123456789abcdef))

fmt.Println(string(h))

// Output:
// 0123456789abcdef
```

--------------------------------

### PHC String Format Example

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/passwordhash/README.md

An alternative storage format compatible with external Argon2 implementations.

```text
$argon2id$v=19$m=65536,t=3,p=4$<base64 salt>$<base64 key>
```

--------------------------------

### Initialize and Use Slack Webhook Client

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/slack/README.md

Demonstrates how to create a new Slack client with default settings, perform a health check, and send a message.

```go
c, err := slack.New(
    webhookURL,
    "my-bot",
    ":rocket:",
    "",
    "#deployments",
)
if err != nil {
    return err
}

if err := c.HealthCheck(ctx); err != nil {
    return err
}

err = c.Send(ctx,
    "deployment succeeded",
    "", // use default username
    "", // use default icon emoji
    "", // use default icon URL
    "", // use default channel
)
if err != nil {
    return err
}
```

--------------------------------

### Generate Random Bytes

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/random/README.md

Example of generating a slice of random bytes using the random package.

```go
r := random.New(nil)

b, err := r.RandomBytes(4)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("%v\n", b)
```

--------------------------------

### Usage of testutil helpers

Source: https://github.com/tecnickcom/nurago/blob/main/pkg/testutil/README.md

Demonstrates initializing error mocks, capturing output, setting up a router, and normalizing timestamps.

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

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

	h := testutil.RouterWithHandler(http.MethodGet, "/health", func(w http.ResponseWriter, _ *http.Request) {
	    w.WriteHeader(http.StatusOK)
	})
	_ = h

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

--------------------------------

### Clone repository for new service

Source: https://github.com/tecnickcom/nurago/blob/main/README.md

Clones the repository to start scaffolding a new web service.

```bash
$ git clone https://github.com/tecnickcom/nurago.git

Cloning into 'nurago'...
```

--------------------------------

### Log into Docker container

Source: https://github.com/tecnickcom/nurago/blob/main/examples/service/README.md

Starts an interactive session inside the newly created Docker container.

```bash
docker run -t -i nuragoexampleowner/nuragoexampledev /bin/bash
```

--------------------------------

### Change directory to project

Source: https://github.com/tecnickcom/nurago/blob/main/README.md

Navigates into the newly cloned project directory.

```bash
$ cd nurago/
```
Tokens:
Raw