net-connector 0.16.1 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8afbc2a37dcb0b9b96be6fd1af171201cb5315803452632f4af2be0db4d5a297
-  data.tar.gz: f11815c48829959e83e89b2bfd37956c4ee9c8eded44c92c200445292fe458c0
+  metadata.gz: 233cb61903727cc01241fcae91e4e540a8bae1462b01210e73aa246fd1a906c9
+  data.tar.gz: 923cdca12fc7c38841743618a0d22527536bee646de7687c26480afbc3265a4a
 SHA512:
-  metadata.gz: 4de68d2427f07acaca0820aac064faeabad7d73a4be81e3286566affb3300a84511955a1f5b721751a488b38651cafe0226a2daecd1bed54d8521f7967b0bd48
-  data.tar.gz: c5d55197568da8f3a7945dd44697ad79d840ca7416408c57b9d605f1e2afb772d0a634eff72102e364e81fee6fdbb526a020300fa8085ac2018b58866cf96b96
+  metadata.gz: d3f2a794edb16faf5429967c4a25ee53a949fef194883cb5aefdc0f9a1a9968ccdf8a539e2f059a4a7d3f28d1e299ab1481c5d66823d555324bb11e2ae10ee0c
+  data.tar.gz: a3ca7a0f4bee7e40861a700063c448f5ac918bf09d7d5b5c87510a664eb024c3fd98cee3ae9a27516d63b59ee8c7aa6af7000231d74acaf24405c2852a7b423f

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 更新记录
 
+## 0.17.0 - 2026-10-22
+
+- Centralize inventory selection and CLI filters in Net::Connector::Inventory; add vendor/model inclusion, exclusion and matching modes.
+
 ## 未发布
 
 ## 0.16.1 - 2026-10-21

data/lib/net/connector/{netdisco → inventory}/address_set.rb

@@ -4,7 +4,7 @@ require "ipaddr"
 
 module Net
   module Connector
-    module Netdisco
+    module Inventory
       # 精确地址用索引，网段和范围只保存端点；绝不展开地址或发起扫描。
       class AddressSet
         # 规范化精确地址并合并同族网段区间，不展开大型地址范围。

