tube 0.0.2

This crate was renamed to 'tubez'. Please use that crate instead.
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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

use std::collections::HashMap;

pub(in super) const CLIENT_HAS_FINISHED_SENDING_FRAMETYPE: u8 = 0x0;
pub(in super) const DRAIN_FRAMETYPE: u8 = 0x1;
pub(in super) const NEWTUBE_FRAMETYPE: u8 = 0x2;
pub(in super) const PAYLOAD_FRAMETYPE: u8 = 0x3;
pub(in super) const PAYLOAD_ACK_FRAMETYPE: u8 = 0x4;
pub(in super) const SERVER_HAS_FINISHED_SENDING_FRAMETYPE: u8 = 0x5;
pub(in super) const ABORT_FRAMETYPE: u8 = 0x6;

/**
 * Each encoded Tube frame specifies its own structure, but all frames begin 
 * with the following header structure:
 *
 *   +-----------------+----------------------------+
 *   |  FrameType(u8)  |  FrameBodyByteLength(u16)  |
 *   +-----------------+----------------------------+
 *
 * The FrameType value indicates how the frame's body should be parsed, and the 
 * FrameBodyByteLength value indicates the number of bytes the frame's body 
 * occupies. 
 *
 * FrameBodyByteLength only specifies the size of the frame's body, it does not 
 * account for the 3 bytes used in the frame's header structure.
 */
#[derive(Clone,Debug,PartialEq)]
pub enum AbortReason {
    ApplicationAbort,
    ApplicationError,
    TransportErrorWhileSynchronizingTubeState,
    Unknown,
}
impl From<u8> for AbortReason {
    fn from(reason: u8) -> Self {
        match reason {
            0x0 => AbortReason::ApplicationAbort,
            0x1 => AbortReason::ApplicationError,
            0x2 => AbortReason::TransportErrorWhileSynchronizingTubeState,
            _   => AbortReason::Unknown,
        }
    }
}
impl Into<u8> for AbortReason {
    fn into(self) -> u8 {
        match self {
            AbortReason::ApplicationAbort                          => 0x00,
            AbortReason::ApplicationError                          => 0x01,
            AbortReason::TransportErrorWhileSynchronizingTubeState => 0x02,
            AbortReason::Unknown                                   => 0xFF,
        }
    }
}

#[derive(Clone,Debug,PartialEq)]
pub enum Frame {
    /**
     * This frame is sent by the client when it will send no further Payload 
     * frames for a given Tube.
     *
     *   +---------------+
     *   |  TubeId(u16)  |
     *   +---------------+
     */
    ClientHasFinishedSending {
        tube_id: u16,
    },

    /**
     * This frame is sent to both peers as a signal that a TubeTransport 
     * needs to be drained (AKA gracefully shutdown). It is up to the 
     * application running on each peer to use this signal to coordinate the 
     * graceful shutdown of all Tubes hosted by the TubeTransport this 
     * frame arrived on.
     */
    Drain,

    /**
     * This frame is sent by either peer to indicate the creation of a new 
     * Tube. Client-generated Tubes always use an odd-numbered id, and 
     * Server-generated Tubes always use an even-numbered id.
     *
     *   +---------------+-----------------------------+
     *   |  TubeId(u16)  |  Utf8EncodedJSONHeaders(*)  |
     *   +---------------+-----------------------------+
     */
    NewTube {
        tube_id: u16,
        headers: HashMap<String, String>,
    },

    /**
     * This frame is sent by either peer to transmit data.
     *
     *   +---------------+-------------------+-------------+-----------+
     *   |  TubeId(u16)  |  AckRequested(1)  |  AckId(15)  |  Data(*)  |
     *   +---------------+-------------------+-------------+-----------+
     */
    Payload {
        tube_id: u16,
        ack_id: Option<u16>,
        data: Vec<u8>,
    },

    /**
     * This frame is sent by either peer when it receives a Payload frame that 
     * specifies an ack_id. Note that receipt of a PayloadAck frame only means 
     * the other peer received a Payload, it does not necessarily mean that the 
     * application successfully processed the payload.
     *
     *   +---------------+---------------+-------------+
     *   |  TubeId(u16)  |  RESERVED(1)  |  AckId(15)  |
     *   +---------------+---------------+-------------+
     */
    PayloadAck {
        tube_id: u16,
        ack_id: u16,
    },

    /**
     * This frame is sent by the server when it will send no further Payload 
     * frames for a given Tube.
     *
     *   +---------------+
     *   |  TubeId(u16)  |
     *   +---------------+
     */
    ServerHasFinishedSending {
        tube_id: u16,
    },

    /**
     * This frame is sent by either peer in order to immediately end the Tube, 
     * no waiting for both peers to agree by sending their respective 
     * HasFinishedSending frame.
     *
     *   +-----------------------------------+
     *   |  TubeId(u16)  |  AbortReason(u8)  |
     *   +-----------------------------------+
     */
    Abort {
        tube_id: u16,
        reason: AbortReason,
    },
}