network-infra-utility 0.2.0 → 0.5.0

data/service/ssh/lib/network_infra_utility/ssh/client.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "timeout"
+
+require_relative "ipc/transport"
+require_relative "ipc/router"
+require_relative "ipc/coalesce"
+require_relative "ipc/errors"
+require_relative "session/manager"
+require_relative "security/vault"
+require_relative "security/host_key"
+require_relative "config/settings"
+require_relative "config/schema"
+require_relative "config/store"
+
+module NetworkInfraUtility
+  module SSH
+    # SSH 客户端主入口：管理引擎生命周期与模块协调。
+    #
+    # 用法：
+    #   client = SSH::Client.new
+    #   client.start_engine
+    #   session = client.connect(host: "10.0.0.1", user: "admin")
+    #   terminal = session.open_terminal
+    #   terminal.puts("show version")
+    class Client
+      PROTOCOL_VER = "1.0"
+      ENGINE_STARTUP_TIMEOUT = 10 # 秒
+      # 默认引擎后端：:rust 或 :erlang
+      DEFAULT_BACKEND = :rust
+      # 引擎进程退出检测轮询间隔（秒）
+      ENGINE_WATCH_INTERVAL = 2
+
+      attr_reader :ipc, :sessions, :vault, :settings, :coalesce, :host_key, :backend
+
+      def initialize(config_dir: nil, backend: nil)
+        @settings = Config::Settings.new(config_dir)
+        @vault = Security::Vault.new(@settings.master_password)
+        @host_key = Security::HostKey.new(@settings.known_hosts_path)
+        @ipc = IPC::Router.new(IPC::Transport.new)
+        @sessions = Session::Manager.new(self)
+        @coalesce = nil
+        @engine_pid = nil
+        @engine_mutex = Mutex.new
+        @started = false
+        @backend = backend || DEFAULT_BACKEND
+        @engine_watcher = nil
+        @exit_callback = nil
+      end
+
+      # 设置引擎异常退出回调
+      # 回调签名: ->(reason) { }
+      # reason 为 :crashed（非零退出）或 :disconnected（IPC 连接断开）
+      def on_engine_exit(&block)
+        @exit_callback = block
+      end
+
+      # 启动 SSH 核心引擎，建立 IPC 连接。
+      def start_engine
+        @engine_mutex.synchronize do
+          raise "Engine already started" if @started
+
+          @engine_pid = spawn_engine
+          # 分离子进程但仍可 wait——Process.detach 返回一个线程，
+          # 如果子进程异常退出，线程能捕获退出码
+          @engine_watcher = Process.detach(@engine_pid)
+          endpoint, token = wait_for_endpoint
+          @ipc.connect(endpoint, auth_token: token, client_id: "ruby-#{Process.pid}")
+
+          # 注册 IPC 断连回调
+          @ipc.on_disconnect do |reason|
+            handle_engine_disconnect(reason)
+          end
+
+          # 注册反向 RPC：hostkey.resolve
+          register_reverse_handlers
+
+          # 初始化 coalesce（需在 hello 之后，获取服务端 capabilities）
+          @coalesce = IPC::Coalesce.new(@ipc)
+          @started = true
+
+          # 启动引擎退出监控线程
+          start_engine_monitor
+        end
+        self
+      end
+
+      # 发起 SSH 连接
+      # @param spec [Hash] 连接参数 {host, port, user, auth, jumps, ...}
+      # @return [Session::Session] 会话对象
+      def connect(spec)
+        ensure_started
+        # Vault 解析凭据引用，返回新 hash（不改入参）
+        resolved_spec = @vault.resolve_credentials(spec)
+        conn_resp = @ipc.call("conn.connect", resolved_spec, timeout_ms: 60_000)
+        @sessions.create(conn_resp[:conn_id], spec, conn_resp[:fingerprint])
+      rescue IPC::RPCError => e
+        raise ConnectionError, e.message
+      end
+
+      # 停止引擎，清理资源
+      def stop
+        @engine_mutex.synchronize do
+          return unless @started
+
+          @engine_monitor&.kill
+          @engine_monitor = nil
+          @sessions.disconnect_all
+          @ipc.call("bye", {}, timeout_ms: 5_000) rescue nil
+          @ipc.close
+          if @engine_pid
+            begin
+              Process.kill("TERM", @engine_pid)
+              # 等待最多 3 秒让引擎优雅退出
+              Timeout.timeout(3) { @engine_watcher&.join } if @engine_watcher
+            rescue => e
+              # 引擎可能已退出，忽略
+            rescue Timeout::Error
+              # 强制杀死
+              Process.kill("KILL", @engine_pid) rescue nil
+            end
+          end
+          @engine_pid = nil
+          @engine_watcher = nil
+          @started = false
+        end
+      end
+
+      # 引擎是否已启动
+      def started?
+        @started
+      end
+
+      private
+
+      def ensure_started
+        start_engine unless @started
+      end
+
+      # 引擎是否存活
+      def engine_alive?
+        return false unless @engine_pid
+        # Process.detach 返回的线程，如果已结束说明子进程已退出
+        return false if @engine_watcher&.join(0)
+        true
+      end
+
+      # 启动引擎退出监控线程
+      def start_engine_monitor
+        @engine_monitor = Thread.new do
+          loop do
+            sleep ENGINE_WATCH_INTERVAL
+            # 检查子进程是否已退出
+            if @engine_watcher&.join(0)
+              exit_status = @engine_watcher.value rescue nil
+              reason = if exit_status && exit_status != 0
+                         :crashed
+                       else
+                         :exited
+                       end
+              handle_engine_exit(reason)
+              break
+            end
+          end
+        rescue => e
+          # 监控线程异常，不中断主流程
+        end
+      end
+
+      # 引擎异常退出时的处理
+      def handle_engine_exit(reason)
+        @started = false
+        @sessions.disconnect_all
+        @exit_callback&.call(reason)
+      end
+
+      # IPC 连接断开时的处理
+      def handle_engine_disconnect(reason)
+        @started = false
+        @sessions.mark_all_disconnected
+        @exit_callback&.call(:disconnected)
+      end
+
+      # ----------------------------------------------------------------
+      # 以下为 private 方法（增强版修复后保留，旧版重复定义已移除）
+      # ----------------------------------------------------------------
+
+      private
+
+      def ensure_started
+        start_engine unless @started
+      end
+
+      # 拉起 Erlang 引擎子进程
+      def spawn_engine
+        binary = engine_binary_path
+        raise "Engine binary not found: #{binary}" unless File.exist?(binary)
+
+        log_dir = @settings.log_dir
+        FileUtils.mkdir_p(log_dir)
+        if Gem.win_platform?
+          # Windows: .cmd files must be invoked via cmd.exe
+          Process.spawn(
+            "cmd", "/c", binary,
+            { out: File.join(log_dir, "engine.log"),
+              err: File.join(log_dir, "engine.err") }
+          )
+        else
+          Process.spawn(
+            binary,
+            { out: File.join(log_dir, "engine.log"),
+              err: File.join(log_dir, "engine.err") }
+          )
+        end
+      end
+
+      # 等待 Erlang 引擎写入端点文件
+      def wait_for_endpoint
+        endpoint_file = @settings.engine_endpoint_file
+        deadline = Time.now + ENGINE_STARTUP_TIMEOUT
+        loop do
+          if File.exist?(endpoint_file)
+            content = File.read(endpoint_file).strip.split("\n")
+            return content[0], content[1]
+          end
+          raise "Erlang engine startup timeout" if Time.now > deadline
+
+          sleep 0.1
+        end
+      end
+
+      # 注册反向 RPC 处理器
+      def register_reverse_handlers
+        @ipc.on_reverse_rpc("hostkey.resolve") do |params|
+          @host_key.resolve(params[:host], params[:port], params[:fingerprint])
+        end
+      end
+
+      def engine_binary_path
+        ext_dir = File.expand_path("../../../ext", __dir__)
+        base = case @backend
+               when :rust
+                 File.join(ext_dir, "ssh_core_rs", "bin", "ssh_core_rs")
+               else
+                 File.join(ext_dir, "ssh_core", "bin", "ssh_core")
+               end
+        Gem.win_platform? ? base + ".cmd" : base
+      end
+    end
+
+    class ConnectionError < StandardError; end
+    class AlreadyStarted < StandardError; end
+  end
+end

