haematite-cli 0.33.0

//! Studio's verbs and head follows, carried to their store: its socket, or
//! its network endpoint over verified TLS (HAEMNET-003 R1), with the same
//! frames either way.
//!
//! The session's Lys pass is presented first (ACCESS-002 R2); a branch's
//! head is followed the same way, the store pushing each change
//! ([`follow`]).
//!
//! Each verb is one connection: hello, then `session.pass` with the
//! session's pass, then the verb. A pass the store refuses ends the request
//! there and the verb is never sent. A door with no lys block presents no
//! pass: hello, then the verb (ACCESS-003 R3). The store's hello says
//! whether it is served through Lys, and a door whose sign-in differs from
//! it refuses the verb by name before sending it: `door_store_needs_lys`
//! for a Lys-served store behind a door with no lys block, and
//! `door_store_without_lys` for a store with no Lys behind a door with one.
//! A hello that says neither, from a store older than ACCESS-003, is carried
//! as before. `hello` touches no resource, so it is
//! answered with the store's own hello. `session.pass` belongs to the door,
//! so a browser can never present a pass of its own.

use std::time::Duration;

use serde_json::value::RawValue;
use serde_json::{Value, json};

use crate::client::{Address, Client, Ended, Refusal, Reply};
use crate::serve::pass::now;

/// What a carried verb came to.
#[derive(Debug)]
pub enum Carried {
    /// The bytes the store sent for `result`.
    Answered(Box<RawValue>),
    /// The store's refusal, or the door's for a verb it keeps to itself.
    Refused(Refusal),
}

/// What a session presents to its store before a verb.
#[derive(Debug, Clone, Copy)]
pub enum Presenting<'a> {
    /// The session's Lys pass, sent as `session.pass`.
    Pass(&'a str),
    /// Nothing: the person at the keyboard of a door with no lys block,
    /// whom a store with no Lys records as its own local owner.
    Local,
}

/// Carry `method` with `params` to the store at `store`, presenting
/// `token` first, each step bounded by `timeout`.
///
/// # Errors
///
/// [`Ended`] as the client names it: nothing asked, or, from the verb's
/// sending on, an outcome that is not known.
pub fn carry(
    store: &Address,
    timeout: Duration,
    token: &str,
    method: &str,
    params: Option<&RawValue>,
) -> Result<Carried, Ended> {
    carry_as(store, "", timeout, Presenting::Pass(token), method, params)
}

/// Carry `method` with `params` to store `name` at `store`, presenting
/// `presenting` first, each step bounded by `timeout`.
///
/// # Errors
///
/// As [`carry`].
pub fn carry_as(
    store: &Address,
    name: &str,
    timeout: Duration,
    presenting: Presenting<'_>,
    method: &str,
    params: Option<&RawValue>,
) -> Result<Carried, Ended> {
    if method == "session.pass" {
        return Ok(Carried::Refused(Refusal {
            code: "invalid_operation".to_owned(),
            message: "session.pass is the door's own and is never carried".to_owned(),
            path: None,
            // The door refuses this itself; no store sent a receipt.
            verified: None,
        }));
    }
    let mut client = Client::reach(store, timeout)?;
    if method == "hello" {
        return Ok(Carried::Answered(client.hello().to_owned()));
    }
    if let Some(refusal) = mismatch(client.hello(), name, presenting) {
        return Ok(Carried::Refused(refusal));
    }
    if let Presenting::Pass(token) = presenting {
        let pass = serde_json::value::to_raw_value(&json!({ "pass": token }))
            .map_err(|error| Ended::NotAsked(format!("the pass could not be written: {error}")))?;
        if let Reply::Refused(refusal) = client.call("session.pass", Some(&pass))? {
            return Ok(Carried::Refused(refusal));
        }
    }
    Ok(match client.call(method, params)? {
        Reply::Answered(answer) => Carried::Answered(answer),
        Reply::Refused(refusal) => Carried::Refused(refusal),
    })
}

/// What asking a store to follow a branch's head came to.
pub enum Followed {
    /// The store took the follow and sent the head it starts from.
    Following(Following),
    /// The store refused the session's pass or the follow.
    Refused(Refusal),
}

/// A follow a store took: the first head it sent, and the connection every
/// later frame arrives on.
pub struct Following {
    /// The bytes the store sent for the first head's `result`.
    pub first: Box<RawValue>,
    client: Client,
    /// When the presented pass expires, in seconds since the epoch, as the
    /// store answered `session.pass`.
    expires: Option<u64>,
    timeout: Duration,
}

