shell_tunnel/
lib.rs

1//! # shell-tunnel
2//!
3//! Ultra-lightweight remote shell gateway with a REST/WebSocket API.
4//!
5//! This crate provides a cross-platform API for programmatic interaction
6//! with system shells. A command is run by a fresh shell — `cmd /c` on
7//! Windows, `/bin/sh -c` elsewhere — and its output is captured through
8//! pipes; nothing here allocates a terminal.
9//!
10//! ## Features
11//!
12//! - **Cross-platform**: One API over the platform's shell
13//! - **Async I/O**: Non-blocking operations using tokio
14//! - **Session Management**: Stateful shell sessions with lifecycle tracking
15//! - **REST API**: HTTP endpoints for command execution
16//! - **WebSocket**: Real-time streaming of command output
17//! - **Lightweight**: Minimal dependencies, small binary size
18//!
19//! ## Quick Start
20//!
21//! ```no_run
22//! use std::sync::Arc;
23//! use shell_tunnel::{Command, CommandExecutor, SessionStore};
24//!
25//! #[tokio::main]
26//! async fn main() -> shell_tunnel::Result<()> {
27//!     // Initialize logging
28//!     shell_tunnel::logging::try_init().ok();
29//!
30//!     // Create a session store
31//!     let store = Arc::new(SessionStore::new());
32//!
33//!     // Create a new session
34//!     let session_id = store.create()?;
35//!
36//!     // Run a command in it — a fresh shell per call, nothing kept between
37//!     let executor = CommandExecutor::new(store);
38//!     let result = executor
39//!         .execute_in_session(&session_id, &Command::new("echo hello"))
40//!         .await?;
41//!
42//!     println!("Session {} exited with {:?}", session_id, result.exit_code);
43//!
44//!     Ok(())
45//! }
46//! ```
47//!
48//! ## API Server
49//!
50//! ```no_run
51//! use shell_tunnel::api::{ServerConfig, serve};
52//!
53//! #[tokio::main]
54//! async fn main() -> shell_tunnel::Result<()> {
55//!     shell_tunnel::logging::try_init().ok();
56//!     let config = ServerConfig::new("127.0.0.1", 3000);
57//!     serve(config).await
58//! }
59//! ```
60
61pub mod api;
62pub mod audit;
63pub mod cli;
64pub mod config;
65pub mod error;
66pub mod execution;
67#[cfg(any(feature = "tls", feature = "relay-client"))]
68pub mod fingerprint;
69pub mod fs;
70pub mod logging;
71pub mod output;
72mod process;
73pub mod relay;
74pub mod security;
75pub mod session;
76#[cfg(feature = "tls")]
77pub mod tls;
78pub mod tunnel;
79#[cfg(feature = "self-update")]
80pub mod update;
81
82// Re-export commonly used types
83pub use error::{Result, ShellTunnelError};
84pub use execution::{Command, CommandExecutor, ExecutionResult};
85pub use fs::{FsError, FsRoot};
86pub use output::{OutputSanitizer, VirtualScreen};
87pub use session::{Session, SessionContext, SessionId, SessionState, SessionStore};
88
89// Re-export API types
90pub use api::{AppState, ServerConfig};
91
92// Re-export security types
93pub use security::{
94    ApiKeyStore, AuthConfig, CapabilitySet, CommandValidator, RateLimiter, TokenRecord,
95    ValidationConfig,
96};
97
98// Re-export reachability types
99pub use relay::{RelayConfig, RelayState};
100pub use tunnel::{TunnelHandle, TunnelProvider};
101
102// Re-export CLI and config types
103pub use cli::{parse_args, print_help, print_version, Args};
104pub use config::{Config, ConfigError};
shell_tunnel/lib.rs

shell_tunnel/
lib.rs
