agency

package
v1.6.6 Latest Latest
Warning

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

 Go to latest Published: Feb 24, 2025 License: Apache-2.0 Imports: 13 Imported by: 14

Documentation

Overview

Package agency provides an API to access the ArangoDB agency (it is unlikely that you need this package directly).

The Agency is fault-tolerant and highly-available key-value store that is used to store critical, low-level information about an ArangoDB cluster.

THIS API IS NOT USED FOR NORMAL DATABASE ACCESS.

Reasons for using this API are: - You want to make use of an indepent Agency as your own HA key-value store. - You want access to low-level information of your database. USE WITH GREAT CARE!

WARNING: Messing around in the Agency can quickly lead to a corrupt database!

Index

Constants

This section is empty.

Variables

View Source 
var (
	// AlreadyLockedError indicates that the lock is already locked.
	AlreadyLockedError = errors.New("already locked")
	// NotLockedError indicates that the lock is not locked when trying to unlock.
	NotLockedError = errors.New("not locked")
)

Functions

func AreAgentsHealthy 

func AreAgentsHealthy(ctx context.Context, clients []driver.Connection) error

AreAgentsHealthy performs a health check on all given agents. Of the given agents, 1 must respond as leader and all others must redirect to the leader. The function returns nil when all agents are healthy or an error when something is wrong.

func IsAlreadyLocked 

func IsAlreadyLocked(err error) bool

IsAlreadyLocked returns true if the given error is or is caused by an AlreadyLockedError.

func IsKeyNotFound 

func IsKeyNotFound(err error) bool

IsKeyNotFound returns true if the given error is (or is caused by) a KeyNotFoundError.

func IsNotLocked 

func IsNotLocked(err error) bool

IsNotLocked returns true if the given error is or is caused by an NotLockedError.

func IsSameEndpoint 

func IsSameEndpoint(a, b string) bool

IsSameEndpoint returns true when the 2 given endpoints refer to the same server.

func NewAgencyConnection 

func NewAgencyConnection(config http.ConnectionConfig) (driver.Connection, error)

NewAgencyConnection creates an agency connection for agents at the given endpoints. This type of connection differs from normal HTTP/VST connection in the way requests are executed. This type of connection makes use of the fact that only 1 agent will respond to requests at a time. All other agents will respond with an "I'm not the leader" error. A request will be send to all agents at the same time. The result of the first agent to respond with a normal response is used.

func WithAllowDifferentLeaderEndpoints 

func WithAllowDifferentLeaderEndpoints(parent context.Context) context.Context

WithAllowNoLeader is used to configure a context to make AreAgentsHealthy accept the situation where leader endpoint is different (during agency endpoint update).

func WithAllowNoLeader 

func WithAllowNoLeader(parent context.Context) context.Context

WithAllowNoLeader is used to configure a context to make AreAgentsHealthy accept the situation where it finds 0 leaders.

Types

type Agency 

type Agency interface {
	// Connection returns the connection used by this api.
	Connection() driver.Connection

	// ReadKey reads the value of a given key in the agency.
	ReadKey(ctx context.Context, key []string, value interface{}) error

	// WriteTransaction performs transaction in the agency.
	// Transaction can have a list of operations to perform like e.g. delete, set, observe...
	// Transaction can have preconditions which must be fulfilled to perform transaction.
	WriteTransaction(ctx context.Context, transaction Transaction) error

	// Deprecated: TTL param is removed since 3.12, use WriteTransaction instead
	//
	// WriteKey writes the given value with the given key with a given TTL (unless TTL is zero).
	// If you pass a condition (only 1 allowed), this condition has to be true,
	// otherwise the write will fail with a ConditionFailed error.
	WriteKey(ctx context.Context, key []string, value interface{}, ttl time.Duration, condition ...WriteCondition) error

	// Deprecated: use 'WriteTransaction' instead
	//
	// WriteKeyIfEmpty writes the given value with the given key only if the key was empty before.
	WriteKeyIfEmpty(ctx context.Context, key []string, value interface{}, ttl time.Duration) error

	// Deprecated: use 'WriteTransaction' instead
	//
	// WriteKeyIfEqualTo writes the given new value with the given key only if the existing value for that key equals
	// to the given old value.
	WriteKeyIfEqualTo(ctx context.Context, key []string, newValue, oldValue interface{}, ttl time.Duration) error

	// Deprecated: use 'WriteTransaction' instead
	//
	// RemoveKey removes the given key.
	// If you pass a condition (only 1 allowed), this condition has to be true,
	// otherwise the remove will fail with a ConditionFailed error.
	RemoveKey(ctx context.Context, key []string, condition ...WriteCondition) error

	// Deprecated: use 'WriteTransaction' instead
	//
	// RemoveKeyIfEqualTo removes the given key only if the existing value for that key equals
	// to the given old value.
	RemoveKeyIfEqualTo(ctx context.Context, key []string, oldValue interface{}) error

	// Deprecated: use 'WriteTransaction' instead
	//
	// Register a URL to receive notification callbacks when the value of the given key changes
	RegisterChangeCallback(ctx context.Context, key []string, cbURL string) error

	// Deprecated: use 'WriteTransaction' instead
	//
	// Register a URL to receive notification callbacks when the value of the given key changes
	UnregisterChangeCallback(ctx context.Context, key []string, cbURL string) error
}

Agency provides API implemented by the ArangoDB agency.

func NewAgency 

func NewAgency(conn driver.Connection) (Agency, error)

NewAgency creates an Agency accessor for the given connection. The connection must contain the endpoints of one or more agents, and only agents.

type ConditionsMap 

type ConditionsMap map[string]KeyConditioner

func ConvertWriteCondition 

func ConvertWriteCondition(cond WriteCondition) ConditionsMap

ConvertWriteCondition creates new conditions to the transaction using deprecated structure 'WriteCondition'

type Key 

type Key []string

func (Key) CreateSubKey 

func (k Key) CreateSubKey(elements ...string) Key

CreateSubKey creates new key based on receiver key. Returns new key with new allocated memory.

type KeyChanger 

type KeyChanger interface {
	// GetKey returns which key must be changed
	GetKey() string
	// GetOperation returns what type of operation must be performed on a key
	GetOperation() string
	// GetURL returns URL address where must be sent callback in case of some changes on key
	GetURL() string
	// GetNew returns new value for a key in the agency
	GetNew() interface{}
	// GetVal returns new value for a key in the agency
	GetVal() interface{}

	// Deprecated: removed since 3.12
	//
	// GetTTL returns how long (in seconds) a key will live in the agency
	GetTTL() time.Duration
}

KeyChanger describes how operation should be performed on a key in the agency

func NewKeyArrayErase 

func NewKeyArrayErase(key []string, value interface{}) KeyChanger

NewKeyArrayErase returns a new key operation for removing elements from the array.

func NewKeyArrayPush 

func NewKeyArrayPush(key []string, value interface{}) KeyChanger

NewKeyArrayPush returns a new key operation for adding elements to the array.

func NewKeyArrayReplace 

func NewKeyArrayReplace(key []string, oldValue, newValue interface{}) KeyChanger

NewKeyArrayReplace returns a new key operation for replacing element in the array.

func NewKeyDelete 

func NewKeyDelete(key []string) KeyChanger

NewKeyDelete returns a new key operation which must be removed from the agency

func NewKeyObserve deprecated 

func NewKeyObserve(key []string, URL string, observe bool) KeyChanger

NewKeyObserve returns a new key callback operation which must be written in the agency. URL parameter describes where callback must be sent in case of changes on a key. When 'observe' is false then we want to stop observing a key.

Deprecated: observe param is removed since 3.12

func NewKeySet deprecated 

func NewKeySet(key []string, value interface{}, TTL time.Duration) KeyChanger

NewKeySet returns a new key operation which must be set in the agency

Deprecated: TTL param is removed since 3.12, use NewKeySetV2 instead

func NewKeySetV2 added in v1.6.1 

func NewKeySetV2(key []string, value interface{}) KeyChanger

