s2_sdk/
lib.rs

1/*!
2Rust SDK for [S2](https://s2.dev/).
3
4The Rust SDK provides ergonomic wrappers and utilities to interact with the
5[S2 API](https://s2.dev/docs/rest/records/overview).
6
7# Getting started
8
91. Ensure you have added [tokio](https://crates.io/crates/tokio) and [futures](https://crates.io/crates/futures) as dependencies.
10   ```bash
11   cargo add tokio --features full
12   cargo add futures
13   ```
14
151. Add the `s2-sdk` dependency to your project:
16
17   ```bash
18   cargo add s2-sdk
19   ```
20
211. Generate an access token by logging into the web console at [s2.dev](https://s2.dev/dashboard).
22
231. Perform an operation.
24
25   ```no_run
26    use s2_sdk::{
27        S2,
28        types::{ListBasinsInput, S2Config},
29    };
30
31    #[tokio::main]
32    async fn main() -> Result<(), Box<dyn std::error::Error>> {
33        let s2 = S2::new(S2Config::new("<YOUR_ACCESS_TOKEN>"))?;
34        let page = s2.list_basins(ListBasinsInput::new()).await?;
35        println!("My basins: {:?}", page.values);
36        Ok(())
37    }
38   ```
39
40See [`S2`] for account-level operations, [`S2Basin`] for basin-level operations,
41and [`S2Stream`] for stream-level operations.
42
43# Examples
44
45We have curated a bunch of examples in the
46[repository](https://github.com/s2-streamstore/s2/tree/main/sdk/examples)
47demonstrating how to use the SDK effectively:
48
49* [List all basins](https://github.com/s2-streamstore/s2/blob/main/sdk/examples/list_all_basins.rs)
50* [Explicit stream trimming](https://github.com/s2-streamstore/s2/blob/main/sdk/examples/explicit_trim.rs)
51* [Producer](https://github.com/s2-streamstore/s2/blob/main/sdk/examples/producer.rs)
52* [Consumer](https://github.com/s2-streamstore/s2/blob/main/sdk/examples/consumer.rs)
53* and many more...
54
55This documentation is generated using
56[`rustdoc-scrape-examples`](https://doc.rust-lang.org/rustdoc/scraped-examples.html),
57so you will be able to see snippets from examples right here in the
58documentation.
59
60# Integration tests with s2-lite
61
62Use [`s2-testcontainers`](https://docs.rs/s2-testcontainers/latest/s2_testcontainers/)
63to start `s2-lite` from the S2 Docker image and get an SDK client/config without
64manual Docker port allocation, endpoint plumbing, or health polling. See the
65[`s2_lite` example](https://github.com/s2-streamstore/s2/blob/main/testcontainers/examples/s2_lite.rs)
66for the canonical setup.
67
68# Feedback
69
70We use [Github Issues](https://github.com/s2-streamstore/s2/issues)
71to track feature requests and issues with the SDK. If you wish to provide
72feedback, report a bug or request a feature, feel free to open a Github
73issue.
74
75# Quick Links
76
77* [S2 Website](https://s2.dev)
78* [S2 Documentation](https://s2.dev/docs)
79* [CHANGELOG](https://github.com/s2-streamstore/s2/blob/main/sdk/CHANGELOG.md)
80*/
81
82#![doc(
83    html_favicon_url = "https://raw.githubusercontent.com/s2-streamstore/s2/main/assets/s2-black.png"
84)]
85#![doc(
86    html_logo_url = "https://raw.githubusercontent.com/s2-streamstore/s2/main/assets/s2-black.png"
87)]
88#![warn(missing_docs)]
89
90#[rustfmt::skip]
91mod api;
92mod client;
93mod frame_signal;
94mod session;
95
96pub mod batching;
97mod ops;
98pub mod producer;
99mod retry;
100pub mod types;
101
102pub use ops::{S2, S2Basin, S2Stream};
103/// Append session for pipelining multiple appends with backpressure control.
104///
105/// See [`AppendSession`](append_session::AppendSession).
106pub mod append_session {
107    pub use crate::session::append::{
108        AppendSession, AppendSessionConfig, BatchSubmitPermit, BatchSubmitTicket,
109    };
110}
s2_sdk/lib.rs

s2_sdk/
lib.rs
