diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b92f97..c10a4c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,52 @@ +## 1.5.0 (unreleased) +--------------------- + +- Add `flask_jsonapi.ViewSet`, `DetailView` and `ListView`: a layered way to declare a resource. A ViewSet declares + `allowed_actions`, `guards`, `object_permissions`, `middlewares` and one `data_service`, which run in a fixed + order: allowed actions and guards before the request body is parsed, then object permissions, middlewares and + the data service. `flask_jsonapi.guards` and `flask_jsonapi.middlewares` (`Middleware`, `build_pipeline`, + `CheckRequiredListFilters`) are new. +- Add `flask_jsonapi.permissions.ObjectPermissions` and `CheckObjectPermission` for the `object_permissions` slot. + `CheckObjectPermission` plugs an existing `PermissionChecker` into a ViewSet. Its `apply_permission_filter` + returns filters that restrict a list to the objects the client may list, and may raise `PermissionException` + (403) when the client's own filters ask for objects it may not list. `check_list_permission` runs on the listed + objects as a safety net: if it drops any, a warning is logged and the total is left out of the response. +- Add `flask_jsonapi.data_services`: HTTP-agnostic data services that raise their own exceptions + (`ResourceNotFound`, `PermissionDenied`, `InvalidData`, `Conflict`, ...), which a view translates to JSON:API + errors. Data services, middlewares and object permissions name their methods after the actions: `create`, + `read`, `list`, `update` and `destroy`. It includes a new `SqlAlchemyModelRepository` and + `LegacyRepositoryAdapter`, which lets a new ViewSet use a legacy repository (`PATCH` then answers 200 with a body + instead of 204). +- Add `flask_jsonapi.data_services.ListResult(items, total)`, which `list` returns: the items, and the number of + objects matching the filters before pagination, or `None`. A data service sets the total when the request asks + for a page. `ListView` calls `list` once per request and builds the pagination links from the total. Without a + total, `last` is `null` and `next` is present only for a full page. `SqlAlchemyModelRepository.list` counts and + slices one filtered query. `LegacyRepositoryAdapter.list` calls `get_count` only when the request asks for a page. +- Add `flask_jsonapi.resources.ListResourceBase`, the base class of `ResourceList` and `ListView`, and + `SizeNumberPagination.get_links_without_total`. A custom pagination class used by `ListView` must implement + `get_links` and `get_links_without_total`. +- Add `Actions.list`. `Actions.read_many` stays as an alias with the same value. +- Deprecate `ResourceRepositoryViewSet`, `ResourceRepositoryDetailView`, `ResourceRepositoryListView`, + `ProtectedViewSet`, `ProtectedDetailView`, `ProtectedListView`, the `AllowedActions*` mixins, `ResourceRepository` + and the legacy `SqlAlchemyModelRepository` (documented only, there are no runtime warnings). See the migration guide. +- Every error from a view is now a JSON:API error document, for legacy views too. Unexpected exceptions are logged and + rendered as a generic 500 without internal details, and `flask.abort()` keeps its status, title and headers (for + example `WWW-Authenticate`). An `abort()` carrying an explicit response returns that response unchanged. +- Flask app error handlers (`@app.errorhandler`) no longer run for exceptions raised inside flask-jsonapi views: + those become JSON:API errors, unexpected ones a generic 500. In testing mode such exceptions no longer reach the + test client either. +- Errors while dumping a GET response (`AttributeError`, `KeyError`, `ValueError` from a schema) are a generic 500 + without details instead of a 500 whose `detail` is the exception message. +- `HEAD` is served by the `GET` handler instead of failing with a 500. +- `PATCH` with a wrong resource `type` answers 409 Conflict instead of 500. +- JSON:API exception classes accept keyword arguments (`status`, `title`, `detail`, `source`). The old positional + forms still work. New exceptions: `Unauthorized`, `UnprocessableEntity` and `ServiceUnavailable`. +- `str(exc)` of a JSON:API exception is now its `detail`. Without a `source` argument, `ForbiddenError(...).source` + and `MethodNotAllowed(...).source` are now `None` instead of `{}`; `to_dict()` is unaffected. +- Empty `detail` and `source` are omitted from error objects. Tests that compare a whole error body to one with + `'source': {}` need updating. + + ## 1.4.2 (unreleased) --------------------- diff --git a/README.md b/README.md index 899a21a..48051e5 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ from sqlalchemy.ext.declarative import declarative_base from marshmallow_jsonapi import Schema, fields import flask_jsonapi -from flask_jsonapi.resource_repositories import sqlalchemy_repositories +from flask_jsonapi.data_services import sqlalchemy_repositories db_engine = sqlalchemy.create_engine('sqlite:///') session = scoped_session(sessionmaker(bind=db_engine)) @@ -51,7 +51,6 @@ Base.metadata.create_all(db_engine) class ArticleRepository(sqlalchemy_repositories.SqlAlchemyModelRepository): model = Article - instance_name = 'articles' session = session class ArticleSchema(Schema): @@ -60,18 +59,33 @@ class ArticleSchema(Schema): class Meta: type_ = 'articles' - strict = True -class ArticleRepositoryViewSet(flask_jsonapi.resource_repository_views.ResourceRepositoryViewSet): - schema = ArticleSchema - repository = ArticleRepository() +class ArticleViewSet(flask_jsonapi.ViewSet): + schema_class = ArticleSchema + data_service = ArticleRepository() + allowed_actions = { + flask_jsonapi.Actions.create, + flask_jsonapi.Actions.read, + flask_jsonapi.Actions.list, + flask_jsonapi.Actions.update, + flask_jsonapi.Actions.destroy, + } app = flask.Flask(__name__) api = flask_jsonapi.Api(app) -api.repository(ArticleRepositoryViewSet(), 'articles', '/articles/') +api.repository(ArticleViewSet(), 'articles', '/articles/') app.run(host='127.0.0.1', port=5000) ``` +`allowed_actions` lists what the endpoint serves; a ViewSet that does not declare it serves nothing. A ViewSet can +also declare `guards` (request checks such as authentication), `object_permissions` (row-level permissions, for +example a `flask_jsonapi.permissions.CheckObjectPermission`) and `middlewares` around its `data_service`. The data +service has one method per action: `create`, `read`, `list`, `update` and `destroy`. `list` returns a +`flask_jsonapi.data_services.ListResult` with the items and, when the client asks for a page, their total. +The [documentation](https://flask-jsonapi.readthedocs.io/) describes every layer, and the +[guide](https://flask-jsonapi.readthedocs.io/en/latest/guide.html) shows how to add authentication, permissions and +business logic, and builds a complete application. + ### Usage Create a new `Article` with title “First article”: diff --git a/docs/examples/full_example.py b/docs/examples/full_example.py new file mode 100644 index 0000000..f552e35 --- /dev/null +++ b/docs/examples/full_example.py @@ -0,0 +1,157 @@ +import flask +import sqlalchemy +import sqlalchemy.orm + +from marshmallow_jsonapi import Schema +from marshmallow_jsonapi import fields + +import flask_jsonapi + +from flask_jsonapi import exceptions +from flask_jsonapi import guards +from flask_jsonapi import permissions +from flask_jsonapi.data_services import sqlalchemy_repositories + +# One in-memory database shared by every thread of the development server. +engine = sqlalchemy.create_engine( + 'sqlite://', poolclass=sqlalchemy.pool.StaticPool, connect_args={'check_same_thread': False}, +) +session = sqlalchemy.orm.scoped_session(sqlalchemy.orm.sessionmaker(bind=engine)) +Base = sqlalchemy.orm.declarative_base() + + +class Author(Base): + __tablename__ = 'authors' + id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True) + name = sqlalchemy.Column(sqlalchemy.String, nullable=False) + + +class Article(Base): + __tablename__ = 'articles' + id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True) + title = sqlalchemy.Column(sqlalchemy.String, nullable=False) + body = sqlalchemy.Column(sqlalchemy.String, nullable=False, default='') + author_id = sqlalchemy.Column(sqlalchemy.Integer, sqlalchemy.ForeignKey('authors.id'), nullable=False) + author = sqlalchemy.orm.relationship(Author) + + +class AuthorSchema(Schema): + id = fields.Int(as_string=True) + name = fields.Str(required=True) + + class Meta: + type_ = 'authors' + + +class ArticleSchema(Schema): + id = fields.Int(as_string=True) + title = fields.Str(required=True) + body = fields.Str() + author = fields.Relationship( + type_='authors', include_resource_linkage=True, schema='AuthorSchema', dump_only=True, + ) + + class Meta: + type_ = 'articles' + + +class AuthorRepository(sqlalchemy_repositories.SqlAlchemyModelRepository): + model = Author + session = session + + +class ArticleRepository(sqlalchemy_repositories.SqlAlchemyModelRepository): + model = Article + session = session + + +# Fixed tokens for the example only. A real application checks a token against its identity provider. +DEMO_TOKENS = { + 'alice-token': 1, + 'bob-token': 2, +} + + +def current_author_id(): + scheme, _, token = flask.request.headers.get('Authorization', '').partition(' ') + if scheme != 'Bearer': + return None + return DEMO_TOKENS.get(token) + + +class RequireToken(guards.Guard): + def check(self, action): + if current_author_id() is None: + raise exceptions.Unauthorized(detail='A valid bearer token is required.') + + +class AuthorCanChange(permissions.PermissionChecker): + def check_create_permission(self, *, data): + return {**data, 'author_id': current_author_id()} + + def check_read_permission(self, *, resource): + return resource + + def check_update_permission(self, *, resource, data): + return self._check_author(resource), data + + def check_destroy_permission(self, *, resource): + return self._check_author(resource) + + @staticmethod + def _check_author(article): + if article.author_id != current_author_id(): + raise permissions.PermissionException(detail='Only the author can change an article.') + return article + + +class AuthorPermissions(permissions.CheckObjectPermission): + permission_checker = AuthorCanChange() + + def apply_permission_filter(self, filters): + return dict(filters) + + +class AuthorViewSet(flask_jsonapi.ViewSet): + schema_class = AuthorSchema + data_service = AuthorRepository() + allowed_actions = { + flask_jsonapi.Actions.read, + flask_jsonapi.Actions.list, + } + guards = [RequireToken()] + + +class ArticleViewSet(flask_jsonapi.ViewSet): + schema_class = ArticleSchema + data_service = ArticleRepository() + allowed_actions = { + flask_jsonapi.Actions.create, + flask_jsonapi.Actions.read, + flask_jsonapi.Actions.list, + flask_jsonapi.Actions.update, + } + guards = [RequireToken()] + object_permissions = AuthorPermissions() + + +app = flask.Flask(__name__) +api = flask_jsonapi.Api(app) +api.repository(AuthorViewSet(), 'authors', '/authors/') +api.repository(ArticleViewSet(), 'articles', '/articles/') + + +@app.teardown_appcontext +def remove_session(exception): + session.remove() + + +def create_database(): + Base.metadata.create_all(engine) + session.add_all([Author(id=1, name='Alice'), Author(id=2, name='Bob')]) + session.commit() + + +if __name__ == '__main__': + create_database() + app.run(host='127.0.0.1', port=5000) diff --git a/docs/filtering.rst b/docs/filtering.rst index 401c2ac..75be037 100644 --- a/docs/filtering.rst +++ b/docs/filtering.rst @@ -7,7 +7,8 @@ Flask-jsonapi supports resource filtering. **Note:** -All results of examples are ``filters`` parameter passed to ``read_many`` method of ``ResourceList`` or ``get_list`` method of ``ResourceRepositoryViewSet``. +All results of examples are the ``filters`` parameter passed to the ``list`` method of a data +service, to ``read_many`` of ``ResourceList`` or to ``get_list`` of a legacy repository. Simple Usage diff --git a/docs/guide.rst b/docs/guide.rst new file mode 100644 index 0000000..ee3a78a --- /dev/null +++ b/docs/guide.rst @@ -0,0 +1,576 @@ +Guide +===== + +This page shows how to build an API with :class:`flask_jsonapi.ViewSet`: what the design gives you, short recipes +for common tasks and one complete application. :doc:`view_sets`, :doc:`views` and :doc:`layers` are the reference +for every part. + +Strong points +------------- + +* Each layer has one job and knows nothing about the others. +* The order of the layers is fixed, and one ViewSet declaration shows all of them. +* Allowed actions and guards run before any input is parsed. +* Object permissions have their own slot and always run before every middleware. +* A ViewSet serves nothing it does not declare: ``allowed_actions`` defaults to empty. +* Data services carry no HTTP and can be called from anywhere: tasks, scripts, tests. +* A list and its total come from one call, so every filter a layer adds applies to both. +* Every exception raised in a layer reaches the client as a JSON:API error document, with an honest status and + no internal details. +* The object of a detail request is loaded once and handed to ``update`` and ``destroy``. +* One declaration can be reused for another audience by subclassing. + +A request passes the layers in this order: + +.. code-block:: text + + request + -> headers 406, 415 for a wrong Accept or Content-Type header + -> allowed actions 405 if the ViewSet does not declare the action + -> guards 401, 403, ... raised by your checks + -> parsing 400, 409, 422 for a bad query string or body + -> object permissions 403 for a call the client has no right to make + -> middlewares wrap every call to the data service + -> data service loads and stores the data; 404, 409, 422, 503 from its exceptions + response + +See :ref:`layers-request-flow` for the exact steps of every HTTP method. + +How to +------ + +The recipes build on each other. Names that a recipe uses without defining, such as ``ArticleSchema`` or +``ArticleRepository``, are defined in an earlier recipe or in the :ref:`full example `. + +Serve a read-only resource +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + import flask_jsonapi + + + class AuthorViewSet(flask_jsonapi.ViewSet): + schema_class = AuthorSchema + data_service = AuthorRepository() + allowed_actions = {flask_jsonapi.Actions.read, flask_jsonapi.Actions.list} + + + api = flask_jsonapi.Api(app) + api.repository(AuthorViewSet(), 'authors', '/authors/') + +``GET /authors/`` and ``GET /authors/1/`` are served. ``POST``, ``PATCH`` and ``DELETE`` answer ``405``. + +Require authentication +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + import flask + + from flask_jsonapi import exceptions + from flask_jsonapi import guards + + + class RequireToken(guards.Guard): + def check(self, action): + if not token_is_valid(flask.request.headers.get('Authorization')): + raise exceptions.Unauthorized(detail='A valid token is required.') + +Add it to the ViewSet with ``guards = [RequireToken()]``. ``token_is_valid`` stands for your own check. A request +without a valid token answers ``401`` before its body is read. ``check`` receives the action, for example +``flask_jsonapi.Actions.list``, so a guard can treat reads and writes differently. + +Allow a client to see and change only what it owns +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from flask_jsonapi import permissions + + + class AuthorChecker(permissions.PermissionChecker): + def check_create_permission(self, *, data): + return {**data, 'author_id': current_author_id()} + + def check_read_permission(self, *, resource): + if resource.author_id != current_author_id(): + raise permissions.PermissionException(detail='This article belongs to someone else.') + return resource + + def check_update_permission(self, *, resource, data): + return resource, data + + def check_destroy_permission(self, *, resource): + return resource + + + class OwnArticles(permissions.CheckObjectPermission): + permission_checker = AuthorChecker() + + def apply_permission_filter(self, filters): + return {**filters, 'author_id': current_author_id()} + +Add it with ``object_permissions = OwnArticles()``. ``current_author_id()`` stands for the way your application +identifies the client; it reads the request on every call, because one ``OwnArticles`` instance serves all requests +(see :ref:`view-sets-instances`). A new article gets the client as its author, the list shows only the client's articles +(and the pagination total includes only those), and ``GET``, ``PATCH`` or ``DELETE`` on someone else's article +answers ``403``. The update and delete checks pass the object through, because ``PATCH`` and ``DELETE`` load it +through ``read`` first, which already ran ``check_read_permission``. + +``apply_permission_filter`` returns filters that restrict the list to what the client may list. It may also raise +``PermissionException`` when the client's own filters ask for objects it may not list, and the request answers +``403``. ``check_list_permission`` then runs on the listed objects as a safety net: if it drops any, the response +leaves out the total and a warning is logged. See :ref:`layers-permission-filter`. + +Require a filter on a list +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + import flask_jsonapi + + from flask_jsonapi import middlewares + + + class CommentFilterSchema(flask_jsonapi.FilterSchema): + article_id = flask_jsonapi.FilterField() + + + class CommentViewSet(flask_jsonapi.ViewSet): + schema_class = CommentSchema + data_service = CommentRepository() + filter_schema = CommentFilterSchema() + allowed_actions = {flask_jsonapi.Actions.list} + middlewares = [middlewares.CheckRequiredListFilters(['article_id'])] + +``GET /comments/?filter[article_id]=1`` lists the comments of one article. ``GET /comments/`` answers ``400`` +with the detail ``"article_id" filter is required``. + +Add a filter from the request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + import flask + + from flask_jsonapi import middlewares + + + class InClientLanguage(middlewares.Middleware): + def list(self, *, filters, inner, **kwargs): + return inner.list(filters=self.with_language(filters), **kwargs) + + @staticmethod + def with_language(filters): + language = flask.request.accept_languages.best_match(['en', 'pl'], default='en') + return {**filters, 'language': language} + +The list shows the articles in the language of the ``Accept-Language`` header, and the pagination total includes +only those articles. Build a new dict and leave ``filters`` unchanged. + +Record changes +~~~~~~~~~~~~~~ + +.. code-block:: python + + import logging + + from flask_jsonapi import middlewares + + audit_log = logging.getLogger('audit') + + + class RecordChanges(middlewares.Middleware): + def update(self, *, resource, data, inner): + before = {key: getattr(resource, key) for key in data} + result = inner.update(resource=resource, data=data) + audit_log.info('Article %s changed from %r to %r.', resource.id, before, data) + return result + +If ``inner.update`` raises, the exception propagates and the code after it does not run. +Object permissions run before every middleware, so with ``object_permissions = OwnArticles()`` and +``middlewares = [RecordChanges()]`` a forbidden change stops at ``OwnArticles`` and is never recorded. + +Run business logic as a data service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from flask_jsonapi import data_services + + + class EmptyArticle(data_services.InvalidData): + pass + + + class PublishArticle(data_services.DataService): + def __init__(self, repository): + self.repository = repository + + def read(self, *, id): + return self.repository.read(id=id) + + def update(self, *, resource, data): + if not resource.body: + raise EmptyArticle('An empty article cannot be published.', field='body') + return self.repository.update(resource=resource, data={'published': True}) + +Serve it from its own ViewSet: + +.. code-block:: python + + class ArticlePublicationViewSet(flask_jsonapi.ViewSet): + schema_class = ArticleSchema + data_service = PublishArticle(ArticleRepository()) + allowed_actions = {flask_jsonapi.Actions.update} + guards = [RequireToken()] + object_permissions = OwnArticles() + + + api.repository(ArticlePublicationViewSet(), 'article_publications', '/article-publications/') + +``PATCH /article-publications/1/`` publishes the article, or answers ``422`` with ``source.pointer`` set to +``/data/attributes/body``. The view picks the status from the base class of the exception, see +:ref:`layers-errors`. ``PublishArticle`` touches no HTTP, so a script or a task can call it directly: +``PublishArticle(ArticleRepository()).update(resource=article, data={})``. + +.. _guide-list-source: + +Serve a list from a source of your own +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from flask_jsonapi import data_services + + + class ArticleSearch(data_services.DataService): + def __init__(self, index): + self.index = index + + def list(self, *, filters, sorting, pagination): + hits = self.index.search(filters.get('text', ''), sorting) + if not pagination: + return data_services.ListResult(hits, total=None) + start = (pagination['number'] - 1) * pagination['size'] + return data_services.ListResult(hits[start:start + pagination['size']], total=len(hits)) + +``index`` stands for a search index of your own. ``list`` returns a ``ListResult`` with the objects of the page and +the number of all matches. Set the total whenever the request asks for a page: the list view builds the ``last`` +link from it. With ``total=None`` the ``last`` link is ``null``, and ``next`` is present only after a full page. + +Compute a field for the response +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from marshmallow_jsonapi import Schema + from marshmallow_jsonapi import fields + + + class ArticleSchema(Schema): + id = fields.Int(as_string=True) + title = fields.Str(required=True) + body = fields.Str() + word_count = fields.Method('count_words', dump_only=True) + + class Meta: + type_ = 'articles' + + def count_words(self, article): + return len((article.body or '').split()) + +``word_count`` is dump-only: responses include it and requests cannot set it. The schema computes it once per +object in the response, so middlewares and data services never deal with presentation. + +Expose the same resource to another audience +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + class InternalArticleViewSet(ArticleViewSet): + allowed_actions = {*ArticleViewSet.allowed_actions, flask_jsonapi.Actions.destroy} + guards = [] + object_permissions = None + + + api.repository(ArticleViewSet(), 'articles', '/articles/') + api.repository(InternalArticleViewSet(), 'internal_articles', '/internal/articles/') + +The internal endpoint serves other services of your network, so expose it only there. It keeps the schema, the +filters, the middlewares and the data service, asks for no token, shows every article and adds ``DELETE``. A +subclass replaces ``allowed_actions``, ``guards``, ``object_permissions`` and ``middlewares``; nothing is merged, +and what it does not set it inherits. To extend an inherited list, write it out: +``middlewares = [*ArticleViewSet.middlewares, RecordChanges()]``. + +Use the SQLAlchemy repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from flask_jsonapi.data_services import sqlalchemy_repositories + + + class ArticleRepository(sqlalchemy_repositories.SqlAlchemyModelRepository): + model = Article + session = session + + def get_query(self): + return super().get_query().filter(Article.deleted_at.is_(None)) + +``read`` and ``list`` both start from ``get_query``, so a deleted article is not +listed, not part of a total and not found. Every write takes a ``strategy``, ``'commit'`` by default: + +.. code-block:: python + + articles = ArticleRepository() + revisions = RevisionRepository() + + article = articles.create(data={'title': 'Draft'}, strategy='flush') + revisions.create(data={'article_id': article.id, 'title': article.title}) + +``'flush'`` sends the insert and assigns ``article.id`` without committing. The second write commits both, +because both repositories use the same session (``RevisionRepository`` is another repository on it). Database +errors become data service exceptions, for example a unique constraint violation becomes ``Conflict`` and answers +``409``. + +.. _guide-full-example: + +Full example +------------ + +A complete application with two resources, authors and articles. Every client with a token can read authors and +articles. A client creates articles as their author, and only the author can change an article. Articles cannot be +deleted. + +.. literalinclude:: examples/full_example.py + :language: python + +The parts, from the top: + +* ``Author`` and ``Article`` are SQLAlchemy models; an article belongs to an author. ``ArticleSchema`` dumps the + author as a relationship, so ``GET /articles/1/?include=author`` includes it. +* ``current_author_id()`` identifies the client by the ``Authorization: Bearer `` header. The tokens are + fixed for the example. +* ``RequireToken`` is a guard: a request without a known token answers ``401``. +* ``AuthorPermissions`` is a ``CheckObjectPermission`` with the ``AuthorCanChange`` checker, set as the + ``object_permissions`` of ``ArticleViewSet``. A new article gets the client as its author, and ``PATCH`` by anyone + else answers ``403``. Every article is readable, so ``apply_permission_filter`` adds no filter. +* ``AuthorViewSet`` serves reads only. ``ArticleViewSet`` serves create, read, list and update, not delete. +* ``ArticleSchema`` loads ``data.id``, so a client may choose an article's id on ``POST``. An id that is already + in use answers ``409``. +* ``remove_session`` closes the session at the end of every request. + +Install the library with SQLAlchemy support and run the file: + +.. code-block:: bash + + pip install 'flask-jsonapi[sqlalchemy]' + python full_example.py + +An ``Accept`` header, when present, must be exactly ``application/vnd.api+json`` (``406`` otherwise). curl sends +``Accept: */*`` by default, so the requests below set it. ``POST`` and ``PATCH`` also need +``Content-Type: application/vnd.api+json`` (``415`` otherwise). +The responses below are formatted for reading. + +A request without a token: + +.. code-block:: bash + + curl -H 'Accept: application/vnd.api+json' http://localhost:5000/articles/ + +``401 Unauthorized``: + +.. code-block:: json + + { + "errors": [ + { + "status": 401, + "title": "Unauthorized", + "detail": "A valid bearer token is required." + } + ], + "jsonapi": { + "version": "1.0" + } + } + +Alice creates an article: + +.. code-block:: bash + + curl -H 'Accept: application/vnd.api+json' \ + -H 'Content-Type: application/vnd.api+json' \ + -H 'Authorization: Bearer alice-token' \ + http://localhost:5000/articles/ \ + --data '{"data": {"type": "articles", "attributes": {"title": "Hello", "body": "First post."}}}' + +``201 Created``: + +.. code-block:: json + + { + "data": { + "type": "articles", + "id": "1", + "attributes": { + "title": "Hello", + "body": "First post." + }, + "relationships": { + "author": { + "data": { + "type": "authors", + "id": "1" + } + } + } + }, + "jsonapi": { + "version": "1.0" + } + } + +Bob lists the articles: + +.. code-block:: bash + + curl -H 'Accept: application/vnd.api+json' \ + -H 'Authorization: Bearer bob-token' \ + http://localhost:5000/articles/ + +``200 OK``: + +.. code-block:: json + + { + "data": [ + { + "type": "articles", + "id": "1", + "attributes": { + "title": "Hello", + "body": "First post." + }, + "relationships": { + "author": { + "data": { + "type": "authors", + "id": "1" + } + } + } + } + ], + "meta": { + "count": 1 + }, + "jsonapi": { + "version": "1.0" + } + } + +Bob asks for the first page, one article per page (``-g`` stops curl from reading the brackets as a pattern): + +.. code-block:: bash + + curl -g -H 'Accept: application/vnd.api+json' \ + -H 'Authorization: Bearer bob-token' \ + 'http://localhost:5000/articles/?page[size]=1&page[number]=1' + +``200 OK``, with the pagination links built from the total. There is only one article, so ``next`` is ``null`` +and ``last`` is the first page: + +.. code-block:: json + + { + "data": [ + { + "type": "articles", + "id": "1", + "attributes": { + "title": "Hello", + "body": "First post." + }, + "relationships": { + "author": { + "data": { + "type": "authors", + "id": "1" + } + } + } + } + ], + "links": { + "self": "http://localhost:5000/articles/?page[size]=1&page[number]=1", + "first": "http://localhost:5000/articles/?page[size]=1&page[number]=1", + "previous": null, + "next": null, + "last": "http://localhost:5000/articles/?page[size]=1&page[number]=1" + }, + "meta": { + "count": 1 + }, + "jsonapi": { + "version": "1.0" + } + } + +Bob tries to change Alice's article: + +.. code-block:: bash + + curl -X PATCH \ + -H 'Accept: application/vnd.api+json' \ + -H 'Content-Type: application/vnd.api+json' \ + -H 'Authorization: Bearer bob-token' \ + http://localhost:5000/articles/1/ \ + --data '{"data": {"type": "articles", "id": "1", "attributes": {"title": "Mine now"}}}' + +``403 Forbidden``, and the article keeps its title: + +.. code-block:: json + + { + "errors": [ + { + "status": 403, + "title": "Forbidden", + "detail": "Only the author can change an article." + } + ], + "jsonapi": { + "version": "1.0" + } + } + +Alice tries to delete her article, which ``ArticleViewSet`` does not declare: + +.. code-block:: bash + + curl -X DELETE \ + -H 'Accept: application/vnd.api+json' \ + -H 'Authorization: Bearer alice-token' \ + http://localhost:5000/articles/1/ + +``405 Method Not Allowed``: + +.. code-block:: json + + { + "errors": [ + { + "status": 405, + "title": "Method not allowed", + "detail": "Delete is not allowed for this resource" + } + ], + "jsonapi": { + "version": "1.0" + } + } + +These requests and responses are checked by ``tests/test_docs_full_example.py``. diff --git a/docs/index.rst b/docs/index.rst index 8554555..654dcbd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,8 +33,11 @@ Flask-jsonapi implements the following parts of the JSON API specification: * **sparse fieldsets** [`specification `__] * **links** [`specification `__] - resolved by marshmallow-jsonapi (`docs `__) * **error objects** [`specification `__] -* **resource-level permissions** - view-level decorators support in ViewSets -* **object-level permissions** - interfaces added in [`#43 `__] +* **allowed actions** - a ViewSet declares which actions it serves, see :doc:`view_sets` +* **resource-level permissions** - guards run before the request body is parsed, see :doc:`layers` +* **business logic** - middlewares wrap the data service, see :doc:`layers` +* **object-level permissions** - the ``object_permissions`` of a ViewSet check every call to the data service, + see :doc:`layers` Not implemented yet: @@ -46,13 +49,15 @@ Architecture Flow through layers beginning with an HTTP Request and ending with an HTTP Response:: - Schema - 🡙 - [HTTP Request] -> [Flask Routing] -> ViewSet -> View -> Repository -> ( ) - ( Storage ) - [HTTP Response] <- View <- Repository <- ( ) - 🡙 - Schema + [HTTP Request] -> [Flask Routing] -> View -> Allowed actions -> Guards + -> Object permissions -> Middlewares -> Data service -> Storage + + [HTTP Response] <- View <- Object permissions <- Middlewares <- Data service <- Storage + +The View parses the request and dumps the response with the Schema. + +Every layer is described in :doc:`layers`. ``ResourceRepositoryViewSet`` and ``ProtectedViewSet`` are deprecated +since 1.5.0, see :doc:`migration`. Installation ------------ @@ -83,7 +88,7 @@ Configuration from marshmallow_jsonapi import Schema, fields import flask_jsonapi - from flask_jsonapi.resource_repositories import sqlalchemy_repositories + from flask_jsonapi.data_services import sqlalchemy_repositories db_engine = sqlalchemy.create_engine('sqlite:///') session = scoped_session(sessionmaker(bind=db_engine)) @@ -99,7 +104,6 @@ Configuration class ArticleRepository(sqlalchemy_repositories.SqlAlchemyModelRepository): model = Article - instance_name = 'articles' session = session class ArticleSchema(Schema): @@ -108,17 +112,26 @@ Configuration class Meta: type_ = 'articles' - strict = True - class ArticleRepositoryViewSet(flask_jsonapi.resource_repository_views.ResourceRepositoryViewSet): - schema = ArticleSchema - repository = ArticleRepository() + class ArticleViewSet(flask_jsonapi.ViewSet): + schema_class = ArticleSchema + data_service = ArticleRepository() + allowed_actions = { + flask_jsonapi.Actions.create, + flask_jsonapi.Actions.read, + flask_jsonapi.Actions.list, + flask_jsonapi.Actions.update, + flask_jsonapi.Actions.destroy, + } app = flask.Flask(__name__) api = flask_jsonapi.Api(app) - api.repository(ArticleRepositoryViewSet(), 'articles', '/articles/') + api.repository(ArticleViewSet(), 'articles', '/articles/') app.run(host='127.0.0.1', port=5000) +``allowed_actions`` lists what the endpoint serves; a ViewSet that does not declare it serves nothing. +Guards, object permissions, middlewares and data services are described in :doc:`layers`. + Usage ~~~~~ @@ -186,9 +199,12 @@ Table of Contents :maxdepth: 3 Overview + guide tutorial view_sets views + layers + migration repositories including_relationships sparse_fieldsets diff --git a/docs/layers.rst b/docs/layers.rst new file mode 100644 index 0000000..ffd6e74 --- /dev/null +++ b/docs/layers.rst @@ -0,0 +1,571 @@ +Layers +====== + +.. versionadded:: 1.5.0 + +A :doc:`ViewSet ` declares a resource as a stack of small layers. Each layer has one job and knows +nothing about the layers around it: + +.. code-block:: text + + [HTTP request] + | + [Accept and Content-Type header checks] (406, 415) + | + allowed actions - is this action served at all? (405) + | + guards - may this request be served at all? (401, 403, ...) + | + [body or query string parsing] + | + object permissions - check every call against the client's rights (403) + | + middlewares - wrap every call to the data service + | + data service - loads and stores the data + | + [storage] + +This page describes every layer, the order they run in and the errors they produce. + +.. _layers-request-flow: + +Request flow +------------ + +The order of the steps is fixed. No attribute of the ViewSet can change it: + +1. Header checks: ``406`` for an ``Accept`` header other than ``application/vnd.api+json``, ``415`` for a + ``POST`` or ``PATCH`` with a wrong ``Content-Type``. +2. Allowed actions: ``405`` if the ViewSet does not declare the action. +3. Guards, in list order. +4. Parsing of the body, or of the filters, sorting and pagination of a list. ``include`` and ``fields`` are + parsed when the response is dumped. +5. Object permissions, when ``object_permissions`` is set. +6. Middlewares, in list order. +7. The data service. + +Steps 5 to 7 form the pipeline, which the view calls with the methods listed in :ref:`layers-actions`. Allowed +actions and guards run **before** the request body is parsed, so a request that is not allowed or not +authenticated is rejected without looking at its payload. + +The calls of every HTTP method: + +List view, ``GET``: + +1. ``allowed_actions`` check (``405`` if ``Actions.list`` is not allowed). +2. Guards, in list order. +3. Query string parsing: filters, sorting, pagination. +4. ``pipeline.list(filters=..., sorting=..., pagination=...)``, once. It returns a ``ListResult``; the response + holds its items, and the pagination links are built from its total, see :ref:`layers-list-results`. + +List view, ``POST``: allowed actions, guards, body parsing, ``pipeline.create(data=...)``, ``201``. + +Detail view: + +* ``GET``: allowed actions, guards, ``resource = pipeline.read(id=id)``, dump. +* ``PATCH``: allowed actions, guards, check that the ``id`` in the body matches the URL (``409`` if it does not), + body parsing, ``resource = pipeline.read(id=id)``, ``pipeline.update(resource=resource, data=data)``. + The answer is ``200`` with the dumped result, or ``204`` if the data service returned ``None``. +* ``DELETE``: allowed actions, guards, ``resource = pipeline.read(id=id)``, + ``pipeline.destroy(resource=resource)``, ``204``. + +On detail actions the object is loaded exactly once per request and handed down as ``resource``. The load in +``PATCH`` and ``DELETE`` goes through the pipeline like any other call, so the object permissions check read +permission when the object is loaded and update or delete permission when it is handed down: you must be able to +see an object to change it. + +.. _layers-actions: + +Allowed actions +--------------- + +``allowed_actions`` is a set of :class:`flask_jsonapi.Actions` values. It defaults to the empty set, so a ViewSet +that does not declare it serves nothing. + +Each action has one method name, used by data services, middlewares, object permissions and the pipeline alike: + +.. list-table:: + :header-rows: 1 + + * - Action + - HTTP request + - Method + * - ``Actions.create`` + - ``POST /articles/`` + - ``create(*, data)`` + * - ``Actions.read`` + - ``GET /articles/1/`` + - ``read(*, id)`` + * - ``Actions.list`` + - ``GET /articles/`` + - ``list(*, filters, sorting, pagination)``, returning a ``ListResult`` + * - ``Actions.update`` + - ``PATCH /articles/1/`` + - ``update(*, resource, data)`` + * - ``Actions.destroy`` + - ``DELETE /articles/1/`` + - ``destroy(*, resource)`` + +Middleware and object permission methods take the same keyword arguments plus ``inner``. ``PATCH`` and +``DELETE`` call ``read`` first to load the object. +``Actions.read_many`` is an alias of ``Actions.list`` with the same value, so a set that names either serves lists. + +An action that is not listed is answered with ``405`` and a JSON:API error document. Data services therefore +implement every action they support and never raise "not allowed" themselves. + +Guards +------ + +A guard is a request-level yes or no check. It never sees the body, the object or the data service. + +.. code-block:: python + + import flask + + from flask_jsonapi import exceptions + from flask_jsonapi import guards + + + class CheckApiToken(guards.Guard): + def check(self, action): + if not token_is_valid(flask.request.headers.get('Authorization')): + raise exceptions.Unauthorized(detail='A valid token is required.') + +``token_is_valid`` stands for whatever check your application uses. A guard receives the action that is being +performed and rejects the request by raising a :class:`flask_jsonapi.exceptions.JsonApiException`. Guards run +inside the view, so the rejection is rendered as a JSON:API error document with the exception's status. + +``guards`` is a list, checked in order. Guards raise exceptions instead of calling ``flask.abort()``; an +``abort()`` that is left in a guard is still turned into a JSON:API error (see :ref:`layers-errors`), but the +exceptions in :mod:`flask_jsonapi.exceptions` give you control over the detail. + +Object permissions +------------------ + +Object permissions check every call to the data service against the client's rights: which objects it may see, +create, change and delete. ``ViewSet.object_permissions`` holds one object permission layer, or ``None`` (the +default) for no layer. The view places it outermost in the pipeline, after guards and parsing and before every +middleware, so its position never depends on a list. Like a middleware, it receives ``inner``, the rest of the +pipeline, with every call. Middlewares therefore see the filters the permission layer passes on: they may add +filters, but must not remove or replace the ones it added. + +:class:`flask_jsonapi.permissions.CheckObjectPermission` is built on the +:class:`flask_jsonapi.permissions.PermissionChecker` interface. It calls the checker for every action: + +* ``create``: ``check_create_permission(data=data)``, passing on the data the checker returns. +* ``read``: loads through ``inner``, then ``check_read_permission(resource=...)``. +* ``list``: passes ``apply_permission_filter(filters)`` to ``inner.list``, then runs ``check_list_permission`` on + the items, see :ref:`layers-permission-filter`. +* ``update``: ``check_update_permission(resource=..., data=...)``, passing on the data the checker returns. +* ``destroy``: ``check_destroy_permission(resource=...)``. + +Subclass it, give it a checker and implement ``apply_permission_filter``, which must return a new dict: + +.. code-block:: python + + from flask_jsonapi import permissions + + + class AuthorChecker(permissions.PermissionChecker): + def check_read_permission(self, *, resource): + return self._check(resource) + + def check_destroy_permission(self, *, resource): + return self._check(resource) + + def check_update_permission(self, *, resource, data): + return self._check(resource), data + + def check_create_permission(self, *, data): + return {**data, 'author_id': current_author_id()} + + @staticmethod + def _check(resource): + if resource.author_id != current_author_id(): + raise permissions.PermissionException + return resource + + + class OwnArticles(permissions.CheckObjectPermission): + permission_checker = AuthorChecker() + + def apply_permission_filter(self, filters): + return {**filters, 'author_id': current_author_id()} + +Set it with ``object_permissions = OwnArticles()``. ``current_author_id()`` stands for the way your application +identifies the client. It reads the client from the request on every call, because one instance serves all +requests, see :ref:`view-sets-instances`. A ``PermissionException`` answers ``403``, and the default +``check_list_permission`` leaves out of a list the objects that ``check_read_permission`` rejects. + +.. _layers-permission-filter: + +Lists: the permission filter and the safety net +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The permission checker decides which objects a client may see. ``apply_permission_filter`` puts the same +decision into the query, so the data service returns only those objects and the total includes only them. Its +contract: + +* It returns new filters that restrict the list to the objects the client may list. It never mutates ``filters``. +* It may raise ``PermissionException`` when the client's own filters ask for objects the client may not list. The + request answers ``403`` and the data service is not called. + +Here articles belong to projects, and a client lists the articles of the projects it is a member of: + +.. code-block:: python + + class MemberProjects(permissions.CheckObjectPermission): + permission_checker = MemberChecker() + + def apply_permission_filter(self, filters): + project_ids = member_project_ids() + if 'project_id' in filters: + if filters['project_id'] not in project_ids: + raise permissions.PermissionException(detail='You may not list this project.') + return dict(filters) + return {**filters, 'project_id__in': project_ids} + +``MemberChecker`` and ``member_project_ids()`` stand for your own checker and lookup. The lookup returns the ids +in the form the filter schema parses them, strings for a ``FilterField`` with the default type. +``GET /articles/?filter[project_id]=7`` answers ``403`` when the client is not a member of project 7. Without a +``project_id`` filter, the layer restricts the list to the client's projects, and the database combines that with +every other filter. + +After the data service returns, ``check_list_permission`` runs on the items as a safety net. When the filter is +right, it drops nothing and the result passes on unchanged. When it drops an object, the filter and the check +disagree: a bug in the filter, or a request crafted to exploit one. The total then includes objects the client may +not see, so the layer returns the remaining items with ``total=None`` and logs a warning on the +``flask_jsonapi.permissions.object_permissions`` logger, without any object data. A paginated response is then +shorter than the page size, so it has neither a ``next`` nor a ``last`` link, see :ref:`layers-list-results`. + +To write an object permission layer of your own, subclass :class:`flask_jsonapi.permissions.ObjectPermissions`. It +has the methods of :ref:`layers-actions`, each with ``inner``, but no pass-through defaults: every method is +abstract, so you have to state the behaviour for every action and a forgotten ``list`` cannot silently allow +everything. Its ``list`` returns a ``ListResult``, see :ref:`layers-list-results`. + +Middlewares +----------- + +Middlewares are optional business layers between the object permissions and the data service. They have the +methods of :ref:`layers-actions`, and each one receives ``inner``, the rest of the chain, which has the same +interface as a data service. A middleware that does not override a method passes the call through unchanged. + +.. code-block:: python + + class Middleware: + def create(self, *, data, inner): + return inner.create(data=data) + + def read(self, *, id, inner): + return inner.read(id=id) + + def list(self, *, filters, sorting, pagination, inner): + return inner.list(filters=filters, sorting=sorting, pagination=pagination) + + def update(self, *, resource, data, inner): + return inner.update(resource=resource, data=data) + + def destroy(self, *, resource, inner): + return inner.destroy(resource=resource) + +Subclass :class:`flask_jsonapi.middlewares.Middleware` and override only what you need. This middleware shows only +published articles, in the list and in its pagination total: + +.. code-block:: python + + from flask_jsonapi import data_services + from flask_jsonapi import middlewares + + + class OnlyPublished(middlewares.Middleware): + def list(self, *, filters, inner, **kwargs): + return inner.list(filters={**filters, 'published': True}, **kwargs) + +Code before the call to ``inner`` runs on the way in, code after it runs on the way out: + +.. code-block:: python + + class LogRetitles(middlewares.Middleware): + def update(self, *, resource, data, inner): + old_title = resource.title + result = inner.update(resource=resource, data=data) + logger.info('Article %s retitled from %r to %r.', resource.id, old_title, result.title) + return result + +The view wraps the object permissions around the first middleware and each middleware around the next one, with +the data service innermost. The result is itself a data service, so the view only ever calls +``pipeline.(...)``. Middlewares do not need to know about the list of middlewares or about the data +service. Middleware and data service instances are shared by all requests, so keep per-request state out of them, +see :ref:`view-sets-instances`. + +Rules for middlewares: + +* **List order is execution order.** With ``middlewares = [A(), B()]``, the code of ``A`` before ``inner`` runs + first, then the code of ``B``, then the data service. Code after ``inner`` runs in the opposite order. +* **A middleware may call** ``inner`` **more than once.** Every call goes through the rest of the chain again: + + .. code-block:: python + + class RetryWhenUnavailable(middlewares.Middleware): + def read(self, *, id, inner): + try: + return inner.read(id=id) + except data_services.Unavailable: + return inner.read(id=id) + +* **Exceptions propagate.** Code after ``inner`` runs only when ``inner`` returns. A middleware must not swallow + exceptions it does not handle, as the example above handles only ``Unavailable``. +* **Do not mutate the input in place.** ``filters`` and ``data`` may be shared with other layers. Build a new + dict, as the examples above do with ``{**filters, ...}``, and pass that down. +* **A list returns a** ``ListResult``. A middleware that changes the items on the way out builds a new one. It + keeps the total when every object stays, and sets it to ``None`` when it removes objects, because the total would + include them: + + .. code-block:: python + + class HideEmbargoed(middlewares.Middleware): + def list(self, *, inner, **kwargs): + result = inner.list(**kwargs) + visible = [article for article in result.items if not is_embargoed(article)] + if len(visible) == len(result.items): + return result + return data_services.ListResult(visible, total=None) + + ``is_embargoed`` stands for a rule of your own. A page that loses objects this way is short and has no ``next`` + link. Leaving objects out with a filter on the way in keeps the total and full pages, as ``OnlyPublished`` above + does, so remove objects on the way out only when no filter can express the rule. + +Required list filters +~~~~~~~~~~~~~~~~~~~~~ + +:class:`flask_jsonapi.middlewares.CheckRequiredListFilters` rejects a list request that lacks the named filters +with ``400``. The filters must also be declared in the ViewSet's ``filter_schema``. The names are the keys of the +parsed filters, as the data service receives them: ``filter[author_id][in]`` is checked as ``author_id__in``, and a +filter field declared with ``attribute=`` is checked under that attribute path, not under its query string name. + +.. code-block:: python + + from flask_jsonapi.middlewares import CheckRequiredListFilters + + + class ArticleViewSet(flask_jsonapi.ViewSet): + filter_schema = ArticleFilterSchema() + middlewares = [CheckRequiredListFilters(['title'])] + +.. _layers-data-services: + +Data services +------------- + +A data service is the innermost layer. It has one method per action, with keyword-only arguments: + +.. code-block:: python + + class DataService: + def create(self, *, data): ... + def read(self, *, id): ... + def list(self, *, filters, sorting, pagination) -> ListResult: ... + def update(self, *, resource, data): ... + def destroy(self, *, resource): ... + +:class:`flask_jsonapi.data_services.DataService` is the base class; a method you do not override raises +``NotImplementedError``, which is harmless as long as the action is not in ``allowed_actions``. + +``resource`` is the object that ``read`` returned for this request. It is never ``None`` (a ``read`` +that returns ``None`` answers ``404``) and a data service never has to load it again. + +.. _layers-list-results: + +List results +~~~~~~~~~~~~ + +``list`` returns a :class:`flask_jsonapi.data_services.ListResult` with two fields: + +* ``items``: the objects of the requested page, or all matching objects when the request asks for no page. +* ``total``: the number of objects that match the filters, before pagination, or ``None``. + +A data service sets ``total`` when ``pagination`` is given, and may leave it ``None`` otherwise. ``pagination`` is +a dict with ``size`` and ``number`` (starting at 1), or an empty dict when the request asks for no page. The +items and the total come from one call, so every filter a layer adds applies to both. :ref:`guide-list-source` +shows a data service that builds a ``ListResult`` itself. + +The list view builds the pagination links from the result. With a total, the links are ``self``, ``first``, +``previous``, ``next`` and ``last``, and ``next`` is present up to the last page. With ``total=None`` the view +cannot know the last page: ``last`` is ``null``, and ``next`` is present only when the page is full, that is when +it holds ``size`` items. A short page has no ``next`` link. A full last page still has one, and the next page is +empty. + +A data service is either a repository or a use case. A repository stores objects. A use case does something else +on the same endpoint, such as publishing an article or computing statistics: + +.. code-block:: python + + class PublishArticles(data_services.DataService): + def __init__(self, repository): + self.repository = repository + + def read(self, *, id): + return self.repository.read(id=id) + + def update(self, *, resource, data): + return self.repository.update(resource=resource, data={'published': True}) + +SQLAlchemy repository +~~~~~~~~~~~~~~~~~~~~~ + +``flask_jsonapi.data_services.sqlalchemy_repositories.SqlAlchemyModelRepository`` stores a model in a SQLAlchemy +session. Set ``model`` and ``session``, and override ``filter_methods_map``, ``get_query``, ``build`` or +``update_attribute`` to customise it. + +.. code-block:: python + + from flask_jsonapi.data_services import sqlalchemy_repositories + + + class ArticleRepository(sqlalchemy_repositories.SqlAlchemyModelRepository): + model = Article + session = session + +* ``list`` filters the query from ``get_query`` once. When the request asks for a page, it counts that query for + the total and returns the requested slice of the same query. +* ``update(resource=..., data=...)`` changes the object it is given and never fetches it again. +* ``destroy(resource=...)`` deletes the object it is given. +* Writes take a ``strategy``: ``'commit'`` (the default) or ``'flush'``. + +Exceptions +~~~~~~~~~~ + +Data services are HTTP-agnostic. They raise the exceptions from :mod:`flask_jsonapi.data_services` and never HTTP +ones. Subclass a base class for your own business rules and the status follows: + +.. code-block:: python + + class TitleLocked(data_services.InvalidData): + pass + + + class ArticleRepository(sqlalchemy_repositories.SqlAlchemyModelRepository): + model = Article + session = session + + def update(self, *, resource, data, **kwargs): + if resource.published and 'title' in data: + raise TitleLocked('A published article cannot be retitled.', field='title') + return super().update(resource=resource, data=data, **kwargs) + +The SQLAlchemy repository translates database errors itself. An ``IntegrityError`` becomes ``Conflict``, an +``OperationalError`` (lost connection, timeout, deadlock) becomes ``Unavailable`` and any other ``SQLAlchemyError`` +becomes a plain ``DataServiceException``. A ``DataError``, which the database raises for a malformed value such as +``not-a-uuid`` in a ``uuid`` column, is a client mistake and is translated by where it happened: ``read`` +raises ``ResourceNotFound`` (no resource can have that id), ``list`` raises +``InvalidFilterParameter``, and the writing methods raise ``InvalidData``. The session is rolled back first, after +failed reads as well as writes, so an aborted transaction never reaches the next statement. + +.. _layers-errors: + +Errors +------ + +Every error a client receives from a flask-jsonapi view is a JSON:API error document. The view translates the +exceptions of the layers below it in one place, by base class, for every action: + +.. list-table:: + :header-rows: 1 + + * - Raised + - HTTP status + * - ``data_services.ResourceNotFound`` + - 404 + * - ``data_services.PermissionDenied`` + - 403 + * - ``data_services.InvalidData`` + - 422, with ``source.pointer`` set to ``/data/attributes/`` when ``field`` is given + * - ``data_services.Conflict`` + - 409 + * - ``data_services.InvalidSortParameter``, ``data_services.InvalidFilterParameter`` + - 400 + * - ``data_services.Unavailable`` + - 503 + * - any other ``data_services.DataServiceException`` + - 500, logged, with no internal details in the body + * - a ``flask_jsonapi.exceptions.JsonApiException`` (from a guard, the object permissions, a middleware or the view) + - its own ``status`` + * - a ``werkzeug.exceptions.HTTPException``, for example from ``flask.abort()`` + - the same status and title, keeping its headers such as ``WWW-Authenticate`` or ``Allow`` + * - an ``abort()`` carrying an explicit response, such as ``flask.abort(flask.Response(...))`` + - that response, returned unchanged: it is not a JSON:API document + * - any other exception + - 500, logged with ``logger.exception``, with no internal details in the body + +A 500 stays a 500: the status is honest, what is hidden is the body. + +:mod:`flask_jsonapi.exceptions` has the exceptions that guards and middlewares raise, among them ``Unauthorized`` +(401), ``ForbiddenError`` (403), ``Conflict`` (409), ``UnprocessableEntity`` (422) and ``ServiceUnavailable`` +(503). They take keyword arguments: + +.. code-block:: python + + raise exceptions.ForbiddenError(detail='Only the author can do this.') + raise exceptions.JsonApiException(status=418, title='Teapot', detail='Short and stout.', source={}) + +The older positional forms, such as ``JsonApiException(source, detail)``, keep working. Empty ``detail`` and +``source`` members are left out of the error object. + +``view_decorators`` run outside the view, so the errors of a decorator are not converted to JSON:API documents. +Keep authentication in guards. + +Rendering and presentation +-------------------------- + +Presentation belongs in the schema, not in the pipeline. A schema dumps once per object in the response and +never during permission loads, so a rendered field costs nothing on ``DELETE`` and nothing extra on ``PATCH``, +which dumps the returned object once. + +Use a ``fields.Method`` to compute a read-only attribute on dump, and ``post_load`` to prepare incoming data +for saving: + +.. code-block:: python + + import html + + import marshmallow + + from marshmallow_jsonapi import Schema + from marshmallow_jsonapi import fields + + + class ArticleSchema(Schema): + id = fields.Int() + title = fields.Str(required=True) + body = fields.Str() + body_html = fields.Method('render_body_html', dump_only=True) + + class Meta: + type_ = 'articles' + + def render_body_html(self, article): + return '

