From 5084ec33a2b44c221ab0416ce74d2de553585127 Mon Sep 17 00:00:00 2001 From: Francis Charette Migneault Date: Mon, 26 Oct 2020 13:04:39 -0400 Subject: [PATCH] add docs for ServiceBaseWMS, ServiceGeoserverWMS and ServiceNCWMS2 --- docs/permissions.rst | 2 +- docs/references.rst | 2 ++ docs/services.rst | 74 ++++++++++++++++++++++++++++++++++++++------ magpie/services.py | 20 ++++++------ tests/utils.py | 2 +- 5 files changed, 78 insertions(+), 22 deletions(-) diff --git a/docs/permissions.rst b/docs/permissions.rst index e9b1ee41e..30678911b 100644 --- a/docs/permissions.rst +++ b/docs/permissions.rst @@ -442,7 +442,7 @@ As a general of thumb, all :term:`Permission` are resolved such that more restri the actual :term:`Resource` for the targeted :term:`User` will have priority, both in terms of inheritance by tree hierarchy and by :term:`Group` memberships. -.. _permission_representations:: +.. _permission_representations: Permissions Representations -------------------------------------- diff --git a/docs/references.rst b/docs/references.rst index 3dd58b89d..d16bd6330 100644 --- a/docs/references.rst +++ b/docs/references.rst @@ -3,10 +3,12 @@ .. _Alembic: https://alembic.sqlalchemy.org/ .. _Authomatic: https://authomatic.github.io/authomatic/ +.. _GeoServer: http://geoserver.org/ .. _Gunicorn: https://gunicorn.org/ .. _issue: https://github.com/Ouranosinc/Magpie/issues/new .. _Magpie Docker Images: https://hub.docker.com/r/pavics/magpie/tags .. _Magpie REST API: https://pavics-magpie.readthedocs.io/en/latest/api.html +.. _ncWMS2: https://github.com/Reading-eScience-Centre/ncwms .. _Ouranosinc/requests-magpie: https://github.com/Ouranosinc/requests-magpie .. _Phoenix: https://github.com/bird-house/pyramid-phoenix .. _PostgreSQL: https://www.postgresql.org/ diff --git a/docs/services.rst b/docs/services.rst index db9788927..7101b5701 100644 --- a/docs/services.rst +++ b/docs/services.rst @@ -41,7 +41,7 @@ interpreted into a given :class:`Permission`. The second is :meth:`magpie.servic which similarly tells the interpretation method to convert the request into a :class:`magpie.models.Resource` reference. Whenever :term:`Effective Permissions` or :term:`ACL` needs to be resolved in order to determine if a -:term:`Request User` can have access or not to a :term:`Resource`, `MĖ€agpie` will employ the appropriate :term:`Service` +:term:`Request User` can have access or not to a :term:`Resource`, `Magpie` will employ the appropriate :term:`Service` implementation and call the methods to process the result. .. versionchanged:: 3.0 @@ -57,11 +57,13 @@ On top of the above methods, the following attributes must be defined.
+.. temporarily use services module to reduce displayed name in table +.. py:currentmodule:: magpie.services + + .. list-table:: :header-rows: 1 - .. py:currentmodule:: magpie.services - * - Attribute - Description * - :attr:`ServiceInterface.service_type` |br| (``str``) @@ -100,11 +102,11 @@ Available Services ServiceAccess ~~~~~~~~~~~~~~~~~~~~~ -The implementation of this service is handled by class :class:`magpie.services.ServiceAccess`. It is intended to act -as a simple *all-or-nothing* endpoint barrier, where only :attr:`Permission.ACCESS` can be applied, and only directly on -the :term:`Service` itself. A :term:`User` or :term:`Group` that has that :term:`Permission` with :attr:`Access.ALLOW` -will be able to reach the :term:`Service`. Any other operation, (or explicit :attr:`Access.DENY`) will all result into -denied access to the private URL registered by the :term:`Service. +The implementation of this :term:`Service` is handled by class :class:`magpie.services.ServiceAccess`. It is intended to +act as a simple *all-or-nothing* endpoint barrier, where only :attr:`Permission.ACCESS` can be applied, and only +directly on the :term:`Service` itself. A :term:`User` or :term:`Group` that has that :term:`Permission` with +:attr:`Access.ALLOW` will be able to reach the :term:`Service`. Any other operation (or explicit :attr:`Access.DENY`) +will all result into denied access to the private URL registered by the :term:`Service`. .. versionchanged:: 3.0 This :term:`Service` implementation dates prior to the integration of :class:`Access` and :class:`Scope` concepts @@ -264,16 +266,68 @@ above *default* ``file_patterns``. The ``file_patterns`` allow for example to co ``file.nc.html`` as the same :term:`Resource` internally, which avoids duplicating :term:`Applied Permissions` across multiple :term:`Resource` for every *metadata*/*data* representation. +ServiceBaseWMS +~~~~~~~~~~~~~~~~~~~~~ + +.. seealso:: + Derived implementations: + - `ServiceGeoserverWMS`_ + - `ServiceNCWMS2`_ + +This is a *partial base* class employed to represent :term:`OWS` `Web Map Service` extended via other complete classes. +It cannot be employed directly as :term:`Service` instance. The derived classes provide different parsing methodologies +and children :term:`Resource` representation according to their respective functionalities. + +It provides support for the following permissions, each corresponding to the appropriate functionality of `WMS`: + +- :attr:`Permission.GET_CAPABILITIES` +- :attr:`Permission.GET_MAP` +- :attr:`Permission.GET_FEATURE_INFO` +- :attr:`Permission.GET_LEGEND_GRAPHIC` +- :attr:`Permission.GET_METADATA` + +Similar to any other :term:`OWS` based :term:`Service`, the HTTP request takes a ``request`` query parameter that +indicates which of the above :term:`Permission` is being requested. + ServiceGeoserverWMS ~~~~~~~~~~~~~~~~~~~~~ -.. todo:: details, depends on ServiceBaseWMS +.. seealso:: + Base class: `ServiceBaseWMS`_ + +This implementation is defined by :class:`magpie.services.ServiceGeoserverWMS`. It extends the base class by using +children :term:`Resource` defined by :class:`magpie.models.Workspace`, which supports the same set of :term:`Permission` +as their parent :term:`Service`. Each of those :class:`magpie.models.Workspace` correspond to the equivalent element +provided to `GeoServer`_ based HTTP request using query parameter ``layers``, following format +``layers=:``. The :term:`Permission` is obtained from the ``request`` query parameter. + +.. warning:: + As of latest version of `Magpie`, there is no specific handling of the specific ``LayerName`` part of the targeted + :term:`Resource`. Please submit an `issue`_ with specific use-case if this is something that would be required. + ServiceNCWMS2 ~~~~~~~~~~~~~~~~~~~~~ -.. todo:: details, depends on ServiceBaseWMS +.. seealso:: + Base class: `ServiceBaseWMS`_ + +This implementation is defined by :class:`magpie.services.ServiceNCWMS2`. It extends the base class by using +children :term:`Resource` defined as :class:`magpie.models.Directory` and :class:`magpie.models.File` instances but, +using the corresponding :term:`Permission` entries from `ServiceBaseWMS`_ class instead of the default +:attr:`Permission.READ` and :attr:`Permission.WRITE` (i.e.: see `ServiceTHREDDS`_). The general idea is that the remote +`ncWMS2`_ *service provider* being represented by this :term:`Service` points to the same `NetCDF` file resources as +offered by `THREDDS`, but for mapping display. The HTTP request therefore points toward another proxy endpoint and +employs different query parameters specific to `WMS` requests (instead of `THREDDS`), although the provided file +reference is technically the same. For this reason, the same :term:`Resource` hierarchy is supported, with any number +of nested :class:`magpie.models.Directory` and :class:`magpie.models.File` as leaves. The targeted :term:`Resource` by +the HTTP request is extracted from either the ``dataset``, ``layername`` or ``layers`` query parameter, depending on the +appropriate :term:`Permission` being requested, based on the ``request`` query parameter. + +.. note:: + Although the class name employs ``NCWMS2``, the registered type is represented by the string ``ncwms`` for + executing requests toward the `Magpie` API and contents returned in its responses. ServiceWPS diff --git a/magpie/services.py b/magpie/services.py index 073a4c97b..896bfe13f 100644 --- a/magpie/services.py +++ b/magpie/services.py @@ -456,16 +456,6 @@ def resource_requested(self): "dataset" ] - resource_types_permissions = { - models.Workspace: [ - Permission.GET_CAPABILITIES, - Permission.GET_MAP, - Permission.GET_FEATURE_INFO, - Permission.GET_LEGEND_GRAPHIC, - Permission.GET_METADATA, - ] - } - class ServiceNCWMS2(ServiceBaseWMS): """ @@ -543,6 +533,16 @@ class ServiceGeoserverWMS(ServiceBaseWMS): """ service_type = "geoserverwms" + resource_types_permissions = { + models.Workspace: [ + Permission.GET_CAPABILITIES, + Permission.GET_MAP, + Permission.GET_FEATURE_INFO, + Permission.GET_LEGEND_GRAPHIC, + Permission.GET_METADATA, + ] + } + def resource_requested(self): permission = self.permission_requested() path_parts = self._get_request_path_parts() diff --git a/tests/utils.py b/tests/utils.py index 7db95163a..e21a9c887 100644 --- a/tests/utils.py +++ b/tests/utils.py @@ -353,7 +353,7 @@ def mocked(container): def wrapped(*_, **__): with mock.patch("magpie.services.get_settings", side_effect=mocked), \ mock.patch("magpie.utils.get_settings", side_effect=mocked): - return test(*_, **__) # pylint: disable=E117,W0311 + return test(*_, **__) return wrapped