velocity-python 0.1.103__tar.gz → 0.1.105__tar.gz

{velocity_python-0.1.103 → velocity_python-0.1.105}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.103
+Version: 0.1.105
 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.103 → velocity_python-0.1.105}/pyproject.toml

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

{velocity_python-0.1.103 → velocity_python-0.1.105}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.103"
+__version__ = version = "0.1.105"
 
 import importlib as _importlib
 

velocity_python-0.1.105/src/velocity/aws/feature_flags.py

@@ -0,0 +1,159 @@
+"""Environment-scoped feature flags with cross-database mirroring.
+
+Generalises a pattern proven in production (CaringCent BackOffice): a
+``sys_feature_flags`` table that holds **one row per system**, keyed by an
+``applied_system`` column, where every copy of the database carries every
+system's row. Two behaviours follow:
+
+* **Reads are scoped to the current system.** A bare ``find({})`` is wrong the
+  moment a second system's row exists — it returns an arbitrary one. Callers go
+  through :func:`get`, which selects the row for :func:`current_system`.
+* **Writes mirror to the alternate database.** demo and production are separate
+  databases on the same instance; a flag saved in either is copied to the other
+  (matched by ``applied_system``, never ``sys_id`` — row ids differ between
+  databases) so the two converge no matter where the edit happened, and a
+  demo refresh preserves the demo row. :func:`mirror_row` does one row (the
+  real-time hook); :func:`reconcile` does all rows (the catch-up after the
+  alternate was unreachable, or a fresh environment).
+
+velocity owns only the **mechanism**. The flag columns and what they mean stay
+in each app's schema and code — this module never names a business flag. The
+row key is the runtime **stage** (``demo`` / ``production``), so every database
+carries one row per stage and each environment reads its own; the alternate
+database name comes from config (:data:`ALTERNATE_DB_CONFIG_KEY`). (An app that
+one day consolidates several systems into one database can widen the key then;
+today the stage is the whole identity.)
+"""
+
+from __future__ import annotations
+
+import logging
+
+log = logging.getLogger(__name__)
+
+SYSTEM_COLUMN = "applied_system"
+DEFAULT_TABLE = "sys_feature_flags"
+ALTERNATE_DB_CONFIG_KEY = "DBAlternate"
+
+_alternate_engines: dict = {}
+
+
+def current_system(default: str | None = None) -> str | None:
+    """The ``applied_system`` key for the running environment — the runtime
+    stage (``demo`` / ``production``). Every database carries one row per stage;
+    this selects the running one.
+    """
+    from velocity.aws import ssm_config
+
+    return (ssm_config.get_stage() or "").strip() or default
+
+
+def get(tx, system: str | None = None, *, table: str = DEFAULT_TABLE,
+        raise_on_missing: bool = False) -> dict:
+    """The feature-flag row for ``system`` (defaults to :func:`current_system`).
+
+    Returns a plain dict; ``{}`` when no row matches unless ``raise_on_missing``.
+    """
+    system = system if system is not None else current_system()
+    row = tx.table(table).find({SYSTEM_COLUMN: system})
+    if not row:
+        if raise_on_missing:
+            raise KeyError(f"no {table} row for {SYSTEM_COLUMN}={system!r}")
+        return {}
+    return dict(row)
+
+
+def _without_sys(row) -> dict:
+    """A row's business columns — the ``sys_*`` bookkeeping never crosses over."""
+    return {k: v for k, v in dict(row).items() if not str(k).startswith("sys_")}
+
+
+def alternate_engine(alternate_db: str | None = None):
+    """Engine for the alternate database — same instance, other ``database``.
+
+    Host/port/user/password are inherited from the running config, so no
+    separate credentials are needed; only the database name changes. Cached per
+    database name so repeated mirrors in one process reuse the connection.
+    """
+    from velocity.aws import ssm_config
+    from velocity.db.servers import postgres
+
+    if alternate_db is None:
+        alternate_db = ssm_config.getenv(ALTERNATE_DB_CONFIG_KEY, raise_on_missing=True)
+    if alternate_db not in _alternate_engines:
+        _alternate_engines[alternate_db] = postgres.initialize({"database": alternate_db})
+    return _alternate_engines[alternate_db]
+
+
+def mirror_row(row, *, alternate_db: str | None = None, engine=None,
+               table: str = DEFAULT_TABLE) -> str | None:
+    """Upsert one flags row into the alternate database by ``applied_system``.
+
+    Returns the mirrored key, or ``None`` when the row has no system key (a
+    keyless row is skipped, never mirrored to an arbitrary target).
+    """
+    data = _without_sys(row)
+    key = data.get(SYSTEM_COLUMN)
+    if not key:
+        return None
+    engine = engine or alternate_engine(alternate_db)
+    with engine.transaction() as alt:
+        alt.table(table).merge(data, pk={SYSTEM_COLUMN: key})
+    return key
+
+
+def reconcile(tx, *, alternate_db: str | None = None, engine=None,
+              table: str = DEFAULT_TABLE) -> dict:
+    """Mirror every flags row into the alternate database. Catch-up companion of
+    :func:`mirror_row`. Returns ``{"synced": [...], "skipped": [...]}``."""
+    engine = engine or alternate_engine(alternate_db)
+    synced: list = []
+    skipped: list = []
+    rows = list(tx.table(table).select())
+    with engine.transaction() as alt:
+        for row in rows:
+            data = _without_sys(row)
+            key = data.get(SYSTEM_COLUMN)
+            if not key:
+                skipped.append(dict(row).get("sys_id"))
+                continue
+            alt.table(table).merge(data, pk={SYSTEM_COLUMN: key})
+            synced.append(key)
+    return {"synced": synced, "skipped": skipped}
+
+
+def _toast(context, message: str, level: str) -> None:
+    """Best-effort operator toast; a context without one is fine (a queue run)."""
+    response = getattr(context, "response", None)
+    toast = getattr(response() if callable(response) else None, "toast", None)
+    if callable(toast):
+        toast(message, level)
+
+
+def make_mirror_hook(*, alternate_db: str | None = None,
+                     table: str = DEFAULT_TABLE, notify: bool = True):
+    """An RWX ``after_new`` / ``after_write`` callable that mirrors the saved
+    row to the alternate database.
+
+    This is how the sync stays in ONE place: the app's ``rwx/<table>.py`` is a
+    two-line re-export (``after_new = after_write = make_mirror_hook()``) — the
+    logic lives here in velocity, not copied per repo. Warn-and-continue: a flag
+    save is never blocked by the alternate database being unreachable; the
+    :func:`reconcile` action (also here) is the catch-up.
+    """
+
+    def hook(tx, table_name, sys_id, row, context):
+        del tx, table_name, sys_id
+        try:
+            key = mirror_row(row, alternate_db=alternate_db, table=table)
+            if notify and key:
+                _toast(context, f"Feature flags for '{key}' mirrored to the "
+                       "alternate database.", "success")
+        except Exception as exc:  # warn-and-continue — never block the save
+            log.warning("feature-flag mirror to alternate DB failed", exc_info=True)
+            if notify:
+                _toast(context, "Flag change saved HERE but NOT mirrored to the "
+                       f"alternate database ({exc}). Run the reconcile once it "
+                       "is reachable.", "warning")
+
+    return hook

{velocity_python-0.1.103 → velocity_python-0.1.105}/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.105/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.103 → velocity_python-0.1.105}/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.103 → velocity_python-0.1.105}/src/velocity_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.103
+Version: 0.1.105
 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.103 → velocity_python-0.1.105}/src/velocity_python.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ src/velocity/aws/amplify_build.py
 src/velocity/aws/blobs.py
 src/velocity/aws/dirty_pipeline.py
 src/velocity/aws/email.py
+src/velocity/aws/feature_flags.py
 src/velocity/aws/job_results.py
 src/velocity/aws/s3.py
 src/velocity/aws/sms.py
@@ -38,6 +39,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
@@ -212,6 +214,7 @@ tests/test_delete_hook_fk_blocked.py
 tests/test_dirty_pipeline_fast_path.py
 tests/test_email_processing.py
 tests/test_enqueue_send_failures.py
+tests/test_feature_flags.py
 tests/test_get_cognito_user_provider.py
 tests/test_http_handler_rollback.py
 tests/test_iconv_money_to_cents.py
@@ -254,6 +257,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