zonesync 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28f9ce19995f365781be12a19d5275cdf6e8448a9e48024032071739c8742784
-  data.tar.gz: 668226c517ca89940c1d74dd25a1ce54777cee4bdb98a27ccde7607c412b1802
+  metadata.gz: 3e2ac350c2fe58aaed3387c001755daba2e460747b09e12ca187e3643895cfec
+  data.tar.gz: b9c28c96bfcb6e4964060aa6fac6b05af5533d7903dd74b76850cc1d58904158
 SHA512:
-  metadata.gz: 897243ccc6bbf7812713a9acc1238018affce8691d03cabc8e3cf5ea11efc92be23dc79aee80c7f6da969d94aae471bff1a5a9ddcce6c11bd4089d586d18bb89
-  data.tar.gz: e633c1772ba7da543d75c93528ed1a54a4a57b79a7ff9e25fdb766fb4cb4ee7040048735c192d2f4f828e9a961044d59bca52e1e86c3064f87a4e28eda8efd47
+  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/Gemfile

@@ -4,3 +4,4 @@ source 'https://rubygems.org'
 gemspec
 
 gem "debug"
+gem "activesupport"

data/lib/zonesync/cli.rb

@@ -1,12 +1,19 @@
+# typed: strict
+require "sorbet-runtime"
+
 require "thor"
 
 module Zonesync
   class CLI < Thor
+    extend T::Sig
+
     default_command :sync
     desc "sync --source=Zonefile --destination=zonesync", "syncs the contents of the Zonefile to the DNS server configured in Rails.application.credentials.zonesync"
     option :source, default: "Zonefile", desc: "path to the zonefile"
     option :destination, default: "zonesync", desc: "key to the DNS server configuration in Rails.application.credentials"
     method_option :dry_run, type: :boolean, default: false, aliases: :n, desc: "log operations to STDOUT but don't perform the sync"
+    method_option :force, type: :boolean, default: false, desc: "ignore checksum mismatches and force the sync"
+    sig { void }
     def sync
       kwargs = options.to_hash.transform_keys(&:to_sym)
       Zonesync.call(**kwargs)
@@ -18,11 +25,13 @@ module Zonesync
     desc "generate --source=zonesync --destination=Zonefile", "generates a Zonefile from the DNS server configured in Rails.application.credentials.zonesync"
     option :source, default: "zonesync", desc: "key to the DNS server configuration in Rails.application.credentials"
     option :destination, default: "Zonefile", desc: "path to the zonefile"
+    sig { void }
     def generate
       kwargs = options.to_hash.transform_keys(&:to_sym)
       Zonesync.generate(**kwargs)
     end
 
+    sig { returns(TrueClass) }
     def self.exit_on_failure? = true
   end
 end

data/lib/zonesync/cloudflare.rb

@@ -1,83 +1,107 @@
+# typed: strict
+require "sorbet-runtime"
+
 require "zonesync/record"
 require "zonesync/http"
 
 module Zonesync
   class Cloudflare < Provider
+    sig { returns(String) }
     def read
-      ([fake_soa] + all.keys.map do |hash|
-        Record.new(hash)
-      end).map(&:to_s).join("\n") + "\n"
+      records = [fake_soa] + all.keys
+      records.map(&:to_s).join("\n") + "\n"
     end
 
+    sig { params(record: Record).void }
     def remove record
-      id = all.fetch(record.to_h)
+      id = all.fetch(record)
       http.delete("/#{id}")
     end
 
+    sig { params(old_record: Record, new_record: Record).void }
     def change old_record, new_record
-      id = all.fetch(old_record.to_h)
-      http.patch("/#{id}", {
-        name: new_record[:name],
-        type: new_record[:type],
-        ttl: new_record[:ttl],
-        content: new_record[:rdata],
-        comment: new_record[:comment],
-      })
+      id = all.fetch(old_record)
+      http.patch("/#{id}", to_hash(new_record))
     end
 
+    sig { params(record: Record).void }
     def add record
-      http.post(nil, {
-        name: record[:name],
-        type: record[:type],
-        ttl: record[:ttl],
-        content: record[:rdata],
-        comment: record[:comment],
-      })
+      add_with_duplicate_handling(record) do
+        begin
+          http.post("", to_hash(record))
+        rescue RuntimeError => e
+          # Convert CloudFlare-specific duplicate error to standard exception
+          if e.message.include?('"code":81058') && e.message.include?("An identical record already exists")
+            raise DuplicateRecordError.new(record, "CloudFlare error 81058")
+          else
+            # Re-raise other errors
+            raise
+          end
+        end
+      end
     end
 
+    sig { returns(T::Hash[Record, String]) }
     def all
-      @all ||= begin
-        response = http.get(nil)
-        response["result"].reduce({}) do |map, attrs|
-          map.merge to_record(attrs) => attrs["id"]
-        end
+      response = http.get("")
+      response["result"].reduce({}) do |map, attrs|
+        map.merge to_record(attrs) => attrs["id"]
       end
     end
 
     private
 
