thrall 0.0.15

thrall: the foot — a tool-execution client for a yog server
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//! The preface: what this end states, and every way a peer can fail to agree.

use super::{PROTOCOL, confirm, state};
use crate::channel::Failure;
use crate::channel::frame;
use serde_json::{Value, json};

/// The bytes a peer stating `protocol` would put on the wire.
fn stated(v: &Value) -> Vec<u8> {
    let mut wire = Vec::new();
    frame::write_value(&mut wire, v).expect("write");
    wire
}

/// What this end writes is one frame carrying one key.
#[test]
fn this_end_states_one_integer_in_one_frame() {
    let mut wire = Vec::new();
    state(&mut wire).expect("state");
    let mut read = wire.as_slice();
    assert_eq!(
        frame::read_value(&mut read).expect("read"),
        Some(json!({ "protocol": PROTOCOL })),
    );
    assert_eq!(
        frame::read_value(&mut read).ok(),
        None,
        "the preface is one frame and nothing follows it here"
    );
}

/// An engine speaking this version is admitted, and says nothing about it.
///
/// It states the number the way the far end states it — `corpus::PROTOCOL`, a
/// literal copied from yog — rather than the pin this file is about, so the two
/// have different sources here as they do on the wire.
#[test]
fn an_engine_of_this_version_is_confirmed() {
    let wire = stated(&json!({ "protocol": crate::corpus::PROTOCOL }));
    assert_eq!(confirm(&mut wire.as_slice()), Ok(()));
}

/// A mismatch names BOTH versions and the remedy. That is the requirement, not
/// a nicety: the sentence is the upgrade prompt, so a number an operator can
/// act on has to be in it.
///
/// **And it is a [`Failure::Skew`]**, which is the half that decides a
/// lifetime: a version the two ends do not share is a fact about the two
/// binaries, so every later dial buys the same handshake and the same sentence
/// (bl-5d62).
#[test]
fn a_mismatch_names_both_versions_and_the_remedy() {
    let wire = stated(&json!({ "protocol": 99 }));
    let Failure::Skew(refusal) = confirm(&mut wire.as_slice()).expect_err("refused") else {
        panic!("a stated version this end does not speak is not the wire");
    };
    assert!(
        refusal.contains(&format!("version {PROTOCOL}")),
        "{refusal}"
    );
    assert!(refusal.contains("engine speaks 99"), "{refusal}");
    assert!(refusal.contains("upgrade the older component"), "{refusal}");
    assert!(
        !refusal.contains("negotiat") || refusal.contains("no negotiation"),
        "the refusal must not offer a negotiation: {refusal}"
    );
}

/// Three ways to state nothing in a frame that DID arrive — an unversioned
/// build writing a gesture envelope where a preface belongs, a frame that is
/// not an object, and the key carrying something that is not an integer. All
/// three are one sentence, and all three are skew: the peer deliberately wrote
/// what it wrote, and it will write it again next time.
#[test]
fn a_preface_that_arrived_and_states_nothing_is_skew() {
    let arrived = [
        stated(&json!({"op": "advertise"})),
        stated(&json!(["not an object"])),
        stated(&json!({"protocol": "one"})),
    ];
    for wire in arrived {
        let Failure::Skew(refusal) = confirm(&mut wire.as_slice()).expect_err("refused") else {
            panic!("a frame the peer wrote is not the wire");
        };
        assert!(
            refusal.contains("the engine speaks no version"),
            "{refusal}"
        );
    }
}

/// **A preface that never arrived is the WIRE**, and that is the one place this
/// end parts from REMOTE §3's own collapsing of the two cases (bl-5d62). The
/// engine refuses a peer of the wrong version and a peer that hung up
/// mid-preface with one sentence, because it can serve neither. A foot is
/// asking a different question — whether dialling again could help — and there
/// they part: an engine restarting under a foot's dial says nothing at all, and
/// a foot that took that as final would exit on the blip that a redial exists
/// for.
#[test]
fn a_preface_that_never_arrived_is_the_wire() {
    let Failure::Wire(refusal) = confirm(&mut [].as_slice()).expect_err("refused") else {
        panic!("a peer that hung up mid-preface is not a version this end cannot speak");
    };
    assert!(
        refusal.contains("the engine speaks no version"),
        "the sentence is the same sentence: {refusal}"
    );
}