natsclient

package
v0.1.0-alpha.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 22 Imported by: 0

README

natsclient

A NATS client for SemEngine. It wraps nats.go, keeps nats.go's automatic reconnection, and adds helpers for JetStream streams, consumers and key-value buckets.

Overview

The natsclient package wraps the NATS Go client (nats.go) and keeps nats.go's automatic reconnection with natsclient's settings: unlimited attempts (WithMaxReconnects) and a ReconnectWait of 2 s (WithReconnectWait). How soon each attempt comes is not promised. While nats.go reconnects, Publish, RequestClassified and Subscribe return ErrNotConnected at once, and key-value calls wait for their context (probe P15).

Every call that waits for the server takes a context, and the context ends that wait (P13). It does not end a call held behind a write the server is not reading. Such a call waits up to nats.go's write timeout for each write ahead of it (one minute by default; WithWriteTimeout sets it), or until Close closes the socket (P13, P14, P17). Connect returns within its context, and so does Close on a connection the client dialled (TestConnectEndsWithItsContext, TestCloseEndsAHeldWrite).

ADR-112 records what natsclient promises over nats.go, and the test or probe behind each promise. A probe is a program with its source, command, versions and output; ADR-112's Status names where each one is recorded.

This package is the foundation for all NATS communication in SemEngine, providing both core pub/sub functionality and advanced features like JetStream streams, consumers, and Key-Value stores. The client handles connection lifecycle management automatically, allowing applications to focus on business logic rather than connection state management.

Installation

import "github.com/c360studio/semengine/natsclient"

Core Concepts

Connection Lifecycle

Connection states transition through: Disconnected → Connecting → Connected → Reconnecting (on failure) → Connected. The client handles all transitions automatically. With a finite WithMaxReconnects, nats.go closes the connection once its attempts run out; the client keeps it installed and reports Disconnected, and Connect refuses with errs.ErrAlreadyStarted. A Client connects once; recovery is a new Client (measured at 0 by TestIntegration_ReconnectionIsRedial; above 0 not promised).

KVStore Abstraction

A high-level abstraction over NATS KV providing automatic CAS (Compare-And-Swap) retry logic, JSON helpers, and consistent error handling for configuration management scenarios.

Handler contexts and handler panics

The context passed to ConsumeStreamWithConfig and ConsumeInternalStreamWithConfig bounds the consumer's setup only. Each handler's context descends from a context the client owns for that consumer, which it cancels when Close begins; Close still waits for every handler to return. ConsumeStreamWithConfigContexts takes a second context, handlerCtx, when the caller wants to choose the handlers' parent itself.

