[Processes] Add access policies documentation

Author: dmarteau

qjazz-processes/doc/configs/server.toml

@@ -12,6 +12,7 @@ description = "Publish Qgis processing algorithms as OGC api processes"
 
 # Defining job realm allow filtering job's requests by a token that is
 # set by the client when requesting task execution (see description below).
+# 
 [job_realm]
 #
 # Enable job realm header
@@ -231,6 +232,7 @@ enabled = false
 
 # The storage configuration is used for configuring the
 # connections to storage backends used by workers.
+# 
 [storage]
 #
 # Allow insecure downloads

qjazz-processes/doc/configs/worker.toml

@@ -7,6 +7,7 @@ level = "INFO"
 # Worker configuration
 # 
 # Configure celery worker settings
+# 
 [worker]
 #
 # Celery amqp broker host

qjazz-processes/doc/index.rst

@@ -13,6 +13,7 @@ Welcome to qjazz-processes's documentation!
    parameters
    execution
    jobrealm
+   policies
    openapi
 
 Indices and tables

qjazz-processes/doc/policies.rst

@@ -0,0 +1,174 @@
+.. _access_policies:
+
+Access policies
+===============
+
+Access policies control:
+
+- Which services a request can access
+- Which processes a user can execute
+- How services and projects are resolved from requests
+- How URLs are formatted for process links
+
+Implementing custom access policies
+-----------------------------------
+
+Custom access policies may be implemented from external modules.
+
+You may configure custom policies from the [access_policy] section of the
+server configuration:
+
+    .. code-block:: toml
+
+      [access_policy]
+      #
+      # Access policy module
+      #
+      # The module implementing the access policy for
+      # processes execution.
+      # 
+      policy_class = "mymodule.MyAccessPolicy"
+      
+      # The configuration of the custom policies in TOML
+      # format
+      [accesspolicy.config]
+
+
+AccessPolicy Protocol
+---------------------
+
+The ``policy_class`` must be an import string pointing to a class implementing the ``AccessPolicy`` protocol:
+
+
+Class Attributes
+~~~~~~~~~~~~~~~~
+
+``Config``: ``type[ConfigBase]``
+    A Pydantic model class for configuration. Defaults to ``NoConfig``.
+
+    The configuration will be validated against this model.
+
+``executor``: ``AsyncExecutor``
+    Set automatically by the framework. Provides access to available services.
+
+Methods
+~~~~~~~
+
+``setup(app: web.Application) -> None``
+    Called when the policy is initialized. Use to set up any resources.
+
+    *Default*: No-op.
+
+``service_permission(request: aiohttp.web.Request, service: str) -> bool``
+    Check if the request has permission to access the specified service.
+
+``execute_permission(request: web.Request, service: str, process_id: str, project: Optional[str] -> bool``
+    Check if the request has permission to execute the given process.
+
+``get_service(request: aiohttp.web.Request) -> str``
+    Resolve and return the service identifier for the request.
+    Called when a request requires service resolution.
+
+``get_project(request: aiohttp.web.Request) -> Optional[str]``
+    Resolve and return the project (QGIS project path) for the request.
+    Returns ``None`` if no project is specified.
+
+``prefix: str`` (property)
+    URL prefix for the policy. Used in path formatting.
+
+    *Default*: Empty string.
+
+``format_path(request: aiohttp.web.Request, path: str, service: Optional[str] = None, project: Optional[str] = None, *, query: Optional[str] = None) -> str``
+    Format a complete URL including service and project parameters.
+    Used to generate process links in API responses.
+
+Implementing a Custom Policy
+-----------------------------
+
+1. Create a Python package with your policy class:
+
+   .. code:: python
+
+       # my_policy/__init__.py
+       from my_policy.config import MyPolicyConfig
+       from my_policy.policy import MyAccessPolicy
+
+2. Define a configuration model:
+
+   .. code:: python
+
+       # my_policy/config.py
+       from qjazz_core.config import ConfigBase
+       from qjazz_core.models import Field
+
+
+       class MyPolicyConfig(ConfigBase):
+           allowed_services: list[str] = Field(
+               default=[],
+               description="List of allowed service names",
+           )
+
+3. Implement the policy class:
+
+   .. code:: python
+
+       # my_policy/policy.py
+       from typing import Optional
+       from aiohttp import web
+       from qjazz_processes.server.accesspolicy import AccessPolicy
+       from qjazz_core.config import ConfigBase
+
+
+       class MyAccessPolicy(AccessPolicy):
+           Config = MyPolicyConfig
+
+           def __init__(self, conf: MyPolicyConfig):
+               self._allowed = set(conf.allowed_services)
+
+           def setup(self, app: web.Application):
+               # Initialize resources if needed
+               pass
+
+           def service_permission(self, request: web.Request, service: str) -> bool:
+               return service in self._allowed
+
+           def execute_permission(
+               self,
+               request: web.Request,
+               service: str,
+               process_id: str,
+               project: Optional[str] = None,
+           ) -> bool:
+               # Add custom logic (e.g., check user permissions)
+               return True
+
+           def get_service(self, request: web.Request) -> str:
+               return request.query.get("service", "")
+
+           def get_project(self, request: web.Request) -> Optional[str]:
+               return request.query.get("map")
+
+           @property
+           def prefix(self) -> str:
+               return "/custom"
+
+           def format_path(
+               self,
+               request: web.Request,
+               path: str,
+               service: Optional[str] = None,
+               project: Optional[str] = None,
+               *,
+               query: Optional[str] = None,
+           ) -> str:
+               # Build URL with custom logic
+               return f"{self.prefix}{path}?service={service}&map={project}"
+
+4. Configure the policy in your server settings:
+
+   .. code:: python
+
+       AccessPolicyConfig(
+           policy_class="my_policy.policy.MyAccessPolicy",
+           config={"allowed_services": ["wfs", "wms"]},
+       )

qjazz-processes/src/qjazz_processes/server/accesspolicy.py

@@ -1,3 +1,14 @@
+""" Access policy configuration
+
+Access policies control:
+
+- Which services a request can access
+- Which processes a user can execute
+- How services and projects are resolved from requests
+- How URLs are formatted for process links
+
+Custom access policies can be implemented in external python module.
+"""
 from abc import abstractmethod
 from typing import (
     Annotated,
@@ -80,7 +91,7 @@ def get_service(self, request: web.Request) -> str:
 
     @abstractmethod
     def get_project(self, request: web.Request) -> Optional[str]:
-        """Return project for therequest"""
+        """Return project for the request"""
         ...
 
     @property

qjazz-processes/src/qjazz_processes/server/policies/__init__.py

@@ -1,2 +1,6 @@
 # reimport
-from .default import DefaultAccessPolicy  # noqa F401
+from .default import DefaultAccessPolicy
+
+__all__ = (
+    "DefaultAccessPolicy",
+)