data/lib/net/connector/inventory/filters.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "selection"
+
+module Net
+  module Connector
+    module Inventory
+      # 脚本共享筛选词汇和参数；配置来源及优先级仍由宿主决定。
+      module Filters
+        LISTS = {
+          "hosts" => :include_hosts, "exclude_hosts" => :exclude_hosts,
+          "names" => :include_names, "exclude_names" => :exclude_names,
+          "vendors" => :include_vendors, "exclude_vendors" => :exclude_vendors,
+          "models" => :include_models, "exclude_models" => :exclude_models
+        }.freeze
+        MODES = %w[name_match model_match].freeze
+        FIELDS = (LISTS.keys + MODES).freeze
+        FLAGS = {
+          "--hosts LIST" => "hosts", "--exclude-hosts LIST" => "exclude_hosts",
+          "--name LIST" => "names", "--exclude-name LIST" => "exclude_names",
+          "--vendor LIST" => "vendors", "--exclude-vendor LIST" => "exclude_vendors",
+          "--model LIST" => "models", "--exclude-model LIST" => "exclude_models"
+        }.freeze
+
+        def self.selection(values)
+          arguments = LISTS.to_h { |key, argument| [argument, values.fetch(key, [])] }
+          MODES.each { |key| arguments[key.to_sym] = values.fetch(key, :contains) }
+          Selection.new(**arguments)
+        end
+
+        # 每个回调只交付本次参数；追加或覆盖由配置适配器显式处理。
+        def self.add_options(parser, single_host: true, &accept)
+          flags = single_host ? {"--host IP" => "hosts"}.merge(FLAGS) : FLAGS
+          flags.each do |flag, key|
+            parser.on(flag, "筛选已有清单，同类条件取并集，排除优先") do |value|
+              items = value.split(",", -1).map(&:strip)
+              raise OptionParser::InvalidArgument, "filter list contains empty items" if items.empty? || items.any?(&:empty?)
+
+              accept.call(key, items)
+            end
+          end
+          MODES.each do |key|
+            parser.on("--#{key.tr("_", "-")} MODE", %w[contains prefix glob], "匹配方式 contains / prefix / glob") { |value| accept.call(key, value) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/inventory/selection.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "address_set"
+
+module Net
+  module Connector
+    module Inventory
+      # 只筛选已有设备，不识别厂商、不发现地址、不建立连接。
+      class Selection
+        Decision = Data.define(:reasons) do
+          def initialize(reasons:)
+            super(reasons: reasons.dup.freeze)
+          end
+
+          def selected? = reasons.empty?
+        end
+
+        def initialize(include_hosts: [], exclude_hosts: [], include_names: [], exclude_names: [],
+                       include_vendors: [], exclude_vendors: [], include_models: [], exclude_models: [],
+                       name_match: :contains, model_match: :contains)
+          @include_hosts, @exclude_hosts = AddressSet.new(include_hosts), AddressSet.new(exclude_hosts)
+          @names = [text_list(include_names), text_list(exclude_names), mode(name_match)].freeze
+          @models = [text_list(include_models), text_list(exclude_models), mode(model_match)].freeze
+          @vendors = [vendor_list(include_vendors), vendor_list(exclude_vendors)].freeze
+          freeze
+        end
+
+        # 同字段包含取并集，不同字段取交集；排除优先，原因不携带设备正文。
+        def evaluate(host:, vendor: nil, name: nil, model: nil)
+          reasons = []
+          if @exclude_hosts.include?(host)
+            reasons << :host_excluded
+          elsif !@include_hosts.empty? && !@include_hosts.include?(host)
+            reasons << :host_not_included
+          end
+          vendor = vendor.to_s
+          if @vendors.last.include?(vendor)
+            reasons << :vendor_excluded
+          elsif !@vendors.first.empty? && !@vendors.first.include?(vendor)
+            reasons << :vendor_not_included
+          end
+          reasons << text_reason(:name, name, @names)
+          reasons << text_reason(:model, model, @models)
+          Decision.new(reasons: reasons.compact)
+        end
+
+        def selected?(host, vendor = nil, name: nil, model: nil)
+          evaluate(host: host, vendor: vendor, name: name, model: model).selected?
+        end
+
+        def inspect = "#<#{self.class}>"
+        alias to_s inspect
+
+        private
+
+        def mode(value)
+          unless (value.is_a?(String) || value.is_a?(Symbol)) && %w[contains prefix glob].include?(value.to_s)
+            raise ArgumentError, "match mode must be contains, prefix or glob"
+          end
+          value.to_sym
+        end
+
+        def text_list(values)
+          unless values.is_a?(Array) && values.all? { |v| v.is_a?(String) && v.valid_encoding? && !v.strip.empty? && !/[\x00-\x1f\x7f]/.match?(v) }
+            raise ArgumentError, "filters must be arrays of nonempty text"
+          end
+          values.map { |v| v.downcase.freeze }.uniq.freeze
+        end
+
+        def vendor_list(values)
+          unless values.is_a?(Array) && values.all? { |v| v.is_a?(String) || v.is_a?(Symbol) }
+            raise ArgumentError, "vendors must be strings or symbols"
+          end
+          text_list(values.map(&:to_s))
+        end
+
+        def text_reason(field, value, rules)
+          includes, excludes, match = rules
+          value = value&.to_s&.encode("UTF-8", invalid: :replace, undef: :replace, replace: "")&.downcase
+          return :"#{field}_excluded" if value && excludes.any? { |pattern| matches?(pattern, value, match) }
+          return :"#{field}_not_included" if !includes.empty? && (!value || includes.none? { |pattern| matches?(pattern, value, match) })
+
+          nil
+        end
+
+        def matches?(pattern, value, match)
+          case match
+          when :contains then value.include?(pattern)
+          when :prefix then value.start_with?(pattern)
+          when :glob then File.fnmatch?(pattern, value)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -6,6 +6,7 @@ require_relative "../planner"
 require_relative "../config"
 require_relative "../../config"
 require_relative "help"
+require_relative "../../inventory/filters"
 
 module Net
   module Connector
@@ -208,25 +209,16 @@ module Net
 
           # 同类 CLI 筛选替换 YAML；重复参数在本次调用内合并，绝不把范围展开为地址列表。
           def self.add_filters(opts, values)
-            {
-              "--hosts PATTERNS" => ["NC_INCLUDE_HOSTS", "包含地址、网段或范围，逗号分隔"],
-              "--exclude-hosts PATTERNS" => ["NC_EXCLUDE_HOSTS", "排除地址、网段或范围"],
-              "--name PATTERNS" => ["NC_INCLUDE_NAMES", "包含设备名称，可重复或逗号分隔"],
-              "--exclude-name PATTERNS" => ["NC_EXCLUDE_NAMES", "排除设备名称，可重复或逗号分隔"],
-              "--vendor NAMES" => ["NC_INCLUDE_VENDORS", "包含连接器厂商名"],
-              "--exclude-vendor NAMES" => ["NC_EXCLUDE_VENDORS", "排除连接器厂商名"]
-            }.each do |flag, (key, description)|
-              opts.on(flag, description) do |value|
-                items = value.split(",", -1).map(&:strip)
-                raise OptionParser::InvalidArgument if items.empty? || items.any?(&:empty?)
-
-                previous = values[:environment][key]&.split(",") || []
-                values[:environment][key] = (previous + items).uniq.join(",")
+            Net::Connector::Inventory::Filters.add_options(opts, single_host: false) do |key, value|
+              field = Net::Connector::Inventory::Filters::LISTS.fetch(key, key).to_s
+              environment_key = "NC_#{field.upcase}"
+              if value.is_a?(Array)
+                previous = values[:environment][environment_key]&.split(",") || []
+                values[:environment][environment_key] = (previous + value).uniq.join(",")
+              else
+                values[:environment][environment_key] = value
               end
             end
-            opts.on("--name-match MODE", %w[contains prefix glob], "名称匹配方式：contains / prefix / glob") do |value|
-              values[:environment]["NC_NAME_MATCH"] = value
-            end
             opts.on("--host IP", "选择单台设备，可重复") do |value|
               raise OptionParser::InvalidArgument if value.empty? || value.match?(/[\/,]/)
 

data/lib/net/connector/netdisco/config/defaults.rb

@@ -15,7 +15,8 @@ module Net
                               "cache_directory" => "./.cache/net-connector/inventory", "inventory_timeout" => 300,
                               "page_size" => 500, "allow_insecure_http" => false },
               "inventory" => { "include_hosts" => [], "exclude_hosts" => [], "include_names" => [], "exclude_names" => [],
-                               "include_vendors" => [], "exclude_vendors" => [], "name_match" => "contains" },
+                               "include_vendors" => [], "exclude_vendors" => [], "name_match" => "contains",
+                               "include_models" => [], "exclude_models" => [], "model_match" => "contains" },
               "ssh" => { "protocol" => "ssh", "host_key_policy" => "accept_new", "log_level" => "info" },
               "backup" => { "directory" => directory || "./backups", "parallel" => 4 }
             }