Subscribe and SubscribeForRequests follow the same rule: the context bounds setup only, and each handler's context descends from a context the client owns for that subscription, not from the context given to the call. Ending the call's context after it returned does not end a handler. The client cancels that context after Close has begun, including when the subscription was already unsubscribed while a handler still runs; it also cancels it once delivery has ended and the last handler has returned. Unsubscribe alone cancels nothing. A Subscribe handler's context also carries the trace from the message's headers (none from the call's context) and ends after 30 seconds. Subscription.Drain(ctx) returning nil proves every running handler has returned; Unsubscribe stops delivery but does not wait for a running handler.

A panic in a message handler is recovered: it is logged at error level with the message's subject, counted on the JetStream error metric as operation handler_panic, and the message is Nak'd (TestSafeHandleMessageRecoversPanicNaksLogsAndCounts). A Nak that fails is logged with the panic. The server redelivers a Nak'd message (TestIntegration_ConsumeStreamWithConfig_Nak).

A handler that returns without settling its message is not Nak'd for it. The server redelivers such a message when its ack wait ends, as TestIntegrationConsumeDeliveryWithHeartbeatStoppedRenewalUsesBackOff shows for a consumer with BackOff. For a plain consumer handler, that redelivery is not measured here.

Distributed Tracing

All publish and request methods automatically propagate W3C-compliant trace context. If no trace exists in the context, one is auto-generated, ensuring every message can be correlated across services.

Headers injected:

  • traceparent - W3C Trace Context format (00-{trace_id}-{span_id}-{flags})
  • X-Trace-ID, X-Span-ID, X-Parent-Span-ID - Simplified headers for compatibility

Usage

Basic Example
// Create and connect to NATS
client, err := natsclient.NewClient("nats://localhost:4222")
if err != nil {
    return err
}

ctx := context.Background()
err = client.Connect(ctx)
if err != nil {
    return err
}
defer client.Close(ctx)

// Publish a message
err = client.Publish(ctx, "subject.name", []byte("message data"))

// Subscribe to messages
sub, err := client.Subscribe(ctx, "subject.*", func(msgCtx context.Context, msg *nats.Msg) {
    // Handle message
    fmt.Printf("Received: %s\n", string(msg.Data))
})

When Subscribe returns, the server has read the subscription, so a request from another connection finds it, unless the server refused it. A refusal is not returned as an error. A client that connected with Connect logs it, and a client built with WithMetrics also counts it on semengine_nats_server_refusals_total, labelled reason (permission_violation or max_subscriptions_exceeded). The count can rise after Subscribe has returned. A publish the server refuses is counted the same way.

Advanced Usage
// Create client with options
client, err := natsclient.NewClient("nats://localhost:4222",
    natsclient.WithMaxReconnects(-1),  // Infinite reconnects
    natsclient.WithReconnectWait(2*time.Second),
)

// JetStream operations
js, err := client.JetStream()
stream, err := js.CreateStream(ctx, jetstream.StreamConfig{
    Name:     "EVENTS",
    Subjects: []string{"events.>"},
})

// Key-Value store with CAS
bucket, err := client.CreateKeyValueBucket(ctx, jetstream.KeyValueConfig{
    Bucket: "config",
})

kvStore := client.NewKVStore(bucket)
err = kvStore.UpdateJSON(ctx, "service.config", func(config map[string]any) error {
    config["enabled"] = true
    return nil
})
Tracing
// Traces are auto-generated - no action needed for basic tracing
err := client.Publish(ctx, "events.user", data)

// Explicit trace context
tc := natsclient.NewTraceContext()
ctx = natsclient.ContextWithTrace(ctx, tc)
reply, err := client.RequestClassified(ctx, "service.action", data, 5*time.Second)

// Extract trace from incoming message
tc = natsclient.ExtractTrace(msg)
if tc != nil {
    // Create child span for downstream calls
    childCtx := natsclient.ContextWithTrace(ctx, tc.NewSpan())
    err = client.Publish(childCtx, "downstream.subject", response)
}

API Reference

Types
Client

Main client type providing NATS connectivity.

type Client struct {
    // Internal fields not exposed
}
KVStore

High-level KV operations with built-in CAS support.

type KVStore struct {
    // Internal fields not exposed
}
KVOptions

Configuration for KV operations behavior.

type KVOptions struct {
    MaxRetries            int           // Maximum CAS retry attempts (default: 10)
    RetryDelay            time.Duration // Initial delay between retries (default: 10ms)
    Timeout               time.Duration // Ends the wait for the server's answer, not a held write (default: 5s)
    MaxValueSize          int           // Maximum size for values (default: 1MB)
    UseExponentialBackoff bool          // Enable exponential backoff with jitter (default: true)
    MaxRetryDelay         time.Duration // Maximum delay between retries (default: 1s)
}
Functions
NewClient(url string, opts ...ClientOption) (*Client, error)

Creates a new NATS client with the specified server URL and options.

(c *Client) Connect(ctx context.Context) error

Establishes connection to NATS server.

(c *Client) Publish(ctx context.Context, subject string, data []byte) error

Publishes a message to the specified subject.

NewKVStore

(c *Client) NewKVStore(bucket jetstream.KeyValue, opts ...func(*KVOptions)) *KVStore

Creates a KVStore instance for high-level KV operations.

UpdateJSON

(kv *KVStore) UpdateJSON(ctx context.Context, key string, updateFn func(map[string]any) error) error

Performs CAS update on JSON data with automatic retry on conflicts.

IsKVTombstone

IsKVTombstone(operation jetstream.KeyValueOp) bool

Reports whether a KV watch entry removes its key: a delete or a purge. Both arrive with an empty value, so a watcher that handles a removal checks this one predicate rather than testing for a delete and forgetting the purge.

Logging

WithLogger(logger *slog.Logger) ClientOption sets the logger for debug output.

Architecture

Design Decisions

Context-First API: every call that waits for the server, except RTT, takes a context.Context first, and the context ends that wait (P13, P18). It does not end a write the server is not reading (see the overview).

KVStore Abstraction: Created high-level KV abstraction with built-in CAS retry logic to eliminate code duplication across services. Centralizes revision conflict handling and retry logic.

Integration Points
  • Dependencies: NATS server (2.x compatible)
  • Used By: Code that needs NATS messaging
  • Data Flow: Application → Client → NATS Connection → Server

Configuration

Connection Options
WithMaxReconnects(-1)              // Infinite reconnects (default: -1)
WithReconnectWait(2*time.Second)   // Wait between reconnects (default: 2s)
WithTimeout(10*time.Second)        // Connection timeout (default: 5s)
WithWriteTimeout(10*time.Second)   // How long one write may wait for the server to read it (default: 1m, nats.go's)
WithPingInterval(10*time.Second)   // How often nats.go sends the server a PING (default: 30s)
WithLogger(logger)                  // Enable debug logging
WithMetrics(registry)               // Record JetStream and server-refusal metrics on registry

Give each client its own metrics registry. A registry holds one client's JetStream series: its stream and consumer gauges are set from what that client reads from the server. A second client on the same registry writes the same collectors, so the two overwrite each other's gauges, and which client's value a scrape shows is not promised. No configuration we know of runs two clients on one registry.

At nats.go v1.55.0, a write the timeout ends partway closes the socket, and nats.go reconnects (TestWriteTimeoutAndPingIntervalOptions). How soon the connection carries messages again is not promised. WithPingInterval sets how soon nats.go finds a silent server when no write is held; while a write is held its check does not fire. Each option refuses a value that is not positive.

Error Handling

Error Types
var (
    ErrNotConnected       = fmt.Errorf("not connected to NATS: %w", errs.ErrConnectionLost)
    ErrKVKeyNotFound      = errors.New("kv: key not found")
    ErrKVRevisionMismatch = errors.New("kv: revision mismatch (concurrent update)")
    ErrKVMaxRetriesExceeded = errors.New("kv: max retries exceeded")
    ErrKVSkipWrite        = errors.New("kv: update callback skipped the write")
)
Error Detection
// Check specific errors
if errors.Is(err, natsclient.ErrNotConnected) {
    // The client is not connected; try again later
}

// KV conflict detection
if errors.Is(err, natsclient.ErrKVRevisionMismatch) {
    // Handle concurrent update
}

// Helper functions for NATS errors
if natsclient.IsKVNotFoundError(err) {
    // Key doesn't exist
}
Skipping a write

ErrKVSkipWrite is not returned by the client. An update callback returns it, wrapped or not, to say that the read value needs no change. That run writes nothing, the value returned beside the error is ignored, and the call returns no error: UpdateWithRetryRead and UpdateWithRetryRev return revision 0, and UpdateWithRetry and UpdateJSON return nil. No write ever commits at revision 0, so (0, nil) means the callback skipped.

UpdateWithRetryRead's callback also gets the revision the bytes were read at, or 0 when the key is absent (never written, deleted or purged). A caller that decides to skip keeps that revision from the callback's argument; the call's result is only ever the revision of its own write.

var readAt uint64
committed, err := kv.UpdateWithRetryRead(ctx, key, func(current []byte, revision uint64) ([]byte, error) {
    readAt = revision
    if alreadyApplied(current) {
        return nil, natsclient.ErrKVSkipWrite
    }
    return apply(current), nil
})
// committed is 0 after a skip or an error; readAt is the revision the last run read.

Testing

Test Utilities

The package's integration tests start a real NATS server with internal/harness/natsfixture:

// Start a disposable NATS server via testcontainers; its Stop runs on t.Cleanup
fixture := natsfixture.New(t)
if err := fixture.Start(t.Context()); err != nil {
    t.Fatal(err)
}

client, err := natsclient.NewClient(fixture.URL())
if err == nil {
    err = client.Connect(t.Context())
}
Testing Patterns
  • Uses real NATS server via testcontainers (no mocks)
  • Tests actual behavior including connection lifecycle
  • Thread-safe testing with proper synchronization

Performance Considerations

  • Concurrency: Thread-safe for concurrent use from multiple goroutines
  • Memory: Scales with number of active subscriptions and consumers
  • Throughput: Limited by network latency and NATS server performance

Examples

Resilient Publisher
package main

import (
    "context"
    "log"
    "log/slog"
    "time"

    "github.com/c360studio/semengine/natsclient"
)

func main() {
    client, err := natsclient.NewClient("nats://localhost:4222",
        natsclient.WithMaxReconnects(-1),
        natsclient.WithLogger(slog.Default()),
    )
    if err != nil {
        log.Fatal(err)
    }
    
    ctx := context.Background()
    if err := client.Connect(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Close(ctx)
    
    // While nats.go reconnects, Publish returns ErrNotConnected at once, and the
    // loop tries again on its next tick. A nil error means the message is in
    // nats.go's buffer, not that the server has it (ADR-112).
    for {
        if err := client.Publish(ctx, "telemetry.data", []byte("sensor reading")); err != nil {
            log.Printf("Publish error: %v", err)
        }
        time.Sleep(time.Second)
    }
}
Configuration Management with KV
// Manage service configuration with optimistic locking
bucket, _ := client.CreateKeyValueBucket(ctx, jetstream.KeyValueConfig{
    Bucket:   "config",
    History:  5,
    Replicas: 3,
})

kvStore := client.NewKVStore(bucket)

// Atomic configuration update with retry
err = kvStore.UpdateJSON(ctx, "services.processor", func(config map[string]any) error {
    // This function may be called multiple times on conflict
    config["workers"] = 10
    config["timeout"] = "30s"
    return nil
})

License

MIT

Documentation

Overview

Package natsclient provides a client for managing NATS connections and their health status.

Package natsclient provides a NATS client with automatic reconnection and comprehensive JetStream/KV support for distributed edge systems.

The natsclient package wraps the standard NATS Go client. It keeps nats.go's automatic reconnection with natsclient's settings (see Connection Lifecycle below). Every call that waits for the server takes a context, which ends that wait. It does not end a wait behind a write the server is not reading, which lasts until the write completes or nats.go's write timeout (WithWriteTimeout) ends it (measured at nats.go v1.55.0, ADR-112); Close, on a connection the client dialled, and Connect are the exception (TestCloseEndsAHeldWrite, TestConnectEndsWithItsContext). It serves as the foundation for all of SemEngine's NATS communication.

Core Features

Connection Lifecycle Management: Handles connection states automatically through the lifecycle: Disconnected → Connecting → Connected → Reconnecting → Connected. The client manages all transitions.

JetStream Support: Full support for JetStream streams, consumers, and Key-Value stores with proper error handling.

KVStore Abstraction: High-level abstraction over NATS KV providing automatic CAS (Compare-And-Swap) retry logic, a JSON read-modify-write helper (UpdateJSON), and consistent error handling for configuration management scenarios.

Basic Usage

Creating and connecting to NATS:

client, err := natsclient.NewClient("nats://localhost:4222")
if err != nil {
    return err
}

ctx := context.Background()
err = client.Connect(ctx)
if err != nil {
    return err
}
defer client.Close(ctx)

// Publish a message
err = client.Publish(ctx, "subject.name", []byte("message data"))

// Subscribe to messages (receives full *nats.Msg for access to Subject, Data, Headers)
sub, err := client.Subscribe(ctx, "subject.*", func(msgCtx context.Context, msg *nats.Msg) {
    // Handle message with context (30s timeout per message)
    // For wildcard subscriptions, msg.Subject contains the actual subject
    fmt.Printf("Received on %s: %s\n", msg.Subject, string(msg.Data))
})

Advanced Configuration

Creating client with options:

client, err := natsclient.NewClient("nats://localhost:4222",
    natsclient.WithMaxReconnects(-1),  // Infinite reconnects
    natsclient.WithReconnectWait(2*time.Second),
)

Who owns a stream's limits

A stream's limits belong to the component that DECLARES it. If you only READ a stream, bind it by name with GetStream and declare nothing:

if _, err := client.GetStream(ctx, streamName); err != nil {
    if errors.Is(err, jetstream.ErrStreamNotFound) {
        // The stream is not there RIGHT NOW. Handle that — and do not create
        // the stream to make the error go away.
        return nil
    }
    return err
}

One probe's not-found is NOT durable evidence that the declaring component is absent. On a clustered deployment it may also be what a node that has not applied the meta assignment says about a stream that exists; that is not measured, since no test here runs a cluster. So a decision taken for the PROCESS LIFETIME on that answer — disabling a subscriber, skipping a component, reporting a deployment shape — can be decided by cluster timing, and then it fails in the worst direction: boot SUCCEEDS and the work silently never happens.

Take that decision from the guarded consumer setup instead. ConsumeStreamWithConfig, ConsumeStreamWithConfigContexts and ConsumeInternalStreamWithConfig re-observe an absent stream for the framework's visibility budget, meant to wait out that cluster window (not measured, as above), and the error they return carries ErrStreamNotVisible only when the stream stayed absent for the whole budget (stream_visibility_test.go, with a stand-in for JetStream). Branch on that sentinel — never on a bare jetstream.ErrStreamNotFound, which those same operations also return for a consumer-creation or consumer-observation fault against a stream that is present.

This is not style. EnsureStream is get-or-create: a reader that calls it with its own configuration either creates the stream with limits it does not own, or binds an existing one and has its declaration silently discarded — after which the stream's limits are decided permanently by boot order. Since the framework's provisioner reconciles retention drift, two components declaring one stream differently is worse than that: each repairs the other's value on every boot, forever. Neither can detect it locally, because a caller sees its own declaration and the live stream, never the other declaration.

EnsureStream reports a divergence between what you declared and what a bound stream actually carries (see DiffDeclaredStream). A report that returns on every boot, with the observed value alternating, is that flap.

JetStream Operations

Working with JetStream streams and consumers:

// Create a stream. An ordinary stream MUST declare a finite MaxAge and a
// finite MaxBytes, and creation is refused without them. MaxBytes 0 and -1
// both mean unlimited to JetStream (measured at nats-server v2.14.7,
// ADR-112), so neither is a declaration. Set Discard explicitly too — it
// cannot be required (DiscardOld is the field's zero value) but at a
// finite MaxBytes it decides whether the oldest messages are evicted or
// the newest are refused.
stream, err := client.CreateStream(ctx, jetstream.StreamConfig{
    Name:     "EVENTS",
    Subjects: []string{"events.>"},
    MaxAge:   24 * time.Hour,
    MaxBytes: 1 << 30,
    Discard:  jetstream.DiscardOld,
})

// Publish to stream
err = client.PublishToStream(ctx, "events.user.created", []byte(`{"user_id": "123"}`))

// A port-backed consumer supplies bounded owner context. The client observes
// requested versus effective acknowledgement admission before delivery.
ownerCtx, cancelOwner := context.WithCancel(ctx)
consumeHandle, err := client.ConsumeStreamWithConfig(ownerCtx,
    natsclient.PortConsumerContext{Component: "example", Port: "events"},
    natsclient.StreamConsumerConfig{
        StreamName: "EVENTS", ConsumerName: "example-events",
        FilterSubject: "events.>", AckPolicy: "explicit",
    }, func(_ context.Context, msg jetstream.Msg) {
    // Process event - msg.Subject() contains actual subject for wildcard filters
    processEvent(msg.Subject(), msg.Data())
    msg.Ack()
})
if err != nil {
    cancelOwner()
    return err
}
// The owner retains consumeHandle and cancelOwner while running. During Stop,
// drain the handle. Closed reports the end of a drain that completed, but it can
// report the end early once delivery was stopped without a drain or the
// connection was force-closed (nats.go jetstream/pull.go:822-837). A nil
// client.Close is the proof that no handler invocation is still running.
shutdownCtx, cancelShutdown := context.WithTimeout(context.Background(), 5*time.Second)
defer cancelShutdown()
consumeHandle.Drain()
select {
case <-consumeHandle.Closed():
case <-shutdownCtx.Done():
    cancelOwner()
    return shutdownCtx.Err()
}
cancelOwner()

// Framework-internal consumers with no JetStreamPort contract retain the
// native handle. Drain it when done; client.Close stops and joins the consumer
// if the caller has not, and its nil return proves no handler still runs.
internalHandle, err := client.ConsumeInternalStreamWithConfig(ctx, internalConfig, internalHandler)
if err == nil {
    defer internalHandle.Drain()
}

Key-Value Store

Using KVStore for configuration management with atomic updates:

// Create or get KV bucket
bucket, err := client.CreateKeyValueBucket(ctx, jetstream.KeyValueConfig{
    Bucket:   "config",
    History:  5,
    Replicas: 3,
})

// Create KVStore wrapper
kvStore := client.NewKVStore(bucket)

// Atomic JSON update with automatic CAS retry
err = kvStore.UpdateJSON(ctx, "service.config", func(config map[string]any) error {
    // This function may be called multiple times on conflict
    config["enabled"] = true
    config["workers"] = 10
    return nil
})

// Read a JSON value: KVStore has no JSON getter, so decode the entry's bytes
entry, err := kvStore.Get(ctx, "service.config")
if err != nil {
    return err
}
var config map[string]any
err = json.Unmarshal(entry.Value, &config)

Connection Status and Health

Monitoring connection health:

// Check current status
status := client.Status()
switch status {
case natsclient.StatusConnected:
    // Healthy and ready
case natsclient.StatusReconnecting:
    // Temporarily disconnected, reconnecting
case natsclient.StatusDisconnected:
    // Not connected
}

// Get detailed status
statusInfo := client.GetStatus()
log.Printf("Status: %v, RTT: %v",
    statusInfo.Status,
    statusInfo.RTT)

// Wait for connection
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
err := client.WaitForConnection(ctx)

Error Handling

The package defines specific error types for different failure scenarios:

var (
    ErrNotConnected       = fmt.Errorf("not connected to NATS: %w", errs.ErrConnectionLost)
)

Error detection patterns:

err := client.Publish(ctx, "subject", data)
if err != nil {
    // Check for connection issues
    if errors.Is(err, natsclient.ErrNotConnected) {
        // Trigger reconnection
        return
    }

    // Other error
    log.Printf("Publish failed: %v", err)
}

KV-specific error handling:

err := kvStore.UpdateJSON(ctx, key, updateFn)
if err != nil {
    // Check for key not found
    if natsclient.IsKVNotFoundError(err) {
        // Key doesn't exist, create it
    }

    // Check for conflict (CAS failed after retries)
    if natsclient.IsKVConflictError(err) {
        // Too many concurrent updates
    }
}

Connection Options

Available configuration options:

WithMaxReconnects(n int)              // Maximum reconnection attempts (-1 = infinite)
WithReconnectWait(d time.Duration)    // Wait between reconnection attempts
WithTimeout(d time.Duration)          // Connection timeout
WithWriteTimeout(d time.Duration)     // How long a write may wait for the server to read it (default: one minute, nats.go's)
WithPingInterval(d time.Duration)     // How often to PING the server (default: 30 s)
WithLogger(logger *slog.Logger)       // Custom logger for debug output
WithName(name string)                 // Client identification

Authentication and Security

Username/password authentication:

client, err := natsclient.NewClient(url,
    natsclient.WithCredentials("username", "password"),
)

Note: Credentials are cleared from memory when the client is closed.

Testing

The package's integration tests start a real NATS server with internal/harness/natsfixture:

func TestMyService(t *testing.T) {
    // Start a disposable NATS server via testcontainers; its Stop runs on t.Cleanup
    fixture := natsfixture.New(t)
    if err := fixture.Start(t.Context()); err != nil {
        t.Fatal(err)
    }

    client, err := natsclient.NewClient(fixture.URL())
    assert.NoError(t, err)
    assert.NoError(t, client.Connect(t.Context()))

    // Test with real NATS server
    err = client.Publish(t.Context(), "test.subject", []byte("test data"))
    assert.NoError(t, err)
}

Testing patterns:

  • Uses real NATS server via testcontainers (no mocks)
  • Tests actual behavior including connection lifecycle
  • Thread-safe testing with proper synchronization

Thread Safety

The Client type is thread-safe and can be used concurrently from multiple goroutines:

  • All public methods are safe for concurrent use
  • Connection state is managed with atomic operations and mutexes
  • Subscriptions and consumers can be created from any goroutine
  • Only the first Close() drains; a later Close() waits for the same completion

Performance Considerations

Concurrency: Thread-safe for concurrent use from multiple goroutines. No artificial concurrency limits - scales with available system resources.

Memory: Memory usage scales with number of active subscriptions and consumers. Each subscription maintains its own message buffer. Health monitoring adds minimal overhead (one goroutine with configurable interval).

Throughput: Limited primarily by network latency and NATS server performance.

Connection Lifecycle: natsclient asks nats.go to wait ReconnectWait between reconnect attempts: 2 s by default, natsclient's setting (WithReconnectWait). How nats.go paces the attempts is not promised (ADR-112).

Distributed Tracing

The package provides W3C-compliant trace context propagation for distributed tracing. All publish and request methods automatically generate trace context if none exists, ensuring complete observability across the message flow.

Trace headers are injected into all outbound NATS messages:

  • traceparent: W3C Trace Context header (00-{trace_id}-{span_id}-{flags})
  • X-Trace-ID: Simplified trace ID header
  • X-Span-ID: Current span identifier
  • X-Parent-Span-ID: Parent span for nested operations

Using trace context:

// Traces are auto-generated if not present
err := client.Publish(ctx, "subject", data)

// Or provide explicit trace context
tc := natsclient.NewTraceContext()
ctx = natsclient.ContextWithTrace(ctx, tc)
err := client.Publish(ctx, "subject", data)

// Extract trace from received message
tc := natsclient.ExtractTrace(msg)
if tc != nil {
    log.Printf("Trace ID: %s, Span ID: %s", tc.TraceID, tc.SpanID)
}

Creating child spans for nested operations:

parentTC, _ := natsclient.TraceContextFromContext(ctx)
childTC := parentTC.NewSpan()
childCtx := natsclient.ContextWithTrace(ctx, childTC)
reply, err := client.RequestClassified(childCtx, "service.action", data, timeout)

The unified RPC error contract (ADR-060)

A request/reply is EITHER a success body (nil Go error) OR a single typed error value. A SubscribeForRequests handler that returns a Go error has it sent as a header-classified reply:

  • Headers: X-Status: error + X-Error-Class: invalid|transient|fatal
  • X-Error-Code: <stable machine code> (when coded)
  • Body: the standard {"message": "...", "detail": {...}} envelope

There is no in-band error channel: a reply with no X-Status header is success, whatever its body says.

Callers use RequestClassified, or RequestWithRetryClassified only when an operation-specific non-graph contract authorizes redelivery. Both surface the classified error via the err return (transport AND handler failures, uniformly). Canonical graph mutations always use one RequestClassified attempt; components own any later retry decision:

data, err := c.RequestClassified(ctx, "subject", body, 5*time.Second)
if err != nil {
    if errors.Is(err, errs.ErrRevisionMismatch) { /* caller may re-read and retry */ }
    if errs.IsInvalid(err)   { /* 4xx — bad input */ }
    if errs.IsTransient(err) { /* surface or apply an explicit operation policy */ }
    var ce *errs.ClassifiedError
    if errors.As(err, &ce)   { /* ce.Code, ce.Detail */ }
}
json.Unmarshal(data, &resp) // success body; err already handled

FOOTGUN: RequestWithHeaders returns the reply as received and does NOT inspect the X-Status header — a handler error arrives as the error envelope body with err == nil, which a caller would silently json.Unmarshal as a zero-valued success. A caller of RequestWithHeaders runs ClassifyReply on the reply; every other caller uses RequestClassified.

Handler-side, return a classified error so the headers carry truth:

return nil, errs.ClassifiedCode(errs.ErrorInvalid,
    "entity_not_found", fmt.Errorf("not found: %s", req.ID))
// Consumer via RequestClassified: errs.IsInvalid(err) == true,
// errors.As → ce.Code == "entity_not_found"; gateways map that to 404.

Architecture Integration

The natsclient package is the NATS layer under SemEngine's other packages. It records JetStream stream and consumer metrics in a metric.MetricsRegistry when given one (WithMetrics), and returns pkg/errs classified errors.

Data flow:

Application → Client → NATS Connection → NATS Server

Design Decisions

Context-First API: every call that waits for the server takes a context.Context as its first parameter, and the context ends that wait. It does not end a wait behind a write the server is not reading (measured at nats.go v1.55.0, ADR-112); Close and Connect are the exception (TestCloseEndsAHeldWrite, TestConnectEndsWithItsContext). RTT takes no context.

KVStore Abstraction: Created high-level KV abstraction with built-in CAS retry logic to eliminate code duplication across services. Centralizes revision conflict handling and retry logic.

Testcontainers over Mocks: Integration tests use real NATS server via testcontainers to catch actual integration issues. Mock-based testing can miss edge cases in the NATS protocol implementation.

Examples

Resilient publisher with automatic reconnection:

package main

import (
    "context"
    "log"
    "log/slog"
    "time"

    "github.com/c360studio/semengine/natsclient"
)

func main() {
    client, err := natsclient.NewClient("nats://localhost:4222",
        natsclient.WithMaxReconnects(-1),
        natsclient.WithLogger(slog.Default()),
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()
    if err := client.Connect(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Close(ctx)

    // While nats.go reconnects, Publish returns ErrNotConnected at once, and the
    // loop tries again on its next tick. A nil error means the message is in
    // nats.go's buffer, not that the server has it (ADR-112).
    for {
        if err := client.Publish(ctx, "telemetry.data", []byte("sensor reading")); err != nil {
            log.Printf("Publish error: %v", err)
        }
        time.Sleep(time.Second)
    }
}

Configuration management with atomic updates:

// Manage service configuration with optimistic locking
bucket, _ := client.CreateKeyValueBucket(ctx, jetstream.KeyValueConfig{
    Bucket:   "config",
    History:  5,
    Replicas: 3,
})

kvStore := client.NewKVStore(bucket)

// Atomic configuration update with automatic retry
err = kvStore.UpdateJSON(ctx, "services.processor", func(config map[string]any) error {
    // This function may be called multiple times on conflict
    config["workers"] = 10
    config["timeout"] = "30s"
    return nil
})

For more examples and detailed usage, see the README.md in this directory.

Package natsclient — the unified RPC error contract (ADR-060).

A request/reply is EITHER a success body (with no error header) OR a single typed error value. There is no in-band error channel. A handler error from a SubscribeForRequests handler — and from direct msg.Respond callers that opt in via RespondError — travels as wire headers plus a standard JSON error body:

X-Status:      error
X-Error-Class: transient | invalid | fatal
X-Error-Code:  entity_not_found | revision_mismatch | ...   (when coded)
body:          {"message": "<text>", "detail": {...}}

ClassifyReply reconstructs a *errs.ClassifiedError from these: the class drives errs.IsInvalid / IsTransient / IsFatal, the code is reached via errors.As(err, &ce) → ce.Code, the one control-flow sentinel round-trips via errors.Is(err, errs.ErrRevisionMismatch), and the structured detail via ce.Detail.

Caller pattern:

data, err := c.RequestClassified(ctx, subj, body, timeout)
if err != nil {
    // transport OR classified handler error, uniformly:
    if errors.Is(err, errs.ErrRevisionMismatch) { /* caller decides whether to re-read and retry */ }
    if errs.IsInvalid(err) { /* 4xx */ }
    if errs.IsTransient(err) { /* surface or apply the operation's explicit policy */ }
    var ce *errs.ClassifiedError
    if errors.As(err, &ce) { /* ce.Code, ce.Detail */ }
    return err
}
json.Unmarshal(data, &resp) // data is a success body; err already handled

Handler pattern: return (nil, err) — SubscribeForRequests calls RespondError for you. HTTP semantics (404 vs 400) belong at the gateway, which reads ce.Code (e.g. entity_not_found → 404) rather than substring-sniffing.

Footgun — RequestWithHeaders does not classify

RequestWithHeaders returns the reply as received and does NOT inspect the X-Status header. A handler error reply carries the {message, detail} body with err == nil, so

msg, err := c.RequestWithHeaders(...)
if err != nil { return err }
json.Unmarshal(msg.Data, &resp)   // mis-decodes an error body as success

silently mis-decodes failures. A caller of RequestWithHeaders runs ClassifyReply on the reply; every other caller uses RequestClassified or RequestWithRetryClassified, which do it for them.

Sentinel chains do not survive the wire boundary

classifiedFromHeader reconstructs a fresh *errs.ClassifiedError from the headers + body. An arbitrary inner sentinel chain (jetstream.ErrKeyNotFound, etc.) is LOST in transit; what round-trips is the {class, code, message, detail} contract — including errs.ErrRevisionMismatch by code. Surface any other distinction a consumer must branch on as a code (ce.Code).

Package natsclient provides request/reply pattern support for NATS.

Package natsclient provides JetStream stream management utilities.

Index

Constants

View Source
const (
	// KVStreamPrefix is the NATS naming convention for a KV bucket's backing
	// stream: KV_<bucket> (nats.go jetstream/kv.go, kvBucketNamePre = "KV_").
	KVStreamPrefix = "KV_"

	// ObjectStoreStreamPrefix is the NATS naming convention for an
	// ObjectStore's backing stream: OBJ_<bucket> (nats.go
	// jetstream/object.go, objNameTmpl = "OBJ_%s").
	ObjectStoreStreamPrefix = "OBJ_"
)

Backing-stream naming conventions. NATS implements every KV bucket and every ObjectStore as an ordinary JetStream stream with a reserved name prefix, so a bucket's lifecycle-eviction config (MaxAge/MaxBytes/Discard) is reachable through the plain stream API. That reachability is what the retention reconcilers here and in storage/objectstore depend on — and it is also what lets an unfiltered provisioning seam stamp age eviction onto authoritative graph state, which is why every such seam refuses these prefixes outright.

These are the ONE definition of each prefix. The KV and ObjectStore retention paths and every provisioning guard read them from here so the convention cannot fork into per-package literals.

View Source
const (
	// HeaderStatus is set to HeaderStatusError on reply messages that
	// represent a handler-side failure. Absent on success replies.
	HeaderStatus = "X-Status"

	// HeaderErrorClass carries the pkg/errs.ErrorClass value as a
	// lowercase string: "transient", "invalid", or "fatal". Set
	// only when HeaderStatus == HeaderStatusError.
	HeaderErrorClass = "X-Error-Class"

	// HeaderErrorCode carries the ADR-060 stable machine Code for the
	// failure (the graph.ErrorCode* values: "entity_not_found",
	// "revision_mismatch", ...). ClassifyReply reads it into
	// (*errs.ClassifiedError).Code so errors.Is(err, ErrRevisionMismatch)
	// and ce.Code discrimination work across the wire. Set ONLY when the
	// handler error carries a non-empty Code; an uncoded handler error
	// carries no X-Error-Code header.
	HeaderErrorCode = "X-Error-Code"
)

Header keys for the header-classified error convention. A failure reply carries X-Status: error plus the class/code headers; ClassifyReply reconstructs the typed error from them.

View Source
const (
	HeaderStatusError = "error"

	ErrorClassTransient = "transient"
	ErrorClassInvalid   = "invalid"
	ErrorClassFatal     = "fatal"
)

Values used in HeaderStatus / HeaderErrorClass.

View Source
const (
	// MaxKVLiteralTokenBytes is the byte budget for one literal KV token.
	MaxKVLiteralTokenBytes = 512
	// MaxKVLiteralKeyBytes is the byte budget for one complete literal KV key.
	MaxKVLiteralKeyBytes = 1024
	// MaxKVLiteralKeyTokens is the arity budget for one complete literal KV key.
	MaxKVLiteralKeyTokens = 64
	// MaxKVWildcardFilterBytes is the byte budget for one complete KV filter.
	MaxKVWildcardFilterBytes = 1024
	// MaxKVWildcardFilterTokens is the arity budget for one complete KV filter.
	MaxKVWildcardFilterTokens = 64
	// MaxKVOpaqueTokenInputBytes is the largest byte string accepted by the v1 opaque codec.
	MaxKVOpaqueTokenInputBytes = 254
	// MaxKVOpaqueTokenBytes is the largest token produced or accepted by the v1 opaque codec.
	MaxKVOpaqueTokenBytes = 511
)
View Source
const (
	// ErrorCodeKVTokenInvalid classifies invalid literal KV tokens.
	ErrorCodeKVTokenInvalid = "kv_token_invalid"
	// ErrorCodeKVKeyInvalid classifies invalid literal KV keys.
	ErrorCodeKVKeyInvalid = "kv_key_invalid"
	// ErrorCodeKVFilterInvalid classifies invalid KV wildcard filters.
	ErrorCodeKVFilterInvalid = "kv_filter_invalid"
	// ErrorCodeKVTokenEncodeInvalid classifies unsupported opaque-token input.
	ErrorCodeKVTokenEncodeInvalid = "kv_token_encode_invalid"
	// ErrorCodeKVTokenDecodeInvalid classifies invalid opaque-token encodings.
	ErrorCodeKVTokenDecodeInvalid = "kv_token_decode_invalid"
	// ErrorCodeResponseTooLarge classifies a reply refused because its encoding
	// exceeds the server's maximum payload (class invalid). SubscribeForRequests
	// answers with it when a handler's reply is too large to publish; a handler
	// that bounds its own pages returns the same code when no page fits.
	ErrorCodeResponseTooLarge = "response_too_large"
)
View Source
const (
	// KVReasonEmpty identifies an empty whole input.
	KVReasonEmpty = "empty"
	// KVReasonBytes identifies a whole-input byte-budget violation.
	KVReasonBytes = "bytes"
	// KVReasonTokens identifies a whole-input token-count violation.
	KVReasonTokens = "tokens"
	// KVReasonEmptyToken identifies an empty position in a key or filter.
	KVReasonEmptyToken = "empty_token"
	// KVReasonTokenBytes identifies a per-token byte-budget violation.
	KVReasonTokenBytes = "token_bytes"
	// KVReasonSeparator identifies a separator in a literal token.
	KVReasonSeparator = "separator"
	// KVReasonWildcard identifies a wildcard in a literal position.
	KVReasonWildcard = "wildcard"
	// KVReasonPosition identifies a wildcard in a forbidden position.
	KVReasonPosition = "position"
	// KVReasonAlphabet identifies a byte outside the literal alphabet.
	KVReasonAlphabet = "alphabet"
	// KVReasonVersion identifies an unknown opaque codec version.
	KVReasonVersion = "version"
	// KVReasonHex identifies malformed opaque hexadecimal.
	KVReasonHex = "hex"
	// KVReasonNoncanonical identifies valid but non-canonical opaque hexadecimal.
	KVReasonNoncanonical = "noncanonical"
)
View Source
const (
	// KVDetailReason is the mandatory stable reason detail key.
	KVDetailReason = "reason"
	// KVDetailMeasuredBytes reports the rejected byte count.
	KVDetailMeasuredBytes = "measured_bytes"
	// KVDetailAllowedBytes reports the applicable byte budget.
	KVDetailAllowedBytes = "allowed_bytes"
	// KVDetailMeasuredTokens reports the rejected token count.
	KVDetailMeasuredTokens = "measured_tokens"
	// KVDetailAllowedTokens reports the applicable token-count budget.
	KVDetailAllowedTokens = "allowed_tokens"
	// KVDetailTokenIndex reports the zero-based failing position.
	KVDetailTokenIndex = "token_index"
)
View Source
const (
	// DefaultReadinessProbeTimeout bounds each attempt. Short so a
	// not-yet-subscribed responder fails fast and retries instead of consuming a
	// full query timeout per attempt.
	DefaultReadinessProbeTimeout = 2 * time.Second
	// DefaultReadinessBudget bounds the TOTAL wall-clock spent waiting for the
	// responder to come up before the error surfaces. Neither bounds a wait
	// behind a write the server is not reading: such a write holds an attempt
	// until it completes or nats.go's write timeout (one minute by default,
	// WithWriteTimeout) ends it (measured at nats.go v1.55.0, ADR-112).
	DefaultReadinessBudget = 30 * time.Second
)

Readiness-gated read defaults (the third bucket of the request doctrine). A readiness-gated read tolerates a not-yet-subscribed responder at cold start / after reconnect: it retries with a SHORT per-attempt timeout up to a bounded TOTAL budget, returning the first reply. Because the per-attempt timeout is short and the total is bounded, a genuinely hung responder fails within the budget rather than a full-timeout×N storm — so it does NOT mask a hung responder the way retrying a full-timeout query would. Distinct from RequestClassified (steady-state query: timeout = real signal, no retry) and RequestWithRetryClassified (an operation whose contract authorizes redelivery: retry on no reply, at full timeout).

View Source
const (
	// TraceparentHeader is the W3C standard trace context header
	// Format: 00-{trace_id}-{span_id}-{flags}
	// trace_id: 32 hex chars (16 bytes), span_id: 16 hex chars (8 bytes)
	TraceparentHeader = "traceparent"

	// TraceIDHeader is a simplified header for internal use
	TraceIDHeader = "X-Trace-ID"
	// SpanIDHeader is a simplified header for internal use
	SpanIDHeader = "X-Span-ID"
	// ParentSpanHeader is a simplified header for internal use
	ParentSpanHeader = "X-Parent-Span-ID"
)

W3C Trace Context headers

View Source
const DefaultRequestHandlerTimeout = 30 * time.Second

DefaultRequestHandlerTimeout bounds a single inbound request-handler invocation (SubscribeForRequests). It caps how long a handler may run before its context is cancelled, so a wedged or pathologically slow handler cannot pin a NATS delivery goroutine indefinitely. This is the CI/default value and MUST NOT change without weighing every request handler in the tree; slow-by-design handlers (e.g. an LLM answer-synthesis path that legitimately needs >30s) raise it per deployment via the SEMENGINE_NATS_REQUEST_HANDLER_TIMEOUT environment variable rather than editing this constant.

View Source
const DefaultRequestTimeout = 5 * time.Second

DefaultRequestTimeout is the default timeout for request/reply operations.

Variables

View Source
var (
	ErrKVKeyNotFound        = errors.New("kv: key not found")
	ErrKVKeyExists          = errors.New("kv: key already exists")
	ErrKVRevisionMismatch   = errors.New("kv: revision mismatch (concurrent update)")
	ErrKVMaxRetriesExceeded = errors.New("kv: max retries exceeded")
	// ErrKVSkipWrite, returned by an update callback (wrapped or not), makes the update write nothing.
	ErrKVSkipWrite = errors.New("kv: update callback skipped the write")
)

Well-known errors matching Graph processor patterns

View Source
var ErrBackingStreamNotProvisionable = errors.New(
	"stream provisioning governs ordinary streams only; " +
		"KV and ObjectStore backing streams are not provisionable here")

ErrBackingStreamNotProvisionable is returned when a stream-provisioning seam is handed a KV or ObjectStore backing-stream name. Sentinel so a boot path (or a test) can classify the refusal distinctly from a NATS-side create failure.

View Source
var ErrGraphBucketRetention = errors.New("bucket has lifecycle retention, which is forbidden for state that must not be evicted")

ErrGraphBucketRetention is returned by CheckNoLifecycleRetention when a bucket holding state that must not be evicted carries a lifecycle-eviction config. Sentinel so a boot path can classify it (fail-closed) distinctly from a transient status error.

Two callers, one mechanical rule and two reasons for it: the live graph bucket (ADR-068 — eviction is reachability-blind) and the shared configuration bucket that holds the create-once platform identity (ADR-102 — an expired identity is reminted as a second authority that can never be reconciled). The exported name predates the second caller.

View Source
var ErrHeartbeatFailed = errors.New("delivery heartbeat failed")

ErrHeartbeatFailed identifies loss of the InProgress settlement path while work may already have caused an external effect.

View Source
var (
	// ErrNotConnected wraps errs.ErrConnectionLost, so errs.IsTransient and
	// errs.Classify both call it transient.
	ErrNotConnected = fmt.Errorf("not connected to NATS: %w", errs.ErrConnectionLost)
)

Error messages

View Source
var ErrStreamBoundsUndeclared = errors.New("ordinary stream bounds are not declared")

ErrStreamBoundsUndeclared is the ONE identity for the bounds requirement, whichever seam refuses. `config` shares this value rather than defining its own, so a caller — including a sister repo — can test for the requirement without knowing whether the declarative path or the programmatic one caught it.

View Source
var ErrStreamNotVisible = errors.New("stream not visible for the whole stream-visibility budget")

ErrStreamNotVisible reports that a stream this connection was told did not exist stayed absent for the framework's entire stream-visibility budget.

It is the only durable evidence of absence natsclient produces, and a caller deciding anything for the process lifetime — disabling a subscriber, skipping a component, reporting a deployment shape — branches on THIS. A bare jetstream.ErrStreamNotFound is not evidence of absence: on a clustered deployment it may also be what a node that has not applied the meta assignment says about a stream that exists (not measured: no test here runs a cluster), and it also reaches a consumer-setup caller from consumer CREATION and consumer OBSERVATION, neither of which is a statement about the stream's existence at all.

The contract, in three parts, is natsclient's own logic, tested with a stand-in for JetStream (stream_visibility_test.go):

  • Produced only when the visibility budget was spent re-observing a stream reported absent on this connection.
  • Always joined with the absent classification, so errors.Is(err, jetstream.ErrStreamNotFound) holds on the same error.
  • NEVER produced when the caller's context ended the wait. That error carries the caller's own cause joined with the absent classification, because a wait the caller cut short measured nothing.

Functions

func BucketLastSeq

func BucketLastSeq(ctx context.Context, bucket interface {
	Status(context.Context) (jetstream.KeyValueStatus, error)
}) (uint64, error)

BucketLastSeq returns the backing stream's LastSeq for a KV bucket — the highest sequence ever assigned to the bucket, read fresh from the server on every call.

It is the query-time "target" for revision-lag readiness (ADR-066): every committed write to the bucket has a Revision() <= LastSeq, and LastSeq is monotonic even under History=1 — a purge raises FirstSeq but never lowers LastSeq. LastSeq shares the same sequence space as KeyValueEntry.Revision() (both are stream sequence numbers), so a caller can compare an indexed-revision watermark directly against it. Prefer this over the last watch entry's Delta()==0: that cache is stale exactly in the committed-but-not-yet-delivered window this target must see through.

func BucketRetention

func BucketRetention(ctx context.Context, bucket jetstream.KeyValue) (maxAge time.Duration, maxBytes int64, err error)

BucketRetention returns a bucket's lifecycle-eviction config from its backing stream: maxAge (the KV bucket's TTL — age eviction) and maxBytes (size eviction; 0/negative = unlimited). Callers on the live graph assert both are non-binding — NATS age/size eviction is reachability-blind and would drop entities with live inbound edges (ADR-068). Mirrors BucketLastSeq: the KeyValueStatus interface does not surface these, so we read the concrete JetStream-backed status's stream config.

func CheckNoLifecycleRetention

func CheckNoLifecycleRetention(name string, maxAge time.Duration, maxBytes int64) error

CheckNoLifecycleRetention is the pure guardrail: it errors if a bucket's retention config is binding. maxAge > 0 (a TTL) is always a violation. maxBytes > 0 is a violation too — a size cap evicts by size, which is blind to whether the key it drops was reachable or was the deployment's own identity; a deployment that genuinely wants a non-binding crash backstop should size it far above steady state and treat hitting it as an alert, not configure it here. Pure + no I/O so it is unit-testable; the boot path pairs it with BucketRetention.

func CheckOrdinaryStreamName

func CheckOrdinaryStreamName(name, source string) error

CheckOrdinaryStreamName is the fail-closed name guard shared by every stream-provisioning seam. Stream provisioning governs ORDINARY streams — JetStream streams a component creates to carry time-shaped events. NATS also implements every KV bucket and every ObjectStore as a JetStream stream (KVStreamPrefix+<bucket> and ObjectStoreStreamPrefix+<bucket>), which puts those resources within reach of the plain stream API. They are not ordinary streams: KV buckets are acquired through the bucket descriptor catalog's acquisition seam or by the product component that owns them, content stores through the content-store constructor, and both retention contracts belong to graph-retention (ADR-068/073).

The hazard is measured, not theoretical. Handing an EXISTING OBJ_ backing stream to a reconciling provisioner switches on age eviction, flips Discard to delete-oldest, AND replaces the store's real chunk/meta subjects — silently, returning nil. On a get-or-create seam the damage is name-squatting instead: a stream created under a bucket's reserved name carrying a foreign TTL and the wrong subjects, which the bucket's later catalog acquisition then collides with. Both shapes are refused here, at the seam.

The rule is the NAME PREFIX, not descriptor-catalog membership, because every downstream safety net has a hole: ReconcileNoLifecycleRetention clears only MaxAge/MaxBytes and never a discard policy; a descriptor declared retention-unmanaged reconciles nothing at all; and product or sister-repo buckets outside the catalog have neither an acquisition seam nor a pre-start backstop to repair a stamp a provisioner applied. A guard covering only catalog members would leave all three open.

The source argument names where the declaration came from — an operator config key, a component port, or the calling seam — so the operator can find and delete it. This function is pure and I/O-free, so it can run at config validation, before any JetStream call, and before any connection check.

func CheckStreamBounds

func CheckStreamBounds(cfg jetstream.StreamConfig, source string) error

CheckStreamBounds refuses to CREATE an ordinary stream that declares no finite byte and age bounds.

It is pure and I/O-free, so a caller can run it at configuration-validation time rather than discovering the refusal at boot. Backing streams are not its business: a KV or ObjectStore backing stream is refused outright by CheckOrdinaryStreamName, and its retention contract belongs to graph-retention (ADR-068/073), so this returns nil for one rather than demanding bounds that would be the wrong requirement entirely.

source names the caller so an operator can find what to edit.

func ClassifyConsumerPolicyError

func ClassifyConsumerPolicyError(err error, operation string) error

ClassifyConsumerPolicyError classifies NATS policy rejections as invalid configuration while preserving all other failures as transient.

func ClassifyReply

func ClassifyReply(msg *nats.Msg) ([]byte, error)

ClassifyReply inspects a reply message and returns either the success body (when no error signal is present) or a classified error suitable for branching with errs.IsInvalid / IsTransient / IsFatal.

ADR-060: a failure is signalled ONLY by the X-Status: error header. The body is the standard {message, detail} envelope; the message + detail + the X-Error-Class / X-Error-Code headers reconstruct a *errs.ClassifiedError so errors.As(err, &ce) reaches ce.Code/ce.Detail and errors.Is(err, errs.ErrRevisionMismatch) round-trips. A body alone never signals failure: every producer header-stamps via RespondError.

Numbers in Detail decode as float64 (ADR-060): every integer up to 2^53 survives the wire exactly, and a larger revision may come back rounded. No known workload reaches that range, so the limit is the contract.

func ContextWithTrace

func ContextWithTrace(ctx context.Context, tc *TraceContext) context.Context

ContextWithTrace returns a context with trace information

func DecodeKVOpaqueToken

func DecodeKVOpaqueToken(token string) ([]byte, error)

DecodeKVOpaqueToken decodes one canonical v1 opaque token. It rejects unknown versions, malformed hexadecimal, and uppercase non-canonical forms.

func DivergenceLabels

func DivergenceLabels(divergences []StreamFieldDivergence) []string

DivergenceLabels renders divergences for a log attribute.

func EncodeKVOpaqueToken

func EncodeKVOpaqueToken(raw []byte) (string, error)

EncodeKVOpaqueToken encodes arbitrary bytes as one canonical v1 literal KV token. Callers must explicitly choose opaque storage for their key axis.

func EnsureFrameworkBucket

func EnsureFrameworkBucket(ctx context.Context, c *Client, spec BucketSpec) (jetstream.KeyValue, error)

EnsureFrameworkBucket is the OWNER acquisition seam: create-or-open the bucket, reconcile the live bucket to the declared policy (retention per Kind; History to the declared value), verify by re-read, and return the handle. Any failure returns to the caller's Start, which the composition root fails closed (the component-start barrier) — that composition is why no post-start boot sweep exists anymore.

Reconciling at acquisition (rather than at boot only) is what closes the post-boot-cutoff class: a dynamic component add/edit re-acquires its buckets through this seam and reconciles them right there.

func FilteredKeys

func FilteredKeys(ctx context.Context, kv interface {
	WatchFiltered(ctx context.Context, keys []string, opts ...jetstream.WatchOpt) (jetstream.KeyWatcher, error)
}, pattern string) ([]string, error)

FilteredKeys returns keys matching a NATS wildcard pattern from a KV reader, such as a jetstream.KeyValue. The pattern should be a valid NATS subject filter (e.g., "0.>" for level-0 community keys). It completes the same way as KVStore.KeysByFilter, bounded by the caller's context alone. It returns nil and no error when no key matches (TestIntegration_FilteredKeyListingsNoMatch).

func InjectTrace

func InjectTrace(ctx context.Context, msg *nats.Msg)

InjectTrace adds trace headers to a NATS message from context

func IsKVConflictError

func IsKVConflictError(err error) bool

IsKVConflictError checks if error indicates a conflict (key exists or wrong revision). Like IsKVNotFoundError it reads the error's type, never its text. A wrong last sequence comes back as 10164 or 10071, both "wrong last sequence" (server/errors.json at nats-server v2.15.2, read); that a replicated stream answers 10164 and a single replica 10071 is not measured and not promised.

func IsKVNotFoundError

func IsKVNotFoundError(err error) bool

IsKVNotFoundError checks if error indicates key absence — either a never-created key (jetstream.ErrKeyNotFound) or a tombstoned key (jetstream.ErrKeyDeleted). Both surface to callers as "the key is not there"; UpdateWithRetry relies on this to set revision=0 and route the updateFn down the create path.

The NATS Go SDK's public Get already maps ErrKeyDeleted → ErrKeyNotFound, so in the common KVStore.Get path only ErrKeyNotFound reaches us. The ErrKeyDeleted branch defends paths that bypass that mapping (Watch handler entry-error chains, GetRevision wrappers, future SDK changes). The mapping is read at nats.go v1.55.0 (jetstream/kv.go:1011-1013), not measured.

The class is read from the error's type, never its text: a refusal's text can name a stored entity, and an ID holding "10037" is not an absence.

func IsKVTombstone

func IsKVTombstone(operation jetstream.KeyValueOp) bool

IsKVTombstone reports whether an authoritative KV watch entry removes the current value. NATS emits both DEL and PURGE tombstones with empty payloads; neither is an entity document and both must drive identical cleanup paths.

func IsNoResponders

func IsNoResponders(err error) bool

IsNoResponders reports whether err is (or wraps) the NATS "no responders" transport error — the responder is not subscribed. The condition is temporary at startup / after a reconnect (retry via a readiness-gated read); its errs class is not promised (ADR-112). It is distinct from a timeout of an EXISTING responder (which signals it is hung — surface, don't retry). On nats-server's default configuration a request with no subscriber gets no responders at once (measured at nats.go v1.55.0, ADR-112; TestIntegration_Request_Timeout asserts the error). Whether another server configuration answers with a plain timeout instead is not promised, so a false here does NOT prove a responder exists — it only confirms the fast-fail no-responders signal when the server sends it.

func OpenFrameworkBucket

func OpenFrameworkBucket(ctx context.Context, c *Client, spec BucketSpec) (jetstream.KeyValue, error)

OpenFrameworkBucket is the READER acquisition seam: bind must-exist. It NEVER creates (a reader that creates is an emitter of divergent configuration) and NEVER reconciles (a reader that "fixes" stream config is the same bug class). An absent bucket yields a classified not-ready error naming the catalog Owner, so the operator reads "wait for / deploy the owner", not "the reader is broken".

func ReconcileNoLifecycleRetention

func ReconcileNoLifecycleRetention(
	ctx context.Context, js jetstream.JetStream, bucket string, logger *slog.Logger,
) error

ReconcileNoLifecycleRetention is the boot-time guard for a framework-owned KV bucket — ADR-068's "no reference-blind lifecycle retention on state the live graph references" invariant, applied to the derived-KV plane. It is the KV analogue of the ObjectStore guard (storage/objectstore/retention.go) and runs TWO steps IN ORDER on the backing stream (KV_<bucket>):

  1. Reconcile (strip-and-log). If the backing stream carries a binding MaxAge/MaxBytes (e.g. a foreign 7-day TTL from a process that won the get-or-create race, or an out-of-band NATS edit), clear it via UpdateStream and emit a WARN naming the bucket and the removed retention. Stripping stops FUTURE time/size eviction and deletes no stored key, so it self-heals existing buckets that a create-or-get path would otherwise never reconcile.

  2. Assert (fail-closed). Re-read the backing stream fresh and run the pure CheckNoLifecycleRetention. If retention is STILL binding (the UpdateStream was denied, or a concurrent writer re-set it), return a wrapped fatal ErrGraphBucketRetention so startup fails closed rather than proceeding to silently expire graph state a day later.

The strip trigger and the final assert share ONE predicate (CheckNoLifecycleRetention) with the ObjectStore guard, so KV and ObjectStore can never diverge on what "binding" means.

func RespondError

func RespondError(msg *nats.Msg, err error) error

RespondError writes a header-classified error reply to msg: the X-Status / X-Error-Class / X-Error-Code headers carry the class + code, and the body is the {message, detail} envelope (ADR-060).

Used by SubscribeForRequests internally + by direct-msg.Respond handlers that opt in to the convention.

Returns nil + no-op when err is nil (treat as success — caller should have used msg.Respond with success data). Returns errMissingReplySubject when the inbound message had no reply subject; caller can ignore (the request was fire-and-forget).

func TerminateDelivery

func TerminateDelivery(err error) error

TerminateDelivery marks err for JetStream Term handling. Transient and cancellation errors must be returned unchanged so their existing NAK paths remain intact.

func ValidateKVLiteralKey

func ValidateKVLiteralKey(key string) error

ValidateKVLiteralKey validates a complete dot-separated literal KV key. It rejects wildcards and empty positions and never changes key identity.

func ValidateKVLiteralToken

func ValidateKVLiteralToken(token string) error

ValidateKVLiteralToken validates one literal NATS KV key position. It never rewrites, normalizes, or encodes the supplied token.

func ValidateKVWildcardFilter

func ValidateKVWildcardFilter(filter string) error

ValidateKVWildcardFilter validates a complete KV search filter. Wildcards are accepted only as a complete '*' token or a complete final '>' token.

Types

type BucketClass

type BucketClass string

BucketClass classifies what kind of state a framework bucket holds. It is descriptive (operator/reviewer-facing); no enforcement derives from it.

const (
	// ClassAuthoritative is canonical domain state (ENTITY_STATES).
	ClassAuthoritative BucketClass = "authoritative"
	// ClassDerived is state rebuilt from authoritative state (the indexes).
	ClassDerived BucketClass = "derived"
	// ClassOperational is framework-internal operational state, including
	// redelivery stamps, readiness envelopes, and storage reports.
	ClassOperational BucketClass = "operational"
	// ClassDiagnostic classifies diagnostic state rather than graph correctness
	// state. No current graph catalog descriptor uses this class.
	ClassDiagnostic BucketClass = "diagnostic"
)

Bucket classes.

type BucketSpec

type BucketSpec struct {
	Name        string
	Owner       string // the component/subsystem that provisions and writes it
	Description string // stamped on the bucket so `nats kv ls` self-describes

	Class     BucketClass
	Retention RetentionPolicy
	Write     WritePolicy
	Posture   CreatePosture

	History  uint8 // KV history depth (stream MaxMsgsPerSubject); 0 = 1
	Replicas int
}

BucketSpec is one framework bucket's full declaration: identity, ownership, policy, and bucket configuration. The framework KV catalog (graph/kvcatalog) is a table of these; every enforcement set the framework uses is a derived view.

func (BucketSpec) Validate

func (s BucketSpec) Validate() error

Validate fails closed on a descriptor this binary cannot enforce. EVERY discriminated field is checked against its explicit allowed arms with a fail-closed default: an unknown RetentionKind (a newer catalog on an older binary) must be an invalid-policy error, never a silently unapplied policy — and an empty or typoed Write policy must never validate, because the derived owned-bucket write guard filters on it and a zero value would silently drop the bucket OUT of the guard set (fail-open in the exact foundation meant to replace review-maintained integrity). Class and Posture get the same treatment: a descriptor grammar that tolerates zero values is a hand list with extra steps.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client manages a NATS connection, its JetStream context and its health status.

func NewClient

func NewClient(urls string, opts ...ClientOption) (*Client, error)

NewClient creates a new NATS client with optional configuration. The urls parameter accepts comma-separated NATS server URLs for clustering support (e.g., "nats://server1:4222,nats://server2:4222").

func (*Client) Close

func (m *Client) Close(ctx context.Context) error

Close drains and closes the NATS connection and waits until everything the client owns has finished: its background goroutines and timer callbacks, every running invocation of a message handler passed to Subscribe, SubscribeForRequests or a Consume method, the async publish error handler, and the connection's event handlers. It returns nil only then. When ctx ends first, or has already ended, Close returns ctx.Err() at once, even while another Close is draining, and the cleanup continues; a later Close waits for the same completion. On a connection the client dialled, an ended ctx also closes the socket and ends a reconnect dial nats.go has in progress, so a write the server is not reading does not hold Close (TestCloseEndsAHeldWrite, TestCloseEndsAReconnectDial); a message still buffered then is not promised to reach the server. Once Close has begun the client starts no new work: background work offered after that is dropped and logged at debug level, and Connect, Subscribe, SubscribeForRequests and the Consume methods return nats.ErrConnectionClosed. Work admitted before Close began may still run while Close waits for it; message handlers keep handling messages already delivered during the drain. Status keeps its value while Close drains and reports Disconnected once the cleanup has finished. After a Close whose context cut the drain short, the native connection GetConnection returned reports CLOSED: nats.go v1.55.0's drain no longer moves a connection closed under it back to DRAINING_PUBS (nats.go:6442-6444, :6471-6480, read, not measured; v1.54.0's did, for up to 5 s). No event handler of the client runs then. A drain that runs out of time is reported by the first Close as a transient error wrapping nats.ErrDrainTimeout. A Close called from inside one of the client's callbacks waits on a join that includes its own invocation, so it returns ctx.Err() when its context ends and never returns nil. Close refuses a nil context with an error and touches nothing.

func (*Client) Connect

func (m *Client) Connect(ctx context.Context) error

Connect establishes connection to NATS server. It refuses a nil context, an ended context and a client that already has a connection installed, with an error and before any dial (TestConnectRefusesAnEndedContext). A connection is installed while it is connected, while nats.go reconnects it, and after nats.go has closed it because a finite WithMaxReconnects ran out (Status then reports Disconnected); that refusal matches errs.ErrAlreadyStarted. A Client connects once; recovery is a new Client. When its context ends during the attempt, it ends the dial, a host name's lookup included, or closes the socket while it waits for the server's answer, and returns a transient error matching the context's error (TestConnectEndsWithItsContext). The context does not bound the connection's later reconnects (TestReconnectAfterConnectContextEnded). Once Close has begun it returns nats.ErrConnectionClosed before dialling, whether or not its context has ended (TestConnectRefusesAnEndedContext). Connect returns an error when Close has begun before it finished; the connection it dialled is then closed and nothing it would have started runs. A Connect that returns an error has no event handler of the connection it dialled still running, and does not change the status of a connection another Connect installed.

func (*Client) ConsumeInternalStreamWithConfig

func (c *Client) ConsumeInternalStreamWithConfig(
	ctx context.Context,
	cfg StreamConsumerConfig,
	handler func(ctx context.Context, msg jetstream.Msg),
) (jetstream.ConsumeContext, error)

ConsumeInternalStreamWithConfig consumes a stream for framework-internal users that make no JetStreamPort configuration claim. The caller owns the exact returned native handle and should Drain it when it is done with it. Closed can report the end early once delivery was stopped without a drain or the connection was force-closed (nats.go jetstream/pull.go:822-837); a nil Client.Close is the proof that no handler invocation is still running. Client.Close stops and joins this consumer if the caller has not. Once Close has begun this method returns nats.ErrConnectionClosed.

As with ConsumeStreamWithConfig, ctx is used for the setup only and is not retained: each handler's context descends from a context the client owns for this consumer, cancelled when Close begins. A write the server is not reading holds the setup, as there (measured at nats.go v1.55.0, ADR-112).

func (*Client) ConsumeStreamWithConfig

func (c *Client) ConsumeStreamWithConfig(
	ctx context.Context,
	owner PortConsumerContext,
	cfg StreamConsumerConfig,
	handler func(ctx context.Context, msg jetstream.Msg),
) (jetstream.ConsumeContext, error)

ConsumeStreamWithConfig creates a port-backed JetStream consumer with full configuration. The caller owns the exact returned native handle and should Drain it when it is done with it. Closed can report the end early once delivery was stopped without a drain or the connection was force-closed (nats.go jetstream/pull.go:822-837); a nil Client.Close is the proof that no handler invocation is still running. Client.Close stops and joins this consumer if the caller has not. Once Close has begun this method returns nats.ErrConnectionClosed. The handler receives the raw jetstream.Msg and must settle it with Ack, Nak, or Term.

ctx is used for the setup only and is not retained. It does not end a wait behind a write the server is not reading: such a write holds the setup until it completes or nats.go's write timeout (one minute by default, WithWriteTimeout) ends it (measured at nats.go v1.55.0, ADR-112). Each handler's context descends from a context the client owns for this consumer: it is cancelled when Close begins, and Close joins every handler invocation. A caller that wants its own parent for the handlers uses ConsumeStreamWithConfigContexts.

func (*Client) ConsumeStreamWithConfigContexts

func (c *Client) ConsumeStreamWithConfigContexts(
	setupCtx context.Context,
	handlerCtx context.Context,
	owner PortConsumerContext,
	cfg StreamConsumerConfig,
	handler func(ctx context.Context, msg jetstream.Msg),
) (jetstream.ConsumeContext, error)

ConsumeStreamWithConfigContexts creates a port-backed JetStream consumer with separate setup and delivered-message authority. The caller owns the exact returned native handle and should Drain it when it is done with it. Closed can report the end early once delivery was stopped without a drain or the connection was force-closed (nats.go jetstream/pull.go:822-837); a nil Client.Close is the proof that no handler invocation is still running. Client.Close stops and joins this consumer if the caller has not. Once Close has begun this method returns nats.ErrConnectionClosed.

setupCtx is used only for the setup and is not retained; as with ConsumeStreamWithConfig, a write the server is not reading holds the setup (measured at nats.go v1.55.0, ADR-112). handlerCtx is the parent of every handler's context for as long as the consumer runs; its end does not stop delivery, it only ends the context each later handler receives.

func (*Client) CreateKeyValueBucket

func (m *Client) CreateKeyValueBucket(ctx context.Context, cfg jetstream.KeyValueConfig) (jetstream.KeyValue, error)

CreateKeyValueBucket creates or gets a KV bucket with configuration

func (*Client) CreateStream

func (m *Client) CreateStream(ctx context.Context, cfg jetstream.StreamConfig) (jetstream.Stream, error)

CreateStream creates a JetStream stream

func (*Client) DeleteKeyValueBucket

func (m *Client) DeleteKeyValueBucket(ctx context.Context, name string) error

DeleteKeyValueBucket deletes a KV bucket

func (*Client) EnsureStream

func (c *Client) EnsureStream(ctx context.Context, cfg jetstream.StreamConfig) (jetstream.Stream, error)

EnsureStream creates a stream if it doesn't exist, or returns the existing one.

func (*Client) GetConnection

func (m *Client) GetConnection() *nats.Conn

GetConnection returns the current NATS connection

func (*Client) GetKeyValueBucket

func (m *Client) GetKeyValueBucket(ctx context.Context, name string) (jetstream.KeyValue, error)

GetKeyValueBucket gets an existing KV bucket

func (*Client) GetStatus

func (m *Client) GetStatus() *Status

GetStatus returns current status information

func (*Client) GetStream

func (m *Client) GetStream(ctx context.Context, name string) (jetstream.Stream, error)

GetStream gets an existing JetStream stream.

Its jetstream.ErrStreamNotFound means "not on this connection, now" — it is a point-in-time probe, not durable evidence of absence. A clustered node that has not applied the meta assignment may also answer it for a stream that exists; that is not measured, since no test here runs a cluster. A caller deciding something for the process lifetime wants ErrStreamNotVisible out of the guarded consumer setup instead; see that sentinel and the package doc.

func (*Client) IsHealthy

func (m *Client) IsHealthy() bool

IsHealthy returns true if the connection is healthy

func (*Client) JetStream

func (m *Client) JetStream() (jetstream.JetStream, error)

JetStream returns the JetStream context

func (*Client) ListKeyValueBuckets

func (m *Client) ListKeyValueBuckets(ctx context.Context) ([]string, error)

ListKeyValueBuckets lists all KV buckets

func (*Client) MaxPayload

func (m *Client) MaxPayload() (int64, error)

MaxPayload observes the maximum payload reported by the active NATS connection. The value is diagnostic and may change after it is returned; callers must treat the result of an actual publish as authoritative.

func (*Client) NewKVStore

func (c *Client) NewKVStore(bucket jetstream.KeyValue, opts ...func(*KVOptions)) *KVStore

NewKVStore creates a new KV store with the given bucket

func (*Client) ObserveDirectPortConsumerPolicy

func (c *Client) ObserveDirectPortConsumerPolicy(
	ctx context.Context,
	owner PortConsumerContext,
	finalConfig jetstream.ConsumerConfig,
	consumer jetstream.Consumer,
) (func(), error)

ObserveDirectPortConsumerPolicy observes an OTEL-owned direct consumer and returns opaque cleanup for its canonical policy record.

func (*Client) Publish

func (m *Client) Publish(ctx context.Context, subject string, data []byte) error

Publish publishes a message to a NATS subject

func (*Client) PublishBatchToStream

func (m *Client) PublishBatchToStream(ctx context.Context, subject string, msgs [][]byte) error

PublishBatchToStream publishes every message in msgs to one subject via the async path, waits for all acks, and returns a single aggregate error. Per-subject ordering from this single calling goroutine is preserved: the async path stores messages in publish order (TestIntegration_PublishToStreamAsync_Ordering); the order after nats.go retries a publish that met no responders is not promised. It is the convenience path for bursty producers that do not need per-message futures.

ctx does not end a wait behind a write the server is not reading: each publish is written under nats.go's connection lock, so such a write holds the batch until it completes or nats.go's write timeout (one minute by default, WithWriteTimeout) ends it (measured at nats.go v1.55.0, ADR-112).

The drain waits on THIS batch's own futures, not the JetStream context's connection-global PublishAsyncComplete, so a concurrent async producer on the same Client cannot make this batch over-wait. If ctx is cancelled before all acks arrive, it returns the context error rather than hanging (TestIntegration_PublishBatchToStream_CtxCancel); the already-enqueued publishes still resolve in the background, and a failed ack is still counted by the async error handler. An enqueue error stops further enqueuing but already-enqueued messages are still drained. Ack failures are accounted once by asyncPublishErrHandler — this loop only collects them for the returned error (accounting here too would double-count).

func (*Client) PublishToStream

func (m *Client) PublishToStream(ctx context.Context, subject string, data []byte) error

PublishToStream publishes to a JetStream stream with automatic trace context propagation. If no trace context exists in ctx, one is auto-generated for distributed tracing.

func (*Client) PublishToStreamWithAck

func (c *Client) PublishToStreamWithAck(
	ctx context.Context,
	subject string,
	data []byte,
) (*jetstream.PubAck, error)

PublishToStreamWithAck publishes a message to a JetStream subject with acknowledgment. Trace context is auto-generated if not present, and propagated via NATS message headers. A failure of the publish itself is counted as publish_to_stream and classified transient; ErrNotConnected and a JetStream error come back unchanged.

func (*Client) PublishToStreamWithMsgID

func (m *Client) PublishToStreamWithMsgID(ctx context.Context, subject string, data []byte, msgID string) error

PublishToStreamWithMsgID publishes to a JetStream stream stamping the Nats-Msg-Id header so the server's duplicate-detection window collapses re-publishes/redeliveries of the same logical event to a single store.

This is the producer half of the at-least-once idempotency contract (ADR-055): graph-ingest's stream consumer is at-least-once and MergeEntity APPENDS triples on merge, so a redelivered born-once entity payload would double-apply its triples without dedup. Callers pass a DETERMINISTIC msgID for the logical event (e.g. "<loopID>:spawn", "<entityID>:v<n>") so a retry/redelivery carries the same ID.

Scope of the guarantee: dedup only holds WITHIN the stream's configured duplicate window (config.StreamConfig.Duplicates; the NATS server default is 2m when unset: server/stream.go:1903 at nats-server v2.15.2, read, not measured). Redelivery outside that window — e.g. DeliverPolicy:all replay on consumer recreation — can still re-append. An empty msgID is equivalent to PublishToStream (no dedup), so this is a safe drop-in.

func (*Client) RTT

func (m *Client) RTT() (time.Duration, error)

RTT returns the round-trip time to the NATS server

func (*Client) Reply

func (c *Client) Reply(ctx context.Context, replyTo string, data []byte) error

Reply sends a reply to a request message. This is typically used by service handlers to respond to requests.

func (*Client) ReplyWithHeaders

func (c *Client) ReplyWithHeaders(ctx context.Context, replyTo string, data []byte, headers map[string]string) error

ReplyWithHeaders sends a reply with custom headers.

func (*Client) RequestClassified

func (c *Client) RequestClassified(ctx context.Context, subject string, data []byte, timeout time.Duration) ([]byte, error)

RequestClassified performs the request through RequestWithHeaders, with no headers, then runs the reply through ClassifyReply so the returned error covers both transport and handler failure modes uniformly.

Transport failures are returned as the underlying error. A timeout returns context.DeadlineExceeded, which classifies as ErrorTransient via pkg/errs.IsTransient (measured at nats.go v1.55.0, ADR-112). No responders returns nats.ErrNoResponders, matched by errors.Is or IsNoResponders; its class is not promised (ADR-112). Classification does not authorize a retry; the operation's contract owns that decision.

Handler failures arrive as a *errs.ClassifiedError reconstructed from the X-Error-Class / X-Error-Code headers + {message, detail} body. Caller branches on errs.IsInvalid / IsTransient / IsFatal.

Use this for steady-state queries and canonical graph mutations. Graph create, reconcile, append, and delete always make one transport attempt; ambiguity is returned to the component. Use RequestWithRetryClassified only for a non-graph operation whose contract explicitly authorizes redelivery.

func (*Client) RequestReadyClassified

func (c *Client) RequestReadyClassified(
	ctx context.Context, subject string, data []byte, probeTimeout, budget time.Duration,
) ([]byte, error)

RequestReadyClassified is the readiness-gated read (the third bucket of the request doctrine). It runs the short-timeout, budget-bounded readiness loop, then runs the final reply through ClassifyReply so transport failures (no-responders / probe timeout, retried until the budget) and handler failures (X-Error-Class/Code headers) arrive uniformly.

Use for the FIRST read on boot / initial reconcile / after a reconnect, where a not-yet-subscribed responder must not degrade to a full-query-timeout hang. For steady-state reads use RequestClassified (timeout = real signal).

func (*Client) RequestWithHeaders

func (c *Client) RequestWithHeaders(
	ctx context.Context,
	subject string,
	data []byte,
	headers map[string]string,
	timeout time.Duration,
) (*nats.Msg, error)

RequestWithHeaders performs a request/reply operation with custom headers, converted from the map to NATS message headers. It returns the reply message as received, headers included, and does not classify it: a SubscribeForRequests handler's error arrives as a reply whose X-Status header is "error", with a nil error, not as err. Callers run ClassifyReply on the reply; a caller that sends no headers uses RequestClassified, which does both.

func (*Client) RequestWithRetryClassified

func (c *Client) RequestWithRetryClassified(
	ctx context.Context,
	subject string,
	data []byte,
	timeout time.Duration,
	cfg retry.Config,
) ([]byte, error)

RequestWithRetryClassified is the retrying sibling of RequestClassified. It makes its attempts through retry.Do with cfg: MaxAttempts counts every attempt, a count below one makes one attempt, and a config retry.Do refuses is returned before anything is sent (its error class is not promised). Only an attempt that got no reply is retried. A reply of any kind, an error reply included, ends the call, and ClassifyReply runs once on it, so a handler error is never retried.

Use this only where an operation-specific contract explicitly authorizes redelivery after transport ambiguity. Handler failures arrive as for RequestClassified: a *errs.ClassifiedError reconstructed from the X-Error-Class / X-Error-Code headers + {message, detail} body. After the last failed attempt the transport error arrives wrapped by retry.Do and still matches with errors.Is: a timeout matches context.DeadlineExceeded (transient by pkg/errs.IsTransient, measured at nats.go v1.55.0, ADR-112), no responders matches nats.ErrNoResponders (IsNoResponders; class not promised, ADR-112). A caller's cancellation, before or during an attempt, matches context.Canceled and is transient.

Canonical graph mutations and steady-state queries use RequestClassified. Retrying graph mutations can duplicate effects after a lost reply; retrying a hung query masks responder problems as latency.

func (*Client) Status

func (m *Client) Status() ConnectionStatus

Status returns the current connection status

func (*Client) Subscribe

func (m *Client) Subscribe(ctx context.Context, subject string, handler func(context.Context, *nats.Msg)) (*Subscription, error)

Subscribe subscribes to a NATS subject with context propagation. Each message handler receives the full *nats.Msg to access Subject, Data, Headers, etc. This is essential for wildcard subscriptions where the actual subject differs from the pattern. Returns a Subscription handle that can be used to unsubscribe. Once Close has begun it returns nats.ErrConnectionClosed and subscribes nothing. Close joins every running invocation of handler.

When Subscribe returns a subscription, the server has read its SUB: Subscribe sends a PING on the connection it subscribed on and waits for the PONG, which the server sends once it has read the SUB, so a message or request sent to that server from any connection after the call returns finds the subscription, unless the server refused the SUB (for permissions, or for the connection's limit on subscriptions). A refused SUB is not reported here: Subscribe returns the subscription and nil, and a client that connected with Connect logs the refusal at error level. The wait for the PONG ends when the server answers, when ctx ends, or when DefaultRequestTimeout has passed, whichever comes first. ctx does not end a wait for the connection itself: while the server is not reading and the connection's send buffer is full, Subscribe, like every call that writes on the connection, waits for each held write on the connection, its own or another goroutine's, until that write completes or nats.go's write timeout (one minute by default) ends it, so it can be held a minute or more. If ctx has already ended, Subscribe sends no SUB and returns a transient error matching ctx's error. Nothing here says when a responder in another component has subscribed, or what holds after a reconnect or across the servers of a cluster.

When the wait does not complete, or Close has begun when it ends, Subscribe ends the subscription (it unsubscribes it, so it is not restored on a reconnect; on a connection Close is draining or has closed, Close ends it) and returns no subscription and the first of these errors that holds:

  • nats.ErrConnectionClosed, if Close has begun;
  • a transient error matching context.Canceled or context.DeadlineExceeded, if ctx ended or DefaultRequestTimeout passed;
  • a transient error matching ErrNotConnected, and not nats.ErrConnectionClosed, if the connection was lost or closed by anything but Close.

It does not wait for a running invocation of handler; Close joins that invocation.

ctx is used for the setup only (the subscribe and the round trip above) and is not retained. Each handler invocation's context descends from a context the client owns for this subscription, not from ctx: ending ctx after the call returned does not end a handler. The client cancels that context after Close has begun, also after Unsubscribe while a handler still runs, and once delivery has ended and the last invocation has returned. A handler's context also ends when its 30-second processing timeout passes, and carries the trace from the message's headers when it has one, and no value of ctx. Unsubscribe stops delivery but does not wait for a running handler; Subscription.Drain returning nil is what proves every handler has returned.

func (*Client) SubscribeForRequests

func (c *Client) SubscribeForRequests(
	ctx context.Context,
	subject string,
	handler func(ctx context.Context, data []byte) ([]byte, error),
) (*Subscription, error)

SubscribeForRequests subscribes to a subject and handles request/reply patterns. The handler receives the message data and reply subject, and should return the response data or an error. Returns the Subscription so the caller can unsubscribe when done. This is a convenience method for implementing request/reply services. Once Close has begun it returns nats.ErrConnectionClosed and subscribes nothing. Close joins every running invocation of handler.

When SubscribeForRequests returns a subscription, the server has read its SUB: the call sends a PING on the connection it subscribed on and waits for the PONG, which the server sends once it has read the SUB, so a request sent to that server from any connection after the call returns finds the handler, unless the server refused the SUB (for permissions, or for the connection's limit on subscriptions). A refused SUB is not reported here: the call returns the subscription and nil, and a client that connected with Connect logs the refusal at error level. The wait for the PONG ends when the server answers, when ctx ends, or when DefaultRequestTimeout has passed, whichever comes first. ctx does not end a wait for the connection itself: while the server is not reading and the connection's send buffer is full, the call, like every call that writes on the connection, waits for each held write on the connection, its own or another goroutine's, until that write completes or nats.go's write timeout (one minute by default) ends it, so it can be held a minute or more. If ctx has already ended, the call sends no SUB and returns a transient error matching ctx's error. Nothing here says when a responder in another component has subscribed, or what holds after a reconnect or across the servers of a cluster.

When the wait does not complete, or Close has begun when it ends, the call ends the subscription (it unsubscribes it, so it is not restored on a reconnect; on a connection Close is draining or has closed, Close ends it) and returns no subscription and the first of these errors that holds:

  • nats.ErrConnectionClosed, if Close has begun;
  • a transient error matching context.Canceled or context.DeadlineExceeded, if ctx ended or DefaultRequestTimeout passed;
  • a transient error matching ErrNotConnected, and not nats.ErrConnectionClosed, if the connection was lost or closed by anything but Close.

It does not wait for a running invocation of handler; Close joins that invocation.

ctx is used for the setup only (the subscribe and the round trip above) and is not retained. Each handler invocation's context descends from a context the client owns for this subscription, not from ctx: ending ctx after the call returned does not end a handler. The client cancels that context after Close has begun, also after Unsubscribe while a handler still runs, and once delivery has ended and the last invocation has returned. A handler's context also ends when the per-request handler timeout passes, and carries the trace from the request's headers when it has one, and no value of ctx. Unsubscribe stops delivery but does not wait for a running handler; Subscription.Drain returning nil is what proves every handler has returned.

func (*Client) URLs

func (m *Client) URLs() string

URLs returns the NATS server URLs (comma-separated for clustering)

func (*Client) WaitConsumerHandlers

func (c *Client) WaitConsumerHandlers(ctx context.Context, handle jetstream.ConsumeContext) error

WaitConsumerHandlers waits until delivery on the consumer whose handle this client returned from ConsumeStreamWithConfig, ConsumeStreamWithConfigContexts or ConsumeInternalStreamWithConfig has ended, every handler invocation of it has returned and its durable claim is released, so a consumer with the same durable can start on this client. From then on no handler of it starts; a later delivery is refused, logged and counted.

It waits and stops nothing: ending delivery stays the caller's (Drain or Stop on its handle) or Close's. The handle's Closed() is not this wait: it can close while a handler still runs (jetstream/pull.go:855-870 at nats.go v1.55.0). How long delivery takes to end after a Drain is not promised.

If ctx ends first it returns an error matching ctx.Err() and changes nothing; a later call waits again. A handle stays known for the client's life, so a call after its handlers finished, or after Close returned nil, returns nil at once. A nil ctx, and a handle this client did not return (nil, another client's, a value nats.go never made), are refused at once as invalid input. It never closes, drains or reconnects the client.

func (*Client) WaitForBucket

func (m *Client) WaitForBucket(ctx context.Context, name string, timeout time.Duration) (jetstream.KeyValue, error)

WaitForBucket waits for a KV bucket to become available, retrying until the timeout expires or the context is cancelled. Neither ends a wait behind a write the server is not reading: each attempt is a JetStream request, and such a write holds it until the write completes or nats.go's write timeout (one minute by default, WithWriteTimeout) ends it (measured at nats.go v1.55.0, ADR-112). Use this when a component depends on a bucket created by another component with unpredictable startup timing.

For more advanced patterns (background recovery, loss detection), use pkg/resource.Watcher directly.

func (*Client) WaitForConnection

func (m *Client) WaitForConnection(ctx context.Context) error

WaitForConnection waits for the connection to be established

type ClientOption

type ClientOption func(*Client) error

ClientOption is a functional option for configuring the Client

func WithConnectionLossTimeout

func WithConnectionLossTimeout(grace time.Duration) ClientOption

WithConnectionLossTimeout configures how long the client tolerates a continuous broker outage before the connection-lost callback fires.

When set together with WithConnectionLostCallback, a timer arms on the first disconnect; if the connection has not recovered within grace, the callback runs once with the original disconnect error. A reconnect before the deadline cancels the timer. A non-positive grace disables the watchdog (the default — onConnectionLost never fires automatically).

The callback only signals — it does not call os.Exit or otherwise act on the client. Callers decide the policy (graceful shutdown, alerting, degraded-mode flag, etc.).

func WithConnectionLostCallback

func WithConnectionLostCallback(fn func(error)) ClientOption

WithConnectionLostCallback sets a callback for when connection is completely lost

func WithCredentials

func WithCredentials(username, password string) ClientOption

WithCredentials sets username and password for authentication

func WithHealthInterval

func WithHealthInterval(d time.Duration) ClientOption

WithHealthInterval sets the interval for health monitoring

func WithLogger

func WithLogger(logger *slog.Logger) ClientOption

WithLogger sets a structured logger for the client. If nil, defaults to slog.Default().

func WithMaxReconnects

func WithMaxReconnects(maxN int) ClientOption

WithMaxReconnects sets the maximum number of reconnection attempts (-1 for infinite)

func WithMetrics

func WithMetrics(registry *metric.MetricsRegistry) ClientOption

WithMetrics enables JetStream metrics collection using the provided registry. Metrics will track streams and consumers created through this client.

Give each client its own registry. A registry holds one client's JetStream series: its stream and consumer gauges are set from what that client reads from the server. A second client on the same registry writes the same collectors, so the two overwrite each other's gauges, and which client's value a scrape shows is not promised. No configuration we know of runs two clients on one registry.

func WithName

func WithName(name string) ClientOption

WithName sets the client name for identification

func WithPingInterval

func WithPingInterval(d time.Duration) ClientOption

WithPingInterval sets how often nats.go sends the server a PING (nats.PingInterval). The default is 30 s. When PINGs go unanswered, nats.go finds the connection stale, closes it and reconnects: at 300 ms that took 1.2 s at nats.go v1.54.0 and 0.9 s at v1.55.0 (measured, ADR-112); the timing at other values is not promised.

While a write is held this check does not fire (measured at nats.go v1.55.0, ADR-112), so only the write timeout ends that write. d must be positive: NewClient refuses any other value as invalid (TestWriteTimeoutAndPingIntervalOptions).

func WithReconnectWait

func WithReconnectWait(d time.Duration) ClientOption

WithReconnectWait sets the wait time between reconnection attempts

func WithTimeout

func WithTimeout(d time.Duration) ClientOption

WithTimeout sets the connection timeout

func WithWriteTimeout

func WithWriteTimeout(d time.Duration) ClientOption

WithWriteTimeout sets how long one write may wait for the server to read it before nats.go fails the write (nats.FlusherTimeout). One deadline covers a whole flush, so at 10 s a 1 MB message needs about 100 KB/s. The default is nats.go's, one minute. Other calls on the connection wait behind a held write (measured at nats.go v1.55.0, ADR-112).

At nats.go v1.55.0 a write the timeout ends partway closes the socket, and nats.go reconnects (measured, ADR-112). How soon the connection carries messages again is not promised. d must be positive: NewClient refuses any other value as invalid (TestWriteTimeoutAndPingIntervalOptions).

type ConnectionStatus

type ConnectionStatus int

ConnectionStatus represents the state of the NATS connection

const (
	StatusDisconnected ConnectionStatus = iota
	StatusConnecting
	StatusConnected
	StatusReconnecting
)

Possible connection statuses

func (ConnectionStatus) String

func (s ConnectionStatus) String() string

String returns the string representation of ConnectionStatus

type CreatePosture

type CreatePosture string

CreatePosture declares how a bucket comes into existence.

const (
	// PostureOwnerCreates: the declared owner provisions the bucket through
	// EnsureFrameworkBucket; readers must-exist via OpenFrameworkBucket.
	PostureOwnerCreates CreatePosture = "owner-creates"
	// PostureReaderMustExist: no in-process owner provisions it; every binding
	// is must-exist. No shipped descriptor uses this posture today — it exists
	// because the catalog grammar declares both arms.
	PostureReaderMustExist CreatePosture = "reader-must-exist"
)

Create postures.

type DeliveryDecision

type DeliveryDecision uint8

DeliveryDecision is the owner-supplied semantic outcome for one delivery.

const (
	// DeliveryDecisionInvalid is the zero and invalid decision.
	DeliveryDecisionInvalid DeliveryDecision = iota
	// DeliveryDecisionAck declares that the owner-defined durable consequence completed.
	DeliveryDecisionAck
	// DeliveryDecisionRetry declares a repairable semantic failure.
	DeliveryDecisionRetry
	// DeliveryDecisionTerminate declares immutable poison for this delivery.
	DeliveryDecisionTerminate
	// DeliveryDecisionQuarantine declares that retry and termination are not proven safe.
	DeliveryDecisionQuarantine
)

type DeliveryMetadataUnavailableError

type DeliveryMetadataUnavailableError struct {
	// contains filtered or unexported fields
}

DeliveryMetadataUnavailableError identifies missing or invalid server delivery metadata. The stable token allows callers to classify the failure while Unwrap preserves the transport or validation cause.

func (*DeliveryMetadataUnavailableError) Error

func (*DeliveryMetadataUnavailableError) Unwrap

type DeliveryResult

type DeliveryResult struct {
	// contains filtered or unexported fields
}

DeliveryResult is the immutable semantic and local transport observation produced by ConsumeDeliveryWithHeartbeat. It exposes no server-confirmation affordance: this contract uses plain Ack/Nak/NakWithDelay/Term, whose nil return proves the local call only, so there is nothing a caller could read that would mean the server settled the delivery.

func ConsumeDeliveryWithHeartbeat

func ConsumeDeliveryWithHeartbeat(
	ctx context.Context,
	msg jetstream.Msg,
	policy HeartbeatDeliveryPolicy,
) DeliveryResult

ConsumeDeliveryWithHeartbeat validates server delivery metadata, runs setup-validated work, renews the delivery lease, joins work on cancellation or control loss, and attempts at most one local terminal method. It owns no consumer lifecycle or restart state.

func SettleDelivery

func SettleDelivery(msg jetstream.Msg, decision DeliveryDecision, cause error) DeliveryResult

SettleDelivery validates one joined semantic outcome and attempts at most one immediate terminal method. It owns no work or delivery lifecycle.

Retry here is a bare Nak, which asks for no delay; JetStream redelivers the message (TestIntegrationSemanticRetryProducesDurableRedelivery), and how soon is not promised. That is right only for a lane whose Retry is rare and whose consumer bounds the attempts. A lane that classifies ordinary transient errors as Retry wants SettleDeliveryWithRetry instead.

func SettleDeliveryWithRetry

func SettleDeliveryWithRetry(
	msg jetstream.Msg,
	retry DeliveryRetryPolicy,
	decision DeliveryDecision,
	cause error,
) DeliveryResult

SettleDeliveryWithRetry is SettleDelivery with the Retry policy supplied by the caller rather than fixed at immediate. Every other rule is identical: it validates the closed decision/error tuple, attempts at most one terminal method, and owns no work, context, heartbeat, or consumer lifecycle.

The typed heartbeat owner already takes its retry policy this way; a settlement-only lane has exactly the same need — a Retry that means "not yet" should not spin at line rate — and had no way to say it.

func (DeliveryResult) Cause

func (r DeliveryResult) Cause() error

Cause returns the semantic or decision-validation cause.

func (DeliveryResult) Decision

func (r DeliveryResult) Decision() DeliveryDecision

Decision returns the exact decision requested by joined work.

func (DeliveryResult) Err

func (r DeliveryResult) Err() error

Err aggregates the semantic, heartbeat-control, and local settlement evidence. Only a clean local Ack returns nil.

func (DeliveryResult) OwnerStopRequired

func (r DeliveryResult) OwnerStopRequired() bool

OwnerStopRequired reports that the exact delivery owner must stop its lane.

func (DeliveryResult) Quarantined

func (r DeliveryResult) Quarantined() bool

Quarantined reports that no terminal method was safe to attempt.

func (DeliveryResult) SettlementMethodFailed

func (r DeliveryResult) SettlementMethodFailed() bool

SettlementMethodFailed reports local method return failure only.

type DeliveryRetryPolicy

type DeliveryRetryPolicy struct {
	// contains filtered or unexported fields
}

DeliveryRetryPolicy is the opaque explicit-Nak policy for semantic Retry. It is independent of consumer AckWait and BackOff.

func DelayedDeliveryRetry

func DelayedDeliveryRetry(delay time.Duration) (DeliveryRetryPolicy, error)

DelayedDeliveryRetry selects NakWithDelay for a semantic Retry decision.

func ImmediateDeliveryRetry

func ImmediateDeliveryRetry() DeliveryRetryPolicy

ImmediateDeliveryRetry selects plain Nak for a semantic Retry decision.

type DeliveryWork

type DeliveryWork func(context.Context, []byte) (DeliveryDecision, error)

DeliveryWork performs one delivery's owner-defined work and returns its semantic decision followed by the cause required by that decision. Data is read-only and invocation-scoped; work must not retain or mutate it.

type DeliveryWorkPanicError

type DeliveryWorkPanicError struct {
	// contains filtered or unexported fields
}

DeliveryWorkPanicError identifies a panic recovered from DeliveryWork. The panic is converted to an error so callers can observe the quarantined cause.

func (*DeliveryWorkPanicError) Error

func (e *DeliveryWorkPanicError) Error() string

func (*DeliveryWorkPanicError) Unwrap

func (e *DeliveryWorkPanicError) Unwrap() error

type HeartbeatDeliveryPolicy

type HeartbeatDeliveryPolicy struct {
	// contains filtered or unexported fields
}

HeartbeatDeliveryPolicy is an immutable, setup-validated policy for one typed heartbeat delivery. It retains no context or lifecycle authority.

func ValidateHeartbeatDeliveryPolicy

func ValidateHeartbeatDeliveryPolicy(
	ctx context.Context,
	cfg StreamConsumerConfig,
	heartbeat time.Duration,
	retry DeliveryRetryPolicy,
	work DeliveryWork,
) (HeartbeatDeliveryPolicy, error)

ValidateHeartbeatDeliveryPolicy validates one delivery policy before the caller acquires its consumer. cfg must be the same value used for acquisition.

ctx is a setup-time precondition only: it is checked for nil and for an already-ended deadline so a policy cannot be built for a lifecycle that has gone away. It confers no lifecycle authority, is not retained by the returned policy, and does not govern any delivery — per-delivery context comes from the consume callback passed to ConsumeDeliveryWithHeartbeat.

type InvalidDeliveryDecisionError

type InvalidDeliveryDecisionError struct {
	// contains filtered or unexported fields
}

InvalidDeliveryDecisionError identifies a decision/error tuple that does not satisfy the closed DeliveryWork contract.

func (*InvalidDeliveryDecisionError) Error

func (*InvalidDeliveryDecisionError) Unwrap

func (e *InvalidDeliveryDecisionError) Unwrap() error

type KVEntry

type KVEntry struct {
	Key      string
	Value    []byte
	Revision uint64
}

KVEntry wraps a KV entry with its revision for CAS operations

type KVOptions

type KVOptions struct {
	MaxRetries            int           // Maximum CAS retry attempts
	RetryDelay            time.Duration // Initial delay between retries
	Timeout               time.Duration // Ends the wait for the server's answer, not a held write (measured at nats.go v1.55.0, ADR-112)
	MaxValueSize          int           // Maximum size for values (default: 1MB)
	UseExponentialBackoff bool          // Enable exponential backoff with jitter
	MaxRetryDelay         time.Duration // Maximum delay between retries
}

KVOptions configures KV operations behavior

func DefaultKVOptions

func DefaultKVOptions() KVOptions

DefaultKVOptions returns sensible defaults matching Graph processor

type KVStore

type KVStore struct {
	// contains filtered or unexported fields
}

KVStore provides high-level KV operations with built-in CAS support

func (*KVStore) AssertNoLifecycleRetention

func (kv *KVStore) AssertNoLifecycleRetention(ctx context.Context, name string) error

AssertNoLifecycleRetention reads this bucket's retention config and returns ErrGraphBucketRetention if it is binding — the boot-time guardrail for a live graph bucket (ADR-068) and for the shared configuration bucket that holds the create-once platform identity (ADR-102). A retention config here means some process won the get-or-create race with a TTL/size cap; fail-closed rather than silently expire state that cannot be regenerated.

func (*KVStore) Create

func (kv *KVStore) Create(ctx context.Context, key string, value []byte) (uint64, error)

Create only creates if key doesn't exist (returns error if exists)

func (*KVStore) Delete

func (kv *KVStore) Delete(ctx context.Context, key string) error

Delete removes a key from the bucket

func (*KVStore) DeleteAtRevision

func (kv *KVStore) DeleteAtRevision(ctx context.Context, key string, revision uint64) error

DeleteAtRevision removes a key only when revision is still current. It makes one revision-fenced delete attempt and never reads or retries.

func (*KVStore) Get

func (kv *KVStore) Get(ctx context.Context, key string) (*KVEntry, error)

Get retrieves a value with its revision for CAS operations

func (*KVStore) Keys

func (kv *KVStore) Keys(ctx context.Context) ([]string, error)

Keys returns every key in the bucket, sorted, each once, or no keys and an error. It applies the store's operation timeout, then lists the filter ">" as keysByFilter does, so a listing cut short is an error, never a partial list. An empty bucket gives nil and no error.

func (*KVStore) KeysByFilter

func (kv *KVStore) KeysByFilter(ctx context.Context, pattern string) ([]string, error)

KeysByFilter returns all keys matching an exact NATS subject filter. Unlike KeysByPrefix, this supports fixed-position wildcards such as "*.org.platform.system.domain.type.instance" (ADR-102 canonical order). It applies the store's operation timeout, then lists as keysByFilter does.

func (*KVStore) KeysByPrefix

func (kv *KVStore) KeysByPrefix(ctx context.Context, prefix string) ([]string, error)

KeysByPrefix returns all keys matching the given prefix. Uses JetStream KV's native key filtering (TestKVStore_KeysByPrefix). The prefix is automatically converted to a NATS wildcard pattern (prefix + ">").

func (*KVStore) Put

func (kv *KVStore) Put(ctx context.Context, key string, value []byte) (uint64, error)

Put creates or updates a key without revision check (last writer wins)

func (*KVStore) Update

func (kv *KVStore) Update(ctx context.Context, key string, value []byte, revision uint64) (uint64, error)

Update performs CAS update with explicit revision

func (*KVStore) UpdateJSON

func (kv *KVStore) UpdateJSON(ctx context.Context, key string,
	updateFn func(current map[string]any) error) error

UpdateJSON performs CAS update on JSON data with automatic retry

func (*KVStore) UpdateWithRetry

func (kv *KVStore) UpdateWithRetry(ctx context.Context, key string,
	updateFn func(current []byte) ([]byte, error)) error

UpdateWithRetry performs CAS update with automatic retry on conflicts If the key doesn't exist, it creates it.

Use UpdateWithRetryRev when the caller must ATTRIBUTE the write to itself: this variant discards the committed revision, and re-reading it afterwards is not equivalent — another writer can commit in between, and the re-read then returns that writer's revision.

func (*KVStore) UpdateWithRetryRead

func (kv *KVStore) UpdateWithRetryRead(ctx context.Context, key string,
	updateFn func(current []byte, revision uint64) ([]byte, error)) (uint64, error)

UpdateWithRetryRead is UpdateWithRetryRev whose callback also gets the revision it read.

revision is the revision of current, or 0 when the key is absent (never written, deleted or purged); no commit is revision 0. A callback error that errors.Is matches to ErrKVSkipWrite ends the call after that run: nothing is written, the value returned beside it is ignored, and the call returns (0, nil). Everything else is as UpdateWithRetryRev documents.

func (*KVStore) UpdateWithRetryRev

func (kv *KVStore) UpdateWithRetryRev(ctx context.Context, key string,
	updateFn func(current []byte) ([]byte, error)) (uint64, error)

UpdateWithRetryRev is UpdateWithRetry that also returns the EXACT KV revision the committed write produced.

This exists because a post-hoc `Get` is not a substitute. Between the CAS and the re-read, another writer can commit; the re-read then reports THAT writer's revision, and any caller that attributes the reported revision to its own write is now holding someone else's. The rule engine's per-rule feedback-loop tracker does exactly that attribution, and `shouldSkipRule` consumes the recorded revision once and returns true — so a mis-attributed revision makes the rule silently DROP the external writer's genuine change.

Note this is a strictly different safety property from the readiness consumer's `IndexedRevision >= myRev` check, which tolerates over-reporting because revisions are monotonic. Two consumers, two properties; do not generalize from the tolerant one.

On any non-nil error, and on a callback's ErrKVSkipWrite, the returned revision is 0 — the call attributes no commit to itself. That does not mean nothing committed: a write that returns an error may have committed. So the callback runs again only after a failed read, a revision conflict, or jetstream.ErrNoStreamResponse (no stream received the write); any other write error ends the call, errors.Is reaching it.

func (*KVStore) Watch

func (kv *KVStore) Watch(ctx context.Context, pattern string) (jetstream.KeyWatcher, error)

Watch creates a watcher for key changes Note: Watch does not apply timeout as it creates a long-lived watcher

type PermanentDeliveryError

type PermanentDeliveryError struct {
	// contains filtered or unexported fields
}

PermanentDeliveryError marks a handler failure as structurally permanent for this exact message: a binding maps it to DeliveryDecisionTerminate rather than retrying a message no redelivery can fix. Unwrap preserves the handler's typed error contract.

func (*PermanentDeliveryError) Error

func (e *PermanentDeliveryError) Error() string

func (*PermanentDeliveryError) Unwrap

func (e *PermanentDeliveryError) Unwrap() error

type PortConsumerContext

type PortConsumerContext struct {
	Component      string
	Port           string
	ComponentOwned bool
}

PortConsumerContext identifies the component port that owns a consumer. Stream, consumer, and policy values are derived from the final configuration and NATS.

type ResourceKind

type ResourceKind string

ResourceKind classifies a physical JetStream stream name by the reserved backing-stream namespace it occupies. It is the naming convention read two ways: the provisioning guard refuses everything that is not an ordinary stream, and the storage inventory reports every kind.

const (
	// ResourceOrdinaryStream is a stream a component provisions to carry
	// time-shaped events — the only kind stream provisioning governs.
	ResourceOrdinaryStream ResourceKind = "stream"
	// ResourceKeyValue is a KV bucket's backing stream (KVStreamPrefix).
	ResourceKeyValue ResourceKind = "kv"
	// ResourceObjectStore is an ObjectStore's backing stream
	// (ObjectStoreStreamPrefix).
	ResourceObjectStore ResourceKind = "objectstore"
)

Resource kinds.

func ClassifyBackingStream

func ClassifyBackingStream(stream string) (ResourceKind, string)

ClassifyBackingStream maps a physical JetStream stream name to the logical resource it backs: the kind, and for a backing stream the bucket name behind it (empty for an ordinary stream, which has no bucket).

EXACTLY ONE leading prefix is stripped. A product bucket may legitimately be named "KV_FOO", whose backing stream is then "KV_KV_FOO" and whose real name is "KV_FOO" — not "FOO". Stripping greedily would attribute that resource to a different bucket entirely, which is why the recovery lives here, once, and is read by both the provisioning guard's diagnostic and the inventory's owner attribution: the two can disagree about a bucket's name only if they compute it separately, so they do not.

The rule is the prefix and nothing else — no catalog lookup, no membership test — so a product or sister-repo bucket outside the framework catalog classifies identically to a framework one.

type RetentionKind

type RetentionKind string

RetentionKind discriminates a bucket's declared retention policy. Every switch over it MUST carry a default arm that fails closed: a Kind this binary does not know (a newer catalog on an older binary) is an invalid policy, never a silent no-op.

const (
	// RetentionNoLifecycle: no NATS TTL (MaxAge) or binding MaxBytes, ever —
	// correctness-critical no-eviction state (ADR-068). Acquisition strips a
	// foreign retention in place or fails closed.
	RetentionNoLifecycle RetentionKind = "no-lifecycle"
	// RetentionBoundedTTL: the declared TTL IS the contract. Acquisition
	// converges MaxAge TO the declared TTL — preserved, never stripped.
	RetentionBoundedTTL RetentionKind = "bounded-ttl"
	// RetentionNoLifecycleStrict is RetentionNoLifecycle with the repair
	// removed: acquisition VERIFIES that no TTL or binding MaxBytes is in force
	// and fails closed if one is, never stripping it in place.
	//
	// The distinction is not fussiness. Stripping a TTL repairs the POLICY
	// while saying nothing about the keys it already deleted, and for
	// create-once state that is the worse outcome: the shared configuration
	// bucket's platform identity may already have expired, so a silent repair
	// hands the next boot an empty bucket to mint a SECOND authority into —
	// exactly the remint ADR-104 exists to prevent, and one ADR-102 forbids
	// ever reconciling. Refusing makes the operator provision storage
	// the identity can actually survive in.
	RetentionNoLifecycleStrict RetentionKind = "no-lifecycle-strict"
	// RetentionUnmanaged means acquisition does not reconcile retention. No
	// current graph catalog descriptor uses this kind.
	RetentionUnmanaged RetentionKind = "unmanaged"
)

Retention kinds. Current graph catalog rows use no-lifecycle; bounded-ttl and unmanaged remain validated grammar arms outside that population. Adding a future kind (e.g. bounded-storage's DiscardNew ceiling) requires a new constant, RetentionPolicy parameters, and a reconcile arm.

type RetentionPolicy

type RetentionPolicy struct {
	Kind RetentionKind
	// TTL is the declared bucket TTL. Meaningful (and required non-zero) for
	// RetentionBoundedTTL only.
	TTL time.Duration
}

RetentionPolicy is a discriminated Kind plus its parameters — a struct, not a bare enum, so a future kind adds params without reshaping every consumer.

type Status

type Status struct {
	Status ConnectionStatus
	RTT    time.Duration
}

Status holds runtime status information for the NATS manager

type StreamAutoCreateConfig

type StreamAutoCreateConfig struct {
	// Subjects for the stream. If empty, derived from FilterSubject.
	Subjects []string

	// Storage type: "file" (default) or "memory"
	Storage string

	// Retention policy: "limits" (default), "interest", "work_queue"
	Retention string

	// MaxAge is the maximum age of messages. REQUIRED and must be positive:
	// auto-create is stream provisioning, and an ordinary stream declares finite
	// bounds (see CheckStreamBounds). There is no framework default — one would be
	// a bound nobody chose, indistinguishable in the operator surface from one
	// somebody did, which is what the bounds requirement exists to end.
	MaxAge time.Duration

	// Duplicates is the server-side duplicate-detection window for the
	// Nats-Msg-Id header (ADR-055). Zero leaves the NATS server
	// default (2m: server/stream.go:1903 at nats-server v2.15.2, read, not
	// measured). ensureStreamForConsumer clamps it down to MaxAge when it
	// exceeds it; the clamp is natsclient's own. That the server rejects
	// creation when it exceeds MaxAge is not measured, and not promised.
	Duplicates time.Duration

	// MaxBytes is the maximum total size. REQUIRED and must be positive, for the
	// same reason as MaxAge: JetStream reads 0 and -1 alike as unlimited, so
	// neither is a declaration.
	MaxBytes int64

	// Discard is what happens at the ceiling: jetstream.DiscardOld evicts the
	// oldest, jetstream.DiscardNew refuses the write.
	//
	// It exists here so an auto-create path can carry a declaration's discard
	// policy. Without it this struct could express a bound but not what happens
	// when the bound is reached, so a caller recreating a stream from an operator's
	// declaration silently substituted DiscardOld — the zero value — for whatever
	// they chose. It cannot be REQUIRED (DiscardOld being the zero value is exactly
	// why), but it can at least be expressible.
	Discard jetstream.DiscardPolicy

	// MaxMsgs is the maximum number of messages (0 = unlimited).
	MaxMsgs int64

	// Replicas is the number of replicas (default 1).
	Replicas int
}

StreamAutoCreateConfig configures automatic stream creation.

func DefaultStreamConfig

func DefaultStreamConfig() *StreamAutoCreateConfig

DefaultStreamConfig returns the auto-create defaults for the fields that HAVE defaults: storage tier, retention policy and replica count.

It deliberately declares NO bounds: a default MaxAge with MaxBytes unset is the silent framework default the bounds requirement keeps out of the configuration path, a retention window nobody chose and no size ceiling at all. A caller that auto-creates must state its own bounds; CheckStreamBounds refuses the creation otherwise.

type StreamConsumerConfig

type StreamConsumerConfig struct {
	// StreamName is the name of the stream to consume from (required).
	StreamName string

	// ConsumerName is the durable consumer name. If empty, creates an ephemeral consumer.
	ConsumerName string

	// FilterSubject filters messages within the stream. If empty, receives all messages.
	FilterSubject string

	// DeliverPolicy determines where to start delivering messages.
	// Options: "all" (default), "last", "new", "by_start_time"
	DeliverPolicy string

	// AckPolicy determines how messages are acknowledged.
	// Options: "explicit" (default), "none", "all"
	AckPolicy string

	// MaxDeliver is the maximum number of delivery attempts (0 = unlimited).
	MaxDeliver int

	// AckWait is how long to wait for an ack before redelivery.
	// Default is 30 seconds.
	AckWait time.Duration

	// MaxAckPending limits the number of outstanding (unacknowledged) messages
	// that can be delivered to a consumer. This provides backpressure to prevent
	// overwhelming the consumer. 0 leaves it unset, so NATS applies inherited,
	// default, or server/account-capped policy; -1 means unlimited outstanding acks.
	MaxAckPending int

	// AutoCreate enables automatic stream creation if it doesn't exist.
	AutoCreate bool

	// AutoCreateConfig is used when auto-creating a stream.
	// If nil, defaults are used based on FilterSubject.
	AutoCreateConfig *StreamAutoCreateConfig

	// BackOff overrides AckWait per retry attempt. Index 0 is the first retry
	// wait, index 1 is the second, and so on. The last value is used for all
	// subsequent retries. If empty, AckWait applies uniformly.
	BackOff []time.Duration

	// MessageTimeout is the context timeout for processing each message.
	// This timeout is passed to the handler and should accommodate the full
	// processing time including any downstream calls (e.g., LLM requests).
	// Default is 30 seconds if not specified.
	MessageTimeout time.Duration

	// DisableMessageTimeout keeps the handler context bound to the consumer
	// lifecycle. Use only when the handler applies its own ordinary work deadline
	// and needs to retain an in-flight delivery across that deadline.
	DisableMessageTimeout bool
}

StreamConsumerConfig configures a JetStream consumer.

type StreamFieldDivergence

type StreamFieldDivergence struct {
	// Field is the jetstream.StreamConfig field name, so it can be found in code.
	Field string
	// Declared is what the caller asked for.
	Declared string
	// Observed is what the live stream actually carries.
	Observed string
}

StreamFieldDivergence is one field a caller declared that the live stream does not match.

The values are rendered strings rather than typed values because the whole point is to be read by a person: a duration, a byte count and a subject list have nothing in common except that an operator needs to see both sides.

func DiffDeclaredStream

func DiffDeclaredStream(declared, observed jetstream.StreamConfig) []StreamFieldDivergence

DiffDeclaredStream reports the DECLARED fields, of those it compares, whose live value differs.

The compared set is the limits and the routing — the fields whose divergence changes what the stream does with messages. It is NOT every field of jetstream.StreamConfig: Description, AllowDirect, DenyDelete, DenyPurge, AllowRollup, Compression, Metadata, SubjectTransform, RePublish, Placement, Mirror, Sources, ConsumerLimits and FirstSeq are not compared, so a caller that declares one of those and binds a stream without it is not told. AllowDirect is the one with real operational weight (a bound stream without it silently refuses direct gets); the rest are descriptive or advanced-topology fields whose divergence does not change delivery. Widen the set rather than assuming it is already complete.

It is exported so a caller CAN do more than have it logged — treating a subject divergence as fatal, say, since a stream that does not capture the caller's subject makes every publish fail. Nothing in this repository does yet: gated-dag makes exactly that check, but through its own wildcard-aware subjectCovered rather than this set comparison. The framework reports; an owner that needs to act has the values to act on.

func (StreamFieldDivergence) String

func (d StreamFieldDivergence) String() string

String renders one divergence for a diagnostic.

type Subscription

type Subscription struct {
	// contains filtered or unexported fields
}

Subscription wraps a NATS subscription for lifecycle management.

func (*Subscription) Drain

func (s *Subscription) Drain(ctx context.Context) error

Drain stops new deliveries and returns once the subscription's delivery goroutine has exited, so every callback has returned. If the connection closes before or during the drain, Drain still returns nil after the in-flight callback returns (TestSubscriptionDrainConnectionClosesMidDrain, with a stand-in subscription); messages queued but not yet delivered may be discarded, because core NATS is at-most-once. If ctx ends first, Drain returns ctx's error and a later call rejoins the same native drain; it never starts a second one.

func (*Subscription) Unsubscribe

func (s *Subscription) Unsubscribe() error

Unsubscribe unsubscribes from the subject

type TraceContext

type TraceContext struct {
	TraceID      string // 32 hex chars (16 bytes)
	SpanID       string // 16 hex chars (8 bytes)
	ParentSpanID string // 16 hex chars, empty for root span
	Sampled      bool
}

TraceContext holds trace information propagated through the system

func ExtractTrace

func ExtractTrace(msg *nats.Msg) *TraceContext

ExtractTrace reads trace headers from a NATS message

func ExtractTraceFromJetStream

func ExtractTraceFromJetStream(headers nats.Header) *TraceContext

ExtractTraceFromJetStream reads trace headers from a JetStream message

func NewTraceContext

func NewTraceContext() *TraceContext

NewTraceContext creates a new trace context with generated IDs

func ParseTraceparent

func ParseTraceparent(header string) (*TraceContext, error)

ParseTraceparent parses W3C traceparent header Format: {version}-{trace_id}-{span_id}-{flags} Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

func TraceContextFromContext

func TraceContextFromContext(ctx context.Context) (*TraceContext, bool)

TraceContextFromContext extracts trace context from context

func (*TraceContext) FormatTraceparent

func (tc *TraceContext) FormatTraceparent() string

FormatTraceparent formats trace context as W3C traceparent

func (*TraceContext) NewSpan

func (tc *TraceContext) NewSpan() *TraceContext

NewSpan creates a child span from existing trace context

type WritePolicy

type WritePolicy string

WritePolicy declares who may write a framework bucket. The framework-owned write-guard set is DERIVED from this field (Write == WriteOwnerOnly), never hand-maintained.

const (
	// WriteOwnerOnly means only the declared owner writes; a generic KV writer
	// (rule update_kv) is rejected at load and at runtime.
	WriteOwnerOnly WritePolicy = "owner-only"
	// WriteOpen means writes are not restricted to one declared owner. No current
	// graph catalog descriptor uses this policy.
	WriteOpen WritePolicy = "open"
)

Write policies.

Directories

Path Synopsis
Package storagereport produces and reads the account storage report.
Package storagereport produces and reads the account storage report.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL