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_activity.py · 7.1 KB · 167 lines
| 1 | """Activity feed -- a fold over the record-change ledger, not a new event system. |
| 2 | |
| 3 | Every create/update/delete already flows through |
| 4 | ``object_record_changes.append_record_change`` (called from |
| 5 | object_records.py's create/update/delete paths), which durably appends |
| 6 | actor, action, collection, record_id, and before/after snapshots to one |
| 7 | JSONL log per collection: ``data/record_changes/{collection}/changes.jsonl``. |
| 8 | |
| 9 | ``recent_activity`` reads those logs across every collection that has one, |
| 10 | merges them newest-first, and derives a human title from each change's |
| 11 | snapshot. "actor ACTION collection title" is exactly the shape of a classic |
| 12 | content activity feed, and it required no new storage and no new write path |
| 13 | -- universal attribution already recorded everything a feed needs. |
| 14 | """ |
| 15 | |
| 16 | from __future__ import annotations |
| 17 | |
| 18 | from datetime import datetime, timezone |
| 19 | from pathlib import Path |
| 20 | from typing import Any, Iterable |
| 21 | |
| 22 | import object_collections |
| 23 | import object_record_changes |
| 24 | from object_versions import DEFAULT_DATA_DIR |
| 25 | |
| 26 | # Internal/system collections that would drown out real user activity in a |
| 27 | # feed meant to answer "what did people do": shell scrollback and AI usage/ |
| 28 | # billing counters today, and (as they show up) any rate-limit- or |
| 29 | # ops-bookkeeping-style collection whose writes aren't something a person |
| 30 | # did. Extend this set rather than filtering ad hoc per call site. |
| 31 | EXCLUDED_COLLECTIONS = frozenset({ |
| 32 | "shell_commands", |
| 33 | "ai_usage", |
| 34 | # Derived collections. A rollup rewriting its own output is not |
| 35 | # something a person did, and a feed of "what happened" that is 99% |
| 36 | # machine churn is a feed nobody can read. These are also, by a wide |
| 37 | # margin, the largest change logs on a busy server -- one of them |
| 38 | # reached 944MB while the collection it describes held 1818 rows -- |
| 39 | # because a rewrite appends an entry per row, every pass, forever. |
| 40 | "analytics_top_paths", |
| 41 | "analytics_top_ips", |
| 42 | "analytics_status", |
| 43 | "analytics_daily", |
| 44 | "page_views", |
| 45 | "attention_counts", |
| 46 | }) |
| 47 | |
| 48 | # First present of these fields on the change's snapshot becomes the feed |
| 49 | # row's title; record_id is the final fallback so every entry always has |
| 50 | # something to show. |
| 51 | _TITLE_FIELDS = ("title", "name", "number", "subject", "body", "content", "comment", "message") |
| 52 | # Text-shaped fallback fields (body/content/...) can be long; a feed row wants |
| 53 | # a glance, not a paragraph, so they're truncated. Named/numbered fields are |
| 54 | # already short and shown whole. |
| 55 | _TITLE_TEXT_FIELDS = frozenset({"body", "content", "comment", "message"}) |
| 56 | _TITLE_MAX = 80 |
| 57 | |
| 58 | |
| 59 | def recent_activity( |
| 60 | *, |
| 61 | base_dir: Path | str = DEFAULT_DATA_DIR, |
| 62 | actor: str | None = None, |
| 63 | limit: int = 50, |
| 64 | roots: Iterable[Path] | None = None, |
| 65 | ) -> list[dict[str, Any]]: |
| 66 | """Return up to `limit` record-change entries across collections, newest first. |
| 67 | |
| 68 | Each entry is shaped ``{actor, action, collection, record_id, title, |
| 69 | timestamp}`` -- never the full before/after snapshot. A feed is a |
| 70 | signal, not a data dump. |
| 71 | |
| 72 | Scoping (v1): when `actor` is given, only entries whose actor matches |
| 73 | are returned -- the classic "your activity" feed (e.g. "dan CREATED |
| 74 | NOTE ... 2m ago" for dan's own changes across every collection). Every |
| 75 | entry here is guaranteed visible to that actor because they made the |
| 76 | change, so this sidesteps per-entry permission checks entirely. |
| 77 | |
| 78 | Deferred: a broader "activity on anything I can see" feed -- changes by |
| 79 | *other* actors, filtered per record against the viewer's read access -- |
| 80 | needs the permission engine's row filters threaded through here (see |
| 81 | plan/vocabulary/23-activity-spec.md's per-collection/per-record feeds). |
| 82 | That is real work (a read-policy check per candidate entry) and is not |
| 83 | attempted by this function. |
| 84 | |
| 85 | `roots` mirrors object_collections.list_collections's signature for |
| 86 | symmetry; it is unused here because record-change logs live entirely |
| 87 | under `base_dir` and don't depend on which object source roots are |
| 88 | mounted. |
| 89 | """ |
| 90 | if limit < 1: |
| 91 | raise ValueError("limit must be at least 1") |
| 92 | |
| 93 | entries: list[dict[str, Any]] = [] |
| 94 | for collection in _collections_with_changes(base_dir=base_dir): |
| 95 | if collection in EXCLUDED_COLLECTIONS: |
| 96 | continue |
| 97 | # Reads each collection's whole change log (list_record_changes |
| 98 | # loads the full JSONL regardless of `limit`) -- fine at current |
| 99 | # scale, where these logs are small. A real tail-read (seek to the |
| 100 | # last N lines instead of parsing the whole file) is future work |
| 101 | # if/when logs grow large; requesting the module's own max here |
| 102 | # avoids clipping an actor's older entries out of an otherwise |
| 103 | # chatty collection before the actor filter below gets to see them. |
| 104 | payload = object_record_changes.list_record_changes( |
| 105 | collection, |
| 106 | base_dir=base_dir, |
| 107 | limit=object_record_changes.MAX_CHANGE_LIMIT, |
| 108 | # Tail-read: a feed wants the newest entries, and this loop |
| 109 | # visits EVERY collection's log. Parsing each in full made the |
| 110 | # page cost the whole history of the server -- a gigabyte of |
| 111 | # JSON on one core, and a page that never finished loading. |
| 112 | tail_only=True, |
| 113 | ) |
| 114 | for change in payload["changes"]: |
| 115 | if actor is not None and change.get("actor") != actor: |
| 116 | continue |
| 117 | entries.append(_feed_entry(change)) |
| 118 | |
| 119 | entries.sort(key=lambda entry: _sort_key(entry["timestamp"]), reverse=True) |
| 120 | return entries[:limit] |
| 121 | |
| 122 | |
| 123 | def _feed_entry(change: dict[str, Any]) -> dict[str, Any]: |
| 124 | return { |
| 125 | "actor": change.get("actor"), |
| 126 | "action": change.get("action"), |
| 127 | "collection": change.get("collection"), |
| 128 | "record_id": change.get("record_id"), |
| 129 | "title": _derive_title(change), |
| 130 | "timestamp": change.get("timestamp"), |
| 131 | } |
| 132 | |
| 133 | |
| 134 | def _derive_title(change: dict[str, Any]) -> str: |
| 135 | # Deletes have no `after`; fall back to the last-known `before`. |
| 136 | snapshot = change.get("after") or change.get("before") or {} |
| 137 | for field in _TITLE_FIELDS: |
| 138 | value = snapshot.get(field) |
| 139 | if value: |
| 140 | text = str(value) |
| 141 | if field in _TITLE_TEXT_FIELDS and len(text) > _TITLE_MAX: |
| 142 | text = text[:_TITLE_MAX].rstrip() + "…" |
| 143 | return text |
| 144 | return str(change.get("record_id") or "") |
| 145 | |
| 146 | |
| 147 | def _sort_key(timestamp: Any) -> datetime: |
| 148 | try: |
| 149 | return datetime.fromisoformat(str(timestamp)) |
| 150 | except ValueError: |
| 151 | # Malformed timestamp: sort it oldest rather than crash the whole |
| 152 | # feed over one bad entry. |
| 153 | return datetime.min.replace(tzinfo=timezone.utc) |
| 154 | |
| 155 | |
| 156 | def _collections_with_changes(*, base_dir: Path | str) -> list[str]: |
| 157 | """Return every collection name with a record_changes log on disk.""" |
| 158 | root = Path(base_dir) / object_record_changes.RECORD_CHANGES_DIR |
| 159 | if not root.exists() or not root.is_dir(): |
| 160 | return [] |
| 161 | |
| 162 | names = [] |
| 163 | for path in sorted(root.glob(f"*/{object_record_changes.CHANGES_FILE}")): |
| 164 | name = path.parent.name |
| 165 | if object_collections.validate_collection_name(name): |
| 166 | names.append(name) |
| 167 | return names |