velocity-python 0.1.106__tar.gz → 0.1.107__tar.gz

{velocity_python-0.1.106 → velocity_python-0.1.107}/PKG-INFO

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

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

{velocity_python-0.1.106 → velocity_python-0.1.107}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.106"
+__version__ = version = "0.1.107"
 
 import importlib as _importlib
 

{velocity_python-0.1.106 → velocity_python-0.1.107}/src/velocity/aws/capabilities/__init__.py

@@ -10,13 +10,23 @@ from .base import (  # noqa: F401
     EVERY_15_MINUTES,
     HOURLY,
     NIGHTLY,
+    POLICY_KINDS,
     REGISTRY,
     Capability,
     capability,
+    catalog,
+    describe,
     get,
+    load_config,
+    policy_field,
     resolve_config,
+    validate_policy,
+)
+from .dispatch import (  # noqa: F401
+    CapabilityCatalogMixin,
+    CapabilityDispatcher,
+    run_capability,
 )
-from .dispatch import CapabilityDispatcher, run_capability  # noqa: F401
 from .provisioning import provision, trigger_key  # noqa: F401
 
 # built-ins (importing registers them)
@@ -29,14 +39,21 @@ from .security import SecurityMixin  # noqa: E402,F401
 
 __all__ = [
     "Capability",
+    "CapabilityCatalogMixin",
     "CapabilityDispatcher",
+    "POLICY_KINDS",
     "REGISTRY",
     "capability",
+    "catalog",
+    "describe",
     "get",
+    "load_config",
+    "policy_field",
     "provision",
     "resolve_config",
     "run_capability",
     "trigger_key",
+    "validate_policy",
     "NIGHTLY",
     "HOURLY",
     "EVERY_15_MINUTES",

velocity_python-0.1.107/src/velocity/aws/capabilities/base.py

@@ -0,0 +1,254 @@
+"""Capabilities: self-describing system-level features a site can turn on.
+
+A whole class of features has the same shape — some schema, a recurring
+schedule, a handler, a few config knobs, maybe a handler mixin: retention
+pruning, session reaping, the feature-flag mirror, mail harvest, demo-safety
+scrubs, ops metrics. A :class:`Capability` declares all of that in ONE object,
+so the deploy pipeline can materialise it (see :mod:`provisioning`) and the
+queue handler can run it (see :mod:`dispatch`) without a bespoke migration or
+wiring per feature.
+
+Division of labour:
+
+* **code** (a subclass registered with :func:`capability`) says what the
+  feature *is* — its schema, default cadence, default knobs, and the work;
+* the **control plane** (the site registry) says which sites/environments run
+  it and with what policy, delivered to the site as an entry that
+  :func:`provisioning.provision` materialises.
+
+Config resolution (:func:`resolve_config`): the capability's ``defaults`` are
+the floor; the environment's feature-flag row overrides the knobs the
+capability declares (so they are edited on the Feature Flags page and mirrored
+between databases); the site's registry ``config`` overrides everything (the
+per-site policy — e.g. *which* tables retention may touch).
+
+A capability also **describes itself** — ``label``, ``description`` and a
+``policy`` schema (:func:`policy_field`) — so an admin UI can offer the
+registry as a pick-list and render a real editor for each policy instead of
+a JSON box (:func:`catalog`), and so a write can be checked against the same
+declaration before it lands (:func:`validate_policy`). One declaration, next
+to the code that reads the config; nothing to keep in step by hand.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import re
+
+# cron expressions the scheduler (croniter) accepts
+NIGHTLY = "0 3 * * *"
+HOURLY = "0 * * * *"
+EVERY_15_MINUTES = "*/15 * * * *"
+CRON_WORDS = {
+    NIGHTLY: "nightly at 03:00 UTC",
+    HOURLY: "hourly",
+    EVERY_15_MINUTES: "every 15 minutes",
+}
+
+# policy field kinds an editor knows how to render and this module validates
+CIDR_LIST = "cidr_list"  # ["203.0.113.0/24", "198.51.100.7"]
+COUNTRY_LIST = "country_list"  # ["US", "CA"] ISO 3166-1 alpha-2
+TABLE_DAYS = "table_days"  # {"aws_api_activity": 90}
+NUMBER = "number"
+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)
+
+IDENTIFIER = re.compile(r"^[a-z_][a-z0-9_]*$")
+COUNTRY_CODE = re.compile(r"^[A-Z]{2}$")
+
+REGISTRY: dict = {}
+
+
+def policy_field(name, kind, label, help="", **extra) -> dict:
+    """One entry of a capability's ``policy`` schema. ``extra`` carries
+    kind-specific hints an editor may use (``options`` for a choice,
+    ``default``, ``placeholder``, ``multiline``, ``min``)."""
+    if kind not in POLICY_KINDS:
+        raise ValueError(f"policy field {name!r}: unknown kind {kind!r}")
+    return {"name": name, "kind": kind, "label": label, "help": help, **extra}
+
+
+class Capability:
+    name: str = ""
+    label: str = ""  # human name; defaults to the name titled
+    description: str = ""  # one or two sentences for the pick-list
+    tier: str = "runtime"  # "runtime" (a Lambda runs it) | "infra" (stacks)
+    schema: dict = {}  # {table: {column: sql type}} -> ensure_schema
+    defaults: dict = {}  # flag name -> default; seeded as TEXT feature flags
+    schedules: tuple = ()  # ((action, cron), ...)
+    mixins: tuple = ()  # handler mixins the site attaches at runtime
+    applies_to: tuple = ("demo", "production")  # default stages; registry can force
+    policy: tuple = ()  # (policy_field(...), ...) — the per-site config shape
+
+    def handle(self, action, tx, context, config):
+        """Do the work for one scheduled/queued ``action``. Return a JSON-able
+        summary (it lands in the queue response and the job log)."""
+        raise NotImplementedError(f"{self.name}: no handler for action {action!r}")
+
+    def on_refresh(self, tx, config):
+        """Hook run after a demo refresh (optional) — scrub/neutralise here."""
+        return None
+
+
+def capability(cls):
+    """Class decorator: instantiate and register under ``cls.name``."""
+    if not getattr(cls, "name", ""):
+        raise ValueError(f"{cls.__name__} must set a non-empty `name`")
+    REGISTRY[cls.name] = cls()
+    return cls
+
+
+def get(name):
+    try:
+        return REGISTRY[name]
+    except KeyError:
+        known = ", ".join(sorted(REGISTRY)) or "(none registered)"
+        raise KeyError(f"unknown capability {name!r}; registered: {known}") from None
+
+
+def resolve_config(cap, flags=None, row_config=None) -> dict:
+    """defaults <- feature flags (declared knobs only) <- site registry config."""
+    config = dict(cap.defaults)
+    flags = flags or {}
+    for key in cap.defaults:
+        value = flags.get(key)
+        if value not in (None, ""):
+            config[key] = value
+    config.update(row_config or {})
+    return config
+
+
+# ── self-description ────────────────────────────────────────────────────
+
+
+def describe(cap) -> dict:
+    """JSON-able description of one capability for a UI or a CLI."""
+    return {
+        "name": cap.name,
+        "label": cap.label or cap.name.replace("_", " ").title(),
+        "description": cap.description,
+        "tier": cap.tier,
+        "applies_to": list(cap.applies_to),
+        "schedules": [
+            {"action": action, "cron": cron, "when": CRON_WORDS.get(cron, cron)}
+            for action, cron in cap.schedules
+        ],
+        "flags": list(cap.defaults),
+        "policy": [dict(field) for field in cap.policy],
+    }
+
+
+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"])
+
+
+def load_config(raw) -> dict:
+    """A row's ``config`` as a dict: JSON text, a dict, or empty."""
+    if raw in (None, ""):
+        return {}
+    if isinstance(raw, str):
+        value = json.loads(raw)
+    else:
+        value = raw
+    if not isinstance(value, dict):
+        raise ValueError("policy must be a JSON object")
+    return value
+
+
+def validate_policy(name, config) -> list:
+    """Check a site's ``config`` against the capability's declared policy.
+
+    Returns human-readable problems (empty = valid). Declared fields are
+    typed; undeclared keys pass through untouched — a policy may carry more
+    than the editor knows (an older row, a hand edit), and the capability
+    decides what it reads. An unknown capability name is itself a problem.
+    """
+    cap = REGISTRY.get(name)
+    if cap is None:
+        known = ", ".join(sorted(REGISTRY)) or "(none registered)"
+        return [f"unknown capability {name!r}; registered: {known}"]
+    try:
+        config = load_config(config)
+    except ValueError as exc:
+        return [f"policy is not valid JSON: {exc}"]
+
+    problems = []
+    for field in cap.policy:
+        value = config.get(field["name"])
+        if value in (None, "", [], {}):
+            continue
+        problems.extend(
+            f"{field['label']}: {problem}"
+            for problem in _check_field(field, value)
+        )
+    return problems
+
+
+def _check_field(field, value):
+    kind = field["kind"]
+    if kind in (CIDR_LIST, COUNTRY_LIST, LIST):
+        if not isinstance(value, (list, tuple)):
+            return ["must be a list"]
+        problems = []
+        for item in value:
+            item = str(item).strip()
+            if kind == CIDR_LIST:
+                try:
+                    ipaddress.ip_network(item, strict=False)
+                except ValueError:
+                    problems.append(f"{item!r} is not an IP address or CIDR")
+            elif kind == COUNTRY_LIST and not COUNTRY_CODE.match(item.upper()):
+                problems.append(f"{item!r} is not a two-letter country code")
+        return problems
+    if kind == TABLE_DAYS:
+        if not isinstance(value, dict):
+            return ["must map table names to days"]
+        problems = []
+        for table, days in value.items():
+            if not IDENTIFIER.match(str(table)):
+                problems.append(f"{table!r} is not a table name")
+            if days in (None, "", 0):
+                continue  # falls back to the default window
+            if not _is_int(days) or int(days) < 1:
+                problems.append(f"{table}: days must be a whole number >= 1")
+        return problems
+    if kind == NUMBER:
+        if isinstance(value, bool) or not _is_number(value):
+            return ["must be a number"]
+        minimum = field.get("min")
+        if minimum is not None and float(value) < minimum:
+            return [f"must be >= {minimum}"]
+        return []
+    if kind == BOOLEAN:
+        ok = isinstance(value, bool) or str(value).lower() in ("true", "false")
+        return [] if ok else ["must be true or false"]
+    if kind == CHOICE:
+        options = field.get("options") or ()
+        return [] if value in options else [f"must be one of {', '.join(options)}"]
+    if kind == TEXT:
+        return [] if isinstance(value, str) else ["must be text"]
+    return []
+
+
+def _is_int(value) -> bool:
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, int):
+        return True
+    return isinstance(value, str) and value.strip().isdigit()
+
+
+def _is_number(value) -> bool:
+    if isinstance(value, (int, float)):
+        return True
+    try:
+        float(str(value))
+        return True
+    except ValueError:
+        return False

