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 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
// Copyright 2018 Peter Williams <peter@newton.cx>
// Licensed under the MIT License.
#![deny(missing_docs)]
#![doc(html_root_url = "https://docs.rs/stund_protocol/0.1.4")]
//! The stund client-server communication protocol.
//!
//! [Stund](https://github.com/pkgw/stund) is a simple daemon for maintaining
//! SSH tunnels. This crate defines the communication protocol used between
//! the CLI client and the daemon that acts as the parent to SSH processes.
//!
//! The protocol only has a handful of commands at the moment. These are
//! defined in this main module. The [`client`] submodule implements the
//! client protocol.
extern crate bytes;
extern crate dirs;
#[macro_use] extern crate failure;
#[macro_use] extern crate futures;
extern crate libc;
extern crate serde;
#[macro_use] extern crate serde_derive;
#[macro_use] extern crate state_machine_future;
extern crate tokio_codec;
extern crate tokio_core;
extern crate tokio_io;
extern crate tokio_serde_bincode;
extern crate tokio_uds;
use failure::Error;
use std::path::PathBuf;
pub mod codecs;
pub mod client;
/// Get the path to the Unix domain socket used for client/server communication.
///
/// At the moment, this is fixed to `$HOME/.ssh/stund.sock`.
pub fn get_socket_path() -> Result<PathBuf, Error> {
let mut p = dirs::home_dir().ok_or(format_err!("unable to determine your home directory"))?;
p.push(".ssh");
p.push("stund.sock");
Ok(p)
}
/// A message that the client may send to the server.
///
/// Some messages are only allowed in certain contexts.
#[derive(Debug, Deserialize, PartialEq, Serialize)]
pub enum ClientMessage {
/// Open an SSH tunnel.
Open(OpenParameters),
/// User input to be sent to SSH.
UserData(Vec<u8>),
/// Close an existing tunnel.
Close(CloseParameters),
/// Ask the daemon about its status.
QueryStatus,
/// Tell the daemon to exit.
Exit,
/// End the session.
Goodbye,
}
/// A message that the server may send to the client.
#[derive(Debug, Deserialize, PartialEq, Serialize)]
pub enum ServerMessage {
/// Generic message indicating success with whatever the client was asking
/// for.
Ok,
/// Generic message indicating an error with whatever the client was
/// asking for.
Error(String),
/// Output from an SSH process to be reported to the user by the client.
SshData(Vec<u8>),
/// In response to an `Open` message, indicates that this tunnel is
/// already open.
TunnelAlreadyOpen,
/// In response to a `Close` message, indicates that no such tunnel was
/// open.
TunnelNotOpen,
/// In response to a `QueryStatus` message, information about the server
/// status.
StatusResponse(StatusInformation),
}
/// Parameters to the "Open" command.
///
/// This command takes only a single parameter. The model of `stund` is that
/// configuration of details like usernames should be done via the
/// `$HOME/.ssh/config` file, and so are not needed here.
#[derive(Debug, Deserialize, PartialEq, Serialize)]
pub struct OpenParameters {
/// The hostname to which to connect.
pub host: String,
}
/// Possible outcomes of the "Open" command.
///
/// Besides these outcomes, an error may be signal by the return of a textual
/// error message.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum OpenResult {
/// Indicates that the tunnel was successfully opened.
Success,
/// Indicates that nothing was done because a tunnel to the specified
/// host was already open.
AlreadyOpen,
}
/// Parameters to the "Close" command.
#[derive(Debug, Deserialize, PartialEq, Serialize)]
pub struct CloseParameters {
/// The hostname of the connection to be closed.
pub host: String,
}
/// Possible outcomes of the "Close" command.
///
/// Besides these outcomes, an error may be signal by the return of a textual
/// error message.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CloseResult {
/// Indicates that the tunnel was successfully opened.
Success,
/// Indicates that nothing was done because no tunnel to the specified
/// host was open.
NotOpen,
}
/// Information about the current status of the server.
#[derive(Debug, Deserialize, PartialEq, Serialize)]
pub struct StatusInformation {
/// A list of information about the tunnels that have been opened during
/// this server’s lifetime.
///
/// This list includes tunnels that have been closed, but not any tunnels
/// opened from any previous invocations of the server.
pub tunnels: Vec<TunnelInformation>,
}
/// Information about a single tunnel opened by the server.
#[derive(Debug, Deserialize, PartialEq, Serialize)]
pub struct TunnelInformation {
/// The hostname associated with the connection.
pub host: String,
/// The current state of the SSH tunnel.
pub state: TunnelState,
}
/// The state of a single tunnel opened by the server.
#[derive(Debug, Deserialize, PartialEq, Serialize)]
pub enum TunnelState {
/// The tunnel is currently opene.
Open,
/// The tunnel was opened but then was manually closed.
Closed,
/// The tunnel was opened but died unexpectedly.
///
/// This may be due to something like a connection drop or the user
/// killing the associated SSH process outside of the server’s knowledge.
Died,
}