dockerapi 0.14.0 → 0.19.0

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.
@@ -1,17 +1,33 @@
1
1
  module Docker
2
2
  module API
3
+
4
+ ##
5
+ # This class represents a validation error.
3
6
  class ValidationError < StandardError
7
+
8
+ ##
9
+ # @params permitted [Array]: permitted values.
10
+ # @params unpermitted [Array]: unpermitted values.
4
11
  def initialize permitted, unpermitted
5
12
  super("Unpermitted options found: #{unpermitted.to_s}. Permitted are #{permitted.to_s}")
6
13
  end
7
14
  end
15
+
16
+ ##
17
+ # This class represents a parameter validation error.
18
+ class InvalidParameter < Docker::API::ValidationError; end
19
+
20
+ ##
21
+ # This class represents a request body validation error.
22
+ class InvalidRequestBody < Docker::API::ValidationError; end
23
+
24
+ ##
25
+ # This class represents a generic error.
8
26
  class Error < StandardError
9
27
  def initialize msg = "Error without specific message"
10
28
  super(msg)
11
29
  end
12
30
  end
13
-
14
- class InvalidParameter < Docker::API::ValidationError; end
15
- class InvalidRequestBody < Docker::API::ValidationError; end
31
+
16
32
  end
17
33
  end
@@ -1,42 +1,55 @@
1
- module Docker
2
- module API
3
- class Exec < Docker::API::Base
1
+ ##
2
+ # This class represents the Docker API exec related endpoints.
3
+ # @see https://docs.docker.com/engine/api/v1.40/#tag/Exec
4
+ class Docker::API::Exec < Docker::API::Base
4
5
 
5
- def create name, body = {}
6
- @connection.request(method: :post, path: "/containers/#{name}/exec", headers: {"Content-Type": "application/json"}, body: body.to_json )
7
- end
8
-
9
- def start name, body = {}
10
- stream = ""
11
- response = @connection.request(method: :post,
12
- path: "/exec/#{name}/start",
13
- headers: {"Content-Type": "application/json"},
14
- body: body.to_json,
15
- response_block: lambda { |chunk, remaining_bytes, total_bytes| stream += chunk.to_s.encode('UTF-8', invalid: :replace, undef: :replace, replace: '?') }
16
- )
17
- response.data.merge!({stream: stream})
18
- response
19
- end
6
+ ##
7
+ # Run a command inside a running container.
8
+ #
9
+ # Docker API: POST /containers/{id}/exec
10
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/ContainerExec
11
+ #
12
+ # @param name [String]: The ID or name of the container.
13
+ # @param body [Hash]: Request body to be sent as json.
14
+ def create name, body = {}
15
+ @connection.request(method: :post, path: "/containers/#{name}/exec", headers: {"Content-Type": "application/json"}, body: body.to_json )
16
+ end
20
17
 
21
- def resize name, params = {}
22
- @connection.post(build_path("/exec/#{name}/resize", params))
23
- end
18
+ ##
19
+ # Start a previously set up exec instance.
20
+ #
21
+ # Docker API: POST /exec/{id}/start
22
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/ExecStart
23
+ #
24
+ # @param name [String]: Exec instance ID.
25
+ # @param body [Hash]: Request body to be sent as json.
26
+ # @param &block: Replace the default output to stdout behavior.
27
+ def start name, body = {}, &block
28
+ @connection.request(method: :post, path: "/exec/#{name}/start", headers: {"Content-Type": "application/json"}, body: body.to_json,
29
+ response_block: block_given? ? block : default_streamer )
30
+ end
24
31
 
25
- def details name
26
- @connection.get("/exec/#{name}/json")
27
- end
28
-
29
- #################################################
30
- # Items in this area to be removed before 1.0.0 #
31
- #################################################
32
- def inspect *args
33
- return super.inspect if args.size == 0
34
- warn "WARNING: #inspect is deprecated and will be removed in the future, please use #details instead."
35
- name = args[0]
36
- details(name)
37
- end
38
- #################################################
32
+ ##
33
+ # Resize the TTY session used by an exec instance.
34
+ #
35
+ # Docker API: POST /exec/{id}/resize
36
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/ExecResize
37
+ #
38
+ # @param name [String]: Exec instance ID.
39
+ # @param body [Hash]: Request body to be sent as json.
40
+ def resize name, params = {}
41
+ @connection.post(build_path("/exec/#{name}/resize", params))
42
+ end
39
43
 
40
- end
44
+ ##
45
+ # Return low-level information about an exec instance.
46
+ #
47
+ # Docker API: GET /exec/{id}/json
48
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/ExecInspect
49
+ #
50
+ # @param name [String]: Exec instance ID.
51
+ def details name
52
+ @connection.get("/exec/#{name}/json")
41
53
  end
