HTTP API: episodes

The input of episodes.attach: which piece of work this connection is carrying.

The identity is the only field, and an unknown one is refused rather than ignored, so a client that sends a peer id under another name learns it at once:

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");

The answer of episodes.attach: the episode the connection now holds, whether it was resumed rather than opened, and how long it outlives a lost connection.

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}");
}

One episode: what the client calls itself, which connection holds it now, and what the repository did about it.

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"));

Where an episode stands: held by a live connection, or waiting for its client to come back. There is no closed state, because a closed episode leaves the board; what survives it is the repository's own record.

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\"");

The input of episodes.detach: the episode to close.

Empty is a valid input, meaning the episode the calling connection holds; over an interface with no connection that input is refused, since there is nothing to take "this one's episode" from.

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");

The answer of episodes.detach: the episode as it was closed, no longer held by any connection, with what the repository's end event reported.

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"]));

The answer of episodes.list: every episode this server holds, counted by state, and the one the caller holds. In memory only — it is the association between live connections and the repository's records, which stops being true when the process stops.

The two counts partition the list, and mine is left out of the JSON rather than written as null when the caller holds nothing, which is always so over plain HTTP:

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());