data/service/ssh/lib/network_infra_utility/ssh/config/schema.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module NetworkInfraUtility
+  module SSH
+    module Config
+      # 配置校验与版本迁移。
+      class SchemaError < StandardError; end
+
+      module Schema
+        SCHEMA_VERSION = 1
+
+        # 会话字段定义
+        SESSION_FIELDS = {
+          id: String, name: String, group: String, host: String, port: Integer,
+          user: String, tags: Array, auth: Hash, terminal: Hash,
+          keepalive: Hash, proxy: Hash, jumps: Array, port_forwards: Array,
+          macro: Hash, log: Hash, auto_reconnect: Hash,
+          algorithms: Hash, connect_timeout_ms: Integer
+        }.freeze
+
+        # 分组字段定义
+        GROUP_FIELDS = {
+          id: String, name: String, parent: String, collapsed: [TrueClass, FalseClass]
+        }.freeze
+
+        # @param doc [Hash] 加载的 YAML 文档
+        # @return [:ok] 校验通过
+        # @raise [SchemaError] 校验失败
+        def self.validate(doc)
+          raise SchemaError, "version mismatch" unless doc[:version] == SCHEMA_VERSION
+
+          (doc[:sessions] || []).each_with_index do |s, i|
+            validate_session(s, i)
+          end
+          (doc[:groups] || []).each_with_index do |g, i|
+            validate_group(g, i)
+          end
+          :ok
+        end
+
+        # 迁移旧版本到当前版本
+        def self.migrate(doc)
+          # V1.0 仅 v1，预留迁移接口
+          doc
+        end
+
+        class << self
+          private
+
+          def validate_session(session, index)
+            SESSION_FIELDS.each do |field, type|
+              val = session[field]
+              next if val.nil?
+
+              unless valid_type?(val, type)
+                raise SchemaError, "Session[#{index}] field '#{field}' type mismatch: expected #{type}, got #{val.class}"
+              end
+            end
+
+            raise SchemaError, "Session[#{index}] missing required host" unless session[:host]
+            raise SchemaError, "Session[#{index}] missing required user" unless session[:user]
+          end
+
+          def validate_group(group, index)
+            GROUP_FIELDS.each do |field, type|
+              val = group[field]
+              next if val.nil?
+
+              unless valid_type?(val, type)
+                raise SchemaError, "Group[#{index}] field '#{field}' type mismatch"
+              end
+            end
+          end
+
+          def valid_type?(val, type)
+            case type
+            when Array
+              # 数组类型：每个元素都是一个可接受类型（联合类型）
+              type.any? { |t| valid_type?(val, t) }
+            when Class
+              val.is_a?(type)
+            else
+              val.is_a?(type)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/service/ssh/lib/network_infra_utility/ssh/config/settings.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+require "tmpdir"
+
+module NetworkInfraUtility
+  module SSH
+    module Config
+      # 全局设置加载。
+      class Settings
+        DEFAULT_CONFIG_DIR = File.expand_path("~/.network-infra-utility")
+        DEFAULT_SETTINGS = {
+          master_password: nil,
+          log_dir: nil,
+          config_dir: DEFAULT_CONFIG_DIR,
+          default_terminal: "xterm-256color",
+          default_scrollback: 10_000,
+          default_keepalive_interval: 30,
+          default_theme: "dark"
+        }.freeze
+
+        attr_reader :config_dir, :data
+
+        def initialize(config_dir = nil)
+          @config_dir = config_dir || DEFAULT_CONFIG_DIR
+          @data = load_settings
+        end
+
+        def master_password
+          @data[:master_password]
+        end
+
+        def master_password=(pwd)
+          @data[:master_password] = pwd
+        end
+
+        def log_dir
+          @data[:log_dir] || File.join(@config_dir, "logs")
+        end
+
+        def sessions_path
+          File.join(@config_dir, "sessions.yml")
+        end
+
+        def vault_path
+          File.join(@config_dir, "vault.yml")
+        end
+
+        def known_hosts_path
+          File.join(@config_dir, "known_hosts.yml")
+        end
+
+        def settings_path
+          File.join(@config_dir, "settings.yml")
+        end
+
+        def engine_endpoint_file
+          uid = if Gem.win_platform?
+                   ENV["USERNAME"] || "default"
+                 else
+                   Process.uid.to_s
+                 end
+          File.join(Dir.tmpdir, "ssh_core_#{uid}.endpoint")
+        end
+
+        def default_terminal
+          @data[:default_terminal]
+        end
+
+        def default_scrollback
+          @data[:default_scrollback]
+        end
+
+        def default_keepalive_interval
+          @data[:default_keepalive_interval]
+        end
+
+        def default_theme
+          @data[:default_theme]
+        end
+
+        private
+
+        def windows?
+          RUBY_PLATFORM =~ /mswin|mingw|cygwin/
+        end
+
+        def load_settings
+          path = settings_path
+          defaults = DEFAULT_SETTINGS.merge(config_dir: @config_dir)
+
+          if File.exist?(path)
+            loaded = YAML.safe_load(File.read(path), symbolize_names: true) || {}
+            defaults.merge(loaded)
+          else
+            defaults
+          end
+        end
+      end
+    end
+  end
+end

data/service/ssh/lib/network_infra_utility/ssh/config/store.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require_relative "schema"
+
+module NetworkInfraUtility
+  module SSH
+    module Config
+      # 会话/分组/片段的统一持久化。
+      # 原子写：先写 .tmp 再 rename，防止崩溃导致配置损坏。
+      class Store
+        attr_reader :path, :doc
+
+        def initialize(path)
+          @path = path
+          @doc = load
+        end
+
+        def sessions
+          @doc[:sessions] || []
+        end
+
+        def groups
+          @doc[:groups] || []
+        end
+
+        def find_session(id)
+          sessions.find { |s| s[:id] == id }
+        end
+
+        def find_group(id)
+          groups.find { |g| g[:id] == id }
+        end
+
+        def add_session(session)
+          @doc[:sessions] ||= []
+          @doc[:sessions] << session
+          save
+        end
+
+        def update_session(id, updates)
+          session = find_session(id)
+          return unless session
+
+          session.merge!(updates)
+          save
+        end
+
+        def remove_session(id)
+          @doc[:sessions]&.delete_if { |s| s[:id] == id }
+          save
+        end
+
+        def add_group(group)
+          @doc[:groups] ||= []
+          @doc[:groups] << group
+          save
+        end
+
+        def remove_group(id)
+          @doc[:groups]&.delete_if { |g| g[:id] == id }
+          save
+        end
+
+        def save
+          tmp = "#{@path}.tmp"
+          FileUtils.mkdir_p(File.dirname(@path))
+          File.write(tmp, YAML.dump(@doc))
+          File.rename(tmp, @path)
+        end
+
+        def reload
+          @doc = load
+        end
+
+        private
+
+        def load
+          if File.exist?(@path)
+            raw = YAML.safe_load(File.read(@path), symbolize_names: true, permitted_classes: [Symbol]) || {}
+            Schema.migrate(raw)
+          else
+            { version: Schema::SCHEMA_VERSION, groups: [], sessions: [] }
+          end
+        end
+      end
+    end
+  end
+end

