Documentation
¶
Index ¶
- Constants
- Variables
- type ACL
- func (a *ACL) Clone(id string, q *WriteOptions) (string, *WriteMeta, error)
- func (a *ACL) Create(acl *ACLEntry, q *WriteOptions) (string, *WriteMeta, error)
- func (a *ACL) Destroy(id string, q *WriteOptions) (*WriteMeta, error)
- func (a *ACL) Info(id string, q *QueryOptions) (*ACLEntry, *QueryMeta, error)
- func (a *ACL) List(q *QueryOptions) ([]*ACLEntry, *QueryMeta, error)
- func (a *ACL) Update(acl *ACLEntry, q *WriteOptions) (*WriteMeta, error)
- type ACLEntry
- type Agent
- func (a *Agent) CheckDeregister(checkID string) error
- func (a *Agent) CheckRegister(check *AgentCheckRegistration) error
- func (a *Agent) Checks() (map[string]*AgentCheck, error)
- func (a *Agent) DisableNodeMaintenance() error
- func (a *Agent) DisableServiceMaintenance(serviceID string) error
- func (a *Agent) EnableNodeMaintenance(reason string) error
- func (a *Agent) EnableServiceMaintenance(serviceID, reason string) error
- func (a *Agent) FailTTL(checkID, note string) error
- func (a *Agent) ForceLeave(node string) error
- func (a *Agent) Join(addr string, wan bool) error
- func (a *Agent) Members(wan bool) ([]*AgentMember, error)
- func (a *Agent) NodeName() (string, error)
- func (a *Agent) PassTTL(checkID, note string) error
- func (a *Agent) Self() (map[string]map[string]interface{}, error)
- func (a *Agent) ServiceDeregister(serviceID string) error
- func (a *Agent) ServiceRegister(service *AgentServiceRegistration) error
- func (a *Agent) Services() (map[string]*AgentService, error)
- func (a *Agent) UpdateTTL(checkID, note, status string) error
- func (a *Agent) WarnTTL(checkID, note string) error
- type AgentCheck
- type AgentCheckRegistration
- type AgentMember
- type AgentService
- type AgentServiceCheck
- type AgentServiceChecks
- type AgentServiceRegistration
- type Catalog
- func (c *Catalog) Datacenters() ([]string, error)
- func (c *Catalog) Deregister(dereg *CatalogDeregistration, q *WriteOptions) (*WriteMeta, error)
- func (c *Catalog) Node(node string, q *QueryOptions) (*CatalogNode, *QueryMeta, error)
- func (c *Catalog) Nodes(q *QueryOptions) ([]*Node, *QueryMeta, error)
- func (c *Catalog) Register(reg *CatalogRegistration, q *WriteOptions) (*WriteMeta, error)
- func (c *Catalog) Service(service, tag string, q *QueryOptions) ([]*CatalogService, *QueryMeta, error)
- func (c *Catalog) Services(q *QueryOptions) (map[string][]string, *QueryMeta, error)
- type CatalogDeregistration
- type CatalogNode
- type CatalogRegistration
- type CatalogService
- type Client
- func (c *Client) ACL() *ACL
- func (c *Client) Agent() *Agent
- func (c *Client) Catalog() *Catalog
- func (c *Client) Coordinate() *Coordinate
- func (c *Client) Event() *Event
- func (c *Client) Health() *Health
- func (c *Client) KV() *KV
- func (c *Client) LockKey(key string) (*Lock, error)
- func (c *Client) LockOpts(opts *LockOptions) (*Lock, error)
- func (c *Client) PreparedQuery() *PreparedQuery
- func (c *Client) Raw() *Raw
- func (c *Client) SemaphoreOpts(opts *SemaphoreOptions) (*Semaphore, error)
- func (c *Client) SemaphorePrefix(prefix string, limit int) (*Semaphore, error)
- func (c *Client) Session() *Session
- func (c *Client) Status() *Status
- type Config
- type Coordinate
- type CoordinateDatacenterMap
- type CoordinateEntry
- type Event
- type Health
- func (h *Health) Checks(service string, q *QueryOptions) ([]*HealthCheck, *QueryMeta, error)
- func (h *Health) Node(node string, q *QueryOptions) ([]*HealthCheck, *QueryMeta, error)
- func (h *Health) Service(service, tag string, passingOnly bool, q *QueryOptions) ([]*ServiceEntry, *QueryMeta, error)
- func (h *Health) State(state string, q *QueryOptions) ([]*HealthCheck, *QueryMeta, error)
- type HealthCheck
- type HttpBasicAuth
- type KV
- func (k *KV) Acquire(p *KVPair, q *WriteOptions) (bool, *WriteMeta, error)
- func (k *KV) CAS(p *KVPair, q *WriteOptions) (bool, *WriteMeta, error)
- func (k *KV) Delete(key string, w *WriteOptions) (*WriteMeta, error)
- func (k *KV) DeleteCAS(p *KVPair, q *WriteOptions) (bool, *WriteMeta, error)
- func (k *KV) DeleteTree(prefix string, w *WriteOptions) (*WriteMeta, error)
- func (k *KV) Get(key string, q *QueryOptions) (*KVPair, *QueryMeta, error)
- func (k *KV) Keys(prefix, separator string, q *QueryOptions) ([]string, *QueryMeta, error)
- func (k *KV) List(prefix string, q *QueryOptions) (KVPairs, *QueryMeta, error)
- func (k *KV) Put(p *KVPair, q *WriteOptions) (*WriteMeta, error)
- func (k *KV) Release(p *KVPair, q *WriteOptions) (bool, *WriteMeta, error)
- type KVPair
- type KVPairs
- type Lock
- type LockOptions
- type Node
- type PreparedQuery
- func (c *PreparedQuery) Create(query *PreparedQueryDefinition, q *WriteOptions) (string, *WriteMeta, error)
- func (c *PreparedQuery) Delete(queryID string, q *QueryOptions) (*QueryMeta, error)
- func (c *PreparedQuery) Execute(queryIDOrName string, q *QueryOptions) (*PreparedQueryExecuteResponse, *QueryMeta, error)
- func (c *PreparedQuery) Get(queryID string, q *QueryOptions) ([]*PreparedQueryDefinition, *QueryMeta, error)
- func (c *PreparedQuery) List(q *QueryOptions) ([]*PreparedQueryDefinition, *QueryMeta, error)
- func (c *PreparedQuery) Update(query *PreparedQueryDefinition, q *WriteOptions) (*WriteMeta, error)
- type PreparedQueryDefinition
- type PreparedQueryExecuteResponse
- type QueryDNSOptions
- type QueryDatacenterOptions
- type QueryMeta
- type QueryOptions
- type Raw
- type Semaphore
- type SemaphoreOptions
- type ServiceEntry
- type ServiceQuery
- type Session
- func (s *Session) Create(se *SessionEntry, q *WriteOptions) (string, *WriteMeta, error)
- func (s *Session) CreateNoChecks(se *SessionEntry, q *WriteOptions) (string, *WriteMeta, error)
- func (s *Session) Destroy(id string, q *WriteOptions) (*WriteMeta, error)
- func (s *Session) Info(id string, q *QueryOptions) (*SessionEntry, *QueryMeta, error)
- func (s *Session) List(q *QueryOptions) ([]*SessionEntry, *QueryMeta, error)
- func (s *Session) Node(node string, q *QueryOptions) ([]*SessionEntry, *QueryMeta, error)
- func (s *Session) Renew(id string, q *WriteOptions) (*SessionEntry, *WriteMeta, error)
- func (s *Session) RenewPeriodic(initialTTL string, id string, q *WriteOptions, doneCh chan struct{}) error
- type SessionEntry
- type Status
- type UserEvent
- type WriteMeta
- type WriteOptions
Constants ¶
const ( // ACLCLientType is the client type token ACLClientType = "client" // ACLManagementType is the management type token ACLManagementType = "management" )
const ( // DefaultLockSessionName is the Session Name we assign if none is provided DefaultLockSessionName = "Consul API Lock" // DefaultLockSessionTTL is the default session TTL if no Session is provided // when creating a new Lock. This is used because we do not have another // other check to depend upon. DefaultLockSessionTTL = "15s" // DefaultLockWaitTime is how long we block for at a time to check if lock // acquisition is possible. This affects the minimum time it takes to cancel // a Lock acquisition. DefaultLockWaitTime = 15 * time.Second // DefaultLockRetryTime is how long we wait after a failed lock acquisition // before attempting to do the lock again. This is so that once a lock-delay // is in affect, we do not hot loop retrying the acquisition. DefaultLockRetryTime = 5 * time.Second // LockFlagValue is a magic flag we set to indicate a key // is being used for a lock. It is used to detect a potential // conflict with a semaphore. LockFlagValue = 0x2ddccbc058a50c18 )
const ( // DefaultSemaphoreSessionName is the Session Name we assign if none is provided DefaultSemaphoreSessionName = "Consul API Semaphore" // DefaultSemaphoreSessionTTL is the default session TTL if no Session is provided // when creating a new Semaphore. This is used because we do not have another // other check to depend upon. DefaultSemaphoreSessionTTL = "15s" // DefaultSemaphoreWaitTime is how long we block for at a time to check if semaphore // acquisition is possible. This affects the minimum time it takes to cancel // a Semaphore acquisition. DefaultSemaphoreWaitTime = 15 * time.Second // DefaultSemaphoreKey is the key used within the prefix to // use for coordination between all the contenders. DefaultSemaphoreKey = ".lock" // SemaphoreFlagValue is a magic flag we set to indicate a key // is being used for a semaphore. It is used to detect a potential // conflict with a lock. SemaphoreFlagValue = 0xe0f69a2baa414de0 )
const ( // SessionBehaviorRelease is the default behavior and causes // all associated locks to be released on session invalidation. SessionBehaviorRelease = "release" // SessionBehaviorDelete is new in Consul 0.5 and changes the // behavior to delete all associated locks on session invalidation. // It can be used in a way similar to Ephemeral Nodes in ZooKeeper. SessionBehaviorDelete = "delete" )
Variables ¶
var ( // ErrLockHeld is returned if we attempt to double lock ErrLockHeld = fmt.Errorf("Lock already held") // ErrLockNotHeld is returned if we attempt to unlock a lock // that we do not hold. ErrLockNotHeld = fmt.Errorf("Lock not held") // ErrLockInUse is returned if we attempt to destroy a lock // that is in use. ErrLockInUse = fmt.Errorf("Lock in use") // ErrLockConflict is returned if the flags on a key // used for a lock do not match expectation ErrLockConflict = fmt.Errorf("Existing key does not match lock use") )
var ( // ErrSemaphoreHeld is returned if we attempt to double lock ErrSemaphoreHeld = fmt.Errorf("Semaphore already held") // ErrSemaphoreNotHeld is returned if we attempt to unlock a semaphore // that we do not hold. ErrSemaphoreNotHeld = fmt.Errorf("Semaphore not held") // ErrSemaphoreInUse is returned if we attempt to destroy a semaphore // that is in use. ErrSemaphoreInUse = fmt.Errorf("Semaphore in use") // ErrSemaphoreConflict is returned if the flags on a key // used for a semaphore do not match expectation ErrSemaphoreConflict = fmt.Errorf("Existing key does not match semaphore use") )
var ErrSessionExpired = errors.New("session expired")
Functions ¶
This section is empty.
Types ¶
type ACL ¶
type ACL struct {
// contains filtered or unexported fields
}
ACL can be used to query the ACL endpoints
func (*ACL) Destroy ¶
func (a *ACL) Destroy(id string, q *WriteOptions) (*WriteMeta, error)
Destroy is used to destroy a given ACL token ID
type ACLEntry ¶
type ACLEntry struct { CreateIndex uint64 ModifyIndex uint64 ID string Name string Type string Rules string }
ACLEntry is used to represent an ACL entry
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
Agent can be used to query the Agent endpoints
func (*Agent) CheckDeregister ¶
CheckDeregister is used to deregister a check with the local agent
func (*Agent) CheckRegister ¶
func (a *Agent) CheckRegister(check *AgentCheckRegistration) error
CheckRegister is used to register a new check with the local agent
func (*Agent) Checks ¶
func (a *Agent) Checks() (map[string]*AgentCheck, error)
Checks returns the locally registered checks
func (*Agent) DisableNodeMaintenance ¶
DisableNodeMaintenance toggles node maintenance mode off for the agent we are connected to.
func (*Agent) DisableServiceMaintenance ¶
DisableServiceMaintenance toggles service maintenance mode off for the given service ID.
func (*Agent) EnableNodeMaintenance ¶
EnableNodeMaintenance toggles node maintenance mode on for the agent we are connected to.
func (*Agent) EnableServiceMaintenance ¶
EnableServiceMaintenance toggles service maintenance mode on for the given service ID.
func (*Agent) ForceLeave ¶
ForceLeave is used to have the agent eject a failed node
func (*Agent) Members ¶
func (a *Agent) Members(wan bool) ([]*AgentMember, error)
Members returns the known gossip members. The WAN flag can be used to query a server for WAN members.
func (*Agent) Self ¶
Self is used to query the agent we are speaking to for information about itself
func (*Agent) ServiceDeregister ¶
ServiceDeregister is used to deregister a service with the local agent
func (*Agent) ServiceRegister ¶
func (a *Agent) ServiceRegister(service *AgentServiceRegistration) error
ServiceRegister is used to register a new service with the local agent
func (*Agent) Services ¶
func (a *Agent) Services() (map[string]*AgentService, error)
Services returns the locally registered services
type AgentCheck ¶
type AgentCheck struct { Node string CheckID string Name string Status string Notes string Output string ServiceID string ServiceName string }
AgentCheck represents a check known to the agent
type AgentCheckRegistration ¶
type AgentCheckRegistration struct { ID string `json:",omitempty"` Name string `json:",omitempty"` Notes string `json:",omitempty"` ServiceID string `json:",omitempty"` AgentServiceCheck }
AgentCheckRegistration is used to register a new check
type AgentMember ¶
type AgentMember struct { Name string Addr string Port uint16 Tags map[string]string Status int ProtocolMin uint8 ProtocolMax uint8 ProtocolCur uint8 DelegateMin uint8 DelegateMax uint8 DelegateCur uint8 }
AgentMember represents a cluster member known to the agent
type AgentService ¶
AgentService represents a service known to the agent
type AgentServiceCheck ¶
type AgentServiceCheck struct { Script string `json:",omitempty"` Interval string `json:",omitempty"` Timeout string `json:",omitempty"` TTL string `json:",omitempty"` HTTP string `json:",omitempty"` TCP string `json:",omitempty"` Status string `json:",omitempty"` }
AgentServiceCheck is used to create an associated check for a service
type AgentServiceChecks ¶
type AgentServiceChecks []*AgentServiceCheck
type AgentServiceRegistration ¶
type AgentServiceRegistration struct { ID string `json:",omitempty"` Name string `json:",omitempty"` Tags []string `json:",omitempty"` Port int `json:",omitempty"` Address string `json:",omitempty"` Check *AgentServiceCheck Checks AgentServiceChecks }
AgentServiceRegistration is used to register a new service
type Catalog ¶
type Catalog struct {
// contains filtered or unexported fields
}
Catalog can be used to query the Catalog endpoints
func (*Catalog) Datacenters ¶
Datacenters is used to query for all the known datacenters
func (*Catalog) Deregister ¶
func (c *Catalog) Deregister(dereg *CatalogDeregistration, q *WriteOptions) (*WriteMeta, error)
func (*Catalog) Node ¶
func (c *Catalog) Node(node string, q *QueryOptions) (*CatalogNode, *QueryMeta, error)
Node is used to query for service information about a single node
func (*Catalog) Nodes ¶
func (c *Catalog) Nodes(q *QueryOptions) ([]*Node, *QueryMeta, error)
Nodes is used to query all the known nodes
func (*Catalog) Register ¶
func (c *Catalog) Register(reg *CatalogRegistration, q *WriteOptions) (*WriteMeta, error)
func (*Catalog) Service ¶
func (c *Catalog) Service(service, tag string, q *QueryOptions) ([]*CatalogService, *QueryMeta, error)
Service is used to query catalog entries for a given service
type CatalogDeregistration ¶
type CatalogNode ¶
type CatalogNode struct { Node *Node Services map[string]*AgentService }
type CatalogRegistration ¶
type CatalogRegistration struct { Node string Address string Datacenter string Service *AgentService Check *AgentCheck }
type CatalogService ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client provides a client to the Consul API
func (*Client) Coordinate ¶
func (c *Client) Coordinate() *Coordinate
Coordinate returns a handle to the coordinate endpoints
func (*Client) LockKey ¶
LockKey returns a handle to a lock struct which can be used to acquire and release the mutex. The key used must have write permissions.
func (*Client) LockOpts ¶
func (c *Client) LockOpts(opts *LockOptions) (*Lock, error)
LockOpts returns a handle to a lock struct which can be used to acquire and release the mutex. The key used must have write permissions.
func (*Client) PreparedQuery ¶
func (c *Client) PreparedQuery() *PreparedQuery
PreparedQuery returns a handle to the prepared query endpoints.
func (*Client) SemaphoreOpts ¶
func (c *Client) SemaphoreOpts(opts *SemaphoreOptions) (*Semaphore, error)
SemaphoreOpts is used to create a Semaphore with the given options. The prefix must have write privileges, and the limit must be agreed upon by all contenders. If a Session is not provided, one will be created.
func (*Client) SemaphorePrefix ¶
SemaphorePrefix is used to created a Semaphore which will operate at the given KV prefix and uses the given limit for the semaphore. The prefix must have write privileges, and the limit must be agreed upon by all contenders.
type Config ¶
type Config struct { // Address is the address of the Consul server Address string // Scheme is the URI scheme for the Consul server Scheme string // Datacenter to use. If not provided, the default agent datacenter is used. Datacenter string // HttpClient is the client to use. Default will be // used if not provided. HttpClient *http.Client // HttpAuth is the auth info to use for http access. HttpAuth *HttpBasicAuth // WaitTime limits how long a Watch will block. If not provided, // the agent default values will be used. WaitTime time.Duration // Token is used to provide a per-request ACL token // which overrides the agent's default token. Token string }
Config is used to configure the creation of a client
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns a default configuration for the client
type Coordinate ¶
type Coordinate struct {
// contains filtered or unexported fields
}
Coordinate can be used to query the coordinate endpoints
func (*Coordinate) Datacenters ¶
func (c *Coordinate) Datacenters() ([]*CoordinateDatacenterMap, error)
Datacenters is used to return the coordinates of all the servers in the WAN pool.
func (*Coordinate) Nodes ¶
func (c *Coordinate) Nodes(q *QueryOptions) ([]*CoordinateEntry, *QueryMeta, error)
Nodes is used to return the coordinates of all the nodes in the LAN pool.
type CoordinateDatacenterMap ¶
type CoordinateDatacenterMap struct { Datacenter string Coordinates []CoordinateEntry }
CoordinateDatacenterMap represents a datacenter and its associated WAN nodes and their associates coordinates.
type CoordinateEntry ¶
type CoordinateEntry struct { Node string Coord *coordinate.Coordinate }
CoordinateEntry represents a node and its associated network coordinate.
type Event ¶
type Event struct {
// contains filtered or unexported fields
}
Event can be used to query the Event endpoints
func (*Event) Fire ¶
Fire is used to fire a new user event. Only the Name, Payload and Filters are respected. This returns the ID or an associated error. Cross DC requests are supported.
func (*Event) IDToIndex ¶
IDToIndex is a bit of a hack. This simulates the index generation to convert an event ID into a WaitIndex.
type Health ¶
type Health struct {
// contains filtered or unexported fields
}
Health can be used to query the Health endpoints
func (*Health) Checks ¶
func (h *Health) Checks(service string, q *QueryOptions) ([]*HealthCheck, *QueryMeta, error)
Checks is used to return the checks associated with a service
func (*Health) Node ¶
func (h *Health) Node(node string, q *QueryOptions) ([]*HealthCheck, *QueryMeta, error)
Node is used to query for checks belonging to a given node
func (*Health) Service ¶
func (h *Health) Service(service, tag string, passingOnly bool, q *QueryOptions) ([]*ServiceEntry, *QueryMeta, error)
Service is used to query health information along with service info for a given service. It can optionally do server-side filtering on a tag or nodes with passing health checks only.
func (*Health) State ¶
func (h *Health) State(state string, q *QueryOptions) ([]*HealthCheck, *QueryMeta, error)
State is used to retrieve all the checks in a given state. The wildcard "any" state can also be used for all checks.
type HealthCheck ¶
type HealthCheck struct { Node string CheckID string Name string Status string Notes string Output string ServiceID string ServiceName string }
HealthCheck is used to represent a single check
type HttpBasicAuth ¶
type HttpBasicAuth struct { // Username to use for HTTP Basic Authentication Username string // Password to use for HTTP Basic Authentication Password string }
HttpBasicAuth is used to authenticate http client with HTTP Basic Authentication
type KV ¶
type KV struct {
// contains filtered or unexported fields
}
KV is used to manipulate the K/V API
func (*KV) Acquire ¶
Acquire is used for a lock acquisition operation. The Key, Flags, Value and Session are respected. Returns true on success or false on failures.
func (*KV) CAS ¶
CAS is used for a Check-And-Set operation. The Key, ModifyIndex, Flags and Value are respected. Returns true on success or false on failures.
func (*KV) Delete ¶
func (k *KV) Delete(key string, w *WriteOptions) (*WriteMeta, error)
Delete is used to delete a single key
func (*KV) DeleteCAS ¶
DeleteCAS is used for a Delete Check-And-Set operation. The Key and ModifyIndex are respected. Returns true on success or false on failures.
func (*KV) DeleteTree ¶
func (k *KV) DeleteTree(prefix string, w *WriteOptions) (*WriteMeta, error)
DeleteTree is used to delete all keys under a prefix
func (*KV) Keys ¶
Keys is used to list all the keys under a prefix. Optionally, a separator can be used to limit the responses.
type KVPair ¶
type KVPair struct { Key string CreateIndex uint64 ModifyIndex uint64 LockIndex uint64 Flags uint64 Value []byte Session string }
KVPair is used to represent a single K/V entry
type Lock ¶
type Lock struct {
// contains filtered or unexported fields
}
Lock is used to implement client-side leader election. It is follows the algorithm as described here: https://consul.io/docs/guides/leader-election.html.
func (*Lock) Destroy ¶
Destroy is used to cleanup the lock entry. It is not necessary to invoke. It will fail if the lock is in use.
func (*Lock) Lock ¶
Lock attempts to acquire the lock and blocks while doing so. Providing a non-nil stopCh can be used to abort the lock attempt. Returns a channel that is closed if our lock is lost or an error. This channel could be closed at any time due to session invalidation, communication errors, operator intervention, etc. It is NOT safe to assume that the lock is held until Unlock() unless the Session is specifically created without any associated health checks. By default Consul sessions prefer liveness over safety and an application must be able to handle the lock being lost.
type LockOptions ¶
type LockOptions struct { Key string // Must be set and have write permissions Value []byte // Optional, value to associate with the lock Session string // Optional, created if not specified SessionName string // Optional, defaults to DefaultLockSessionName SessionTTL string // Optional, defaults to DefaultLockSessionTTL }
LockOptions is used to parameterize the Lock behavior.
type PreparedQuery ¶
type PreparedQuery struct {
// contains filtered or unexported fields
}
PreparedQuery can be used to query the prepared query endpoints.
func (*PreparedQuery) Create ¶
func (c *PreparedQuery) Create(query *PreparedQueryDefinition, q *WriteOptions) (string, *WriteMeta, error)
Create makes a new prepared query. The ID of the new query is returned.
func (*PreparedQuery) Delete ¶
func (c *PreparedQuery) Delete(queryID string, q *QueryOptions) (*QueryMeta, error)
Delete is used to delete a specific prepared query.
func (*PreparedQuery) Execute ¶
func (c *PreparedQuery) Execute(queryIDOrName string, q *QueryOptions) (*PreparedQueryExecuteResponse, *QueryMeta, error)
Execute is used to execute a specific prepared query. You can execute using a query ID or name.
func (*PreparedQuery) Get ¶
func (c *PreparedQuery) Get(queryID string, q *QueryOptions) ([]*PreparedQueryDefinition, *QueryMeta, error)
Get is used to fetch a specific prepared query.
func (*PreparedQuery) List ¶
func (c *PreparedQuery) List(q *QueryOptions) ([]*PreparedQueryDefinition, *QueryMeta, error)
List is used to fetch all the prepared queries (always requires a management token).
func (*PreparedQuery) Update ¶
func (c *PreparedQuery) Update(query *PreparedQueryDefinition, q *WriteOptions) (*WriteMeta, error)
Update makes updates to an existing prepared query.
type PreparedQueryDefinition ¶
type PreparedQueryDefinition 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 // 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 }
PrepatedQueryDefinition defines a complete prepared query.
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 []ServiceEntry // 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 }
PreparedQueryExecuteResponse has the results of executing a query.
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 { // LastIndex. This can be used as a WaitIndex to perform // a blocking query LastIndex uint64 // Time of last contact from the leader for the // server servicing the request LastContact time.Duration // Is there a known leader KnownLeader bool // How long did the request take RequestTime time.Duration }
QueryMeta is used to return meta data about a query
type QueryOptions ¶
type QueryOptions struct { // Providing a datacenter overwrites the DC provided // by the Config Datacenter string // AllowStale allows any Consul server (non-leader) to service // a read. This allows for lower latency and higher throughput AllowStale bool // RequireConsistent forces the read to be fully consistent. // This is more expensive but prevents ever performing a stale // read. RequireConsistent bool // WaitIndex is used to enable a blocking query. Waits // until the timeout or the next index is reached WaitIndex uint64 // WaitTime is used to bound the duration of a wait. // Defaults to that of the Config, but can be overridden. WaitTime time.Duration // Token is used to provide a per-request ACL token // which overrides the agent's default token. Token string // Near is used to provide a node name that will sort the results // in ascending order based on the estimated round trip time from // that node. Setting this to "_agent" will use the agent's node // for the sort. Near string }
QueryOptions are used to parameterize a query
type Raw ¶
type Raw struct {
// contains filtered or unexported fields
}
Raw can be used to do raw queries against custom endpoints
type Semaphore ¶
type Semaphore struct {
// contains filtered or unexported fields
}
Semaphore is used to implement a distributed semaphore using the Consul KV primitives.
func (*Semaphore) Acquire ¶
Acquire attempts to reserve a slot in the semaphore, blocking until success, interrupted via the stopCh or an error is encountered. Providing a non-nil stopCh can be used to abort the attempt. On success, a channel is returned that represents our slot. This channel could be closed at any time due to session invalidation, communication errors, operator intervention, etc. It is NOT safe to assume that the slot is held until Release() unless the Session is specifically created without any associated health checks. By default Consul sessions prefer liveness over safety and an application must be able to handle the session being lost.
type SemaphoreOptions ¶
type SemaphoreOptions struct { Prefix string // Must be set and have write permissions Limit int // Must be set, and be positive Value []byte // Optional, value to associate with the contender entry Session string // Optional, created if not specified SessionName string // Optional, defaults to DefaultLockSessionName SessionTTL string // Optional, defaults to DefaultLockSessionTTL }
SemaphoreOptions is used to parameterize the Semaphore
type ServiceEntry ¶
type ServiceEntry struct { Node *Node Service *AgentService Checks []*HealthCheck }
ServiceEntry is used for the health service endpoint
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 // 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 }
ServiceQuery is used to query for a set of healthy nodes offering a specific service.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session can be used to query the Session endpoints
func (*Session) Create ¶
func (s *Session) Create(se *SessionEntry, q *WriteOptions) (string, *WriteMeta, error)
Create makes a new session. Providing a session entry can customize the session. It can also be nil to use defaults.
func (*Session) CreateNoChecks ¶
func (s *Session) CreateNoChecks(se *SessionEntry, q *WriteOptions) (string, *WriteMeta, error)
CreateNoChecks is like Create but is used specifically to create a session with no associated health checks.
func (*Session) Destroy ¶
func (s *Session) Destroy(id string, q *WriteOptions) (*WriteMeta, error)
Destroy invalidates a given session
func (*Session) Info ¶
func (s *Session) Info(id string, q *QueryOptions) (*SessionEntry, *QueryMeta, error)
Info looks up a single session
func (*Session) List ¶
func (s *Session) List(q *QueryOptions) ([]*SessionEntry, *QueryMeta, error)
List gets all active sessions
func (*Session) Node ¶
func (s *Session) Node(node string, q *QueryOptions) ([]*SessionEntry, *QueryMeta, error)
List gets sessions for a node
func (*Session) Renew ¶
func (s *Session) Renew(id string, q *WriteOptions) (*SessionEntry, *WriteMeta, error)
Renew renews the TTL on a given session
func (*Session) RenewPeriodic ¶
func (s *Session) RenewPeriodic(initialTTL string, id string, q *WriteOptions, doneCh chan struct{}) error
RenewPeriodic is used to periodically invoke Session.Renew on a session until a doneCh is closed. This is meant to be used in a long running goroutine to ensure a session stays valid.
type SessionEntry ¶
type SessionEntry struct { CreateIndex uint64 ID string Name string Node string Checks []string LockDelay time.Duration Behavior string TTL string }
SessionEntry represents a session in consul
type Status ¶
type Status struct {
// contains filtered or unexported fields
}
Status can be used to query the Status endpoints
type UserEvent ¶
type UserEvent struct { ID string Name string Payload []byte NodeFilter string ServiceFilter string TagFilter string Version int LTime uint64 }
UserEvent represents an event that was fired by the user
type WriteOptions ¶
type WriteOptions struct { // Providing a datacenter overwrites the DC provided // by the Config Datacenter string // Token is used to provide a per-request ACL token // which overrides the agent's default token. Token string }
WriteOptions are used to parameterize a write