From 8de8f1950a1b177db1cd1ca1d1ec5c79b74cdc0e Mon Sep 17 00:00:00 2001 From: Vaibhav Rabber Date: Thu, 19 Dec 2024 21:44:59 +0530 Subject: [PATCH] docs: `s2::client` (#121) Signed-off-by: Vaibhav Rabber --- src/client.rs | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/src/client.rs b/src/client.rs index 86827bb..3965b0e 100644 --- a/src/client.rs +++ b/src/client.rs @@ -1,4 +1,35 @@ //! SDK client implementation. +//! +//! The module defines three clients: +//! +//! | | Operations | API Service | +//! |------------------|--------------------------|------------------| +//! | [`Client`] | Account level operations | [AccountService] | +//! | [`BasinClient`] | Basin level operations | [BasinService] | +//! | [`StreamClient`] | Stream level operations | [StreamService] | +//! +//! To interact with any client, you need an authentication token which can be +//! generated by the the web console at [s2.dev]. This token is passed to the +//! client via a [`ClientConfig`]. +//! +//! Along with the authentication token, a [`ClientConfig`] defines other +//! request parameters such as timeouts, S2 endpoints, etc. +//! +//! A client can be created using the corresponding `new()` method. To avoid +//! creating multiple connections to each service, [`Client::basin_client`] can be +//! used to create a [`BasinClient`] and [`BasinClient::stream_client`] can be +//! used to create a [`StreamClient`]. +//! +//! **Note:** Even though the client creation operation is cheap, a +//! [`BasinClient`] should preferably be stored instead of using +//! [`Client::basin_client`] multiple times as the account endpoint might vary +//! from the basin endpoint creating a new connection each time the request is +//! sent. See [`S2Endpoints`]. +//! +//! [AccountService]: https://s2.dev/docs/interface/grpc-api#accountservice +//! [BasinService]: https://s2.dev/docs/interface/grpc-api#basinservice +//! [StreamService]: https://s2.dev/docs/interface/grpc-api#streamservice +//! [s2.dev]: https://s2.dev/dashboard use std::{env::VarError, fmt::Display, str::FromStr, time::Duration};