runloopable / platform /core /app_dashboard.py
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
8133df9 verified
Raw History Blame Contribute Delete
12.5 kB
"""Validate dashboard figures through explicit source adapters before serialization."""
from __future__ import annotations
from datetime import date
import inspect
import logging
import math
import re
from typing import NotRequired, TypedDict
from core.request_timing import raise_if_resource_error, remaining_budget
class Figure(TypedDict):
"""A checked figure with flat or grouped series and optional comparison evidence."""
id: str
label: str
value: float | int | str | None
unit: str
series: list
source_table: str
validated: bool
reason: str | None
change: NotRequired[dict]
noPrior: NotRequired[bool]
headline: NotRequired[bool]
# Each App's headline figures draw first, in one row. An entry matches its id exactly. A trailing `*`
# also matches a currency suffix (`net-payout-USD`, `storage_fees_USD`). An id a module does not serve is skipped.
HEADLINES = {
"restock_planner": ("skus_critical", "units_to_send", "days_of_supply"),
"aged_stock": ("aged_units", "storage_fees*", "long_term_storage_fees*"),
"reimbursements": ("open-value-*", "paid-*"),
"payouts": ("net-payout-*", "next-deposit-*", "fee-share-*"),
"account_health": ("open_risks", "open_alerts"),
"returns_refunds": ("return_rate", "refund_rate", "refund_cost"),
"repeat_buyers": ("repeat_share", "repeat_revenue"),
"opportunity_finder": ("open_opportunities", "search_volume"),
"ranking_diagnostic": ("rank_drops", "suppressed", "stranded"),
"competitor_watch": ("tracked_terms", "open_alerts"),
"amazon_dashboard": ("sales", "net_profit", "ad_spend", "units"),
"amazon_operator": ("spend", "ad_sales", "acos", "tacos"),
}
def is_headline(kind, identity):
"""True when a served figure id is one of its kind's headline figures."""
if not isinstance(identity, str):
return False
for head in HEADLINES.get(kind, ()):
stem = head.rstrip("*-_")
if identity == stem or (head.endswith("*") and identity[:len(stem) + 1] in (stem + "-", stem + "_")
and len(identity) > len(stem) + 1):
return True
return False
UNAVAILABLE = "This figure could not be validated."
ADAPTER = "Dashboard data is unavailable."
_UNSAFE = re.compile(r"select\s|insert\s|update\s|delete\s|from\s+\w|postgres|password|secret|token|credential|://|traceback|\bSQL\b|\.env|configuration", re.I)
_META = ("id", "label", "unit", "source_table", "source_tables", "source_databases")
_log = logging.getLogger(__name__)
_STEPS = {"provider": "Loading the figures", "batch validate": "Checking the figures",
"figure validate": "Checking this figure", "read": "Reading the dashboard"}
_TABLE = re.compile(r'(?:no such table:?\s+|table with name\s+|relation\s+(?="))"?([A-Za-z_]\w{0,62})', re.I)
_TIMEOUT = re.compile(r"timed?\s?out|timeout|canceling statement", re.I)
def safe_reason(value, default=UNAVAILABLE):
"""Retain short public source reasons without backend or credential details."""
if not isinstance(value, str) or not value.strip() or len(value) > 240 or _UNSAFE.search(value):
return default
return value.strip()
def plain_cause(exc, step, source=None):
"""One screen line naming a caught failure's step and source, with no class name, SQL or path."""
doing = _STEPS.get(step, "Loading the dashboard")
sources = [source] if isinstance(source, str) else list(source or ())
where = " or ".join(s for s in sources if isinstance(s, str) and re.fullmatch(r"[A-Za-z_]\w{0,62}", s))
found = _TABLE.search(str(exc))
if isinstance(exc, PermissionError):
line = f"Your account cannot read {where}." if where else "Your account cannot read this dashboard source."
elif found or isinstance(exc, FileNotFoundError):
table = found.group(1) if found else where
line = f"{doing} stopped because the {table} table is missing." if table else f"{doing} stopped because a source table is missing."
elif isinstance(exc, TimeoutError) or _TIMEOUT.search(type(exc).__name__ + " " + str(exc)):
line = f"{doing} timed out waiting on {where}." if where else f"{doing} timed out waiting on its source."
else:
line = f"{doing} failed while reading {where}." if where else f"{doing} failed. Try again shortly."
return safe_reason(line, default=f"{doing} failed. Try again shortly.")
def log_failure(logger, exc, step, kind, tenant, figure=None):
"""Write one server line with the traceback for a caught failure. An access refusal is a warning."""
level = logging.WARNING if isinstance(exc, PermissionError) else logging.ERROR
logger.log(level, "App dashboard %s failed: kind=%s tenant=%s figure=%s",
step, kind, tenant, figure or "-", exc_info=(type(exc), exc, exc.__traceback__))
def unavailable(raw=None, reason=UNAVAILABLE):
raw = raw if isinstance(raw, dict) else {}
out = {key: raw[key] for key in _META if isinstance(raw.get(key), str)
or (isinstance(raw.get(key), list) and all(isinstance(s, str) for s in raw[key]))}
text = lambda key, default: raw[key] if isinstance(raw.get(key), str) else default
out.update(id=text("id", "dashboard"), label=text("label", "Dashboard"),
unit=text("unit", ""), source_table=text("source_table", ""),
value=None, series=[], validated=False, reason=safe_reason(reason))
# Failed evidence cannot carry auxiliary numbers, including comparison or scope counts.
if "change" in raw:
out["change"] = dict(previous=None, absolute=None, percent=None, reason="No comparison data")
out["noPrior"] = True
return out
def _number(value):
try:
return type(value) in (int, float) and math.isfinite(value)
except OverflowError:
return False
def _json_safe(value):
if value is None or isinstance(value, str) or type(value) is bool:
return True
if type(value) in (int, float):
return _number(value)
if isinstance(value, list):
return all(_json_safe(item) for item in value)
if isinstance(value, dict):
return all(isinstance(key, str) and _json_safe(item) for key, item in value.items())
return False
def _point(point):
if not isinstance(point, dict):
return False
x = point.get("x", point.get("date", point.get("label")))
value = point.get("y") if "y" in point else point.get("value")
return (isinstance(x, str) and bool(x) and ("y" in point or "value" in point)
and (value is None or _number(value)) and _json_safe(point))
def well_formed(raw):
if not isinstance(raw, dict) or any(not isinstance(raw.get(key), str) or not raw[key]
for key in ("id", "label", "unit", "source_table")):
return False
value = raw.get("value")
# Dates are semantic values, never numeric strings masquerading as measures.
date_value = False
if raw["unit"] == "date" and isinstance(value, str) and re.fullmatch(r"\d{4}-\d{2}-\d{2}", value):
try:
date_value = date.fromisoformat(value).isoformat() == value
except ValueError:
pass
if not (_number(value) or date_value):
return False
series = raw.get("series")
if not isinstance(series, list):
return False
for part in series:
if isinstance(part, dict) and "points" in part:
if not (isinstance(part.get("key", part.get("id")), str) and isinstance(part.get("label"), str)
and isinstance(part["points"], list) and all(_point(p) for p in part["points"])):
return False
elif not _point(part):
return False
change = raw.get("change")
if change is not None and (not isinstance(change, dict) or any(
change.get(key) is not None and not _number(change[key]) for key in ("previous", "absolute", "percent"))):
return False
return _json_safe({key: value for key, value in raw.items() if key != "validate"})
def _accept(check, identity):
return isinstance(check, dict) and check.get("ok") is True and check.get("id") == identity
def _bind(fn, *args, **kwargs):
if not callable(fn):
return False
try:
inspect.signature(fn).bind(*args, **kwargs)
return True
except (TypeError, ValueError):
return False
def checked_dashboard(module, *, descriptor, tenant, start, end, runtime, options=None):
"""Call the canonical provider and recheck each figure using its public validation contract."""
remaining_budget()
options = dict(options or {})
kwargs = dict(start=start, end=end, st=runtime, **options)
provider = getattr(module, "dashboard", None)
kind = descriptor.get("kind") if isinstance(descriptor, dict) else None
sources = descriptor.get("sources") if isinstance(descriptor, dict) else None
if not _bind(provider, tenant, **kwargs):
return {"figures": [unavailable(reason=ADAPTER)]}
try:
payload = provider(tenant, **kwargs)
except Exception as exc:
raise_if_resource_error(exc)
log_failure(_log, exc, "provider", kind, tenant)
remaining_budget()
return {"figures": [unavailable(reason=plain_cause(exc, "provider", sources))]}
remaining_budget()
rows = payload.get("figures") if isinstance(payload, dict) else None
if not isinstance(rows, list):
return {"figures": [unavailable(reason=ADAPTER)]}
validate = getattr(module, "validate_figure", None)
batch = getattr(module, "validate", None)
batch_checks, batch_reason = None, ADAPTER
batch_args = (tenant,) if _bind(batch, tenant, figures=rows, **kwargs) else (tenant, rows)
batch_kwargs = dict(kwargs, figures=rows) if len(batch_args) == 1 else kwargs
if not callable(validate) and _bind(batch, *batch_args, **batch_kwargs):
try:
evidence = batch(*batch_args, **batch_kwargs)
remaining_budget()
if isinstance(evidence, dict) and evidence.get("ok") is True and isinstance(evidence.get("figures"), list):
batch_checks = evidence["figures"]
except Exception as exc:
raise_if_resource_error(exc)
log_failure(_log, exc, "batch validate", kind, tenant)
batch_reason = plain_cause(exc, "batch validate", sources)
remaining_budget()
out, seen = [], set()
for raw in rows:
remaining_budget()
if not well_formed(raw) or raw["id"] in seen:
out.append(unavailable(raw, safe_reason(raw.get("reason")) if isinstance(raw, dict) else UNAVAILABLE))
continue
identity = raw["id"]
seen.add(identity)
check, reason = None, batch_reason
try:
if _bind(validate, tenant, raw, **kwargs):
check = validate(tenant, raw, **kwargs)
elif _bind(raw.get("validate")):
result = raw["validate"]()
check = {"ok": True, "id": raw["id"]} if result is True else result
elif batch_checks is not None:
matches = [c for c in batch_checks if isinstance(c, dict) and c.get("id") == raw["id"]]
check = matches[0] if len(matches) == 1 else None
remaining_budget()
if check is not None:
reason = safe_reason(check.get("reason")) if isinstance(check, dict) else UNAVAILABLE
except Exception as exc:
raise_if_resource_error(exc)
log_failure(_log, exc, "figure validate", kind, tenant, identity)
remaining_budget()
reason = plain_cause(exc, "figure validate", raw.get("source_table"))
if not _accept(check, identity) or raw.get("id") != identity or not well_formed(raw):
out.append(unavailable(raw, reason))
continue
# Only the module's independently checked payload enters the public envelope.
served = {key: value for key, value in raw.items() if key not in ("validate", "headline")}
served["validated"] = True
served["reason"] = safe_reason(raw.get("reason"), default="") or None
if is_headline(kind, identity):
served["headline"] = True
out.append(served)
envelope = {key: payload[key] for key in ("prior_start", "prior_end", "compare", "basis")
if isinstance(payload.get(key), str)}
return {**envelope, "kind": descriptor["kind"], "start": start, "end": end, "figures": out}