structs

package
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Nov 21, 2018 License: MPL-2.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ACLBootstrapInit is used to perform a scan for existing tokens which
	// will decide whether bootstrapping is allowed for a cluster. This is
	// initiated by the leader when it steps up, if necessary.
	ACLBootstrapInit = "bootstrap-init"

	// ACLBootstrapNow is used to perform a one-time ACL bootstrap operation on
	// a cluster to get the first management token.
	ACLBootstrapNow = "bootstrap-now"

	// ACLSet creates or updates a token.
	ACLSet ACLOp = "set"

	// ACLForceSet is deprecated, but left for backwards compatibility.
	ACLForceSet = "force-set"

	// ACLDelete deletes a token.
	ACLDelete = "delete"
)
View Source 
const (
	// ACLTypeClient tokens have rules applied
	ACLTypeClient = "client"

	// ACLTypeManagement tokens have an always allow policy, so they can
	// make other tokens and can access all resources.
	ACLTypeManagement = "management"
)
View Source 
const (
	SerfCheckID           types.CheckID = "serfHealth"
	SerfCheckName                       = "Serf Health Status"
	SerfCheckAliveOutput                = "Agent alive and reachable"
	SerfCheckFailedOutput               = "Agent not live or unreachable"
)

These are used to manage the built-in "serfHealth" check that's attached to every node in the catalog.

View Source 
const (
	ConsulServiceID   = "consul"
	ConsulServiceName = "consul"
)

These are used to manage the "consul" service that's attached to every Consul server node in the catalog.

View Source 
const (
	RegisterRequestType       MessageType = 0
	DeregisterRequestType                 = 1
	KVSRequestType                        = 2
	SessionRequestType                    = 3
	ACLRequestType                        = 4
	TombstoneRequestType                  = 5
	CoordinateBatchUpdateType             = 6
	PreparedQueryRequestType              = 7
	TxnRequestType                        = 8
	AutopilotRequestType                  = 9
	AreaRequestType                       = 10
	ACLBootstrapRequestType               = 11 // FSM snapshots only.
)

These are serialized between Consul servers and stored in Consul snapshots, so entries must only ever be added.

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:"

	// MetaSegmentKey is the node metadata key used to store the node's network segment
	MetaSegmentKey = "consul-network-segment"

	// 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 (
	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                   = errors.New(errNoLeader)
	ErrNoDCPath                   = errors.New(errNoDCPath)
	ErrNoServers                  = errors.New(errNoServers)
	ErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)
	ErrSegmentsNotSupported       = errors.New(errSegmentsNotSupported)
	ErrRPCRateExceeded            = errors.New(errRPCRateExceeded)
)
View Source 
var ACLBootstrapNotAllowedErr = errors.New("ACL bootstrap no longer allowed")

ACLBootstrapNotAllowedErr is returned once we know that a bootstrap can no longer be done since the cluster was bootstrapped, or a management token was created manually.

View Source 
var ACLBootstrapNotInitializedErr = errors.New("ACL bootstrap not initialized, need to force a leader election and ensure all Consul servers support this feature")

ACLBootstrapNotInitializedErr is returned when a bootstrap is attempted but we haven't yet initialized ACL bootstrap. It provides some guidance to operators on how to proceed.

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 IsErrNoLeader added in v1.0.0 

func IsErrNoLeader(err error) bool

func IsErrRPCRateExceeded added in v0.9.3 

func IsErrRPCRateExceeded(err error) bool

func SatisfiesMetaFilters 

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

SatisfiesMetaFilters returns true if the metadata map contains the given filters

func ValidStatus 

func ValidStatus(s string) bool

func ValidateMetadata 

func ValidateMetadata(meta map[string]string, allowConsulPrefix bool) error

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

Types

type ACL 

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 

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 ACLBootstrap 

type ACLBootstrap struct {
	// AllowBootstrap will only be true if no existing management tokens
	// have been found.
	AllowBootstrap bool

	RaftIndex
}