data/lib/net/connector/netdisco/config/initializer.rb

@@ -102,10 +102,11 @@ module Net
             if document.dig("netdisco", "source") == "http"
               field(document, "netdisco", "url", "清单 URL", mode.nil? ? "https://netdisco.example.invalid" : nil)
             end
-            %w[include_hosts exclude_hosts include_names exclude_names].each do |key|
+            %w[include_hosts exclude_hosts include_names exclude_names include_models exclude_models].each do |key|
               field(document, "inventory", key, key, [], list: true)
             end
             field(document, "inventory", "name_match", "名称匹配 contains/prefix/glob", "contains")
+            field(document, "inventory", "model_match", "型号匹配 contains/prefix/glob", "contains")
             %w[include_vendors exclude_vendors].each { |key| field(document, "inventory", key, key, [], list: true) }
             if document.key?("topology")
               field(document, "topology", "parallel", "拓扑并发数 1..500", inherited_parallel)

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

@@ -45,6 +45,9 @@ module Net
                            "include_names" => ["NC_INCLUDE_NAMES", :list],
                            "exclude_names" => ["NC_EXCLUDE_NAMES", :list],
                            "name_match" => ["NC_NAME_MATCH", :string],
+                           "include_models" => ["NC_INCLUDE_MODELS", :list],
+                           "exclude_models" => ["NC_EXCLUDE_MODELS", :list],
+                           "model_match" => ["NC_MODEL_MATCH", :string],
                            "exclude_vendors" => ["NC_EXCLUDE_VENDORS", :list],
                            "include_vendors" => ["NC_INCLUDE_VENDORS", :list],
                            "vendor_overrides" => ["NC_VENDOR_OVERRIDES", :json],

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

