netstack 0.1.1 → 0.2.0

data/lib/netstack/connector/log/transcript.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    class Log
+
+      # 已渲染、已脱敏的字节按行变成事件，半行在上下文切换前收尾。
+      class Transcript
+        def initialize(&on_line)
+          @on_line = on_line
+          @buffer = +"".b
+        end
+
+        def write(bytes)
+          @buffer << bytes
+          while (ending = @buffer.index("\n"))
+            @on_line.call(@buffer.slice!(0, ending + 1).chomp)
+          end
+          bytes.bytesize
+        end
+
+        def flush; end
+
+        def finish
+          @on_line.call(@buffer) unless @buffer.empty?
+          @buffer = +"".b
+        end
+      end
+
+      private_constant :RedactingWriter, :Transcript
+    end
+  end
+end

data/lib/netstack/connector/log.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "fileutils"
+require "logger"
+require "securerandom"
+
+module Netstack
+  module Connector
+    # 单个设备会话的日志，按级别控制是否包含完整回显。
+    class Log
+      LEVELS = { debug: ::Logger::DEBUG, info: ::Logger::INFO,
+                 warn: ::Logger::WARN, error: ::Logger::ERROR }.freeze
+      CONTEXT_FIELDS = %w[host session_id operation command_id text source line].freeze
+      private_constant :CONTEXT_FIELDS
+
+      # 保存日志配置和敏感信息脱敏器。
+      def initialize(configuration, redactor:)
+        @configuration = configuration
+        @redactor = redactor
+        @context = {}.freeze
+      end
+
+      # 为会话打开日志文件或应用日志器。
+      def open(transport)
+        @transport = transport
+        @session_id = SecureRandom.hex(8).freeze
+        @command_sequence = 0
+        @io = open_file(@configuration.log_file) if @configuration.log_file
+        if @configuration.log_format == :raw
+          @writer = @output = RedactingWriter.new(@io, @redactor) if @io
+        elsif @io || @configuration.logger
+          @logger = @configuration.logger || ::Logger.new(@io, formatter: Formatter.new)
+          open_transcript if @io && @configuration.log_level == :debug
+        end
+      rescue => error
+        close_preserving_error
+        raise build_error("unable to open session log", error), cause: nil
+      end
+
+      # 上下文只在持有会话锁期间使用；收尾必须先于恢复父上下文。
+      def with_context(**fields)
+        previous = @context
+        failed = false
+        finish_output
+        @context = @context.merge(fields).freeze
+        yield
+      rescue Exception # rubocop:disable Lint/RescueException -- Preserve this body's failure, including interruption, during log cleanup.
+        failed = true
+        raise
+      ensure
+        begin
+          finish_output
+        rescue Error
+          raise unless failed
+        ensure
+          @context = previous
+        end
+      end
+
+      def with_operation_context(name, &)
+        with_context(operation: name || @context[:operation] || :script, &)
+      end
+
+      def with_command_context(command, &)
+        @command_sequence += 1
+        with_context(command_id: @command_sequence, phase: :command,
+                     text: command.sensitive? ? "[REDACTED]" : command.text,
+                     source: command.source, line: command.line, &)
+      end
+
+      # 将终端回显接入当前会话日志。
+      def attach
+        return unless @transport && @writer
+
+        @transport.log_output = self
+        @attached = true
+      end
+
+      # 判断当前日志级别是否需要完整设备回显。
+      def debug? = @configuration.log_level == :debug && (!!@writer || enabled?(:debug))
+
+      # 按日志级别写入已脱敏的业务事件。
+      def log_event(name, level: :info, **fields)
+        return unless @logger || @configuration.on_event
+
+        finish_output
+        write_event(name, level: level, **fields)
+      rescue Error
+        raise
+      rescue => error
+        raise build_error("unable to write session event", error), cause: nil
+      end
+
+      # 异常正文由会话先脱敏；类型、错误码和阶段只允许共享词表中的值进入日志。
+      def log_failure(name, failure, phase: nil, **fields)
+        log_event(name, level: :error, **fields,
+                  error: ErrorMetadata.type(failure.class.name) || "StandardError",
+                  code: ErrorMetadata.code(failure.code),
+                  phase: ErrorMetadata.phase(failure.phase) || ErrorMetadata.phase(phase),
+                  message: failure.message)
+      end
+
+      # 用户钩子可能把未登记的配置片段放进事件名、字段名或值；敏感范围统一隐藏。
+      def log_custom_event(name, level: :info, **fields)
+        if @redactor.sensitive?
+          log_event("custom", level: level, details: "[REDACTED]")
+        else
+          log_event(name, level: level, **fields)
+        end
+      end
+
+      # 登录完成并收集动态口令后，再记录已脱敏的认证回显。
+      def log_authentication_output(bytes)
+        return unless debug?
+
+        with_context(phase: :login) do
+          log_event("login_output", level: :debug)
+          if @writer
+            write(@redactor.call(bytes))
+            flush
+          else
+            log_response_output(bytes)
+          end
+        end
+      end
+
+      # 注入日志器与文件回显共用事件格式；两次脱敏覆盖终端控制符拼接。
+      def log_response_output(bytes)
+        return unless debug? && !@writer && !@redactor.output_sensitive?
+
+        @redactor.call(TerminalRenderer.render(@redactor.call(bytes))).each_line do |line|
+          write_event("device_output", level: :debug, output: line.chomp)
+        end
+      rescue Error
+        raise
+      rescue => error
+        raise build_error("unable to write device output", error), cause: nil
+      end
+
+      # 向终端日志写入已处理的回显字节。
+      def write(bytes)
+        return unless @writer && !@redactor.output_sensitive?
+
+        @writer.write(bytes)
+      rescue Error
+        raise
+      rescue => error
+        raise build_error("unable to write session log", error), cause: nil
+      end
+
+      # 刷新日志缓冲区。
+      def flush
+        @writer&.flush
+        @io&.flush
+      rescue Error
+        raise
+      rescue => error
+        raise build_error("unable to flush session log", error), cause: nil
+      end
+
+      # 执行代码块期间暂停自动记录传输回显。
+      def pause
+        finish_output
+        @transport.log_output = nil if @transport
+        yield
+      ensure
+        @transport.log_output = self if @transport && @writer && @attached
+      end
+
+      # 断开回显记录并关闭日志资源。
+      def close
+        begin
+          @transport.log_output = nil if @transport
+          finish_output
+        ensure
+          begin
+            @io&.close
+          ensure
+            @writer = @output = @transcript = @logger = @io = @transport = @session_id = nil
+            @attached = false
+          end
+        end
+      rescue Error
+        raise
+      rescue => error
+        raise build_error("unable to close session log", error), cause: nil
+      end
+
+      private
+
+      # 每次读取调用方的当前阈值，不缓存级别、不改写共享 Logger。
+      def enabled?(level)
+        LEVELS.fetch(level) >= LEVELS.fetch(@configuration.log_level) &&
+          (@configuration.on_event || (@logger && LEVELS.fetch(level) >= @logger.level))
+      end
+
+      def write_event(name, level:, **fields)
+        return unless enabled?(level)
+
+        values = @context.compact.merge(fields.reject { |key, _| CONTEXT_FIELDS.include?(key.to_s) })
+        values = values.merge(host: @configuration.host, session_id: @session_id)
+        event = Event.new(name, values, redactor: @redactor)
+        @logger.public_send(level, event) if @logger && LEVELS.fetch(level) >= @logger.level
+        @configuration.on_event&.call(event)
+      end
+
+      def open_transcript
+        @transcript = Transcript.new { |line| write_event("device_output", level: :debug, output: line) }
+        @output = RedactingWriter.new(@transcript, @redactor)
+        @writer = TerminalRenderer.new(@output, max_line_bytes: @configuration.max_output_bytes)
+      end
+
+      # 先渲染，再结束过滤流，最后发出半行事件；顺序不能反转。
+      def finish_output
+        @writer.finish if @writer.respond_to?(:finish)
+        @output&.finish unless @output.equal?(@writer)
+        @transcript&.finish
+      rescue Error
+        raise
+      rescue => error
+        raise build_error("unable to finish session output", error), cause: nil
+      end
+
+      # 非阻塞打开后检查同一文件描述符，拒绝 FIFO 等特殊文件，避免连接前无限等待。
+      # 仅常规文件可配置私有权限并接收设备日志。
+      def open_file(path)
+        FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+        file = File.open(path, File::WRONLY | File::CREAT | File::APPEND | File::NOFOLLOW | File::NONBLOCK, 0o600)
+        begin
+          raise IOError, "session log must be a regular file" unless file.stat.file?
+
+          file.chmod(0o600)
+          file.binmode
+          file.write("\n") if file.size.positive? && @configuration.log_format == :text
+          file
+        rescue Exception # rubocop:disable Lint/RescueException -- Release partially configured files on interrupts too.
+          begin
+            file.close
+          rescue
+            # 保留设置失败的原始原因。
+          end
+          raise
+        end
+      end
+
+      # 在日志打开失败后尽力释放资源。
+      def close_preserving_error
+        close
+      rescue
+        nil
+      end
+
+      # 将日志异常包装成统一错误并保留脱敏原因。
+      def build_error(message, error)
+        LogError.new(message, phase: :logging,
+                     underlying: UnderlyingError.new(error, @redactor, sensitive: @redactor.sensitive?))
+      end
+    end
+  end
+end

