README
¶
Native Go Zookeeper Client Library
This library enables users to communicate with Zookeeper servers over the Zookeeper wire protocol and provides an API for easy usage. It leverages the Jute compiler for simple serialization and deserialization of protocol messages.
Message formats are defined in a Jute file which can be compiled to Go code similarly to Thrift or Protobuf.
The Jute compiler can be ran from the internal directory by running go generate, which will run the compiler against the zookeeper.jute definition file.
The project is still in active development and therefore may not be ready for production use.
Setup
The recommended procedure is to download the zk client via go get:
go get -u github.com/facebookincubator/zk
After successfully running this command, the library will be available in your GOPATH, and you can start using it to communicate with your Zookeeper infrastructure.
Usage
The default way library users can communicate with a Zookeeper server is by using the Client abstraction and its methods. It provides a functionality of retryable calls as well as additional configuration parameters.
Upon reconnecting, the client simply creates a new session instead of attempting to reuse the old sessionID if one was generated.
It is also possible to use a raw connection via DialContext for more fine-tuned control. This call returns a Conn instance which can be used for manual RPCs, and does not offer any additional functionalities such as reconnects.
Connections are kept alive by the client and should be closed after usage by calling Client.Reset() or Conn.Close() depending on the API.
Default Client
client := &Client{
Network: "tcp",
Ensemble: "127.0.0.1:2181",
}
defer client.Reset()
data, err := client.GetData(context.Background(), "/")
log.Println(string(data))
children, err := client.GetChildren(context.Background(), "/")
log.Println(children)
Retryable client
When connection problems or timeouts are encountered, the client will try to re-establish the connection and retry the operation. Some errors are non-retryable, for example if the znode specified does not exist.
client := &Client{
Network: "tcp",
Ensemble: "127.0.0.1:2181",
MaxRetries: 5,
SessionTimeout: time.Second,
}
defer client.Reset()
data, err := client.GetData(context.Background(), "/")
log.Println(string(data))
Custom dialers
Should library users require custom discovery mechanisms, for example for connecting to multiple nodes, they can add a custom Dialer to the Client.
client := &Client{
Dialer: func(ctx context.Context, network, addr string) (net.Conn, error) {
// custom logic here
}
}
Using lower-level primitives
Client users can get access to the lower-level Conn primitive by Calling zk.DialContext. The connection’s lifetime can then be handled by passing a Context to the call.
conn, err := DialContext(context.Background(), "tcp", "127.0.0.1:2181")
if err != nil {
log.Println("unexpected error: ", err)
}
defer conn.Close()
data, err := conn.GetData("/")
if err != nil {
log.Println("unexpected error calling GetData: ", err)
}
See also example.go for an example CLI which uses this library.
TODO
- Support for watches
- Support for locks and other recipes
- Extension of the API so that all of Zookeeper’s client commands are supported
- Digest-based and SASL authentication
Contributing
Want to contribute? Great! See the CONTRIBUTING.md file for more information on how to help out.
License
This library is MIT licensed, as found in the LICENSE file.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrMaxRetries = errors.New("connection failed after max retries")
ErrMaxRetries is used to differentiate retryable from non-retryable errors in the client.
Functions ¶
func ReadRecord ¶
func ReadRecord(r io.Reader) (*proto.RequestHeader, jute.RecordReader, error)
ReadRecord reads the request header and body depending on the opcode. It returns the serialized request header and body, or an error if it occurs.
func WriteRecords ¶
func WriteRecords(w io.Writer, generated ...jute.RecordWriter) error
WriteRecords takes in one or more RecordWriter instances, serializes them to a byte array and writes them to the provided io.Writer.
Types ¶
type Client ¶
type Client struct {
// Dialer is a function to be used to establish a connection to a single host.
Dialer func(ctx context.Context, network, addr string) (net.Conn, error)
SessionTimeout time.Duration
MaxRetries int
Network string
Ensemble string
// contains filtered or unexported fields
}
Client represents a Zookeeper client abstraction with additional configuration parameters.
func (*Client) DialContext ¶
DialContext connects the ZK client to the specified Zookeeper server. The provided context is used to determine the dial lifetime.
func (*Client) GetChildren ¶
GetChildren uses the retryable client to call GetChildren on a Zookeeper server.
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn represents a client connection to a Zookeeper server and parameters needed to handle its lifetime.
func DialContext ¶
DialContext connects to the ZK server using the default client.
func (*Conn) GetChildren ¶
GetChildren returns all children of a node at the given path, if they exist.
Source Files
Directories