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