registration

Documentation

Overview

Package registration manages worker registration with sqi-server over NATS.

Lifecycle

A Registrar is created once at worker startup, after the NATS connection is established. Its Registrar.Register method publishes a protocol.RegisterMsg to the worker.register JetStream subject. On graceful shutdown, Registrar.Deregister publishes a protocol.DeregisterMsg to worker.deregister so the server marks the worker offline immediately.

Re-registration

Registrar.SetupReconnectHook installs a NATS reconnect callback that re-publishes the registration message whenever the connection is restored after a drop. This ensures the server always has a current, online record for the worker without requiring a process restart.

Acknowledgment

In Phase 1 the server processes worker.register via a JetStream push consumer and does not send a reply. A successful NATS publish (no error) is treated as registration success. Request-reply acknowledgment with explicit accept/reject is a planned protocol enhancement.

In-memory capability map

The Registrar stores the merged capabilities.Capabilities for the lifetime of the process. Heartbeat publishers and log formatters access it via Registrar.Capabilities so they can include capability context in their output without re-detecting hardware on every call.

Index

• type Registrar
  • func New(nc *nats.Conn, workerID string, cfg workerconfig.WorkerSettings, ...) *Registrar
  • func (r *Registrar) Capabilities() capabilities.Capabilities
  • func (r *Registrar) Deregister(reason string)
  • func (r *Registrar) LastRegisteredAt() time.Time
  • func (r *Registrar) Register(ctx context.Context) error
  • func (r *Registrar) SetupReconnectHook(_ context.Context)

Types

type Registrar

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

Registrar publishes worker registration and deregistration messages and stores the worker's capability map in memory for the process lifetime.

func New

func New(
	nc *nats.Conn,
	workerID string,
	cfg workerconfig.WorkerSettings,
	caps capabilities.Capabilities,
	logger *slog.Logger,
) *Registrar

New creates a Registrar. caps should already have manual tags merged in (via capabilities.Capabilities.MergeManualTags) before being passed here.

func (*Registrar) Capabilities

func (r *Registrar) Capabilities() capabilities.Capabilities

Capabilities returns the merged capability set stored at construction time. The returned value is a copy; mutations do not affect the Registrar's state.

func (*Registrar) Deregister

func (r *Registrar) Deregister(reason string)

Deregister publishes a DeregisterMsg to worker.deregister on graceful shutdown so the server marks this worker offline immediately rather than waiting for the heartbeat timeout sweep.

Deregister is best-effort: failures are logged as warnings since the server will detect the absence via heartbeat timeout regardless. The caller is responsible for flushing any buffered publishes before closing the NATS connection (typically via natsclient.Drain deferred in start.go).

func (*Registrar) LastRegisteredAt

func (r *Registrar) LastRegisteredAt() time.Time

LastRegisteredAt returns the time of the most recent successful Register call, or the zero time if Register has never succeeded in this process lifetime. Safe for concurrent use; the heartbeat watchdog uses this to determine whether it needs to re-register after a reconnect.

func (*Registrar) Register

func (r *Registrar) Register(ctx context.Context) error

Register publishes a RegisterMsg to worker.register. It is safe to call multiple times (at boot and on NATS reconnect).

In Phase 1 there is no server reply; a successful publish is taken as registration success (see package-level documentation for rationale).

func (*Registrar) SetupReconnectHook

func (r *Registrar) SetupReconnectHook(_ context.Context)

SetupReconnectHook installs a NATS reconnect handler that re-publishes the registration message whenever the connection is restored. It replaces any previously set ReconnectHandler on the connection, so callers must install this after any other reconnect hooks they require.

Re-registration failures are logged but do not cause a fatal error; the server's heartbeat sweep will time out the stale worker record regardless and the next successful heartbeat will re-establish liveness.