pdns_api 0.0.5 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c1a4f09dcbfd236725e10397468a523a9b9a19d4
-  data.tar.gz: 4294fc6d7f39065d5c64bdfe902a290def36b48d
+  metadata.gz: fc62c8d844cbb2661dc1f19f56e6a12b4f659095
+  data.tar.gz: 28c1046f94f11236f1c4ab43ecce060976351104
 SHA512:
-  metadata.gz: 5ddabc8ebca91f59ddb30cded068d20aba62054266d1c6faf7d89781037bfef3064ba0d046085dd78daecfd085c5a5bbbdd9021e4ba0af590d2fbb06b1073b9f
-  data.tar.gz: d26e976a7a9e62d8225193d848894337afe5b39a5272b7e78e92bb175cab7ae86f3b79575c6839ba85e0369878d0da815dfc248d66548e6aa9bf9412a29304fd
+  metadata.gz: 02ea243ba0cba7ea74b905c6b6475682e94227f0a97899a01d9a4167651440512e73d720baad8b5a804886e6f7c7c9cd4b43a9c1ae8f329b0e399526649b852d
+  data.tar.gz: d069a42d616b1b48d65ca6a4f41bd31be5204284308545763b59dbecc982ca0a8c3afb8ba13fce0275e7729440b6c634f1841c328f449428c58987ae538978f2

data/lib/pdns_api/api.rb

@@ -1,58 +1,74 @@
+# Copyright 2016 - Silke Hofstra
+#
+# Licensed under the EUPL, Version 1.1 or -- as soon they will be approved by
+# the European Commission -- subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Licence is distributed on an "AS IS" basis,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied.
+# See the Licence for the specific language governing
+# permissions and limitations under the Licence.
+#
+
 require 'pdns_api/http'
 
-# PDNS API interface
+##
+#
 module PDNS
-  # Class for interacting with the API
+  ##
+  # The superclass for all PDNS objects.
   class API
-    attr_reader :url, :class, :version
-
-    def initialize(args)
-      @class   = :client
-      @http    = PDNS::HTTP.new(args)
-      @version = @http.version
-      @parent  = self
-      @url     = @http.uri
-      @info    = {}
-    end
+    ##
+    # The url of the resource object.
+    attr_reader :url
 
-    ## Standard manipulation methods
+    ##
+    # The class of the resource object.
+    attr_reader :class
 
-    # Get information for this object
+    ##
+    # Gets the information of this object from the API and use it
+    # to update the object's information.
     def get
       @info = @http.get @url
     end
 
-    # Delete this object
+    ##
+    # Deletes this object
     def delete
       @http.delete @url
     end
 
-    # Create this object on the server
+    ##
+    # Creates this object on the server
     def create(info = nil)
       info(info)
       @http.post("#{@parent.url}/#{@class}", @info)
     end
 
-    # Get/set info
+    ##
+    # Gets and sets the object information.
+    # This does not cause an API request.
+    #
+    # If +info+ is set this method updates the current information.
+    #
     def info(info = nil)
       return @info if info.nil?
 
       @info.merge!(info)
     end
 
-    ## Helper methods
-
+    ##
+    # Ensures the object is an array.
+    # If it is not, an array containing the item is returned
     def ensure_array(item)
       return item if item.is_a? Array
       [item]
     end
-
-    def self.hash_sym_to_string(hash)
-      hash.map { |symbol, value| [symbol.to_s, value] }.to_h
-    end
-
-    def self.hash_string_to_sym(hash)
-      hash.map { |string, value| [string.to_sym, value] }.to_h
-    end
   end
 end

data/lib/pdns_api/client.rb

@@ -1,14 +1,54 @@
+# Copyright 2016 - Silke Hofstra
+#
+# Licensed under the EUPL, Version 1.1 or -- as soon they will be approved by
+# the European Commission -- subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Licence is distributed on an "AS IS" basis,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied.
+# See the Licence for the specific language governing
+# permissions and limitations under the Licence.
+#
+
 require 'pdns_api/version'
 require 'pdns_api/api'
 require 'pdns_api/server'
 