+    sig { params(record: Record).returns(T::Hash[String, String]) }
+    def to_hash record
+      hash = record.to_h
+      content = hash.delete(:rdata)
+
+      if record.type == "MX"
+        # For MX records, split "priority hostname" into separate fields
+        priority, hostname = T.must(content).split(" ", 2)
+        hash[:priority] = priority.to_i
+        hash[:content] = hostname.sub(/\.$/, "") # remove trailing dot
+      else
+        hash[:content] = content
+      end
+
+      hash[:comment] = hash.delete(:comment) # maintain original order
+      hash
+    end
+
+    sig { params(attrs: T::Hash[String, String]).returns(Record) }
     def to_record attrs
       rdata = attrs["content"]
       if %w[CNAME MX].include?(attrs["type"])
-        rdata = normalize_trailing_period(rdata)
+        rdata = normalize_trailing_period(T.must(rdata))
       end
       if attrs["type"] == "MX"
         rdata = "#{attrs["priority"]} #{rdata}"
       end
       if %w[TXT SPF NAPTR].include?(attrs["type"])
-        rdata = normalize_quoting(rdata)
-      end
-      if attrs["type"] == "TXT"
-        rdata = normalize_quoting(rdata)
+        rdata = normalize_quoting(T.must(rdata))
       end
       Record.new(
-        name: normalize_trailing_period(attrs["name"]),
+        name: normalize_trailing_period(T.must(attrs["name"])),
         type: attrs["type"],
         ttl: attrs["ttl"].to_i,
         rdata:,
         comment: attrs["comment"],
-      ).to_h
+      )
     end
 
+    sig { params(value: String).returns(String) }
     def normalize_trailing_period value
       value =~ /\.$/ ? value : value + "."
     end
 
+    sig { params(value: String).returns(String) }
     def normalize_quoting value
-      value =~ /^".+"$/ ? value : %("#{value}") # handle quote wrapping
+      value = value =~ /^".+"$/ ? value : %("#{value}") # handle quote wrapping
       value.gsub('" "', "") # handle multiple txt record joining
     end
 
+    sig { returns(Zonesync::Record) }
     def fake_soa
       zone_name = http.get("/..")["result"]["name"]
       Record.new(
@@ -89,19 +113,20 @@ module Zonesync
       )
     end
 
+    sig { returns(HTTP) }
     def http
       return @http if @http
-      @http = HTTP.new("https://api.cloudflare.com/client/v4/zones/#{credentials[:zone_id]}/dns_records")
-      @http.before_request do |request|
+      @http = T.let(HTTP.new("https://api.cloudflare.com/client/v4/zones/#{config.fetch(:zone_id)}/dns_records"), T.nilable(Zonesync::HTTP))
+      T.must(@http).before_request do |request|
         request["Content-Type"] = "application/json"
-        if credentials[:token]
-          request["Authorization"] = "Bearer #{credentials[:token]}"
+        if config[:token]
+          request["Authorization"] = "Bearer #{config[:token]}"
         else
-          request["X-Auth-Email"] = credentials[:email]
-          request["X-Auth-Key"] = credentials[:key]
+          request["X-Auth-Email"] = config.fetch(:email)
+          request["X-Auth-Key"] = config.fetch(:key)
         end
       end
-      @http
+      T.must(@http)
     end
   end
 end

data/lib/zonesync/diff.rb

@@ -1,11 +1,20 @@
+# typed: strict
+require "sorbet-runtime"
+
 require "diff/lcs"
 
 module Zonesync
-  class Diff < Struct.new(:from, :to)
+  Operation = T.type_alias { [Symbol, T::Array[Record]] }
+
+  Diff = Struct.new(:from, :to) do
+    extend T::Sig
+
+    sig { params(from: T::Array[Record], to: T::Array[Record]).returns(T.untyped) }
     def self.call(from:, to:)
       new(from, to).call
     end
 
+    sig { returns(T::Array[[Symbol, T::Array[Record]]]) }
     def call
       changes = ::Diff::LCS.sdiff(from, to)
       changes.map do |change|

data/lib/zonesync/errors.rb

@@ -1,10 +1,17 @@
+# typed: strict
+require "sorbet-runtime"
+
 module Zonesync
   class ConflictError < StandardError
+    extend T::Sig
+
+    sig { params(existing: T.nilable(Record), new: Record).void }
     def initialize existing, new
       @existing = existing
       @new = new
     end
 
+    sig { returns(String) }
     def message
       <<~MSG
         The following untracked DNS record already exists and would be overwritten.
@@ -15,10 +22,14 @@ module Zonesync
   end
 
   class MissingManifestError < StandardError
+    extend T::Sig
+
+    sig { params(manifest: Record).void }
     def initialize manifest
       @manifest = manifest
     end
 
+    sig { returns(String) }
     def message
       <<~MSG
         The zonesync_manifest TXT record is missing. If this is the very first sync, make sure the Zonefile matches what's on the DNS server exactly. Otherwise, someone else may have removed it.
