pdns_api 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 657948fecf6bc98b2564c4ca8a662fe535effc76
-  data.tar.gz: 5f3d133e97e22df2ff682500d079bc0cbeed06f8
+SHA256:
+  metadata.gz: 983b46d03f4c320e0ede5af20db05e9e0823e49f53d38116edceaa8070ee7ac9
+  data.tar.gz: 535c5967564d63f66820208181e5ab93aa9c80e636447e0d6a9a31783619f9f0
 SHA512:
-  metadata.gz: b1f5e2794d3d8da64596717ac8beb59328e90eb6774e91561aff3183eb6ed9e5bfb74549056c6247599279b56482046dad74e195692d4d2d11b13a20131978bc
-  data.tar.gz: b4f3d1ac66fd8abe82170710da88927f86d4283018384804188eb715472203347306c227d8d2536a17df995af6286587e7dfbcd2545eb00551c85a37e72ec077
+  metadata.gz: 86e358875b062b3a937357e87e55cd410d4edde9cdd002e1dedc8eae2d4e5eebf20eb736d3d9e736aa6fc1983c29175dbab2f00f7b19573ca2a7e31f40b4145f
+  data.tar.gz: 036fe570d1f54074abbb29ed40ead3a7afb740e652b31ce5d0cff2354da5c4caedb988fceb4f8304ae9fa7079a764ca3ecbb8644a345a5b3080619ee124e38fd

data/lib/pdns_api/api.rb

@@ -18,23 +18,25 @@
 require 'pdns_api/http'
 
 ##
-#
+# Module for interaction with the PowerDNS HTTP API.
 module PDNS
   ##
   # The superclass for all PDNS objects.
   class API
     ##
-    # The url of the resource object.
+    # @return the url of the resource object.
     attr_reader :url
 
     ##
-    # The class of the resource object.
+    # @return the class of the resource object.
     attr_reader :class
 
     ##
     # Changes this object's information on the server.
     #
-    # +rrsets+ is used as changeset for the update.
+    # @param rrsets [Array] is used as changeset for the change.
+    # @return [Hash] result of the change.
+    #
     def change(rrsets)
       @http.put(@url, rrsets)
     end
@@ -45,20 +47,27 @@ module PDNS
     # If +info+ is set this method updates the current information.
     # The current information is used to create the object.
     #
-    # Example:
+    # @param info [Hash, nil] Information to set when creating the object.
+    # @return [Hash] result of the creation.
+    #
+    # @example
     #  zone.create(
     #    name: zone.id,
     #    kind: 'Native',
     #    dnssec: true,
     #    nameservers: %w( ns0.example.com. ns1.example.com. )
     #  )
+    #
     def create(info = nil)
       info(info)
       @http.post("#{@parent.url}/#{@class}", @info)
     end
 
     ##
-    # Deletes this object
+    # Deletes this object.
+    #
+    # @return [Hash] result of the deletion.
+    #
     def delete
       @http.delete @url
     end
@@ -66,6 +75,9 @@ module PDNS
     ##
     # Gets the information of this object from the API and use it
     # to update the object's information.
+    #
+    # @return [Hash] the object's information from the API.
+    #
     def get
       @info = @http.get @url
     end
@@ -74,7 +86,9 @@ module PDNS
     # Gets and sets the object information.
     # This does not cause an API request.
     #
-    # If +info+ is set this method updates the current information.
+    # @param info [Hash, nil] Information to change.
+    # @return [Hash] this object's information.
+    #
     def info(info = nil)
       return @info if info.nil?
 
@@ -84,6 +98,10 @@ module PDNS
     ##
     # Ensures the object is an array.
     # If it is not, an array containing the item is returned.
+    #
+    # @param item anything that might or might not be an +Array+.
+    # @return [Array] +item+ as an array.
+    #
     def ensure_array(item)
       return item if item.is_a? Array
       [item]

data/lib/pdns_api/client.rb

@@ -20,13 +20,13 @@ require 'pdns_api/api'
 require 'pdns_api/server'
 
 ##
-#
+# Module for interaction with the PowerDNS HTTP API.
 module PDNS
   ##
   # Class for interaction with the top level API.
   class Client < API
     ##
-    # The PowerDNS API version in use.
+    # @return [Integer] the PowerDNS API version in use.
     attr_reader :version
 
     ##
@@ -34,9 +34,11 @@ module PDNS
     undef_method :change, :create, :delete
 
     ##
-    # Creates a client object.
-    # +args+ is used to create an HTTP object,
-    # which is used by all created objects.
+    # Creates a +Client+ object.
+    #
+    # @param args [Hash] Arguments used to create an +HTTP+ object,
+    #   which is used by all created objects.
+    #
     def initialize(args)
       @class   = :client
       @http    = PDNS::HTTP.new(args)
@@ -49,10 +51,13 @@ module PDNS
     ##
     # Returns existing or creates a +Server+ object.
     #
-    # If +id+ is not set the current servers are returned in a hash
-    # containing +Server+ objects.
+    # @param id [String, nil] ID of a Server.
+    #
+    # @return [Hash, Server] Hash of +Server+ objects or a single +Server+ object.
+    #   - If +id+ is not set the current servers are returned in a hash
+    #     containing +Server+ objects.
+    #   - If +id+ is set a +Server+ object with the provided ID is returned.
     #
-    # If +id+ is set a +Server+ object with the provided ID is returned.
     def servers(id = nil)
       return Server.new(@http, self, id) unless id.nil?
 

data/lib/pdns_api/config.rb

@@ -16,13 +16,13 @@
 #
 
 ##
-#
+# Module for interaction with the PowerDNS HTTP API.
 module PDNS
   ##
   # Configuration option for a DNS Server.
   class Config < API
     ##
-    # The name of the configuration option.
+    # @return [String] the name of the configuration option.
     attr_accessor :name
 
     ##
@@ -32,10 +32,11 @@ module PDNS
     ##
     # Creates a configuration option object.
     #
-    # - +http+:   An HTTP object for interaction with the PowerDNS server.
-    # - +parent+: This object's parent.
-    # - +name+:   Name of the configuration option.
-    # - +value+:  Optional value of the configuration option.
+    # @param http   [HTTP]   An HTTP object for interaction with the PowerDNS server.
+    # @param parent [API]    This object's parent.
+    # @param name   [String] Name of the configuration option.
+    # @param value  [String] Optional value of the configuration option.
+    #
     def initialize(http, parent, name, value = nil)
       @class  = :config
       @http   = http
@@ -49,17 +50,22 @@ module PDNS
     ##
     # Gets or sets the +value+ attribute.
     #
-    # If +value+ is not set the current +value+ is returned.
-    # If +value+ is set the object's +value+ is updated and +info+ is set and returned
+    # @param value [String, nil] the value of the object.
+    # @return [String] the value of the object.
+    #   If +value+ is set the object's +value+ is updated.
+    #
     def value(value = nil)
       return @value if value.nil?
-      @value = value
       @info  = { type: 'ConfigSetting', name: @name, value: value }
+      @value = value
     end
 
     ##
     # Gets the current information.
     # This also updates +value+.
+    #
+    # @return [Hash] the object's information from the API.
+    #
     def get
       res = @http.get @url
       value(res[:value]) if res.key? :value
@@ -67,12 +73,16 @@ module PDNS
     end
 
     ##
-    # Updates the object on the server.
+    # Changes this object's information on the server.
+    #
+    # @param value [String, nil] Value to change the object to.
+    #   - If +value+ is set, the current +value+ is used.
+    #   - If +value+ is not set, +value+ is updated and then used.
     #
-    # If +value+ is set, the current +value+ is used.
-    # If +value+ is not set, +value+ is updated and then used.
+    # @return [Hash] result of the change.
     #
-    # Example:
+    # @example
+    #   config = server.config('version')
     #   config.change('PowerDNS v3.14159265')
     #
     def change(value = nil)

data/lib/pdns_api/cryptokey.rb

@@ -16,22 +16,23 @@
 #
 
 ##
-#
+# Module for interaction with the PowerDNS HTTP API.
 module PDNS
   ##
   # Cryptokey for a zone.
   class CryptoKey < API
     ##
-    # The ID of the cryptokey.
+    # @return [Integer] the ID of the cryptokey.
     attr_reader :id
 
     ##
     # Creates a cryptokey object.
     #
-    # - +http+:   An HTTP object for interaction with the PowerDNS server.
-    # - +parent+: This object's parent.
-    # - +id+:     Identifier of the cryptokey.
-    # - +info+:   Optional information about the cryptokey.
+    # @param http   [HTTP]    An HTTP object for interaction with the PowerDNS server.
+    # @param parent [API]     This object's parent.
+    # @param id     [Integer] Identifier of the cryptokey.
+    # @param info   [Hash]    Optional information about the cryptokey.
+    #
     def initialize(http, parent, id, info = {})
       @class  = :cryptokeys
       @http   = http

data/lib/pdns_api/http.rb

@@ -16,51 +16,75 @@
 #
 
 ##
-#
+# Module for interaction with the PowerDNS HTTP API.
 module PDNS
   ##
   # Class for connecting to the PowerDNS API.
   class HTTP
     ##
-    # The headers used for requests.
+    # @return [Hash] the headers used for requests.
     attr_accessor :headers
 
     ##
-    # The PowerDNS API version in use.
-    attr_reader   :version
+    # @return [Integer] the PowerDNS API version in use.
+    attr_reader :version
 
     ##
     # Creates a PDNS connection.
     #
-    # +args+ is a a hash which should include:
-    # - +:host+: hostname or IP address of the PowerDNS server.
-    # - +:key+:  API key for the PowerDNS server.
-    #
-    # It may include:
-    # - +:port+:    Port the server listens on. Defaults to +8081+.
-    # - +:version+: Version of the API to use.  Defaults to +1+.
+    # @param args [Hash] should include:
+    #   - +:host+: hostname or IP address of the PowerDNS server.
+    #   - +:key+:  API key for the PowerDNS server.
+    #   It may include:
+    #   - +:port+:    Port the server listens on. Defaults to +8081+.
+    #   - +:version+: Version of the API to use.  Defaults to +1+.
+    #   - +:scheme+:  Scheme - HTTP or HTTPS.  Defaults to +http+.
     #   The version of the API depends on the version of PowerDNS.
     #
-    # TODO: retrieve endpoint from +/api+ if version is not provided.
     def initialize(args)
       @host    = args[:host]
-      @key     = args[:key]
+      @headers = { 'X-API-Key' => args[:key] }
       @port    = args.key?(:port)    ? args[:port]    : 8081
-      @version = args.key?(:version) ? args[:version] : 1
-      @headers = { 'X-API-Key' => @key }
+      @version = args.key?(:version) ? args[:version] : api_version
+      @scheme  = args.key?(:scheme)  ? args[:scheme]  : 'http'
+    end
+
+    ##
+    # Get the version of the API.
+    #
+    # @return [Integer] version of the PowerDNS API.
+    #
+    def api_version
+      # Do a request for the API endpoints
+      net = Net::HTTP::Get.new('/api', @headers)
+      res = http(net)
+
+      # APIv0 does not play nice.
+      return 0 unless res.is_a? Array
+
+      # Return the highest API version.
+      res.map { |a| a[:version] }.max.to_i
     end
 
     ##
     # Returns the correct URI for a request.
     # This depends on the API version.
+    #
+    # @param request [String] Requested URI.
+    # @return [String] Correct URI for the API version.
+    #
     def uri(request = '')
       base = ''
-      base = "/api/v#{@version}" unless @version == 0 || request[0..3] == '/api'
+      base = "/api/v#{@version}" unless @version.zero? || request[0..3] == '/api'
       base + request
     end
 
     ##
     # Decodes the response from the server.
+    #
+    # @param response [Net::HTTPResponse] response to decode.
+    # @return [Hash] decoded response.
+    #
     def response_decode(response)
       return {} if response.body.nil?
 
@@ -74,22 +98,24 @@ module PDNS
 
     ##
     # Does an HTTP request and returns the response.
-    # Parameters are:
-    # - +net+:  Net::HTTP method object to use in request.
-    # - +body+: Optional body of the request.
-    # Returns the decoded response.
+    #
+    # @param net  [Net::HTTP] object to use in request.
+    # @param body [Hash]      body of the request.
+    #
+    # @return [Hash] decoded response from server.
+    #
     def http(net, body = nil)
       # Debug output
       puts "#{net.method}: #{net.path}\nBody: #{body.to_json}" if ENV['DEBUG']
 
       # Start an HTTP connection
       begin
-        response = Net::HTTP.start(@host, @port) do |http|
+        response = Net::HTTP.start(@host, @port, use_ssl: @scheme == 'https') do |http|
           # Do the request
           http.request(net, body.to_json)
         end
-      rescue StandardError, Timeout::Error => e
-        abort("Error: #{e}")
+      rescue StandardError => e
+        return { error: e.to_s }
       end
 
       response_decode(response)
@@ -97,7 +123,10 @@ module PDNS
 
     ##
     # Does an HTTP +DELETE+ request to +uri+.
-    # Returns the decoded response.
+    #
+    # @param uri [String] URI for request.
+    # @return [Hash] the decoded response.
+    #
     def delete(uri)
       uri = uri(uri)
       net = Net::HTTP::Delete.new(uri, @headers)
@@ -106,7 +135,10 @@ module PDNS
 
     ##
     # Does an HTTP +GET+ request to +uri+.
-    # Returns the decoded response.
+    #
+    # @param uri [String] URI for request.
+    # @return [Hash] the decoded response.
+    #
     def get(uri)
       uri = uri(uri)
       net = Net::HTTP::Get.new(uri, @headers)
@@ -115,7 +147,11 @@ module PDNS
 
     ##
     # Does an HTTP +PATCH+ request to +uri+.
-    # Returns the decoded response.
+    #
+    # @param uri [String] URI for request.
+    # @param body [Hash]  Body to include in request.
+    # @return [Hash] the decoded response.
+    #
     def patch(uri, body = nil)
       uri = uri(uri)
       net = Net::HTTP::Patch.new(uri, @headers)
@@ -124,7 +160,11 @@ module PDNS
 
     ##
     # Does an HTTP +POST+ request to +uri+.
-    # Returns the decoded response.
+    #
+    # @param uri [String] URI for request.
+    # @param body [Hash]  Body to include in request.
+    # @return [Hash] the decoded response.
+    #
     def post(uri, body = nil)
       uri = uri(uri)
       net = Net::HTTP::Post.new(uri, @headers)
@@ -133,7 +173,11 @@ module PDNS
 
     ##
     # Does an HTTP +PUT+ request to +uri+.
-    # Returns the decoded response.
+    #
+    # @param uri [String] URI for request.
+    # @param body [Hash]  Body to include in request.
+    # @return [Hash] the decoded response.
+    #
     def put(uri, body = nil)
       uri = uri(uri)
       net = Net::HTTP::Put.new(uri, @headers)

data/lib/pdns_api/metadata.rb

@@ -16,22 +16,23 @@
 #
 
 ##
-#
+# Module for interaction with the PowerDNS HTTP API.
 module PDNS
   ##
   # Metadata for a zone.
   class Metadata < API
     ##
-    # The kind of metadata.
+    # @return [name] the kind of metadata.
     attr_accessor :kind
 
     ##
     # Creates a configuration option object.
     #
-    # - +http+:   An HTTP object for interaction with the PowerDNS server.
-    # - +parent+: This object's parent.
-    # - +kind+:   Name of the metadata.
-    # - +value+:  Optional value of the metadata.
+    # @param http   [HTTP]   An HTTP object for interaction with the PowerDNS server.
+    # @param parent [API]    This object's parent.
+    # @param kind   [String] Kind of the metadata.
+    # @param value  [String] Optional value of the metadata.
+    #
     def initialize(http, parent, kind, value = [])
       @class  = :metadata
       @http   = http
@@ -45,8 +46,10 @@ module PDNS
     ##
     # Gets or sets the +value+ attribute.
     #
-    # If +value+ is not set the current +value+ is returned.
-    # If +value+ is set the object's +value+ is updated and +info+ is set and returned.
+    # @param value [String, nil] the value of the object.
+    # @return [String] the value of the object.
+    #   If +value+ is set the object's +value+ is updated.
+    #
     def value(value = nil)
       return @info[:metadata] if value.nil?
 
@@ -54,13 +57,16 @@ module PDNS
       value = ensure_array(value)
 
       # Set value and info
-      @value = value
       @info  = { type: 'Metadata', kind: @kind, metadata: value }
+      @value = value
     end
 
     ##
     # Gets the current information.
     # This also updates +value+.
+    #
+    # @return [Hash] the object's information from the API.
+    #
     def get
       res = @http.get @url
       value(res[:value]) if res.key? :value
@@ -68,10 +74,18 @@ module PDNS
     end
 
     ##
-    # Updates the object on the server.
+    # Changes this object's information on the server.
+    #
+    # @param value [String, nil] Value to change the object to.
+    #   - If +value+ is set, the current +value+ is used.
+    #   - If +value+ is not set, +value+ is updated and then used.
+    #
+    # @return [Hash] result of the change.
+    #
+    # @example
+    #   metadata = zone.metadata('ALLOW-AXFR-FROM')
+    #   metadata.change('AUTO-NS')
     #
-    # If +value+ is set, the current +value+ is used.
-    # If +value+ is not set, +value+ is updated and then used.
     def change(value = nil)
       value(value)
       @http.put(@url, @info)

data/lib/pdns_api/override.rb

@@ -16,22 +16,23 @@
 #
 
 ##
-#
+# Module for interaction with the PowerDNS HTTP API.
 module PDNS
   ##
   # Override for a server.
   class Override < API
     ##
-    # The ID of the override.
+    # @return [Integer] the ID of the override.
     attr_reader :id
 
     ##
     # Creates a configuration option object.
     #
-    # - +http+:   An HTTP object for interaction with the PowerDNS server.
-    # - +parent+: This object's parent.
-    # - +id+:     ID of the override.
-    # - +info+:   Optional information of the override.
+    # @param http   [HTTP]    An HTTP object for interaction with the PowerDNS server.
+    # @param parent [API]     This object's parent.
+    # @param id     [Integer] ID of the override.
+    # @param info   [Hash]    Optional information of the override.
+    #
     def initialize(http, parent, id, info = {})
       @class  = :overrides
       @http   = http

data/lib/pdns_api/server.rb

@@ -20,22 +20,23 @@ require 'pdns_api/override'
 require 'pdns_api/zone'
 
 ##
-#
+# Module for interaction with the PowerDNS HTTP API.
 module PDNS
   ##
   # Server object for accessing data for a particular server.
   class Server < API
     ##
-    # The ID of the server.
+    # @return [String] the ID of the server.
     attr_reader :id
 
     ##
     # Creates a Server object.
     #
-    # - +http+:   An HTTP object for interaction with the PowerDNS server.
-    # - +parent+: This object's parent.
-    # - +id+:     ID of the server.
-    # - +info+:   Optional information of the server.
+    # @param http   [HTTP]   An HTTP object for interaction with the PowerDNS server.
+    # @param parent [API]    This object's parent.
+    # @param id     [String] ID of the server.
+    # @param info   [Hash]   Optional information of the server.
+    #
     def initialize(http, parent, id, info = {})
       @class  = :servers
       @http   = http
@@ -46,13 +47,21 @@ module PDNS
     end
 
     ##
-    # Flushes cache for +domain+.
-    def cache(domain)
-      # TODO: #{url}/cache/flush?domain=:domain: PUT
+    # Flushes cache for a domain.
+    #
+    # @param domain [String] name of the domain.
+    # @return [Hash] result of the action.
+    #
+    def cache_flush(domain)
+      @http.put("#{@url}/cache/flush?domain=#{domain}")
     end
 
     ##
     # Searches through the server's log with +search_term+.
+    #
+    # @param search_term [String] terms to search for.
+    # @return [Hash] result of the search.
+    #
     def search_log(search_term)
       # TODO: /servers/:server_id/search-log?q=:search_term: GET
     end
@@ -65,8 +74,24 @@ module PDNS
 
     ##
     # Manipulates the query tracing log.
+    #
+    # @param domain_regex [String, nil]
+    #   Regular expression to match for domain tracing.
+    #   Set to nil to turn off tracking.
+    #
+    # @return [Hash] Regular expression and matching log lines.
+    #
+    def trace=(domain_regex)
+      @http.put("#{@url}/trace", domains: domain_regex)
+    end
+
+    ##
+    # Retrieves the query tracing log.
+    #
+    # @return [Hash] Regular expression and matching log lines.
+    #
     def trace
-      # TODO: /servers/:server_id/trace: GET, PUT
+      @http.get("#{@url}/trace")
     end
 
     ##
@@ -78,10 +103,14 @@ module PDNS
     ##
     # Returns existing configuration or creates a +Config+ object.
     #
-    # If +name+ is not set the current configuration is returned in a hash.
+    # @param name [String, nil]  Name of the configuration option.
+    # @param value [String, nil] Value op the configuration option.
+    #
+    # @return [Hash, Config] Hash containing +Config+ objects or a single +Config+ object.
+    #   - If +name+ is not set the current configuration is returned in a hash.
+    #   - If +name+ is set a +Config+ object is returned using the provided +name+.
+    #   - If +value+ is set as well, a complete config object is returned.
     #
-    # If +name+ is set a +Config+ object is returned using the provided +name+.
-    # If +value+ is set as well, a complete config object is returned.
     def config(name = nil, value = nil)
       return Config.new(@http, self, name, value) unless name.nil? || value.nil?
       return Config.new(@http, self, name) unless name.nil?
@@ -94,10 +123,13 @@ module PDNS
     ##
     # Returns existing or creates an +Override+ object.
     #
-    # If +id+ is not set the current servers are returned in a hash
-    # containing +Override+ objects.
+    # @param id [Integer, nil] ID of the override.
+    #
+    # @return [Hash, Override] Hash containing +Override+ objects or a single +Override+ object.
+    #   - If +id+ is not set the current servers are returned in a hash
+    #     containing +Override+ objects.
+    #   - If +id+ is set an +Override+ object with the provided ID is returned.
     #
-    # If +id+ is set an +Override+ object with the provided ID is returned.
     def overrides(id = nil)
       return Override.new(@http, self, id) unless id.nil?
 
@@ -108,10 +140,13 @@ module PDNS
     ##
     # Returns existing or creates a +Zone+ object.
     #
-    # If +id+ is not set the current servers are returned in a hash
-    # containing +Zone+ objects.
+    # @param id [String, nil] ID of the override.
+    #
+    # @return [Hash, Zone] Hash containing +Zone+ objects or a single +Zone+ object.
+    #   - If +id+ is not set the current servers are returned in a hash
+    #     containing +Zone+ objects.
+    #   - If +id+ is set a +Server+ object with the provided ID is returned.
     #
-    # If +id+ is set a +Server+ object with the provided ID is returned.
     def zones(id = nil)
       return Zone.new(@http, self, id) unless id.nil?
 

data/lib/pdns_api/version.rb

@@ -16,9 +16,9 @@
 #
 
 ##
-#
+# Module for interaction with the PowerDNS HTTP API.
 module PDNS
   ##
   # The version of +pdns_api+.
-  VERSION = '0.1.2'.freeze
+  VERSION = '0.1.3'.freeze
 end

data/lib/pdns_api/zone.rb

@@ -19,22 +19,23 @@ require 'pdns_api/metadata'
 require 'pdns_api/cryptokey'
 
 ##
-#
+# Module for interaction with the PowerDNS HTTP API.
 module PDNS
   ##
   # Zone on a server.
   class Zone < API
     ##
-    # The ID of the zone.
+    # @return [String] the ID of the zone.
     attr_reader :id
 
     ##
     # Creates a Zone object.
     #
-    # - +http+:   An HTTP object for interaction with the PowerDNS server.
-    # - +parent+: This object's parent.
-    # - +id+:     ID of the zone.
-    # - +info+:   Optional information of the zone.
+    # @param http   [HTTP]   An HTTP object for interaction with the PowerDNS server.
+    # @param parent [API]    This object's parent.
+    # @param id     [String] ID of the zone.
+    # @param info   [Hash]   Optional information of the zone.
+    #
     def initialize(http, parent, id, info = {})
       @class  = :zones
       @http   = http
@@ -48,12 +49,17 @@ module PDNS
     # Modifies information (records) of a zone.
     # Also formats records to match the API requirements.
     #
-    # Example:
+    # @param rrsets [Array] Changeset to send to the PowerDNS API.
+    #
+    # @return [Hash] result of the changeset.
+    #
+    # @example
     #  zone.modify([
     #     changetype: 'DELETE',
     #     name: 'www.example.com.',
     #     type: 'A'
     #  ])
+    #
     def modify(rrsets)
       rrsets.map! do |rrset|
         rrset = format_records(rrset) if rrset.key?(:records)
@@ -66,7 +72,7 @@ module PDNS
     ##
     # Notifies slaves for a zone.
     # Only works for domains for which the server is a master.
-    # Returns the result of the notification.
+    # @return [Hash] the result of the notification.
     def notify
       @http.put "#{@url}/notify"
     end
@@ -74,14 +80,14 @@ module PDNS
     ##
     # Retrieves the data for a zone.
     # Only works for domains for which the server is a slave.
-    # Returns the result of the retrieval.
+    # @return [Hash] the result of the retrieval.
     def axfr_retrieve
       @http.put "#{@url}/axfr-retrieve"
     end
 
     ##
     # Exports the zone as a bind zone file.
-    # Returns a hash containing the zone in +:result+.
+    # @return [Hash] containing the Bind formatted zone in +:result+.
     def export
       data = @http.get "#{@url}/export"
       data.delete(:error) if data[:error] == 'Non-JSON response'
@@ -90,7 +96,7 @@ module PDNS
 
     ##
     # Checks the zone for errors.
-    # Returns the result of the check.
+    # @return [Hash] the result of the check.
     def check
       @http.get "#{@url}/check"
     end
@@ -105,7 +111,11 @@ module PDNS
     # - An +Array+ containing record values.
     # - An +Array+ containing hashes as specified in the PowerDNS API.
     #
-    # Example:
+    # @param rrsets [Array<Object>] Array of Hashes containing records to replace.
+    #
+    # @return [Hash] Hash containing result of the operation.
+    #
+    # @example
     #   zone.add({
     #     name: 'www0.example.com.',
     #     type: 'A',
@@ -146,14 +156,16 @@ module PDNS
     ##
     # Updates (replaces) records for a name/type combination in the zone.
     #
-    # +rrsets+ is used to create a changeset.
-    #
     # Elements of +rrsets+ can contain +:records+, which can be:
     # - A +String+ containing a single record value.
     # - An +Array+ containing record values.
     # - An +Array+ containing hashes as specified in the PowerDNS API.
     #
-    # Example:
+    # @param rrsets [Array<Object>] Array of Hashes containing records to replace.
+    #
+    # @return [Hash] Hash containing result of the operation.
+    #
+    # @example
     #   zone.update({
     #     name: 'www0.example.com.',
     #     type: 'A',
@@ -184,7 +196,12 @@ module PDNS
     ##
     # Removes all records for a name/type combination from the zone.
     #
-    # Example:
+    # @param rrsets [Array<Object>] Array of Hashes to delete.
+    #  The Hash(es) in the Array should contain +:name+ and +:type+.
+    #
+    # @return [Hash] Hash containing result of the operation.
+    #
+    # @example
     #   zone.remove({
     #     name: 'www0.example.com.',
     #     type: 'A'
@@ -205,12 +222,15 @@ module PDNS
     ##
     # Returns existing metadata or creates a +Metadata+ object.
     #
-    # If +kind+ is not set the current metadata is returned in a hash.
+    # @param kind  [String, nil] The kind of metadata.
+    # @param value [String, nil] The value of the metadata.
     #
-    # If +kind+ is set a +Metadata+ object is returned using the provided +kind+.
-    # If +value+ is set as well, a complete Metadata object is returned.
+    # @return [Metadata, Hash] Hash containing all metadata, or single +Metadata+ object.
+    #   - If +kind+ is not set the current metadata is returned in a +Hash+.
+    #   - If +kind+ is set a +Metadata+ object is returned using the provided +kind+.
+    #   - If +value+ is set as well, a complete Metadata object is returned.
     #
-    # Example:
+    # @example
     #  # Retrieve all metadata in a hash
     #  zone.metadata
     #  # Create a metadata object
@@ -237,14 +257,21 @@ module PDNS
     ##
     # Returns existing or creates a +CryptoKey+ object.
     #
-    # If +id+ is not set the current servers are returned in a hash
-    # containing +CryptoKey+ objects.
     #
-    # If +id+ is set a +CryptoKey+ object with the provided ID is returned.
     #
-    # Example:
+    #
+    #
+    # @param id [Integer, nil] ID of a +CryptoKey+.
+    #
+    # @return [Hash, CryptoKey] Hash of +CryptoKeys+ or a single +CryptoKey+.
+    #   - If +id+ is not set the current servers are returned in a hash
+    #     containing +CryptoKey+ objects.
+    #   - If +id+ is set a +CryptoKey+ object with the provided ID is returned.
+    #
+    # @example
     #  ckeys = zone.cryptokeys
     #  ckey  = zone.cryptokey(12)
+    #
     def cryptokeys(id = nil)
       return CryptoKey.new(@http, self, id) unless id.nil?
 
@@ -259,6 +286,10 @@ module PDNS
 
     ##
     # Formats a single record to match what is required by the API.
+    #
+    # @param record [String, Hash] Record to format.
+    # @return [Hash] Formatted record.
+    #
     def format_single_record(record)
       # Ensure content
       record = { content: record } if record.is_a? String
@@ -274,6 +305,9 @@ module PDNS
 
     ##
     # Format the records in an RRset te match what is required by the API.
+    # @param rrset [Hash] RRset of which to format the records.
+    # @return [Hash] Formatted RRset.
+    #
     def format_records(rrset)
       # Ensure existence of required keys
       rrset[:records].map! do |record|
@@ -284,7 +318,7 @@ module PDNS
         record[:disabled] ||= !!rrset[:disabled]
 
         # Return record
-        next record unless @http.version == 0
+        next record unless @http.version.zero?
 
         # But add some more for APIv0
         record.merge(name: rrset[:name], type: rrset[:type], ttl: rrset[:ttl])
@@ -294,8 +328,12 @@ module PDNS
 
     ##
     # Returns the records matching the ones in +rrset+ from +data+.
-    # +data+ should be the result from +get+.
-    def current_records(rrset, data)
+    #
+    # @param rrset [Hash] RRset to match current records with.
+    # @param data  [Hash] RRsets currently on the server. Should be the result from +get+.
+    # @return [Array] Currently existing records.
+    #
+    def current_records(rrset, data) # rubocop:disable Metrics/AbcSize
       # Get the records from the data, `records` is v0, `rrsets` is v1
       records = data[:records] || data[:rrsets]
 
@@ -303,12 +341,12 @@ module PDNS
       current = records.select { |r| r[:name] == rrset[:name] && r[:type] == rrset[:type] }
 
       # Get only content/disabled for API v0
-      if @http.version == 0
-        current.map! { |record| { content:  record[:content], disabled: record[:disabled] } }
+      if @http.version.zero?
+        current.map! { |record| { content: record[:content], disabled: record[:disabled] } }
       end
 
       # For API v1 there is only one element containing all records
-      current = current.first[:records] unless @http.version == 0
+      current = current.first[:records] unless current.empty? || @http.version.zero?
 
       # Return the records
       current

data/lib/pdns_api.rb

@@ -28,6 +28,10 @@ module PDNS
   class << self
     ##
     # Create a PDNS::Client object.
+    #
+    # @param args [Hash] arguments used to create a +Client+ object.
+    # @return [Client] a client object to communicate to the API.
+    #
     def new(args)
       Client.new(args)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pdns_api
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Silke Hofstra
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-31 00:00:00.000000000 Z
+date: 2018-09-04 00:00:00.000000000 Z
 dependencies: []
 description: A gem for manipulation of DNS through the PowerDNS API
 email: silke.ruby@slxh.nl
@@ -29,7 +29,7 @@ files:
 - lib/pdns_api/zone.rb
 homepage: https://github.com/silkeh/ruby-pdns_api
 licenses:
-- EUPL
+- EUPL-1.1
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -47,7 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: PowerDNS API gem