Source code for fleetmesh_node.config.changestore

"""The audit trail: every change, durable, in order.

`announce` says a change happened on a channel, and a channel reaches whatever
backends an operator configured. That is the right way to tell somebody, and
the wrong way to keep a record: if no file backend is configured there is no
trail at all, and an audit trail that depends on how the log was set up is not
an audit trail.

So a change is both announced and stored. The store is the record; the channel
is the notification.

`seq` is explicit and taken from `MAX(seq) + 1` under the store lock, for the
reason `grants.history` does the same: auto-increment is spelled differently
by the two backends and SQLite cannot add one with ALTER TABLE, while `rowid`
does not exist on PostgreSQL at all. Order matters here more than it does for
grants - "who changed it last" is the question an audit trail is for - so it
is a column and not an accident of storage.

`DURABILITY = 'commit'`: a change must be on disk before the call returns. The
window class would let a batch sit in memory, and the one record you cannot
afford to lose to a crash is the one that says what somebody just did.
"""
from __future__ import annotations

import json
from typing import Any, Optional, Sequence, TypedDict

from ..compartment.schema import Column, Index, Table
from ..storage import SqliteStore
from .change import Change


[docs]class ChangeRow(TypedDict): """One stored change, as an operator reads it back. A named record for the reason check-dicts.py enforces it: an audit row is read by field name, and this is the row. """ seq: int at: int resource: str was: Any now: Any source: str operator: str session: str tool: str assurance: str verified: bool conflicts: list[str] proofs: list[Any]
[docs]class TrailState(TypedDict): """How much trail there is, and how much of it nobody owns.""" changes: int last_seq: int unattributed: int unverified: int conflicted: int
[docs]class ChangeStore(SqliteStore): """Config changes, newest last by `seq`.""" DURABILITY = 'commit' SCHEMA = ( Table('changes', ( Column('seq', 'INTEGER', primary_key=True), Column('at', 'INTEGER', not_null=True), Column('resource', 'TEXT', not_null=True), Column('was', 'TEXT'), Column('now', 'TEXT'), Column('source', 'TEXT', not_null=True), Column('operator', 'TEXT', not_null=True), Column('session', 'TEXT', not_null=True), Column('tool', 'TEXT', not_null=True), Column('assurance', 'TEXT', not_null=True), Column('verified', 'INTEGER', not_null=True), Column('conflicts', 'TEXT', not_null=True), Column('proofs', 'TEXT', not_null=True), ), indices=( # The three questions an operator asks of an audit trail: what changed # on this setting, what did this person change, and what did that one # run do. Index('changes_resource', ('resource', 'seq')), Index('changes_operator', ('operator', 'seq')), Index('changes_session', ('session', 'seq')), )), ) def _next_seq(self) -> int: """The next record number. Every caller holds the store lock, so the read-then-write cannot race.""" row = self._one('SELECT COALESCE(MAX(seq), 0) + 1 FROM changes') return int(row[0]) if row and row[0] is not None else 1
[docs] def put(self, change: Change) -> int: """Store one change and return its seq. The values go through `Change.describe()`, so a secret is already redacted by the time it reaches a row: an audit trail that records the wallet URI it just rotated has published it to everyone who can read the database. """ rec = change.describe() act = change.actor with self.transaction() as cur: seq = self._next_seq() cur.execute( 'INSERT INTO changes (seq, at, resource, was, now, source, operator, session, ' 'tool, assurance, verified, conflicts, proofs) ' 'VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)', (seq, int(act.at), rec['resource'], json.dumps(rec['was']), json.dumps(rec['now']), rec['source'], act.operator, act.session, act.tool, act.assurance or '', 1 if act.verified else 0, json.dumps(act.conflicts()), json.dumps([p.describe() for p in act.proofs]))) return seq
def _rows(self, where: str, args: Sequence[Any], limit: int) -> list[ChangeRow]: rows = self._all( 'SELECT seq, at, resource, was, now, source, operator, session, tool, ' 'assurance, verified, conflicts, proofs FROM changes ' + where + ' ORDER BY seq DESC LIMIT ?', tuple(args) + (int(limit),)) out: list[ChangeRow] = [] for r in rows: row: ChangeRow = { 'seq': int(r[0]), 'at': int(r[1]), 'resource': r[2], 'was': json.loads(r[3]) if r[3] is not None else None, 'now': json.loads(r[4]) if r[4] is not None else None, 'source': r[5], 'operator': r[6] or '(unknown)', 'session': r[7], 'tool': r[8], 'assurance': r[9] or '(none)', 'verified': bool(r[10]), 'conflicts': json.loads(r[11] or '[]'), 'proofs': json.loads(r[12] or '[]'), } out.append(row) return out
[docs] def recent(self, limit: int = 50) -> list[ChangeRow]: """Newest first, which is the order the question is usually asked in.""" return self._rows('', (), limit)
[docs] def of_resource(self, resource: str, limit: int = 50) -> list[ChangeRow]: """What changed on one setting. 'who last touched this' lives here.""" return self._rows('WHERE resource = ?', (resource,), limit)
[docs] def of_operator(self, operator: str, limit: int = 50) -> list[ChangeRow]: return self._rows('WHERE operator = ?', (operator,), limit)
[docs] def of_session(self, session: str, limit: int = 200) -> list[ChangeRow]: """One run of one tool. A dozen changes from one `meshctl apply` are one act, and this is what makes them readable as one.""" return self._rows('WHERE session = ?', (session,), limit)
[docs] def unattributed(self, limit: int = 50) -> list[ChangeRow]: """Changes with nobody named. The thing to watch on a node several people manage.""" return self._rows("WHERE operator = ''", (), limit)
[docs] def unverified(self, limit: int = 50) -> list[ChangeRow]: """Changes whose author was claimed but never proved. Separate from unattributed, because 'said they were X' and 'said nothing' are different and only one of them is a policy violation worth chasing.""" return self._rows('WHERE verified = 0', (), limit)
[docs] def conflicted(self, limit: int = 50) -> list[ChangeRow]: """Changes where two rungs named different subjects.""" return self._rows("WHERE conflicts <> '[]'", (), limit)
[docs] def state(self) -> TrailState: """For the health block: how much trail there is and how much of it nobody owns.""" row = self._one('SELECT COUNT(*), COALESCE(MAX(seq), 0) FROM changes') total, last = (int(row[0]), int(row[1])) if row else (0, 0) un = self._one("SELECT COUNT(*) FROM changes WHERE operator = ''") nv = self._one('SELECT COUNT(*) FROM changes WHERE verified = 0') cf = self._one("SELECT COUNT(*) FROM changes WHERE conflicts <> '[]'") out: TrailState = {'changes': total, 'last_seq': last, 'unattributed': int(un[0]) if un else 0, 'unverified': int(nv[0]) if nv else 0, 'conflicted': int(cf[0]) if cf else 0} return out
[docs]def record(store: Optional[ChangeStore], log: Any, change: Change) -> Optional[int]: """Store the change, then announce it. Stored first on purpose. The announcement is a notification and may go nowhere an operator kept; the row is the record, and a crash between the two should lose the telling rather than the evidence. """ from . import change as change_mod # noqa: PLC0415 (avoids a cycle) seq = store.put(change) if store is not None else None change_mod.announce(log, change) return seq
__all__ = ['ChangeStore', 'ChangeRow', 'TrailState', 'record']