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

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

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

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

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

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.104"
+__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.104 → 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.104
+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.104 → 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
@@ -213,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

velocity_python-0.1.105/tests/test_feature_flags.py

@@ -0,0 +1,176 @@
+"""Environment-scoped feature flags: current-system resolution, scoped reads,
+and the cross-database mirror/reconcile mechanism (no DB — fakes throughout)."""
+
+import pytest
+
+from velocity.aws import feature_flags as ff
+
+
+# ── fakes ────────────────────────────────────────────────────────────────
+
+class FakeTable:
+    def __init__(self, rows):
+        self.rows = rows
+        self.merges = []  # (data, pk)
+
+    def find(self, where):
+        for row in self.rows:
+            if all(row.get(k) == v for k, v in where.items()):
+                return dict(row)
+        return None
+
+    def select(self, *_a, **_k):
+        return list(self.rows)
+
+    def merge(self, data, pk):
+        self.merges.append((dict(data), dict(pk)))
+
+
+class FakeTx:
+    def __init__(self, rows):
+        self._table = FakeTable(rows)
+
+    def table(self, _name):
+        return self._table
+
+
+class FakeEngine:
+    """Alternate-DB stand-in: hands out one table and records its merges."""
+
+    def __init__(self, rows=None):
+        self.table_obj = FakeTable(rows or [])
+
+    def transaction(self):
+        engine = self
+
+        class _Ctx:
+            def __enter__(self_):
+                return engine
+
+            def __exit__(self_, *exc):
+                return False
+
+        return _Ctx()
+
+    def table(self, _name):
+        return self.table_obj
+
+
+class FakeResponse:
+    def __init__(self):
+        self.toasts = []
+
+    def toast(self, message, level):
+        self.toasts.append((message, level))
+
+
+class FakeContext:
+    def __init__(self):
+        self._response = FakeResponse()
+
+    def response(self):
+        return self._response
+
+
+DEMO = {"sys_id": 1, "applied_system": "demo",
+        "gmail_sync_allowlist": "a@example.com", "sys_dirty": True}
+PROD = {"sys_id": 2, "applied_system": "production",
+        "gmail_sync_allowlist": None}
+
+
+# ── current_system (the runtime stage) ───────────────────────────────────
+
+def test_current_system_is_the_stage(monkeypatch):
+    import velocity.aws.ssm_config as ssm
+    monkeypatch.setattr(ssm, "get_stage", lambda *a, **k: "production")
+    assert ff.current_system() == "production"
+
+
+def test_current_system_default_when_no_stage(monkeypatch):
+    import velocity.aws.ssm_config as ssm
+    monkeypatch.setattr(ssm, "get_stage", lambda *a, **k: None)
+    assert ff.current_system(default="demo") == "demo"
+
+
+# ── get (scoped read) ────────────────────────────────────────────────────
+
+def test_get_scopes_to_the_named_stage():
+    tx = FakeTx([DEMO, PROD])
+    assert ff.get(tx, "production")["applied_system"] == "production"
+    assert ff.get(tx, "demo")["gmail_sync_allowlist"] == "a@example.com"
+
+
+def test_get_missing_returns_empty_or_raises():
+    tx = FakeTx([DEMO])
+    assert ff.get(tx, "nope") == {}
+    with pytest.raises(KeyError):
+        ff.get(tx, "nope", raise_on_missing=True)
+
+
+def test_get_defaults_system_to_current(monkeypatch):
+    monkeypatch.setattr(ff, "current_system", lambda: "production")
+    assert ff.get(FakeTx([DEMO, PROD]))["applied_system"] == "production"
+
+
+# ── mirror_row ───────────────────────────────────────────────────────────
+
+def test_mirror_row_strips_sys_and_keys_by_stage():
+    engine = FakeEngine()
+    key = ff.mirror_row(DEMO, engine=engine)
+    assert key == "demo"
+    data, pk = engine.table_obj.merges[0]
+    assert pk == {"applied_system": "demo"}
+    assert "sys_dirty" not in data and "sys_id" not in data
+    assert data["gmail_sync_allowlist"] == "a@example.com"
+
+
+def test_mirror_row_skips_keyless_row():
+    engine = FakeEngine()
+    assert ff.mirror_row({"sys_id": 9, "flag": "x"}, engine=engine) is None
+    assert engine.table_obj.merges == []
+
+
+# ── reconcile ────────────────────────────────────────────────────────────
+
+def test_reconcile_mirrors_every_keyed_row():
+    tx = FakeTx([DEMO, PROD, {"sys_id": 3, "applied_system": None}])
+    engine = FakeEngine()
+    result = ff.reconcile(tx, engine=engine)
+    assert result["synced"] == ["demo", "production"]
+    assert result["skipped"] == [3]
+    assert len(engine.table_obj.merges) == 2
+
+
+# ── the reusable RWX hook ────────────────────────────────────────────────
+
+def test_mirror_hook_delegates_and_toasts_success():
+    engine = FakeEngine()
+    hook = ff.make_mirror_hook()
+    ctx = FakeContext()
+    # engine is injected via a closure over alternate_engine; patch it
+    import velocity.aws.feature_flags as mod
+    orig = mod.alternate_engine
+    mod.alternate_engine = lambda *a, **k: engine
+    try:
+        hook(None, "sys_feature_flags", 1, DEMO, ctx)
+    finally:
+        mod.alternate_engine = orig
+    assert engine.table_obj.merges[0][1] == {"applied_system": "demo"}
+    assert ctx.response().toasts[0][1] == "success"
+
+
+def test_mirror_hook_warns_and_continues_on_failure():
+    hook = ff.make_mirror_hook()
+    ctx = FakeContext()
+    import velocity.aws.feature_flags as mod
+    orig = mod.alternate_engine
+
+    def boom(*a, **k):
+        raise RuntimeError("alternate unreachable")
+
+    mod.alternate_engine = boom
+    try:
+        hook(None, "sys_feature_flags", 1, DEMO, ctx)  # must NOT raise
+    finally:
+        mod.alternate_engine = orig
+    assert ctx.response().toasts[0][1] == "warning"