data/lib/netstack/connector/log_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    class LogError < Error; end
+  end
+end

data/lib/netstack/connector/login_timeout.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    class LoginTimeout < AuthenticationError; end
+  end
+end

data/lib/netstack/connector/output_limit_exceeded.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    class OutputLimitExceeded < Error; end
+  end
+end

data/lib/netstack/connector/parsing_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    class ParsingError < Error; end
+  end
+end

data/lib/netstack/connector/profile/builder.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    class Profile
+      # 构造器把声明块中的领域语言转换为设备档案字段。
+      class Builder
+        # 保存继承值并提供 commands、prompts 等有限的声明入口。
+        def initialize(parent)
+          @values = parent.to_h
+        end
+
+        # 声明运行配置和保存配置命令。
+        def commands(&definition)
+          validate_block!(:commands, definition)
+          commands = Commands.new(
+            @values[:config_commands], @values[:save_commands]
+          )
+          commands.instance_eval(&definition)
+          @values[:config_commands] = commands.config_commands
+          @values[:save_commands] = commands.save_commands
+          self
+        end
+
+        # 声明登录、命令、凭据和提权提示符。
+        def prompts(&definition)
+          validate_block!(:prompts, definition)
+          Prompts.new(@values).instance_eval(&definition)
+          self
+        end
+
+        # 声明分页模式及自动翻页响应。
+        def pager(&definition)
+          validate_block!(:pager, definition)
+          Pager.new(@values).instance_eval(&definition)
+          self
+        end
+
+        # 声明认证失败和命令失败的输出模式。
+        def errors(&definition)
+          validate_block!(:errors, definition)
+          Errors.new(@values).instance_eval(&definition)
+          self
+        end
+
+        # 声明登录挑战和命令确认交互。
+        def interactions(&definition)
+          validate_block!(:interactions, definition)
+          interactions = Interactions.new(@values)
+          interactions.instance_eval(&definition)
+          @values[:login_interactions] = interactions.login_interactions
+          @values[:confirmation_interactions] = interactions.confirmation_interactions
+          self
+        end
+
+        # 声明进入特权模式所需的命令和提示符。
+        def privilege(&definition)
+          validate_block!(:privilege, definition)
+          Privilege.new(@values).instance_eval(&definition)
+          self
+        end
+
+        # 声明旧版 SSH 协商参数。
+        def ssh(&definition)
+          validate_block!(:ssh, definition)
+          Ssh.new(@values).instance_eval(&definition)
+          self
+        end
+
+        # 设置设备命令的默认超时秒数。
+        def command_timeout(seconds)
+          @values[:command_timeout] = seconds
+          self
+        end
+
+        # 设置避免设备自动换行的终端宽高。
+        def terminal_size(width, height = nil)
+          @values[:terminal_size] = height.nil? ? width : [width, height]
+          self
+        end
+
+        # 绑定已加载的策略类；nil 明确关闭继承的业务能力。
+        def tftp_strategy(klass)
+          @values[:tftp_strategy] = klass
+          self
+        end
+
+        # 指定运行配置采集策略，覆盖继承的厂商规则。
+        def running_config_strategy(klass)
+          @values[:running_config_strategy] = klass
+          self
+        end
+
+        # 指定邻居发现和描述下发策略，nil 表示关闭能力。
+        def topology_strategy(klass)
+          @values[:topology_strategy] = klass
+          self
+        end
+
+        # 将声明字段校验并构造成不可变档案。
+        def build = Profile.new(**@values)
+
+        private
+
+        # 块式声明入口必须有明确的子 DSL，避免静默忽略配置。
+        def validate_block!(name, definition)
+          raise ArgumentError, "#{name} requires a block" unless definition
+        end
+
+        # 命令集合的声明对象。
+        class Commands
+          attr_reader :config_commands, :save_commands
+
+          # 复制继承的命令，后续修改不会污染父类档案。
+          def initialize(config_commands, save_commands)
+            @config_commands = config_commands&.dup
+            @save_commands = save_commands.dup
+          end
+
+          # 声明读取运行配置的命令序列。
+          def running_config(*commands)
+            @config_commands = commands.flatten
+          end
+
+          # 声明保存配置的命令序列。
+          def save_config(*commands)
+            @save_commands = commands.flatten
+          end
+        end
+
+        # 提示符的声明对象。
+        class Prompts
+          # 将登录、命令、用户名、密码和特权提示写入当前档案。
+          def initialize(values)
+            @values = values
+          end
+
+          # 声明登录结束提示符。
+          def login(pattern) = @values[:login_prompt] = pattern
+
+          # 声明普通命令结束提示符。
+          def command(pattern) = @values[:command_prompt] = pattern
+
+          # 声明用户名输入提示。
+          def username(pattern) = @values[:username_prompt] = pattern
+
+          # 声明密码输入提示。
+          def password(pattern) = @values[:password_prompt] = pattern
+
+          # 声明特权模式提示符。
+          def privilege(pattern) = @values[:privilege_prompt] = pattern
+        end
+
+        # 分页规则的声明对象。
+        class Pager
+          # 将分页模式和响应写入当前档案。
+          def initialize(values)
+            @values = values
+          end
+
+          # 声明分页提示匹配模式。
+          def pattern(value) = @values[:pager_pattern] = value
+
+          # 声明匹配分页提示后发送的字节。
+          def response(value) = @values[:pager_response] = value
+        end
+
+        # 设备错误模式的声明对象。
+        class Errors
+          # 将错误模式列表写入当前档案。
+          def initialize(values)
+            @values = values
+          end
+
+          # 替换认证失败模式列表。
+          def authentication(*patterns)
+            @values[:authentication_error_patterns] = patterns.flatten
+          end
+
+          # 替换命令失败模式列表。
+          def command(*patterns)
+            @values[:command_error_patterns] = patterns.flatten
+          end
+        end
+
+        # 登录和命令交互的声明对象。
+        class Interactions
+          attr_reader :login_interactions, :confirmation_interactions
+
+          # 复制继承的交互规则，子类可以在其上追加设备差异。
+          def initialize(values)
+            @login_interactions = values[:login_interactions].dup
+            @confirmation_interactions = values[:confirmation_interactions].dup
+          end
+
+          # 声明登录阶段的一次性应答。
+          def login(pattern, response:, sensitive: false, limit: 1, capture: true)
+            @login_interactions << Interaction.new(pattern, response, sensitive: sensitive,
+                                                   limit: limit, capture: capture)
+          end
+
+          # 声明命令阶段的确认应答。
+          def confirm(pattern, response:, sensitive: false, limit: nil, capture: true)
+            @confirmation_interactions << Interaction.new(pattern, response, sensitive: sensitive,
+                                                          limit: limit, capture: capture)
+          end
+        end
+
+        # 特权认证规则的声明对象。
+        class Privilege
+          # 将特权命令和结束提示写入当前档案。
+          def initialize(values)
+            @values = values
+          end
+
+          # 声明进入特权模式的设备命令。
+          def command(value) = @values[:privilege_command] = value
+
+          # 声明特权命令完成后的提示符。
+          def prompt(value) = @values[:privilege_prompt] = value
+        end
+
+        # SSH 兼容参数的声明对象。
+        class Ssh
+          # 将旧版 SSH 参数写入当前档案。
+          def initialize(values)
+            @values = values
+          end
+
+          # 声明连接旧版设备所需的参数序列。
+          def legacy_arguments(*arguments) = @values[:legacy_ssh_arguments] = arguments.flatten
+        end
+      end
+    end
+  end
+end