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

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

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

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

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

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

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

@@ -0,0 +1,60 @@
+"""System-level capabilities a site turns on: declared once in code, toggled
+per site/environment by the control plane, materialised by
+:func:`provisioning.provision` at deploy time and run by
+:class:`dispatch.CapabilityDispatcher` at runtime. See :mod:`base`.
+
+Importing this package registers the built-in capabilities.
+"""
+
+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 .provisioning import provision, trigger_key  # noqa: F401
+
+# built-ins (importing registers them)
+from . import retention  # noqa: E402,F401
+from . import security  # noqa: E402,F401
+from . import infra  # noqa: E402,F401
+from . import single_session  # noqa: E402,F401
+from . import jobs  # noqa: E402,F401
+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.107/src/velocity/aws/capabilities/dispatch.py

@@ -0,0 +1,61 @@
+"""Runtime dispatch: route the ``run-capability`` queue action to a capability.
+
+A site's queue handler mixes in :class:`CapabilityDispatcher`; the scheduler
+stubs seeded by :mod:`provision` enqueue ``run-capability`` with
+``{"capability": name, "action": action}`` and this routes it. Config is
+resolved locally — the site's own ``sys_capabilities`` row plus its feature
+flags — so the runtime never reaches into the control plane.
+"""
+
+from __future__ import annotations
+
+import json
+
+from velocity.aws import feature_flags
+
+from .base import REGISTRY, catalog, resolve_config
+from .provisioning import SITE_TABLE
+
+
+def run_capability(tx, context, name, action):
+    """Resolve config and run one capability action. Returns the response body."""
+    cap = REGISTRY.get(name)
+    if cap is None:
+        return {"error": f"unknown capability {name!r}", "capability": name}
+
+    row = tx.table(SITE_TABLE).find({"name": name}) or {}
+    if row and row.get("enabled") is False:
+        return {
+            "capability": name,
+            "action": action,
+            "skipped": "disabled for this site",
+        }
+
+    raw = row.get("config") if row else None
+    row_config = json.loads(raw) if isinstance(raw, str) and raw else (raw or {})
+    config = resolve_config(cap, flags=feature_flags.get(tx), row_config=row_config)
+
+    result = cap.handle(action, tx, context, config)
+    return {"capability": name, "action": action, "result": result}
+
+
+class CapabilityDispatcher:
+    """Queue-handler mixin: ``run-capability`` -> the registered capability."""
+
+    def OnActionRunCapability(self, tx, context):
+        payload = context.payload() or {}
+        body = run_capability(
+            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.107/src/velocity/aws/capabilities/jobs.py

@@ -0,0 +1,59 @@
+"""jobs: the scheduled half of asynchronous-job hygiene.
+
+``JobHandler`` only discovers a stale job (worker died: Lambda timeout / OOM)
+when someone polls its status — an abandoned job nobody polls stays "Running"
+forever, and ``aws_job_activity`` is never pruned. This capability sweeps on
+a schedule with the SAME predicate the web tier uses
+(``velocity.aws.job_lifecycle.job_is_stale``): stale jobs are persisted as
+Failed with the standard message, and old activity rows are purged.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+
+from velocity.aws.job_lifecycle import (
+    JOB_ACTIVITY_TABLE,
+    STALE_FAILURE,
+    STALE_JOB_STATUSES,
+    job_is_stale,
+)
+
+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),)
+
+    def handle(self, action, tx, context, config):
+        if action != "expire_stale":
+            raise ValueError(f"jobs: unknown action {action!r}")
+        now = datetime.datetime.now(datetime.timezone.utc)
+        stale_after = datetime.timedelta(
+            minutes=int(config.get("job_stale_minutes") or 16)
+        )
+        jobs = tx.table(JOB_ACTIVITY_TABLE)
+
+        expired = 0
+        for status in sorted(STALE_JOB_STATUSES):
+            for job in jobs.select(where={"status": status}):
+                if job_is_stale(job, now=now, stale_after=stale_after):
+                    jobs.update(
+                        {"status": "Failed", "message": json.dumps(STALE_FAILURE)},
+                        where={"sys_id": job["sys_id"]},
+                    )
+                    expired += 1
+
+        days = int(config.get("job_retention_days") or 30)
+        purged = jobs.purge({"<sys_created": now - datetime.timedelta(days=days)})
+        return {"expired": expired, "purged": purged}