velocity-python 0.1.109__tar.gz → 0.1.111__tar.gz

{velocity_python-0.1.109/src/velocity_python.egg-info → velocity_python-0.1.111}/PKG-INFO

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

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

{velocity_python-0.1.109 → velocity_python-0.1.111}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.109"
+__version__ = version = "0.1.111"
 
 import importlib as _importlib
 

{velocity_python-0.1.109 → velocity_python-0.1.111}/src/velocity/aws/capabilities/base.py

@@ -55,7 +55,16 @@ TEXT = "text"
 BOOLEAN = "boolean"
 CHOICE = "choice"  # one of `options`
 LIST = "list"  # free strings
-POLICY_KINDS = (CIDR_LIST, COUNTRY_LIST, TABLE_DAYS, NUMBER, TEXT, BOOLEAN, CHOICE, LIST)
+POLICY_KINDS = (
+    CIDR_LIST,
+    COUNTRY_LIST,
+    TABLE_DAYS,
+    NUMBER,
+    TEXT,
+    BOOLEAN,
+    CHOICE,
+    LIST,
+)
 
 IDENTIFIER = re.compile(r"^[a-z_][a-z0-9_]*$")
 COUNTRY_CODE = re.compile(r"^[A-Z]{2}$")
@@ -145,7 +154,9 @@ def describe(cap) -> dict:
 def catalog() -> list:
     """Every registered capability, described, ordered by label — the
     pick-list an admin UI shows."""
-    return sorted((describe(cap) for cap in REGISTRY.values()), key=lambda d: d["label"])
+    return sorted(
+        (describe(cap) for cap in REGISTRY.values()), key=lambda d: d["label"]
+    )
 
 
 def load_config(raw) -> dict:
@@ -232,8 +243,7 @@ def validate_policy(name, config) -> list:
         if value in (None, "", [], {}):
             continue
         problems.extend(
-            f"{field['label']}: {problem}"
-            for problem in _check_field(field, value)
+            f"{field['label']}: {problem}" for problem in _check_field(field, value)
         )
     return problems
 

{velocity_python-0.1.109 → velocity_python-0.1.111}/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,12 +62,10 @@ KNOBS = {
     "security_events_days": "90",
 }
 
-_cache: dict = {}
-
 
 def clear_cache():
     """Forget the cached site row AND the shared flags row (tests)."""
-    _cache.clear()
+    read_cache.invalidate(SITE_TABLE)
     feature_flags.clear_cache()
 
 
@@ -174,13 +172,15 @@ 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):

{velocity_python-0.1.109 → velocity_python-0.1.111}/src/velocity/aws/feature_flags.py

@@ -32,9 +32,9 @@ mechanism applied to the flags table, keyed by ``applied_system``.
 from __future__ import annotations
 
 import logging
-import time
 
 from velocity.aws import mirror as _mirror
+from velocity.cache import memo, read_cache
 
 log = logging.getLogger(__name__)
 
@@ -46,7 +46,6 @@ CACHE_SECONDS_CONFIG_KEY = "FeatureFlagCacheSeconds"
 DEFAULT_CACHE_SECONDS = 60
 
 _alternate_engines = _mirror._alternate_engines
-_cache: dict = {}  # (system, table) -> (expires_at, row)
 _cache_seconds: float | None = None
 
 
@@ -102,37 +101,39 @@ def cache_seconds() -> float:
     return _cache_seconds
 
 
-def clear_cache() -> None:
+def clear_cache(table: str = DEFAULT_TABLE) -> None:
     """Forget cached rows (after a local flags write; tests)."""
     global _cache_seconds
-    _cache.clear()
+    read_cache.invalidate(table)
     _cache_seconds = None
 
 
 def get_cached(
-    tx, system: str | None = None, *, table: str = DEFAULT_TABLE, now: float | None = None
+    tx,
+    system: str | None = None,
+    *,
+    table: str = DEFAULT_TABLE,
+    now: float | None = None,
 ) -> dict:
