zonesync 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed23482c3eeed63566e03e79231562447d9f63c09a2d382151d6cd3b123b3502
-  data.tar.gz: 45c154c9bd89d9f1ad97df54ec0c4d30ab49995716fbd3e519b4381f890c2259
+  metadata.gz: aaa6c630bddb382ab5b051983a3af48b5d59583a2e6befb51bf4098e3ccbdbb0
+  data.tar.gz: 7005f724efb994e55bc9d581780a8ba5711729ba208b9ef4c8fb77cc48d018bc
 SHA512:
-  metadata.gz: 2870e1fd94f37248ddd609da2a90be47e9487f11e371043b48ed00465fbc727f69fd36614d83b8adf4ff7661bc90dfbbeb100c964c572a49b2ad97ab36b4ad97
-  data.tar.gz: 3dcde654cdbdcaa806734b41c99286ba4724b812c58a4b22af7232bde1e5410892edda80b4475918b512738750a44a709c87c0af4b3483d6a9cc669bc12158b5
+  metadata.gz: ca2cc5e0fefcbf14efe91cb80b84ef20b485715891d92b8f2cd1f58cb2b6193bf9a7a51e822fa046a516bb275a7c5a5fb98e19d2cb9ae08cee41208434986f9e
+  data.tar.gz: bb66c82041407b2e3d3a57e0c1c381dc9a7ac77fb1d09db52d61892fb76409541a3d5059f916205f00dbf304a71218a0df7f60c6fb995350a1928d8026e8b617

data/CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Zonesync is a Ruby gem that synchronizes DNS zone files with DNS providers (Cloudflare, Route53). It treats DNS configuration as code, enabling version control and CI/CD workflows for DNS records.
+
+## Commands
+
+### Development Commands
+- `bundle install` - Install dependencies
+- `bundle exec rake` - Run all tests (default task)
+- `bundle exec rspec` - Run RSpec tests
+- `bundle exec rspec spec/path/to/specific_spec.rb` - Run a single test file
+- `bundle exec rspec spec/path/to/specific_spec.rb:123` - Run a specific test at line 123
+
+### Application Commands
+- `bundle exec zonesync` - Sync Zonefile to configured DNS provider
+- `bundle exec zonesync --dry-run` - Preview changes without applying them
+- `bundle exec zonesync --force` - Force sync ignoring checksum mismatches
+- `bundle exec zonesync generate` - Generate Zonefile from DNS provider
+
+### Type Checking (Sorbet)
+- `bundle exec srb tc` - Run Sorbet type checker
+- `bundle exec tapioca gem` - Generate RBI files for gems
+
+## Architecture
+
+### Core Components
+
+**Provider Pattern**: Abstract base class `Provider` with concrete implementations:
+- `Cloudflare` - Cloudflare DNS API integration
+- `Route53` (AWS) - Route53 DNS API integration
+- `Filesystem` - Local zone file operations
+- `Memory` - In-memory provider for testing
+
+**Key Classes**:
+- `Sync` - Orchestrates synchronization between source and destination providers
+- `Generate` - Generates zone files from DNS providers
+- `Record` - Represents DNS records with type, name, content, TTL
+- `Zonefile` - Parses and generates RFC-compliant zone files
+- `Diff` - Calculates differences between record sets
+- `Manifest` - Tracks which records are managed by zonesync
+- `Validator` - Validates operations and handles conflicts
+
+### Data Flow
+
+1. **Sync Process**: `Zonefile` → `Provider.diff!()` → `operations[]` → `destination.apply()`
+2. **Generate Process**: DNS Provider → `Zonefile.generate()` → local file
+3. **Validation**: Checksum verification prevents conflicting external changes
+4. **Manifest**: TXT records track zonesync-managed records vs external ones
+
+### Safety Mechanisms
+
+- **Checksum verification**: Detects external changes to managed records
+- **Manifest tracking**: Distinguishes zonesync-managed vs external records
+- **Force mode**: Bypass safety checks when needed
+- **Dry-run mode**: Preview changes without applying them
+
+### Configuration
+
+Credentials stored in Rails-style encrypted configuration:
+- `config/credentials.yml.enc` - Encrypted credentials file
+- `config/master.key` - Encryption key
+- `RAILS_MASTER_KEY` env var - Alternative key source
+
+## Testing
+
+- **RSpec** for testing framework
+- **WebMock** for HTTP request stubbing
+- **Feature specs** in `spec/features/` test end-to-end workflows
+- **Unit specs** test individual classes and methods
+- All tests should pass before committing changes
+
+## Type Safety
+
+Uses **Sorbet** for gradual typing:
+- All files have `# typed: strict` or similar headers
+- Method signatures use `sig { ... }` blocks
+- `extend T::Sig` enables signature checking
+- RBI files in `sorbet/rbi/` define external gem types
+
+## Error Handling
+
+Custom exceptions in `lib/zonesync/errors.rb`:
+- `ConflictError` - Record conflicts
+- `ChecksumMismatchError` - External changes detected
+- `MissingManifestError` - Missing manifest record
+- `DuplicateRecordError` - Duplicate record handling

data/lib/zonesync/errors.rb

@@ -1,22 +1,56 @@
 # typed: strict
 require "sorbet-runtime"
+require "zonesync/record_hash"
 
 module Zonesync
+  class ValidationError < StandardError
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @errors = T.let([], T::Array[StandardError])
+    end
+
+    sig { params(error: StandardError).void }
+    def add(error)
+      @errors << error
+    end
+
+    sig { returns(T::Boolean) }
+    def any?
+      @errors.any?
+    end
+
+    sig { returns(String) }
+    def message
+      @errors.map(&:message).join("\n\n#{'-' * 60}\n\n")
+    end
+
+    sig { returns(T::Array[StandardError]) }
+    attr_reader :errors
+  end
+
   class ConflictError < StandardError
     extend T::Sig
 
-    sig { params(existing: T.nilable(Record), new: Record).void }
-    def initialize existing, new
-      @existing = existing
-      @new = new
+    sig { params(conflicts: T::Array[[T.nilable(Record), Record]]).void }
+    def initialize(conflicts)
+      @conflicts = conflicts
     end
 
     sig { returns(String) }
     def message
-      <<~MSG
-        The following untracked DNS record already exists and would be overwritten.
-          existing: #{@existing}
-          new:      #{@new}
+      conflicts_text = @conflicts.sort_by { |_existing, new_rec| new_rec.name }.map do |existing_rec, new_rec|
+        "  existing: #{existing_rec}\n  new:      #{new_rec}"
+      end.join("\n\n")
+
+      count = @conflicts.length
+      record_word = count == 1 ? "record" : "records"
+      exists_word = count == 1 ? "exists" : "exist"
+
+      <<~MSG.chomp
+        The following untracked DNS #{record_word} already #{exists_word} and would be overwritten:
+        #{conflicts_text}
       MSG
     end
   end
@@ -41,20 +75,71 @@ module Zonesync
   class ChecksumMismatchError < StandardError
     extend T::Sig
 
-    sig { params(existing: T.nilable(Record), new: Record).void }
-    def initialize existing, new
+    sig {
+      params(
+        existing: T.nilable(Record),
+        new: T.nilable(Record),
+        expected_record: T.nilable(Record),
+        actual_record: T.nilable(Record),
+        missing_hash: T.nilable(String)
+      ).void
+    }
+    def initialize(existing = nil, new = nil, expected_record: nil, actual_record: nil, missing_hash: nil)
       @existing = existing
       @new = new
+      @expected_record = expected_record
+      @actual_record = actual_record
+      @missing_hash = missing_hash
     end
 
     sig { returns(String) }
     def message
+      # V2 manifest integrity violation
+      if @missing_hash
+        return generate_v2_message
+      end
+
+      # V1 checksum mismatch
       <<~MSG
         The zonesync_checksum TXT record does not match the current state of the DNS records. This probably means that someone else has changed them.
           existing: #{@existing}
           new:      #{@new}
       MSG
     end
