Debian Codegraph @

troveclient/apiclient/client.py

raw
1 # Copyright 2010 Jacob Kaplan-Moss
2 # Copyright 2011 OpenStack Foundation
3 # Copyright 2011 Piston Cloud Computing, Inc.
4 # Copyright 2013 Alessio Ababilov
5 # Copyright 2013 Grid Dynamics
6 # Copyright 2013 OpenStack Foundation
7 # All Rights Reserved.
8 #
9 # Licensed under the Apache License, Version 2.0 (the "License"); you may
10 # not use this file except in compliance with the License. You may obtain
11 # a copy of the License at
12 #
13 # http://www.apache.org/licenses/LICENSE-2.0
14 #
15 # Unless required by applicable law or agreed to in writing, software
16 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
17 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
18 # License for the specific language governing permissions and limitations
19 # under the License.
20
21 """
22 OpenStack Client interface. Handles the REST calls and responses.
23 """
24
25 # E0202: An attribute inherited from %s hide this method
26 # pylint: disable=E0202
27
28 import json
29 import logging
30 import time
31
32 import requests
33
34 from oslo_utils import importutils
35 from troveclient.apiclient import exceptions
36
37
38 LOG = logging.getLogger(__name__)
39
40
41 class HTTPClient(object):
42 """This client handles sending HTTP requests to OpenStack servers.
43
44 Features:
45
46 - share authentication information between several clients to different
47 services (e.g., for compute and image clients);
48 - reissue authentication request for expired tokens;
49 - encode/decode JSON bodies;
50 - raise exceptions on HTTP errors;
51 - pluggable authentication;
52 - store authentication information in a keyring;
53 - store time spent for requests;
54 - register clients for particular services, so one can use
55 `http_client.identity` or `http_client.compute`;
56 - log requests and responses in a format that is easy to copy-and-paste
57 into terminal and send the same request with curl.
58
59 """
60
61 user_agent = "troveclient.apiclient"
62
63 def __init__(self,
64 auth_plugin,
65 region_name=None,
66 endpoint_type="publicURL",
67 original_ip=None,
68 verify=True,
69 cert=None,
70 timeout=None,
71 timings=False,
72 keyring_saver=None,
73 debug=False,
74 user_agent=None,
75 http=None):
76 self.auth_plugin = auth_plugin
77
78 self.endpoint_type = endpoint_type
79 self.region_name = region_name
80
81 self.original_ip = original_ip
82 self.timeout = timeout
83 self.verify = verify
84 self.cert = cert
85
86 self.keyring_saver = keyring_saver
87 self.debug = debug
88 self.user_agent = user_agent or self.user_agent
89
90 self.times = [] # [("item", starttime, endtime), ...]
91 self.timings = timings
92
93 # requests within the same session can reuse TCP connections from pool
94 self.http = http or requests.Session()
95
96 self.cached_token = None
97
98 def _http_log_req(self, method, url, kwargs):
99 if not self.debug:
100 return
101
102 string_parts = [
103 "curl -i",
104 "-X '%s'" % method,
105 "'%s'" % url,
106 ]
107
108 for element in kwargs['headers']:
109 header = "-H '%s: %s'" % (element, kwargs['headers'][element])
110 string_parts.append(header)
111
112 LOG.debug("REQ: %s", " ".join(string_parts))
113 if 'data' in kwargs:
114 LOG.debug("REQ BODY: %s\n", kwargs['data'])
115
116 def _http_log_resp(self, resp):
117 if not self.debug:
118 return
119 LOG.debug(
120 "RESP: [%s] %s\n",
121 resp.status_code,
122 resp.headers)
123 if resp._content_consumed:
124 LOG.debug(
125 "RESP BODY: %s\n",
126 resp.text)
127
128 def serialize(self, kwargs):
129 if kwargs.get('json') is not None:
130 kwargs['headers']['Content-Type'] = 'application/json'
131 kwargs['data'] = json.dumps(kwargs['json'])
132 try:
133 del kwargs['json']
134 except KeyError:
135 pass
136
137 def get_timings(self):
138 return self.times
139
140 def reset_timings(self):
141 self.times = []
142
143 def request(self, method, url, **kwargs):
144 """Send an http request with the specified characteristics.
145
146 Wrapper around `requests.Session.request` to handle tasks such as
147 setting headers, JSON encoding/decoding, and error handling.
148
149 :param method: method of HTTP request
150 :param url: URL of HTTP request
151 :param kwargs: any other parameter that can be passed to
152 requests.Session.request (such as `headers`) or `json`
153 that will be encoded as JSON and used as `data` argument
154 """
155 kwargs.setdefault("headers", kwargs.get("headers", {}))
156 kwargs["headers"]["User-Agent"] = self.user_agent
157 if self.original_ip:
158 kwargs["headers"]["Forwarded"] = "for=%s;by=%s" % (
159 self.original_ip, self.user_agent)
160 if self.timeout is not None:
161 kwargs.setdefault("timeout", self.timeout)
162 kwargs.setdefault("verify", self.verify)
163 if self.cert is not None:
164 kwargs.setdefault("cert", self.cert)
165 self.serialize(kwargs)
166
167 self._http_log_req(method, url, kwargs)
168 if self.timings:
169 start_time = time.time()
170 resp = self.http.request(method, url, **kwargs)
171 if self.timings:
172 self.times.append(("%s %s" % (method, url),
173 start_time, time.time()))
174 self._http_log_resp(resp)
175
176 if resp.status_code >= 400:
177 LOG.debug(
178 "Request returned failure status: %s",
179 resp.status_code)
180 raise exceptions.from_response(resp, method, url)
181
182 return resp
183
184 @staticmethod
185 def concat_url(endpoint, url):
186 """Concatenate endpoint and final URL.
187
188 E.g., "http://keystone/v2.0/" and "/tokens" are concatenated to
189 "http://keystone/v2.0/tokens".
190
191 :param endpoint: the base URL
192 :param url: the final URL
193 """
194 return "%s/%s" % (endpoint.rstrip("/"), url.strip("/"))
195
196 def client_request(self, client, method, url, **kwargs):
197 """Send an http request using `client`'s endpoint and specified `url`.
198
199 If request was rejected as unauthorized (possibly because the token is
200 expired), issue one authorization attempt and send the request once
201 again.
202
203 :param client: instance of BaseClient descendant
204 :param method: method of HTTP request
205 :param url: URL of HTTP request
206 :param kwargs: any other parameter that can be passed to
207 `HTTPClient.request`
208
209 """
210
211 filter_args = {
212 "endpoint_type": client.endpoint_type or self.endpoint_type,
213 "service_type": client.service_type,
214 }
215 token, endpoint = (self.cached_token, client.cached_endpoint)
216 just_authenticated = False
217 if not (token and endpoint):
218 try:
219 token, endpoint = self.auth_plugin.token_and_endpoint(
220 **filter_args)
221 except exceptions.EndpointException:
222 pass
223 if not (token and endpoint):
224 self.authenticate()
225 just_authenticated = True
226 token, endpoint = self.auth_plugin.token_and_endpoint(
227 **filter_args)
228 if not (token and endpoint):
229 raise exceptions.AuthorizationFailure(
230 "Cannot find endpoint or token for request")
231
232 old_token_endpoint = (token, endpoint)
233 kwargs.setdefault("headers", {})["X-Auth-Token"] = token
234 self.cached_token = token
235 client.cached_endpoint = endpoint
236 # Perform the request once. If we get Unauthorized, then it
237 # might be because the auth token expired, so try to
238 # re-authenticate and try again. If it still fails, bail.
239 try:
240 return self.request(
241 method, self.concat_url(endpoint, url), **kwargs)
242 except exceptions.Unauthorized as unauth_ex:
243 if just_authenticated:
244 raise
245 self.cached_token = None
246 client.cached_endpoint = None
247 self.authenticate()
248 try:
249 token, endpoint = self.auth_plugin.token_and_endpoint(
250 **filter_args)
251 except exceptions.EndpointException:
252 raise unauth_ex
253 if (not (token and endpoint) or
254 old_token_endpoint == (token, endpoint)):
255 raise unauth_ex
256 self.cached_token = token
257 client.cached_endpoint = endpoint
258 kwargs["headers"]["X-Auth-Token"] = token
259 return self.request(
260 method, self.concat_url(endpoint, url), **kwargs)
261
262 def add_client(self, base_client_instance):
263 """Add a new instance of :class:`BaseClient` descendant.
264
265 `self` will store a reference to `base_client_instance`.
266
267 Example:
268
269 >>> def test_clients():
270 ... from keystoneclient.auth import keystone
271 ... from openstack.common.apiclient import client
272 ... auth = keystone.KeystoneAuthPlugin(
273 ... username="user", password="pass", tenant_name="tenant",
274 ... auth_url="http://auth:5000/v2.0")
275 ... openstack_client = client.HTTPClient(auth)
276 ... # create nova client
277 ... from novaclient.v1_1 import client
278 ... client.Client(openstack_client)
279 ... # create keystone client
280 ... from keystoneclient.v2_0 import client
281 ... client.Client(openstack_client)
282 ... # use them
283 ... openstack_client.identity.tenants.list()
284 ... openstack_client.compute.servers.list()
285 """
286 service_type = base_client_instance.service_type
287 if service_type and not hasattr(self, service_type):
288 setattr(self, service_type, base_client_instance)
289
290 def authenticate(self):
291 self.auth_plugin.authenticate(self)
292 # Store the authentication results in the keyring for later requests
293 if self.keyring_saver:
294 self.keyring_saver.save(self)
295
296
297 class BaseClient(object):
298 """Top-level object to access the OpenStack API.
299
300 This client uses :class:`HTTPClient` to send requests. :class:`HTTPClient`
301 will handle a bunch of issues such as authentication.
302 """
303
304 service_type = None
305 endpoint_type = None # "publicURL" will be used
306 cached_endpoint = None
307
308 def __init__(self, http_client, extensions=None):
309 self.http_client = http_client
310 http_client.add_client(self)
311
312 # Add in any extensions...
313 if extensions:
314 for extension in extensions:
315 if extension.manager_class:
316 setattr(self, extension.name,
317 extension.manager_class(self))
318
319 def client_request(self, method, url, **kwargs):
320 return self.http_client.client_request(
321 self, method, url, **kwargs)
322
323 def head(self, url, **kwargs):
324 return self.client_request("HEAD", url, **kwargs)
325
326 def get(self, url, **kwargs):
327 return self.client_request("GET", url, **kwargs)
328
329 def post(self, url, **kwargs):
330 return self.client_request("POST", url, **kwargs)
331
332 def put(self, url, **kwargs):
333 return self.client_request("PUT", url, **kwargs)
334
335 def delete(self, url, **kwargs):
336 return self.client_request("DELETE", url, **kwargs)
337
338 def patch(self, url, **kwargs):
339 return self.client_request("PATCH", url, **kwargs)
340
341 @staticmethod
342 def get_class(api_name, version, version_map):
343 """Returns the client class for the requested API version
344
345 :param api_name: the name of the API, e.g. 'compute', 'image', etc
346 :param version: the requested API version
347 :param version_map: a dict of client classes keyed by version
348 :rtype: a client class for the requested API version
349 """
350 try:
351 client_path = version_map[str(version)]
352 except (KeyError, ValueError):
353 msg = "Invalid %s client version '%s'. must be one of: %s" % (
354 (api_name, version, ', '.join(version_map.keys())))
355 raise exceptions.UnsupportedVersion(msg)
356
357 return importutils.import_class(client_path)