ACLBootstrap keeps track of whether bootstrapping ACLs is allowed for a cluster.

type ACLOp 

type ACLOp string

ACLOp is used in RPCs to encode ACL operations.

type ACLPolicy 

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

ACLPolicy is a policy that can be associated with a token.

type ACLPolicyRequest 

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 

func (r *ACLPolicyRequest) RequestDatacenter() string

RequestDatacenter returns the DC this request is targeted to.

type ACLReplicationStatus 

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 

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

ACLRequest is used to create, update or delete an ACL

func (*ACLRequest) RequestDatacenter 

func (r *ACLRequest) RequestDatacenter() string

type ACLRequests 

type ACLRequests []*ACLRequest

ACLRequests is a list of ACL change requests.

type ACLSpecificRequest 

type ACLSpecificRequest struct {
	Datacenter string
	ACL        string
	QueryOptions
}

ACLSpecificRequest is used to request an ACL by ID

func (*ACLSpecificRequest) RequestDatacenter 

func (r *ACLSpecificRequest) RequestDatacenter() string

RequestDatacenter returns the DC this request is targeted to.

type ACLs 

type ACLs []*ACL

ACLs is a slice of ACLs.

type AutopilotSetConfigRequest 

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

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

	// 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 

func (op *AutopilotSetConfigRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type CheckDefinition 

type CheckDefinition struct {
	ID        types.CheckID
	Name      string
	Notes     string
	ServiceID string
	Token     string
	Status    string

	// Copied fields from CheckType without the fields
	// already present in CheckDefinition:
	//
	//   ID (CheckID), Name, Status, Notes
	//
	ScriptArgs                     []string
	HTTP                           string
	Header                         map[string][]string
	Method                         string
	TCP                            string
	Interval                       time.Duration
	DockerContainerID              string
	Shell                          string
	GRPC                           string
	GRPCUseTLS                     bool
	TLSSkipVerify                  bool
	Timeout                        time.Duration
	TTL                            time.Duration
	DeregisterCriticalServiceAfter time.Duration
}

CheckDefinition is used to JSON decode the Check definitions

func (*CheckDefinition) CheckType 

func (c *CheckDefinition) CheckType() *CheckType

func (*CheckDefinition) HealthCheck 

func (c *CheckDefinition) HealthCheck(node string) *HealthCheck

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 

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) FilterIgnore added in v1.0.7 

func (nodes CheckServiceNodes) FilterIgnore(onlyPassing bool,
	ignoreCheckIDs []types.CheckID) CheckServiceNodes

FilterIgnore removes nodes that are failing health checks just like Filter. It also ignores the status of any check with an ID present in ignoreCheckIDs as if that check didn't exist. Note that this returns the filtered results AND modifies the receiver for performance.

func (CheckServiceNodes) Shuffle 

func (nodes CheckServiceNodes) Shuffle()

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

type CheckType 

type CheckType struct {
	CheckID types.CheckID
	Name    string
	Status  string
	Notes   string

	ScriptArgs        []string
	HTTP              string
	Header            map[string][]string
	Method            string
	TCP               string
	Interval          time.Duration
	DockerContainerID string
	Shell             string
	GRPC              string
	GRPCUseTLS        bool
	TLSSkipVerify     bool
	Timeout           time.Duration
	TTL               time.Duration

	// DeregisterCriticalServiceAfter, if >0, will cause the associated
	// service, if any, to be deregistered if this check is critical for
	// longer than this duration.
	DeregisterCriticalServiceAfter time.Duration
}

CheckType is used to create either the CheckMonitor or the CheckTTL. Six types are supported: Script, HTTP, TCP, Docker, TTL and GRPC. Script, HTTP, Docker, TCP and GRPC all require Interval. Only one of the types may to be provided: TTL or Script/Interval or HTTP/Interval or TCP/Interval or Docker/Interval or GRPC/Interval.

