netstack 0.1.1 → 0.2.0

data/lib/netstack/backups/repository.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Netstack
+  # 外部备份身份与证据；访问控制和保留策略由宿主管理。
+  module Backups
+    # Device association and version ownership belong here; storage and permissions do not.
+    class Repository
+      attr_reader :client
+
+      def initialize(client:)
+        @client = client
+      end
+
+      def node(target:, aliases: [], nodes: client.nodes)
+        raise InputError, "Backup aliases must be an array" unless aliases.is_a?(Array)
+        candidates = [target.key, target.host, *aliases].map { |value| Values.text(value, name: "node alias").downcase }.uniq
+        host = canonical_host(target.host)
+        matches = nodes.select do |row|
+          values = row.values_at("name", "full_name", "ip").compact.map { |value| Values.text(value, name: "node identity").downcase }
+          !(values & candidates).empty? || (row["ip"] && canonical_host(row["ip"]) == host)
+        end
+        raise Netstack::Error.new("Multiple backup nodes match the target", code: :ambiguous_node) if matches.length > 1
+        match = matches.first
+        if match && match["ip"] && canonical_host(match["ip"]) != host
+          raise Netstack::Error.new("Backup node address conflicts with target", code: :node_identity_conflict)
+        end
+        match && Values.copy(match)
+      end
+
+      def node!(target:, aliases: [])
+        node(target: target, aliases: aliases) || raise(Netstack::Error.new("Backup node was not found", code: :node_not_found))
+      end
+
+      def configuration(node:)
+        Artifact.new(client.configuration(**identity(node)))
+      end
+
+      def versions(node:)
+        client.versions(**identity(node))
+      end
+
+      def diff(node:, from_oid:, to_oid:)
+        known = versions(node: node).map { |row| row.fetch("oid") }
+        unless from_oid != to_oid && known.include?(from_oid) && known.include?(to_oid)
+          raise InputError, "Select two distinct versions belonging to this node"
+        end
+        Diff.new(client.diff(**identity(node), from_oid: from_oid, to_oid: to_oid))
+      end
+
+      def identity(node)
+        { node_name: Values.text(node.fetch("name"), name: "node name"), group: Values.text(node["group"], name: "node group", optional: true) }
+      end
+
+      # Stable device identity available from Oxidized; status and timestamps are excluded.
+      def fingerprint(node)
+        Values.copy(node.slice("name", "group", "ip", "full_name", "model"))
+      end
+
+      def target_fingerprint(target)
+        serial = target.attributes[:serial] || target.attributes["serial"]
+        Values.copy({ "key" => target.key, "host" => target.host, "platform" => target.platform,
+          "attributes" => { "serial" => serial }.compact })
+      end
+
+      private
+
+      def canonical_host(value)
+        text = Values.text(value, name: "node address").downcase.delete_suffix(".")
+        IPAddr.new(text).to_s
+      rescue IPAddr::InvalidAddressError
+        text
+      end
+    end
+  end
+end

