net-connector 0.4.2 → 0.6.0

data/lib/net/connector/engine/session.rb

@@ -40,7 +40,22 @@ module Net
       def mark_privileged! = @privileged = true
 
       # 记录脚本之外的业务结果，例如设备报告的 TFTP 上传状态。
-      def log_event(name, **fields) = @log.event(name, **fields)
+      def log_event(name, **fields) = @log.log_custom_event(name, **fields)
+
+      # 业务名称贯穿脚本及其钩子，底层命令另外分配独立序号。
+      def log_script(operation:, steps:)
+        @log.with_operation_context(operation) do
+          started = Expect.monotonic
+          @log.log_event("operation_start", level: :debug, phase: :script)
+          result = yield
+          log_operation_completion(started, result.is_a?(Result) ? result.error : nil, steps: steps.size)
+          result
+        rescue => error
+          failure = normalize_error(error, phase: :script)
+          log_operation_completion(started, failure, steps: steps.size)
+          raise failure, cause: nil
+        end
+      end
 
       # 在会话锁内建立连接。
       def connect
@@ -53,7 +68,7 @@ module Net
           return perform_locked(phase) { yield }
         end
         unless @lock.try_lock
-          raise error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
+          raise build_error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
         end
 
         begin
@@ -66,11 +81,18 @@ module Net
       # 业务操作在多次脚本之间持有租约；只有同一线程和 Fiber 可顺序使用。
       def with_operation(phase)
         unless @lock.try_lock
-          raise error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
+          raise build_error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
         end
         @operation_owner = [Thread.current, Fiber.current]
+        result = nil
         begin
-          yield
+          @log.with_operation_context(phase) { result = yield }
+        rescue Error => error
+          raise unless result.is_a?(Result)
+
+          # 日志收尾失败不能抹去已完成的设备步骤，也不能覆盖原业务错误。
+          Result.new(steps: result.steps, config: result.config,
+                     error: result.error || normalize_error(error, phase: phase))
         ensure
           @operation_owner = nil
           @lock.unlock
@@ -81,7 +103,7 @@ module Net
       def assert_path_lock_order!(phase)
         return unless @lock.locked?
 
-        raise error(SessionBusy, "backup path ownership must be acquired before a session operation", phase: phase), cause: nil
+        raise build_error(SessionBusy, "backup path ownership must be acquired before a session operation", phase: phase), cause: nil
       end
 
       # 一次操作从连接到结果处理始终持锁；异常或 throw 中断都关闭未完成会话。
@@ -118,7 +140,7 @@ module Net
       # 独占关闭会话；已有操作占用时返回会话繁忙错误。
       def close
         unless @lock.try_lock
-          raise error(SessionBusy, "cannot close a session owned by another operation", phase: :close), cause: nil
+          raise build_error(SessionBusy, "cannot close a session owned by another operation", phase: :close), cause: nil
         end
 
         begin
@@ -131,7 +153,7 @@ module Net
       # 执行特权认证，并更新提示符及特权状态。
       def enable(command, prompt)
         unless command
-          raise error(UnsupportedOperation, "privilege authentication is not supported", phase: :enable), cause: nil
+          raise build_error(UnsupportedOperation, "privilege authentication is not supported", phase: :enable), cause: nil
         end
 
         @privileged = false
@@ -142,8 +164,8 @@ module Net
       end
 
       # 命令准备、交换、后处理及回调共用一份临时词表，退出时一并清除。
-      def command_scope(command)
-        redactor.scope do
+      def with_command_redaction(command)
+        redactor.with_scope do
           protect_command(command)
           yield
         end
@@ -151,10 +173,10 @@ module Net
 
       # 批次准备和最终清理也可能读取配置；在作用域退出前归一化其异常，
       # 防止清理钩子的消息或回溯将已完成步骤中的正文带回诊断通道。
-      def output_scope(enabled)
+      def with_sensitive_output(enabled)
         return yield unless enabled
 
-        redactor.scope do
+        redactor.with_scope do
           redactor.output_sensitive!
           yield
         rescue => error
@@ -163,29 +185,47 @@ module Net
       end
 
       # 复用完整命令的脱敏范围；厂商后续查询产生的秘密保留到外层回调结束。
