pdns_api 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 657948fecf6bc98b2564c4ca8a662fe535effc76
4
- data.tar.gz: 5f3d133e97e22df2ff682500d079bc0cbeed06f8
2
+ SHA256:
3
+ metadata.gz: 983b46d03f4c320e0ede5af20db05e9e0823e49f53d38116edceaa8070ee7ac9
4
+ data.tar.gz: 535c5967564d63f66820208181e5ab93aa9c80e636447e0d6a9a31783619f9f0
5
5
  SHA512:
6
- metadata.gz: b1f5e2794d3d8da64596717ac8beb59328e90eb6774e91561aff3183eb6ed9e5bfb74549056c6247599279b56482046dad74e195692d4d2d11b13a20131978bc
7
- data.tar.gz: b4f3d1ac66fd8abe82170710da88927f86d4283018384804188eb715472203347306c227d8d2536a17df995af6286587e7dfbcd2545eb00551c85a37e72ec077
6
+ metadata.gz: 86e358875b062b3a937357e87e55cd410d4edde9cdd002e1dedc8eae2d4e5eebf20eb736d3d9e736aa6fc1983c29175dbab2f00f7b19573ca2a7e31f40b4145f
7
+ data.tar.gz: 036fe570d1f54074abbb29ed40ead3a7afb740e652b31ce5d0cff2354da5c4caedb988fceb4f8304ae9fa7079a764ca3ecbb8644a345a5b3080619ee124e38fd
data/lib/pdns_api/api.rb CHANGED
@@ -18,23 +18,25 @@
18
18
  require 'pdns_api/http'
19
19
 
20
20
  ##
21
- #
21
+ # Module for interaction with the PowerDNS HTTP API.
22
22
  module PDNS
23
23
  ##
24
24
  # The superclass for all PDNS objects.
25
25
  class API
26
26
  ##
27
- # The url of the resource object.
27
+ # @return the url of the resource object.
28
28
  attr_reader :url
29
29
 
30
30
  ##
31
- # The class of the resource object.
31
+ # @return the class of the resource object.
32
32
  attr_reader :class
33
33
 
34
34
  ##
35
35
  # Changes this object's information on the server.
36
36
  #
37
- # +rrsets+ is used as changeset for the update.
37
+ # @param rrsets [Array] is used as changeset for the change.
38
+ # @return [Hash] result of the change.
39
+ #
38
40
  def change(rrsets)
39
41
  @http.put(@url, rrsets)
40
42
  end
@@ -45,20 +47,27 @@ module PDNS
45
47
  # If +info+ is set this method updates the current information.
46
48
  # The current information is used to create the object.
47
49
  #
48
- # Example:
50
+ # @param info [Hash, nil] Information to set when creating the object.
51
+ # @return [Hash] result of the creation.
52
+ #
53
+ # @example
49
54
  # zone.create(
50
55
  # name: zone.id,
51
56
  # kind: 'Native',
52
57
  # dnssec: true,
53
58
  # nameservers: %w( ns0.example.com. ns1.example.com. )
54
59
  # )
60
+ #
55
61
  def create(info = nil)
56
62
  info(info)
57
63
  @http.post("#{@parent.url}/#{@class}", @info)
58
64
  end
59
65
 
60
66
  ##
61
- # Deletes this object
67
+ # Deletes this object.
68
+ #
69
+ # @return [Hash] result of the deletion.
70
+ #
62
71
  def delete
63
72
  @http.delete @url
64
73
  end
@@ -66,6 +75,9 @@ module PDNS
66
75
  ##
67
76
  # Gets the information of this object from the API and use it
68
77
  # to update the object's information.
78
+ #
79
+ # @return [Hash] the object's information from the API.
80
+ #
69
81
  def get
70
82
  @info = @http.get @url
71
83
  end
@@ -74,7 +86,9 @@ module PDNS
74
86
  # Gets and sets the object information.
75
87
  # This does not cause an API request.
76
88
  #
77
- # If +info+ is set this method updates the current information.
89
+ # @param info [Hash, nil] Information to change.
90
+ # @return [Hash] this object's information.
91
+ #
78
92
  def info(info = nil)
79
93
  return @info if info.nil?
80
94
 
@@ -84,6 +98,10 @@ module PDNS
84
98
  ##
85
99
  # Ensures the object is an array.
86
100
  # If it is not, an array containing the item is returned.
101
+ #
102
+ # @param item anything that might or might not be an +Array+.
103
+ # @return [Array] +item+ as an array.
104
+ #
87
105
  def ensure_array(item)
88
106
  return item if item.is_a? Array
89
107
  [item]
@@ -20,13 +20,13 @@ require 'pdns_api/api'
20
20
  require 'pdns_api/server'
21
21
 
22
22
  ##
23
- #
23
+ # Module for interaction with the PowerDNS HTTP API.
24
24
  module PDNS
25
25
  ##
26
26
  # Class for interaction with the top level API.
27
27
  class Client < API