@@ -38,7 +38,7 @@ module Net
           end
           vendor = rules.resolve(row)
           name = [row["name"], row["dns"]].find { |value| value && !value.strip.empty? }
-          issue ||= :filtered unless rules.selected?(host, vendor, name: name&.strip)
+          issue ||= :filtered unless rules.selected?(host, vendor, name: name&.strip, model: row["model"])
           issue ||= :unsupported_vendor unless vendor
           new(host: host, source_ip: source_ip, name: name&.strip, vendor: vendor,
               source_vendor: row["vendor"], model: row["model"], os: row["os"],

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

@@ -2,7 +2,7 @@
 
 require "ipaddr"
 require_relative "../../connector"
-require_relative "address_set"
+require_relative "../inventory/selection"
 
 module Net
   module Connector
@@ -12,17 +12,11 @@ module Net
         # 校验并保存清单过滤和厂商映射规则。
         def initialize(include_hosts: [], exclude_hosts: [], include_vendors: [], vendor_overrides: {},
                        host_overrides: {}, mappings: [], include_names: [], exclude_names: [],
-                       name_match: :contains, exclude_vendors: [])
-          @include_hosts = AddressSet.new(include_hosts)
-          @exclude_hosts = AddressSet.new(exclude_hosts)
-          @include_vendors = vendor_list(include_vendors)
-          @exclude_vendors = vendor_list(exclude_vendors)
-          @include_names = name_list(include_names)
-          @exclude_names = name_list(exclude_names)
-          unless (name_match.is_a?(String) || name_match.is_a?(Symbol)) && %w[contains prefix glob].include?(name_match.to_s)
-            raise ArgumentError, "name_match must be contains, prefix or glob"
-          end
-          @name_match = name_match.to_sym
+                       name_match: :contains, exclude_vendors: [], include_models: [], exclude_models: [], model_match: :contains)
+          @selection = Net::Connector::Inventory::Selection.new(include_hosts: include_hosts, exclude_hosts: exclude_hosts,
+            include_names: include_names, exclude_names: exclude_names, name_match: name_match,
+            include_vendors: vendor_list(include_vendors), exclude_vendors: vendor_list(exclude_vendors),
+            include_models: include_models, exclude_models: exclude_models, model_match: model_match)
           @vendor_overrides = vendor_mapping(vendor_overrides)
           @host_overrides = host_mapping(host_overrides)
           @mappings = device_mappings(mappings)
@@ -153,19 +147,8 @@ module Net
         end
 
         # 判断设备是否通过地址和厂商过滤。
