ezk

Overview ¶

Package ezk is an enhanced Zookeeper client. It uses the connection and underlying operations from https://github.com/samuel/go-zookeeper/zk in conjunction with automatic retry of operations via the https://github.com/betable/retry library.

ABOUT THE CHROOT PREFIX, ABSOLUTE PATHS, AND RELATIVE PATHS
===========================================================

Examples of Chroot prefixes commonly used are
 "/production/", "/staging/", and "/devtest/".
These prefixes let one multitask the Zookeeper
cluster for different responsibilities without
incurring crosstalk between applications.

The Chroot prefix is implicitly prepended to any
relative path supplied to an ezk API call.

Our (enforced) zookeeper path convention for the
ClientConfig.Chroot string allows us to distinguish
between chroot-ed paths and non-chroot paths, and
between absolute versus relative paths as follows:

* the Chroot prefix must always start with a forward slash.
A single '/' alone is a valid Chroot prefix. If the prefix
is longer than one character, the Chroot prefix must
also end with a '/' as well--in this case the prefix will
contain exactly two '/' slash characters; one at the
beginning and one at the end.

A Chroot prefix therefore names either zero or one
znodes.

For example: "/prod/", "/staging/", and "/devtest/" are all
legal Chroot strings. Counter-examples: "/prod" is not
a legal Chroot value, nor is "prod/", nor is "prod".
User code can distinguish Chroot prefixes by checking
whether the first byte of the string is '/' or not.
See the IsAbsolutePath() and RemoveChroot()
helper functions.

* All paths that are intended to be relative to the Chroot
prefix must *not* start with a forward slash and must
not end with a forward slash; they are like relative paths in Unix.

So legal examples of relative paths: "myservice/config/my-servers",
"piper", or "timeseries", or "timeseries/config". The
requirement forbidding the trailing '/' is enforced on the
Zookeeper server side.

* The ezk library will form the full path (spoken on the wire to
the Zookeeper) by a simple concatenation of Chroot + relative path.

* The helper function RemoveChroot(path) will detect and
automatically remove any chroot prefix from path, and returns a
relative path. It will leave untouched already relative paths.

* Important: when receiving watch events on channels from the
github.com/samuel/go-zookeeper/zk library, they are of the
following Event type. See the notes on the Path field below.

type Event struct {
    Type   EventType
    State  State

    // Path is for non-session events; it is
    // the (absolute, Chroot-prefixed) path
    // of the watched node. [1]
    Path   string

    Err    error
    Server string // For connection events
}

Note [1] that this Path is absolute, it includes the Chroot
prefix. Users should call RemoveChroot() function as needed
before using the Event.Path field if they require a relative
path.