slbotbm commented on code in PR #3809:
URL: https://github.com/apache/iggy/pull/3809#discussion_r3707430413
##########
core/common/src/types/message/partitioning.rs:
##########
@@ -25,11 +25,17 @@ use std::{
hash::{Hash, Hasher},
};
-/// `Partitioning` is used to specify to which partition the messages should
be sent.
-/// It has the following kinds:
+/// A type that defines a what strategy the server should choose to partition
the messages.
+///
+/// Iggy uses a hierarchical model for append-only logs. A stream contains
topics which hold partitions. Each partition is an append-only log.[^note]
+/// A producer of messages such as an [`IggyProducer`], that appends messages
to the log can choose between three partitioning strategies.
/// - `Balanced` - the partition ID is calculated by the server using the
round-robin algorithm.
-/// - `PartitionId` - the partition ID is provided by the client.
/// - `MessagesKey` - the partition ID is calculated by the server using the
hash of the provided messages key.
+/// - `PartitionId` - the partition ID is provided by the client.
+///
+/// Note, that using a [`Partitioner`] on top of [`Partitioning`] sets the
strategy to [`PartitioningKind::PartitionId`] and the value to whatever
[`Partitioner::calculate_partition_id()`] computes.
Review Comment:
"to whatever [`Partitioner::calculate_partition_id()`] computes." implies
that the calculation is non-deterministic. It would be better to phrase this in
a way that allows the user to understand how `calculate_partition_id`
calculates the partition
##########
core/common/src/traits/partitioner.rs:
##########
@@ -21,8 +21,18 @@ use crate::types::message::IggyMessage;
use std::fmt::Debug;
/// The trait represent the logic responsible for calculating the partition ID
and is used by the `IggyClient`.
-/// This might be especially useful when the partition ID is not constant and
might be calculated based on the stream ID, topic ID and other parameters.
+///
+/// Iggy uses a hierarchical model for append-only logs. A stream contains
topics which hold partitions. Each partition is an append-only log.[^note]
+/// A producer of messages such as an [`IggyProducer`], that appends messages
to the log, might want to choose to which partition to write the messages.
+/// To do that, a producer can take a type that implements this trait.
+/// This might be especially useful when computing the partition ID requires
some client side info, i.e. stream ID, topic ID and [`IggyMessage`] attributes.
+///
+/// Note, that the [`Partitioning`] of a producer defines what _partitioning
strategy_ is triggered on the server.
+/// Using a [`Partitioner`] in a producer sets the strategy in to request a
specific partition [`PartitioningKind::PartitionID`] calculated with
[`Partitioner::calculate_partition_id()`].
Review Comment:
The usage of [`Partitioner`] in a producer allows the user to set a strategy
that will request a specific partition [...] calculated using [...].
While I think the above is a better formulation, I think it would be better
to completely change the sentence since it is difficult to understand and is
missing information
##########
core/sdk/src/clients/client.rs:
##########
@@ -55,9 +55,159 @@ const SESSION_CONTROL_CODES: [u32; 5] = [
LOGIN_REGISTER_WITH_PAT_CODE,
];
-/// The main client struct which implements all the `Client` traits and wraps
the underlying low-level client for the specific transport.
+/// A high-level, transport-agnostic client for an Iggy server.
///
-/// It also provides the additional builders for the standalone consumer,
consumer group, and producer.
+/// `IggyClient` wraps a transport-specific low-level **client**
([`ClientWrapper`]) and
+/// **provides access to the full server API**.
+/// Iggy comes with four options for client-server communication: TCP, QUIC,
WebSocket and HTTP.
+/// The `IggyClient` is configured with one of these transport modes, hence
abstracting
+/// transport specific implementations away.
+///
+/// The [`ClientWrapper`] lives behind an [`IggyRwLock`] so that one connection
+/// can be shared safely. You create a single client and use it from many tasks
+/// at once (producers, consumers, the background heartbeat), and they all talk
+/// over the same connection. The lock keeps that safe. Many operations can
read
+/// from the connection at the same time, while actions that reshape it, like
+/// connecting, reconnecting, or logging in, briefly take exclusive access. It
is
+/// also async-aware, so holding it across a call to the server never blocks
the
+/// runtime.
+///
+/// A [`Partitioner`] and a client-side [`EncryptorKind`] are optional, and
both
+/// default to disabled. The [`Partitioner`] computes on the client-side the
target
+/// partition for messages published without an explicit partition. Hence,
routing
+/// can depend on the stream, topic, and/ or message contents.
+///
+/// The [`EncryptorKind`] encrypts each message payload before it leaves the
client and decrypts it on
+/// the way back, keeping payloads opaque to the server. Attach either through
+/// [`create`].
+///
+/// # What you can do
+///
+/// Configure a connection with an Iggy server and interact with it.
+/// The [`IggyClient`] provides various methods to setup the connection using
connection strings,
+/// builder patterns or an already existing [`ClientWrapper`].
+/// You can spawn [`IggyConsumer`]s and [`IggyProducer`]s that share that
connection.
+///
+/// The full server API is split into domain-specific traits.
+/// `IggyClient` implements [`Client`], the supertrait, which pulls every
domain-specific trait.
+/// Bring the one you need into scope to call its methods.
+/// `use iggy::prelude::*` brings all of them in at once.
+///
+/// - [`SystemClient`]: ping, server statistics, snapshots, and
connected-client info.
+/// - [`UserClient`]: create, inspect, update, and delete users and their
permissions.
+/// - [`PersonalAccessTokenClient`]: create, list, and delete personal access
tokens, log in with one.
+/// - [`StreamClient`]: create, get, update, delete, and purge streams.
+/// - [`TopicClient`]: create, get, update, delete, and purge topics within a
stream.
+/// - [`PartitionClient`]: add and remove partitions on a topic.
+/// - [`SegmentClient`]: delete closed segments from a partition.
+/// - [`ConsumerGroupClient`]: create, get, delete, and join or leave consumer
groups.
+/// - [`ConsumerOffsetClient`]: store, read, and delete consumer offsets.
+/// - [`MessageClient`]: send and poll messages, and flush the unsaved buffer.
+///
+/// Additionally, you can bypass invoking methods from these traits and
directly talk binary to the server with [`send_binary_request`] and
[`send_http_request`] for http.
+/// Both are essentially backdoors for low-level control. You need to know the
server codes and the wire format.
Review Comment:
> /// Additionally, you can bypass invoking methods from these traits and
directly talk binary to the server with [`send_binary_request`] and
[`send_http_request`] for http.
Additionally, you can bypass invoking methods from these traits and directly
talk to the server with [`send_binary_request`] and [`send_http_request`] for
http.
> /// Both are essentially backdoors for low-level control. You need to know
the server codes and the wire format.
The "backdoor" framing looks wrong. Maybe think of another way of saying
this?
##########
core/common/src/traits/partitioner.rs:
##########
@@ -21,8 +21,18 @@ use crate::types::message::IggyMessage;
use std::fmt::Debug;
/// The trait represent the logic responsible for calculating the partition ID
and is used by the `IggyClient`.
-/// This might be especially useful when the partition ID is not constant and
might be calculated based on the stream ID, topic ID and other parameters.
+///
+/// Iggy uses a hierarchical model for append-only logs. A stream contains
topics which hold partitions. Each partition is an append-only log.[^note]
+/// A producer of messages such as an [`IggyProducer`], that appends messages
to the log, might want to choose to which partition to write the messages.
+/// To do that, a producer can take a type that implements this trait.
+/// This might be especially useful when computing the partition ID requires
some client side info, i.e. stream ID, topic ID and [`IggyMessage`] attributes.
Review Comment:
> stream ID, topic ID and [`IggyMessage`] attributes.
stream ID, topic ID or [`IggyMessage`] attributes.
##########
core/common/src/traits/partitioner.rs:
##########
@@ -21,8 +21,18 @@ use crate::types::message::IggyMessage;
use std::fmt::Debug;
/// The trait represent the logic responsible for calculating the partition ID
and is used by the `IggyClient`.
-/// This might be especially useful when the partition ID is not constant and
might be calculated based on the stream ID, topic ID and other parameters.
+///
+/// Iggy uses a hierarchical model for append-only logs. A stream contains
topics which hold partitions. Each partition is an append-only log.[^note]
+/// A producer of messages such as an [`IggyProducer`], that appends messages
to the log, might want to choose to which partition to write the messages.
+/// To do that, a producer can take a type that implements this trait.
+/// This might be especially useful when computing the partition ID requires
some client side info, i.e. stream ID, topic ID and [`IggyMessage`] attributes.
Review Comment:
> This might be especially useful
This may be especially useful
##########
core/sdk/src/clients/client.rs:
##########
@@ -55,9 +55,159 @@ const SESSION_CONTROL_CODES: [u32; 5] = [
LOGIN_REGISTER_WITH_PAT_CODE,
];
-/// The main client struct which implements all the `Client` traits and wraps
the underlying low-level client for the specific transport.
+/// A high-level, transport-agnostic client for an Iggy server.
///
-/// It also provides the additional builders for the standalone consumer,
consumer group, and producer.
+/// `IggyClient` wraps a transport-specific low-level **client**
([`ClientWrapper`]) and
+/// **provides access to the full server API**.
+/// Iggy comes with four options for client-server communication: TCP, QUIC,
WebSocket and HTTP.
+/// The `IggyClient` is configured with one of these transport modes, hence
abstracting
+/// transport specific implementations away.
+///
+/// The [`ClientWrapper`] lives behind an [`IggyRwLock`] so that one connection
+/// can be shared safely. You create a single client and use it from many tasks
+/// at once (producers, consumers, the background heartbeat), and they all talk
+/// over the same connection. The lock keeps that safe. Many operations can
read
+/// from the connection at the same time, while actions that reshape it, like
+/// connecting, reconnecting, or logging in, briefly take exclusive access. It
is
+/// also async-aware, so holding it across a call to the server never blocks
the
+/// runtime.
+///
+/// A [`Partitioner`] and a client-side [`EncryptorKind`] are optional, and
both
+/// default to disabled. The [`Partitioner`] computes on the client-side the
target
+/// partition for messages published without an explicit partition. Hence,
routing
+/// can depend on the stream, topic, and/ or message contents.
+///
+/// The [`EncryptorKind`] encrypts each message payload before it leaves the
client and decrypts it on
+/// the way back, keeping payloads opaque to the server. Attach either through
+/// [`create`].
+///
+/// # What you can do
Review Comment:
What you can do -> What can be done
##########
core/sdk/src/clients/client.rs:
##########
@@ -55,9 +55,159 @@ const SESSION_CONTROL_CODES: [u32; 5] = [
LOGIN_REGISTER_WITH_PAT_CODE,
];
-/// The main client struct which implements all the `Client` traits and wraps
the underlying low-level client for the specific transport.
+/// A high-level, transport-agnostic client for an Iggy server.
///
-/// It also provides the additional builders for the standalone consumer,
consumer group, and producer.
+/// `IggyClient` wraps a transport-specific low-level **client**
([`ClientWrapper`]) and
+/// **provides access to the full server API**.
+/// Iggy comes with four options for client-server communication: TCP, QUIC,
WebSocket and HTTP.
+/// The `IggyClient` is configured with one of these transport modes, hence
abstracting
+/// transport specific implementations away.
+///
+/// The [`ClientWrapper`] lives behind an [`IggyRwLock`] so that one connection
+/// can be shared safely. You create a single client and use it from many tasks
+/// at once (producers, consumers, the background heartbeat), and they all talk
+/// over the same connection. The lock keeps that safe. Many operations can
read
+/// from the connection at the same time, while actions that reshape it, like
+/// connecting, reconnecting, or logging in, briefly take exclusive access. It
is
+/// also async-aware, so holding it across a call to the server never blocks
the
+/// runtime.
+///
+/// A [`Partitioner`] and a client-side [`EncryptorKind`] are optional, and
both
+/// default to disabled. The [`Partitioner`] computes on the client-side the
target
+/// partition for messages published without an explicit partition. Hence,
routing
+/// can depend on the stream, topic, and/ or message contents.
+///
+/// The [`EncryptorKind`] encrypts each message payload before it leaves the
client and decrypts it on
+/// the way back, keeping payloads opaque to the server. Attach either through
+/// [`create`].
+///
+/// # What you can do
+///
+/// Configure a connection with an Iggy server and interact with it.
+/// The [`IggyClient`] provides various methods to setup the connection using
connection strings,
+/// builder patterns or an already existing [`ClientWrapper`].
+/// You can spawn [`IggyConsumer`]s and [`IggyProducer`]s that share that
connection.
+///
+/// The full server API is split into domain-specific traits.
+/// `IggyClient` implements [`Client`], the supertrait, which pulls every
domain-specific trait.
+/// Bring the one you need into scope to call its methods.
+/// `use iggy::prelude::*` brings all of them in at once.
+///
+/// - [`SystemClient`]: ping, server statistics, snapshots, and
connected-client info.
+/// - [`UserClient`]: create, inspect, update, and delete users and their
permissions.
+/// - [`PersonalAccessTokenClient`]: create, list, and delete personal access
tokens, log in with one.
+/// - [`StreamClient`]: create, get, update, delete, and purge streams.
+/// - [`TopicClient`]: create, get, update, delete, and purge topics within a
stream.
+/// - [`PartitionClient`]: add and remove partitions on a topic.
+/// - [`SegmentClient`]: delete closed segments from a partition.
+/// - [`ConsumerGroupClient`]: create, get, delete, and join or leave consumer
groups.
+/// - [`ConsumerOffsetClient`]: store, read, and delete consumer offsets.
+/// - [`MessageClient`]: send and poll messages, and flush the unsaved buffer.
+///
+/// Additionally, you can bypass invoking methods from these traits and
directly talk binary to the server with [`send_binary_request`] and
[`send_http_request`] for http.
+/// Both are essentially backdoors for low-level control. You need to know the
server codes and the wire format.
+///
+/// # Usage
+///
+/// The typical lifecycle of an [`IggyClient`] is construct [`connect`], use,
and finally [`shutdown`].
+///
+/// 1. Construct a client from a connection string
([`from_connection_string`]),
+/// from the [`builder`], or by wrapping an existing transport client with
+/// [`new`] / [`create`].
+/// 2. Call [`connect`] to establish the connection. If the transport was
+/// configured with auto-login, this also authenticates. Otherwise call
+/// [`UserClient::login_user`] afterwards.
+/// 3. Spawn [`IggyConsumer`]s and [`IggyProducers`] to write and consume
messages
+/// to and from the server.
Review Comment:
> 3. Spawn [`IggyConsumer`]s and [`IggyProducers`] to write and consume
messages to and from the server.
Spawn [`IggyConsumer`]s and [`IggyProducer`]s to write to, and consume
messages from, the server.
##########
core/sdk/src/clients/client.rs:
##########
@@ -55,9 +55,159 @@ const SESSION_CONTROL_CODES: [u32; 5] = [
LOGIN_REGISTER_WITH_PAT_CODE,
];
-/// The main client struct which implements all the `Client` traits and wraps
the underlying low-level client for the specific transport.
+/// A high-level, transport-agnostic client for an Iggy server.
///
-/// It also provides the additional builders for the standalone consumer,
consumer group, and producer.
+/// `IggyClient` wraps a transport-specific low-level **client**
([`ClientWrapper`]) and
+/// **provides access to the full server API**.
+/// Iggy comes with four options for client-server communication: TCP, QUIC,
WebSocket and HTTP.
+/// The `IggyClient` is configured with one of these transport modes, hence
abstracting
+/// transport specific implementations away.
+///
+/// The [`ClientWrapper`] lives behind an [`IggyRwLock`] so that one connection
+/// can be shared safely. You create a single client and use it from many tasks
+/// at once (producers, consumers, the background heartbeat), and they all talk
+/// over the same connection. The lock keeps that safe. Many operations can
read
+/// from the connection at the same time, while actions that reshape it, like
+/// connecting, reconnecting, or logging in, briefly take exclusive access. It
is
+/// also async-aware, so holding it across a call to the server never blocks
the
+/// runtime.
Review Comment:
I'd ideally rephrase this paragraph. There is a lot of repetition here and
the paragraph can be shortened.
##########
core/common/src/traits/partitioner.rs:
##########
@@ -21,8 +21,18 @@ use crate::types::message::IggyMessage;
use std::fmt::Debug;
/// The trait represent the logic responsible for calculating the partition ID
and is used by the `IggyClient`.
-/// This might be especially useful when the partition ID is not constant and
might be calculated based on the stream ID, topic ID and other parameters.
+///
+/// Iggy uses a hierarchical model for append-only logs. A stream contains
topics which hold partitions. Each partition is an append-only log.[^note]
+/// A producer of messages such as an [`IggyProducer`], that appends messages
to the log, might want to choose to which partition to write the messages.
Review Comment:
> might want to choose to which partition to write the messages.
might want to choose which partition to write the messages into.
##########
core/sdk/src/clients/client.rs:
##########
@@ -55,9 +55,159 @@ const SESSION_CONTROL_CODES: [u32; 5] = [
LOGIN_REGISTER_WITH_PAT_CODE,
];
-/// The main client struct which implements all the `Client` traits and wraps
the underlying low-level client for the specific transport.
+/// A high-level, transport-agnostic client for an Iggy server.
///
-/// It also provides the additional builders for the standalone consumer,
consumer group, and producer.
+/// `IggyClient` wraps a transport-specific low-level **client**
([`ClientWrapper`]) and
+/// **provides access to the full server API**.
+/// Iggy comes with four options for client-server communication: TCP, QUIC,
WebSocket and HTTP.
+/// The `IggyClient` is configured with one of these transport modes, hence
abstracting
+/// transport specific implementations away.
+///
+/// The [`ClientWrapper`] lives behind an [`IggyRwLock`] so that one connection
+/// can be shared safely. You create a single client and use it from many tasks
+/// at once (producers, consumers, the background heartbeat), and they all talk
+/// over the same connection. The lock keeps that safe. Many operations can
read
Review Comment:
"The lock keeps that safe" is not required.
##########
core/sdk/src/clients/client.rs:
##########
@@ -55,9 +55,159 @@ const SESSION_CONTROL_CODES: [u32; 5] = [
LOGIN_REGISTER_WITH_PAT_CODE,
];
-/// The main client struct which implements all the `Client` traits and wraps
the underlying low-level client for the specific transport.
+/// A high-level, transport-agnostic client for an Iggy server.
///
-/// It also provides the additional builders for the standalone consumer,
consumer group, and producer.
+/// `IggyClient` wraps a transport-specific low-level **client**
([`ClientWrapper`]) and
+/// **provides access to the full server API**.
+/// Iggy comes with four options for client-server communication: TCP, QUIC,
WebSocket and HTTP.
+/// The `IggyClient` is configured with one of these transport modes, hence
abstracting
+/// transport specific implementations away.
+///
+/// The [`ClientWrapper`] lives behind an [`IggyRwLock`] so that one connection
+/// can be shared safely. You create a single client and use it from many tasks
+/// at once (producers, consumers, the background heartbeat), and they all talk
+/// over the same connection. The lock keeps that safe. Many operations can
read
+/// from the connection at the same time, while actions that reshape it, like
+/// connecting, reconnecting, or logging in, briefly take exclusive access. It
is
+/// also async-aware, so holding it across a call to the server never blocks
the
+/// runtime.
+///
+/// A [`Partitioner`] and a client-side [`EncryptorKind`] are optional, and
both
+/// default to disabled. The [`Partitioner`] computes on the client-side the
target
+/// partition for messages published without an explicit partition. Hence,
routing
+/// can depend on the stream, topic, and/ or message contents.
+///
+/// The [`EncryptorKind`] encrypts each message payload before it leaves the
client and decrypts it on
+/// the way back, keeping payloads opaque to the server. Attach either through
+/// [`create`].
+///
+/// # What you can do
+///
+/// Configure a connection with an Iggy server and interact with it.
+/// The [`IggyClient`] provides various methods to setup the connection using
connection strings,
+/// builder patterns or an already existing [`ClientWrapper`].
+/// You can spawn [`IggyConsumer`]s and [`IggyProducer`]s that share that
connection.
+///
+/// The full server API is split into domain-specific traits.
+/// `IggyClient` implements [`Client`], the supertrait, which pulls every
domain-specific trait.
+/// Bring the one you need into scope to call its methods.
+/// `use iggy::prelude::*` brings all of them in at once.
+///
+/// - [`SystemClient`]: ping, server statistics, snapshots, and
connected-client info.
+/// - [`UserClient`]: create, inspect, update, and delete users and their
permissions.
+/// - [`PersonalAccessTokenClient`]: create, list, and delete personal access
tokens, log in with one.
+/// - [`StreamClient`]: create, get, update, delete, and purge streams.
+/// - [`TopicClient`]: create, get, update, delete, and purge topics within a
stream.
+/// - [`PartitionClient`]: add and remove partitions on a topic.
+/// - [`SegmentClient`]: delete closed segments from a partition.
+/// - [`ConsumerGroupClient`]: create, get, delete, and join or leave consumer
groups.
+/// - [`ConsumerOffsetClient`]: store, read, and delete consumer offsets.
+/// - [`MessageClient`]: send and poll messages, and flush the unsaved buffer.
+///
+/// Additionally, you can bypass invoking methods from these traits and
directly talk binary to the server with [`send_binary_request`] and
[`send_http_request`] for http.
+/// Both are essentially backdoors for low-level control. You need to know the
server codes and the wire format.
+///
+/// # Usage
+///
+/// The typical lifecycle of an [`IggyClient`] is construct [`connect`], use,
and finally [`shutdown`].
+///
+/// 1. Construct a client from a connection string
([`from_connection_string`]),
+/// from the [`builder`], or by wrapping an existing transport client with
+/// [`new`] / [`create`].
+/// 2. Call [`connect`] to establish the connection. If the transport was
+/// configured with auto-login, this also authenticates. Otherwise call
+/// [`UserClient::login_user`] afterwards.
Review Comment:
> Otherwise call [`UserClient::login_user`] afterwards.
"Otherwise call [`login_user`] afterwards." seems better
##########
core/sdk/src/clients/client.rs:
##########
@@ -55,9 +55,159 @@ const SESSION_CONTROL_CODES: [u32; 5] = [
LOGIN_REGISTER_WITH_PAT_CODE,
];
-/// The main client struct which implements all the `Client` traits and wraps
the underlying low-level client for the specific transport.
+/// A high-level, transport-agnostic client for an Iggy server.
///
-/// It also provides the additional builders for the standalone consumer,
consumer group, and producer.
+/// `IggyClient` wraps a transport-specific low-level **client**
([`ClientWrapper`]) and
+/// **provides access to the full server API**.
+/// Iggy comes with four options for client-server communication: TCP, QUIC,
WebSocket and HTTP.
+/// The `IggyClient` is configured with one of these transport modes, hence
abstracting
+/// transport specific implementations away.
+///
+/// The [`ClientWrapper`] lives behind an [`IggyRwLock`] so that one connection
+/// can be shared safely. You create a single client and use it from many tasks
+/// at once (producers, consumers, the background heartbeat), and they all talk
+/// over the same connection. The lock keeps that safe. Many operations can
read
+/// from the connection at the same time, while actions that reshape it, like
+/// connecting, reconnecting, or logging in, briefly take exclusive access. It
is
+/// also async-aware, so holding it across a call to the server never blocks
the
+/// runtime.
+///
+/// A [`Partitioner`] and a client-side [`EncryptorKind`] are optional, and
both
+/// default to disabled. The [`Partitioner`] computes on the client-side the
target
+/// partition for messages published without an explicit partition. Hence,
routing
+/// can depend on the stream, topic, and/ or message contents.
+///
+/// The [`EncryptorKind`] encrypts each message payload before it leaves the
client and decrypts it on
+/// the way back, keeping payloads opaque to the server. Attach either through
+/// [`create`].
+///
+/// # What you can do
+///
+/// Configure a connection with an Iggy server and interact with it.
+/// The [`IggyClient`] provides various methods to setup the connection using
connection strings,
+/// builder patterns or an already existing [`ClientWrapper`].
+/// You can spawn [`IggyConsumer`]s and [`IggyProducer`]s that share that
connection.
+///
+/// The full server API is split into domain-specific traits.
+/// `IggyClient` implements [`Client`], the supertrait, which pulls every
domain-specific trait.
+/// Bring the one you need into scope to call its methods.
+/// `use iggy::prelude::*` brings all of them in at once.
+///
+/// - [`SystemClient`]: ping, server statistics, snapshots, and
connected-client info.
+/// - [`UserClient`]: create, inspect, update, and delete users and their
permissions.
+/// - [`PersonalAccessTokenClient`]: create, list, and delete personal access
tokens, log in with one.
+/// - [`StreamClient`]: create, get, update, delete, and purge streams.
+/// - [`TopicClient`]: create, get, update, delete, and purge topics within a
stream.
+/// - [`PartitionClient`]: add and remove partitions on a topic.
+/// - [`SegmentClient`]: delete closed segments from a partition.
+/// - [`ConsumerGroupClient`]: create, get, delete, and join or leave consumer
groups.
+/// - [`ConsumerOffsetClient`]: store, read, and delete consumer offsets.
+/// - [`MessageClient`]: send and poll messages, and flush the unsaved buffer.
+///
+/// Additionally, you can bypass invoking methods from these traits and
directly talk binary to the server with [`send_binary_request`] and
[`send_http_request`] for http.
+/// Both are essentially backdoors for low-level control. You need to know the
server codes and the wire format.
+///
+/// # Usage
+///
+/// The typical lifecycle of an [`IggyClient`] is construct [`connect`], use,
and finally [`shutdown`].
Review Comment:
> construct [`connect`], use, and finally [`shutdown`].
construct, [`connect`], use, and finally [`shutdown`].
##########
core/sdk/src/clients/client.rs:
##########
@@ -55,9 +55,159 @@ const SESSION_CONTROL_CODES: [u32; 5] = [
LOGIN_REGISTER_WITH_PAT_CODE,
];
-/// The main client struct which implements all the `Client` traits and wraps
the underlying low-level client for the specific transport.
+/// A high-level, transport-agnostic client for an Iggy server.
///
-/// It also provides the additional builders for the standalone consumer,
consumer group, and producer.
+/// `IggyClient` wraps a transport-specific low-level **client**
([`ClientWrapper`]) and
+/// **provides access to the full server API**.
+/// Iggy comes with four options for client-server communication: TCP, QUIC,
WebSocket and HTTP.
+/// The `IggyClient` is configured with one of these transport modes, hence
abstracting
+/// transport specific implementations away.
+///
+/// The [`ClientWrapper`] lives behind an [`IggyRwLock`] so that one connection
+/// can be shared safely. You create a single client and use it from many tasks
+/// at once (producers, consumers, the background heartbeat), and they all talk
+/// over the same connection. The lock keeps that safe. Many operations can
read
+/// from the connection at the same time, while actions that reshape it, like
+/// connecting, reconnecting, or logging in, briefly take exclusive access. It
is
+/// also async-aware, so holding it across a call to the server never blocks
the
+/// runtime.
+///
+/// A [`Partitioner`] and a client-side [`EncryptorKind`] are optional, and
both
+/// default to disabled. The [`Partitioner`] computes on the client-side the
target
+/// partition for messages published without an explicit partition. Hence,
routing
+/// can depend on the stream, topic, and/ or message contents.
+///
+/// The [`EncryptorKind`] encrypts each message payload before it leaves the
client and decrypts it on
+/// the way back, keeping payloads opaque to the server. Attach either through
+/// [`create`].
+///
+/// # What you can do
+///
+/// Configure a connection with an Iggy server and interact with it.
+/// The [`IggyClient`] provides various methods to setup the connection using
connection strings,
+/// builder patterns or an already existing [`ClientWrapper`].
+/// You can spawn [`IggyConsumer`]s and [`IggyProducer`]s that share that
connection.
+///
+/// The full server API is split into domain-specific traits.
+/// `IggyClient` implements [`Client`], the supertrait, which pulls every
domain-specific trait.
+/// Bring the one you need into scope to call its methods.
+/// `use iggy::prelude::*` brings all of them in at once.
+///
+/// - [`SystemClient`]: ping, server statistics, snapshots, and
connected-client info.
+/// - [`UserClient`]: create, inspect, update, and delete users and their
permissions.
+/// - [`PersonalAccessTokenClient`]: create, list, and delete personal access
tokens, log in with one.
+/// - [`StreamClient`]: create, get, update, delete, and purge streams.
+/// - [`TopicClient`]: create, get, update, delete, and purge topics within a
stream.
+/// - [`PartitionClient`]: add and remove partitions on a topic.
+/// - [`SegmentClient`]: delete closed segments from a partition.
+/// - [`ConsumerGroupClient`]: create, get, delete, and join or leave consumer
groups.
+/// - [`ConsumerOffsetClient`]: store, read, and delete consumer offsets.
+/// - [`MessageClient`]: send and poll messages, and flush the unsaved buffer.
+///
+/// Additionally, you can bypass invoking methods from these traits and
directly talk binary to the server with [`send_binary_request`] and
[`send_http_request`] for http.
+/// Both are essentially backdoors for low-level control. You need to know the
server codes and the wire format.
+///
+/// # Usage
+///
+/// The typical lifecycle of an [`IggyClient`] is construct [`connect`], use,
and finally [`shutdown`].
+///
+/// 1. Construct a client from a connection string
([`from_connection_string`]),
+/// from the [`builder`], or by wrapping an existing transport client with
+/// [`new`] / [`create`].
+/// 2. Call [`connect`] to establish the connection. If the transport was
+/// configured with auto-login, this also authenticates. Otherwise call
+/// [`UserClient::login_user`] afterwards.
+/// 3. Spawn [`IggyConsumer`]s and [`IggyProducers`] to write and consume
messages
+/// to and from the server.
+/// 4. Call [`shutdown`] (or drop the client) to release resources; drop also
+/// leaves any consumer groups the client had joined.
Review Comment:
You talk about drop leaving any consumer groups behind here, but do not talk
about what shutdown does to consumer groups.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
