velocity-python 0.1.108__tar.gz → 0.1.110__tar.gz

{velocity_python-0.1.108/src/velocity_python.egg-info → velocity_python-0.1.110}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.108
+Version: 0.1.110
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -251,6 +251,7 @@ Full documentation is included in the `docs/` directory of the source distributi
 | Async Support | `docs/async.md` | AsyncTransaction, AsyncTable, AsyncResult, parallel queries with gather() |
 | Configuration Reference | `docs/configuration.md` | All environment variables, engine options, and connection settings |
 | AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions, async jobs (JobHandler + job result stores) |
+| Cross-database Mirroring | `docs/mirroring.md` | Keep a table identical in two databases (demo ↔ production) by natural key; rwx hooks, FK translation, reconcile |
 | NoSQL Adapters | `docs/nosql.md` | Redis, DynamoDB, MongoDB, Elasticsearch, Cassandra, Couchbase behind one capability-honest contract |
 | Payment Processing | `docs/payment.md` | Stripe and Braintree adapters, payment lifecycle |
 | Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing and SMTP sending |

{velocity_python-0.1.108 → velocity_python-0.1.110}/README.md

@@ -157,6 +157,7 @@ Full documentation is included in the `docs/` directory of the source distributi
 | Async Support | `docs/async.md` | AsyncTransaction, AsyncTable, AsyncResult, parallel queries with gather() |
 | Configuration Reference | `docs/configuration.md` | All environment variables, engine options, and connection settings |
 | AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions, async jobs (JobHandler + job result stores) |
+| Cross-database Mirroring | `docs/mirroring.md` | Keep a table identical in two databases (demo ↔ production) by natural key; rwx hooks, FK translation, reconcile |
 | NoSQL Adapters | `docs/nosql.md` | Redis, DynamoDB, MongoDB, Elasticsearch, Cassandra, Couchbase behind one capability-honest contract |
 | Payment Processing | `docs/payment.md` | Stripe and Braintree adapters, payment lifecycle |
 | Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing and SMTP sending |

{velocity_python-0.1.108 → velocity_python-0.1.110}/pyproject.toml

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

{velocity_python-0.1.108 → velocity_python-0.1.110}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.108"
+__version__ = version = "0.1.110"
 
 import importlib as _importlib
 

{velocity_python-0.1.108 → velocity_python-0.1.110}/src/velocity/aws/capabilities/security.py

@@ -27,9 +27,9 @@ from __future__ import annotations
 import datetime
 import ipaddress
 import logging
-import time
 
 from velocity.aws import feature_flags