-        def selected?(host, vendor, name: nil)
-          return false if @exclude_hosts.include?(host)
-          return false if !@include_hosts.empty? && !@include_hosts.include?(host)
-          return false if @exclude_vendors.include?(vendor)
-          return false if !@include_vendors.empty? && !@include_vendors.include?(vendor)
-
-          return true if @include_names.empty? && @exclude_names.empty?
-
-          value = name.to_s.encode("UTF-8", invalid: :replace, undef: :replace, replace: "").downcase
-          return false if @exclude_names.any? { |pattern| name_matches?(pattern, value) }
-          return false if !@include_names.empty? && @include_names.none? { |pattern| name_matches?(pattern, value) }
-
-          true
+        def selected?(host, vendor, name: nil, model: nil)
+          @selection.selected?(host, vendor, name: name, model: model)
         end
 
         private
@@ -176,23 +159,6 @@ module Net
           wireless ? :h3c_wireless : :h3c
         end
 
-        # 校验名称过滤项为有效非空文本，统一小写并去重冻结。
-        def name_list(values)
-          unless values.is_a?(Array) && values.all? { |value| value.is_a?(String) && !value.strip.empty? && value.valid_encoding? }
-            raise ArgumentError, "name filters must be arrays of nonempty strings"
-          end
-          values.map { |value| value.downcase.freeze }.uniq.freeze
-        end
-
-        # 按包含、前缀或通配符模式匹配已规范化的设备名称。
-        def name_matches?(pattern, value)
-          case @name_match
-          when :contains then value.include?(pattern)
-          when :prefix then value.start_with?(pattern)
-          when :glob then File.fnmatch?(pattern, value)
-          end
-        end
-
         # 将设备标签转为便于匹配的小写词串。
         def normalize(value) = value.to_s.downcase.gsub(/[^a-z0-9]+/, " ").strip
       end

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

@@ -190,6 +190,8 @@ module Net
                     exclude_vendors: list("NC_EXCLUDE_VENDORS"),
                     include_names: list("NC_INCLUDE_NAMES"), exclude_names: list("NC_EXCLUDE_NAMES"),
                     name_match: raw("NC_NAME_MATCH", "contains"),
+                    include_models: list("NC_INCLUDE_MODELS"), exclude_models: list("NC_EXCLUDE_MODELS"),
+                    model_match: raw("NC_MODEL_MATCH", "contains"),
                     vendor_overrides: json("NC_VENDOR_OVERRIDES", {}),
                     host_overrides: json("NC_HOST_OVERRIDES", {}),
                     mappings: json("NC_DEVICE_RULES", []))
@@ -381,6 +383,8 @@ module Net
                          exclude_vendors: list("NC_EXCLUDE_VENDORS"),
                          include_names: list("NC_INCLUDE_NAMES"), exclude_names: list("NC_EXCLUDE_NAMES"),
                          name_match: raw("NC_NAME_MATCH", "contains"),
+                         include_models: list("NC_INCLUDE_MODELS"), exclude_models: list("NC_EXCLUDE_MODELS"),
+                         model_match: raw("NC_MODEL_MATCH", "contains"),
                          vendor_overrides: json("NC_VENDOR_OVERRIDES", {}),
                          host_overrides: json("NC_HOST_OVERRIDES", {}),
                          device_rules: json("NC_DEVICE_RULES", []) },

data/lib/net/connector/version.rb

@@ -3,6 +3,6 @@
 module Net
   module Connector
     # gemspec、CLI 与发布工具共用此版本，运行时读取不触发设备依赖加载。
-    VERSION = "0.16.1"
+    VERSION = "0.17.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.16.1
+  version: 0.17.0
 platform: ruby
 authors:
 - net-connector contributors
@@ -417,8 +417,10 @@ files:
 - lib/net/connector/engine/terminal/renderer.rb
 - lib/net/connector/engine/terminal/text.rb
 - lib/net/connector/engine/transports.rb
+- lib/net/connector/inventory/address_set.rb
+- lib/net/connector/inventory/filters.rb
+- lib/net/connector/inventory/selection.rb
 - lib/net/connector/netdisco.rb
-- lib/net/connector/netdisco/address_set.rb
 - lib/net/connector/netdisco/batch.rb
 - lib/net/connector/netdisco/cli.rb
 - lib/net/connector/netdisco/cli/backup.rb