Struct zookeeper_client::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 limitations, e.g. Error::ConnectionLoss, Error::QuotaExceeded 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, timeout: Duration ) -> Result<Client, ConnectError>

Connects to ZooKeeper cluster with specified session timeout.

pub fn session_id(&self) -> SessionId

ZooKeeper session id.

pub fn session_password(&self) -> &[u8]

Session password.

pub fn into_session(self) -> (SessionId, Vec<u8>)

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(self, root: &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 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.

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.

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.

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 identication. 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 resistent 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 multi reader.

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

Creates a multi writer.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy 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.