28
28
  ##
29
- # The PowerDNS API version in use.
29
+ # @return [Integer] the PowerDNS API version in use.
30
30
  attr_reader :version
31
31
 
32
32
  ##
@@ -34,9 +34,11 @@ module PDNS
34
34
  undef_method :change, :create, :delete
35
35
 
36
36
  ##
37
- # Creates a client object.
38
- # +args+ is used to create an HTTP object,
39
- # which is used by all created objects.
37
+ # Creates a +Client+ object.
38
+ #
39
+ # @param args [Hash] Arguments used to create an +HTTP+ object,
40
+ # which is used by all created objects.
41
+ #
40
42
  def initialize(args)
41
43
  @class = :client
42
44
  @http = PDNS::HTTP.new(args)
@@ -49,10 +51,13 @@ module PDNS
49
51
  ##
50
52
  # Returns existing or creates a +Server+ object.
51
53
  #
52
- # If +id+ is not set the current servers are returned in a hash
53
- # containing +Server+ objects.
54
+ # @param id [String, nil] ID of a Server.
55
+ #
56
+ # @return [Hash, Server] Hash of +Server+ objects or a single +Server+ object.
57
+ # - If +id+ is not set the current servers are returned in a hash
58
+ # containing +Server+ objects.
59
+ # - If +id+ is set a +Server+ object with the provided ID is returned.
54
60
  #
55
- # If +id+ is set a +Server+ object with the provided ID is returned.
56
61
  def servers(id = nil)
57
62
  return Server.new(@http, self, id) unless id.nil?
58
63
 
@@ -16,13 +16,13 @@
16
16
  #
17
17
 
18
18
  ##
19
- #
19
+ # Module for interaction with the PowerDNS HTTP API.
20
20
  module PDNS
21
21
  ##
22
22
  # Configuration option for a DNS Server.
23
23
  class Config < API
24
24
  ##
25
- # The name of the configuration option.
25
+ # @return [String] the name of the configuration option.
26
26
  attr_accessor :name
27
27
 
28
28
  ##
@@ -32,10 +32,11 @@ module PDNS
32
32
  ##
33
33
  # Creates a configuration option object.
34
34
  #
35
- # - +http+: An HTTP object for interaction with the PowerDNS server.
36
- # - +parent+: This object's parent.
37
- # - +name+: Name of the configuration option.
38
- # - +value+: Optional value of the configuration option.
35
+ # @param http [HTTP] An HTTP object for interaction with the PowerDNS server.
36
+ # @param parent [API] This object's parent.
37
+ # @param name [String] Name of the configuration option.
38
+ # @param value [String] Optional value of the configuration option.
39
+ #
39
40
  def initialize(http, parent, name, value = nil)
40
41
  @class = :config
41
42
  @http = http
@@ -49,17 +50,22 @@ module PDNS
49
50
  ##
50
51
  # Gets or sets the +value+ attribute.
51
52
  #
52
- # If +value+ is not set the current +value+ is returned.
53
- # If +value+ is set the object's +value+ is updated and +info+ is set and returned
53
+ # @param value [String, nil] the value of the object.
54
+ # @return [String] the value of the object.
55
+ # If +value+ is set the object's +value+ is updated.
56
+ #
54
57
  def value(value = nil)
55
58
  return @value if value.nil?
56
- @value = value
57
59
  @info = { type: 'ConfigSetting', name: @name, value: value }
60
+ @value = value
58
61
  end
59
62
 
60
63
  ##
61
64
  # Gets the current information.
62
65
  # This also updates +value+.
66
+ #
67
+ # @return [Hash] the object's information from the API.
68
+ #
63
69
  def get
64
70
  res = @http.get @url
65
71
  value(res[:value]) if res.key? :value
@@ -67,12 +73,16 @@ module PDNS
67
73
  end
68
74
 
69
75
  ##
70
- # Updates the object on the server.
76
+ # Changes this object's information on the server.
77
+ #
78
+ # @param value [String, nil] Value to change the object to.
79
+ # - If +value+ is set, the current +value+ is used.
80
+ # - If +value+ is not set, +value+ is updated and then used.
71
81
  #
72
- # If +value+ is set, the current +value+ is used.
73
- # If +value+ is not set, +value+ is updated and then used.
82
+ # @return [Hash] result of the change.
74
83
  #
75
- # Example:
84
+ # @example
85
+ # config = server.config('version')
76
86
  # config.change('PowerDNS v3.14159265')
77
87
  #
78
88
  def change(value = nil)
@@ -16,22 +16,23 @@
16
16
  #
17
17
 
18
18
  ##
19
- #
19
+ # Module for interaction with the PowerDNS HTTP API.
20
20
  module PDNS
21
21
  ##
22
22
  # Cryptokey for a zone.
23
23
  class CryptoKey < API
24
24
  ##
25
- # The ID of the cryptokey.
25
+ # @return [Integer] the ID of the cryptokey.
26
26
  attr_reader :id
27
27
 
