Source code for fleetmesh_strfry.plugin

"""The in-process plugin: StrfryRelayBridge as a node compartment, plus the CLI verbs.

Declared in the node's config.json:

    "plugins": ["fleetmesh_strfry.plugin:StrfryBridgePlugin"],
    "extensions": {"strfry": {"url": "ws://127.0.0.1:7777", "policy": {"enforce_grants": false}}}

The node imports this class at start, builds it from its NodeContext
(`from_context`), starts and stops it with the other compartments, drains
the egress queue on every tick, and reports `stats()` under
`health.subsystems.strfry`. The compartment does not `requires` the
`bridge` compartment: when the node has one, `start()` binds to it so its
state names the relay bridge it sits beside; when the node has none the
strfry bridge still runs. That is what "soft" means here.

`cli` is the hook `fleetmesh_node/commands` reads: each entry is `(verb, register_fn)`
and `register_fn(subparsers)` adds the verb to the `meshnode` parser, so
`meshnode strfry DIR status|plugin|export|import|eval` keeps working with the
plugin installed. The same functions back `python -m fleetmesh_strfry`.
"""
from __future__ import annotations

import argparse
import json
import os
import sys
from typing import Any, Callable, Mapping, Optional

from fleetmesh_node import keystore
from fleetmesh_node.protocols.nostr import eventstore
from fleetmesh_node.storage import grants
from fleetmesh_node.compartment import Compartment

from .bridge import StrfryRelayBridge
from .pipe import StrfryPipe
from .policy import DEFAULT_STRFRY_URL, StrfryPluginRunner, StrfryPolicyConfig, StrfryPolicyEngine

PLUGIN_REF = 'fleetmesh_strfry.plugin:StrfryBridgePlugin'
EXTENSION_KEY = 'strfry'


