"""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),)