Skip to main content

Crate kaivrpc

Crate kaivrpc 

Source
Expand description

kaivrpc — RPC over kaiv 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.

.!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 Strings and Vec<String>s and wire them into whatever server you have. Dispatch, authentication, and authorization stay yours.

Re-exports§

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

Modules§

axum_support
Optional axum glue (--features axum).
error
Errors: the crate’s own failure type, and the application error a response carries in its tail.
request
The request side: a document in, a method name and typed params out.
response
The response side: the composed envelope, buffered or streamed.
schemas
The envelope microschemas, as authored .saiv source.

Enums§

Head
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. A field’s wire-type override (matched by field name, wherever the field appears).

Type Aliases§

Heads
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. Field-name → Head overrides.