kaivrpc 0.2.0

RPC over kaiv documents: the request/response envelope, typed params, and line-per-element streaming
Documentation
//! **kaivrpc** — RPC over [kaiv](https://kaiv.io/) documents.
//!
//! A request is a document; a response is a document. Both sides
//! are ordinary kaiv, so a request can be saved, diffed, and
//! replayed with `curl --data-binary @req.kaiv`, and a response
//! can be validated against its schema, grepped, or consumed
//! line by line as it streams.
//!
//! ```text
//! .!kaiv                       →  .!daiv
//! method=Post.MultiGet            .!schema:kaivrpc/response-head
//! /params::ws=AGORA               .!schema:<method's data schema>
//! /params/@ids;=t3_9fq2k          .!schema:kaivrpc/response-tail
//!                                 !str'::status=ok
//!                                 !str'/data/@posts/0::id=t3_9fq2k
//!                                 …
//!                                 !null'::error=
//!                                 !int'::n=1
//! ```
//!
//! # The envelope is three composed schemas
//!
//! A response declares a **head** (`::status`, the verdict before
//! any data flows), the method's own **data schema** (fields under
//! `/data`), and a **tail** (`::error?` and the required `::n`).
//! Composition order is composed field order, so the ordered scan
//! enforces the layout — and because the tail is schema-REQUIRED
//! and last, a truncated response fails validation on the client
//! with no protocol machinery at all. The envelope schemas live in
//! this crate's [`schemas`] module; publish them (or your own
//! namespaced copies — see [`Envelope::with_schemas`]) so clients
//! can resolve them.
//!
//! # Streaming is the point
//!
//! Every canonical line is a self-contained `(type, namepath,
//! value)` fact, so a server can flush as it goes and a client can
//! act on each element the moment its run ends.
//! [`Response::stream_chunks`] emits one chunk per element run —
//! the measured compression-friendly cadence (flushing per LINE
//! forfeits compression; per element run costs ~30% against a
//! buffered body while keeping a shared compression context for
//! the whole response).
//!
//! # What this crate is not
//!
//! Transport-agnostic by construction: no HTTP framework, no
//! async runtime. You get `String`s and `Vec<String>`s and wire
//! them into whatever server you have. Dispatch, authentication,
//! and authorization stay yours.

#![forbid(unsafe_code)]

#[cfg(feature = "axum")]
pub mod axum_support;
pub mod error;
pub mod request;
pub mod response;
pub mod schemas;

pub use error::{Error, RpcError};
pub use request::{Request, ValidationFailure};
pub use response::{Envelope, Response};

/// Per-field wire-type overrides — re-exported from kaiv, since
/// every non-trivial response needs them: serde sees only the Rust
/// type, but a union's discriminant and `!text` are NOMINAL on the
/// wire.
pub use kaiv::serde::{Head, Heads};