consul

package module
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Nov 27, 2018 License: MIT Imports: 24 Imported by: 6

README

consul-go CircleCI Go Report Card GoDoc

Motivations

Consul being built in Go it already has pretty good client library support, however the package was written a while ago and still lack modern Go features.
This package exposes an API for interacting with a consul agent. It differs from the standard Go package in a couple of ways:

  • The abstractions are not one-to-one translations of the Consul API, instead the package offers building blocks that can be used to interract with Consul.

  • Arguments are passed by value which makes the code easier to manipulate, safer (no risk of dereferencing nil pointers), and greatly reduces the number of dynamic memory allocations.

  • The Client type borrows its design from the net/http package and makes the its use more idiomatic to Go developers.

  • The client methods all support passing a context.Context, allowing finer grain control over requests timeout and cancellations.

Resolver

One of the main features of Consul is service discovery, which means translating a logical service name into a set of network addresses at which clients can access it.
The package offers a high-level abstraction to address this specific use-case with the Resolver type.

package main

import (
    "context"
    "fmt"

    "github.com/segmentio/consul-go"
)

func main() {
    // Queries Consul for a list of addresses where "my-service" is available,
    // the result will be sorted to get the addresses closest to the agent first.
    rslv := &Resolver{
        Near: "_agent",
    }

    addrs, err := rslv.LookupService(context.Background(), "my-service")
    if err != nil {
        fmt.Println(err)
        return
    }

    for _, addr := range addrs {
        fmt.Println(addr)
    }
}

Dialer

Resolving service names to addresses is often times done because the program intends to connect to those services.
The package provides an abstractions of this mechanism with the Dialer type, which mirror the standard net.Dialer to make it an easy drop-in replacement and bring service discovery to existing software.

Here's an example of how the Dialer type can be paired with the standard HTTP client:

package main

import (
    "context"
    "fmt"
    "net/http"
    "os"

    "github.com/segmentio/consul-go"
)

func main() {
    // Replace the DialContext method on the default transport to use consul for
    // all host name resolutions.
    http.DefaultTransport.DialContext = (&consul.Dialer{
        Timeout:   30 * time.Second,
        KeepAlive: 30 * time.Second,
        DualStack: true,
    }).DialContext

    res, err := http.Get("http://my-service/")
    if err != nil {
        fmt.Println(err)
        return
    }

    io.Copy(os.Stdout, res.Body)
    res.Body.Close()
}

Listener

On the other side, services also need to register to consul. While there are ways to automate this using tools like registrator some systems may need to have finer grain control over the metadata attached to the service registration. This is where the Listener type comes into play. It allows the creation of net.Listener values that are automatically registered to Consul.

Here's an example of how the Listener type can be paired with the standard HTTP server:

package main

import (
    "context"
    "fmt"
    "net/http"

    "github.com/segmentio/consul-go"
)

func main() {
    // This listener automatically registers the IP and port that it accepts
    // connections on.
    httpLstn, err := consul.Listen("tcp", ":0")
    if err != nil {
        fmt.Println(err)
        return
    }

    (&http.Server{
        Handler: http.HandlerFunc(func(res http.ResponseWriter, req *http.Request) {
            // ...
        }),
    }).Serve(httpLstn)
}

Transport (HTTP)

The approach of overwritting the dialer in the HTTP transport may not always be ideal because of connection pooling, there will be a sticky effect where all requests going out for a single hostname would hit the same services. This is due to the fact that once the connection is established no more consul lookups are made to resolve service names.
An alternative option is to make a service resolution call for every request, which may resolve to different network addresses and better distribute the load among the pool of available services. The httpconsul package has a decorator that is intended to transparently provide this feature on http.RoundTripper instances.

package main

import (
    "net/http"

    "github.com/segmentio/consul-go/httpconsul"
)

func main() {
    // Wraps the default transport so all service names are looked up in consul.
    // The consul client uses its own transport so there's no risk of recursive
    // loop here.
    http.DefaultTransport = httpconsul.NewTransport(http.DefaultTransport)

    // ...
}

Sessions and Locks

Sessions and Locks have lifetimes, which translates nicely into the Go Context concept. The APIs abstract sessions and locks as contexts, which makes it possible to inject dependencies on Consul Sessions and Locks into any context-aware code.

The synchronization mechanisms come in various locking algorithms (see Lock, and other similar functions). Lock takes a list of keys and blocks until it was able to acquire all of them, the algorithm is designed to prevent deadlocks (by sorting the list of keys and acquiring the locks sequentially).

Here are a couple of examples:

Creating Sessions
// Creates a session in Consul and returns a context associated to it.
// The session is automatically renewed, and destroyed when cancel is called.
//
// If the session gets expired or removed for some reason the context is
// asynchronously canceled.
ctx, cancel := consul.WithSession(context.Background(), consul.Session{
  Name: "my session",
})
Acquiring Locks
// A session is automatically created and attached to the keys, if the session
// expires it also releases the locks which means the returned context would
// get asynchronously canceled. This is great to build algorithms that depend
// on the lock being held and need to abort their execution if they detect that
// they lost ownership of the keys.
ctx, cancel := consul.Lock(context.Background(), "key-1", "key-A")
Chaining dependencies
// This context is canceled after 10 seconds, it's the parent context of the
// session which means it expires the session after 10 seconds.
deadline, cancel := context.WithTimeout(context.Background(), 10*time.Second)
// ...
session, destroy := consul.WithSession(deadline, consul.Session{
  Name: "my session",
})
// By passing the session as parent context we can attach the session to
// multiple locks, if it expires, all those locks are released and their
// contexts are canceled.
lock1, release1 := consul.Lock(session, "key-1")
lock2, release2 := consul.Lock(session, "key-2")

Documentation

Overview

Package consul provides the implementation of a consul client.

Index

Constants

View Source 
const (
	// DefaultAddress is the default consul agent address used when creating a
	// consul client.
	DefaultAddress = "localhost:8500"

	ConsulEnvironment = "CONSUL_HTTP_ADDR"
)

Variables

View Source 
var (
	// DefaultTransport is the default HTTP transport used by consul clients.
	// It differs from the default transport in net/http because we don't want
	// to enable compression, or allow requests to be proxied. The sizes of the
	// connection pool is also tuned to lower numbers since clients usually
	// communicate with their local agent only. Finally the timeouts are set to
	// lower values because the client and agent most likely communicate over
	// the loopback interface.
	DefaultTransport http.RoundTripper = &http.Transport{
		DialContext: (&net.Dialer{
			Timeout: 5 * time.Second,
		}).DialContext,
		DisableCompression:    true,
		MaxIdleConns:          5,
		MaxIdleConnsPerHost:   2,
		IdleConnTimeout:       90 * time.Second,
		TLSHandshakeTimeout:   5 * time.Second,
		ResponseHeaderTimeout: 5 * time.Second,
		ExpectContinueTimeout: 5 * time.Second,
	}

	// DefaultClient is the default client used when none is specified.
	DefaultClient = &Client{
		Address: getConsulAddress(),
	}

	// DefaultUserAgent is the default user agent used by consul clients when
	// none has been set.
	DefaultUserAgent string
)
View Source 
var (
	// DefaultLocker is the default Locker used by the package-level lock
	// management functions.
	DefaultLocker = &Locker{}

	// LocksKey is used to lookup the keys held by a lock from its associated
	// context.
	LocksKey = &contextKey{"consul-locks-key"}

	// Unlocked is the error returned by contexts when the lock they were
	// associated with has been lost.
	Unlocked = errors.New("unlocked")
)
View Source 
var (
	DefaultWatcher = &Watcher{
		MaxAttempts:    defMaxAttempts,
		InitialBackoff: defInitialBackoff,
		MaxBackoff:     defMaxBackoff,
	}

	// WatchTransport is the same as DefaultTransport with a longer
	// ResponseHeaderTimeout.  This is copied from DefaultTransport.  We don't
	// do an actual copy because the Transport uses mutexes.  copied mutexes
	// are ineffective.  You will panic on concurrent map access if running
	// with other clients without instantiating a new transport for watch.
	WatchTransport http.RoundTripper = &http.Transport{
		DialContext: (&net.Dialer{
			Timeout: 5 * time.Second,
		}).DialContext,
		DisableCompression:    true,
		MaxIdleConns:          5,
		MaxIdleConnsPerHost:   2,
		IdleConnTimeout:       90 * time.Second,
		TLSHandshakeTimeout:   5 * time.Second,
		ResponseHeaderTimeout: 1 * time.Minute,
		ExpectContinueTimeout: 5 * time.Second,
	}
)
View Source 
var DefaultAgent = &Agent{}

DefaultAgent is an agent configured to expose the agent information of the consul agent that the default client connects to.

View Source 
var DefaultCatalog = &Catalog{}

DefaultCatalog is a catalog configured to use the default client.

View Source 
var DefaultResolver = &Resolver{
	OnlyPassing: true,
	Cache:       &ResolverCache{Balancer: MultiBalancer(defaultCacheBalancer(), &Shuffler{})},
	Blacklist:   &ResolverBlacklist{},
	Balancer:    &LoadBalancer{New: func() Balancer { return &RoundRobin{} }},
	Sort:        WeightedShuffleOnRTT,
}

DefaultResolver is the Resolver used by a Dialer when non has been specified.

View Source 
var DefaultTomography = &Tomography{}

DefaultTomography is used as the default Tomography instance when

View Source 
var (
	// SessionKey is the key at which the Session value is stored in a context.
	SessionKey = &contextKey{"consul-session"}
)

Functions

func Dial 

func Dial(network string, address string) (net.Conn, error)

Dial is a wrapper for calling (*Dialer).Dial on a default dialer.

func DialContext 

func DialContext(ctx context.Context, network string, address string) (net.Conn, error)

