kinto 19.5.0__py3-none-any.whl → 20.0.0__py3-none-any.whl

kinto/core/cornice/pyramidhook.py

@@ -0,0 +1,373 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this file,
+# You can obtain one at http://mozilla.org/MPL/2.0/.
+import copy
+import functools
+import itertools
+
+from pyramid.exceptions import PredicateMismatch
+from pyramid.httpexceptions import (
+    HTTPException,
+    HTTPMethodNotAllowed,
+    HTTPNotAcceptable,
+    HTTPUnsupportedMediaType,
+)
+from pyramid.security import NO_PERMISSION_REQUIRED
+
+from kinto.core.cornice.cors import (
+    CORS_PARAMETERS,
+    apply_cors_post_request,
+    get_cors_preflight_view,
+    get_cors_validator,
+)
+from kinto.core.cornice.errors import Errors
+from kinto.core.cornice.service import decorate_view
+from kinto.core.cornice.util import (
+    content_type_matches,
+    current_service,
+    is_string,
+    match_accept_header,
+    match_content_type_header,
+    to_list,
+)
+
+
+def get_fallback_view(service):
+    """Fallback view for a given service, called when nothing else matches.
+
+    This method provides the view logic to be executed when the request
+    does not match any explicitly-defined view.  Its main responsibility
+    is to produce an accurate error response, such as HTTPMethodNotAllowed,
+    HTTPNotAcceptable or HTTPUnsupportedMediaType.
+    """
+
+    def _fallback_view(request):
+        # Maybe we failed to match any definitions for the request method?
+        if request.method not in service.defined_methods:
+            response = HTTPMethodNotAllowed()
+            response.allow = service.defined_methods
+            raise response
+        # Maybe we failed to match an acceptable content-type?
+        # First search all the definitions to find the acceptable types.
+        # XXX: precalculate this like the defined_methods list?
+        acceptable = []
+        supported_contenttypes = []
+        for method, _, args in service.definitions:
+            if method != request.method:
+                continue
+
+            if "accept" in args:
+                acceptable.extend(service.get_acceptable(method, filter_callables=True))
+                acceptable.extend(request.info.get("acceptable", []))
+                acceptable = list(set(acceptable))
+
+                # Now check if that was actually the source of the problem.
+                if not request.accept.acceptable_offers(offers=acceptable):
+                    request.errors.add(
+                        "header",
+                        "Accept",
+                        "Accept header should be one of {0}".format(acceptable).encode("ascii"),
+                    )
+                    request.errors.status = HTTPNotAcceptable.code
+                    error = service.error_handler(request)
+                    raise error
+
+            if "content_type" in args:
+                supported_contenttypes.extend(
+                    service.get_contenttypes(method, filter_callables=True)
+                )
+                supported_contenttypes.extend(request.info.get("supported_contenttypes", []))
+                supported_contenttypes = list(set(supported_contenttypes))
+
+                # Now check if that was actually the source of the problem.
+                if not content_type_matches(request, supported_contenttypes):
+                    request.errors.add(
+                        "header",
+                        "Content-Type",
+                        "Content-Type header should be one of {0}".format(
+                            supported_contenttypes
+                        ).encode("ascii"),
+                    )
+                    request.errors.status = HTTPUnsupportedMediaType.code
+                    error = service.error_handler(request)
+                    raise error
+
+        # In the absence of further information about what went wrong,
+        # let upstream deal with the mismatch.
+
+        # After "custom predicates" feature has been added there is no need in
+        # this line. Instead requests will be filtered by  "custom predicates"
+        # feature filter and exception "404 Not found" error will be raised. In
+        # order to avoid unpredictable cases, we left this line in place and
+        # excluded it from coverage.
+        raise PredicateMismatch(service.name)  # pragma: no cover
+
+    return _fallback_view
+
+
+def apply_filters(request, response):
+    if request.matched_route is not None:
+        # do some sanity checking on the response using filters
+        service = current_service(request)
+        if service is not None:
+            kwargs, ob = getattr(request, "cornice_args", ({}, None))
+            for _filter in kwargs.get("filters", []):
+                if is_string(_filter) and ob is not None:
+                    _filter = getattr(ob, _filter)
+                try:
+                    response = _filter(response, request)
+                except TypeError:
+                    response = _filter(response)
+            if service.cors_enabled:
+                apply_cors_post_request(service, request, response)
+
+    return response
+
+
+def handle_exceptions(exc, request):
+    # At this stage, the checks done by the validators had been removed because
+    # a new response started (the exception), so we need to do that again.
+    if not isinstance(exc, HTTPException):
+        raise
+    request.info["cors_checked"] = False
+    return apply_filters(request, exc)
+
+
+def add_nosniff_header(request, response):
+    """IE has some rather unfortunately content-type-sniffing behaviour
+    that can be used to trigger XSS attacks via a JSON API, as described here:
+
+    * http://blog.watchfire.com/wfblog/2011/10/json-based-xss-exploitation.html
+    * https://superevr.com/blog/2012/exploiting-xss-in-ajax-web-applications/
+
+    Make cornice safe-by-default against this attack by including the header.
+    """
+    response.headers.setdefault("X-Content-Type-Options", "nosniff")
+
+
+def wrap_request(event):
+    """Adds a "validated" dict, a custom "errors" object and an "info" dict to
+    the request object if they don't already exists
+    """
+    request = event.request
+    request.add_response_callback(apply_filters)
+    request.add_response_callback(add_nosniff_header)
+
+    if not hasattr(request, "validated"):
+        setattr(request, "validated", {})
+
+    if not hasattr(request, "errors"):
+        if request.registry.settings.get("available_languages"):
+            setattr(request, "errors", Errors(localizer=request.localizer))
+        else:
+            setattr(request, "errors", Errors())
+
+    if not hasattr(request, "info"):
+        setattr(request, "info", {})
+
+
+def register_service_views(config, service):
+    """Register the routes of the given service into the pyramid router.
+
+    :param config: the pyramid configuration object that will be populated.
+    :param service: the service object containing the definitions
+    """
+    route_name = service.name
+    existing_route = service.pyramid_route
+    prefix = config.route_prefix or ""
+    services = config.registry.cornice_services
+    if existing_route:
+        route_name = existing_route
+        services["__cornice" + existing_route] = service
+    else:
+        services[prefix + service.path] = service
+
+    # before doing anything else, register a view for the OPTIONS method
+    # if we need to
+    if service.cors_enabled and "OPTIONS" not in service.defined_methods:
+        service.add_view(
+            "options", view=get_cors_preflight_view(service), permission=NO_PERMISSION_REQUIRED
+        )
+
+    # register the fallback view, which takes care of returning good error
+    # messages to the user-agent
+    cors_validator = get_cors_validator(service)
+
+    # Cornice-specific arguments that pyramid does not know about
+    cornice_parameters = (
+        "filters",
+        "validators",
+        "schema",
+        "klass",
+        "error_handler",
+        "deserializer",
+    ) + CORS_PARAMETERS
+
+    # 1. register route
+
+    route_args = {}
+
+    if hasattr(service, "factory"):
+        route_args["factory"] = service.factory
+
+    routes = config.get_predlist("route")
+    for predicate in routes.sorter.names:
+        # Do not let the custom predicates handle validation of Header Accept,
+        # which will pass it through to pyramid. It is handled by
+        # _fallback_view(), because it allows callable.
+        if predicate == "accept":
+            continue
+
+        if hasattr(service, predicate):
+            route_args[predicate] = getattr(service, predicate)
+
+    # register route when not using exiting pyramid routes
+    if not existing_route:
+        config.add_route(route_name, service.path, **route_args)
+
+    # 2. register view(s)
+
+    for method, view, args in service.definitions:
+        args = copy.copy(args)  # make a copy of the dict to not modify it
+        # Deepcopy only the params we're possibly passing on to pyramid
+        # (Some of those in cornice_parameters, e.g. ``schema``, may contain
+        # unpickleable values.)
+        for item in args:
+            if item not in cornice_parameters:
+                args[item] = copy.deepcopy(args[item])
+
+        args["request_method"] = method
+
+        if service.cors_enabled:
+            args["validators"].insert(0, cors_validator)
+
+        decorated_view = decorate_view(view, dict(args), method, route_args)
+
+        for item in cornice_parameters:
+            if item in args:
+                del args[item]
+
+        # filter predicates defined on Resource
+        route_predicates = config.get_predlist("route").sorter.names
+        view_predicates = config.get_predlist("view").sorter.names
+        for pred in set(route_predicates).difference(view_predicates):
+            if pred in args:
+                args.pop(pred)
+
+        # pop and compute predicates which get passed through to Pyramid 1:1
+
+        predicate_definitions = _pop_complex_predicates(args)
+
+        if predicate_definitions:
+            empty_contenttype = [({"kind": "content_type", "value": ""},)]
+            for predicate_list in predicate_definitions + empty_contenttype:
+                args = dict(args)  # make a copy of the dict to not modify it
+
+                # prepare view args by evaluating complex predicates
+                _mungle_view_args(args, predicate_list)
+
+                # We register the same view multiple times with different
+                # accept / content_type / custom_predicates arguments
+                config.add_view(view=decorated_view, route_name=route_name, **args)
+
+        else:
+            # it is a simple view, we don't need to loop on the definitions
+            # and just add it one time.
+            config.add_view(view=decorated_view, route_name=route_name, **args)
+
+    if service.definitions:
+        # Add the fallback view last
+        config.add_view(
+            view=get_fallback_view(service),
+            route_name=route_name,
+            permission=NO_PERMISSION_REQUIRED,
+            require_csrf=False,
+        )
+
+
+def _pop_complex_predicates(args):
+    """
+    Compute the cartesian product of "accept" and "content_type"
+    fields to establish all possible predicate combinations.
+
+    .. seealso::
+
+        https://github.com/mozilla-services/cornice/pull/91#discussion_r3441384
+    """
+
+    # pop and prepare individual predicate lists
+    accept_list = _pop_predicate_definition(args, "accept")
+    content_type_list = _pop_predicate_definition(args, "content_type")
+
+    # compute cartesian product of prepared lists, additionally
+    # remove empty elements of input and output lists
+    product_input = filter(None, [accept_list, content_type_list])
+
+    # In Python 3, the filter() function returns an iterator, not a list.
+    # http://getpython3.com/diveintopython3/ \
+    # porting-code-to-python-3-with-2to3.html#filter
+    predicate_product = list(filter(None, itertools.product(*product_input)))
+
+    return predicate_product
+
+
+def _pop_predicate_definition(args, kind):
+    """
+    Build a dictionary enriched by "kind" of predicate definition list.
+    This is required for evaluation in ``_mungle_view_args``.
+    """
+    values = to_list(args.pop(kind, ()))
+    # In much the same way as filter(), the map() function [in Python 3] now
+    # returns an iterator. (In Python 2, it returned a list.)
+    # http://getpython3.com/diveintopython3/ \
+    # porting-code-to-python-3-with-2to3.html#map
+    values = list(map(lambda value: {"kind": kind, "value": value}, values))
+    return values
+
+
+def _mungle_view_args(args, predicate_list):
+    """
+    Prepare view args by evaluating complex predicates
+    which get passed through to Pyramid 1:1.
+    Also resolve predicate definitions passed as callables.
+
+    .. seealso::
+
+        https://github.com/mozilla-services/cornice/pull/91#discussion_r3441384
+    """
+
+    # map kind of argument value to function for resolving callables
+    callable_map = {
+        "accept": match_accept_header,
+        "content_type": match_content_type_header,
+    }
+
+    # iterate and resolve all predicates
+    for predicate_entry in predicate_list:
+        kind = predicate_entry["kind"]
+        value = predicate_entry["value"]
+
+        # we need to build a custom predicate if argument value is a callable
+        predicates = args.get("custom_predicates", [])
+        if callable(value):
+            func = callable_map[kind]
+            predicate_checker = functools.partial(func, value)
+            predicates.append(predicate_checker)
+            args["custom_predicates"] = predicates
+        else:
+            # otherwise argument value is just a scalar
+            args[kind] = value
+
+
+def register_resource_views(config, resource):
+    """Register a resource and it's views.
+
+    :param config:
+        The pyramid configuration object that will be populated.
+    :param resource:
+        The resource class containing the definitions
+    """
+    services = resource._services
+
+    for service in services.values():
+        config.add_cornice_service(service)

kinto/core/cornice/renderer.py

@@ -0,0 +1,89 @@
+from pyramid import httpexceptions as exc
+from pyramid.renderers import JSON
+from pyramid.response import Response
+
+
+def bytes_adapter(obj, request):
+    """Convert bytes objects to strings for json error renderer."""
+    if isinstance(obj, bytes):
+        return obj.decode("utf8")
+    return obj
+
+
+class JSONError(exc.HTTPError):
+    def __init__(self, serializer, serializer_kw, errors, status=400):
+        body = {"status": "error", "errors": errors}
+        Response.__init__(self, serializer(body, **serializer_kw))
+        self.status = status
+        self.content_type = "application/json"
+
+
+class CorniceRenderer(JSON):
+    """We implement JSON serialization by extending Pyramid's default
+    JSON rendering machinery using our own custom Content-Type logic `[1]`_.
+
+    This allows developers to config the JSON renderer using Pyramid's
+    configuration machinery `[2]`_.
+
+      .. _`[1]`: https://github.com/mozilla-services/cornice/pull/116 \
+                 #issuecomment-14355865
+      .. _`[2]`: http://pyramid.readthedocs.io/en/latest/narr/renderers.html \
+                 #serializing-custom-objects
+    """
+
+    acceptable = ("application/json", "text/plain")
+
+    def __init__(self, *args, **kwargs):
+        """Adds a `bytes` adapter by default."""
+        super(CorniceRenderer, self).__init__(*args, **kwargs)
+        self.add_adapter(bytes, bytes_adapter)
+
+    def render_errors(self, request):
+        """Returns an HTTPError with the given status and message.
+
+        The HTTP error content type is "application/json"
+        """
+        default = self._make_default(request)
+        serializer_kw = self.kw.copy()
+        serializer_kw["default"] = default
+        return JSONError(
+            serializer=self.serializer,
+            serializer_kw=serializer_kw,
+            errors=request.errors,
+            status=request.errors.status,
+        )
+
+    def render(self, value, system):
+        """Extends the default `_render` function of the pyramid JSON renderer.
+
+        Compared to the default `pyramid.renderers.JSON` renderer:
+            1. Overrides the response with an empty string and
+               no Content-Type in case of HTTP 204.
+            2. Overrides the default behavior of Content-Type handling,
+               forcing the use of `acceptable_offers`, instead of letting
+               the user specify the Content-Type manually.
+               TODO: maybe explain this a little better
+        """
+        request = system.get("request")
+        if request is not None:
+            response = request.response
+
+            # Do not return content with ``204 No Content``
+            if response.status_code == 204:
+                response.content_type = None
+                return ""
+
+            ctypes = request.accept.acceptable_offers(offers=self.acceptable)
+            if not ctypes:
+                ctypes = [(self.acceptable[0], 1.0)]
+            response.content_type = ctypes[0][0]
+        default = self._make_default(request)
+        return self.serializer(value, default=default, **self.kw)
+
+    def __call__(self, info):
+        """Overrides the default behavior of `pyramid.renderers.JSON`.
+
+        Uses a public `render()` method instead of defining render inside
+        `__call__`, to let the user extend it if necessary.
+        """
+        return self.render

