askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
object_governance.py · 10.8 KB · 258 lines
| 1 | """What governs a collection -- and the workflow diagram, compiled. |
| 2 | |
| 3 | There is deliberately no workflow engine here (docs/write-pipeline.md): a |
| 4 | business process is transitions on records plus reactions that write the |
| 5 | next record. The objection to that design is legibility -- "without an |
| 6 | engine, how does anyone SEE the workflow?" -- and this module is the |
| 7 | answer: **because every kind of rule has exactly one declared home, the |
| 8 | diagram is compilable.** Transitions and their guards live in the schema; |
| 9 | gates are named by `hooks.before_write`; reactions declare `HANDLES` |
| 10 | lists; notifications are `notify_rules` rows; the clock's work is |
| 11 | scheduler task entries. None of it is arbitrary code hiding in a |
| 12 | callback, which is precisely why Rails and Django could never draw this |
| 13 | picture: their workflow existed only as the union of whatever every |
| 14 | callback happened to do. |
| 15 | |
| 16 | Two outputs, one truth: |
| 17 | |
| 18 | - ``governs(collection)`` -- the placement table for one collection, live: |
| 19 | every declaration, gate, reaction, notification and schedule that will |
| 20 | touch a write, with where each lives. "Why did my record change?" as a |
| 21 | data structure. |
| 22 | - ``workflow_mermaid(collection)`` -- the state machine plus the |
| 23 | cross-collection reaction edges, as Mermaid source. Text on purpose: |
| 24 | it renders in the docs, in GitHub, in the shell, and in any tool that |
| 25 | speaks Mermaid, and it diffs in the change log like everything else. |
| 26 | |
| 27 | Read-only folds; never raises for a missing layer -- an app with no hooks |
| 28 | simply has no gate rows, which is itself the honest report. |
| 29 | """ |
| 30 | |
| 31 | from __future__ import annotations |
| 32 | |
| 33 | import json |
| 34 | import re |
| 35 | from pathlib import Path |
| 36 | from typing import Any, Iterable |
| 37 | |
| 38 | import object_namespace |
| 39 | import object_records |
| 40 | import object_schemas |
| 41 | from object_versions import DEFAULT_DATA_DIR |
| 42 | |
| 43 | _HANDLES_RE = re.compile(r"^HANDLES\s*=\s*(\[.*?\])", re.MULTILINE | re.DOTALL) |
| 44 | _EVENT_RE = re.compile(r"^([a-z0-9_]+)\.record\.(created|updated|deleted)$") |
| 45 | |
| 46 | |
| 47 | def _safe_records(collection: str, base_dir) -> list[dict]: |
| 48 | try: |
| 49 | return object_records.read_collection_records(collection, base_dir=base_dir) |
| 50 | except Exception: |
| 51 | return [] |
| 52 | |
| 53 | |
| 54 | def _schema(collection: str, base_dir) -> dict | None: |
| 55 | try: |
| 56 | return object_schemas.get_schema(collection, base_dir=base_dir) |
| 57 | except Exception: |
| 58 | return None |
| 59 | |
| 60 | |
| 61 | def _handler_index(roots: Iterable[Path] | None = None) -> list[dict]: |
| 62 | """Every HANDLES declaration across the object roots. |
| 63 | |
| 64 | Parsed from source with a regex rather than imported: an index must |
| 65 | never execute the objects it is indexing, and a module-level HANDLES |
| 66 | list is by convention a literal (the same convention the real |
| 67 | dispatcher relies on). |
| 68 | """ |
| 69 | out = [] |
| 70 | for root in (list(roots) if roots is not None else object_namespace.get_object_roots()): |
| 71 | root = Path(root) |
| 72 | if not root.exists(): |
| 73 | continue |
| 74 | for path in sorted(root.rglob("*.py")): |
| 75 | try: |
| 76 | source = path.read_text(encoding="utf-8", errors="replace") |
| 77 | except OSError: |
| 78 | continue |
| 79 | match = _HANDLES_RE.search(source) |
| 80 | if not match: |
| 81 | continue |
| 82 | raw = match.group(1).replace("'", '"') |
| 83 | raw = re.sub(r",\s*\]", "]", raw) # Python allows a trailing comma; JSON does not |
| 84 | try: |
| 85 | events = json.loads(raw) |
| 86 | except (ValueError, TypeError): |
| 87 | continue |
| 88 | try: |
| 89 | object_id = object_namespace.object_id_from_path(path, root) |
| 90 | except ValueError: |
| 91 | continue |
| 92 | parsed = [] |
| 93 | for event in events: |
| 94 | m = _EVENT_RE.match(str(event)) |
| 95 | if m: |
| 96 | parsed.append({"collection": m.group(1), "action": m.group(2)}) |
| 97 | if parsed: |
| 98 | out.append({"object_id": object_id, "events": parsed, "path": str(path)}) |
| 99 | return out |
| 100 | |
| 101 | |
| 102 | def governs(collection: str, *, base_dir=DEFAULT_DATA_DIR, |
| 103 | roots: Iterable[Path] | None = None) -> dict[str, Any]: |
| 104 | """The live placement table for one collection. |
| 105 | |
| 106 | Returns {"collection", "declarations", "gates", "reactions", |
| 107 | "notifications", "schedules", "views"} -- each entry naming WHAT the |
| 108 | rule is and WHERE it lives, which is the whole point: the seven layers |
| 109 | that may act on a write, answered in one call instead of seven files. |
| 110 | """ |
| 111 | schema = _schema(collection, base_dir) or {} |
| 112 | fields = schema.get("fields", []) |
| 113 | |
| 114 | declarations: dict[str, Any] = { |
| 115 | "required": [f["name"] for f in fields if f.get("required")], |
| 116 | "enums": {f["name"]: f["enum"] for f in fields if f.get("enum")}, |
| 117 | "relations": {f["name"]: f["relation"]["collection"] |
| 118 | for f in fields if isinstance(f.get("relation"), dict)}, |
| 119 | "formulas": {f["name"]: f["formula"] for f in fields if f.get("formula")}, |
| 120 | "rollups": {f["name"]: f["rollup"] for f in fields if f.get("rollup")}, |
| 121 | "transitions": {}, |
| 122 | } |
| 123 | for field in fields: |
| 124 | if not field.get("transitions"): |
| 125 | continue |
| 126 | moves = {} |
| 127 | for state, targets in field["transitions"].items(): |
| 128 | normalized = [] |
| 129 | for target in targets: |
| 130 | if isinstance(target, dict): |
| 131 | normalized.append({"to": target.get("to"), |
| 132 | "when": target.get("when") or None}) |
| 133 | else: |
| 134 | normalized.append({"to": target, "when": None}) |
| 135 | moves[state] = normalized |
| 136 | declarations["transitions"][field["name"]] = moves |
| 137 | |
| 138 | hook_id = (schema.get("hooks") or {}).get("before_write") |
| 139 | gates = [{"kind": "before_write_hook", "object_id": hook_id, |
| 140 | "note": "fails closed; runs before validation on every create/update"}] if hook_id else [] |
| 141 | |
| 142 | reactions, feeds = [], [] |
| 143 | for handler in _handler_index(roots): |
| 144 | for event in handler["events"]: |
| 145 | if event["collection"] == collection: |
| 146 | reactions.append({"object_id": handler["object_id"], |
| 147 | "on": event["action"]}) |
| 148 | # the other direction: which collections' handlers THIS collection's |
| 149 | # composers feed is visible in live data via generated_from provenance |
| 150 | for row in _safe_records("fin_journals", base_dir): |
| 151 | src = str(row.get("generated_from") or "") |
| 152 | if src.startswith(f"{collection}/"): |
| 153 | feeds.append("fin_journals") |
| 154 | break |
| 155 | |
| 156 | notifications = [ |
| 157 | {"rule_id": r.get("id"), "event": r.get("event_pattern"), |
| 158 | "recipients": r.get("recipients")} |
| 159 | for r in _safe_records("notify_rules", base_dir) |
| 160 | if str(r.get("event_pattern") or "").startswith(f"{collection}.") |
| 161 | ] |
| 162 | |
| 163 | schedules = [] |
| 164 | try: |
| 165 | state = __import__("object_state").get_object_state("scheduler", base_dir) |
| 166 | for key, value in state.items(): |
| 167 | if not key.startswith("task_"): |
| 168 | continue |
| 169 | try: |
| 170 | task = json.loads(value) |
| 171 | except (ValueError, TypeError): |
| 172 | continue |
| 173 | schedules.append({"task": task.get("id"), "runs": task.get("object_id"), |
| 174 | "schedule": task.get("schedule"), |
| 175 | "status": task.get("status")}) |
| 176 | except Exception: |
| 177 | pass |
| 178 | |
| 179 | views = [{"view": r.get("id"), "route": r.get("route")} |
| 180 | for r in _safe_records("views", base_dir) |
| 181 | if collection in str(r.get("blocks") or "")] |
| 182 | |
| 183 | return { |
| 184 | "collection": collection, |
| 185 | "declarations": declarations, |
| 186 | "gates": gates, |
| 187 | "reactions": sorted(reactions, key=lambda r: (r["object_id"], r["on"])), |
| 188 | "feeds": sorted(set(feeds)), |
| 189 | "notifications": notifications, |
| 190 | "schedules": schedules, |
| 191 | "views": views, |
| 192 | } |
| 193 | |
| 194 | |
| 195 | def workflow_mermaid(collection: str, *, base_dir=DEFAULT_DATA_DIR, |
| 196 | roots: Iterable[Path] | None = None) -> str: |
| 197 | """The collection's workflow as Mermaid source: the declared state |
| 198 | machine, guard labels, the gate, and every reaction edge. |
| 199 | |
| 200 | Compiled, not drawn: change a transition or install a handler and the |
| 201 | next render shows it. A diagram that is generated from the same |
| 202 | declarations the server enforces cannot drift from the truth -- which |
| 203 | is the failing of every hand-maintained workflow picture. |
| 204 | """ |
| 205 | info = governs(collection, base_dir=base_dir, roots=roots) |
| 206 | lines = ["flowchart LR"] |
| 207 | |
| 208 | transitions = info["declarations"]["transitions"] |
| 209 | if transitions: |
| 210 | field, moves = next(iter(transitions.items())) |
| 211 | states = sorted({s for s in moves} | |
| 212 | {t["to"] for targets in moves.values() for t in targets if t["to"]}) |
| 213 | lines.append(f' subgraph {collection}["{collection}.{field}"]') |
| 214 | for state in states: |
| 215 | lines.append(f' {collection}_{state}(["{state}"])') |
| 216 | for state, targets in moves.items(): |
| 217 | for target in targets: |
| 218 | if not target["to"]: |
| 219 | continue |
| 220 | label = "" |
| 221 | if target["when"]: |
| 222 | conds = ", ".join(f"{k}={v}" for k, v in target["when"].items()) |
| 223 | label = f'|"{conds}"|' |
| 224 | lines.append(f" {collection}_{state} -->{label} {collection}_{target['to']}") |
| 225 | lines.append(" end") |
| 226 | else: |
| 227 | lines.append(f' {collection}[("{collection}")]') |
| 228 | |
| 229 | # Edges attach to the subgraph id (the collection) so the picture stays |
| 230 | # readable: gates guard the whole write surface, reactions fire on the |
| 231 | # whole collection, not on one state. |
| 232 | anchor = collection |
| 233 | |
| 234 | for gate in info["gates"]: |
| 235 | lines.append(f' {gate["object_id"]}{{{{"gate: {gate["object_id"]}"}}}}') |
| 236 | lines.append(f' {gate["object_id"]} -.->|"before every write"| {anchor}') |
| 237 | declared = set() |
| 238 | for reaction in info["reactions"]: |
| 239 | node = reaction["object_id"] |
| 240 | if node not in declared: |
| 241 | lines.append(f' {node}[/"{node}"/]') |
| 242 | declared.add(node) |
| 243 | lines.append(f' {anchor} -->|"on {reaction["on"]}"| {node}') |
| 244 | for fed in info["feeds"]: |
| 245 | lines.append(f' {fed}[("{fed}")]') |
| 246 | lines.append(f' {anchor} ==>|"composes (generated_from)"| {fed}') |
| 247 | for note in info["notifications"]: |
| 248 | rid = re.sub(r"\W", "_", str(note["rule_id"] or "notify")) |
| 249 | lines.append(f' n_{rid}>"notify: {note["event"]}"]') |
| 250 | lines.append(f' {anchor} -.-> n_{rid}') |
| 251 | # Scheduled runners that react to this collection get a clock edge, so |
| 252 | # "time does this" is visible in the same picture as "writes do this". |
| 253 | reaction_ids = {r["object_id"] for r in info["reactions"]} |
| 254 | for task in info["schedules"]: |
| 255 | if task.get("runs") in reaction_ids: |
| 256 | lines.append(f' clock_{task["task"]}(("{task["schedule"]}"))') |
| 257 | lines.append(f' clock_{task["task"]} -.-> {task["runs"]}') |
| 258 | return "\n".join(lines) |