Ouranosinc · fmigneault · Feb 1, 2022 · Jan 6, 2022 · Jan 6, 2022 · Jan 6, 2022
diff --git a/.dockerignore b/.dockerignore
@@ -13,6 +13,7 @@ venv
 
 # Node
 node_modules
+package.json
 package-lock.json
 
 # Makefile

diff --git a/.gitignore b/.gitignore
@@ -12,6 +12,7 @@ share
 
 # Node
 node_modules
+package.json
 package-lock.json
 
 # Makefile

diff --git a/CHANGES.rst b/CHANGES.rst
@@ -7,22 +7,6 @@ Changes
 `Unreleased <https://github.com/Ouranosinc/Magpie/tree/master>`_ (latest)
 ------------------------------------------------------------------------------------
 
-* Nothing new for the moment.
-
-`3.20.1 <https://github.com/Ouranosinc/Magpie/tree/3.20.1>`_ (2022-01-19)
-------------------------------------------------------------------------------------
-
-Bug Fixes
-~~~~~~~~~~~~~~~~~~~~~
-* Fix `Twitcher` ``/verify`` endpoint integrated through ``MagpieAdapter`` to validate synchronized authentication
-  policies across both services. The endpoint now supports query parameter credentials to facilitate call directly
-  within a web browser (not assuming JSON contents) and properly parses cookies from both policies to report more
-  detailed error messages in case of failure.
-* Fix ``error`` and ``type`` representation when handling raised exception by ``evaluate_call`` utility function.
-
-`3.20.0 <https://github.com/Ouranosinc/Magpie/tree/3.20.0>`_ (2022-01-06)
-------------------------------------------------------------------------------------
-
 Features / Changes
 ~~~~~~~~~~~~~~~~~~~~~
 * Add missing ``ServiceWFS`` permissions according to `OGC WFS standard <https://www.ogc.org/standards/wfs>`_.
@@ -51,6 +35,13 @@ Features / Changes
 * Adjust UI to consider ``child_structure_allowed`` definitions to propose only applicable ``Resource`` types in the
   combobox when creating a new ``Resource`` in the tree hierarchy.
 * Add UI submission field to provide ``Service`` JSON configuration at creation when supported by the type.
+* Add ``child_structure_allowed`` to ``ServiceAPI`` and ``ServiceTHREDDS`` to be more explicit about allowed structure
+  hierarchies in API responses. Their original behaviour remains unchanged, but is further enforced during validation
+  of their children resource type creation against explicit structure.
+* Add multi-``Resource`` ACL resolution within the same request to support ``Service`` implementations that can refer
+  to multiple items simultaneously. An example of this is the comma-separated list of ``Layer`` defined by ``typeNames``
+  of new ``ServiceGeoserverWMS`` implementation. Access is granted if the ``User`` has access to **ALL** ``Resource``
+  resolved from parsing the request.
 
 Bug Fixes
 ~~~~~~~~~~~~~~~~~~~~~
@@ -65,6 +56,17 @@ Bug Fixes
 * Fix `Effective Resolution` of ``Permission`` applied for ``ServiceGeoserverWMS`` to consider ``Scope`` modifier
   of ``Service`` and ``Workspace`` for access to be resolved at the ``Layer`` level.
 
+`3.20.1 <https://github.com/Ouranosinc/Magpie/tree/3.20.1>`_ (2022-01-19)
+------------------------------------------------------------------------------------
+
+Bug Fixes
+~~~~~~~~~~~~~~~~~~~~~
+* Fix `Twitcher` ``/verify`` endpoint integrated through ``MagpieAdapter`` to validate synchronized authentication
+  policies across both services. The endpoint now supports query parameter credentials to facilitate call directly
+  within a web browser (not assuming JSON contents) and properly parses cookies from both policies to report more
+  detailed error messages in case of failure.
+* Fix ``error`` and ``type`` representation when handling raised exception by ``evaluate_call`` utility function.
+
 `3.20.0 <https://github.com/Ouranosinc/Magpie/tree/3.20.0>`_ (2022-01-06)
 ------------------------------------------------------------------------------------
 

diff --git a/Makefile b/Makefile
@@ -696,7 +696,7 @@ test-remote-only:		## run only remote tests with the environment Python
 .PHONY: test-custom-only
 test-custom-only:		## run custom marker tests using SPEC="<marker-specification>"
 	@echo "Running custom tests..."
