Struct Client

pub struct Client { /* private fields */ }

Client encapsulates ZooKeeper session to interact with ZooKeeper cluster.

Besides semantic errors, node operations could also fail due to cluster availability and capabilities, e.g. Error::ConnectionLoss, Error::QuotaExceeded, Error::Unimplemented and so on.

All remote operations will fail after session expired, failed or closed.

Notable behaviors

• All cloned clients share same authentication identities.
• All methods construct resulting future by sending request synchronously and polling output asynchronously. This guarantees that requests are sending to server in the order of method call but not future evaluation.

Implementations

impl Client

pub async fn connect(cluster: &str) -> Result<Self, Error>

Connects to ZooKeeper cluster.

pub fn builder() -> ClientBuilder

👎Deprecated since 0.7.0: use Client::connector instead

Creates a builder with configurable options in connecting to ZooKeeper cluster.

pub fn connector() -> Connector

Creates a builder with configurable options in connecting to ZooKeeper cluster.

pub fn path(&self) -> &str

Path of chroot.

pub fn session(&self) -> &SessionInfo

ZooKeeper session info.

pub fn session_id(&self) -> SessionId

ZooKeeper session id.

pub fn into_session(self) -> SessionInfo

Consumes this instance into session info.

pub fn session_timeout(&self) -> Duration

Negotiated session timeout.

pub fn state(&self) -> SessionState

Latest session state.

pub fn state_watcher(&self) -> StateWatcher

Creates a StateWatcher to track future session state updates.

pub fn chroot<'a>(self, path: impl Into<Cow<'a, str>>) -> Result<Client, Client>

Changes root directory to given absolute path.

Errors

In case of bad root path, old client is wrapped in Result::Err.

Notable behaviors

• Existing watchers are not affected.

pub async fn mkdir( &self, path: &str, options: &CreateOptions<'_>, ) -> Result<(), Error>

Makes directories up to path. Treats it as mkdir -p.

Notable behaviors

• No atomic, so it could fail with only partial directories created.
• Pure asynchronous, so there is no order guarantee.
• No Error::NodeExists.

Notable errors

• Error::NoNode if chroot does not exist.
• Error::BadArguments if CreateMode is ephemeral or sequential.
• Error::InvalidAcl if acl is invalid or empty.

pub fn create<'a: 'f, 'b: 'f, 'f>( &'a self, path: &'b str, data: &[u8], options: &CreateOptions<'_>, ) -> impl Future<Output = Result<(Stat, CreateSequence), Error>> + Send + 'f

Creates node with given path and data.

Notable errors

• Error::NodeExists if a node with same path already exists.
• Error::NoNode if parent node does not exist.
• Error::NoChildrenForEphemerals if parent node is ephemeral.
• Error::InvalidAcl if acl is invalid or empty.

Notable behaviors

The resulting Stat will be Stat::is_invalid if assumed server version is 3.4 series or below. See ClientBuilder::assume_server_version and ZOOKEEPER-1297.

pub fn delete( &self, path: &str, expected_version: Option<i32>, ) -> impl Future<Output = Result<(), Error>> + Send

Deletes node with specified path.

Notable errors

• Error::NoNode if such node does not exist.
• Error::BadVersion if such node exists but has different version.
• Error::NotEmpty if such node exists but has children.

pub fn get_data( &self, path: &str, ) -> impl Future<Output = Result<(Vec<u8>, Stat), Error>> + Send

Gets stat and data for node with given path.

Notable errors

• Error::NoNode if such node does not exist.

pub fn get_and_watch_data( &self, path: &str, ) -> impl Future<Output = Result<(Vec<u8>, Stat, OneshotWatcher), Error>> + Send + '_

Gets stat and data for node with given path, and watches node deletion and data change.

The watch will be triggered by:

• Data change.
• Node deletion.
• Session expiration.

Notable errors

• Error::NoNode if such node does not exist.

