ezdyn 0.2.2

data/lib/ezdyn/record.rb

@@ -0,0 +1,142 @@
+module EZDyn
+  # Abstraction of Dyn REST API DNS records.
+  class Record
+    # Default TTL (time to live) for new records
+    DefaultTTL = 300
+
+    # @private
+    def initialize(client:, raw: nil, uri: nil, type: nil, fqdn: nil, value: nil, ttl: nil, record_id: nil)
+      @client = client
+      @exists = nil
+      @type = RecordType.find(type)
+      @fqdn = fqdn
+      @value = value
+      @ttl = ttl
+      @in_sync = false
+
+      if not raw.nil?
+        self.sync_raw(raw)
+
+      elsif not uri.nil?
+        @uri = uri.gsub(%r{^/?(REST/)?}, "")
+        if @uri !~ %r{^[A-Za-z]+Record/[^/]+/[^/]+/[0-9]+}
+          raise "Invalid Record URI: '#{uri}'"
+        end
+
+        type_uri_name, zone, fqdn, record_id = @uri.split('/')
+
+        @type = RecordType.find(type_uri_name)
+        @fqdn = fqdn
+        @record_id = record_id
+        @zone = Zone.new(client: @client, name: zone)
+        @exists = true
+      end
+    end
+
+    # Returns the record type.
+    def type
+      self.sync! if @type.nil?
+      @type
+    end
+
+    # Returns the TTL of this record.
+    def ttl
+      self.sync! if @ttl.nil?
+      @ttl
+    end
+
+    # Returns the FQDN of this record.
+    def fqdn
+      self.sync! if @fqdn.nil?
+      @fqdn
+    end
+
+    # Returns the record data value.
+    def value
+      self.sync! if @value.nil?
+      @value
+    end
+
+    # Returns the Dyn REST API ID for this record.
+    def record_id
+      self.sync! if @record_id.nil?
+      @record_id
+    end
+
+    # Returns the zone of this record.
+    def zone
+      @zone ||= @client.guess_zone(fqdn: self.fqdn)
+    end
+
+    # Returns whether this record existed at its last sync.
+    def exists?
+      @exists
+    end
+
+    # Returns whether this record has been synced.
+    def in_sync?
+      @in_sync
+    end
+
+    # @private
+    def uri
+      if @uri.nil?
+        "#{self.type.uri_name}/#{self.zone.name}/#{self.fqdn}/#{self.record_id}"
+      else
+        @uri
+      end
+    end
+
+    # Attempts to sync the record to the API.
+    #
+    # @raise [RuntimeError] if the record could not be synced.
+    # @raise [RuntimeError] if more than one record matches this record.
+    # @raise [RuntimeError] if returned data was not in an expected format.
+    def sync!
+      return self if self.in_sync?
+
+      data = @client.fetch_uri_data(uri: self.uri)
+      if data.is_a? Array
+        if data.count == 0
+          @in_sync = true
+          @exists = false
+          return self
+
+        elsif data.count > 1
+          raise "More than one record was found"
+
+        end
+      end
+
+      if data.is_a? Array and data.count == 1
+        data = data.first
+      end
+
+      if data.is_a? Hash
+        self.sync_raw(data)
+
+      else
+        raise "Unrecognized data: #{data.class} #{data}"
+      end
+
+      self
+    end
+
+    # @private
+    def sync_raw(raw)
+      @zone = Zone.new(client: @client, name: raw["zone"])
+      @ttl = raw["ttl"]
+      @fqdn = raw["fqdn"]
+      @type = RecordType.find(raw["record_type"])
+      @record_id = raw["record_id"].to_s
+      @value = raw["rdata"][@type.value_key]
+      @in_sync = true
+      @exists = true
+    end
+
+    # Attempt to delete this record.
+    def delete!
+      @client.delete(record: self)
+    end
+  end
+end

data/lib/ezdyn/record_type.rb

@@ -0,0 +1,78 @@
+module EZDyn
+  # Encapsulates the properties of supported record types
+  class RecordType
+    # @private
+    @@types = []
+
+    # Check if a type is valid.
+    #
+    # @return [Boolean] Whether the type given is valid.
+    def self.valid_type?(t)
+      not RecordType.find(t).nil?
+    end
+
+    # The URI path element that signals this record type.
+    attr_reader :uri_name
+
+    # The dict key for this record type's `rdata` value.
+    attr_reader :value_key
+
+    # RecordType constructor. In general there is no reason to call this method
+    # directly as all known record types are created at file load time. Instead
+    # the #find method is the preferred way to fetch a RecordType object.
+    #
+    # @param name [Symbol] The canonical type of the record.
+    # @param uri_name [String] URI path element for the record type.
+    # @param value_key [String] Record data value dict key.
+    def initialize(name:, uri_name:, value_key:)
+      EZDyn.debug { "RecordType.new( name: #{name}, uri_name: #{uri_name}, value_key: #{value_key} )" }
+      @name =  name
+      @uri_name = uri_name
+      @value_key = value_key
+    end
+
+    # Converts several possible representations of a RecordType into an
+    # appropriate class instance. Pass in a RecordType instance, a String or
+    # Symbol of the type name or the String fragment of a REST API URI.
+    #
+    # @param to_find [EZDyn::RecordType, String, Symbol] Representation of the
+    #   paramter to be found.
+    # @return [EZDyn::RecordType] The class instance requested or `nil` if none
+    #   is found.
+    def self.find(to_find)
+      EZDyn.debug { "RecordType#find( [#{to_find.class}] #{to_find} )" }
+      if to_find.is_a? RecordType
+        return to_find
+
+      else
+        return @@types.find { |ctype| ctype.name == to_find.to_s.upcase } ||
+                 @@types.find { |ctype| ctype.uri_name.downcase == to_find.to_s.downcase }
+      end
+
+      EZDyn.debug { "No such RecordType was found" }
+    end
+
+    # Provides an all-caps String representation of the record type, eg 'A','CNAME'.
+    #
+    # @return [String] The name of the record type.
+    def name
+      @name.to_s.upcase
+    end
+
+    # Converts the RecordType to the all-caps String of the record type.
+    #
+    # @return [String] The displayable String representation.
+    def to_s
+      self.name
+    end
+
+    # initialize cache of supported types
+    [
+      { name: :any,   uri_name: "ANYRecord",   value_key: nil       },
+      { name: :a,     uri_name: "ARecord",     value_key: "address" },
+      { name: :cname, uri_name: "CNAMERecord", value_key: "cname"   },
+    ].each do |args|
+      @@types << EZDyn::RecordType.new(**args)
+    end
+  end
+end

data/lib/ezdyn/response.rb

@@ -0,0 +1,82 @@
+module EZDyn
+  # Abstraction of a Dyn REST API response.
+  class Response
+    # @private
+    def initialize(response)
+      @response = response
+      EZDyn.debug { "API RESPONSE: #{@response.body}" }
+      if @response.body =~ %r{^/REST/Job/[0-9]+$}
+        EZDyn.debug { "Response delayed! Try again later!" }
+        @raw = {
+          "status" => "delayed",
+          "job_id" => @response.body.split('/').last,
+          "msgs" => [],
+          "data" => {},
+        }
+      else
+        @raw = JSON.parse(@response.body)
+      end
+    end
+
+    # Returns the status message of the response.
+    #
+    # @return [String] The status field of the response.
+    def status
+      @raw["status"]
+    end
+
+    # Was the response successful?
+    #
+    # @return [Boolean] Returns true if the response was successful.
+    def success?
+      self.status == "success"
+    end
+
+    # Do we have to wait for the response?
+    #
+    # @return [Boolean] Returns true if the response is delayed and you
+    #   must wait and try again.
+    def delayed?
+      self.status == "delayed"
+    end
+
+    # The job ID returned by the response.
+    #
+    # @return [String] The job ID of the response.
+    def job_id
+      @raw["job_id"]
+    end
+
+    # The payload data from the response.
+    #
+    # @return [Hash] The payload data of the response.
+    def data
+      @raw["data"]
+    end
+
+    # Full version of the descriptive response message with log levels and
+    # error codes.
+    #
+    # @return [String] Full descriptive message of the response with error
+    #   codes and log levels.
+    def full_message
+      @raw["msgs"].collect do |msg|
+        "[#{msg["SOURCE"]}] #{msg["LVL"]} (#{msg["ERR_CD"]}): #{msg[msg["LVL"]]}"
+      end.join("\n")
+    end
+
+    # The simple descriptive message of the response from the API.
+    #
+    # @return [String] Descriptive message of the response.
+    def simple_message
+      @raw["msgs"].collect { |m| m[m["LVL"]] }.join("\n")
+    end
+
+    # All error codes returned by the response.
+    #
+    # @return [Array<String>] An array of error codes returned by the response.
+    def error_codes
+      @raw["msgs"].collect { |m| m["ERR_CD"] }.compact.uniq
+    end
+  end
+end

data/lib/ezdyn/version.rb

@@ -0,0 +1,4 @@
+module EZDyn
+  # The version number of the library.
+  VERSION = "0.2.2"
+end

data/lib/ezdyn/zone.rb

@@ -0,0 +1,113 @@
+module EZDyn
+  # Abstraction of Dyn REST API DNS Zones
+  class Zone
+    attr_reader :name, :type, :serial, :serial_style
+
+    # @private
+    def initialize(client:, name: nil, type: nil, serial: nil, serial_style: nil, raw: nil, uri: nil)
+      EZDyn.debug { "Zone.new( client: Client{}, name: #{name}, type: #{type}, serial: #{serial}, serial_style: #{serial_style}, raw: #{raw.nil? ? nil : raw.to_json}, uri: #{uri} )" }
+      @client = client
+      @name = name
+      @type = type
+      @serial = serial
+      @serial_style = serial_style
+      @in_sync = false
+
+      if not raw.nil?
+        self.sync_raw(raw)
+      end
+
+      if not uri.nil?
+        uri.gsub!(%r{^/?(REST/)?}, '')
+        if uri =~ %r{^Zone/([^/]+)/?$}
+          @name = $1
+        end
+      end
+    end
+
+    # Returns the zone type.
+    def type
+      self.sync! if @type.nil?
+      @type
+    end
+
+    # Returns the serial number of the zone.
+    def serial
+      self.sync! if @serial.nil?
+      @serial
+    end
+
+    # Returns the style of serial number in use by this zone.
+    def serial_style
+      self.sync! if @serial_style.nil?
+      @serial_style
+    end
+
+    # @private
+    def uri
+      "/Zone/#{self.name}"
+    end
+
+    # Indicates whether the object has been synced with the API.
+    def in_sync?
+      @in_sync
+    end
+
+    # Attempt to sync the object with the API.
+    #
+    # @raise [RuntimeError] if the object does not exist or could not be synced.
+    def sync!
+      EZDyn.debug { "Zone{#{self.name}}.sync!" }
+      return self if self.in_sync?
+
+      data = @client.fetch_uri_data(uri: self.uri)
+      if data.is_a? Hash
+        sync_raw(data)
+      else
+        raise "Failed to sync zone #{self.name}"
+      end
+
+      self
+    end
+
+    # @private
+    def sync_raw(raw)
+      EZDyn.debug { "Zone{#{self.name}}.sync_raw( #{raw.nil? ? nil : raw.to_json} )" }
+      @name = raw["zone"]
+      @type = raw["zone_type"]
+      @serial = raw["serial"]
+      @serial_style = raw["serial_style"]
+      @in_sync = true
+    end
+
+    # Returns the name of the zone for display purposes.
+    def to_s
+      self.name
+    end
+  end
+
+  class Client
+    # @private
+    def fetch_zones
+      EZDyn.debug { "Client.fetch_zones()" }
+      @zones = self.fetch_uri_data(uri: '/Zone/').
+        collect { |uri| Zone.new(client: self, uri: uri) }
+    end
+
+    # List all DNS zones known to this client.
+    #
+    # @return [Array<Zone>] An array of Zone objects.
+    def zones
+      EZDyn.debug { "Client.zones()" }
+      @zones ||= self.fetch_zones
+    end
+
+    # Match the given FQDN to a zone known to this client.
+    #
+    # @return [Zone] The appropriate Zone object, or nil if nothing matched.
+    def guess_zone(fqdn:)
+      EZDyn.debug { "Client.guess_zone( fqdn: #{fqdn} )" }
+      self.zones.find { |z| fqdn.downcase =~ /#{z.name.downcase}$/ }
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: ezdyn
+version: !ruby/object:Gem::Version
+  version: 0.2.2
+platform: ruby
+authors:
+- David Adams
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-09-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: Library and CLI tool for easy Dynect DNS updates
+email: dadams@instructure.com
+executables:
+- ezdyn
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- bin/ezdyn
+- ezdyn.gemspec
+- lib/ezdyn.rb
+- lib/ezdyn/changes.rb
+- lib/ezdyn/client.rb
+- lib/ezdyn/consts.rb
+- lib/ezdyn/crud.rb
+- lib/ezdyn/log.rb
+- lib/ezdyn/record.rb
+- lib/ezdyn/record_type.rb
+- lib/ezdyn/response.rb
+- lib/ezdyn/version.rb
+- lib/ezdyn/zone.rb
+homepage: https://github.com/instructure
+licenses:
+- Nonstandard
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: Simple library for Dyn Managed DNS
+test_files: []