impl Following {
    /// The store's next frame of the follow: a head, or the refusal that
    /// ends it. The store sends a frame only when the head moves, so the
    /// read waits as long as that takes, bounded by the pass's expiry and
    /// `timeout` past it: the store ends every follow at that expiry, so a
    /// read still waiting then means a store that stopped answering. With no
    /// expiry known the read is unbounded.
    ///
    /// # Errors
    ///
    /// [`Ended`] as the client names it when no frame could be read.
    pub fn next_frame(&mut self) -> Result<Reply, Ended> {
        self.client.next_reply()
    }

    pub(super) fn disconnect_handle(&self) -> std::io::Result<crate::client::network::Hangup> {
        self.client.follow_socket()
    }

    /// Bound every later read by the pass's expiry and `timeout` past it,
    /// set once when the follow starts. A store that has already closed the
    /// connection refuses the bound on some systems (macOS answers EINVAL);
    /// what it sent before closing is still read, and the read itself then
    /// names the closed connection, so that refusal is not the follow's end.
    fn bound_reads(&self) {
        let bound = self.expires.map(|expires| {
            let left = Duration::from_secs(expires.saturating_sub(now()));
            left.saturating_add(self.timeout)
        });
        if let Err(ended) = self.client.read_within(bound) {
            eprintln!("haematite door: a follow's read bound was not set: {ended}");
        }
    }
}

/// Ask the store at `store` to follow `branch`'s head, presenting `token`
/// first, each step up to the first head bounded by `timeout`.
///
/// # Errors
///
/// [`Ended`] as the client names it. A follow changes nothing, so an
/// unknown outcome only means no head was read.
pub fn follow(
    store: &Address,
    timeout: Duration,
    token: &str,
    branch: &str,
) -> Result<Followed, Ended> {
    follow_as(store, "", timeout, Presenting::Pass(token), branch)
}

/// Ask store `name` at `store` to follow `branch`'s head, presenting `presenting` first.
///
/// Each step up to the first head is bounded by `timeout`. With no pass
/// there is no expiry, and later reads wait until the head moves or the
/// store ends the follow.
///
/// # Errors
///
/// As [`follow`].
pub fn follow_as(
    store: &Address,
    name: &str,
    timeout: Duration,
    presenting: Presenting<'_>,
    branch: &str,
) -> Result<Followed, Ended> {
    let mut client = Client::reach(store, timeout)?;
    if let Some(refusal) = mismatch(client.hello(), name, presenting) {
        return Ok(Followed::Refused(refusal));
    }
    let expires = match presenting {
        Presenting::Pass(token) => {
            let pass = raw(&json!({ "pass": token }))?;
            match client.call("session.pass", Some(&pass))? {
                Reply::Refused(refusal) => return Ok(Followed::Refused(refusal)),
                Reply::Answered(answer) => expiry(&answer),
            }
        }
        Presenting::Local => None,
    };
    let params = raw(&json!({ "branch": branch }))?;
    Ok(match client.call("head.follow", Some(&params))? {
        Reply::Answered(first) => {
            let following = Following {
                first,
                client,
                expires,
                timeout,
            };
            following.bound_reads();
            Followed::Following(following)
        }
        Reply::Refused(refusal) => Followed::Refused(refusal),
    })
}

/// The door's refusal when the store's hello and the door's sign-in differ
/// on Lys, before any verb is sent; `None` when they agree, or when the
/// hello does not say.
fn mismatch(hello: &RawValue, name: &str, presenting: Presenting<'_>) -> Option<Refusal> {
    let through_lys = serde_json::from_str::<Value>(hello.get())
        .ok()?
        .get("lys")?
        .as_bool()?;
    let store = if name.is_empty() {
        "this store".to_owned()
    } else {
        format!("store {name}")
    };
    let (code, message) = match (presenting, through_lys) {
        (Presenting::Local, true) => (
            "door_store_needs_lys",
            format!(
                "{store} is served through Lys, and this door has no lys block, so it signs nobody in through Lys; add a lys block to the door to reach it"
            ),
        ),
        (Presenting::Pass(_), false) => (
            "door_store_without_lys",
            format!(
                "{store} is not served through Lys, and this door signs people in through Lys and carries their pass; serve the store with a [lys] block, or run the door with no lys block"
            ),
        ),
        _ => return None,
    };
    Some(Refusal {
        code: code.to_owned(),
        message,
        path: None,
        // The door refuses this itself; no store sent a receipt.
        verified: None,
    })
}

fn raw(value: &Value) -> Result<Box<RawValue>, Ended> {
    serde_json::value::to_raw_value(value)
        .map_err(|error| Ended::NotAsked(format!("the request could not be written: {error}")))
}

/// The expiry, in seconds since the epoch, a store answered `session.pass`
/// with: `{holder, expires}`.
fn expiry(answer: &RawValue) -> Option<u64> {
    let answer: Value = serde_json::from_str(answer.get()).ok()?;
    answer.get("expires")?.as_u64()
}

#[cfg(test)]
#[path = "forward_tests.rs"]
mod tests;