kinto/core/cornice/resource.py

@@ -0,0 +1,205 @@
+# -*- coding: utf-8 -*-
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this file,
+# You can obtain one at http://mozilla.org/MPL/2.0/.
+import functools
+import warnings
+
+import venusian
+
+from kinto.core.cornice import Service
+
+
+def resource(depth=2, **kw):
+    """Class decorator to declare resources.
+
+    All the methods of this class named by the name of HTTP resources
+    will be used as such. You can also prefix them by ``"collection_"`` and
+    they will be treated as HTTP methods for the given collection path
+    (collection_path), if any.
+
+    :param depth:
+        Which frame should be looked in default 2.
+
+    :param kw:
+        Keyword arguments configuring the resource.
+
+    Here is an example::
+
+        @resource(collection_path='/users', path='/users/{id}')
+    """
+
+    def wrapper(klass):
+        return add_resource(klass, depth, **kw)
+
+    return wrapper
+
+
+def add_resource(klass, depth=2, **kw):
+    """Function to declare resources of a Class.
+
+    All the methods of this class named by the name of HTTP resources
+    will be used as such. You can also prefix them by ``"collection_"`` and
+    they will be treated as HTTP methods for the given collection path
+    (collection_path), if any.
+
+    :param klass:
+        The class (resource) on which to register the service.
+
+    :param depth:
+        Which frame should be looked in default 2.
+
+    :param kw:
+        Keyword arguments configuring the resource.
+
+
+    Here is an example:
+
+    .. code-block:: python
+
+        class User(object):
+            pass
+
+        add_resource(User, collection_path='/users', path='/users/{id}')
+
+    Alternatively if you want to reuse your existing pyramid routes:
+
+    .. code-block:: python
+
+        class User(object):
+            pass
+
+        add_resource(User, collection_pyramid_route='users',
+            pyramid_route='user')
+
+    """
+
+    services = {}
+
+    if ("collection_pyramid_route" in kw or "pyramid_route" in kw) and (
+        "collection_path" in kw or "path" in kw
+    ):
+        raise ValueError("You use either paths or route names, not both")
+
+    if "collection_path" in kw:
+        if kw["collection_path"] == kw["path"]:
+            msg = "Warning: collection_path and path are not distinct."
+            warnings.warn(msg)
+
+        prefixes = ("", "collection_")
+    else:
+        prefixes = ("",)
+
+    if "collection_pyramid_route" in kw:
+        if kw["collection_pyramid_route"] == kw["pyramid_route"]:
+            msg = "Warning: collection_pyramid_route and pyramid_route are not distinct."
+            warnings.warn(msg)
+
+        prefixes = ("", "collection_")
+
+    for prefix in prefixes:
+        # get clean view arguments
+        service_args = {}
+        for k in list(kw):
+            if k.startswith("collection_"):
+                if prefix == "collection_":
+                    service_args[k[len(prefix) :]] = kw[k]
+            elif k not in service_args:
+                service_args[k] = kw[k]
+
+        # auto-wire klass as its own view factory, unless one
+        # is explicitly declared.
+        if "factory" not in kw:
+            service_args["factory"] = klass
+
+        # create service
+        service_name = service_args.pop("name", None) or klass.__name__.lower()
+        service_name = prefix + service_name
+        service = services[service_name] = Service(name=service_name, depth=depth, **service_args)
+        # ensure the service comes with the same properties as the wrapped
+        # resource
+        functools.update_wrapper(service, klass)
+
+        # initialize views
+        for verb in ("get", "post", "put", "delete", "options", "patch"):
+            view_attr = prefix + verb
+            meth = getattr(klass, view_attr, None)
+
+            if meth is not None:
+                # if the method has a __views__ arguments, then it had
+                # been decorated by a @view decorator. get back the name of
+                # the decorated method so we can register it properly
+                views = getattr(meth, "__views__", [])
+                if views:
+                    for view_args in views:
+                        service.add_view(verb, view_attr, klass=klass, **view_args)
+                else:
+                    service.add_view(verb, view_attr, klass=klass)
+
+    setattr(klass, "_services", services)
+
+    def callback(context, name, ob):
+        # get the callbacks registered by the inner services
+        # and call them from here when the @resource classes are being
+        # scanned by venusian.
+        for service in services.values():
+            config = context.config.with_package(info.module)
+            config.add_cornice_service(service)
+
+    info = venusian.attach(klass, callback, category="pyramid", depth=depth)
+
+    return klass
+
+
+def view(**kw):
+    """Method decorator to store view arguments when defining a resource with
+    the @resource class decorator
+
+    :param kw:
+        Keyword arguments configuring the view.
+    """
+
+    def wrapper(func):
+        return add_view(func, **kw)
+
+    return wrapper
+
+
+def add_view(func, **kw):
+    """Method to store view arguments when defining a resource with
+    the add_resource class method
+
+    :param func:
+        The func to hook to
+
+    :param kw:
+        Keyword arguments configuring the view.
+
+    Example:
+
+    .. code-block:: python
+
+        class User(object):
+
+            def __init__(self, request):
+                self.request = request
+
+            def collection_get(self):
+                return {'users': _USERS.keys()}
+
+            def get(self):
+                return _USERS.get(int(self.request.matchdict['id']))
+
+        add_view(User.get, renderer='json')
+        add_resource(User, collection_path='/users', path='/users/{id}')
+    """
+    # XXX needed in py2 to set on instancemethod
+    if hasattr(func, "__func__"):  # pragma: no cover
+        func = func.__func__
+    # store view argument to use them later in @resource
+    views = getattr(func, "__views__", None)
+    if views is None:
+        views = []
+        setattr(func, "__views__", views)
+    views.append(kw)
+    return func