54
+
42
55
  end
@@ -21,8 +21,11 @@ class Docker::API::Image < Docker::API::Base
21
21
  # @see https://docs.docker.com/engine/api/v1.40/#tag/Distribution
22
22
  #
23
23
  # @param name [String]: The ID or name of the image.
24
- def distribution name
25
- @connection.get("/distribution/#{name}/json")
24
+ # @param authentication [Hash]: Authentication parameters.
25
+ def distribution name, authentication = {}
26
+ request = {method: :get, path: "/distribution/#{name}/json"}
27
+ request[:headers] = {"X-Registry-Auth" => auth_encoder(authentication)} if authentication.any?
28
+ @connection.request(request)
26
29
  end
27
30
 
28
31
  ##
@@ -37,7 +40,7 @@ class Docker::API::Image < Docker::API::Base
37
40
  end
38
41
 
39
42
  ##
40
- # Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.
43
+ # Return a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.
41
44
  #
42
45
  # Docker API: GET /images/json
43
46
  # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageList
@@ -105,7 +108,7 @@ class Docker::API::Image < Docker::API::Base
105
108
  # @param path [String]: Path to the exported file.
106
109
  # @param &block: Replace the default file writing behavior.
107
110
  def export name, path, &block
108
- @connection.request(method: :get, path: build_path("/images/#{name}/get") , response_block: block_given? ? block.call : default_writer(path))
111
+ @connection.request(method: :get, path: build_path("/images/#{name}/get") , response_block: block_given? ? block : default_writer(path))
109
112
  end
110
113
 
111
114
  ##
@@ -130,8 +133,8 @@ class Docker::API::Image < Docker::API::Base
130
133
  # @param params [Hash]: Parameters that are appended to the URL.
131
134
  # @param authentication [Hash]: Authentication parameters.
132
135
  def push name, params = {}, authentication = {}
133
- raise Docker::API::Error.new("Provide authentication parameters to push an image") unless authentication.keys.size > 0
134
- @connection.request(method: :post, path: build_path("/images/#{name}/push", params), headers: { "X-Registry-Auth" => Base64.urlsafe_encode64(authentication.to_json.to_s).chomp } )
136
+ raise Docker::API::Error.new("Provide authentication parameters to push an image") unless authentication.any?
137
+ @connection.request(method: :post, path: build_path("/images/#{name}/push", params), headers: { "X-Registry-Auth" => auth_encoder(authentication) } )
135
138
  end
136
139
 
137
140
  ##
@@ -158,13 +161,13 @@ class Docker::API::Image < Docker::API::Base
158
161
  # @param authentication [Hash]: Authentication parameters.
159
162
  # @param &block: Replace the default output to stdout behavior.
160
163
  def create params = {}, authentication = {}, &block
161
- request = {method: :post, path: build_path("/images/create", params), response_block: block_given? ? block.call : default_streamer }
164
+ request = {method: :post, path: build_path("/images/create", params), response_block: block_given? ? block : default_streamer }
162
165
  if params.has_key? :fromSrc and !params[:fromSrc].match(/^(http|https)/) # then it's using a tar file
163
166
  path = params[:fromSrc]
164
167
  params[:fromSrc] = "-"
165
168
  default_reader(path, build_path("/images/create", params))
166
169
  else
167
- request[:headers] = { "X-Registry-Auth" => Base64.encode64(authentication.to_json.to_s).chomp } if authentication.keys.size > 0
170
+ request[:headers] = { "X-Registry-Auth" => auth_encoder(authentication) } if authentication.any?
168
171
  @connection.request(request)
169
172
  end
170
173
  end
@@ -183,10 +186,10 @@ class Docker::API::Image < Docker::API::Base
183
186
  raise Docker::API::Error.new("Expected path or params[:remote]") unless path || params[:remote]
184
187
 
185
188
  headers = {"Content-type": "application/x-tar"}
186
- headers.merge!({"X-Registry-Config": Base64.urlsafe_encode64(authentication.to_json.to_s).chomp}) if authentication.keys.size > 0
189
+ headers.merge!({"X-Registry-Config": auth_encoder(authentication) }) if authentication.any?
187
190
 
188
191
  if path == nil and params.has_key? :remote
189
- response = @connection.request(method: :post, path: build_path("/build", params), headers: headers, response_block: block_given? ? block.call : default_streamer)
192
+ response = @connection.request(method: :post, path: build_path("/build", params), headers: headers, response_block: block_given? ? block : default_streamer)
190
193
  else
