network-infra-utility 0.6.0 → 0.8.3

data/service/geoquery/cache.rb

@@ -0,0 +1,78 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+require "json"
+
+module GeoQuery
+  # ------------------------------------------------------------------
+  # JSON 文件缓存 — 移植自 ip_geo_lookup.py 的缓存设计
+  # ------------------------------------------------------------------
+  # 结构: { "ip" => { result..., "ts" => 1716000000 } }
+  # 线程安全 (Mutex); 不可达 (unreachable) 类结果不写入缓存。
+  class Cache
+    attr_reader :path
+
+    # 默认缓存根目录: ENV["NGEO_CACHE_DIR"] || ~/.network-infra-utility/
+    def self.default_dir
+      dir = ENV["NGEO_CACHE_DIR"].to_s
+      dir.empty? ? File.join(Dir.home, ".network-infra-utility") : File.expand_path(dir)
+    end
+
+    def initialize(path)
+      @path = path
+      @lock = Mutex.new
+      @data = load
+    end
+
+    # 命中返回结果 Hash (附加 "cached" => true), 未命中返回 nil
+    def get(ip)
+      @lock.synchronize do
+        hit = @data[ip]
+        hit ? hit.merge("cached" => true) : nil
+      end
+    end
+
+    # 写入一条 (网络类不可达状态不落盘, 下次重查)
+    def put(ip, result)
+      return if result["state"] == "unreachable"
+      @lock.synchronize do
+        @data[ip] = result.merge("ts" => Time.now.to_i)
+      end
+    end
+
+    def save
+      @lock.synchronize do
+        dir = File.dirname(@path)
+        require "fileutils"
+        FileUtils.mkdir_p(dir)
+        File.binwrite(@path, JSON.pretty_generate(@data))
+      end
+      @path
+    end
+
+    def size
+      @lock.synchronize { @data.size }
+    end
+
+    def stats
+      loaded = @lock.synchronize { @data.dup }
+      states = Hash.new(0)
+      loaded.each_value { |v| states[v["state"]] += 1 }
+      {
+        "total" => loaded.size,
+        "file" => @path,
+        "size_kb" => File.exist?(@path) ? (File.size(@path) / 1024.0).round(1) : 0,
+        "states" => states,
+      }
+    end
+
+    private
+
+    def load
+      return {} unless File.exist?(@path)
+      JSON.parse(File.binread(@path))
+    rescue JSON::ParserError, Errno::ENOENT
+      {}
+    end
+  end
+end

data/service/geoquery/geo_cache.rb

