sd

Documentation

Overview

Package sd provides utilities related to service discovery. That includes the client-side loadbalancer pattern, where a microservice subscribes to a service discovery system in order to reach remote instances; as well as the registrator pattern, where a microservice registers itself in a service discovery system. Implementations are provided for most common systems.

Index

• type DefaultEndpointer
  • func NewEndpointer[Request, Response any](src Instancer, f Factory[Request, Response], logger log.Logger, ...) *DefaultEndpointer[Request, Response]
  • func (de *DefaultEndpointer[Request, Response]) Close()
  • func (de *DefaultEndpointer[Request, Response]) Endpoints() ([]endpoint.Endpoint[Request, Response], error)
• type Endpointer
• type EndpointerOption
  • func InvalidateOnError(timeout time.Duration) EndpointerOption
• type Event
• type Factory
• type FixedEndpointer
  • func (s FixedEndpointer[Request, Response]) Endpoints() ([]endpoint.Endpoint[Request, Response], error)
• type FixedInstancer
  • func (d FixedInstancer) Deregister(ch chan<- Event)
  • func (d FixedInstancer) Register(ch chan<- Event)
  • func (d FixedInstancer) Stop()
• type Instancer
• type Registrar

Types

type DefaultEndpointer

type DefaultEndpointer[Request, Response any] struct {
	// contains filtered or unexported fields
}

DefaultEndpointer implements an Endpointer interface. When created with NewEndpointer function, it automatically registers as a subscriber to events from the Instances and maintains a list of active Endpoints.

func NewEndpointer

func NewEndpointer[Request, Response any](src Instancer, f Factory[Request, Response], logger log.Logger, options ...EndpointerOption) *DefaultEndpointer[Request, Response]

NewEndpointer creates an Endpointer that subscribes to updates from Instancer src and uses factory f to create Endpoints. If src notifies of an error, the Endpointer keeps returning previously created Endpoints assuming they are still good, unless this behavior is disabled via InvalidateOnError option.

func (*DefaultEndpointer[Request, Response]) Close

func (de *DefaultEndpointer[Request, Response]) Close()

Close deregisters DefaultEndpointer from the Instancer and stops the internal go-routine.

func (*DefaultEndpointer[Request, Response]) Endpoints

func (de *DefaultEndpointer[Request, Response]) Endpoints() ([]endpoint.Endpoint[Request, Response], error)

Endpoints implements Endpointer.

type Endpointer

type Endpointer[Request, Response any] interface {
	Endpoints() ([]endpoint.Endpoint[Request, Response], error)
}

Endpointer listens to a service discovery system and yields a set of identical endpoints on demand. An error indicates a problem with connectivity to the service discovery system, or within the system itself; an Endpointer may yield no endpoints without error.

type EndpointerOption

type EndpointerOption func(*endpointerOptions)

EndpointerOption allows control of endpointCache behavior.

func InvalidateOnError

func InvalidateOnError(timeout time.Duration) EndpointerOption

InvalidateOnError returns EndpointerOption that controls how the Endpointer behaves when then Instancer publishes an Event containing an error. Without this option the Endpointer continues returning the last known endpoints. With this option, the Endpointer continues returning the last known endpoints until the timeout elapses, then closes all active endpoints and starts returning an error. Once the Instancer sends a new update with valid resource instances, the normal operation is resumed.

type Event

type Event struct {
	Instances []string
	Err       error
}

Event represents a push notification generated from the underlying service discovery implementation. It contains either a full set of available resource instances, or an error indicating some issue with obtaining information from discovery backend. Examples of errors may include loosing connection to the discovery backend, or trying to look up resource instances using an incorrectly formatted key. After receiving an Event with an error the listenter should treat previously discovered resource instances as stale (although it may choose to continue using them). If the Instancer is able to restore connection to the discovery backend it must push another Event with the current set of resource instances.

type Factory

type Factory[Request, Response any] func(instance string) (endpoint.Endpoint[Request, Response], io.Closer, error)

Factory is a function that converts an instance string (e.g. host:port) to a specific endpoint. Instances that provide multiple endpoints require multiple factories. A factory also returns an io.Closer that's invoked when the instance goes away and needs to be cleaned up. Factories may return nil closers.

Users are expected to provide their own factory functions that assume specific transports, or can deduce transports by parsing the instance string.

type FixedEndpointer

type FixedEndpointer[Request, Response any] []endpoint.Endpoint[Request, Response]

FixedEndpointer yields a fixed set of endpoints.

func (FixedEndpointer[Request, Response]) Endpoints

func (s FixedEndpointer[Request, Response]) Endpoints() ([]endpoint.Endpoint[Request, Response], error)

Endpoints implements Endpointer.

type FixedInstancer

type FixedInstancer []string

FixedInstancer yields a fixed set of instances.

func (FixedInstancer) Deregister

func (d FixedInstancer) Deregister(ch chan<- Event)

Deregister implements Instancer.

func (FixedInstancer) Register

func (d FixedInstancer) Register(ch chan<- Event)

Register implements Instancer.

func (FixedInstancer) Stop

func (d FixedInstancer) Stop()

Stop implements Instancer.

type Instancer

type Instancer interface {
	Register(chan<- Event)
	Deregister(chan<- Event)
	Stop()
}

Instancer listens to a service discovery system and notifies registered observers of changes in the resource instances. Every event sent to the channels contains a complete set of instances known to the Instancer. That complete set is sent immediately upon registering the channel, and on any future updates from discovery system.

type Registrar

type Registrar interface {
	Register()
	Deregister()
}

Registrar registers instance information to a service discovery system when an instance becomes alive and healthy, and deregisters that information when the service becomes unhealthy or goes away.

Registrar implementations exist for various service discovery systems. Note that identifying instance information (e.g. host:port) must be given via the concrete constructor; this interface merely signals lifecycle changes.