DialContext is a wrapper for calling (*Dialer).DialContext on a default dialer.

func Distance 

func Distance(a Coordinates, b Coordinates) time.Duration

Distance computes the approximate RTT between two Consul coordinates.

The algorithm was taken from: https://www.consul.io/docs/internals/coordinates.html#working-with-coordinates

func ListServices 

func ListServices(ctx context.Context) (map[string][]string, error)

ListServices is a helper function that delegates to the default catalog.

func Listen 

func Listen(network string, address string) (net.Listener, error)

Listen creates a listener that accept connections on the given network and address, and registers to consul using the default client.

func ListenContext 

func ListenContext(ctx context.Context, network string, address string) (net.Listener, error)

ListenContext creates a listener that accept connections on the given network and address, and registers to consul use the default client.

The context may be used to asynchronously cancel the consul registration.

func Lock 

func Lock(ctx context.Context, keys ...string) (context.Context, context.CancelFunc)

Lock calls DefaultLocker.Lock.

func LookupHost 

func LookupHost(ctx context.Context, name string) ([]string, error)

LookupHost is a wrapper around the default resolver's LookupHost method.

func Shuffle 

func Shuffle(list []Endpoint)

Shuffle is a sorting function that randomly rearranges the list of endpoints.

func TryLockOne 

func TryLockOne(ctx context.Context, keys ...string) (context.Context, context.CancelFunc)

TryLockOne calls DefaultLocker.TryLockOne.

func Watch 

func Watch(ctx context.Context, key string, handler WatcherFunc)

Watch is the package-level Watch definition which is called on DefaultWatcher.

func WatchPrefix 

func WatchPrefix(ctx context.Context, prefix string, handler WatcherFunc)

WatchPrefix is the package-level WatchPrefix definition which is called on DefaultWatcher.

func WeightRTT 

func WeightRTT(endpoint Endpoint) float64

WeightRTT returns the weight of the given endpoint based on it's RTT value.

func WeightedShuffle 

func WeightedShuffle(list []Endpoint, weightOf func(Endpoint) float64)

WeightedShuffle is a sorting function that randomly rearranges the list of endpoints, using the weightOf function to obtain the weight of each endpoint of the list.

func WeightedShuffleOnRTT 

func WeightedShuffleOnRTT(list []Endpoint)

WeightedShuffleOnRTT is a sorting function that randomly rearranges the list of endpoints, using the RTT as a weight to increase the chance of endpoints with low RTT to be placed at the front of the list.

func WithSession 

func WithSession(ctx context.Context, session Session) (context.Context, context.CancelFunc)

WithSession constructs a copy of the context which is attached to a newly created session.

Types

type Agent 

type Agent struct {
	// Client
	Client *Client

	// Configures how often the state is updated. If zero, the state is updated
	// every second.
	CacheTimeout time.Duration
	// contains filtered or unexported fields
}

Agent exposes methods to get information about the agent that a client is configured to connect to.

func (*Agent) NodeName 

func (a *Agent) NodeName(ctx context.Context) (string, error)

NodeName fetches the name of the node that the consul agent is running on.

type Balancer 

type Balancer interface {
	// Balance is called with a service name and a list of endpoints that this
	// name resolved to, and returns the potentially modified list of endpoints
	// sorted by preference.
	//
	// The returned slice of endpoints may or may not be the same slice than the
	// one that was passed to the method, the balancer implementation is allowed
	// to perform in-place modifications of the endpoints slice, applications
	// must take into consideration that the balancer ownes the slice for the
	// duration of the method call.
	//
	// Balance must not retain the slice of endpoints it received, nor the one
	// it returned.
	Balance(name string, endpoints []Endpoint) []Endpoint
}

Balancer is the interface implemented by types that provides load balancing algorithms for a Resolver.

Balancers must be safe to use concurrently from multiple goroutines.

func MultiBalancer 

func MultiBalancer(balancers ...Balancer) Balancer

MultiBalancer composes a new Balancer from a list of multiple balancers, each of them being called for each Balance call in the order that they were given to the function.

func PreferEC2AvailabilityZone 

func PreferEC2AvailabilityZone(c *http.Client) Balancer

PreferEC2AvailabilityZone is a constructor for a balancer which prefers routing traffic to services registered in the same EC2 availability zone than the caller.

If the metadata aren't available the function returns the NullBalancer balancer which doesn't modify the list of endpoints.

type BalancerFunc 

type BalancerFunc func(string, []Endpoint) []Endpoint

BalancerFunc allows regular functions to be used as balancers.

func (BalancerFunc) Balance 

func (f BalancerFunc) Balance(name string, endpoints []Endpoint) []Endpoint

Balance calls f, satisfies the Balancer interface.

type Catalog 

type Catalog struct {
	// The client used by the catalog, which may be nil to indicate that a
	// default client should be used.
	Client *Client
}

Catalog exposes methods to interract with the consul catalog.

func (*Catalog) ListServices 

func (c *Catalog) ListServices(ctx context.Context) (services map[string][]string, err error)

ListServices returns the list of services registered to consul as a map of service names to the list of known tags for that service.

type Client 

type Client struct {
	// Address of the consul agent this client sends requests to.
	// DefaultAddress is used if this field is empty.
	Address string

	// UserAgent may be set to any string which identify who the client is.
	UserAgent string

	// Datacenter may be set to configure which consul datacenter the client
	// sends requests for.
	// If Datacenter is an empty string the agent's default is used.
	Datacenter string

	// Transport is the HTTP transport used by the client to send requests to
	// its agent.
	// If Transport is nil then DefaultTransport is used instead.
	Transport http.RoundTripper
}

A Client exposes an API for communicating with a consul agent.

The properties of a client are only read by its method, it is therefore safe to use a client concurrently from multiple goroutines.

Clients are safe to used concurrently from multiple goroutines after they were first constructed.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, path string, query Query, recv interface{}) error

Delete sends a DELETE request to the consul agent.

See (*Client).Do for the full documentation.

func (*Client) Do 

func (c *Client) Do(ctx context.Context, method string, path string, query Query, send interface{}, recv interface{}) (err error)

Do sends a request to the consul agent. The method, path, and query arguments represent the API call being made. The send argument is the value sent in the body of the request, which is usually of struct type, or nil if the request has an empty body. The recv argument should be a pointer to a type which matches the format of the response, or nil if no response is expected.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, path string, query Query, recv interface{}) error

Get sends a GET request to the consul agent.

See (*Client).Do for the full documentation.

func (*Client) Put 

func (c *Client) Put(ctx context.Context, path string, query Query, send interface{}, recv interface{}) error

Put sends a PUT request to the consul agent.

See (*Client).Do for the full documentation.

type Coordinates 

type Coordinates struct {
	Adjustment float64
	Error      float64
	Height     float64
	Vec        [8]float64
}

The Coordinates type represents network coordinates of nodes in a consul system.

More information can be found at: https://www.consul.io/docs/internals/coordinates.html

type Dialer 

type Dialer struct {
	Timeout       time.Duration
	Deadline      time.Time
	LocalAddr     net.Addr
	DualStack     bool
	FallbackDelay time.Duration
	KeepAlive     time.Duration
	BlacklistTTL  time.Duration
	Resolver      *Resolver
}

The Dialer type mirrors the net.Dialer API but uses consul to resolve service names to network addresses instead of DNS.

The Dialer always ignores ports specified in the addreses that it's trying to connect to and uses the ports looked up from consul instead, unless it was given and address which is a valid IP representation in which case it does not resolve the service name and directly establish the connection.

For a full description of each of the fields please refer to the net.Dialer documentation at https://golang.org/pkg/net/#Dialer.

func (*Dialer) Dial 

func (d *Dialer) Dial(network string, address string) (net.Conn, error)

Dial establishes a network connection to address, using consul to resolve the address if necessary.

For a full description of the method's behavior please refer to the (*net.Dialer).Dial documentation at https://golang.org/pkg/net/#Dialer.Dial.

func (*Dialer) DialContext 

func (d *Dialer) DialContext(ctx context.Context, network string, address string) (net.Conn, error)

DialContext establishes a network connection to address, using consul to resolve the address if necessary.

For a full description of the method's behavior please refer to the (*net.Dialer).Dialcontext documentation at https://golang.org/pkg/net/#Dialer.DialContext.

type Endpoint 

type Endpoint struct {
	// The ID under which the service was registered.
	ID string

	// The node name that the endpoint belongs to.
	Node string

	// The network address at which the service can be reached.
	Addr net.Addr

	// The list of tags associated with the service.
	Tags []string

	// The set of metadata associated with the node on which the service is
	// running.
	Meta map[string]string

	// RTT is an estimation of the round-trip-time between the node specified by
	// Resolver.Agent and the endpoint (may be zero if the information wasn't yet
	// available).
	RTT time.Duration
	// contains filtered or unexported fields
}

An Endpoint represents the address at which a service is available, coupled with the metadata associated with the service registration.

func LookupService 

func LookupService(ctx context.Context, name string) ([]Endpoint, error)

LookupService is a wrapper around the default resolver's LookupService method.

type KeyData 

type KeyData struct {
	CreateIndex int64
	ModifyIndex int64
	Key         string
	Flags       int64
	Value       []byte
	Session     SessionID
}

KeyData is a representation of a key in Consul, which follows the structure documented at https://www.consul.io/api/kv.html#read-key

type Listener 

type Listener struct {
	// The Client used to register the listener to a consul agent. If nil, the
	// default client is used instead.
	Client *Client

	// A unique identifier for the service registered to consul. This only needs
	// to be unique within the agent that the service registers to, and may be
	// omitted. In that case, ServiceName is used instead.
	// This value is appended to ServiceName using ':' as separator to create a
	// unique ID for the listener within a set of services with the same name.
	ServiceID string

	// The logical name of the service registered to consul. If none is set, the
	// program name is used instead.
	ServiceName string

	// A list of tags to set on the service registered to consul.
	ServiceTags []string

	// If non-nil, specifies the address under which the service will be
	// registered to consul. This is useful when running within a container for
	// example, where the program may not have access to the external address to
	// which clients should connect to in order to reach the service.
	// By default, the address that new listeners accept connections on is used.
	ServiceAddress net.Addr

	// Configures whether registering the service with specific tags should
	// overwrite existing values.
	ServiceEnableTagOverride bool

	// If the listener is intended to be used to serve HTTP connection this
	// field may be set to the path that consul should query to health check
	// the service.
	CheckHTTP string

	// CheckInterval is the time interval set on the TCP check that is
	// registered to consul along with the service. Defaults to 10 seconds.
	CheckInterval time.Duration

	// Amount of time after which a service that is reported critical should be
	// automatically deregistered. Defaults to never.
	CheckDeregisterCriticalServiceAfter time.Duration
}

The Listener type contains options to create listeners that automatically register to consul.

func (*Listener) Listen 

func (l *Listener) Listen(network string, address string) (net.Listener, error)

Listen creates a new listener that accepts network connections on the given address, and automatically registers to consul.

func (*Listener) ListenContext 

func (l *Listener) ListenContext(ctx context.Context, network string, address string) (net.Listener, error)

ListenContext creates a new listener that accepts network connections on the given address, and automatically registers to consul.

The context may be used to asynchronously cancel the consul registration.

func (*Listener) Register 

func (l *Listener) Register(ctx context.Context, lstn net.Listener) (net.Listener, error)

Register registers the given listener to consul and returns a decorated version of it which deregisters when the service from consul when it's closed.

The given listener is not closed when registration fails.

type LoadBalancer 

type LoadBalancer struct {
	// Constructs the balancing algorithm used by this load balancer.
	//
	// The function cannot be nil or calling the LoadBalancer's Balance method
	// will panic.
	New func() Balancer
	// contains filtered or unexported fields
}

A LoadBalancer is an implementation of Balancer which maintains a set of balancers that are local to each service name that Balance has been called for. It enables using simple load balancing algorithms that are designed to work on a set of endpoints belonging to a single service (like RoundRobin) in the context of the Resolver which may be used to

func (*LoadBalancer) Balance 

func (lb *LoadBalancer) Balance(name string, endpoints []Endpoint) []Endpoint

Balance satisfies the Balancer interface.

type Locker 

type Locker struct {
	// The client used to send requests to the consul agent. If nil, the default
	// client is used instead.
	Client *Client

	// A key prefix to apply to all operations made on this locker.
	Keyspace string

	// LockDelay is the amount of time that a lock will stay held if it hasn't
	// been released and the session that was attached to it expired.
	LockDelay time.Duration

	// The behavior to used when releasing a lock (default to Release).
	UnlockBehavior SessionBehavior
}

A Locker exposes methods for acquiring locks on keys of the consul key/value store.

func (*Locker) Lock 

func (l *Locker) Lock(ctx context.Context, keys ...string) (context.Context, context.CancelFunc)

Lock acquires locks on the given keys. The method blocks until the locks were acquired, or the context was canceled. The returned context will be canceled when the locks are released (by calling the cancellation function), or if the ownership was lost, in this case the contexts' Err method returns Unlocked.

func (*Locker) TryLockOne 

func (l *Locker) TryLockOne(ctx context.Context, keys ...string) (context.Context, context.CancelFunc)

TryLockOne attempts to acquire a lock on one of the given keys. The returned context will be canceled when the lock is released (by calling the cancellation function), or if the ownership was lost, in this case the context's Err method returns Unlocked. The method never blocks, if it fails to acquire any of the locks it returns a canceled context.

type LookupServiceFunc 

type LookupServiceFunc func(context.Context, string) ([]Endpoint, error)

LookupServiceFunc is the signature of functions that can be used to lookup service names.

type NodeCoordinates 

type NodeCoordinates map[string]Coordinates

NodeCoordinates is a mapping of node names to their consul coordinates.

func (NodeCoordinates) Distance 

func (coords NodeCoordinates) Distance(nodeA string, nodeB string) (time.Duration, bool)

Distance computes the approximate RTT between two nodes of coords. The second return value is true if both nodes existed in the map, false otherwise.

type NullBalancer 

type NullBalancer struct{}

NullBalancer is a balancer which doesn't modify the list of endpoints.

func (*NullBalancer) Balance 

func (*NullBalancer) Balance(name string, endpoints []Endpoint) []Endpoint

Balance satisfies the Balancer interface.

type Param 

type Param struct {
	Name  string
	Value string
}

Param represents a single item in a query string.

type PreferTags 

type PreferTags []string

PreferTags is a balancer which groups endpoints that match certain tags. The tags are ordered by preference, so endpoints matching the tag at index zero will be placed at the head of the result list.

The result slice is also truncated to return only endpoints that matched at least one tag, unless this would end up returning an empty slice, in which case the balancer simply returns the full endpoints list.

func (PreferTags) Balance 

func (tags PreferTags) Balance(name string, endpoints []Endpoint) []Endpoint

Balance satisfies the Balancer interface.

type Query 

type Query []Param

Query is a representation of a URL query string as a list of parameters.

func (*Query) Add 

func (q *Query) Add(new Param)

func (Query) String 

func (q Query) String() string

String satisfies the fmt.Stringer interface.

func (Query) Values 

func (q Query) Values() url.Values

Values converts q to a url.Values.

type Resolver 

type Resolver struct {
	// The client used by the resolver, which may be nil to indicate that a
	// default client should be used.
	Client *Client

	// A list of service tags used to filter the result set. Only addresses of
	// services that match those tags will be returned by LookupService.
	ServiceTags []string

	// A set of key/value pairs used to filter the result set. Only addresses of
	// nodes that have matching metadata will be returned by LookupService.
	NodeMeta map[string]string

	// If set to true, the resolver only returns services that are passing their
	// health checks.
	OnlyPassing bool

	// If set to true, allow any server to serve the requests (not only the
	// leader).
	AllowStale bool

	// If set to true, allow the agent to serve the requests from its local
	// cache instead of forwarding the requests to the servers.
	AllowCached bool

	// If set to true, disable fetching the node coordinates when looking up
	// service endpoints.
	DisableCoordinates bool

	// Cache used by the resolver to reduce the number of round-trips to consul.
	// If set to nil then no cache is used.
	//
	// ResolverCache instances should not be shared by multiple resolvers
	// because the cache uses the service name as a lookup key, but the resolver
	// may apply filters based on the values of the ServiceTags, NodeMeta, and
	// OnlyPassing fields.
	Cache *ResolverCache

	// This field may be set to allow the resolver to support temporarily
	// blacklisting addresses that are known to be unreachable.
	Blacklist *ResolverBlacklist

	// Agent is used to set the origin from which the distance to each endpoints
	// are computed. If nil, DefaultAgent is used instead.
	Agent *Agent

	// Tomography is used when Agent is set to compute the distance from the
	// agnet to the endpoints. If nil, DefaultTomography is used instead.
	Tomography *Tomography

	// The balancer is used to reorder the list of endpoints returned by the
	// resolver when looking up services.
	//
	// This field takes precedence over Sort, to use a simple sorting function,
	// set the value to nil.
	Balancer Balancer

	// Sort is called to order the list of endpoints returned by the resolver.
	// Setting this field to nil means no ordering of the endpoints is done.
	//
	// If the resolver is intended to be used to distribute load across a pool
	// of services it is important to set a Sort function that shuffles the list
	// of endpoints, otherwise consecutive calls would likely return the list in
	// the same order, and picking the first item would result in routing all
	// traffic to a single instance of the service.
	//
	// DEPRECATED: use Balancer instead.
	Sort func([]Endpoint)
}

A Resolver is a high-level abstraction on top of the consul service discovery API.

The zero-value is a valid Resolver that uses DefaultClient to query the consul agent.

func (*Resolver) LookupHost 

func (rslv *Resolver) LookupHost(ctx context.Context, name string) ([]string, error)

LookupHost resolves a service name to a list of network addresses.

The method name is a bit misleading because it uses the term Host but accepts a service name as argument, this is done to match the signature of the net.(*Resolver).LookupHost method so the types can satisfy the same interface.

func (*Resolver) LookupService 

func (rslv *Resolver) LookupService(ctx context.Context, name string) ([]Endpoint, error)

LookupService resolves a service name to a list of endpoints using the resolver's configuration to narrow and sort the result set.

func (*Resolver) LookupServiceInto 

func (rslv *Resolver) LookupServiceInto(ctx context.Context, name string, list []Endpoint) ([]Endpoint, error)

LookupServiceInto resolves a service name to a list of endpoints using the resolver's configuration to narrow and sort the result set. It uses the provided slice to store the results, if it has a large enough capacity.

type ResolverBlacklist 

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

ResolverBlacklist implements a negative caching for Resolver instances. It works by registering addresses that should be filtered out of a service name resolution result, with a deadline at which the address blacklist will expire.

func (*ResolverBlacklist) Blacklist 

func (blacklist *ResolverBlacklist) Blacklist(addr net.Addr, expireAt time.Time)

Blacklist adds a blacklisted address, which expires and expireAt is reached.

func (*ResolverBlacklist) Filter 

func (blacklist *ResolverBlacklist) Filter(endpoints []Endpoint, now time.Time) []Endpoint

Filter takes a slice of endpoints and the current time, and returns that same slice trimmed, where all blacklisted addresses have been filtered out.

type ResolverCache 

type ResolverCache struct {
	// The maximum age of cache entries. If zero, a default value of 1 second is
	// used.
	CacheTimeout time.Duration

	// A balancer used by the cache to potentially filter or reorder endpoints
	// from the resolved names before caching them.
	Balancer Balancer
	// contains filtered or unexported fields
}

The ResolverCache type provides the implementation of a caching layer for service name resolutions.

Instances of ResolverCache are save to use concurrently from multiple goroutines.

func (*ResolverCache) LookupService 

func (cache *ResolverCache) LookupService(ctx context.Context, name string, lookup LookupServiceFunc) ([]Endpoint, error)

LookupService resolves a service name by fetching the address list from the cache, or calling lookup if the name did not exist.

func (*ResolverCache) LookupServiceInto 

func (cache *ResolverCache) LookupServiceInto(ctx context.Context, name string, list []Endpoint, lookup LookupServiceFunc) ([]Endpoint, error)

LookupServiceInto resolves a service name by fetching the address list from the cache, or calling lookup if the name did not exist. The results are stored in the provided list value, if it has a large enough capacity.

type Rotator 

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

Rotator is the implementation of a load balancing algorithms similar to RoundRobin but which returns the full list of endpoints instead of a single one.

Using this balancer is useful to take advantage of the automatic retry logic implemented in the dialer or http transport.

func (*Rotator) Balance 

func (rr *Rotator) Balance(name string, endpoints []Endpoint) []Endpoint

Balance satisfies the Balancer interface.

type RoundRobin 

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

RoundRobin is the implementation of a simple load balancing algorithms which chooses and returns a single endpoint of the input list in a round robin fashion.

func (*RoundRobin) Balance 

func (rr *RoundRobin) Balance(name string, endpoints []Endpoint) []Endpoint

Balance satisfies the Balancer interface.

type Session 

type Session struct {
	// The client used to create the session.
	Client *Client

	// A human-readable name for the session (optional).
	Name string

	// The session ID, this should not be set when creating the session but it
	// may be read from the context associated with the session.
	ID SessionID

	// The behavior to apply to keys associated with the session when the
	// session expires.
	//
	// If unset, uses Release.
	Behavior SessionBehavior

	// LockDelay is the amount of time that a lock will stay held if it hasn't
	// been released and the session that was attached to it expired.
	//
	// If zero, 15 seconds is used.
	LockDelay time.Duration

	// The time-to-live of the session, a session automatically expires if it
	// hasn't been renewed for longer than its TTL.
	//
	// If zero, uses 2 x LockDelay.
	TTL time.Duration
}

Session carries a session configuration, it is used in the WithSession function to customize the session properties.

type SessionBehavior 

type SessionBehavior string

SessionBehavior is an enumeration repesenting the behaviors of session expirations. 

const (
	// Release describes the release behavior, locks are released on keys
	// associated with an expired session.
	Release SessionBehavior = "release"

	// Delete describes the delete behavior, keys are deleted when the session
	// that hold a lock on them expires.
	Delete SessionBehavior = "delete"
)

type SessionID 

type SessionID string

SessionID is a type representing unique session identifiers.

type Shuffler 

type Shuffler struct{}

Shuffler is a Balancer implementation which returns a randomly shuffled list of endpoints.

func (*Shuffler) Balance 

func (*Shuffler) Balance(name string, endpoints []Endpoint) []Endpoint

Balance satsifies the Balancer interface.

type Store 

type Store struct {
	// The client used to send requests to the consul agent.
	Client *Client

	// A key prefix to apply to all operations made on this store.
	Keyspace string

	// Allow read operations to hit any consul servers, not just the leader.
	AllowStale bool
}

A Store exposes an API to interract with the consul key/value store.

func (*Store) Delete 

func (store *Store) Delete(ctx context.Context, prefix string, index int64) (ok bool, err error)

Delete deletes the keys stored under the given prefix. If index is set to a positive value, it is used to turn the delete call into a compare-and-swap operation where the keys are only deleted if the last index that modified them matches the given index.

The method returns a boolean to indicate whether the keys could be deleted.

func (*Store) Read 

func (store *Store) Read(ctx context.Context, key string) (value io.ReadCloser, index int64, err error)

Read reads the value of the given key, returning it as a pair of an io.ReadCloser and value of the last index that modified the key.

The program must close the value when it's done reading from it to prevent any leak of internal resources.

func (*Store) ReadValue 

func (store *Store) ReadValue(ctx context.Context, key string, ptr interface{}) (index int64, err error)

ReadValue reads the JSON-encoded value at the given key into ptr. The usual unmarshaling rules apply.

See Read for more details on the method.

func (*Store) Session 

func (store *Store) Session(ctx context.Context, key string) (session Session, err error)

Session return the session used to lock the given key. It returns an error if the key is not locked or does not exist.

func (*Store) Tree 

func (store *Store) Tree(ctx context.Context, prefix string) (keys []string, err error)

Tree recursively scans the given key prefix in the consul key/value store, returning the list of keys as a slice of strings.

If the consul key/value store contains a large number of keys under the given prefix, one may prefer to use the Walk method to iterate through the keys without loading them all in memory.

func (*Store) Walk 

func (store *Store) Walk(ctx context.Context, prefix string, walk func(key string) error) (err error)

Walk traverses the keyspace under the given prefix, calling the walk function and passing each key.

If the walk function returns an error the iteration is stopped and the error is returned by Walk.

func (*Store) WalkData 

func (store *Store) WalkData(ctx context.Context, prefix string, walk func(data KeyData) error) (err error)

WalkData traverses the keyspace under the given prefix, calling the walk function and passing each key's data

If the walk function returns an error the iteration is stopped and the error is returned by WalkData

func (*Store) Write 

func (store *Store) Write(ctx context.Context, key string, value io.ReadCloser, index int64) (ok bool, err error)

Write writes bytes from value at the given key in the consul key/value store.

If index is set to a positive value, it is used to turn the write call into a compare-and-swap operation. The value will only be updated if the last index that modified the key matches the given index.

If the given context inherits from a lock, the associated session is used to allow the write operation to succeed.

The method returns a boolean that indicates whether the write operation succeeded, it would return false if the key was locked by another session or if index was specified but was different in consul.

The value is always closed by a call to Write, even if the method returns an error.

func (*Store) WriteValue 

func (store *Store) WriteValue(ctx context.Context, key string, value interface{}, index int64) (ok bool, err error)

WriteValue writes the JSON representation of value at the given key. The usual marshaling rules apply.

See Write for more details on the method.

type Tomography 

type Tomography struct {
	// The Client used to send requests to a consul agent.
	Client *Client

	// Configures how often the state is updated. If zero, the state is updated
	// every second.
	CacheTimeout time.Duration
	// contains filtered or unexported fields
}

Tomography exposes methods to fetch network coordinates information from consul.

The Tomography implementation uses an internal cache of node coordinates that is updated asynchronously and fully non-blocking (except for the very first call which has to initialize the cache).

Methods of Tomography are safe to use concurrently from multiple goroutines, assuming the fields aren't being modified after the value was constructed.

func (*Tomography) NodeCoordinates 

func (t *Tomography) NodeCoordinates(ctx context.Context) (NodeCoordinates, error)

NodeCoordinates returns the current coordinates of all nodes in the consul datacenter.

type Watcher 

type Watcher struct {
	Client *Client
	// MaxAttempts limits the number of subsequent failed API calls before
	// bailing out of the watch. Defaults to 10.
	MaxAttempts int

	// InitialBackoff is the amount of time to wait on the initial backoff when
	// an error occurs. Backoff durations are subsequently increased exponentially
	// while less than MaxBackoff. Defaults to 1s.
	InitialBackoff time.Duration

	// MaxBackoff limits the maximum time to wait when doing exponential backoff
	// after encountering errors. Defaults to 30s.
	MaxBackoff time.Duration
}

Watcher is the struct upon which Watch and WatchPrefix are built.

func (*Watcher) Watch 

func (w *Watcher) Watch(ctx context.Context, key string, handler WatcherFunc)

Watch executes a long poll for changes to the given key. handler will be called immediately upon registration to initialize the watch and returns the initial value (as a list, this is what Consul API returns). In cases where the key is being rapidly updated, there is a chance that Watch can miss intermediate updates due to the way the API is implemented. However, Watch will always converge on the most recent value. See https://github.com/hashicorp/consul/issues/1761 for details.

func (*Watcher) WatchPrefix 

func (w *Watcher) WatchPrefix(ctx context.Context, prefix string, handler WatcherFunc)

WatchPrefix executes a long poll for changes to anything under the given prefix. handler will be called immediately upon registration to initialize the watch and returns the initial value (as a list, this is what Consul API returns). In cases where children of prefix are being rapidly updated, there is a chance that WatchPrefix can miss intermediate updates due to the way the API is implemented. However, WatchPrefix will always converge on the most recent values. See https://github.com/hashicorp/consul/issues/1761 for details.

type WatcherFunc 

type WatcherFunc func([]KeyData, error)

WatcherFunc is the function signature for the callback from watch. It passes a list of KeyData representing the most recent value or values stored at the key or everything below the prefix. It can be nil. error is passed through to the handler if it is not Temporary. Caller is responsible for stopping the watch via canceling the context and implementing back off logic. If the error is temporary, it will not pass it through to the WatcherFunc unless MaxAttempts was hit.

type WeightedShuffler 

type WeightedShuffler struct {
	// WeightOf returns the weight of an endpoint.
	WeightOf func(Endpoint) float64
}

WeightedShuffler is a Balancer implementation which shuffles the list of endpoints using a different weight for each endpoint.

func (*WeightedShuffler) Balance 

func (ws *WeightedShuffler) Balance(name string, endpoints []Endpoint) []Endpoint

Balance satisfies the Balancer interface.

Source Files

View all Source files

Directories

Path Synopsis
Package httpconsul provides extensions to integrate the standard net/http package with consul.
 Package httpconsul provides extensions to integrate the standard net/http package with consul.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.