ul-api-utils 9.3.0__py3-none-any.whl

ul_api_utils/resources/health_check/health_check.py

@@ -0,0 +1,439 @@
+import time
+from enum import Enum, IntEnum
+from typing import List, Callable, Any, Optional, Dict, TYPE_CHECKING, Tuple, NamedTuple, Set, Union
+
+from pydantic import model_validator, ConfigDict, Field, BaseModel, PositiveInt, TypeAdapter
+from sqlalchemy.sql import text
+from ul_unipipeline.errors import UniError
+from ul_unipipeline.modules.uni import Uni
+
+from ul_api_utils.api_resource.api_response import JsonApiResponsePayload
+from ul_api_utils.errors import Client4XXInternalApiError, Server5XXInternalApiError
+from ul_api_utils.internal_api.internal_api import InternalApi
+from ul_api_utils.internal_api.internal_api_response import InternalApiResponse
+from ul_api_utils.resources.health_check.const import INTERNAL_API_HEALTH_CHECK_PATH, SERVICE_NAME_DELIMITER
+
+if TYPE_CHECKING:
+    import flask_sqlalchemy
+    from redis import Redis
+
+
+class HealthCheckResultStatus(IntEnum):
+    OK = 200
+    WARN = 400
+    HAS_ERRORS = 503
+
+    @property
+    def status_code(self) -> int:
+        if self is HealthCheckResultStatus.OK:
+            return 200
+        if self is HealthCheckResultStatus.WARN:
+            return 400
+        if self is HealthCheckResultStatus.HAS_ERRORS:
+            return 503
+        raise NotImplementedError()
+
+
+THandlerReturn = Tuple[HealthCheckResultStatus, str, List['HealthCheckResult']]
+
+
+class HealthCheckStepType(Enum):
+    COMMON_CHECK = "COMMON_CHECK"
+    INTERNAL_API_CHECK = "INTERNAL_API_CHECK"
+    MESSAGE_QUEUE_CHECK = "MESSAGE_QUEUE_CHECK"
+    INTERNAL_API_HEALTH_CHECK = "INTERNAL_API_HEALTH_CHECK"
+
+    def _handle_internal_api_check(
+        self,
+        fn: Callable[..., InternalApiResponse[JsonApiResponsePayload]],
+        args: Tuple[Any, ...],
+        kwargs: Dict[str, Any],
+    ) -> THandlerReturn:
+        try:
+            executed_result = fn(*args, **kwargs)
+            executed_result.check()
+        except Exception as e:  # noqa: B902
+            return HealthCheckResultStatus.HAS_ERRORS, str(e), []
+        return HealthCheckResultStatus.OK, '', []
+
+    def _handle_internal_api_health_check(self, fn: Callable[..., InternalApiResponse[JsonApiResponsePayload]], args: Tuple[Any, ...], kwargs: Dict[str, Any]) -> THandlerReturn:
+        try:
+            error = None
+            executed_result = fn(*args, **kwargs)
+            try:
+                executed_result.check()
+            except (Client4XXInternalApiError, Server5XXInternalApiError) as e:
+                error = e
+            payload = TypeAdapter(HealthCheckApiResponse).validate_python(executed_result.payload_raw).checks
+            if error:
+                if isinstance(error, Client4XXInternalApiError):
+                    return HealthCheckResultStatus.WARN, '', payload
+                return HealthCheckResultStatus.HAS_ERRORS, '', payload
+            return HealthCheckResultStatus.OK, '', payload
+        except Exception as e:  # noqa: B902
+            return HealthCheckResultStatus.HAS_ERRORS, str(e), []
+
+    def _handle_common_check(self, fn: Callable[..., None], args: Tuple[Any, ...], kwargs: Dict[str, Any]) -> THandlerReturn:
+        try:
+            fn(*args, **kwargs)
+        except Exception as e:  # noqa: B902
+            return HealthCheckResultStatus.HAS_ERRORS, str(e), []
+        return HealthCheckResultStatus.OK, '', []
+
+    def _handle_message_queue_check(self, fn: Callable[..., List['HealthCheckQueueStats']], args: Tuple[Any, ...], kwargs: Dict[str, Any]) -> THandlerReturn:
+        try:
+            queues_stats = fn(*args, **kwargs)
+        except Exception as e:  # noqa: B902
+            return HealthCheckResultStatus.HAS_ERRORS, str(e), []
+
+        return (
+            max(stat.status for stat in queues_stats),
+            "".join(f"{stat.info}. \n" for stat in queues_stats),
+            [],
+        )
+
+    def run(self, fn: Callable[..., Any], args: Tuple[Any, ...], kwargs: Dict[str, Any]) -> Tuple[HealthCheckResultStatus, str, List['HealthCheckResult']]:
+        if self is HealthCheckStepType.COMMON_CHECK:
+            return self._handle_common_check(fn, args, kwargs)
+        if self is HealthCheckStepType.INTERNAL_API_CHECK:
+            return self._handle_internal_api_check(fn, args, kwargs)
+        if self is HealthCheckStepType.INTERNAL_API_HEALTH_CHECK:
+            return self._handle_internal_api_health_check(fn, args, kwargs)
+        if self is HealthCheckStepType.MESSAGE_QUEUE_CHECK:
+            return self._handle_message_queue_check(fn, args, kwargs)
+        raise NotImplementedError()
+
+
+class HealthCheckResult(BaseModel):
+    name: str = Field(
+        ...,
+        title="Health check step name",
+        description="The health-check contains multiple steps to check, each of the steps gets a name.",
+    )
+    time_spent: float = Field(
+        ...,
+        title="Time of execution",
+        description="Each health-check step takes some time to be processed, "
+                    "tells how much time took code execution for the health-check step.",
+    )
+    status: HealthCheckResultStatus
+    info: Optional[str] = Field(
+        None,
+        title="Information about health-check step",
+        description="Each successful health-check step has a status code "
+                    "but each failed have the error description here.",
+    )
+    type: HealthCheckStepType
+    internal_health_check_results: List['HealthCheckResult'] = Field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return self.status == HealthCheckResultStatus.OK
+
+
+def get_general_status(statuses: Set[HealthCheckResultStatus]) -> HealthCheckResultStatus:
+    if HealthCheckResultStatus.HAS_ERRORS in statuses:
+        return HealthCheckResultStatus.HAS_ERRORS
+    if HealthCheckResultStatus.HAS_ERRORS not in statuses and HealthCheckResultStatus.WARN in statuses:
+        return HealthCheckResultStatus.WARN
+    return HealthCheckResultStatus.OK
+
+
+class HealthCheckStep(NamedTuple):
+    name: str
+    type: HealthCheckStepType
+    executable: Callable[..., Any]
+    executable_args: Tuple[Any, ...] = tuple()
+    executable_kwargs: Any = Field(default_factory=lambda: dict())
+
+    def run(self) -> Tuple[HealthCheckResultStatus, float, str, List[HealthCheckResult]]:
+        start_time = time.perf_counter()
+        status, info, internal_health_check_results = self.type.run(self.executable, self.executable_args, self.executable_kwargs)
+        time_spent = time.perf_counter() - start_time
+        return status, time_spent, info, internal_health_check_results
+
+
+class HealthCheckContext:
+    def __init__(self, service_name: str, request_service_names: str, db: Optional['flask_sqlalchemy.SQLAlchemy'] = None):
+        self._db = db
+        self._request_service_names = service_name + SERVICE_NAME_DELIMITER + request_service_names
+        self._steps: List[HealthCheckStep] = []
+
+    @property
+    def steps(self) -> List[HealthCheckStep]:
+        return self._steps
+
+    def add_step(
+        self,
+        name: str,
+        executable: Callable[..., Any],
+        type_: HealthCheckStepType = HealthCheckStepType.COMMON_CHECK,
+        executable_args: Optional[Tuple[Any, ...]] = None,
+        executable_kwargs: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Registers a health-check step that would be executed automatically when health-check endpoint is called.
+
+        Note:
+            The executable provided to this method should not handle any exceptions that might be raised
+            because the error handling would be applied later under the hood, when all steps are executed.
+            On the contrary, the executable can raise exceptions inside of it as an indicator to the health-check
+            that something gone wrong. Also, function should not return any value because it won't be handled.
+        """
+        if not executable_kwargs:
+            executable_kwargs = {}
+        if not executable_args:
+            executable_args = tuple()
+        assert callable(executable), "You should provide a function that performs a step of a health check"
+        assert isinstance(executable_kwargs, dict), "Provide keyword arguments to function"
+        already_existing_steps = [step.name for step in self._steps]
+        assert name not in already_existing_steps, "This step has already been registered"
+        self._steps.append(
+            HealthCheckStep(
+                name=name,
+                type=type_,
+                executable=executable,
+                executable_args=executable_args,
+                executable_kwargs=executable_kwargs,
+            ),
+        )
+
+    def check_internal_api_route(
+        self,
+        internal_api: InternalApi,
+        name: str,
+        path: str,
+        *,
+        private: bool = True,
+        has_std_schema: bool = True,
+        q: Optional[Dict[str, Any]] = None,
+        access_token: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+        kind: HealthCheckStepType = HealthCheckStepType.INTERNAL_API_CHECK,
+    ) -> None:
+        """
+        Registers a wrapper for add_step but created with purpose
+        to distinguish Internal Api checks from other custom checks.
+
+        Note:
+            Supports only GET calls to Internal Api.
+            If you want your health-check step to perform other
+            methods you might need to add it here but its arguable
+            that you expect this behavior from health-check.
+
+        Parameters:
+            internal_api: Instance of self_api (internal_api) that can be found in project configuration.
+            name: The name of the health-check step, f.e. "All BS are online" or "GET devices".
+            path: The endpoint that you want to call through internal api, f.e. "/devices/info".
+            private: Private or not.
+            has_std_schema: Has schema or not.
+            q: Query parameters for the internal api GET request.
+            access_token: Token to access the internal_api endpoint, usually should use _default_auth_token.
+            headers: Headers for the request.
+            kind: Type of the check.
+        """
+        self.add_step(
+            name=name,
+            type_=kind,
+            executable=internal_api.request_get,
+            executable_args=(path,),
+            executable_kwargs={
+                "private": private,
+                "has_std_schema": has_std_schema,
+                "q": q,
+                "access_token": access_token,
+                "headers": headers,
+            },
+        )
+
+    def check_internal_api_health(self, internal_api: InternalApi, name: str) -> None:
+        """
+        Registers a wrapper for add_step but created with purpose
+        to distinguish self-api health-check from other custom checks.
+        """
+        self.check_internal_api_route(
+            internal_api,
+            name,
+            kind=HealthCheckStepType.INTERNAL_API_HEALTH_CHECK,
+            path=INTERNAL_API_HEALTH_CHECK_PATH,
+            q={"service_names": self._request_service_names},
+        )
+
+    def check_database_connection_exists(self) -> None:
+        """
+        Registers a wrapper for add_step but created with purpose
+        to distinguish database connection check from other custom checks.
+        """
+        if self._db is None:
+            raise NotImplementedError("This function should not be used in a health-check of a service, "
+                                      f"that doesn't have db connection, {self._db=}")
+        self.add_step(
+            name="Database connection exists",
+            type_=HealthCheckStepType.COMMON_CHECK,
+            executable=self._db_connection_exists,
+        )
+
+    def check_redis_connection_exists(self, redis_client: 'Union[Redis[str], Redis[bytes]]') -> None:
+        """
+        Registers a wrapper for add_step but created with purpose
+        to distinguish redis client connection check from other custom checks.
+        """
+        self.add_step(
+            name="Redis connection exists",
+            type_=HealthCheckStepType.COMMON_CHECK,
+            executable=self._redis_connection_exists,
+            executable_args=(redis_client,),
+        )
+
+    def check_message_queue_connection_exists(
+        self, uni: Uni,
+    ) -> None:
+        """
+        Registers a wrapper for add_step but created with purpose
+        to distinguish message queue connection check from other custom checks.
+        """
+        self.add_step(
+            name="Message Queue Connection",
+            type_=HealthCheckStepType.COMMON_CHECK,
+            executable=self._message_queue_connection_exists,
+            executable_kwargs={"uni": uni},
+        )
+
+    def check_message_queues_health(
+        self,
+        uni: Uni,
+        override_queue_limits: Optional[Dict[str, 'HealthCheckMessageQueueRange']] = None,
+    ) -> None:
+        """
+        Registers a wrapper for add_step but created with purpose
+        to distinguish message queue health checks from other custom checks.
+
+        Parameters:
+            uni: Instance of Uni class with .dag config, usually can be found in lib.py in every service.
+            override_queue_limits: Dictionary that contains queue name as a key, and HealthCheckMessageQueueRange
+                                   with attributes **OK** and **WARN** set.
+        """
+        self.add_step(
+            name="Message Queue Checks",
+            type_=HealthCheckStepType.MESSAGE_QUEUE_CHECK,
+            executable=self._message_queue_count_check,
+            executable_kwargs={
+                "uni": uni,
+                "override_queue_limits": override_queue_limits,
+            },
+        )
+
+    def _db_connection_exists(self) -> None:
+        """Basic SELECT 1 query to check the database connection."""
+        if self._db:  # just for mypy
+            self._db.session.query(text("1")).from_statement(text("SELECT 1")).all()
+
+    def _redis_connection_exists(self, redis_client: 'Union[Redis[str], Redis[bytes]]') -> None:
+        connection = redis_client.ping()
+        if not connection:
+            raise ConnectionError("Couldn't establish a connection to Redis client.")
+
+    def _message_queue_connection_exists(self, uni: Uni) -> None:
+        """Get the broker if success than connection exists."""
+        workers = uni.config.workers.values()
+        assert workers, "Workers are not set up"
+        for wd in uni.config.workers.values():
+            broker = uni._mediator.get_broker(wd.broker.name)
+            broker.connect()
+
+    @staticmethod
+    def _message_queue_count_check(
+        uni: Uni,
+        override_queue_limits: Optional[Dict[str, 'HealthCheckMessageQueueRange']] = None,
+    ) -> List['HealthCheckQueueStats']:
+        """
+        Retrieves all message broker queues and processing a status for each one of them.
+        Checks for typos that could've been coded through **override_queue_limits** parameter.
+        By default, it checks message queue health by pending messages and the default configuration is defined
+        in HealthCheckMessageQueueRange.
+        """
+        if override_queue_limits is None:
+            override_queue_limits = {}
+
+        queue_stats = []
+        available_queues = [wd.topic for wd in uni.config.workers.values()]
+        for overriden_queue in override_queue_limits.keys():
+            if overriden_queue not in available_queues:
+                raise KeyError(f"Can't find queue with name {overriden_queue} in the list of available queues.")
+
+        for wd in uni.config.workers.values():
+            broker = uni._mediator.get_broker(wd.broker.name)
+            try:
+                message_count = broker.get_topic_approximate_messages_count(wd.topic)
+            except UniError:
+                continue
+            if wd.topic in override_queue_limits:
+                overriden_queue_limit = override_queue_limits[wd.topic]
+            else:
+                overriden_queue_limit = HealthCheckMessageQueueRange()
+            queue_status = overriden_queue_limit.get_status(message_count=message_count)
+            queue_stats.append(HealthCheckQueueStats(message_count=message_count, queue_name=wd.topic, status=queue_status))
+        return queue_stats
+
+
+class HealthCheckApiResponse(JsonApiResponsePayload):
+    service_name: str
+    checks: List[HealthCheckResult] = Field(default_factory=list)
+
+    model_config = ConfigDict(use_enum_values=True)
+
+
+class HealthCheckMessageQueueRange(BaseModel):
+    """
+    Data class that was implemented in order to classify the health of message queues.
+    It derives status of message queue by the number of messages the queue has in it.
+    Queue classification by default:
+      - **OK** if the queue has **0** pending messages
+      - **WARN** if the queue has **1-100** pending messages
+      - **HAS_ERRORS** if the queue has **more than 100** pending messages
+    Note:
+        To override the default behavior, please provide attributes (ok, warn).
+        Make sure that warn is more than ok.
+    """
+    ok: PositiveInt = Field(
+        0,
+        title="Max OK message count",
+        description="Maximum number of messages for queue to have in order to be classified with status HEALTHY (200).",
+    )
+    warn: PositiveInt = Field(
+        100,
+        title="Max WARN message count",
+        description="Maximum number of messages for queue to have in order to be classified with status WARN (400).",
+    )
+
+    @model_validator(mode='after')
+    def root_validate(self) -> 'HealthCheckMessageQueueRange':
+        ok, warn = self.ok, self.warn
+        if ok is not None and warn is not None:
+            if ok >= warn:
+                raise ValueError(f"OK attribute should be less than WARN attribute, but you provided {ok=}, {warn=}")
+        return self
+
+    def get_status(self, message_count: int) -> HealthCheckResultStatus:
+        if message_count <= self.ok:
+            return HealthCheckResultStatus.OK
+        if self.ok < message_count <= self.warn:
+            return HealthCheckResultStatus.WARN
+        return HealthCheckResultStatus.HAS_ERRORS
+
+
+class HealthCheckQueueStats(BaseModel):
+    message_count: int
+    queue_name: str
+    status: HealthCheckResultStatus
+
+    @property
+    def info(self) -> str:
+        return f"Queue with name {self.queue_name} has {self.message_count} messages and status {self.status}"
+
+
+class HealthCheckQueueMessageCountStatus(BaseModel):
+    queue_name: str
+    message_count_status_map: Dict[range, HealthCheckResultStatus]
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)

ul_api_utils/resources/health_check/health_check_template.py

@@ -0,0 +1,64 @@
+from datetime import datetime
+from typing import List
+
+from ul_api_utils.resources.health_check.health_check import HealthCheckResult
+
+
+def render_result_row(result: HealthCheckResult, lvl: int) -> str:
+    table_s = ''
+    td_s = ''
+    td_s += f'<td>{"->&nbsp;" * lvl}{result.name}</td>'
+    td_s += f'<td>{result.status.name}</td>'
+    td_s += f'<td>{result.time_spent: <4.3f}s</td>'
+    td_s += f'<td><pre style="display: block; padding: 0; margin: 0;">' \
+            f'<code style="display: block; padding: 0; margin: 0;">{result.info if result.info is not None else "-"}</code></pre></td>'
+    table_s += f'<tr class="status-{result.status.name.lower()}">{td_s}</tr>'
+    if result.internal_health_check_results:
+        for res in result.internal_health_check_results:
+            table_s += render_result_row(res, lvl + 1)
+    return table_s
+
+
+def generate_health_check_table(health_check_results: List[HealthCheckResult], service_name: str) -> str:
+    header_s = f'''<!doctype html>
+    <html lang="en">
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+        <meta http-equiv="X-UA-Compatible" content="ie=edge">
+        <title>Health Check</title>
+    </head>
+    <body>
+    <div class="container">
+    <h1>Health Check Results {service_name} ({datetime.now().strftime("%Y-%m-%d %H:%M:%S")})</h1>
+    '''
+    footer_s = '''
+        </div>
+        <style>
+            .container { max-width: 1024px; margin: 30vh auto 100px; font-family: monospace; font-size: 14px; line-height: 1.2; }
+            table { border-collapse: collapse; width: 100%; background: white; }
+            table th { padding: 2px 4px; }
+            table td { padding: 2px 4px; border: 1px solid #ccc; }
+            table tr.status-ok > td { background: #a7ffa7; }
+            table tr.status-warn > td { background: yellow; }
+            table tr.status-has_errors > td { background: #f7abab; }
+        </style>
+        </body>
+    </html>
+    '''
+
+    table_s = '<table>' \
+              '<thead>' \
+              '<tr>' \
+              '<th align="left">Name of Test</th>' \
+              '<th align="left">Status</th>' \
+              '<th align="left">Duration</th>' \
+              '<th align="left">Info</th>' \
+              '</tr>' \
+              '</thead>' \
+              '<tbody>'
+    for result in health_check_results:
+        table_s += render_result_row(result, 0)
+
+    table_s += '</tbody></table>'
+    return header_s + table_s + footer_s

ul_api_utils/resources/health_check/resource.py

@@ -0,0 +1,97 @@
+from typing import Callable, TYPE_CHECKING, List, Tuple
+
+from ul_api_utils.api_resource.api_request import ApiRequestQuery
+from ul_api_utils.api_resource.api_resource import ApiResource
+from ul_api_utils.api_resource.api_resource_config import ApiResourceConfig
+from ul_api_utils.api_resource.api_response import HtmlApiResponse, JsonApiResponse
+from ul_api_utils.resources.health_check.const import SERVICE_NAME_DELIMITER
+from ul_api_utils.resources.health_check.health_check import HealthCheckContext, HealthCheckStep, HealthCheckResultStatus, HealthCheckResult, HealthCheckApiResponse
+from ul_api_utils.resources.health_check.health_check_template import generate_health_check_table
+from ul_api_utils.utils.api_method import ApiMethod
+
+if TYPE_CHECKING:
+    from ul_api_utils.modules.api_sdk import ApiSdk
+
+
+class HealthCheckQuery(ApiRequestQuery):
+    service_names: str = ''
+
+
+def run_health_check_steps(steps: List[HealthCheckStep]) -> Tuple[bool, HealthCheckResultStatus, List[HealthCheckResult]]:
+    """
+    Runs all the health-check steps and populates the result list
+    where all results of steps execution are stored.
+    Catches all exceptions that are being raised inside health-check steps and writes the exception info
+    to the info.
+    Also, calculates time of execution of each health-check step.
+    """
+    results: List[HealthCheckResult] = []
+    for step in steps:
+        step_status, time_spent, info, payload = step.run()
+        results.append(HealthCheckResult(
+            type=step.type,
+            name=step.name,
+            time_spent=time_spent,
+            status=step_status,
+            info=info,
+            internal_health_check_results=payload,
+        ))
+    result_statuses = set(result.status for result in results)
+    ok = any(status != HealthCheckResultStatus.OK for status in result_statuses)
+    status = max(result_statuses)
+    return ok, status, results
+
+
+def init_health_check_resource(fn: Callable[[HealthCheckContext], None], *, api_sdk: 'ApiSdk') -> None:
+    @api_sdk.html_view(ApiMethod.GET, path="/sys/health-check", access=api_sdk.ACCESS_PUBLIC)
+    def health_check_web(api_resource: ApiResource, query: HealthCheckQuery) -> HtmlApiResponse:
+        if api_sdk.config.service_name in query.service_names.split(SERVICE_NAME_DELIMITER):
+            return HtmlApiResponse(
+                ok=True,
+                content='',
+                status_code=200,
+            )
+
+        health_check_context = HealthCheckContext(
+            db=api_sdk.db,
+            service_name=api_sdk.config.service_name,
+            request_service_names=query.service_names,
+        )
+        fn(health_check_context)
+        ok, status, results = run_health_check_steps(health_check_context.steps)
+
+        return HtmlApiResponse(
+            ok=ok,
+            content=generate_health_check_table(results, api_sdk.config.service_name),
+            status_code=status.status_code,
+        )
+
+    @api_sdk.rest_api(ApiMethod.GET, path="/health-check", access=api_sdk.ACCESS_PUBLIC, config=ApiResourceConfig(swagger_disabled=True))
+    def health_check_api(api_resource: ApiResource, query: HealthCheckQuery) -> JsonApiResponse[HealthCheckApiResponse]:
+        if api_sdk.config.service_name in query.service_names.split(SERVICE_NAME_DELIMITER):
+            response = api_resource.response_ok(
+                HealthCheckApiResponse(
+                    service_name=api_sdk.config.service_name,
+                ),
+                total_count=0,
+            )
+            response.status_code = 200
+            return response
+
+        health_check_context = HealthCheckContext(
+            db=api_sdk.db,
+            service_name=api_sdk.config.service_name,
+            request_service_names=query.service_names,
+        )
+        fn(health_check_context)
+        ok, status, results = run_health_check_steps(health_check_context.steps)
+
+        response = api_resource.response_ok(
+            HealthCheckApiResponse(
+                service_name=api_sdk.config.service_name,
+                checks=results,
+            ),
+            total_count=len(results),
+        )
+        response.status_code = status.status_code
+        return response

ul_api_utils/resources/not_implemented.py

@@ -0,0 +1,25 @@
+from typing import Tuple, Callable
+
+from flask import request, Response, jsonify
+
+from ul_api_utils.const import RESPONSE_PROP_OK, RESPONSE_PROP_PAYLOAD, RESPONSE_PROP_ERRORS, MIME__JSON
+from ul_api_utils.debug.debugger import Debugger
+from ul_api_utils.utils.api_method import ApiMethod
+
+
+def not_implemented_handler(error: Exception, *, import_name: str, debugger_enabled: Callable[[], bool]) -> Tuple[Response, int]:
+    d = Debugger(import_name, debugger_enabled(), ApiMethod(request.method), request.url)
+
+    if MIME__JSON not in request.headers.get('accept', ''):
+        return Response('501. Not Implemented'), 501
+    return jsonify({
+        RESPONSE_PROP_OK: False,
+        RESPONSE_PROP_PAYLOAD: None,
+        RESPONSE_PROP_ERRORS: [
+            {
+                "error_type": "not-implemented",
+                "error_message": f"{request.method} {request.url}",
+            },
+        ],
+        **(d.render_dict(501) if d is not None else {}),
+    }), 501

ul_api_utils/resources/permissions.py

@@ -0,0 +1,29 @@
+from typing import List, TYPE_CHECKING, Optional, Union, Callable, Any, Dict
+
+from ul_api_utils.access import GLOBAL_PERMISSION__PUBLIC, PermissionRegistry
+from ul_api_utils.api_resource.api_resource import ApiResource
+from ul_api_utils.api_resource.api_resource_config import ApiResourceConfig
+from ul_api_utils.api_resource.api_response import JsonApiResponse, JsonApiResponsePayload
+from ul_api_utils.const import API_PATH__PERMISSIONS
+
+if TYPE_CHECKING:
+    from ul_api_utils.modules.api_sdk import ApiSdk
+
+
+class ApiPermissionsResponse(JsonApiResponsePayload):
+    category: str
+    permissions: List[Dict[str, Any]]
+    service: str
+
+
+def load_permissions(sdk: 'ApiSdk', app_name: str, permissions_registry: Optional[Union[Callable[[], PermissionRegistry], PermissionRegistry]]) -> None:
+    @sdk.rest_api('GET', API_PATH__PERMISSIONS, access=GLOBAL_PERMISSION__PUBLIC, config=ApiResourceConfig(swagger_group='system'))
+    def permissions(api_resource: ApiResource) -> JsonApiResponse[List[ApiPermissionsResponse]]:
+        if permissions_registry is None:
+            reg = PermissionRegistry(app_name, 0, 0)
+        elif isinstance(permissions_registry, PermissionRegistry):
+            reg = permissions_registry
+        else:
+            reg = permissions_registry()
+        resource_permissions = reg.get_categories_with_permissions()
+        return api_resource.response_ok(resource_permissions, len(resource_permissions))