-    """:func:`get` behind a per-container TTL cache — the hot-path reader.
+    """: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. A
-    flag saved through the mirror hook clears the local cache, so the
-    environment that made the change sees it at once; the other environment
-    sees it within the TTL.
+    :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()
-    ttl = cache_seconds()
-    if ttl <= 0:
-        return get(tx, system, table=table)
-    now = time.monotonic() if now is None else now
-    key = (system, table)
-    hit = _cache.get(key)
-    if hit and hit[0] > now:
-        return dict(hit[1])
-    row = get(tx, system, table=table)
-    _cache[key] = (now + ttl, dict(row))
+    row = memo(
+        ("feature_flags", table, system),
+        lambda: dict(get(tx, system, table=table)),
+        cache_seconds(),
+        tables=(table,),
+        now=now,
+    )
     return dict(row)
 
 

{velocity_python-0.1.109 → velocity_python-0.1.111}/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,40 @@ 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 +842,77 @@ 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}"
+                    f"Failed to retrieve Cognito user: {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"),
+            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.109 → velocity_python-0.1.111}/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.109 → velocity_python-0.1.111}/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,10 @@ 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.109 → velocity_python-0.1.111}/src/velocity/aws/mirror.py

@@ -176,7 +176,9 @@ def _run(operation, context, what, verbs, notify):
     except MirrorSkip as skip:
         log.warning("%s not %s the alternate database: %s", what, done, skip)
         if notify:
-            toast(context, f"{what} {undone} the alternate database: {skip}.", "warning")
+            toast(
+                context, f"{what} {undone} the alternate database: {skip}.", "warning"
+            )
         return None
     except Exception as exc:  # never block the local write
         log.warning("%s: mirror to the alternate database failed", what, exc_info=True)

velocity_python-0.1.111/src/velocity/cache.py