+
+    private
+
+    sig { returns(String) }
+    def generate_v2_message
+      if @expected_record && @actual_record
+        # Record was modified
+        actual_hash = RecordHash.generate(@actual_record)
+        <<~MSG.chomp
+          The following tracked DNS record has been modified externally:
+            Expected: #{@expected_record.name} #{@expected_record.ttl} #{@expected_record.type} #{@expected_record.rdata} (hash: #{@missing_hash})
+            Actual:   #{@actual_record.name} #{@actual_record.ttl} #{@actual_record.type} #{@actual_record.rdata} (hash: #{actual_hash})
+
+          This probably means someone else has changed it. Use --force to override.
+        MSG
+      elsif @expected_record
+        # Record was deleted
+        <<~MSG.chomp
+          The following tracked DNS record has been deleted externally:
+            Expected: #{@expected_record.name} #{@expected_record.ttl} #{@expected_record.type} #{@expected_record.rdata} (hash: #{@missing_hash})
+            Not found in current remote records.
+
+          This probably means someone else has deleted it. Use --force to override.
+        MSG
+      else
+        # Fallback: we don't have source records to look up details
+        <<~MSG.chomp
+          The following tracked DNS record has been modified or deleted externally:
+            Expected hash: #{@missing_hash} (not found in current records)
+
+          This probably means someone else has changed it. Use --force to override.
+        MSG
+      end
+    end
   end
 
   class DuplicateRecordError < StandardError

data/lib/zonesync/manifest.rb

@@ -2,6 +2,7 @@
 require "sorbet-runtime"
 
 require "zonesync/record"
+require "zonesync/record_hash"
 require "digest"
 
 module Zonesync
@@ -22,13 +23,7 @@ module Zonesync
 
     sig { returns(Zonesync::Record) }
     def generate
-      Record.new(
-        name: "zonesync_manifest.#{zone.origin}",
-        type: "TXT",
-        ttl: 3600,
-        rdata: generate_rdata,
-        comment: nil,
-      )
+      generate_v2
     end
 
     sig { returns(T.nilable(Zonesync::Record)) }
@@ -49,6 +44,18 @@ module Zonesync
       )
     end
 
+    sig { returns(Zonesync::Record) }
+    def generate_v2
+      hashes = diffable_records.map { |record| RecordHash.generate(record) }
+      Record.new(
+        name: "zonesync_manifest.#{zone.origin}",
+        type: "TXT",
+        ttl: 3600,
+        rdata: hashes.join(',').inspect,
+        comment: nil,
+      )
+    end
+
     sig { params(record: Zonesync::Record).returns(T::Boolean) }
     def diffable? record
       if existing?
@@ -58,19 +65,43 @@ module Zonesync
       end
     end
 
+    sig { returns(T::Boolean) }
+    def v1_format?
+      return false unless existing?
+      manifest_data = T.must(existing).rdata[1..-2]
+      # V1 format uses "TYPE:" syntax, v2 uses comma-separated hashes
+      manifest_data.include?(":") || manifest_data.include?(";")
+    end
+
+    sig { returns(T::Boolean) }
+    def v2_format?
+      return false unless existing?
+      !v1_format?
+    end
+
     sig { params(record: Zonesync::Record).returns(T::Boolean) }
     def matches? record
       return false unless existing?
-      hash = T.must(existing)
-        .rdata[1..-2] # remove quotes
-        .split(";")
-        .reduce({}) do |hash, pair|
-          type, short_names = pair.split(":")
-          hash[type] = short_names.split(",")
-          hash
-        end
-      shorthands = hash.fetch(record.type, [])
-      shorthands.include?(shorthand_for(record))
+      manifest_data = T.must(existing).rdata[1..-2] # remove quotes
+
+      # Check if this is v2 format (comma-separated hashes) or v1 format (type:names)
+      if manifest_data.include?(";")
+        # V1 format: "A:@,mail;CNAME:www;MX:@ 10,@ 20"
+        hash = manifest_data
+          .split(";")
+          .reduce({}) do |hash, pair|
+            type, short_names = pair.split(":")
+            hash[type] = short_names.split(",")
+            hash
+          end
+        shorthands = hash.fetch(record.type, [])
+        shorthands.include?(shorthand_for(record))
+      else
+        # V2 format: "1r81el0,60oib3,ky0g92,9pp0kg"
+        expected_hashes = manifest_data.split(",")
+        record_hash = RecordHash.generate(record)
+        expected_hashes.include?(record_hash)
+      end
     end
 
     sig { params(record: Zonesync::Record, with_type: T::Boolean).returns(String) }

data/lib/zonesync/provider.rb

@@ -26,7 +26,7 @@ module Zonesync
     sig { params(other: Provider, force: T::Boolean).returns(T::Array[Operation]) }
     def diff! other, force: false
       operations = diff(other).call
-      Validator.call(operations, self, force: force)
+      Validator.call(operations, self, other, force: force)
       operations
     end
 
@@ -98,6 +98,31 @@ module Zonesync
         return
       end
     end
+
+    private
+
+    sig { params(remote_records: T::Array[Record], expected_hashes: T::Array[String]).returns(T::Array[Record]) }
+    def hash_based_diffable_records(remote_records, expected_hashes)
+      require 'set'
+      expected_set = Set.new(expected_hashes)
+      found_set = Set.new
+      diffable = []
+
+      remote_records.each do |record|
+        hash = RecordHash.generate(record)
+        if expected_set.include?(hash)
+          found_set.add(hash)
+          diffable << record
+        end
+      end
+
+      missing = expected_set - found_set
+      if missing.any?
+        raise ConflictError.new([[nil, diffable.first || remote_records.first]])
+      end
+
+      diffable.sort
+    end
   end
 
   require "zonesync/cloudflare"

data/lib/zonesync/record.rb

@@ -53,6 +53,37 @@ module Zonesync
       string << " ; #{comment}" if comment
       string
     end
+
+    sig { params(other: Record).returns(T::Boolean) }
+    def identical_to?(other)
+      name == other.name && type == other.type && ttl == other.ttl && rdata == other.rdata
+    end
+
+    sig { params(other: Record).returns(T::Boolean) }
+    def conflicts_with?(other)
+      return false unless name == other.name && type == other.type
+
+      case type
+      when "CNAME", "SOA"
+        true
+      when "MX"
+        existing_priority = rdata.split(' ').first
+        new_priority = other.rdata.split(' ').first
+        existing_priority == new_priority
+      else
+        false
+      end
+    end
+
+    sig { params(type: String).returns(T::Boolean) }
+    def self.single_record_per_name?(type)
+      type == "CNAME" || type == "SOA"
+    end
+
+    sig { params(records: T::Array[Record]).returns(T::Array[Record]) }
+    def self.non_meta(records)
+      records.reject { |r| r.manifest? || r.checksum? }
+    end
   end
 end
 

data/lib/zonesync/record_hash.rb

@@ -0,0 +1,15 @@
+# typed: strict
+require "sorbet-runtime"
+require "zlib"
+
+module Zonesync
+  module RecordHash
+    extend T::Sig
+
+    sig { params(record: Record).returns(String) }
+    def self.generate(record)
+      identity = "#{record.name}:#{record.type}:#{record.ttl}:#{record.rdata}"
+      Zlib.crc32(identity).to_s(36)
+    end
+  end
+end

data/lib/zonesync/route53.rb

@@ -4,6 +4,7 @@ require "sorbet-runtime"
 require "zonesync/record"
 require "zonesync/http"
 require "rexml/document"
+require "erb"
 
 module Zonesync
   class Route53 < Provider
@@ -21,7 +22,58 @@ module Zonesync
 
     sig { params(record: Record).void }
     def remove(record)
-      change_record("DELETE", record)
+      if record.type == "TXT"
+        # Route53 requires all TXT records with the same name to be managed together
+        existing_txt_records = records.select do |r|
+          r.name == record.name && r.type == "TXT"
+        end
+
+        if existing_txt_records.length == 1
+          # Only one TXT record, delete it normally
+          change_record("DELETE", record)
+        else
+          # Multiple TXT records - delete all, then recreate without the removed one
+          remaining_txt_records = existing_txt_records.reject { |r| r == record }
+
+          # Use change_records to handle both DELETE and CREATE in one request
+          grouped = [
+            [existing_txt_records, "DELETE"],
+            [remaining_txt_records, "CREATE"]
+          ]
+
+          http.post("", ERB.new(<<~XML, trim_mode: "-").result(binding))
+            <?xml version="1.0" encoding="UTF-8"?>
+            <ChangeResourceRecordSetsRequest xmlns="https://route53.amazonaws.com/doc/2013-04-01/">
+              <ChangeBatch>
+                <Changes>
+                  <%- grouped.each do |records_list, action| -%>
+                  <%- records_grouped = records_list.group_by { |r| [r.name, r.type, r.ttl] } -%>
+                  <%- records_grouped.each do |(name, type, ttl), group_records| -%>
+                  <Change>
+                    <Action><%= action %></Action>
+                    <ResourceRecordSet>
+                      <Name><%= name %></Name>
+                      <Type><%= type %></Type>
+                      <TTL><%= ttl %></TTL>
+                      <ResourceRecords>
+                        <%- group_records.each do |group_record| -%>
+                        <ResourceRecord>
+                          <Value><%= group_record.rdata %></Value>
+                        </ResourceRecord>
+                        <%- end -%>
+                      </ResourceRecords>
+                    </ResourceRecordSet>
+                  </Change>
+                  <%- end -%>
+                  <%- end -%>
+                </Changes>
+              </ChangeBatch>
+            </ChangeResourceRecordSetsRequest>
+          XML
+        end
+      else
+        change_record("DELETE", record)
+      end
     end
 
     sig { params(old_record: Record, new_record: Record).void }
@@ -34,7 +86,19 @@ module Zonesync
     def add(record)
       add_with_duplicate_handling(record) do
         begin
-          change_record("CREATE", record)
+          if record.type == "TXT"
+            # Route53 requires all TXT records with the same name to be combined into a single record set
+            existing_txt_records = records.select do |r|
+              r.name == record.name && r.type == "TXT"
+            end
+            all_txt_records = existing_txt_records + [record]
+
+            # Use UPSERT if records already exist, CREATE if they don't
+            action = existing_txt_records.empty? ? "CREATE" : "UPSERT"
+            change_records(action, all_txt_records)
+          else
+            change_record("CREATE", record)
+          end
         rescue RuntimeError => e
           # Convert Route53-specific duplicate error to standard exception
           if e.message.include?("RRSet already exists")
@@ -75,6 +139,39 @@ module Zonesync
       XML
     end
 
+    sig { params(action: String, records_list: T::Array[Record]).void }
+    def change_records(action, records_list)
+      # Group records by name and type to handle multiple values
+      grouped = records_list.group_by { |r| [r.name, r.type, r.ttl] }
+
+      http.post("", ERB.new(<<~XML, trim_mode: "-").result(binding))
+        <?xml version="1.0" encoding="UTF-8"?>
+        <ChangeResourceRecordSetsRequest xmlns="https://route53.amazonaws.com/doc/2013-04-01/">
+          <ChangeBatch>
+            <Changes>
+              <%- grouped.each do |(name, type, ttl), records| -%>
+              <Change>
+                <Action><%= action %></Action>
+                <ResourceRecordSet>
+                  <Name><%= name %></Name>
+                  <Type><%= type %></Type>
+                  <TTL><%= ttl %></TTL>
+                  <ResourceRecords>
+                    <%- records.each do |record| -%>
+                    <ResourceRecord>
+                      <Value><%= record.rdata %></Value>
+                    </ResourceRecord>
+                    <%- end -%>
+                  </ResourceRecords>
+                </ResourceRecordSet>
+              </Change>
+              <%- end -%>
+            </Changes>
+          </ChangeBatch>
+        </ChangeResourceRecordSetsRequest>
+      XML
+    end
+
     sig { params(el: REXML::Element).returns(T::Array[Record]) }
     def to_records(el)
       el.elements.collect("ResourceRecords/ResourceRecord") do |rr|

data/lib/zonesync/sync.rb

@@ -21,13 +21,24 @@ module Zonesync
         end
       end
 