data/lib/netstack/backups/request.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Netstack
+  module Backups
+    # A successful queue response means accepted, never completed. A host persists
+    # each returned event under execution_id and invokes recover to poll again.
+    class Request
+      def initialize(repository:, clock: -> { Time.now.utc })
+        @repository = repository
+        @clock = clock
+      end
+
+      def call(target:, execution_id:, checkpoint:, aliases: [])
+        raise InputError, "checkpoint must be callable" unless checkpoint.respond_to?(:call)
+        id = Values.text(execution_id, name: "execution_id")
+        nodes = @repository.client.nodes
+        node = @repository.node(target: target, aliases: aliases, nodes: nodes)
+        raise Netstack::Error.new("Backup node was not found", code: :node_not_found) unless node
+        # Upstream ignores group in /node/next, so group alone cannot disambiguate a queue write.
+        if nodes.count { |row| row["name"] == node["name"] } != 1
+          raise Netstack::Error.new("Oxidized queue requires a globally unique node name", code: :ambiguous_node)
+        end
+        event = { "execution_id" => id, "node" => node.slice("name", "group"),
+                  "node_fingerprint" => @repository.fingerprint(node), "target" => @repository.target_fingerprint(target),
+                  "requested_at" => @clock.call.utc.iso8601(6), "baseline_end" => node.dig("last", "end"), "stage" => "started" }
+        persist!(checkpoint, event)
+        @repository.client.request_backup(**@repository.identity(node))
+        event = event.merge("stage" => "receipt")
+        persist!(checkpoint, event)
+        Values.copy(event)
+      end
+
+      def recover(execution_id:, events:, checkpoint:)
+        id = Values.text(execution_id, name: "execution_id")
+        raise InputError, "checkpoint must be callable" unless checkpoint.respond_to?(:call)
+        unless events.is_a?(Array) && !events.empty? && events.all? { |event| event.is_a?(Hash) } && events.map { |event| event["stage"] }.then { |stages| [%w[started], %w[started receipt], %w[started receipt verified], %w[started verified]].include?(stages) }
+          raise InputError, "Invalid backup checkpoint sequence"
+        end
+        first = events.first
+        unless events.all? { |event| event.is_a?(Hash) && event["execution_id"] == id && event.except("stage", "completed_at") == first.except("stage", "completed_at") }
+          raise InputError, "Backup checkpoints do not belong to this execution"
+        end
+        return Values.copy(events.last) if events.last["stage"] == "verified"
+
+        requested = Values.time(first.fetch("requested_at"), name: "requested_at")
+        identity = first.fetch("node")
+        nodes = @repository.client.nodes.select { |row| row.slice("name", "group") == identity }
+        raise Netstack::Error.new("Backup node identity changed", code: :unknown_result) unless nodes.length == 1
+        unless first["node_fingerprint"].is_a?(Hash) && @repository.fingerprint(nodes.first) == first["node_fingerprint"]
+          raise Netstack::Error.new("Backup node identity changed", code: :unknown_result)
+        end
+        last = nodes.first["last"]
+        return Values.copy(first.merge("stage" => "pending")) unless last.is_a?(Hash) && last["start"] && last["end"]
+        started = Values.time(last["start"], name: "backup start")
+        ended = Values.time(last["end"], name: "backup end")
+        return Values.copy(first.merge("stage" => "pending")) unless started >= requested && ended >= started && last["end"] != first["baseline_end"]
+        unless %w[success ok].include?(last["status"])
+          raise Netstack::Error.new("Backup attempt failed", code: :backup_failed, stage: :verification)
+        end
+        result = first.merge("stage" => "verified", "completed_at" => ended.iso8601(6))
+        persist!(checkpoint, result)
+        Values.copy(result)
+      end
+
+      private
+
+      def persist!(checkpoint, event)
+        raise Netstack::Error.new("Backup checkpoint was not committed", code: :checkpoint_failed, stage: :checkpoint) unless checkpoint.call(Values.copy(event)) == true
+      rescue Netstack::Error
+        raise
+      rescue StandardError
+        raise Netstack::Error.new("Backup checkpoint failed", code: :checkpoint_failed, stage: :checkpoint), cause: nil
+      end
+    end
+  end
+end

data/lib/netstack/circuits/business_calendar.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Netstack
+  module Circuits
+    # A fixed-offset business calendar. For DST zones, inject a callable calendar
+    # using the host's timezone library instead of changing ENV['TZ'] globally.
+    class BusinessCalendar
+      attr_reader :daily_seconds
+
+      def initialize(utc_offset:, weekdays: [1, 2, 3, 4, 5], starts_at: "09:00", ends_at: "18:00", holidays: [])
+        valid_weekdays = weekdays.is_a?(Array) && weekdays.any? && weekdays.all? { |day| day.is_a?(Integer) && (0..6).cover?(day) }
+        unless utc_offset.is_a?(String) && utc_offset.match?(/\A[+-](?:0\d|1[0-4]):[0-5]\d\z/) && valid_weekdays
+          Monitoring::Inputs.invalid!("Invalid business calendar")
+        end
+        @utc_offset = utc_offset.freeze
+        @weekdays = weekdays.uniq.freeze
+        @start = minutes(starts_at)
+        @finish = minutes(ends_at)
+        Monitoring::Inputs.invalid!("Business hours must finish on the same day after they start") unless @finish > @start
+        @daily_seconds = (@finish - @start) * 60
+        @holidays = holidays.map { |day| Date.iso8601(day).iso8601 }.freeze
+      rescue Date::Error, TypeError
+        Monitoring::Inputs.invalid!("Invalid business holiday")
+      end
+
+      def call(time)
+        local = time.getlocal(@utc_offset)
+        date = local.to_date.iso8601
+        workday = @weekdays.include?(local.wday) && !@holidays.include?(date)
+        minute = (local.hour * 60) + local.min
+        { "date" => date, "business" => workday && minute >= @start && minute < @finish }
+      end
+
+      def consecutive_workdays?(previous, current)
+        date = Date.iso8601(previous) + 1
+        date += 1 until @weekdays.include?(date.wday) && !@holidays.include?(date.iso8601)
+        date.iso8601 == current
+      end
+
+      private
+
+      def minutes(value)
+        Monitoring::Inputs.invalid!("Business time must be HH:MM") unless value.is_a?(String) && value.match?(/\A(?:[01]\d|2[0-3]):[0-5]\d\z/)
+        hour, minute = value.split(":").map(&:to_i)
+        (hour * 60) + minute
+      end
+    end
+  end
+end