func (*CheckType) Empty added in v1.0.0 

func (c *CheckType) Empty() bool

Empty checks if the CheckType has no fields defined. Empty checks parsed from json configs are filtered out

func (*CheckType) IsDocker 

func (c *CheckType) IsDocker() bool

IsDocker returns true when checking a docker container.

func (*CheckType) IsGRPC added in v1.0.4 

func (c *CheckType) IsGRPC() bool

IsGRPC checks if this is a GRPC type

func (*CheckType) IsHTTP 

func (c *CheckType) IsHTTP() bool

IsHTTP checks if this is a HTTP type

func (*CheckType) IsMonitor 

func (c *CheckType) IsMonitor() bool

IsMonitor checks if this is a Monitor type

func (*CheckType) IsScript 

func (c *CheckType) IsScript() bool

IsScript checks if this is a check that execs some kind of script.

func (*CheckType) IsTCP 

func (c *CheckType) IsTCP() bool

IsTCP checks if this is a TCP type

func (*CheckType) IsTTL 

func (c *CheckType) IsTTL() bool

IsTTL checks if this is a TTL type

func (*CheckType) Validate added in v1.0.0 

func (c *CheckType) Validate() error

Validate returns an error message if the check is invalid

type CheckTypes 

type CheckTypes []*CheckType

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 

func (r *ChecksInStateRequest) RequestDatacenter() string

type CompoundResponse 

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 

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

Coordinate stores a node name with its associated network coordinate.

type CoordinateUpdateRequest 

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

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

func (*CoordinateUpdateRequest) RequestDatacenter 

func (c *CoordinateUpdateRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given update request.

type Coordinates 

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 

func (r *DCSpecificRequest) RequestDatacenter() string

type DatacenterMap 

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 

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 

func (d *DirEntry) Clone() *DirEntry

Returns a clone of the given directory entry.

type EventFireRequest 

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 

func (r *EventFireRequest) RequestDatacenter() string

type EventFireResponse 

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

	Definition HealthCheckDefinition

	RaftIndex
}

HealthCheck represents a single check on a given node

func (*HealthCheck) Clone 

func (c *HealthCheck) Clone() *HealthCheck

Clone returns a distinct clone of the HealthCheck.

func (*HealthCheck) IsSame 

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 HealthCheckDefinition added in v1.0.1 

type HealthCheckDefinition struct {
	HTTP                           string               `json:",omitempty"`
	TLSSkipVerify                  bool                 `json:",omitempty"`
	Header                         map[string][]string  `json:",omitempty"`
	Method                         string               `json:",omitempty"`
	TCP                            string               `json:",omitempty"`
	Interval                       api.ReadableDuration `json:",omitempty"`
	Timeout                        api.ReadableDuration `json:",omitempty"`
	DeregisterCriticalServiceAfter api.ReadableDuration `json:",omitempty"`
}

type HealthChecks 

type HealthChecks []*HealthCheck

HealthChecks is a collection of HealthCheck structs.

type IndexedACLs 

type IndexedACLs struct {
	ACLs ACLs
	QueryMeta
}

IndexedACLs has tokens along with the Raft metadata about them.

type IndexedCheckServiceNodes 

type IndexedCheckServiceNodes struct {
	Nodes CheckServiceNodes
	QueryMeta
}

type IndexedCoordinate 

type IndexedCoordinate struct {
	Coord *coordinate.Coordinate
	QueryMeta
}

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

type IndexedCoordinates 

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 

type IndexedKeyList struct {
	Keys []string
	QueryMeta
}

type IndexedNodeDump 

type IndexedNodeDump struct {
	Dump NodeDump
	QueryMeta
}

type IndexedNodeServices 

type IndexedNodeServices struct {
	// TODO: This should not be a pointer, see comments in
	// agent/catalog_endpoint.go.
	NodeServices *NodeServices
	QueryMeta
}