28
28
  ##
29
29
  # Creates a cryptokey object.
30
30
  #
31
- # - +http+: An HTTP object for interaction with the PowerDNS server.
32
- # - +parent+: This object's parent.
33
- # - +id+: Identifier of the cryptokey.
34
- # - +info+: Optional information about the cryptokey.
31
+ # @param http [HTTP] An HTTP object for interaction with the PowerDNS server.
32
+ # @param parent [API] This object's parent.
33
+ # @param id [Integer] Identifier of the cryptokey.
34
+ # @param info [Hash] Optional information about the cryptokey.
35
+ #
35
36
  def initialize(http, parent, id, info = {})
36
37
  @class = :cryptokeys
37
38
  @http = http
data/lib/pdns_api/http.rb CHANGED
@@ -16,51 +16,75 @@
16
16
  #
17
17
 
18
18
  ##
19
- #
19
+ # Module for interaction with the PowerDNS HTTP API.
20
20
  module PDNS
21
21
  ##
22
22
  # Class for connecting to the PowerDNS API.
23
23
  class HTTP
24
24
  ##
25
- # The headers used for requests.
25
+ # @return [Hash] the headers used for requests.
26
26
  attr_accessor :headers
27
27
 
28
28
  ##
29
- # The PowerDNS API version in use.
30
- attr_reader :version
29
+ # @return [Integer] the PowerDNS API version in use.
30
+ attr_reader :version
31
31
 
32
32
  ##
33
33
  # Creates a PDNS connection.
34
34
  #
35
- # +args+ is a a hash which should include:
36
- # - +:host+: hostname or IP address of the PowerDNS server.
37
- # - +:key+: API key for the PowerDNS server.
38
- #
39
- # It may include:
40
- # - +:port+: Port the server listens on. Defaults to +8081+.
41
- # - +:version+: Version of the API to use. Defaults to +1+.
35
+ # @param args [Hash] should include:
36
+ # - +:host+: hostname or IP address of the PowerDNS server.
37
+ # - +:key+: API key for the PowerDNS server.
38
+ # It may include:
39
+ # - +:port+: Port the server listens on. Defaults to +8081+.
40
+ # - +:version+: Version of the API to use. Defaults to +1+.
41
+ # - +:scheme+: Scheme - HTTP or HTTPS. Defaults to +http+.
42
42
  # The version of the API depends on the version of PowerDNS.
43
43
  #
44
- # TODO: retrieve endpoint from +/api+ if version is not provided.
45
44
  def initialize(args)
46
45
  @host = args[:host]
47
- @key = args[:key]
46
+ @headers = { 'X-API-Key' => args[:key] }
48
47
  @port = args.key?(:port) ? args[:port] : 8081
49
- @version = args.key?(:version) ? args[:version] : 1
50
- @headers = { 'X-API-Key' => @key }
48
+ @version = args.key?(:version) ? args[:version] : api_version
49
+ @scheme = args.key?(:scheme) ? args[:scheme] : 'http'
50
+ end
51
+
52
+ ##
53
+ # Get the version of the API.
54
+ #
55
+ # @return [Integer] version of the PowerDNS API.
56
+ #
57
+ def api_version
58
+ # Do a request for the API endpoints
59
+ net = Net::HTTP::Get.new('/api', @headers)
60
+ res = http(net)
61
+
62
+ # APIv0 does not play nice.
63
+ return 0 unless res.is_a? Array
64
+
65
+ # Return the highest API version.
66
+ res.map { |a| a[:version] }.max.to_i
51
67
  end
52
68
 
53
69
  ##
54
70
  # Returns the correct URI for a request.
55
71
  # This depends on the API version.
72
+ #
73
+ # @param request [String] Requested URI.
74
+ # @return [String] Correct URI for the API version.
75
+ #
56
76
  def uri(request = '')
57
77
  base = ''
58
- base = "/api/v#{@version}" unless @version == 0 || request[0..3] == '/api'
78
+ base = "/api/v#{@version}" unless @version.zero? || request[0..3] == '/api'
59
79
  base + request
60
80
  end
61
81
 
62
82
  ##
63
83
  # Decodes the response from the server.
84
+ #
85
+ # @param response [Net::HTTPResponse] response to decode.
86
+ # @return [Hash] decoded response.
87
+ #
64
88
  def response_decode(response)
65
89
  return {} if response.body.nil?
66
90
 
@@ -74,22 +98,24 @@ module PDNS
74
98
 
75
99
  ##
76
100
  # Does an HTTP request and returns the response.
77
- # Parameters are:
78
- # - +net+: Net::HTTP method object to use in request.
79
- # - +body+: Optional body of the request.
80
- # Returns the decoded response.
101
+ #
102
+ # @param net [Net::HTTP] object to use in request.
103
+ # @param body [Hash] body of the request.
104
+ #
105
+ # @return [Hash] decoded response from server.
106
+ #
81
107
  def http(net, body = nil)
82
108
  # Debug output
83
109
  puts "#{net.method}: #{net.path}\nBody: #{body.to_json}" if ENV['DEBUG']
84
110
 
85
111
  # Start an HTTP connection
86
112
  begin
87
- response = Net::HTTP.start(@host, @port) do |http|
113
+ response = Net::HTTP.start(@host, @port, use_ssl: @scheme == 'https') do |http|
88
114
  # Do the request
89
115
  http.request(net, body.to_json)
90
116
  end
91
- rescue StandardError, Timeout::Error => e
92
- abort("Error: #{e}")
117
+ rescue StandardError => e
118
+ return { error: e.to_s }
93
119
  end
94
120
 
95
121
  response_decode(response)
@@ -97,7 +123,10 @@ module PDNS
97
123
 
98
124
  ##
99
125
  # Does an HTTP +DELETE+ request to +uri+.
100
- # Returns the decoded response.
126
+ #
127
+ # @param uri [String] URI for request.
128
+ # @return [Hash] the decoded response.
129
+ #
101
130
  def delete(uri)
102
131
  uri = uri(uri)
103
132
  net = Net::HTTP::Delete.new(uri, @headers)
@@ -106,7 +135,10 @@ module PDNS
106
135
 
107
136
  ##
108
137
  # Does an HTTP +GET+ request to +uri+.
109
- # Returns the decoded response.
138
+ #
139
+ # @param uri [String] URI for request.
140
+ # @return [Hash] the decoded response.
141
+ #
110
142
  def get(uri)
111
143
  uri = uri(uri)
112
144
  net = Net::HTTP::Get.new(uri, @headers)
@@ -115,7 +147,11 @@ module PDNS
115
147
 
116
148
  ##
117
149
  # Does an HTTP +PATCH+ request to +uri+.
118
- # Returns the decoded response.
150
+ #
151
+ # @param uri [String] URI for request.
152
+ # @param body [Hash] Body to include in request.
153
+ # @return [Hash] the decoded response.
154
+ #
119
155
  def patch(uri, body = nil)
120
156
  uri = uri(uri)
121
157
  net = Net::HTTP::Patch.new(uri, @headers)
@@ -124,7 +160,11 @@ module PDNS
124
160
 
125
161
  ##
126
162
  # Does an HTTP +POST+ request to +uri+.
127
- # Returns the decoded response.
163
+ #
164
+ # @param uri [String] URI for request.
165
+ # @param body [Hash] Body to include in request.
166
+ # @return [Hash] the decoded response.
167
+ #
128
168
  def post(uri, body = nil)
129
169
  uri = uri(uri)
130
170
  net = Net::HTTP::Post.new(uri, @headers)
@@ -133,7 +173,11 @@ module PDNS
133
173
 
134
174
  ##
135
175
  # Does an HTTP +PUT+ request to +uri+.
136
- # Returns the decoded response.
176
+ #
177
+ # @param uri [String] URI for request.
178
+ # @param body [Hash] Body to include in request.
179
+ # @return [Hash] the decoded response.
180
+ #
137
181
  def put(uri, body = nil)
138
182
  uri = uri(uri)
139
183
  net = Net::HTTP::Put.new(uri, @headers)
@@ -16,22 +16,23 @@
16
16
  #
17
17
 
18
18
  ##
19
- #
19
+ # Module for interaction with the PowerDNS HTTP API.
20
20
  module PDNS
21
21
  ##
22
22
  # Metadata for a zone.
23
23
  class Metadata < API
24
24
  ##
25
- # The kind of metadata.
25
+ # @return [name] the kind of metadata.
26
26
  attr_accessor :kind
27
27
 
28
28
  ##
29
29
  # Creates a configuration option object.
30
30
  #
31
- # - +http+: An HTTP object for interaction with the PowerDNS server.
32
- # - +parent+: This object's parent.
33
- # - +kind+: Name of the metadata.
34
- # - +value+: Optional value of the metadata.
31
+ # @param http [HTTP] An HTTP object for interaction with the PowerDNS server.
32
+ # @param parent [API] This object's parent.
33
+ # @param kind [String] Kind of the metadata.
34
+ # @param value [String] Optional value of the metadata.
35
+ #
35
36
  def initialize(http, parent, kind, value = [])
36
37
  @class = :metadata
37
38
  @http = http
@@ -45,8 +46,10 @@ module PDNS
45
46
  ##
46
47
  # Gets or sets the +value+ attribute.
47
48
  #
48
- # If +value+ is not set the current +value+ is returned.
49
- # If +value+ is set the object's +value+ is updated and +info+ is set and returned.
49
+ # @param value [String, nil] the value of the object.
50
+ # @return [String] the value of the object.
51
+ # If +value+ is set the object's +value+ is updated.
52
+ #
50
53
  def value(value = nil)
51
54
  return @info[:metadata] if value.nil?
52
55
 
@@ -54,13 +57,16 @@ module PDNS
54
57
  value = ensure_array(value)
55
58
 