data/service/ssh/lib/network_infra_utility/ssh/ipc/coalesce.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "base64"
+require "thread"
+require_relative "router"
+
+module NetworkInfraUtility
+  module SSH
+    module IPC
+      # 推送消费端：批量消费 channel.data.batch，按 channel 路由到对应 Terminal。
+      # 修正 E9（背压）和 E8（订阅泄漏）。
+      class Coalesce
+        attr_reader :batch_enabled
+
+        def initialize(router)
+          @router = router
+          @terminals = {}              # [conn_id, ch_id] => Terminal::Emulator
+          @terminals_mutex = Mutex.new
+          @batch_enabled = router.server_capabilities&.include?("coalesce") || false
+          @sids = {}                   # [conn_id, ch_id] => subscription_id
+          setup_subscriptions
+        end
+
+        # 注册一个通道到终端的映射
+        def register_channel(conn_id, ch_id, terminal)
+          key = [conn_id, ch_id]
+          @terminals_mutex.synchronize { @terminals[key] = terminal }
+
+          # 降级模式：逐条 channel.data
+          unless @batch_enabled
+            sid = @router.subscribe("channel.data") do |p|
+              next unless p[:id] == ch_id
+
+              data = Base64.decode64(p[:data])
+              terminal.feed(data)
+            end
+            @sids[key] = sid
+          end
+        end
+
+        # 注销通道映射，清理订阅
+        def unregister_channel(conn_id, ch_id)
+          key = [conn_id, ch_id]
+          @terminals_mutex.synchronize { @terminals.delete(key) }
+
+          sid = @sids.delete(key)
+          @router.unsubscribe("channel.data", sid) if sid
+        end
+
+        # 查找终端（供 batch 分发用）
+        def find_terminal(conn_id, ch_id)
+          @terminals_mutex.synchronize { @terminals[[conn_id, ch_id]] }
+        end
+
+        private
+
+        def setup_subscriptions
+          return unless @batch_enabled
+
+          @router.subscribe("channel.data.batch") do |p|
+            items = p[:items] || []
+            items.each do |item|
+              # batch 中 item[:id] 是 channel_id，需与已注册的 channel 匹配
+              dispatch_batch_item(item[:id], item[:data])
+            end
+          end
+        end
+
+        def dispatch_batch_item(ch_id, b64_data)
+          data = Base64.decode64(b64_data)
+          @terminals_mutex.synchronize do
+            @terminals.each do |_key, terminal|
+              next unless terminal.channel_id == ch_id
+
+              terminal.feed(data)
+              break
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/service/ssh/lib/network_infra_utility/ssh/ipc/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module NetworkInfraUtility
+  module SSH
+    module IPC
+      # IPC 层异常基类
+      class Error < StandardError; end
+
+      # RPC 超时
+      class RPCTimeout < Error; end
+
+      # 远程返回的 JSON-RPC error 对象
+      class RPCError < Error
+        attr_reader :code, :data
+
+        def initialize(error_obj)
+          @code = error_obj[:code]
+          @data = error_obj[:data]
+          super(error_obj[:message] || "RPC error code=#{@code}")
+        end
+      end
+
+      # 连接尚未就绪时操作通道
+      class NotReady < Error; end
+
+      # 背压暂停时 send 被拒
+      class FlowPaused < Error; end
+
+      # IPC 连接断开
+      class ConnectionLost < Error; end
+
+      # 配置 Schema 版本不匹配
+      class SchemaMismatch < Error; end
+    end
+  end
+end