[docs]class StrfryBridgePlugin(Compartment): """The strfry relay bridge as a `subsystem/1` compartment.""" name = EXTENSION_KEY reads = ('extensions',) commands = { 'show': {'args': {}, 'does': 'the strfry bridge: connection, counters, policy telemetry', 'reply': 'the stats() dict'}, 'flush': {'args': {}, 'does': 'send what is queued for strfry now', 'reply': '{"sent": n}'}, }
[docs] def __init__(self, node: Any = None, store_backend: Any = None, grant_store: Any = None, settings: Optional[Mapping[str, Any]] = None, clock: Optional[Callable[[], int]] = None) -> None: super().__init__(node) s = dict(settings or {}) self.url: str = str(s.get('url') or DEFAULT_STRFRY_URL) policy_cfg = StrfryPolicyConfig.from_dict(s.get('policy') or {}) engine = StrfryPolicyEngine(config=policy_cfg, store_backend=store_backend, grant_store=grant_store, clock=clock) kinds = s.get('kinds') self.bridge: StrfryRelayBridge = StrfryRelayBridge( store_backend=store_backend, strfry_url=self.url, policy_engine=engine, kinds=list(kinds) if kinds else None, clock=clock) self.relay_bridge: Any = None # the node's `bridge` compartment, when bound # Removes the egress handler from the node's face; set while started. self._face_unsubscribe: Optional[Callable[[], None]] = None
[docs] @classmethod def from_context(cls, ctx: Any) -> 'StrfryBridgePlugin': ext = (ctx.cfg_of('extensions', {}) or {}).get(EXTENSION_KEY, {}) or {} return cls(node=ctx.node, store_backend=ctx.stores.events, grant_store=ctx.stores.grants, settings=ext, clock=ctx.clock)
# ---- the soft dependency on the relay bridge ---------------------------------
[docs] def bind(self, relay_bridge: Any) -> None: """Sit beside the node's RelayBridge. Optional: nothing here needs it.""" self.relay_bridge = relay_bridge
# ---- lifecycle -------------------------------------------------------------
[docs] def start(self) -> None: if self.relay_bridge is None and self.node is not None: rb = getattr(self.node, 'bridge', None) if rb is not None: self.bind(rb) add = getattr(getattr(self.node, 'face', None), 'add_event_handler', None) if add is not None and self._face_unsubscribe is None: self._face_unsubscribe = add(self.bridge.enqueue) self.bridge.start()
[docs] def stop(self) -> list[tuple[str, str]]: if self._face_unsubscribe is not None: self._face_unsubscribe() self._face_unsubscribe = None self.bridge.stop() return [('stopped strfry bridge', self.url)]
[docs] def tick(self, now: int) -> list[tuple[Any, ...]]: # The strfry bridge only drains its own queue after an inbound event; # a quiet strfry would hold queued egress forever. The tick drains it. sent = self.bridge.flush_egress() if sent > 0: return [('strfry', f'flushed {sent} egress events to strfry')] return []
# ---- being watched ---------------------------------------------------------
[docs] def stats(self) -> dict[str, Any]: return self.bridge.stats()
[docs] def state(self) -> dict[str, Any]: st = dict(self.stats()) st['relay_bridge'] = self.relay_bridge is not None return st
[docs] def trouble(self) -> list[str]: out: list[str] = [] if self.bridge._thread is not None and not self.bridge.connected: out.append('not connected to strfry at %s%s' % ( self.url, (' (%s)' % self.bridge.last_error) if self.bridge.last_error else '')) pending = self.bridge.pending_egress() if pending: out.append('%d events queued for strfry' % pending) return out
[docs] def command(self, name: str, args: dict[str, Any]) -> Any: if name == 'show': return self.state() if name == 'flush': return {'sent': self.bridge.flush_egress()} raise KeyError(name)
# ---- the CLI hook ---------------------------------------------------------- cli: tuple[tuple[str, Callable[[Any], None]], ...] = () # set below, after register_cli exists
# --------------------------------------------------------------------------- # The operator's verbs: `meshnode strfry DIR ACTION` and `python -m fleetmesh_strfry ACTION --dir DIR` # --------------------------------------------------------------------------- STORE_FILE = 'store.sqlite' # what `meshnode strfry` opened; see README "Which store" GRANTS_FILE = 'grants.sqlite'
[docs]def open_stores(directory: str, store_file: str = STORE_FILE) -> tuple[eventstore.NodeStore, grants.GrantStore]: st = eventstore.NodeStore(os.path.join(directory, store_file)) gr = grants.GrantStore(os.path.join(directory, GRANTS_FILE)) return st, gr
[docs]def cmd_strfry(a: argparse.Namespace) -> int | None: """The former `meshnode strfry` command, behaviour unchanged.""" action = getattr(a, 'action', 'status') or 'status' ks = keystore.Keystore.load(a.dir) st, gr = open_stores(a.dir, getattr(a, 'store_file', None) or STORE_FILE) cfg = policy_config(a) # --no-ingest: strfry is the store. A relay that only filters must not # keep a second, unswept copy of everything it accepts in store.sqlite. engine = StrfryPolicyEngine(config=cfg, store_backend=None if getattr(a, 'no_ingest', False) else st, grant_store=gr) as_json = bool(getattr(a, 'json', False)) if action == 'plugin': runner = StrfryPluginRunner(engine) runner.run_stdio(sys.stdin, sys.stdout) return 0 elif action == 'status': url = getattr(a, 'url', DEFAULT_STRFRY_URL) or DEFAULT_STRFRY_URL stats = { 'node_id': ks.node_pk, 'target_strfry_url': url, 'policy': engine.stats(), } if as_json: print(json.dumps(stats, indent=2)) else: print('strfry Bridge & Policy Status:') print(' Node ID: %s' % ks.node_pk) print(' Target strfry URL: %s' % url) print(' Enforce Grants: %s' % cfg.enforce_grants) print(' Shadow Reject: %s' % cfg.shadow_reject) print(' Ingress Evaluated: %d (Accepted: %d, Rejected: %d)' % ( engine.ingress_evaluated, engine.ingress_accepted, engine.ingress_rejected )) return 0 elif action == 'export': out_file = getattr(a, 'out', None) if out_file: with open(out_file, 'w', encoding='utf-8') as f: n = StrfryPipe.export_jsonl(st, f) print(f"Exported {n} events to {out_file}") else: StrfryPipe.export_jsonl(st, sys.stdout) return 0 elif action == 'import': in_file = getattr(a, 'in_file', None) if in_file: with open(in_file, 'r', encoding='utf-8') as f: imp, dup, err = StrfryPipe.import_jsonl(st, f) else: imp, dup, err = StrfryPipe.import_jsonl(st, sys.stdin) if as_json: print(json.dumps({'imported': imp, 'duplicates': dup, 'errors': err})) else: print(f"strfry Import: {imp} imported, {dup} duplicates, {err} errors") return 0 elif action == 'eval': ev_str = getattr(a, 'event', None) if not ev_str: sys.exit('eval requires --event <json>') try: ev_data = json.loads(ev_str) except Exception as e: sys.exit(f'invalid event json: {e}') res = engine.evaluate_ingress({'type': 'new', 'event': ev_data}) if as_json: print(json.dumps(res, indent=2)) else: print('Evaluation Verdict:') print(' Action: %s' % res.get('action')) if 'msg' in res: print(' Reason: %s' % res.get('msg')) return 0 if res.get('action') == 'accept' else 1 return None
ACTIONS: tuple[str, ...] = ('plugin', 'status', 'export', 'import', 'eval')
[docs]def add_strfry_arguments(p: argparse.ArgumentParser) -> argparse.ArgumentParser: """The flags `meshnode strfry` took, on any parser.""" p.add_argument('--url', default=DEFAULT_STRFRY_URL, help='strfry WebSocket URL') p.add_argument('--out', help='output JSONL file path for export') p.add_argument('--in', dest='in_file', help='input JSONL file path for import') p.add_argument('--event', help='raw JSON event string to evaluate') p.add_argument('--enforce-grants', action='store_true', help='enforce bilateral peering grants') p.add_argument('--shadow', action='store_true', help='use shadowReject instead of reject') p.add_argument('--policy', help='JSON file of StrfryPolicyConfig keys (allowed_kinds, max_event_bytes, rate limits, ...)') p.add_argument('--no-ingest', action='store_true', help='evaluate only; do not copy accepted events into the node store') return p
[docs]def policy_config(a: argparse.Namespace) -> StrfryPolicyConfig: """The policy from --policy FILE, with --enforce-grants / --shadow switching their keys on.""" d: dict[str, Any] = {} path = getattr(a, 'policy', None) if path: with open(path, encoding='utf-8') as f: d = json.load(f) if not isinstance(d, dict): raise ValueError('%s: the policy file must hold a JSON object' % path) if getattr(a, 'enforce_grants', False): d['enforce_grants'] = True if getattr(a, 'shadow', False): d['shadow_reject'] = True return StrfryPolicyConfig.from_dict(d)
[docs]def register_cli(sub: argparse._SubParsersAction) -> None: """Add `meshnode strfry DIR ACTION` to the node's parser. The `cli` hook calls this.""" from fleetmesh_node.commands.base import add_command sf = add_command(sub, 'strfry', cmd_strfry, 'strfry relay bridge, write-policy plugin, and pipe sync', js=True) sf.add_argument('action', choices=ACTIONS, default='status', nargs='?') add_strfry_arguments(sf)
StrfryBridgePlugin.cli = (('strfry', register_cli),)