+from velocity.cache import memo, read_cache
 
 from .base import (
     CIDR_LIST,
@@ -62,11 +62,10 @@ KNOBS = {
     "security_events_days": "90",
 }
 
-_cache: dict = {}
-
-
 def clear_cache():
-    _cache.clear()
+    """Forget the cached site row AND the shared flags row (tests)."""
+    read_cache.invalidate(SITE_TABLE)
+    feature_flags.clear_cache()
 
 
 # ── request facts ───────────────────────────────────────────────────────
@@ -172,13 +171,9 @@ def check_rate(tx, bucket, *, limit, now, table=RATE_TABLE):
 
 
 def _cached(key, loader, *, now=None):
-    now = now or time.monotonic()
-    hit = _cache.get(key)
-    if hit and hit[0] > now:
-        return hit[1]
-    value = loader()
-    _cache[key] = (now + CACHE_TTL_SECONDS, value)
-    return value
+    """The process read cache (velocity.cache), tagged with the site table
+    so provisioning's own writes to it in this process drop the entry."""
+    return memo(("security",) + tuple(key), loader, CACHE_TTL_SECONDS, tables=(SITE_TABLE,), now=now)
 
 
 def _site_row(tx):
@@ -201,7 +196,10 @@ def _site_row(tx):
 
 
 def _flags(tx):
-    return _cached(("flags",), lambda: feature_flags.get(tx))
+    """The stage's flags row from velocity's container cache — shared with
+    the handler context and session control, so the guards add no read of
+    their own to a request."""
+    return feature_flags.get_cached(tx)
 
 
 def _row_config(row) -> dict:

{velocity_python-0.1.108 → velocity_python-0.1.110}/src/velocity/aws/feature_flags.py

@@ -23,19 +23,30 @@ 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.)
+
+The mirroring itself is the generic :mod:`velocity.aws.mirror` (any table,
+any natural key, optional foreign-key translation); this module is that
+mechanism applied to the flags table, keyed by ``applied_system``.
 """
 
 from __future__ import annotations
 
 import logging
 
+from velocity.aws import mirror as _mirror
+from velocity.cache import memo, read_cache
+
 log = logging.getLogger(__name__)
 
 SYSTEM_COLUMN = "applied_system"
 DEFAULT_TABLE = "sys_feature_flags"
-ALTERNATE_DB_CONFIG_KEY = "DBAlternate"
+ALTERNATE_DB_CONFIG_KEY = _mirror.ALTERNATE_DB_CONFIG_KEY
+# how long a warm container may reuse the flags row before re-reading it
+CACHE_SECONDS_CONFIG_KEY = "FeatureFlagCacheSeconds"
+DEFAULT_CACHE_SECONDS = 60
 
-_alternate_engines: dict = {}
+_alternate_engines = _mirror._alternate_engines
+_cache_seconds: float | None = None
 
 
 def current_system(default: str | None = None) -> str | None:
@@ -68,20 +79,74 @@ def get(
     return dict(row)
 
 
+def cache_seconds() -> float:
+    """Seconds a warm container may reuse the flags row: the
+    ``FeatureFlagCacheSeconds`` config key, default 60; ``0`` reads the row
+    on every call. Resolved once per container."""
+    global _cache_seconds
+    if _cache_seconds is None:
+        raw = None
+        try:
+            from velocity.aws import ssm_config
+
+            raw = ssm_config.getenv(CACHE_SECONDS_CONFIG_KEY, None)
+        except Exception:
+            raw = None
+        try:
+            _cache_seconds = (
+                float(raw) if raw not in (None, "") else float(DEFAULT_CACHE_SECONDS)
+            )
+        except (TypeError, ValueError):
+            _cache_seconds = float(DEFAULT_CACHE_SECONDS)
+    return _cache_seconds
+
+
+def clear_cache(table: str = DEFAULT_TABLE) -> None:
+    """Forget cached rows (after a local flags write; tests)."""
+    global _cache_seconds
+    read_cache.invalidate(table)
+    _cache_seconds = None
+
+
+def get_cached(
+    tx, system: str | None = None, *, table: str = DEFAULT_TABLE, now: float | None = None
+) -> dict:
+    """:func:`get` through the process read cache (:mod:`velocity.cache`)
+    — the hot-path reader.
+
+    The flags row is ONE row per stage, and every reader in a request
+    (the handler context, the security guards, session control, any
+    capability knob) wants the same one: this makes it at most one read per
+    :func:`cache_seconds` per container, however many readers there are.
+    Tagged with the table, so a flags write through the table API in this
+    process (the mirror hook, a save) drops it at once; the other
+    environment sees the change within the TTL.
+    """
+    system = system if system is not None else current_system()
+    row = memo(
+        ("feature_flags", table, system),
+        lambda: dict(get(tx, system, table=table)),
+        cache_seconds(),
+        tables=(table,),
+        now=now,
+    )
+    return dict(row)
+
+
 def load(tx, loader=None) -> dict:
     """The request-time flag source used by handler contexts.
 
     An injected ``loader(tx)`` wins (apps that resolve flags their own way);
