zonesync 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed23482c3eeed63566e03e79231562447d9f63c09a2d382151d6cd3b123b3502
-  data.tar.gz: 45c154c9bd89d9f1ad97df54ec0c4d30ab49995716fbd3e519b4381f890c2259
+  metadata.gz: 3e2ac350c2fe58aaed3387c001755daba2e460747b09e12ca187e3643895cfec
+  data.tar.gz: b9c28c96bfcb6e4964060aa6fac6b05af5533d7903dd74b76850cc1d58904158
 SHA512:
-  metadata.gz: 2870e1fd94f37248ddd609da2a90be47e9487f11e371043b48ed00465fbc727f69fd36614d83b8adf4ff7661bc90dfbbeb100c964c572a49b2ad97ab36b4ad97
-  data.tar.gz: 3dcde654cdbdcaa806734b41c99286ba4724b812c58a4b22af7232bde1e5410892edda80b4475918b512738750a44a709c87c0af4b3483d6a9cc669bc12158b5
+  metadata.gz: 8861b5bbcb843c30e3017eb2989fc3391913452246d5a6d798b8ccac677430ae845f5189271a6a07d8f4b7f72f07db34153f480281a3e6d398e135c3b0b28cf1
+  data.tar.gz: 6a471b920e9cd971a023eca9992894c65f43ef9e6fffe9d873abb32706f265db98043fdeb7e749cd7a87feeda0faefac8bd4b1477f27059e28b8e793f3f091fe

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/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

@@ -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_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,5 +1,6 @@
 # typed: strict
 require "sorbet-runtime"
+require "zonesync/record_hash"
 
 module Zonesync
   Validator = Struct.new(:operations, :destination) do
@@ -12,15 +13,16 @@ module Zonesync
 
     sig { params(force: T::Boolean).void }
     def call(force: false)
-      if operations.any? && !manifest.existing?
+      if !force && operations.any? && !manifest.existing?
         raise MissingManifestError.new(manifest.generate)
       end
-      if !force && manifest.existing_checksum && manifest.existing_checksum != manifest.generate_checksum
+      # Only validate checksums for v1 manifests (v2 manifests provide integrity via hashes)
+      if !force && manifest.v1_format? && manifest.existing_checksum && manifest.existing_checksum != manifest.generate_checksum
         raise ChecksumMismatchError.new(manifest.existing_checksum, manifest.generate_checksum)
       end
       operations.each do |method, args|
         if method == :add
-          validate_addition args.first
+          validate_addition args.first, force: force
         end
       end
       nil
@@ -33,13 +35,65 @@ module Zonesync
       destination.manifest
     end
 
-    sig { params(record: Record).void }
-    def validate_addition record
+    sig { params(record: Record, force: T::Boolean).void }
+    def validate_addition record, force: false
       return if manifest.matches?(record)
-      shorthand = manifest.shorthand_for(record, with_type: true)
-      conflicting_record = destination.records.find do |r|
-        manifest.shorthand_for(r, with_type: true) == shorthand
+      return if force
+
+      # Use hash-based conflict detection when we have a v2 manifest
+      if manifest.existing? && !manifest.existing.rdata[1..-2].include?(";")
+        # V2 hash-based manifest: check for untracked records that conflict
+        record_hash = RecordHash.generate(record)
+        expected_hashes = manifest.existing.rdata[1..-2].split(",")
+
+        # Find conflicting records that would be overwritten by this addition
+        conflicting_record = destination.records.find do |r|
+          next if r.manifest? || r.checksum?
+
+          # Skip if this record is tracked in the manifest
+          r_hash = RecordHash.generate(r)
+          next if expected_hashes.include?(r_hash)
+
+          # Skip if it's exactly the same record (we're just starting to track it)
+          next if r.name == record.name && r.type == record.type && r.ttl == record.ttl && r.rdata == record.rdata
+
+          # Check for conflicts based on record type
+          case record.type
+          when "CNAME", "SOA"
+            # These types only allow one record per name
+            r.name == record.name && r.type == record.type
+          when "MX"
+            # MX records conflict if same name and same priority (first part of rdata)
+            if r.name == record.name && r.type == record.type
+              existing_priority = r.rdata.split(' ').first
+              new_priority = record.rdata.split(' ').first
+              existing_priority == new_priority
+            end
+          else
+            # For other types (A, AAAA, TXT, etc.), multiple records are allowed
+            # Only conflict if trying to add identical record (but we already checked that above)
+            false
+          end
+        end
+      else
+        # V1 name-based manifest or no manifest
+        if manifest.existing?
+          # V1 name-based manifest: use old shorthand logic
+          shorthand = manifest.shorthand_for(record, with_type: true)
+          conflicting_record = destination.records.find do |r|
+            manifest.shorthand_for(r, with_type: true) == shorthand
+          end
+        else
+          # No manifest: only conflict if exact same record exists
+          conflicting_record = destination.records.find do |r|
+            r.name == record.name &&
+            r.type == record.type &&
+            r.ttl == record.ttl &&
+            r.rdata == record.rdata
+          end
+        end
       end
+
       return if !conflicting_record
       return if conflicting_record == record
       raise Zonesync::ConflictError.new(conflicting_record, record)

data/lib/zonesync/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zonesync
-  VERSION = "0.10.0"
+  VERSION = "0.11.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.11.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-09-18 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