-# PDNS client
+##
+#
 module PDNS
-  # Client
+  ##
+  # Class for interaction with the top level API.
   class Client < API
+    ##
+    # The PowerDNS API version in use.
     attr_reader :version
 
-    ## Main methods
+    ##
+    # Creates a client object.
+    # +args+ is used to create an HTTP object,
+    # which is used by all created objects.
+    def initialize(args)
+      @class   = :client
+      @http    = PDNS::HTTP.new(args)
+      @version = @http.version
+      @parent  = self
+      @url     = @http.uri
+      @info    = {}
+    end
+
+    ##
+    # Returns existing or creates a +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.
     def servers(id = nil)
       return Server.new(@http, self, id) unless id.nil?
 

data/lib/pdns_api/config.rb

@@ -1,9 +1,41 @@
-# PDNS Server config
+# Copyright 2016 - Silke Hofstra
+#
+# Licensed under the EUPL, Version 1.1 or -- as soon they will be approved by
+# the European Commission -- subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Licence is distributed on an "AS IS" basis,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied.
+# See the Licence for the specific language governing
+# permissions and limitations under the Licence.
+#
+
+##
+#
 module PDNS
-  # Server config
+  ##
+  # Configuration option for a DNS Server.
   class Config < API
-    attr_accessor :name, :value
+    ##
+    # The name of the configuration option.
+    attr_accessor :name
+
+    ##
+    # The value of the configuration option.
+    attr_accessor :value
 
+    ##
+    # 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.
     def initialize(http, parent, name, value = nil)
       @class  = :config
       @http   = http
@@ -14,21 +46,31 @@ module PDNS
       value(@value)
     end
 
-    ## Simple interfaces to metadata
-    # Get/set config value
+    ##
+    # 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
     def value(value = nil)
-      return @info[:value] if value.nil?
+      return @value if value.nil?
       @value = value
       @info  = { type: 'ConfigSetting', name: @name, value: value }
     end
 
-    # Get configuration value
+    ##
+    # Gets the current information.
+    # This also updates +value+.
     def get
-      res = @http.get(@url)
-      return value if res.key? :value
+      res = @http.get @url
+      value(res[:value]) if res.key? :value
+      res
     end
 
-    # Change configuration
+    ##
+    # Updates the object on the server.
+    #
+    # 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/cryptokey.rb

@@ -1,7 +1,33 @@
-# PDNS Zone CryptoKeys
+# Copyright 2016 - Silke Hofstra
+#
+# Licensed under the EUPL, Version 1.1 or -- as soon they will be approved by
+# the European Commission -- subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Licence is distributed on an "AS IS" basis,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied.
+# See the Licence for the specific language governing
+# permissions and limitations under the Licence.
+#
+
+##
+#
 module PDNS
-  # Zone CryptoKey
+  ##
+  # Cryptokey for a zone.
   class CryptoKey < API
+    ##
+    # 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.
     def initialize(http, parent, id, info = {})
       @class  = :cryptokeys
       @http   = http
@@ -11,9 +37,10 @@ module PDNS
       @url    = "#{parent.url}/#{@class}/#{id}"
     end
 
-    ## Simple interfaces to metadata
-
-    # Change cryptokey information
+    ##
+    # Changes cryptokey information
+    #
+    # +rrset+ is used as changeset for the update.
     def change(rrsets)
       @http.put(@url, rrsets)
     end

data/lib/pdns_api/http.rb

@@ -1,10 +1,47 @@
-# PDNS HTTP API interface
+# Copyright 2016 - Silke Hofstra
+#
+# Licensed under the EUPL, Version 1.1 or -- as soon they will be approved by
+# the European Commission -- subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Licence is distributed on an "AS IS" basis,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied.
+# See the Licence for the specific language governing
+# permissions and limitations under the Licence.
+#
+
+##
+#
 module PDNS
-  # Class for doing HTTP requests
+  ##
+  # Class for connecting to the PowerDNS API.
   class HTTP
