py-app-runner 0.5.49.dev0__py3-none-any.whl

py_app_runner/audit/diff.py

@@ -0,0 +1,202 @@
+"""Comparing a row before a change against the values written to it.
+
+The comparison is the hard part. The two sides come from different places - one read back
+from Postgres, one handed in by the caller - and psycopg returns real Python types, so
+neither `==` nor a blind `str()` is right. `Decimal("10.50")` meets the `10.5` a caller
+passed, and a `date` meets its ISO string; calling either pair different reports a change on
+a column nobody touched, which is how an audit log becomes something nobody opens.
+"""
+
+import datetime
+import json
+from decimal import Decimal, InvalidOperation
+from typing import Any
+
+REDACTED = "***"
+
+# Only consulted when at least one side is a real bool. That guard is load-bearing: without
+# it a text column holding the literal "true" would silently equal one holding "1", and the
+# trail would stop showing a change that really happened.
+_TRUE = frozenset({"1", "t", "true", "y", "yes", "on"})
+_FALSE = frozenset({"0", "f", "false", "n", "no", "off", ""})
+
+
+def _boolish(value: Any) -> str:
+    """Reduce a value to "1"/"0" if it reads as a boolean, else to something that cannot
+    match either - so an unrecognised value still fails the comparison rather than being
+    guessed at."""
+
+    if isinstance(value, bool):
+        return "1" if value else "0"
+
+    if isinstance(value, int):
+        return "1" if value == 1 else ("0" if value == 0 else str(value))
+
+    text = str(value).strip().lower()
+    if text in _TRUE:
+        return "1"
+
+    if text in _FALSE:
+        return "0"
+
+    return text
+
+
+def _as_decimal(value: Any) -> Decimal | None:
+    if isinstance(value, bool):
+        return None
+
+    if isinstance(value, Decimal):
+        return value
+
+    if isinstance(value, (int, float)):
+        return Decimal(str(value))
+
+    if isinstance(value, str):
+        try:
+            return Decimal(value)
+        except (InvalidOperation, ValueError):
+            return None
+
+    return None
+
+
+def _is_plain_date(value: Any) -> bool:
+    return isinstance(value, datetime.date) and not isinstance(value, datetime.datetime)
+
+
+def _as_datetime(value: Any, as_date: bool) -> datetime.datetime | datetime.date | None:
+    """Parse to whichever of date/datetime the comparison is being made in.
+
+    Which one that is depends on the *other* operand: a `date` column comes back from
+    psycopg as a date, and its ISO string parsed as a datetime would be midnight on that
+    day - never equal to the date itself. So the pair decides the type, not each side
+    independently.
+    """
+
+    if isinstance(value, datetime.datetime):
+        return value.date() if as_date else value
+
+    if isinstance(value, datetime.date):
+        return value
+
+    if isinstance(value, str):
+        try:
+            return datetime.date.fromisoformat(value) if as_date else datetime.datetime.fromisoformat(value)
+        except ValueError:
+            return None
+
+    return None
+
+
+def same(a: Any, b: Any) -> bool:
+    """Whether two values represent the same stored content.
+
+    Deliberately not `==`. The two sides come from different places - one read back from
+    Postgres, one handed in by the caller - so a `date` legitimately meets its ISO string
+    and a `Decimal` meets an int.
+    """
+
+    if a is None or b is None:
+        return a is None and b is None
+
+    if isinstance(a, bool) or isinstance(b, bool):
+        return _boolish(a) == _boolish(b)
+
+    # Ordered before the numeric branch: datetime is not a number, but date arithmetic
+    # types would otherwise fall through to the string comparison and compare formatting
+    # rather than instants.
+    if isinstance(a, (datetime.datetime, datetime.date)) or isinstance(b, (datetime.datetime, datetime.date)):
+        as_date = _is_plain_date(a) or _is_plain_date(b)
+        left, right = _as_datetime(a, as_date), _as_datetime(b, as_date)
+        if left is None or right is None:
+            return str(a) == str(b)
+
+        if isinstance(left, datetime.datetime) and isinstance(right, datetime.datetime):
+            # A tz-aware value and a naive one cannot be ordered against each other, and
+            # guessing a timezone for the naive side would silently shift it.
+            if (left.tzinfo is None) != (right.tzinfo is None):
+                return str(a) == str(b)
+
+        return left == right
+
+    if isinstance(a, (dict, list, tuple, set)) or isinstance(b, (dict, list, tuple, set)):
+        return _json(a) == _json(b)
+
+    left_number, right_number = _as_decimal(a), _as_decimal(b)
+    if left_number is not None and right_number is not None:
+        return left_number == right_number
+
+    return str(a) == str(b)
+
+
+def _json(value: Any) -> str:
+    try:
+        return json.dumps(value, sort_keys=True, default=str)
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def mask(values: dict[str, Any], exclude: list[str]) -> dict[str, Any]:
+    """Replace excluded values while keeping their keys.
+
+    The key stays so the trail still shows that a password changed; only the value is
+    withheld.
+    """
+
+    if not exclude:
+        return values
+
+    return {key: (REDACTED if key in exclude else value) for key, value in values.items()}
+
+
+def between(
+    before: dict[str, Any] | None,
+    after: dict[str, Any] | None,
+    exclude: list[str] | None = None,
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    """Compare a row before and after, returning only what changed.
+
+    Four shapes: (None, after) is an insert, (before, None) a delete, (before, after) an
+    update reporting only differences, and (None, None) nothing.
+    """
+
+    excluded = exclude or []
+
+    if before is None and after is None:
+        return (None, None)
+
+    if before is None:
+        return (None, mask(after or {}, excluded))
+
+    if after is None:
+        return (mask(before, excluded), None)
+
+    old_values: dict[str, Any] = {}
+    new_values: dict[str, Any] = {}
+
+    # Only keys present in `after` are considered. An update is routinely handed three
+    # columns against a thirty-column row, and reporting the other twenty-seven as changes
+    # to nothing is how a trail becomes unreadable.
+    for key, new_value in after.items():
+        # A key absent from `before` is a change from None - the case a naive dict diff
+        # drops silently, and exactly the shape of "this column was just populated".
+        old_value = before.get(key)
+
+        if same(old_value, new_value):
+            continue
+
+        if key in excluded:
+            old_values[key] = REDACTED
+            new_values[key] = REDACTED
+            continue
+
+        old_values[key] = old_value
+        new_values[key] = new_value
+
+    if not new_values:
+        # Collapses to a pair of Nones rather than empty dicts, which is what lets the
+        # caller read "nothing changed" without inspecting the contents.
+        return (None, None)
+
+    return (old_values, new_values)

py_app_runner/audit/errors.py

@@ -0,0 +1,8 @@
+class AuditError(Exception):
+    """A refusal or a failed write in the audit trail.
+
+    Raised rather than logged when `strict` is on, which is the default: an audit trail
+    that quietly stops recording is worse than one that is obviously broken, because the
+    gap is only discovered when somebody goes looking for the row that should have been
+    there.
+    """

py_app_runner/audit/event.py

@@ -0,0 +1,130 @@
+"""The event, and the ambient context it is filled in from.
+
+The request id has to be per-task, which is why it is a ContextVar the bridge sets per
+request rather than anything process-wide. A single server process handles many requests at
+once, so a shared id would make "everything that happened in this request" return somebody
+else's changes alongside your own - and the trail would look correct while saying something
+false.
+"""
+
+import contextlib
+import contextvars
+import secrets
+from collections.abc import Iterator
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+CREATED = "created"
+UPDATED = "updated"
+DELETED = "deleted"
+
+
+@dataclass(frozen=True)
+class Actor:
+    type: str = ""
+    id: str = ""
+    name: str = ""
+
+
+@dataclass(frozen=True)
+class RequestContext:
+    request_id: str = ""
+    url: str = ""
+    ip_address: str = ""
+    user_agent: str = ""
+    actor: Actor = field(default_factory=Actor)
+
+
+# Defaulted to None rather than to an empty RequestContext. The instance would be shared by
+# every task that never entered request_context(), and while this one is frozen, a default
+# that is an object at all is the shape that goes wrong the moment somebody makes it
+# mutable.
+_context: contextvars.ContextVar[RequestContext | None] = contextvars.ContextVar(
+    "py_app_runner_audit_context", default=None
+)
+
+_EMPTY = RequestContext()
+
+
+def new_request_id() -> str:
+    """32 hex characters. Groups every change made during one request or CLI run."""
+
+    return secrets.token_hex(16)
+
+
+def current_context() -> RequestContext:
+    """An empty context outside any request, so recording never depends on having entered
+    one - a CLI command that audits a change still writes a row, just without an actor."""
+
+    return _context.get() or _EMPTY
+
+
+def set_context(context: RequestContext) -> contextvars.Token[RequestContext | None]:
+    return _context.set(context)
+
+
+@contextlib.contextmanager
+def request_context(
+    actor: Actor | None = None,
+    url: str = "",
+    ip_address: str = "",
+    user_agent: str = "",
+    request_id: str | None = None,
+) -> Iterator[RequestContext]:
+    """Establish the ambient context for one request, or one CLI run.
+
+    The bridge enters this per request; a command enters it once for the whole command. The
+    token is reset on the way out so a task that runs after this one does not inherit it.
+    """
+
+    context = RequestContext(
+        request_id=request_id if request_id is not None else new_request_id(),
+        url=url,
+        ip_address=ip_address,
+        user_agent=user_agent,
+        actor=actor or Actor(),
+    )
+
+    token = _context.set(context)
+    try:
+        yield context
+    finally:
+        _context.reset(token)
+
+
+@dataclass(frozen=True)
+class AuditEvent:
+    event: str
+    entity_type: str
+    entity_id: str = ""
+    module: str = ""
+    old_values: dict[str, Any] | None = None
+    new_values: dict[str, Any] | None = None
+    actor_type: str = ""
+    actor_id: str = ""
+    actor_name: str = ""
+    request_id: str = ""
+    url: str = ""
+    ip_address: str = ""
+    user_agent: str = ""
+    tags: list[str] = field(default_factory=list)
+    context: dict[str, Any] | None = None
+    created_at: Any = None
+
+    def with_resolved(self, context: RequestContext) -> "AuditEvent":
+        """Fill in only the fields that are still empty.
+
+        A caller that named the actor explicitly - an import recording who requested it
+        rather than whoever happens to be logged in - keeps what it passed.
+        """
+
+        return replace(
+            self,
+            actor_type=self.actor_type or context.actor.type,
+            actor_id=self.actor_id or context.actor.id,
+            actor_name=self.actor_name or context.actor.name,
+            request_id=self.request_id or context.request_id,
+            url=self.url or context.url,
+            ip_address=self.ip_address or context.ip_address,
+            user_agent=self.user_agent or context.user_agent,
+        )

py_app_runner/audit/store.py

@@ -0,0 +1,134 @@
+"""The single writer.
+
+One INSERT per event, on the cursor the caller handed in, inside whatever transaction the
+caller already opened. No buffering, no batching, no flush on shutdown - that is not an
+omission, it is the whole guarantee: a rolled-back change takes its audit row with it, and
+anything that defers the write gives that up.
+"""
+
+import datetime
+import json
+import re
+from typing import Any
+
+import psycopg
+from psycopg import sql
+
+from py_app_runner.audit.errors import AuditError
+from py_app_runner.audit.event import AuditEvent
+
+# The audit table is an identifier, so it cannot be bound as a parameter. Identifier()
+# quotes it, but a resolver is application code that may have been handed a value derived
+# from a request, so the shape is checked before it gets there.
+_TABLE_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$")
+
+# Values are cut to fit rather than rejected. An audit write that throws because somebody's
+# name is long has turned the trail into an outage.
+_WIDTHS = {
+    "request_id": 32,
+    "module": 64,
+    "event": 32,
+    "entity_type": 128,
+    "entity_id": 64,
+    "actor_type": 32,
+    "actor_id": 64,
+    "actor_name": 190,
+    "ip_address": 45,
+}
+
+_COLUMNS = (
+    "created_at",
+    "request_id",
+    "module",
+    "event",
+    "entity_type",
+    "entity_id",
+    "actor_type",
+    "actor_id",
+    "actor_name",
+    "old_values",
+    "new_values",
+    "url",
+    "ip_address",
+    "user_agent",
+    "tags",
+    "context",
+)
+
+
+def assert_table_name(table: str) -> str:
+    if _TABLE_RE.match(table) is None:
+        raise AuditError(f"Refusing to write the audit trail to {table!r}: not a plain table name")
+
+    return table
+
+
+def qualified(table: str) -> sql.Composed:
+    """Quote a schema qualifier as two identifiers.
+
+    Identifier("public.audit_log") quotes the dot into the name, producing a single
+    relation that does not exist.
+    """
+
+    return sql.SQL(".").join(sql.Identifier(part) for part in table.split("."))
+
+
+def _fit(column: str, value: str) -> str:
+    width = _WIDTHS.get(column)
+    if width is None or len(value) <= width:
+        return value
+
+    return value[:width]
+
+
+def _json(value: Any) -> str | None:
+    if value is None:
+        return None
+
+    try:
+        # ensure_ascii off so a name keeps its diacritics rather than becoming escapes
+        # nobody can read in a SELECT; default=str so a Decimal or a datetime in a payload
+        # is recorded rather than failing the whole write.
+        return json.dumps(value, ensure_ascii=False, default=str)
+    except (TypeError, ValueError):
+        # The change itself already happened. Losing the detail of it is bad; failing the
+        # request over an unserialisable value in a context dict is worse.
+        return None
+
+
+class Store:
+    def __init__(self, table: str = "audit_log") -> None:
+        self.table = assert_table_name(table)
+
+    async def write(self, cur: psycopg.AsyncCursor, event: AuditEvent) -> None:
+        statement = sql.SQL("INSERT INTO {rel} ({cols}) VALUES ({vals})").format(
+            rel=qualified(self.table),
+            cols=sql.SQL(", ").join(sql.Identifier(c) for c in _COLUMNS),
+            vals=sql.SQL(", ").join(sql.Placeholder() for _ in _COLUMNS),
+        )
+
+        await cur.execute(statement, self.row(event))
+
+    def row(self, event: AuditEvent) -> tuple[Any, ...]:
+        created_at = event.created_at or datetime.datetime.now(datetime.UTC)
+
+        return (
+            created_at,
+            _fit("request_id", event.request_id),
+            _fit("module", event.module),
+            _fit("event", event.event),
+            _fit("entity_type", event.entity_type),
+            _fit("entity_id", event.entity_id),
+            _fit("actor_type", event.actor_type),
+            _fit("actor_id", event.actor_id),
+            _fit("actor_name", event.actor_name),
+            _json(event.old_values),
+            _json(event.new_values),
+            event.url,
+            _fit("ip_address", event.ip_address),
+            event.user_agent,
+            # An empty tag list stores NULL rather than "[]", so "has tags" is a NULL check
+            # rather than a json length.
+            _json(event.tags) if event.tags else None,
+            _json(event.context),
+        )