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 (P13, P14); Close, on a connection the client dialled, and Connect are the exception (T1, T4; ADR-112). 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 (P16, at nats-server v2.14.7), 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 and no legacy "error: <msg>" body — a reply with no X-Status header is success.
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 (P13); Close and Connect are the exception (T1, T4; P18; ADR-112). 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, gh#93).
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. (The earlier additive window — a legacy "error: <msg>" body kept alongside the headers — was retired with the PR-D breaking change.)
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
- Variables
- func BucketLastSeq(ctx context.Context, bucket interface{ ... }) (uint64, error)
- func BucketRetention(ctx context.Context, bucket jetstream.KeyValue) (maxAge time.Duration, maxBytes int64, err error)
- func CheckNoLifecycleRetention(name string, maxAge time.Duration, maxBytes int64) error
- func CheckOrdinaryStreamName(name, source string) error
- func CheckStreamBounds(cfg jetstream.StreamConfig, source string) error
- func ClassifyConsumerPolicyError(err error, operation string) error
- func ClassifyReply(msg *nats.Msg) ([]byte, error)
- func ContextWithTrace(ctx context.Context, tc *TraceContext) context.Context
- func DecodeKVOpaqueToken(token string) ([]byte, error)
- func DivergenceLabels(divergences []StreamFieldDivergence) []string
- func EncodeKVOpaqueToken(raw []byte) (string, error)
- func EnsureFrameworkBucket(ctx context.Context, c *Client, spec BucketSpec) (jetstream.KeyValue, error)
- func FilteredKeys(ctx context.Context, kv interface{ ... }, pattern string) ([]string, error)
- func InjectTrace(ctx context.Context, msg *nats.Msg)
- func IsKVConflictError(err error) bool
- func IsKVNotFoundError(err error) bool
- func IsKVTombstone(operation jetstream.KeyValueOp) bool
- func IsNoResponders(err error) bool
- func OpenFrameworkBucket(ctx context.Context, c *Client, spec BucketSpec) (jetstream.KeyValue, error)
- func ReconcileNoLifecycleRetention(ctx context.Context, js jetstream.JetStream, bucket string, ...) error
- func RespondError(msg *nats.Msg, err error) error
- func TerminateDelivery(err error) error
- func ValidateKVLiteralKey(key string) error
- func ValidateKVLiteralToken(token string) error
- func ValidateKVWildcardFilter(filter string) error
- type BucketClass
- type BucketSpec
- type Client
- func (m *Client) Close(ctx context.Context) error
- func (m *Client) Connect(ctx context.Context) error
- func (c *Client) ConsumeInternalStreamWithConfig(ctx context.Context, cfg StreamConsumerConfig, ...) (jetstream.ConsumeContext, error)
- func (c *Client) ConsumeStreamWithConfig(ctx context.Context, owner PortConsumerContext, cfg StreamConsumerConfig, ...) (jetstream.ConsumeContext, error)
- func (c *Client) ConsumeStreamWithConfigContexts(setupCtx context.Context, handlerCtx context.Context, ...) (jetstream.ConsumeContext, error)
- func (m *Client) CreateKeyValueBucket(ctx context.Context, cfg jetstream.KeyValueConfig) (jetstream.KeyValue, error)
- func (m *Client) CreateStream(ctx context.Context, cfg jetstream.StreamConfig) (jetstream.Stream, error)
- func (m *Client) DeleteKeyValueBucket(ctx context.Context, name string) error
- func (c *Client) EnsureStream(ctx context.Context, cfg jetstream.StreamConfig) (jetstream.Stream, error)
- func (m *Client) GetConnection() *nats.Conn
- func (m *Client) GetKeyValueBucket(ctx context.Context, name string) (jetstream.KeyValue, error)
- func (m *Client) GetStatus() *Status
- func (m *Client) GetStream(ctx context.Context, name string) (jetstream.Stream, error)
- func (m *Client) IsHealthy() bool
- func (m *Client) JetStream() (jetstream.JetStream, error)
- func (m *Client) ListKeyValueBuckets(ctx context.Context) ([]string, error)
- func (m *Client) MaxPayload() (int64, error)
- func (c *Client) NewKVStore(bucket jetstream.KeyValue, opts ...func(*KVOptions)) *KVStore
- func (c *Client) ObserveDirectPortConsumerPolicy(ctx context.Context, owner PortConsumerContext, ...) (func(), error)
- func (m *Client) Publish(ctx context.Context, subject string, data []byte) error
- func (m *Client) PublishBatchToStream(ctx context.Context, subject string, msgs [][]byte) error
- func (m *Client) PublishToStream(ctx context.Context, subject string, data []byte) error
- func (c *Client) PublishToStreamWithAck(ctx context.Context, subject string, data []byte) (*jetstream.PubAck, error)
- func (m *Client) PublishToStreamWithMsgID(ctx context.Context, subject string, data []byte, msgID string) error
- func (m *Client) RTT() (time.Duration, error)
- func (c *Client) Reply(ctx context.Context, replyTo string, data []byte) error
- func (c *Client) ReplyWithHeaders(ctx context.Context, replyTo string, data []byte, headers map[string]string) error
- func (c *Client) RequestClassified(ctx context.Context, subject string, data []byte, timeout time.Duration) ([]byte, error)
- func (c *Client) RequestReadyClassified(ctx context.Context, subject string, data []byte, ...) ([]byte, error)
- func (c *Client) RequestWithHeaders(ctx context.Context, subject string, data []byte, headers map[string]string, ...) (*nats.Msg, error)
- func (c *Client) RequestWithRetryClassified(ctx context.Context, subject string, data []byte, timeout time.Duration, ...) ([]byte, error)
- func (m *Client) Status() ConnectionStatus
- func (m *Client) Subscribe(ctx context.Context, subject string, handler func(context.Context, *nats.Msg)) (*Subscription, error)
- func (c *Client) SubscribeForRequests(ctx context.Context, subject string, ...) (*Subscription, error)
- func (m *Client) URLs() string
- func (c *Client) WaitConsumerHandlers(ctx context.Context, handle jetstream.ConsumeContext) error
- func (m *Client) WaitForBucket(ctx context.Context, name string, timeout time.Duration) (jetstream.KeyValue, error)
- func (m *Client) WaitForConnection(ctx context.Context) error
- type ClientOption
- func WithConnectionLossTimeout(grace time.Duration) ClientOption
- func WithConnectionLostCallback(fn func(error)) ClientOption
- func WithCredentials(username, password string) ClientOption
- func WithHealthInterval(d time.Duration) ClientOption
- func WithLogger(logger *slog.Logger) ClientOption
- func WithMaxReconnects(maxN int) ClientOption
- func WithMetrics(registry *metric.MetricsRegistry) ClientOption
- func WithName(name string) ClientOption
- func WithPingInterval(d time.Duration) ClientOption
- func WithReconnectWait(d time.Duration) ClientOption
- func WithTimeout(d time.Duration) ClientOption
- func WithWriteTimeout(d time.Duration) ClientOption
- type ConnectionStatus
- type CreatePosture
- type DeliveryDecision
- type DeliveryMetadataUnavailableError
- type DeliveryResult
- func ConsumeDeliveryWithHeartbeat(ctx context.Context, msg jetstream.Msg, policy HeartbeatDeliveryPolicy) DeliveryResult
- func SettleDelivery(msg jetstream.Msg, decision DeliveryDecision, cause error) DeliveryResult
- func SettleDeliveryWithRetry(msg jetstream.Msg, retry DeliveryRetryPolicy, decision DeliveryDecision, ...) DeliveryResult
- type DeliveryRetryPolicy
- type DeliveryWork
- type DeliveryWorkPanicError
- type HeartbeatDeliveryPolicy
- type InvalidDeliveryDecisionError
- type KVEntry
- type KVOptions
- type KVStore
- func (kv *KVStore) AssertNoLifecycleRetention(ctx context.Context, name string) error
- func (kv *KVStore) Create(ctx context.Context, key string, value []byte) (uint64, error)
- func (kv *KVStore) Delete(ctx context.Context, key string) error
- func (kv *KVStore) DeleteAtRevision(ctx context.Context, key string, revision uint64) error
- func (kv *KVStore) Get(ctx context.Context, key string) (*KVEntry, error)
- func (kv *KVStore) Keys(ctx context.Context) ([]string, error)
- func (kv *KVStore) KeysByFilter(ctx context.Context, pattern string) ([]string, error)
- func (kv *KVStore) KeysByPrefix(ctx context.Context, prefix string) ([]string, error)
- func (kv *KVStore) Put(ctx context.Context, key string, value []byte) (uint64, error)
- func (kv *KVStore) Update(ctx context.Context, key string, value []byte, revision uint64) (uint64, error)
- func (kv *KVStore) UpdateJSON(ctx context.Context, key string, updateFn func(current map[string]any) error) error
- func (kv *KVStore) UpdateWithRetry(ctx context.Context, key string, updateFn func(current []byte) ([]byte, error)) error
- func (kv *KVStore) UpdateWithRetryRead(ctx context.Context, key string, ...) (uint64, error)
- func (kv *KVStore) UpdateWithRetryRev(ctx context.Context, key string, updateFn func(current []byte) ([]byte, error)) (uint64, error)
- func (kv *KVStore) Watch(ctx context.Context, pattern string) (jetstream.KeyWatcher, error)
- type PermanentDeliveryError
- type PortConsumerContext
- type ResourceKind
- type RetentionKind
- type RetentionPolicy
- type Status
- type StreamAutoCreateConfig
- type StreamConsumerConfig
- type StreamFieldDivergence
- type Subscription
- type TraceContext
- type WritePolicy
Constants ¶
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.
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", ...). Additive over the gh#93 header set: // legacy callers ignore it; 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, so existing uncoded handler // errors are byte-for-byte unchanged on the wire (the reply body is // also unchanged — Code rides the header; the standard error body for // Detail lands with the breaking PR). 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.
const ( HeaderStatusError = "error" ErrorClassTransient = "transient" ErrorClassInvalid = "invalid" ErrorClassFatal = "fatal" )
Values used in HeaderStatus / HeaderErrorClass.
const ( // MaxKVLiteralTokenBytes is the SemStreams byte budget for one literal KV token. MaxKVLiteralTokenBytes = 512 // MaxKVLiteralKeyBytes is the SemStreams byte budget for one complete literal KV key. MaxKVLiteralKeyBytes = 1024 // MaxKVLiteralKeyTokens is the SemStreams arity budget for one complete literal KV key. MaxKVLiteralKeyTokens = 64 // MaxKVWildcardFilterBytes is the SemStreams byte budget for one complete KV filter. MaxKVWildcardFilterBytes = 1024 // MaxKVWildcardFilterTokens is the SemStreams 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 )
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" )
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" )
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" )
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 (P13; ADR-112). DefaultReadinessBudget = 30 * time.Second )
Readiness-gated read defaults (ADR-060 sibling doctrine, third bucket — see SemStreams' docs/operations/07-nats-request-retry.md at the pin; not carried here). 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).
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
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.
const DefaultRequestTimeout = 5 * time.Second
DefaultRequestTimeout is the default timeout for request/reply operations.
Variables ¶
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
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.
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 D1 — eviction is reachability-blind) and the shared configuration bucket that holds the create-once platform identity (ADR-102 decision 7 — an expired identity is reminted as a second authority that can never be reconciled). The exported name predates the second caller.
var ErrHeartbeatFailed = errors.New("delivery heartbeat failed")
ErrHeartbeatFailed identifies loss of the InProgress settlement path while work may already have caused an external effect.
var ( // ErrNotConnected wraps errs.ErrConnectionLost, so errs.IsTransient and // errs.Classify both call it transient (T7). ErrNotConnected = fmt.Errorf("not connected to NATS: %w", errs.ErrConnectionLost) )
Error messages
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.
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 D1). Mirrors BucketLastSeq: the KeyValueStatus interface does not surface these, so we read the concrete JetStream-backed status's stream config.
func CheckNoLifecycleRetention ¶
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 ¶
CheckOrdinaryStreamName is the fail-closed name guard shared by every stream-provisioning seam. Stream provisioning governs ORDINARY streams — JetStream streams SemStreams 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 ¶
ClassifyConsumerPolicyError classifies NATS policy rejections as invalid configuration while preserving all other failures as transient.
func ClassifyReply ¶
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. The legacy "error: " body fallback is gone (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 (#509).
func ContextWithTrace ¶
func ContextWithTrace(ctx context.Context, tc *TraceContext) context.Context
ContextWithTrace returns a context with trace information
func DecodeKVOpaqueToken ¶
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 ¶
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 ¶
InjectTrace adds trace headers to a NATS message from context
func IsKVConflictError ¶
IsKVConflictError checks if error indicates a conflict (key exists or wrong revision). Like IsKVNotFoundError it reads the error's type, never its text (#146). A replicated stream reports a wrong last sequence as 10164 where a single replica reports 10071.
func IsKVNotFoundError ¶
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). See issue #122 and feedback_jetstream_sentinel_set_coverage.
The class is read from the error's type, never its text (#146): 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 ¶
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 (P15; 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 — the #714 class) 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 D1 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 (framework-owned-bucket-guards; #622). It is the KV analogue of the shipped ObjectStore guard (storage/objectstore/retention.go) and runs TWO steps IN ORDER on the backing stream (KV_<bucket>):
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, as in #610/#611, 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 legacy buckets that a create-or-get path would otherwise never reconcile.
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 ¶
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 ¶
TerminateDelivery marks err for JetStream Term handling. Transient and cancellation errors must be returned unchanged so their existing NAK paths remain intact.
func ValidateKVLiteralKey ¶
ValidateKVLiteralKey validates a complete dot-separated literal KV key. It rejects wildcards and empty positions and never changes key identity.
func ValidateKVLiteralToken ¶
ValidateKVLiteralToken validates one literal NATS KV key position. It never rewrites, normalizes, or encodes the supplied token.
func ValidateKVWildcardFilter ¶
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 ¶
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 (T1, T8; P17, P23); 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 ¶
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 (T3). 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 (T4). The context does not bound the connection's later reconnects (T5). Once Close has begun it returns nats.ErrConnectionClosed before dialling, whether or not its context has ended (T3). 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 (design D3).
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 (owner ruling, #9 comment 5994720412 item 2). A write the server is not reading holds the setup, as there (P13; 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 (owner ruling, #9 comment 5994720412 item 2). 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 (P13; 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 (P13; 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 ¶
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 ¶
GetConnection returns the current NATS connection
func (*Client) GetKeyValueBucket ¶
GetKeyValueBucket gets an existing KV bucket
func (*Client) GetStream ¶
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) ListKeyValueBuckets ¶
ListKeyValueBuckets lists all KV buckets
func (*Client) MaxPayload ¶
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 ¶
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) PublishBatchToStream ¶
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 (gh#470).
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 (P13; 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 ¶
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 §5, "T1"): 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). Redelivery outside that window — e.g. DeliverPolicy:all replay on consumer recreation — can still re-append; see ADR-055 Open Question #1. An empty msgID is equivalent to PublishToStream (no dedup), so this is a safe drop-in.
func (*Client) Reply ¶
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 (P10). No responders returns nats.ErrNoResponders, matched by errors.Is or IsNoResponders; its class is not promised until #93 settles how raw nats.go errors classify (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. See docs/operations/07-nats-request-retry.md.
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). See docs/operations/07-nats-request-retry.md.
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, P10), 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. See docs/operations/07-nats-request-retry.md.
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 (owner ruling, #9 comment 5994720412 item 2). 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 (owner ruling, #9 comment 5994720412 item 2). 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) WaitConsumerHandlers ¶
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 (P13). 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.
type ClientOption ¶
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 (legacy behavior — 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 (P20, P24); the timing at other values is not promised.
While a write is held this check does not fire (P20; P24r at nats.go v1.55.0, PR #492 comment 6545759092), so only the write timeout ends that write. d must be positive: NewClient refuses any other value as invalid (T9).
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 (design D4). The default is nats.go's, one minute. Other calls on the connection wait behind a held write (T2; P17).
At nats.go v1.55.0 a write the timeout ends partway closes the socket, and nats.go reconnects (probes P14 and P24r, PR #492 comment 6545759092; owner ruling, comment 6545866336). How soon the connection carries messages again is not promised. d must be positive: NewClient refuses any other value as invalid (T9).
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 (e *DeliveryMetadataUnavailableError) Error() string
func (*DeliveryMetadataUnavailableError) Unwrap ¶
func (e *DeliveryMetadataUnavailableError) Unwrap() error
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 (e *InvalidDeliveryDecisionError) Error() string
func (*InvalidDeliveryDecisionError) Unwrap ¶
func (e *InvalidDeliveryDecisionError) Unwrap() error
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 (P13, P14; 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 ¶
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 D1) and for the shared configuration bucket that holds the create-once platform identity (ADR-102 d7). 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) DeleteAtRevision ¶
DeleteAtRevision removes a key only when revision is still current. It makes one revision-fenced delete attempt and never reads or retries.
func (*KVStore) Keys ¶
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 (#533). An empty bucket gives nil and no error.
func (*KVStore) KeysByFilter ¶
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 ¶
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) 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.
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 ¶
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 SemStreams 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 decision 7 // 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 §5 "T1"). Zero leaves the NATS server
// default (2m). 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. It used to return MaxAge 7 days with MaxBytes unset — the exact silent framework default the bounds requirement removed from the configuration path, still handing out 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 (gh#480).
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.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package storagereport produces and reads the account storage report.
|
Package storagereport produces and reads the account storage report. |