netstack 0.1.1 → 0.2.0

data/lib/netstack/connector/vendors/radware/topology.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    module Vendors
+      class Radware
+        class Topology < Netstack::Connector::Topology::Strategy
+          # Alteon 只支持读取端口描述，不提供邻居发现或自动改写。
+          def self.supports?(capability) = capability == :interface_descriptions
+
+          # 从设备配置转储解析端口名称。
+          def description_template = "radware_port_names.textfsm"
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/vendors/radware.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    module Vendors
+      class Radware < Netstack::Connector::Device
+        vendor :radware
+        # 声明菜单式 CLI 的命令、提示、超时、诊断和确认规则。
+        profile do
+          running_config_strategy Netstack::Connector::Vendors::Radware::RunningConfig
+          tftp_strategy Netstack::Connector::Vendors::Radware::TftpBackup
+          topology_strategy Netstack::Connector::Vendors::Radware::Topology
+          commands do
+            running_config "/cfg/dump"
+            save_config "/cfg/save"
+          end
+
+          prompts do
+            login(/(?:\A|(?<=[\r\n]))(?:>>[^\r\n]*#|(?!>>)[^\r\n]+[>#])\s*\z/)
+            command(/(?:\A|(?<=[\r\n]))[^\r\n]+#\s*\z/)
+          end
+
+          errors do
+            command(/^[ \t]*(?:Unknown|Invalid|Error)\s+command\b/i)
+          end
+
+          command_timeout 30
+
+          interactions do
+            confirm %r{Confirm\s+Sync\s+to\s+Peer\s+\[y/n\]:\s*\z}i, response: "y\n"
+            confirm %r{Synchronize\s+configuration\s+changes\?\s+\[y/n\]:\s*\z}i, response: "y\n"
+            confirm %r{Confirm\s+saving\s+to\s+FLASH\s+\[y/n\]:\s*\z}i, response: "y\n"
+            confirm %r{Confirm\s+operation\s+without\s+applying\s+changes\s+
+              \(leave\s+them\s+pending\)\s+\[y/n\]:\s*\z}ix, response: "y\n"
+            confirm %r{Confirm\s+operation\s+without\s+saving\s+changes\s+
+              \(leave\s+them\s+pending\)\s+\[y/n\]:?\s*\z}ix, response: "y\n"
+            confirm(/Confirm\s+seeing\s+above\s+note\s+\[y\]:\s*\z/i, response: "y\n")
+            confirm(/Please\s+enter\s+y\s+to\s+perform\s+the\s+action,\s+n\s+to\s+skip\s+it:\s*\z/i,
+                    response: "y\n"
+            )
+            confirm %r{Display\s+private\s+keys\?\s+\[y/n\]:\s*\z}i, response: "n\n"
+          end
+        end
+
+        # 连接有效期间返回登录横幅中的 HA 状态。
+        def ha_state = connected? ? @ha_state : nil
+
+        protected
+
+        # 从登录横幅提取 HA 状态并冻结，供连接期间查询。
+        def after_login(_session, response)
+          @ha_state = response.raw[/^\s*HA\s+State:\s*(\S+)/i, 1]&.freeze
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/write_timeout.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    class WriteTimeout < Error; end
+  end
+end

data/lib/netstack/connector.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../netstack" unless defined?(Netstack::LOADER)
+
+module Netstack
+  # 单设备会话、厂商语法及配置操作；不读取清单或持久化执行任务。
+  module Connector
+    VENDORS = {
+      h3c: "H3c", h3c_wireless: "H3cWireless", cisco_ios: "CiscoIos",
+      cisco_nxos: "CiscoNxos", radware: "Radware", palo_alto: "PaloAlto",
+      huawei: "Huawei", hillstone: "Hillstone"
+    }.freeze
+
+    def self.vendors = VENDORS.keys
+
+    def self.vendor_class(vendor)
+      key = vendor.to_s.downcase.tr(" -", "__").to_sym
+      name = VENDORS.fetch(key) { raise ArgumentError, "unsupported vendor: #{vendor.inspect}" }
+      Vendors.const_get(name, false)
+    end
+
+    def self.build(vendor, **settings)
+      vendor_class(vendor).new(**settings)
+    end
+
+    def self.open(vendor, **settings, &)
+      raise ArgumentError, "open requires a block" unless block_given?
+
+      vendor_class(vendor).open(**settings, &)
+    end
+  end
+end

data/lib/netstack/ddi/applier.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Ddi
+    # 只有开始检查点已持久化，才应用范围内的有序意图。
+    # 恢复通过读取当前状态并绑定新建父对象 ID 推进，不重放写入。
+    # 变更已验证与 DNS/DHCP 服务已部署分别表达。
+    class Applier
+      def initialize(client:, settings:)
+        @settings = settings
+        @state = State.new(client: client, settings: settings)
+      end
+
+      def call(plan:, execution_id:, checkpoint:)
+        recover(plan: plan, execution_id: execution_id, events: [], checkpoint: checkpoint)
+      end
+
+      def recover(plan:, execution_id:, events:, checkpoint:)
+        raise InputError, "checkpoint must be callable" unless checkpoint.respond_to?(:call)
+        id = Values.text(execution_id, name: "execution_id")
+        raise InputError, "DDI plan belongs to a different scope" unless plan.scope == @settings.to_h
+        groups = validate_events!(plan, id, events)
+        plan.operations.each_with_index do |operation, index|
+          history = groups.fetch(index, [])
+          next if history.last&.fetch("stage") == "verified"
+          operation = bind_parent(plan, operation, index, groups)
+          current = @state.read(operation.fetch("kind"), operation.fetch("identity"))
+          base = { "execution_id" => id, "plan_digest" => plan.digest, "operation" => index }
+          if history.empty?
+            unless current == operation["before"]
+              raise Netstack::Error.new("DDI object changed after planning", code: :state_conflict, stage: :preflight)
+            end
+            persist!(checkpoint, base.merge("stage" => "started"))
+            receipt = @state.write(operation)
+            persist!(checkpoint, base.merge("stage" => "receipt", "receipt" => receipt))
+            current = @state.read(operation.fetch("kind"), operation.fetch("identity"))
+          else
+            receipt = history.find { |event| event["stage"] == "receipt" }&.fetch("receipt")
+          end
+          expected_id = receipt.is_a?(Integer) ? receipt : operation["desired"] && operation.dig("before", "id")
+          unless @state.matches?(current, operation["desired"]) && (!expected_id || current&.fetch("id", nil) == expected_id)
+            raise Netstack::Error.new("DDI write outcome needs reconciliation", code: :unknown_result, stage: :verification,
+                                      details: { "operation" => index })
+          end
+          verified = base.merge("stage" => "verified", "observed" => current)
+          persist!(checkpoint, verified)
+          groups[index] = [verified]
+        end
+        Values.copy({ "execution_id" => id, "plan_digest" => plan.digest, "state" => "verified" })
+      end
+
+      private
+
+      def bind_parent(plan, operation, index, groups)
+        return operation unless %w[role record].include?(operation["kind"])
+        identity = operation.fetch("identity")
+        parent_index = (0...index).to_a.reverse.find do |candidate|
+          previous = plan.operations[candidate]
+          previous["kind"] == "zone" && previous["desired"] && previous["identity"].slice("view_id", "name") == identity.slice("view_id", "name")
+        end
+        return operation unless parent_index
+        observed = groups.fetch(parent_index).last.fetch("observed")
+        operation.merge("identity" => identity.merge("zone_id" => observed.fetch("id")))
+      end
+
+      def validate_events!(plan, execution_id, events)
+        raise InputError, "DDI checkpoints must be an array" unless events.is_a?(Array)
+        groups = {}
+        events.each do |event|
+          unless event.is_a?(Hash) && event["execution_id"] == execution_id && event["plan_digest"] == plan.digest && event["operation"].is_a?(Integer) && event["operation"].between?(0, plan.operations.length - 1)
+            raise InputError, "DDI checkpoints do not match this execution"
+          end
+          index = event["operation"]
+          if index.positive? && groups[index - 1]&.last&.fetch("stage") != "verified"
+            raise InputError, "DDI operations are out of order"
+          end
+          history = (groups[index] ||= [])
+          stages = history.map { |item| item["stage"] } + [event["stage"]]
+          unless [%w[started], %w[started receipt], %w[started verified], %w[started receipt verified]].include?(stages)
+            raise InputError, "Invalid DDI checkpoint stage"
+          end
+          if event["stage"] == "receipt" && event["receipt"] != true && !(event["receipt"].is_a?(Integer) && event["receipt"].positive?)
+            raise InputError, "Invalid DDI receipt"
+          end
+          if event["stage"] == "verified"
+            operation = plan.operations[index]
+            receipt = history.find { |item| item["stage"] == "receipt" }&.fetch("receipt")
+            expected_id = receipt.is_a?(Integer) ? receipt : operation["desired"] && operation.dig("before", "id")
+            unless @state.matches?(event["observed"], operation["desired"]) && (!expected_id || event.dig("observed", "id") == expected_id)
+              raise InputError, "DDI verification does not match its receipt"
+            end
+          end
+          history << event
+        end
+        groups
+      end
+
+      def persist!(checkpoint, event)
+        raise Netstack::Error.new("DDI 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("DDI checkpoint failed", code: :checkpoint_failed, stage: :checkpoint), cause: nil
+      end
+    end
+  end
+end

data/lib/netstack/ddi/deployment.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Ddi
+    # Legacy v1 exposes server-wide status, not a submission ID. Require an
+    # observed active phase after our receipt before accepting DONE.
+    class Deployment
+      ACTIVE = [-1, 0, 1].freeze
+      FAILED = [2, 3, 4, 6].freeze
+
+      def initialize(client:, settings:)
+        @client = client
+        @settings = settings
+        @scope = Scope.new(client: client, settings: settings)
+      end
+
+      def submit(plan:, mutation_result:, checkpoint:, events: [])
+        raise InputError, "checkpoint must be callable" unless checkpoint.respond_to?(:call)
+        unless plan.scope == @settings.to_h && mutation_result.is_a?(Hash) && mutation_result["state"] == "verified" && mutation_result["plan_digest"] == plan.digest
+          raise InputError, "Deployment requires verified DDI writes in this scope"
+        end
+        id = Values.text(mutation_result["execution_id"], name: "execution_id")
+        groups = validate_events!(plan, id, events)
+        return [] if plan.operations.empty? || plan.services.empty?
+        raise InputError, "No deployment servers configured" if @settings.server_ids.empty?
+        emitted = []
+        @settings.server_ids.each do |server_id|
+          history = groups[server_id]
+          if history
+            raise Netstack::Error.new("Deployment submission outcome is unknown; do not replay it", code: :unknown_result) if history.last["stage"] == "started"
+            raise Netstack::Error.new("Deployment needs review before further submissions", code: :deployment_failed) if %w[failed warning].include?(history.last["stage"])
+            next
+          end
+          status = status(server_id)
+          raise Netstack::Error.new("Another deployment is active", code: :deployment_busy) if ACTIVE.include?(status)
+          base = { "execution_id" => id, "plan_digest" => plan.digest, "server_id" => server_id, "services" => plan.services }
+          persist!(checkpoint, base.merge("stage" => "started"), emitted)
+          @client.write(:post, "deployServerServices", query: { serverId: server_id, services: "services=#{plan.services.join(",")}" })
+          persist!(checkpoint, base.merge("stage" => "receipt"), emitted)
+        end
+        Values.copy(emitted)
+      end
+
+      def recover(plan:, execution_id:, events:, checkpoint:)
+        raise InputError, "checkpoint must be callable" unless checkpoint.respond_to?(:call)
+        raise InputError, "DDI deployment scope changed" unless plan.scope == @settings.to_h
+        execution_id = Values.text(execution_id, name: "execution_id")
+        groups = validate_events!(plan, execution_id, events)
+        return {} if plan.operations.empty? || plan.services.empty?
+        result = {}
+        @settings.server_ids.each do |server_id|
+          history = groups[server_id]
+          unless history
+            result[server_id] = "not_submitted"
+            next
+          end
+          last = history.last
+          if %w[verified warning failed].include?(last["stage"])
+            result[server_id] = last["stage"]
+            next
+          end
+          current = status(server_id)
+          # A lost submission receipt cannot be correlated through this API.
+          if last["stage"] == "started"
+            result[server_id] = "unknown"
+            next
+          end
+          if ACTIVE.include?(current)
+            persist!(checkpoint, last.merge("stage" => "active", "status" => current), []) unless last["stage"] == "active"
+            result[server_id] = "pending"
+          elsif current == 7 && last["stage"] == "active"
+            persist!(checkpoint, last.merge("stage" => "verified", "status" => current), [])
+            result[server_id] = "verified"
+          elsif FAILED.include?(current) && last["stage"] == "active"
+            persist!(checkpoint, last.merge("stage" => "failed", "status" => current), [])
+            result[server_id] = "failed"
+          elsif current == 5 && last["stage"] == "active"
+            persist!(checkpoint, last.merge("stage" => "warning", "status" => current), [])
+            result[server_id] = "warning"
+          else
+            result[server_id] = "unknown"
+          end
+        end
+        Values.copy(result)
+      end
+
+      private
+
+      def validate_events!(plan, execution_id, events)
+        raise InputError, "Invalid deployment checkpoints" unless events.is_a?(Array)
+        raise InputError, "Empty plans cannot have deployment checkpoints" if !events.empty? && (plan.operations.empty? || plan.services.empty?)
+        groups = {}
+        events.each do |event|
+          unless event.is_a?(Hash) && event["execution_id"] == execution_id && event["plan_digest"] == plan.digest && @settings.server_ids.include?(event["server_id"]) && event["services"] == plan.services
+            raise InputError, "Deployment checkpoints do not match this execution"
+          end
+          server_id = event["server_id"]
+          group = (groups[server_id] ||= [])
+          stage = event["stage"]
+          valid_stage = case group.last&.fetch("stage")
+          when nil then stage == "started"
+          when "started" then stage == "receipt"
+          when "receipt" then stage == "active" && ACTIVE.include?(event["status"])
+          when "active" then (stage == "verified" && event["status"] == 7) || (stage == "warning" && event["status"] == 5) || (stage == "failed" && FAILED.include?(event["status"]))
+          else false
+          end
+          raise InputError, "Invalid deployment checkpoint sequence" unless valid_stage
+          if stage == "started"
+            preceding = @settings.server_ids.take_while { |id| id != server_id }
+            unless preceding.all? { |id| groups[id]&.any? { |item| item["stage"] == "receipt" } }
+              raise InputError, "Deployment submissions are out of order"
+            end
+          end
+          group << event
+        end
+        groups
+      end
+
+      def status(server_id)
+        @scope.entity!(server_id, types: ["Server"])
+        value = @client.json("getServerDeploymentStatus", serverId: server_id)
+        raise Netstack::Error.new("Invalid deployment status", code: :invalid_response) unless value.is_a?(Integer) && (-1..8).cover?(value)
+        value
+      end
+
+      def persist!(checkpoint, event, events)
+        event = Values.copy(event)
+        raise Netstack::Error.new("Deployment checkpoint was not committed", code: :checkpoint_failed, stage: :checkpoint) unless checkpoint.call(event) == true
+        events << event
+      rescue Netstack::Error
+        raise
+      rescue StandardError
+        raise Netstack::Error.new("Deployment checkpoint failed", code: :checkpoint_failed, stage: :checkpoint), cause: nil
+      end
+    end
+  end
+end

data/lib/netstack/ddi/inputs.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Netstack
+  module Ddi
+    module Inputs
+      module_function
+
+      def id(value) = Values.integer(value, name: "BlueCat object ID", min: 1)
+
+      def domain(value)
+        value = Values.text(value, name: "domain").downcase.delete_suffix(".")
+        unless value.length <= 253 && value.split(".", -1).length >= 2 && value.split(".", -1).all? { |label| label.match?(/\A[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\z/) }
+          raise InputError, "Invalid DNS name"
+        end
+        value
+      end
+
+      def ipv4(value)
+        value = Values.text(value, name: "IPv4 address")
+        address = IPAddr.new(value)
+        raise InputError, "Invalid IPv4 address" unless address.ipv4? && !value.include?("/")
+        address.to_s
+      rescue IPAddr::InvalidAddressError
+        raise InputError, "Invalid IPv4 address"
+      end
+
+      def network(value)
+        value = Values.text(value, name: "IPv4 CIDR")
+        parts = value.split("/", -1)
+        raise InputError, "IPv4 CIDR must contain one address and one prefix" unless parts.size == 2
+        address, prefix = parts
+        prefix = Values.integer(prefix, name: "IPv4 prefix", min: 0, max: 30)
+        network = IPAddr.new("#{ipv4(address)}/#{prefix}")
+        raise InputError, "CIDR must be an aligned IPv4 network" unless network.to_s == ipv4(address)
+        network
+      end
+
+      def cidr(value)
+        network = network(value)
+        "#{network}/#{network.prefix}"
+      end
+
+      def mac(value)
+        value = Values.text(value, name: "MAC address").downcase.tr("-", ":")
+        raise InputError, "Invalid MAC address" unless value.match?(/\A(?:[0-9a-f]{2}:){5}[0-9a-f]{2}\z/)
+        value
+      end
+
+      def properties(value)
+        raise Netstack::Error.new("Invalid BlueCat properties", code: :invalid_response) unless value.is_a?(String)
+        value.split(/(?<!\\)\|/).each_with_object({}) do |part, result|
+          key, content = part.split("=", 2)
+          raise Netstack::Error.new("Invalid BlueCat properties", code: :invalid_response) unless key && content && !result.key?(key)
+          result[key] = content.gsub("\\|", "|")
+        end
+      end
+    end
+  end
+end

data/lib/netstack/ddi/manager.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Netstack
+  # 限定范围的 DNS/DHCP/IPAM 意图；BlueCat 传输与宿主事务各自独立。
+  module Ddi
+    # Produces a reviewable intent from exact current state; planning never writes.
+    class Manager
+      def initialize(client:, settings:)
+        @client = client
+        @settings = settings
+        @state = State.new(client: client, settings: settings)
+      end
+
+      def dns_zone(name:, replace: false)
+        dns_plan(name: name, replace: replace)
+      end
+
+      def dns_record(name:, value:, type: "A", replace: false)
+        raise InputError, "Only A and CNAME records are supported" unless %w[A CNAME].include?(type)
+        value = type == "A" ? Inputs.ipv4(value) : Inputs.domain(value)
+        dns_plan(name: name, replace: replace, record: { "type" => type, "rdata" => value })
+      end
+
+      def dns_forward(name:, roles:, replace: false)
+        roles = Settings.roles(roles)
+        raise InputError, "Forward zones require a FORWARDER role" unless roles.any? { |role| role["type"] == "FORWARDER" }
+        dns_plan(name: name, replace: replace, roles: roles)
+      end
+
+      def delete_zone(name:, recursive: false)
+        raise InputError, "Zone deletion requires explicit recursive intent" unless recursive == true
+        name = Inputs.domain(name)
+        require_views!
+        operations = @settings.views.filter_map do |view|
+          operation("zone", { "view_id" => view["id"], "name" => name }, nil, delete: true)
+        end
+        plan(operations: operations, services: ["DNS"])
+      end
+
+      def blacklist(name:, present: true)
+        raise InputError, "Blacklist policy is not configured" unless @settings.policy_id
+        raise InputError, "Blacklist present must be boolean" unless [true, false].include?(present)
+        identity = { "name" => Inputs.domain(name), "policy_id" => @settings.policy_id }
+        op = operation("blacklist", identity, present ? { "present" => true } : nil, delete: !present)
+        plan(operations: [op].compact, services: ["DNS"])
+      end
+
+      def block(cidr:, parent_id: @settings.configuration_id)
+        cidr = Inputs.cidr(cidr)
+        parent_id = Inputs.id(parent_id)
+        validate_container!(parent_id, cidr) unless parent_id == @settings.configuration_id
+        op = operation("block", { "parent_id" => parent_id, "cidr" => cidr }, { "cidr" => cidr })
+        plan(operations: [op].compact, services: [])
+      end
+
+      def network(cidr:, block_id:, gateway:)
+        cidr, block_id, gateway = Inputs.cidr(cidr), Inputs.id(block_id), Inputs.ipv4(gateway)
+        validate_container!(block_id, cidr)
+        usable!(Inputs.network(cidr), gateway)
+        op = operation("network", { "parent_id" => block_id, "cidr" => cidr }, { "cidr" => cidr, "gateway" => gateway })
+        plan(operations: [op].compact, services: ["DHCP"])
+      end
+
+      def delete_network(cidr:, block_id:)
+        identity = { "parent_id" => Inputs.id(block_id), "cidr" => Inputs.cidr(cidr) }
+        op = operation("network", identity, nil, delete: true)
+        plan(operations: [op].compact, services: ["DHCP"])
+      end
+
+      def dhcp_range(cidr:, network_id:, start: nil, end_address: nil, reserve_tail: nil)
+        network = Inputs.network(cidr)
+        network_id = Inputs.id(network_id)
+        row = @client.entity("getEntityById", id: network_id)
+        unless row && row["type"] == "IP4Network" && Inputs.properties(row["properties"])["CIDR"] == "#{network}/#{network.prefix}"
+          raise InputError, "DHCP network ID does not match the exact CIDR"
+        end
+        if reserve_tail
+          raise InputError, "Specify explicit bounds or reserve_tail" if start || end_address
+          tail = Values.integer(reserve_tail, name: "reserved tail", min: 1)
+          start = network.to_range.first.succ.to_s
+          last = network.to_range.last.to_i - tail
+          raise InputError, "Network is too small for the reserved tail" unless last > network.to_i
+          end_address = IPAddr.new(last, Socket::AF_INET).to_s
+        end
+        start, end_address = Inputs.ipv4(start), Inputs.ipv4(end_address)
+        usable!(network, start)
+        usable!(network, end_address)
+        raise InputError, "DHCP range end precedes start" if IPAddr.new(start).to_i > IPAddr.new(end_address).to_i
+        gateway = Inputs.properties(row["properties"])["gateway"]
+        if gateway && (IPAddr.new(start).to_i..IPAddr.new(end_address).to_i).cover?(IPAddr.new(Inputs.ipv4(gateway)).to_i)
+          raise InputError, "DHCP range includes the gateway"
+        end
+        identity = { "network_id" => network_id, "start" => start, "end" => end_address }
+        op = operation("range", identity, identity.slice("start", "end"))
+        plan(operations: [op].compact, services: ["DHCP"])
+      end
+
+      def fixed_address(ip:, mac:)
+        address_plan(ip: ip, mac: Inputs.mac(mac))
+      end
+
+      def reserve_address(ip:)
+        ip = Inputs.ipv4(ip)
+        before = @state.read("address", { "ip" => ip })
+        raise InputError, "An existing MAC binding is required" unless before && before["mac"]
+        address_plan(ip: ip, mac: Inputs.mac(before["mac"]))
+      end
+
+      private
+
+      def plan(operations:, services:)
+        Plan.new(operations: operations, services: services, scope: @settings.to_h)
+      end
+
+      def dns_plan(name:, replace:, record: nil, roles: nil)
+        raise InputError, "replace must be boolean" unless [true, false].include?(replace)
+        name = Inputs.domain(name)
+        require_views!
+        operations = []
+        @settings.views.each do |view|
+          identity = { "view_id" => view["id"], "name" => name }
+          existing = @state.read("zone", identity)
+          if replace && existing
+            validate_delete!(existing)
+            operations << { "kind" => "zone", "identity" => identity, "before" => existing, "desired" => nil }
+          end
+          fresh = replace || existing.nil?
+          desired = { "name" => name, "deployable" => "true" }
+          op = fresh ? { "kind" => "zone", "identity" => identity, "before" => nil, "desired" => desired } : operation("zone", identity, desired)
+          operations << op if op
+          (roles || view["roles"]).each do |role|
+            role_identity = identity.merge("interface_id" => role["interface_id"])
+            role_identity["zone_id"] = existing["id"] unless fresh
+            desired = { "type" => role["type"] }
+            op = fresh ? { "kind" => "role", "identity" => role_identity, "before" => nil, "desired" => desired } : operation("role", role_identity, desired)
+            operations << op if op
+          end
+          next unless record
+          record_identity = identity.merge("type" => record["type"])
+          record_identity["zone_id"] = existing["id"] unless fresh
+          unless fresh
+            other_type = record["type"] == "A" ? "CNAME" : "A"
+            raise InputError, "A and CNAME cannot coexist at the same name" if @state.read("record", identity.merge("type" => other_type))
+          end
+          op = fresh ? { "kind" => "record", "identity" => record_identity, "before" => nil, "desired" => record } : operation("record", record_identity, record)
+          operations << op if op
+        end
+        plan(operations: operations, services: ["DNS"])
+      end
+
+      def address_plan(ip:, mac:)
+        ip = Inputs.ipv4(ip)
+        network = @client.entity("getIPRangedByIP", containerId: @settings.configuration_id, type: "IP4Network", address: ip)
+        raise InputError, "Address does not belong to a managed network" unless network && network["type"] == "IP4Network"
+        props = Inputs.properties(network["properties"])
+        usable!(Inputs.network(props["CIDR"]), ip)
+        raise InputError, "Gateway cannot be reserved as a client address" if props["gateway"] == ip
+        identity = { "ip" => ip }
+        before = @state.read("address", identity)
+        raise InputError, "Address is bound to another MAC" if before && before["mac"] && before["mac"] != mac
+        desired = { "mac" => mac, "state" => "DHCP_RESERVED" }
+        op = @state.matches?(before, desired) ? nil : { "kind" => "address", "identity" => identity, "before" => before, "desired" => desired }
+        plan(operations: [op].compact, services: ["DHCP"])
+      end
+
+      def operation(kind, identity, desired, delete: false)
+        before = @state.read(kind, identity)
+        return nil if @state.matches?(before, desired)
+        validate_delete!(before) if delete && before && kind != "blacklist"
+        raise Netstack::Error.new("Existing DDI object conflicts with requested state", code: :state_conflict) if before && !delete
+        { "kind" => kind, "identity" => identity, "before" => before, "desired" => desired }
+      end
+
+      def validate_delete!(before)
+        @state.validate_delete!(before.fetch("id"))
+      end
+
+      def validate_container!(id, cidr)
+        row = @client.entity("getEntityById", id: id)
+        raise InputError, "Parent is not an IPv4 block" unless row && row["type"] == "IP4Block"
+        parent = Inputs.network(Inputs.properties(row["properties"])["CIDR"])
+        child = Inputs.network(cidr)
+        raise InputError, "Child network must be inside its parent block" unless parent.include?(child) && parent.prefix < child.prefix
+      end
+
+      def usable!(network, ip)
+        address = IPAddr.new(ip)
+        return if network.include?(address) && address != network.to_range.first && address != network.to_range.last
+        raise InputError, "Address must be a usable host inside the network"
+      end
+
+      def require_views!
+        raise InputError, "At least one managed DNS view is required" if @settings.views.empty?
+      end
+    end
+  end
+end