+    ##
+    # The headers used for requests.
     attr_accessor :headers
+
+    ##
+    # 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+.
+    #   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]
@@ -13,25 +50,17 @@ module PDNS
       @headers = { 'X-API-Key' => @key }
     end
 
+    ##
+    # Returns the correct URI for a request.
+    # This depends on the API version.
     def uri(request = '')
       base = ''
-      base = "/api/v#{@version}" unless @version == 0 || request[0..4] == '/api/'
+      base = "/api/v#{@version}" unless @version == 0 || request[0..3] == '/api'
       base + request
     end
 
-    # Create the right method object
-    def http_method(method, uri)
-      # Create the right request
-      case method
-      when 'GET'    then Net::HTTP::Get.new(uri, @headers)
-      when 'PATCH'  then Net::HTTP::Patch.new(uri, @headers)
-      when 'POST'   then Net::HTTP::Post.new(uri, @headers)
-      when 'PUT'    then Net::HTTP::Put.new(uri, @headers)
-      when 'DELETE' then Net::HTTP::Delete.new(uri, @headers)
-      else               abort('Unknown method: ' + method)
-      end
-    end
-
+    ##
+    # Decodes the response from the server.
     def response_decode(response)
       return {} if response.body.nil?
 
@@ -43,17 +72,21 @@ module PDNS
       end
     end
 
-    # Do an HTTP request
-    def http(method, request, body = nil)
+    ##
+    # 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.
+    def http(net, body = nil)
+      # Debug output
+      puts 'Body: ' + body.to_json if ENV['DEBUG']
+
       # Start an HTTP connection
       begin
         response = Net::HTTP.start(@host, @port) do |http|
-          # Create uri & request
-          uri = uri(request)
-          req = http_method(method, uri)
-
           # Do the request
-          http.request(req, body.to_json)
+          http.request(net, body.to_json)
         end
       rescue StandardError, Timeout::Error => e
         abort("Error: #{e}")
@@ -62,29 +95,49 @@ module PDNS
       response_decode(response)
     end
 
-    # Do a DELETE request
+    ##
+    # Does an HTTP +DELETE+ request to +uri+.
+    # Returns the decoded response.
     def delete(uri)
-      http('DELETE', uri)
+      uri = uri(uri)
+      net = Net::HTTP::Delete.new(uri, @headers)
+      http(net)
     end
 
-    # Do a GET request
+    ##
+    # Does an HTTP +GET+ request to +uri+.
+    # Returns the decoded response.
     def get(uri)
-      http('GET', uri)
+      uri = uri(uri)
+      net = Net::HTTP::Get.new(uri, @headers)
+      http(net)
     end
 
-    # Do a PATCH request
+    ##
+    # Does an HTTP +PATCH+ request to +uri+.
+    # Returns the decoded response.
     def patch(uri, body = nil)
-      http('PATCH', uri, body)
+      uri = uri(uri)
+      net = Net::HTTP::Patch.new(uri, @headers)
+      http(net, body)
     end
 
-    # Do a POST request
+    ##
+    # Does an HTTP +POST+ request to +uri+.
+    # Returns the decoded response.
     def post(uri, body = nil)
-      http('POST', uri, body)
+      uri = uri(uri)
+      net = Net::HTTP::Post.new(uri, @headers)
+      http(net, body)
     end
 
-    # Do a PUT request
+    ##
+    # Does an HTTP +PUT+ request to +uri+.
+    # Returns the decoded response.
     def put(uri, body = nil)
-      http('PUT', uri, body)
+      uri = uri(uri)
+      net = Net::HTTP::Put.new(uri, @headers)
+      http(net, body)
     end
   end
 end

data/lib/pdns_api/metadata.rb

@@ -1,37 +1,82 @@
-# PDNS Zone Metadata
+# Copyright 2016 - Silke Hofstra
+#
+# Licensed under the EUPL, Version 1.1 or -- as soon they will be approved by
+# the European Commission -- subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Licence is distributed on an "AS IS" basis,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied.
+# See the Licence for the specific language governing
+# permissions and limitations under the Licence.
+#
+
+##
+#
 module PDNS
