discovery

Documentation

Overview

Package discovery advertises the running sqi-server on the local network via multicast DNS (mDNS / DNS-SD) so that workers and the sqi CLI can find it without manual address configuration.

The server publishes a single "_sqi._tcp" service instance whose SRV record points at the HTTP API port — the canonical, externally-bound sqi endpoint (the embedded NATS broker defaults to loopback). Additional connection details, including the NATS port, are carried in TXT records:

id=<instance-id>   unique per process; lets clients dedupe re-announcements
http=<http-port>   REST + WebSocket API port (also the SRV port)
nats=<nats-port>   embedded NATS JetStream port for worker connections
host=<hostname>    advertising host's reported name
version=<version>  server build version

Advertisement is toggleable via configuration (see Config.Enabled) for environments that prohibit multicast, such as most cloud VPCs.

Index

• type Config
• type Responder
  • func New(cfg Config, logger *slog.Logger) (*Responder, error)
  • func (r *Responder) Shutdown()
  • func (r *Responder) Start(ctx context.Context) error

Types

type Config

type Config struct {
	// Enabled controls whether the responder publishes an mDNS record.
	// When false, [New] still succeeds but [Responder.Start] is a no-op.
	Enabled bool

	// InstanceName is the DNS-SD service instance name (the human-readable
	// label shown in service browsers). Each sqi-server on the same subnet
	// should use a distinct name. Must not be empty when Enabled is true.
	InstanceName string

	// HTTPAddr is the server's HTTP listen address ("host:port"). The port is
	// extracted and advertised as the SRV record port.
	HTTPAddr string

	// NATSAddr is the embedded NATS listen address ("host:port"). The port is
	// extracted and advertised in the "nats" TXT record.
	NATSAddr string

	// InstanceID uniquely identifies this server process. When empty, [New]
	// generates a random UUID. Advertised in the "id" TXT record.
	InstanceID string
}

Config holds the parameters needed to advertise the sqi-server instance.

type Responder

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

Responder owns the lifecycle of the mDNS service advertisement. Create one with New, then call Responder.Start and Responder.Shutdown.

func New

func New(cfg Config, logger *slog.Logger) (*Responder, error)

New validates cfg and returns a Responder. It parses the HTTP and NATS ports up front so configuration errors surface before the server boots. An empty Config.InstanceID is filled with a freshly generated UUID.

When cfg.Enabled is false, port parsing is skipped and the returned responder's Start is a no-op.

func (*Responder) Shutdown

func (r *Responder) Shutdown()

Shutdown stops the mDNS advertisement, sending goodbye packets so browsers remove the service promptly. It is safe to call when Start was never called or discovery is disabled.

Start and Shutdown are not safe for concurrent use; the server lifecycle calls them sequentially (Start during boot, Shutdown during graceful stop).

func (*Responder) Start

func (r *Responder) Start(ctx context.Context) error

Start publishes the mDNS service record on all multicast-capable interfaces. It returns nil immediately when discovery is disabled. The advertisement runs in background goroutines managed by the underlying responder until Responder.Shutdown is called.

The ctx argument is accepted for symmetry with other components and to allow future cancellation support; the current zeroconf registration is non-blocking and does not observe it.