runloopable / platform /core /chart_system.py
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
ce9586e verified
Raw History Blame Contribute Delete
10.9 kB
"""chart_system.py β€” a SAVED CONFIGURABLE-INTERFACE RECORD (wave 47, instruction 18, W47-T30).
⭐ **OWNER RULING R7 IS WHY THIS FILE EXISTS.** Verbatim: *"every interface like chart, swap etc.
that we need to configure should act like route with the right side navigation to choose the
specific view we want to see. So its not pegged on a per view basis."* Time-series state hides
today inside `ws["views"][vid]["config"]["display"]` β€” one copy per view, owned by nobody, listed
nowhere, and lost the moment the view it rode on is changed or deleted. That is precisely what the
ruling rejects.
⭐ **CONTRACT C6:** *"a saved chart is a record, not a view setting. It carries its own id, name and
owner and is listed independently of `ws["views"]`, so a second consumer can reuse the type
unchanged."*
β›”β›” **THIS FILE MUST NEVER INTERPRET `config`, AND THAT IS THE WHOLE REUSABILITY CONTRACT.** A
record carries a `kind` (this wave's only shipped consumer writes `"timeseries"`) and an OPAQUE
`config` dict stored verbatim. There is deliberately NO allowlist of kinds and NO knowledge of a
single config key: a second consumer ("swap", a map preset, a pivot) stores its own `kind` and its
own config shape with ZERO change to this file. An `if kind == "timeseries"` here β€” or a field
named after the time-series β€” breaks C6 while passing every gate.
β›” **INDEPENDENT STORAGE IS THE NEGATIVE CONTROL, not a detail.** Charts live in their own
dedicated store bucket, `loopable_chart_system`. The view documents live in the personal source
strata of per-topic table workspace buckets (`customer_table_workspace`,
`product_table_workspace`, a `ut_*` key); the reserved `__shared__` member is for field annotations,
not Views. Nothing in this module reads or writes a workspace document, a `views` map, or anything
named `ws[...]`, so deleting a view cannot delete a chart: they are different keys in the store and
there is no code path between them.
⭐ **THE SHAPE OF THIS MODULE MIRRORS `core/route_system.py` DELIBERATELY** β€” a dedicated
module-level `STORE_KEY`, a projected `_store` read, a read-modify-write `_persist` under the
store's own lock, server-minted ids, and a duck-typed `st` (only `get` / `get_projection` /
`update` are ever used). Like that module this one imports ONLY stdlib and NOTHING from
`platform/core/`, so it can never drag a topic, a permission model or a connector into a record
type that is meant to outlive all three. The small duplication of `_now` / `_store` / `_persist` is
correct here rather than a smell: there is no shared lower-level helper to reuse, and importing
`route_system` would couple charts to routes for four lines of code.
⚠ NAME IS NOT UNIQUE. `id` is the only match key, exactly as for a Route. Two charts may share a
name on one database and neither is lost.
⚠ PERMISSION IS NOT DECIDED HERE. Visibility is a per-database question and its one chokepoint is
`deps.Session.require(<database>)` in `aios-web/api/routes_charts.py`, the same predicate the nav
uses. This module stores `database` as a DATABASE KEY (`customer_data`, `product_data`, a `ut_*`
table key) β€” never the React client's separate `SurfaceScope` vocabulary ("customer", "product"),
which is a different string space and a separately booked defect.
"""
import copy
import json
import re
import uuid
from datetime import datetime, timezone
#: The DEDICATED bucket. Not inside any workspace document β€” that separation is what makes C6's
#: "listed independently of ws['views']" a fact about storage rather than a promise about code.
STORE_KEY = "loopable_chart_system"
#: A DEFAULT, never a constraint: any slug is accepted. β›” Never a retired kind: S68-T44 retired
#: `timeseries` and its boot purge deletes every chart of that kind (and every stored kind-less
#: one), so a kind-less chart written AFTER the purge must not be re-stamped as Time-series.
DEFAULT_KIND = "chart"
_MAX_NAME = 120
_MAX_KIND = 40
_MAX_DATABASE = 200
_MAX_ID = 80
_MAX_STAMP = 120
#: A client may not park an unbounded blob in the tenant store. A BYTE CAP is not interpretation:
#: it never looks at a key, only at the serialized length.
MAX_CONFIG_BYTES = 64 * 1024
_KIND_CLEAN = re.compile(r"[^a-z0-9_]+")
def _now():
return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
def _store(st):
"""The bucket, projected when the runtime offers a projection (never the whole store)."""
try:
projected = getattr(st, "get_projection", None)
if callable(projected):
return dict(projected(STORE_KEY, drop=()) or {})
return dict(st.get(STORE_KEY) or {})
except Exception:
return {}
def _persist(st, mutate):
"""Read-modify-write under the store's own lock, mirroring `route_system._persist`."""
result = {}
def apply(current):
state = copy.deepcopy(current) if isinstance(current, dict) else {}
state.setdefault("charts", [])
next_state, value = mutate(state)
result["value"] = copy.deepcopy(value)
return next_state
st.update(STORE_KEY, apply, flush="sync")
return result.get("value")
def _text(raw, limit):
return str(raw if raw is not None else "").strip()[:limit]
def _slug_kind(raw):
"""A kind is SANITIZED, never validated against a list. See the module note."""
slug = _KIND_CLEAN.sub("_", str(raw or "").strip().lower())[:_MAX_KIND].strip("_")
return slug or DEFAULT_KIND
def _config(raw):
"""`(value, ok)` for an OPAQUE config: JSON-safe and under the byte cap, or refused.
Strictly JSON-serializable with no `default=` coercion, because the store persists JSON and a
value that only stringifies would be a write that fails later, somewhere else. Nothing here
inspects a key, and nothing may start to.
"""
if raw is None:
return {}, True
if not isinstance(raw, dict):
return {}, False
try:
blob = json.dumps(raw)
except (TypeError, ValueError):
return {}, False
if len(blob.encode("utf-8")) > MAX_CONFIG_BYTES:
return {}, False
return copy.deepcopy(raw), True
def _record(raw, *, created_by="", tenant_id="", prior=None):
"""Normalize one chart, or None when it is not a chart.
β›” `database`, `createdBy`, `createdAt`, `tenantId` and `id` are all PRIOR-WINS on update.
An update that could move a chart to another database would be a permission escape: the caller
passed the wall for the database the chart is on, not for the one being named.
"""
raw = raw if isinstance(raw, dict) else {}
prior = prior if isinstance(prior, dict) else None
name = _text(raw.get("name"), _MAX_NAME)
if not name and prior is not None:
name = _text(prior.get("name"), _MAX_NAME)
if not name:
return None
database = _text(prior.get("database") if prior is not None else raw.get("database"),
_MAX_DATABASE)
if not database:
return None
kind_src = raw.get("kind")
if kind_src in (None, "") and prior is not None:
kind_src = prior.get("kind")
kind = _slug_kind(kind_src)
if "config" in raw:
config, ok = _config(raw.get("config"))
if not ok:
return None
elif prior is not None:
config = copy.deepcopy(prior.get("config") or {})
else:
config = {}
now = _now()
if prior is not None:
chart_id = _text(prior.get("id"), _MAX_ID)
owner = _text(prior.get("createdBy"), _MAX_STAMP).lower()
tenant = _text(prior.get("tenantId"), _MAX_STAMP)
created_at = _text(prior.get("createdAt"), 40) or now
else:
chart_id = "chart_" + uuid.uuid4().hex
owner = _text(created_by, _MAX_STAMP).lower()
tenant = _text(tenant_id, _MAX_STAMP)
created_at = now
return {"id": chart_id,
"tenantId": tenant,
"kind": kind,
"database": database,
"name": name,
"config": config,
"createdBy": owner,
"createdAt": created_at,
"updatedAt": now}
def _tenant_ok(chart, tenant_id):
if not tenant_id:
return True
stamped = str(chart.get("tenantId") or "")
return not stamped or stamped == str(tenant_id)
def list_charts(st, *, database=None, tenant_id=None):
"""Every saved chart in this store, optionally narrowed to one database key.
Sorted by name then id so a navigator renders stably; NAME IS NOT UNIQUE, so id breaks ties.
"""
charts = [c for c in (_store(st).get("charts") or []) if isinstance(c, dict)]
charts = [c for c in charts if _tenant_ok(c, tenant_id)]
want = str(database or "").strip()
if want:
charts = [c for c in charts if str(c.get("database") or "") == want]
return sorted(charts, key=lambda c: (str(c.get("name") or "").lower(), str(c.get("id") or "")))
def get_chart(st, chart_id, *, tenant_id=None):
"""One chart by id, or None. The caller still owes the per-database wall."""
wanted = str(chart_id or "").strip()
if not wanted:
return None
for chart in list_charts(st, tenant_id=tenant_id):
if str(chart.get("id") or "") == wanted:
return chart
return None
def put_chart(st, raw, *, tenant_id, created_by):
"""Create (no `id`) or update (`id` of an existing chart). None when the input is not a chart.
An `id` naming a chart that does not exist is refused rather than created, so an upsert
primitive cannot become a way to choose your own id.
"""
incoming = dict(raw) if isinstance(raw, dict) else {}
wanted = str(incoming.get("id") or "").strip()
prior = get_chart(st, wanted, tenant_id=tenant_id) if wanted else None
if wanted and prior is None:
return None
record = _record(incoming, created_by=created_by, tenant_id=tenant_id, prior=prior)
if record is None:
return None
def mutate(state):
charts = [c for c in (state.get("charts") or []) if isinstance(c, dict)]
replaced = False
for index, chart in enumerate(charts):
if str(chart.get("id") or "") == record["id"]:
charts[index] = record
replaced = True
break
if not replaced:
charts.append(record)
state["charts"] = charts
return state, record
return _persist(st, mutate)
def delete_chart(st, chart_id):
"""True when a chart was removed. Touches nothing but this module's own bucket."""
wanted = str(chart_id or "").strip()
if not wanted:
return False
def mutate(state):
charts = [c for c in (state.get("charts") or []) if isinstance(c, dict)]
keep = [c for c in charts if str(c.get("id") or "") != wanted]
state["charts"] = keep
return state, len(keep) != len(charts)
return bool(_persist(st, mutate))