-  # Zone Metadata
+  ##
+  # Metadata for a zone.
   class Metadata < API
-    def initialize(http, parent, kind, info = {})
+    ##
+    # The kind of metadata.
+    attr_accessor :kind
+
+    ##
+    # The value of the metadata.
+    attr_accessor :value
+
+    ##
+    # 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.
+    def initialize(http, parent, kind, value = [])
       @class  = :metadata
       @http   = http
       @parent = parent
       @kind   = kind
-      @info   = info
-      @url    = "#{parent.url}/metadata/#{kind}"
+      @url    = "#{parent.url}/#{@class}/#{kind}"
+      @value  = value.get if value.empty?
+      value(@value)
     end
 
-    ## Simple interfaces to metadata
-
-    # Set the metadata value
+    ##
+    # 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.
     def value(value = nil)
       return @info[:metadata] if value.nil?
 
       # Convert to array if value is string
-      value = [value] if value.is_a? String
+      value = ensure_array(value)
 
-      # Set info
-      @info = { type: 'Metadata', kind: @kind, metadata: value }
+      # Set value and info
+      @value = value
+      @info  = { type: 'Metadata', kind: @kind, metadata: value }
     end
 
-    # Retrieve metadata value
+    ##
+    # Gets the current information.
+    # This also updates +value+.
     def get
       res = @http.get @url
-      return value if res.key? :value
+      value(res[:value]) if res.key? :value
+      res
     end
 
-    # Change metadata
-    def change(value)
+    ##
+    # Updates the object on the server.
+    #
+    # 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)
     end

data/lib/pdns_api/override.rb

@@ -1,9 +1,37 @@
-# PDNS Server Override
+# Copyright 2016 - Silke Hofstra
+#
+# Licensed under the EUPL, Version 1.1 or -- as soon they will be approved by
+# the European Commission -- subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Licence is distributed on an "AS IS" basis,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied.
+# See the Licence for the specific language governing
+# permissions and limitations under the Licence.
+#
+
+##
+#
 module PDNS
-  # Server override
+  ##
+  # Override for a server.
   class Override < API
-    attr_reader :id, :url, :info
+    ##
+    # 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.
     def initialize(http, parent, id, info = {})
       @class  = :overrides
       @http   = http
@@ -13,9 +41,10 @@ module PDNS
       @url    = "#{parent.url}/#{@class}/#{id}"
     end
 
-    ## Simple interfaces to overrides
-
-    # Change override settings
+    ##
+    # Changes override information.
+    #
+    # +rrset+ is used as changeset for the update.
     def change(rrsets)
       @http.put(@url, rrsets)
     end

data/lib/pdns_api/server.rb

@@ -1,13 +1,41 @@
+# Copyright 2016 - Silke Hofstra
+#
+# Licensed under the EUPL, Version 1.1 or -- as soon they will be approved by
+# the European Commission -- subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Licence is distributed on an "AS IS" basis,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied.
+# See the Licence for the specific language governing
+# permissions and limitations under the Licence.
+#
+
 require 'pdns_api/config'
 require 'pdns_api/override'
 require 'pdns_api/zone'
 
-# PDNS Server
+##
+#
 module PDNS
-  # PDNS Server
+  ##
+  # Server object for accessing data for a particular server.
   class Server < API
+    ##
+    # 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.
     def initialize(http, parent, id, info = {})
       @class  = :servers
       @http   = http
@@ -17,36 +45,45 @@ module PDNS
       @info   = info
     end
 
-    ## Server interfaces
-    # TODO: /servers/:server_id: ?
-
-    ## Server actions
-
+    ##
+    # Flushes cache for +domain+.
     def cache(domain)
       # TODO: #{url}/cache/flush?domain=:domain: PUT
     end
 
+    ##
+    # Searches through the server's log with +search_term+.
     def search_log(search_term)
       # TODO: /servers/:server_id/search-log?q=:search_term: GET
     end
 
