From cf7752f3715de4eda83c7191c8f662c29c227a8d Mon Sep 17 00:00:00 2001 From: Eugene Date: Sun, 4 Feb 2024 21:40:43 +0100 Subject: [PATCH] clean up module docs --- russh/src/client/mod.rs | 49 ++--------------------- russh/src/server/mod.rs | 89 ++--------------------------------------- 2 files changed, 7 insertions(+), 131 deletions(-) diff --git a/russh/src/client/mod.rs b/russh/src/client/mod.rs index 4838e9fb..8216fa84 100644 --- a/russh/src/client/mod.rs +++ b/russh/src/client/mod.rs @@ -26,52 +26,11 @@ //! The [Session](client::Session) is passed to the [Handler](client::Handler) //! when the client receives data. //! -//! ```no_run -//! use async_trait::async_trait; -//! use std::sync::Arc; -//! use russh::*; -//! use russh::server::{Auth, Session}; -//! use russh_keys::*; -//! use futures::Future; -//! use std::io::Read; +//! Check out the following examples: //! -//! struct Client { -//! } -//! -//! #[async_trait] -//! impl client::Handler for Client { -//! type Error = anyhow::Error; -//! -//! async fn check_server_key(self, server_public_key: &key::PublicKey) -> Result<(Self, bool), Self::Error> { -//! println!("check_server_key: {:?}", server_public_key); -//! Ok((self, true)) -//! } -//! -//! async fn data(self, channel: ChannelId, data: &[u8], session: client::Session) -> Result<(Self, client::Session), Self::Error> { -//! println!("data on channel {:?}: {:?}", channel, std::str::from_utf8(data)); -//! Ok((self, session)) -//! } -//! } -//! -//! #[tokio::main] -//! async fn main() { -//! let config = russh::client::Config::default(); -//! let config = Arc::new(config); -//! let sh = Client{}; -//! -//! let key = russh_keys::key::KeyPair::generate_ed25519().unwrap(); -//! let mut agent = russh_keys::agent::client::AgentClient::connect_env().await.unwrap(); -//! agent.add_identity(&key, &[]).await.unwrap(); -//! let mut session = russh::client::connect(config, ("127.0.0.1", 22), sh).await.unwrap(); -//! if session.authenticate_future(std::env::var("USER").unwrap_or("user".to_owned()), key.clone_public_key().unwrap(), agent).await.1.unwrap() { -//! let mut channel = session.channel_open_session().await.unwrap(); -//! channel.data(&b"Hello, world!"[..]).await.unwrap(); -//! if let Some(msg) = channel.wait().await { -//! println!("{:?}", msg) -//! } -//! } -//! } -//! ``` +//! * [Client that connects to a server, runs a command and prints its output](https://github.com/warp-tech/russh/blob/main/russh/examples/client_exec_simple.rs) +//! * [Client that connects to a server, runs a command in a PTY and provides interactive input/output](https://github.com/warp-tech/russh/blob/main/russh/examples/client_exec_interactive.rs) +//! * [SFTP client (with `russh-sftp`)](https://github.com/warp-tech/russh/blob/main/russh/examples/sftp_client.rs) //! //! [Session]: client::Session diff --git a/russh/src/server/mod.rs b/russh/src/server/mod.rs index 49f6f439..9f7aebaa 100644 --- a/russh/src/server/mod.rs +++ b/russh/src/server/mod.rs @@ -22,93 +22,10 @@ //! In both cases, you'll first need to implement the [Handler](server::Handler) trait - //! this is where you'll handle various events. //! -//! Here is an example server, which forwards input from each client -//! to all other clients: +//! Check out the following examples: //! -//! ``` -//! use async_trait::async_trait; -//! use std::sync::{Mutex, Arc}; -//! use russh::*; -//! use russh::server::{Auth, Session, Msg}; -//! use russh_keys::*; -//! use std::collections::HashMap; -//! use futures::Future; -//! -//! #[tokio::main] -//! async fn main() { -//! let client_key = russh_keys::key::KeyPair::generate_ed25519().unwrap(); -//! let client_pubkey = Arc::new(client_key.clone_public_key().unwrap()); -//! let mut config = russh::server::Config::default(); -//! config.inactivity_timeout = Some(std::time::Duration::from_secs(3)); -//! config.auth_rejection_time = std::time::Duration::from_secs(3); -//! config.keys.push(russh_keys::key::KeyPair::generate_ed25519().unwrap()); -//! let config = Arc::new(config); -//! let sh = Server{ -//! client_pubkey, -//! clients: Arc::new(Mutex::new(HashMap::new())), -//! id: 0 -//! }; -//! tokio::time::timeout( -//! std::time::Duration::from_secs(1), -//! russh::server::run(config, ("0.0.0.0", 2222), sh) -//! ).await.unwrap_or(Ok(())); -//! } -//! -//! #[derive(Clone)] -//! struct Server { -//! client_pubkey: Arc, -//! clients: Arc>>>, -//! id: usize, -//! } -//! -//! impl server::Server for Server { -//! type Handler = Self; -//! fn new_client(&mut self, _: Option) -> Self { -//! let s = self.clone(); -//! self.id += 1; -//! s -//! } -//! } -//! -//! #[async_trait] -//! impl server::Handler for Server { -//! type Error = anyhow::Error; -//! -//! async fn channel_open_session(self, channel: Channel, session: Session) -> Result<(Self, bool, Session), Self::Error> { -//! { -//! let mut clients = self.clients.lock().unwrap(); -//! clients.insert((self.id, channel.id()), channel); -//! } -//! Ok((self, true, session)) -//! } -//! async fn auth_publickey(self, _: &str, _: &key::PublicKey) -> Result<(Self, Auth), Self::Error> { -//! Ok((self, server::Auth::Accept)) -//! } -//! async fn data(self, channel: ChannelId, data: &[u8], mut session: Session) -> Result<(Self, Session), Self::Error> { -//! { -//! let mut clients = self.clients.lock().unwrap(); -//! for ((id, _channel_id), ref mut channel) in clients.iter_mut() { -//! channel.data(data); -//! } -//! } -//! Ok((self, session)) -//! } -//! } -//! ``` -//! -//! Note the call to `session.handle()`, which allows to keep a handle -//! to a client outside the event loop. This feature is internally -//! implemented using `futures::sync::mpsc` channels. -//! -//! Note that this is just a toy server. In particular: -//! -//! - It doesn't handle errors when `s.data` returns an error, i.e. when the -//! client has disappeared -//! -//! - Each new connection increments the `id` field. Even though we -//! would need a lot of connections per second for a very long time to -//! saturate it, there are probably better ways to handle this to -//! avoid collisions. +//! * [Server that forwards your input to all connected clients](https://github.com/warp-tech/russh/blob/main/russh/examples/echoserver.rs) +//! * [Server handing channel processing off to a library (here, `russh-sftp`)](https://github.com/warp-tech/russh/blob/main/russh/examples/sftp_server.rs) use std; use std::collections::HashMap;