adapterutil

Documentation

Overview

Package adapterutil centralizes shared plumbing helpers used by GoCell adapters (postgres / redis / rabbitmq / vault). It depends only on stdlib so it can be imported from any adapter package without introducing cross-adapter coupling.

Index

• Constants
• func CloseWithDeadline(ctx context.Context, name string, closeFn func() error) error
• func DownJitter(d time.Duration) time.Duration
• func ExponentialBackoffWithJitter(base, max time.Duration, attempt int) time.Duration
• func HealthToProbe(name healthz.ProbeName, healthFn func(context.Context) error, ...) healthz.Probe

Constants

const DefaultProbeTimeout = 5 * time.Second

DefaultProbeTimeout bounds a /readyz probe so a slow dependency does not hold the readyz response indefinitely. 5s matches Kubernetes /readyz conventions and the prior PGResource probe timeout (now centralized).

Functions

func CloseWithDeadline

func CloseWithDeadline(ctx context.Context, name string, closeFn func() error) error

CloseWithDeadline runs closeFn in a goroutine and returns whichever completes first: closeFn's result or ctx.Err() when the context's deadline/cancellation fires. The name is used for structured logging.

closeFn is always invoked, even when ctx is already done at entry — admitted close must best-effort run. A pre-canceled ctx still returns ctx.Err() promptly via the select once both branches are ready (Go selects uniformly, so the ctx.Done branch may win, but closeFn has already been launched). This replaces the duplicated "goroutine + select + slog" pattern previously copied across postgres/redis/rabbitmq/vault adapters.

closeFn returning a non-nil error is surfaced verbatim with no additional logging when the receiver is still waiting. If the deadline has already fired and closeFn returns an error after the fact, that error is logged at Warn under "adapter close error after budget exceeded" so operators can correlate late failures with the timeout. On successful completion the helper also logs at Info under "adapter closed" so operators can correlate adapter shutdowns with the surrounding lifecycle events.

Callers that own background goroutines (reconnect loops, watchdogs) must signal those goroutines (e.g. close a stop channel) BEFORE invoking CloseWithDeadline so those goroutines exit before or concurrently with the underlying network close.

ref: uber-go/fx app.go StopTimeout — shared shutdown budget pattern. ref: uber-go/fx lifecycle OnStop(ctx) — ContextCloser semantics. ref: ThreeDotsLabs/watermill-amqp pkg/amqp/publisher.go Close — closeCh signal then conn.Close() under the caller's budget.

func DownJitter

func DownJitter(d time.Duration) time.Duration

DownJitter applies 0-25% downward jitter to d (used for stale-claim reclaim spreading). The result is in [0.75*d, d].

ref: adapters/rabbitmq/connection.go addDownJitter.

func ExponentialBackoffWithJitter

func ExponentialBackoffWithJitter(base, max time.Duration, attempt int) time.Duration

ExponentialBackoffWithJitter returns the reconnect delay for attempt N using outbox.ExponentialDelay(base, max, attempt) with ±25% jitter. When the exponential value reaches/exceeds max, jitter is applied then capped so the result never exceeds max.

When the exponential value is below max, ±25% jitter is applied and the result is capped at max if the positive jitter would overshoot.

ref: adapters/rabbitmq/connection.go backoffDelay. ref: eclipse/autopaho auto.go ReconnectBackoff.

func HealthToProbe

func HealthToProbe(
	name healthz.ProbeName,
	healthFn func(context.Context) error,
	timeout time.Duration,
) healthz.Probe

HealthToProbe wraps a Health(ctx) error function as a single typed healthz.Probe. The probe applies an inner context.WithTimeout(timeout) so a slow dependency does not hold /readyz indefinitely. When timeout <= 0 the helper substitutes DefaultProbeTimeout.

This centralizes the "Health → Probe + inner deadline" boilerplate that would otherwise be duplicated across every adapter implementing lifecycle.ManagedResource. It is the dual to CloseWithDeadline for the readiness-probe side of the contract.

For adapters requiring multiple named probes (e.g. postgres.Pool exposes postgres_ready + postgres_indexes_valid_ready), build the []Probe slice directly in the adapter; this helper is intentionally scoped to the common single-probe case. A multi-entry variant was considered but deferred until a third multi-probe caller emerges (YAGNI).

The name argument is a healthz.ProbeName-typed const declared at the caller's adapter (e.g. redis.ProbeReady); a bare string literal here fails archtest PROBENAME-SEALED-FUNNEL-01. The probe is constructed via healthz.NewProbe so the typed-name discipline persists into the registry.

ref: kubernetes/kubernetes pkg/util/healthz — named health checkers with per-probe deadlines. ref: uber-go/fx app.go StopTimeout — same shared-deadline pattern, dual side.