56
59
  # Set value and info
57
- @value = value
58
60
  @info = { type: 'Metadata', kind: @kind, metadata: value }
61
+ @value = value
59
62
  end
60
63
 
61
64
  ##
62
65
  # Gets the current information.
63
66
  # This also updates +value+.
67
+ #
68
+ # @return [Hash] the object's information from the API.
69
+ #
64
70
  def get
65
71
  res = @http.get @url
66
72
  value(res[:value]) if res.key? :value
@@ -68,10 +74,18 @@ module PDNS
68
74
  end
69
75
 
70
76
  ##
71
- # Updates the object on the server.
77
+ # Changes this object's information on the server.
78
+ #
79
+ # @param value [String, nil] Value to change the object to.
80
+ # - If +value+ is set, the current +value+ is used.
81
+ # - If +value+ is not set, +value+ is updated and then used.
82
+ #
83
+ # @return [Hash] result of the change.
84
+ #
85
+ # @example
86
+ # metadata = zone.metadata('ALLOW-AXFR-FROM')
87
+ # metadata.change('AUTO-NS')
72
88
  #
73
- # If +value+ is set, the current +value+ is used.
74
- # If +value+ is not set, +value+ is updated and then used.
75
89
  def change(value = nil)
76
90
  value(value)
77
91
  @http.put(@url, @info)
@@ -16,22 +16,23 @@
16
16
  #
17
17
 
18
18
  ##
19
- #
19
+ # Module for interaction with the PowerDNS HTTP API.
20
20
  module PDNS
21
21
  ##
22
22
  # Override for a server.
23
23
  class Override < API
24
24
  ##
25
- # The ID of the override.
25
+ # @return [Integer] the ID of the override.
26
26
  attr_reader :id
27
27
 
28
28
  ##
29
29
  # Creates a configuration option object.
30
30
  #
31
- # - +http+: An HTTP object for interaction with the PowerDNS server.
32
- # - +parent+: This object's parent.
33
- # - +id+: ID of the override.
34
- # - +info+: Optional information of the override.
31
+ # @param http [HTTP] An HTTP object for interaction with the PowerDNS server.
32
+ # @param parent [API] This object's parent.
33
+ # @param id [Integer] ID of the override.
34
+ # @param info [Hash] Optional information of the override.
35
+ #
35
36
  def initialize(http, parent, id, info = {})
36
37
  @class = :overrides
37
38
  @http = http
@@ -20,22 +20,23 @@ require 'pdns_api/override'
20
20
  require 'pdns_api/zone'
21
21
 
22
22
  ##
23
- #
23
+ # Module for interaction with the PowerDNS HTTP API.
24
24
  module PDNS
25
25
  ##
26
26
  # Server object for accessing data for a particular server.
27
27
  class Server < API
28
28
  ##
29
- # The ID of the server.
29
+ # @return [String] the ID of the server.
30
30
  attr_reader :id
31
31
 
32
32
  ##
33
33
  # Creates a Server object.
34
34
  #
35
- # - +http+: An HTTP object for interaction with the PowerDNS server.
36
- # - +parent+: This object's parent.
37
- # - +id+: ID of the server.
38
- # - +info+: Optional information of the server.
35
+ # @param http [HTTP] An HTTP object for interaction with the PowerDNS server.
36
+ # @param parent [API] This object's parent.
37
+ # @param id [String] ID of the server.
38
+ # @param info [Hash] Optional information of the server.
39
+ #
39
40
  def initialize(http, parent, id, info = {})
40
41
  @class = :servers
41
42
  @http = http
@@ -46,13 +47,21 @@ module PDNS
46
47
  end
47
48
 
48
49
  ##
49
- # Flushes cache for +domain+.
50
- def cache(domain)
51
- # TODO: #{url}/cache/flush?domain=:domain: PUT
50
+ # Flushes cache for a domain.
51
+ #
52
+ # @param domain [String] name of the domain.
53
+ # @return [Hash] result of the action.
54
+ #
55
+ def cache_flush(domain)
56
+ @http.put("#{@url}/cache/flush?domain=#{domain}")
52
57
  end
53
58
 
54
59
  ##
55
60
  # Searches through the server's log with +search_term+.
61
+ #
62
+ # @param search_term [String] terms to search for.
63
+ # @return [Hash] result of the search.
64
+ #
56
65
  def search_log(search_term)
57
66
  # TODO: /servers/:server_id/search-log?q=:search_term: GET
58
67
  end
@@ -65,8 +74,24 @@ module PDNS
65
74
 
66
75
  ##
67
76
  # Manipulates the query tracing log.
77
+ #
78
+ # @param domain_regex [String, nil]
79
+ # Regular expression to match for domain tracing.
80
+ # Set to nil to turn off tracking.
81
+ #
82
+ # @return [Hash] Regular expression and matching log lines.
83
+ #
84
+ def trace=(domain_regex)
85
+ @http.put("#{@url}/trace", domains: domain_regex)
86
+ end
87
+
88
+ ##
89
+ # Retrieves the query tracing log.
90
+ #
91
+ # @return [Hash] Regular expression and matching log lines.
92
+ #
68
93
  def trace
