OpenStack Identity Authentication Library
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

discover.py 55KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414
  1. # Licensed under the Apache License, Version 2.0 (the "License"); you may
  2. # not use this file except in compliance with the License. You may obtain
  3. # a copy of the License at
  4. #
  5. # http://www.apache.org/licenses/LICENSE-2.0
  6. #
  7. # Unless required by applicable law or agreed to in writing, software
  8. # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  9. # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  10. # License for the specific language governing permissions and limitations
  11. # under the License.
  12. """The passive components to version discovery.
  13. The Discover object in discover.py contains functions that can create objects
  14. on your behalf. These functions are not usable from within the keystoneauth1
  15. library because you will get dependency resolution issues.
  16. The Discover object in this file provides the querying components of Discovery.
  17. This includes functions like url_for which allow you to retrieve URLs and the
  18. raw data specified in version discovery responses.
  19. """
  20. import copy
  21. import re
  22. import os_service_types
  23. import six
  24. from six.moves import urllib
  25. from keystoneauth1 import _utils as utils
  26. from keystoneauth1 import exceptions
  27. _LOGGER = utils.get_logger(__name__)
  28. LATEST = float('inf')
  29. _SERVICE_TYPES = os_service_types.ServiceTypes()
  30. def _str_or_latest(val):
  31. """Convert val to a string, handling LATEST => 'latest'.
  32. :param val: An int or the special value LATEST.
  33. :return: A string representation of val. If val was LATEST, the return is
  34. 'latest'.
  35. """
  36. return 'latest' if val == LATEST else str(val)
  37. def _int_or_latest(val):
  38. """Convert val to an int or the special value LATEST.
  39. :param val: An int()-able, or the string 'latest', or the special value
  40. LATEST.
  41. :return: An int, or the special value LATEST
  42. """
  43. return LATEST if val == 'latest' or val == LATEST else int(val)
  44. def get_version_data(session, url, authenticated=None):
  45. """Retrieve raw version data from a url.
  46. The return is a list of dicts of the form::
  47. [{
  48. 'status': 'STABLE',
  49. 'id': 'v2.3',
  50. 'links': [
  51. {
  52. 'href': 'http://network.example.com/v2.3',
  53. 'rel': 'self',
  54. },
  55. {
  56. 'href': 'http://network.example.com/',
  57. 'rel': 'collection',
  58. },
  59. ],
  60. 'min_version': '2.0',
  61. 'max_version': '2.7',
  62. },
  63. ...,
  64. ]
  65. Note:
  66. The maximum microversion may be specified by `max_version` or `version`,
  67. the former superseding the latter.
  68. All `*version` keys are optional.
  69. Other keys and 'links' entries are permitted, but ignored.
  70. :param session: A Session object that can be used for communication.
  71. :type session: keystoneauth1.session.Session
  72. :param string url: Endpoint or discovery URL from which to retrieve data.
  73. :param bool authenticated: Include a token in the discovery call.
  74. (optional) Defaults to None.
  75. :return: A list of dicts containing version information.
  76. :rtype: list(dict)
  77. """
  78. headers = {'Accept': 'application/json'}
  79. resp = session.get(url, headers=headers, authenticated=authenticated)
  80. try:
  81. body_resp = resp.json()
  82. except ValueError:
  83. pass
  84. else:
  85. # In the event of querying a root URL we will get back a list of
  86. # available versions.
  87. try:
  88. return body_resp['versions']['values']
  89. except (KeyError, TypeError):
  90. pass
  91. # Most servers don't have a 'values' element so accept a simple
  92. # versions dict if available.
  93. try:
  94. return body_resp['versions']
  95. except KeyError:
  96. pass
  97. # Otherwise if we query an endpoint like /v2.0 then we will get back
  98. # just the one available version.
  99. try:
  100. return [body_resp['version']]
  101. except KeyError:
  102. pass
  103. err_text = resp.text[:50] + '...' if len(resp.text) > 50 else resp.text
  104. raise exceptions.DiscoveryFailure('Invalid Response - Bad version data '
  105. 'returned: %s' % err_text)
  106. def normalize_version_number(version):
  107. """Turn a version representation into a tuple.
  108. Examples:
  109. The following all produce a return value of (1, 0)::
  110. 1, '1', 'v1', [1], (1,), ['1'], 1.0, '1.0', 'v1.0', (1, 0)
  111. The following all produce a return value of (1, 20, 3)::
  112. 'v1.20.3', '1.20.3', (1, 20, 3), ['1', '20', '3']
  113. The following all produce a return value of (LATEST, LATEST)::
  114. 'latest', 'vlatest', ('latest', 'latest'), (LATEST, LATEST)
  115. The following all produce a return value of (2, LATEST)::
  116. '2.latest', 'v2.latest', (2, LATEST), ('2', 'latest')
  117. :param version: A version specifier in any of the following forms:
  118. String, possibly prefixed with 'v', containing one or more numbers
  119. *or* the string 'latest', separated by periods. Examples: 'v1',
  120. 'v1.2', '1.2.3', '123', 'latest', '1.latest', 'v1.latest'.
  121. Integer. This will be assumed to be the major version, with a minor
  122. version of 0.
  123. Float. The integer part is assumed to be the major version; the
  124. decimal part the minor version.
  125. Non-string iterable comprising integers, integer strings, the string
  126. 'latest', or the special value LATEST.
  127. Examples: (1,), [1, 2], ('12', '34', '56'), (LATEST,), (2, 'latest')
  128. :return: A tuple of len >= 2 comprising integers and/or LATEST.
  129. :raises TypeError: If the input version cannot be interpreted.
  130. """
  131. # Copy the input var so the error presents the original value
  132. ver = version
  133. # If it's a non-string iterable, turn it into a string for subsequent
  134. # processing. This ensures at least 1 decimal point if e.g. [1] is given.
  135. if not isinstance(ver, six.string_types):
  136. try:
  137. ver = '.'.join(map(_str_or_latest, ver))
  138. except TypeError:
  139. # Not an iterable
  140. pass
  141. # If it's a numeric or an integer as a string then normalize it to a
  142. # float string. This ensures 1 decimal point.
  143. # If it's a float as a string, don't do that, the split/map below will do
  144. # what we want. (Otherwise, we wind up with 3.20 -> (3, 2))
  145. if isinstance(ver, six.string_types):
  146. # trim the v from a 'v2.0' or similar
  147. ver = ver.lstrip('v')
  148. try:
  149. # If version is a pure int, like '1' or '200' this will produce
  150. # a stringified version with a .0 added. If it's any other number,
  151. # such as '1.1' - int(version) raises an Exception
  152. ver = str(float(int(ver)))
  153. except ValueError:
  154. pass
  155. # If it's an int or float, turn it into a float string
  156. elif isinstance(ver, (int, float)):
  157. ver = _str_or_latest(float(ver))
  158. # At this point, we should either have a string that contains numbers with
  159. # at least one decimal point, or something decidedly else.
  160. # if it's a string from above break it on .
  161. try:
  162. ver = ver.split('.')
  163. except AttributeError:
  164. # Not a string
  165. pass
  166. # Handle special case variants of just 'latest'
  167. if ver == 'latest' or tuple(ver) == ('latest',):
  168. return LATEST, LATEST
  169. # It's either an interable, or something else that makes us sad.
  170. try:
  171. return tuple(map(_int_or_latest, ver))
  172. except (TypeError, ValueError):
  173. pass
  174. raise TypeError('Invalid version specified: %s' % version)
  175. def _normalize_version_args(version, min_version, max_version):
  176. if version and (min_version or max_version):
  177. raise ValueError(
  178. "version is mutually exclusive with min_version and max_version")
  179. if version:
  180. # Explode this into min_version and max_version
  181. min_version = normalize_version_number(version)
  182. max_version = (min_version[0], LATEST)
  183. return min_version, max_version
  184. if min_version == 'latest':
  185. if max_version not in (None, 'latest'):
  186. raise ValueError(
  187. "min_version is 'latest' and max_version is {max_version}"
  188. " but is only allowed to be 'latest' or None".format(
  189. max_version=max_version))
  190. max_version = 'latest'
  191. # Normalize e.g. empty string to None
  192. min_version = min_version or None
  193. max_version = max_version or None
  194. if min_version:
  195. min_version = normalize_version_number(min_version)
  196. # If min_version was specified but max_version was not, max is latest.
  197. max_version = normalize_version_number(max_version or 'latest')
  198. # NOTE(efried): We should be doing this instead:
  199. # max_version = normalize_version_number(max_version or 'latest')
  200. # However, see first NOTE(jamielennox) in EndpointData._set_version_info.
  201. if max_version:
  202. max_version = normalize_version_number(max_version)
  203. if None not in (min_version, max_version) and max_version < min_version:
  204. raise ValueError("min_version cannot be greater than max_version")
  205. return min_version, max_version
  206. def version_to_string(version):
  207. """Turn a version tuple into a string.
  208. :param tuple version: A version represented as a tuple of ints. As a
  209. special case, a tuple member may be LATEST, which
  210. translates to 'latest'.
  211. :return: A version represented as a period-delimited string.
  212. """
  213. # Special case
  214. if all(ver == LATEST for ver in version):
  215. return 'latest'
  216. return ".".join(map(_str_or_latest, version))
  217. def _version_between(min_version, max_version, candidate):
  218. """Determine whether a candidate version is within a specified range.
  219. :param min_version: The minimum version that is acceptable.
  220. None/empty indicates no lower bound.
  221. :param max_version: The maximum version that is acceptable.
  222. None/empty indicates no upper bound.
  223. :param candidate: Candidate version to test. May not be None/empty.
  224. :return: True if candidate is between min_version and max_version; False
  225. otherwise.
  226. :raises ValueError: If candidate is None.
  227. :raises TypeError: If any input cannot be normalized.
  228. """
  229. if not candidate:
  230. raise ValueError("candidate is required.")
  231. candidate = normalize_version_number(candidate)
  232. # Normalize up front to validate any malformed inputs
  233. if min_version:
  234. min_version = normalize_version_number(min_version)
  235. if max_version:
  236. max_version = normalize_version_number(max_version)
  237. # If the candidate is less than the min_version, it's not a match.
  238. # No min_version means no lower bound.
  239. if min_version and candidate < min_version:
  240. return False
  241. # If the candidate is higher than the max_version, it's not a match.
  242. # No max_version means no upper bound.
  243. if max_version and candidate > max_version:
  244. return False
  245. return True
  246. def version_match(required, candidate):
  247. """Test that an available version satisfies the required version.
  248. To be suitable a version must be of the same major version as required
  249. and be at least a match in minor/patch level.
  250. eg. 3.3 is a match for a required 3.1 but 4.1 is not.
  251. :param tuple required: the version that must be met.
  252. :param tuple candidate: the version to test against required.
  253. :returns: True if candidate is suitable False otherwise.
  254. :rtype: bool
  255. """
  256. # major versions must be the same (e.g. even though v2 is a lower
  257. # version than v3 we can't use it if v2 was requested)
  258. if candidate[0] != required[0]:
  259. return False
  260. # prevent selecting a minor version less than what is required
  261. if candidate < required:
  262. return False
  263. return True
  264. def _latest_soft_match(required, candidate):
  265. if not required:
  266. return False
  267. if LATEST not in required:
  268. return False
  269. if all(part == LATEST for part in required):
  270. return True
  271. if required[0] == candidate[0] and required[1] == LATEST:
  272. return True
  273. # TODO(efried): Do we need to handle >2-part version numbers here?
  274. return False
  275. def _combine_relative_url(discovery_url, version_url):
  276. # NOTE(jamielennox): urllib.parse.urljoin allows the url to be relative
  277. # or even protocol-less. The additional trailing '/' makes urljoin respect
  278. # the current path as canonical even if the url doesn't include it. for
  279. # example a "v2" path from http://host/admin should resolve as
  280. # http://host/admin/v2 where it would otherwise be host/v2. This has no
  281. # effect on absolute urls.
  282. url = urllib.parse.urljoin(discovery_url.rstrip('/') + '/', version_url)
  283. # Sadly version discovery documents are common with the scheme
  284. # and netloc broken.
  285. parsed_version_url = urllib.parse.urlparse(url)
  286. parsed_discovery_url = urllib.parse.urlparse(discovery_url)
  287. return urllib.parse.ParseResult(
  288. parsed_discovery_url.scheme,
  289. parsed_discovery_url.netloc,
  290. parsed_version_url.path,
  291. parsed_version_url.params,
  292. parsed_version_url.query,
  293. parsed_version_url.fragment).geturl()
  294. def _version_from_url(url):
  295. if not url:
  296. return url
  297. url = urllib.parse.urlparse(url)
  298. for part in reversed(url.path.split('/')):
  299. try:
  300. return normalize_version_number(part)
  301. except Exception:
  302. pass
  303. return None
  304. class Status(object):
  305. CURRENT = 'CURRENT'
  306. SUPPORTED = 'SUPPORTED'
  307. DEPRECATED = 'DEPRECATED'
  308. EXPERIMENTAL = 'EXPERIMENTAL'
  309. UNKNOWN = 'UNKNOWN'
  310. KNOWN = (CURRENT, SUPPORTED, DEPRECATED, EXPERIMENTAL)
  311. @classmethod
  312. def normalize(cls, raw_status):
  313. """Turn a status into a canonical status value.
  314. If the status from the version discovery document does not match one
  315. of the known values, it will be set to 'UNKNOWN'.
  316. :param str raw_status: Status value from a discovery document.
  317. :returns: A canonicalized version of the status. Valid values
  318. are CURRENT, SUPPORTED, DEPRECATED, EXPERIMENTAL and UNKNOWN
  319. :rtype: str
  320. """
  321. status = raw_status.upper()
  322. if status == 'STABLE':
  323. status = 'CURRENT'
  324. if status not in cls.KNOWN:
  325. status = cls.UNKNOWN
  326. return status
  327. class Discover(object):
  328. CURRENT_STATUSES = ('stable', 'current', 'supported')
  329. DEPRECATED_STATUSES = ('deprecated',)
  330. EXPERIMENTAL_STATUSES = ('experimental',)
  331. def __init__(self, session, url, authenticated=None):
  332. self._url = url
  333. self._data = get_version_data(session, url,
  334. authenticated=authenticated)
  335. def raw_version_data(self, allow_experimental=False,
  336. allow_deprecated=True, allow_unknown=False):
  337. """Get raw version information from URL.
  338. Raw data indicates that only minimal validation processing is performed
  339. on the data, so what is returned here will be the data in the same
  340. format it was received from the endpoint.
  341. :param bool allow_experimental: Allow experimental version endpoints.
  342. :param bool allow_deprecated: Allow deprecated version endpoints.
  343. :param bool allow_unknown: Allow endpoints with an unrecognised status.
  344. :returns: The endpoints returned from the server that match the
  345. criteria.
  346. :rtype: list
  347. """
  348. versions = []
  349. for v in self._data:
  350. try:
  351. status = v['status']
  352. except KeyError:
  353. _LOGGER.warning('Skipping over invalid version data. '
  354. 'No stability status in version.')
  355. continue
  356. status = status.lower()
  357. if status in self.CURRENT_STATUSES:
  358. versions.append(v)
  359. elif status in self.DEPRECATED_STATUSES:
  360. if allow_deprecated:
  361. versions.append(v)
  362. elif status in self.EXPERIMENTAL_STATUSES:
  363. if allow_experimental:
  364. versions.append(v)
  365. elif allow_unknown:
  366. versions.append(v)
  367. return versions
  368. def version_data(self, reverse=False, **kwargs):
  369. """Get normalized version data.
  370. Return version data in a structured way.
  371. :param bool reverse: Reverse the list. reverse=true will mean the
  372. returned list is sorted from newest to oldest
  373. version.
  374. :returns: A list of :class:`VersionData` sorted by version number.
  375. :rtype: list(VersionData)
  376. """
  377. data = self.raw_version_data(**kwargs)
  378. versions = []
  379. for v in data:
  380. try:
  381. version_str = v['id']
  382. except KeyError:
  383. _LOGGER.info('Skipping invalid version data. Missing ID.')
  384. continue
  385. try:
  386. links = v['links']
  387. except KeyError:
  388. _LOGGER.info('Skipping invalid version data. Missing links')
  389. continue
  390. version_number = normalize_version_number(version_str)
  391. # collect microversion information
  392. # NOTE(efried): Some existing discovery documents (e.g. from nova
  393. # v2.0 in the pike release) include *version keys with "" (empty
  394. # string) values, expecting them to be treated the same as if the
  395. # keys were absent.
  396. min_microversion = v.get('min_version') or None
  397. if min_microversion:
  398. min_microversion = normalize_version_number(min_microversion)
  399. max_microversion = v.get('max_version')
  400. if not max_microversion:
  401. max_microversion = v.get('version') or None
  402. if max_microversion:
  403. max_microversion = normalize_version_number(max_microversion)
  404. next_min_version = v.get('next_min_version') or None
  405. if next_min_version:
  406. next_min_version = normalize_version_number(next_min_version)
  407. not_before = v.get('not_before') or None
  408. self_url = None
  409. collection_url = None
  410. for link in links:
  411. try:
  412. rel = link['rel']
  413. url = _combine_relative_url(self._url, link['href'])
  414. except (KeyError, TypeError):
  415. _LOGGER.info('Skipping invalid version link. '
  416. 'Missing link URL or relationship.')
  417. continue
  418. if rel.lower() == 'self':
  419. self_url = url
  420. elif rel.lower() == 'collection':
  421. collection_url = url
  422. if not self_url:
  423. _LOGGER.info('Skipping invalid version data. '
  424. 'Missing link to endpoint.')
  425. continue
  426. versions.append(
  427. VersionData(version=version_number,
  428. url=self_url,
  429. collection=collection_url,
  430. min_microversion=min_microversion,
  431. max_microversion=max_microversion,
  432. next_min_version=next_min_version,
  433. not_before=not_before,
  434. status=Status.normalize(v['status']),
  435. raw_status=v['status']))
  436. versions.sort(key=lambda v: v['version'], reverse=reverse)
  437. return versions
  438. def version_string_data(self, reverse=False, **kwargs):
  439. """Get normalized version data with versions as strings.
  440. Return version data in a structured way.
  441. :param bool reverse: Reverse the list. reverse=true will mean the
  442. returned list is sorted from newest to oldest
  443. version.
  444. :returns: A list of :class:`VersionData` sorted by version number.
  445. :rtype: list(VersionData)
  446. """
  447. version_data = self.version_data(reverse=reverse, **kwargs)
  448. for version in version_data:
  449. for key in ('version', 'min_microversion', 'max_microversion'):
  450. if version[key]:
  451. version[key] = version_to_string(version[key])
  452. return version_data
  453. def data_for(self, version, **kwargs):
  454. """Return endpoint data for a version.
  455. NOTE: This method raises a TypeError if version is None. It is
  456. kept for backwards compatability. New code should use
  457. versioned_data_for instead.
  458. :param tuple version: The version is always a minimum version in the
  459. same major release as there should be no compatibility issues with
  460. using a version newer than the one asked for.
  461. :returns: the endpoint data for a URL that matches the required version
  462. (the format is described in version_data) or None if no
  463. match.
  464. :rtype: dict
  465. """
  466. version = normalize_version_number(version)
  467. for data in self.version_data(reverse=True, **kwargs):
  468. # Since the data is reversed, the latest version is first. If
  469. # latest was requested, return it.
  470. if _latest_soft_match(version, data['version']):
  471. return data
  472. if version_match(version, data['version']):
  473. return data
  474. return None
  475. def url_for(self, version, **kwargs):
  476. """Get the endpoint url for a version.
  477. NOTE: This method raises a TypeError if version is None. It is
  478. kept for backwards compatability. New code should use
  479. versioned_url_for instead.
  480. :param tuple version: The version is always a minimum version in the
  481. same major release as there should be no compatibility issues with
  482. using a version newer than the one asked for.
  483. :returns: The url for the specified version or None if no match.
  484. :rtype: str
  485. """
  486. data = self.data_for(version, **kwargs)
  487. return data['url'] if data else None
  488. def versioned_data_for(self, url=None,
  489. min_version=None, max_version=None,
  490. **kwargs):
  491. """Return endpoint data for the service at a url.
  492. min_version and max_version can be given either as strings or tuples.
  493. :param string url: If url is given, the data will be returned for the
  494. endpoint data that has a self link matching the url.
  495. :param min_version: The minimum endpoint version that is acceptable. If
  496. min_version is given with no max_version it is as if max version is
  497. 'latest'. If min_version is 'latest', max_version may only be
  498. 'latest' or None.
  499. :param max_version: The maximum endpoint version that is acceptable. If
  500. min_version is given with no max_version it is as if max version is
  501. 'latest'. If min_version is 'latest', max_version may only be
  502. 'latest' or None.
  503. :returns: the endpoint data for a URL that matches the required version
  504. (the format is described in version_data) or None if no
  505. match.
  506. :rtype: dict
  507. """
  508. min_version, max_version = _normalize_version_args(
  509. None, min_version, max_version)
  510. no_version = not max_version and not min_version
  511. version_data = self.version_data(reverse=True, **kwargs)
  512. # If we don't have to check a min_version, we can short
  513. # circuit anything else
  514. if (max_version == (LATEST, LATEST) and
  515. (not min_version or min_version == (LATEST, LATEST))):
  516. # because we reverse we can just take the first entry
  517. return version_data[0]
  518. if url:
  519. url = url.rstrip('/') + '/'
  520. if no_version and not url:
  521. # because we reverse we can just take the first entry
  522. return version_data[0]
  523. # Version data is in order from highest to lowest, so we return
  524. # the first matching entry
  525. for data in version_data:
  526. if url and data['url'] and data['url'].rstrip('/') + '/' == url:
  527. return data
  528. if _latest_soft_match(min_version, data['version']):
  529. return data
  530. # Only validate version bounds if versions were specified
  531. if min_version and max_version and _version_between(
  532. min_version, max_version, data['version']):
  533. return data
  534. # If there is no version requested and we could not find a matching
  535. # url in the discovery doc, that means we've got an unversioned
  536. # endpoint in the catalog and the user is requesting version data
  537. # so that they know what version they got. We can return the first
  538. # entry from version_data, because the user hasn't requested anything
  539. # different.
  540. if no_version and url:
  541. return version_data[0]
  542. # We couldn't find a match.
  543. return None
  544. def versioned_url_for(self, min_version=None, max_version=None, **kwargs):
  545. """Get the endpoint url for a version.
  546. min_version and max_version can be given either as strings or tuples.
  547. :param min_version: The minimum version that is acceptable. If
  548. min_version is given with no max_version it is as if max version
  549. is 'latest'.
  550. :param max_version: The maximum version that is acceptable. If
  551. min_version is given with no max_version it is as if max version is
  552. 'latest'.
  553. :returns: The url for the specified version or None if no match.
  554. :rtype: str
  555. """
  556. data = self.versioned_data_for(min_version=min_version,
  557. max_version=max_version, **kwargs)
  558. return data['url'] if data else None
  559. class VersionData(dict):
  560. """Normalized Version Data about an endpoint."""
  561. def __init__(
  562. self,
  563. version,
  564. url,
  565. collection=None,
  566. max_microversion=None,
  567. min_microversion=None,
  568. next_min_version=None,
  569. not_before=None,
  570. status='CURRENT',
  571. raw_status=None):
  572. super(VersionData, self).__init__()
  573. self['version'] = version
  574. self['url'] = url
  575. self['collection'] = collection
  576. self['max_microversion'] = max_microversion
  577. self['min_microversion'] = min_microversion
  578. self['next_min_version'] = next_min_version
  579. self['not_before'] = not_before
  580. self['status'] = status
  581. self['raw_status'] = raw_status
  582. @property
  583. def version(self):
  584. """The normalized version of the endpoint."""
  585. return self.get('version')
  586. @property
  587. def url(self):
  588. """The url for the endpoint."""
  589. return self.get('url')
  590. @property
  591. def collection(self):
  592. """The URL for the discovery document.
  593. May be None.
  594. """
  595. return self.get('collection')
  596. @property
  597. def min_microversion(self):
  598. """The minimum microversion supported by the endpoint.
  599. May be None.
  600. """
  601. return self.get('min_microversion')
  602. @property
  603. def max_microversion(self):
  604. """The maximum microversion supported by the endpoint.
  605. May be None.
  606. """
  607. return self.get('max_microversion')
  608. @property
  609. def status(self):
  610. """A canonicalized version of the status.
  611. Valid values are CURRENT, SUPPORTED, DEPRECATED and EXPERIMENTAL.
  612. """
  613. return self.get('status')
  614. @property
  615. def raw_status(self):
  616. """The status as provided by the server."""
  617. return self.get('raw_status')
  618. class EndpointData(object):
  619. """Normalized information about a discovered endpoint.
  620. Contains url, version, microversion, interface and region information.
  621. This is essentially the data contained in the catalog and the version
  622. discovery documents about an endpoint that is used to select the endpoint
  623. desired by the user. It is returned so that a user can know which qualities
  624. a discovered endpoint had, in case their request allowed for a range of
  625. possibilities.
  626. """
  627. def __init__(self,
  628. catalog_url=None,
  629. service_url=None,
  630. service_type=None,
  631. service_name=None,
  632. service_id=None,
  633. region_name=None,
  634. interface=None,
  635. endpoint_id=None,
  636. raw_endpoint=None,
  637. api_version=None,
  638. major_version=None,
  639. min_microversion=None,
  640. max_microversion=None,
  641. next_min_version=None,
  642. not_before=None,
  643. status=None):
  644. self.catalog_url = catalog_url
  645. self.service_url = service_url
  646. self.service_type = service_type
  647. self.service_name = service_name
  648. self.service_id = service_id
  649. self.interface = interface
  650. self.region_name = region_name
  651. self.endpoint_id = endpoint_id
  652. self.raw_endpoint = raw_endpoint
  653. self.major_version = major_version
  654. self.min_microversion = min_microversion
  655. self.max_microversion = max_microversion
  656. self.next_min_version = next_min_version
  657. self.not_before = not_before
  658. self.status = status
  659. self._saved_project_id = None
  660. self._catalog_matches_version = False
  661. self._catalog_matches_exactly = False
  662. self._disc = None
  663. self.api_version = api_version or _version_from_url(self.url)
  664. def __copy__(self):
  665. """Return a new EndpointData based on this one."""
  666. new_data = EndpointData(
  667. catalog_url=self.catalog_url,
  668. service_url=self.service_url,
  669. service_type=self.service_type,
  670. service_name=self.service_name,
  671. service_id=self.service_id,
  672. region_name=self.region_name,
  673. interface=self.interface,
  674. endpoint_id=self.endpoint_id,
  675. raw_endpoint=self.raw_endpoint,
  676. api_version=self.api_version,
  677. major_version=self.major_version,
  678. min_microversion=self.min_microversion,
  679. max_microversion=self.max_microversion,
  680. next_min_version=self.next_min_version,
  681. not_before=self.not_before,
  682. status=self.status,
  683. )
  684. # Save cached discovery object - but we don't want to
  685. # actually provide a constructor argument
  686. new_data._disc = self._disc
  687. new_data._saved_project_id = self._saved_project_id
  688. return new_data
  689. def __str__(self):
  690. """Produce a string like EndpointData{key=val, ...}, for debugging."""
  691. str_attrs = (
  692. 'api_version', 'catalog_url', 'endpoint_id', 'interface',
  693. 'major_version', 'max_microversion', 'min_microversion',
  694. 'next_min_version', 'not_before', 'raw_endpoint', 'region_name',
  695. 'service_id', 'service_name', 'service_type', 'service_url', 'url')
  696. return "%s{%s}" % (self.__class__.__name__, ', '.join(
  697. ["%s=%s" % (attr, getattr(self, attr)) for attr in str_attrs]))
  698. @property
  699. def url(self):
  700. return self.service_url or self.catalog_url
  701. def get_current_versioned_data(self, session, allow=None, cache=None,
  702. project_id=None):
  703. """Run version discovery on the current endpoint.
  704. A simplified version of get_versioned_data, get_current_versioned_data
  705. runs discovery but only on the endpoint that has been found already.
  706. It can be useful in some workflows where the user wants version
  707. information about the endpoint they have.
  708. :param session: A session object that can be used for communication.
  709. :type session: keystoneauth1.session.Session
  710. :param dict allow: Extra filters to pass when discovering API
  711. versions. (optional)
  712. :param dict cache: A dict to be used for caching results in
  713. addition to caching them on the Session.
  714. (optional)
  715. :param string project_id: ID of the currently scoped project. Used for
  716. removing project_id components of URLs from
  717. the catalog. (optional)
  718. :returns: A new EndpointData with the requested versioned data.
  719. :rtype: :py:class:`keystoneauth1.discover.EndpointData`
  720. :raises keystoneauth1.exceptions.discovery.DiscoveryFailure: If the
  721. appropriate versioned data
  722. could not be discovered.
  723. """
  724. min_version, max_version = _normalize_version_args(
  725. self.api_version, None, None)
  726. return self.get_versioned_data(
  727. session=session, allow=allow, cache=cache, allow_version_hack=True,
  728. discover_versions=True,
  729. min_version=min_version, max_version=max_version)
  730. def get_versioned_data(self, session, allow=None, cache=None,
  731. allow_version_hack=True, project_id=None,
  732. discover_versions=True,
  733. min_version=None, max_version=None):
  734. """Run version discovery for the service described.
  735. Performs Version Discovery and returns a new EndpointData object with
  736. information found.
  737. min_version and max_version can be given either as strings or tuples.
  738. :param session: A session object that can be used for communication.
  739. :type session: keystoneauth1.session.Session
  740. :param dict allow: Extra filters to pass when discovering API
  741. versions. (optional)
  742. :param dict cache: A dict to be used for caching results in
  743. addition to caching them on the Session.
  744. (optional)
  745. :param bool allow_version_hack: Allow keystoneauth to hack up catalog
  746. URLS to support older schemes.
  747. (optional, default True)
  748. :param string project_id: ID of the currently scoped project. Used for
  749. removing project_id components of URLs from
  750. the catalog. (optional)
  751. :param bool discover_versions: Whether to get version metadata from
  752. the version discovery document even
  753. if it's not neccessary to fulfill the
  754. major version request. (optional,
  755. defaults to True)
  756. :param min_version: The minimum version that is acceptable. If
  757. min_version is given with no max_version it is as
  758. if max version is 'latest'.
  759. :param max_version: The maximum version that is acceptable. If
  760. min_version is given with no max_version it is as
  761. if max version is 'latest'.
  762. :returns: A new EndpointData with the requested versioned data.
  763. :rtype: :py:class:`keystoneauth1.discover.EndpointData`
  764. :raises keystoneauth1.exceptions.discovery.DiscoveryFailure: If the
  765. appropriate versioned data
  766. could not be discovered.
  767. """
  768. min_version, max_version = _normalize_version_args(
  769. None, min_version, max_version)
  770. if not allow:
  771. allow = {}
  772. # This method should always return a new EndpointData
  773. new_data = copy.copy(self)
  774. new_data._set_version_info(
  775. session=session, allow=allow, cache=cache,
  776. allow_version_hack=allow_version_hack, project_id=project_id,
  777. discover_versions=discover_versions, min_version=min_version,
  778. max_version=max_version)
  779. return new_data
  780. def get_all_version_string_data(self, session, project_id=None):
  781. """Return version data for all versions discovery can find.
  782. :param string project_id: ID of the currently scoped project. Used for
  783. removing project_id components of URLs from
  784. the catalog. (optional)
  785. :returns: A list of :class:`VersionData` sorted by version number.
  786. :rtype: list(VersionData)
  787. """
  788. versions = []
  789. for vers_url in self._get_discovery_url_choices(project_id=project_id):
  790. try:
  791. d = get_discovery(session, vers_url)
  792. except Exception as e:
  793. # Ignore errors here - we're just searching for one of the
  794. # URLs that will give us data.
  795. _LOGGER.debug(
  796. "Failed attempt at discovery on %s: %s", vers_url, str(e))
  797. continue
  798. for version in d.version_string_data():
  799. versions.append(version)
  800. break
  801. return versions or self._infer_version_data(project_id)
  802. def _infer_version_data(self, project_id=None):
  803. """Return version data dict for when discovery fails.
  804. :param string project_id: ID of the currently scoped project. Used for
  805. removing project_id components of URLs from
  806. the catalog. (optional)
  807. :returns: A list of :class:`VersionData` sorted by version number.
  808. :rtype: list(VersionData)
  809. """
  810. version = self.api_version
  811. if version:
  812. version = version_to_string(self.api_version)
  813. url = self.url.rstrip("/")
  814. if project_id and url.endswith(project_id):
  815. url, _ = self.url.rsplit('/', 1)
  816. url += "/"
  817. return [VersionData(url=url, version=version)]
  818. def _set_version_info(self, session, allow=None, cache=None,
  819. allow_version_hack=True, project_id=None,
  820. discover_versions=False,
  821. min_version=None, max_version=None):
  822. match_url = None
  823. no_version = not max_version and not min_version
  824. if no_version and not discover_versions:
  825. # NOTE(jamielennox): This may not be the best thing to default to
  826. # but is here for backwards compatibility. It may be worth
  827. # defaulting to the most recent version.
  828. return
  829. elif no_version and discover_versions:
  830. # We want to run discovery, but we don't want to find different
  831. # endpoints than what's in the catalog
  832. allow_version_hack = False
  833. match_url = self.url
  834. if project_id:
  835. self.project_id = project_id
  836. discovered_data = None
  837. # Maybe we've run discovery in the past and have a document that can
  838. # satisfy the request without further work
  839. if self._disc:
  840. discovered_data = self._disc.versioned_data_for(
  841. min_version=min_version, max_version=max_version,
  842. url=match_url, **allow)
  843. if not discovered_data:
  844. self._run_discovery(
  845. session=session, cache=cache,
  846. min_version=min_version, max_version=max_version,
  847. project_id=project_id, allow_version_hack=allow_version_hack,
  848. discover_versions=discover_versions)
  849. if not self._disc:
  850. return
  851. discovered_data = self._disc.versioned_data_for(
  852. min_version=min_version, max_version=max_version,
  853. url=match_url, **allow)
  854. if not discovered_data:
  855. if min_version and not max_version:
  856. raise exceptions.DiscoveryFailure(
  857. "Minimum version {min_version} was not found".format(
  858. min_version=version_to_string(min_version)))
  859. elif max_version and not min_version:
  860. raise exceptions.DiscoveryFailure(
  861. "Maximum version {max_version} was not found".format(
  862. max_version=version_to_string(max_version)))
  863. elif min_version and max_version:
  864. raise exceptions.DiscoveryFailure(
  865. "No version found between {min_version}"
  866. " and {max_version}".format(
  867. min_version=version_to_string(min_version),
  868. max_version=version_to_string(max_version)))
  869. self.min_microversion = discovered_data['min_microversion']
  870. self.max_microversion = discovered_data['max_microversion']
  871. self.next_min_version = discovered_data['next_min_version']
  872. self.not_before = discovered_data['not_before']
  873. self.api_version = discovered_data['version']
  874. self.status = discovered_data['status']
  875. # TODO(mordred): these next two things should be done by Discover
  876. # in versioned_data_for.
  877. discovered_url = discovered_data['url']
  878. # NOTE(jamielennox): urljoin allows the url to be relative or even
  879. # protocol-less. The additional trailing '/' make urljoin respect
  880. # the current path as canonical even if the url doesn't include it.
  881. # for example a "v2" path from http://host/admin should resolve as
  882. # http://host/admin/v2 where it would otherwise be host/v2.
  883. # This has no effect on absolute urls returned from url_for.
  884. url = urllib.parse.urljoin(self._disc._url.rstrip('/') + '/',
  885. discovered_url)
  886. # If we had to pop a project_id from the catalog_url, put it back on
  887. if self._saved_project_id:
  888. url = urllib.parse.urljoin(url.rstrip('/') + '/',
  889. self._saved_project_id)
  890. self.service_url = url
  891. def _run_discovery(self, session, cache, min_version, max_version,
  892. project_id, allow_version_hack, discover_versions):
  893. tried = set()
  894. for vers_url in self._get_discovery_url_choices(
  895. project_id=project_id,
  896. allow_version_hack=allow_version_hack,
  897. min_version=min_version,
  898. max_version=max_version):
  899. if self._catalog_matches_exactly and not discover_versions:
  900. # The version we started with is correct, and we don't want
  901. # new data
  902. return
  903. if vers_url in tried:
  904. continue
  905. tried.add(vers_url)
  906. try:
  907. self._disc = get_discovery(
  908. session, vers_url,
  909. cache=cache,
  910. authenticated=False)
  911. break
  912. except (exceptions.DiscoveryFailure,
  913. exceptions.HttpError,
  914. exceptions.ConnectionError):
  915. continue
  916. if not self._disc:
  917. # We couldn't find a version discovery document anywhere.
  918. if self._catalog_matches_version:
  919. # But - the version in the catalog is fine.
  920. self.service_url = self.catalog_url
  921. return
  922. # NOTE(jamielennox): The logic here is required for backwards
  923. # compatibility. By itself it is not ideal.
  924. if allow_version_hack:
  925. # NOTE(jamielennox): If we can't contact the server we
  926. # fall back to just returning the URL from the catalog. This
  927. # is backwards compatible behaviour and used when there is no
  928. # other choice. Realistically if you have provided a version
  929. # you should be able to rely on that version being returned or
  930. # the request failing.
  931. _LOGGER.warning(
  932. 'Failed to contact the endpoint at %s for '
  933. 'discovery. Fallback to using that endpoint as '
  934. 'the base url.', self.url)
  935. return
  936. else:
  937. # NOTE(jamielennox): If you've said no to allow_version_hack
  938. # and we can't determine the actual URL this is a failure
  939. # because we are specifying that the deployment must be up to
  940. # date enough to properly specify a version and keystoneauth
  941. # can't deliver.
  942. raise exceptions.DiscoveryFailure(
  943. "Version requested but version discovery document was not"
  944. " found and allow_version_hack was False")
  945. def _get_discovery_url_choices(
  946. self, project_id=None, allow_version_hack=True,
  947. min_version=None, max_version=None):
  948. """Find potential locations for version discovery URLs.
  949. min_version and max_version are already normalized, so will either be
  950. None or a tuple.
  951. """
  952. url = urllib.parse.urlparse(self.url.rstrip('/'))
  953. url_parts = url.path.split('/')
  954. # First, check to see if the catalog url ends with a project id
  955. # We need to remove it and save it for later if it does
  956. if project_id and url_parts[-1].endswith(project_id):
  957. self._saved_project_id = url_parts.pop()
  958. elif not project_id:
  959. # Peek to see if -2 is a version. If so, -1 is a project_id,
  960. # even if we don't know that at this point in the call stack
  961. try:
  962. normalize_version_number(url_parts[-2])
  963. self._saved_project_id = url_parts.pop()
  964. except (IndexError, TypeError):
  965. pass
  966. catalog_discovery = versioned_discovery = None
  967. # Next, check to see if the url indicates a version and if that
  968. # version either matches our version request or is within the
  969. # range requested. If so, we can start by trying the given url
  970. # as it has a high potential for success.
  971. try:
  972. url_version = normalize_version_number(url_parts[-1])
  973. versioned_discovery = urllib.parse.ParseResult(
  974. url.scheme,
  975. url.netloc,
  976. '/'.join(url_parts),
  977. url.params,
  978. url.query,
  979. url.fragment).geturl()
  980. except TypeError:
  981. pass
  982. else:
  983. # `is_between` means version bounds were specified *and* the URL
  984. # version is between them.
  985. is_between = min_version and max_version and _version_between(
  986. min_version, max_version, url_version)
  987. exact_match = (is_between and max_version and
  988. max_version[0] == url_version[0])
  989. high_match = (is_between and max_version and
  990. max_version[1] != LATEST and
  991. version_match(max_version, url_version))
  992. if exact_match or is_between:
  993. self._catalog_matches_version = True
  994. self._catalog_matches_exactly = exact_match
  995. # The endpoint from the catalog matches the version request
  996. # We construct a URL minus any project_id, but we don't
  997. # return it just yet. It's a good option, but unless we
  998. # have an exact match or match the max requested, we want
  999. # to try for an unversioned endpoint first.
  1000. catalog_discovery = urllib.parse.ParseResult(
  1001. url.scheme,
  1002. url.netloc,
  1003. '/'.join(url_parts),
  1004. url.params,
  1005. url.query,
  1006. url.fragment).geturl().rstrip('/') + '/'
  1007. # If we found a viable catalog endpoint and it's
  1008. # an exact match or matches the max, go ahead and give
  1009. # it a go.
  1010. if catalog_discovery and (high_match or exact_match):
  1011. yield catalog_discovery
  1012. catalog_discovery = None
  1013. url_parts.pop()
  1014. if allow_version_hack:
  1015. # If there were projects or versions in the url they are now gone.
  1016. # That means we're left with what should be the unversioned url.
  1017. hacked_url = urllib.parse.ParseResult(
  1018. url.scheme,
  1019. url.netloc,
  1020. '/'.join(url_parts),
  1021. url.params,
  1022. url.query,
  1023. url.fragment).geturl()
  1024. # Since this is potentially us constructing a base URL from the
  1025. # versioned URL - we need to make sure it has a trailing /. But
  1026. # we only want to do that if we have built a new URL - not if
  1027. # we're using the one from the catalog
  1028. if hacked_url != self.catalog_url:
  1029. hacked_url = hacked_url.strip('/') + '/'
  1030. yield hacked_url
  1031. # If we have a catalog discovery url, it either means we didn't
  1032. # return it earlier because it wasn't an exact enough match, or
  1033. # that we did and it failed. We don't double-request things when
  1034. # consuming this, so it's safe to return it here in case we didn't
  1035. # already return it.
  1036. if catalog_discovery:
  1037. yield catalog_discovery
  1038. # NOTE(mordred): For backwards compatibility people might have
  1039. # added version hacks using the version hack system. The logic
  1040. # above should handle most cases, so by the time we get here it's
  1041. # most likely to be a no-op
  1042. yield self._get_catalog_discover_hack()
  1043. elif versioned_discovery and self._saved_project_id:
  1044. # We popped a project_id but are either avoiding version hacks
  1045. # or we didn't request a version. That means we still want to fetch
  1046. # the document from the "catalog url" - but the catalog url is has
  1047. # a project_id suffix so is likely not going to work for us. Try
  1048. # fetching from the project-less versioned endpoint.
  1049. yield versioned_discovery
  1050. # As a final fallthrough case, return the actual unmodified url from
  1051. # the catalog.
  1052. yield self.catalog_url
  1053. def _get_catalog_discover_hack(self):
  1054. """Apply the catalog hacks and figure out an unversioned endpoint.
  1055. This function is internal to keystoneauth1.
  1056. :returns: A url that has been transformed by the regex hacks that
  1057. match the service_type.
  1058. """
  1059. return _VERSION_HACKS.get_discover_hack(self.service_type, self.url)
  1060. def get_discovery(session, url, cache=None, authenticated=False):
  1061. """Return the discovery object for a URL.
  1062. Check the session and the plugin cache to see if we have already
  1063. performed discovery on the URL and if so return it, otherwise create
  1064. a new discovery object, cache it and return it.
  1065. NOTE: This function is expected to be used by keystoneauth and should not
  1066. be needed by users part of normal usage. A normal user should use
  1067. get_endpoint or get_endpoint_data on `keystoneauth.session.Session` or
  1068. endpoint_filters on `keystoneauth.session.Session` or
  1069. `keystoneauth.session.Session`. However, should the user need to perform
  1070. direct discovery for some reason, this function should be used so that
  1071. the discovery caching is used.
  1072. :param session: A session object to discover with.
  1073. :type session: keystoneauth1.session.Session
  1074. :param str url: The url to lookup.
  1075. :param dict cache:
  1076. A dict to be used for caching results, in addition to caching them
  1077. on the Session. (optional) Defaults to None.
  1078. :param bool authenticated:
  1079. Include a token in the discovery call. (optional) Defaults to None,
  1080. which will use a token if an auth plugin is installed.
  1081. :raises keystoneauth1.exceptions.discovery.DiscoveryFailure:
  1082. if for some reason the lookup fails.
  1083. :raises keystoneauth1.exceptions.http.HttpError:
  1084. An error from an invalid HTTP response.
  1085. :returns: A discovery object with the results of looking up that URL.
  1086. :rtype: :py:class:`keystoneauth1.discover.Discovery`
  1087. """
  1088. # There are between one and three different caches. The user may have
  1089. # passed one in. There is definitely one on the session, and there is
  1090. # one on the auth plugin if the Session has an auth plugin.
  1091. caches = []
  1092. # If a cache was passed in, check it first.
  1093. if cache is not None:
  1094. caches.append(cache)
  1095. # If the session has a cache, check it second, since it could have been
  1096. # provided by the user at Session creation time.
  1097. if hasattr(session, '_discovery_cache'):
  1098. caches.append(session._discovery_cache)
  1099. # Finally check the auth cache associated with the Session.
  1100. if session.auth and hasattr(session.auth, '_discovery_cache'):
  1101. caches.append(session.auth._discovery_cache)
  1102. for cache in caches:
  1103. disc = cache.get(url)
  1104. if disc:
  1105. break
  1106. else:
  1107. disc = Discover(session, url, authenticated=authenticated)
  1108. # Whether we get one from fetching or from cache, set it in the
  1109. # caches. This assures that if we combine sessions and auth plugins
  1110. # that we don't make unnecesary calls.
  1111. if disc:
  1112. for cache in caches:
  1113. cache[url] = disc
  1114. return disc
  1115. class _VersionHacks(object):
  1116. """A container to abstract the list of version hacks.
  1117. This could be done as simply a dictionary but is abstracted like this to
  1118. make for easier testing.
  1119. """
  1120. def __init__(self):
  1121. self._discovery_data = {}
  1122. def add_discover_hack(self, service_type, old, new=''):
  1123. """Add a new hack for a service type.
  1124. :param str service_type: The service_type in the catalog.
  1125. :param re.RegexObject old: The pattern to use.
  1126. :param str new: What to replace the pattern with.
  1127. """
  1128. hacks = self._discovery_data.setdefault(service_type, [])
  1129. hacks.append((old, new))
  1130. def get_discover_hack(self, service_type, url):
  1131. """Apply the catalog hacks and figure out an unversioned endpoint.
  1132. :param str service_type: the service_type to look up.
  1133. :param str url: The original url that came from a service_catalog.
  1134. :returns: Either the unversioned url or the one from the catalog
  1135. to try.
  1136. """
  1137. for old, new in self._discovery_data.get(service_type, []):
  1138. new_string, number_of_subs_made = old.subn(new, url)
  1139. if number_of_subs_made > 0:
  1140. return new_string
  1141. return url
  1142. _VERSION_HACKS = _VersionHacks()
  1143. _VERSION_HACKS.add_discover_hack('identity', re.compile('/v2.0/?$'), '/')
  1144. def add_catalog_discover_hack(service_type, old, new):
  1145. """Add a version removal rule for a particular service.
  1146. Originally deployments of OpenStack would contain a versioned endpoint in
  1147. the catalog for different services. E.g. an identity service might look
  1148. like ``http://localhost:5000/v2.0``. This is a problem when we want to use
  1149. a different version like v3.0 as there is no way to tell where it is
  1150. located. We cannot simply change all service catalogs either so there must
  1151. be a way to handle the older style of catalog.
  1152. This function adds a rule for a given service type that if part of the URL
  1153. matches a given regular expression in *old* then it will be replaced with
  1154. the *new* value. This will replace all instances of old with new. It should
  1155. therefore contain a regex anchor.
  1156. For example the included rule states::
  1157. add_catalog_version_hack('identity', re.compile('/v2.0/?$'), '/')
  1158. so if the catalog retrieves an *identity* URL that ends with /v2.0 or
  1159. /v2.0/ then it should replace it simply with / to fix the user's catalog.
  1160. :param str service_type: The service type as defined in the catalog that
  1161. the rule will apply to.
  1162. :param re.RegexObject old: The regular expression to search for and replace
  1163. if found.
  1164. :param str new: The new string to replace the pattern with.
  1165. """
  1166. _VERSION_HACKS.add_discover_hack(service_type, old, new)