5. Python API Reference (fleetmesh_strfry)
This page documents the Python classes and functions provided by the fleetmesh-strfry package.
5.1. Bridge Core (fleetmesh_strfry.bridge)
Live Streaming Bridge (StrfryRelayBridge).
Real-time bidirectional streaming between a local/remote strfry relay (via WebSocket) and the Fleetmesh node store and P2P gossip planes.
Moved verbatim from meshnode’s fleetmesh_node/strfry_bridge.py; only the import paths changed.
- class fleetmesh_strfry.bridge.StrfryRelayBridge[source]
Bases:
objectLive bidirectional WebSocket streaming bridge connecting strfry and Fleetmesh.
- __init__(store_backend, strfry_url='ws://127.0.0.1:7777', policy_engine=None, kinds=None, clock=None)[source]
- enqueue(event)[source]
Queue event for strfry; it goes out on the next flush_egress.
The queue holds the newest 1000: when full, the oldest is dropped.
- Parameters:
event (NostrEvent)
- Return type:
None
- publish_to_strfry(event)[source]
Publish an outbound event to the strfry relay after egress policy check.
- Parameters:
event (NostrEvent)
- Return type:
- flush_egress()[source]
Send queued egress to strfry; returns how many went out.
Driven from three places: after every (re)connect of the read loop, after every inbound event, and from the plugin’s tick() - so a quiet strfry that sends nothing still gets what was queued for it. What cannot be sent because strfry is unreachable is put back at the front of the queue for the next attempt, in order.
- Return type:
5.2. Policy Engine (fleetmesh_strfry.policy)
strfry write-policy engine, its configuration, and the stdio plugin runner.
Native strfry Write-Policy Plugin Protocol (stdio line-based IPC): - Line-delimited JSON interface compliant with strfry’s writePolicy plugin engine. - Evaluates BIP-340 Schnorr signatures, timestamp skew, NIP-40 expiration, payload MTUs,
per-IP/per-pubkey rate limits, and Fleetmesh bilateral grants (Kind 30803).
Automatically intercepts and records mesh control events (11801, 11802, 11803, 30801, 30802, 30803, 30810, 30811) into the local meshnode store.
Answers with strfry actions: accept, reject (with diagnostic reason), and shadowReject.
Symmetrical Egress Policy (pluginOut): - As specified in spec.html (§ Sovereignty and Policy Seams):
Enforces local shard sovereignty, preventing quarantined notes from leaking to wide-mesh peers with actions: allow, drop, shadowDrop, and redact.
Moved verbatim from meshnode’s fleetmesh_node/strfry_bridge.py; only the import paths changed.
- class fleetmesh_strfry.policy.StrfryPolicyConfig[source]
Bases:
objectConfiguration governing strfry writePolicy and egressPolicy evaluation.
- __init__(require_valid_sig=True, max_future_seconds=900, max_event_bytes=262144, rate_limit_per_min=1200, rate_limit_per_pubkey=180, rate_limit_per_ip=300, enforce_grants=False, shadow_reject=False, blocked_pubkeys=None, allowed_pubkeys=None, blocked_kinds=None, allowed_kinds=None, allowed_shards=None, quarantine_kinds=None, roster_file=None)[source]
- class fleetmesh_strfry.policy.StrfryPolicyEngine[source]
Bases:
objectCore policy engine evaluating strfry ingress and symmetrical egress traffic.
- __init__(config=None, store_backend=None, grant_store=None, clock=None)[source]
- Parameters:
config (StrfryPolicyConfig | None)
store_backend (Any | None)
grant_store (Any | None)
- Return type:
None
- evaluate_ingress(payload)[source]
Evaluate an inbound event submitted via strfry writePolicy.
- Returns one of:
{“id”: “<id>”, “action”: “accept”} {“id”: “<id>”, “action”: “reject”, “msg”: “blocked: <reason>”} {“id”: “<id>”, “action”: “shadowReject”}
- class fleetmesh_strfry.policy.StrfryPluginRunner[source]
Bases:
objectManages external process execution conforming to strfry’s writePolicy plugin IPC.
- __init__(engine)[source]
- Parameters:
engine (StrfryPolicyEngine)
- Return type:
None
- engine: StrfryPolicyEngine
5.3. Bulk Data Pipeline (fleetmesh_strfry.pipe)
High-throughput bulk stream pipe (StrfryPipe): JSONL export/import compatible with strfry.
Streaming JSONL export (NodeStore -> strfry export format).
Streaming JSONL import (strfry export -> NodeStore) with deduplication and origin tracking.
Moved verbatim from meshnode’s fleetmesh_node/strfry_bridge.py; only the import paths changed.
- class fleetmesh_strfry.pipe.StrfryPipe[source]
Bases:
objectHigh-throughput bulk streaming export and import compatible with strfry.
- static export_jsonl(store_backend, out_stream)[source]
Stream events from NodeStore out to JSONL (strfry export format).
5.4. Compartment Plugin (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.
- class fleetmesh_strfry.plugin.StrfryBridgePlugin[source]
Bases:
CompartmentThe strfry relay bridge as a subsystem/1 compartment.
- commands: Mapping[str, CommandSpec] = {'flush': {'args': {}, 'does': 'send what is queued for strfry now', 'reply': '{"sent": n}'}, 'show': {'args': {}, 'does': 'the strfry bridge: connection, counters, policy telemetry', 'reply': 'the stats() dict'}}
- classmethod from_context(ctx)[source]
Build from a NodeContext. When NEEDS is declared, constructs from declarations.
- Parameters:
ctx (Any)
- Return type:
- bind(relay_bridge)[source]
Sit beside the node’s RelayBridge. Optional: nothing here needs it.
- Parameters:
relay_bridge (Any)
- Return type:
None
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- trouble()[source]
What an operator should be told without having to ask for it.
Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.
- command(name, args)[source]
Answer a declared command: its arguments checked against the declaration, then what its run names. A KeyError for a name this compartment does not declare; a CommandError for arguments it does not take.
The KeyError is the declared contract and a dozen suites assert it, so it stays. Registry.dispatch is what turns this one shape into a ControlError on the way to the control socket - see the note there (audit I14).
- fleetmesh_strfry.plugin.open_stores(directory, store_file='store.sqlite')[source]
- Parameters:
- Return type:
- fleetmesh_strfry.plugin.cmd_strfry(a)[source]
The former meshnode strfry command, behaviour unchanged.
- fleetmesh_strfry.plugin.add_strfry_arguments(p)[source]
The flags meshnode strfry took, on any parser.
- Parameters:
p (ArgumentParser)
- Return type: