structs

package
v0.8.4 Latest Latest
Warning

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

Go to latest
Published: Jun 9, 2017 License: MPL-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// IgnoreUnknownTypeFlag is set along with a MessageType
	// to indicate that the message type can be safely ignored
	// if it is not recognized. This is for future proofing, so
	// that new commands can be added in a way that won't cause
	// old servers to crash when the FSM attempts to process them.
	IgnoreUnknownTypeFlag MessageType = 128

	// NodeMaint is the special key set by a node in maintenance mode.
	NodeMaint = "_node_maintenance"

	// ServiceMaintPrefix is the prefix for a service in maintenance mode.
	ServiceMaintPrefix = "_service_maintenance:"

	// Client tokens have rules applied
	ACLTypeClient = "client"

	// Management tokens have an always allow policy.
	// They are used for token management.
	ACLTypeManagement = "management"

	// MaxLockDelay provides a maximum LockDelay value for
	// a session. Any value above this will not be respected.
	MaxLockDelay = 60 * time.Second
)
View Source
const (
	SessionTTLMax        = 24 * time.Hour
	SessionTTLMultiplier = 2
)
View Source
const (
	ACLSet      ACLOp = "set"
	ACLForceSet       = "force-set" // Deprecated, left to backwards compatibility
	ACLDelete         = "delete"
)
View Source
const (
	KeyringList    KeyringOp = "list"
	KeyringInstall           = "install"
	KeyringUse               = "use"
	KeyringRemove            = "remove"
)
View Source
const (
	// QueryTemplateTypeNamePrefixMatch uses the Name field of the query as
	// a prefix to select the template.
	QueryTemplateTypeNamePrefixMatch = "name_prefix_match"
)

Variables

View Source
var (
	ErrNoLeader  = fmt.Errorf("No cluster leader")
	ErrNoDCPath  = fmt.Errorf("No path to datacenter")
	ErrNoServers = fmt.Errorf("No known Consul servers")
)

Functions

func Decode

func Decode(buf []byte, out interface{}) error

Decode is used to decode a MsgPack encoded object

func Encode

func Encode(t MessageType, msg interface{}) ([]byte, error)

Encode is used to encode a MsgPack object with type prefix

func SatisfiesMetaFilters added in v0.7.3

func SatisfiesMetaFilters(meta map[string]string, filters map[string]string) bool

SatisfiesMetaFilters returns true if the metadata map contains the given filters

func ValidStatus added in v0.5.1

func ValidStatus(s string) bool

func ValidateMetadata added in v0.7.3

func ValidateMetadata(meta map[string]string) error

ValidateMeta validates a set of key/value pairs from the agent config

Types

type ACL added in v0.4.0

type ACL struct {
	ID    string
	Name  string
	Type  string
	Rules string

	RaftIndex
}

ACL is used to represent a token and its rules

func (*ACL) IsSame added in v0.7.0

func (a *ACL) IsSame(other *ACL) bool

IsSame checks if one ACL is the same as another, without looking at the Raft information (that's why we didn't call it IsEqual). This is useful for seeing if an update would be idempotent for all the functional parts of the structure.

type ACLOp added in v0.4.0

type ACLOp string

type ACLPolicy added in v0.4.0

type ACLPolicy struct {
	ETag   string
	Parent string
	Policy *acl.Policy
	TTL    time.Duration
	QueryMeta
}

type ACLPolicyRequest added in v0.4.0

type ACLPolicyRequest struct {
	Datacenter string
	ACL        string
	ETag       string
	QueryOptions
}

ACLPolicyRequest is used to request an ACL by ID, conditionally filtering on an ID

func (*ACLPolicyRequest) RequestDatacenter added in v0.4.0

func (r *ACLPolicyRequest) RequestDatacenter() string

type ACLReplicationStatus added in v0.7.0

type ACLReplicationStatus struct {
	Enabled          bool
	Running          bool
	SourceDatacenter string
	ReplicatedIndex  uint64
	LastSuccess      time.Time
	LastError        time.Time
}

ACLReplicationStatus provides information about the health of the ACL replication system.

type ACLRequest added in v0.4.0

type ACLRequest struct {
	Datacenter string
	Op         ACLOp
	ACL        ACL
	WriteRequest
}

ACLRequest is used to create, update or delete an ACL

func (*ACLRequest) RequestDatacenter added in v0.4.0

func (r *ACLRequest) RequestDatacenter() string

type ACLRequests added in v0.7.0

type ACLRequests []*ACLRequest

ACLRequests is a list of ACL change requests.

type ACLSpecificRequest added in v0.4.0

type ACLSpecificRequest struct {
	Datacenter string
	ACL        string
	QueryOptions
}

ACLSpecificRequest is used to request an ACL by ID

func (*ACLSpecificRequest) RequestDatacenter added in v0.4.0

func (r *ACLSpecificRequest) RequestDatacenter() string

type ACLs added in v0.4.0

type ACLs []*ACL

type AutopilotConfig added in v0.8.0

type AutopilotConfig struct {
	// CleanupDeadServers controls whether to remove dead servers when a new
	// server is added to the Raft peers.
	CleanupDeadServers bool

	// LastContactThreshold is the limit on the amount of time a server can go
	// without leader contact before being considered unhealthy.
	LastContactThreshold time.Duration

	// MaxTrailingLogs is the amount of entries in the Raft Log that a server can
	// be behind before being considered unhealthy.
	MaxTrailingLogs uint64

	// ServerStabilizationTime is the minimum amount of time a server must be
	// in a stable, healthy state before it can be added to the cluster. Only
	// applicable with Raft protocol version 3 or higher.
	ServerStabilizationTime time.Duration

	// (Enterprise-only) RedundancyZoneTag is the node tag to use for separating
	// servers into zones for redundancy. If left blank, this feature will be disabled.
	RedundancyZoneTag string

	// (Enterprise-only) DisableUpgradeMigration will disable Autopilot's upgrade migration
	// strategy of waiting until enough newer-versioned servers have been added to the
	// cluster before promoting them to voters.
	DisableUpgradeMigration bool

	// RaftIndex stores the create/modify indexes of this configuration.
	RaftIndex
}

AutopilotConfig holds the Autopilot configuration for a cluster.

type AutopilotSetConfigRequest added in v0.8.0

type AutopilotSetConfigRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// Config is the new Autopilot configuration to use.
	Config AutopilotConfig

	// CAS controls whether to use check-and-set semantics for this request.
	CAS bool

	// WriteRequest holds the ACL token to go along with this request.
	WriteRequest
}

AutopilotSetConfigRequest is used by the Operator endpoint to update the current Autopilot configuration of the cluster.

func (*AutopilotSetConfigRequest) RequestDatacenter added in v0.8.0

func (op *AutopilotSetConfigRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type CheckServiceNode

type CheckServiceNode struct {
	Node    *Node
	Service *NodeService
	Checks  HealthChecks
}

CheckServiceNode is used to provide the node, its service definition, as well as a HealthCheck that is associated.

type CheckServiceNodes

type CheckServiceNodes []CheckServiceNode

func (CheckServiceNodes) Filter added in v0.6.0

func (nodes CheckServiceNodes) Filter(onlyPassing bool) CheckServiceNodes

Filter removes nodes that are failing health checks (and any non-passing check if that option is selected). Note that this returns the filtered results AND modifies the receiver for performance.

func (CheckServiceNodes) Shuffle added in v0.6.0

func (nodes CheckServiceNodes) Shuffle()

Shuffle does an in-place random shuffle using the Fisher-Yates algorithm.

type ChecksInStateRequest

type ChecksInStateRequest struct {
	Datacenter      string
	NodeMetaFilters map[string]string
	State           string
	Source          QuerySource
	QueryOptions
}

ChecksInStateRequest is used to query for nodes in a state

func (*ChecksInStateRequest) RequestDatacenter added in v0.2.0

func (r *ChecksInStateRequest) RequestDatacenter() string

type CompoundResponse added in v0.5.0

type CompoundResponse interface {
	// Add adds a new response to the compound response
	Add(interface{})

	// New returns an empty response object which can be passed around by
	// reference, and then passed to Add() later on.
	New() interface{}
}

CompoundResponse is an interface for gathering multiple responses. It is used in cross-datacenter RPC calls where more than 1 datacenter is expected to reply.

type Coordinate added in v0.6.0

type Coordinate struct {
	Node  string
	Coord *coordinate.Coordinate
}

Coordinate stores a node name with its associated network coordinate.

type CoordinateUpdateRequest added in v0.6.0

type CoordinateUpdateRequest struct {
	Datacenter string
	Node       string
	Coord      *coordinate.Coordinate
	WriteRequest
}

CoordinateUpdateRequest is used to update the network coordinate of a given node.

func (*CoordinateUpdateRequest) RequestDatacenter added in v0.6.0

func (c *CoordinateUpdateRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given update request.

type Coordinates added in v0.6.0

type Coordinates []*Coordinate

type DCSpecificRequest

type DCSpecificRequest struct {
	Datacenter      string
	NodeMetaFilters map[string]string
	Source          QuerySource
	QueryOptions
}

DCSpecificRequest is used to query about a specific DC

func (*DCSpecificRequest) RequestDatacenter added in v0.2.0

func (r *DCSpecificRequest) RequestDatacenter() string

type DatacenterMap added in v0.6.0

type DatacenterMap struct {
	Datacenter  string
	AreaID      types.AreaID
	Coordinates Coordinates
}

DatacenterMap is used to represent a list of nodes with their raw coordinates, associated with a datacenter. Coordinates are only compatible between nodes in the same area.

type DeregisterRequest

type DeregisterRequest struct {
	Datacenter string
	Node       string
	ServiceID  string
	CheckID    types.CheckID
	WriteRequest
}

DeregisterRequest is used for the Catalog.Deregister endpoint to deregister a node as providing a service. If no service is provided the entire node is deregistered.

func (*DeregisterRequest) RequestDatacenter added in v0.2.0

func (r *DeregisterRequest) RequestDatacenter() string

type DirEntries

type DirEntries []*DirEntry

type DirEntry

type DirEntry struct {
	LockIndex uint64
	Key       string
	Flags     uint64
	Value     []byte
	Session   string `json:",omitempty"`

	RaftIndex
}

DirEntry is used to represent a directory entry. This is used for values in our Key-Value store.

func (*DirEntry) Clone added in v0.6.0

func (d *DirEntry) Clone() *DirEntry

Returns a clone of the given directory entry.

type EventFireRequest added in v0.4.0

type EventFireRequest struct {
	Datacenter string
	Name       string
	Payload    []byte

	// Not using WriteRequest so that any server can process
	// the request. It is a bit unusual...
	QueryOptions
}

EventFireRequest is used to ask a server to fire a Serf event. It is a bit odd, since it doesn't depend on the catalog or leader. Any node can respond, so it's not quite like a standard write request. This is used only internally.

func (*EventFireRequest) RequestDatacenter added in v0.4.0

func (r *EventFireRequest) RequestDatacenter() string

type EventFireResponse added in v0.4.0

type EventFireResponse struct {
	QueryMeta
}

EventFireResponse is used to respond to a fire request.

type HealthCheck

type HealthCheck struct {
	Node        string
	CheckID     types.CheckID // Unique per-node ID
	Name        string        // Check name
	Status      string        // The current check status
	Notes       string        // Additional notes with the status
	Output      string        // Holds output of script runs
	ServiceID   string        // optional associated service
	ServiceName string        // optional service name
	ServiceTags []string      // optional service tags

	RaftIndex
}

HealthCheck represents a single check on a given node

func (*HealthCheck) Clone added in v0.7.0

func (c *HealthCheck) Clone() *HealthCheck

Clone returns a distinct clone of the HealthCheck.

func (*HealthCheck) IsSame added in v0.6.0

func (c *HealthCheck) IsSame(other *HealthCheck) bool

IsSame checks if one HealthCheck is the same as another, without looking at the Raft information (that's why we didn't call it IsEqual). This is useful for seeing if an update would be idempotent for all the functional parts of the structure.

type HealthChecks

type HealthChecks []*HealthCheck

HealthChecks is a collection of HealthCheck structs.

type IndexedACLs added in v0.4.0

type IndexedACLs struct {
	ACLs ACLs
	QueryMeta
}

type IndexedCheckServiceNodes

type IndexedCheckServiceNodes struct {
	Nodes CheckServiceNodes
	QueryMeta
}

type IndexedCoordinate added in v0.6.0

type IndexedCoordinate struct {
	Coord *coordinate.Coordinate
	QueryMeta
}

IndexedCoordinate is used to represent a single node's coordinate from the state store.

type IndexedCoordinates added in v0.6.0

type IndexedCoordinates struct {
	Coordinates Coordinates
	QueryMeta
}

IndexedCoordinates is used to represent a list of nodes and their corresponding raw coordinates.

type IndexedDirEntries

type IndexedDirEntries struct {
	Entries DirEntries
	QueryMeta
}

type IndexedHealthChecks

type IndexedHealthChecks struct {
	HealthChecks HealthChecks
	QueryMeta
}

type IndexedKeyList added in v0.2.0

type IndexedKeyList struct {
	Keys []string
	QueryMeta
}

type IndexedNodeDump added in v0.2.0

type IndexedNodeDump struct {
	Dump NodeDump
	QueryMeta
}

type IndexedNodeServices

type IndexedNodeServices struct {
	NodeServices *NodeServices
	QueryMeta
}

type IndexedNodes

type IndexedNodes struct {
	Nodes Nodes
	QueryMeta
}

type IndexedPreparedQueries added in v0.6.0

type IndexedPreparedQueries struct {
	Queries PreparedQueries
	QueryMeta
}

type IndexedServiceNodes

type IndexedServiceNodes struct {
	ServiceNodes ServiceNodes
	QueryMeta
}

type IndexedServices

type IndexedServices struct {
	Services Services
	QueryMeta
}

type IndexedSessions added in v0.3.0

type IndexedSessions struct {
	Sessions Sessions
	QueryMeta
}

type KVSRequest

type KVSRequest struct {
	Datacenter string
	Op         api.KVOp // Which operation are we performing
	DirEnt     DirEntry // Which directory entry
	WriteRequest
}

KVSRequest is used to operate on the Key-Value store

func (*KVSRequest) RequestDatacenter added in v0.2.0

func (r *KVSRequest) RequestDatacenter() string

type KeyListRequest added in v0.2.0

type KeyListRequest struct {
	Datacenter string
	Prefix     string
	Seperator  string
	QueryOptions
}

KeyListRequest is used to list keys

func (*KeyListRequest) RequestDatacenter added in v0.2.0

func (r *KeyListRequest) RequestDatacenter() string

type KeyRequest

type KeyRequest struct {
	Datacenter string
	Key        string
	QueryOptions
}

KeyRequest is used to request a key, or key prefix

func (*KeyRequest) RequestDatacenter added in v0.2.0

func (r *KeyRequest) RequestDatacenter() string

type KeyringOp added in v0.5.0

type KeyringOp string

type KeyringRequest added in v0.5.0

type KeyringRequest struct {
	Operation   KeyringOp
	Key         string
	Datacenter  string
	Forwarded   bool
	RelayFactor uint8
	QueryOptions
}

KeyringRequest encapsulates a request to modify an encryption keyring. It can be used for install, remove, or use key type operations.

func (*KeyringRequest) RequestDatacenter added in v0.5.0

func (r *KeyringRequest) RequestDatacenter() string

type KeyringResponse added in v0.5.0

type KeyringResponse struct {
	WAN        bool
	Datacenter string
	Messages   map[string]string `json:",omitempty"`
	Keys       map[string]int
	NumNodes   int
	Error      string `json:",omitempty"`
}

KeyringResponse is a unified key response and can be used for install, remove, use, as well as listing key queries.

type KeyringResponses added in v0.5.0

type KeyringResponses struct {
	Responses []*KeyringResponse
	QueryMeta
}

KeyringResponses holds multiple responses to keyring queries. Each datacenter replies independently, and KeyringResponses is used as a container for the set of all responses.

func (*KeyringResponses) Add added in v0.5.0

func (r *KeyringResponses) Add(v interface{})

func (*KeyringResponses) New added in v0.5.0

func (r *KeyringResponses) New() interface{}

type MessageType

type MessageType uint8
const (
	RegisterRequestType MessageType = iota
	DeregisterRequestType
	KVSRequestType
	SessionRequestType
	ACLRequestType
	TombstoneRequestType
	CoordinateBatchUpdateType
	PreparedQueryRequestType
	TxnRequestType
	AutopilotRequestType
	AreaRequestType
)

type Node

type Node struct {
	ID              types.NodeID
	Node            string
	Address         string
	Datacenter      string
	TaggedAddresses map[string]string
	Meta            map[string]string

	RaftIndex
}

Used to return information about a node

type NodeDump added in v0.2.0

type NodeDump []*NodeInfo

NodeDump is used to dump all the nodes with all their associated data. This is currently used for the UI only, as it is rather expensive to generate.

type NodeInfo added in v0.2.0

type NodeInfo struct {
	ID              types.NodeID
	Node            string
	Address         string
	TaggedAddresses map[string]string
	Meta            map[string]string
	Services        []*NodeService
	Checks          HealthChecks
}

NodeInfo is used to dump all associated information about a node. This is currently used for the UI only, as it is rather expensive to generate.

type NodeService

type NodeService struct {
	ID                string
	Service           string
	Tags              []string
	Address           string
	Port              int
	EnableTagOverride bool

	RaftIndex
}

NodeService is a service provided by a node

func (*NodeService) IsSame added in v0.6.0

func (s *NodeService) IsSame(other *NodeService) bool

IsSame checks if one NodeService is the same as another, without looking at the Raft information (that's why we didn't call it IsEqual). This is useful for seeing if an update would be idempotent for all the functional parts of the structure.

func (*NodeService) ToServiceNode added in v0.6.0

func (s *NodeService) ToServiceNode(node string) *ServiceNode

ToServiceNode converts the given node service to a service node.

type NodeServices

type NodeServices struct {
	Node     *Node
	Services map[string]*NodeService
}

type NodeSpecificRequest

type NodeSpecificRequest struct {
	Datacenter string
	Node       string
	QueryOptions
}

NodeSpecificRequest is used to request the information about a single node

func (*NodeSpecificRequest) RequestDatacenter added in v0.2.0

func (r *NodeSpecificRequest) RequestDatacenter() string

type Nodes

type Nodes []*Node

type OperatorHealthReply added in v0.8.0

type OperatorHealthReply struct {
	// Healthy is true if all the servers in the cluster are healthy.
	Healthy bool

	// FailureTolerance is the number of healthy servers that could be lost without
	// an outage occurring.
	FailureTolerance int

	// Servers holds the health of each server.
	Servers []ServerHealth
}

OperatorHealthReply is a representation of the overall health of the cluster

type PreparedQueries added in v0.6.0

type PreparedQueries []*PreparedQuery

type PreparedQuery added in v0.6.0

type PreparedQuery struct {
	// ID is this UUID-based ID for the query, always generated by Consul.
	ID string

	// Name is an optional friendly name for the query supplied by the
	// user. NOTE - if this feature is used then it will reduce the security
	// of any read ACL associated with this query/service since this name
	// can be used to locate nodes with supplying any ACL.
	Name string

	// Session is an optional session to tie this query's lifetime to. If
	// this is omitted then the query will not expire.
	Session string

	// Token is the ACL token used when the query was created, and it is
	// used when a query is subsequently executed. This token, or a token
	// with management privileges, must be used to change the query later.
	Token string

	// Template is used to configure this query as a template, which will
	// respond to queries based on the Name, and then will be rendered
	// before it is executed.
	Template QueryTemplateOptions

	// Service defines a service query (leaving things open for other types
	// later).
	Service ServiceQuery

	// DNS has options that control how the results of this query are
	// served over DNS.
	DNS QueryDNSOptions

	RaftIndex
}

PreparedQuery defines a complete prepared query, and is the structure we maintain in the state store.

func (*PreparedQuery) GetACLPrefix added in v0.6.4

func (pq *PreparedQuery) GetACLPrefix() (string, bool)

GetACLPrefix returns the prefix to look up the prepared_query ACL policy for this query, and whether the prefix applies to this query. You always need to check the ok value before using the prefix.

type PreparedQueryExecuteRemoteRequest added in v0.6.0

type PreparedQueryExecuteRemoteRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// Query is a copy of the query to execute.  We have to ship the entire
	// query over since it won't be present in the remote state store.
	Query PreparedQuery

	// Limit will trim the resulting list down to the given limit.
	Limit int

	// QueryOptions (unfortunately named here) controls the consistency
	// settings for the the service lookups.
	QueryOptions
}

PreparedQueryExecuteRemoteRequest is used when running a local query in a remote datacenter.

func (*PreparedQueryExecuteRemoteRequest) RequestDatacenter added in v0.6.0

func (q *PreparedQueryExecuteRemoteRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type PreparedQueryExecuteRequest added in v0.6.0

type PreparedQueryExecuteRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// QueryIDOrName is the ID of a query _or_ the name of one, either can
	// be provided.
	QueryIDOrName string

	// Limit will trim the resulting list down to the given limit.
	Limit int

	// Source is used to sort the results relative to a given node using
	// network coordinates.
	Source QuerySource

	// Agent is used to carry around a reference to the agent which initiated
	// the execute request. Used to distance-sort relative to the local node.
	Agent QuerySource

	// QueryOptions (unfortunately named here) controls the consistency
	// settings for the query lookup itself, as well as the service lookups.
	QueryOptions
}

PreparedQueryExecuteRequest is used to execute a prepared query.

func (*PreparedQueryExecuteRequest) RequestDatacenter added in v0.6.0

func (q *PreparedQueryExecuteRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type PreparedQueryExecuteResponse added in v0.6.0

type PreparedQueryExecuteResponse struct {
	// Service is the service that was queried.
	Service string

	// Nodes has the nodes that were output by the query.
	Nodes CheckServiceNodes

	// DNS has the options for serving these results over DNS.
	DNS QueryDNSOptions

	// Datacenter is the datacenter that these results came from.
	Datacenter string

	// Failovers is a count of how many times we had to query a remote
	// datacenter.
	Failovers int

	// QueryMeta has freshness information about the query.
	QueryMeta
}

PreparedQueryExecuteResponse has the results of executing a query.

type PreparedQueryExplainResponse added in v0.6.4

type PreparedQueryExplainResponse struct {
	// Query has the fully-rendered query.
	Query PreparedQuery

	// QueryMeta has freshness information about the query.
	QueryMeta
}

PreparedQueryExplainResponse has the results when explaining a query/

type PreparedQueryOp added in v0.6.0

type PreparedQueryOp string
const (
	PreparedQueryCreate PreparedQueryOp = "create"
	PreparedQueryUpdate PreparedQueryOp = "update"
	PreparedQueryDelete PreparedQueryOp = "delete"
)

type PreparedQueryRequest added in v0.6.0

type PreparedQueryRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// Op is the operation to apply.
	Op PreparedQueryOp

	// Query is the query itself.
	Query *PreparedQuery

	// WriteRequest holds the ACL token to go along with this request.
	WriteRequest
}

QueryRequest is used to create or change prepared queries.

func (*PreparedQueryRequest) RequestDatacenter added in v0.6.0

func (q *PreparedQueryRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type PreparedQuerySpecificRequest added in v0.6.0

type PreparedQuerySpecificRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// QueryID is the ID of a query.
	QueryID string

	// QueryOptions (unfortunately named here) controls the consistency
	// settings for the query lookup itself, as well as the service lookups.
	QueryOptions
}

PreparedQuerySpecificRequest is used to get information about a prepared query.

func (*PreparedQuerySpecificRequest) RequestDatacenter added in v0.6.0

func (q *PreparedQuerySpecificRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type QueryDNSOptions added in v0.6.0

type QueryDNSOptions struct {
	// TTL is the time to live for the served DNS results.
	TTL string
}

QueryDNSOptions controls settings when query results are served over DNS.

type QueryDatacenterOptions added in v0.6.0

type QueryDatacenterOptions struct {
	// NearestN is set to the number of remote datacenters to try, based on
	// network coordinates.
	NearestN int

	// Datacenters is a fixed list of datacenters to try after NearestN. We
	// never try a datacenter multiple times, so those are subtracted from
	// this list before proceeding.
	Datacenters []string
}

QueryDatacenterOptions sets options about how we fail over if there are no healthy nodes in the local datacenter.

type QueryMeta added in v0.2.0

type QueryMeta struct {
	// This is the index associated with the read
	Index uint64

	// If AllowStale is used, this is time elapsed since
	// last contact between the follower and leader. This
	// can be used to gauge staleness.
	LastContact time.Duration

	// Used to indicate if there is a known leader node
	KnownLeader bool
}

QueryMeta allows a query response to include potentially useful metadata about a query

type QueryOptions added in v0.2.0

type QueryOptions struct {
	// Token is the ACL token ID. If not provided, the 'anonymous'
	// token is assumed for backwards compatibility.
	Token string

	// If set, wait until query exceeds given index. Must be provided
	// with MaxQueryTime.
	MinQueryIndex uint64

	// Provided with MinQueryIndex to wait for change.
	MaxQueryTime time.Duration

	// If set, any follower can service the request. Results
	// may be arbitrarily stale.
	AllowStale bool

	// If set, the leader must verify leadership prior to
	// servicing the request. Prevents a stale read.
	RequireConsistent bool
}

QueryOptions is used to specify various flags for read queries

func (QueryOptions) ACLToken added in v0.4.0

func (q QueryOptions) ACLToken() string

func (QueryOptions) AllowStaleRead added in v0.2.0

func (q QueryOptions) AllowStaleRead() bool

func (QueryOptions) IsRead added in v0.2.0

func (q QueryOptions) IsRead() bool

IsRead is always true for QueryOption.

type QuerySource added in v0.6.0

type QuerySource struct {
	Datacenter string
	Node       string
}

QuerySource is used to pass along information about the source node in queries so that we can adjust the response based on its network coordinates.

type QueryTemplateOptions added in v0.6.4

type QueryTemplateOptions struct {
	// Type, if non-empty, means that this query is a template. This is
	// set to one of the QueryTemplateType* constants above.
	Type string

	// Regexp is an optional regular expression to use to parse the full
	// name, once the prefix match has selected a template. This can be
	// used to extract parts of the name and choose a service name, set
	// tags, etc.
	Regexp string
}

QueryTemplateOptions controls settings if this query is a template.

type RPCInfo added in v0.2.0

type RPCInfo interface {
	RequestDatacenter() string
	IsRead() bool
	AllowStaleRead() bool
	ACLToken() string
}

RPCInfo is used to describe common information about query

type RaftConfigurationResponse added in v0.7.0

type RaftConfigurationResponse struct {
	// Servers has the list of servers in the Raft configuration.
	Servers []*RaftServer

	// Index has the Raft index of this configuration.
	Index uint64
}

RaftConfigrationResponse is returned when querying for the current Raft configuration.

type RaftIndex added in v0.6.0

type RaftIndex struct {
	CreateIndex uint64
	ModifyIndex uint64
}

RaftIndex is used to track the index used while creating or modifying a given struct type.

type RaftRemovePeerRequest added in v0.8.0

type RaftRemovePeerRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// Address is the peer to remove, in the form "IP:port".
	Address raft.ServerAddress

	// ID is the peer ID to remove.
	ID raft.ServerID

	// WriteRequest holds the ACL token to go along with this request.
	WriteRequest
}

RaftRemovePeerRequest is used by the Operator endpoint to apply a Raft operation on a specific Raft peer by address in the form of "IP:port".

func (*RaftRemovePeerRequest) RequestDatacenter added in v0.8.0

func (op *RaftRemovePeerRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type RaftServer added in v0.7.0

type RaftServer struct {
	// ID is the unique ID for the server. These are currently the same
	// as the address, but they will be changed to a real GUID in a future
	// release of Consul.
	ID raft.ServerID

	// Node is the node name of the server, as known by Consul, or this
	// will be set to "(unknown)" otherwise.
	Node string

	// Address is the IP:port of the server, used for Raft communications.
	Address raft.ServerAddress

	// Leader is true if this server is the current cluster leader.
	Leader bool

	// Voter is true if this server has a vote in the cluster. This might
	// be false if the server is staging and still coming online, or if
	// it's a non-voting server, which will be added in a future release of
	// Consul.
	Voter bool
}

RaftServer has information about a server in the Raft configuration.

type RegisterRequest

type RegisterRequest struct {
	Datacenter      string
	ID              types.NodeID
	Node            string
	Address         string
	TaggedAddresses map[string]string
	NodeMeta        map[string]string
	Service         *NodeService
	Check           *HealthCheck
	Checks          HealthChecks

	// SkipNodeUpdate can be used when a register request is intended for
	// updating a service and/or checks, but doesn't want to overwrite any
	// node information if the node is already registered. If the node
	// doesn't exist, it will still be created, but if the node exists, any
	// node portion of this update will not apply.
	SkipNodeUpdate bool

	WriteRequest
}

RegisterRequest is used for the Catalog.Register endpoint to register a node as providing a service. If no service is provided, the node is registered.

func (*RegisterRequest) ChangesNode added in v0.7.2

func (r *RegisterRequest) ChangesNode(node *Node) bool

ChangesNode returns true if the given register request changes the given node, which can be nil. This only looks for changes to the node record itself, not any of the health checks.

func (*RegisterRequest) RequestDatacenter added in v0.2.0

func (r *RegisterRequest) RequestDatacenter() string

type ServerHealth added in v0.8.0

type ServerHealth struct {
	// ID is the raft ID of the server.
	ID string

	// Name is the node name of the server.
	Name string

	// Address is the address of the server.
	Address string

	// The status of the SerfHealth check for the server.
	SerfStatus serf.MemberStatus

	// Version is the Consul version of the server.
	Version string

	// Leader is whether this server is currently the leader.
	Leader bool

	// LastContact is the time since this node's last contact with the leader.
	LastContact time.Duration

	// LastTerm is the highest leader term this server has a record of in its Raft log.
	LastTerm uint64

	// LastIndex is the last log index this server has a record of in its Raft log.
	LastIndex uint64

	// Healthy is whether or not the server is healthy according to the current
	// Autopilot config.
	Healthy bool

	// Voter is whether this is a voting server.
	Voter bool

	// StableSince is the last time this server's Healthy value changed.
	StableSince time.Time
}

ServerHealth is the health (from the leader's point of view) of a server.

func (*ServerHealth) IsHealthy added in v0.8.0

func (h *ServerHealth) IsHealthy(lastTerm uint64, leaderLastIndex uint64, autopilotConf *AutopilotConfig) bool

IsHealthy determines whether this ServerHealth is considered healthy based on the given Autopilot config

func (*ServerHealth) IsStable added in v0.8.0

func (h *ServerHealth) IsStable(now time.Time, conf *AutopilotConfig) bool

IsStable returns true if the ServerHealth is in a stable, passing state according to the given AutopilotConfig

type ServerStats added in v0.8.0

type ServerStats struct {
	// LastContact is the time since this node's last contact with the leader.
	LastContact string

	// LastTerm is the highest leader term this server has a record of in its Raft log.
	LastTerm uint64

	// LastIndex is the last log index this server has a record of in its Raft log.
	LastIndex uint64
}

ServerStats holds miscellaneous Raft metrics for a server

type ServiceNode

type ServiceNode struct {
	ID                       types.NodeID
	Node                     string
	Address                  string
	Datacenter               string
	TaggedAddresses          map[string]string
	NodeMeta                 map[string]string
	ServiceID                string
	ServiceName              string
	ServiceTags              []string
	ServiceAddress           string
	ServicePort              int
	ServiceEnableTagOverride bool

	RaftIndex
}

ServiceNode represents a node that is part of a service. ID, Address, TaggedAddresses, and NodeMeta are node-related fields that are always empty in the state store and are filled in on the way out by parseServiceNodes(). This is also why PartialClone() skips them, because we know they are blank already so it would be a waste of time to copy them.

func (*ServiceNode) PartialClone added in v0.7.0

func (s *ServiceNode) PartialClone() *ServiceNode

PartialClone() returns a clone of the given service node, minus the node- related fields that get filled in later, Address and TaggedAddresses.

func (*ServiceNode) ToNodeService added in v0.6.0

func (s *ServiceNode) ToNodeService() *NodeService

ToNodeService converts the given service node to a node service.

type ServiceNodes

type ServiceNodes []*ServiceNode

type ServiceQuery added in v0.6.0

type ServiceQuery struct {
	// Service is the service to query.
	Service string

	// Failover controls what we do if there are no healthy nodes in the
	// local datacenter.
	Failover QueryDatacenterOptions

	// If OnlyPassing is true then we will only include nodes with passing
	// health checks (critical AND warning checks will cause a node to be
	// discarded)
	OnlyPassing bool

	// Near allows the query to always prefer the node nearest the given
	// node. If the node does not exist, results are returned in their
	// normal randomly-shuffled order. Supplying the magic "_agent" value
	// is supported to sort near the agent which initiated the request.
	Near string

	// Tags are a set of required and/or disallowed tags. If a tag is in
	// this list it must be present. If the tag is preceded with "!" then
	// it is disallowed.
	Tags []string

	// NodeMeta is a map of required node metadata fields. If a key/value
	// pair is in this map it must be present on the node in order for the
	// service entry to be returned.
	NodeMeta map[string]string
}

ServiceQuery is used to query for a set of healthy nodes offering a specific service.

type ServiceSpecificRequest

type ServiceSpecificRequest struct {
	Datacenter      string
	NodeMetaFilters map[string]string
	ServiceName     string
	ServiceTag      string
	TagFilter       bool // Controls tag filtering
	Source          QuerySource
	QueryOptions
}

ServiceSpecificRequest is used to query about a specific service

func (*ServiceSpecificRequest) RequestDatacenter added in v0.2.0

func (r *ServiceSpecificRequest) RequestDatacenter() string

type Services

type Services map[string][]string

Used to return information about a provided services. Maps service name to available tags

type Session added in v0.3.0

type Session struct {
	ID        string
	Name      string
	Node      string
	Checks    []types.CheckID
	LockDelay time.Duration
	Behavior  SessionBehavior // What to do when session is invalidated
	TTL       string

	RaftIndex
}

Session is used to represent an open session in the KV store. This issued to associate node checks with acquired locks.

type SessionBehavior added in v0.5.0

type SessionBehavior string
const (
	SessionKeysRelease SessionBehavior = "release"
	SessionKeysDelete                  = "delete"
)

type SessionOp added in v0.3.0

type SessionOp string
const (
	SessionCreate  SessionOp = "create"
	SessionDestroy           = "destroy"
)

type SessionRequest added in v0.3.0

type SessionRequest struct {
	Datacenter string
	Op         SessionOp // Which operation are we performing
	Session    Session   // Which session
	WriteRequest
}

SessionRequest is used to operate on sessions

func (*SessionRequest) RequestDatacenter added in v0.3.0

func (r *SessionRequest) RequestDatacenter() string

type SessionSpecificRequest added in v0.3.0

type SessionSpecificRequest struct {
	Datacenter string
	Session    string
	QueryOptions
}

SessionSpecificRequest is used to request a session by ID

func (*SessionSpecificRequest) RequestDatacenter added in v0.3.0

func (r *SessionSpecificRequest) RequestDatacenter() string

type Sessions added in v0.3.0

type Sessions []*Session

type SnapshotOp added in v0.7.1

type SnapshotOp int
const (
	SnapshotSave SnapshotOp = iota
	SnapshotRestore
)

type SnapshotRequest added in v0.7.1

type SnapshotRequest struct {
	// Datacenter is the target datacenter for this request. The request
	// will be forwarded if necessary.
	Datacenter string

	// Token is the ACL token to use for the operation. If ACLs are enabled
	// then all operations require a management token.
	Token string

	// If set, any follower can service the request. Results may be
	// arbitrarily stale. Only applies to SnapshotSave.
	AllowStale bool

	// Op is the operation code for the RPC.
	Op SnapshotOp
}

SnapshotRequest is used as a header for a snapshot RPC request. This will precede any streaming data that's part of the request and is JSON-encoded on the wire.

type SnapshotResponse added in v0.7.1

type SnapshotResponse struct {
	// Error is the overall error status of the RPC request.
	Error string

	// QueryMeta has freshness information about the server that handled the
	// request. It is only filled in for a SnapshotSave.
	QueryMeta
}

SnapshotResponse is used header for a snapshot RPC response. This will precede any streaming data that's part of the request and is JSON-encoded on the wire.

type TombstoneOp added in v0.5.0

type TombstoneOp string
const (
	TombstoneReap TombstoneOp = "reap"
)

type TombstoneRequest added in v0.5.0

type TombstoneRequest struct {
	Datacenter string
	Op         TombstoneOp
	ReapIndex  uint64
	WriteRequest
}

TombstoneRequest is used to trigger a reaping of the tombstones

func (*TombstoneRequest) RequestDatacenter added in v0.5.0

func (r *TombstoneRequest) RequestDatacenter() string

type TxnError added in v0.7.0

type TxnError struct {
	OpIndex int
	What    string
}

TxnError is used to return information about an error for a specific operation.

func (TxnError) Error added in v0.7.0

func (e TxnError) Error() string

Error returns the string representation of an atomic error.

type TxnErrors added in v0.7.0

type TxnErrors []*TxnError

TxnErrors is a list of TxnError entries.

type TxnKVOp added in v0.7.0

type TxnKVOp struct {
	Verb   api.KVOp
	DirEnt DirEntry
}

TxnKVOp is used to define a single operation on the KVS inside a transaction

type TxnKVResult added in v0.7.0

type TxnKVResult *DirEntry

TxnKVResult is used to define the result of a single operation on the KVS inside a transaction.

type TxnOp added in v0.7.0

type TxnOp struct {
	KV *TxnKVOp
}

TxnOp is used to define a single operation inside a transaction. Only one of the types should be filled out per entry.

type TxnOps added in v0.7.0

type TxnOps []*TxnOp

TxnOps is a list of operations within a transaction.

type TxnReadRequest added in v0.7.0

type TxnReadRequest struct {
	Datacenter string
	Ops        TxnOps
	QueryOptions
}

TxnReadRequest is used as a fast path for read-only transactions that don't modify the state store.

func (*TxnReadRequest) RequestDatacenter added in v0.7.0

func (r *TxnReadRequest) RequestDatacenter() string

type TxnReadResponse added in v0.7.0

type TxnReadResponse struct {
	TxnResponse
	QueryMeta
}

TxnReadResponse is the structure returned by a TxnReadRequest.

type TxnRequest added in v0.7.0

type TxnRequest struct {
	Datacenter string
	Ops        TxnOps
	WriteRequest
}

TxnRequest is used to apply multiple operations to the state store in a single transaction

func (*TxnRequest) RequestDatacenter added in v0.7.0

func (r *TxnRequest) RequestDatacenter() string

type TxnResponse added in v0.7.0

type TxnResponse struct {
	Results TxnResults
	Errors  TxnErrors
}

TxnResponse is the structure returned by a TxnRequest.

type TxnResult added in v0.7.0

type TxnResult struct {
	KV TxnKVResult
}

TxnResult is used to define the result of a given operation inside a transaction. Only one of the types should be filled out per entry.

type TxnResults added in v0.7.0

type TxnResults []*TxnResult

TxnResults is a list of TxnResult entries.

type WriteRequest added in v0.2.0

type WriteRequest struct {
	// Token is the ACL token ID. If not provided, the 'anonymous'
	// token is assumed for backwards compatibility.
	Token string
}

func (WriteRequest) ACLToken added in v0.4.0

func (w WriteRequest) ACLToken() string

func (WriteRequest) AllowStaleRead added in v0.2.0

func (w WriteRequest) AllowStaleRead() bool

func (WriteRequest) IsRead added in v0.2.0

func (w WriteRequest) IsRead() bool

WriteRequest only applies to writes, always false

Jump to

Keyboard shortcuts

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