ytsaurus_rpc/lib.rs
1//! A client for the YTsaurus **RPC proxy**.
2//!
3//! HTTP API v4 — which [`ytsaurus-client`](https://docs.rs/ytsaurus-client) speaks —
4//! can already reach every dynamic-table command. This crate exists for
5//! latency and throughput under concurrency, never for capability: one
6//! connection multiplexes many in-flight requests, where HTTP pays its
7//! per-request cost every time.
8//!
9//! # The protocol is four layers, and only the top one looks familiar
10//!
11//! | Layer | What it is | Module |
12//! | --- | --- | --- |
13//! | 1 | **Bus** — framed, checksummed packets over TCP | [`bus`] |
14//! | 2 | **RPC envelope** — request and response headers, `TError` | [`rpc`] |
15//! | 3 | **API surface** — generated protobuf | [`proto`] |
16//! | 4 | **Row wire format** — rows in attachments, not protobuf fields | [`wire`] |
17//!
18//! Layer 4 is the one that surprises people: rows do **not** travel as
19//! protobuf. `api_service.proto` says outright that "actual data is passed via
20//! attachments in the wire protocol", and that format is neither YSON nor
21//! Skiff — it is a third one, mandatory for every dynamic-table read and write.
22//!
23//! # Shape of the code
24//!
25//! The parsers are **sans-io**: [`crc64`], [`bus::packet`], [`rpc`] and
26//! [`wire`] are pure functions from bytes to values, with no `async` anywhere,
27//! so every one of them is testable without a runtime — and fuzzable, though
28//! they are not yet fuzzed (gate E in `docs/rpc-compatibility.md`). `async`
29//! appears only at the I/O edges — [`bus::Bus`] and
30//! [`connection::Connection`].
31//!
32//! # Example
33//!
34//! ```no_run
35//! use ytsaurus_rpc::client::{Client, LookupOptions};
36//! use ytsaurus_rpc::wire::{UnversionedValue, Value};
37//!
38//! # async fn example() -> ytsaurus_rpc::error::Result<()> {
39//! let client = Client::connect("localhost:8011").await?;
40//!
41//! let key = vec![UnversionedValue::new(0, Value::Int64(42))];
42//! let rows = client
43//! .lookup_rows("//tmp/table", &["key"], &[key], LookupOptions::default())
44//! .await?;
45//!
46//! // One entry per key asked for, in order; `None` where the key had no row.
47//! for row in rows {
48//! println!("{row:?}");
49//! }
50//! # Ok(())
51//! # }
52//! ```
53//!
54//! # Status
55//!
56//! **Pre-release**, and published from 0.3.0. The ship gates are not all green
57//! and the API may change in a patch release. What is implemented, what is
58//! deliberately left out and what has actually been run against a cluster are
59//! listed in [`docs/rpc-compatibility.md`][compat] in the repository.
60//!
61//! [compat]: https://github.com/sshaplygin/ytsaurus-rs/blob/main/docs/rpc-compatibility.md
62
63pub mod blocking;
64pub mod bus;
65pub mod client;
66pub mod connection;
67pub mod crc64;
68pub mod error;
69pub mod guid;
70pub mod proto;
71pub mod rpc;
72pub mod wire;
73
74pub use client::{Client, ClientBuilder, Transaction};
75pub use error::{Error, Result, YtError};
76pub use guid::Guid;
77pub use wire::{Row, UnversionedValue, Value, ValueType};