kaivrpc 0.2.0

RPC over kaiv documents: the request/response envelope, typed params, and line-per-element streaming
Documentation
//! The response side: the composed envelope, buffered or
//! streamed.

use kaiv::builder::DaivBuilder;
use kaiv::serde::Heads;
use serde::Serialize;

use crate::error::{Error, RpcError};
use crate::schemas;

/// Which schemas a response declares around its data layer.
///
/// The default names the schemas this crate ships
/// ([`schemas::HEAD_NAME`] / [`schemas::TAIL_NAME`]); deployments
/// that publish their own namespaced copies name those instead.
#[derive(Debug, Clone)]
pub struct Envelope {
    head: String,
    tail: String,
}

impl Default for Envelope {
    fn default() -> Self {
        Envelope {
            head: schemas::HEAD_NAME.to_string(),
            tail: schemas::TAIL_NAME.to_string(),
        }
    }
}

impl Envelope {
    /// The envelope naming this crate's shipped schemas.
    pub fn kaivrpc() -> Envelope {
        Envelope::default()
    }

    /// An envelope naming your own published head/tail schemas
    /// (e.g. `acme/rpc/response-head`). The FIELDS must match what
    /// this crate emits — `status`, `error?`, `n` — since the
    /// emitters here write them; only the registry names differ.
    pub fn with_schemas(head: impl Into<String>, tail: impl Into<String>) -> Envelope {
        Envelope {
            head: head.into(),
            tail: tail.into(),
        }
    }
}

/// A response under construction.
///
/// Two shapes come out of the same envelope, byte-identical when
/// concatenated: [`buffered`](Response::buffered) for a single
/// body, [`stream_chunks`](Response::stream_chunks) for chunked
/// transfer with one chunk per element run.
pub struct Response<'a> {
    envelope: Envelope,
    /// The method's own data schema, declared between head and
    /// tail. `None` for methods with no published schema — the
    /// response is still well-formed, just less checkable.
    data_schema: Option<String>,
    heads: Heads<'a>,
}

impl<'a> Response<'a> {
    /// A response builder for one method.
    pub fn new(envelope: Envelope, data_schema: Option<&str>, heads: Heads<'a>) -> Response<'a> {
        Response {
            envelope,
            data_schema: data_schema.map(str::to_string),
            heads,
        }
    }

    /// The declaration header plus `status=ok` — chunk zero of a
    /// stream, and the opening of a buffered document.
    fn open(&self, status: &str) -> Result<String, Error> {
        let mut b = DaivBuilder::new();
        b.declare_schema(&self.envelope.head)?;
        if let Some(s) = &self.data_schema {
            b.declare_schema(s)?;
        }
        b.declare_schema(&self.envelope.tail)?;
        b.leaf("::status", "str", status, None)?;
        Ok(b.finish_daiv())
    }

    /// The tail: `error` (null on success) and the required count.
    fn close(&self, error: Option<&RpcError>, n: usize) -> Result<String, Error> {
        let mut b = DaivBuilder::new();
        match error {
            Some(e) => b.leaf("::error", "str", &e.to_line(), None)?,
            None => b.leaf("::error", "null", "", None)?,
        }
        b.leaf("::n", "int", &n.to_string(), None)?;
        Ok(data_lines(b))
    }

    /// A complete buffered response: header, `status=ok`, the
    /// serialized data under `/data`, the tail.
    ///
    /// `n` is the element count clients read as the stream's
    /// length — the length of the response's primary collection.
    pub fn buffered<T: Serialize>(&self, data: &T, n: usize) -> Result<String, Error> {
        let mut out = self.open("ok")?;
        let mut b = DaivBuilder::new();
        kaiv::serde::serialize_into(&mut b, "/data", self.heads, data)?;
        out.push_str(&data_lines(b));
        out.push_str(&self.close(None, n)?);
        Ok(out)
    }

    /// The streamed form: chunk zero is the header plus the
    /// verdict, then ONE CHUNK PER ELEMENT of `items` (written at
    /// `{array_path}/{index}`), then the tail.
    ///
    /// Flush one chunk per element run — that cadence keeps lines
    /// arriving as lines while preserving a shared compression
    /// context for the response; flushing per LINE forfeits
    /// compression almost entirely.
    ///
    /// Concatenated, the chunks equal [`buffered`](Self::buffered)
    /// for the same elements, so a client that simply collects the
    /// body cannot tell which shape it received.
    pub fn stream_chunks<T: Serialize>(
        &self,
        array_path: &str,
        items: &[T],
    ) -> Result<Vec<String>, Error> {
        let mut chunks = Vec::with_capacity(items.len() + 2);
        chunks.push(self.open("ok")?);
        for (i, item) in items.iter().enumerate() {
            let mut b = DaivBuilder::new();
            kaiv::serde::serialize_into(&mut b, &format!("{array_path}/{i}"), self.heads, item)?;
            chunks.push(data_lines(b));
        }
        chunks.push(self.close(None, items.len())?);
        Ok(chunks)
    }

    /// The error document: the envelope with no data layer —
    /// `status=error`, the tail carrying the error line, `n` zero.
    ///
    /// Note a mid-stream failure is different: a server that has
    /// already flushed `status=ok` reports it in the TAIL via
    /// [`fail_late`](Self::fail_late), which is exactly why the
    /// tail carries an error field at all.
    pub fn error(&self, error: &RpcError) -> Result<String, Error> {
        let mut b = DaivBuilder::new();
        b.declare_schema(&self.envelope.head)?;
        b.declare_schema(&self.envelope.tail)?;
        b.leaf("::status", "str", "error", None)?;
        let mut out = b.finish_daiv();
        out.push_str(&self.close(Some(error), 0)?);
        Ok(out)
    }

    /// The tail for a stream that started `ok` and then failed —
    /// append it in place of the closing chunk. `n` is however
    /// many elements did make it out.
    pub fn fail_late(&self, error: &RpcError, n: usize) -> Result<String, Error> {
        self.close(Some(error), n)
    }
}

/// A builder's data lines without the `.!daiv` declaration — what
/// a mid-stream chunk appends to an already-opened document.
fn data_lines(b: DaivBuilder) -> String {
    let doc = b.finish_daiv();
    match doc.split_once('\n') {
        Some((_declaration, rest)) => rest.to_string(),
        None => String::new(),
    }
}

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

