consulapi

README

consulapi

A consul client for the rest of us.

About

consulapi is a consul client library for Go programs, targeted at the "99% use case". While an official Go client provided by Hashicorp exists and exposes the complete functionality of consul, it is sometimes difficult to use and is always extremely painful to work with in tests.

This consul client library for Go aims to be easily mockable, and provides interfaces that are very easy to understand.

Install

Like any go library, just use go get to install. If the Go team ever officially blesses a package manager, we'll switch to that.

go get github.com/shoenig/consulapi

Usage

Creating a client is very simple - just call New with the desired ClientOptions.

options := consulapi.ClientOptions{
    Address: "http://localhost:8500", // default
    HTTPTimeout: 10 * time.Seconds, // default
    SkipTLSVerification: false, // http used by default
 }

client := consulapi.New(options)
// client implements the consulapi.Client interface

members, err := client.Members()
// etc ...

Design

A few factors contribute to the simplicity of consulapi.

First, we export interfaces instead of concrete implementations. This enabled both re-implementations if necessary, as well enables the use of mocks in testing. A mock implementation of the Client interface is automatically generated and provided in the consulapitest package.

Second, the nature of the key-value store is significantly limited. consulapi enforces a strongly opinionated design that all keys and values must be strings, and that all keys may only be / separated. This cuts down on a lot of type casting overhead.

Third, the source code itself is intended to be easy to read and understand. It is centered around common http method calls, with the intent of being a reduced reflection of the HTTP API.

Documentation

Index

• Constants
• type Agent
• type AgentInfo
• type AsLeaderFunc
• type Candidate
• type Catalog
• type Client
  • func New(opts ClientOptions) Client
• type ClientOptions
• type KV
• type LeaderSession
• type LeadershipConfig
• type Node
• type NodeInfo
• type RequestError
  • func (h *RequestError) Error() string
  • func (h *RequestError) StatusCode() int
• type Service
• type Session
• type SessionConfig
• type SessionID
• type SessionTerminationBehavior

Constants

const (
	SessionRelease SessionTerminationBehavior = "release"
	SessionDelete  SessionTerminationBehavior = "delete"

	SessionMinimumTTL = 10 * time.Second
	SessionMaximumTTL = 86400 * time.Second

	SessionMinimumLockDelay = 0 * time.Second
	SessionMaximumLockDelay = 60 * time.Second
)

Types

type Agent

type Agent interface {
	Self() (AgentInfo, error)
	Members(wan bool) ([]AgentInfo, error)
	Reload() error
	MaintenanceMode(enabled bool, reason string) error
}

Agent provides an interface to information about the consul agent that is being communicated with.

type AgentInfo

type AgentInfo struct {
	Name    string            `json:"Name"`
	Address string            `json:"Addr"`
	Port    int               `json:"Port"`
	Tags    map[string]string `json:"Tags"`
}

An AgentInfo contains information about a particular consul agent.

type AsLeaderFunc

type AsLeaderFunc func(context.Context) error

AsLeaderFunc is executed when the client is able to acquire the underlying consul leader lock. When a value is sent on context.Done, this client is no longer the elected leader and must cease any operations that require leadership. A reasonable implementation will return from the function as soon as possible context cancellation.

If the implementation returns from the function before the context is cancelled, leadership will be abdicated, the context will be cancelled, and no further action should be taken until elected leader again.

type Candidate

type Candidate interface {
	Participate(LeadershipConfig, AsLeaderFunc) (LeaderSession, error)
}

A Candidate implementation is able to Participate in leadership elections.

type Catalog

type Catalog interface {
	// Datacenters will return the list of datacenters that
	// are members of the gossip ring known by the consul agent.
	Datacenters() ([]string, error)

	// Nodes will return the list of nodes in dc.
	Nodes(dc string) ([]Node, error)

	// Node will return detailed meta information associated
	// a particular node in dc.
	Node(dc, name string) (NodeInfo, error)

	// Services will return a list of names of services
	// in dc, along with the associated tags for each service.
	Services(dc string) (map[string][]string, error)

	// Service returns detailed meta information about a particular
	// named service, in dc, which matches all of the listed tags.
	Service(dc, service string, tags ...string) ([]Service, error)
}

A Catalog represents the consul catalog feature.

type Client

type Client interface {
	Agent
	Catalog
	KV
	Session
	Candidate
}

A Client is used to communicate with consul. The interface is composed of other interfaces, which reflect the different categories of API supported by the consul agent.

func New

func New(opts ClientOptions) Client

New creates a new Client that will connect to the configured consul agent.

type ClientOptions

type ClientOptions struct {
	// Address (optional) of the consul agent to communicate with. This value
	// will default to http://localhost:8500 if left unset. This is likely
	// the desired value, as consul is designed to run with an agent on
	// every node.
	Address string

	// HTTPTimeout (optional) configures how long underlying HTTP requests should
	// wait before giving up and returning a timeout error. By default, this value
	// is 10 seconds.
	HTTPTimeout time.Duration

	// SkipTLSVerification configures the underlying HTTP client to ignore
	// any TLS certificate validation errors. This is a hacky option that can
	// be useful for working in environments that are using self-signed
	// certificates. For best security practices, this option should never
	// be used in a production environment.
	SkipTLSVerification bool

	// Token (optional) will be used to authenticate requests to consul.
	Token string

	// Logger may be optionally configured as an output for trace level logging
	// produced internally by the Client. This can be helpful for debugging logic
	// errors in client code.
	Logger *log.Logger
}

ClientOptions are used to configure options of a client upon creation.

type KV

type KV interface {
	// Get will return the value defined at path, for dc.
	Get(dc, path string) (string, error)
	// Put will set value at path, in dc.
	Put(dc, path, value string) error
	// Delete will remove the value at path, in dc.
	Delete(dc, path string) error
	// Keys will list all subpaths in asciibetical order.
	// The returned paths may be terminal (ie, the value is
	// stored content) or they may be further traversable like
	// a directory listing, in dc.
	Keys(dc, path string) ([]string, error)
	// Recurse will recursively descend through path, collecting
	// all KV pairs along the way, in dc.
	Recurse(dc, path string) ([][2]string, error)
}

A KV represents the key-value store built into consul.

Although consul supports arbitrary bytes as keys and values, this library assumes all keys and values are strings. This helps simplify code for clients, the 99% use case for which is reading and writing small configuration values and other string-y information.

Each method allows for specifying a particular dc from which to set or retrieve information. If left unset, the dc defaults to the dc associated with the consul agent being communicated with.

type LeaderSession

type LeaderSession interface {
	Abdicate() error
	SessionID() string
	Current() (string, error)
}

A LeaderSession is used to inspect and manage the underlying consul session being used to participate in leadership elections.

type LeadershipConfig

type LeadershipConfig struct {
	// Key is the path used to store session information in
	// the consul KV store. This must be set for the client to be used for
	// leader election. Typically this value will look something like
	// "service/<service name>/leader".
	Key string

	// ContactInfo is an opaque string that identifies the leader elected node.
	// This is what clients should use to know how to connect to the service
	// that is currently the leader. How this string is created, parsed, and
	// interpreted is an implementation detail left to the clients. Typically,
	// this string will in the form of a URI.
	ContactInfo string

	// Description is an arbitrary human-readable name for this leader election.
	// If not set, Description defaults to "default-leader-session".
	Description string

	// See SessionConfig.LockDelay.
	LockDelay time.Duration

	// See SessionConfig.TTL.
	TTL time.Duration
}

type Node

type Node struct {
	Name            string            `json:"Node"`
	Address         string            `json:"Address"`
	TaggedAddresses map[string]string `json:"TaggedAddresses"`
}

A Node represents a host on which a consul agent is running.

type NodeInfo

type NodeInfo struct {
	Node struct {
		Name            string            `json:"Node"`
		Address         string            `json:"Address"`
		TaggedAddresses map[string]string `json:"TaggedAddresses"`
	} `json:"Node"`
	Services map[string]struct {
		ID      string   `json:"ID"`
		Service string   `json:"Service"`
		Tags    []string `json:"Tags"`
		Port    int      `json:"Port"`
	} `json:"Services"`
}

A NodeInfo contains detailed information about a node, including all of the services defined to exist on that node.

type RequestError

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

RequestError exposes the status code of a http request error

func (*RequestError) Error

func (h *RequestError) Error() string

func (*RequestError) StatusCode

func (h *RequestError) StatusCode() int

type Service

type Service struct {
	Node            string            `json:"Node"`
	Address         string            `json:"Address"`
	TaggedAddresses map[string]string `json:"TaggedAddresses"`
	ServiceID       string            `json:"ServiceID"`
	ServiceName     string            `json:"ServiceName"`
	ServiceTags     []string          `json:"ServiceTags"`
	ServiceAddress  string            `json:"ServiceAddress"`
	ServicePort     int               `json:"ServicePort"`
}

A Service defines a program that is configured to be running somewhere.

By default, a service is defined on the same node the service itself is running. However, it is possible to specify the ServiceAddress, which 'overrides' the Address value (which is always associated with the node), which allows for pointing at services that may be running on nodes that are not associated with the consul cluster.

type Session

type Session interface {
	CreateSession(dc string, config SessionConfig) (SessionID, error)
	DeleteSession(dc string, id SessionID) error
	ReadSession(dc string, id SessionID) (SessionConfig, error)
	ListSessions(dc, node string) (map[SessionID]SessionConfig, error)
	RenewSession(dc string, id SessionID) (time.Duration, error)
}

type SessionConfig

type SessionConfig struct {
	// The node with which the session is associated. Typically, this should be
	// set to the node name of the local consul agent. That information can be
	// retrieved using the Self endpoint.
	Node string `json:"Node"`

	// Name is a human-readable identifier for this session.
	Name string `json:"Name"`

	// LockDelay determines the minimum amount of time that must pass
	// after a lock expiration before a new lock acquisition may take place.
	// The use of such a delay is to allow the potentially still-alive leader
	// to detect its own lock invalidation and stop processing requests that
	// may lead to an inconsistent state. This mechanism is not "bullet-proof",
	// but it eliminates the need for clients to include their own timeout code.
	// A zero-value disables this feature.
	LockDelay time.Duration `json:"LockDelay"`

	// TTL represents the amount of time that may pass before the session
	// automatically becomes invalidated. Typically a lower value for TTL
	// is better, as a node that unexpectedly goes "off the grid" will
	// continue to own the lock until the TTL expires.
	TTL time.Duration `json:"TTL"`

	// Behavior controls what action to take when a session is invalidated.
	// - SessionRelease: causes any held locks to be released.
	// - SessionDelete: causes any held locks to be deleted.
	Behavior SessionTerminationBehavior `json:"Behavior"`
}

type SessionID

type SessionID string

type SessionTerminationBehavior

type SessionTerminationBehavior string