Reference¶

Page	Covers
Server settings	`ServerSettings` — the embedded server
Client settings	`ClientSettings` and `CredentialSource` — the connection
Errors	The sentinels, and what each one means went wrong

The generated API reference lives at pkg.go.dev.

Packages¶

Import path	Purpose
`gitlab.com/phpboyscout/go/nats`	Settings, errors, `CredentialSource`
`gitlab.com/phpboyscout/go/nats/server`	Embedded server, `controls` registration
`gitlab.com/phpboyscout/go/nats/client`	Connection, bounded subscriptions, JetStream creation
`gitlab.com/phpboyscout/go/nats/natstest`	A real server and client for a test — see the how-to

The split matters: importing nats/client alone does not pull a broker into your binary. Importing nats/server does, and should be a decision rather than a side effect.

On configuration¶

None of these structs is read from a file by this module. The calling application maps its own configuration onto them. Every field carries mapstructure, yaml and json tags so that mapping is a decode rather than a hand-written assignment.

Publishing and JetStream¶

Method	Purpose
`Publish(ctx, subject, data)`	Send. A context deadline asks for confirmation
`PublishMsg(ctx, msg)`	Send with headers
`Request(ctx, subject, data)`	Send and wait for one reply
`Subscribe(subject, handler)`	Bounded subscription, confirmed with the server
`QueueSubscribe(subject, queue, handler)`	The same, with competing consumers
`Stream(ctx, StreamSettings)`	Create a stream, refusing an unbounded one
`KeyValue(ctx, BucketSettings)`	Create a bucket, refusing an unbounded one
`ObjectStore(ctx, BucketSettings)`	Create an object store, refusing an unbounded one
`JetStream()`	The JetStream context, for everything past creation
`Raw()`	The underlying connection. An escape hatch, named as one

Lifecycle¶

Method	Purpose
`Start(ctx)`	Connects. The controller's `StartFunc`
`Stop(ctx)`	Drains, bounded by the context. The controller's `StopFunc`
`Close(ctx)`	Drains and waits. A context with no deadline gets `DefaultDrainTimeout`
`Readiness()`	False while reconnecting — recoverable, but cannot carry traffic
`Liveness()`	False only when closed, which is where NATS stops reconnecting

Construction and options¶

Function	Purpose
`client.Connect(ctx, settings, cred, opts...)`	Build and connect immediately
`client.New(settings, cred, opts...)`	Build without connecting
`client.Register(ctx, id, controller, settings, cred, opts...)`	Build and hand the lifecycle to `controls`
`client.InProcess(srv)`	Reach a server in this process, bypassing TCP
`client.WithLogger(l)`	Defaults to `slog.Default()`
`client.OnShed(fn)`	Called when a subscription drops messages. Must not block
`client.OnError(fn)`	Every asynchronous error. Must not block
`client.WithDrainTimeout(d)`	Overrides how long the library spends draining