+    ##
+    # Gets the statistics for the server.
     def statistics
       # TODO: /servers/:server_id/statistics: GET
     end
 
+    ##
+    # Manipulates the query tracing log.
     def trace
       # TODO: /servers/:server_id/trace: GET, PUT
     end
 
+    ##
+    # Manipulates failure logging.
     def failures
       # TODO: /servers/:server_id/failures: GET, PUT
     end
 
-    ## Server resources
-
-    # Get or set server config
+    ##
+    # Returns existing configuration or creates a +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.
     def config(name = nil, value = nil)
-      return Config.new(@http, self, name, value).create unless 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?
 
       # Get all current configuration
@@ -54,7 +91,13 @@ module PDNS
       config.map { |c| [c[:name], c[:value]] }.to_h
     end
 
-    # Get or set server overrides, not yet implemented
+    ##
+    # Returns existing or creates an +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.
     def overrides(id = nil)
       return Override.new(@http, self, id) unless id.nil?
 
@@ -62,9 +105,15 @@ module PDNS
       overrides.map { |o| [o[:id], Override.new(@http, self, o[:id], o)] }.to_h
     end
 
-    # Get zones or create one
-    def zones(zone_id = nil)
-      return Zone.new(@http, self, zone_id) unless zone_id.nil?
+    ##
+    # Returns existing or creates a +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.
+    def zones(id = nil)
+      return Zone.new(@http, self, id) unless id.nil?
 
       zones = @http.get("#{@url}/zones")
       zones.map { |z| [z[:id], Zone.new(@http, self, z[:id], z)] }.to_h

data/lib/pdns_api/version.rb

@@ -1,4 +1,24 @@
-# PDNS version
+# Copyright 2016 - Silke Hofstra
+#
+# Licensed under the EUPL, Version 1.1 or -- as soon they will be approved by
+# the European Commission -- subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Licence is distributed on an "AS IS" basis,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied.
+# See the Licence for the specific language governing
+# permissions and limitations under the Licence.
+#
+
+##
+#
 module PDNS
-  VERSION = '0.0.5'.freeze
+  ##
+  # The version of +pdns_api+.
+  VERSION = '0.1.0'.freeze
 end

data/lib/pdns_api/zone.rb

@@ -1,12 +1,40 @@
-# PDNS Zone
+# Copyright 2016 - Silke Hofstra
+#
+# Licensed under the EUPL, Version 1.1 or -- as soon they will be approved by
+# the European Commission -- subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Licence is distributed on an "AS IS" basis,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied.
+# See the Licence for the specific language governing
+# permissions and limitations under the Licence.
+#
+
+require 'pdns_api/metadata'
+require 'pdns_api/cryptokey'
+
+##
+#
 module PDNS
-  require_relative 'metadata'
-  require_relative 'cryptokey'
-
-  # Zone
+  ##
+  # Zone on a server.
   class Zone < API
+    ##
+    # 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.
     def initialize(http, parent, id, info = {})
       @class  = :zones
       @http   = http
@@ -16,47 +44,113 @@ module PDNS
       @url    = "#{parent.url}/#{@class}/#{id}"
     end
 
-    ## Zone interfaces
-
-    # Modifies present RRsets and comments.
+    ##
+    # Modifies information (records) of a zone.
+    # Also formats records to match the API requirements.
     def modify(rrsets)
-      rrsets.map! { |rrset| format_records(rrset) if rrset.key?(:records) }
+      rrsets.map! do |rrset|
+        rrset = format_records(rrset) if rrset.key?(:records)
+        rrset
+      end
 
       @http.patch(@url, rrsets: rrsets)
     end
 
+    ##
     # Modifies basic zone data (metadata).
+    # +rrset+ is used as changeset for the update.
     def change(rrsets)
       @http.put(@url, rrsets)
     end
 
-    ## Zone actions
-
-    # Notify slaves for a zone
+    ##
+    # Notifies slaves for a zone.
+    # Only works for domains for which the server is a master.
+    # Returns the result of the notification.
     def notify
       @http.put "#{@url}/notify"
     end
 
-    # Get the AXFR for a zone
+    ##
+    # Retrieves the data for a zone.
+    # Only works for domains for which the server is a slave.
+    # Returns the result of the retrieval.
     def axfr_retrieve
       @http.put "#{@url}/axfr-retrieve"
     end
 
-    # Export a zone
+    ##
+    # Exports the zone as a bind zone file.
+    # Returns a hash containing the zone in +:result+.
     def export
-      @http.get "#{@url}/export"
+      data = @http.get "#{@url}/export"
+      data.delete(:error) if data[:error] == 'Non-JSON response'
+      data
     end
 
-    # Check a zone
+    ##
+    # Checks the zone for errors.
+    # Returns the result of the check.
     def check
       @http.get "#{@url}/check"
     end
 
-    ## Zone resources
+    ##
+    # Adds records to the ones already existing in the zone.
+    #
+    # The existing records are retrieved and merged with the ones given in +rrsets+.
+    def add(*rrsets)
+      # Get current zone data
+      data = get
+
+      # Return any errors
+      return data if data.key?(:error)
+
+      # Add these records to the rrset
+      rrsets.map! do |rrset|
+        # Get current data from rrset
+        current = current_records(rrset, data)
+
+        # Merge data
+        rrset[:records]    = current + ensure_array(rrset[:records])
+        rrset[:changetype] = 'REPLACE'
+        rrset
+      end
+      modify(rrsets)
+    end
+
+    ##
+    # Updates (replaces) records for a name/type combination in the zone.
+    def update(*rrsets)
+      # Set type and format records
+      rrsets.map! do |rrset|
+        rrset[:changetype] = 'REPLACE'
+        rrset[:records] = ensure_array(rrset[:records])
+        rrset
+      end
+      modify(rrsets)
+    end
+
+    ##
+    # Removes all records for a name/type combination from the zone.
+    def remove(*rrsets)
+      # Set type and format records
+      rrsets.map! do |rrset|
+        rrset[:changetype] = 'DELETE'
+        rrset
+      end
+      modify(rrsets)
+    end
 
-    # Manipulate metadata for a zone
+    ##
+    # Returns existing metadata or creates a +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.
     def metadata(kind = nil, value = nil)
-      return Metadata.new(@http, self, kind, value).create unless kind.nil? || value.nil?
+      return Metadata.new(@http, self, kind, value) unless kind.nil? || value.nil?
       return Metadata.new(@http, self, kind) unless kind.nil?
 
       # Get all current metadata
@@ -66,10 +160,16 @@ module PDNS
       return metadata if metadata.is_a?(Hash) && metadata.key?(:error)
 
       # Convert metadata to hash
-      metadata.map! { |c| [c[:kind], c[:metadata]] }.to_h
+      metadata.map { |c| [c[:kind], c[:metadata]] }.to_h
     end
 
-    # Change cryptokeys for a zone
+    ##
+    # 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.
     def cryptokeys(id = nil)
       return CryptoKey.new(@http, self, id) unless id.nil?
 
@@ -77,11 +177,13 @@ module PDNS
       cryptokeys = @http.get("#{@url}/cryptokeys")
 
       # Convert cryptokeys to hash
-      cryptokeys.map! { |c| [c[:id], CryptoKey.new(@http, self, c[:id], c)] }.to_h
+      cryptokeys.map { |c| [c[:id], CryptoKey.new(@http, self, c[:id], c)] }.to_h
     end
 
-    ## Additional methods
+    private
 
+    ##
+    # Formats a single record to match what is required by the API.
     def format_single_record(record)
       # Ensure content
       record = { content: record } if record.is_a? String
@@ -95,11 +197,9 @@ module PDNS
       record
     end
 
-    # Add required items to records in an rrset
+    ##
+    # Format the records in an RRset te match what is required by the API.
     def format_records(rrset)
-      # Abort if rrset is something else than an array
-      abort('Error: records needs to be array') unless rrset[:records].is_a? Array
-
       # Ensure existence of required keys
       rrset[:records].map! do |record|
         # Format the record content
@@ -117,69 +217,26 @@ module PDNS
       rrset
     end
 
-    # Add records to the ones already existing
-    # Only works from API v1 and up
-    def add(*rrsets)
-      # Get current zone data
-      data = get
+    ##
+    # Returns the records matching the ones in +rrset+ from +data+.
+    # +data+ should be the result from +get+.
+    def current_records(rrset, data)
+      # Get the records from the data, `records` is v0, `rrset` is v1
+      records = data[:records] || data[:rrset]
 
-      # Return any errors
-      return data if data.key?(:error)
-
-      # Run v0 version
-      return add_v0(rrsets, data) if @http.version == 0
+      # Select records matching type/name
+      current = records.select { |r| r[:name] == rrset[:name] && r[:type] == rrset[:type] }
 
-      # Add these records to the rrset
-      rrsets.map! do |rrset|
-        # Get current data from rrset
-        current = data[:rrsets].select { |r| r[:name] == rrset[:name] && r[:type] == rrset[:type] }
-
-        # Merge data
-        rrset[:records]    = current.first[:records] + ensure_array(rrset[:records])
-        rrset[:changetype] = 'REPLACE'
-        rrset
+      # Get only content/disabled for API v0
+      if @http.version == 0
+        current.map! { |record| { content:  record[:content], disabled: record[:disabled] } }
       end
-      modify(rrsets)
-    end
 
-    # Add records to the ones already existing
-    # Only works from API v1 and down
-    def add_v0(rrsets, data)
-      # Add these records to the rrset
-      rrsets.map! do |rrset|
-        current = data[:records].select do |r|
-          r[:name] == rrset[:name] && r[:type] == rrset[:type]
-        end
-        current.map! do |record|
-          {
-            content:  record[:content],
-            disabled: record[:disabled]
-          }
-        end
-        rrset[:records] = current + ensure_array(rrset[:records])
-        rrset[:changetype] = 'REPLACE'
-        rrset
-      end
-      modify(rrsets)
-    end
-
-    def update(*rrsets)
-      # Set type and format records
-      rrsets.map! do |rrset|
-        rrset[:changetype] = 'REPLACE'
-        rrset[:records] = ensure_array(rrset[:records])
-        rrset
-      end
-      modify(rrsets)
-    end
+      # For API v1 there is only one element containing all records
+      current = current.first[:records] unless @http.version == 0
 
-    def remove(*rrsets)
-      # Set type and format records
-      rrsets.map! do |rrset|
-        rrset[:changetype] = 'DELETE'
-        rrset
-      end
-      modify(rrsets)
+      # Return the records
+      current
     end
   end
 end

data/lib/pdns_api.rb

@@ -1,11 +1,33 @@
+# Copyright 2016 - Silke Hofstra
+#
+# Licensed under the EUPL, Version 1.1 or -- as soon they will be approved by
+# the European Commission -- subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Licence is distributed on an "AS IS" basis,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied.
+# See the Licence for the specific language governing
+# permissions and limitations under the Licence.
+#
+
 require 'json'
 require 'net/http'
 
-# PDNS module
+##
+# Module for interaction with the PowerDNS HTTP API.
 module PDNS
   require_relative 'pdns_api/client'
 
+  ##
+  # Class for creation of PDNS objects.
   class << self
+    ##
+    # Create a PDNS::Client object.
     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.0.5
+  version: 0.1.0
 platform: ruby
 authors:
 - Silke Hofstra
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-24 00:00:00.000000000 Z
+date: 2016-05-30 00:00:00.000000000 Z
 dependencies: []
 description: A gem for manipulation of DNS through the PowerDNS API
 email: silke@slxh.eu
@@ -29,7 +29,7 @@ files:
 - lib/pdns_api/zone.rb
 homepage: https://github.com/silkeh/ruby-pdns_api
 licenses:
-- GPLv3+
+- EUPL
 metadata: {}
 post_install_message: 
 rdoc_options: []