pub fn check_stat( &self, path: &str, ) -> impl Future<Output = Result<Option<Stat>, Error>> + Send

Checks stat for node with given path.

pub fn check_and_watch_stat( &self, path: &str, ) -> impl Future<Output = Result<(Option<Stat>, OneshotWatcher), Error>> + Send + '_

Checks stat for node with given path, and watches node creation, deletion and data change.

The watch will be triggered by:

• Data change.
• Node creation and deletion.
• Session expiration.

pub fn set_data( &self, path: &str, data: &[u8], expected_version: Option<i32>, ) -> impl Future<Output = Result<Stat, Error>> + Send

Sets data for node with given path and returns updated stat.

Notable errors

• Error::NoNode if such node does not exist.
• Error::BadVersion if such node exists but has different version.
• Error::NoAuth if the client has insufficient authorization to such node.

pub fn set_data_internally( &self, path: &str, data: &[u8], expected_version: Option<i32>, ) -> Result<impl Future<Output = Result<Stat, Error>>, Error>

pub fn list_children( &self, path: &str, ) -> impl Future<Output = Result<Vec<String>, Error>> + Send + '_

Lists children for node with given path.

Notable errors

• Error::NoNode if such node does not exist.

pub fn list_and_watch_children( &self, path: &str, ) -> impl Future<Output = Result<(Vec<String>, OneshotWatcher), Error>> + Send + '_

Lists children for node with given path, and watches node deletion, children creation and deletion.

The watch will be triggered by:

• Children creation and deletion.
• Node deletion.
• Session expiration.

Notable errors

• Error::NoNode if such node does not exist.

pub fn get_children( &self, path: &str, ) -> impl Future<Output = Result<(Vec<String>, Stat), Error>> + Send

Gets stat and children for node with given path.

Notable errors

• Error::NoNode if such node does not exist.

pub fn get_and_watch_children( &self, path: &str, ) -> impl Future<Output = Result<(Vec<String>, Stat, OneshotWatcher), Error>> + Send + '_

Gets stat and children for node with given path, and watches node deletion, children creation and deletion.

The watch will be triggered by:

• Children creation and deletion.
• Node deletion.
• Session expiration.

Notable errors

• Error::NoNode if such node does not exist.

pub fn count_descendants_number( &self, path: &str, ) -> impl Future<Output = Result<usize, Error>> + Send

Counts descendants number for node with given path.

Notable errors

• Error::NoNode if such node does not exist.

pub fn list_ephemerals( &self, path: &str, ) -> impl Future<Output = Result<Vec<String>, Error>> + Send + '_

Lists all ephemerals nodes that created by current session and starts with given path.

Notable behaviors

• No Error::NoNode if node with give path does not exist.
• Result will include given path if that node is ephemeral.
• Returned paths are located at chroot but not ZooKeeper root.

pub fn get_acl( &self, path: &str, ) -> impl Future<Output = Result<(Vec<Acl>, Stat), Error>> + Send + '_

Gets acl and stat for node with given path.

Notable errors

• Error::NoNode if such node does not exist.

pub fn set_acl( &self, path: &str, acl: &[Acl], expected_acl_version: Option<i32>, ) -> impl Future<Output = Result<Stat, Error>> + Send + '_

Sets acl for node with given path and returns updated stat.

Notable errors

• Error::NoNode if such node does not exist.
• Error::BadVersion if such node exists but has different acl version.

pub fn watch( &self, path: &str, mode: AddWatchMode, ) -> impl Future<Output = Result<PersistentWatcher, Error>> + Send + '_

Watches possible nonexistent path using specified mode.

The watch will be triggered by:

• Data change, children creation and deletion.
• Session activities.

Cautions

• Holds returned watcher without polling events may result in memory burst.
• At the time of written, ZooKeeper ZOOKEEPER-4466 does not support oneshot and persistent watch on same path.
• Persistent watch could lose events during reconnection due to ZOOKEEPER-4698.

