chore(activity-log): scaffold feature plan and phase subplans
This commit is contained in:
@@ -0,0 +1,118 @@
|
||||
# Phase 2: Recorder, actor context, retention, lifecycle
|
||||
|
||||
**Status:** ⬜ Not Started
|
||||
**Parent plan:** [PLAN.md](./PLAN.md)
|
||||
**Domain:** backend
|
||||
|
||||
## Objective
|
||||
|
||||
Build the runtime layer over the Phase 1 repository: a thread-safe `ActivityRecorder` facade
|
||||
that persists an entry AND pushes a live `activity_logged` event; an actor `ContextVar`
|
||||
populated by the auth layer; a background `ActivityLogRetentionEngine` mirroring
|
||||
`AutoBackupEngine`; and the `main.py`/`dependencies.py` wiring (init, DI getter, retention
|
||||
start/stop, shutdown ordering). After this phase the audit log records nothing yet (no call
|
||||
sites) — that is Phase 3 — but the full machinery is live and unit-tested.
|
||||
|
||||
## Tasks
|
||||
|
||||
- [ ] Create `server/src/ledgrab/core/activity_log/__init__.py` and
|
||||
`server/src/ledgrab/core/activity_log/recorder.py`:
|
||||
- `ActivityRecorder(repo: ActivityLogRepository, processor_manager, *, loop=None)`.
|
||||
- `record(category, action, *, severity="info", actor=None, entity_type=None,
|
||||
entity_id=None, entity_name=None, message, metadata=None) -> None`:
|
||||
- resolve `actor` from the actor `ContextVar` when not supplied, default `"system"`;
|
||||
- build an `ActivityLogEntry` (id `al_<uuid8>`, `ts=datetime.now(timezone.utc)`);
|
||||
- **thread-safe write:** if called on the event loop thread, write inline via
|
||||
`repo.record(entry)` then fire the live event; if called from another thread (zeroconf
|
||||
discovery), marshal the whole write+emit onto the loop via
|
||||
`loop.call_soon_threadsafe(...)`. Capture the loop lazily (mirror
|
||||
`utils/log_broadcaster.py:ensure_loop`/`call_soon_threadsafe`). Never raise into the
|
||||
caller — audit recording is best-effort and must not break the audited action; log
|
||||
failures at `warning`.
|
||||
- live push: `processor_manager.fire_event({"type": "activity_logged", "entry": entry_as_dict})`.
|
||||
- Provide a tiny helper to serialize an entry to the same dict shape the API returns
|
||||
(reuse in Phase 4 / frontend).
|
||||
- `enabled` flag honored: when retention settings say `enabled=false`, `record()` is a
|
||||
no-op — EXCEPT the "audit log disabled" event itself, which must be recorded before the
|
||||
flag takes effect (see retention engine).
|
||||
- [ ] Actor `ContextVar`:
|
||||
- Add `current_actor: ContextVar[str]` (module-level, e.g. in `core/activity_log/context.py`
|
||||
or `api/auth.py`). In `verify_api_key` (`api/auth.py`), set it next to the existing
|
||||
`request.state.auth_label = ...` (both the authenticated label and the `"anonymous"`
|
||||
branch). Default `"system"` when unset. Ensure no cross-request leakage (set on every
|
||||
auth evaluation).
|
||||
- [ ] Create `server/src/ledgrab/core/activity_log/retention.py`:
|
||||
- `ActivityLogRetentionEngine(repo, db, recorder)` mirroring `core/backup/auto_backup.py`:
|
||||
`_load_settings()`/`_save_settings()` via `db.get_setting("activity_log")` /
|
||||
`db.set_setting("activity_log", {...})`, `DEFAULT_SETTINGS = {"enabled": True,
|
||||
"max_days": 90, "max_entries": 20000}`.
|
||||
`async start()` → spawn `_retention_loop()` (`asyncio.create_task`); loop sleeps a sane
|
||||
interval (e.g. hourly) then calls `repo.prune(before_ts=now-max_days, max_entries=...)`.
|
||||
`async stop()` → cancel + await task. `get_settings()` / `async update_settings(...)`
|
||||
that persist and apply (changing `enabled` is logged via the recorder BEFORE disabling).
|
||||
- [ ] Wiring:
|
||||
- `main.py`: instantiate `activity_log_repo = ActivityLogRepository(db)` (module level near
|
||||
other stores); in `lifespan` startup build `activity_recorder` + `activity_log_retention_engine`,
|
||||
pass to `init_dependencies(...)`, and `await activity_log_retention_engine.start()`.
|
||||
- In `lifespan` **shutdown**: record a `system` / `server_shutting_down` event via the
|
||||
recorder as the **first** shutdown action (before engines/db close), then
|
||||
`await _bounded("activity_log_retention.stop", activity_log_retention_engine.stop(), timeout=0.5)`.
|
||||
- `api/dependencies.py`: add `activity_recorder` + `activity_log_repo` +
|
||||
`activity_log_retention_engine` to `_deps`, parameters to `init_dependencies`, and
|
||||
getters `get_activity_recorder()`, `get_activity_log_repo()`,
|
||||
`get_activity_log_retention_engine()`.
|
||||
- [ ] Realtime allowlist (order matters — do allowlist FIRST so the parity test stays green):
|
||||
- Add `'activity_logged'` to `_ALLOWED_SERVER_EVENT_TYPES` in
|
||||
`server/src/ledgrab/static/js/core/events-ws.ts` (+ a one-line comment naming the source).
|
||||
- Confirm `tests/test_events_ws_parity.py` passes with the new emit type.
|
||||
- [ ] Unit tests `server/tests/core/test_activity_recorder.py` +
|
||||
`test_activity_log_retention.py`:
|
||||
- recorder persists an entry AND calls `fire_event` with `type=="activity_logged"`;
|
||||
- actor resolves from ContextVar; defaults to `"system"`; failure in repo doesn't raise;
|
||||
- cross-thread `record()` (call from a `threading.Thread`) routes through the loop and persists;
|
||||
- retention prunes per settings; settings round-trip via db; disabling logs the disable event.
|
||||
|
||||
## Files to Modify/Create
|
||||
|
||||
- `server/src/ledgrab/core/activity_log/__init__.py` — new
|
||||
- `server/src/ledgrab/core/activity_log/recorder.py` — new
|
||||
- `server/src/ledgrab/core/activity_log/context.py` — new (actor ContextVar) *(or place in auth.py)*
|
||||
- `server/src/ledgrab/core/activity_log/retention.py` — new
|
||||
- `server/src/ledgrab/api/auth.py` — modify: set actor ContextVar in `verify_api_key`
|
||||
- `server/src/ledgrab/main.py` — modify: instantiate, wire lifespan start/shutdown
|
||||
- `server/src/ledgrab/api/dependencies.py` — modify: `_deps`, `init_dependencies`, getters
|
||||
- `server/src/ledgrab/static/js/core/events-ws.ts` — modify: allowlist `activity_logged`
|
||||
- `server/tests/core/test_activity_recorder.py` — new
|
||||
- `server/tests/core/test_activity_log_retention.py` — new
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Recorder persists + fires `activity_logged`; never raises into callers; thread-safe from
|
||||
non-loop threads.
|
||||
- Actor ContextVar populated by auth; default `"system"`; no cross-request leakage.
|
||||
- Retention engine starts/stops cleanly in lifespan; prunes by age + count; settings persist.
|
||||
- `server_shutting_down` is recorded before teardown; no lost-on-graceful-shutdown entries.
|
||||
- `test_events_ws_parity.py` green (allowlist updated). Existing tests still green; `ruff` clean.
|
||||
|
||||
## Notes
|
||||
|
||||
- Reference: `core/backup/auto_backup.py` (engine shape, settings persistence, `_bounded`
|
||||
shutdown in `main.py`), `utils/log_broadcaster.py` (`ensure_loop`, `call_soon_threadsafe`
|
||||
thread marshaling), `core/processing/processor_manager.py:247` (`fire_event`).
|
||||
- **Do not add any instrumentation call sites in this phase** — only the machinery. Phase 3
|
||||
adds the `record(...)` calls. (Intermediate commit emits nothing; that is fine and green.)
|
||||
- Freeze the `ActivityLogEntry` dict shape here — Phase 4 (API response) and Phase 5
|
||||
(frontend `entry`) consume it.
|
||||
|
||||
## Review Checklist
|
||||
|
||||
- [ ] All tasks completed
|
||||
- [ ] Code follows project conventions (engine/DI patterns)
|
||||
- [ ] No unintended side effects (no call sites yet; lifespan order correct)
|
||||
- [ ] Build passes (ruff + pytest, incl. parity test)
|
||||
- [ ] Tests pass (new + existing)
|
||||
|
||||
## Handoff to Next Phase
|
||||
|
||||
<!-- Filled in by the implementer: final recorder.record(...) signature, the actor ContextVar
|
||||
import path, the frozen entry dict shape, and the DI getter names Phase 3/4 will import. -->
|
||||
Reference in New Issue
Block a user