69
- # TODO: /servers/:server_id/trace: GET, PUT
94
+ @http.get("#{@url}/trace")
70
95
  end
71
96
 
72
97
  ##
@@ -78,10 +103,14 @@ module PDNS
78
103
  ##
79
104
  # Returns existing configuration or creates a +Config+ object.
80
105
  #
81
- # If +name+ is not set the current configuration is returned in a hash.
106
+ # @param name [String, nil] Name of the configuration option.
107
+ # @param value [String, nil] Value op the configuration option.
108
+ #
109
+ # @return [Hash, Config] Hash containing +Config+ objects or a single +Config+ object.
110
+ # - If +name+ is not set the current configuration is returned in a hash.
111
+ # - If +name+ is set a +Config+ object is returned using the provided +name+.
112
+ # - If +value+ is set as well, a complete config object is returned.
82
113
  #
83
- # If +name+ is set a +Config+ object is returned using the provided +name+.
84
- # If +value+ is set as well, a complete config object is returned.
85
114
  def config(name = nil, value = nil)
86
115
  return Config.new(@http, self, name, value) unless name.nil? || value.nil?
87
116
  return Config.new(@http, self, name) unless name.nil?
@@ -94,10 +123,13 @@ module PDNS
94
123
  ##
95
124
  # Returns existing or creates an +Override+ object.
96
125
  #
97
- # If +id+ is not set the current servers are returned in a hash
98
- # containing +Override+ objects.
126
+ # @param id [Integer, nil] ID of the override.
127
+ #
128
+ # @return [Hash, Override] Hash containing +Override+ objects or a single +Override+ object.
129
+ # - If +id+ is not set the current servers are returned in a hash
130
+ # containing +Override+ objects.
131
+ # - If +id+ is set an +Override+ object with the provided ID is returned.
99
132
  #
100
- # If +id+ is set an +Override+ object with the provided ID is returned.
101
133
  def overrides(id = nil)
102
134
  return Override.new(@http, self, id) unless id.nil?
103
135
 
@@ -108,10 +140,13 @@ module PDNS
108
140
  ##
109
141
  # Returns existing or creates a +Zone+ object.
110
142
  #
111
- # If +id+ is not set the current servers are returned in a hash
112
- # containing +Zone+ objects.
143
+ # @param id [String, nil] ID of the override.
144
+ #
145
+ # @return [Hash, Zone] Hash containing +Zone+ objects or a single +Zone+ object.
146
+ # - If +id+ is not set the current servers are returned in a hash
147
+ # containing +Zone+ objects.
148
+ # - If +id+ is set a +Server+ object with the provided ID is returned.
113
149
  #
114
- # If +id+ is set a +Server+ object with the provided ID is returned.
115
150
  def zones(id = nil)
116
151
  return Zone.new(@http, self, id) unless id.nil?
117
152
 
@@ -16,9 +16,9 @@
16
16
  #
17
17
 
18
18
  ##
19
- #
19
+ # Module for interaction with the PowerDNS HTTP API.
20
20
  module PDNS
21
21
  ##
22
22
  # The version of +pdns_api+.
23
- VERSION = '0.1.2'.freeze
23
+ VERSION = '0.1.3'.freeze
24
24
  end
data/lib/pdns_api/zone.rb CHANGED
@@ -19,22 +19,23 @@ require 'pdns_api/metadata'
19
19
  require 'pdns_api/cryptokey'
20
20
 
21
21
  ##
22
- #
22
+ # Module for interaction with the PowerDNS HTTP API.
23
23
  module PDNS
24
24
  ##
25
25
  # Zone on a server.
26
26
  class Zone < API
27
27
  ##
28
- # The ID of the zone.
28
+ # @return [String] the ID of the zone.
29
29
  attr_reader :id
30
30
 
31
31
  ##
32
32
  # Creates a Zone object.
33
33
  #
34
- # - +http+: An HTTP object for interaction with the PowerDNS server.
35
- # - +parent+: This object's parent.
36
- # - +id+: ID of the zone.
37
- # - +info+: Optional information of the zone.
34
+ # @param http [HTTP] An HTTP object for interaction with the PowerDNS server.
35
+ # @param parent [API] This object's parent.
36
+ # @param id [String] ID of the zone.
37
+ # @param info [Hash] Optional information of the zone.
38
+ #
38
39
  def initialize(http, parent, id, info = {})
39
40
  @class = :zones
40
41
  @http = http
@@ -48,12 +49,17 @@ module PDNS
48
49
  # Modifies information (records) of a zone.
49
50
  # Also formats records to match the API requirements.
50
51
  #
51
- # Example:
52
+ # @param rrsets [Array] Changeset to send to the PowerDNS API.
53
+ #
54
+ # @return [Hash] result of the changeset.
55
+ #
56
+ # @example
52
57
  # zone.modify([
