ezdyn 0.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d24c4fe0dc33f7c3811c278361eca07dc3238312
+  data.tar.gz: 77d401779004efe034f9e67a248798f289fe5042
+SHA512:
+  metadata.gz: 605af431e632c95a448973f647fbc072cd8ef96765b47da25a089359f2a4bc96239f84f414945e503c561ef35ef2ca1f28e4e2eb4cc363482e7456c69b5cabd8
+  data.tar.gz: e08bc7239b87985c2a78dc77fd267c4c223886212fe5314f8009880b007d3853de83c93cf6242c0e1ee4abe9d1261e40e02a63c17f5767708b2920b564119a76

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# ezdyn changelog
+
+## Version 0.2.0 - 2015-09-19
+
+* ezdyn command line tool
+* several bug fixes
+
+
+## Version 0.1.1 - 2015-09-19
+
+* Added YARD docs
+* Added Rakefile with gem and doc commands
+* Renamed Type to RecordType for clarity
+
+
+## Version 0.1.0 - 2015-09-18
+
+* Refactored client code to a new class
+* Factored record type handling into its own class
+* Added stderr verbose logger
+* Keep track of pending changes globally, plus reporting
+* Commit and Rollback do not require zone specification
+
+
+## Version 0.0.0 - 2015-09-18
+
+* Session management: login/logout
+* Basic CRUD: create, update, upsert, delete, delete_all, records_for
+* Transactions: Commit, Rollback
+* Zone, Record, Response objects

data/README.md

@@ -0,0 +1,139 @@
+# ezdyn
+
+Gem library and command line tool for Dyn Managed DNS API access.
+
+See https://help.dyn.com/dns-api-knowledge-base/
+
+
+## Installation
+
+    $ rake gem:install
+
+
+## Command Line Usage
+
+Use the `ezdyn` tool installed with the gem to make one-off or batched DNS changes from the command line.
+
+See `ezdyn --help` for all options. Use command line flags or environment variables (see below) for authentication.
+
+Important options include:
+
+* `--file <filename>` provide a file of commands, one per line
+* `--apply`: apply changes when done (default is dry-run mode)
+* `--check`: check syntax only (does not connect to API or need credentials)
+
+If `--file` is not specified, commands are read from the command line arguments. Each ezdyn command must be enclosed in quotes to distiguish it from other commands.
+
+### Command syntax
+
+There are three possible commands:
+
+* `create <type> <fqdn> <value> [<ttl>]`
+* `upsert <type> <fqdn> <value> [<ttl>]`
+* `delete <type> <fqdn>`
+
+The `ttl` field is always optional. You may use `update` as well as `upsert`, but both commands will create a record if it does not exist, and update an existing record if it does exist.
+
+### Examples
+
+You can issue commands directly from the command line.
+
+To perform a dry-run of creating a new A record:
+
+    $ ezdyn "create A test.example.com 192.168.0.1"
+
+To check the syntax (requiring no API interaction) on creating two CNAME records:
+
+    $ ezdyn --check "create cname test1.example.com other1.example.com" \
+                    "create cname test2.example.com other2.example.com"
+
+To actually update/upsert an A record:
+
+    $ ezdyn "update A test3.example.com 10.0.0.10" --apply
+
+To process a list of commands from a file:
+
+    $ ezdyn --file dns-changes.txt
+
+Where `dns-changes.txt` may look like:
+
+    create A web1.example.com 10.1.100.1 600
+    create A web2.example.com 10.1.200.1 1200
+    create A web3.example.com 192.168.0.2 30
+    delete ALL oldweb.example.com
+
+
+### Notes
+
+* Dry runs do interact with the Dyn API. This is useful to check for the validity of your changes before making them.
+* ezdyn does not yet deal correctly with multiple records on a single node. Delete operations will delete multiple records on a node, but create and update operations should bail and complain about multiple records.
+* Exception handling is poor at the moment, so when things go wrong it might look ugly, but most dangerous situations should be prevented.
+* Only A and CNAME records are supported at present.
+
+
+## Library Usage
+
+    require 'ezdyn'
+
+    # create new client object using explicit vars
+    dyn = EZDyn::Client.new(customer_name: customer_name,
+                            username: username,
+                            password: password)
+
+    # (or create one using environment variables (see below)
+    dyn2 = EZDyn::Client.new
+
+    # create a new A record
+    # (login step is implicit in first access)
+    dyn.create(type: "A",
+               fqdn: "website.example.com",
+               value: "10.0.0.1")
+
+    # no wait, take that back
+    dyn.rollback
+
+    # delete any CNAME records for alias.example.com
+    dyn.delete_all(type: "cname", fqdn: "alias.example.com")
+
+    # update the A record for mail.example.com, or, if it
+    # does not exist, create it with the given value and ttl
+    dyn.update(type: :a,
+               fqdn: "mail.example.com",
+               value: "10.0.0.2",
+               ttl: 600)
+
+    # print all pending changes
+    puts "Pending changes:"
+    dyn.pending_changes.each do |pc|
+      puts "  #{pc}"
+    end
+
+    # commit all changes (with optional zone update message)
+    dyn.commit(message: "Just an example")
+
+    # close session (it will time out after 60 minutes)
+    dyn.logout
+
+
+## Environment Variables
+
+You may specify the `customer_name`, `username`, and `password` parameters via environment variables:
+
+* `DYN_CUSTOMER_NAME`
+* `DYN_USERNAME`
+* `DYN_PASSWORD`
+
+You may also enable verbose debug logging by setting `EZDYN_DEBUG` to any value.
+
+
+## API Documentation
+
+You can generate the YARD docs for the library by running `rake docs`. Then open `doc/index.html` in your web browser.
+
+
+## TODO
+
+* Implement actual Exception classes
+* Fewer exceptions should be raised overall
+* Support additional record types (esp MX, AAAA)
+* Mock API endpoint for testing, also actual tests

data/bin/ezdyn

@@ -0,0 +1,226 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'io/console'
+
+def die(msg)
+  errsay "ERROR: #{msg}"
+  exit 1
+end
+
+def say(msg = nil)
+  puts msg unless $options[:quiet]
+end
+
+def errsay(msg = nil)
+  STDERR.puts msg unless $options[:quiet]
+end
+
+$options = {
+  dryrun: true,
+  ignore_syntax_errors: false,
+  check: false,
+}
+client_args = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: #{File.basename($0)} [options]"
+
+  opts.on_head(
+    '-f', '--file FILENAME',
+    'File path to a batch of ezdyn commands'
+  ) do |arg|
+
+    die("Input file '#{arg}' could not be found.") if not File.readable?(arg)
+
+    $options[:batchfile] = arg
+    $options[:batchmode] = true
+  end
+
+  opts.on_head('--apply', 'Actually apply changes, do not just perform a dry run.') do
+    $options[:dryrun] = false
+  end
+
+  opts.on_head('--check', 'Check all command syntax, but do not interact with the API.') do
+    $options[:check] = true
+  end
+
+  opts.on('-C', '--customer-name NAME', 'Dyn API Customer Name') do |arg|
+    client_args[:customer_name] = arg
+  end
+
+  opts.on('-u', '--user USERNAME', 'Dyn API Username') do |arg|
+    client_args[:username] = arg
+  end
+
+  opts.on('-p', '--password PASSWORD', 'Dyn API Password') do |arg|
+    client_args[:password] = arg
+  end
+
+  opts.on('--ignore-syntax-errors', 'Do not fail if a command has a syntax error. Just skip.') do
+    $options[:ignore_syntax_errors] = true
+  end
+
+  opts.on('--force', 'Do not ask for confirmation to commit changes.') do
+    $options[:force] = true
+  end
+
+  opts.on('-q', '--quiet', 'Quiet mode (implies --force: apply mode will not ask for confirmation!)') do
+    $options[:quiet] = true
+    $options[:force] = true
+  end
+
+  opts.on_tail('--debug', 'Enable debug logging') do
+    $options[:debug] = true
+  end
+
+  opts.on_tail('-v','--version', 'Display version') do
+    require 'ezdyn/version'
+    puts "ezdyn #{EZDyn::VERSION}"
+    exit
+  end
+end.parse!
+
+if $options[:debug]
+  ENV['EZDYN_DEBUG'] = "1"
+end
+
+if $options[:batchmode]
+  if ARGV.count > 0
+    die "Cannot handle commands both on the command line and in a file"
+  end
+else
+  if ARGV.count < 1
+    die "Nothing to do"
+  end
+end
+
+commands =
+  if $options[:batchmode]
+    File.read($options[:batchfile]).split("\n")
+  else
+    ARGV.dup
+  end
+
+# in check mode, we won't interact with the API
+if not $options[:check]
+  require 'ezdyn'
+  $dyn = EZDyn::Client.new(**client_args)
+end
+
+$check_warnings = 0
+
+def handle_syntax_error(msg)
+  if $options[:check]
+    $check_warnings += 1
+
+  elsif not $options[:ignore_syntax_errors]
+    die msg
+  end
+  errsay "WARNING: #{msg}"
+end
+
+
+commands.each do |line|
+  tokens = line.chomp.strip.split(/\s+/)
+  next if tokens.empty?
+
+  cmd = tokens.shift.downcase
+
+  case cmd
+  when 'create'
+    type, fqdn, value, ttl = tokens.shift(4)
+    if type.nil? or type.empty? or
+       fqdn.nil? or fqdn.empty? or
+       value.nil? or value.empty? or
+       tokens.count > 0
+      handle_syntax_error("'create' command expects 3-4 arguments")
+      next
+    end
+    next if $options[:check]
+
+    say "DynAPI: Creating #{fqdn} #{ttl||"(#{EZDyn::Record::DefaultTTL})"} #{type.upcase} #{value}"
+    $dyn.create(type: type, fqdn: fqdn, value: value, ttl: ttl)
+
+  when 'update','upsert'
+    type, fqdn, value, ttl = tokens.shift(4)
+    if type.nil? or type.empty? or
+       fqdn.nil? or fqdn.empty? or
+       value.nil? or value.empty? or
+       tokens.count > 0
+      handle_syntax_error("'#{cmd}' command expects 3-4 arguments")
+      next
+    end
+    next if $options[:check]
+
+    say "DynAPI: Upserting #{fqdn} #{ttl||"(#{EZDyn::Record::DefaultTTL})"} #{type.upcase} #{value}"
+    $dyn.update(type: type, fqdn: fqdn, value: value, ttl: ttl)
+
+  when 'delete'
+    type, fqdn = tokens.shift(2)
+    if type.nil? or type.empty? or
+       fqdn.nil? or fqdn.empty? or
+       tokens.count > 0
+      handle_syntax_error("'delete' command expects exactly two arguments")
+      next
+    end
+    next if $options[:check]
+
+    if type.downcase == "all" or type.downcase == "any"
+      say "DynAPI: Deleting ALL records for '#{fqdn}'"
+      $dyn.records_for(fqdn: fqdn).each(&:delete!)
+    else
+      say "DynAPI: Deleting #{type.upcase} records for '#{fqdn}'"
+      $dyn.records_for(type: type, fqdn: fqdn).each(&:delete!)
+    end
+
+  else
+    handle_syntax_error("Invalid or unknown command '#{cmd}'")
+    next
+  end
+end
+
+if $options[:check]
+  if $check_warnings > 0
+    die "Found #{$check_warnings} syntax errors"
+  else
+    say "Syntax OK"
+  end
+  exit
+end
+
+say
+if $dyn.pending_changes.nil? or $dyn.pending_changes.count < 1
+  say "NOTICE: No changes were made."
+  exit
+end
+
+say "Pending changes:"
+$dyn.pending_changes.each do |pc|
+  say "  #{pc}"
+end
+say
+
+
+if $options[:dryrun]
+  say "DynAPI: This is a dry run. Rolling back changes."
+  $dyn.rollback
+
+else
+  if not $options[:force]
+    print "Would you like to apply these changes? (y/N) "
+    if STDIN.getch != 'y'
+      say
+      say "DynAPI: Changes rejected. Rolling back."
+      $dyn.rollback
+    else
+      say
+      say "DynAPI: Apply mode in effect and changes confirmed. Committing!"
+      $dyn.commit
+    end
+  else
+    say "DynAPI: Apply and force modes in effect. Committing!"
+    $dyn.commit
+  end
+end
+
+$dyn.logout

data/ezdyn.gemspec

@@ -0,0 +1,24 @@
+require_relative 'lib/ezdyn/version'
+
+Gem::Specification.new do |s|
+  s.name = "ezdyn"
+  s.version = EZDyn::VERSION
+  s.author = "David Adams"
+  s.email = "dadams@instructure.com"
+  s.date = Time.now.strftime("%Y-%m-%d")
+  s.license = "Nonstandard"
+  s.homepage = "https://github.com/instructure"
+
+  s.summary = "Simple library for Dyn Managed DNS"
+  s.description = "Library and CLI tool for easy Dynect DNS updates"
+
+  s.require_paths = ["lib"]
+  s.files =
+    Dir["lib/**/*.rb"] +
+    Dir["*.md"] +
+    ["ezdyn.gemspec"]
+  s.bindir = "bin"
+  s.executables = ["ezdyn"]
+
+  s.add_development_dependency 'yard', '~>0.8'
+end

data/lib/ezdyn.rb

@@ -0,0 +1,11 @@
+require 'json'
+require 'ezdyn/version'
+require 'ezdyn/consts'
+require 'ezdyn/log'
+require 'ezdyn/client'
+require 'ezdyn/zone'
+require 'ezdyn/record_type'
+require 'ezdyn/response'
+require 'ezdyn/record'
+require 'ezdyn/crud'
+require 'ezdyn/changes'

data/lib/ezdyn/changes.rb

@@ -0,0 +1,111 @@
+module EZDyn
+  class Client
+    # @private
+    def add_pending_change(chg)
+      @pending_changes ||= []
+      @pending_changes << chg
+    end
+
+    # @private
+    def pending_change_zones
+      @pending_changes.collect(&:zone).uniq
+    end
+
+    # List currently pending changes (optionally per zone).
+    #
+    # @param zone [String] (Optional) If specified, only return pending changes
+    #   for the named zone.
+    # @return [Array] Array of [Change] objects awaiting commit.
+    def pending_changes(zone: nil)
+      if zone.nil?
+        @pending_changes
+      else
+        zone = Zone.new(client: self, name: zone)
+        @pending_changes.select do |pc|
+          pc.zone.name == zone.name
+        end
+      end
+    end
+
+    # @private
+    def clear_pending_changes(zone: nil)
+      if zone.nil?
+        @pending_changes = []
+      else
+        @pending_changes.delete_if do |pc|
+          pc.zone.name == zone.to_s
+        end
+      end
+    end
+  end
+
+  # Generic base class for any pending change.
+  class Change
+    # Returns the zone this change is part of.
+    #
+    # @return [Zone] The zone this change is part of.
+    def zone
+      @record.zone
+    end
+  end
+
+  # A pending record creation.
+  class CreateChange < Change
+    # @private
+    def initialize(record:)
+      @record = record
+    end
+
+    # Returns a string representation of the change.
+    #
+    # @return [String] A string representation of this change.
+    def to_s
+      "CREATE #{@record.fqdn}.   #{@record.ttl} #{@record.type}   #{@record.value}"
+    end
+  end
+
+  # A pending record update.
+  class UpdateChange < Change
+    # @private
+    def initialize(record:, new_record:)
+      @record = record.sync!
+      @new_record = new_record
+    end
+
+    # Returns a string representation of the change.
+    #
+    # @return [String] A string representation of this change.
+    def to_s
+      ttl_string =
+        if @record.ttl == @new_record.ttl
+          @record.ttl
+        else
+          "(( #{@record.ttl} -> #{@new_record.ttl} ))"
+        end
+
+      value_string =
+        if @record.value == @new_record.value
+          @record.value
+        else
+          "(( #{@record.value} -> #{@new_record.value} ))"
+        end
+
+      "UPDATE #{@record.fqdn}.   #{ttl_string} #{@record.type}   #{value_string}"
+    end
+  end
+
+  # A pending record deletion.
+  class DeleteChange < Change
+    # @private
+    def initialize(record:)
+      @record = record.sync!
+    end
+
+    # Returns a string representation of the change.
+    #
+    # @return [String] A string representation of this change.
+    def to_s
+      "DELETE #{@record.fqdn}.   #{@record.ttl} #{@record.type}   #{@record.value}"
+    end
+  end
+end