-    otherwise :func:`get` — velocity's stage-scoped reader — is the source,
-    never raising into the request. The legacy CaringCent
-    ``support.app.helpers`` loader remains only as a last resort when the
-    velocity reader finds no row (it raises on a missing row, which those
-    apps rely on); absent that package the answer is ``{}``.
+    otherwise :func:`get_cached` — velocity's stage-scoped reader behind the
+    container cache — is the source, never raising into the request. The
+    legacy CaringCent ``support.app.helpers`` loader remains only as a last
+    resort when the velocity reader finds no row (it raises on a missing
+    row, which those apps rely on); absent that package the answer is ``{}``.
     """
     if callable(loader):
         return loader(tx)
     try:
-        flags = get(tx)
+        flags = get_cached(tx)
     except Exception:
         flags = {}
     if flags:
@@ -101,28 +166,13 @@ def _legacy_support_loader(tx):
     return helpers.get_feature_flags(tx)
 
 
-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_")}
+_without_sys = _mirror.business_columns
+_toast = _mirror.toast
 
 
 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]
+    """Engine for the alternate database — see :func:`velocity.aws.mirror.alternate_engine`."""
+    return _mirror.alternate_engine(alternate_db)
 
 
 def mirror_row(
@@ -133,14 +183,9 @@ def mirror_row(
     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
+    pk = _mirror.mirror_row(row, table=table, key=(SYSTEM_COLUMN,), engine=engine)
+    return pk[SYSTEM_COLUMN] if pk else None
 
 
 def reconcile(
@@ -149,27 +194,11 @@ def reconcile(
     """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)
+    result = _mirror.reconcile(tx, table=table, key=(SYSTEM_COLUMN,), engine=engine)
+    return {
+        "synced": [pk[SYSTEM_COLUMN] for pk in result["synced"]],
+        "skipped": result["skipped"],
+    }
 
 
 def make_mirror_hook(
@@ -187,6 +216,7 @@ def make_mirror_hook(
 
     def hook(tx, table_name, sys_id, row, context):
         del tx, table_name, sys_id
+        clear_cache()  # the row just changed here: this container re-reads it
         try:
             key = mirror_row(row, alternate_db=alternate_db, table=table)
             if notify and key:

{velocity_python-0.1.108 → velocity_python-0.1.110}/src/velocity/aws/handlers/context.py

@@ -17,6 +17,7 @@ from velocity.aws.ssm_config import get_project_name as config_get_project_name
 from velocity.aws.ssm_config import get_region as config_get_region
 from velocity.aws.ssm_config import get_stage as config_get_stage
 from velocity.logging import get_logger
+from velocity.cache import memo
 
 engine = velocity.db.postgres.initialize()
 
@@ -81,6 +82,38 @@ def _get_controls_vars() -> dict:
     }
 
 
+# ── the signed-in user, cached per container ─────────────────────────────
+USER_CACHE_CONFIG_KEY = "UserCacheSeconds"
+DEFAULT_USER_CACHE_SECONDS = 60
+_user_cache_seconds = None
+
+
+def user_cache_seconds() -> float:
+    """Seconds a warm container may reuse a signed-in user's Cognito record and
+    user-table row: the ``UserCacheSeconds`` config key, default 60. A disabled
+    or deleted user keeps that container's access until it expires — accepted
+    policy (Paul, 2026-09-13). ``0`` looks the user up on every request."""
+    global _user_cache_seconds
+    if _user_cache_seconds is None:
+        raw = None
+        try:
+            raw = config_getenv(USER_CACHE_CONFIG_KEY, None)
+        except Exception:
+            raw = None
+        try:
+            _user_cache_seconds = (
+                float(raw) if raw not in (None, "") else float(DEFAULT_USER_CACHE_SECONDS)
+            )
+        except (TypeError, ValueError):
+            _user_cache_seconds = float(DEFAULT_USER_CACHE_SECONDS)
+    return _user_cache_seconds
+
+
+def clear_user_cache_config() -> None:
+    global _user_cache_seconds
+    _user_cache_seconds = None
+
+
 @engine.transaction
 class Context:
 
@@ -807,63 +840,73 @@ class Context:
                 "cannot resolve a Cognito user"
             ) from None
 
-        try:
-            self.perf.start("cognito admin_get_user")
-            response = cognito_client.admin_get_user(
-                UserPoolId=user_pool_id,
-                Username=user_sub,
-            )
-            self.perf.log("cognito admin_get_user")
-            resolved_username = response.get("Username")
-        except cognito_client.exceptions.UserNotFoundException:
+        # one Cognito round trip per user per UserCacheSeconds per container
+        # (velocity.cache); a lookup that fails is never cached
+        def resolve():
             try:
-                self.perf.start("cognito list_users")
-                list_response = cognito_client.list_users(
+                self.perf.start("cognito admin_get_user")
+                response = cognito_client.admin_get_user(
                     UserPoolId=user_pool_id,
-                    Filter=f'sub = "{user_sub}"',
-                    Limit=1,
+                    Username=user_sub,
                 )
-                self.perf.log("cognito list_users")
+                self.perf.log("cognito admin_get_user")
+                resolved_username = response.get("Username")
+            except cognito_client.exceptions.UserNotFoundException:
+                try:
+                    self.perf.start("cognito list_users")
+                    list_response = cognito_client.list_users(
+                        UserPoolId=user_pool_id,
+                        Filter=f'sub = "{user_sub}"',
+                        Limit=1,
+                    )
+                    self.perf.log("cognito list_users")
+                except ClientError as exc:
+                    message = exc.response.get("Error", {}).get("Message", "Unknown error")
+                    raise AlertError(
+                        f"Failed to search Cognito user by sub: {message}"
+                    ) from None
+
+                users = list_response.get("Users", [])
+                if not users:
+                    raise AlertError("Cognito user not found") from None
+
+                user = users[0]
+                response = {
+                    "Username": user.get("Username"),
+                    "UserAttributes": user.get("Attributes", []),
+                    "Enabled": user.get("Enabled"),
+                    "UserStatus": user.get("UserStatus"),
+                    "UserCreateDate": user.get("UserCreateDate"),
+                    "UserLastModifiedDate": user.get("UserLastModifiedDate"),
+                }
+                resolved_username = response.get("Username")
             except ClientError as exc:
                 message = exc.response.get("Error", {}).get("Message", "Unknown error")
-                raise AlertError(
-                    f"Failed to search Cognito user by sub: {message}"
-                ) from None
-
-            users = list_response.get("Users", [])
-            if not users:
-                raise AlertError("Cognito user not found") from None
-
-            user = users[0]
-            response = {
-                "Username": user.get("Username"),
-                "UserAttributes": user.get("Attributes", []),
-                "Enabled": user.get("Enabled"),
-                "UserStatus": user.get("UserStatus"),
-                "UserCreateDate": user.get("UserCreateDate"),
-                "UserLastModifiedDate": user.get("UserLastModifiedDate"),
+                raise AlertError(f"Failed to retrieve Cognito user: {message}") from None
+
+            attributes = {
+                attr["Name"]: attr.get("Value")
+                for attr in response.get("UserAttributes", [])
             }
-            resolved_username = response.get("Username")
-        except ClientError as exc:
-            message = exc.response.get("Error", {}).get("Message", "Unknown error")
-            raise AlertError(f"Failed to retrieve Cognito user: {message}") from None
-
-        attributes = {
-            attr["Name"]: attr.get("Value")
-            for attr in response.get("UserAttributes", [])
-        }
 
-        user = {
-            "username": resolved_username or user_sub,
-            "email": attributes.get("email"),
-            "attributes": attributes,
-            "enabled": response.get("Enabled"),
-            "user_status": response.get("UserStatus"),
-            "sub": attributes.get("sub", user_sub),
-        }
+            user = {
+                "username": resolved_username or user_sub,
+                "email": attributes.get("email"),
+                "attributes": attributes,
+                "enabled": response.get("Enabled"),
+                "user_status": response.get("UserStatus"),
+                "sub": attributes.get("sub", user_sub),
+            }
 
-        self.perf.log("get_cognito_user total")
+            return user
 
+        user = memo(
+            ("cognito", user_pool_id, user_sub),
+            resolve,
+            user_cache_seconds(),
+            cache_none=False,
+        )
+        self.perf.log("get_cognito_user total")
         return user
 
     def get_cognito_user_optional(self, aws_event):

{velocity_python-0.1.108 → velocity_python-0.1.110}/src/velocity/aws/handlers/lambda_handler.py

@@ -161,15 +161,13 @@ class LambdaHandler(BaseHandler):
                 )
 
             context.perf.start("user lookup")
-            row = tx.table(self.user_table).find(
-                {"email_address": session.get("email_address")}
-            )
+            user = self._cached_user(tx, session.get("email_address"))
             context.perf.log("user lookup")
-            if not row:
+            if not user:
                 raise Exception(
                     "A valid user with permission is required to access this function [DB]"
                 )
-            self.current_user = row.to_dict()
+            self.current_user = user
 
         temp = copy.deepcopy(context.postdata() or {})
         payload = temp.get("payload")
@@ -181,6 +179,29 @@ class LambdaHandler(BaseHandler):
             extra={"payload": pprint.pformat(temp)},
         )
 