53
58
  # changetype: 'DELETE',
54
59
  # name: 'www.example.com.',
55
60
  # type: 'A'
56
61
  # ])
62
+ #
57
63
  def modify(rrsets)
58
64
  rrsets.map! do |rrset|
59
65
  rrset = format_records(rrset) if rrset.key?(:records)
@@ -66,7 +72,7 @@ module PDNS
66
72
  ##
67
73
  # Notifies slaves for a zone.
68
74
  # Only works for domains for which the server is a master.
69
- # Returns the result of the notification.
75
+ # @return [Hash] the result of the notification.
70
76
  def notify
71
77
  @http.put "#{@url}/notify"
72
78
  end
@@ -74,14 +80,14 @@ module PDNS
74
80
  ##
75
81
  # Retrieves the data for a zone.
76
82
  # Only works for domains for which the server is a slave.
77
- # Returns the result of the retrieval.
83
+ # @return [Hash] the result of the retrieval.
78
84
  def axfr_retrieve
79
85
  @http.put "#{@url}/axfr-retrieve"
80
86
  end
81
87
 
82
88
  ##
83
89
  # Exports the zone as a bind zone file.
84
- # Returns a hash containing the zone in +:result+.
90
+ # @return [Hash] containing the Bind formatted zone in +:result+.
85
91
  def export
86
92
  data = @http.get "#{@url}/export"
87
93
  data.delete(:error) if data[:error] == 'Non-JSON response'
@@ -90,7 +96,7 @@ module PDNS
90
96
 
91
97
  ##
92
98
  # Checks the zone for errors.
93
- # Returns the result of the check.
99
+ # @return [Hash] the result of the check.
94
100
  def check
95
101
  @http.get "#{@url}/check"
96
102
  end
@@ -105,7 +111,11 @@ module PDNS
105
111
  # - An +Array+ containing record values.
106
112
  # - An +Array+ containing hashes as specified in the PowerDNS API.
107
113
  #
108
- # Example:
114
+ # @param rrsets [Array<Object>] Array of Hashes containing records to replace.
115
+ #
116
+ # @return [Hash] Hash containing result of the operation.
117
+ #
118
+ # @example
109
119
  # zone.add({
110
120
  # name: 'www0.example.com.',
111
121
  # type: 'A',
@@ -146,14 +156,16 @@ module PDNS
146
156
  ##
147
157
  # Updates (replaces) records for a name/type combination in the zone.
148
158
  #
149
- # +rrsets+ is used to create a changeset.
150
- #
151
159
  # Elements of +rrsets+ can contain +:records+, which can be:
152
160
  # - A +String+ containing a single record value.
153
161
  # - An +Array+ containing record values.
154
162
  # - An +Array+ containing hashes as specified in the PowerDNS API.
155
163
  #
156
- # Example:
164
+ # @param rrsets [Array<Object>] Array of Hashes containing records to replace.
165
+ #
166
+ # @return [Hash] Hash containing result of the operation.
167
+ #
168
+ # @example
157
169
  # zone.update({
158
170
  # name: 'www0.example.com.',
159
171
  # type: 'A',
@@ -184,7 +196,12 @@ module PDNS
184
196
  ##
185
197
  # Removes all records for a name/type combination from the zone.
186
198
  #
187
- # Example:
199
+ # @param rrsets [Array<Object>] Array of Hashes to delete.
200
+ # The Hash(es) in the Array should contain +:name+ and +:type+.
201
+ #
202
+ # @return [Hash] Hash containing result of the operation.
203
+ #
204
+ # @example
188
205
  # zone.remove({
189
206
  # name: 'www0.example.com.',
190
207
  # type: 'A'
@@ -205,12 +222,15 @@ module PDNS
205
222
  ##
206
223
  # Returns existing metadata or creates a +Metadata+ object.
207
224
  #
208
- # If +kind+ is not set the current metadata is returned in a hash.
225
+ # @param kind [String, nil] The kind of metadata.
226
+ # @param value [String, nil] The value of the metadata.
209
227
  #
210
- # If +kind+ is set a +Metadata+ object is returned using the provided +kind+.
211
- # If +value+ is set as well, a complete Metadata object is returned.
228
+ # @return [Metadata, Hash] Hash containing all metadata, or single +Metadata+ object.
229
+ # - If +kind+ is not set the current metadata is returned in a +Hash+.
230
+ # - If +kind+ is set a +Metadata+ object is returned using the provided +kind+.
231
+ # - If +value+ is set as well, a complete Metadata object is returned.
212
232
  #
213
- # Example:
233
+ # @example
214
234
  # # Retrieve all metadata in a hash
215
235
  # zone.metadata
216
236
  # # Create a metadata object
@@ -237,14 +257,21 @@ module PDNS
237
257
  ##
238
258
  # Returns existing or creates a +CryptoKey+ object.
239
259
  #
