chore(docs): proposal core/sdk lib.rs and IggyClient docs - #3809
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #3809 +/- ##
============================================
- Coverage 75.78% 74.18% -1.60%
Complexity 969 969
============================================
Files 1323 1323
Lines 159751 154825 -4926
Branches 133139 128291 -4848
============================================
- Hits 121071 114861 -6210
- Misses 35045 36022 +977
- Partials 3635 3942 +307
🚀 New features to boost your workflow:
|
| /// 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. |
There was a problem hiding this comment.
might want to choose to which partition to write the messages.
might want to choose which partition to write the messages into.
| /// 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. |
There was a problem hiding this comment.
This might be especially useful
This may be especially useful
There was a problem hiding this comment.
stream ID, topic ID and [
IggyMessage] attributes.
stream ID, topic ID or [IggyMessage] attributes.
| /// 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()`]. |
There was a problem hiding this 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
| /// - `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. |
There was a problem hiding this 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
| /// 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 |
There was a problem hiding this comment.
"The lock keeps that safe" is not required.
| /// - [`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. |
There was a problem hiding this 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?
| /// | ||
| /// # Usage | ||
| /// | ||
| /// The typical lifecycle of an [`IggyClient`] is construct [`connect`], use, and finally [`shutdown`]. |
There was a problem hiding this comment.
construct [
connect], use, and finally [shutdown].
construct, [connect], use, and finally [shutdown].
| /// 2. Call [`connect`] to establish the connection. If the transport was | ||
| /// configured with auto-login, this also authenticates. Otherwise call | ||
| /// [`UserClient::login_user`] afterwards. |
There was a problem hiding this comment.
Otherwise call [
UserClient::login_user] afterwards.
"Otherwise call [login_user] afterwards." seems better
| /// 3. Spawn [`IggyConsumer`]s and [`IggyProducers`] to write and consume messages | ||
| /// to and from the server. |
There was a problem hiding this comment.
- 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.
| /// 4. Call [`shutdown`] (or drop the client) to release resources; drop also | ||
| /// leaves any consumer groups the client had joined. |
There was a problem hiding this comment.
You talk about drop leaving any consumer groups behind here, but do not talk about what shutdown does to consumer groups.
2 participants
Draft PR as discussed here: https://discord.com/channels/1144142576266530928/1144142825630474360/1507361396382240839
Would be nice to get some feedback on:
If the general direction is good and supported, happy to clean and merge.
Would suggest to continue with IggyConsumer and IggyProducer in a next PR.
Which issue does this PR address?
Closes #3306Rationale
Adding User facing docs for the Rust SDK.
What changed?
Local Execution
AI Usage
Everything is manually written or at least re-written in cases I had claude suggest a formulation.