ctx_driver 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1f792a12c386d5fdef44c86c9743d2f916ad1c654d552dccb22158710ef0025
-  data.tar.gz: afe56046cd35730cc233bafd0de69cd25886cec841c65aa379557b1ea0287302
+  metadata.gz: e6148df70de9c5d2f553071b6ce9179f4cf71aa7c5c51e3293f3d1487f463a34
+  data.tar.gz: 5a125fb3880cc2f841d00e5ca98f0884b84a4a6f75be30ec5008e4acba714e1a
 SHA512:
-  metadata.gz: d289d193573088f0524ce654497fa3b6eb010b0829a66c89fd327a8bb5a89a8417f0d2a0329be0c404438a7dc33e49bcf33d917f62529c7eea1841c6d0457f54
-  data.tar.gz: 77b1a08cb2e1db7884017d030587cf679f0437bdb71109ded4e352335c0509effca89e9f9e97382b560bbaf5cf50abe5179622fad781a691a848c3916c48432d
+  metadata.gz: 3c4430a8db98abfdbaa5919f7f50cc3a0dc3269155e4ca281ba8661535df72ac803cc6484239c5aabc219c748af884d84e155b67109b6ba9387aa0f0a395b024
+  data.tar.gz: 84c752509fc15b61ca63ea79081b8a9279220b717cfca788cfb8cf367e41cf05ed6e1634d925e0883288e36a9c098e2b405094a86cef18b0a918dbee7d11884b

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 Changes to the public contract are recorded here. Versions follow Semantic Versioning.
 
+## 0.2.0 (2026-10-17)
+
+- Require ctx_parser 0.2.x for the renamed public contracts.
+
+- Mark an aborted command unusable for the current reader while propagating cancellation, including Thread termination, without closing or replaying the borrowed session.
+- Snapshot start times and response bodies before subsequent caller callbacks can mutate them.
+- Validate session and clock protocols, capture field types, and success/failure/skipped consistency.
+- Ignore non-exception connector `Error` constants when classifying failures.
+- Decode native responses without redundant output concatenation or a full array of body lines.
+
+- Name the borrowed-session adapter `CtxDriver::Session` and load it from `ctx_driver/session`.
+
+- Separate command receipt, command failure, and retained session failure terminology without changing execution behavior.
+
 ## 0.1.0 (2026-10-16)
 
 ### Added

data/README-zh.md

@@ -76,14 +76,22 @@ puts "SHA-256: #{capture.evidence.first[:sha256]}"
 
 自定义会话实现 `connected?` 和 `send_commands([command])`。回执提供 `output`、布尔 `success?`、数组 `steps`、成功正文 `value!` 及失败时的 `error`。成功读取必须只有一个完成步骤。只有会话显式声明 `preserve_session_on_rejection:` 关键字时才传入该选项。
 