191
194
  default_reader(path, build_path("/build", params), headers)
192
195
  end
@@ -1,50 +1,86 @@
1
- module Docker
2
- module API
3
- class Network < Docker::API::Base
4
-
5
- def list params = {}
6
- @connection.get(build_path("/networks", params))
7
- end
8
-
9
- def details name, params = {}
10
- @connection.get(build_path([name], params))
11
- end
12
-
13
- def create body = {}
14
- @connection.request(method: :post, path: build_path(["create"]), headers: {"Content-Type": "application/json"}, body: body.to_json)
15
- end
16
-
17
- def remove name
18
- @connection.delete(build_path([name]))
19
- end
20
-
21
- def prune params = {}
22
- @connection.post(build_path(["prune"], params))
23
- end
24
-
25
- def connect name, body = {}
26
- @connection.request(method: :post, path: build_path([name, "connect"]), headers: {"Content-Type": "application/json"}, body: body.to_json)
27
- end
28
-
29
- def disconnect name, body = {}
30
- @connection.request(method: :post, path: build_path([name, "disconnect"]), headers: {"Content-Type": "application/json"}, body: body.to_json)
31
- end
32
-
33
- #################################################
34
- # Items in this area to be removed before 1.0.0 #
35
- #################################################
36
- def base_path
37
- "/networks"
38
- end
39
-
40
- def inspect *args
41
- return super.inspect if args.size == 0
42
- warn "WARNING: #inspect is deprecated and will be removed in the future, please use #details instead."
43
- name, params = args[0], args[1] || {}
44
- details(name, params)
45
- end
46
- #################################################
47
-
48
- end
1
+ ##
2
+ # This class represents the Docker API endpoints regarding networks.
3
+ # @see https://docs.docker.com/engine/api/v1.40/#tag/Network
4
+ class Docker::API::Network < Docker::API::Base
5
+
6
+ ##
7
+ # List networks.
8
+ #
9
+ # Docker API: GET /networks
10
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkList
11
+ #
12
+ # @param params [Hash]: Parameters that are appended to the URL.
13
+ def list params = {}
14
+ @connection.get(build_path("/networks", params))
15
+ end
16
+
17
+ ##
18
+ # Inspect a network.
19
+ #
20
+ # Docker API: GET /networks/{id}
21
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkInspect
22
+ #
23
+ # @param name [String]: The ID or name of the network.
24
+ # @param params [Hash]: Parameters that are appended to the URL.
25
+ def details name, params = {}
26
+ @connection.get(build_path("/networks/#{name}", params))
27
+ end
28
+
29
+ ##
30
+ # Create a network.
31
+ #
32
+ # Docker API: POST /networks/create
33
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkCreate
34
+ #
35
+ # @param body [Hash]: Request body to be sent as json.
36
+ def create body = {}
37
+ @connection.request(method: :post, path: "/networks/create", headers: {"Content-Type": "application/json"}, body: body.to_json)
38
+ end
39
+
40
+ ##
41
+ # Remove a network.
42
+ #
43
+ # Docker API: DELETE /networks/{id}
44
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkDelete
45
+ #
46
+ # @param name [String]: The ID or name of the network.
47
+ def remove name
48
+ @connection.delete("/networks/#{name}")
49
49
  end
50
+
51
+ ##
52
+ # Delete unused networks.
53
+ #
54
+ # Docker API: POST /networks/prune
55
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkPrune
56
+ #
57
+ # @param params [Hash]: Parameters that are appended to the URL.
58
+ def prune params = {}
59
+ @connection.post(build_path("/networks/prune", params))
60
+ end
61
+
62
+ ##
63
+ # Connect a container to a network.
64
+ #
65
+ # Docker API: POST /networks/{id}/connect
66
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkConnect
67
+ #
68
+ # @param name [String]: The ID or name of the network.
69
+ # @param body [Hash]: Request body to be sent as json.
70
+ def connect name, body = {}
71
+ @connection.request(method: :post, path: "/networks/#{name}/connect", headers: {"Content-Type": "application/json"}, body: body.to_json)
72
+ end
73
+
74
+ ##
75
+ # Disconnect a container from a network.
76
+ #
77
+ # Docker API: POST /networks/{id}/disconnect
78
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkDisconnect
79
+ #
80
+ # @param name [String]: The ID or name of the network.
81
+ # @param body [Hash]: Request body to be sent as json.
82
+ def disconnect name, body = {}
83
+ @connection.request(method: :post, path: "/networks/#{name}/disconnect", headers: {"Content-Type": "application/json"}, body: body.to_json)
84
+ end
85
+
50
86
  end
@@ -1,34 +1,53 @@
1
- module Docker
2
- module API
3
- class Node < Docker::API::Base
1
+ # This class represents the Docker API endpoints regarding nodes.
2
+ #
3
+ # Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
4
+ # @see https://docs.docker.com/engine/api/v1.40/#tag/Node
5
+ class Docker::API::Node < Docker::API::Base
4
6
 
5
- def list params = {}
6
- @connection.get(build_path("/nodes", params))
7
- end
8
-
9
- def update name, params = {}, body = {}
10
- @connection.request(method: :post, path: build_path("nodes/#{name}/update", params), headers: {"Content-Type": "application/json"}, body: body.to_json)
11
- end
12
-
13
- def delete name, params = {}
14
- @connection.delete(build_path("/nodes/#{name}", params))
15
- end
7
+ ##
8
+ # List nodes.
9
+ #
10
+ # Docker API: GET /nodes
11
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/NodeList
12
+ #
13
+ # @param params [Hash]: Parameters that are appended to the URL.
14
+ def list params = {}
15
+ @connection.get(build_path("/nodes", params))
16
+ end
16
17
 
17
- def details name
18
- @connection.get("/nodes/#{name}")
19
- end
18
+ ##
19
+ # Update a node.
20
+ #
21
+ # Docker API: POST /nodes/{id}/update
22
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/NodeUpdate
23
+ #
24
+ # @param name [String]: The ID or name of the node.
25
+ # @param params [Hash]: Parameters that are appended to the URL.
26
+ # @param body [Hash]: Request body to be sent as json.
27
+ def update name, params = {}, body = {}
28
+ @connection.request(method: :post, path: build_path("nodes/#{name}/update", params), headers: {"Content-Type": "application/json"}, body: body.to_json)
29
+ end
20
30
 
21
- #################################################
22
- # Items in this area to be removed before 1.0.0 #
23
- #################################################
24
- def inspect *args
25
- return super.inspect if args.size == 0
26
- warn "WARNING: #inspect is deprecated and will be removed in the future, please use #details instead."
27
- name = args[0]
28
- details(name)
29
- end
30
- #################################################
31
+ ##
32
+ # Delete a node.
33
+ #
34
+ # Docker API: DELETE /nodes/{id}
35
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/NodeDelete
36
+ #
37
+ # @param name [String]: The ID or name of the node.
38
+ # @param params [Hash]: Parameters that are appended to the URL.
39
+ def delete name, params = {}
40
+ @connection.delete(build_path("/nodes/#{name}", params))
41
+ end
31
42
 
32
- end
43
+ ##
44
+ # Inspect a node.
45
+ #
46
+ # Docker API: GET /nodes/{id}
47
+ # @see https://docs.docker.com/engine/api/v1.40/#operation/NodeInspect
48
+ #
49
+ # @param name [String]: The ID or name of the node.
50
+ def details name
51
+ @connection.get("/nodes/#{name}")
33
52
  end
34
53
  end
@@ -1,25 +1,33 @@
1
- module Docker
2
- module API
3
- class Response < Excon::Response
4
- attr_reader(:json, :path)
1
+ ##
2
+ # Reponse class.
3
+ class Docker::API::Response < Excon::Response
4
+ attr_reader(:json, :path)
5
5
 
6
- def initialize data
7
- super data
8
- @json = parse_json @body
9
- @path = @data[:path]
10
- end
6
+ ##
7
+ # Initialize a new Response object.
8
+ #
9
+ # @params data [Object]: Reponse's data.
10
+ def initialize data
11
+ super data
12
+ @json = parse_json @body
13
+ @path = @data[:path]
14
+ end
11
15
 
12
- def success?
13
- (200..204).include? @status
14
- end
16
+ ##
17
+ # Return true if Response status is in 200..204 range.
18
+ def success?
19
+ (200..204).include? @status
20
+ end
15
21
 
16
- private
22
+ private
17
23
 
18
- def parse_json data
19
- return nil unless headers["Content-Type"] == "application/json"
20
- return nil if data == ""
21
- data.split("\r\n").size > 1 ? data.split("\r\n").map{ |e| eval(e) } : JSON.parse(data)
22
- end
23
- end
24
+ ##
25
+ # Create a json from Response data attribute.
26
+ #
27
+ # @params data [String]: String to be converted in json.
28
+ def parse_json data
29
+ return nil unless headers["Content-Type"] == "application/json"
30
+ return nil if data == ""
31
+ data.split("\r\n").size > 1 ? data.split("\r\n").map{ |e| eval(e) } : JSON.parse(data)
24
32
  end
25
33
  end