@@ -28,11 +39,15 @@ module Zonesync
   end
 
   class ChecksumMismatchError < StandardError
+    extend T::Sig
+
+    sig { params(existing: T.nilable(Record), new: Record).void }
     def initialize existing, new
       @existing = existing
       @new = new
     end
 
+    sig { returns(String) }
     def message
       <<~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.
@@ -41,5 +56,25 @@ module Zonesync
       MSG
     end
   end
+
+  class DuplicateRecordError < StandardError
+    extend T::Sig
+
+    sig { params(record: Record, provider_message: T.nilable(String)).void }
+    def initialize record, provider_message = nil
+      @record = record
+      @provider_message = provider_message
+    end
+
+    sig { returns(String) }
+    def message
+      msg = "Record already exists: #{@record.name} #{@record.type}"
+      msg += " (#{@provider_message})" if @provider_message
+      msg
+    end
+
+    sig { returns(Record) }
+    attr_reader :record
+  end
 end
 

data/lib/zonesync/generate.rb

@@ -0,0 +1,14 @@
+# typed: strict
+require "sorbet-runtime"
+
+module Zonesync
+  Generate = Struct.new(:source, :destination) do
+    extend T::Sig
+
+    sig { void }
+    def call
+      destination.write(source.read)
+      nil
+    end
+  end
+end

data/lib/zonesync/http.rb

@@ -1,38 +1,51 @@
+# typed: strict
+require "sorbet-runtime"
+
 require "net/http"
 require "json"
 
 module Zonesync
-  class HTTP < Struct.new(:base)
-    def initialize(...)
-      super 
-      @before_request = []
-      @after_response = []
+  HTTP = Struct.new(:base) do
+    extend T::Sig
+
+    sig { params(base: String).void }
+    def initialize(base)
+      super
+      @before_request = T.let([], T::Array[T.untyped])
+      @after_response = T.let([], T::Array[T.untyped])
     end
 
+    sig { params(path: String).returns(T.untyped) }
     def get path
       request("get", path)
     end
 
+    sig { params(path: String, body: T.untyped).returns(T.untyped) }
     def post path, body
       request("post", path, body)
     end
 
+    sig { params(path: String, body: T.untyped).returns(T.untyped) }
     def patch path, body
       request("patch", path, body)
     end
 
+    sig { params(path: String).returns(T.untyped) }
     def delete path
       request("delete", path)
     end
 
+    sig { params(block: T.proc.params(arg0: T.untyped, arg1: T.untyped, arg2: T.untyped).void).void }
     def before_request &block
       @before_request << block
     end
 
+    sig { params(block: T.proc.params(arg0: T.untyped).void).void }
     def after_response &block
       @after_response << block
     end
 
+    sig { params(method: String, path: String, body: T.untyped).returns(T.untyped) }
     def request method, path, body=nil
       uri = URI.parse("#{base}#{path}")
       request = Net::HTTP.const_get(method.to_s.capitalize).new(uri.path)
@@ -42,12 +55,15 @@ module Zonesync
       end
 
       response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
-        body = JSON.dump(body) if request.fetch("Content-Type", "").include?("application/json")
-        http.request(request, body)
+        if request.fetch("Content-Type", "").include?("application/json")
+          http.request(request, JSON.dump(body))
+        else
+          http.request(request, body)
+        end
       end
 
       @after_response.each do |block|
-        call(response)
+        block.call(response)
       end
 
       raise response.body unless response.code =~ /^20.$/

data/lib/zonesync/logger.rb

@@ -1,24 +1,29 @@
+# typed: strict
+require "sorbet-runtime"
+
 require "logger"
 require "fileutils"
 
-class Logger
-  def self.log method, args, dry_run: false
-    loggers = [::Logger.new(STDOUT)]
+module Zonesync
+  class Logger
+    extend T::Sig
 
-    if !dry_run
-      FileUtils.mkdir_p("log")
-      loggers << ::Logger.new("log/zonesync.log")
-    end
+    sig { params(method: Symbol, records: T::Array[Record], dry_run: T::Boolean).void }
+    def self.log method, records, dry_run: false
+      loggers = [::Logger.new(STDOUT)]
 
-    loggers.each do |logger|
-      operation = case args
-      when Array
-        (args.length == 2 ? "\n" : "") +
-          args.map { |r| r.to_h.values.join(" ") }.join("->\n")
-      else
-        args.to_h.values.join(" ")
+      if !dry_run
+        FileUtils.mkdir_p("log")
+        loggers << ::Logger.new("log/zonesync.log")
+      end
+
+      loggers.each do |logger|
+        operation =
+          (records.length == 2 ? "\n" : "") +
+          records.map { |r| r.to_h.values.join(" ") }.join("->\n")
+        logger.info "Zonesync: #{method.capitalize} #{operation}"
       end
-      logger.info "Zonesync: #{method.capitalize} #{operation}"
     end
   end
 end
+