keepup-admin 0.1.1__tar.gz → 0.3.0__tar.gz

{keepup_admin-0.1.1/keepup_admin.egg-info → keepup_admin-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keepup-admin
-Version: 0.1.1
+Version: 0.3.0
 Summary: An admin framework over FastAPI: plugins, panel, users, replicas
 Author-email: Fedor Sergeev <fksergeev@gmail.com>
 License-Expression: Apache-2.0
@@ -25,27 +25,44 @@ Requires-Dist: sqlalchemy<3,>=2.0
 Requires-Dist: psycopg2-binary>=2.9
 Requires-Dist: apscheduler<4,>=3.10
 Requires-Dist: bcrypt<5,>=4.0
-Requires-Dist: pyjwt[crypto]<3,>=2.10
-Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: pyjwt[crypto]<3,>=2.15
+Requires-Dist: python-multipart>=0.0.31
 Requires-Dist: PyYAML<7,>=6.0
 Requires-Dist: psutil>=7.0
 Requires-Dist: prometheus-client>=0.24
-Requires-Dist: requests>=2.31
+Requires-Dist: requests>=2.33
 Requires-Dist: httpx>=0.28
+Requires-Dist: cryptography>=50.0
+Requires-Dist: urllib3>=2.8
 Provides-Extra: test
 Requires-Dist: pytest>=8; extra == "test"
 Requires-Dist: pytest-asyncio>=0.24; extra == "test"
 Requires-Dist: pytest-cov>=5; extra == "test"
+Requires-Dist: uvicorn>=0.30; extra == "test"
 Provides-Extra: postgres
 Requires-Dist: asyncpg>=0.31; extra == "postgres"
 Dynamic: license-file
 
 # keepup
 
+[![tests](https://github.com/FedorSergeev/keepup-admin/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/FedorSergeev/keepup-admin/actions/workflows/tests.yml)
+[![security](https://github.com/FedorSergeev/keepup-admin/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/FedorSergeev/keepup-admin/actions/workflows/security.yml)
+[![PyPI](https://img.shields.io/pypi/v/keepup-admin)](https://pypi.org/project/keepup-admin/)
+[![licence](https://img.shields.io/pypi/l/keepup-admin)](LICENSE)
+
 [Project page](https://fedorsergeev.github.io/keepup-admin/) ·
 [Package](https://pypi.org/project/keepup-admin/) ·
 [Changes](CHANGELOG.md)
 
+Four badges, not six checks. These answer what somebody deciding whether to
+install asks: does it run on my Python, is there a known vulnerability in what
+it pulls in, what will I get, and may I use it. `quality`, `build` and `codeql`
+are housekeeping and live on the Actions page -- six badges in a row stop being
+read at all.
+
+A badge shows; it does not require. What keeps a red check from being merged is
+a branch rule, not a picture -- see `doc/keepup.md`.
+
 An admin framework over FastAPI. You give it settings; it gives you an
 application with a panel, a plugin runtime, users, a database layer, an audit,
 metrics and coordination between replicas already wired.
@@ -73,7 +90,7 @@ so the import name is free.
 | **Panel** | the shell, visual themes, and the catalogue of sections with role grants |
 | **Users** | local accounts, roles, panel sessions, sign-in through an external provider |
 | **Database** | a SQLAlchemy layer with a pool, table declarations for two dialects |
-| **Replicas** | distributed locks, leader election, a message bus, a cluster registry |
+| **Replicas** | distributed locks, a message bus, a cluster registry, performance settings in one place |
 | **Observability** | audit of incoming requests, an event log, metrics, log shipping |
 
 ## What it does not decide for you

{keepup_admin-0.1.1 → keepup_admin-0.3.0}/README.md

@@ -1,9 +1,23 @@
 # keepup
 
+[![tests](https://github.com/FedorSergeev/keepup-admin/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/FedorSergeev/keepup-admin/actions/workflows/tests.yml)
+[![security](https://github.com/FedorSergeev/keepup-admin/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/FedorSergeev/keepup-admin/actions/workflows/security.yml)
+[![PyPI](https://img.shields.io/pypi/v/keepup-admin)](https://pypi.org/project/keepup-admin/)
+[![licence](https://img.shields.io/pypi/l/keepup-admin)](LICENSE)
+
 [Project page](https://fedorsergeev.github.io/keepup-admin/) ·
 [Package](https://pypi.org/project/keepup-admin/) ·
 [Changes](CHANGELOG.md)
 
+Four badges, not six checks. These answer what somebody deciding whether to
+install asks: does it run on my Python, is there a known vulnerability in what
+it pulls in, what will I get, and may I use it. `quality`, `build` and `codeql`
+are housekeeping and live on the Actions page -- six badges in a row stop being
+read at all.
+
+A badge shows; it does not require. What keeps a red check from being merged is
+a branch rule, not a picture -- see `doc/keepup.md`.
+
 An admin framework over FastAPI. You give it settings; it gives you an
 application with a panel, a plugin runtime, users, a database layer, an audit,
 metrics and coordination between replicas already wired.
@@ -31,7 +45,7 @@ so the import name is free.
 | **Panel** | the shell, visual themes, and the catalogue of sections with role grants |
 | **Users** | local accounts, roles, panel sessions, sign-in through an external provider |
 | **Database** | a SQLAlchemy layer with a pool, table declarations for two dialects |
-| **Replicas** | distributed locks, leader election, a message bus, a cluster registry |
+| **Replicas** | distributed locks, a message bus, a cluster registry, performance settings in one place |
 | **Observability** | audit of incoming requests, an event log, metrics, log shipping |
 
 ## What it does not decide for you

keepup_admin-0.3.0/admin_trail.py

@@ -0,0 +1,60 @@
+"""What an administrator changed, written into the event log (keepup-67).
+
+The event log is where a deployment looks for who did what, and the framework's
+own administrative surface left nothing there: purging the log, changing the
+panel's sections, their grants and the themes, and switching a plugin's
+decision were visible only in the application log -- which rotates, is shipped
+elsewhere or nowhere, and is not what an operator reads. Each of those now
+writes one event naming the administrator.
+
+The types below are the framework's. Neither they nor the types an application
+declares can be created by hand through `POST /api/events`: a journal the
+watched party can fill with lookalikes is not evidence (keepup/events_api.py).
+
+Writing the trail never fails the action it records: the action has already
+happened, and answering an error for it would only invite a repeat. A trail
+that could not be written is logged as an error.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from keepup import events
+
+logger = logging.getLogger(__name__)
+
+#: What an application may import from this module. Everything else is
+#: internal and may change without notice -- see doc/keepup.md.
+__all__ = [
+    "ADMIN_EVENT_TYPES",
+    "EVENTS_PURGED",
+    "PLUGIN_DECISION_CHANGED",
+    "SECTIONS_CHANGED",
+    "THEMES_CHANGED",
+    "record",
+]
+
+EVENTS_PURGED = "admin_events_purged"
+SECTIONS_CHANGED = "admin_sections_changed"
+THEMES_CHANGED = "admin_themes_changed"
+PLUGIN_DECISION_CHANGED = "admin_plugin_decision_changed"
+
+ADMIN_EVENT_TYPES = (EVENTS_PURGED, SECTIONS_CHANGED, THEMES_CHANGED, PLUGIN_DECISION_CHANGED)
+
+
+def _author(admin: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    admin = admin or {}
+    return {"user_id": admin.get("id"), "username": admin.get("username")}
+
+
+async def record(event_type: str, admin: Optional[Dict[str, Any]], text: str,
+                 **details: Any) -> Optional[int]:
+    """Write one administrative event; the id, or None when it could not be written."""
+    data = {"by": _author(admin), **details}
+    try:
+        return await events.event_manager.create_event(
+            event_type=event_type, event_text=text, event_data=data)
+    except Exception as error:
+        logger.error(f"Could not record {event_type} by {data['by'].get('username')}: {error}")
+        return None
+

keepup_admin-0.3.0/api_docs.py

@@ -0,0 +1,76 @@
+"""The API schema and the documentation pages built from it (keepup-96).
+
+FastAPI serves its OpenAPI schema at /openapi.json to anybody, and the schema
+describes every route of the application -- the administrative ones with their
+parameters and bodies. For somebody outside that is a map of where to knock.
+FastAPI has no notion of who is asking, so the framework takes both routes over:
+
+- the schema answers an administrator only, like every other administrative
+  route of the framework, unless the application opens it on purpose
+  (``KeepupSettings.openapi_public``) or removes it (``openapi_url=None``);
+- the documentation pages stay public shells: they fetch the schema from the
+  browser, with the panel's cookie, so an administrator sees the API and anybody
+  else sees the refusal.
+
+Building the schema in code -- ``app.openapi()``, which ci/generate_openapi.py
+calls -- is untouched: it never went through the route.
+"""
+
+from fastapi import Depends
+from fastapi.openapi.docs import (
+    get_redoc_html,
+    get_swagger_ui_html,
+    get_swagger_ui_oauth2_redirect_html,
+)
+from fastapi.responses import JSONResponse
+
+from keepup.auth.dependencies import get_current_admin
+
+#: What an application may import from this module. Everything else is
+#: internal and may change without notice -- see doc/keepup.md.
+__all__ = ["OAUTH2_REDIRECT_URL", "register_api_documentation"]
+
+#: Where Swagger UI returns from an OAuth2 sign-in; FastAPI's own default.
+OAUTH2_REDIRECT_URL = "/docs/oauth2-redirect"
+
+
+def register_api_documentation(app, settings) -> None:
+    """The schema route and the documentation pages, as the settings ask.
+
+    Called right after the application is created: FastAPI used to register
+    these in its constructor, ahead of any route of the application, and a page
+    registered later could be shadowed by a route that happens to match it.
+    """
+    schema_url = settings.openapi_url
+    if not schema_url:
+        # No schema, no pages: they would have nothing to show.
+        return
+
+    if settings.openapi_public:
+        async def api_schema():
+            return JSONResponse(app.openapi())
+    else:
+        async def api_schema(admin: dict = Depends(get_current_admin)):
+            return JSONResponse(app.openapi())
+
+    app.add_api_route(schema_url, api_schema, methods=["GET"], include_in_schema=False)
+
+    if settings.docs_url:
+        async def swagger_page():
+            return get_swagger_ui_html(openapi_url=schema_url, title=f"{app.title} - API",
+                                       oauth2_redirect_url=OAUTH2_REDIRECT_URL)
+
+        async def swagger_redirect():
+            return get_swagger_ui_oauth2_redirect_html()
+
+        app.add_api_route(settings.docs_url, swagger_page, methods=["GET"],
+                          include_in_schema=False)
+        app.add_api_route(OAUTH2_REDIRECT_URL, swagger_redirect, methods=["GET"],
+                          include_in_schema=False)
+
+    if settings.redoc_url:
+        async def redoc_page():
+            return get_redoc_html(openapi_url=schema_url, title=f"{app.title} - API")
+
+        app.add_api_route(settings.redoc_url, redoc_page, methods=["GET"],
+                          include_in_schema=False)

{keepup_admin-0.1.1 → keepup_admin-0.3.0}/audit.py

@@ -17,7 +17,6 @@ recorded says so by name -- ``configure(redaction=keep_as_is)``.
 import asyncio
 import json
 import logging
-import os
 import time
 from contextlib import asynccontextmanager
 from datetime import datetime
@@ -26,8 +25,8 @@ from typing import Any, Dict, Optional
 from sqlalchemy import CheckConstraint, Column, DateTime, Index, Integer, Text, UniqueConstraint
 from sqlalchemy.dialects import postgresql
 
-from keepup import tables
-from keepup.db import DatabaseManager, DatabaseManagerV2, db_config
+from keepup import retention, tables
+from keepup.db import DatabaseManagerV2, db_config
 from keepup.instance import get_instance_id
 
 #: What an application may import from this module. Everything else is
@@ -132,6 +131,26 @@ incoming_requests_lock = asyncio.Lock()
 
 BUFFER_FLUSH_INTERVAL = 125
 BUFFER_MAX_SIZE = 100
+#: The most requests the buffer holds, whatever happens to the database
+#: (keepup-68). A failed flush puts its rows back, so with the database away the
+#: buffer used to grow with every request; past this the oldest go.
+BUFFER_HARD_LIMIT = 10_000
+#: After a failed flush, requests do not start another one for this long: the
+#: timed flusher still retries, but not every request on its own.
+FLUSH_RETRY_PAUSE_SECONDS = 5.0
+
+_flush_lock = asyncio.Lock()
+_flush_paused_until = 0.0
+dropped_requests = 0
+#: A request running this long is written without its outcome (keepup-41): the
+#: process that would have finished it has most likely gone.
+IN_FLIGHT_STALE_SECONDS = 3600
+
+
+def _as_datetime(value) -> datetime:
+    if isinstance(value, str):
+        return datetime.fromisoformat(value.replace('Z', ''))
+    return value
 
 
 class IncomingRequestLogger:
@@ -162,7 +181,13 @@ class IncomingRequestLogger:
                 'request_start_at': request_start,
                 'created_at': datetime.utcnow()
             }
-            if len(incoming_requests_buffer) >= BUFFER_MAX_SIZE:
+            global dropped_requests
+            while len(incoming_requests_buffer) > BUFFER_HARD_LIMIT:
+                # Insertion order: the first key is the oldest request.
+                incoming_requests_buffer.pop(next(iter(incoming_requests_buffer)))
+                dropped_requests += 1
+            if (len(incoming_requests_buffer) >= BUFFER_MAX_SIZE and not _flush_lock.locked()
+                    and time.monotonic() >= _flush_paused_until):
                 asyncio.create_task(IncomingRequestLogger.flush_buffer())
 
         return request_id
@@ -211,103 +236,98 @@ class IncomingRequestLogger:
             return True
 
     @staticmethod
-    async def flush_buffer() -> int:
-        """Write the buffered requests to the database."""
+    async def flush_buffer(include_in_flight: bool = False, now: Optional[datetime] = None) -> int:
+        """Write the finished requests of the buffer to the database.
+
+        A request still running stays in the buffer (keepup-41): written by a
+        timed flush and dropped from the buffer, it could no longer receive its
+        outcome -- end_request found nothing, logged "not found", and the table
+        kept a request with no status. Two exceptions: a request running longer
+        than IN_FLIGHT_STALE_SECONDS is written without an outcome, since the
+        process that would finish it has most likely gone and the buffer must
+        not grow forever; and at shutdown (``include_in_flight``) everything is
+        written -- nothing will finish afterwards.
+        """
+        # One flush at a time: a full buffer asked for one on every request.
+        async with _flush_lock:
+            return await IncomingRequestLogger._flush_buffer(include_in_flight, now)
 
+    @staticmethod
+    async def _flush_buffer(include_in_flight: bool, now: Optional[datetime]) -> int:
+        global _flush_paused_until, dropped_requests
+        now = now or datetime.utcnow()
+        # The buffer lock is taken by the start and the end of every request, so
+        # it is held only to pick the rows and take them out -- never across the
+        # write, which runs in a worker thread and may take as long as the
+        # database does (keepup-44).
         async with incoming_requests_lock:
-            if not incoming_requests_buffer:
-                return 0
-
-            requests_to_insert = list(incoming_requests_buffer.values())
-            inserted_count = 0
-
-            try:
-                values = []
-                for req in requests_to_insert:
-                    values.append((
-                        req['instance_id'],
-                        req['method'],
-                        req['endpoint'],
-                        req['host'],
-                        json.dumps(req['request_data']) if req['request_data'] else None,
-                        req['request_start_at'],
-                        req.get('request_end_at'),
-                        req.get('duration_ms'),
-                        req.get('http_status'),
-                        json.dumps(req.get('response_data')) if req.get('response_data') else None,
-                        req.get('error_message'),
-                        req['created_at']
-                    ))
-
-                if values:
-                    if db_config.is_postgres():
-                        query = '''
-                        INSERT INTO incoming_requests 
-                        (instance_id, method, endpoint, host, request_data, request_start_at, 
-                         request_end_at, duration_ms, http_status, response_data, error_message, created_at)
-                        VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
-                        ON CONFLICT (instance_id, method, endpoint, request_start_at) 
-                        DO NOTHING
-                        '''
-                    else:
-                        query = '''
-                        INSERT OR IGNORE INTO incoming_requests 
-                        (instance_id, method, endpoint, host, request_data, request_start_at, 
-                         request_end_at, duration_ms, http_status, response_data, error_message, created_at)
-                        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                        '''
-
-                    if db_config.is_postgres():
-                        conn = DatabaseManager.get_connection()
-                        cursor = conn.cursor()
-                        try:
-                            cursor.executemany(query, values)
-                            inserted_count = cursor.rowcount
-                            conn.commit()
-                        finally:
-                            cursor.close()
-                            conn.close()
-                    else:
-                        conn = DatabaseManager.get_connection()
-                        cursor = conn.cursor()
-                        try:
-                            cursor.executemany(query, values)
-                            inserted_count = cursor.rowcount
-                            conn.commit()
-                        finally:
-                            cursor.close()
-                            conn.close()
-
-                    if inserted_count > 0:
-                        inserted_ids = []
-                        for req_id, req_data in incoming_requests_buffer.items():
-                            for v in values:
-                                if (req_data['instance_id'] == v[0] and
-                                        req_data['method'] == v[1] and
-                                        req_data['endpoint'] == v[2] and
-                                        req_data['request_start_at'] == v[5]):
-                                    inserted_ids.append(req_id)
-                                    break
-
-                        for req_id in inserted_ids:
-                            incoming_requests_buffer.pop(req_id, None)
-
-                        logger.info(f"Flushed {inserted_count} incoming requests to database")
-
-            except Exception as e:
-                logger.error(f"Error flushing incoming requests buffer: {str(e)}")
-
-            return inserted_count
+            chosen = {
+                request_id: req for request_id, req in incoming_requests_buffer.items()
+                if include_in_flight or 'request_end_at' in req
+                or (now - _as_datetime(req['request_start_at'])).total_seconds()
+                >= IN_FLIGHT_STALE_SECONDS
+            }
+            for request_id in chosen:
+                incoming_requests_buffer.pop(request_id, None)
+        if not chosen:
+            return 0
+
+        rows = [{
+            'instance_id': req['instance_id'],
+            'method': req['method'],
+            'endpoint': req['endpoint'],
+            'host': req['host'],
+            'request_data': json.dumps(req['request_data']) if req['request_data'] else None,
+            'request_start_at': req['request_start_at'],
+            'request_end_at': req.get('request_end_at'),
+            'duration_ms': req.get('duration_ms'),
+            'http_status': req.get('http_status'),
+            'response_data': (json.dumps(req.get('response_data'))
+                              if req.get('response_data') else None),
+            'error_message': req.get('error_message'),
+            'created_at': req['created_at'],
+        } for req in chosen.values()]
+        columns = ("instance_id, method, endpoint, host, request_data, request_start_at, "
+                   "request_end_at, duration_ms, http_status, response_data, error_message, "
+                   "created_at")
+        placeholders = ", ".join(":" + c.strip() for c in columns.split(","))
+        if db_config.is_postgres():
+            query = (f"INSERT INTO incoming_requests ({columns}) VALUES ({placeholders}) "
+                     f"ON CONFLICT (instance_id, method, endpoint, request_start_at) DO NOTHING")
+        else:
+            query = f"INSERT OR IGNORE INTO incoming_requests ({columns}) VALUES ({placeholders})"
+
+        try:
+            inserted_count = await DatabaseManagerV2.execute_many_async(query, rows)
+        except Exception as e:
+            # Back into the buffer: the next flush tries again. A request that
+            # somehow reappeared meanwhile keeps its newer entry.
+            logger.error(f"Error flushing incoming requests buffer: {str(e)}")
+            _flush_paused_until = time.monotonic() + FLUSH_RETRY_PAUSE_SECONDS
+            async with incoming_requests_lock:
+                for request_id, req in chosen.items():
+                    incoming_requests_buffer.setdefault(request_id, req)
+            return 0
+
+        # Every chosen request is gone from the buffer, written or ignored as a
+        # duplicate alike: an ignored one is already in the table.
+        if inserted_count:
+            logger.info(f"Flushed {inserted_count} incoming requests to database")
+        if dropped_requests:
+            logger.warning(f"{dropped_requests} incoming requests were dropped from the "
+                           f"audit while it could not be written")
+            dropped_requests = 0
+        return inserted_count
 
 
 #: What PostgreSQL enforces with named constraints, SQLite held as a unique
 #: index of the same name and no checks at all; each dialect keeps what it had.
 # --- how long a row lives ----------------------------------------------------
 
-#: How many days an audit row is kept. The table used to have no sweep at all,
-#: while metric snapshots and application events both had one: it grew for as
-#: long as the deployment ran, and every row in it was a second place a value
-#: from a query string lived.
+#: How many days an audit row is kept. The table used to have no sweep at all:
+#: it grew for as long as the deployment ran, and every row in it was a second
+#: place a value from a query string lived. The event log is swept the same way
+#: (keepup/retention.py).
 DEFAULT_AUDIT_RETENTION_DAYS = 30
 #: How often the sweep runs.
 AUDIT_SWEEP_INTERVAL_SECONDS = 3600
@@ -324,35 +344,12 @@ AUDIT_RETENTION_LOCK = "incoming_requests_retention"
 
 
 def retention_days():
-    """How many days rows are kept, from the environment or the default.
-
-    Returns:
-        A positive number of days; rubbish in the variable means the default
-        and a line in the log, because a sweep that switched itself off
-        silently would be worse than one that swept too much.
-    """
-    raw = os.getenv("AUDIT_RETENTION_DAYS")
-    if raw in (None, ""):
-        return DEFAULT_AUDIT_RETENTION_DAYS
-    try:
-        value = int(raw)
-    except (TypeError, ValueError):
-        logger.warning("AUDIT_RETENTION_DAYS=%r is not a number, using %s",
-                       raw, DEFAULT_AUDIT_RETENTION_DAYS)
-        return DEFAULT_AUDIT_RETENTION_DAYS
-    if value <= 0:
-        logger.warning("AUDIT_RETENTION_DAYS=%s must be positive, using %s",
-                       value, DEFAULT_AUDIT_RETENTION_DAYS)
-        return DEFAULT_AUDIT_RETENTION_DAYS
-    return value
+    """How many days audit rows are kept (``AUDIT_RETENTION_DAYS``, 30 by default)."""
+    return retention.retention_days("AUDIT_RETENTION_DAYS", DEFAULT_AUDIT_RETENTION_DAYS)
 
 
 def purge_old_requests(days=None, now=None):
-    """Delete audit rows older than the retention period.
-
-    The boundary is computed here rather than in the statement: the interval
-    syntax differs between the engines, and a query written for one does not
-    run on the other.
+    """Delete audit rows older than the retention period, in chunks.
 
     Args:
         days: how many days to keep; read from the environment when omitted.
@@ -361,27 +358,10 @@ def purge_old_requests(days=None, now=None):
     Returns:
         How many rows were deleted.
     """
-    from datetime import timedelta
-
-    keep_days = days if days is not None else retention_days()
-    cutoff = (now or datetime.utcnow()) - timedelta(days=keep_days)
-
-    removed = 0
-    for _ in range(AUDIT_MAX_CHUNKS_PER_PASS):
-        rows = DatabaseManagerV2.execute(
-            "SELECT id FROM incoming_requests WHERE created_at < :cutoff "
-            "ORDER BY created_at ASC LIMIT :limit",
-            {"cutoff": cutoff, "limit": AUDIT_DELETE_CHUNK_ROWS})
-        if not rows:
-            break
-        ids = {f"i{index}": row["id"] for index, row in enumerate(rows)}
-        placeholders = ", ".join(f":{key}" for key in ids)
-        DatabaseManagerV2.execute_commit(
-            f"DELETE FROM incoming_requests WHERE id IN ({placeholders})", ids)
-        removed += len(rows)
-        if len(rows) < AUDIT_DELETE_CHUNK_ROWS:
-            break
-    return removed
+    return retention.purge_older_than(
+        "incoming_requests", "created_at",
+        days if days is not None else retention_days(),
+        AUDIT_DELETE_CHUNK_ROWS, AUDIT_MAX_CHUNKS_PER_PASS, now=now)
 
 
 async def audit_retention_background():
@@ -457,6 +437,12 @@ async def background_buffer_flusher():
             await asyncio.sleep(10)
 
 
+def _is_refusal(error: BaseException) -> bool:
+    """An HTTP refusal a route raised on purpose, whose text is its answer."""
+    from starlette.exceptions import HTTPException
+    return isinstance(error, HTTPException)
+
+
 @asynccontextmanager
 async def log_api_request(
         method: str,
@@ -483,10 +469,12 @@ async def log_api_request(
 
     except Exception as e:
         if request_id:
+            # A refusal keeps its reason: it is the answer the client was given.
+            # Anything else keeps its kind, not its text (keepup-76).
             await IncomingRequestLogger.end_request(
                 request_id=request_id,
                 duration_ms=int((time.time() - start_time) * 1000),
-                error_message=str(e)
+                error_message=str(e) if _is_refusal(e) else type(e).__name__
             )
         raise