-      def exchange(command, timeout:, prompt: nil)
-        redactor.scope(reuse: true) do
+      def execute_command(command, timeout:, prompt: nil)
+        redactor.with_scope(reuse: true) do
           protect_command(command)
-          started = Expect.monotonic
-          @log.event("command_start", text: command.sensitive? ? "[REDACTED]" : command.text)
-          sensitive_dialogue = [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
-          private_output = command.sensitive? || redactor.output_sensitive? || sensitive_dialogue
-          @log.event("device_output", level: :debug) if @log.detailed? && !private_output
-          response = exchange_command(command, timeout: timeout, prompt: prompt)
-          @log.response_output(response.raw) unless private_output
-          @log.event("command_complete", status: "response_received")
-          @log.event("command_detail", level: :debug,
-                     duration_ms: ((Expect.monotonic - started) * 1000).round,
-                     response_bytes: response.raw.bytesize)
-          response
-        rescue => error
-          failure = normalize_error(error, phase: :command, command: command)
-          @log.event("command_complete", level: :error, status: "failed",
-                     error: failure.class.name, message: failure.message)
-          raise failure, cause: nil
+          @log.with_command_context(command) { execute_command_with_logging(command, timeout: timeout, prompt: prompt) }
+        ensure
+          # 失败的敏感探测也可能被钩子捕获后继续；离开作用域前始终通知执行器。
+          yield if block_given?
         end
       end
 
+      def execute_command_with_logging(command, timeout:, prompt:)
+        started = Expect.monotonic
+        @log.log_event("command_start")
+        sensitive_dialogue = [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
+        private_output = command.sensitive? || redactor.output_sensitive? || sensitive_dialogue
+        @log.log_event("device_output", level: :debug) if @log.debug? && !private_output
+        response = exchange_command(command, timeout: timeout, prompt: prompt)
+        @log.log_response_output(response.raw) unless private_output
+        details = { duration_ms: elapsed_ms(started), response_bytes: response.raw.bytesize }
+        @log.log_event("command_complete", status: "response_received", **details)
+        response
+      rescue => error
+        failure = normalize_error(error, phase: :command, command: command)
+        @log.log_failure("command_complete", failure, status: "failed", duration_ms: elapsed_ms(started), phase: :command)
+        raise failure, cause: nil
+      end
+
+      def elapsed_ms(started) = ((Expect.monotonic - started) * 1000).round
+
+      def log_operation_completion(started, failure, steps: nil)
+        fields = { status: failure ? "failed" : "completed", duration_ms: elapsed_ms(started), steps: steps,
+                   phase: :script }
+        if failure
+          @log.log_failure("operation_complete", failure, **fields, failed_command: failure.command)
+        else
+          @log.log_event("operation_complete", **fields)
+        end
+      end
+
+      private :execute_command_with_logging, :elapsed_ms, :log_operation_completion
+
       # 在用户钩子运行前标记敏感上下文，动态交互尚未返回时也能保护其异常。
       def protect_command(command)
         redactor.output_sensitive! if command.output_sensitive?
@@ -208,7 +248,7 @@ module Net
                                  deadline: deadline, phase: :command, command: command)
           @prompt = response.prompt
           if (diagnostic = @dialogue.diagnostic(response.raw))
-            raise error(DeviceError, diagnostic, phase: :command, command: command, output: response.raw), cause: nil
+            raise build_error(DeviceError, diagnostic, phase: :command, command: command, output: response.raw), cause: nil
           end
 
           response
@@ -243,7 +283,7 @@ module Net
       end
 
       # 创建带脱敏上下文、阶段、命令和输出尾部的领域错误。
-      def error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
+      def build_error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
         sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
         message = safe_error_text(message, sensitive: sensitive)
         output = safe_error_text(output, sensitive: sensitive)
@@ -264,8 +304,8 @@ module Net
           end
           message = safe_error_text(exception.message, sensitive: sensitive)
           output = safe_error_text(exception.output, sensitive: sensitive)
-          return exception.class.new(
-            message, code: exception.code,
+          return exception.with_diagnostics(
+            message: message,
             host: exception.host || configuration.host, phase: exception.phase || phase,
             command: failed_command && redactor.call(failed_command),
             source: exception.source || command&.source, line: exception.line || command&.line,
@@ -279,7 +319,7 @@ module Net
                 when IOError, SystemCallError, Expect::SpawnError then TransportError
                 else InternalError
                 end
-        error(klass, "#{phase} failed: #{exception.class}", phase: phase, command: command, underlying: exception)
+        build_error(klass, "#{phase} failed: #{exception.class}", phase: phase, command: command, underlying: exception)
       end
 
       # 敏感上下文的任意异常和设备输出可能只包含局部秘密，保留类型和错误码诊断。
@@ -306,27 +346,28 @@ module Net
         attempted_recovery = false
         begin
           @state = :connecting
+          started = Expect.monotonic
           redactor.reset
           @log.open(transport)
-          @log.event("connect", host: configuration.host, username: configuration.username,
-                     protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
+          @log.log_event("connect", host: configuration.host, username: configuration.username,
+                         phase: :connect, protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
           transport.open
           @state = :authenticating
-          @log.event("login_start", level: :debug)
+          @log.log_event("login_start", level: :debug, phase: :login)
           response = @authentication.login
           safe_response = Response.new(raw: redactor.call(response.raw), output: redactor.call(response.output),
                                        prompt: response.prompt)
           @prompt = response.prompt
           @after_login.call(self, safe_response)
-          @log.authentication_output(response.raw)
-          @log.event("login_complete", status: "ok", prompt: response.prompt)
+          @log.log_authentication_output(response.raw)
+          @log.log_event("login_complete", status: "ok", prompt: response.prompt, phase: :login, duration_ms: elapsed_ms(started))
           @log.attach
           @state = :ready
         rescue => error
           phase = (@state == :connecting) ? :connect : :login
           failure = normalize_error(error, phase: phase)
-          @log.event(phase == :connect ? "connect_failed" : "login_complete", level: :error,
-                     status: "failed", error: failure.class.name, message: failure.message, phase: phase)
+          @log.log_failure(phase == :connect ? "connect_failed" : "login_complete", failure,
+                           status: "failed", phase: phase, duration_ms: elapsed_ms(started))
           close_preserving_failure
           replacement = attempted_recovery ? nil : @recovery.recover(failure, transport)
           if replacement

data/lib/net/connector/engine/terminal_text.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "terminal_renderer"
+require_relative "errors"
+
+module Net
+  module Connector
+    # 设备/文件提供的是字节，不受 Ruby 源文件编码控制。解析边界只接受 UTF-8，
+    # 不猜测编码、不改写原文，也不让终端编辑把非法字节抹掉后变成可信证据。
+    module TerminalText
+      def self.utf8(bytes, host: nil)
+        raise ArgumentError, "text must be a String" unless bytes.is_a?(String)
+
+        text = bytes.b.force_encoding(Encoding::UTF_8)
+        invalid_encoding!(host) unless text.valid_encoding?
+        text
+      end
+
+      def self.render(bytes, host: nil)
+        TerminalRenderer.render(utf8(bytes, host: host), strict_utf8: true).force_encoding(Encoding::UTF_8)
+      rescue Encoding::InvalidByteSequenceError
+        invalid_encoding!(host)
+      end
+
+      def self.invalid_encoding!(host)
+        raise ParsingError.new("device output is not valid UTF-8", code: :invalid_output_encoding,
+                               host: host, phase: :parse), cause: nil
+      end
+
+      private_class_method :invalid_encoding!
+    end
+  end
+end

data/lib/net/connector/engine/transport.rb

@@ -46,7 +46,7 @@ module Net
                      end
           # Profile 使用宽、高；PTY 使用行数、列数。
           @channel.slave.winsize = @terminal_size.reverse if @terminal_size
-          @channel.log_output = method(:record)
+          @channel.log_output = method(:write_log_output)
           @channel.spawn(*argv)
           self
         rescue Exception # rubocop:disable Lint/RescueException -- A half-open PTY must be released on interrupts.
@@ -104,7 +104,7 @@ module Net
         private
 
         # 检查缓冲上限并把设备输出写入当前日志目标。
-        def record(bytes)
+        def write_log_output(bytes)
           if @channel.buffer.bytesize > configuration.max_output_bytes
             raise OutputLimitExceeded.new("transport buffer exceeded max_output_bytes",
                                           phase: :read, output: @channel.buffer.dup), cause: nil

data/lib/net/connector/netdisco/batch.rb

@@ -8,9 +8,7 @@ module Net
     module Netdisco
       # 单台设备的最终结果，保留状态、配置产物和错误类型。
       Outcome = Data.define(:device, :status, :backup, :error_code, :error_type,
-                            :started_at, :finished_at) do
-        attr_reader :diagnostic
-
+                            :started_at, :finished_at, :duration_ms, :diagnostic) do
         # 创建结果，允许计划阶段尚无执行时间。
         def initialize(device:, status:, backup:, error_code:, error_type:, started_at: nil, finished_at: nil,
                        duration_ms: nil, diagnostic: nil)
@@ -19,19 +17,18 @@ module Net
           end
           raise ArgumentError, "diagnostic must be a Diagnostic" unless diagnostic.nil? || diagnostic.instance_of?(Diagnostic)
 
-          @duration_ms, @diagnostic = duration_ms, diagnostic
           super(device: device, status: status, backup: backup, error_code: error_code, error_type: error_type,
-                started_at: started_at, finished_at: finished_at)
+                started_at: started_at, finished_at: finished_at, duration_ms: duration_ms, diagnostic: diagnostic)
         end
 
-        # Data 成员保持不变；Worker 加上时间、旧文件迁移调整产物时仍保留内部元数据。
+        # 修改诊断或时刻时释放不再匹配的派生元数据。
         def with(**attributes)
           return self if attributes.empty?
 
-          metadata = { duration_ms: @duration_ms, diagnostic: diagnostic }
-          metadata[:duration_ms] = nil if attributes.key?(:started_at) || attributes.key?(:finished_at)
-          metadata[:diagnostic] = nil if attributes.key?(:error_code) || attributes.key?(:error_type)
-          self.class.new(**to_h, **metadata.merge(attributes))
+          values = to_h
+          values[:duration_ms] = nil if attributes.key?(:started_at) || attributes.key?(:finished_at)
+          values[:diagnostic] = nil if attributes.key?(:error_code) || attributes.key?(:error_type)
+          self.class.new(**values.merge(attributes))
         end
 
         # 判断设备是否完成配置保存或上报上传成功。
@@ -42,13 +39,6 @@ module Net
 
         # 判断设备是否因为清单或采样规则未执行。
         def skipped? = !success? && !partial? && status != :failed
-
-        # 计算设备任务的耗时，计划阶段没有时间时返回空值。
-        def duration_ms
-          return @duration_ms unless @duration_ms.nil?
-
-          [((finished_at - started_at) * 1000).round, 0].max if started_at && finished_at
-        end
       end
 
       # 汇总一次批量任务的设备结果、回调故障和报告写入状态。
@@ -63,34 +53,8 @@ module Net
         # 空清单与已尝试但未全部成功的批次分别标记。
         def status = outcomes.empty? ? :no_devices : (success? ? :succeeded : :incomplete)
 
-        # 单独请求 v2 包装，不改变旧 Data 的成员、解构或默认 summary。
-        def report(policy: :strict) = Report.new(self, policy: policy)
-
-        # 生成可写入报告及供命令行展示的结构化摘要。
-        def summary
-          {
-            mode: mode, status: status, started_at: started_at.iso8601, finished_at: finished_at.iso8601,
-            total: outcomes.size,
-            succeeded: outcomes.count(&:success?),
-            partial: outcomes.count(&:partial?),
-            failed: outcomes.count { |item| item.status == :failed },
-            skipped: outcomes.count(&:skipped?),
-            counts: counts,
-            callback_errors: callback_errors,
-            devices: outcomes.map do |item|
-              { host: item.device.host || item.device.source_ip, name: item.device.name,
-                vendor: item.device.vendor,
-                status: item.status, path: item.backup&.path,
-                bytes: item.backup.is_a?(Backup) ? item.backup.bytes : nil,
-                sha256: item.backup.is_a?(Backup) ? item.backup.sha256 : nil,
-                change: item.backup.is_a?(Backup) ? item.backup.change : nil,
-                previous_sha256: item.backup.is_a?(Backup) ? item.backup.previous_sha256 : nil,
-                started_at: item.started_at&.iso8601, finished_at: item.finished_at&.iso8601,
-                duration_ms: item.duration_ms,
-                error_code: item.error_code, error_type: item.error_type }
-            end
-          }
-        end
+        # 显式从原始执行结果构造报告。
+        def build_report(policy: :strict) = Report.new(self, policy: policy)
       end
 
       autoload :Report, File.expand_path("report", __dir__)

data/lib/net/connector/netdisco/cli.rb

@@ -48,11 +48,10 @@ module Net
 
           batch = backup(fleet, plan, settings, options)
           summary = batch.summary
-          summary = summary.merge(report_location: batch.report_location, report_error: batch.report_error) unless batch.instance_of?(Report)
           @output.puts JSON.pretty_generate(summary)
-          (batch.instance_of?(Report) ? batch.policy_success? : batch.success?) ? 0 : 1
-        rescue Operations::PrivateFile::WriteError => exception
-          message = Operations::PrivateFile.receipt_error?(exception) ? exception.message : exception.class.name
+          batch.policy_success? ? 0 : 1
+        rescue Storage::PrivateFile::WriteError => exception
+          message = Storage::PrivateFile.receipt_error?(exception) ? exception.message : exception.class.name
           @error.puts "net-connector-backup: #{message}"
           2
         rescue OptionParser::ParseError, ArgumentError, KeyError, Errno::ENOENT,
@@ -70,6 +69,9 @@ module Net
         def settings_for(options)
           defaults = options[:config] ? ConfigFile.load(options[:config]) : {}
           values = {}
+          values["NETDISCO_SOURCE"] = options[:source] if options[:source]
+          values["NETDISCO_QUERY"] = options[:query] if options[:query]
+          values["NETDISCO_QUERY_PARAMS"] = options[:query_params] if options[:query_params]
           values["NET_CONNECTOR_BACKUP_DIRECTORY"] = options[:directory] if options[:directory]
           values["NET_CONNECTOR_CONCURRENCY"] = options[:concurrency].to_s if options[:concurrency]
           values["NET_CONNECTOR_MAX_SCRIPT_OUTPUT_BYTES"] = options[:max_script_output_bytes].to_s if options[:max_script_output_bytes]
@@ -81,8 +83,8 @@ module Net
 
         # 导出已有配置不创建清单或设备连接。
         def export_config(settings, options)
-          path = Operations::SavedConfig.new(directory: settings.backup_directory)
-                                        .export(host: options[:export], output: options[:output], io: @output)
+          path = Storage::SavedConfig.new(directory: settings.backup_directory)
+                                     .export(host: options[:export], output: options[:output], io: @output)
           @output.puts JSON.generate(host: options[:export], output: path) if path
         end
 
@@ -103,7 +105,7 @@ module Net
 
         # 仅执行已经校验的计划，保留本地与 TFTP 两种结果语义。
         def backup(fleet, plan, settings, options)
-          reporting = options.slice(:success_policy, :report_schema)
+          reporting = options.slice(:success_policy)
           if options[:tftp]
             fleet.tftp_backup_all(plan: plan, server: settings.tftp_server,
                                   concurrency: settings.concurrency,
@@ -121,6 +123,9 @@ module Net
           parser = OptionParser.new do |args|
             args.banner = "用法：net-connector-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
             args.on("--config FILE", "读取不含凭据的 YAML 设置") { |value| options[:config] = value }
+            args.on("--source SOURCE", %w[http postgres], "清单来源：http（默认）或 postgres") { |value| options[:source] = value }
+            args.on("--query SQL", "PostgreSQL 清单查询，使用 $1、$2 绑定参数") { |value| options[:query] = value }
+            args.on("--query-params JSON", "查询参数的 JSON 数组") { |value| options[:query_params] = value }
             args.on("--show-config", "显示生效的非敏感设置") { options[:show_config] = true }
             args.on("--plan", "预览设备清单，不连接设备") { options[:plan] = true }
             args.on("--tftp", "由设备发起 TFTP 备份") { options[:tftp] = true }
@@ -135,7 +140,6 @@ module Net
             end
             args.on("--all", "选择全部就绪设备") { options[:all] = true }
             args.on("--success-policy POLICY", %w[strict selected], "成功判定：strict（默认）或 selected") { |value| options[:success_policy] = value.to_sym }
-            args.on("--report-schema N", Integer, "报告版本：1（默认）或 2；selected 使用 2") { |value| options[:report_schema] = value }
             args.on("-v", "--version", "显示版本") do
               @output.puts Net::Connector::VERSION
               options[:done] = true
@@ -153,15 +157,18 @@ module Net
 
         # 拒绝互斥或缺少依赖的命令行选项。
         def validate_options!(options)
-          Report.options(policy: options.fetch(:success_policy, :strict), schema: options[:report_schema])
+          Report.validate_policy!(options.fetch(:success_policy, :strict))
           Planner.validate_limit!(options[:limit])
           Worker.new(concurrency: options[:concurrency]) if options[:concurrency]
           modes = [:show_config, :plan, :export].count { |key| options[key] }
           raise ArgumentError, "--show-config、--plan 和 --export 只能选择一项" if modes > 1
           raise ArgumentError, "--output 需要同时指定 --export" if options[:output] && !options[:export]
           raise ArgumentError, "--all 不能与 --limit-per-vendor 同时使用" if options[:all] && options[:limit]
+          if options[:export] && (options[:source] || options[:query] || options[:query_params])
+            raise ArgumentError, "--export 不能与清单查询选项同时使用"
+          end
           if options[:export] && (options[:tftp] || options[:all] || options[:limit] || options[:concurrency] || options[:host] ||
-                                  options[:success_policy] || options[:report_schema] || options[:max_script_output_bytes])
+            options[:success_policy] || options[:max_script_output_bytes])
             raise ArgumentError, "--export 不能与备份选项同时使用"
           end
         end

data/lib/net/connector/netdisco/client.rb

@@ -96,7 +96,7 @@ module Net
           @options.fetch(:max_pages).times do |index|
             uri = endpoint("api/v1/search/device")
             uri.query = URI.encode_www_form(fields: FIELDS.join(","), limit: @options.fetch(:page_size),
-                                           offset: index * @options.fetch(:page_size))
+                                            offset: index * @options.fetch(:page_size))
             page = request_json(uri, authorized_get(uri, token), budget, allow_empty: true, query_fallback: true)
             validate_rows!(page, budget)
             return rows.uniq if page.empty?
@@ -109,10 +109,10 @@ module Net
           end
           raise Error.new("Netdisco inventory exceeded max_pages", code: :max_pages), cause: nil
         rescue QueryRequired
-          legacy_devices(token, budget)
+          query_required_devices(token, budget)
         end
 
-        def legacy_devices(token, budget)
+        def query_required_devices(token, budget)
           uri = endpoint("api/v1/search/device")
           uri.query = URI.encode_www_form(q: "%", seeallcolumns: true)
           rows = request_json(uri, authorized_get(uri, token), budget, allow_empty: true)
@@ -274,6 +274,7 @@ module Net
         end
 
         def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         def present?(value) = value.is_a?(String) && !value.strip.empty?
       end
     end

data/lib/net/connector/netdisco/config_file.rb

@@ -9,7 +9,10 @@ module Net
       # 命令行使用的无凭据 YAML 配置，环境变量优先。
       class ConfigFile
         FIELDS = {
-          "netdisco" => { "url" => ["NETDISCO_URL", :string],
+          "netdisco" => { "source" => ["NETDISCO_SOURCE", :string],
+                          "query" => ["NETDISCO_QUERY", :string],
+                          "query_params" => ["NETDISCO_QUERY_PARAMS", :json_array],
+                          "url" => ["NETDISCO_URL", :string],
                           "page_size" => ["NETDISCO_PAGE_SIZE", :integer],
                           "max_pages" => ["NETDISCO_MAX_PAGES", :integer],
                           "max_response_bytes" => ["NETDISCO_MAX_RESPONSE_BYTES", :integer],
@@ -94,8 +97,8 @@ module Net
             end
 
             value.join(",")
-          when :json
-            expected = name == "device_rules" ? Array : Hash
+          when :json, :json_array
+            expected = type == :json_array || name == "device_rules" ? Array : Hash
             raise ArgumentError, "#{section}.#{name} must be a #{expected}" unless value.is_a?(expected)
 
             JSON.generate(value)