network-infra-utility 0.3.0 → 0.6.0

data/service/ssh/ext/ssh_core_rs/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "ssh_core_rs"
+version = "1.0.0"
+edition = "2021"
+description = "Rust SSH core engine — IPC-compatible replacement for Erlang ssh_core"
+
+[[bin]]
+name = "ssh_core_rs"
+path = "src/main.rs"
+
+[dependencies]
+# 禁用默认特性（aws-lc-rs 需要 NASM/C11），改用 ring（纯 Rust 加密后端）
+# 不启用 async-trait：russh 0.61 的 Handler trait 使用原生 AFIT（impl Future），
+# 启用 async-trait 会导致 impl 与 trait 的生命周期签名不匹配（E0195）
+russh = { version = "0.61", default-features = false, features = ["ring", "rsa", "flate2"] }
+tokio = { version = "1", features = ["full"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+base64 = "0.22"
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+thiserror = "1"
+dashmap = "6"
+rand = "0.8"
+sha2 = "0.10"
+russh-sftp = "2.4.0"
+
+[profile.release]
+opt-level = 3
+lto = true

data/service/ssh/ext/ssh_core_rs/bin/ssh_core_rs

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# ssh_core_rs engine launcher for Linux/macOS
+# Starts the Rust SSH core engine in foreground mode.
+# Called by Ruby Client.spawn_engine via Process.spawn.
+#
+# This is the Rust-based replacement for the Erlang ssh_core engine.
+# It implements the exact same IPC protocol, so Ruby can switch between
+# the two backends by changing the engine_binary_path in client.rb.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SRC_DIR="$(dirname "$SCRIPT_DIR")"
+
+# Delete stale endpoint file so Ruby can detect fresh startup
+ENDPOINT_FILE="/tmp/ssh_core_$(id -u).endpoint"
+rm -f "$ENDPOINT_FILE"
+
+# Check if pre-built binary exists
+BINARY="$SRC_DIR/target/release/ssh_core_rs"
+if [ -f "$BINARY" ]; then
+    exec "$BINARY"
+fi
+
+# Build if not yet compiled
+echo "Building ssh_core_rs (release)..." >&2
+if ! command -v cargo &> /dev/null; then
+    echo "Error: cargo not found in PATH. Please install Rust toolchain." >&2
+    exit 1
+fi
+cargo build --release --manifest-path "$SRC_DIR/Cargo.toml"
+
+# Run the engine in foreground (blocks until shutdown)
+exec "$BINARY"

data/service/ssh/ext/ssh_core_rs/bin/ssh_core_rs.cmd

@@ -0,0 +1,40 @@
+@echo off
+REM ssh_core_rs engine launcher for Windows
+REM Starts the Rust SSH core engine in foreground mode.
+REM Called by Ruby Client.spawn_engine via Process.spawn.
+REM
+REM This is the Rust-based replacement for the Erlang ssh_core engine.
+REM It implements the exact same IPC protocol, so Ruby can switch between
+REM the two backends by changing the engine_binary_path in client.rb.
+
+setlocal
+
+set SCRIPT_DIR=%~dp0
+set SRC_DIR=%SCRIPT_DIR%..
+
+REM Delete stale endpoint file so Ruby can detect fresh startup
+set EP_FILE=%TEMP%\ssh_core_%USERNAME%.endpoint
+if exist "%EP_FILE%" del "%EP_FILE%"
+
+REM Check if pre-built binary exists
+set BINARY=%SRC_DIR%\target\release\ssh_core_rs.exe
+if exist "%BINARY%" goto :run
+
+REM Build if not yet compiled
+echo Building ssh_core_rs (release)...
+where cargo >nul 2>nul
+if %ERRORLEVEL% neq 0 (
+    echo Error: cargo not found in PATH. Please install Rust toolchain.
+    exit /b 1
+)
+cargo build --release --manifest-path "%SRC_DIR%\Cargo.toml"
+if %ERRORLEVEL% neq 0 (
+    echo Error: cargo build failed.
+    exit /b 1
+)
+
+:run
+REM Run the engine in foreground (blocks until shutdown)
+"%BINARY%"
+
+endlocal

data/service/ssh/ext/ssh_core_rs/src/channel.rs

@@ -0,0 +1,296 @@
+//! 通道管理器 — 管理所有 SSH 通道的打开、发送、关闭和窗口变更。
+//! 对应 Erlang 端的 ssh_channel_stm.erl。
+//!
+//! 核心职责：
+//!   - channel.open：打开 shell/exec/subsystem 通道，请求 PTY，返回 channel_id
+//!   - channel.send：Base64 解码后向通道发送数据
+//!   - channel.close：关闭通道
+//!   - channel.window_change：变更 PTY 窗口大小
+//!   - 通过 handler 的 ConnShared 注册数据接收器，推送 channel.data / channel.eof
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use russh::Channel;
+use russh::client;
+use serde_json::{json, Value};
+use tokio::sync::{mpsc, RwLock};
+use tracing::debug;
+
+use crate::codec;
+use crate::coalesce::Coalescer;
+use crate::conn::ConnManager;
+use crate::handler::{ChannelData, ConnShared};
+use crate::proto;
+
+/// 通道管理器
+pub struct ChannelManager {
+    /// IPC channel_id → 通道状态
+    channels: RwLock<HashMap<String, ChannelEntry>>,
+    /// 连接管理器引用
+    conn_mgr: Arc<ConnManager>,
+    /// coalesce 引用（用于数据推送）
+    coalesce: Arc<Coalescer>,
+}
+
+/// 单个通道的状态
+struct ChannelEntry {
+    conn_id: String,
+    russh_ch_id: russh::ChannelId,
+    /// 通道对象（通过 Arc<Mutex> 保护，可 clone Arc）
+    channel: Arc<tokio::sync::Mutex<Channel<client::Msg>>>,
+    /// 数据接收任务 handle
+    data_task: tokio::sync::Mutex<Option<tokio::task::JoinHandle<()>>>,
+}
+
+impl ChannelManager {
+    pub fn new(conn_mgr: Arc<ConnManager>, coalesce: Arc<Coalescer>) -> Arc<Self> {
+        Arc::new(Self {
+            channels: RwLock::new(HashMap::new()),
+            conn_mgr,
+            coalesce,
+        })
+    }
+
+    /// RPC: channel.open
+    pub async fn rpc_open(&self, params: Value) -> Result<Value, String> {
+        let conn_id = proto::get_str(&params, "conn_id")
+            .ok_or("missing conn_id")?
+            .to_string();
+        let ch_type = proto::get_str(&params, "type").unwrap_or("shell");
+        let cols = proto::get_num(&params, "cols").unwrap_or(80.0) as u32;
+        let rows = proto::get_num(&params, "rows").unwrap_or(24.0) as u32;
+        let term_type = proto::get_str(&params, "term").unwrap_or("xterm-256color");
+        let command = proto::get_str(&params, "command");
+
+        // 获取连接的 handle 和 shared
+        let (handle, shared) = self
+            .conn_mgr
+            .get_handle_and_shared(&conn_id)
+            .await
+            .ok_or("conn_not_found")?;
+
+        // 打开 session 通道
+        let channel = handle
+            .channel_open_session()
+            .await
+            .map_err(|e| format!("channel_open_failed: {}", e))?;
+
+        let russh_ch_id = channel.id();
+        let ipc_ch_id = codec::gen_channel_id(&conn_id);
+
+        // 根据类型初始化通道
+        match ch_type {
+            "shell" => {
+                // 请求 PTY
+                channel
+                    .request_pty(true, term_type, cols, rows, 0, 0, &[])
+                    .await
+                    .map_err(|e| format!("pty_request_failed: {}", e))?;
+                // 请求 shell
+                channel
+                    .request_shell(true)
+                    .await
+                    .map_err(|e| format!("shell_request_failed: {}", e))?;
+            }
+            "exec" => {
+                let cmd = command.ok_or("missing command for exec")?;
+                channel
+                    .exec(true, cmd)
+                    .await
+                    .map_err(|e| format!("exec_failed: {}", e))?;
+            }
+            "subsystem" => {
+                let subsystem = command.ok_or("missing subsystem name")?;
+                channel
+                    .request_subsystem(true, subsystem)
+                    .await
+                    .map_err(|e| format!("subsystem_failed: {}", e))?;
+            }
+            _ => return Err(format!("unsupported_channel_type: {}", ch_type)),
+        }
+
+        // 注册数据接收器到 ConnShared（handler 的 data 回调会通过此 tx 推送数据）
+        let (data_tx, data_rx) = mpsc::unbounded_channel::<ChannelData>();
+        shared.register_channel_tx(russh_ch_id, data_tx).await;
+
+        // 启动数据接收循环（从 handler 转发的数据推送到 coalesce / IPC）
+        let coalesce = Arc::clone(&self.coalesce);
+        let ipc_ch_id_clone = ipc_ch_id.clone();
+        let conn_id_clone = conn_id.clone();
+        let shared_clone = Arc::clone(&shared);
+        let russh_id_for_close = russh_ch_id;
+        let data_task = tokio::spawn(async move {
+            Self::data_receive_loop(
+                data_rx,
+                coalesce,
+                ipc_ch_id_clone,
+                conn_id_clone,
+                shared_clone,
+                russh_id_for_close,
+            )
+            .await;
+        });
+
+        // 保存通道状态
+        let entry = ChannelEntry {
+            conn_id: conn_id.clone(),
+            russh_ch_id,
+            channel: Arc::new(tokio::sync::Mutex::new(channel)),
+            data_task: tokio::sync::Mutex::new(Some(data_task)),
+        };
+        self.channels
+            .write()
+            .await
+            .insert(ipc_ch_id.clone(), entry);
+
+        debug!(
+            "channel.open: conn={} ipc_ch={} russh_ch={} type={}",
+            conn_id, ipc_ch_id, russh_ch_id, ch_type
+        );
+
+        Ok(json!({
+            "channel_id": ipc_ch_id
+        }))
+    }
+
+    /// RPC: channel.send
+    pub async fn rpc_send(&self, params: Value) -> Result<Value, String> {
+        let ch_id = proto::get_str(&params, "id")
+            .ok_or("missing id")?
+            .to_string();
+        let b64_data = proto::get_str(&params, "data")
+            .ok_or("missing data")?;
+
+        let data = codec::decode_b64(b64_data).map_err(|e| format!("base64_decode_failed: {}", e))?;
+
+        let channel_arc = {
+            let channels = self.channels.read().await;
+            channels
+                .get(&ch_id)
+                .map(|e| Arc::clone(&e.channel))
+                .ok_or("channel_not_found")?
+        };
+
+        // 通过 russh Channel 发送数据
+        let ch = channel_arc.lock().await;
+        ch.data(data.as_slice())
+            .await
+            .map_err(|e| format!("send_failed: {}", e))?;
+
+        debug!("channel.send: ch={} bytes={}", ch_id, data.len());
+        Ok(json!({"ok": true}))
+    }
+
+    /// RPC: channel.close
+    pub async fn rpc_close(&self, params: Value) -> Result<Value, String> {
+        let ch_id = proto::get_str(&params, "id")
+            .ok_or("missing id")?
+            .to_string();
+
+        let entry = self.channels.write().await.remove(&ch_id);
+        match entry {
+            Some(e) => {
+                // 关闭 russh 通道
+                {
+                    let ch = e.channel.lock().await;
+                    let _ = ch.close().await;
+                }
+
+                // 注销数据接收器
+                // 获取 shared 来注销——需要通过 conn_mgr
+                if let Some((_handle, shared)) = self.conn_mgr.get_handle_and_shared(&e.conn_id).await {
+                    shared.unregister_channel_tx(e.russh_ch_id).await;
+                }
+
+                // 取消数据接收任务
+                if let Some(task) = e.data_task.lock().await.take() {
+                    task.abort();
+                }
+
+                debug!("channel.close: ch={}", ch_id);
+                Ok(json!({"ok": true}))
+            }
+            None => Err("channel_not_found".to_string()),
+        }
+    }
+
+    /// RPC: channel.window_change
+    pub async fn rpc_window_change(&self, params: Value) -> Result<Value, String> {
+        let ch_id = proto::get_str(&params, "id")
+            .ok_or("missing id")?
+            .to_string();
+        let cols = proto::get_num(&params, "cols").unwrap_or(80.0) as u32;
+        let rows = proto::get_num(&params, "rows").unwrap_or(24.0) as u32;
+
+        let channel_arc = {
+            let channels = self.channels.read().await;
+            channels
+                .get(&ch_id)
+                .map(|e| Arc::clone(&e.channel))
+                .ok_or("channel_not_found")?
+        };
+
+        let ch = channel_arc.lock().await;
+        ch.window_change(cols as u32, rows as u32, 0, 0)
+            .await
+            .map_err(|e| format!("window_change_failed: {}", e))?;
+
+        debug!("channel.window_change: ch={} cols={} rows={}", ch_id, cols, rows);
+        Ok(json!({"ok": true}))
+    }
+
+    /// 数据接收循环：从 handler 转发的 ChannelData 推送到 coalesce / IPC
+    async fn data_receive_loop(
+        mut data_rx: mpsc::UnboundedReceiver<ChannelData>,
+        coalesce: Arc<Coalescer>,
+        ipc_ch_id: String,
+        conn_id: String,
+        shared: Arc<ConnShared>,
+        russh_ch_id: russh::ChannelId,
+    ) {
+        while let Some(data) = data_rx.recv().await {
+            match data {
+                ChannelData::Stdout { data } => {
+                    // 推送到 coalesce（批量合并推送）
+                    coalesce.enqueue(&ipc_ch_id, data).await;
+                }
+                ChannelData::Extended { data, ext } => {
+                    // 扩展数据（stderr）——直接推送，不走 coalesce
+                    let b64 = codec::encode_b64(&data);
+                    shared
+                        .gateway
+                        .push_event(
+                            "channel.extended_data",
+                            json!({
+                                "id": ipc_ch_id,
+                                "data": b64,
+                                "ext": ext
+                            }),
+                        )
+                        .await;
+                }
+                ChannelData::Eof { reason } => {
+                    // 推送 channel.eof
+                    shared
+                        .gateway
+                        .push_event(
+                            "channel.eof",
+                            json!({
+                                "id": ipc_ch_id,
+                                "reason": reason
+                            }),
+                        )
+                        .await;
+                    // 收到 EOF 后，先 flush coalesce 中该通道的剩余数据
+                    coalesce.flush_channel(&ipc_ch_id).await;
+                    break;
+                }
+            }
+        }
+
+        // 注销数据接收器
+        shared.unregister_channel_tx(russh_ch_id).await;
+        debug!("conn {} channel {} data receive loop ended", conn_id, ipc_ch_id);
+    }
+}

data/service/ssh/ext/ssh_core_rs/src/coalesce.rs

@@ -0,0 +1,143 @@
+//! 高频数据合并器 — 8ms tick 或 16KB watermark 刷新 batch。
+//! 对应 Erlang 端的 ssh_ipc_coalesce.erl。
+//!
+//! 核心设计（与 Erlang 端完全对齐）：
+//!   - 每个通道的数据通过 enqueue() 添加到 buffer
+//!   - 每 COALESCE_TICK_MS（8ms）定时刷出一个 channel.data.batch 推送
+//!   - 当 buffer 总大小达到 COALESCE_WATERMARK_BYTES（16KB）时立即刷新
+//!   - flush_channel() 用于通道关闭时单独 flush 该通道的剩余数据
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+use tokio::sync::Mutex;
+use tokio::time::{interval, Duration};
+use tracing::trace;
+
+use crate::codec;
+use crate::gateway::Gateway;
+
+/// 合并 tick 间隔（毫秒）
+const COALESCE_TICK_MS: u64 = 8;
+
+/// 合并 watermark（字节）
+const COALESCE_WATERMARK_BYTES: usize = 16 * 1024;
+
+/// 缓冲区中单个通道的数据
+struct ChannelBuffer {
+    /// 累积的数据块
+    data: Vec<u8>,
+}
+
+/// 合并器状态
+struct CoalesceState {
+    /// channel_id → buffer
+    buffer: HashMap<String, ChannelBuffer>,
+    /// 缓冲区总大小
+    total_size: usize,
+}
+
+/// 合并器
+pub struct Coalescer {
+    state: Mutex<CoalesceState>,
+    gateway: Arc<Gateway>,
+}
+
+impl Coalescer {
+    pub fn new(gateway: Arc<Gateway>) -> Arc<Self> {
+        Arc::new(Self {
+            state: Mutex::new(CoalesceState {
+                buffer: HashMap::new(),
+                total_size: 0,
+            }),
+            gateway,
+        })
+    }
+
+    /// 启动定时 flush 循环
+    pub fn start(self: &Arc<Self>) {
+        let this = Arc::clone(self);
+        tokio::spawn(async move {
+            let mut ticker = interval(Duration::from_millis(COALESCE_TICK_MS));
+            ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+
+            loop {
+                ticker.tick().await;
+                this.flush().await;
+            }
+        });
+    }
+
+    /// 入队数据（由 channel.rs 调用）
+    pub async fn enqueue(&self, channel_id: &str, data: Vec<u8>) {
+        let mut state = self.state.lock().await;
+
+        let entry = state
+            .buffer
+            .entry(channel_id.to_string())
+            .or_insert(ChannelBuffer { data: Vec::new() });
+        entry.data.extend_from_slice(&data);
+        state.total_size += data.len();
+
+        // 达到 watermark 立即 flush
+        if state.total_size >= COALESCE_WATERMARK_BYTES {
+            drop(state);
+            self.flush().await;
+        }
+    }
+
+    /// 刷出所有通道的累积数据为 channel.data.batch 推送
+    pub async fn flush(&self) {
+        let mut state = self.state.lock().await;
+        if state.buffer.is_empty() {
+            return;
+        }
+
+        // 取出 buffer
+        let buffer = std::mem::take(&mut state.buffer);
+        state.total_size = 0;
+        drop(state);
+
+        // 构建 batch items
+        let items: Vec<Value> = buffer
+            .into_iter()
+            .map(|(ch_id, buf)| {
+                let b64 = codec::encode_b64(&buf.data);
+                json!({
+                    "id": ch_id,
+                    "data": b64
+                })
+            })
+            .collect();
+
+        if !items.is_empty() {
+            trace!("coalesce flush: {} channels", items.len());
+            self.gateway
+                .push_batch(json!({ "items": items }))
+                .await;
+        }
+    }
+
+    /// 单独 flush 指定通道的剩余数据（通道关闭时调用）
+    pub async fn flush_channel(&self, channel_id: &str) {
+        let mut state = self.state.lock().await;
+
+        if let Some(buf) = state.buffer.remove(channel_id) {
+            state.total_size = state.total_size.saturating_sub(buf.data.len());
+
+            let b64 = codec::encode_b64(&buf.data);
+            drop(state);
+
+            // 单独推送该通道的数据
+            self.gateway
+                .push_batch(json!({
+                    "items": [{
+                        "id": channel_id,
+                        "data": b64
+                    }]
+                }))
+                .await;
+        }
+    }
+}

data/service/ssh/ext/ssh_core_rs/src/codec.rs

@@ -0,0 +1,71 @@
+//! 编解码工具：Base64、ID 生成、SHA-256 指纹。
+//! 对应 Erlang 端的 ssh_codec.erl。
+
+use base64::Engine;
+use rand::RngCore;
+use sha2::{Digest, Sha256};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// 当前 Unix 时间戳（毫秒）
+pub fn unix_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}
+
+/// Base64 编码
+pub fn encode_b64(data: &[u8]) -> String {
+    base64::engine::general_purpose::STANDARD.encode(data)
+}
+
+/// Base64 解码
+pub fn decode_b64(s: &str) -> Result<Vec<u8>, base64::DecodeError> {
+    base64::engine::general_purpose::STANDARD.decode(s)
+}
+
+/// 生成连接 ID: conn_<unix_ms>_<8hex>
+pub fn gen_conn_id() -> String {
+    let ts = unix_ms();
+    let mut buf = [0u8; 4];
+    rand::thread_rng().fill_bytes(&mut buf);
+    let rand_hex: String = buf.iter().map(|b| format!("{:02x}", b)).collect();
+    format!("conn_{}_{}", ts, rand_hex)
+}
+
+/// 生成通道 ID: ch_<conn_short>_<seq>
+pub fn gen_channel_id(conn_id: &str) -> String {
+    let conn_short: String = conn_id.chars().take(16).collect();
+    let seq = unix_ms() % 100_000;
+    format!("ch_{}_{}", conn_short, seq)
+}
+
+/// 生成 SFTP 会话 ID: sftp_<conn_short>_<ts>
+pub fn gen_sftp_id(conn_id: &str) -> String {
+    let conn_short: String = conn_id.chars().take(16).collect();
+    let ts = unix_ms();
+    format!("sftp_{}_{}", conn_short, ts)
+}
+
+/// 生成端口转发规则 ID: fwd_<conn_short>_<seq>
+pub fn gen_rule_id(conn_id: &str) -> String {
+    let conn_short: String = conn_id.chars().take(16).collect();
+    let ts = unix_ms();
+    format!("fwd_{}_{}", conn_short, ts)
+}
+
+/// 计算公钥的 SHA-256 指纹（OpenSSH 格式）。
+/// 输入为公钥的 DER 编码字节。
+pub fn fingerprint(public_key_der: &[u8]) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(public_key_der);
+    let hash = hasher.finalize();
+    format!("SHA256:{}", encode_b64(&hash))
+}
+
+/// 生成认证 Token（32 字节随机数 Base64 编码）
+pub fn gen_auth_token() -> String {
+    let mut buf = [0u8; 32];
+    rand::thread_rng().fill_bytes(&mut buf);
+    encode_b64(&buf)
+}