velocity-python 0.1.102__tar.gz → 0.1.104__tar.gz

{velocity_python-0.1.102 → velocity_python-0.1.104}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.102
+Version: 0.1.104
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.102 → velocity_python-0.1.104}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.102"
+version = "0.1.104"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.1.102 → velocity_python-0.1.104}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.102"
+__version__ = version = "0.1.104"
 
 import importlib as _importlib
 

{velocity_python-0.1.102 → velocity_python-0.1.104}/src/velocity/aws/handlers/mixins/__init__.py

@@ -6,15 +6,19 @@ This package provides mixins for common Lambda handler patterns:
 - ButtonHandler: Dynamic button action handler loading
 - DataServiceMixin: Generic CRUD operations for database-backed APIs
 - JobHandler: get-job-status / download-job-result / cancel-job for async jobs
+- SessionControlMixin: opt-in single-active-login enforcement (register /
+  check / end session actions; pairs with velocity-react's SessionGate)
 """
 
 from .web_handler import WebHandler, ButtonHandler
 from .data_service import DataServiceMixin
 from .job_handler import JobHandler
+from .session_control import SessionControlMixin
 
 __all__ = [
     "WebHandler",
     "ButtonHandler",
     "DataServiceMixin",
     "JobHandler",
+    "SessionControlMixin",
 ]

{velocity_python-0.1.102 → velocity_python-0.1.104}/src/velocity/aws/handlers/mixins/data_service.py

@@ -65,12 +65,59 @@ def _bump_sys_id_sequence(tx, table):
     )
 
 
+def _sys_id_fk_references(tx, table):
+    """Foreign keys pointing AT this table's sys_id, as
+    (referencing_table, referencing_column) pairs. A multi-column FK yields
+    referencing_column None (callers treat it conservatively)."""
+    return tx.execute(
+        """select con.conrelid::regclass::text as referencing_table,
+                  case when array_length(con.conkey, 1) = 1
+                       then (select att.attname from pg_attribute att
+                              where att.attrelid = con.conrelid
+                                and att.attnum = con.conkey[1])
+                  end as referencing_column
+           from pg_constraint con
+           join pg_class rel on rel.oid = con.confrelid
+           join pg_namespace nsp on nsp.oid = rel.relnamespace
+           where con.contype = 'f' and nsp.nspname = 'public'
+             and rel.relname = %s
+             and (select att.attname from pg_attribute att
+                   where att.attrelid = con.confrelid
+                     and att.attnum = con.confkey[1]) = 'sys_id'""",
+        (table,),
+    ).all()
+
+
+def _count_fk_rows(tx, references, sys_id):
+    """Rows that actually reference ``sys_id`` through the given FK pairs.
+    Returns human-readable "table (n row(s))" descriptions, or raises for an
+    FK shape too odd to check safely (multi-column, unquotable names)."""
+    blocked = []
+    for ref in references:
+        ref_table = ref.get("referencing_table") or ""
+        ref_column = ref.get("referencing_column") or ""
+        if not (_IDENTIFIER_RE.match(ref_table) and _IDENTIFIER_RE.match(ref_column)):
+            raise AlertError(
+                f"Renumbering is not allowed: {ref_table or 'a table'} references "
+                f"this table through a foreign key this tool cannot inspect."
+            )
+        count = tx.execute(
+            f'select count(*) as n from "{ref_table}" where "{ref_column}" = %s',
+            (sys_id,),
+        ).scalar()
+        if count:
+            blocked.append(f"{ref_table} ({count} row(s))")
+    return blocked
+
+
 def renumber_row(tx, table, old_sys_id, new_sys_id, overwrite=False):
     """Assign a CHOSEN sys_id to an existing row (admin surgery).
 
     Rules (deliberately simple):
-    - refused when any real foreign-key constraint references this table's
-      sys_id (renumbering under FKs is a cascade problem for another day);
+    - a foreign-key CONSTRAINT on this table's sys_id is fine; what refuses
+      the change is actual referencing ROWS — rows pointing at the old id
+      (reassigning references is not implemented), or, on overwrite, rows
+      pointing at the occupant that would be deleted;
     - when the target sys_id already exists: refused unless ``overwrite`` —
       which DELETES the occupying row first;
     - the table's sys_id sequence is bumped past MAX(sys_id) afterwards so
@@ -95,27 +142,24 @@ def renumber_row(tx, table, old_sys_id, new_sys_id, overwrite=False):
     if not tx.table(table).find(old_id):
         raise AlertError(f"Record {old_id} was not found in {table}.")
 
-    referencing = tx.execute(
-        """select con.conrelid::regclass::text as referencing_table
-           from pg_constraint con
-           join pg_class rel on rel.oid = con.confrelid
-           join pg_namespace nsp on nsp.oid = rel.relnamespace
-           where con.contype = 'f' and nsp.nspname = 'public'
-             and rel.relname = %s
-           limit 5""",
-        (table,),
-    ).all()
-    if referencing:
-        tables = ", ".join(sorted({r["referencing_table"] for r in referencing}))
+    references = _sys_id_fk_references(tx, table)
+    blocked = _count_fk_rows(tx, references, old_id)
+    if blocked:
         raise AlertError(
-            f"Renumbering is not allowed: {tables} reference(s) {table} "
-            "through a foreign key. (Denied for now — reassigning "
-            "references is not implemented.)"
+            f"Renumbering is not allowed: {', '.join(sorted(blocked))} still "
+            f"reference {table} {old_id}. (Reassigning references is not "
+            "implemented — repoint or remove those rows first.)"
         )
 
     if tx.table(table).find(new_id):
         if not overwrite:
             return "exists"
+        occupied = _count_fk_rows(tx, references, new_id)
+        if occupied:
+            raise AlertError(
+                f"Cannot overwrite {table} {new_id}: {', '.join(sorted(occupied))} "
+                "still reference it."
+            )
         tx.execute(f'DELETE FROM "{table}" WHERE sys_id = %s', (new_id,))
 
     tx.execute(

velocity_python-0.1.104/src/velocity/aws/handlers/mixins/session_control.py

@@ -0,0 +1,277 @@
+"""Single-active-session enforcement for handler-backed apps.
+
+One live login per user: at sign-in the client registers a per-browser
+session key; if another live session exists (and the user row's
+``allow_multiple_sessions`` switch is off) the register answers
+``conflict`` with the other session's ip / browser / times so the UI can
+offer the choice — take over (ends the other session; its next heartbeat
+signs it out) or back out of this sign-in. A periodic client heartbeat
+keeps ``last_seen_at`` fresh and learns when it has been superseded;
+sessions quiet past ``session_stale_minutes`` are expired server-side so a
+crashed browser can't hold the account hostage.
+
+Feature switch — OFF by default (opt-in per app):
+  - class attribute ``single_session_enforcement = True`` turns it on;
+  - the ``SingleSessionEnforcement`` config key overrides per environment
+    (same precedence pattern as ``QueryMaxRows``).
+When off, every action answers as if the session were fine, so a deployed
+frontend gate (velocity-react ``SessionGate``) becomes a no-op without a
+frontend change.
+
+Everything is scoped by the AUTHENTICATED session's email — the payload
+only supplies the caller's own session key, so no action can read or end
+another user's sessions. Sessions live in ``session_table`` (default
+``app_session``; auto-created on first write under unlocked auto-schema —
+locked-schema apps declare it in their ensure_schema). The per-user
+switch column is read from the handler's ``user_table``.
+
+Usage::
+
+    class HttpEventHandler(SessionControlMixin, WebHandler, LambdaHandler):
+        user_table = "app_user"
+        single_session_enforcement = True
+
+Promoted 2026-09-07 from dance.10sp.us (same lifecycle as tenspace's
+app_auth: proven in the app, then centralized).
+"""
+
+import datetime
+
+from velocity.aws import ssm_config
+
+_TRUE = {"1", "true", "yes", "on"}
+_FALSE = {"0", "false", "no", "off"}
+
+
+def _now():
+    return datetime.datetime.now(datetime.timezone.utc)
+
+
+def _iso(value):
+    return value.isoformat() if hasattr(value, "isoformat") else (value or None)
+
+
+def describe_browser(user_agent):
+    """Friendly 'Chrome on Windows' from a raw UA (best-effort, no deps)."""
+    ua = user_agent or ""
+    if "Edg/" in ua:
+        browser = "Edge"
+    elif "OPR/" in ua or "Opera" in ua:
+        browser = "Opera"
+    elif "Chrome/" in ua:
+        browser = "Chrome"
+    elif "Firefox/" in ua:
+        browser = "Firefox"
+    elif "Safari/" in ua:
+        browser = "Safari"
+    else:
+        browser = "Unknown browser"
+    # order matters: Android UAs contain "Linux", iPads report "Mac OS X"
+    if "Windows" in ua:
+        os_name = "Windows"
+    elif "Android" in ua:
+        os_name = "Android"
+    elif "iPhone" in ua or "iPad" in ua:
+        os_name = "iPhone/iPad"
+    elif "Mac OS X" in ua:
+        os_name = "Mac"
+    elif "Linux" in ua:
+        os_name = "Linux"
+    else:
+        os_name = ""
+    return f"{browser} on {os_name}" if os_name else browser
+
+
+def client_info(aws_event):
+    """(ip, user_agent) from the API Gateway event — server-derived, never
+    trusted from the payload."""
+    identity = (aws_event or {}).get("requestContext", {}).get("identity", {})
+    headers = (aws_event or {}).get("headers") or {}
+    ip = identity.get("sourceIp") or ""
+    user_agent = headers.get("User-Agent") or headers.get("user-agent") or ""
+    return ip, user_agent
+
+
+def _describe(row):
+    return {
+        "ip": row.get("ip") or "",
+        "browser": row.get("browser") or row.get("user_agent") or "",
+        "started_at": _iso(row.get("started_at")),
+        "last_seen_at": _iso(row.get("last_seen_at")),
+    }
+
+
+class SessionControlMixin:
+    """register-session / check-session / end-session for the handler.
+
+    Add the three action names to any non-staff/authenticated-only allowlist
+    the handler enforces — every signed-in user needs them.
+    """
+
+    # The app-level switch (see module docstring). The
+    # ``SingleSessionEnforcement`` config key overrides per environment.
+    single_session_enforcement = False
+
+    session_table = "app_session"
+    session_stale_minutes = 10
+    # user-table column holding the per-user opt-out of the single limit
+    session_multi_column = "allow_multiple_sessions"
+
+    # ── switch resolution ────────────────────────────────────────────────
+    def _session_enforcement_enabled(self):
+        raw = None
+        try:
+            raw = ssm_config.getenv("SingleSessionEnforcement", None)
+        except Exception:
+            raw = None
+        if raw is not None:
+            lowered = str(raw).strip().lower()
+            if lowered in _TRUE:
+                return True
+            if lowered in _FALSE:
+                return False
+        return bool(self.single_session_enforcement)
+
+    def _session_user_table(self):
+        return getattr(self, "user_table", None) or "app_user"
+
+    # ── shared internals ─────────────────────────────────────────────────
+    def _session_email(self, context):
+        return ((context.session() or {}).get("email_address") or "").strip().lower()
+
+    def _live_sessions(self, tx, email, now):
+        """Live sessions for the user, expiring quiet ones on the way."""
+        sessions = tx.table(self.session_table)
+        stale_after = datetime.timedelta(minutes=self.session_stale_minutes)
+        live = []
+        for row in sessions.select(where={"email_address": email, "ended_at": None}):
+            seen = row.get("last_seen_at") or row.get("started_at")
+            if seen and (now - seen) > stale_after:
+                sessions.update(
+                    {"ended_at": now, "ended_by": "expired (no heartbeat)"},
+                    where={"sys_id": row["sys_id"]},
+                )
+                continue
+            live.append(row)
+        return live
+
+    def _allow_multiple(self, tx, email):
+        row = next(
+            iter(
+                tx.table(self._session_user_table()).select(
+                    where={"email_address": email}, qty=1
+                )
+            ),
+            None,
+        )
+        return bool(row and row.get(self.session_multi_column))
+
+    # ── actions ──────────────────────────────────────────────────────────
+    def OnActionRegisterSession(self, tx, context):
+        """Claim (or refresh) the caller's session; 'conflict' when someone
+        else is signed in, the user's multi-session switch is off, and this
+        isn't a takeover."""
+        payload = context.payload() or {}
+        email = self._session_email(context)
+        session_key = payload.get("session_key")
+        if not (email and session_key) or not self._session_enforcement_enabled():
+            context.response().set_body({"status": "active"})
+            return
+        ip, user_agent = client_info(self.aws_event)
+        now = _now()
+        sessions = tx.table(self.session_table)
+
+        mine = next(
+            iter(sessions.select(where={"session_key": session_key}, qty=1)), None
+        )
+        others = [
+            r
+            for r in self._live_sessions(tx, email, now)
+            if r.get("session_key") != session_key
+        ]
+        takeover = bool(payload.get("takeover"))
+
+        if others and not takeover and not self._allow_multiple(tx, email):
+            # my previously-live row (a page refresh) doesn't excuse the
+            # conflict: only an ACTIVE claim survives, and mine may have
+            # been superseded
+            if not (mine and mine.get("ended_at") is None):
+                context.response().set_body(
+                    {"status": "conflict", "sessions": [_describe(r) for r in others]}
+                )
+                return
+
+        if takeover:
+            for row in others:
+                sessions.update(
+                    {
+                        "ended_at": now,
+                        "ended_by": (
+                            f"signed out by a new sign-in from {ip or 'unknown ip'}"
+                        ),
+                    },
+                    where={"sys_id": row["sys_id"]},
+                )
+
+        fields = {
+            "email_address": email,
+            "ip": ip,
+            "user_agent": user_agent,
+            "browser": describe_browser(user_agent),
+            "last_seen_at": now,
+        }
+        if mine and mine.get("ended_at") is None:
+            # same login continuing (page refresh) — keep started_at
+            sessions.update(fields, where={"sys_id": mine["sys_id"]})
+        else:
+            # brand-new sign-in, or reclaiming a key that was previously ended
+            fields.update({"started_at": now, "ended_at": None, "ended_by": None})
+            sessions.upsert(fields, {"session_key": session_key})
+        context.response().set_body({"status": "active"})
+
+    def OnActionCheckSession(self, tx, context):
+        """Heartbeat: refresh last_seen_at, or report who superseded us."""
+        payload = context.payload() or {}
+        email = self._session_email(context)
+        session_key = payload.get("session_key")
+        if not (email and session_key) or not self._session_enforcement_enabled():
+            context.response().set_body({"status": "active"})
+            return
+        now = _now()
+        sessions = tx.table(self.session_table)
+        mine = next(
+            iter(
+                sessions.select(
+                    where={"session_key": session_key, "email_address": email}, qty=1
+                )
+            ),
+            None,
+        )
+        if mine and mine.get("ended_at") is None:
+            sessions.update({"last_seen_at": now}, where={"sys_id": mine["sys_id"]})
+            context.response().set_body({"status": "active"})
+            return
+        live = self._live_sessions(tx, email, now)
+        context.response().set_body(
+            {
+                "status": "superseded",
+                "reason": (mine or {}).get("ended_by") or "session ended",
+                "by": _describe(live[0]) if live else None,
+            }
+        )
+
+    def OnActionEndSession(self, tx, context):
+        """Clean sign-out: release the caller's own session claim."""
+        payload = context.payload() or {}
+        email = self._session_email(context)
+        session_key = payload.get("session_key")
+        if email and session_key and self._session_enforcement_enabled():
+            tx.table(self.session_table).update(
+                {"ended_at": _now(), "ended_by": "signed out"},
+                where={
+                    "session_key": session_key,
+                    "email_address": email,
+                    "ended_at": None,
+                },
+            )
+        context.response().set_body({"status": "ended"})

{velocity_python-0.1.102 → velocity_python-0.1.104}/src/velocity/misc/pdf.py

@@ -161,12 +161,23 @@ def _prepend_env_path(name: str, *paths: str) -> None:
     os.environ[name] = os.pathsep.join(merged)
 
 
+def _configure_layer_fonts() -> None:
+    """Point fontconfig at a Lambda layer's /opt/fonts when nothing else has.
+
+    Must run BEFORE the first render in the process: with no usable
+    fontconfig config Pango gets a NULL font and the whole runtime dies with
+    a segmentation fault, not a Python error (found live 2026-09-07 on an
+    AL2023/python3.12 stack whose functions did not set FONTCONFIG_PATH).
+    Harmless off-Lambda — the directory simply doesn't exist."""
+    if os.path.isdir("/opt/fonts") and not os.environ.get("FONTCONFIG_PATH"):
+        os.environ["FONTCONFIG_PATH"] = "/opt/fonts"
+
+
 def _configure_wkhtml_runtime() -> None:
     # Lambda layers put the binary in /opt/bin and its shared libs in /opt/lib.
     _prepend_env_path("PATH", "/opt/bin")
     _prepend_env_path("LD_LIBRARY_PATH", "/opt/lib")
-    if os.path.isdir("/opt/fonts") and not os.environ.get("FONTCONFIG_PATH"):
-        os.environ["FONTCONFIG_PATH"] = "/opt/fonts"
+    _configure_layer_fonts()
 
 
 def _find_wkhtmltopdf() -> str | None:
@@ -351,6 +362,7 @@ class WeasyPrintRenderer(BasePdfRenderer):
                 "that carries its Pango/Cairo libraries and set LD_LIBRARY_PATH=/opt/lib, "
                 f"FONTCONFIG_PATH=/opt/fonts). Root cause: {_weasyprint_import_error!r}"
             )
+        _configure_layer_fonts()
         css_text = page_css(page)
         if extra_css:
             css_text += "\n" + extra_css

{velocity_python-0.1.102 → velocity_python-0.1.104}/src/velocity_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.102
+Version: 0.1.104
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.102 → velocity_python-0.1.104}/src/velocity_python.egg-info/SOURCES.txt

@@ -38,6 +38,7 @@ src/velocity/aws/handlers/sqs_handler.py
 src/velocity/aws/handlers/mixins/__init__.py
 src/velocity/aws/handlers/mixins/data_service.py
 src/velocity/aws/handlers/mixins/job_handler.py
+src/velocity/aws/handlers/mixins/session_control.py
 src/velocity/aws/handlers/mixins/web_handler.py
 src/velocity/aws/tests/__init__.py
 src/velocity/aws/tests/test_amplify_build_policy_size.py
@@ -254,6 +255,7 @@ tests/test_row_cache_staleness.py
 tests/test_schema_migrations.py
 tests/test_security_hardening.py
 tests/test_server_cursor.py
+tests/test_session_control.py
 tests/test_single_autocommit_safety.py
 tests/test_spreadsheet_functions.py
 tests/test_sqlite_backend.py

{velocity_python-0.1.102 → velocity_python-0.1.104}/tests/test_data_service_renumber.py

@@ -1,5 +1,6 @@
-"""renumber_row: chosen-sys_id assignment with FK denial, occupied-target
-confirmation, overwrite semantics, and the sequence bump."""
+"""renumber_row: chosen-sys_id assignment with row-level FK checking (a
+constraint alone no longer denies — actual referencing ROWS do), occupied-
+target confirmation, overwrite semantics, and the sequence bump."""
 
 import pytest
 from unittest.mock import MagicMock
@@ -9,9 +10,13 @@ from velocity.aws.handlers.mixins.data_service import renumber_row
 
 
 class FakeTx:
-    def __init__(self, existing_ids=(5,), fk_tables=()):
+    def __init__(self, existing_ids=(5,), fk=(), refs=None):
+        """``fk``: (referencing_table, referencing_column) pairs — the FK
+        constraints on this table's sys_id. ``refs``: {(table, column):
+        {sys_id: row_count}} — the rows actually referencing each id."""
         self.existing = set(existing_ids)
-        self.fk_tables = list(fk_tables)
+        self.fk = list(fk)
+        self.refs = refs or {}
         self.executed = []
         outer = self
 
@@ -29,8 +34,15 @@ class FakeTx:
         result = MagicMock()
         if "pg_constraint" in sql:
             result.all.return_value = [
-                {"referencing_table": t} for t in self.fk_tables
+                {"referencing_table": t, "referencing_column": c} for t, c in self.fk
             ]
+        elif sql.strip().lower().startswith("select count(*)"):
+            for (t, c), counts in self.refs.items():
+                if f'"{t}"' in sql and f'"{c}"' in sql:
+                    result.scalar.return_value = counts.get(params[0], 0)
+                    break
+            else:
+                result.scalar.return_value = 0
         else:
             result.all.return_value = []
         if sql.strip().upper().startswith("DELETE"):
@@ -54,6 +66,28 @@ def test_simple_renumber_updates_and_bumps_sequence():
     assert 42 in tx.existing and 5 not in tx.existing
 
 
+def test_fk_constraint_without_referencing_rows_is_allowed():
+    # Paul's studios case (2026-09-05): a legacy event.studio_id FK exists,
+    # but no event row points at this studio — the renumber must proceed.
+    tx = FakeTx(existing_ids=(5,), fk=(("event", "studio_id"),))
+    assert renumber_row(tx, "studio", 5, 42) == "renumbered"
+    assert any(s.startswith("select count(*)") for s in sqls(tx))
+    assert 42 in tx.existing
+
+
+def test_actual_referencing_rows_deny_with_counts():
+    tx = FakeTx(
+        existing_ids=(5,),
+        fk=(("event", "studio_id"),),
+        refs={("event", "studio_id"): {5: 3}},
+    )
+    with pytest.raises(AlertError) as err:
+        renumber_row(tx, "studio", 5, 42)
+    assert "event (3 row(s))" in str(err.value)
+    assert "still reference studio 5" in str(err.value)
+    assert not any(s.startswith(("DELETE", "UPDATE")) for s in sqls(tx))
+
+
 def test_occupied_target_reports_exists_without_touching_data():
     tx = FakeTx(existing_ids=(5, 42))
     assert renumber_row(tx, "studio", 5, 42) == "exists"
@@ -61,19 +95,32 @@ def test_occupied_target_reports_exists_without_touching_data():
 
 
 def test_overwrite_deletes_the_occupant_then_renumbers():
-    tx = FakeTx(existing_ids=(5, 42))
+    tx = FakeTx(existing_ids=(5, 42), fk=(("event", "studio_id"),))
     assert renumber_row(tx, "studio", 5, 42, overwrite=True) == "renumbered"
     ordered = [s.split()[0] for s in sqls(tx) if s.split()[0] in ("DELETE", "UPDATE")]
     assert ordered == ["DELETE", "UPDATE"]
     assert tx.existing == {42}
 
 
-def test_foreign_key_reference_denies_the_change():
-    tx = FakeTx(existing_ids=(5,), fk_tables=("event_link_student",))
+def test_overwrite_refused_when_the_occupant_is_referenced():
+    tx = FakeTx(
+        existing_ids=(5, 42),
+        fk=(("event", "studio_id"),),
+        refs={("event", "studio_id"): {42: 2}},
+    )
     with pytest.raises(AlertError) as err:
-        renumber_row(tx, "people", 5, 42)
-    assert "event_link_student" in str(err.value)
-    assert not any(s.startswith(("DELETE", "UPDATE")) for s in sqls(tx))
+        renumber_row(tx, "studio", 5, 42, overwrite=True)
+    assert "Cannot overwrite studio 42" in str(err.value)
+    assert "event (2 row(s))" in str(err.value)
+    assert 42 in tx.existing  # occupant untouched
+
+
+def test_uninspectable_fk_shape_stays_conservatively_denied():
+    # Multi-column FK surfaces referencing_column None — deny rather than guess.
+    tx = FakeTx(existing_ids=(5,), fk=(("event_link", None),))
+    with pytest.raises(AlertError) as err:
+        renumber_row(tx, "studio", 5, 42)
+    assert "cannot inspect" in str(err.value)
 
 
 @pytest.mark.parametrize(

{velocity_python-0.1.102 → velocity_python-0.1.104}/tests/test_pdf.py

@@ -382,3 +382,28 @@ class TestWeasyPrintReal:
     def test_real_render_produces_a_pdf(self):
         out = html_to_pdf("<h1>hello</h1>", engine="weasyprint", margin="0in")
         assert out.startswith(b"%PDF-")
+
+
+class TestLayerFontConfiguration:
+    """_configure_layer_fonts: points fontconfig at /opt/fonts before a render
+    so Pango can never come up font-less on Lambda (a NULL font segfaults the
+    runtime — found live 2026-09-07)."""
+
+    def test_sets_fontconfig_path_when_layer_fonts_exist(self, monkeypatch):
+        monkeypatch.delenv("FONTCONFIG_PATH", raising=False)
+        monkeypatch.setattr(
+            pdfmod.os.path, "isdir", lambda p: p == "/opt/fonts"
+        )
+        pdfmod._configure_layer_fonts()
+        assert pdfmod.os.environ["FONTCONFIG_PATH"] == "/opt/fonts"
+
+    def test_never_overrides_an_explicit_setting_or_missing_dir(self, monkeypatch):
+        monkeypatch.setenv("FONTCONFIG_PATH", "/custom/fonts")
+        monkeypatch.setattr(pdfmod.os.path, "isdir", lambda p: True)
+        pdfmod._configure_layer_fonts()
+        assert pdfmod.os.environ["FONTCONFIG_PATH"] == "/custom/fonts"
+
+        monkeypatch.delenv("FONTCONFIG_PATH", raising=False)
+        monkeypatch.setattr(pdfmod.os.path, "isdir", lambda p: False)
+        pdfmod._configure_layer_fonts()
+        assert "FONTCONFIG_PATH" not in pdfmod.os.environ