Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/object_governance.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

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
3There is deliberately no workflow engine here (docs/write-pipeline.md): a
4business process is transitions on records plus reactions that write the
5next record. The objection to that design is legibility -- "without an
6engine, how does anyone SEE the workflow?" -- and this module is the
7answer: **because every kind of rule has exactly one declared home, the
8diagram is compilable.** Transitions and their guards live in the schema;
9gates are named by `hooks.before_write`; reactions declare `HANDLES`
10lists; notifications are `notify_rules` rows; the clock's work is
11scheduler task entries. None of it is arbitrary code hiding in a
12callback, which is precisely why Rails and Django could never draw this
13picture: their workflow existed only as the union of whatever every
14callback happened to do.
15
16Two 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
27Read-only folds; never raises for a missing layer -- an app with no hooks
28simply has no gate rows, which is itself the honest report.
29"""
30
31from __future__ import annotations
32
33import json
34import re
35from pathlib import Path
36from typing import Any, Iterable
37
38import object_namespace
39import object_records
40import object_schemas
41from 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
47def _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
54def _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
61def _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
102def 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
195def 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)