fleetmesh-node 0.2.0__py3-none-any.whl

node/storage/grants.py

@@ -0,0 +1,317 @@
+"""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'
+
+
+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)))
+
+    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()
+
+    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}
+
+    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])
+
+    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 -------------
+    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()
+
+    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]}
+
+    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 ----------------------------------
+    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
+
+    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()
+
+    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]}
+
+    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.
+    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)]
+
+    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()
+
+    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\'')})
+

node/storage/locator.py

@@ -0,0 +1,150 @@
+"""Where each of the node's stores lives, decided once from config.
+
+Every store site in the tree reads the same two things: a directory and a
+logical name, joined into `<directory>/<name>.sqlite`. That join is the only
+reason the tree is tied to SQLite now that the dialect layer exists, so it is
+the thing to replace - not with a flag threaded through fourteen files, but
+with one object that answers "where does the store called `grants` live" and
+is built once from the node's configuration.
+
+    loc = Locator.from_config(directory)                  # the default
+    loc = Locator.from_config(directory, url='postgresql://...')
+    store = loc.open(grants.GrantStore, 'grants')
+
+On SQLite that is the same path the site computed before, so the default node
+is byte-for-byte unchanged. On PostgreSQL every store gets the same URL: one
+node per database is settled (docs/storage-backends.md section 10), the forty-
+four table names do not collide, and the schema version is already keyed by
+store name rather than by database - the defect that taught us so is recorded
+at postgres.py:218.
+
+One dialect instance is shared by every store it opens. `PostgresDialect`
+learns each table's columns and primary key from the DDL passing through
+`sql()`, so sharing means the reflection is learned once rather than fourteen
+times, and the methods that use a connection take it as an argument.
+
+A backend is named by URL scheme, and an unknown one is refused by name
+rather than quietly becoming a filename.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Callable, Optional, TypedDict
+
+from .dialect import Dialect, SqliteDialect
+
+SQLITE_SUFFIX = '.sqlite'
+POSTGRES_SCHEMES = ('postgresql://', 'postgres://')
+
+
+class _Backend(TypedDict):
+    backend: str
+
+
+class StorageBackend(_Backend, total=False):
+    """The backend as `meshnode health` reports it.
+
+    A named record rather than a loose mapping, for the same reason
+    `StoreLease` is one: check-dicts.py holds this tree to typing what it
+    returns, and a row an operator reads by field name is the case that rule
+    exists for. Exactly one of `directory` and `server` is present - which one
+    is the answer being reported.
+    """
+    directory: str
+    server: str
+    owner: str
+
+
+class Locator:
+    """The node's storage target. Build it with `from_config`."""
+
+    def __init__(self, directory: str, dialect: Dialect,
+                 url: Optional[str] = None, owner: Optional[str] = None) -> None:
+        self.directory: str = directory
+        self.dialect: Dialect = dialect
+        self.url: Optional[str] = url
+        self.owner: Optional[str] = owner
+
+    # ---- construction -----------------------------------------------------
+
+    @classmethod
+    def from_config(cls, directory: str, url: Optional[str] = None,
+                    owner: Optional[str] = None) -> 'Locator':
+        """The locator a node's config asks for.
+
+        No URL is the default and needs nothing of the operator. A URL names
+        its backend by scheme; anything else is a configuration error and is
+        reported as one, because treating it as a path would produce a node
+        that silently ran on SQLite while an operator believed otherwise.
+
+        `owner` is the node's identity for the ownership lease. It is what
+        makes one node per database enforced rather than assumed
+        (docs/storage-backends.md section 5a): `BaseStore` claims a lease only
+        when it is given an owner, so a locator without one opens stores that
+        claim nothing. On a server every store shares the database and
+        therefore shares the one `fleetmesh_owner` row, so the first store to
+        open claims the database for this node and a second node is refused.
+        """
+        if not url:
+            return cls(directory, SqliteDialect(), owner=owner)
+        if url.startswith(POSTGRES_SCHEMES):
+            from .postgres import PostgresDialect  # noqa: PLC0415  (optional)
+            return cls(directory, PostgresDialect(), url=url, owner=owner)
+        raise ValueError(
+            'unknown storage URL scheme: %r - expected one of %s, or no URL for the '
+            'SQLite default' % (url.split('://')[0], ', '.join(POSTGRES_SCHEMES)))
+
+    # ---- use --------------------------------------------------------------
+
+    def target(self, name: str) -> str:
+        """The connection target for the store called `name`.
+
+        A file per store on SQLite. One database for all of them on a server,
+        which is what "one node per database" means.
+        """
+        if self.url is not None:
+            return self.url
+        return os.path.join(self.directory, name + SQLITE_SUFFIX)
+
+    def open(self, store_cls: Callable[..., Any], name: str, **kw: Any) -> Any:
+        """Construct a store of `store_cls` where `name` belongs.
+
+        `kw` is passed through untouched, so a store with its own arguments -
+        `ttl_seconds`, `readonly` - keeps them, and a caller naming `owner`
+        itself wins over the locator's.
+        """
+        if self.owner is not None:
+            kw.setdefault('owner', self.owner)
+        return store_cls(self.target(name), dialect=self.dialect, **kw)
+
+    # ---- what an operator is shown ----------------------------------------
+
+    def describe(self) -> StorageBackend:
+        """The backend, for `meshnode health`.
+
+        Which backend is live is otherwise invisible until something breaks,
+        and a node believed to be on PostgreSQL while running on SQLite is
+        exactly the failure this reports. The URL is reduced to host and
+        database: a connection string carries a password.
+        """
+        out: StorageBackend = {'backend': self.dialect.name}
+        if self.url is None:
+            out['directory'] = self.directory
+        else:
+            out['server'] = redact(self.url)
+        if self.owner is not None:
+            out['owner'] = self.owner
+        return out
+
+
+def redact(url: str) -> str:
+    """`postgresql://user:pw@host:5432/db` -> `host:5432/db`.
+
+    A password in a connection string must not reach a log, a health block or
+    a receipt, and the part an operator needs to recognise the server is the
+    part after the credentials.
+    """
+    rest = url.split('://', 1)[1] if '://' in url else url
+    if '@' in rest:
+        rest = rest.rsplit('@', 1)[1]
+    return rest.split('?', 1)[0]