aflib 0.0.1__tar.gz → 0.0.2__tar.gz

{aflib-0.0.1 → aflib-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aflib
-Version: 0.0.1
+Version: 0.0.2
 Summary: Helper library for business logic inside Airflows plpython function bodies
 License: MIT
 License-File: LICENSE
@@ -29,34 +29,38 @@ local-import, git or private-index route. Declare it in
 `models/pythonPackages/pythonPackages.airflows`:
 
 ```
-pythonPackage aflib==0.0.1
+pythonPackage aflib==0.0.2
 ```
 
 Then import it from a function body.
 
-## What 0.0.1 gives you
+## What 0.0.2 gives you
 
 ```python
-from aflib import BadParameter, Db, fail, ok, params
+from aflib import Db, errors, fail, logging, ok, params
 
 db = Db(plpy)
+log = logging.logger(plpy, source="Economic.receipt_cancel")
 
 try:
     receipt_id = params.as_int(p_id_receipt, name="p_id_receipt", required=True)
-except BadParameter as exc:
-    return fail("invalid_param", str(exc))
 
-row = db.query(
-    'SELECT id, amount FROM "Economic"."Receipt" WHERE id = $1',
-    [receipt_id], ["integer"],
-).one()
+    row = db.query(
+        'SELECT id, amount FROM "Economic"."Receipt" WHERE id = $1',
+        [receipt_id], ["integer"],
+    ).one()
 
-if row is None:
-    return fail("not_found", "No receipt with that id")
+    if row is None:
+        return fail("not_found", "No receipt with that id")
 
-return ok(row)
+    return ok(row)
+except Exception as exc:
+    return errors.to_fail(exc, log=log)
 ```
 
+**The `try` is not optional, and `except Exception` is not laziness.** See
+[Never let an exception escape](#never-let-an-exception-escape) below — both are load-bearing.
+
 - **`Db(plpy)`** — `plpy` is injected, never imported, because the function body is the only
   composition root available. `db.query(...)` returns a `Rows` you narrow with `.one()`
   (`None` for no row, and it refuses more than one rather than silently taking the first),
@@ -71,6 +75,16 @@ return ok(row)
 - **`codec.dumps` / `loads`** — JSON that raises on anything it cannot serialize instead of
   stringifying it. `numeric` columns arrive as `decimal.Decimal` and are encoded as strings,
   never floats, so exactness survives the round trip.
+- **`errors.to_fail(exc, log=log)`** — converts any exception into a failure envelope, keeping
+  the caller's message and the log's detail as two separate strings. A `BadParameter` is
+  described to the caller in full, because it is about their own input; anything else becomes
+  a generic `internal_error` whose detail goes only to the log. It returns the envelope even
+  if logging itself fails, because a broken log sink must not turn a handled failure back
+  into an escaping one.
+- **`logging.logger(plpy, source=…)`** — one JSON object per line, `level` and `event` always
+  present, written through `plpy.log`. It never raises, even when handed a value that cannot
+  be encoded: the line is most needed in the error path, so a single exotic field must not be
+  able to silence it.
 
 ## Platform constraints worth knowing before you build on it
 
@@ -93,6 +107,36 @@ the library has the shape it does.
 - **Never cache request-scoped state in `GD` or `SD`.** Consecutive calls land on different
   pooled backends, and the connection role varies per caller.
 
+### Never let an exception escape
+
+**An unhandled exception's message is returned to the caller, and it includes internal detail
+that the caller should not see.** A function body cannot influence that response: it is built
+outside the database from the driver's error message, and there is no setting that trims it.
+The only way to control what a caller receives is to not raise — catch everything and return
+a failure envelope instead. That is what `errors.to_fail` is for, and it is why every example
+here wraps its work in a `try`.
+
+`except Exception` is required rather than merely convenient. **`plpy.Error` does not inherit
+from `plpy.SPIError`**, so the narrower `except plpy.SPIError` catches neither `plpy.error()`
+nor an ordinary Python exception — only their common ancestor covers all three.
+
+Two related facts worth knowing before you design around logging:
+
+- **Of plpython's five informational sinks, only `log` and `warning` are written.** `debug`,
+  `info` and `notice` return successfully and are discarded, because `log_min_messages`
+  defaults to `WARNING` and those three rank below it while `log` ranks above. A level that
+  vanishes is worse than one that does not exist, which is why `aflib.logging` puts severity
+  in the payload and writes everything through `plpy.log`.
+- **The platform logs every call's parameter values in plaintext** before the body runs. So
+  never pass a secret as a function parameter — it is recorded no matter how careful the body
+  is — and do not log parameter values yourself, since that cannot reduce the exposure and
+  only makes it look deliberate.
+
+- **A callee's error message reaches its caller unredacted.** Function bodies compose through
+  SQL, and when a callee raises, its message crosses to the caller intact while its exception
+  *type* does not. So a business outcome has to travel as a returned value — `ok`/`fail` — and
+  never as an exception, and nothing sensitive may ever go into an exception message.
+
 ## Tests
 
 ```

{aflib-0.0.1 → aflib-0.0.2}/README.md

@@ -20,34 +20,38 @@ local-import, git or private-index route. Declare it in
 `models/pythonPackages/pythonPackages.airflows`:
 
 ```
-pythonPackage aflib==0.0.1
+pythonPackage aflib==0.0.2
 ```
 
 Then import it from a function body.
 
-## What 0.0.1 gives you
+## What 0.0.2 gives you
 
 ```python
-from aflib import BadParameter, Db, fail, ok, params
+from aflib import Db, errors, fail, logging, ok, params
 
 db = Db(plpy)
+log = logging.logger(plpy, source="Economic.receipt_cancel")
 
 try:
     receipt_id = params.as_int(p_id_receipt, name="p_id_receipt", required=True)
-except BadParameter as exc:
-    return fail("invalid_param", str(exc))
 
-row = db.query(
-    'SELECT id, amount FROM "Economic"."Receipt" WHERE id = $1',
-    [receipt_id], ["integer"],
-).one()
+    row = db.query(
+        'SELECT id, amount FROM "Economic"."Receipt" WHERE id = $1',
+        [receipt_id], ["integer"],
+    ).one()
 
-if row is None:
-    return fail("not_found", "No receipt with that id")
+    if row is None:
+        return fail("not_found", "No receipt with that id")
 
-return ok(row)
+    return ok(row)
+except Exception as exc:
+    return errors.to_fail(exc, log=log)
 ```
 
+**The `try` is not optional, and `except Exception` is not laziness.** See
+[Never let an exception escape](#never-let-an-exception-escape) below — both are load-bearing.
+
 - **`Db(plpy)`** — `plpy` is injected, never imported, because the function body is the only
   composition root available. `db.query(...)` returns a `Rows` you narrow with `.one()`
   (`None` for no row, and it refuses more than one rather than silently taking the first),
@@ -62,6 +66,16 @@ return ok(row)
 - **`codec.dumps` / `loads`** — JSON that raises on anything it cannot serialize instead of
   stringifying it. `numeric` columns arrive as `decimal.Decimal` and are encoded as strings,
   never floats, so exactness survives the round trip.
+- **`errors.to_fail(exc, log=log)`** — converts any exception into a failure envelope, keeping
+  the caller's message and the log's detail as two separate strings. A `BadParameter` is
+  described to the caller in full, because it is about their own input; anything else becomes
+  a generic `internal_error` whose detail goes only to the log. It returns the envelope even
+  if logging itself fails, because a broken log sink must not turn a handled failure back
+  into an escaping one.
+- **`logging.logger(plpy, source=…)`** — one JSON object per line, `level` and `event` always
+  present, written through `plpy.log`. It never raises, even when handed a value that cannot
+  be encoded: the line is most needed in the error path, so a single exotic field must not be
+  able to silence it.
 
 ## Platform constraints worth knowing before you build on it
 
@@ -84,6 +98,36 @@ the library has the shape it does.
 - **Never cache request-scoped state in `GD` or `SD`.** Consecutive calls land on different
   pooled backends, and the connection role varies per caller.
 
+### Never let an exception escape
+
+**An unhandled exception's message is returned to the caller, and it includes internal detail
+that the caller should not see.** A function body cannot influence that response: it is built
+outside the database from the driver's error message, and there is no setting that trims it.
+The only way to control what a caller receives is to not raise — catch everything and return
+a failure envelope instead. That is what `errors.to_fail` is for, and it is why every example
+here wraps its work in a `try`.
+
+`except Exception` is required rather than merely convenient. **`plpy.Error` does not inherit
+from `plpy.SPIError`**, so the narrower `except plpy.SPIError` catches neither `plpy.error()`
+nor an ordinary Python exception — only their common ancestor covers all three.
+
+Two related facts worth knowing before you design around logging:
+
+- **Of plpython's five informational sinks, only `log` and `warning` are written.** `debug`,
+  `info` and `notice` return successfully and are discarded, because `log_min_messages`
+  defaults to `WARNING` and those three rank below it while `log` ranks above. A level that
+  vanishes is worse than one that does not exist, which is why `aflib.logging` puts severity
+  in the payload and writes everything through `plpy.log`.
+- **The platform logs every call's parameter values in plaintext** before the body runs. So
+  never pass a secret as a function parameter — it is recorded no matter how careful the body
+  is — and do not log parameter values yourself, since that cannot reduce the exposure and
+  only makes it look deliberate.
+
+- **A callee's error message reaches its caller unredacted.** Function bodies compose through
+  SQL, and when a callee raises, its message crosses to the caller intact while its exception
+  *type* does not. So a business outcome has to travel as a returned value — `ok`/`fail` — and
+  never as an exception, and nothing sensitive may ever go into an exception message.
+
 ## Tests
 
 ```

{aflib-0.0.1 → aflib-0.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aflib"
-version = "0.0.1"
+version = "0.0.2"
 description = "Helper library for business logic inside Airflows plpython function bodies"
 readme = "README.md"
 # The platform runs Python 3.11.2 (observed, not assumed — see docs/platform-constraints.md).
@@ -33,3 +33,4 @@ include = [
     "README.md",
     "LICENSE",
 ]
+

aflib-0.0.2/src/aflib/__init__.py

@@ -0,0 +1,56 @@
+"""Helper library for business logic inside Airflows `plpython3u` function bodies.
+
+Nothing enters this package until it has run on a real Airflows instance. See
+`docs/02-roadmap.md` for what exists and what is still only a plan.
+
+`src/aflib/` imports the standard library, `plpy` and `airflows` — nothing else. See
+`docs/adr/0001-stdlib-only-no-third-party-dependencies.md`.
+
+A function body's whole import line, and the shape of a body:
+
+    from aflib import Db, errors, fail, logging, ok, params
+
+    db = Db(plpy)
+    log = logging.logger(plpy, source="Economic.receipt_cancel")
+
+    try:
+        tid = params.as_int(p_id_receipt, name="p_id_receipt", required=True)
+
+        row = db.query("SELECT * FROM t WHERE id = $1", [tid], ["integer"]).one()
+        if row is None:
+            return fail("not_found", "No receipt with that id")
+        return ok(row)
+    except Exception as exc:
+        return errors.to_fail(exc, log=log)
+
+**The `try` is not optional.** An exception that escapes a function body is returned to the
+HTTP caller along with the function's name, the failing line number and the literal source
+line — so catching everything is a security control, not a matter of taste. `except
+Exception` is also the only clause that works: `plpy.Error` does not inherit from
+`plpy.SPIError`, so the narrower version catches neither `plpy.error()` nor an ordinary
+Python exception.
+"""
+
+from aflib import codec, db, errors, logging, params, result
+from aflib.db import Db
+from aflib.params import BadParameter
+from aflib.result import fail, ok
+
+# Kept in step with `pyproject.toml` by hand. A deployed body returns this so a run can
+# prove which aflib it actually imported — a stale package otherwise looks exactly like a
+# working one.
+__version__ = "0.0.2"
+
+__all__ = [
+    "BadParameter",
+    "Db",
+    "codec",
+    "db",
+    "errors",
+    "fail",
+    "logging",
+    "ok",
+    "params",
+    "result",
+    "__version__",
+]

aflib-0.0.2/src/aflib/errors.py

@@ -0,0 +1,111 @@
+"""Turning any exception into something safe to return.
+
+    from aflib import Db, errors, logging as aflog, ok
+
+    log = aflog.logger(plpy, source="Economic.receipt_cancel")
+    try:
+        ...
+        return ok(data)
+    except Exception as exc:          # noqa: BLE001 - see below, this is the point
+        return errors.to_fail(exc, log=log)
+
+**Why a body must catch everything.** An exception that escapes is returned to the HTTP
+caller together with the function's name, the failing line number and the literal source
+line. Every `httpEnabled` endpoint is directly reachable, so an uncaught error is a
+source-disclosure primitive: make a function fail, read one line of it, and repeat. The
+platform produces that response in its own Java handler from the JDBC driver's message —
+there is no setting that suppresses it, and nothing a body can do except not raise.
+
+**`except Exception` is not laziness here, it is the only sufficient clause.** `plpy.Error`
+does not inherit from `plpy.SPIError`, so the narrower `except plpy.SPIError` catches
+neither `plpy.error()` nor any ordinary Python exception. Only their common ancestor covers
+all three.
+
+**The caller's message and the log's detail are two different strings.** A callee's message
+text reaches its caller unredacted, so anything a body knows — a connection string, a token,
+another customer's row — must go to the log and never into what is returned.
+"""
+
+from collections import namedtuple
+
+from aflib import result
+
+Failure = namedtuple("Failure", ("code", "message", "detail"))
+"""What a caller may be told (`code`, `message`) and what it may not (`detail`).
+
+`detail` is `None` when nothing is being hidden — a bad parameter is already described to
+the caller in full, so there is nothing left to log.
+"""
+
+# The message every unrecognised failure gets. Deliberately says nothing: not the exception
+# type, not the text, not where it happened.
+_INTERNAL_MESSAGE = "An internal error occurred."
+
+# Only SQLSTATEs OBSERVED on the platform are mapped, and only those safe to name. This is
+# short on purpose. Inventing a table from the Postgres manual would put codes here that no
+# run has ever produced, and the mapping is what a caller sees — a wrong entry is a wrong
+# answer to a user. The write slices will observe the constraint violations (unique,
+# foreign key, check, not-null) and each one earns its place then.
+#
+#   22P02  invalid_text_representation — 'abc' where a number was wanted. The caller's own
+#          input, so naming the category tells them something useful and reveals nothing.
+_SAFE_SQLSTATES = {
+    "22P02": ("invalid_value", "A value was not in the expected format."),
+}
+
+
+def classify(exc):
+    """Describe `exc` as a `Failure`, splitting what is safe to return from what is not."""
+    # Imported lazily: `params` imports nothing from here, but keeping the dependency at
+    # call time leaves the two modules independent of import order.
+    from aflib.params import BadParameter
+
+    if isinstance(exc, BadParameter):
+        # Already a description of the caller's own input, so it can be quoted back
+        # verbatim and there is nothing to hide.
+        return Failure("invalid_param", str(exc), None)
+
+    sqlstate = getattr(exc, "sqlstate", None)
+    detail = _detail(exc, sqlstate)
+
+    if sqlstate in _SAFE_SQLSTATES:
+        code, message = _SAFE_SQLSTATES[sqlstate]
+        return Failure(code, message, detail)
+
+    return Failure("internal_error", _INTERNAL_MESSAGE, detail)
+
+
+def to_fail(exc, log=None):
+    """Log what must stay hidden, and return the failure envelope for the caller.
+
+    The envelope is returned even if logging fails. A broken sink must not turn a handled
+    failure back into an escaping exception — that would disclose source at the very moment
+    the code was trying to prevent it.
+    """
+    failure = classify(exc)
+
+    if log is not None and failure.detail is not None:
+        try:
+            log.error("request_failed", code=failure.code, detail=failure.detail)
+        except Exception:
+            # Swallowed deliberately, and this is the one place it is right to do so: the
+            # caller's response matters more than the log line, and re-raising here would
+            # defeat the module's whole purpose.
+            pass
+
+    return result.fail(failure.code, failure.message)
+
+
+def _detail(exc, sqlstate):
+    """The hidden half: everything useful for diagnosis, none of it caller-facing.
+
+    The exception's class name is included because it is how the platform distinguishes a
+    callee's Python raise (`ExternalRoutineException`) from `plpy.error()`
+    (`InternalError`) from a real database error (`DivisionByZero`) — all of which arrive
+    as SPI errors once they cross a function boundary.
+    """
+    parts = [type(exc).__name__]
+    if sqlstate is not None:
+        parts.append("sqlstate=" + str(sqlstate))
+    parts.append(str(exc))
+    return " ".join(parts)

aflib-0.0.2/src/aflib/logging.py

@@ -0,0 +1,119 @@
+"""Structured logging through the one sink the server actually writes.
+
+    from aflib import logging as aflog
+
+    log = aflog.logger(plpy, source="Economic.receipt_cancel")
+    log.info("receipt_cancelled", receipt_id=7)
+    log.error("unexpected_failure", detail=str(exc))
+
+One JSON object per line, `level` and `event` always present. Severity lives **in the
+payload**, not in the choice of sink, and there is a reason for that.
+
+plpython offers five informational sinks and only two of them are written: `log` and
+`warning`. `debug`, `info` and `notice` succeed, report nothing wrong, and are discarded by
+the server, because `log_min_messages` sits at its default of `WARNING` and those three
+rank below it. Offering them as levels would be a false promise — the call works and the
+line is gone.
+
+Of the two that survive, this module uses **`log`**. It is written under the default
+configuration and is not delivered to a client; a `warning` is also written but IS
+delivered to a connected SQL client, which is a leak risk for nothing `log` does not
+already give. And never `plpy.error()`, which *raises*: reaching for it in an error path
+would abort the handler that was trying to report the failure.
+
+**Do not log parameter values.** The platform already writes every call's parameters —
+names, declared types and values — to its log in plaintext before the body runs. Repeating
+them cannot reduce that exposure and only makes it look deliberate.
+"""
+
+import json
+from decimal import Decimal
+
+# `level` and `event` are how a line is found in a log that is grepped rather than
+# queried. A field silently overwriting either would break every search built on them.
+_RESERVED = ("level", "event")
+
+
+def _lenient(value):
+    """Called by `json.dumps` only for values it cannot serialise itself.
+
+    Unlike `codec.dumps`, this **never refuses**. That difference is deliberate: refusing
+    is right for a response, where a wrong value must not reach a caller, and wrong for a
+    log, where the line is most needed in the error path. One exotic field must not be able
+    to silence the record that explains a failure.
+    """
+    if isinstance(value, Decimal):
+        # A string, not a float, for the same reason a response does it: `float` loses
+        # exactness and drops the trailing zero that makes a price a price.
+        return str(value)
+    return repr(value)
+
+
+class Logger:
+    """Writes one JSON line per call. Never raises on its own account."""
+
+    def __init__(self, plpy, source=None):
+        self._plpy = plpy
+        self._source = source
+
+    # `event` is positional-ONLY (the `/`) so that `event=` lands in `**fields` and meets
+    # the reserved-name guard below. Left as a normal parameter, Python raises
+    # "multiple values for argument 'event'" instead — a different error for the same
+    # mistake that `level=` makes, and one that says nothing about why the name is taken.
+    def info(self, event, /, **fields):
+        """Something happened that is worth a line."""
+        self._write("info", event, fields)
+
+    def error(self, event, /, **fields):
+        """Something failed. Tags the line `error`; does not raise, and does not abort."""
+        self._write("error", event, fields)
+
+    def _write(self, level, event, fields):
+        for name in _RESERVED:
+            if name in fields:
+                raise ValueError(
+                    "a field may not be named {!r}: it would overwrite the record's own "
+                    "{} and break every log search that relies on it".format(name, name)
+                )
+
+        record = {"level": level, "event": event}
+        if self._source is not None:
+            # Omitted rather than written as null when absent: a cron or a trigger has no
+            # meaningful source, and `"source": null` on every such line is noise.
+            record["source"] = self._source
+        record.update(fields)
+
+        self._plpy.log(self._encode(record))
+
+    @staticmethod
+    def _encode(record):
+        """Encode the record, falling back rather than raising.
+
+        `default=` is never consulted for a **circular** structure — `json.dumps` raises
+        before it gets there — so a lenient default alone does not make this safe. Losing
+        the fields is an acceptable outcome; losing the line is not, because a silently
+        dropped record makes a failure look like nothing happened at all.
+        """
+        try:
+            return json.dumps(record, default=_lenient)
+        except Exception as exc:
+            # Rebuilt from the keys that are known to be encodable, following the same
+            # absent-not-null rule as the normal path.
+            safe = {key: record[key] for key in ("level", "event", "source")
+                    if key in record}
+            # Names the cause so the missing fields are explained rather than a mystery,
+            # and keeps the field NAMES, which are often enough to identify the call site.
+            safe["unencodable"] = {
+                "reason": type(exc).__name__ + ": " + str(exc),
+                "fields": sorted(k for k in record if k not in safe),
+            }
+            return json.dumps(safe)
+
+
+def logger(plpy, source=None):
+    """Build a logger over an injected `plpy`.
+
+    `plpy` is passed in rather than imported for the same reason `Db` takes it: the
+    function body is the composition root, and tests hand over a double.
+    """
+    return Logger(plpy, source=source)

{aflib-0.0.1 → aflib-0.0.2}/tests/conftest.py

@@ -57,14 +57,55 @@ class FakeResult:
         return iter(self._rows)
 
 
+class FakeError(Exception):
+    """Stands in for `plpy.Error`, what `plpy.error()` raises.
+
+    Deliberately NOT a subclass of anything resembling `SPIError`: on the platform
+    `plpy.Error` does not inherit from `plpy.SPIError` (gap G32, probe `slice2-r1`), which
+    is why `except plpy.SPIError` fails to catch it.
+    """
+
+
 class FakePlpy:
     """Stands in for the plpython `plpy` global."""
 
+    Error = FakeError
+
     def __init__(self, rows=None, colnames=None):
         self.rows = rows if rows is not None else []
         self.colnames = colnames
         self.executed = []
         self.prepared = []
+        # Every sink is recorded SEPARATELY, because which one a line went to is the
+        # finding that matters: only `log` and `warning` are written by the server at all,
+        # and the other three are silently discarded (gap G35, probe `slice2-r1`). A double
+        # that lumped them together could not catch a logger writing into the void.
+        self.logged = []
+        self.noticed = []
+        self.warned = []
+        self.informed = []
+        self.debugged = []
+
+    def log(self, message):
+        self.logged.append(message)
+
+    def notice(self, message):
+        self.noticed.append(message)
+
+    def warning(self, message):
+        self.warned.append(message)
+
+    def info(self, message):
+        self.informed.append(message)
+
+    def debug(self, message):
+        self.debugged.append(message)
+
+    def error(self, message):
+        # RAISES, as the real one does. A logger that reached for this in an error path
+        # would abort the very handler trying to report a failure, so the double has to
+        # make that mistake fail a test rather than pass one.
+        raise FakeError(message)
 
     def prepare(self, sql, argtypes=None):
         plan = ("PLAN", sql, tuple(argtypes or ()))

aflib-0.0.2/tests/test_errors.py

@@ -0,0 +1,159 @@
+"""Turning any exception into something safe to return.
+
+This module exists because of one observed platform behaviour: an exception that escapes a
+function body is returned to the HTTP caller **with the function's name, the failing line
+number and the literal source line** (gap G33). Every `httpEnabled` endpoint is directly
+reachable, so an uncaught error is a source-disclosure primitive — make a function fail,
+read a line of it, repeat. Catching everything is therefore a security control, not tidiness.
+
+Two more findings shape it:
+
+- `except Exception` is the only sufficient guard. `plpy.Error` does not inherit from
+  `plpy.SPIError`, so the obvious clause catches neither `plpy.error()` nor a plain Python
+  exception (G32).
+- A callee's message text reaches its caller unredacted (G32). So the message a caller sees
+  and the detail that goes to the log are **two different strings**, and conflating them is
+  the bug this module is built to prevent.
+"""
+
+import json
+
+from aflib import errors, logging as aflog
+from aflib.params import BadParameter
+
+
+class FakeSPIError(Exception):
+    """An exception carrying `sqlstate`, as every plpy SPI error does (G32)."""
+
+    def __init__(self, message, sqlstate):
+        Exception.__init__(self, message)
+        self.sqlstate = sqlstate
+
+
+SECRET = "customers.card_token = 4111111111111111"
+
+
+# --- classify: what the caller may see, and what it may not -----------
+
+def test_a_bad_parameter_is_the_callers_own_fault_and_may_be_quoted_back():
+    # The message describes what the caller sent, so it reveals nothing they did not
+    # already know. Nothing is hidden, so there is nothing to log.
+    failure = errors.classify(BadParameter("p_int: expected a whole number, got 'abc'"))
+
+    assert failure.code == "invalid_param"
+    assert failure.message == "p_int: expected a whole number, got 'abc'"
+    assert failure.detail is None
+
+
+def test_an_unrecognised_exception_becomes_a_generic_internal_error():
+    failure = errors.classify(RuntimeError("connection to " + SECRET + " failed"))
+
+    assert failure.code == "internal_error"
+
+
+def test_an_internal_errors_message_never_carries_the_original_text():
+    # THE test this module exists for. If this ever fails, the module is worse than
+    # nothing: it would look like a safety layer while forwarding the detail anyway.
+    failure = errors.classify(RuntimeError("connection to " + SECRET + " failed"))
+
+    assert SECRET not in failure.message
+    assert "RuntimeError" not in failure.message
+
+
+def test_the_original_text_is_preserved_for_the_log():
+    # Hidden from the caller, not thrown away — otherwise nothing could be diagnosed.
+    failure = errors.classify(RuntimeError("connection to " + SECRET + " failed"))
+
+    assert SECRET in failure.detail
+    assert "RuntimeError" in failure.detail
+
+
+def test_an_observed_sqlstate_is_reported_as_the_callers_fault():
+    # 22P02 is invalid_text_representation: 'abc' where a number was wanted. Observed on
+    # the platform, so it is mapped. The code is named; the text still is not.
+    failure = errors.classify(
+        FakeSPIError('invalid input syntax for type integer: "abc"', "22P02"))
+
+    assert failure.code == "invalid_value"
+    assert "abc" not in failure.message
+
+
+def test_an_unmapped_sqlstate_stays_internal():
+    # Deliberately conservative: only SQLSTATEs actually observed on the platform are
+    # mapped. Anything else is internal until a real run proves what it should be.
+    failure = errors.classify(FakeSPIError("something odd", "99999"))
+
+    assert failure.code == "internal_error"
+
+
+def test_the_sqlstate_is_recorded_in_the_detail():
+    failure = errors.classify(FakeSPIError("something odd", "99999"))
+
+    assert "99999" in failure.detail
+
+
+# --- to_fail: the whole error path a body needs -----------------------
+
+def test_to_fail_returns_a_failure_envelope():
+    envelope = json.loads(errors.to_fail(RuntimeError("boom " + SECRET)))
+
+    assert envelope["ok"] is False
+    assert envelope["error"]["code"] == "internal_error"
+
+
+def test_the_envelope_never_carries_the_original_text():
+    envelope = errors.to_fail(RuntimeError("boom " + SECRET))
+
+    assert SECRET not in envelope
+
+
+def test_to_fail_logs_the_hidden_detail_when_given_a_logger(make_plpy):
+    fake = make_plpy()
+
+    errors.to_fail(RuntimeError("boom " + SECRET), log=aflog.logger(fake))
+
+    assert len(fake.logged) == 1
+    record = json.loads(fake.logged[0])
+    assert record["level"] == "error"
+    assert SECRET in record["detail"]
+
+
+def test_to_fail_logs_the_code_it_returned(make_plpy):
+    # So a log line can be tied to the response the caller actually received.
+    fake = make_plpy()
+
+    errors.to_fail(RuntimeError("boom"), log=aflog.logger(fake))
+
+    assert json.loads(fake.logged[0])["code"] == "internal_error"
+
+
+def test_to_fail_logs_nothing_when_there_is_nothing_hidden(make_plpy):
+    # A bad parameter is already fully described to the caller. Logging it again would fill
+    # the log with other people's typos.
+    fake = make_plpy()
+
+    errors.to_fail(BadParameter("p_int: expected a whole number"), log=aflog.logger(fake))
+
+    assert fake.logged == []
+
+
+def test_to_fail_works_without_a_logger():
+    # A body that has not built a logger must still be able to fail safely — otherwise the
+    # safe path is the inconvenient one.
+    envelope = json.loads(errors.to_fail(RuntimeError("boom")))
+
+    assert envelope["ok"] is False
+
+
+def test_to_fail_still_returns_an_envelope_if_logging_itself_fails():
+    # The response matters more than the log line. If the sink is broken, the caller must
+    # still get a clean failure rather than an escaping exception — which would disclose
+    # source (G33) at the worst possible moment.
+    class BrokenLogger:
+        def error(self, event, **fields):
+            raise RuntimeError("sink is down")
+
+    envelope = json.loads(errors.to_fail(RuntimeError("boom"), log=BrokenLogger()))
+
+    assert envelope["ok"] is False
+    assert envelope["error"]["code"] == "internal_error"

aflib-0.0.2/tests/test_logging.py

@@ -0,0 +1,170 @@
+"""What a body may rely on when it writes a log line.
+
+Every choice tested here is forced by something observed on the platform, not preferred:
+
+- Of plpython's five informational sinks, only `log` and `warning` are written by the
+  server at all — `debug`, `info` and `notice` succeed and are silently discarded (gap
+  G35). A level that vanishes is a false promise, so severity travels in the payload and
+  every line goes to one sink.
+- That sink is `log`. It is written under the server's default configuration and is not
+  delivered to a client, whereas a warning IS delivered to a connected SQL client for no
+  benefit `log` does not already give (G35).
+- Never `plpy.error()`: it raises. In an error path that would abort the handler trying to
+  report the failure (G32).
+- The platform already logs every call's parameter values in plaintext (G34), so a logger
+  must not be the thing that makes that worse.
+"""
+
+import json
+
+import pytest
+
+from aflib import logging as aflog
+
+
+def test_a_line_is_written_through_plpy_log(make_plpy):
+    fake = make_plpy()
+    aflog.logger(fake).info("receipt_cancelled")
+
+    assert len(fake.logged) == 1
+
+
+def test_no_other_sink_is_ever_touched(make_plpy):
+    # The three silent sinks would lose the line; `warning` would reach a SQL client.
+    fake = make_plpy()
+    log = aflog.logger(fake)
+
+    log.info("a")
+    log.error("b")
+
+    assert fake.noticed == []
+    assert fake.warned == []
+    assert fake.informed == []
+    assert fake.debugged == []
+
+
+def test_error_does_not_raise(make_plpy):
+    # `plpy.error()` raises. If `error()` reached for it, reporting a failure would abort
+    # the handler doing the reporting — the worst possible moment.
+    fake = make_plpy()
+
+    aflog.logger(fake).error("unexpected_failure")
+
+    assert len(fake.logged) == 1
+
+
+def test_each_line_is_one_json_object_carrying_level_and_event(make_plpy):
+    fake = make_plpy()
+    aflog.logger(fake).info("receipt_cancelled")
+
+    record = json.loads(fake.logged[0])
+    assert record["level"] == "info"
+    assert record["event"] == "receipt_cancelled"
+
+
+def test_error_lines_are_marked_as_such_in_the_payload(make_plpy):
+    fake = make_plpy()
+    aflog.logger(fake).error("boom")
+
+    assert json.loads(fake.logged[0])["level"] == "error"
+
+
+def test_fields_are_merged_into_the_object(make_plpy):
+    fake = make_plpy()
+    aflog.logger(fake).info("receipt_cancelled", receipt_id=7, reason="duplicate")
+
+    record = json.loads(fake.logged[0])
+    assert record["receipt_id"] == 7
+    assert record["reason"] == "duplicate"
+
+
+def test_source_is_included_when_given(make_plpy):
+    fake = make_plpy()
+    aflog.logger(fake, source="Economic.receipt_cancel").info("started")
+
+    assert json.loads(fake.logged[0])["source"] == "Economic.receipt_cancel"
+
+
+def test_source_is_absent_rather_than_null_when_not_given(make_plpy):
+    # A cron or trigger has no meaningful source. Writing `"source": null` on every line
+    # would be noise in a log that is grepped, not queried.
+    fake = make_plpy()
+    aflog.logger(fake).info("started")
+
+    assert "source" not in json.loads(fake.logged[0])
+
+
+def test_a_field_that_cannot_be_serialised_still_produces_a_line(make_plpy):
+    # THE most important test here. `codec.dumps` refuses unserialisable values by design,
+    # which is right for a response and fatal for a log: the logger is most needed in the
+    # error path, and one exotic field must not silence it.
+    class Unserialisable:
+        pass
+
+    fake = make_plpy()
+    aflog.logger(fake).error("failed", culprit=Unserialisable())
+
+    record = json.loads(fake.logged[0])
+    assert record["event"] == "failed"
+    assert "Unserialisable" in str(record["culprit"])
+
+
+def test_a_decimal_field_is_written_as_a_string(make_plpy):
+    # Same rule as the response envelope: a money value keeps its exactness.
+    from decimal import Decimal
+
+    fake = make_plpy()
+    aflog.logger(fake).info("charged", amount=Decimal("1234.50"))
+
+    assert json.loads(fake.logged[0])["amount"] == "1234.50"
+
+
+def test_a_field_may_not_overwrite_level_or_event(make_plpy):
+    # `level` and `event` are what makes a line findable. A caller passing either as a
+    # field would silently break every search that relies on them, so it fails loudly at
+    # the call site instead.
+    fake = make_plpy()
+    log = aflog.logger(fake)
+
+    with pytest.raises(ValueError) as exc:
+        log.info("started", level="debug")
+    assert "level" in str(exc.value)
+
+    with pytest.raises(ValueError):
+        log.info("started", event="something_else")
+
+
+def test_a_circular_field_still_produces_a_line(make_plpy):
+    # `default=` is never consulted for a circular structure — `json.dumps` raises
+    # ValueError before reaching it. Without a guard the logger would raise from inside an
+    # error handler, which is the one thing it promises not to do.
+    circular = {}
+    circular["self"] = circular
+
+    fake = make_plpy()
+    aflog.logger(fake).error("failed", data=circular)
+
+    record = json.loads(fake.logged[0])
+    assert record["level"] == "error"
+    assert record["event"] == "failed"
+    # The fallback follows the same rule as the normal path: absent, not null.
+    assert "source" not in record
+
+
+def test_a_line_that_cannot_be_encoded_says_so(make_plpy):
+    # Losing the fields is acceptable; losing the fact that something was logged, and
+    # silently, is not — that would make a failure look like nothing happened.
+    circular = {}
+    circular["self"] = circular
+
+    fake = make_plpy()
+    aflog.logger(fake).error("failed", data=circular)
+
+    assert "unencodable" in fake.logged[0]
+
+
+def test_logging_nothing_but_an_event_is_valid(make_plpy):
+    fake = make_plpy()
+    aflog.logger(fake).info("started")
+
+    assert json.loads(fake.logged[0]) == {"level": "info", "event": "started"}

{aflib-0.0.1 → aflib-0.0.2}/tests/test_public_api.py

@@ -34,6 +34,19 @@ def test_exports_db_directly():
     assert aflib.Db is not None
 
 
+def test_exports_the_failure_path():
+    # A body's error handler is the one thing that must never be awkward to reach: if
+    # `errors` or `logging` needed a longer import than the happy path, the safe route
+    # would be the inconvenient one — and an exception that escapes returns the function's
+    # own source line to the caller.
+    from aflib import errors, logging
+
+    assert errors.to_fail is not None
+    assert logging.logger is not None
+    assert "errors" in aflib.__all__
+    assert "logging" in aflib.__all__
+
+
 def test_exports_bad_parameter_directly():
     # A body catches this by name. Re-exported so `from aflib import BadParameter` works
     # without knowing which module defines it — it moves to an `errors` module in slice 2,

aflib-0.0.1/src/aflib/__init__.py

@@ -1,42 +0,0 @@
-"""Helper library for business logic inside Airflows `plpython3u` function bodies.
-
-Nothing enters this package until it has run on a real Airflows instance. See
-`docs/02-roadmap.md` for what exists and what is still only a plan.
-
-`src/aflib/` imports the standard library, `plpy` and `airflows` — nothing else. See
-`docs/adr/0001-stdlib-only-no-third-party-dependencies.md`.
-
-A function body's whole import line, and the shape of a body:
-
-    from aflib import Db, ok, fail, params
-
-    db = Db(plpy)
-    tid = params.as_int(p_id_receipt, name="p_id_receipt", required=True)
-
-    row = db.query("SELECT * FROM t WHERE id = $1", [tid], ["integer"]).one()
-    if row is None:
-        return fail("not_found", "No receipt with that id")
-    return ok(row)
-"""
-
-from aflib import codec, db, params, result
-from aflib.db import Db
-from aflib.params import BadParameter
-from aflib.result import fail, ok
-
-# Kept in step with `pyproject.toml` by hand. A deployed body returns this so a run can
-# prove which aflib it actually imported — a stale package otherwise looks exactly like a
-# working one.
-__version__ = "0.0.1"
-
-__all__ = [
-    "BadParameter",
-    "Db",
-    "codec",
-    "db",
-    "fail",
-    "ok",
-    "params",
-    "result",
-    "__version__",
-]