Documentation ¶
Overview ¶
Package zk is a native Go client library for the ZooKeeper orchestration service.
Index ¶
- Constants
- Variables
- func FLWRuok(servers []string, timeout time.Duration) []bool
- func FormatServers(servers []string) []string
- func ParseConnectionString(s string) (servers []string, chroot string)
- func WithChroot(chroot string) connOption
- func WithDialer(dialer Dialer) connOption
- func WithEventCallback(cb EventCallback) connOption
- func WithHostProvider(hostProvider HostProvider) connOption
- func WithLogInfo(logInfo bool) connOption
- func WithLogger(logger Logger) connOption
- func WithMaxBufferSize(maxBufferSize int) connOption
- func WithMaxConnBufferSize(maxBufferSize int) connOption
- type ACL
- type CheckVersionRequest
- type Conn
- func (c *Conn) AddAuth(scheme string, auth []byte) error
- func (c *Conn) Children(path string) ([]string, *Stat, error)
- func (c *Conn) ChildrenW(path string) ([]string, *Stat, <-chan Event, error)
- func (c *Conn) Close()
- func (c *Conn) Create(path string, data []byte, flags int32, acl []ACL) (string, error)
- func (c *Conn) CreateProtectedEphemeralSequential(path string, data []byte, acl []ACL) (string, error)
- func (c *Conn) Delete(path string, version int32) error
- func (c *Conn) Exists(path string) (bool, *Stat, error)
- func (c *Conn) ExistsW(path string) (bool, *Stat, <-chan Event, error)
- func (c *Conn) Get(path string) ([]byte, *Stat, error)
- func (c *Conn) GetACL(path string) ([]ACL, *Stat, error)
- func (c *Conn) GetW(path string) ([]byte, *Stat, <-chan Event, error)
- func (c *Conn) Multi(ops ...interface{}) ([]MultiResponse, error)
- func (c *Conn) Server() string
- func (c *Conn) SessionID() int64
- func (c *Conn) Set(path string, data []byte, version int32) (*Stat, error)
- func (c *Conn) SetACL(path string, acl []ACL, version int32) (*Stat, error)
- func (c *Conn) SetLogger(l Logger)
- func (c *Conn) State() State
- func (c *Conn) Sync(path string) (string, error)
- type CreateRequest
- type DNSHostProvider
- type DeleteRequest
- type Dialer
- type ErrCode
- type ErrMissingServerConfigField
- type Event
- type EventCallback
- type EventType
- type HostProvider
- type Lock
- type Logger
- type Mode
- type MultiResponse
- type PathVersionRequest
- type Server
- type ServerClient
- type ServerClients
- type ServerConfig
- type ServerConfigServer
- type ServerStats
- type SetDataRequest
- type Stat
- type State
- type TestCluster
- func (tc *TestCluster) Connect(idx int) (*Conn, error)
- func (tc *TestCluster) ConnectAll() (*Conn, <-chan Event, error)
- func (tc *TestCluster) ConnectAllTimeout(sessionTimeout time.Duration) (*Conn, <-chan Event, error)
- func (tc *TestCluster) ConnectWithOptions(sessionTimeout time.Duration, options ...connOption) (*Conn, <-chan Event, error)
- func (tc *TestCluster) StartAllServers() error
- func (tc *TestCluster) StartServer(server string)
- func (tc *TestCluster) Stop() error
- func (tc *TestCluster) StopAllServers() error
- func (tc *TestCluster) StopServer(server string)
- type TestServer
Constants ¶
const ( FlagEphemeral = 1 FlagSequence = 2 )
const ( PermRead = 1 << iota PermWrite PermCreate PermDelete PermAdmin PermAll = 0x1f )
Constants for ACL permissions
const ( DefaultServerTickTime = 2000 DefaultServerInitLimit = 10 DefaultServerSyncLimit = 5 DefaultServerAutoPurgeSnapRetainCount = 3 DefaultPeerPort = 2888 DefaultLeaderElectionPort = 3888 )
const (
DefaultPort = 2181
)
Variables ¶
var ( ErrConnectionClosed = errors.New("zk: connection closed") ErrUnknown = errors.New("zk: unknown error") ErrAPIError = errors.New("zk: api error") ErrNoNode = errors.New("zk: node does not exist") ErrNoAuth = errors.New("zk: not authenticated") ErrBadVersion = errors.New("zk: version conflict") ErrNoChildrenForEphemerals = errors.New("zk: ephemeral nodes may not have children") ErrNodeExists = errors.New("zk: node already exists") ErrNotEmpty = errors.New("zk: node has children") ErrSessionExpired = errors.New("zk: session has been expired by the server") ErrInvalidACL = errors.New("zk: invalid ACL specified") ErrAuthFailed = errors.New("zk: client authentication failed") ErrClosing = errors.New("zk: zookeeper is closing") ErrNothing = errors.New("zk: no server responsees to process") ErrSessionMoved = errors.New("zk: session moved to another server, so operation is ignored") )
var ( // ErrDeadlock is returned by Lock when trying to lock twice without unlocking first ErrDeadlock = errors.New("zk: trying to acquire a lock twice") // ErrNotLocked is returned by Unlock when trying to release a lock that has not first be acquired. ErrNotLocked = errors.New("zk: not locked") )
var ( ErrUnhandledFieldType = errors.New("zk: unhandled field type") ErrPtrExpected = errors.New("zk: encode/decode expect a non-nil pointer to struct") ErrShortBuffer = errors.New("zk: buffer too small") )
var ErrInvalidPath = errors.New("zk: invalid path")
ErrInvalidPath indicates that an operation was being attempted on an invalid path. (e.g. empty path)
var ErrNoServer = errors.New("zk: could not connect to a server")
ErrNoServer indicates that an operation cannot be completed because attempts to connect to all servers in the list failed.
Functions ¶
func FLWRuok ¶
FLWRuok is a FourLetterWord helper function. In particular, this function pulls the ruok output from each server.
func FormatServers ¶
FormatServers takes a slice of addresses, and makes sure they are in a format that resembles <addr>:<port>. If the server has no port provided, the DefaultPort constant is added to the end.
func ParseConnectionString ¶
func WithChroot ¶
func WithChroot(chroot string) connOption
func WithDialer ¶
func WithDialer(dialer Dialer) connOption
WithDialer returns a connection option specifying a non-default Dialer.
func WithEventCallback ¶
func WithEventCallback(cb EventCallback) connOption
WithEventCallback returns a connection option that specifies an event callback. The callback must not block - doing so would delay the ZK go routines.
func WithHostProvider ¶
func WithHostProvider(hostProvider HostProvider) connOption
WithHostProvider returns a connection option specifying a non-default HostProvider.
func WithLogInfo ¶
func WithLogInfo(logInfo bool) connOption
WithLogInfo returns a connection option specifying whether or not information messages shoud be logged.
func WithLogger ¶
func WithLogger(logger Logger) connOption
WithLogger returns a connection option specifying a non-default Logger
func WithMaxBufferSize ¶
func WithMaxBufferSize(maxBufferSize int) connOption
WithMaxBufferSize sets the maximum buffer size used to read and decode packets received from the Zookeeper server. The standard Zookeeper client for Java defaults to a limit of 1mb. For backwards compatibility, this Go client defaults to unbounded unless overridden via this option. A value that is zero or negative indicates that no limit is enforced.
This is meant to prevent resource exhaustion in the face of potentially malicious data in ZK. It should generally match the server setting (which also defaults ot 1mb) so that clients and servers agree on the limits for things like the size of data in an individual znode and the total size of a transaction.
For production systems, this should be set to a reasonable value (ideally that matches the server configuration). For ops tooling, it is handy to use a much larger limit, in order to do things like clean-up problematic state in the ZK tree. For example, if a single znode has a huge number of children, it is possible for the response to a "list children" operation to exceed this buffer size and cause errors in clients. The only way to subsequently clean up the tree (by removing superfluous children) is to use a client configured with a larger buffer size that can successfully query for all of the child names and then remove them. (Note there are other tools that can list all of the child names without an increased buffer size in the client, but they work by inspecting the servers' transaction logs to enumerate children instead of sending an online request to a server.
func WithMaxConnBufferSize ¶
func WithMaxConnBufferSize(maxBufferSize int) connOption
WithMaxConnBufferSize sets maximum buffer size used to send and encode packets to Zookeeper server. The standard Zookeepeer client for java defaults to a limit of 1mb. This option should be used for non-standard server setup where znode is bigger than default 1mb.
Types ¶
type ACL ¶
type CheckVersionRequest ¶
type CheckVersionRequest PathVersionRequest
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
func Connect ¶
func Connect(servers []string, sessionTimeout time.Duration, options ...connOption) (*Conn, <-chan Event, error)
Connect establishes a new connection to a pool of zookeeper servers. The provided session timeout sets the amount of time for which a session is considered valid after losing connection to a server. Within the session timeout it's possible to reestablish a connection to a different server and keep the same session. This is means any ephemeral nodes and watches are maintained.
func ConnectWithDialer ¶
func ConnectWithDialer(servers []string, sessionTimeout time.Duration, dialer Dialer) (*Conn, <-chan Event, error)
ConnectWithDialer establishes a new connection to a pool of zookeeper servers using a custom Dialer. See Connect for further information about session timeout. This method is deprecated and provided for compatibility: use the WithDialer option instead.
func (*Conn) CreateProtectedEphemeralSequential ¶
func (c *Conn) CreateProtectedEphemeralSequential(path string, data []byte, acl []ACL) (string, error)
CreateProtectedEphemeralSequential fixes a race condition if the server crashes after it creates the node. On reconnect the session may still be valid so the ephemeral node still exists. Therefore, on reconnect we need to check if a node with a GUID generated on create exists.
func (*Conn) Multi ¶
func (c *Conn) Multi(ops ...interface{}) ([]MultiResponse, error)
Multi executes multiple ZooKeeper operations or none of them. The provided ops must be one of *CreateRequest, *DeleteRequest, *SetDataRequest, or *CheckVersionRequest.
func (*Conn) SetLogger ¶
SetLogger sets the logger to be used for printing errors. Logger is an interface provided by this package.
type DNSHostProvider ¶
type DNSHostProvider struct {
// contains filtered or unexported fields
}
DNSHostProvider is the default HostProvider. It currently matches the Java StaticHostProvider, resolving hosts from DNS once during the call to Init. It could be easily extended to re-query DNS periodically or if there is trouble connecting.
func (*DNSHostProvider) Connected ¶
func (hp *DNSHostProvider) Connected()
Connected notifies the HostProvider of a successful connection.
func (*DNSHostProvider) Init ¶
func (hp *DNSHostProvider) Init(servers []string) error
Init is called first, with the servers specified in the connection string. It uses DNS to look up addresses for each server, then shuffles them all together.
func (*DNSHostProvider) Len ¶
func (hp *DNSHostProvider) Len() int
Len returns the number of servers available
func (*DNSHostProvider) Next ¶
func (hp *DNSHostProvider) Next() (server string, retryStart bool)
Next returns the next server to connect to. retryStart will be true if we've looped through all known servers without Connected() being called.
type DeleteRequest ¶
type DeleteRequest PathVersionRequest
type ErrMissingServerConfigField ¶
type ErrMissingServerConfigField string
func (ErrMissingServerConfigField) Error ¶
func (e ErrMissingServerConfigField) Error() string
type EventCallback ¶
type EventCallback func(Event)
EventCallback is a function that is called when an Event occurs.
type HostProvider ¶
type HostProvider interface { // Init is called first, with the servers specified in the connection string. Init(servers []string) error // Len returns the number of servers. Len() int // Next returns the next server to connect to. retryStart will be true if we've looped through // all known servers without Connected() being called. Next() (server string, retryStart bool) // Notify the HostProvider of a successful connection. Connected() }
HostProvider is used to represent a set of hosts a ZooKeeper client should connect to. It is an analog of the Java equivalent: http://svn.apache.org/viewvc/zookeeper/trunk/src/java/main/org/apache/zookeeper/client/HostProvider.java?view=markup
type Lock ¶
type Lock struct {
// contains filtered or unexported fields
}
Lock is a mutual exclusion lock.
func NewLock ¶
NewLock creates a new lock instance using the provided connection, path, and acl. The path must be a node that is only used by this lock. A lock instances starts unlocked until Lock() is called.
type Logger ¶
type Logger interface {
Printf(string, ...interface{})
}
Logger is an interface that can be implemented to provide custom log output.
var DefaultLogger Logger = defaultLogger{}
DefaultLogger uses the stdlib log package for logging.
type MultiResponse ¶
type PathVersionRequest ¶
type Server ¶
type ServerClient ¶
type ServerClient struct { Queued int64 Received int64 Sent int64 SessionID int64 Lcxid int64 Lzxid int64 Timeout int32 LastLatency int32 MinLatency int32 AvgLatency int32 MaxLatency int32 Established time.Time LastResponse time.Time Addr string LastOperation string // maybe? Error error }
ServerClient is the information for a single Zookeeper client and its session. This is used to parse/extract the output fo the `cons` command.
type ServerClients ¶
type ServerClients struct { Clients []*ServerClient Error error }
ServerClients is a struct for the FLWCons() function. It's used to provide the list of Clients.
This is needed because FLWCons() takes multiple servers.
func FLWCons ¶
func FLWCons(servers []string, timeout time.Duration) ([]*ServerClients, bool)
FLWCons is a FourLetterWord helper function. In particular, this function pulls the ruok output from each server.
As with FLWSrvr, the boolean value indicates whether one of the requests had an issue. The Clients struct has an Error value that can be checked.
type ServerConfig ¶
type ServerConfig struct { TickTime int // Number of milliseconds of each tick InitLimit int // Number of ticks that the initial synchronization phase can take SyncLimit int // Number of ticks that can pass between sending a request and getting an acknowledgement DataDir string // Direcrory where the snapshot is stored ClientPort int // Port at which clients will connect AutoPurgeSnapRetainCount int // Number of snapshots to retain in dataDir AutoPurgePurgeInterval int // Purge task internal in hours (0 to disable auto purge) Servers []ServerConfigServer }
type ServerConfigServer ¶
type ServerStats ¶
type ServerStats struct { Sent int64 Received int64 NodeCount int64 MinLatency int64 AvgLatency int64 MaxLatency int64 Connections int64 Outstanding int64 Epoch int32 Counter int32 BuildTime time.Time Mode Mode Version string Error error }
ServerStats is the information pulled from the Zookeeper `stat` command.
func FLWSrvr ¶
func FLWSrvr(servers []string, timeout time.Duration) ([]*ServerStats, bool)
FLWSrvr is a FourLetterWord helper function. In particular, this function pulls the srvr output from the zookeeper instances and parses the output. A slice of *ServerStats structs are returned as well as a boolean value to indicate whether this function processed successfully.
If the boolean value is false there was a problem. If the *ServerStats slice is empty or nil, then the error happened before we started to obtain 'srvr' values. Otherwise, one of the servers had an issue and the "Error" value in the struct should be inspected to determine which server had the issue.
type SetDataRequest ¶
type Stat ¶
type Stat struct { Czxid int64 // The zxid of the change that caused this znode to be created. Mzxid int64 // The zxid of the change that last modified this znode. Ctime int64 // The time in milliseconds from epoch when this znode was created. Mtime int64 // The time in milliseconds from epoch when this znode was last modified. Version int32 // The number of changes to the data of this znode. Cversion int32 // The number of changes to the children of this znode. Aversion int32 // The number of changes to the ACL of this znode. EphemeralOwner int64 // The session id of the owner of this znode if the znode is an ephemeral node. If it is not an ephemeral node, it will be zero. DataLength int32 // The length of the data field of this znode. NumChildren int32 // The number of children of this znode. Pzxid int64 // last modified children }
type TestCluster ¶
type TestCluster struct { Path string Servers []TestServer }
func StartTestCluster ¶
func StartTestCluster(size int, stdout, stderr io.Writer) (*TestCluster, error)
func (*TestCluster) ConnectAll ¶
func (tc *TestCluster) ConnectAll() (*Conn, <-chan Event, error)
func (*TestCluster) ConnectAllTimeout ¶
func (*TestCluster) ConnectWithOptions ¶
func (*TestCluster) StartAllServers ¶
func (tc *TestCluster) StartAllServers() error
func (*TestCluster) StartServer ¶
func (tc *TestCluster) StartServer(server string)
func (*TestCluster) Stop ¶
func (tc *TestCluster) Stop() error
func (*TestCluster) StopAllServers ¶
func (tc *TestCluster) StopAllServers() error
func (*TestCluster) StopServer ¶
func (tc *TestCluster) StopServer(server string)