Documentation
¶
Overview ¶
Package server runs a NATS server inside this process and hands its lifecycle to go/controls.
Why embedding is not a compromise ¶
nats-server is a Go library. The Options struct passed to NewServer when embedding carries Cluster, Gateway, LeafNode, Routes, JetStream, StoreDir and the rest — the same fields a standalone deployment sets in a configuration file. There is no reduced embedded mode. Embedding is constructing the server in your own process, and everything a standalone server can do, this one can.
That is what makes the progression continuous: a single process with no socket, then a listener, then a mesh, then somebody else's cluster. Only the wiring changes.
When not to use this package ¶
Most services should not. If a NATS cluster already exists, import nats/client and connect to it — pulling a broker into a binary to reach a broker that is already running is a dependency nobody needed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Liveness ¶
Liveness reports whether the server is running at all.
Distinct from readiness on purpose: a server that is running but not yet accepting connections is starting, and restarting it would only make it start again.
func Readiness ¶
Readiness reports whether the server is accepting connections.
Running() is checked first, and it is not redundant. ReadyForConnections asks whether every configured listener is up, and its check for the client listener is `s.listener != nil || opts.DontListen` (server.go:3980) — so an in-process server, which by definition has no listener, satisfies it whether or not the server is running. A stopped one reported READY, which is the fail-open shape: a probe that says yes when the thing is gone.
Types ¶
type Registrar ¶
type Registrar interface {
Register(id string, opts ...controls.ServiceOption)
}
Registrar is the one thing this package needs from a controller.
Narrower than controls.Controllable, which composes five interfaces, because registering a service is all that happens here — and controls' own documentation says to prefer the narrow interface where one will do.
The practical payoff is that the wiring becomes observable: a test can hand in a recorder and assert what was registered, where against the full interface it would mean faking five interfaces to exercise one method.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is an embedded NATS server and the settings it was built from.
func New ¶
New builds an embedded server without registering it, for a caller composing its own lifecycle. Most callers want Register.
func Register ¶
func Register( ctx context.Context, id string, controller Registrar, logger *slog.Logger, settings gonats.ServerSettings, ) (*Server, error)
Register builds an embedded server and registers it with the controller.
The returned Server is usable immediately for wiring — an in-process client can be constructed from it — but is not started until the controller starts it, which is the same contract go/transport's Register offers.
func (*Server) ClientURL ¶
ClientURL reports the address a client would dial.
Always empty for now: every server this package builds is in-process, so there is nothing to dial, and returning an address that cannot be reached would be worse than returning none.
func (*Server) InProcessConn ¶
InProcessConn satisfies the client library's InProcessConnProvider, so a client in this process can reach this server without a network hop.
It is on Server rather than exposed as a function because the connection is the server's to hand out: a caller holding a Server can connect to it, and a caller who does not, cannot.
It waits up to ReadyTimeout for startup to complete. nats-server hands out an in-process connection as soon as it is running, before JetStream is up, so a client starting alongside the server would otherwise meet no responders (spec 0003).
func (*Server) Raw ¶
func (s *Server) Raw() *natsserver.Server
Raw returns the underlying server.
An escape hatch, and used as one. Anything reached through here is outside what this module promises to keep working, so a second caller reaching for the same thing is a request for it to be a setting instead.