OpenStack Block Storage (Cinder)
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.

478 lines
18 KiB

# Copyright 2010 OpenStack Foundation
# All Rights Reserved.
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
import enum
import json
import os
import re
import urllib
from oslo_config import cfg
from oslo_log import log as logging
import webob
from cinder.api import api_utils
from cinder.api import microversions as mv
from cinder.common import constants
from cinder import exception
from cinder.i18n import _
api_common_opts = [
help='The maximum number of items that a collection '
'resource returns in a single response'),
help="Json file indicating user visible filter "
"parameters for list queries."),
CONF.import_opt('public_endpoint', 'cinder.api.views.versions')
LOG = logging.getLogger(__name__)
ATTRIBUTE_CONVERTERS = {'name~': 'display_name~',
'description~': 'display_description~'}
METADATA_TYPES = enum.Enum('METADATA_TYPES', 'user image')
def get_pagination_params(params, max_limit=None):
"""Return marker, limit, offset tuple from request.
:param params: `wsgi.Request`'s GET dictionary, possibly containing
'marker', 'limit', and 'offset' variables. 'marker' is the
id of the last element the client has seen, 'limit' is the
maximum number of items to return and 'offset' is the number
of items to skip from the marker or from the first element.
If 'limit' is not specified, or > max_limit, we default to
max_limit. Negative values for either offset or limit will
cause exc.HTTPBadRequest() exceptions to be raised. If no
offset is present we'll default to 0 and if no marker is
present we'll default to None.
:max_limit: Max value 'limit' return value can take
:returns: Tuple (marker, limit, offset)
max_limit = max_limit or CONF.osapi_max_limit
limit = _get_limit_param(params, max_limit)
marker = _get_marker_param(params)
offset = _get_offset_param(params)
return marker, limit, offset
def _get_limit_param(params, max_limit=None):
"""Extract integer limit from request's dictionary or fail.
Defaults to max_limit if not present and returns max_limit if present
'limit' is greater than max_limit.
max_limit = max_limit or CONF.osapi_max_limit
limit = int(params.pop('limit', max_limit))
except ValueError:
msg = _('limit param must be an integer')
raise webob.exc.HTTPBadRequest(explanation=msg)
if limit < 0:
msg = _('limit param must be positive')
raise webob.exc.HTTPBadRequest(explanation=msg)
limit = min(limit, max_limit)
return limit
def _get_marker_param(params):
"""Extract marker id from request's dictionary (defaults to None)."""
return params.pop('marker', None)
def _get_offset_param(params):
"""Extract offset id from request's dictionary (defaults to 0) or fail."""
offset = params.pop('offset', 0)
return api_utils.validate_integer(offset,
def limited(items, request, max_limit=None):
"""Return a slice of items according to requested offset and limit.
:param items: A sliceable entity
:param request: ``wsgi.Request`` possibly containing 'offset' and 'limit'
GET variables. 'offset' is where to start in the list,
and 'limit' is the maximum number of items to return. If
'limit' is not specified, 0, or > max_limit, we default
to max_limit. Negative values for either offset or limit
will cause exc.HTTPBadRequest() exceptions to be raised.
:kwarg max_limit: The maximum number of items to return from 'items'
max_limit = max_limit or CONF.osapi_max_limit
marker, limit, offset = get_pagination_params(request.GET.copy(),
range_end = offset + (limit or max_limit)
return items[offset:range_end]
def get_sort_params(params, default_key='created_at', default_dir='desc'):
"""Retrieves sort keys/directions parameters.
Processes the parameters to create a list of sort keys and sort directions
that correspond to either the 'sort' parameter or the 'sort_key' and
'sort_dir' parameter values. The value of the 'sort' parameter is a comma-
separated list of sort keys, each key is optionally appended with
Note that the 'sort_key' and 'sort_dir' parameters are deprecated in kilo
and an exception is raised if they are supplied with the 'sort' parameter.
The sort parameters are removed from the request parameters by this
:param params: webob.multidict of request parameters (from
:param default_key: default sort key value, added to the list if no
sort keys are supplied
:param default_dir: default sort dir value, added to the list if the
corresponding key does not have a direction
:returns: list of sort keys, list of sort dirs
:raise webob.exc.HTTPBadRequest: If both 'sort' and either 'sort_key' or
'sort_dir' are supplied parameters
if 'sort' in params and ('sort_key' in params or 'sort_dir' in params):
msg = _("The 'sort_key' and 'sort_dir' parameters are deprecated and "
"cannot be used with the 'sort' parameter.")
raise webob.exc.HTTPBadRequest(explanation=msg)
sort_keys = []
sort_dirs = []
if 'sort' in params:
for sort in params.pop('sort').strip().split(','):
sort_key, _sep, sort_dir = sort.partition(':')
if not sort_dir:
sort_dir = default_dir
sort_key = params.pop('sort_key', default_key)
sort_dir = params.pop('sort_dir', default_dir)
return sort_keys, sort_dirs
def get_request_url(request):
url = request.application_url
headers = request.headers
forwarded = headers.get('X-Forwarded-Host')
if forwarded:
url_parts = list(urllib.parse.urlsplit(url))
url_parts[1] = re.split(r',\s?', forwarded)[-1]
url = urllib.parse.urlunsplit(url_parts).rstrip('/')
return url
def remove_version_from_href(href):
"""Removes the first API version from the href.
Given: ''
Returns: ''
Given: ''
Returns: ''
Given: ''
Returns: ''
parsed_url = urllib.parse.urlsplit(href)
url_parts = parsed_url.path.split('/')
# NOTE: this should match vX.X or vX
expression = re.compile(r'^v([0-9]+|[0-9]+\.[0-9]+)(/.*|$)')
for x in range(len(url_parts)):
if expression.match(url_parts[x]):
del url_parts[x]
new_path = '/'.join(url_parts)
if new_path == parsed_url.path:
msg = 'href %s does not contain version' % href
raise ValueError(msg)
parsed_url = list(parsed_url)
parsed_url[2] = new_path
return urllib.parse.urlunsplit(parsed_url)
class ViewBuilder(object):
"""Model API responses as dictionaries."""
_collection_name = None
def _get_links(self, request, identifier):
return [{"rel": "self",
"href": self._get_href_link(request, identifier), },
{"rel": "bookmark",
"href": self._get_bookmark_link(request, identifier), }]
def _get_next_link(self, request, identifier, collection_name):
"""Return href string with proper limit and marker params."""
params = request.params.copy()
params["marker"] = identifier
prefix = self._update_link_prefix(get_request_url(request),
url = os.path.join(prefix,
return "%s?%s" % (url, urllib.parse.urlencode(params))
def _get_href_link(self, request, identifier):
"""Return an href string pointing to this object."""
prefix = self._update_link_prefix(get_request_url(request),
return os.path.join(prefix,
def _get_bookmark_link(self, request, identifier):
"""Create a URL that refers to a specific resource."""
base_url = remove_version_from_href(get_request_url(request))
base_url = self._update_link_prefix(base_url,
return os.path.join(base_url,
def _get_collection_links(self, request, items, collection_name,
item_count=None, id_key="uuid"):
"""Retrieve 'next' link, if applicable.
The next link is included if we are returning as many items as we can,
given the restrictions of limit optional request parameter and
osapi_max_limit configuration parameter as long as we are returning
some elements.
So we return next link if:
1) 'limit' param is specified and equal to the number of items.
2) 'limit' param is NOT specified and the number of items is
equal to CONF.osapi_max_limit.
:param request: API request
:param items: List of collection items
:param collection_name: Name of collection, used to generate the
next link for a pagination query
:param item_count: Length of the list of the original collection
:param id_key: Attribute key used to retrieve the unique ID, used
to generate the next link marker for a pagination query
:returns: links
item_count = item_count or len(items)
limit = _get_limit_param(request.GET.copy())
if len(items) and limit <= item_count:
return self._generate_next_link(items, id_key, request,
return []
def _generate_next_link(self, items, id_key, request,
links = []
last_item = items[-1]
if id_key in last_item:
last_item_id = last_item[id_key]
last_item_id = last_item["id"]
"rel": "next",
"href": self._get_next_link(request, last_item_id,
return links
def _update_link_prefix(self, orig_url, prefix):
if not prefix:
return orig_url
url_parts = list(urllib.parse.urlsplit(orig_url))
prefix_parts = list(urllib.parse.urlsplit(prefix))
url_parts[0:2] = prefix_parts[0:2]
url_parts[2] = prefix_parts[2] + url_parts[2]
return urllib.parse.urlunsplit(url_parts).rstrip('/')
def get_cluster_host(req, params, cluster_version=None):
"""Get cluster and host from the parameters.
This method checks the presence of cluster and host parameters and returns
them depending on the cluster_version.
If cluster_version is False we will never return the cluster_name and we
will require the presence of the host parameter.
If cluster_version is None we will always check for the presence of the
cluster parameter, and if cluster_version is a string with a version we
will only check for the presence of the parameter if the version of the
request is not less than it. In both cases we will require one and only
one parameter, host or cluster.
if (cluster_version is not False and
cluster_name = params.get('cluster')
msg = _('One and only one of cluster and host must be set.')
cluster_name = None
msg = _('Host field is missing.')
host = params.get('host')
if bool(cluster_name) == bool(host):
raise exception.InvalidInput(reason=msg)
return cluster_name, host
def _initialize_filters():
if not os.path.exists(CONF.resource_query_filters_file):
"resource query filters file does not exist: %s",
with open(CONF.resource_query_filters_file, 'r') as filters_file:
_FILTERS_COLLECTION = json.load(filters_file)
def get_enabled_resource_filters(resource=None):
"""Get list of configured/allowed filters for the specified resource.
This method checks resource_query_filters_file and returns dictionary
which contains the specified resource and its allowed filters:
.. code-block:: json
"resource": ["filter1", "filter2", "filter3"]
if resource is not specified, all of the configuration will be returned,
and if the resource is not found, empty dict will be returned.
if not resource:
return {resource: _FILTERS_COLLECTION[resource]}
except Exception:
LOG.debug("Failed to collect resource %s's filters.", resource)
return {}
def get_time_comparsion_operators():
"""Get list of time comparsion operators.
This method returns list which contains the allowed comparsion operators.
return ["gt", "gte", "eq", "neq", "lt", "lte"]
def convert_filter_attributes(filters, resource):
for key in filters.copy().keys():
if resource in ['volume', 'backup',
'snapshot'] and key in ATTRIBUTE_CONVERTERS.keys():
filters[ATTRIBUTE_CONVERTERS[key]] = filters[key]
def reject_invalid_filters(context, filters, resource,
invalid_filters = []
for key in filters.copy().keys():
# Only ASCII characters can be valid filter keys,
# in PY2/3, the key can be either unicode or string.
if isinstance(key, str):
except (UnicodeEncodeError, UnicodeDecodeError):
raise webob.exc.HTTPBadRequest(
explanation=_('Filter keys can only contain '
'ASCII characters.'))
if context.is_admin and resource not in ['pool']:
# Allow all options except resource is pool
# pool API is only available for admin
# Check the configured filters against those passed in resource
configured_filters = get_enabled_resource_filters(resource)
if configured_filters:
configured_filters = configured_filters[resource]
configured_filters = []
for key in filters.copy().keys():
if not enable_like_filter:
if key not in configured_filters:
# If 'key~' is configured, both 'key' and 'key~' are valid.
if not (key in configured_filters or
"%s~" % key in configured_filters):
if invalid_filters:
if 'all_tenants' in invalid_filters:
# NOTE: this is a special case: the cinderclient always adds
# 'all_tenants', so we don't want to hold that against a non-admin
# user and we silently ignore it. See Bug #1917574.
if len(invalid_filters) == 0:
raise webob.exc.HTTPBadRequest(
explanation=_('Invalid filters %s are found in query '
'options.') % ','.join(invalid_filters))
def process_general_filtering(resource):
def wrapper(process_non_general_filtering):
def _decorator(*args, **kwargs):
req_version = kwargs.get('req_version')
filters = kwargs.get('filters')
context = kwargs.get('context')
if req_version.matches(mv.RESOURCE_FILTER):
support_like = False
if req_version.matches(mv.LIKE_FILTER):
support_like = True
reject_invalid_filters(context, filters,
resource, support_like)
convert_filter_attributes(filters, resource)
process_non_general_filtering(*args, **kwargs)
return _decorator
return wrapper