-      schecksum = source.manifest.generate_checksum
-      dchecksum = destination.manifest.existing_checksum
-      if schecksum != dchecksum
-        if dchecksum
-          operations << [:change, [dchecksum, schecksum]]
-        else
-          operations << [:add, [schecksum]]
+      # Only sync checksums for v1 manifests (v2 manifests provide integrity via hashes)
+      source_will_generate_v2 = !source.manifest.existing? # No existing manifest = will generate v2
+      dest_has_checksum = destination.manifest.existing_checksum
+      dest_has_v1_manifest = destination.manifest.existing? && destination.manifest.v1_format?
+
+      if source_will_generate_v2 && dest_has_checksum
+        # Transitioning to v2: remove old checksum
+        operations << [:remove, [dest_has_checksum]]
+      elsif !source_will_generate_v2 && (source.manifest.v1_format? || dest_has_v1_manifest)
+        # Both source and dest use v1 format: sync checksum
+        schecksum = source.manifest.generate_checksum
+        dchecksum = destination.manifest.existing_checksum
+        if schecksum != dchecksum
+          if dchecksum
+            operations << [:change, [dchecksum, schecksum]]
+          else
+            operations << [:add, [schecksum]]
+          end
         end
       end
 

data/lib/zonesync/validator.rb

@@ -1,28 +1,44 @@
 # typed: strict
 require "sorbet-runtime"
+require "zonesync/record_hash"
 
 module Zonesync
-  Validator = Struct.new(:operations, :destination) do
+  Validator = Struct.new(:operations, :destination, :source) do
     extend T::Sig
 
-    sig { params(operations: T::Array[Operation], destination: Provider, force: T::Boolean).void }
-    def self.call(operations, destination, force: false)
-      new(operations, destination).call(force: force)
+    sig { params(operations: T::Array[Operation], destination: Provider, source: T.nilable(Provider), force: T::Boolean).void }
+    def self.call(operations, destination, source = nil, force: false)
+      new(operations, destination, source).call(force: force)
     end
 
     sig { params(force: T::Boolean).void }
     def call(force: false)
-      if operations.any? && !manifest.existing?
-        raise MissingManifestError.new(manifest.generate)
+      validation_error = ValidationError.new
+
+      if !force && operations.any? && !manifest.existing?
+        validation_error.add(MissingManifestError.new(manifest.generate))
       end
-      if !force && manifest.existing_checksum && manifest.existing_checksum != manifest.generate_checksum
-        raise ChecksumMismatchError.new(manifest.existing_checksum, manifest.generate_checksum)
+
+      if !force && manifest.v1_format? && manifest.existing_checksum && manifest.existing_checksum != manifest.generate_checksum
+        validation_error.add(ChecksumMismatchError.new(manifest.existing_checksum, manifest.generate_checksum))
       end
-      operations.each do |method, args|
-        if method == :add
-          validate_addition args.first
-        end
+
+      if !force && manifest.v2_format?
+        integrity_error = validate_v2_manifest_integrity
+        validation_error.add(integrity_error) if integrity_error
       end
+
+      conflicts = operations.map do |method, args|
+        method == :add ? validate_addition(args.first, force: force) : nil
+      end.compact
+      validation_error.add(ConflictError.new(conflicts)) if conflicts.any?
+
+      if validation_error.errors.length == 1
+        raise validation_error.errors.first
+      elsif validation_error.errors.length > 1
+        raise validation_error
+      end
+
       nil
     end
 
@@ -33,16 +49,96 @@ module Zonesync
       destination.manifest
     end
 