{velocity_python-0.1.106 → velocity_python-0.1.107}/src/velocity/aws/capabilities/dispatch.py

@@ -13,7 +13,7 @@ import json
 
 from velocity.aws import feature_flags
 
-from .base import REGISTRY, resolve_config
+from .base import REGISTRY, catalog, resolve_config
 from .provisioning import SITE_TABLE
 
 
@@ -48,3 +48,14 @@ class CapabilityDispatcher:
             tx, context, payload.get("capability"), payload.get("action")
         )
         context.response().set_body(body)
+
+
+class CapabilityCatalogMixin:
+    """Web-handler mixin for the control plane: ``capability-catalog`` answers
+    with every registered capability described (``{"rows": [...]}`` — the
+    shape velocity-react's ApiSelect and option hooks consume), so the admin
+    UI's pick-list and policy editors come from the code, not a copy."""
+
+    def OnActionCapabilityCatalog(self, tx, context):
+        del tx
+        context.response().set_body({"rows": catalog()})

velocity_python-0.1.107/src/velocity/aws/capabilities/infra.py

@@ -0,0 +1,121 @@
+"""Infra-tier capabilities: rendered into a site's CloudFormation stacks by
+the sitefactory templates rather than run by a Lambda.
+
+They are registered here so the registry recognises their names (the
+provisioner would otherwise refuse an unknown capability) and so they sit
+on the same Site Capabilities page as everything else; their ``config`` is
+the template's policy. Nothing here executes at runtime.
+
+* ``security_headers`` — the CloudFront response-headers policy on the web
+  distribution (HSTS, nosniff, frame options, referrer policy, XSS-off, and
+  an optional ``csp``). Free; ON by default for every factory site — a row
+  is only needed to turn it OFF or to set a Content-Security-Policy.
+* ``api_throttling`` — API Gateway stage throttling (``rate`` requests/s,
+  ``burst``). Free; the template defaults apply without a row.
+"""
+
+from __future__ import annotations
+
+from .base import BOOLEAN, CHOICE, NUMBER, TEXT, Capability, capability, policy_field
+
+
+class InfraCapability(Capability):
+    tier = "infra"
+    schedules = ()
+    schema = {}
+
+    def handle(self, action, tx, context, config):
+        raise RuntimeError(
+            f"{self.name} is an infra capability rendered into the site's stacks "
+            f"by sitefactory; it has no runtime action ({action!r})"
+        )
+
+
+@capability
+class SecurityHeaders(InfraCapability):
+    name = "security_headers"
+    label = "Security headers (CloudFront)"
+    description = (
+        "Browser hardening headers on every web response: HSTS, nosniff, frame "
+        "options, referrer policy, and an optional Content-Security-Policy. "
+        "Free; on for every factory site by default — add a row to turn it "
+        "off or to set a CSP. Applied by site-update-web, not the backend deploy."
+    )
+    # the keys sitefactory.templates.web.security_headers_config reads
+    policy = (
+        policy_field(
+            "enabled",
+            BOOLEAN,
+            "Send security headers",
+            "Off removes the headers policy from the distribution.",
+            default=True,
+        ),
+        policy_field(
+            "csp",
+            TEXT,
+            "Content-Security-Policy",
+            "Optional. Sent verbatim; a wrong CSP blocks your own scripts, so "
+            "test on demo first.",
+            multiline=True,
+            placeholder="default-src 'self'; img-src 'self' data:",
+        ),
+        policy_field(
+            "frame_options",
+            CHOICE,
+            "Frame options",
+            "SAMEORIGIN lets the site frame itself; DENY forbids all framing.",
+            options=("SAMEORIGIN", "DENY"),
+            default="SAMEORIGIN",
+        ),
+        policy_field(
+            "referrer_policy",
+            CHOICE,
+            "Referrer policy",
+            "",
+            options=(
+                "strict-origin-when-cross-origin",
+                "no-referrer",
+                "same-origin",
+                "strict-origin",
+            ),
+            default="strict-origin-when-cross-origin",
+        ),
+        policy_field(
+            "hsts_max_age",
+            NUMBER,
+            "HSTS max-age (seconds)",
+            "Two years (63072000) is the preload-list minimum.",
+            default=63072000,
+            min=0,
+        ),
+    )
+
+
+@capability
+class ApiThrottling(InfraCapability):
+    name = "api_throttling"
+    label = "API throttling (API Gateway)"
+    description = (
+        "Stage-level request throttling on the private and public APIs — the "
+        "first, free line against floods. Free; the template defaults (100 "
+        "requests/s, burst 200) apply without a row. Applied by site-up."
+    )
+    # the keys sitefactory.driver reads for the api template
+    policy = (
+        policy_field(
+            "rate",
+            NUMBER,
+            "Steady rate (requests / second)",
+            "",
+            default=100,
+            min=1,
+        ),
+        policy_field(
+            "burst",
+            NUMBER,
+            "Burst (requests)",
+            "Short spikes above the steady rate that are still served.",
+            default=200,
+            min=1,
+        ),
+    )

