consul

package
v0.6.32 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package consul keeps a service present in Consul: manifest per version, instance state under a TTL session (it disappears with the instance) and the catalog registration. The state is published from before the author's tree starts (phase starting) so a service waiting for its dependencies is visible; the catalog registration follows only once it serves. Consul being absent never fails the service.

Index

Constants

View Source
const BackplaneService = "backplane"

BackplaneService is the service name backplane runs under.

Variables

View Source
var (
	// ErrStateHeld: the instance state key is locked by a session that is
	// not an incarnation of this instance, or is still in its lock delay.
	ErrStateHeld = errors.New("consul: instance state held")
	// ErrDuplicateInstance: another live process runs with this instance id.
	ErrDuplicateInstance = errors.New("consul: duplicate instance id")
	// ErrManifestConflict: this version already has different declarations.
	ErrManifestConflict = errors.New("consul: different manifest already published for this version")
)
View Source
var ErrNotReady = errors.New("consul mesh: no certificate or roots yet")

ErrNotReady: the leaf certificate or the roots are not fetched yet.

View Source
var ErrRoot = errors.New("consul mesh: root does not parse")

ErrRoot: a root of the CA does not parse.

Functions

This section is empty.

Types

type Check

type Check struct {
	Interval        time.Duration
	Timeout         time.Duration
	DeregisterAfter time.Duration
}

Check is the catalog registration's health check; zero fields take the defaults (10s, 5s, 1m).

type ConfigState

type ConfigState interface {
	Effective() configrt.Effective
	OnChange(fn func())
}

ConfigState is the dynamic configuration seen by the presence.

type Discovery added in v0.3.0

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

Discovery finds backplane's replicas: the instance states the SDK of each one writes to KV (phase serving, with a platform port), as the registry reads them. Lists are cached for a few seconds.

func NewDiscovery added in v0.3.0

func NewDiscovery(client *api.Client) *Discovery

NewDiscovery creates the discovery over client.

func (*Discovery) Backplanes added in v0.3.0

func (d *Discovery) Backplanes(ctx context.Context) ([]string, error)

Backplanes is the platform addresses (host:port) of the serving replicas.

func (*Discovery) WatchBound added in v0.6.8

func (d *Discovery) WatchBound(ctx context.Context, service string, fn func(hooks []string)) error

WatchBound calls fn with service's bound hooks (short names; empty when none) now and after every change, until ctx ends. A failed query is retried; fn keeps the last set meanwhile.

type Identity

type Identity struct {
	Service      string
	Version      string
	Instance     string
	Address      string
	PlatformPort uint16
	PublicPort   uint16 // 0 when the service has no managed public routes
	Commit       string
}

Identity is how the instance presents itself.

type Mesh added in v0.6.20

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

Mesh is a service's identity from Consul's CA and intentions, followed by blocking queries as configuration is: the service's leaf certificate (renewed by the agent before it expires and when the CA's root rotates), the CA's roots, and the intentions naming the service as destination. Who may call is decided here from the intentions, as Consul orders them (exact source before a wildcard): the agent's own authorize endpoint caches its answer.

func NewMesh added in v0.6.20

func NewMesh(p MeshParams) *Mesh

NewMesh creates the identity; Run follows it.

func (*Mesh) Authorize added in v0.6.20

func (m *Mesh) Authorize(caller string) (bool, string)

Authorize decides from the intentions: the first naming caller or "*"; none: the default.

func (*Mesh) Certificate added in v0.6.20

func (m *Mesh) Certificate() *tls.Certificate

Certificate is the service's current leaf certificate.

func (*Mesh) Ready added in v0.6.20

func (m *Mesh) Ready() error

Ready is nil once the certificate, the roots and the intentions are known.

func (*Mesh) Roots added in v0.6.20

func (m *Mesh) Roots() *x509.CertPool

Roots are the CA's current roots.

func (*Mesh) Run added in v0.6.20

func (m *Mesh) Run(ctx context.Context) error

Run follows the leaf, the roots and the intentions until ctx ends.

type MeshParams added in v0.6.20

type MeshParams struct {
	Client  *api.Client
	Service string
	// DefaultAllow: a caller no intention names is allowed.
	DefaultAllow bool
	Log          *xlog.Logger
}

MeshParams configure NewMesh.

type Params

type Params struct {
	Client   *api.Client
	Log      *xlog.Logger
	Identity Identity
	Manifest *backplanev1.Manifest
	// Register in the catalog; false when the deployment registers.
	Register bool
	// Tags of the catalog registration.
	Tags  []string
	Check Check
	// SessionTTL of the session holding the instance state; 0 is 30s,
	// clamped to Consul's 10s..24h. Renewed every TTL/3; renewals failing
	// for TTL/2 re-establish the presence.
	SessionTTL time.Duration
	// Config may be nil.
	Config ConfigState
	// Nodes reports the author's dependencies; may be nil. Read on every
	// state write and renew tick: a change is published within a renew
	// interval, or at once after Changed.
	Nodes func() []*backplanev1.NodeStatus
	// Transports reports NATS, Temporal and OTLP; may be nil. Consul is
	// added by the presence itself. Read like Nodes.
	Transports func() []*backplanev1.TransportStatus
}

Params of New.

type Presence

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

Presence is a lifecycle component.

func New

func New(p Params) (*Presence, error)

New creates the presence; nothing is sent until Start.

func (*Presence) Changed

func (p *Presence) Changed()

Changed republishes the state now: nodes or transports changed.

func (*Presence) Deregister

func (p *Presence) Deregister(ctx context.Context) error

Deregister marks the instance stopping: it leaves the catalog at once and the state says so, while the session and the state live on until Stop. Call it when the instance stops taking traffic. Best effort: Consul errors are logged.

func (*Presence) Register

func (p *Presence) Register(context.Context) error

Register marks the instance serving: the state says so and the loop registers in the catalog (when the SDK registers), retrying in the background. Call it when the instance takes traffic.

func (*Presence) Start

func (p *Presence) Start(_ context.Context, g node.Group) error

Start publishes the manifest and the instance state (phase starting) in the background, ahead of the author's tree; the catalog registration waits for Register. Retries never block or fail the service.

func (*Presence) Stop

func (p *Presence) Stop(ctx context.Context) error

Stop waits for the presence loop to exit (the node has already cancelled it), then deregisters and destroys the session so the state key disappears. Leaving is best effort: Consul errors are logged.

Jump to

Keyboard shortcuts

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