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* [Caught-up read session](https://github.com/s2-streamstore/s2/blob/main/sdk/examples/caught_up.rs)
54* and many more...
55
56This documentation is generated using
57[`rustdoc-scrape-examples`](https://doc.rust-lang.org/rustdoc/scraped-examples.html),
58so you will be able to see snippets from examples right here in the
59documentation.
60
61# Integration tests with s2-lite
62
63Use [`s2-testcontainers`](https://docs.rs/s2-testcontainers/latest/s2_testcontainers/)
64to start `s2-lite` from the S2 Docker image and get an SDK client/config without
65manual Docker port allocation, endpoint plumbing, or health polling. See the
66[`s2_lite` example](https://github.com/s2-streamstore/s2/blob/main/testcontainers/examples/s2_lite.rs)
67for the canonical setup.
68
69# Feedback
70
71We use [Github Issues](https://github.com/s2-streamstore/s2/issues)
72to track feature requests and issues with the SDK. If you wish to provide
73feedback, report a bug or request a feature, feel free to open a Github
74issue.
75
76# Quick Links
77
78* [S2 Website](https://s2.dev)
79* [S2 Documentation](https://s2.dev/docs)
80* [CHANGELOG](https://github.com/s2-streamstore/s2/blob/main/sdk/CHANGELOG.md)
81*/
82
83#![doc(
84    html_favicon_url = "https://raw.githubusercontent.com/s2-streamstore/s2/main/assets/s2-black.png"
85)]
86#![doc(
87    html_logo_url = "https://raw.githubusercontent.com/s2-streamstore/s2/main/assets/s2-black.png"
88)]
89#![warn(missing_docs)]
90
91#[rustfmt::skip]
92mod api;
93mod client;
94mod frame_signal;
95mod session;
96
97pub mod batching;
98pub mod error;
99mod ops;
100pub mod producer;
101mod retry;
102pub mod types;
103
104pub use ops::{S2, S2Basin, S2Stream};
105/// Append session for pipelining multiple appends with backpressure control.
106///
107/// See [`AppendSession`](append_session::AppendSession).
108pub mod append_session {
109    pub use crate::session::append::{
110        AppendSession, AppendSessionConfig, BatchSubmitPermit, BatchSubmitTicket,
111    };
112}
113/// Continuous read sessions.
114pub mod read_session {
115    pub use crate::session::read::ReadSession;
116}
s2_sdk/lib.rs

s2_sdk/
lib.rs