-	@[ "${SPEC}" ] || ( echo ">> 'TESTS' is not set"; exit 1 )
+	@[ "${SPEC}" ] || ( echo ">> 'SPEC' is not set"; exit 1 )
 	@bash -c '$(CONDA_CMD) pytest tests $(TEST_VERBOSITY) -m "${SPEC}" --junitxml "$(APP_ROOT)/tests/results.xml"'
 
 .PHONY: test-docker

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -52,3 +52,25 @@ div.bordered-content {
     border: 1px solid #C6C9CB;
     padding: 0 1em 1em 0;
 }
+
+/* apply the parent list number prefixed to the current list numbers
+    https://stackoverflow.com/a/13841818
+*/
+div.parent-list-numbers ol {
+    counter-reset: item;
+}
+
+div.parent-list-numbers ol li {
+    counter-increment: item;
+}
+
+div.parent-list-numbers ol ol > li::before {
+    content: counters(item, ".") ")";
+    margin-left: -3em;
+}
+
+div.parent-list-numbers > ol > li > ol > li {
+    list-style: none;
+    display: inline-flex;
+    display: -webkit-box;
+}
diff --git a/docs/authentication.rst b/docs/authentication.rst
@@ -62,9 +62,10 @@ Query Parameters
 
 This method employs the query string parameters in the URL to provide the credentials. The format is as follows.
 
-.. code-block::
+.. code-block:: http
 
-    GET {MAGPIE_URL}/signin?user_name=<usr>&password=<pwd>
+    GET /signin?user_name=<usr>&password=<pwd> HTTP/1.1
+    Host: {MAGPIE_URL}
 
 
 The response will contain :ref:`Authentication Headers` detail needed for user identification.
@@ -89,37 +90,39 @@ Body content requests allow multiple variants, based on the specified ``Content-
 All variants employ a similar structure, but indicate the format of the body to be parsed.
 By default, ``application/json`` is employed if none was specified.
 
-.. code-block::
+.. code-block:: http
 
-    POST {MAGPIE_URL}/signin
-    Headers
-        Content-Type: multipart/form-data; boundary=<boundary-string>
-    Body
-        user_name: "<usr>"
-        password: "<pwd>"
-        provider_name: "<provider>"     # optional
+    POST /signin HTTP/1.1
+    Host: {MAGPIE_URL}
+    Content-Type: multipart/form-data; boundary=<boundary-string>
 
+    --<boundary-string>
+    user_name: "<usr>"
+    password: "<pwd>"
+    provider_name: "<provider>"     # optional
+    --<boundary-string>--
 
-.. code-block::
 
-    POST {MAGPIE_URL}/signin
-    Headers
-        Content-Type: application/x-www-form-urlencoded
-    Body
-        user_name=<usr>&password=<pwd>&provider_name=<provider>
+.. code-block:: http
 
+    POST /signin HTTP/1.1
+    Host: {MAGPIE_URL}
+    Content-Type: application/x-www-form-urlencoded
 
-.. code-block::
+    user_name=<usr>&password=<pwd>&provider_name=<provider>
 
-    POST {MAGPIE_URL}/signin
-    Headers
-        Content-Type: application/json
-    Body
-        {
-            "user_name": "<usr>",
-            "password": "<pwd>",
-            "provider_name": "<provider>"
-        }
+
+.. code-block::  http
+
+    POST /signin HTTP/1.1
+    Host: {MAGPIE_URL}
+    Content-Type: application/json
+
+    {
+        "user_name": "<usr>",
+        "password": "<pwd>",
+        "provider_name": "<provider>"
+    }
 
 
 The response will contain :ref:`Authentication Headers` detail needed for user identification.
@@ -196,7 +199,7 @@ Authentication Headers
 After execution of an :term:`Authentication` request, a ``Set-Cookie`` header with `Magpie` user identification token
 named according to :ref:`config_security` should be set in the response as follows.
 
-.. code-block::
+.. code-block:: http
 
     Set-Cookie: {MAGPIE_COOKIE_NAME}=<auth-token>!userid_type:int;
                 [Domain=<domain>; Path=<path>; HttpOnly; SameSite=Lax; Max-Age=<seconds>; expires=<datetime>]
@@ -239,8 +242,8 @@ Authorization Headers
 Following any successful :term:`Authentication` request as presented in the previous section, the obtained ``Cookie``
 defines which :term:`Logged User` attempts to accomplish an operation against a given protected URI. `Magpie` employs
 the same ``Cookie`` both for operations provided by its API and for accessing the real :term:`Resource` protected