NewKeySetV2 returns a new key operation which must be set in the agency

type KeyConditioner 

type KeyConditioner interface {
	// GetName returns the name of condition e.g.: old, oldNot, oldEmpty, isArray
	GetName() string
	// GetValue returns the value for which condition must be met
	GetValue() interface{}
}

KeyConditioner describes conditions to check before it writes something to the agency

func NewConditionIfEqual 

func NewConditionIfEqual(value interface{}) KeyConditioner

NewConditionIfEqual creates condition where value must equal to a value which is written in the agency

func NewConditionIfNotEqual 

func NewConditionIfNotEqual(value interface{}) KeyConditioner

NewConditionIfNotEqual creates condition where value must not equal to a value which is written in the agency

func NewConditionIsArray 

func NewConditionIsArray(value bool) KeyConditioner

NewConditionIsArray creates condition where value must be an array before it is written

func NewConditionOldEmpty 

func NewConditionOldEmpty(value bool) KeyConditioner

NewConditionOldEmpty creates condition where value must be empty before it is written

type KeyNotFoundError 

type KeyNotFoundError struct {
	Key []string
}

KeyNotFoundError indicates that a key was not found.

func (KeyNotFoundError) Error 

func (e KeyNotFoundError) Error() string

Error returns a human readable error string

type Lock 

type Lock interface {
	// Lock tries to lock the lock.
	// If it is not possible to lock, an error is returned.
	// If the lock is already held by me, an error is returned.
	Lock(ctx context.Context) error

	// Unlock tries to unlock the lock.
	// If it is not possible to unlock, an error is returned.
	// If the lock is not held by me, an error is returned.
	Unlock(ctx context.Context) error

	// IsLocked return true if the lock is held by me.
	IsLocked() bool
}

Lock is an agency backed exclusive lock.

func NewLock 

func NewLock(log Logger, api Agency, key []string, id string, ttl time.Duration) (Lock, error)

NewLock creates a new lock on the given key.

type Logger 

type Logger interface {
	Errorf(msg string, args ...interface{})
}

Logger abstracts a logger.

type Transaction 

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

Transaction stores information about operations which must be performed for particular keys with some conditions

func NewTransaction 

func NewTransaction(clientID string, options TransactionOptions) Transaction

NewTransaction creates new transaction. The argument 'clientID' should be used to mark that transaction sender uniquely.

func (*Transaction) AddCondition 

func (k *Transaction) AddCondition(key []string, condition KeyConditioner) error

AddCondition adds new condition to the list of keys which must be changed in one transaction

func (*Transaction) AddConditionByFullKey 

func (k *Transaction) AddConditionByFullKey(fullKey string, condition KeyConditioner) error

AddConditionByFullKey adds new condition to the list of keys which must be changed in one transaction

func (*Transaction) AddKey 

func (k *Transaction) AddKey(key KeyChanger)

AddKey adds new key which must be changed in one transaction

type TransactionOptions 

type TransactionOptions struct {
	Transient bool
}

TransactionOptions defines options how transaction should behave.

type WriteCondition deprecated 

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

Deprecated: use 'agency.KeyConditioner' instead

WriteCondition is a precondition before a write is accepted.

func (WriteCondition) IfEmpty deprecated 

func (c WriteCondition) IfEmpty(key []string) WriteCondition

Deprecated: use 'agency.KeyConditioner' instead

IfEmpty adds an "is empty" check on the given key to the given condition and returns the updated condition.

func (WriteCondition) IfEqualTo deprecated 

func (c WriteCondition) IfEqualTo(key []string, oldValue interface{}) WriteCondition

Deprecated: use 'agency.KeyConditioner' instead

IfEqualTo adds an "value equals oldValue" check to given old value on the given key to the given condition and returns the updated condition.

func (WriteCondition) IfIsArray deprecated 

func (c WriteCondition) IfIsArray(key []string) WriteCondition

Deprecated: use 'agency.KeyConditioner' instead

IfIsArray adds an "is-array" check on the given key to the given condition and returns the updated condition.

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.