data/lib/netstack/circuits/capacity_review.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Netstack
+  # 链路监控与容量分析；调度和通知由宿主负责。
+  module Circuits
+    # 先评估覆盖率再计算利用率，避免将缺失样本误判为
+    # 空闲容量；注入的日历定义业务时段与工作日。
+    class CapacityReview
+      WINDOW_SECONDS = { "7" => 7 * 86_400, "15" => 15 * 86_400, "31" => 31 * 86_400 }.freeze
+
+      def initialize(calendar:, interval_seconds: 300, minimum_coverage: 0.9, minimum_samples: 12)
+        unless calendar.respond_to?(:call) && calendar.respond_to?(:daily_seconds) && calendar.respond_to?(:consecutive_workdays?) &&
+               interval_seconds.is_a?(Integer) && interval_seconds.positive? && minimum_samples.is_a?(Integer) && minimum_samples.positive?
+          Monitoring::Inputs.invalid!("Invalid capacity review sampling policy")
+        end
+        @calendar = calendar
+        @interval = interval_seconds
+        @minimum_coverage = Monitoring::Inputs.number(minimum_coverage, positive: true)
+        Monitoring::Inputs.invalid!("Coverage must not exceed one") if @minimum_coverage > 1
+        @minimum_samples = minimum_samples
+      end
+
+      def summarize(samples:, inbound_capacity_mbps:, outbound_capacity_mbps:, from:, to:, complete: true)
+        Monitoring::Inputs.boolean(complete)
+        unless from.is_a?(Integer) && from >= 0 && to.is_a?(Integer) && to >= from && (((to - from) / @interval) + 1) <= 2_000_000
+          Monitoring::Inputs.invalid!("Invalid capacity review interval")
+        end
+        capacities = [inbound_capacity_mbps, outbound_capacity_mbps].map { |value| Monitoring::Inputs.number(value, positive: true) * 1_000_000 }
+        values = samples_by_slot(samples, from, to)
+        business = []
+        off = []
+        days = {}
+        (from..to).step(@interval) do |clock|
+          schedule = @calendar.call(Time.at(clock).utc)
+          sample = values[(clock - from) / @interval] || [nil, nil]
+          if schedule.fetch("business")
+            business << [clock, *sample]
+            day = (days[schedule.fetch("date")] ||= [])
+            day << sample
+          else
+            off << sample
+          end
+        end
+        counts = (0..1).map { |direction| business.count { |row| !row[direction + 1].nil? } }
+        coverage = counts.map { |count| business.empty? ? 0.0 : count.fdiv(business.size) }
+        sufficient = complete && counts.all? { |count| count >= @minimum_samples } && coverage.all? { |value| value >= @minimum_coverage }
+        stats = {
+          "from" => from, "to" => to, "interval_seconds" => @interval,
+          "status" => sufficient ? "ok" : "insufficient_data", "expected_samples" => business.size,
+          "in_samples" => counts[0], "out_samples" => counts[1], "in_coverage" => coverage[0], "out_coverage" => coverage[1],
+          "high_continuous_minutes" => high_minutes(business, capacities),
+          "low_continuous_workdays" => low_days(days, capacities)
+        }
+        %w[in out].each_with_index do |direction, index|
+          traffic = business.map { |row| row[index + 1] }.compact
+          p95 = percentile(traffic)
+          maximum = traffic.max
+          off_maximum = off.map { |row| row[index] }.compact.max
+          stats.merge!("#{direction}_p95_bps" => p95, "#{direction}_max_bps" => maximum,
+                       "#{direction}_p95_utilization" => p95 && (p95 / capacities[index]),
+                       "#{direction}_max_utilization" => maximum && (maximum / capacities[index]),
+                       "off_#{direction}_max_utilization" => off_maximum && (off_maximum / capacities[index]))
+        end
+        Values.copy(stats)
+      end
+
+      def decide(windows:)
+        windows = Monitoring::Inputs.object(windows)
+        windows = windows.select { |days, summary| valid_window?(days, summary) }
+        valid = windows.values
+        return decision("insufficient_data", "insufficient_business_samples") if valid.empty?
+        return decision("insufficient_data", "inconsistent_window_end") unless valid.map { |summary| summary["to"] }.uniq.one?
+
+        recent = windows["7"]
+        notices = if valid.any? do |summary|
+          %w[off_in_max_utilization off_out_max_utilization].any? do |key|
+            summary[key] && summary[key] >= 0.9
+          end
+        end
+                    ["off_hours_peak"]
+                  else
+                    []
+                  end
+        return decision("expand_now", "recent_p95_at_capacity", notices) if recent && recent["status"] == "ok" && maximum_utilization(recent) >= 0.95
+        return decision("expand_review", "sustained_high_utilization", notices) if valid.any? { |summary| summary.fetch("high_continuous_minutes", 0) >= 60 }
+        return decision("expand_review", "multiple_high_windows", notices) if valid.count { |summary| maximum_utilization(summary) >= 0.9 } >= 2
+        if valid.any? { |summary| summary.fetch("low_continuous_workdays", 0) >= 10 } || %w[15 31].all? { |key| low_window?(windows[key], 0.2) }
+          return decision("shrink_review", "sustained_low_utilization", notices)
+        end
+
+        decision("watch", "review_threshold_not_reached", notices)
+      end
+
+      private
+
+      def valid_window?(days, summary)
+        duration = WINDOW_SECONDS[days]
+        return false unless duration && summary.is_a?(Hash) && summary["status"] == "ok"
+        first, last, interval = summary.values_at("from", "to", "interval_seconds")
+        return false unless first.is_a?(Integer) && first >= 0 && last.is_a?(Integer) && last - first == duration && interval.is_a?(Integer) && interval.positive?
+        required = %w[in_p95_utilization out_p95_utilization high_continuous_minutes low_continuous_workdays]
+        required.all? { |key| summary[key].is_a?(Numeric) && summary[key].finite? && summary[key] >= 0 } &&
+          %w[off_in_max_utilization off_out_max_utilization].all? { |key| summary[key].nil? || (summary[key].is_a?(Numeric) && summary[key].finite? && summary[key] >= 0) }
+      end
+
+      def samples_by_slot(samples, from, to)
+        Monitoring::Inputs.invalid!("Capacity samples must be an array") unless samples.is_a?(Array)
+        slots = {}
+        seen = {}
+        ordered = samples.map do |sample|
+          sample = Monitoring::Inputs.object(sample)
+          Monitoring::Inputs.invalid!("Invalid capacity sample timestamp") unless sample["clock"].is_a?(Integer)
+          sample["ns"] = sample.fetch("ns", 0)
+          Monitoring::Inputs.invalid!("Invalid capacity sample nanoseconds") unless sample["ns"].is_a?(Integer) && (0...1_000_000_000).cover?(sample["ns"])
+          sample
+        end.sort_by { |sample| [sample.fetch("clock"), sample.fetch("ns")] }
+        ordered.each do |sample|
+          clock = sample.fetch("clock")
+          identity = [clock, sample.fetch("ns")]
+          Monitoring::Inputs.invalid!("Invalid or duplicate capacity sample timestamp") unless clock >= from && clock <= to && !seen[identity]
+          seen[identity] = true
+          slot = (clock - from) / @interval
+          values = %w[in_bps out_bps].map { |key| sample[key].nil? ? nil : Monitoring::Inputs.number(sample[key]) }
+          # Multiple observations in a sampling interval use the latest value per
+          # direction, without inventing a value for an unobserved direction.
+          previous = slots.fetch(slot, [nil, nil])
+          slots[slot] = values.each_with_index.map { |value, index| value.nil? ? previous[index] : value }
+        end
+        slots
+      rescue KeyError
+        Monitoring::Inputs.invalid!("Capacity sample lacks a timestamp")
+      end
+
+      def percentile(values)
+        return nil if values.empty?
+
+        values.sort.fetch((values.size * 0.95).ceil - 1)
+      end
+
+      def high_minutes(rows, capacities)
+        start = nil
+        previous_clock = nil
+        maximum = 0
+        rows.each do |clock, inbound, outbound|
+          high = !inbound.nil? && !outbound.nil? && [inbound / capacities[0], outbound / capacities[1]].max >= 0.9
+          if high
+            start = clock if start.nil? || (previous_clock && clock - previous_clock > @interval)
+            maximum = [maximum, clock - start].max
+          else
+            start = nil
+          end
+          previous_clock = clock
+        end
+        maximum / 60.0
+      end
+
+      def low_days(days, capacities)
+        previous = nil
+        run = 0
+        maximum = 0
+        days.sort.each do |date, samples|
+          full_day = samples.size * @interval == @calendar.daily_seconds
+          complete = samples.all? { |inbound, outbound| !inbound.nil? && !outbound.nil? }
+          low = full_day && complete && samples.all? { |inbound, outbound| inbound / capacities[0] <= 0.2 && outbound / capacities[1] <= 0.2 }
+          run = if low
+                  previous && @calendar.consecutive_workdays?(previous, date) ? run + 1 : 1
+                else
+                  0
+                end
+          maximum = [maximum, run].max
+          previous = date
+        end
+        maximum
+      end
+
+      def maximum_utilization(summary)
+        values = %w[in_p95_utilization out_p95_utilization].filter_map { |key| summary[key] }
+        values.max || 0
+      end
+
+      def low_window?(summary, threshold)
+        summary.is_a?(Hash) && summary["status"] == "ok" &&
+          %w[in_p95_utilization out_p95_utilization].all? { |key| summary[key] && summary[key] <= threshold }
+      end
+
+      def decision(action, reason, notices = [])
+        Values.copy({ "action" => action, "reason" => reason, "notices" => notices })
+      end
+    end
+  end
+end