-behind the :term:`Proxy` according to resolution of :term:`Effective Permissions` based on :term:`Applied Permissions`
-definitions.
+behind the :term:`Proxy` according to resolution of :term:`Effective Permissions <Effective Permission>` based on
+:term:`Applied Permission` definitions.
 
 Access to Magpie Operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -256,14 +259,14 @@ Access to Protected Resources
 
 When sending requests to the :term:`Policy Enforcement Point` (PEP) (e.g.: `Twitcher`_ :term:`Proxy`),
 appropriate ``Cookie`` headers must be defined for it to identify the :term:`Logged User` and resolve its
-:term:`Effective Permissions` accordingly. Not providing those tokens will default to using
+:term:`Effective Permissions <Effective Permission>` accordingly. Not providing those tokens will default to using
 :envvar:`MAGPIE_ANONYMOUS_USER`, which will result into either one of HTTP ``Unauthorized [401]`` or
 ``Forbidden [403]``, depending on how the PEP interprets and returns the response indicated by `Magpie`, unless the
 corresponding :term:`Resource` was allowed for :ref:`perm_public_access`.
 
 When appropriately authenticated, access to the targeted :term:`Resource` will be granted or denied depending on the
-:term:`Effective Permissions` that :term:`Logged User` has for it. This decision is extensively explained in section
-:ref:`perm_resolution`.
+:term:`Effective Permissions <Effective Permission>` that :term:`Logged User` has for it. This decision is extensively
+explained in section :ref:`perm_resolution`.
 
 Another alternative to obtain :term:`Authorization` (only when using the :ref:`utilities_adapter<Magpie Adapter>`) is
 by providing the ``Authorization`` header in the request with appropriate credentials. In this situation, the adapter
@@ -276,7 +279,7 @@ employed instead to process :term:`Authentication` only once.
 
 The format of the ``Authorization`` header is has follows.
 
-.. code-block::
+.. code-block:: http
 
     Authorization: Bearer <access_token>
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -54,6 +54,8 @@
     "doc_redirect",
     "sphinxcontrib.redoc",
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",  # help make cross-references to title/sections
+    "cloud_sptheme.ext.autodoc_sections",  # allow sections in docstrings code
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
@@ -174,7 +176,11 @@ def doc_redirect_include(file_path):
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = [
+    # ignore multiple over-verbose warnings caused
+    # by file not yet generated when TOC is processed
+    "api.rst",
+]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -686,7 +686,7 @@ remain available as described at the start of the :ref:`Configuration` section.
     (Value: ``"admin"``)
 
     Name of the :term:`Permission` used to represent highest administration privilege in the application. It is one of
-    the special :term:`Access Permissions` known by the application (see also :ref:`Route Access` section).
+    the special :term:`Access Permission` known by the application (see also :ref:`Route Access` section).
 
 .. envvar:: MAGPIE_LOGGED_PERMISSION
 
@@ -695,7 +695,7 @@ remain available as described at the start of the :ref:`Configuration` section.
 
     .. versionadded:: 2.0
 
-    Defines a special condition of :term:`Access Permissions` related to the :term:`Logged User` session and the
+    Defines a special condition of :term:`Access Permission` related to the :term:`Logged User` session and the
     targeted :term:`User` by the request. See details in :ref:`Route Access` for when it applies.
 
 .. envvar:: MAGPIE_LOGGED_USER

diff --git a/docs/glossary.rst b/docs/glossary.rst
@@ -27,13 +27,13 @@ Glossary
         grants or denies :term:`Permission` access to the applicable :term:`User` for the targeted :term:`Resource`.
         Formed of multiple :term:`ACE`.
 
-    Allowed Permissions
+    Allowed Permission
         Set of applicable :term:`Permission` values onto an element.
 
         .. seealso::
             :ref:`Allowed Permissions <allowed-permissions>` section for details.
 
-    Applied Permissions
+    Applied Permission
         An active :term:`Permission` for a given :term:`User` or :term:`Group` depending on context.
 
         .. seealso::
@@ -75,13 +75,20 @@ Glossary
         :term:`Group` that has property ``discoverable=True``, making it publicly viewable to any-level user.
         Otherwise, groups can be listed or accessed only by administrators.
 
