registry

package
v0.6.73 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package registry is backplane's view of the installation, built from Consul: the catalog (live instances and their health), the manifests the SDK writes per version, and the instance states under their sessions. Everything else in backplane — configuration and the console — reads a Catalog snapshot and reacts to changes; nothing else talks to Consul for discovery.

A consumer takes a Source and follows it from its own goroutine:

func (x *Consumer) follow(ctx context.Context) error {
    changes := x.src.Changes(ctx) // closed when ctx ends
    for {
        x.apply(x.src.Current()) // the zero Catalog (Index 0) until synced
        if _, ok := <-changes; !ok {
            return nil
        }
    }
}

Snapshots are shared and immutable: never modify their maps, slices or messages. Tests of consumers publish their own snapshots through a Hub.

Index

Constants

View Source
const Prefix = "backplane/services/"

Prefix of everything the SDK writes to Consul KV (§4.2, §17).

Variables

View Source
var ErrNotSynced = errors.New("registry: not synced with consul yet")

ErrNotSynced: the first snapshot is not built yet.

Functions

This section is empty.

Types

type Catalog

type Catalog struct {
	// Index grows with every snapshot; equal indexes mean equal content.
	Index    uint64
	Services map[string]Service
}

Catalog is an immutable snapshot of the installation. A new snapshot is built on every change; readers never see one being modified.

type Hub

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

Hub holds the current snapshot and signals changes: the Source half of the Registry, and on its own the fake Source of tests — Publish what the test needs.

A Hub is shared by pointer: it holds a lock and its subscribers.

func NewHub

func NewHub() *Hub

NewHub is a Hub with the zero Catalog.

func (*Hub) Changes

func (h *Hub) Changes(ctx context.Context) <-chan struct{}

Changes delivers one signal after each new snapshot (one pending signal at most: a slow reader sees the latest snapshot once) and is closed when ctx ends. Read Current after a signal.

func (*Hub) Current

func (h *Hub) Current() Catalog

Current is the latest snapshot. It is shared: never modify its maps, slices or messages.

func (*Hub) Publish

func (h *Hub) Publish(services map[string]Service) (Catalog, bool)

Publish makes services the current snapshot unless it equals the current one; the new snapshot's Index is one above the previous. It reports the snapshot and whether it is new. services is kept: do not modify it after.

type Instance

type Instance struct {
	ID string
	// State is the SDK's instance state; nil when only the catalog knows
	// the instance (it registered but its state expired or is not written).
	State *backplanev1.InstanceState
	// Registered: in the Consul catalog (serving phase).
	Registered bool
	// Healthy: the catalog health check passes.
	Healthy bool
	// Address and Port are what traffic goes to (catalog registration);
	// Port is the public port, 0 without managed routes.
	Address string
	Port    uint32
	// Tags of the catalog registration (BACKPLANE_CONSUL_TAGS).
	Tags []string
}

Instance is one running process.

func (Instance) Available

func (in Instance) Available() bool

Available reports whether this instance is registered, healthy and serving.

type Option

type Option func(*Registry)

Option configures New.

func Backoff

func Backoff(minDelay, maxDelay time.Duration) Option

Backoff bounds the delay between failed queries (default 500ms..30s, jittered).

func WaitTime

func WaitTime(d time.Duration) Option

WaitTime bounds one blocking query (default 5m; Consul caps it at 10m).

type Registry

type Registry struct {
	deps.Component
	// contains filtered or unexported fields
}

Registry follows Consul with blocking queries — the catalog's service list, the health of every followed service and the KV prefix backplane/services/ — and publishes a Catalog snapshot after every change. The first snapshot is published once all of them answered (Synced); until then Current is the zero Catalog. While Consul is down the last snapshot stays and every query retries with backoff.

It is a component: the queries run under its node, from start to stop.

func New

func New(parent deps.Scope, client *api.Client, opts ...Option) *Registry

New creates the registry under parent, reading Consul through client.

func (*Registry) Absent

func (r *Registry) Absent(ctx context.Context, service string) (bool, error)

Absent confirms that no instance is registered (healthy or otherwise) and no instance state remains in Consul. It uses consistent reads, not a cached or stale snapshot. An outage prevents cleanup. Manifests do not imply life.

func (*Registry) Changes

func (r *Registry) Changes(ctx context.Context) <-chan struct{}

Changes signals every new snapshot until ctx ends (see Hub.Changes).

func (*Registry) Current

func (r *Registry) Current() Catalog

Current is the latest snapshot; the zero Catalog before Synced. It is shared: never modify it.

func (*Registry) Err

func (r *Registry) Err() error

Err is the last Consul error while queries are failing, nil otherwise.

func (*Registry) Ready

func (r *Registry) Ready() error

Ready is nil once the first snapshot is published: backplane serves nothing useful without it. A later Consul outage keeps it nil — the last snapshot stays valid — and shows in Err.

func (*Registry) Synced

func (r *Registry) Synced() <-chan struct{}

Synced is closed once the first snapshot is published.

type Service

type Service struct {
	Name string
	// Manifests by version, as written by the SDK.
	Manifests map[string]*backplanev1.Manifest
	// Instances with a published state or a catalog registration, by ID.
	Instances []Instance
}

Service is one service of the installation.

func (Service) Available

func (s Service) Available() *backplanev1.Manifest

Available is the highest version with a registered, healthy serving instance. It never falls back to declarations that cannot currently serve traffic.

func (Service) Healthy

func (s Service) Healthy() []Instance

Healthy lists the instances traffic may go to: registered and passing.

func (Service) Latest

func (s Service) Latest() *backplanev1.Manifest

Latest prefers the highest available version, then a live version, then any known manifest. The fallbacks are for inspection of offline services.

func (Service) Manifest

func (s Service) Manifest(version string) *backplanev1.Manifest

Manifest is the manifest of the instance's version, nil when missing.

type Source

type Source interface {
	// Current is the latest snapshot; the zero Catalog before the first.
	Current() Catalog
	// Changes delivers a signal after every new snapshot until ctx ends;
	// slow readers get one pending signal, never a backlog.
	Changes(ctx context.Context) <-chan struct{}
}

Source is what provides snapshots: the Consul-backed Registry, or a fake in tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL