Source code for fleetmesh_node.storage.grants

"""Grants on disk: the ones this node issued and the ones it holds.

One SQLite table, one row per (peer, direction). The payload is the grant as
decrypted or as written, the envelope id is the kind 30801 that committed to
it, and status is live or revoked. A node that restarts must know exactly
what it granted and what it was granted, or its receipts are fiction.

Two more tables came from the two-machine run. `history` keeps every grant a
pair has been under and the epoch from which it governed, because a window is
priced under the grant that governed it and not under whatever grant happens
to be current when the grace period ends. `pending` holds the grant a window
evaluation decided on until the next window boundary, because a grant that
changes mid-window changes what a receipt in flight means: the issuer was
rejecting every receipt naming the grant it had just replaced, and the
subject was restarting its chain at seq 0 on the grant it had just taken up,
so every amend filed an S2 misreport against an honest node. An amend now
takes effect at a boundary, as the specification's grant loop says: the
verdict on one window shapes "the next window's grant".
"""
from __future__ import annotations

import builtins
import json
import time
from typing import Any, Literal, Mapping, Optional

from ..compartment.schema import Column, Migration, Table
from . import SqliteStore
from fleetmesh_core.wire.interfaces import EventLike, GrantPayload
from fleetmesh_core.wire.wire_types import GoverningRow, GrantListRow, GrantRow, HistoryRow, PendingRow

GrantDirection = Literal['issued', 'received']
ISSUED: GrantDirection = 'issued'
RECEIVED: GrantDirection = 'received'