type IndexedNodes 

type IndexedNodes struct {
	Nodes Nodes
	QueryMeta
}

type IndexedPreparedQueries 

type IndexedPreparedQueries struct {
	Queries PreparedQueries
	QueryMeta
}

type IndexedServiceNodes 

type IndexedServiceNodes struct {
	ServiceNodes ServiceNodes
	QueryMeta
}

type IndexedServices 

type IndexedServices struct {
	Services Services
	QueryMeta
}

type IndexedSessions 

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 

func (r *KVSRequest) RequestDatacenter() string

type KeyListRequest 

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

KeyListRequest is used to list keys

func (*KeyListRequest) RequestDatacenter 

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 

func (r *KeyRequest) RequestDatacenter() string

type KeyringOp 

type KeyringOp string

type KeyringRequest 

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 

func (r *KeyringRequest) RequestDatacenter() string

type KeyringResponse 

type KeyringResponse struct {
	WAN        bool
	Datacenter string
	Segment    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 

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 

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

func (*KeyringResponses) New 

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

type MessageType 

type MessageType uint8

type NetworkSegment added in v1.0.0 

type NetworkSegment struct {
	// Name is the name of the segment.
	Name string

	// Bind is the bind address for this segment.
	Bind *net.TCPAddr

	// Advertise is the advertise address of this segment.
	Advertise *net.TCPAddr

	// RPCListener is whether to bind a separate RPC listener on the bind address
	// for this segment.
	RPCListener bool
}

(Enterprise-only) NetworkSegment is the configuration for a network segment, which is an isolated serf group on the LAN.

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 

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 

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
	Meta              map[string]string
	Port              int
	EnableTagOverride bool

	RaftIndex
}

NodeService is a service provided by a node

func (*NodeService) IsSame 

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 

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 

func (r *NodeSpecificRequest) RequestDatacenter() string

type Nodes 

type Nodes []*Node

type PreparedQueries 

type PreparedQueries []*PreparedQuery

type PreparedQuery 

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 

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 

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 

func (q *PreparedQueryExecuteRemoteRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type PreparedQueryExecuteRequest 

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 

func (q *PreparedQueryExecuteRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type PreparedQueryExecuteResponse 

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 

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 

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

type PreparedQueryRequest 

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 

func (q *PreparedQueryRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type PreparedQuerySpecificRequest 

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 

func (q *PreparedQuerySpecificRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type QueryDNSOptions 

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 

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 

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

	// Consistencylevel returns the consistency used to serve the query
	// Having `discovery_max_stale` on the agent can affect whether
	// the request was served by a leader.
	ConsistencyLevel string
}

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

type QueryOptions 

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

	// If set and AllowStale is true, will try first a stale
	// read, and then will perform a consistent read if stale
	// read is older than value
	MaxStaleDuration time.Duration
}

QueryOptions is used to specify various flags for read queries

func (QueryOptions) ACLToken 

func (q QueryOptions) ACLToken() string

func (QueryOptions) AllowStaleRead 

func (q QueryOptions) AllowStaleRead() bool

func (QueryOptions) ConsistencyLevel added in v1.0.7 

func (q QueryOptions) ConsistencyLevel() string

ConsistencyLevel display the consistency required by a request

func (QueryOptions) IsRead 

func (q QueryOptions) IsRead() bool

IsRead is always true for QueryOption.

type QuerySource 

type QuerySource struct {
	Datacenter string
	Segment    string
	Node       string
	Ip         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 

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

	// RemoveEmptyTags, if true, removes empty tags from matched tag list
	RemoveEmptyTags bool
}

QueryTemplateOptions controls settings if this query is a template.

type RPCInfo 

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

RPCInfo is used to describe common information about query

type RaftConfigurationResponse 

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
}

RaftConfigurationResponse is returned when querying for the current Raft configuration.

type RaftIndex 

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 

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 

func (op *RaftRemovePeerRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type RaftServer 

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

	// Protocol version is the raft protocol version used by the server
	ProtocolVersion string

	// 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 

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 

func (r *RegisterRequest) RequestDatacenter() string

type ServiceDefinition 

type ServiceDefinition struct {
	ID                string
	Name              string
	Tags              []string
	Address           string
	Meta              map[string]string
	Port              int
	Check             CheckType
	Checks            CheckTypes
	Token             string
	EnableTagOverride bool
}

ServiceDefinition is used to JSON decode the Service definitions

func (*ServiceDefinition) CheckTypes 

func (s *ServiceDefinition) CheckTypes() (checks CheckTypes, err error)

func (*ServiceDefinition) NodeService 

func (s *ServiceDefinition) NodeService() *NodeService

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
	ServiceMeta              map[string]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 

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 

func (s *ServiceNode) ToNodeService() *NodeService

ToNodeService converts the given service node to a node service.

type ServiceNodes 

type ServiceNodes []*ServiceNode

type ServiceQuery 

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

	// IgnoreCheckIDs is an optional list of health check IDs to ignore when
	// considering which nodes are healthy. It is useful as an emergency measure
	// to temporarily override some health check that is producing false negatives
	// for example.
	IgnoreCheckIDs []types.CheckID

	// 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 

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 

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 

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

type SessionOp 

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

type SessionRequest 

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 

func (r *SessionRequest) RequestDatacenter() string

type SessionSpecificRequest 

type SessionSpecificRequest struct {
	Datacenter string
	Session    string
	QueryOptions
}

SessionSpecificRequest is used to request a session by ID

func (*SessionSpecificRequest) RequestDatacenter 

func (r *SessionSpecificRequest) RequestDatacenter() string

type Sessions 

type Sessions []*Session

type SnapshotOp 

type SnapshotOp int
const (
	SnapshotSave SnapshotOp = iota
	SnapshotRestore
)

type SnapshotReplyFn 

type SnapshotReplyFn func(reply *SnapshotResponse) error

SnapshotReplyFn gets a peek at the reply before the snapshot streams, which is useful for setting headers.

type SnapshotRequest 

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 

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 

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

type TombstoneRequest 

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

TombstoneRequest is used to trigger a reaping of the tombstones

func (*TombstoneRequest) RequestDatacenter 

func (r *TombstoneRequest) RequestDatacenter() string

type TxnError 

type TxnError struct {
	OpIndex int
	What    string
}

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

func (TxnError) Error 

func (e TxnError) Error() string

Error returns the string representation of an atomic error.

type TxnErrors 

type TxnErrors []*TxnError

TxnErrors is a list of TxnError entries.

type TxnKVOp 

type TxnKVOp struct {
	Verb   api.KVOp
	DirEnt DirEntry
}

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

type TxnKVResult 

type TxnKVResult *DirEntry

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

type TxnOp 

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 

type TxnOps []*TxnOp

TxnOps is a list of operations within a transaction.

type TxnReadRequest 

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 

func (r *TxnReadRequest) RequestDatacenter() string

type TxnReadResponse 

type TxnReadResponse struct {
	TxnResponse
	QueryMeta
}

TxnReadResponse is the structure returned by a TxnReadRequest.

type TxnRequest 

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 

func (r *TxnRequest) RequestDatacenter() string

type TxnResponse 

type TxnResponse struct {
	Results TxnResults
	Errors  TxnErrors
}

TxnResponse is the structure returned by a TxnRequest.

type TxnResult 

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 

type TxnResults []*TxnResult

TxnResults is a list of TxnResult entries.

type WriteRequest 

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 

func (w WriteRequest) ACLToken() string

func (WriteRequest) AllowStaleRead 

func (w WriteRequest) AllowStaleRead() bool

func (WriteRequest) IsRead 

func (w WriteRequest) IsRead() bool

WriteRequest only applies to writes, always false

Source Files

View all Source files

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.