    #[derive(Serialize)]
    struct Row {
        id: String,
        score: i64,
        body: Option<String>,
    }

    #[derive(Serialize)]
    struct Data {
        rows: Vec<Row>,
    }

    fn rows() -> Vec<Row> {
        vec![
            Row {
                id: "t3_a".into(),
                score: 5,
                body: Some("one\ntwo".into()),
            },
            Row {
                id: "t1_b".into(),
                score: -1,
                body: None,
            },
        ]
    }

    const HEADS: Heads<'static> = &[("body", kaiv::serde::Head::Text { embed: "plain" })];

    #[test]
    fn buffered_carries_the_whole_envelope() {
        let r = Response::new(Envelope::kaivrpc(), Some("acme/resp/list"), HEADS);
        let doc = r.buffered(&Data { rows: rows() }, 2).unwrap();
        assert!(doc.starts_with(".!daiv\n"), "{doc}");
        assert!(doc.contains(".!schema:kaivrpc/response-head\n"), "{doc}");
        assert!(doc.contains(".!schema:acme/resp/list\n"), "{doc}");
        assert!(doc.contains(".!schema:kaivrpc/response-tail\n"), "{doc}");
        assert!(doc.contains("!str'::status=ok\n"), "{doc}");
        // Multi-line text rides !text; None rides !null.
        assert!(
            doc.contains("!text'/data/@rows/0::body=one|:|two\n"),
            "{doc}"
        );
        assert!(doc.contains("!null'/data/@rows/1::body=\n"), "{doc}");
        assert!(doc.ends_with("!null'::error=\n!int'::n=2\n"), "{doc}");
    }

    #[test]
    fn streamed_chunks_concatenate_to_the_buffered_document() {
        let r = Response::new(Envelope::kaivrpc(), Some("acme/resp/list"), HEADS);
        let chunks = r.stream_chunks("/data/@rows", &rows()).unwrap();
        assert_eq!(chunks.len(), 4, "header + 2 elements + tail");
        assert!(chunks[0].starts_with(".!daiv\n"));
        assert!(chunks[1].starts_with('!'), "element chunks are bare lines");
        let joined: String = chunks.concat();
        let buffered = r.buffered(&Data { rows: rows() }, 2).unwrap();
        assert_eq!(joined, buffered);
    }

    #[test]
    fn errors_before_and_after_the_verdict() {
        let r = Response::new(Envelope::kaivrpc(), None, &[]);
        let e = RpcError::new(602, "InvalidParams", "ids is empty");

        let early = r.error(&e).unwrap();
        assert!(early.contains("!str'::status=error\n"), "{early}");
        assert!(early.contains("602 InvalidParams: ids is empty"), "{early}");
        assert!(early.contains("!int'::n=0\n"), "{early}");
        // No data schema is declared when there is no data.
        assert!(!early.contains("/data"), "{early}");

        // Mid-stream: the verdict already said ok, so the reason
        // rides the tail.
        let late = r.fail_late(&e, 7).unwrap();
        assert!(late.starts_with("!str'::error=602 "), "{late}");
        assert!(late.ends_with("!int'::n=7\n"), "{late}");
    }

    #[test]
    fn a_deployment_can_name_its_own_envelope_schemas() {
        let r = Response::new(
            Envelope::with_schemas("acme/rpc/head", "acme/rpc/tail"),
            None,
            &[],
        );
        let doc = r.buffered(&Data { rows: vec![] }, 0).unwrap();
        assert!(doc.contains(".!schema:acme/rpc/head\n"), "{doc}");
        assert!(doc.contains(".!schema:acme/rpc/tail\n"), "{doc}");
    }
}