240
- # If +id+ is not set the current servers are returned in a hash
241
- # containing +CryptoKey+ objects.
242
260
  #
243
- # If +id+ is set a +CryptoKey+ object with the provided ID is returned.
244
261
  #
245
- # Example:
262
+ #
263
+ #
264
+ # @param id [Integer, nil] ID of a +CryptoKey+.
265
+ #
266
+ # @return [Hash, CryptoKey] Hash of +CryptoKeys+ or a single +CryptoKey+.
267
+ # - If +id+ is not set the current servers are returned in a hash
268
+ # containing +CryptoKey+ objects.
269
+ # - If +id+ is set a +CryptoKey+ object with the provided ID is returned.
270
+ #
271
+ # @example
246
272
  # ckeys = zone.cryptokeys
247
273
  # ckey = zone.cryptokey(12)
274
+ #
248
275
  def cryptokeys(id = nil)
249
276
  return CryptoKey.new(@http, self, id) unless id.nil?
250
277
 
@@ -259,6 +286,10 @@ module PDNS
259
286
 
260
287
  ##
261
288
  # Formats a single record to match what is required by the API.
289
+ #
290
+ # @param record [String, Hash] Record to format.
291
+ # @return [Hash] Formatted record.
292
+ #
262
293
  def format_single_record(record)
263
294
  # Ensure content
264
295
  record = { content: record } if record.is_a? String
@@ -274,6 +305,9 @@ module PDNS
274
305
 
275
306
  ##
276
307
  # Format the records in an RRset te match what is required by the API.
308
+ # @param rrset [Hash] RRset of which to format the records.
309
+ # @return [Hash] Formatted RRset.
310
+ #
277
311
  def format_records(rrset)
278
312
  # Ensure existence of required keys
279
313
  rrset[:records].map! do |record|
@@ -284,7 +318,7 @@ module PDNS
284
318
  record[:disabled] ||= !!rrset[:disabled]
285
319
 
286
320
  # Return record
287
- next record unless @http.version == 0
321
+ next record unless @http.version.zero?
288
322
 
289
323
  # But add some more for APIv0
290
324
  record.merge(name: rrset[:name], type: rrset[:type], ttl: rrset[:ttl])
@@ -294,8 +328,12 @@ module PDNS
294
328
 
295
329
  ##
296
330
  # Returns the records matching the ones in +rrset+ from +data+.
297
- # +data+ should be the result from +get+.
298
- def current_records(rrset, data)
331
+ #
332
+ # @param rrset [Hash] RRset to match current records with.
333
+ # @param data [Hash] RRsets currently on the server. Should be the result from +get+.
334
+ # @return [Array] Currently existing records.
335
+ #
336
+ def current_records(rrset, data) # rubocop:disable Metrics/AbcSize
299
337
  # Get the records from the data, `records` is v0, `rrsets` is v1
300
338
  records = data[:records] || data[:rrsets]
301
339
 
@@ -303,12 +341,12 @@ module PDNS
303
341
  current = records.select { |r| r[:name] == rrset[:name] && r[:type] == rrset[:type] }
304
342
 
305
343
  # Get only content/disabled for API v0
306
- if @http.version == 0
307
- current.map! { |record| { content: record[:content], disabled: record[:disabled] } }
344
+ if @http.version.zero?
345
+ current.map! { |record| { content: record[:content], disabled: record[:disabled] } }
308
346
  end
309
347
 
310
348
  # For API v1 there is only one element containing all records
311
- current = current.first[:records] unless @http.version == 0
349
+ current = current.first[:records] unless current.empty? || @http.version.zero?
312
350
 
313
351
  # Return the records
314
352
  current
data/lib/pdns_api.rb CHANGED
@@ -28,6 +28,10 @@ module PDNS
28
28
  class << self
29
29
  ##
30
30
  # Create a PDNS::Client object.
31
+ #
32
+ # @param args [Hash] arguments used to create a +Client+ object.
33
+ # @return [Client] a client object to communicate to the API.
34
+ #
31
35
  def new(args)
32
36
  Client.new(args)
33
37
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: pdns_api
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.2
4
+ version: 0.1.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Silke Hofstra
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2016-05-31 00:00:00.000000000 Z
11
+ date: 2018-09-04 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: A gem for manipulation of DNS through the PowerDNS API
14
14
  email: silke.ruby@slxh.nl
@@ -29,7 +29,7 @@ files:
29
29
  - lib/pdns_api/zone.rb
30
30
  homepage: https://github.com/silkeh/ruby-pdns_api
31
31
  licenses:
32
- - EUPL
32
+ - EUPL-1.1
33
33
  metadata: {}
34
34
  post_install_message:
35
35
  rdoc_options: []
@@ -47,7 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
47
47
  version: '0'
48
48
  requirements: []
49
49
  rubyforge_project:
50
- rubygems_version: 2.2.2
50
+ rubygems_version: 2.7.6
51
51
  signing_key:
52
52
  specification_version: 4
53
53
  summary: PowerDNS API gem