@@ -0,0 +1,188 @@
+"""Process-level read cache: reads that may be reused across requests.
+
+velocity's transaction cache (``select(..., cache=True)``) lives and dies
+with one transaction. This store outlives requests on a warm Lambda
+container (or any long-lived process), so a read that is the same for
+every request — a feature-flag row, a capability row, the signed-in user,
+a table's column list, a Cognito lookup — costs one round trip per TTL
+instead of one per request. One store, one policy, no per-module dicts.
+
+Three ways in:
+
+* table reads — ``tx.table(t).find(where, cache_ttl=60)``,
+  ``exists(cache_ttl=60)``, ``sys_columns(cache_ttl=300)``,
+  ``select(..., cache_ttl=60)`` — keyed by database + SQL + params;
+* :func:`memo` — any loader (an API call, a composite of reads), tagged
+  with the tables it depends on;
+* :data:`read_cache` — explicit ``invalidate`` / ``clear`` / ``stats``.
+
+**Invalidation.** A write through the table API (insert / update / delete /
+merge / upsert / truncate) or DDL on table *T* in this process drops every
+entry tagged *T* at once; a raw ``tx.execute`` write is classified and does
+the same. Other processes see the change when their TTL expires — that
+bounded staleness is the contract a caller accepts by naming a TTL.
+``VELOCITY_READ_CACHE=0`` disables the store everywhere (tests, debugging).
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from collections import OrderedDict
+
+ENV_KEY = "VELOCITY_READ_CACHE"
+MAX_ENTRIES = 1024
+# tag for entries that describe the schema (table list, columns): DDL drops
+# them; ordinary writes do not
+SCHEMA_TAG = "__schema__"
+
+_MISS = object()
+
+
+def _norm(table) -> str:
+    return str(table).strip().lower()
+
+
+class ReadCache:
+    """A TTL + LRU store of read results, indexed by the tables they depend on."""
+
+    def __init__(self, max_entries: int = MAX_ENTRIES):
+        self._entries: OrderedDict = OrderedDict()  # key -> (expires_at, value, tags)
+        self._by_table: dict = {}  # tag -> set(keys)
+        self._lock = threading.RLock()
+        self._max = max_entries
+        self._enabled: bool | None = None
+        self.hits = 0
+        self.misses = 0
+
+    # ── switch ──────────────────────────────────────────────────────────
+    def enabled(self) -> bool:
+        if self._enabled is None:
+            raw = os.environ.get(ENV_KEY, "").strip().lower()
+            self._enabled = raw not in ("0", "false", "off", "no")
+        return self._enabled
+
+    def configure(self, *, enabled: bool | None) -> None:
+        """Force the switch (``None`` re-reads the environment)."""
+        self._enabled = enabled
+
+    # ── core ────────────────────────────────────────────────────────────
+    def get(self, key, *, now: float | None = None):
+        """``(hit, value)``; an expired entry is a miss and is dropped."""
+        if not self.enabled():
+            return False, None
+        now = time.monotonic() if now is None else now
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is None:
+                self.misses += 1
+                return False, None
+            expires_at, value, _tags = entry
+            if expires_at <= now:
+                self._drop(key)
+                self.misses += 1
+                return False, None
+            self._entries.move_to_end(key)
+            self.hits += 1
+            return True, value
+
+    def put(
+        self, key, value, ttl: float, *, tables=(), now: float | None = None
+    ) -> None:
+        if not self.enabled() or ttl is None or ttl <= 0:
+            return
+        now = time.monotonic() if now is None else now
+        tags = frozenset(_norm(t) for t in tables if t)
+        with self._lock:
+            if key in self._entries:
+                self._drop(key)
+            self._entries[key] = (now + ttl, value, tags)
+            for tag in tags:
+                self._by_table.setdefault(tag, set()).add(key)
+            while len(self._entries) > self._max:
+                oldest, _ = self._entries.popitem(last=False)
+                self._untag(oldest)
+
+    def memo(
+        self, key, loader, ttl: float, *, tables=(), cache_none: bool = True, now=None
+    ):
+        """``loader()`` once per ``ttl`` for ``key``. ``cache_none=False`` never
+        stores a ``None`` result (a "not found" that may exist a moment later)."""
+        hit, value = self.get(key, now=now)
+        if hit:
+            return value
+        value = loader()
+        if value is not None or cache_none:
+            self.put(key, value, ttl, tables=tables, now=now)
+        return value
+
+    # ── invalidation ────────────────────────────────────────────────────
+    def invalidate(self, table=None) -> int:
+        """Drop every entry tagged ``table`` (all entries when ``None``).
+        Returns how many were dropped."""
+        with self._lock:
+            if table is None:
+                count = len(self._entries)
+                self._entries.clear()
+                self._by_table.clear()
+                return count
+            keys = list(self._by_table.get(_norm(table), ()))
+            for key in keys:
+                self._drop(key)
+            return len(keys)
+
+    def invalidate_schema(self) -> int:
+        """DDL happened: drop the table list / column entries."""
+        return self.invalidate(SCHEMA_TAG)
+
+    def clear(self) -> None:
+        with self._lock:
+            self.invalidate(None)
+            self.hits = 0
+            self.misses = 0
+
+    def _drop(self, key) -> None:
+        self._entries.pop(key, None)
+        self._untag(key)
+
+    def _untag(self, key) -> None:
+        for tag, keys in list(self._by_table.items()):
+            keys.discard(key)
+            if not keys:
+                del self._by_table[tag]
+
+    # ── observability ───────────────────────────────────────────────────
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def stats(self) -> dict:
+        return {
+            "enabled": self.enabled(),
+            "entries": len(self._entries),
+            "hits": self.hits,
+            "misses": self.misses,
+        }
+
+
+read_cache = ReadCache()
+
+
+def memo(key, loader, ttl: float, *, tables=(), cache_none: bool = True, now=None):
+    """Module-level shortcut for :meth:`ReadCache.memo` on the shared store."""
+    return read_cache.memo(
+        key, loader, ttl, tables=tables, cache_none=cache_none, now=now
+    )
+
+
+def db_identity(engine) -> str:
+    """A stable name for the database an engine talks to (part of every
+    table-read key, so two databases on one instance never share entries)."""
+    config = getattr(engine, "config", None)
+    if isinstance(config, dict):
+        host = config.get("host") or ""
+        name = config.get("dbname") or config.get("database") or ""
+        return f"{host}/{name}"
+    if isinstance(config, str):
+        return config
+    return f"engine:{id(engine)}"