breakmancer 0.9.0

Drop a breakpoint into any shell.
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

//! Abstraction layer over pluggable transports.
//!
//! This uses enums rather than `Box<dyn ...>` because the latter is
//! not particularly compatible with a *set* of related traits. (The
//! generics or associated types turn into a nightmare to abstract over.)

use tcp::{TcpClient, TcpConnectParams, TcpServer, TcpTransport};
use wormhole::{WormholeCaller, WormholeListener, WormholeTransport};

use crate::protocol::ControllerId;

/// The controller's side of the transport, listening and ready for a
/// connection.
pub enum TransportListener {
    Tcp(TcpServer),
    Wormhole(WormholeListener),
}

impl TransportListener {
    /// English string describing the listening action, for logging.
    pub fn describe_listening(&self) -> String {
        match self {
            Self::Tcp(tcp) => tcp.describe_listening(),
            Self::Wormhole(w) => w.describe_listening(),
        }
    }

    /// Wait for a connection.
    pub async fn accept_connection(&mut self) -> Result<Transport, String> {
        match self {
            Self::Tcp(tcp) => tcp.accept_connection().await.map(Transport::Tcp),
            Self::Wormhole(w) => w.accept_connection().await.map(Transport::Wormhole),
        }
    }
}

/// The breakpoint's side of the transport, able to create new
/// outbound connections.
pub enum TransportCaller {
    Tcp(TcpClient),
    Wormhole(WormholeCaller),
}

impl TransportCaller {
    /// Initiate a connection.
    pub async fn new_connection(&self) -> Result<Transport, String> {
        match self {
            Self::Tcp(tcp) => tcp.new_connection().await.map(Transport::Tcp),
            Self::Wormhole(w) => w.new_connection().await.map(Transport::Wormhole),
        }
    }
}

/// An active connection for some transport mechanism.
///
/// Should close itself gracefully when dropped.
#[allow(clippy::large_enum_variant)]
pub enum Transport {
    Tcp(TcpTransport),
    Wormhole(WormholeTransport),
}

impl Transport {
    /// Send a raw message frame.
    pub async fn send_raw(&mut self, raw: &[u8]) -> Result<(), String> {
        match self {
            Self::Tcp(tcp) => tcp.send_raw(raw).await,
            Self::Wormhole(w) => w.send_raw(raw).await,
        }
    }

    /// Receive a raw message frame.
    ///
    /// Ok(None) signals that the connection has closed, although this
    /// may not be returned by all implementations.
    pub async fn receive_raw(&mut self) -> Result<Option<Vec<u8>>, String> {
        match self {
            Self::Tcp(tcp) => tcp.receive_raw().await,
            Self::Wormhole(w) => w.receive_raw().await,
        }
    }
}

/// Connection parameters.
#[derive(Clone, Debug)]
pub enum ConnectMethod {
    Tcp(TcpConnectParams),
    Wormhole,
}

impl ConnectMethod {
    /// Create a listener. Some transports may start network activity at this point.
    pub async fn new_listener(
        &self,
        controller_id: &ControllerId,
    ) -> Result<TransportListener, String> {
        let listener = match self {
            Self::Tcp(params) => TransportListener::Tcp(TcpServer::listen(params).await?),
            Self::Wormhole => TransportListener::Wormhole(WormholeListener::new(controller_id)),
        };
        Ok(listener)
    }

    /// Create a caller. Some transports may start network activity at this point.
    pub fn new_caller(&self, controller_id: &ControllerId) -> TransportCaller {
        match self {
            Self::Tcp(params) => TransportCaller::Tcp(TcpClient::new(&params.callback_addr)),
            Self::Wormhole => TransportCaller::Wormhole(WormholeCaller::new(controller_id)),
        }
    }
}

pub mod tcp;
pub mod wormhole;