+    def _cached_user(self, tx, email_address):
+        """The user-table row for the signed-in user as a dict, through the
+        process read cache (velocity.cache) for ``UserCacheSeconds``: one
+        query per TTL per container instead of one per request. A miss is
+        never cached, so a user created a moment ago signs in at once; a
+        write to the user table in this process drops the entry."""
+        from velocity.cache import memo
+
+        from velocity.aws.handlers.context import user_cache_seconds
+
+        def load():
+            row = tx.table(self.user_table).find({"email_address": email_address})
+            return row.to_dict() if row else None
+
+        user = memo(
+            ("user", self.user_table, email_address),
+            load,
+            user_cache_seconds(),
+            tables=(self.user_table,),
+            cache_none=False,
+        )
+        return dict(user) if user else None
+
     def afterAction(self, tx, context):
         self._enhanced_after_action(tx, context)
         logger.debug("starting LamdaHandler.afterAction")

{velocity_python-0.1.108 → velocity_python-0.1.110}/src/velocity/aws/handlers/mixins/data_service.py

@@ -20,6 +20,10 @@ from velocity.aws.handlers.exceptions import AlertError
 from velocity.db.exceptions import DbDataIntegrityError
 from velocity.misc import export
 
+# a table's column list changes only on deploy (schema sync) or a lazy ALTER
+# in this process (which drops the entry): reuse it across requests
+SCHEMA_CACHE_SECONDS = 300
+
 logger = logging.getLogger(__name__)
 
 # Postgres FK-violation text, e.g.:
@@ -522,7 +526,9 @@ class DataServiceMixin:
                     order_dir = parts[1].lower()
 
             if not order_col:
-                available = [c for c in tx.table(obj).sys_columns()]
+                available = [
+                    c for c in tx.table(obj).sys_columns(cache_ttl=SCHEMA_CACHE_SECONDS)
+                ]
                 lowered = {c.lower(): c for c in available}
                 order_col = lowered.get("sys_id") or lowered.get("sys_created")
                 if not order_col and available:
@@ -551,7 +557,9 @@ class DataServiceMixin:
         _inject_row_number_expression(params)
         requested_cols = _extract_requested_column_names(params.get("columns"))
         if requested_cols:
-            available_cols = {c.lower() for c in tx.table(obj).sys_columns()}
+            available_cols = {
+                c.lower() for c in tx.table(obj).sys_columns(cache_ttl=SCHEMA_CACHE_SECONDS)
+            }
             missing = sorted(
                 {c for c in requested_cols if c.lower() not in available_cols},
                 key=lambda v: v.lower(),

{velocity_python-0.1.108 → velocity_python-0.1.110}/src/velocity/aws/handlers/mixins/session_control.py

@@ -120,14 +120,15 @@ class SessionControlMixin:
     # ── switch resolution ────────────────────────────────────────────────
     def _session_flags(self, tx):
         """The stage's feature flags (the `single_session` capability's
-        knobs) — {} when there is no tx or no flags table, so sessions never
-        depend on the flag row existing."""
+        knobs) from velocity's container cache — no read of their own per
+        heartbeat; {} when there is no tx or no flags table, so sessions
+        never depend on the flag row existing."""
         if tx is None:
             return {}
         try:
             from velocity.aws import feature_flags
 
-            return feature_flags.get(tx) or {}
+            return feature_flags.get_cached(tx) or {}
         except Exception:
             return {}