@@ -0,0 +1,233 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+require "json"
+require_relative "normalize"   # GeoQuery.valid_ip? (服务端可单独加载本文件)
+
+module GeoQuery
+  # ------------------------------------------------------------------
+  # GEO_CACHE 外带缓存目录 — geocacheXXXXXXXX.json 文件集的读取/写入/合并
+  # ------------------------------------------------------------------
+  # 文件命名: geocacheYYYYMMDD.json (XXXXXXXX 为 8 位日期时间标签)
+  # 文件格式: { "ip" => { 统一 schema 结果, "ts" => 写入时间戳 } }
+  #           (与 ngeo-cache.json 同构, 便于 -m 合并与跨机拷贝)
+  #
+  # 三个角色:
+  #   1. 查询源 — lookup(ip) 遍历目录内全部缓存文件, 返回该 IP 的定位信息
+  #      (目录内文件增删改自动感知, 服务端/客户端均无需重启)
+  #   2. 产出   — put_batch(results) 把查询结果合并写入当天的 geocacheYYYYMMDD.json
+  #      (同一天多次产出自动归并到同一文件, 同 IP 以新结果覆盖)
+  #   3. 整理   — merge! 把目录内全部缓存文件合并为一个新的 geocacheYYYYMMDD.json
+  #      (同 IP 冲突取 ts 最新; 合并生成时间即新文件的时间标签)
+  #
+  # 命令行入口: bin/ngeo-get (-a 指定目录 / -c 产出 / -nc 不产出 / -m 合并)
+  # 服务端入口: bin/geo-api -a (本地库查不到时兜底, 详见 service/geodb/api.rb)
+  class GeoCache
+    # 缓存文件名: geocache + 8 位日期标签 + .json
+    FILE_RE = /\Ageocache\d{8}\.json\z/.freeze
+    # -p 顺位参数的合法源
+    ORDER_SOURCES = %w[cache local internet].freeze
+    # 可缓存状态 (与 GeoQuery::CACHEABLE_STATES 保持一致;
+    # 独立定义以支持 geodb 服务端单独加载本文件, 不依赖 geoquery.rb)
+    CACHEABLE_STATES = %w[local merged online empty cache].freeze
+    # 归属字段白名单 (产出/转换时提取)
+    FIELDS = %w[country province city isp asn asn_org network usage].freeze
+
+    attr_reader :dir
+
+    # 默认产出目录: ENV["GEO_CACHE_DIR"] || 当前目录
+    def self.default_dir
+      d = ENV["GEO_CACHE_DIR"].to_s
+      d.empty? ? Dir.pwd : File.expand_path(d)
+    end
+
+    # 解析 -p 顺位参数 ("cache,local,internet" / "local internet cache" 等):
+    # 返回源名数组; 非法 (含未知源 / 重复 / 为空) 返回 nil
+    def self.parse_order(str)
+      parts = str.to_s.split(/[,\s]+/).map(&:strip).reject(&:empty?)
+      return nil if parts.empty?
+      return nil unless parts.all? { |p| ORDER_SOURCES.include?(p) }
+      return nil unless parts.uniq.size == parts.size
+      parts
+    end
+
+    # 统一 schema → geo-api 接口的 GeoLite2 风格响应 (服务端缓存命中时用)。
+    # 对应字段缺失时返回 nil (视作该接口无数据, 由调用方继续下一数据源)。
+    def self.to_geolite(kind, hit)
+      case kind
+      when :asn
+        return nil if hit["asn"].to_s.empty?
+        {
+          "network" => hit["network"].to_s,
+          "autonomous_system_number" => hit["asn"].to_s,
+          "autonomous_system_organization" => hit["asn_org"].to_s,
+          "cached" => true,
+        }
+      when :city
+        return nil if hit["province"].to_s.empty? && hit["city"].to_s.empty?
+        g = {}
+        g["country_name"] = hit["country"].to_s unless hit["country"].to_s.empty?
+        g["subdivision_1_name"] = hit["province"].to_s unless hit["province"].to_s.empty?
+        g["city_namezh"] = hit["city"].to_s unless hit["city"].to_s.empty?
+        { "network" => hit["network"].to_s, "geoname" => g, "cached" => true }
+      when :country
+        return nil if hit["country"].to_s.empty?
+        {
+          "network" => hit["network"].to_s,
+          "geoname" => { "country_name" => hit["country"].to_s },
+          "cached" => true,
+        }
+      end
+    end
+
+    def initialize(dir)
+      @dir = File.expand_path(dir.to_s)
+      @files = {}   # path => { mtime: Float, data: Hash }
+      @lock = Mutex.new
+    end
+
+    # 查询: 遍历目录内全部缓存文件, 返回该 IP 的记录 (附加 "cached" => true),
+    # 未命中返回 nil。多文件命中时取 ts 最新。
+    def lookup(ip)
+      @lock.synchronize do
+        refresh!
+        best = nil
+        @files.each_value do |f|
+          hit = f[:data][ip]
+          next unless hit.is_a?(Hash)
+          next if best && hit["ts"].to_i <= best["ts"].to_i
+          best = hit
+        end
+        best ? best.merge("cached" => true) : nil
+      end
+    end
+
+    # 产出: 把查询结果 (统一 schema Hash 数组, 或 {ip=>result} Hash)
+    # 合并写入当天缓存文件 geocacheYYYYMMDD.json。
+    # 仅落盘可缓存状态 (local/merged/online/empty/cache); 同 IP 以本次结果覆盖。
+    # 返回 { "file" => 路径, "entries" => 写入条数 }; 无可写内容返回 nil。
+    def put_batch(results)
+      entries = normalize_entries(results)
+      return nil if entries.empty?
+      @lock.synchronize do
+        path = File.join(@dir, "geocache#{Time.now.strftime('%Y%m%d')}.json")
+        data = read_file(path)
+        entries.each { |ip, r| data[ip] = r.merge("ts" => Time.now.to_i) }
+        write_file(path, data)
+        { "file" => path, "entries" => entries.size }
+      end
+    end
+
+    # 整理: 合并目录内全部缓存文件为一个新的 geocacheYYYYMMDD.json
+    # (合并生成时间即时间标签; 同 IP 冲突取 ts 最新)。
+    # 返回 { "files" => 合并文件数, "entries" => 条目数, "output" => 输出路径 }。
+    def merge!
+      @lock.synchronize do
+        refresh!
+        source_count = @files.size   # 写入前统计 (输出文件可能覆盖同名源文件)
+        merged = {}
+        @files.each_value do |f|
+          f[:data].each do |ip, r|
+            next unless r.is_a?(Hash)
+            cur = merged[ip]
+            merged[ip] = r if cur.nil? || r["ts"].to_i >= cur["ts"].to_i
+          end
+        end
+        path = File.join(@dir, "geocache#{Time.now.strftime('%Y%m%d')}.json")
+        write_file(path, merged)
+        { "files" => source_count, "entries" => merged.size, "output" => path }
+      end
+    end
+
+    # 目录统计: { "dir", "files", "entries", "states" }
+    def stats
+      @lock.synchronize do
+        refresh!
+        states = Hash.new(0)
+        @files.each_value do |f|
+          f[:data].each_value { |r| states[r["state"]] += 1 if r.is_a?(Hash) }
+        end
+        {
+          "dir" => @dir,
+          "files" => @files.size,
+          "entries" => @files.values.sum { |f| f[:data].size },
+          "states" => states,
+        }
+      end
+    end
+
+    private
+
+    # 目录内全部合法缓存文件 (按文件名排序 = 按日期标签排序)
+    def cache_files
+      return [] unless File.directory?(@dir)
+      Dir.glob(File.join(@dir, "geocache*.json"))
+         .select { |p| FILE_RE =~ File.basename(p) }
+         .sort
+    end
+
+    # 感知目录变化: 新增/修改的文件重载, 已删除的移除
+    def refresh!
+      current = {}
+      cache_files.each do |path|
+        mtime = File.mtime(path).to_f
+        prev = @files[path]
+        current[path] = if prev && prev[:mtime] == mtime
+                          prev
+                        else
+                          { mtime: mtime, data: read_file(path) }
+                        end
+      end
+      @files.replace(current)
+    end
+
+    def read_file(path)
+      return {} unless File.exist?(path)
+      raw = File.binread(path)
+      raw = raw.delete_prefix("\xEF\xBB\xBF".b)   # 容错 UTF-8 BOM (Windows 记事本)
+      data = JSON.parse(raw)
+      data.is_a?(Hash) ? data : {}
+    rescue JSON::ParserError, Errno::ENOENT
+      {}
+    end
+
+    def write_file(path, data)
+      require "fileutils"
+      FileUtils.mkdir_p(@dir)
+      tmp = "#{path}.tmp#{Process.pid}"
+      File.binwrite(tmp, JSON.pretty_generate(data))
+      File.rename(tmp, path)
+      @files[path] = { mtime: File.mtime(path).to_f, data: data }
+      path
+    end
+
+    # 产出内容规整: Hash 数组 (取 ip 字段) 或 {ip=>result} Hash
+    # 仅保留 ip 合法且状态可缓存的条目
+    def normalize_entries(results)
+      entries = {}
+      if results.is_a?(Hash)
+        results.each do |ip, r|
+          next unless r.is_a?(Hash) && cacheable?(r) && GeoQuery.valid_ip?(ip)
+          entries[ip.to_s] = pick_fields(r)
+        end
+      elsif results.is_a?(Array)
+        results.each do |r|
+          next unless r.is_a?(Hash)
+          ip = r["ip"].to_s
+          next unless cacheable?(r) && GeoQuery.valid_ip?(ip)
+          entries[ip] = pick_fields(r)
+        end
+      end
+      entries
+    end
+
+    def cacheable?(result)
+      CACHEABLE_STATES.include?(result["state"].to_s)
+    end
+
+    # 提取归属字段 (剔除 state/message/source/sources/ts/cached 等元数据)
+    def pick_fields(r)
+      r.select { |k, _| FIELDS.include?(k) }
+    end
+  end
+end

