kaivrpc 0.2.0

RPC over kaiv documents: the request/response envelope, typed params, and line-per-element streaming
Documentation
//! The envelope microschemas, as authored `.saiv` source.
//!
//! Two tiny schemas compose around every method's own data schema:
//!
//! ```text
//! .!schema:kaivrpc/response-head    ::status — the verdict first
//! .!schema:<method data schema>     fields under /data
//! .!schema:kaivrpc/response-tail    ::error? + ::n — marker last
//! ```
//!
//! Composition order is composed field order, so the ordered scan
//! enforces the layout: `status` cannot arrive after the data, and
//! the tail cannot be missing. That last property is the useful
//! one — a truncated stream fails validation with no protocol
//! machinery, because `::n` is schema-required and last.
//!
//! Publish these under the names in [`HEAD_NAME`] / [`TAIL_NAME`]
//! (or your own namespace — pass the names to
//! [`Envelope::with_schemas`](crate::Envelope::with_schemas)) so
//! clients can resolve what a response declares.

/// The registry name a response's head schema is declared under.
pub const HEAD_NAME: &str = "kaivrpc/response-head";
/// The registry name a response's tail schema is declared under.
pub const TAIL_NAME: &str = "kaivrpc/response-tail";
/// The registry name of the generic request envelope.
pub const REQUEST_NAME: &str = "kaivrpc/request";

/// The response head: the verdict, before any data flows.
pub const HEAD_SAIV: &str = include_str!("../schemas/response-head.saiv");
/// The response tail: why it died (null on success) and the
/// element count that doubles as the end-of-stream marker.
pub const TAIL_SAIV: &str = include_str!("../schemas/response-tail.saiv");
/// The generic request envelope: a method name. `/params` is
/// typed by the method's own request schema, which composes this.
pub const REQUEST_SAIV: &str = include_str!("../schemas/request.saiv");

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn the_shipped_schemas_compile() {
        // The resolver is offline: these three depend on nothing.
        let r = kaiv::Resolver::offline();
        for (name, src) in [
            (HEAD_NAME, HEAD_SAIV),
            (TAIL_NAME, TAIL_SAIV),
            (REQUEST_NAME, REQUEST_SAIV),
        ] {
            kaiv::compile_schema_with(src.as_bytes(), &r).unwrap_or_else(|e| panic!("{name}: {e}"));
        }
    }
}