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 ¶
const Prefix = "backplane/services/"
Prefix of everything the SDK writes to Consul KV (§4.2, §17).
Variables ¶
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 (*Hub) Changes ¶
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 ¶
Current is the latest snapshot. It is shared: never modify its maps, slices or messages.
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.
type Option ¶
type Option func(*Registry)
Option configures New.
type Registry ¶
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 (*Registry) Absent ¶
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) Current ¶
Current is the latest snapshot; the zero Catalog before Synced. It is shared: never modify it.
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) 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.
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.