-单个 reader 顺序使用；跨设备并发分别创建 reader。连接、关闭、凭据和批准命令选择由宿主负责，Reader 不判断任意命令是否只读。普通执行/回执异常转为安全诊断，取消信号继续传播。
+单个 reader 顺序使用；跨设备并发分别创建 reader。连接、关闭、凭据和批准命令选择由宿主负责，Reader 不判断任意命令是否只读。普通执行/回执异常转为安全诊断，取消信号继续传播。执行或响应处理被中断后，当前 Reader 记录 `command_aborted`，后续查询跳过；不会凭 `connected?` 仍为 true 就复用同步状态未知的会话，也不会替宿主关闭连接。
+
+时钟必须可调用且返回 Time，时间在取得时立即复制。正文在检查后续会话状态之前复制。`Capture` 校验字段与状态：成功必须有字符串正文（允许空串），失败没有正文，跳过必须有失败原因且没有执行证据。墙上时钟可能回拨，时间字段不用于推断单调耗时。
 
 详细厂商语义、历史验证记录和 Motor 专用集成说明保留在[架构参考](docs/architecture-zh.md)。其中宿主集成代码需要 Motor，不属于独立 gem API。适配层位于 [Motor 仓库](https://github.com/gatework/motor/tree/main/backend/lib) 的 `backend/lib/baseline`、`backend/lib/vxlan` 和 `backend/lib/wireless`。
 
 原生 `Net::Connector::Base` 会话通过 `execute_operation` 自动适配，不连接、不提权。只去除已匹配的提示符和首行命令回显；连接器因拒绝命令而关闭时，后续读取跳过，不自动重连。自定义会话仍可实现 `send_commands` 协议。
 
+## 领域术语
+
+命令回执属于一次执行，`Capture` 保留处理后的正文和安全证据元数据。命令失败与会话失败具有不同生命周期：独立命令失败后会话仍可能可用，`Reader#failure` 则保留阻止后续查询的首个原因。`Capture#success?` 表示执行结果，不表示解析完整性或设备健康。
+
 ## 开发与测试
 
+共享类按实际职责命名，平台信息放在命名空间中。直接对应设备命令的解析器保留文件名和类名。
+
 ```sh
 bundle install
 bundle exec rake
@@ -91,7 +99,9 @@ bundle exec ruby examples/offline.rb
 bundle exec rake build
 ```
 
-`bundle exec rake` 执行 RSpec、RuboCop 及离线示例。测试放在 `spec/`，沿用项目 RSpec 约定；样例采用合成或脱敏证据。新增解析格式时补充成功、不完整、不支持及非法输入回归。离线测试不代表所有设备版本均通过实机验证。
+`bundle exec rake` 执行 RSpec、RuboCop 及离线示例。测试放在 `spec/`，沿用项目 RSpec 约定；样例采用合成或脱敏证据。新增会话适配时补充成功、拒绝、断链、取消、非法回执及证据保留回归。离线测试不代表所有设备版本均通过实机验证。
+
+`bundle exec ruby -Ilib benchmark/body.rb` 测量合成回显的正文解码时间及对象分配，并校验正文内容；不代表设备网络吞吐。
 
 使用声明的最低 Ruby 版本检查兼容性。方法用途统一使用简明中文注释；复杂实现还需说明业务规则、实现思路及关键分支。保持公开返回值与错误契约。真实回显和凭据不可进入示例、fixture、日志或发布包。
 

data/README.md

@@ -80,8 +80,18 @@ Use each reader sequentially; create separate readers for concurrent devices. Th
 
 Detailed vendor behavior, historical validation notes, and Motor-only integration are preserved in [the architecture reference](docs/architecture-zh.md). Host integration examples in that reference require Motor; they are not standalone gem APIs. Motor adapters live under `backend/lib/baseline`, `backend/lib/vxlan`, and `backend/lib/wireless` in the [Motor repository](https://github.com/gatework/motor/tree/main/backend/lib).
 
+## Domain vocabulary
+
+A command receipt belongs to one execution; a `Capture` holds its processed body and safe evidence metadata. Command failure and session failure have different lifetimes: an independent command may fail while the session remains usable, whereas `Reader#failure` retains the first cause that prevents further queries. `Capture#success?` describes execution, not parsing completeness or device health.
+
+Cancellation during execution or response processing propagates and marks the reader with `command_aborted`. Later reads are skipped even if the borrowed session still reports connected; the host retains responsibility for closing or replacing it.
+
+The clock must be callable and return `Time`. Times and response bodies are copied before later callbacks can mutate them. Successful captures require a string body (including an empty string); failed captures have no body, and skipped captures require a failure without execution evidence. Wall-clock timestamps can move backwards and are not elapsed-time measurements.
+
 ## Development and tests
 
+Name shared classes by their responsibility and use the namespace for platform context. Preserve filenames and class names that directly match device commands.
+
 ```sh
 bundle install
 bundle exec rake
@@ -93,6 +103,8 @@ bundle exec rake build
 
 Use the declared minimum Ruby version for compatibility checks. Document source methods and non-obvious business logic in concise Chinese, preserve public return/error contracts, and never add raw device captures or credentials to examples, fixtures, logs, or release archives.
 
+Run `bundle exec ruby -Ilib benchmark/body.rb` to measure body decoding and allocations against synthetic output, with semantic checks. This does not measure device network throughput.
+
 ## Release
 
 This directory can be maintained as the independent [ctx_driver](https://github.com/gatework/ctx_driver) repository. Update `VERSION` and `CHANGELOG.md`, run the validation and build commands above, and inspect the packaged file list before tagging `vVERSION`.

data/docs/architecture-zh.md

@@ -38,7 +38,11 @@ capture.evidence # command / sha256 / bytes / observed_at
 字段 `started_at/completed_at` 为采集阶段时间；证据的 `observed_at` 为实际收到响应的时间。
 命令失败与领域健康状态分开，Reader 不产生 pass/fail 或完整库存判断。
 
-`StandardError` 在单命令执行、响应验证和状态查询边界转换为安全诊断；取消信号继续抛出。
+`StandardError` 在单命令执行、响应验证和状态查询边界转换为安全诊断；取消信号继续抛出。执行或响应处理未能完成回执时，ensure 保留原有失败或记录 `command_aborted`，包括不进入 rescue 的 Thread.kill。此 Reader 后续只返回 skipped，不关闭借用会话、不重放命令。
+
+开始时间在执行回调之前保存副本，正文在后续状态回调之前保存副本。注入时钟必须可调用并返回 Time；时间允许因墙上时钟校准而回拨。`Capture` 拒绝类型错误以及成功/失败/跳过状态与正文或证据矛盾的回执。
+
+原生适配器只读取渲染后正文的首行来判断回显，不构造全部行数组；成功路径不再调用连接器 `value!` 重复拼接输出，失败仍由连接器原样抛出错误。`benchmark/body.rb` 使用合成回显验证内容、耗时和分配量，不提供真实设备网络性能结论。
 解析异常由领域 Collector 在本条命令或本次 AP 子任务内隔离。
 调用方须顺序使用同一个 Reader；跨设备并发各自建立 Reader。
 

data/lib/ctx_driver/capture.rb

@@ -9,6 +9,22 @@ module CtxDriver
 
     # 冻结单条命令回执及其正文、时间、证据和失败元数据。
     def initialize(command:, body: nil, started_at:, completed_at:, evidence: [], failure: nil, skipped: false)
+      unless command.is_a?(String) && !command.strip.empty? && !/[\x00-\x1f\x7f]/.match?(command)
+        raise ArgumentError, "One command without control characters is required"
+      end
+      raise ArgumentError, "Capture body must be text or nil" unless body.nil? || body.is_a?(String)
+      unless started_at.is_a?(Time) && completed_at.is_a?(Time)
+        raise ArgumentError, "Capture timestamps must be Time values"
+      end
+      unless evidence.is_a?(Array) && evidence.all? { |entry| entry.is_a?(Hash) }
+        raise ArgumentError, "Capture evidence must be hashes"
+      end
+      raise ArgumentError, "Capture failure must be a hash or nil" unless failure.nil? || failure.is_a?(Hash)
+      raise ArgumentError, "Skipped must be boolean" unless [ true, false ].include?(skipped)
+      raise ArgumentError, "Successful captures require a body" if failure.nil? && body.nil?
+      raise ArgumentError, "Failed captures cannot contain a body" if failure && !body.nil?
+      raise ArgumentError, "Skipped captures require failure without evidence" if skipped && (failure.nil? || evidence.any?)
+
       @command = command.dup.freeze
       @body = body&.dup&.freeze
       @started_at, @completed_at = started_at.dup.freeze, completed_at.dup.freeze

data/lib/ctx_driver/failure.rb

@@ -17,9 +17,13 @@ module CtxDriver
 
     # 识别传输异常，不要求特定连接器实现。
     def self.connection_error?(error, owner)
-      (defined?(Net::Connector::Error) && error.is_a?(Net::Connector::Error)) ||
-        (owner.class.const_defined?(:Error) && error.is_a?(owner.class.const_get(:Error))) ||
-        error.is_a?(IOError)
+      return true if error.is_a?(IOError) || (defined?(Net::Connector::Error) && error.is_a?(Net::Connector::Error))
+      return false unless owner.class.const_defined?(:Error)
+
+      error_type = owner.class.const_get(:Error)
+      return false unless error_type.is_a?(Class) && error_type <= StandardError
+
+      error.is_a?(error_type)
     end
 
     # 已加载 net-connector 时复用其稳定诊断词表，否则使用调用方的回退代码。

data/lib/ctx_driver/reader.rb

@@ -4,7 +4,7 @@ require "digest"
 require "time"
 require_relative "capture"
 require_relative "failure"
-require_relative "net_connector_session"
+require_relative "session"
 
 module CtxDriver
   # 借用已打开会话逐条独立查询；连接归属与领域判断由外部负责。
@@ -12,14 +12,16 @@ module CtxDriver
     # 借用已打开会话，并初始化首个失败的跟踪状态。
     def initialize(session:, clock: -> { Time.now.utc })
       if defined?(Net::Connector::Base) && session.is_a?(Net::Connector::Base)
-        session = NetConnectorSession.new(session)
+        session = Session.new(session)
       end
       unless session.respond_to?(:send_commands)
         raise ArgumentError, "Session must implement #send_commands for the command driver protocol"
       end
+      raise ArgumentError, "Session must implement #connected?" unless session.respond_to?(:connected?)
+      raise ArgumentError, "Clock must be callable" unless clock.respond_to?(:call)
 
       @session, @clock = session, clock
-      @unavailable = nil
+      @session_failure = nil
     end
 
     # 执行一条经过校验的查询，保留独立结果或失败。
@@ -28,67 +30,83 @@ module CtxDriver
         raise ArgumentError, "One command without control characters is required"
       end
       command = command.dup.freeze
-      started = @clock.call
+      started_at = current_time
       if failure
-        return Capture.new(command: command, started_at: started, completed_at: @clock.call,
-          failure: @unavailable, skipped: true)
+        return Capture.new(command: command, started_at: started_at, completed_at: current_time,
+          failure: @session_failure, skipped: true)
       end
 
-      acquire(command, started)
+      capture_command(command, started_at)
     end
 
     # 不发送命令即可检查会话可用性，并保留首次失败原因。
     def failure
-      @unavailable ||= session_failure
+      @session_failure ||= detect_session_failure
     end
 
     private
 
+    # 立即保存时钟快照，避免后续用户回调改变已记录的时区或时间。
+    def current_time
+      time = @clock.call
+      raise TypeError, "Clock must return a Time" unless time.is_a?(Time)
+
+      time.dup.freeze
+    end
+
     # 分离执行与回执校验；后续校验失败时仍保留已取得的证据。
-    def acquire(command, started)
-      stage, evidence, failure, body = :execute, [], nil, nil
+    def capture_command(command, started_at)
+      stage, evidence, command_failure, body = :execute, [], nil, nil
+      capture_completed = false
       begin
-        result = if preserves_rejection?
+        receipt = if supports_session_preservation?
           @session.send_commands([ command ], preserve_session_on_rejection: true)
         else
           @session.send_commands([ command ])
         end
         stage = :response
-        output = result.output
+        output = receipt.output
         raise TypeError, "Command output must be text" unless output.is_a?(String)
 
         evidence = [ { command: command, sha256: Digest::SHA256.hexdigest(output), bytes: output.bytesize,
-          observed_at: @clock.call.getutc.iso8601(6) } ]
-        success = result.success?
-        unless [ true, false ].include?(success) && result.steps.is_a?(Array) && (!success || result.steps.one?)
+          observed_at: current_time.getutc.iso8601(6) } ]
+        success = receipt.success?
+        unless [ true, false ].include?(success) && receipt.steps.is_a?(Array) && (!success || receipt.steps.one?)
           raise TypeError, "One query must return one completed command"
         end
         if success
-          body = result.value!
+          body = receipt.value!
           raise TypeError, "Command body must be text" unless body.is_a?(String)
+
+          body = body.dup.freeze
         else
-          failure = Failure.details(result.error, fallback: :command_failed, stage: :execute)
+          command_failure = Failure.details(receipt.error, fallback: :command_failed, stage: :execute)
         end
       rescue StandardError => error
         fallback = stage == :execute ? :command_execution_failed : :invalid_command_result
-        failure = Failure.details(error, fallback: fallback, stage: stage)
+        command_failure = Failure.details(error, fallback: fallback, stage: stage)
       end
-      state_failure = session_failure
+      state_failure = detect_session_failure
       # 单命令失败但会话仍可用时继续独立查询；断链或状态不明才阻止后续提交。
-      @unavailable = failure || state_failure if state_failure
-      Capture.new(command: command, body: failure ? nil : body, started_at: started, completed_at: @clock.call,
-        evidence: evidence, failure: failure)
+      @session_failure = command_failure || state_failure if state_failure
+      capture = Capture.new(command: command, body: command_failure ? nil : body, started_at: started_at, completed_at: current_time,
+        evidence: evidence, failure: command_failure)
+      capture_completed = true
+      capture
+    ensure
+      # Interrupt 与 Thread.kill 不经过 StandardError；未完成回执时禁止继续使用未知同步状态。
+      @session_failure ||= command_failure || { code: :command_aborted, stage: stage || :execute }.freeze unless capture_completed
     end
 
     # 仅在明确支持时复用命令拒绝后的会话；未知提示符仍由连接器关闭处理。
-    def preserves_rejection?
+    def supports_session_preservation?
       @session.method(:send_commands).parameters.any? do |kind, name|
         %i[key keyreq].include?(kind) && name == :preserve_session_on_rejection
       end
     end
 
     # 连接状态不确定时视为不可用，后续跳过的查询保留首次失败原因。
-    def session_failure
+    def detect_session_failure
       state = @session.connected?
       raise TypeError, "Connection state must be boolean" unless [ true, false ].include?(state)
 

data/lib/ctx_driver/{net_connector_session.rb → session.rb}

@@ -2,7 +2,7 @@
 
 module CtxDriver
   # 适配已加载的 net-connector；不连接、不提权，也不恢复已关闭的借用会话。
-  class NetConnectorSession
+  class Session
     # 先交出原始回执，Reader 建立证据后才按需解码正文。
     Response = Data.define(:result) do
       def output = result.output
@@ -12,10 +12,11 @@ module CtxDriver
 
       # 只移除匹配的首行命令回显；保留正文缩进及后续相同行。
       def value!
-        result.value!
+        # 成功路径无需再次拼接全部输出；失败仍交由连接器保留异常契约。
+        result.value! unless result.success?
         step = result.steps.fetch(0)
         body = Net::Connector::TerminalText.render(step.output.delete_suffix(step.prompt.to_s))
-        first = body.lines.first
+        first = body.each_line("\n").first
         first && first.strip == step.command.text ? body.delete_prefix(first) : body
       end
     end

data/lib/ctx_driver/version.rb

@@ -2,5 +2,5 @@
 
 module CtxDriver
   # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ctx_driver
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Gatework contributors
@@ -13,16 +13,16 @@ dependencies:
   name: ctx_parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: digest
   requirement: !ruby/object:Gem::Requirement
@@ -67,8 +67,8 @@ files:
 - lib/ctx_driver.rb
 - lib/ctx_driver/capture.rb
 - lib/ctx_driver/failure.rb
-- lib/ctx_driver/net_connector_session.rb
 - lib/ctx_driver/reader.rb
+- lib/ctx_driver/session.rb
 - lib/ctx_driver/version.rb
 homepage: https://github.com/gatework/ctx_driver
 licenses: