"""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}