{}

'.format(html.escape(article.body or '')) + + @marshmallow.post_load + def prepare_for_save(self, data, **kwargs): + if 'title' in data: + data['title'] = data['title'].strip() + return data + +``post_load`` also runs for ``PATCH``, where the schema is loaded with ``partial=True``, so it must cope with +missing attributes. + +``view_decorators`` +------------------- + +``ViewSet.view_decorators`` wraps the view functions that Flask routes to. Use it only for Flask-level +integration that must wrap the view function itself, for example exempting the views from a CSRF extension: + +.. code-block:: python + + class ArticleViewSet(flask_jsonapi.ViewSet): + view_decorators = [csrf.exempt] + +Do not use it for authentication or permissions. Use guards and object permissions, which run inside the view and +produce JSON:API errors. diff --git a/docs/migration.rst b/docs/migration.rst new file mode 100644 index 0000000..ebddc61 --- /dev/null +++ b/docs/migration.rst @@ -0,0 +1,326 @@ +Migrating to ViewSet +==================== + +.. versionadded:: 1.5.0 + +``ResourceRepositoryViewSet``, ``ProtectedViewSet``, their views and mixins, the ``AllowedActions`` mixins and +``resource_repositories`` are deprecated since 1.5.0. They are documented as deprecated but emit no warnings and +keep their behaviour, so you can upgrade flask-jsonapi first and move one endpoint at a time. + +The only deliberate change for code that is not migrated is error handling, see :ref:`migration-errors`. + +The example +----------- + +Take an ``Article`` endpoint that is read and updated but never created or deleted, requires an API token, and +lets an author see only their own articles. This is how it looks with the legacy classes: + +.. code-block:: python + + import functools + + import flask + + from flask_jsonapi import exceptions + from flask_jsonapi import permissions + from flask_jsonapi.resource_repositories import sqlalchemy_repositories + + + def require_token(view): + @functools.wraps(view) + def wrapper(*args, **kwargs): + if not token_is_valid(flask.request.headers.get('Authorization')): + flask.abort(401) + return view(*args, **kwargs) + return wrapper + + + class AuthorChecker(permissions.PermissionChecker): + def check_read_permission(self, *, resource): + return self._check(resource) + + def check_destroy_permission(self, *, resource): + return self._check(resource) + + def check_update_permission(self, *, resource, data): + return self._check(resource), data + + def check_create_permission(self, *, data): + return data + + @staticmethod + def _check(resource): + if resource.author_id != current_author_id(): + raise permissions.PermissionException + return resource + + + class ArticleRepository(sqlalchemy_repositories.SqlAlchemyModelRepository): + model = Article + instance_name = 'article' + session = session + + def create(self, data, **kwargs): + raise exceptions.ForbiddenError(detail='Articles cannot be created.') + + def delete(self, id, **kwargs): + raise exceptions.ForbiddenError(detail='Articles cannot be deleted.') + + + class ArticleListView(permissions.ProtectedListView): + def _apply_permission_filter(self, filters): + return {**filters, 'author_id': current_author_id()} + + + class ArticleViewSet(permissions.ProtectedViewSet): + schema = ArticleSchema + repository = ArticleRepository() + permission_checker = AuthorChecker() + list_view_cls = ArticleListView + view_decorators = [require_token] + +Here is the same endpoint with ``flask_jsonapi.ViewSet``. The steps below explain each change. + +.. code-block:: python + + import flask + + import flask_jsonapi + + from flask_jsonapi import exceptions + from flask_jsonapi import guards + from flask_jsonapi import permissions + from flask_jsonapi.data_services import sqlalchemy_repositories + + + class CheckApiToken(guards.Guard): + def check(self, action): + if not token_is_valid(flask.request.headers.get('Authorization')): + raise exceptions.Unauthorized(detail='A valid token is required.') + + + class AuthorChecker(permissions.PermissionChecker): + ... # unchanged + + + class OwnArticles(permissions.CheckObjectPermission): + permission_checker = AuthorChecker() + + def apply_permission_filter(self, filters): + return {**filters, 'author_id': current_author_id()} + + + class ArticleRepository(sqlalchemy_repositories.SqlAlchemyModelRepository): + model = Article + session = session + + + class ArticleViewSet(flask_jsonapi.ViewSet): + schema_class = ArticleSchema + allowed_actions = { + flask_jsonapi.Actions.read, + flask_jsonapi.Actions.list, + flask_jsonapi.Actions.update, + } + guards = [CheckApiToken()] + object_permissions = OwnArticles() + data_service = ArticleRepository() + +Step 1: authentication moves from ``view_decorators`` to ``guards`` +------------------------------------------------------------------- + +A decorator wraps the view function, so it runs outside the view. Whatever it raises or aborts with is not +handled by flask-jsonapi, and in the example the client gets an HTML error page. A guard runs inside the view, +before the body is parsed, and raises a JSON:API exception: + +.. code-block:: python + + # before + view_decorators = [require_token] + + # after + guards = [CheckApiToken()] + +``Unauthorized`` is the new 401 exception in :mod:`flask_jsonapi.exceptions`; raise exceptions instead of calling +``flask.abort()``. Keep ``view_decorators`` only for Flask-level integration, for example exempting the views +from a CSRF extension. + +Step 2: "forbidden" stubs become ``allowed_actions`` +---------------------------------------------------- + +The repository no longer says what it cannot do. The ViewSet says what it serves, and a request for anything else +is answered with 405 before the body is parsed: + +.. code-block:: python + + # before: in the repository + def create(self, data, **kwargs): + raise exceptions.ForbiddenError(detail='Articles cannot be created.') + + def delete(self, id, **kwargs): + raise exceptions.ForbiddenError(detail='Articles cannot be deleted.') + + # after: in the ViewSet + allowed_actions = { + flask_jsonapi.Actions.read, + flask_jsonapi.Actions.list, + flask_jsonapi.Actions.update, + } + +Note the status: a stub answered 403 Forbidden, a missing action answers 405 Method Not Allowed. + +``Actions.list`` is the new name of ``Actions.read_many``. The old name stays as an alias with the same value, so +an ``allowed_actions`` that names ``Actions.read_many`` keeps serving lists, in legacy views and in a ViewSet. + +Step 3: the permission checker moves into ``object_permissions`` +---------------------------------------------------------------- + +``PermissionChecker`` classes keep working unchanged. What changes is where they are plugged in. Instead of +``ProtectedViewSet`` with a custom ``ProtectedListView``, a ``flask_jsonapi.permissions.CheckObjectPermission`` +subclass holds the checker and goes into the ViewSet's ``object_permissions`` slot. Its ``apply_permission_filter`` +replaces ``_apply_permission_filter`` of the list view: + +.. code-block:: python + + # before + class ArticleListView(permissions.ProtectedListView): + def _apply_permission_filter(self, filters): + return {**filters, 'author_id': current_author_id()} + + class ArticleViewSet(permissions.ProtectedViewSet): + permission_checker = AuthorChecker() + list_view_cls = ArticleListView + + # after + class OwnArticles(permissions.CheckObjectPermission): + permission_checker = AuthorChecker() + + def apply_permission_filter(self, filters): + return {**filters, 'author_id': current_author_id()} + + class ArticleViewSet(flask_jsonapi.ViewSet): + object_permissions = OwnArticles() + +The list and its total now come from one call to the data service, with the permission filter applied, so the +total includes only objects the filter lets through. ``ProtectedListView`` applied ``_apply_permission_filter`` to +the list only, and took the total from ``get_count`` with the client's filters. + +``apply_permission_filter`` has a contract: it returns filters that restrict the list to the objects the client may +list, and it may raise ``PermissionException`` (``403``) when the client's own filters ask for objects the client +may not list. ``check_list_permission`` still runs on the listed objects. When it drops any, ``ProtectedListView`` +logged a warning and kept the total. ``CheckObjectPermission`` logs a warning without object data and leaves the +total out: the response has no ``last`` link, and a ``next`` link only for a full page. See +:ref:`layers-permission-filter`. + +This changes what is checked on update and delete. The legacy ``ProtectedDetailView`` loaded the object for +``update`` and ``destroy`` without calling ``check_read_permission``, and whether a ``read()`` override of yours ran +on that load depended on where it sat in the class hierarchy. The new views load the object with ``read`` +through the pipeline, once, and hand it to ``update`` or ``destroy`` as ``resource``. ``CheckObjectPermission`` +therefore checks read permission on that load, so read permission is now required to update or delete an object. +If your checker allowed updating objects the user cannot read, change it accordingly. + +Step 4: the repository +---------------------- + +You do not have to migrate the repository together with the ViewSet. Wrap an existing legacy repository in +:class:`flask_jsonapi.data_services.LegacyRepositoryAdapter` and use it as the ``data_service``: + +.. code-block:: python + + from flask_jsonapi import data_services + + class ArticleViewSet(flask_jsonapi.ViewSet): + ... + data_service = data_services.LegacyRepositoryAdapter(ArticleRepository()) + +The adapter calls the repository the way the legacy views did: + +.. list-table:: + :header-rows: 1 + + * - Data service method + - Legacy repository call + * - ``create(data=data)`` + - ``repository.create(data)`` + * - ``read(id=id)`` + - ``repository.get_detail(id)`` + * - ``list(filters=..., sorting=..., pagination=...)`` + - ``repository.get_list(filters, sorting, pagination)`` for the items. ``repository.get_count(filters)`` for + the total, only when the request asks for a page; otherwise the total is ``None`` + * - ``update(resource=resource, data=data)`` + - ``repository.update({**data, 'id': resource.id})`` + * - ``destroy(resource=resource)`` + - ``repository.delete(resource.id)`` + +Legacy repositories still fetch the object again inside ``update`` and ``delete``, which is accepted until you +migrate them. + +.. warning:: + + The adapter returns what the repository returns from ``update``. The legacy SQLAlchemy repository returns the + object, so ``PATCH`` through the adapter answers **200 with a body**, where the legacy view answered + **204** with none. Both are valid JSON:API, but clients that expect an empty body must be checked. + +When you are ready, move the repository to +``flask_jsonapi.data_services.sqlalchemy_repositories.SqlAlchemyModelRepository`` (see below), or write a data +service of your own, and drop the adapter. + +Step 5: raise data service exceptions, not HTTP ones +---------------------------------------------------- + +Legacy repositories raise HTTP exceptions such as ``ForbiddenError`` and ``ObjectNotFound``. A data service raises +exceptions from :mod:`flask_jsonapi.data_services` and the view turns them into HTTP errors: + +.. list-table:: + :header-rows: 1 + + * - Before + - After + * - ``exceptions.ObjectNotFound`` + - ``data_services.ResourceNotFound`` + * - ``exceptions.ForbiddenError`` + - ``data_services.PermissionDenied`` + * - ``exceptions.AttributeValidationError`` + - ``data_services.InvalidData(detail, field=...)`` + * - ``exceptions.InvalidSort`` + - ``data_services.InvalidSortParameter`` + * - ``exceptions.InvalidFilters`` + - ``data_services.InvalidFilterParameter`` + * - a SQL integrity error reported as ``ForbiddenError`` + - ``data_services.Conflict`` (409) + * - a database that is down + - ``data_services.Unavailable`` (503) + +The new SQLAlchemy repository does this for you: an ``IntegrityError`` becomes ``Conflict``, an +``OperationalError`` becomes ``Unavailable`` and any other ``SQLAlchemyError`` becomes a plain +``DataServiceException`` (500). A ``JsonApiException`` raised by a legacy repository behind the adapter still +passes through unchanged. + +Other differences of the new ``SqlAlchemyModelRepository``: + +* ``instance_name`` is gone. +* ``get_detail``, ``get_list`` and ``delete`` are renamed ``read``, ``list`` and ``destroy``, after the actions + (see the table in step 4). Middlewares and object permissions use the same names. ``get_count`` is gone: ``list`` + returns a ``ListResult`` with the items and, when the request asks for a page, the total. A repository that + overrode ``get_list`` and ``get_count`` overrides ``list`` and returns both, see :ref:`layers-list-results`. + ``get_query``, the ``apply_*`` methods, ``build`` and ``update_attribute`` keep theirs. +* ``update(resource=..., data=...)`` and ``destroy(resource=...)`` take the loaded object and never fetch it again. +* All arguments are keyword-only. + +.. _migration-errors: + +What changes for code you do not migrate +---------------------------------------- + +Upgrading changes error responses of legacy views, too: + +* Every error from a view is now a JSON:API error document, including unexpected exceptions (a generic 500 with + no internal details, logged with ``logger.exception``) and ``flask.abort()`` (same status and title). + Errors raised in a ``view_decorators`` decorator are still outside the view and are not converted. +* Flask app error handlers (``@app.errorhandler``) no longer run for exceptions raised inside a flask-jsonapi + view, because the view turns them into JSON:API errors itself. In testing mode such exceptions no longer reach + the test client either. Move that handling into a guard or a middleware, or into the view. +* Empty ``detail`` and ``source`` members are omitted from error objects. A test that compares an error body to + one containing ``'source': {}`` needs updating. +* Exception classes accept keyword arguments. The old positional forms, such as + ``JsonApiException(source, detail)`` and ``ForbiddenError('detail')``, still work. diff --git a/docs/view_sets.rst b/docs/view_sets.rst index e92c9ef..59f0b46 100644 --- a/docs/view_sets.rst +++ b/docs/view_sets.rst @@ -1,2 +1,152 @@ ViewSets ======== + +.. versionadded:: 1.5.0 + +A :class:`flask_jsonapi.ViewSet` declares one resource: its schema, its filters, the actions it serves, the guards, +object permissions and middlewares around the data, and the data service that stores it. Nothing depends on a hidden +convention; everything the endpoint does is visible in the class body. The :doc:`layers` page explains each part. + +.. note:: + + ``ResourceRepositoryViewSet``, ``ProtectedViewSet`` and their views are deprecated since 1.5.0. They keep + working. See :doc:`migration` for moving an endpoint to ``ViewSet``. + +Declaring a ViewSet +------------------- + +.. code-block:: python + + import flask_jsonapi + + + class ArticleViewSet(flask_jsonapi.ViewSet): + schema_class = ArticleSchema + filter_schema = ArticleFilterSchema() + allowed_actions = { + flask_jsonapi.Actions.read, + flask_jsonapi.Actions.list, + flask_jsonapi.Actions.update, + } + guards = [CheckApiToken()] + object_permissions = OwnArticles() + middlewares = [LogRetitles()] + data_service = ArticleRepository() + +.. list-table:: + :header-rows: 1 + + * - Attribute + - Meaning + * - ``schema_class`` + - The marshmallow-jsonapi schema class of the resource. Required. + * - ``data_service`` + - The :ref:`data service ` that stores the resource. Required. + * - ``filter_schema`` + - A ``FilterSchema`` instance that parses the ``filter[...]`` query parameters of the list view. Defaults to + a schema without filters. + * - ``allowed_actions`` + - The set of ``flask_jsonapi.Actions`` the ViewSet serves. Defaults to empty: a ViewSet that does not + declare it serves nothing. + * - ``guards`` + - Request-level checks, run in order before the body is parsed. Defaults to empty. + * - ``object_permissions`` + - The object permission layer, outermost in the pipeline, see :doc:`layers`. Defaults to ``None``: no layer. + * - ``middlewares`` + - Wrappers around the data service calls, outermost first, inside the object permissions. Defaults to empty. + * - ``view_decorators`` + - Decorators applied to the Flask view functions, for Flask-level integration only. Defaults to empty. + * - ``detail_view_class``, ``list_view_class`` + - The view classes. Default to :class:`flask_jsonapi.DetailView` and :class:`flask_jsonapi.ListView`. + +Register it with :class:`flask_jsonapi.Api`, one ViewSet per resource: + +.. code-block:: python + + api = flask_jsonapi.Api(app) + api.repository(ArticleViewSet(), 'articles', '/articles/') + +This registers a list view under ``/articles/`` and a detail view under ``/articles//``. + +.. _view-sets-instances: + +Instances and classes +--------------------- + +An attribute holds a class when the view must create a new object for every request, with arguments taken from the +request. Their names end in ``_class``: + +* ``schema_class``: the view creates a schema for every request, with the ``include`` and ``fields`` of the query + string, or with ``partial=True`` for ``PATCH``. +* ``detail_view_class`` and ``list_view_class``: Flask creates a view object for every request. + +Every layer holds an instance: ``filter_schema``, each of the ``guards``, ``object_permissions``, each of the +``middlewares`` and ``data_service``. Each one is created once, when the module that declares the ViewSet is +imported, and is shared by all requests and all threads. So these instances must not keep per-request state on +``self``: + +* Read the client from ``flask.request`` or ``flask.g`` in the method that needs it, on every call. Never store it + in an attribute: a request in another thread would read or overwrite it. +* Keep values that belong to one request in local variables, or on ``flask.g``, which Flask creates anew for every + request. +* Use a database session scoped to the thread or the request, such as SQLAlchemy's ``scoped_session``, as the + :ref:`full example ` does. + +.. code-block:: python + + class LogReads(middlewares.Middleware): + def read(self, *, id, inner): + author_id = current_author_id() + resource = inner.read(id=id) + logger.info('Author %s read article %s.', author_id, id) + return resource + +``author_id`` is a local variable. Stored as ``self.author_id``, it could be overwritten by a request in another +thread between the assignment and its use. + +Reuse by subclassing +-------------------- + +``guards``, ``object_permissions``, ``middlewares`` and ``allowed_actions`` are plain class attributes. A subclass +replaces them, they are not merged. That makes one definition reusable for several APIs: here the same resource is +served to clients with a token and, without one, to other services in the same network. + +.. code-block:: python + + class InternalArticleViewSet(ArticleViewSet): + allowed_actions = { + flask_jsonapi.Actions.create, + flask_jsonapi.Actions.read, + flask_jsonapi.Actions.list, + flask_jsonapi.Actions.update, + flask_jsonapi.Actions.destroy, + } + guards = [] + object_permissions = None + middlewares = [] + + + api.repository(ArticleViewSet(), 'articles', '/articles/') + api.repository(InternalArticleViewSet(), 'internal_articles', '/internal/articles/') + +The internal ViewSet inherits the schema, the filters and the data service. It switches off the token guard and +the object permissions explicitly, so serve it only where clients from outside cannot reach it. A subclass that does +not set ``allowed_actions`` inherits them. + +To add to the inherited list instead of replacing it, say so explicitly: + +.. code-block:: python + + class AuditedArticleViewSet(ArticleViewSet): + middlewares = [*ArticleViewSet.middlewares, AuditChanges()] + +Data services +------------- + +``data_service`` is an instance of any class with the :class:`flask_jsonapi.data_services.DataService` methods, +see :doc:`layers`: ``create``, ``read``, ``list``, ``update`` and ``destroy``. ``list`` returns a ``ListResult`` +with the items and, when the request asks for a page, their total, see :ref:`layers-list-results`. One instance +is shared by all requests, so keep per-request state out of it, see :ref:`view-sets-instances`. + +An existing legacy repository can be used through +:class:`flask_jsonapi.data_services.LegacyRepositoryAdapter`, see :doc:`migration`. diff --git a/docs/views.rst b/docs/views.rst index 48c5a53..3bb7001 100644 --- a/docs/views.rst +++ b/docs/views.rst @@ -1,2 +1,117 @@ Views ===== + +.. versionadded:: 1.5.0 + +:class:`flask_jsonapi.DetailView` and :class:`flask_jsonapi.ListView` are the views a +:doc:`ViewSet ` registers. You normally do not instantiate them: ``ViewSet.as_detail_view`` and +``ViewSet.as_list_view`` build them from the ViewSet's attributes. + +Both views are Flask class based views. ``DetailView`` is built on ``ResourceDetail``, and ``ListView`` on +``ListResourceBase``. These bases parse the query +string (``include``, ``fields``, ``sort``, ``page``, filters), dump the response and check the ``Content-Type`` and +``Accept`` headers. The views add a fixed way to reach the data: allowed actions, then guards, then the pipeline of +object permissions, middlewares and data service. + +Arguments +--------- + +Both views take these keyword arguments, which the ViewSet passes from its attributes: + +* ``schema``: the schema class. +* ``data_service``: the data service, innermost layer of the pipeline. +* ``allowed_actions``: the set of served actions. +* ``guards``: the guards, checked in order. +* ``object_permissions``: the object permission layer or ``None``. The view places it outermost in the pipeline. +* ``middlewares``: the middlewares, outermost first. The view wraps them around the data service. + +``ListView`` also takes ``filter_schema``. + +To use a view subclass of your own, set ``detail_view_class`` or ``list_view_class`` on the ViewSet. If the +subclass takes extra keyword arguments, add them in ``ViewSet.get_views_kwargs``. Those keyword arguments reach +both the detail and the list view, so both view classes must accept them: the base views reject unknown ones. + +What each method does +--------------------- + +``DetailView``: + +.. list-table:: + :header-rows: 1 + + * - HTTP method + - Action + - Calls on the pipeline + * - ``GET`` + - ``Actions.read`` + - ``read(id=id)`` + * - ``PATCH`` + - ``Actions.update`` + - ``read(id=id)``, then ``update(resource=resource, data=data)`` + * - ``DELETE`` + - ``Actions.destroy`` + - ``read(id=id)``, then ``destroy(resource=resource)`` + +``ListView``: + +.. list-table:: + :header-rows: 1 + + * - HTTP method + - Action + - Calls on the pipeline + * - ``GET`` + - ``Actions.list`` + - ``list(filters=..., sorting=..., pagination=...)``, once; the pagination links use its total + * - ``POST`` + - ``Actions.create`` + - ``create(data=data)`` + +In every method the allowed action is checked first, then the guards, then the request is parsed and only then +the pipeline is called. See :ref:`the request flow `, and :ref:`layers-actions` for the +methods of every action. + +``PATCH`` removes the ``id`` from the body before it reaches ``update``: the object is identified by ``resource``. +A body ``id`` that differs from the URL is rejected with ``409`` before anything is loaded. + +Pagination links +---------------- + +For a request with ``page[size]`` and ``page[number]``, ``ListView`` builds the pagination links from the ``total`` +of the ``ListResult``. When the total is ``None``, ``last`` is ``null`` and ``next`` is present only for a full +page, so a short page has no ``next`` link. See :ref:`layers-list-results`. + +The links come from the view's ``pagination`` attribute, a ``flask_jsonapi.query_string.SizeNumberPagination`` by +default. To change them, set ``pagination`` on a ``ListView`` subclass and name that subclass in the ViewSet's +``list_view_class``. A custom pagination class implements three methods: + +* ``parse()`` returns a dict with ``size`` and ``number``, or an empty dict when the request asks for no page. +* ``get_links(page_size, current_page, total_count)`` is used when the total is known. +* ``get_links_without_total(page_size, current_page, item_count)`` is used when it is ``None``. ``item_count`` + is the number of objects on the current page. + +Both link methods return a dict with ``self``, ``first``, ``previous``, ``next`` and ``last``, holding ``None`` +for a page that does not exist. + +Errors +------ + +Exceptions of the data service are translated to JSON:API errors in the view, for every action. See :ref:`layers-errors` for the table. + +Calling a data service directly +------------------------------- + +The pipeline is a data service itself, so code outside HTTP can use the same layers. ``build_pipeline`` takes a +list of layers, outermost first, and the data service. The view builds its pipeline as +``build_pipeline([object_permissions, *middlewares], data_service)``, leaving out ``object_permissions`` when it is +``None``: + +.. code-block:: python + + from flask_jsonapi import middlewares + + pipeline = middlewares.build_pipeline([OnlyPublished()], ArticleRepository()) + articles = pipeline.list(filters={}, sorting=[], pagination=None).items + +``list`` returns a ``ListResult``: ``items`` holds the objects, and ``total`` is ``None`` here because no page is +requested. diff --git a/flask_jsonapi/__init__.py b/flask_jsonapi/__init__.py index 39cc030..3d89cb9 100644 --- a/flask_jsonapi/__init__.py +++ b/flask_jsonapi/__init__.py @@ -7,25 +7,33 @@ from .resource_repository_views import ResourceRepositoryDetailView from .resource_repository_views import ResourceRepositoryListView from .resource_repository_views import ResourceRepositoryViewSet +from .resources import Actions from .resources import AllowedActionsResourceDetailMixin from .resources import AllowedActionsResourceListMixin from .resources import AllowedActionsResourceViewSetMixin from .resources import ResourceDetail from .resources import ResourceList +from .views import DetailView +from .views import ListView +from .viewsets import ViewSet __all__ = [ - exceptions, - AllowedActionsResourceDetailMixin, - AllowedActionsResourceListMixin, - AllowedActionsResourceViewSetMixin, - Api, - FilterField, - FilterSchema, - ListFilterField, - ResourceRepository, - ResourceRepositoryDetailView, - ResourceRepositoryListView, - ResourceRepositoryViewSet, - ResourceDetail, - ResourceList, + 'exceptions', + 'Actions', + 'AllowedActionsResourceDetailMixin', + 'AllowedActionsResourceListMixin', + 'AllowedActionsResourceViewSetMixin', + 'Api', + 'DetailView', + 'FilterField', + 'FilterSchema', + 'ListFilterField', + 'ListView', + 'ResourceRepository', + 'ResourceRepositoryDetailView', + 'ResourceRepositoryListView', + 'ResourceRepositoryViewSet', + 'ResourceDetail', + 'ResourceList', + 'ViewSet', ] diff --git a/flask_jsonapi/data_services/__init__.py b/flask_jsonapi/data_services/__init__.py new file mode 100644 index 0000000..d11081a --- /dev/null +++ b/flask_jsonapi/data_services/__init__.py @@ -0,0 +1,27 @@ +from . import exceptions +from .base import DataService +from .base import ListResult +from .exceptions import Conflict +from .exceptions import DataServiceException +from .exceptions import InvalidData +from .exceptions import InvalidFilterParameter +from .exceptions import InvalidSortParameter +from .exceptions import PermissionDenied +from .exceptions import ResourceNotFound +from .exceptions import Unavailable +from .legacy import LegacyRepositoryAdapter + +__all__ = [ + 'Conflict', + 'DataService', + 'DataServiceException', + 'InvalidData', + 'InvalidFilterParameter', + 'InvalidSortParameter', + 'LegacyRepositoryAdapter', + 'ListResult', + 'PermissionDenied', + 'ResourceNotFound', + 'Unavailable', + 'exceptions', +] diff --git a/flask_jsonapi/data_services/base.py b/flask_jsonapi/data_services/base.py new file mode 100644 index 0000000..811a688 --- /dev/null +++ b/flask_jsonapi/data_services/base.py @@ -0,0 +1,25 @@ +import dataclasses +import typing + + +@dataclasses.dataclass(frozen=True) +class ListResult: + items: list + total: typing.Optional[int] + + +class DataService: + def create(self, *, data): + raise NotImplementedError('Creating is not implemented.') + + def read(self, *, id): + raise NotImplementedError('Reading is not implemented.') + + def list(self, *, filters, sorting, pagination) -> ListResult: + raise NotImplementedError('Listing is not implemented.') + + def update(self, *, resource, data): + raise NotImplementedError('Updating is not implemented.') + + def destroy(self, *, resource): + raise NotImplementedError('Destroying is not implemented.') diff --git a/flask_jsonapi/data_services/exceptions.py b/flask_jsonapi/data_services/exceptions.py new file mode 100644 index 0000000..b315a69 --- /dev/null +++ b/flask_jsonapi/data_services/exceptions.py @@ -0,0 +1,34 @@ +class DataServiceException(Exception): + def __init__(self, detail=None): + super().__init__(detail) + self.detail = detail + + +class ResourceNotFound(DataServiceException): + pass + + +class PermissionDenied(DataServiceException): + pass + + +class InvalidData(DataServiceException): + def __init__(self, detail=None, field=None): + super().__init__(detail) + self.field = field + + +class Conflict(DataServiceException): + pass + + +class InvalidSortParameter(DataServiceException): + pass + + +class InvalidFilterParameter(DataServiceException): + pass + + +class Unavailable(DataServiceException): + pass diff --git a/flask_jsonapi/data_services/legacy.py b/flask_jsonapi/data_services/legacy.py new file mode 100644 index 0000000..8fb473e --- /dev/null +++ b/flask_jsonapi/data_services/legacy.py @@ -0,0 +1,23 @@ +from . import base + + +class LegacyRepositoryAdapter(base.DataService): + def __init__(self, repository): + self.repository = repository + + def create(self, *, data): + return self.repository.create(data) + + def read(self, *, id): + return self.repository.get_detail(id) + + def list(self, *, filters, sorting, pagination): + items = self.repository.get_list(filters, sorting, pagination) + total = self.repository.get_count(filters) if pagination else None + return base.ListResult(items, total) + + def update(self, *, resource, data): + return self.repository.update({**data, 'id': resource.id}) + + def destroy(self, *, resource): + return self.repository.delete(resource.id) diff --git a/flask_jsonapi/data_services/sqlalchemy_repositories.py b/flask_jsonapi/data_services/sqlalchemy_repositories.py new file mode 100644 index 0000000..7640c9a --- /dev/null +++ b/flask_jsonapi/data_services/sqlalchemy_repositories.py @@ -0,0 +1,167 @@ +import contextlib +import logging + +from sqlalchemy import exc +from sqlalchemy import func +from sqlalchemy.orm import exc as orm_exc + +from flask_jsonapi import exceptions as http_exceptions +from flask_jsonapi.utils import sqlalchemy_django_query + +from . import base +from . import exceptions + +logger = logging.getLogger(__name__) + + +class SqlAlchemyModelRepository(base.DataService): + model = None + session = None + filter_methods_map = {} + + def create(self, *, data, strategy='commit'): + with self._translated_errors('Resource could not be created.', data_error=exceptions.InvalidData): + obj = self.build(data) + self.session.add(obj) + self._run_session_strategy(strategy) + return obj + + def list(self, *, filters=None, sorting=None, pagination=None): + with self._translated_errors( + 'Error while getting resource list.', data_error=exceptions.InvalidFilterParameter): + query = self.apply_filters(self.get_query(), filters) + total = self._count(query) if pagination else None + query = self.apply_sorts(query, sorting) + items = self.apply_pagination(query, pagination).all() + return base.ListResult(items, total) + + def read(self, *, id): + with self._translated_errors( + 'Error while getting resource details.', data_error=exceptions.ResourceNotFound): + try: + return self.get_query().filter(self.model.id == id).one() + except orm_exc.NoResultFound: + raise exceptions.ResourceNotFound('Resource {} not found.'.format(id)) + + def update(self, *, resource, data, strategy='commit'): + with self._translated_errors('Error while updating resource.', data_error=exceptions.InvalidData): + for key, value in data.items(): + self.update_attribute(resource, key, value) + self._run_session_strategy(strategy) + return resource + + def destroy(self, *, resource, strategy='commit'): + with self._translated_errors('Error while deleting resource.', data_error=exceptions.InvalidData): + self.session.delete(resource) + self._run_session_strategy(strategy) + + def get_or_create(self, *, create_data=None, for_update=False, strategy='commit', **kwargs): + with self._translated_errors( + 'Error while getting or creating resource.', data_error=exceptions.InvalidData): + query = self.session.query(self.model) + if for_update: + query = query.with_for_update() + try: + return query.filter_by(**kwargs).one() + except orm_exc.NoResultFound: + create_data = create_data or {} + build_data = kwargs.copy() + build_data.update(create_data) + try: + created = self.build(build_data) + with self.session.begin_nested(): + self.session.add(created) + self._run_session_strategy(strategy) + return created + except exc.IntegrityError as e: + if 'duplicate key value violates unique constraint' in str(e.orig): + return query.filter_by(**kwargs).one() + else: + raise + + def update_or_create(self, *, update_data=None, strategy='commit', **kwargs): + with self._translated_errors( + 'Error while updating or creating resource.', data_error=exceptions.InvalidData): + update_data = update_data or {} + updated_rows = self.session.query(self.model).filter_by(**kwargs).update(update_data) + if updated_rows == 0: + create_data = {} + create_data.update(kwargs) + create_data.update(update_data) + try: + created = self.build(create_data) + with self.session.begin_nested(): + self.session.add(created) + self._run_session_strategy(strategy) + return created + except exc.IntegrityError as e: + if 'duplicate key value violates unique constraint' in str(e.orig): + self.session.query(self.model).filter_by(**kwargs).update(update_data) + self._run_session_strategy(strategy) + else: + raise + else: + self._run_session_strategy(strategy) + + @contextlib.contextmanager + def _translated_errors(self, detail, data_error): + try: + yield + except exc.SQLAlchemyError as error: + self.session.rollback() + if isinstance(error, exc.IntegrityError): + logger.info('Integrity error translated to Conflict.') + raise exceptions.Conflict('Resource conflicts with existing data.') from error + if isinstance(error, exc.OperationalError): + logger.warning('Operational error translated to Unavailable.', exc_info=error) + raise exceptions.Unavailable('Database is temporarily unavailable.') from error + if isinstance(error, exc.DataError): + logger.info('Data error translated to a client error.') + raise data_error('Value has an invalid format.') from error + raise exceptions.DataServiceException(detail) from error + + def _count(self, query): + return self.session.execute(query.statement.with_only_columns(func.count(self.model.id))).scalar() + + def _run_session_strategy(self, strategy): + if strategy == 'commit': + self.session.commit() + if strategy == 'flush': + self.session.flush() + + def get_query(self): + return sqlalchemy_django_query.DjangoQuery(self.model, session=self.session()) + + def apply_filters(self, query, filters): + filters = filters or {} + filters = filters.copy() + for filter, filter_method in self.filter_methods_map.items(): + if filter in filters: + value = filters.pop(filter) + query = query.filter(filter_method(value)) + try: + return query.filter_by(**filters) + except ValueError: + raise exceptions.InvalidFilterParameter('Invalid filter fields.') + + def apply_pagination(self, query, pagination): + pagination = pagination or {} + size = pagination.get('size') + number = pagination.get('number') + if size is not None and number is not None: + return query.limit(size).offset(size * (number - 1)) + else: + return query + + def apply_sorts(self, query, sorting): + sorting = sorting or [] + try: + return query.order_by(*sorting) + except (http_exceptions.InvalidSort, exc.InvalidRequestError): + raise exceptions.InvalidSortParameter('Invalid sort fields.') + + def build(self, kwargs): + return self.model(**kwargs) + + def update_attribute(self, obj, key, new_value): + setattr(obj, key, new_value) diff --git a/flask_jsonapi/exceptions.py b/flask_jsonapi/exceptions.py index dddf84e..0f95900 100644 --- a/flask_jsonapi/exceptions.py +++ b/flask_jsonapi/exceptions.py @@ -2,13 +2,21 @@ class JsonApiException(Exception): title = 'Unknown error' status = 500 - def __init__(self, source, detail, *args, title=None, status=None, **kwargs): + def __init__(self, *args, status=None, title=None, detail=None, source=None): """Initialize a jsonapi exception - :param dict source: the source of the error + Positional arguments are ``source, detail`` and any further ones go to ``Exception``, as in 1.4. + + :param int status: the HTTP status, overrides the class default + :param str title: the title of the error, overrides the class default :param str detail: the detail of the error + :param dict source: the source of the error """ - super().__init__(*args, **kwargs) + if args: + source = args[0] + if len(args) >= 2: + detail = args[1] + super().__init__(*([detail] if detail else []), *args[2:]) self.source = source self.detail = detail if title is not None: @@ -16,11 +24,18 @@ def __init__(self, source, detail, *args, title=None, status=None, **kwargs): if status is not None: self.status = status + def __str__(self): + # 1.4 subclasses may skip super().__init__() and never set detail. + detail = getattr(self, 'detail', None) + return str(detail) if detail else super().__str__() + def to_dict(self): - return {'status': self.status, - 'source': self.source, - 'title': self.title, - 'detail': self.detail} + result = {'status': self.status, 'title': self.title} + if self.detail: + result['detail'] = self.detail + if self.source: + result['source'] = self.source + return result class BadRequest(JsonApiException): @@ -100,13 +115,8 @@ class MethodNotAllowed(JsonApiException): title = "Method not allowed" status = 405 - def __init__(self, detail, source=None, **kwargs): - source = source or {} - super().__init__( - source=source, - detail=detail, - **kwargs, - ) + def __init__(self, detail=None, source=None, **kwargs): + super().__init__(source=source, detail=detail, **kwargs) class InvalidType(JsonApiException): @@ -118,12 +128,8 @@ class NotImplementedMethod(JsonApiException): title = "Method not implemented" status = 501 - def __init__(self, detail, **kwargs): - super().__init__( - source=None, - detail=detail, - **kwargs - ) + def __init__(self, detail=None, source=None, **kwargs): + super().__init__(source=source, detail=detail, **kwargs) class Conflict(JsonApiException): @@ -131,13 +137,27 @@ class Conflict(JsonApiException): status = 409 +class Unauthorized(JsonApiException): + title = 'Unauthorized' + status = 401 + + +class UnprocessableEntity(JsonApiException): + title = 'Unprocessable entity' + status = 422 + + +class ServiceUnavailable(JsonApiException): + title = 'Service unavailable' + status = 503 + + class ForbiddenError(JsonApiException): title = 'Operation forbidden.' status = 403 - def __init__(self, detail, source=None): - self.source = source or {} - self.detail = detail + def __init__(self, detail=None, source=None, **kwargs): + super().__init__(source=source, detail=detail, **kwargs) class AttributeValidationError(JsonApiException): diff --git a/flask_jsonapi/guards.py b/flask_jsonapi/guards.py new file mode 100644 index 0000000..3ad1080 --- /dev/null +++ b/flask_jsonapi/guards.py @@ -0,0 +1,9 @@ +class Guard: + """A request-level yes/no check that runs before the request body is parsed. + + A guard never sees the body, the object or the data service. It raises a + :class:`flask_jsonapi.exceptions.JsonApiException` to reject the request. + """ + + def check(self, action): + raise NotImplementedError diff --git a/flask_jsonapi/middlewares/__init__.py b/flask_jsonapi/middlewares/__init__.py new file mode 100644 index 0000000..a05ac5f --- /dev/null +++ b/flask_jsonapi/middlewares/__init__.py @@ -0,0 +1,9 @@ +from .base import Middleware +from .pipeline import build_pipeline +from .required_filters import CheckRequiredListFilters + +__all__ = [ + 'Middleware', + 'CheckRequiredListFilters', + 'build_pipeline', +] diff --git a/flask_jsonapi/middlewares/base.py b/flask_jsonapi/middlewares/base.py new file mode 100644 index 0000000..0a43459 --- /dev/null +++ b/flask_jsonapi/middlewares/base.py @@ -0,0 +1,15 @@ +class Middleware: + def create(self, *, data, inner): + return inner.create(data=data) + + def read(self, *, id, inner): + return inner.read(id=id) + + def list(self, *, filters, sorting, pagination, inner): + return inner.list(filters=filters, sorting=sorting, pagination=pagination) + + def update(self, *, resource, data, inner): + return inner.update(resource=resource, data=data) + + def destroy(self, *, resource, inner): + return inner.destroy(resource=resource) diff --git a/flask_jsonapi/middlewares/pipeline.py b/flask_jsonapi/middlewares/pipeline.py new file mode 100644 index 0000000..bef8e48 --- /dev/null +++ b/flask_jsonapi/middlewares/pipeline.py @@ -0,0 +1,29 @@ +from flask_jsonapi import data_services + + +class _Link(data_services.DataService): + def __init__(self, middleware, inner): + self.middleware = middleware + self.inner = inner + + def create(self, *, data): + return self.middleware.create(data=data, inner=self.inner) + + def read(self, *, id): + return self.middleware.read(id=id, inner=self.inner) + + def list(self, *, filters, sorting, pagination): + return self.middleware.list(filters=filters, sorting=sorting, pagination=pagination, inner=self.inner) + + def update(self, *, resource, data): + return self.middleware.update(resource=resource, data=data, inner=self.inner) + + def destroy(self, *, resource): + return self.middleware.destroy(resource=resource, inner=self.inner) + + +def build_pipeline(middlewares, data_service): + pipeline = data_service + for middleware in reversed(middlewares): + pipeline = _Link(middleware, pipeline) + return pipeline diff --git a/flask_jsonapi/middlewares/required_filters.py b/flask_jsonapi/middlewares/required_filters.py new file mode 100644 index 0000000..8d5fbd3 --- /dev/null +++ b/flask_jsonapi/middlewares/required_filters.py @@ -0,0 +1,16 @@ +import typing + +from flask_jsonapi.data_services import exceptions + +from . import base + + +class CheckRequiredListFilters(base.Middleware): + def __init__(self, required_filters: typing.List[str]): + self.required_filters = required_filters + + def list(self, *, filters, sorting, pagination, inner): + for name in self.required_filters: + if name not in filters: + raise exceptions.InvalidFilterParameter('"{}" filter is required'.format(name)) + return inner.list(filters=filters, sorting=sorting, pagination=pagination) diff --git a/flask_jsonapi/permissions/__init__.py b/flask_jsonapi/permissions/__init__.py index d4277c4..3fc416c 100644 --- a/flask_jsonapi/permissions/__init__.py +++ b/flask_jsonapi/permissions/__init__.py @@ -6,20 +6,24 @@ from .checkers import ObjectLevelPermissionChecker from .checkers import PermissionChecker from .checkers import PermissionException +from .object_permissions import CheckObjectPermission +from .object_permissions import ObjectPermissions from .views import ProtectedDetailView from .views import ProtectedListView from .views import ProtectedViewSet __all__ = [ - CREATE_ACTION, - READ_ACTION, - UPDATE_ACTION, - DESTROY_ACTION, - LIST_ACTION, - PermissionChecker, - ObjectLevelPermissionChecker, - PermissionException, - ProtectedDetailView, - ProtectedListView, - ProtectedViewSet, + 'CREATE_ACTION', + 'READ_ACTION', + 'UPDATE_ACTION', + 'DESTROY_ACTION', + 'LIST_ACTION', + 'PermissionChecker', + 'ObjectLevelPermissionChecker', + 'PermissionException', + 'ObjectPermissions', + 'CheckObjectPermission', + 'ProtectedDetailView', + 'ProtectedListView', + 'ProtectedViewSet', ] diff --git a/flask_jsonapi/permissions/checkers.py b/flask_jsonapi/permissions/checkers.py index 174b1f3..11c98a9 100644 --- a/flask_jsonapi/permissions/checkers.py +++ b/flask_jsonapi/permissions/checkers.py @@ -10,9 +10,6 @@ class PermissionException(exceptions.JsonApiException): status = http.HTTPStatus.FORBIDDEN.value title = http.HTTPStatus.FORBIDDEN.phrase - def __init__(self, source=None, detail=None, *args, title=None, status=None, **kwargs): - super().__init__(source, detail, *args, title=title, status=status, **kwargs) - Resource = typing.TypeVar('Resource') diff --git a/flask_jsonapi/permissions/object_permissions.py b/flask_jsonapi/permissions/object_permissions.py new file mode 100644 index 0000000..a10c1b1 --- /dev/null +++ b/flask_jsonapi/permissions/object_permissions.py @@ -0,0 +1,71 @@ +import abc +import logging +import typing + +from flask_jsonapi import data_services +from flask_jsonapi import descriptors +from flask_jsonapi.permissions import checkers + +logger = logging.getLogger(__name__) + + +class ObjectPermissions(abc.ABC): + @abc.abstractmethod + def create(self, *, data, inner): + ... + + @abc.abstractmethod + def read(self, *, id, inner): + ... + + @abc.abstractmethod + def list(self, *, filters, sorting, pagination, inner): + ... + + @abc.abstractmethod + def update(self, *, resource, data, inner): + ... + + @abc.abstractmethod + def destroy(self, *, resource, inner): + ... + + +class CheckObjectPermission(ObjectPermissions): + permission_checker = descriptors.NotImplementedProperty('permission_checker') + + def __init__(self, permission_checker: typing.Optional[checkers.PermissionChecker] = None): + if permission_checker: + self.permission_checker = permission_checker + + def create(self, *, data, inner): + data = self.permission_checker.check_create_permission(data=data) + return inner.create(data=data) + + def read(self, *, id, inner): + resource = inner.read(id=id) + return self.permission_checker.check_read_permission(resource=resource) + + def list(self, *, filters, sorting, pagination, inner): + result = inner.list(filters=self.apply_permission_filter(filters), sorting=sorting, pagination=pagination) + permitted = self.permission_checker.check_list_permission(resources=result.items) + if len(permitted) == len(result.items): + return data_services.ListResult(permitted, result.total) + # The filter let through rows the check rejects, so the total counts objects the user may not see. + logger.warning('Object permission check dropped listed objects; the total is hidden.') + return data_services.ListResult(permitted, total=None) + + def update(self, *, resource, data, inner): + resource, data = self.permission_checker.check_update_permission(resource=resource, data=data) + return inner.update(resource=resource, data=data) + + def destroy(self, *, resource, inner): + resource = self.permission_checker.check_destroy_permission(resource=resource) + return inner.destroy(resource=resource) + + @abc.abstractmethod + def apply_permission_filter(self, filters: dict) -> dict: + """Return a new dict restricting the query to objects the user may list; never mutate ``filters``. + + Raise ``PermissionException`` (403) when the client's own filters ask for a scope the user may not list. + """ diff --git a/flask_jsonapi/permissions/views.py b/flask_jsonapi/permissions/views.py index e4b73ef..904f9da 100644 --- a/flask_jsonapi/permissions/views.py +++ b/flask_jsonapi/permissions/views.py @@ -9,6 +9,8 @@ class ProtectedDetailViewMixin: + """Deprecated since 1.5.0, use flask_jsonapi.permissions.CheckObjectPermission with flask_jsonapi.DetailView.""" + def __init__(self, permission_checker: checkers.PermissionChecker, **kwargs): super().__init__(**kwargs) self.permission_checker = permission_checker @@ -39,6 +41,8 @@ def protected_update(self, resource, data, **kwargs): class ProtectedListViewMixin(abc.ABC): + """Deprecated since 1.5.0, use flask_jsonapi.permissions.CheckObjectPermission with flask_jsonapi.ListView.""" + def __init__(self, permission_checker: checkers.PermissionChecker, **kwargs): super().__init__(**kwargs) self.permission_checker = permission_checker @@ -68,14 +72,20 @@ def protected_create(self, data: dict, **kwargs): class ProtectedDetailView(ProtectedDetailViewMixin, resource_repository_views.ResourceRepositoryDetailView): + """Deprecated since 1.5.0, use flask_jsonapi.DetailView with flask_jsonapi.permissions.CheckObjectPermission.""" + pass class ProtectedListView(ProtectedListViewMixin, resource_repository_views.ResourceRepositoryListView): + """Deprecated since 1.5.0, use flask_jsonapi.ListView with flask_jsonapi.permissions.CheckObjectPermission.""" + pass class ProtectedViewSet(resource_repository_views.ResourceRepositoryViewSet): + """Deprecated since 1.5.0, use flask_jsonapi.ViewSet with flask_jsonapi.permissions.CheckObjectPermission.""" + detail_view_cls = ProtectedDetailView list_view_cls: ProtectedListView permission_checker: checkers.PermissionChecker = descriptors.NotImplementedProperty('permission_checker') diff --git a/flask_jsonapi/query_string.py b/flask_jsonapi/query_string.py index 80a6c94..9149937 100644 --- a/flask_jsonapi/query_string.py +++ b/flask_jsonapi/query_string.py @@ -20,6 +20,9 @@ class Pagination(QueryStringParser): def get_links(self, *args, **kwargs): raise NotImplementedError + def get_links_without_total(self, *args, **kwargs): + raise NotImplementedError + class SizeNumberPagination(Pagination): def parse(self): @@ -43,6 +46,11 @@ def get_links(self, page_size, current_page, total_count): next_page = current_page + 1 if current_page < last_page else None return self._format_links(current_page, previous_page, next_page, last_page) + def get_links_without_total(self, page_size, current_page, item_count): + previous_page = current_page - 1 if current_page > 1 else None + next_page = current_page + 1 if item_count == page_size else None + return self._format_links(current_page, previous_page, next_page, last_page=None) + def _format_links(self, current_page, previous_page, next_page, last_page): request_args = flask.request.args.copy() request_args.pop('page[number]') @@ -53,7 +61,7 @@ def _format_links(self, current_page, previous_page, next_page, last_page): 'first': format_query_string.format(1), 'previous': format_query_string.format(previous_page) if previous_page else None, 'next': format_query_string.format(next_page) if next_page else None, - 'last': format_query_string.format(last_page), + 'last': format_query_string.format(last_page) if last_page is not None else None, } @staticmethod diff --git a/flask_jsonapi/resource_repositories/repositories.py b/flask_jsonapi/resource_repositories/repositories.py index fed61da..08d1b55 100644 --- a/flask_jsonapi/resource_repositories/repositories.py +++ b/flask_jsonapi/resource_repositories/repositories.py @@ -4,6 +4,8 @@ class ResourceRepository: + """Deprecated since 1.5.0, use flask_jsonapi.data_services.DataService.""" + def create(self, data, **kwargs): raise exceptions.NotImplementedMethod('Creating is not implemented.') diff --git a/flask_jsonapi/resource_repositories/sqlalchemy_repositories.py b/flask_jsonapi/resource_repositories/sqlalchemy_repositories.py index 5d505f7..2ca0fc8 100644 --- a/flask_jsonapi/resource_repositories/sqlalchemy_repositories.py +++ b/flask_jsonapi/resource_repositories/sqlalchemy_repositories.py @@ -13,6 +13,8 @@ class SqlAlchemyModelRepository(repositories.ResourceRepository): + """Deprecated since 1.5.0, use flask_jsonapi.data_services.sqlalchemy_repositories.SqlAlchemyModelRepository.""" + model = None session = None instance_name = 'model instance' diff --git a/flask_jsonapi/resource_repository_views.py b/flask_jsonapi/resource_repository_views.py index ba9da3a..c37bdad 100644 --- a/flask_jsonapi/resource_repository_views.py +++ b/flask_jsonapi/resource_repository_views.py @@ -5,6 +5,8 @@ class ResourceRepositoryViewMixin: + """Deprecated since 1.5.0, use the views built by flask_jsonapi.ViewSet.""" + repository = repositories.ResourceRepository() def __init__(self, *, repository=None, **kwargs): @@ -14,6 +16,8 @@ def __init__(self, *, repository=None, **kwargs): class ResourceRepositoryDetailView(ResourceRepositoryViewMixin, resources.ResourceDetail): + """Deprecated since 1.5.0, use flask_jsonapi.DetailView.""" + def read(self, id): return self.repository.get_detail(id) @@ -26,6 +30,8 @@ def update(self, id, data, **kwargs): class ResourceRepositoryListView(ResourceRepositoryViewMixin, resources.ResourceList): + """Deprecated since 1.5.0, use flask_jsonapi.ListView.""" + def read_many(self, filters, sorting, pagination): return self.repository.get_list(filters, sorting, pagination) @@ -37,6 +43,8 @@ def get_count(self, filters): class ResourceRepositoryViewSet: + """Deprecated since 1.5.0, use flask_jsonapi.ViewSet.""" + repository = repositories.ResourceRepository() schema = descriptors.NotImplementedProperty('schema') filter_schema = filters_schema.FilterSchema() diff --git a/flask_jsonapi/resources.py b/flask_jsonapi/resources.py index 0483839..27d1926 100644 --- a/flask_jsonapi/resources.py +++ b/flask_jsonapi/resources.py @@ -3,8 +3,8 @@ import logging import marshmallow +import werkzeug.exceptions -from flask import helpers from flask import request from flask import views from marshmallow_jsonapi import exceptions as marshmallow_jsonapi_exceptions @@ -39,23 +39,54 @@ def as_view(cls, name, *class_args, **class_kwargs): def dispatch_request(self, *args, **kwargs): self.args = args self.kwargs = kwargs - handler = getattr(self, request.method.lower(), self._http_method_not_allowed) + handler = self._handler_for(request.method) try: - response_object = handler(request, *args, **kwargs) + return handler(request, *args, **kwargs).make_response() except exceptions.JsonApiException as e: return response.JsonApiErrorResponse( e.to_dict(), status=e.status ).make_response() - else: - return response_object.make_response() + except werkzeug.exceptions.HTTPException as e: + if e.response is not None: + return e.response + if e.code is None: + return self._internal_server_error_response() + return response.JsonApiErrorResponse( + {'status': e.code, 'title': e.name}, + headers=self._forwarded_headers(e), + status=e.code + ).make_response() + except Exception: + logger.exception('Unhandled exception in %s %s', request.method, request.path) + return self._internal_server_error_response() + + def _handler_for(self, method): + handler = getattr(self, method.lower(), None) + if handler is None and method == 'HEAD': + handler = getattr(self, 'get', None) + return handler or self._http_method_not_allowed + + @staticmethod + def _forwarded_headers(http_exception): + return [ + (name, value) for name, value in http_exception.get_headers() + if name.lower() not in ('content-type', 'content-length') + ] + + @staticmethod + def _internal_server_error_response(): + return response.JsonApiErrorResponse( + {'status': http.HTTPStatus.INTERNAL_SERVER_ERROR.value, 'title': 'Internal server error'}, + status=http.HTTPStatus.INTERNAL_SERVER_ERROR + ).make_response() def _http_method_not_allowed(self, request, *args, **kwargs): logger.error( 'Method Not Allowed (%s): %s', request.method, request.path, extra={'status_code': http.HTTPStatus.METHOD_NOT_ALLOWED, 'request': request} ) - return helpers.make_response('Method Not Allowed.', http.HTTPStatus.METHOD_NOT_ALLOWED) + raise exceptions.MethodNotAllowed() class ResourceDetail(ResourceBase): @@ -70,12 +101,6 @@ def get(self, *args, **kwargs): data = self.schema(include_data=include_fields, only=sparse_fields).dump(resource) except marshmallow.ValidationError as e: raise exceptions.JsonApiException(detail='marshmallow.ValidationError', source=e.messages) - except (AttributeError, KeyError, ValueError) as e: - logger.error( - 'Error Processing Request', - extra={'status_code': http.HTTPStatus.BAD_REQUEST, 'request': request, 'exception': e} - ) - raise exceptions.JsonApiException(detail=str(e), source={'component': 'schema'}) else: return response.JsonApiResponse(data) @@ -88,6 +113,8 @@ def patch(self, *args, **kwargs): computed_schema = self.schema(partial=True) try: data = computed_schema.load(request.get_json()) + except marshmallow_jsonapi_exceptions.IncorrectTypeError as e: + return response.JsonApiErrorResponse.from_marshmallow_errors(e.messages, status=http.HTTPStatus.CONFLICT) except marshmallow.ValidationError as e: return response.JsonApiErrorResponse.from_marshmallow_errors(e.messages) else: @@ -132,7 +159,7 @@ def destroy(self, id): raise NotImplementedError -class ResourceList(ResourceBase): +class ListResourceBase(ResourceBase): methods = ['GET', 'POST'] filter_schema = filters_schema.FilterSchema() pagination = query_string.SizeNumberPagination() @@ -142,42 +169,20 @@ def __init__(self, *, filter_schema=None, **kwargs): if filter_schema: self.filter_schema = filter_schema - def get(self, *args, **kwargs): - parsed_filters = self.filter_schema.parse() - parsed_sorting = self.sort_parser.parse() - parsed_pagination = self.pagination.parse() - objects_list = self.read_many(filters=parsed_filters, - sorting=parsed_sorting, - pagination=parsed_pagination) + def _parse_list_query(self): + return { + 'filters': self.filter_schema.parse(), + 'sorting': self.sort_parser.parse(), + 'pagination': self.pagination.parse(), + } + + def _dump_list(self, objects_list): include_fields = self.include_parser.parse() sparse_fields = self.sparse_fields_parser.parse() try: - objects = self.schema( - many=True, include_data=include_fields, only=sparse_fields).dump(objects_list) + return self.schema(many=True, include_data=include_fields, only=sparse_fields).dump(objects_list) except marshmallow.ValidationError as e: raise exceptions.JsonApiException(detail='marshmallow.ValidationError', source=e.messages) - except (AttributeError, KeyError, ValueError) as e: - logger.error( - 'Error Processing Request', - extra={'status_code': http.HTTPStatus.BAD_REQUEST, 'request': request, 'exception': e} - ) - raise exceptions.JsonApiException(detail=str(e), source={'component': 'schema'}) - else: - pagination_links = self.get_pagination_links(parsed_pagination, parsed_filters) - return response.JsonApiListResponse( - response_data=objects, - links=pagination_links, - ) - - def get_pagination_links(self, parsed_pagination, parsed_filters): - if parsed_pagination: - page_size = parsed_pagination['size'] - current_page = parsed_pagination['number'] - total_count = self.get_count(filters=parsed_filters) - pagination_links = self.pagination.get_links(page_size, current_page, total_count) - else: - pagination_links = {} - return pagination_links def post(self, *args, **kwargs): try: @@ -196,25 +201,50 @@ def prepare_response(self, data): status=http.HTTPStatus.CREATED, ) - def read_many(self, filters, sorting, pagination): + def create(self, data, **kwargs): raise NotImplementedError - def get_count(self, filters): + +class ResourceList(ListResourceBase): + def get(self, *args, **kwargs): + query = self._parse_list_query() + objects_list = self.read_many(**query) + objects = self._dump_list(objects_list) + pagination_links = self.get_pagination_links(query['pagination'], query['filters']) + return response.JsonApiListResponse( + response_data=objects, + links=pagination_links, + ) + + def get_pagination_links(self, parsed_pagination, parsed_filters): + if parsed_pagination: + page_size = parsed_pagination['size'] + current_page = parsed_pagination['number'] + total_count = self.get_count(filters=parsed_filters) + pagination_links = self.pagination.get_links(page_size, current_page, total_count) + else: + pagination_links = {} + return pagination_links + + def read_many(self, filters, sorting, pagination): raise NotImplementedError - def create(self, data, **kwargs): + def get_count(self, filters): raise NotImplementedError class Actions: create = 'create' read = 'fetch' - read_many = 'fetch list' + list = 'fetch list' + read_many = list update = 'update' destroy = 'delete' def check_allowed_action(action: str): + """Deprecated since 1.5.0, use the allowed_actions of flask_jsonapi.ViewSet.""" + def decorate(func): @functools.wraps(func) def wrapper(self, *args, **kwargs): @@ -226,6 +256,8 @@ def wrapper(self, *args, **kwargs): class AllowedActionsResourceMixin: + """Deprecated since 1.5.0, use the allowed_actions of flask_jsonapi.ViewSet.""" + allowed_actions = () def __init__(self, *, allowed_actions=None, **kwargs): @@ -235,6 +267,8 @@ def __init__(self, *, allowed_actions=None, **kwargs): class AllowedActionsResourceDetailMixin(AllowedActionsResourceMixin): + """Deprecated since 1.5.0, use flask_jsonapi.DetailView.""" + @check_allowed_action(Actions.read) def get(self, *args, **kwargs): return super().get(*args, **kwargs) @@ -249,6 +283,8 @@ def delete(self, *args, **kwargs): class AllowedActionsResourceListMixin(AllowedActionsResourceMixin): + """Deprecated since 1.5.0, use flask_jsonapi.ListView.""" + @check_allowed_action(Actions.create) def post(self, *args, **kwargs): return super().post(*args, **kwargs) @@ -259,6 +295,8 @@ def get(self, *args, **kwargs): class AllowedActionsResourceViewSetMixin: + """Deprecated since 1.5.0, use flask_jsonapi.ViewSet.""" + detail_view_cls: AllowedActionsResourceMixin list_view_cls: AllowedActionsResourceMixin allowed_actions = () diff --git a/flask_jsonapi/views.py b/flask_jsonapi/views.py new file mode 100644 index 0000000..96fb38d --- /dev/null +++ b/flask_jsonapi/views.py @@ -0,0 +1,125 @@ +import functools +import logging + +from flask_jsonapi import exceptions +from flask_jsonapi import resources +from flask_jsonapi import response +from flask_jsonapi.data_services import exceptions as data_service_exceptions +from flask_jsonapi.middlewares import build_pipeline + +logger = logging.getLogger(__name__) + + +def translate_data_service_exception(error): + if isinstance(error, data_service_exceptions.ResourceNotFound): + return exceptions.ObjectNotFound(detail=error.detail) + if isinstance(error, data_service_exceptions.PermissionDenied): + return exceptions.ForbiddenError(detail=error.detail) + if isinstance(error, data_service_exceptions.InvalidData): + if error.field: + pointer = '/data/attributes/{}'.format(error.field) + return exceptions.AttributeValidationError(error.detail, source={'pointer': pointer}) + return exceptions.UnprocessableEntity(detail=error.detail) + if isinstance(error, data_service_exceptions.Conflict): + return exceptions.Conflict(detail=error.detail) + if isinstance(error, data_service_exceptions.InvalidSortParameter): + return exceptions.InvalidSort(error.detail) + if isinstance(error, data_service_exceptions.InvalidFilterParameter): + return exceptions.InvalidFilters(error.detail) + if isinstance(error, data_service_exceptions.Unavailable): + return exceptions.ServiceUnavailable(detail=error.detail) + logger.exception('Unexpected data service error', exc_info=error) + return exceptions.JsonApiException(status=500, title='Internal server error') + + +def _translating_data_service_errors(method): + @functools.wraps(method) + def wrapper(*args, **kwargs): + try: + return method(*args, **kwargs) + except data_service_exceptions.DataServiceException as error: + raise translate_data_service_exception(error) from error + return wrapper + + +class LayeredViewMixin: + def __init__(self, *, data_service, allowed_actions=(), guards=(), object_permissions=None, middlewares=(), + **kwargs): + super().__init__(**kwargs) + self.allowed_actions = allowed_actions + self.guards = guards + layers = middlewares if object_permissions is None else [object_permissions, *middlewares] + self.pipeline = build_pipeline(layers, data_service) + + def _authorize(self, action): + if action not in self.allowed_actions: + raise exceptions.MethodNotAllowed(detail='{} is not allowed for this resource'.format(action.capitalize())) + for guard in self.guards: + guard.check(action) + + +class DetailView(LayeredViewMixin, resources.ResourceDetail): + def get(self, *args, **kwargs): + self._authorize(resources.Actions.read) + return super().get(*args, **kwargs) + + def patch(self, *args, **kwargs): + self._authorize(resources.Actions.update) + return super().patch(*args, **kwargs) + + def delete(self, *args, **kwargs): + self._authorize(resources.Actions.destroy) + return super().delete(*args, **kwargs) + + @_translating_data_service_errors + def read(self, id): + return self._read_resource(id) + + @_translating_data_service_errors + def update(self, id, data, **kwargs): + resource = self._read_resource(id) + data_without_id = {key: value for key, value in data.items() if key != 'id'} + return self.pipeline.update(resource=resource, data=data_without_id) + + @_translating_data_service_errors + def destroy(self, id): + resource = self._read_resource(id) + return self.pipeline.destroy(resource=resource) + + def _read_resource(self, id): + resource = self.pipeline.read(id=id) + if resource is None: + raise exceptions.ObjectNotFound() + return resource + + +class ListView(LayeredViewMixin, resources.ListResourceBase): + def get(self, *args, **kwargs): + self._authorize(resources.Actions.list) + query = self._parse_list_query() + result = self._list(**query) + return response.JsonApiListResponse( + response_data=self._dump_list(result.items), + links=self._pagination_links(query['pagination'], result), + ) + + def post(self, *args, **kwargs): + self._authorize(resources.Actions.create) + return super().post(*args, **kwargs) + + @_translating_data_service_errors + def _list(self, filters, sorting, pagination): + return self.pipeline.list(filters=filters, sorting=sorting, pagination=pagination) + + def _pagination_links(self, parsed_pagination, result): + if not parsed_pagination: + return {} + page_size = parsed_pagination['size'] + current_page = parsed_pagination['number'] + if result.total is None: + return self.pagination.get_links_without_total(page_size, current_page, len(result.items)) + return self.pagination.get_links(page_size, current_page, result.total) + + @_translating_data_service_errors + def create(self, data, **kwargs): + return self.pipeline.create(data=data) diff --git a/flask_jsonapi/viewsets.py b/flask_jsonapi/viewsets.py new file mode 100644 index 0000000..22c5910 --- /dev/null +++ b/flask_jsonapi/viewsets.py @@ -0,0 +1,39 @@ +from flask_jsonapi import descriptors +from flask_jsonapi import filters_schema +from flask_jsonapi import views + + +class ViewSet: + detail_view_class = views.DetailView + list_view_class = views.ListView + schema_class = descriptors.NotImplementedProperty('schema_class') + data_service = descriptors.NotImplementedProperty('data_service') + filter_schema = filters_schema.FilterSchema() + allowed_actions = frozenset() + guards = () + object_permissions = None + middlewares = () + view_decorators = () + + def as_detail_view(self, view_name): + return self._decorate(self.detail_view_class.as_view(view_name, **self.get_views_kwargs())) + + def as_list_view(self, view_name): + return self._decorate( + self.list_view_class.as_view(view_name, filter_schema=self.filter_schema, **self.get_views_kwargs()) + ) + + def get_views_kwargs(self): + return { + 'schema': self.schema_class, + 'data_service': self.data_service, + 'allowed_actions': self.allowed_actions, + 'guards': self.guards, + 'object_permissions': self.object_permissions, + 'middlewares': self.middlewares, + } + + def _decorate(self, view): + for decorator in self.view_decorators: + view = decorator(view) + return view diff --git a/setup.py b/setup.py index 02aa711..8bba253 100644 --- a/setup.py +++ b/setup.py @@ -14,7 +14,7 @@ def get_long_description(): setup( name='flask-jsonapi', - version='1.4.2.dev0', + version='1.5.0.dev0', description='JSONAPI 1.0 implementation for Flask.', long_description=get_long_description(), long_description_content_type='text/markdown', diff --git a/tests/data_services/__init__.py b/tests/data_services/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/data_services/test_base.py b/tests/data_services/test_base.py new file mode 100644 index 0000000..845b58c --- /dev/null +++ b/tests/data_services/test_base.py @@ -0,0 +1,30 @@ +import dataclasses + +import pytest + +from flask_jsonapi import data_services +from flask_jsonapi.data_services import base + + +@pytest.mark.parametrize(argnames='call', argvalues=[ + lambda service: service.create(data={}), + lambda service: service.read(id=1), + lambda service: service.list(filters=None, sorting=None, pagination=None), + lambda service: service.update(resource=object(), data={}), + lambda service: service.destroy(resource=object()), +], ids=['create', 'read', 'list', 'update', 'destroy']) +def test_base_data_service_methods_are_not_implemented(call): + with pytest.raises(NotImplementedError): + call(base.DataService()) + + +def test_data_service_has_no_count(): + assert not hasattr(base.DataService, 'count') + + +def test_list_result_holds_items_and_total_and_is_frozen(): + result = data_services.ListResult(['a'], total=7) + + assert (result.items, result.total) == (['a'], 7) + with pytest.raises(dataclasses.FrozenInstanceError): + result.total = None diff --git a/tests/layers/__init__.py b/tests/layers/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/layers/conftest.py b/tests/layers/conftest.py new file mode 100644 index 0000000..2c63b37 --- /dev/null +++ b/tests/layers/conftest.py @@ -0,0 +1,116 @@ +import types + +import pytest + +from marshmallow_jsonapi import Schema +from marshmallow_jsonapi import fields + +from flask_jsonapi import data_services +from flask_jsonapi import guards +from flask_jsonapi import middlewares +from flask_jsonapi import permissions +from flask_jsonapi.data_services import exceptions as ds_exceptions + + +class ArticleSchema(Schema): + id = fields.Int() + title = fields.Str(required=True) + owner = fields.Str() + + class Meta: + type_ = 'articles' + self_view = 'articles_detail' + self_view_kwargs = {'id': ''} + self_view_many = 'articles_list' + + +class InMemoryArticles(data_services.DataService): + def __init__(self): + self.rows = {} + self.calls = [] + + def create(self, *, data): + self.calls.append(('create', {'data': data})) + row = types.SimpleNamespace(id=max(self.rows, default=0) + 1, title=None, owner=None) + vars(row).update(data) + self.rows[row.id] = row + return row + + def read(self, *, id): + self.calls.append(('read', {'id': id})) + try: + return self.rows[int(id)] + except (KeyError, ValueError): + raise ds_exceptions.ResourceNotFound('Article {} not found.'.format(id)) + + def list(self, *, filters, sorting, pagination): + self.calls.append(('list', {'filters': filters, 'sorting': sorting, 'pagination': pagination})) + rows = [self.rows[key] for key in sorted(self.rows)] + if pagination: + start = (pagination['number'] - 1) * pagination['size'] + return data_services.ListResult(rows[start:start + pagination['size']], total=len(rows)) + return data_services.ListResult(rows, total=None) + + def update(self, *, resource, data): + self.calls.append(('update', {'resource': resource, 'data': data})) + vars(resource).update(data) + return resource + + def destroy(self, *, resource): + self.calls.append(('destroy', {'resource': resource})) + del self.rows[resource.id] + + +class RecordingGuard(guards.Guard): + def __init__(self, log): + self.log = log + + def check(self, action): + self.log.append('guard') + + +class RecordingMiddleware(middlewares.Middleware): + def __init__(self, log, name): + self.log = log + self.name = name + + def read(self, *, id, inner): + self.log.append(self.name) + return inner.read(id=id) + + def list(self, *, filters, sorting, pagination, inner): + self.log.append(self.name) + return inner.list(filters=filters, sorting=sorting, pagination=pagination) + + +class RecordingObjectPermissions(permissions.ObjectPermissions): + def __init__(self, log): + self.log = log + + def create(self, *, data, inner): + self.log.append('object permissions') + return inner.create(data=data) + + def read(self, *, id, inner): + self.log.append('object permissions') + return inner.read(id=id) + + def list(self, *, filters, sorting, pagination, inner): + self.log.append('object permissions') + return inner.list(filters=filters, sorting=sorting, pagination=pagination) + + def update(self, *, resource, data, inner): + self.log.append('object permissions') + return inner.update(resource=resource, data=data) + + def destroy(self, *, resource, inner): + self.log.append('object permissions') + return inner.destroy(resource=resource) + + +@pytest.fixture +def articles(): + service = InMemoryArticles() + service.rows[1] = types.SimpleNamespace(id=1, title='first', owner='me') + service.rows[2] = types.SimpleNamespace(id=2, title='second', owner='other') + return service diff --git a/tests/layers/test_legacy_adapter.py b/tests/layers/test_legacy_adapter.py new file mode 100644 index 0000000..2af207f --- /dev/null +++ b/tests/layers/test_legacy_adapter.py @@ -0,0 +1,58 @@ +import types + +from unittest import mock + +import pytest + +from flask_jsonapi import data_services +from flask_jsonapi import exceptions + + +def test_update_puts_resource_id_into_data_and_returns_result(): + repository = mock.Mock() + adapter = data_services.LegacyRepositoryAdapter(repository) + result = adapter.update(resource=types.SimpleNamespace(id=7), data={'title': 'x'}) + repository.update.assert_called_once_with({'title': 'x', 'id': 7}) + assert result is repository.update.return_value + + +def test_destroy_passes_resource_id_to_legacy_delete(): + repository = mock.Mock() + data_services.LegacyRepositoryAdapter(repository).destroy(resource=types.SimpleNamespace(id=7)) + repository.delete.assert_called_once_with(7) + + +def test_reads_and_create_are_forwarded_to_legacy_methods(): + repository = mock.Mock() + adapter = data_services.LegacyRepositoryAdapter(repository) + adapter.create(data={'a': 1}) + adapter.read(id=3) + repository.create.assert_called_once_with({'a': 1}) + repository.get_detail.assert_called_once_with(3) + + +def test_paginated_list_returns_items_and_legacy_count(): + repository = mock.Mock() + result = data_services.LegacyRepositoryAdapter(repository).list( + filters={'f': 1}, sorting=['s'], pagination={'size': 1, 'number': 1}) + repository.get_list.assert_called_once_with({'f': 1}, ['s'], {'size': 1, 'number': 1}) + repository.get_count.assert_called_once_with({'f': 1}) + assert result == data_services.ListResult(repository.get_list.return_value, repository.get_count.return_value) + + +def test_unpaginated_list_does_not_count(): + repository = mock.Mock() + result = data_services.LegacyRepositoryAdapter(repository).list(filters={}, sorting=[], pagination={}) + assert result == data_services.ListResult(repository.get_list.return_value, None) + assert not repository.get_count.called + + +def test_adapter_has_no_count(): + assert not hasattr(data_services.LegacyRepositoryAdapter, 'count') + + +def test_legacy_jsonapi_exceptions_pass_through(): + repository = mock.Mock() + repository.get_detail.side_effect = exceptions.ObjectNotFound(source={}, detail='Missing.') + with pytest.raises(exceptions.ObjectNotFound): + data_services.LegacyRepositoryAdapter(repository).read(id=1) diff --git a/tests/layers/test_object_permissions.py b/tests/layers/test_object_permissions.py new file mode 100644 index 0000000..9060a6e --- /dev/null +++ b/tests/layers/test_object_permissions.py @@ -0,0 +1,175 @@ +import logging + +import pytest + +from flask_jsonapi import filters_schema +from flask_jsonapi import middlewares +from flask_jsonapi import permissions +from flask_jsonapi import views +from flask_jsonapi.resources import Actions +from tests.layers.conftest import ArticleSchema + + +class OwnerChecker(permissions.PermissionChecker): + def check_read_permission(self, *, resource): + if resource.owner != 'me': + raise permissions.PermissionException + return resource + + def check_destroy_permission(self, *, resource): + return self.check_read_permission(resource=resource) + + def check_update_permission(self, *, resource, data): + self.check_read_permission(resource=resource) + return resource, {**data, 'title': 'checked'} + + def check_create_permission(self, *, data): + return {'title': 'checked'} + + +class OwnerOnly(permissions.CheckObjectPermission): + def apply_permission_filter(self, filters): + return {**filters, 'owner': 'me'} + + +SAFETY_NET = 'Object permission check dropped listed objects; the total is hidden.' + + +@pytest.fixture +def pipeline(articles): + return middlewares.build_pipeline([OwnerOnly(OwnerChecker())], articles) + + +ACTIONS = ['create', 'read', 'list', 'update', 'destroy'] + + +@pytest.mark.parametrize('missing', ACTIONS) +def test_object_permissions_must_implement_every_action(missing): + methods = {name: lambda self, **kwargs: None for name in ACTIONS if name != missing} + incomplete = type('Incomplete', (permissions.ObjectPermissions,), methods) + + with pytest.raises(TypeError): + incomplete() + + +def test_object_permissions_with_every_action_can_be_instantiated(): + methods = {name: lambda self, **kwargs: None for name in ACTIONS} + type('Complete', (permissions.ObjectPermissions,), methods)() + + +def test_permission_classes_live_in_permissions_only(): + assert permissions.CheckObjectPermission.__module__ == 'flask_jsonapi.permissions.object_permissions' + assert {'ObjectPermissions', 'CheckObjectPermission'} <= set(permissions.__all__) + assert all(isinstance(name, str) for name in permissions.__all__) + assert sorted(middlewares.__all__) == ['CheckRequiredListFilters', 'Middleware', 'build_pipeline'] + assert not hasattr(middlewares, 'PermissionMiddleware') + assert not hasattr(middlewares, 'CheckObjectPermission') + + +def test_check_object_permission_must_implement_permission_filter(): + with pytest.raises(TypeError): + permissions.CheckObjectPermission(OwnerChecker()) + + +def test_permission_checker_must_be_provided(): + with pytest.raises(NotImplementedError): + OwnerOnly().permission_checker + + +def test_read_checks_read_permission(pipeline): + assert pipeline.read(id=1).id == 1 + + with pytest.raises(permissions.PermissionException): + pipeline.read(id=2) + + +def test_create_passes_on_data_returned_by_checker(pipeline, articles): + pipeline.create(data={'title': 'raw'}) + + assert articles.calls[-1] == ('create', {'data': {'title': 'checked'}}) + + +def test_update_passes_on_data_returned_by_checker(pipeline, articles): + resource = articles.rows[1] + + pipeline.update(resource=resource, data={'title': 'raw'}) + + assert articles.calls[-1] == ('update', {'resource': resource, 'data': {'title': 'checked'}}) + + +def test_update_and_destroy_check_their_permission(pipeline, articles): + other = articles.rows[2] + + with pytest.raises(permissions.PermissionException): + pipeline.update(resource=other, data={'title': 'raw'}) + with pytest.raises(permissions.PermissionException): + pipeline.destroy(resource=other) + + assert articles.calls == [] + assert 2 in articles.rows + + +def test_destroy_own_resource(pipeline, articles): + pipeline.destroy(resource=articles.rows[1]) + + assert articles.calls[-1][0] == 'destroy' + assert 1 not in articles.rows + + +def test_object_permissions_have_no_count(): + assert not hasattr(permissions.ObjectPermissions, 'count') + assert not hasattr(permissions.CheckObjectPermission, 'count') + + +def test_list_applies_filter_and_list_check(pipeline, articles): + filters = {} + + result = pipeline.list(filters=filters, sorting=[], pagination={}) + + assert [row.id for row in result.items] == [1] + assert articles.calls[-1] == ('list', {'filters': {'owner': 'me'}, 'sorting': [], 'pagination': {}}) + assert filters == {} + + +def test_safety_net_hides_the_total_and_logs_without_data(pipeline, caplog): + with caplog.at_level(logging.DEBUG): + result = pipeline.list(filters={}, sorting=[], pagination={'size': 10, 'number': 1}) + + assert ([row.id for row in result.items], result.total) == ([1], None) + assert [(record.levelno, record.getMessage()) for record in caplog.records] == [(logging.WARNING, SAFETY_NET)] + assert not hasattr(caplog.records[0], 'filters') + assert caplog.records[0].args == () + + +def test_list_keeps_the_total_when_nothing_was_dropped(articles, caplog): + del articles.rows[2] + pipeline = middlewares.build_pipeline([OwnerOnly(OwnerChecker())], articles) + + with caplog.at_level(logging.WARNING): + result = pipeline.list(filters={}, sorting=[], pagination={'size': 10, 'number': 1}) + + assert ([row.id for row in result.items], result.total) == ([1], 1) + assert caplog.records == [] + + +def test_permission_filter_refusing_the_scope_is_403_before_listing(api, jsonapi_client, articles): + class RefuseForeignOwner(permissions.CheckObjectPermission): + def apply_permission_filter(self, filters): + if filters.get('owner') not in (None, 'me'): + raise permissions.PermissionException(detail='You may not list this scope.') + return {**filters, 'owner': 'me'} + + class OwnerFilters(filters_schema.FilterSchema): + owner = filters_schema.FilterField() + + api.route(views.ListView, 'articles_list', '/articles/', view_kwargs={ + 'schema': ArticleSchema, 'data_service': articles, 'allowed_actions': {Actions.list}, + 'filter_schema': OwnerFilters(), + 'object_permissions': RefuseForeignOwner(OwnerChecker()), + }) + + response = jsonapi_client.get('/articles/?filter[owner]=other') + + assert response.status_code == 403 + assert response.get_json(force=True)['errors'][0]['detail'] == 'You may not list this scope.' + assert articles.calls == [] diff --git a/tests/layers/test_pipeline.py b/tests/layers/test_pipeline.py new file mode 100644 index 0000000..f92d674 --- /dev/null +++ b/tests/layers/test_pipeline.py @@ -0,0 +1,66 @@ +from unittest import mock + +import pytest + +from flask_jsonapi import data_services +from flask_jsonapi import middlewares +from flask_jsonapi.middlewares import pipeline as pipeline_module + + +class Recording(middlewares.Middleware): + def __init__(self, name, events): + self.name = name + self.events = events + + def update(self, *, resource, data, inner): + self.events.append(f'{self.name}:before') + result = inner.update(resource=resource, data=data) + self.events.append(f'{self.name}:after') + return result + + +def test_empty_pipeline_is_the_data_service(): + data_service = mock.Mock(spec=data_services.DataService) + assert middlewares.build_pipeline([], data_service) is data_service + + +def test_middlewares_run_in_list_order(): + events = [] + data_service = mock.Mock(spec=data_services.DataService) + data_service.update.side_effect = lambda **kwargs: events.append('service') + pipeline = middlewares.build_pipeline([Recording('a', events), Recording('b', events)], data_service) + pipeline.update(resource='r', data={}) + assert events == ['a:before', 'b:before', 'service', 'b:after', 'a:after'] + + +@pytest.mark.parametrize('method, kwargs', [ + ('create', {'data': {'a': 1}}), + ('read', {'id': 1}), + ('list', {'filters': {}, 'sorting': [], 'pagination': {}}), + ('update', {'resource': 'r', 'data': {}}), + ('destroy', {'resource': 'r'}), +]) +def test_base_middleware_passes_every_method_through(method, kwargs): + data_service = mock.Mock(spec=data_services.DataService) + pipeline = middlewares.build_pipeline([middlewares.Middleware()], data_service) + result = getattr(pipeline, method)(**kwargs) + getattr(data_service, method).assert_called_once_with(**kwargs) + assert result is getattr(data_service, method).return_value + + +@pytest.mark.parametrize('cls', [middlewares.Middleware, pipeline_module._Link]) +def test_pipeline_has_no_count(cls): + assert not hasattr(cls, 'count') + + +def test_middleware_can_call_inner_more_than_once(): + class ReadsBeforeUpdate(middlewares.Middleware): + def update(self, *, resource, data, inner): + inner.read(id=resource) + return inner.update(resource=resource, data=data) + + data_service = mock.Mock(spec=data_services.DataService) + pipeline = middlewares.build_pipeline([ReadsBeforeUpdate(), middlewares.Middleware()], data_service) + pipeline.update(resource=1, data={}) + data_service.read.assert_called_once_with(id=1) + data_service.update.assert_called_once_with(resource=1, data={}) diff --git a/tests/layers/test_required_filters.py b/tests/layers/test_required_filters.py new file mode 100644 index 0000000..bbe149f --- /dev/null +++ b/tests/layers/test_required_filters.py @@ -0,0 +1,26 @@ +import pytest + +from flask_jsonapi import middlewares +from flask_jsonapi.data_services import exceptions as ds_exceptions + + +def test_required_filters(articles): + pipeline = middlewares.build_pipeline([middlewares.CheckRequiredListFilters(['author_id'])], articles) + + with pytest.raises(ds_exceptions.InvalidFilterParameter) as error_info: + pipeline.list(filters={}, sorting=[], pagination={}) + + assert error_info.value.detail == '"author_id" filter is required' + assert articles.calls == [] + + +def test_required_filters_reports_first_missing_and_passes_when_present(articles): + pipeline = middlewares.build_pipeline( + [middlewares.CheckRequiredListFilters(['author_id', 'owner'])], articles) + + with pytest.raises(ds_exceptions.InvalidFilterParameter) as error_info: + pipeline.list(filters={'owner': 'me'}, sorting=[], pagination={}) + assert error_info.value.detail == '"author_id" filter is required' + + pipeline.list(filters={'author_id': 1, 'owner': 'me'}, sorting=[], pagination={}) + assert articles.calls[-1][0] == 'list' diff --git a/tests/layers/test_views.py b/tests/layers/test_views.py new file mode 100644 index 0000000..d1676e6 --- /dev/null +++ b/tests/layers/test_views.py @@ -0,0 +1,287 @@ +import types + +import flask +import pytest + +from flask_jsonapi import data_services +from flask_jsonapi import exceptions +from flask_jsonapi import guards +from flask_jsonapi import middlewares +from flask_jsonapi import views +from flask_jsonapi.data_services import exceptions as ds_exceptions +from flask_jsonapi.resources import Actions +from tests.layers.conftest import ArticleSchema +from tests.layers.conftest import RecordingGuard +from tests.layers.conftest import RecordingMiddleware +from tests.layers.conftest import RecordingObjectPermissions + +ALL = {Actions.create, Actions.read, Actions.list, Actions.update, Actions.destroy} +NEW_ARTICLE_BODY = {'data': {'type': 'articles', 'attributes': {'title': 'brand new', 'owner': 'me'}}} + + +def patch_body(id, **attributes): + return {'data': {'type': 'articles', 'id': str(id), 'attributes': attributes}} + + +@pytest.fixture +def register(api, articles): + def register_views(**view_kwargs): + view_kwargs.setdefault('allowed_actions', ALL) + view_kwargs.update(data_service=articles, schema=ArticleSchema) + api.route(views.DetailView, 'articles_detail', '/articles//', view_kwargs=view_kwargs) + api.route(views.ListView, 'articles_list', '/articles/', view_kwargs=view_kwargs) + return register_views + + +def error_document(response): + return response.get_json(force=True)['errors'] + + +def test_crud_round_trip(register, jsonapi_client): + register() + assert jsonapi_client.get('/articles/1/').status_code == 200 + assert len(jsonapi_client.get('/articles/').get_json(force=True)['data']) == 2 + assert jsonapi_client.post('/articles/', json=NEW_ARTICLE_BODY).status_code == 201 + patched = jsonapi_client.patch('/articles/1/', json=patch_body(1, title='new')) + assert (patched.status_code, patched.get_json(force=True)['data']['attributes']['title']) == (200, 'new') + assert jsonapi_client.delete('/articles/1/').status_code == 204 + + +@pytest.mark.parametrize('hook', ['read_many', 'get_count', 'get_pagination_links']) +def test_list_view_has_no_legacy_list_hooks(hook): + assert not hasattr(views.ListView, hook) + + +def test_read_many_is_an_alias_of_list(): + assert Actions.read_many == Actions.list + + +def test_read_many_in_allowed_actions_serves_lists(register, jsonapi_client): + register(allowed_actions={Actions.read_many}) + assert jsonapi_client.get('/articles/').status_code == 200 + + +def test_not_allowed_action_is_rejected_before_body_parsing(register, jsonapi_client): + register(allowed_actions={Actions.read}) + response = jsonapi_client.patch('/articles/1/', json=patch_body(1, title=5)) + assert response.status_code == 405 + assert error_document(response)[0]['detail'] == 'Update is not allowed for this resource' + + +def test_empty_allowed_actions_serves_nothing(api, jsonapi_client, articles): + view_kwargs = {'data_service': articles, 'schema': ArticleSchema} + api.route(views.DetailView, 'articles_detail', '/articles//', view_kwargs=view_kwargs) + api.route(views.ListView, 'articles_list', '/articles/', view_kwargs=view_kwargs) + assert jsonapi_client.get('/articles/').status_code == 405 + assert jsonapi_client.get('/articles/1/').status_code == 405 + + +def test_guards_run_before_body_parsing(register, jsonapi_client): + class Deny(guards.Guard): + def check(self, action): + raise exceptions.Unauthorized() + + register(guards=[Deny()]) + response = jsonapi_client.patch('/articles/1/', json=patch_body(1, title=5)) + assert response.status_code == 401 + + +def test_guards_run_in_order_with_the_action(register, jsonapi_client): + seen = [] + + class Recording(guards.Guard): + def __init__(self, name): + self.name = name + + def check(self, action): + seen.append((self.name, action)) + + register(guards=[Recording('first'), Recording('second')]) + assert jsonapi_client.patch('/articles/1/', json=patch_body(1, title='new')).status_code == 200 + assert seen == [('first', Actions.update), ('second', Actions.update)] + + +def test_guard_flask_abort_is_jsonapi(register, jsonapi_client): + class Abort(guards.Guard): + def check(self, action): + flask.abort(400) + + register(guards=[Abort()]) + response = jsonapi_client.get('/articles/') + assert response.status_code == 400 + assert response.headers['Content-Type'] == 'application/vnd.api+json' + + +def test_guard_base_class_is_abstract(): + with pytest.raises(NotImplementedError): + guards.Guard().check(Actions.read) + + +def test_patch_loads_once_and_hands_the_resource_down(register, jsonapi_client, articles): + register() + jsonapi_client.patch('/articles/1/', json=patch_body(1, title='new')) + assert [name for name, kwargs in articles.calls] == ['read', 'update'] + assert articles.calls[1][1]['resource'] is articles.rows[1] + assert 'id' not in articles.calls[1][1]['data'] + + +def test_delete_loads_once_and_hands_the_resource_down(register, jsonapi_client, articles): + register() + jsonapi_client.delete('/articles/1/') + assert [name for name, kwargs in articles.calls] == ['read', 'destroy'] + + +@pytest.mark.parametrize('error, status, expected_error', [ + (ds_exceptions.ResourceNotFound('Missing.'), 404, + {'status': 404, 'title': 'Object not found', 'detail': 'Missing.'}), + (ds_exceptions.PermissionDenied('No.'), 403, + {'status': 403, 'title': 'Operation forbidden.', 'detail': 'No.'}), + (ds_exceptions.InvalidData('Bad.', field='title'), 422, + {'status': 422, 'title': 'Attribute error', 'detail': 'Bad.', 'source': {'pointer': '/data/attributes/title'}}), + (ds_exceptions.InvalidData('Bad.'), 422, + {'status': 422, 'title': 'Unprocessable entity', 'detail': 'Bad.'}), + (ds_exceptions.Conflict('Taken.'), 409, + {'status': 409, 'title': 'Conflict', 'detail': 'Taken.'}), + (ds_exceptions.Unavailable('Later.'), 503, + {'status': 503, 'title': 'Service unavailable', 'detail': 'Later.'}), + (ds_exceptions.DataServiceException('SELECT secret'), 500, + {'status': 500, 'title': 'Internal server error'}), +]) +def test_data_service_errors_are_translated( + register, jsonapi_client, articles, monkeypatch, error, status, expected_error): + register() + + def fail(**kwargs): + raise error + monkeypatch.setattr(articles, 'read', fail) + response = jsonapi_client.get('/articles/1/') + assert response.status_code == status + assert error_document(response) == [expected_error] + + +def test_unexpected_data_service_error_is_logged(register, jsonapi_client, articles, monkeypatch, caplog): + register() + + def fail(**kwargs): + raise ds_exceptions.DataServiceException('SELECT secret') + monkeypatch.setattr(articles, 'read', fail) + jsonapi_client.get('/articles/1/') + assert any(record.name == 'flask_jsonapi.views' and record.exc_info for record in caplog.records) + + +@pytest.mark.parametrize('error, parameter', [ + (ds_exceptions.InvalidSortParameter('Bad sort.'), 'sort'), + (ds_exceptions.InvalidFilterParameter('Bad filter.'), 'filters'), +]) +def test_sort_and_filter_errors_are_400(register, jsonapi_client, articles, monkeypatch, error, parameter): + register() + + def fail(**kwargs): + raise error + monkeypatch.setattr(articles, 'list', fail) + response = jsonapi_client.get('/articles/') + assert response.status_code == 400 + assert error_document(response)[0]['source'] == {'parameter': parameter} + + +def test_patch_and_delete_of_missing_object_are_404(register, jsonapi_client): + register() + assert jsonapi_client.patch('/articles/999/', json=patch_body(999, title='x')).status_code == 404 + assert jsonapi_client.delete('/articles/999/').status_code == 404 + + +def test_paginated_list_makes_one_pipeline_call(register, jsonapi_client, articles): + recorded = [] + + class RecordList(middlewares.Middleware): + def list(self, *, filters, inner, **kwargs): + recorded.append(filters) + return inner.list(filters=filters, **kwargs) + + register(middlewares=[RecordList()]) + assert jsonapi_client.get('/articles/?page[size]=1&page[number]=1').status_code == 200 + assert recorded == [{}] + assert [name for name, kwargs in articles.calls] == ['list'] + + +def links_of(jsonapi_client, query): + response = jsonapi_client.get('/articles/?' + query) + assert response.status_code == 200 + return response.get_json(force=True)['links'] + + +def page_link(number, size): + return 'http://localhost/articles/?page[size]={}&page[number]={}'.format(size, number) + + +def test_links_come_from_the_list_total(register, jsonapi_client): + register() + assert links_of(jsonapi_client, 'page[size]=1&page[number]=1') == { + 'self': page_link(1, size=1), + 'first': page_link(1, size=1), + 'previous': None, + 'next': page_link(2, size=1), + 'last': page_link(2, size=1), + } + + +def test_unpaginated_list_has_no_links(register, jsonapi_client): + register() + assert 'links' not in jsonapi_client.get('/articles/').get_json(force=True) + + +@pytest.mark.parametrize('size, number, expected_previous, expected_next', [ + (2, 1, None, 2), + (4, 1, None, None), + (1, 2, 1, 3), + (2, 2, 1, None), +]) +def test_links_without_total_have_no_last_and_next_only_for_a_full_page( + register, jsonapi_client, articles, monkeypatch, size, number, expected_previous, expected_next): + register() + paginated_list = articles.list + monkeypatch.setattr(articles, 'list', lambda **kwargs: data_services.ListResult( + paginated_list(**kwargs).items, total=None)) + articles.rows[3] = types.SimpleNamespace(id=3, title='third', owner='me') + + links = links_of(jsonapi_client, 'page[size]={}&page[number]={}'.format(size, number)) + + assert links == { + 'self': page_link(number, size), + 'first': page_link(1, size), + 'previous': page_link(expected_previous, size) if expected_previous else None, + 'next': page_link(expected_next, size) if expected_next else None, + 'last': None, + } + + +@pytest.mark.parametrize('method', ['get', 'patch', 'delete']) +def test_missing_resource_from_data_service_is_404(register, jsonapi_client, articles, monkeypatch, method): + register() + monkeypatch.setattr(articles, 'read', lambda **kwargs: None) + response = getattr(jsonapi_client, method)('/articles/1/', json=patch_body(1, title='x')) + assert response.status_code == 404 + assert error_document(response)[0]['status'] == 404 + assert [name for name, kwargs in articles.calls] == [] + + +@pytest.mark.parametrize('url, data_service_call', [('/articles/', 'list'), ('/articles/1/', 'read')]) +def test_object_permissions_run_after_guards_and_before_every_middleware( + register, jsonapi_client, articles, url, data_service_call): + log = [] + register( + guards=[RecordingGuard(log)], + object_permissions=RecordingObjectPermissions(log), + middlewares=[RecordingMiddleware(log, 'first middleware'), RecordingMiddleware(log, 'second middleware')], + ) + assert jsonapi_client.get(url).status_code == 200 + assert log == ['guard', 'object permissions', 'first middleware', 'second middleware'] + assert [name for name, kwargs in articles.calls] == [data_service_call] + + +@pytest.mark.parametrize('view_kwargs', [{}, {'object_permissions': None}]) +@pytest.mark.parametrize('view_class', [views.DetailView, views.ListView]) +def test_without_object_permissions_the_pipeline_has_no_extra_layer(articles, view_class, view_kwargs): + middleware = middlewares.Middleware() + view = view_class(schema=ArticleSchema, data_service=articles, middlewares=[middleware], **view_kwargs) + assert (view.pipeline.middleware, view.pipeline.inner) == (middleware, articles) diff --git a/tests/layers/test_viewsets.py b/tests/layers/test_viewsets.py new file mode 100644 index 0000000..39b836b --- /dev/null +++ b/tests/layers/test_viewsets.py @@ -0,0 +1,120 @@ +import subprocess +import sys + +import pytest + +import flask_jsonapi + +from flask_jsonapi import exceptions +from flask_jsonapi import filters_schema +from flask_jsonapi import guards +from flask_jsonapi import viewsets +from flask_jsonapi.resources import Actions +from tests.layers.conftest import ArticleSchema +from tests.layers.conftest import RecordingGuard +from tests.layers.conftest import RecordingObjectPermissions + + +class DenyAll(guards.Guard): + def check(self, action): + raise exceptions.Unauthorized(detail='denied') + + +def make_viewset(articles, **attributes): + attributes.update(schema_class=ArticleSchema, data_service=articles) + return type('ArticleViewSet', (viewsets.ViewSet,), attributes)() + + +def test_viewset_serves_list_and_detail(api, jsonapi_client, articles): + api.repository(make_viewset(articles, allowed_actions={Actions.read, Actions.list}), 'articles', '/articles/') + assert jsonapi_client.get('/articles/').status_code == 200 + assert jsonapi_client.get('/articles/1/').status_code == 200 + + +def test_filter_schema_reaches_the_list_view(api, jsonapi_client, articles): + class OwnerFilters(filters_schema.FilterSchema): + owner = filters_schema.FilterField() + + viewset = make_viewset(articles, allowed_actions={Actions.list}, filter_schema=OwnerFilters()) + api.repository(viewset, 'articles', '/articles/') + assert jsonapi_client.get('/articles/?filter[owner]=me').status_code == 200 + assert [kwargs['filters'] for name, kwargs in articles.calls if name == 'list'] == [{'owner': 'me'}] + + +def test_viewset_without_allowed_actions_serves_nothing(api, jsonapi_client, articles): + api.repository(make_viewset(articles), 'articles', '/articles/') + assert jsonapi_client.get('/articles/').status_code == 405 + assert jsonapi_client.get('/articles/1/').status_code == 405 + + +def test_subclass_replaces_guards(api, jsonapi_client, articles): + class Public(viewsets.ViewSet): + schema_class = ArticleSchema + data_service = articles + allowed_actions = {Actions.list} + guards = [DenyAll()] + + class Internal(Public): + guards = [] + + api.repository(Public(), 'public', '/public/') + api.repository(Internal(), 'internal', '/internal/') + public_status = jsonapi_client.get('/public/').status_code + internal_status = jsonapi_client.get('/internal/').status_code + assert (public_status, internal_status) == (401, 200) + + +def test_subclass_switches_off_guards_and_object_permissions(api, jsonapi_client, articles): + log = [] + + class Public(viewsets.ViewSet): + schema_class = ArticleSchema + data_service = articles + allowed_actions = {Actions.read, Actions.list} + guards = [RecordingGuard(log)] + object_permissions = RecordingObjectPermissions(log) + + class Internal(Public): + guards = [] + object_permissions = None + + api.repository(Public(), 'public', '/public/') + api.repository(Internal(), 'internal', '/internal/') + public_statuses = [jsonapi_client.get(url).status_code for url in ['/public/', '/public/1/']] + assert (public_statuses, log) == ([200, 200], ['guard', 'object permissions'] * 2) + log.clear() + internal_statuses = [jsonapi_client.get(url).status_code for url in ['/internal/', '/internal/1/']] + assert (internal_statuses, log) == ([200, 200], []) + + +def test_view_decorators_wrap_both_views(api, jsonapi_client, articles): + wrapped = [] + + def record_endpoint(view): + wrapped.append(view.__name__) + return view + + viewset = make_viewset(articles, view_decorators=[record_endpoint]) + api.repository(viewset, 'articles', '/articles/') + assert sorted(wrapped) == ['articles_detail', 'articles_list'] + + +def test_missing_data_service_is_reported(api): + class NoDataServiceViewSet(viewsets.ViewSet): + schema_class = ArticleSchema + + with pytest.raises(NotImplementedError): + api.repository(NoDataServiceViewSet(), 'broken', '/broken/') + + +def test_public_api_exports_layered_classes(): + assert flask_jsonapi.ViewSet is viewsets.ViewSet + assert flask_jsonapi.Actions is Actions + assert all(isinstance(name, str) for name in flask_jsonapi.__all__) + + +def test_new_api_imports_without_sqlalchemy(): + code = ("import sys; sys.modules['sqlalchemy'] = None; " + "import flask_jsonapi, flask_jsonapi.viewsets, flask_jsonapi.views, flask_jsonapi.guards, " + "flask_jsonapi.middlewares, flask_jsonapi.permissions, flask_jsonapi.data_services") + subprocess.run([sys.executable, '-c', code], check=True) diff --git a/tests/sqlalchemy_repository/test_data_service_repository.py b/tests/sqlalchemy_repository/test_data_service_repository.py new file mode 100644 index 0000000..de505c4 --- /dev/null +++ b/tests/sqlalchemy_repository/test_data_service_repository.py @@ -0,0 +1,348 @@ +import contextlib +import logging + +from unittest import mock + +import pytest +import sqlalchemy +import sqlalchemy.exc +import sqlalchemy.orm + +from flask_jsonapi.data_services import exceptions +from flask_jsonapi.data_services import sqlalchemy_repositories + +Base = sqlalchemy.orm.declarative_base() + + +class Article(Base): + __tablename__ = 'articles' + id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True) + title = sqlalchemy.Column(sqlalchemy.String, unique=True) + + +@pytest.fixture +def repository(db_session): + class ArticleRepository(sqlalchemy_repositories.SqlAlchemyModelRepository): + model = Article + session = db_session + + return ArticleRepository() + + +def repository_log_records(caplog): + return [record for record in caplog.records if record.name == sqlalchemy_repositories.logger.name] + + +@contextlib.contextmanager +def recorded_statements(engine): + statements = [] + + def record(conn, cursor, statement, parameters, context, executemany): + statements.append(statement) + + sqlalchemy.event.listen(engine, 'before_cursor_execute', record) + try: + yield statements + finally: + sqlalchemy.event.remove(engine, 'before_cursor_execute', record) + + +@contextlib.contextmanager +def spy_on_with_for_update(): + real = sqlalchemy.orm.Query.with_for_update + with mock.patch.object(sqlalchemy.orm.Query, 'with_for_update', autospec=True, side_effect=real) as spy: + yield spy + + +@contextlib.contextmanager +def concurrent_insert_before_flush(repository, engine, **row): + """Another transaction inserts the row between our lookup and our insert. + + The unique violation is real and happens where PostgreSQL raises it, when the savepoint block flushes. Only the + message is rewritten to PostgreSQL's wording, which the repository matches on and SQLite does not produce. + """ + original_build = repository.build + + def build_after_competing_insert(data): + repository.session.execute(sqlalchemy.insert(Article).values(**row)) + return original_build(data) + + def with_postgres_message(context): + if 'UNIQUE constraint failed' in str(context.original_exception): + postgres_error = Exception('duplicate key value violates unique constraint "articles_key"') + return sqlalchemy.exc.IntegrityError(context.statement, context.parameters, postgres_error) + + sqlalchemy.event.listen(engine, 'handle_error', with_postgres_message) + try: + with mock.patch.object(repository, 'build', side_effect=build_after_competing_insert): + yield + finally: + sqlalchemy.event.remove(engine, 'handle_error', with_postgres_message) + + +@pytest.mark.parametrize(argnames='setup_db_schema', argvalues=[Base], indirect=True) +@pytest.mark.usefixtures('setup_db_schema') +class TestDataServiceRepository: + def test_read_of_missing_row_raises_resource_not_found(self, repository): + with pytest.raises(exceptions.ResourceNotFound): + repository.read(id=404) + + def test_update_uses_given_resource_without_selecting(self, repository, db_engine, db_session): + article = repository.create(data={'title': 'old'}) + db_session.refresh(article) + with recorded_statements(db_engine) as statements: + updated = repository.update(resource=article, data={'title': 'new'}) + assert not [s for s in statements if s.lstrip().upper().startswith('SELECT')] + assert updated.title == 'new' + + def test_destroy_deletes_given_resource(self, repository): + article = repository.create(data={'title': 'gone'}) + repository.destroy(resource=article) + assert repository.list().items == [] + + def test_list_applies_filters_to_items_and_total(self, repository): + repository.create(data={'title': 'a'}) + repository.create(data={'title': 'b'}) + result = repository.list(filters={'title': 'b'}, pagination={'size': 10, 'number': 1}) + assert ([a.title for a in result.items], result.total) == (['b'], 1) + + def test_unpaginated_list_has_no_total_and_does_not_count(self, repository, db_engine): + repository.create(data={'title': 'a'}) + with recorded_statements(db_engine) as statements: + result = repository.list() + assert ([a.title for a in result.items], result.total) == (['a'], None) + assert len(statements) == 1 + assert 'count(' not in statements[0].lower() + + def test_paginated_list_counts_and_slices_one_filtered_query(self, repository, db_engine): + for title in ['ab', 'ac', 'ad', 'bc']: + repository.create(data={'title': title}) + repository.filter_methods_map = {'title_prefix': lambda value: Article.title.startswith(value)} + with mock.patch.object(repository, 'apply_filters', wraps=repository.apply_filters) as apply_filters, \ + recorded_statements(db_engine) as statements: + result = repository.list( + filters={'title_prefix': 'a'}, sorting=['-title'], pagination={'size': 2, 'number': 2}) + assert ([a.title for a in result.items], result.total) == (['ab'], 3) + assert apply_filters.call_count == 1 + count_statements = [s for s in statements if 'count(' in s.lower()] + assert len(statements) == 2 + assert len(count_statements) == 1 + assert 'ORDER BY' not in count_statements[0].upper() + + def test_invalid_sort_raises_invalid_sort_parameter(self, repository): + with pytest.raises(exceptions.InvalidSortParameter): + repository.list(sorting=['nonexistent']) + + def test_invalid_filter_raises_invalid_filter_parameter(self, repository): + with pytest.raises(exceptions.InvalidFilterParameter): + repository.list(filters={'nonexistent': 1}) + + def test_duplicate_raises_conflict_and_session_stays_usable(self, repository): + repository.create(data={'title': 'same'}) + with pytest.raises(exceptions.Conflict): + repository.create(data={'title': 'same'}) + assert repository.create(data={'title': 'other'}).title == 'other' + + def test_conflict_is_logged_as_info_without_parameters(self, repository, caplog): + caplog.set_level(logging.DEBUG) + repository.create(data={'title': 'secret title'}) + with pytest.raises(exceptions.Conflict): + repository.create(data={'title': 'secret title'}) + records = repository_log_records(caplog) + assert [record.levelno for record in records] == [logging.INFO] + assert 'secret title' not in records[0].getMessage() + assert records[0].exc_info is None + + def test_operational_error_raises_unavailable_and_rolls_back(self, repository, caplog): + error = sqlalchemy.exc.OperationalError('x', {}, Exception()) + with mock.patch.object(repository.session, 'commit', side_effect=error), \ + mock.patch.object(repository.session, 'rollback') as rollback: + with pytest.raises(exceptions.Unavailable): + repository.create(data={'title': 'a'}) + assert rollback.called + records = repository_log_records(caplog) + assert [record.levelno for record in records] == [logging.WARNING] + assert records[0].exc_info + + def test_failed_read_rolls_back(self, repository): + error = sqlalchemy.exc.OperationalError('x', {}, Exception()) + with mock.patch.object(repository, 'apply_filters', side_effect=error), \ + mock.patch.object(repository.session, 'rollback') as rollback: + with pytest.raises(exceptions.Unavailable): + repository.list() + assert rollback.called + + @pytest.mark.parametrize(argnames='call, patched, expected', argvalues=[ + (lambda repository: repository.read(id='not-a-number'), 'get_query', exceptions.ResourceNotFound), + (lambda repository: repository.list(), 'apply_filters', exceptions.InvalidFilterParameter), + (lambda repository: repository.create(data={'title': 'a'}), 'build', exceptions.InvalidData), + (lambda repository: repository.update(resource=Article(), data={'title': 'a'}), 'update_attribute', + exceptions.InvalidData), + ], ids=['read', 'list', 'create', 'update']) + def test_data_error_is_translated_by_method_and_rolls_back(self, repository, caplog, call, patched, expected): + caplog.set_level(logging.DEBUG) + error = sqlalchemy.exc.DataError('SELECT secret', {'id': 'secret value'}, Exception('invalid input')) + with mock.patch.object(repository, patched, side_effect=error), \ + mock.patch.object(repository.session, 'rollback') as rollback: + with pytest.raises(expected) as error_info: + call(repository) + assert type(error_info.value) is expected + assert rollback.called + assert 'secret' not in str(error_info.value.detail) + records = repository_log_records(caplog) + assert [record.levelno for record in records] == [logging.INFO] + assert 'secret' not in records[0].getMessage() + assert records[0].exc_info is None + + def test_other_database_error_raises_generic_exception_without_logging(self, repository, caplog): + caplog.set_level(logging.DEBUG) + error = sqlalchemy.exc.SQLAlchemyError('x') + with mock.patch.object(repository.session, 'commit', side_effect=error): + with pytest.raises(exceptions.DataServiceException) as error_info: + repository.create(data={'title': 'a'}) + assert type(error_info.value) is exceptions.DataServiceException + assert repository_log_records(caplog) == [] + + def test_update_or_create_refreshes_loaded_objects(self, repository): + article = repository.create(data={'title': 'old'}, strategy='flush') + repository.update_or_create(update_data={'title': 'new'}, strategy='flush', id=article.id) + assert article.title == 'new' + + def test_list_applies_custom_filter_methods(self, repository): + repository.filter_methods_map = {'title_prefix': lambda value: Article.title.startswith(value)} + repository.create(data={'title': 'ab'}) + repository.create(data={'title': 'ac'}) + repository.create(data={'title': 'bc'}) + result = repository.list(filters={'title_prefix': 'a'}, pagination={'size': 10, 'number': 1}) + assert (sorted(a.title for a in result.items), result.total) == (['ab', 'ac'], 2) + assert [a.title for a in repository.list(filters={'title_prefix': 'a', 'title': 'ac'}).items] == ['ac'] + + +@pytest.mark.parametrize(argnames='setup_db_schema', argvalues=[Base], indirect=True) +@pytest.mark.usefixtures('setup_db_schema') +class TestGetOrCreate: + def test_returns_existing_row_without_inserting(self, repository, db_engine): + existing = repository.create(data={'title': 'a'}) + with recorded_statements(db_engine) as statements: + found = repository.get_or_create(title='a', create_data={'id': 99}) + assert found is existing + assert not [s for s in statements if s.lstrip().upper().startswith('INSERT')] + assert len(repository.list().items) == 1 + + def test_creates_row_from_lookup_kwargs_and_create_data(self, repository): + created = repository.get_or_create(title='a', create_data={'id': 7}) + assert (created.id, created.title) == (7, 'a') + assert [a.id for a in repository.list().items] == [7] + + def test_creates_row_without_create_data(self, repository): + created = repository.get_or_create(title='a') + assert created.title == 'a' + assert len(repository.list().items) == 1 + + def test_commits_by_default(self, repository): + with mock.patch.object(repository.session, 'commit', wraps=repository.session.commit) as commit: + repository.get_or_create(title='a') + assert commit.called + + def test_flush_strategy_does_not_commit(self, repository): + with mock.patch.object(repository.session, 'commit') as commit: + created = repository.get_or_create(title='a', strategy='flush') + assert not commit.called + assert created.id is not None + assert len(repository.list().items) == 1 + + def test_for_update_returns_existing_row_and_requests_the_lock(self, repository): + existing = repository.create(data={'title': 'a'}) + with spy_on_with_for_update() as with_for_update: + assert repository.get_or_create(title='a', for_update=True) is existing + assert with_for_update.call_count == 1 + + def test_for_update_creates_missing_row_and_requests_the_lock(self, repository): + with spy_on_with_for_update() as with_for_update: + created = repository.get_or_create(title='a', for_update=True) + assert created.title == 'a' + assert len(repository.list().items) == 1 + assert with_for_update.call_count == 1 + + def test_lock_is_not_requested_by_default(self, repository): + with spy_on_with_for_update() as with_for_update: + repository.get_or_create(title='a') + assert not with_for_update.called + + def test_create_data_wins_over_lookup_kwargs(self, repository): + created = repository.get_or_create(title='lookup', create_data={'title': 'created'}) + assert created.title == 'created' + + def test_duplicate_key_race_returns_row_found_by_second_lookup(self, repository, db_engine): + with concurrent_insert_before_flush(repository, db_engine, title='a'): + found = repository.get_or_create(title='a', strategy='flush') + assert found.title == 'a' + assert len(repository.list().items) == 1 + + def test_other_integrity_error_is_translated_to_conflict(self, repository): + repository.create(data={'title': 'taken'}) + with pytest.raises(exceptions.Conflict): + repository.get_or_create(id=7, create_data={'title': 'taken'}) + assert repository.get_or_create(title='c').title == 'c' + + def test_data_error_is_translated_and_rolls_back(self, repository): + error = sqlalchemy.exc.DataError('SELECT secret', {}, Exception('invalid input')) + with mock.patch.object(repository, 'build', side_effect=error), \ + mock.patch.object(repository.session, 'rollback') as rollback: + with pytest.raises(exceptions.InvalidData) as error_info: + repository.get_or_create(title='a') + assert rollback.called + assert 'secret' not in str(error_info.value.detail) + + +@pytest.mark.parametrize(argnames='setup_db_schema', argvalues=[Base], indirect=True) +@pytest.mark.usefixtures('setup_db_schema') +class TestUpdateOrCreate: + def test_plain_update_of_matching_row_returns_none(self, repository): + article = repository.create(data={'title': 'old'}) + result = repository.update_or_create(update_data={'title': 'new'}, id=article.id) + assert result is None + assert [a.title for a in repository.list().items] == ['new'] + + def test_creates_row_from_lookup_kwargs_and_update_data_when_nothing_matches(self, repository): + created = repository.update_or_create(update_data={'title': 'a'}, id=7) + assert (created.id, created.title) == (7, 'a') + assert len(repository.list().items) == 1 + + def test_commits_by_default_on_update_and_on_create(self, repository): + article = repository.create(data={'title': 'old'}) + with mock.patch.object(repository.session, 'commit', wraps=repository.session.commit) as commit: + repository.update_or_create(update_data={'title': 'new'}, id=article.id) + assert commit.call_count == 1 + repository.update_or_create(update_data={'title': 'a'}, id=article.id + 1) + assert commit.call_count == 2 + + def test_flush_strategy_does_not_commit(self, repository): + with mock.patch.object(repository.session, 'commit') as commit: + created = repository.update_or_create(update_data={'title': 'a'}, strategy='flush', id=7) + repository.update_or_create(update_data={'title': 'b'}, strategy='flush', id=7) + assert not commit.called + assert created.id == 7 + assert [a.title for a in repository.list().items] == ['b'] + + def test_update_data_wins_over_lookup_kwargs_on_create(self, repository): + created = repository.update_or_create(update_data={'id': 8}, id=7) + assert created.id == 8 + + def test_duplicate_key_race_updates_instead(self, repository, db_engine): + with concurrent_insert_before_flush(repository, db_engine, id=7, title='inserted by another transaction'): + repository.update_or_create(update_data={'title': 'a'}, strategy='flush', id=7) + assert [(a.id, a.title) for a in repository.list().items] == [(7, 'a')] + + def test_duplicate_key_race_commits_by_default(self, repository, db_engine): + with concurrent_insert_before_flush(repository, db_engine, id=7, title='other'), \ + mock.patch.object(repository.session, 'commit', wraps=repository.session.commit) as commit: + repository.update_or_create(update_data={'title': 'a'}, id=7) + assert commit.call_count == 1 + + def test_other_integrity_error_is_translated_to_conflict(self, repository): + repository.create(data={'title': 'taken'}) + with pytest.raises(exceptions.Conflict): + repository.update_or_create(update_data={'title': 'taken'}, id=7) + assert len(repository.list().items) == 1 + assert repository.update_or_create(update_data={'title': 'free'}, id=7).title == 'free' diff --git a/tests/sqlalchemy_repository/test_layers_integration.py b/tests/sqlalchemy_repository/test_layers_integration.py new file mode 100644 index 0000000..b56f988 --- /dev/null +++ b/tests/sqlalchemy_repository/test_layers_integration.py @@ -0,0 +1,210 @@ +import contextlib +import json +import logging + +import marshmallow_jsonapi +import pytest +import sqlalchemy +import sqlalchemy.orm + +from marshmallow_jsonapi import fields + +import flask_jsonapi + +from flask_jsonapi import data_services +from flask_jsonapi import permissions +from flask_jsonapi.data_services import sqlalchemy_repositories +from flask_jsonapi.resource_repositories import sqlalchemy_repositories as legacy_sqlalchemy_repositories + +Base = sqlalchemy.orm.declarative_base() + +OWNER = 'me' +OTHER = 'someone else' + + +class Article(Base): + __tablename__ = 'articles' + id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True) + title = sqlalchemy.Column(sqlalchemy.String, unique=True) + owner = sqlalchemy.Column(sqlalchemy.String) + + +class ArticleSchema(marshmallow_jsonapi.Schema): + id = fields.Int() + title = fields.Str() + owner = fields.Str() + + class Meta: + type_ = 'articles' + + +class OwnerChecker(permissions.PermissionChecker): + def check_read_permission(self, *, resource): + return self._check(resource) + + def check_destroy_permission(self, *, resource): + return self._check(resource) + + def check_update_permission(self, *, resource, data): + return self._check(resource), data + + def check_create_permission(self, *, data): + return data + + @staticmethod + def _check(resource): + if resource.owner != OWNER: + raise permissions.PermissionException + return resource + + +class OwnerOnly(permissions.CheckObjectPermission): + permission_checker = OwnerChecker() + + def apply_permission_filter(self, filters): + return {**filters, 'owner': OWNER} + + +@contextlib.contextmanager +def recorded_statements(engine): + statements = [] + + def record(conn, cursor, statement, parameters, context, executemany): + statements.append(statement) + + sqlalchemy.event.listen(engine, 'before_cursor_execute', record) + try: + yield statements + finally: + sqlalchemy.event.remove(engine, 'before_cursor_execute', record) + + +def make_viewset(data_service): + class ArticleViewSet(flask_jsonapi.ViewSet): + schema_class = ArticleSchema + allowed_actions = { + flask_jsonapi.Actions.create, + flask_jsonapi.Actions.read, + flask_jsonapi.Actions.list, + flask_jsonapi.Actions.update, + flask_jsonapi.Actions.destroy, + } + object_permissions = OwnerOnly() + + ArticleViewSet.data_service = data_service + return ArticleViewSet() + + +def article_body(**attributes): + return json.dumps({'data': {'type': 'articles', **attributes}}) + + +@pytest.fixture +def articles(db_session): + class ArticleRepository(sqlalchemy_repositories.SqlAlchemyModelRepository): + model = Article + session = db_session + + return ArticleRepository() + + +@pytest.fixture +def seed(db_session): + def add(*rows): + for id, title, owner in rows: + db_session.add(Article(id=id, title=title, owner=owner)) + db_session.commit() + + return add + + +@pytest.fixture +def served(app, articles): + flask_jsonapi.Api(app).repository(make_viewset(articles), 'articles', '/articles/') + + +@pytest.mark.parametrize(argnames='setup_db_schema', argvalues=[Base], indirect=True) +@pytest.mark.usefixtures('setup_db_schema', 'served') +class TestSqlAlchemyDataService: + def test_own_object_is_readable_and_others_are_forbidden(self, jsonapi_client, seed): + seed((1, 'mine', OWNER), (2, 'theirs', OTHER)) + assert jsonapi_client.get('/articles/1/').status_code == 200 + assert jsonapi_client.get('/articles/2/').status_code == 403 + + def test_patch_selects_the_object_once(self, jsonapi_client, seed, db_engine): + seed((1, 'mine', OWNER)) + with recorded_statements(db_engine) as statements: + response = jsonapi_client.patch('/articles/1/', data=article_body(id='1', attributes={'title': 'new'})) + assert response.status_code == 200 + before_update = statements[:next(i for i, s in enumerate(statements) if s.startswith('UPDATE'))] + selects_before_update = [statement for statement in before_update if statement.startswith('SELECT')] + assert len(selects_before_update) == 1 + + def test_pagination_total_respects_permissions(self, jsonapi_client, seed): + seed((1, 'a', OWNER), (2, 'b', OWNER), (3, 'c', OTHER), (4, 'd', OTHER)) + response = jsonapi_client.get('/articles/?page[size]=1&page[number]=1') + assert response.status_code == 200 + assert response.get_json(force=True)['links']['last'].endswith('page[number]=2') + + def test_paginated_list_runs_one_count_and_one_select(self, jsonapi_client, seed, db_engine): + seed((1, 'a', OWNER), (2, 'b', OWNER)) + with recorded_statements(db_engine) as statements: + response = jsonapi_client.get('/articles/?page[size]=1&page[number]=1') + assert response.status_code == 200 + assert len(statements) == 2 + assert len([statement for statement in statements if 'count(' in statement.lower()]) == 1 + + def test_duplicate_create_is_a_jsonapi_409(self, jsonapi_client, seed): + seed((1, 'taken', OWNER)) + response = jsonapi_client.post('/articles/', data=article_body(attributes={'title': 'taken', 'owner': OWNER})) + assert response.status_code == 409 + assert response.get_json(force=True)['errors'][0]['status'] == 409 + + def test_mismatched_patch_id_is_409(self, jsonapi_client, seed): + seed((1, 'mine', OWNER)) + response = jsonapi_client.patch('/articles/1/', data=article_body(id='2', attributes={'title': 'new'})) + assert response.status_code == 409 + assert response.get_json(force=True)['errors'][0]['status'] == 409 + + +@pytest.mark.parametrize(argnames='setup_db_schema', argvalues=[Base], indirect=True) +@pytest.mark.usefixtures('setup_db_schema') +def test_legacy_repository_through_adapter(app, jsonapi_client, db_session, seed): + class LegacyArticleRepository(legacy_sqlalchemy_repositories.SqlAlchemyModelRepository): + model = Article + session = db_session + instance_name = 'article' + + viewset = make_viewset(data_services.LegacyRepositoryAdapter(LegacyArticleRepository())) + flask_jsonapi.Api(app).repository(viewset, 'articles', '/articles/') + seed((1, 'mine', OWNER)) + + patched = jsonapi_client.patch('/articles/1/', data=article_body(id='1', attributes={'title': 'new'})) + deleted = jsonapi_client.delete('/articles/1/') + missing = jsonapi_client.get('/articles/1/') + + assert (patched.status_code, deleted.status_code, missing.status_code) == (200, 204, 404) + assert missing.get_json(force=True)['errors'][0]['status'] == 404 + + +@pytest.mark.parametrize(argnames='setup_db_schema', argvalues=[Base], indirect=True) +@pytest.mark.usefixtures('setup_db_schema') +def test_safety_net_hides_the_total_when_the_filter_lets_foreign_rows_through( + app, jsonapi_client, articles, seed, caplog): + class LeakyFilter(OwnerOnly): + def apply_permission_filter(self, filters): + return dict(filters) + + viewset = make_viewset(articles) + viewset.object_permissions = LeakyFilter() + flask_jsonapi.Api(app).repository(viewset, 'articles', '/articles/') + seed((1, 'a', OWNER), (2, 'b', OTHER), (3, 'c', OWNER)) + + response = jsonapi_client.get('/articles/?page[size]=2&page[number]=1') + + document = response.get_json(force=True) + assert [item['id'] for item in document['data']] == [1] + assert (document['links']['last'], document['links']['next']) == (None, None) + warnings = [record for record in caplog.records if record.levelno == logging.WARNING] + assert len(warnings) == 1 + assert OTHER not in warnings[0].getMessage() diff --git a/tests/test_docs_full_example.py b/tests/test_docs_full_example.py new file mode 100644 index 0000000..02950c2 --- /dev/null +++ b/tests/test_docs_full_example.py @@ -0,0 +1,152 @@ +import importlib.util +import json +import pathlib + +import pytest + +EXAMPLE_PATH = pathlib.Path(__file__).parent.parent / 'docs' / 'examples' / 'full_example.py' +JSONAPI = 'application/vnd.api+json' + +ARTICLE = { + 'type': 'articles', + 'id': '1', + 'attributes': {'title': 'Hello', 'body': 'First post.'}, + 'relationships': {'author': {'data': {'type': 'authors', 'id': '1'}}}, +} + + +def error_document(status, title, detail): + return {'errors': [{'status': status, 'title': title, 'detail': detail}], 'jsonapi': {'version': '1.0'}} + + +@pytest.fixture +def client(): + # A fresh module per test means a fresh engine, and with it an empty in-memory database. + spec = importlib.util.spec_from_file_location('full_example', EXAMPLE_PATH) + example = importlib.util.module_from_spec(spec) + spec.loader.exec_module(example) + example.create_database() + return example.app.test_client() + + +def send(client, method, url, token=None, body=None): + headers = {'Accept': JSONAPI} + if token: + headers['Authorization'] = 'Bearer {}'.format(token) + if body is not None: + headers['Content-Type'] = JSONAPI + return client.open(url, method=method, headers=headers, data=json.dumps(body) if body is not None else None) + + +def create_article(client): + body = {'data': {'type': 'articles', 'attributes': {'title': 'Hello', 'body': 'First post.'}}} + return send(client, 'POST', '/articles/', token='alice-token', body=body) + + +def retitle(client, token): + body = {'data': {'type': 'articles', 'id': '1', 'attributes': {'title': 'Mine now'}}} + return send(client, 'PATCH', '/articles/1/', token=token, body=body) + + +def test_request_without_token_is_unauthorized(client): + response = send(client, 'GET', '/articles/') + + assert response.status_code == 401 + assert response.get_json(force=True) == error_document(401, 'Unauthorized', 'A valid bearer token is required.') + + +def test_create_makes_the_client_the_author(client): + response = create_article(client) + + assert response.status_code == 201 + assert response.get_json(force=True) == {'data': ARTICLE, 'jsonapi': {'version': '1.0'}} + + +def test_any_client_with_a_token_lists_articles(client): + create_article(client) + + response = send(client, 'GET', '/articles/', token='bob-token') + + assert response.status_code == 200 + assert response.get_json(force=True) == {'data': [ARTICLE], 'meta': {'count': 1}, 'jsonapi': {'version': '1.0'}} + + +def test_paginated_list_has_links_built_from_the_total(client): + create_article(client) + page = 'http://localhost:5000/articles/?page[size]=1&page[number]=1' + + response = client.get( + '/articles/?page[size]=1&page[number]=1', base_url='http://localhost:5000', + headers={'Accept': JSONAPI, 'Authorization': 'Bearer bob-token'}, + ) + + assert response.status_code == 200 + assert response.get_json(force=True) == { + 'data': [ARTICLE], + 'links': {'self': page, 'first': page, 'previous': None, 'next': None, 'last': page}, + 'meta': {'count': 1}, + 'jsonapi': {'version': '1.0'}, + } + + +def test_update_by_someone_else_is_forbidden_and_changes_nothing(client): + create_article(client) + + response = retitle(client, token='bob-token') + + assert response.status_code == 403 + assert response.get_json(force=True) == error_document(403, 'Forbidden', 'Only the author can change an article.') + title = send(client, 'GET', '/articles/1/', token='alice-token').get_json(force=True)['data']['attributes']['title'] + assert title == 'Hello' + + +def test_author_can_update(client): + create_article(client) + + response = retitle(client, token='alice-token') + + assert response.status_code == 200 + assert response.get_json(force=True)['data']['attributes']['title'] == 'Mine now' + + +def test_undeclared_delete_is_not_allowed(client): + create_article(client) + + response = send(client, 'DELETE', '/articles/1/', token='alice-token') + + assert response.status_code == 405 + assert response.get_json(force=True) == error_document( + 405, 'Method not allowed', 'Delete is not allowed for this resource') + + +def test_author_can_be_included(client): + create_article(client) + + response = send(client, 'GET', '/articles/1/?include=author', token='bob-token') + + assert response.status_code == 200 + assert response.get_json(force=True)['included'] == [ + {'type': 'authors', 'id': '1', 'attributes': {'name': 'Alice'}}, + ] + + +def test_client_chosen_id_already_in_use_is_a_conflict(client): + create_article(client) + body = {'data': {'type': 'articles', 'id': '1', 'attributes': {'title': 'Taken', 'body': ''}}} + + response = send(client, 'POST', '/articles/', token='alice-token', body=body) + + assert response.status_code == 409 + assert response.get_json(force=True)['errors'][0]['status'] == 409 + + +def test_request_without_accept_header_is_served(client): + response = client.get('/articles/', headers={'Authorization': 'Bearer bob-token'}) + + assert response.status_code == 200 + + +def test_request_accepting_anything_is_not_acceptable(client): + response = client.get('/articles/', headers={'Authorization': 'Bearer bob-token', 'Accept': '*/*'}) + + assert response.status_code == 406 diff --git a/tests/test_error_responses.py b/tests/test_error_responses.py new file mode 100644 index 0000000..c3b3e5c --- /dev/null +++ b/tests/test_error_responses.py @@ -0,0 +1,173 @@ +import datetime + +from unittest import mock + +import flask +import marshmallow_jsonapi +import werkzeug.datastructures +import werkzeug.exceptions + +from marshmallow_jsonapi import fields + +from flask_jsonapi import exceptions +from flask_jsonapi import resources +from flask_jsonapi import response as jsonapi_response + + +class ExampleSchema(marshmallow_jsonapi.Schema): + id = fields.Str() + + class Meta: + type_ = 'example' + self_url = '/failing/{id}/' + self_url_kwargs = {'id': ''} + + +class SecretFailingSchema(ExampleSchema): + name = fields.Method('get_name') + + def get_name(self, obj): + raise KeyError('secret') + + +class SuccessfulView(resources.ResourceDetail): + schema = ExampleSchema + + def read(self, id): + return {'id': id} + + def update(self, id, data, **kwargs): + return {'id': id} + + +def make_view(api, error): + class FailingView(resources.ResourceDetail): + schema = ExampleSchema + + def read(self, id): + raise error + + api.route(FailingView, 'failing', '/failing//') + + +def test_unexpected_exception_is_a_generic_jsonapi_500(api, jsonapi_client): + make_view(api, KeyError('database password')) + with mock.patch('flask_jsonapi.resources.logger') as logger: + response = jsonapi_client.get('/failing/1/') + assert response.status_code == 500 + assert response.headers['Content-Type'] == 'application/vnd.api+json' + assert response.get_json(force=True)['errors'] == [{'status': 500, 'title': 'Internal server error'}] + assert b'database password' not in response.data + assert logger.exception.called + + +def test_flask_abort_is_a_jsonapi_error(api, jsonapi_client): + make_view(api, werkzeug.exceptions.Forbidden()) + response = jsonapi_client.get('/failing/1/') + assert response.status_code == 403 + assert response.get_json(force=True)['errors'] == [{'status': 403, 'title': 'Forbidden'}] + + +def test_jsonapi_exception_is_rendered_as_before(api, jsonapi_client): + make_view(api, exceptions.Unauthorized(detail='No token.')) + response = jsonapi_client.get('/failing/1/') + assert response.status_code == 401 + assert response.get_json(force=True)['errors'] == [{'status': 401, 'title': 'Unauthorized', 'detail': 'No token.'}] + + +def test_abort_with_a_response_returns_that_response_unchanged(api, jsonapi_client): + make_view(api, werkzeug.exceptions.HTTPException(response=flask.Response('teapot', 418))) + response = jsonapi_client.get('/failing/1/') + assert response.status_code == 418 + assert response.data == b'teapot' + + +def test_http_exception_without_code_is_a_generic_jsonapi_500(api, jsonapi_client): + make_view(api, werkzeug.exceptions.HTTPException()) + response = jsonapi_client.get('/failing/1/') + assert response.status_code == 500 + assert response.headers['Content-Type'] == 'application/vnd.api+json' + assert response.get_json(force=True)['errors'] == [{'status': 500, 'title': 'Internal server error'}] + + +def test_response_serialization_failure_is_a_generic_jsonapi_500(api, jsonapi_client): + class UnserializableView(resources.ResourceDetail): + schema = ExampleSchema + + def get(self, *args, **kwargs): + return jsonapi_response.JsonApiResponse({'data': datetime.datetime.now()}) + + api.route(UnserializableView, 'unserializable', '/unserializable//') + with mock.patch('flask_jsonapi.resources.logger') as logger: + response = jsonapi_client.get('/unserializable/1/') + assert response.status_code == 500 + assert response.headers['Content-Type'] == 'application/vnd.api+json' + assert response.get_json(force=True)['errors'] == [{'status': 500, 'title': 'Internal server error'}] + assert logger.exception.called + + +def test_head_is_served_by_the_get_handler(api, jsonapi_client): + api.route(SuccessfulView, 'successful', '/successful//') + with mock.patch('flask_jsonapi.resources.logger') as logger: + response = jsonapi_client.head('/successful/1/') + assert response.status_code == 200 + assert response.data == b'' + assert not logger.exception.called + + +def test_method_without_handler_is_a_jsonapi_405(api, jsonapi_client): + class PutWithoutHandlerView(SuccessfulView): + methods = ['GET', 'PUT'] + + api.route(PutWithoutHandlerView, 'put_without_handler', '/put-without-handler//') + response = jsonapi_client.put('/put-without-handler/1/') + assert response.status_code == 405 + assert response.headers['Content-Type'] == 'application/vnd.api+json' + assert response.get_json(force=True)['errors'][0]['status'] == 405 + + +def test_patch_with_wrong_type_is_a_jsonapi_409(api, jsonapi_client): + api.route(SuccessfulView, 'successful', '/successful//') + response = jsonapi_client.patch('/successful/1/', json={'data': {'type': 'wrong', 'id': '1'}}) + assert response.status_code == 409 + assert response.headers['Content-Type'] == 'application/vnd.api+json' + assert response.get_json(force=True)['errors'] == [ + {'detail': 'Invalid type. Expected "example".', 'source': {'pointer': '/data/type'}}, + ] + + +def test_schema_dump_error_is_a_generic_jsonapi_500(api, jsonapi_client): + class SecretFailingView(SuccessfulView): + schema = SecretFailingSchema + + api.route(SecretFailingView, 'secret_failing', '/secret-failing//') + with mock.patch('flask_jsonapi.resources.logger') as logger: + response = jsonapi_client.get('/secret-failing/1/') + assert response.status_code == 500 + assert response.get_json(force=True)['errors'] == [{'status': 500, 'title': 'Internal server error'}] + assert b'secret' not in response.data + assert logger.exception.called + + +def test_list_schema_dump_error_is_a_generic_jsonapi_500(api, jsonapi_client): + class SecretFailingListView(resources.ResourceList): + schema = SecretFailingSchema + + def read_many(self, filters, sorting, pagination): + return [{'id': '1'}] + + api.route(SecretFailingListView, 'secret_failing_list', '/secret-failing/') + with mock.patch('flask_jsonapi.resources.logger') as logger: + response = jsonapi_client.get('/secret-failing/') + assert response.status_code == 500 + assert b'secret' not in response.data + assert logger.exception.called + + +def test_http_exception_headers_are_kept(api, jsonapi_client): + challenge = werkzeug.datastructures.WWWAuthenticate('Bearer', {'realm': 'api'}) + make_view(api, werkzeug.exceptions.Unauthorized(www_authenticate=challenge)) + response = jsonapi_client.get('/failing/1/') + assert response.status_code == 401 + assert response.headers['WWW-Authenticate'] == 'Bearer realm=api' + assert response.headers['Content-Type'] == 'application/vnd.api+json' diff --git a/tests/test_exceptions.py b/tests/test_exceptions.py new file mode 100644 index 0000000..168d53a --- /dev/null +++ b/tests/test_exceptions.py @@ -0,0 +1,68 @@ +import warnings + +import pytest + +from flask_jsonapi import exceptions +from flask_jsonapi.permissions import checkers +from flask_jsonapi.resource_repositories import repositories + + +def test_base_accepts_legacy_positional_source_and_detail(): + error = exceptions.JsonApiException({'pointer': '/data'}, 'boom') + assert error.to_dict() == { + 'status': 500, 'title': 'Unknown error', 'source': {'pointer': '/data'}, 'detail': 'boom', + } + + +@pytest.mark.parametrize('exception_class', [ + exceptions.ForbiddenError, exceptions.MethodNotAllowed, exceptions.NotImplementedMethod, + exceptions.InvalidFilters, exceptions.InvalidSort, exceptions.InvalidPage, + exceptions.InvalidField, exceptions.InvalidInclude, +]) +def test_subclasses_accept_positional_detail(exception_class): + assert exception_class('boom').detail == 'boom' + + +def test_extra_positional_arguments_reach_exception_args(): + error = exceptions.JsonApiException({'pointer': '/data'}, 'boom', 'extra', 2) + assert (error.source, error.detail) == ({'pointer': '/data'}, 'boom') + assert error.args[-2:] == ('extra', 2) + assert str(error) == 'boom' + + +def test_message_survives_in_str_and_args(): + assert str(exceptions.ForbiddenError('boom')) == 'boom' + assert exceptions.ForbiddenError('boom').args == ('boom',) + assert str(exceptions.JsonApiException(detail='boom')) == 'boom' + assert str(exceptions.JsonApiException(status=400)) == '' + + +def test_permission_exception_accepts_positional_source_and_detail(): + error = checkers.PermissionException({'pointer': '/data'}, 'no') + assert (error.source, error.detail, error.status) == ({'pointer': '/data'}, 'no', 403) + + +def test_legacy_resource_repository_still_raises_not_implemented(): + with pytest.raises(exceptions.NotImplementedMethod): + repositories.ResourceRepository().create({}) + + +def test_legacy_signatures_do_not_warn(): + with warnings.catch_warnings(): + warnings.simplefilter('error') + exceptions.ForbiddenError('x') + exceptions.JsonApiException({}, 'x') + + +def test_to_dict_omits_empty_members(): + assert exceptions.JsonApiException(status=400, title='Bad').to_dict() == {'status': 400, 'title': 'Bad'} + + +@pytest.mark.parametrize('exception_class, status, title', [ + (exceptions.Unauthorized, 401, 'Unauthorized'), + (exceptions.Conflict, 409, 'Conflict'), + (exceptions.UnprocessableEntity, 422, 'Unprocessable entity'), + (exceptions.ServiceUnavailable, 503, 'Service unavailable'), +]) +def test_http_exceptions(exception_class, status, title): + assert exception_class().to_dict() == {'status': status, 'title': title} diff --git a/tests/test_integration.py b/tests/test_integration.py index f21950e..22b5916 100644 --- a/tests/test_integration.py +++ b/tests/test_integration.py @@ -116,8 +116,7 @@ def test_bad_get_list(app): headers=JSONAPI_HEADERS, ) result = json.loads(response.data.decode('utf-8')) - assert result['errors'][0]['status'] == 500 - assert result['errors'][0]['detail'] == 'Must have an `id` field' + assert result['errors'] == [{'status': 500, 'title': 'Internal server error'}] def test_bad_get_detail(app): @@ -129,8 +128,7 @@ def test_bad_get_detail(app): headers=JSONAPI_HEADERS, ) result = json.loads(response.data.decode('utf-8')) - assert result['errors'][0]['status'] == 500 - assert result['errors'][0]['detail'] == 'Must have an `id` field' + assert result['errors'] == [{'status': 500, 'title': 'Internal server error'}] def test_bad_data_get_list(app): @@ -144,8 +142,7 @@ def test_bad_data_get_list(app): headers=JSONAPI_HEADERS, ) result = json.loads(response.data.decode('utf-8')) - assert result['errors'][0]['status'] == 500 - assert result['errors'][0]['detail'] == "'int' object has no attribute 'isoformat'" + assert result['errors'] == [{'status': 500, 'title': 'Internal server error'}] def test_bad_data_get_detail(app): @@ -159,8 +156,7 @@ def test_bad_data_get_detail(app): headers=JSONAPI_HEADERS, ) result = json.loads(response.data.decode('utf-8')) - assert result['errors'][0]['status'] == 500 - assert result['errors'][0]['detail'] == "'int' object has no attribute 'isoformat'" + assert result['errors'] == [{'status': 500, 'title': 'Internal server error'}] def test_create_with_missing_data(app): diff --git a/tests/test_query_string.py b/tests/test_query_string.py index 325b66e..4f15a1f 100644 --- a/tests/test_query_string.py +++ b/tests/test_query_string.py @@ -104,6 +104,32 @@ def test_links_with_header(self, app): 'last': 'http://localhost/prefix/examples/?page[size]=10&page[number]=5' } + def test_links_of_empty_list_keep_last_page_zero(self, app): + with app.test_request_context('/examples/?page[size]=10&page[number]=1'): + links = query_string.SizeNumberPagination().get_links(page_size=10, current_page=1, total_count=0) + assert links['last'] == 'http://localhost/examples/?page[size]=10&page[number]=0' + + @pytest.mark.parametrize('current_page, item_count, expected_previous, expected_next', [ + (1, 10, None, 2), + (1, 9, None, None), + (3, 10, 2, 4), + (3, 0, 2, None), + ]) + def test_links_without_total(self, app, current_page, item_count, expected_previous, expected_next): + def page(number): + return 'http://localhost/examples/?page[size]=10&page[number]={}'.format(number) + + with app.test_request_context('/examples/?page[size]=10&page[number]=1'): + links = query_string.SizeNumberPagination().get_links_without_total( + page_size=10, current_page=current_page, item_count=item_count) + assert links == { + 'self': page(current_page), + 'first': page(1), + 'previous': page(expected_previous) if expected_previous else None, + 'next': page(expected_next) if expected_next else None, + 'last': None, + } + class TestSortParser: def test_sorting(self, app, sort_parser):