pub fn sync( &self, path: &str, ) -> impl Future<Output = Result<(), Error>> + Send + '_

Syncs with ZooKeeper leader.

Cautions

sync + read could not guarantee linearizable semantics as sync is not quorum acked and leader could change in between.

See ZOOKEEPER-1675 and ZOOKEEPER-2136 for reference.

pub fn auth( &self, scheme: String, auth: Vec<u8>, ) -> impl Future<Output = Result<(), Error>> + Send + '_

Authenticates session using given scheme and auth identification. This affects only subsequent operations.

Errors

• Error::AuthFailed if authentication failed.
• Other terminal session errors.

Notable behaviors

• Same auth will be resubmitted for authentication after session reestablished.
• This method is resistant to temporary session unavailability, that means SessionState::Disconnected will not end authentication.
• It is ok to ignore resulting future of this method as request is sending synchronously and auth failure will fail ZooKeeper session with SessionState::AuthFailed.

pub fn list_auth_users( &self, ) -> impl Future<Output = Result<Vec<AuthUser>, Error>> + Send

Gets all authentication informations attached to current session.

Requirements

• ZooKeeper 3.7.0 and above

References

• ZOOKEEPER-3969 Add whoami API and Cli command.

pub fn get_config( &self, ) -> impl Future<Output = Result<(Vec<u8>, Stat), Error>> + Send

Gets data for ZooKeeper config node, that is node with path “/zookeeper/config”.

pub fn get_and_watch_config( &self, ) -> impl Future<Output = Result<(Vec<u8>, Stat, OneshotWatcher), Error>> + Send

Gets stat and data for ZooKeeper config node, that is node with path “/zookeeper/config”.

pub fn update_ensemble<'a, I: Iterator<Item = &'a str> + Clone>( &self, update: EnsembleUpdate<'a, I>, expected_zxid: Option<i64>, ) -> impl Future<Output = Result<(Vec<u8>, Stat), Error>> + Send

Updates ZooKeeper ensemble.

Notable errors

• Error::ReconfigDisabled if ZooKeeper reconfiguration is disabled.

References

See ZooKeeper Dynamic Reconfiguration.

pub fn new_multi_reader(&self) -> MultiReader<'_>

Creates a MultiReader.

pub fn new_multi_writer(&self) -> MultiWriter<'_>

Creates a MultiWriter.

pub fn new_check_writer( &self, path: &str, version: Option<i32>, ) -> Result<CheckWriter<'_>, Error>

Creates a CheckWriter, which is similar to MultiWriter but additional path check when CheckWriter::commit.

pub async fn lock( &self, prefix: LockPrefix<'_>, data: &[u8], options: impl Into<LockOptions<'_>>, ) -> Result<LockClient<'_>, Error>

Contends lock/leader/latch using given locking path pattern.

Notable errors

• Error::RuntimeInconsistent if lock path is deleted during contention.
• Error::SessionExpired if session expired before lock acquired.
• Error::NoNode if ancestor nodes do not exist and no options to create them.
• Error::NoChildrenForEphemerals if parent node is ephemeral.
• Error::InvalidAcl if acl is invalid or empty.

Cancellation safety

This method is cancellation safe, so you can free to cancel result future without fear to dangle lock. For example, a timed lock is easy to construct with select! and sleep.

Asynchronous ordering

Comparing to other data operations, e.g. Client::create, this operation is pure asynchronous, so there is no data order guarantee.

Error handling on Error::ConnectionLoss

• If connection loss during lock path creation, this method will find out the created lock path if creation success by matching prefix for LockPrefix::new_curator or ephemeral owner for others.
• Retry all other operations on connection loss.

Notable issues

• ZOOKEEPER-22: Automatic request retries on connection failover.

Notable docs

• ZooKeeper Recipes and Solutions

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.