HTTP API: episodes

Vstup episodes.attach: který kus práce toto připojení nese.

Identita je jediné pole a neznámé je odmítnuto místo ignorováno, takže klient, který pošle peer id pod jiným názvem, se to dozví hned:

use majordomus_cli::capability::builtin::episodes::AttachInput;
let input: AttachInput = serde_json::from_str(r#"{"external_id":"conv-42"}"#).unwrap();
assert_eq!(input.external_id, "conv-42");
assert!(serde_json::from_str::<AttachInput>(r#"{"external_id":"x","peer":"p1"}"#).is_err());
assert!(serde_json::from_str::<AttachInput>("{}").is_err(), "the identity is required");

Odpověď episodes.attach: epizoda, kterou spojení nyní drží, zda byla obnovena místo otevřena a jak dlouho přežije ztrátu spojení.

use majordomus_cli::capability::builtin::episodes::Attached;
let schema = serde_json::to_value(schemars::schema_for!(Attached)).unwrap();
for field in ["episode", "resumed", "reattach_grace_seconds"] {
    assert!(schema["required"].as_array().unwrap().iter().any(|f| f == field), "{field}");
}

Jedna epizoda: jak se klient nazývá, které spojení ji nyní drží a co s ní repozitář udělal.

use majordomus_cli::episodes::{ConnectionEpisode, EpisodeBoard};
use majordomus_cli::peers::{PeerBoard, Transport};
let peer = PeerBoard::new().attach(Transport::Http);
let (episode, _) = EpisodeBoard::new().attach(&peer, "conv-42", "generic");
let episode: ConnectionEpisode = episode;
assert_eq!((episode.external_id.as_str(), episode.provider.as_str()), ("conv-42", "generic"));
assert_eq!(episode.peer.as_ref(), Some(&peer));
// never empty: a board with no repository behind it says so
assert!(episode.repository.contains("without a driver"));

V jakém stavu epizoda je: držená živým připojením, nebo čekající, až se její klient vrátí. Uzavřený stav neexistuje, protože uzavřená epizoda z nástěnky mizí; co ji přežije, je vlastní záznam repozitáře.

use majordomus_cli::episodes::{ConnectionEpisodeState, EpisodeBoard};
use majordomus_cli::peers::{PeerBoard, Transport};
let peer = PeerBoard::new().attach(Transport::Stdio);
let board = EpisodeBoard::new();
assert_eq!(board.attach(&peer, "w", "generic").0.state, ConnectionEpisodeState::Open);
assert_eq!(board.detach(&peer)[0].state, ConnectionEpisodeState::Detached);
assert_eq!(serde_json::to_string(&ConnectionEpisodeState::Detached).unwrap(), "\"detached\"");

Vstup episodes.detach: epizoda k uzavření.

Prázdný je platný vstup a znamená epizodu, kterou drží volající spojení; přes rozhraní bez spojení se tento vstup odmítne, protože není odkud „epizodu tohoto spojení“ vzít.

use majordomus_cli::capability::builtin::episodes::DetachInput;
let mine: DetachInput = serde_json::from_str("{}").unwrap();
assert!(mine.external_id.is_none());
let named: DetachInput = serde_json::from_str(r#"{"external_id":"conv-42"}"#).unwrap();
assert_eq!(named.external_id.as_deref(), Some("conv-42"));
assert_eq!(serde_json::to_string(&mine).unwrap(), "{}", "an omitted id is not written as null");

Odpověď episodes.detach: epizoda tak, jak byla uzavřena, už ji nedrží žádné spojení, s tím, co ohlásila koncová událost repozitáře.

use majordomus_cli::capability::builtin::episodes::Detached;
let schema = serde_json::to_value(schemars::schema_for!(Detached)).unwrap();
assert_eq!(schema["required"], serde_json::json!(["episode"]));

Odpověď episodes.list: každá epizoda, kterou tento server drží, spočítaná podle stavu, a ta, kterou drží volající. Pouze v paměti — je to asociace mezi živými spojeními a záznamy repozitáře, která přestane platit, když se proces zastaví.

Oba počty rozdělují seznam a mine se z JSON vynechá, místo aby se zapsalo jako null, když volající nedrží nic, což je přes prosté HTTP vždy:

use majordomus_cli::capability::builtin::episodes::EpisodeList;
let none = EpisodeList { open: 0, detached: 0, episodes: vec![], mine: None };
let json = serde_json::to_value(&none).unwrap();
assert_eq!(json, serde_json::json!({"open": 0, "detached": 0, "episodes": []}));
let back: EpisodeList = serde_json::from_value(json).unwrap();
assert_eq!(back.open + back.detached, back.episodes.len());