{velocity_python-0.1.106 → velocity_python-0.1.107}/src/velocity/aws/capabilities/jobs.py

@@ -26,6 +26,12 @@ from .base import EVERY_15_MINUTES, Capability, capability
 @capability
 class Jobs(Capability):
     name = "jobs"
+    label = "Job hygiene"
+    description = (
+        "Marks asynchronous jobs whose worker died as Failed (instead of "
+        "Running forever) and prunes old job activity. Windows are per-"
+        "environment flags; no per-site policy."
+    )
     defaults = {"job_stale_minutes": "16", "job_retention_days": "30"}
     schedules = (("expire_stale", EVERY_15_MINUTES),)
 

{velocity_python-0.1.106 → velocity_python-0.1.107}/src/velocity/aws/capabilities/retention.py

@@ -18,7 +18,7 @@ from __future__ import annotations
 import datetime
 import re
 
-from .base import NIGHTLY, Capability, capability
+from .base import NIGHTLY, TABLE_DAYS, Capability, capability, policy_field
 
 IDENTIFIER = re.compile(r"^[a-z_][a-z0-9_]*$")
 TIMESTAMP_COLUMN = "sys_created"
@@ -29,8 +29,25 @@ MAX_BATCHES = 200  # 1M rows per run — well inside the Lambda budget
 @capability
 class Retention(Capability):
     name = "retention"
+    label = "Retention (table pruning)"
+    description = (
+        "Deletes rows older than a per-table window so log-like tables stop "
+        "growing forever. Only the tables listed in the policy are ever touched; "
+        "rows are aged by sys_created and deleted nightly in small batches."
+    )
     defaults = {"purge_default_days": "90"}
     schedules = (("purge", NIGHTLY),)
+    policy = (
+        policy_field(
+            "tables",
+            TABLE_DAYS,
+            "Tables to prune",
+            "Each table and how many days of rows to keep. Leave days blank to "
+            "use the purge_default_days flag. Archives are not logs — list only "
+            "tables you are happy to lose old rows from.",
+            placeholder="aws_api_activity",
+        ),
+    )
 
     def handle(self, action, tx, context, config):
         if action != "purge":

{velocity_python-0.1.106 → velocity_python-0.1.107}/src/velocity/aws/capabilities/security.py

@@ -31,7 +31,15 @@ import time
 
 from velocity.aws import feature_flags
 
-from .base import HOURLY, Capability, capability, resolve_config
+from .base import (
+    CIDR_LIST,
+    COUNTRY_LIST,
+    HOURLY,
+    Capability,
+    capability,
+    policy_field,
+    resolve_config,
+)
 from .provisioning import SITE_TABLE
 
 log = logging.getLogger(__name__)
@@ -174,9 +182,22 @@ def _cached(key, loader, *, now=None):
 
 
 def _site_row(tx):
-    return _cached(
-        ("site", "security"), lambda: tx.table(SITE_TABLE).find({"name": "security"})
-    )
+    """The site's `security` row from sys_capabilities, cached per container.
+
+    A site that has never provisioned a capability has no sys_capabilities
+    table at all — a bare find() there is a failing statement on every request
+    (rolled back and logged by velocity, but noise and a wasted round trip).
+    exists() is a cheap catalog check and the honest answer: not provisioned
+    here, so the mixin is a no-op.
+    """
+
+    def load():
+        table = tx.table(SITE_TABLE)
+        if not table.exists():
+            return None
+        return table.find({"name": "security"})
+
+    return _cached(("site", "security"), load)
 
 
 def _flags(tx):
@@ -311,7 +332,54 @@ class SecurityMixin:
 @capability
 class Security(Capability):
     name = "security"
+    label = "Security guards"
+    description = (
+        "Request-path guards in the application: IP deny/allow lists, country "
+        "allow/block, per-IP and per-user rate limits, payload caps, and an "
+        "audit of every refusal. Each guard is a switch on the Security page; "
+        "this policy holds the lists."
+    )
     defaults = {**SWITCHES, **KNOBS}
+    policy = (
+        policy_field(
+            "ip_denylist",
+            CIDR_LIST,
+            "IP deny list",
+            "Addresses or CIDR ranges refused outright (when the IP deny list "
+            "switch is on).",
+            placeholder="203.0.113.0/24",
+        ),
+        policy_field(
+            "ip_allowlist",
+            CIDR_LIST,
+            "IP allow list",
+            "When the IP allow list switch is on, ONLY these addresses may call "
+            "— an office/VPN lock-down. Leave empty for no restriction.",
+            placeholder="198.51.100.0/24",
+        ),
+        policy_field(
+            "blocked_countries",
+            COUNTRY_LIST,
+            "Blocked countries",
+            "Requests from these countries are refused (country switch on; "
+            "judged from the CloudFront viewer country).",
+        ),
+        policy_field(
+            "allowed_countries",
+            COUNTRY_LIST,
+            "Allowed countries",
+            "When set, only these countries may call. Leave empty to allow all "
+            "but the blocked ones.",
+        ),
+        policy_field(
+            "rate_limit_exempt",
+            CIDR_LIST,
+            "Rate-limit exempt networks",
+            "Addresses never counted against the rate limit (monitors, the "
+            "office, a partner integration).",
+            placeholder="192.0.2.0/24",
+        ),
+    )
     schema = {
         EVENTS_TABLE: {
             "guard": "TEXT",

{velocity_python-0.1.106 → velocity_python-0.1.107}/src/velocity/aws/capabilities/single_session.py

@@ -26,6 +26,13 @@ SESSION_TABLE = "app_session"
 @capability
 class SingleSession(Capability):
     name = "single_session"
+    label = "Single session per user"
+    description = (
+        "One active login per user: a new sign-in ends the older session. "
+        "Enforcement and the staleness window are per-environment flags; the "
+        "reaper deletes sessions not seen for the retention window. No "
+        "per-site policy."
+    )
     defaults = {
         "single_session_enforcement": "true",
         "session_stale_minutes": "10",

{velocity_python-0.1.106 → velocity_python-0.1.107}/src/velocity_python.egg-info/PKG-INFO

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

@@ -211,6 +211,7 @@ tests/test_async_support.py
 tests/test_batch_operations.py
 tests/test_blob_store.py
 tests/test_capabilities.py
+tests/test_capability_catalog.py
 tests/test_column_tx_arg.py
 tests/test_concurrency_safety.py
 tests/test_connection_pool.py