data/service/geoquery/geoquery.rb

@@ -0,0 +1,327 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+# GeoQuery — IP 归属综合查询服务 (GEO_CACHE 缓存 + 本地 geo-api + 互联网 ip-api.com)
+#
+# 命令行入口: bin/gen-get (纯互联网) / bin/ngeo-get (缓存+本地+互联网综合)
+# 详见同目录 GeoQuery.md。
+#
+# 查询模型 (ngeo, 三源顺位编排 — 顺位即优先级, 满意即停, 字段叠加):
+#
+#   1. 会话缓存 (ngeo-cache.json) 命中 → 直接返回
+#   2. 按 -p 顺位逐源查询 (默认 cache → local → internet):
+#      - cache    GEO_CACHE 外带缓存目录 (geocacheXXXXXXXX.json, bin/ngeo-get -a)
+#      - local    本地 geo-api 服务 (GeoLite2)
+#      - internet 互联网 ip-api.com (限速 + 熔断保护)
+#   3. 每源结果按顺位折叠: 先查的源字段优先, 后查的补空缺
+#   4. 折叠后归属满意 (省/市/ASN 齐全) → 提前终止, 不再查后续源
+#   5. 全部源查完仍不满意 → 组装终态 (叠加/部分/空/不可达)
+#
+# 结果状态 (state) 按可信度排序 — 体现 空结果 < 部分 < 缓存 < 实时 < 叠加:
+#
+#   unreachable   各源均无结果且有不联通 (空结果状态, 最低)
+#   local-partial 本地部分结果, 无更多补充 (保留本地字段)
+#   cache-partial 缓存部分结果, 无更多补充 (保留缓存字段)
+#   empty         各源均确认无归属 (如私有/保留地址)
+#   cache         缓存命中且满意
+#   local         本地结果满意 (省/市/ASN 齐全)
+#   online        纯互联网结果
+#   merged        多源叠加综合 (最高)
+module GeoQuery
+  autoload :Cache,        File.expand_path("cache",     __dir__)
+  autoload :GeoCache,     File.expand_path("geo_cache", __dir__)
+  autoload :LocalClient,  File.expand_path("local",     __dir__)
+  autoload :Merge,        File.expand_path("merge",     __dir__)
+  autoload :Normalize,    File.expand_path("normalize", __dir__)
+  autoload :OnlineClient, File.expand_path("online",    __dir__)
+end
+
+module GeoQuery
+  # 可缓存的结果状态 (unreachable / local-partial / cache-partial 不落盘,
+  # 下次重查以便互联网恢复后自动补全)
+  CACHEABLE_STATES = %w[local merged online empty cache].freeze
+end
+
+class GeoQuery::NGeo
+  # 满意度判定字段: 省份 / 城市 / ASN (ASN 齐则用途可推断)
+  SATISFY_FIELDS = %w[province city asn].freeze
+
+  # 互联网熔断: 连续失败 N 次后, COOLDOWN 秒内跳过在线查询
+  BREAKER_THRESHOLD = 3
+  BREAKER_COOLDOWN  = 60
+
+  # 默认查询顺位: 缓存 → 本地 → 互联网
+  DEFAULT_ORDER = %w[cache local internet].freeze
+  # 合法顺位源 (与 GeoQuery::GeoCache::ORDER_SOURCES 一致)
+  ORDER_SOURCES = %w[cache local internet].freeze
+  # sources 键 → 结果来源标注
+  SRC_LABEL = {
+    "cache" => "geo-cache",   # GEO_CACHE 外带缓存
+    "local" => "geo-get",     # 本地 geo-api
+    "online" => "gen-get",    # 互联网 ip-api.com
+  }.freeze
+
+  attr_reader :local, :online, :cache, :geo_cache, :order
+
+  def initialize(geoapi_base: nil, api: nil, timeout: 10,
+                 cache_dir: nil, cache_file: nil,
+                 geo_cache_dir: nil, order: DEFAULT_ORDER)
+    base = geoapi_base || ENV["GEO_API_BASE"] || GeoQuery::LocalClient::DEFAULT_BASE
+    @local  = GeoQuery::LocalClient.new(base: base)
+    @online = GeoQuery::OnlineClient.new(api: api, timeout: timeout)
+    dir = cache_dir || GeoQuery::Cache.default_dir
+    @cache = GeoQuery::Cache.new(cache_file || File.join(dir, "ngeo-cache.json"))
+    @geo_cache = geo_cache_dir ? GeoQuery::GeoCache.new(geo_cache_dir) : nil
+    @order = normalize_order(order)
+    @breaker_mutex = Mutex.new
+    @failures = 0
+    @breaker_until = nil
+  end
+
+  # 综合查询单个 IP。
+  #   refresh:  忽略缓存强制重查 (会话缓存与 GEO_CACHE 均跳过)
+  #   no_local: 跳过本地 geo-api
+  #   save:     是否把结果写入会话缓存 (默认 true)
+  # 查询产出 (geocacheYYYYMMDD.json) 由调用方用 GeoQuery::GeoCache#put_batch 落盘。
+  def lookup(ip, refresh: false, no_local: false, save: true)
+    ip = ip.to_s.strip
+    return invalid_result(ip, "IP 不合法") unless GeoQuery.valid_ip?(ip)
+
+    hit = @cache.get(ip) unless refresh
+    return hit if hit
+
+    result = chain_lookup(ip, refresh: refresh, no_local: no_local)
+    @cache.put(ip, result) if save && GeoQuery::CACHEABLE_STATES.include?(result["state"])
+    result
+  end
+
+  def save_cache
+    @cache.save
+  end
+
+  private
+
+  # ---- 三源顺位编排 ---------------------------------------------------------
+
+  def chain_lookup(ip, refresh: false, no_local: false)
+    plan = planned_order(refresh: refresh, no_local: no_local)
+    acc = nil
+    sources = {}
+
+    # 不参与本次查询的源, 仍按原输出契约标注
+    if no_local && @order.include?("local")
+      sources["local"] = { "state" => "unavailable", "message" => "本地查询已跳过 (--no-local)" }
+    end
+    if refresh && @geo_cache && @order.include?("cache")
+      sources["cache"] = { "state" => "skipped", "message" => "已忽略缓存强制重查 (--refresh)" }
+    end
+
+    plan.each do |src|
+      r = query_source(src, ip)
+      key = src_key(src)
+      sources[key] = note_for(key, r)
+      next unless r["state"] == "ok"
+      acc = fold(acc, r)
+      break if satisfied_fields?(acc)
+    end
+
+    # 满意提前终止后, 顺位中剩余未查的源 → skipped
+    plan.each do |src|
+      key = src_key(src)
+      sources[key] = { "state" => "skipped" } unless sources.key?(key)
+    end
+
+    assemble(ip, acc, sources)
+  end
+
+  # 实际查询的源列表: 顺位中剔除不可用源
+  # (无 GEO_CACHE 目录 → cache 源不存在; refresh → 跳过缓存; no_local → 跳过本地)
+  def planned_order(refresh: false, no_local: false)
+    @order.reject do |src|
+      (src == "cache" && (@geo_cache.nil? || refresh)) ||
+        (src == "local" && no_local)
+    end
+  end
+
+  def query_source(src, ip)
+    case src
+    when "cache"    then query_cache(ip)
+    when "local"    then @local.lookup(ip)
+    when "internet" then online_with_breaker { @online.lookup(ip) }
+    end
+  end
+
+  # GEO_CACHE 缓存查询: 命中记录保留产出时的归属字段,
+  # 有归属 → 规整为 ok 参与折叠; empty → 确认无归属; 未命中 → miss (继续下一源)
+  def query_cache(ip)
+    hit = @geo_cache ? @geo_cache.lookup(ip) : nil
+    return cache_base(ip, "miss", "GEO_CACHE 缓存未命中") unless hit
+    if hit["state"] == "empty"
+      cache_base(ip, "empty", "缓存确认无归属")
+    else
+      cache_base(ip, "ok", "").merge(pick_fields(hit))
+    end
+  end
+
+  def cache_base(ip, state, message)
+    {
+      "ip" => ip, "state" => state, "message" => message,
+      "country" => "", "province" => "", "city" => "",
+      "isp" => "", "asn" => "", "asn_org" => "", "network" => "",
+      "usage" => "", "source" => "geo-cache", "cached" => true,
+    }
+  end
+
+  # 从缓存记录提取归属字段 (剔除 state/message/source/sources/ts/cached)
+  def pick_fields(hit)
+    hit.select { |k, _| GeoQuery::GeoCache::FIELDS.include?(k) }
+  end
+
+  # ---- 折叠 / 终态组装 ------------------------------------------------------
+
+  # acc 优先, r 补空缺 (顺位即优先级)
+  def fold(acc, r)
+    return r.dup unless acc
+    GeoQuery::Merge.fields(acc, r)
+  end
+
+  def assemble(ip, acc, sources)
+    ok_srcs = sources.select { |_, n| n["state"] == "ok" }.keys
+    fields = acc || {}
+
+    state =
+      if ok_srcs.empty?
+        # 无任何归属字段: 有源确认无归属且无不联通 → empty, 否则 unreachable
+        has_empty = sources.values.any? { |n| n["state"] == "empty" }
+        net_down  = sources.values.any? { |n| n["state"] == "unreachable" }
+        (has_empty && !net_down) ? "empty" : "unreachable"
+      elsif ok_srcs.size == 1
+        s = ok_srcs.first
+        if satisfied_fields?(fields)
+          { "cache" => "cache", "local" => "local", "online" => "online" }.fetch(s, "merged")
+        elsif s == "local"
+          "local-partial"
+        elsif s == "cache"
+          "cache-partial"
+        else
+          "online"   # 互联网结果即使不满意仍为 online (对齐原模型)
+        end
+      else
+        "merged"
+      end
+
+    {
+      "ip" => ip,
+      "state" => state,
+      "message" => state_message(state, sources),
+      "country" => fields["country"].to_s,
+      "province" => fields["province"].to_s,
+      "city" => fields["city"].to_s,
+      "isp" => GeoQuery::Normalize.isp_from_asn(fields["asn_org"].to_s),
+      "asn" => fields["asn"].to_s,
+      "asn_org" => fields["asn_org"].to_s,
+      "network" => fields["network"].to_s,
+      "usage" => fields["usage"].to_s,
+      "source" => ok_srcs.empty? ? "ngeo" : "ngeo(#{ok_srcs.map { |s| SRC_LABEL[s] }.join('+')})",
+      "sources" => sources,
+    }.tap do |r|
+      r["cached"] = true if ok_srcs.include?("cache")
+    end
+  end
+
+  # 各源查询说明 → 终态 message
+  def state_message(state, sources)
+    online = sources["online"]
+    case state
+    when "unreachable"
+      if online && online["state"] == "unreachable"
+        "互联网查询不可达: #{online['message']}"
+      else
+        "各数据源均无结果 (本地无数据/GEO_CACHE 未命中)"
+      end
+    when "empty"
+      if online && online["state"] == "empty"
+        "各数据源均确认无归属 (#{online['message']})"
+      else
+        "各数据源均确认无归属"
+      end
+    when "local-partial", "cache-partial"
+      if online && online["state"] == "unreachable"
+        "互联网查询不可达: #{online['message']}"
+      elsif online && online["state"] == "empty"
+        "互联网确认无归属 (#{online['message']})"
+      else
+        "其余数据源无补充结果"
+      end
+    else
+      ""
+    end
+  end
+
+  def note_for(key, client_result)
+    note = { "state" => client_result["state"] }
+    unless client_result["message"].to_s.empty?
+      note["message"] = client_result["message"]
+    end
+    if client_result["state"] == "ok" && key != "online"
+      note["verdict"] = satisfied_fields?(client_result) ? "满意" : "不满意"
+    end
+    note
+  end
+
+  def invalid_result(ip, message)
+    {
+      "ip" => ip, "state" => "invalid", "message" => message,
+      "country" => "", "province" => "", "city" => "",
+      "isp" => "", "asn" => "", "asn_org" => "", "network" => "",
+      "usage" => "", "source" => "ngeo", "sources" => {},
+    }
+  end
+
+  # ---- 满意度 / 熔断 --------------------------------------------------------
+
+  # 满意 = 省份、城市、ASN 全部非空 (ASN 有则用途可推断)
+  def satisfied_fields?(result)
+    SATISFY_FIELDS.all? { |f| !result[f].to_s.empty? }
+  end
+
+  # 顺位参数规整: String (经 GeoCache.parse_order) 或 Array;
+  # 非法时回退默认顺位
+  def normalize_order(order)
+    parts = order.is_a?(String) ? GeoQuery::GeoCache.parse_order(order) : order
+    unless parts.is_a?(Array) && !parts.empty?
+      parts = DEFAULT_ORDER
+    end
+    parts.select { |s| ORDER_SOURCES.include?(s) }
+  end
+
+  # 互联网熔断: 连续 3 次不可达后 60 秒内直接返回 unreachable, 不再发包
+  def online_with_breaker
+    @breaker_mutex.synchronize do
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      if @breaker_until && now < @breaker_until
+        return {
+          "state" => "unreachable",
+          "message" => "熔断中 (前 #{@failures_total} 次不可达, 暂停在线查询)",
+        }
+      end
+      result = yield
+      if result["state"] == "unreachable"
+        @failures += 1
+        if @failures >= BREAKER_THRESHOLD
+          @failures_total = BREAKER_THRESHOLD
+          @breaker_until = now + BREAKER_COOLDOWN
+          @failures = 0
+        end
+      else
+        @failures = 0
+      end
+      result
+    end
+  end
+
+  # sources 键名: internet 源 → "online" (沿用既有输出契约)
+  def src_key(src)
+    src == "internet" ? "online" : src
+  end
+end