[docs]class GrantStore(SqliteStore): SCHEMA = ( Table('grants', ( Column('peer', 'TEXT', not_null=True), Column('direction', 'TEXT', not_null=True), Column('envelope_id', 'TEXT', not_null=True), Column('payload', 'TEXT', not_null=True), Column('tier', 'TEXT', not_null=True), Column('status', 'TEXT', not_null=True, default="'live'"), Column('updated_at', 'INTEGER', not_null=True), ), primary_key=('peer', 'direction')), Table('history', ( Column('peer', 'TEXT', not_null=True), Column('direction', 'TEXT', not_null=True), Column('envelope_id', 'TEXT', not_null=True), Column('payload', 'TEXT', not_null=True), Column('effective_epoch', 'INTEGER', not_null=True), Column('put_at', 'INTEGER', not_null=True), ), primary_key=('peer', 'direction', 'envelope_id')), Table('pending', ( Column('peer', 'TEXT', primary_key=True), Column('payload', 'TEXT', not_null=True), Column('note', 'TEXT'), Column('severity', 'TEXT'), Column('decided_epoch', 'INTEGER', not_null=True), )), Table('seeds', ( Column('peer', 'TEXT', primary_key=True), Column('tier', 'TEXT', not_null=True), Column('at', 'INTEGER', not_null=True), )), ) MIGRATIONS = ( # The envelope's own created_at, which is what NIP-01 supersedes on. A # grant is only ever superseded forwards, so this is how a node refuses # an amend that arrived out of order. Migration(1, up='ALTER TABLE grants ADD COLUMN env_created_at INTEGER', name='grants_env_created_at'), # The signed kind 30801 itself, not only its id. A grant is addressable # under a blinded tag, so each new one replaces the last at that # coordinate and no relay serves the superseded one - and a report # about a past window cites exactly that. A report carries its own # copy now, which it can only do if this node kept it. Migration(2, up='ALTER TABLE history ADD COLUMN event TEXT', name='history_event'), # Insertion order, carried explicitly. `history` ordered by # (effective_epoch, put_at, rowid) and rowid is SQLite's implicit # insertion counter, which PostgreSQL has no equivalent for - ctid is a # physical location, not insertion order, and moves when a row is # updated. Two grants for one peer and direction written in the same # second at the same epoch tie on everything else, and which one won # decided which grant governed the window - the record a peer's # standing is read from. So the tiebreaker becomes a column. Migration(3, up='ALTER TABLE history ADD COLUMN seq INTEGER NOT NULL DEFAULT 0', name='history_seq'), ) def _next_seq(self, peer: str, direction: str) -> int: """The next insertion number for this peer and direction. Explicit rather than an auto-increment, because the two backends spell that differently and SQLite cannot add one with ALTER TABLE. Every caller holds the store lock, so the read-then-write cannot race. """ row = self._one('SELECT COALESCE(MAX(seq), 0) + 1 FROM history ' 'WHERE peer=? AND direction=?', (peer, direction)) return int(row[0]) if row and row[0] is not None else 1 def _post_schema(self) -> None: # Rows written before `seq` existed get their insertion order from the # backend's own, where it has one. SQLite's is `rowid`; PostgreSQL has # none - `ctid` is a physical location, not insertion order, and moves # when a row is updated - but a PostgreSQL store is new, so its history # is empty and there is nothing to carry over. `WHERE seq = 0` makes # this run once: `_next_seq` starts at 1, so a row it numbered is never # mistaken for one that needs numbering. expr = getattr(self.dialect, 'rowid_expr', None) if expr and self.has_column('history', 'seq'): self.execute('UPDATE history SET seq = %s WHERE seq = 0' % expr) # A store from before history existed: whatever it holds now has # governed since the beginning of time, as far as it can tell. for peer, direction, env, payload, updated_at in self._all( 'SELECT peer, direction, envelope_id, payload, updated_at FROM grants'): if self._one('SELECT 1 FROM history WHERE peer=? AND direction=?', (peer, direction)) is None: self.execute( 'INSERT OR IGNORE INTO history ' '(peer, direction, envelope_id, payload, effective_epoch, put_at, event, seq) ' 'VALUES (?,?,?,?,?,?,NULL,?)', (peer, direction, env, payload, 0, updated_at, self._next_seq(peer, direction)))
[docs] def put( self, peer: str, direction: GrantDirection, payload: GrantPayload | Mapping[str, Any], envelope_id: str, now: Optional[int] = None, env_created_at: Optional[int] = None, effective_epoch: Optional[int] = None, event: Optional[EventLike] = None, ) -> None: """Record a grant. effective_epoch is the first window it governs; a caller that does not say gets the window `now` falls in.""" if direction not in (ISSUED, RECEIVED): raise ValueError('direction is issued or received') now = int(now or time.time()) if effective_epoch is None: effective_epoch = now // (payload.get('window') or 3600) with self._lock: if env_created_at is not None: held = self._one('SELECT env_created_at, envelope_id FROM grants WHERE peer=? AND direction=?', (peer, direction)) if held and held[0] is not None and (env_created_at, envelope_id) < (held[0], held[1]): # A grant is only superseded forwards, in the order a relay # resolves the coordinate: latest created_at, lower id on a # tie. Two written for one subject by two threads were put # in the other order, and the issuer then held the one the # relay had let go. The history still records it. self.execute( 'INSERT OR REPLACE INTO history ' '(peer, direction, envelope_id, payload, effective_epoch, put_at, event, seq) ' 'VALUES (?,?,?,?,?,?,?,?)', (peer, direction, envelope_id, json.dumps(payload, sort_keys=True), int(effective_epoch), now, json.dumps(event, sort_keys=True) if event is not None else None, self._next_seq(peer, direction))) self.db.commit() return self.execute('INSERT OR REPLACE INTO grants VALUES (?,?,?,?,?,?,?,?)', (peer, direction, envelope_id, json.dumps(payload, sort_keys=True), payload.get('tier', ''), 'revoked' if payload.get('tier') == 'revoked' else 'live', now, env_created_at)) self.execute( 'INSERT OR REPLACE INTO history ' '(peer, direction, envelope_id, payload, effective_epoch, put_at, event, seq) ' 'VALUES (?,?,?,?,?,?,?,?)', (peer, direction, envelope_id, json.dumps(payload, sort_keys=True), int(effective_epoch), now, json.dumps(event, sort_keys=True) if event is not None else self.envelope_event(peer, direction, envelope_id, as_json=True), self._next_seq(peer, direction))) self.db.commit()
[docs] def governing(self, peer: str, direction: GrantDirection, epoch: int) -> Optional[GoverningRow]: """The grant that governed one window: the latest one effective at or before it. Two written in the same second tie on put_at, so insertion order breaks the tie: a grant is only superseded forwards. Falls back to the current row, so a store that predates the history still answers.""" with self._lock: row = self._one( 'SELECT payload, envelope_id, effective_epoch FROM history WHERE peer=? AND direction=? ' 'AND effective_epoch<=? ORDER BY effective_epoch DESC, put_at DESC, seq DESC LIMIT 1', (peer, direction, int(epoch))) if row is None: # a window before the first grant: the first grant is the nearest answer row = self._one( 'SELECT payload, envelope_id, effective_epoch FROM history WHERE peer=? AND direction=? ' 'ORDER BY effective_epoch, put_at, seq LIMIT 1', (peer, direction)) if row: return {'payload': json.loads(row[0]), 'envelope_id': row[1], 'effective_epoch': row[2]} cur = self.get(peer, direction) if cur is None: return None return {'payload': cur['payload'], 'envelope_id': cur['envelope_id'], 'effective_epoch': None}
[docs] def envelope_event( self, peer: str, direction: GrantDirection, envelope_id: str, as_json: bool = False, ) -> Any: """The signed kind 30801 this node held under that id, if it kept one.""" with self._lock: row = self._one('SELECT event FROM history WHERE peer=? AND direction=? AND envelope_id=?', (peer, direction, envelope_id)) if not row or not row[0]: return None return row[0] if as_json else json.loads(row[0])
[docs] def known_envelopes(self, peer: str, direction: GrantDirection) -> list[str]: with self._lock: return [r[0] for r in self._all( 'SELECT envelope_id FROM history WHERE peer=? AND direction=? ORDER BY effective_epoch, put_at', (peer, direction))]
# ---- the grant a window decided on, waiting for the boundary -------------
[docs] def put_pending(self, peer: str, payload: GrantPayload | Mapping[str, Any], note: str, severity: Optional[str], decided_epoch: int) -> None: with self._lock: self.execute('INSERT OR REPLACE INTO pending VALUES (?,?,?,?,?)', (peer, json.dumps(payload, sort_keys=True), note, severity, int(decided_epoch))) self.db.commit()
[docs] def pending(self, peer: str) -> Optional[PendingRow]: with self._lock: row = self._one('SELECT payload, note, severity, decided_epoch FROM pending WHERE peer=?', (peer,)) if not row: return None return {'payload': json.loads(row[0]), 'note': row[1], 'severity': row[2], 'decided_epoch': row[3]}
[docs] def clear_pending(self, peer: str) -> None: with self._lock: self.execute('DELETE FROM pending WHERE peer=?', (peer,)) self.db.commit()
# ---- the operator's decisions, as applied ----------------------------------
[docs] def seed_applied(self, peer: str) -> Optional[tuple[str, int]]: with self._lock: row = self._one('SELECT tier, at FROM seeds WHERE peer=?', (peer,)) return (row[0], row[1]) if row else None
[docs] def put_seed(self, peer: str, tier: str, at: int) -> None: with self._lock: self.execute('INSERT OR REPLACE INTO seeds VALUES (?,?,?)', (peer, tier, int(at))) self.db.commit()
[docs] def get(self, peer: str, direction: GrantDirection) -> Optional[GrantRow]: # Every write here took the lock and every read did not, on a # connection opened with check_same_thread=False and shared by the # tick, sync, peering and transport threads. sqlite answers that with # an intermittent "bad parameter or other API misuse", which is what a # sweep caught in grants.get after the capacity ladder added a reader # on the peering path. A read is as much a use of the connection as a # write. with self._lock: row = self._one('SELECT payload, envelope_id, status, env_created_at, updated_at FROM grants ' 'WHERE peer=? AND direction=?', (peer, direction)) if not row: return None return {'payload': json.loads(row[0]), 'envelope_id': row[1], 'status': row[2], 'env_created_at': row[3], 'updated_at': row[4]}
[docs] def history(self, peer: str, direction: GrantDirection) -> list[HistoryRow]: """Every grant that has governed a window with this peer, oldest first. Here because `grant_view` in app.py used to read it straight off the connection, without the lock, from the control socket's thread while the tick and the sync threads were writing. `windows_view` beside it took the account store's lock, so the rule was known and this one call was missed. A store that hands out its connection cannot enforce anything about how it is used. """ return [{'envelope_id': r[0], 'effective_epoch': r[1], 'tier': json.loads(r[2]).get('tier')} for r in self._all( 'SELECT envelope_id, effective_epoch, payload FROM history ' 'WHERE peer=? AND direction=? ORDER BY effective_epoch, put_at, seq', (peer, direction))]
# `builtins.list` because the method itself is called `list`, and inside the # class body the bare name would resolve to the method, not the type.
[docs] def list(self, direction: Optional[GrantDirection] = None) -> builtins.list[GrantListRow]: with self._lock: q = 'SELECT peer, direction, payload, envelope_id, status FROM grants' args: tuple[Any, ...] = () if direction: q += ' WHERE direction=?' args = (direction,) return [{'peer': r[0], 'direction': r[1], 'payload': json.loads(r[2]), 'envelope_id': r[3], 'status': r[4]} for r in self._all(q, args)]
[docs] def zero(self, peer: str, now: Optional[int] = None) -> None: """Both directions to zero and revoked: a terminate or a revocation.""" with self._lock: for direction in (ISSUED, RECEIVED): row = self.get(peer, direction) if row: p = row['payload'] p['limits'] = {k: 0 for k in p.get('limits', {})} p['tier'] = 'revoked' self.execute('UPDATE grants SET payload=?, tier=?, status=?, updated_at=? ' 'WHERE peer=? AND direction=?', (json.dumps(p, sort_keys=True), 'revoked', 'revoked', int(now or time.time()), peer, direction)) self.execute('DELETE FROM pending WHERE peer=?', (peer,)) self.db.commit()
[docs] def peers(self) -> builtins.list[str]: with self._lock: return sorted({r[0] for r in self._all('SELECT peer FROM grants WHERE status=\'live\'')})