data/lib/netstack/circuits/endpoint.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Circuits
+    class Endpoint < Data.define(:side, :host_id, :technical_host, :interface_name, :address, :layer3, :managed)
+      def initialize(side:, host_id: nil, technical_host: nil, interface_name: nil, address: nil, layer3: false, managed: true)
+        side = side.to_s
+        Monitoring::Inputs.invalid!("Circuit side must be a or z") unless %w[a z].include?(side)
+        Monitoring::Inputs.boolean(managed)
+        Monitoring::Inputs.boolean(layer3)
+        if managed
+          host_id = Monitoring::Inputs.identifier(host_id)
+          technical_host = Monitoring::Inputs.text(technical_host, name: "technical host")
+          Monitoring::Inputs.invalid!("Invalid technical host") if technical_host.match?(%r{[/\[\](),]})
+          interface_name = Monitoring::Inputs.text(interface_name, name: "interface name")
+        elsif host_id || technical_host || interface_name
+          Monitoring::Inputs.invalid!("External endpoints cannot identify a managed interface")
+        end
+        address = Monitoring::Inputs.ip(address) unless address.nil?
+        super(side: side.freeze, host_id: host_id&.freeze, technical_host: technical_host&.freeze,
+              interface_name: interface_name&.freeze, address: address&.freeze, layer3: layer3, managed: managed)
+      end
+    end
+  end
+end

data/lib/netstack/circuits/monitoring_plan.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Circuits
+    # 读取提供方监控项和归属明确的触发器，构造 Monitoring::Plan。
+    # 规划不执行远端写入；原宿主 ID 限定迁移后的清理范围。
+    class MonitoringPlan
+      PATTERNS = {
+        "in" => /(?:net\.if\.in\[|ifhcin|bits? received|inbound|incoming|入方向速率|接收速率)/i,
+        "out" => /(?:net\.if\.out\[|ifhcout|bits? sent|outbound|outgoing|出方向速率|发送速率)/i,
+        "speed" => /(?:net\.if\.speed|ifhighspeed|interface speed|接口速率)/i,
+        "status" => /(?:net\.if\.(?:status|oper)|ifoperstatus|operational status|interface status|运行状态|接口状态)/i
+      }.freeze
+      DEFAULT_THRESHOLDS = { "high" => 0.95, "high_recovery" => 0.75, "low_bps" => 50, "low_recovery_bps" => 1_000 }.freeze
+
+      def initialize(client:)
+        @client = client
+      end
+
+      def call(key:, name:, bandwidth_mbps:, endpoints:, previous_host_ids: [], thresholds: {})
+        key = Monitoring::Inputs.text(key, name: "circuit key")
+        name = Monitoring::Inputs.text(name, name: "circuit name")
+        capacity = Monitoring::Inputs.number(bandwidth_mbps, positive: true) * 1_000_000
+        unless endpoints.is_a?(Array) && (1..2).cover?(endpoints.size) && endpoints.all?(Endpoint) && endpoints.map(&:side).uniq.size == endpoints.size
+          Monitoring::Inputs.invalid!("Circuit requires distinct a/z endpoints")
+        end
+        managed = endpoints.select(&:managed)
+        Monitoring::Inputs.invalid!("A managed circuit endpoint is required") if managed.empty?
+        identities = managed.map { |endpoint| [endpoint.host_id, endpoint.interface_name.downcase] }
+        Monitoring::Inputs.invalid!("Circuit endpoints must identify distinct interfaces") unless identities.uniq.size == identities.size
+        limits = thresholds!(thresholds)
+        host_ids = managed.map(&:host_id).uniq
+        old_host_ids = Monitoring::Inputs.ids(previous_host_ids)
+        touched_host_ids = old_host_ids | host_ids
+        owned = touched_host_ids.to_h { |host_id| [host_id, owned_triggers(host_id, key)] }
+        operations = cleanup(owned, managed)
+        managed.each do |endpoint|
+          items = @client.query("item", "hostids" => [endpoint.host_id], "monitored" => true)
+          selected = PATTERNS.to_h { |kind, pattern| [kind, select_item(items, endpoint.interface_name, pattern)] }
+          unless (selected["in"] || selected["out"]) && selected["speed"] && selected["status"]
+            Monitoring::Inputs.invalid!("Circuit traffic, speed and status items are required")
+          end
+          selected.each_value { |item| safe_key!(item.fetch("key_")) if item }
+          existing = owned.fetch(endpoint.host_id).select { |trigger| tag(trigger, "netstack.side") == endpoint.side }
+          by_kind = existing.to_h { |trigger| [tag(trigger, "netstack.kind"), trigger] }
+          Monitoring::Inputs.invalid!("Duplicate managed trigger kind") unless by_kind.size == existing.size && !by_kind.key?(nil)
+          previous_status_id = by_kind["interface_status"]&.fetch("triggerid")
+          peer = endpoints.find { |candidate| candidate.side != endpoint.side }
+          reachability_key = append_reachability(operations, endpoint, peer, name)
+          definitions(endpoint, selected, capacity, limits, reachability_key).each do |kind, expressions|
+            operation_key = "#{endpoint.side}:#{kind}"
+            dependencies = kind == "interface_status" ? [] : [{ "triggerid" => { "$ref" => "#{endpoint.side}:interface_status" } }]
+            attributes = {
+              "description" => "#{name} | #{endpoint.side.upcase} | #{kind}",
+              "expression" => expressions.first, "recovery_mode" => 1, "recovery_expression" => expressions.last,
+              "status" => 0, "priority" => 4, "dependencies" => dependencies,
+              "tags" => [{ "tag" => "netstack.circuit", "value" => key },
+                         { "tag" => "netstack.side", "value" => endpoint.side }, { "tag" => "netstack.kind", "value" => kind }]
+            }
+            current = by_kind.delete(kind)
+            if current
+              previous_dependencies = dependency_rows!(current)
+              attributes["dependencies"] = previous_dependencies.reject { |row| row["triggerid"].to_s == previous_status_id.to_s } + dependencies
+              # Only ownership tags are replaced; unrelated annotations survive.
+              attributes["tags"] = valid_tags!(current).reject do |row|
+                %w[netstack.circuit netstack.side netstack.kind].include?(row["tag"])
+              end + attributes["tags"]
+              before = current.slice("expression", "recovery_expression", "status", "tags", "dependencies")
+              operations << Monitoring::Mutation.new(key: operation_key, resource: "trigger", action: "update",
+                                                     id: current.fetch("triggerid"), attributes: attributes, before: before)
+            else
+              operations << Monitoring::Mutation.new(key: operation_key, resource: "trigger", action: "create", attributes: attributes,
+                                                     selector: trigger_selector(endpoint.host_id, key, endpoint.side, kind))
+            end
+          end
+          by_kind.each_value { |trigger| operations << disable_trigger(trigger, "#{endpoint.side}:obsolete:#{trigger.fetch("triggerid")}") }
+        end
+        Monitoring::Plan.new(key: "circuit:#{key}", operations: operations,
+                             managed: { "circuit" => key, "host_ids" => host_ids, "previous_host_ids" => old_host_ids,
+                                        "touched_host_ids" => touched_host_ids })
+      end
+
+      private
+
+      def thresholds!(input)
+        input = Monitoring::Inputs.object(input)
+        Monitoring::Inputs.invalid!("Unknown circuit threshold") unless (input.keys - DEFAULT_THRESHOLDS.keys).empty?
+        limits = DEFAULT_THRESHOLDS.merge(input).transform_values { |value| Monitoring::Inputs.number(value, positive: true) }
+        unless limits["high"] <= 1 && limits["high_recovery"] < limits["high"] && limits["low_bps"] < limits["low_recovery_bps"]
+          Monitoring::Inputs.invalid!("Circuit thresholds require recovery hysteresis")
+        end
+        limits
+      end
+
+      def select_item(items, interface, pattern)
+        matches = items.select do |item|
+          next false unless item["key_"].is_a?(String) && item["name"].is_a?(String)
+
+          searchable = [item["key_"], item["name"], item["snmp_oid"]].compact.join(" ")
+          identity = [item["key_"], item["name"]].join(" ")
+          # An ifIndex or the numeric prefix of an OID does not identify a port.
+          searchable.match?(pattern) && identity.match?(%r{(?:\A|[^a-z0-9/_.-])#{Regexp.escape(interface)}(?=[^a-z0-9/_.-]|\z)}i)
+        end
+        Monitoring::Inputs.invalid!("Ambiguous circuit monitoring item") if matches.size > 1
+        matches.first
+      end
+
+      def definitions(endpoint, items, capacity, limits, reachability_key)
+        host = endpoint.technical_host
+        traffic = [items["in"], items["out"]].compact.map { |item| item.fetch("key_") }
+        speed = items.fetch("speed").fetch("key_")
+        status = items.fetch("status").fetch("key_")
+        values = {
+          "interface_status" => ["last(/#{host}/#{status})<>1", "last(/#{host}/#{status})=1"],
+          "bandwidth_high" => [traffic_expression(host, traffic, speed, "25m", ">", capacity * limits["high"], "or"),
+                               traffic_expression(host, traffic, speed, "15m", "<", capacity * limits["high_recovery"], "and")],
+          "bandwidth_low" => [traffic_expression(host, traffic, speed, "5m", "<", limits["low_bps"], "or"),
+                              traffic_expression(host, traffic, speed, "5m", ">", limits["low_recovery_bps"], "or")]
+        }
+        values["circuit_reachability"] = ["max(/#{host}/#{reachability_key},5m)=0", "min(/#{host}/#{reachability_key},2m)=1"] if reachability_key
+        values
+      end
+
+      def traffic_expression(host, keys, speed, interval, operator, threshold, joiner)
+        value = threshold.to_i == threshold ? threshold.to_i : threshold.round(4)
+        keys.map { |key| "((avg(/#{host}/#{key},#{interval})#{operator}#{value}) and last(/#{host}/#{speed})>0)" }.join(" #{joiner} ")
+      end
+
+      def append_reachability(operations, endpoint, peer, name)
+        return unless endpoint.layer3 && peer&.address
+
+        key = "icmpping[#{peer.address},4,200,,1000]"
+        selector = { "hostids" => [endpoint.host_id], "filter" => { "key_" => [key] } }
+        current = @client.find("item", selector)
+        if current
+          Monitoring::Inputs.invalid!("Reachability item is disabled or belongs to another key") unless current["key_"] == key && current["status"].to_s == "0"
+        else
+          operations << Monitoring::Mutation.new(key: "#{endpoint.side}:reachability_item", resource: "item", action: "create", selector: selector,
+                                                 attributes: { "hostid" => endpoint.host_id, "name" => "#{name} peer reachability", "key_" => key,
+                                                               "type" => 3, "value_type" => 3, "delay" => "1m", "history" => "30d", "trends" => "365d", "status" => 0 })
+        end
+        key
+      end
+
+      def cleanup(owned, endpoints)
+        retained = endpoints.each_with_object({}) do |endpoint, found|
+          owned.fetch(endpoint.host_id).each do |trigger|
+            found[trigger.fetch("triggerid").to_s] = true if tag(trigger, "netstack.side") == endpoint.side
+          end
+        end
+        seen = {}
+        owned.flat_map do |host_id, triggers|
+          triggers.filter_map do |trigger|
+            id = trigger.fetch("triggerid").to_s
+            next if retained[id] || seen[id]
+
+            seen[id] = true
+            disable_trigger(trigger, "cleanup:#{host_id}:#{trigger.fetch("triggerid")}")
+          end
+        end
+      end
+
+      def disable_trigger(trigger, key)
+        Monitoring::Mutation.new(key: key, resource: "trigger", action: "update", id: trigger.fetch("triggerid"),
+                                 attributes: { "status" => 1 }, before: trigger.slice("status", "tags"))
+      end
+
+      def owned_triggers(host_id, circuit_key)
+        @client.query("trigger", trigger_selector(host_id, circuit_key)).select do |trigger|
+          # Never trust an external filter alone to authorize cleanup.
+          tag(trigger, "netstack.circuit") == circuit_key
+        end
+      end
+
+      def trigger_selector(host_id, circuit_key, side = nil, kind = nil)
+        tags = [{ "tag" => "netstack.circuit", "value" => circuit_key, "operator" => 1 }]
+        tags << { "tag" => "netstack.side", "value" => side, "operator" => 1 } if side
+        tags << { "tag" => "netstack.kind", "value" => kind, "operator" => 1 } if kind
+        { "hostids" => [host_id], "tags" => tags, "evaltype" => 0 }
+      end
+
+      def valid_tags!(trigger)
+        rows = trigger["tags"]
+        unless rows.is_a?(Array) && rows.all? { |row| row.is_a?(Hash) && row["tag"].is_a?(String) && row["value"].is_a?(String) }
+          Monitoring::Inputs.invalid!("Invalid trigger ownership tags")
+        end
+        rows
+      end
+
+      def dependency_rows!(trigger)
+        rows = trigger["dependencies"]
+        unless rows.is_a?(Array) && rows.all? { |row| row.is_a?(Hash) && row.key?("triggerid") }
+          Monitoring::Inputs.invalid!("Incomplete trigger dependencies")
+        end
+        ids = Monitoring::Inputs.ids(rows.map { |row| row["triggerid"] })
+        ids.map { |id| { "triggerid" => id } }
+      end
+
+      def tag(trigger, name)
+        values = valid_tags!(trigger).select { |row| row["tag"] == name }.map { |row| row["value"] }.uniq
+        Monitoring::Inputs.invalid!("Ambiguous trigger ownership") if values.size > 1
+        values.first
+      end
+
+      def safe_key!(value)
+        return if value.is_a?(String) && value.match?(%r{\A[a-zA-Z0-9_.]+(?:\[[a-zA-Z0-9_.,:"\-/ ]*\])?\z})
+
+        Monitoring::Inputs.invalid!("Unsafe item key in trigger expression")
+      end
+    end
+  end
+end