-    Effective Permissions
+    Effective Permission
         A :term:`Permission` that has been completely resolved according to all applicable contexts, that indicates
         the final granted or denied result.
 
         .. seealso::
             :ref:`Effective Permissions <effective_permissions>` section for details.
 
+    Effective Resolution
+        Process of resolving :term:`Effective Permission` over a :term:`Resource` considering any applicable
+        :ref:`permission_modifiers`.
+
+        .. seealso::
+            :ref:`perm_resolution` section for details.
+
     External Providers
         Set of all known user-identity :term:`Provider` defined externally to `Magpie`. Each of these :term:`Provider`
         require specific connection methodologies, as configured in :mod:`magpie.security`.
@@ -97,14 +104,14 @@ Glossary
         request to ask for confirmation. The terms and conditions can only be defined upon the :term:`Group` creation
         and can never be modified afterwards.
 
-    Immediate Permissions
+    Immediate Permission
         Describes a :term:`Permission` that originates directly and only from a :term:`Service`.
         This is referenced in only a few use-cases, notably for :ref:`Finding User Permissions`.
 
         .. seealso::
             :ref:`Immediate Permissions <immediate_permissions>` section for details.
 
-    Inherited Permissions
+    Inherited Permission
         Describes a :term:`Permission` that includes both :term:`User` and :term:`Group` contexts simultaneously.
 
         .. seealso::
@@ -130,9 +137,9 @@ Glossary
         geospatial data and service methodologies in order to improve access to geospatial and location information.
 
     OWS
-        Acronym that regroups all :term:`OGC` Web Services. This includes `Web Feature Service` (WFS),
-        `Web Map Service` (WMS) and `Web Processing Service` (WPS) for which `Magpie` offers some specific
-        :term:`Service` request parser implementations.
+        Acronym that regroups all :term:`OGC` Web Services. This includes :term:`Web Feature Service <WFS>` (WFS),
+        :term:`Web Map Service <WMS>` (WMS) and :term:`Web Processing Service <WMS>` (WPS), amongst others, for which
+        `Magpie` offers some specific :term:`Service` request parser implementations.
 
     Pending User
         Account that is pending for validation or approval following self-registration when the application is
@@ -219,3 +226,19 @@ Glossary
 
         .. seealso::
             :ref:`config_webhook` and :ref:`config_file` sections for details.
+
+    Web Feature Service
+    WFS
+
+        One of the :term:`OWS` implementation which `Magpie` offers an implementation
+        for controlling access to layers and their features.
+
+    Web Map Service
+    WMS
+        One of the :term:`OWS` implementation which `Magpie` offers an implementation
+        for controlling access to layers and generated maps from them.
+
+    Web Processing Service
+    WPS
+        One of the :term:`OWS` implementation which `Magpie` offers an implementation
+        for controlling access to description and execution of processes.
diff --git a/docs/performance.rst b/docs/performance.rst
@@ -10,10 +10,10 @@ requests are execute in rapid succession. `PostgreSQL`_ and `SQLAlchemy`_ are us
 when more than a couple requests per second are needed, some solutions are possible to
 improve the performance of these requests by avoiding unnecessary reload of static data.
 
-We can take advantage of the fact that individual :temr:`Permission` and :term:`Service` definitions are not
+We can take advantage of the fact that individual :term:`Permission` and :term:`Service` definitions are not
 susceptible to change often and cache the results of these queries.
 
-While not activated by default, it's possible to cache the :term:`Access Control Lists` (ACLs) and :term:`Service`
+While not activated by default, it's possible to cache the :term:`Access Control List` (ACL) and :term:`Service`
 retrieval operations for all services, and give it an expiration timeout.
 
 .. code-block:: ini
@@ -26,8 +26,8 @@ retrieval operations for all services, and give it an expiration timeout.
 .. warning::
     Take into consideration that settings must be applied to `Twitcher`_ INI file such that incoming proxy requests
     will be effective in its web application, in turn using the :class:`magpie.adapter.MagpieAdapter`. Caching settings
-    defined in `Magpie` INI file will be employed only when requesting :term:`Effective Permissions` resolution using
-    `Magpie`'s API endpoints.
+    defined in `Magpie` INI file will be employed only when requesting
+    :term:`Effective Permissions <Effective Permission>` resolution using `Magpie`'s API endpoints.
 
 
 In the above example, for a particular request that queries a :term:`Logged User`'s ACL for a specific :term:`Service`,