-    sig { params(record: Record).void }
-    def validate_addition record
-      return if manifest.matches?(record)
+    sig { returns(T.nilable(ChecksumMismatchError)) }
+    def validate_v2_manifest_integrity
+      manifest_data = T.must(manifest.existing).rdata[1..-2]
+      expected_hashes = manifest_data.split(",")
+      actual_records = Record.non_meta(destination.records)
+      actual_hash_to_record = actual_records.map { |r| [RecordHash.generate(r), r] }.to_h
+
+      missing_hash = expected_hashes.find { |hash| !actual_hash_to_record.key?(hash) }
+      return nil unless missing_hash
+
+      expected_record = find_expected_record(missing_hash)
+      actual_record = find_modified_record(expected_record, actual_records)
+
+      ChecksumMismatchError.new(
+        expected_record: expected_record,
+        actual_record: actual_record,
+        missing_hash: missing_hash
+      )
+    end
+
+    sig { params(missing_hash: String).returns(T.nilable(Record)) }
+    def find_expected_record(missing_hash)
+      return nil unless source
+
+      source_records = Record.non_meta(source.records)
+      source_records.find { |r| RecordHash.generate(r) == missing_hash }
+    end
+
+    sig { params(expected_record: T.nilable(Record), actual_records: T::Array[Record]).returns(T.nilable(Record)) }
+    def find_modified_record(expected_record, actual_records)
+      return nil unless expected_record
+
+      # For CNAME and SOA, only one record per name is allowed, so check for modification
+      # For other types (A, AAAA, TXT, MX), only check if there's exactly one record
+      # with that name/type - if there are multiples, we can't determine which one it "became"
+      if Record.single_record_per_name?(expected_record.type)
+        actual_records.find do |r|
+          r.name == expected_record.name && r.type == expected_record.type
+        end
+      else
+        matching_records = actual_records.select do |r|
+          r.name == expected_record.name && r.type == expected_record.type
+        end
+        matching_records.first if matching_records.count == 1
+      end
+    end
+
+    sig { params(record: Record, force: T::Boolean).returns(T.nilable([T.nilable(Record), Record])) }
+    def validate_addition record, force: false
+      return nil if manifest.matches?(record)
+      return nil if force
+
+      conflicting_record = if manifest.v2_format?
+        expected_hashes = manifest.existing.rdata[1..-2].split(",")
+        find_v2_conflict(record, expected_hashes)
+      elsif manifest.existing?
+        find_v1_conflict(record)
+      else
+        find_unmanaged_conflict(record)
+      end
+
+      return nil if !conflicting_record
+      return nil if conflicting_record == record
+      [conflicting_record, record]
+    end
+
+    sig { params(record: Record, expected_hashes: T::Array[String]).returns(T.nilable(Record)) }
+    def find_v2_conflict(record, expected_hashes)
+      destination.records.find do |r|
+        next if r.manifest? || r.checksum?
+        next if expected_hashes.include?(RecordHash.generate(r))
+        next if r.identical_to?(record)
+
+        r.conflicts_with?(record)
+      end
+    end
+
+    sig { params(record: Record).returns(T.nilable(Record)) }
+    def find_v1_conflict(record)
       shorthand = manifest.shorthand_for(record, with_type: true)
-      conflicting_record = destination.records.find do |r|
+      destination.records.find do |r|
         manifest.shorthand_for(r, with_type: true) == shorthand
       end
-      return if !conflicting_record
-      return if conflicting_record == record
-      raise Zonesync::ConflictError.new(conflicting_record, record)
+    end
+
+    sig { params(record: Record).returns(T.nilable(Record)) }
+    def find_unmanaged_conflict(record)
+      destination.records.find do |r|
+        r.identical_to?(record)
+      end
     end
   end
 end

data/lib/zonesync/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zonesync
-  VERSION = "0.10.0"
+  VERSION = "0.12.0"
 end

data/lib/zonesync.rb

@@ -7,6 +7,7 @@ require "zonesync/provider"
 require "zonesync/cli"
 require "zonesync/rake"
 require "zonesync/errors"
+require "zonesync/record_hash"
 
 begin # optional active_support dependency
   require "active_support"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zonesync
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Micah Geisel
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-07-19 00:00:00.000000000 Z
+date: 2025-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -148,6 +148,7 @@ extra_rdoc_files: []
 files:
 - ".envrc"
 - ".rspec"
+- CLAUDE.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -166,6 +167,7 @@ files:
 - lib/zonesync/provider.rb
 - lib/zonesync/rake.rb
 - lib/zonesync/record.rb
+- lib/zonesync/record_hash.rb
 - lib/zonesync/route53.rb
 - lib/zonesync/sync.rb
 - lib/zonesync/validator.rb