fleetmesh-strfry 0.1.0__tar.gz

fleetmesh_strfry-0.1.0/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

fleetmesh_strfry-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: fleetmesh-strfry
+Version: 0.1.0
+Summary: The strfry relay bridge for a Fleetmesh node: in-process plugin or standalone service
+License: CC0-1.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fleetmesh-node>=0.2.1
+Dynamic: license-file
+
+# fleetmesh-strfry
+
+The strfry relay bridge for a Fleetmesh node, in its own repo. It was
+`node/strfry_bridge.py` and `meshnode strfry` inside meshnode; the code is the
+same, moved, with two ways to run it.
+
+What it does:
+
+- **StrfryRelayBridge** (`fleetmesh_strfry.bridge`): a WebSocket client that
+  subscribes to a running [strfry](https://github.com/hoytech/strfry) relay,
+  verifies and stores what arrives in the node's event store, and publishes
+  the node's egress to strfry; egress that could not be sent is queued and
+  drained on every tick / `flush_egress()`.
+- **StrfryPolicyEngine / StrfryPluginRunner** (`fleetmesh_strfry.policy`): the
+  strfry [write-policy plugin](https://github.com/hoytech/strfry/blob/master/docs/plugins.md)
+  protocol over stdin/stdout - signature, id, clock-skew, NIP-40 expiry, size,
+  kind/shard/pubkey lists, rate limits, and optional bilateral peering-grant
+  enforcement against the node's `grants.sqlite` - plus the symmetric egress
+  policy (drop / redact).
+- **StrfryPipe** (`fleetmesh_strfry.pipe`): bulk JSONL export/import between
+  the node store and `strfry export` / `strfry import`.
+
+## Where it runs
+
+Standard library only, but it imports the node package at runtime
+(`node.protocols.nostr.eventstore`, `node.protocols.nostr.client`,
+`node.storage.grants`, `node.keystore`, `node.interfaces`, `node.compartment`,
+`node.commands.base`) and, through it, the
+reference `fleetmesh_core` and the schema package `fleetmesh_schema`. It runs
+**on the node host** with those packages importable:
+
+```
+pip install fleetmesh-strfry      # pulls in fleetmesh-node and, through it, core, schema, protocols
+```
+
+or, developing from checkouts, as sibling repos on `PYTHONPATH`:
+
+```
+/opt/fleetmesh/meshnode        # node/
+/opt/fleetmesh/core            # fleetmesh_core/
+/opt/fleetmesh/schema          # fleetmesh_schema/ (+ schema/, schemas/)
+/opt/fleetmesh/strfry-bridge   # this repo
+export PYTHONPATH=/opt/fleetmesh/strfry-bridge:/opt/fleetmesh/meshnode:/opt/fleetmesh/core:/opt/fleetmesh/schema
+```
+
+## Mode 1: in-process plugin
+
+The node loads `StrfryBridgePlugin` as a compartment (meshnode
+`docs/extending.md`): it starts and stops with the node, drains its egress
+queue on every node tick, and reports under `health.subsystems.strfry` /
+`meshnode status`. In the node's `config.json`:
+
+```json
+{
+  "plugins": [{"ref": "fleetmesh_strfry.plugin:StrfryBridgePlugin", "after": "bridge"}],
+  "extensions": {
+    "strfry": {
+      "url": "ws://127.0.0.1:7777",
+      "policy": {"enforce_grants": false, "shadow_reject": false},
+      "kinds": [0, 1, 3, 6, 7, 1059, 11801, 11802, 11803, 30801, 30802, 30803]
+    }
+  }
+}
+```
+
+`after` is optional; `policy` takes every `StrfryPolicyConfig.from_dict` key
+(`max_event_bytes`, `allowed_kinds`, `blocked_kinds`, `quarantine_kinds`,
+`allowed_shards`, `blocked_pubkeys`, `rate_limit_per_min`, ...); `kinds` is the
+strfry subscription filter. The plugin does not *require* the node's `bridge`
+compartment: when the node has one it binds to it, when not it still runs.
+
+With the plugin named in `config.json`, `meshnode` grows the verb back:
+
+```
+meshnode strfry DIR status|plugin|export|import|eval [--url] [--out] [--in] [--event] [--enforce-grants] [--shadow] [--json]
+```
+
+A `bridge.strfry` block left over from before the move is refused by the node's
+config check with a message naming this plugin.
+
+## Mode 2: standalone service
+
+```
+python -m fleetmesh_strfry run    --dir NODE_DIR [--url ws://127.0.0.1:7777] [--every 30]
+python -m fleetmesh_strfry plugin --dir NODE_DIR            # strfry writePolicy stdio runner
+python -m fleetmesh_strfry status|export|import|eval --dir NODE_DIR [flags]
+```
+
+`run` opens the node directory's `store.sqlite` / `grants.sqlite` the way
+`meshnode strfry` did, runs a `StrfryRelayBridge` against `--url`, and
+flushes the egress queue every `--every` seconds until SIGTERM/SIGINT. Exit
+codes: 0 on a clean stop or an accepted `eval`, 1 when `eval` rejects, 2 when
+the arguments are unusable (no such directory, no `keys.json`).
+
+`contrib/fleetmesh-strfry.service` is the systemd unit:
+
+```
+install -m 644 contrib/fleetmesh-strfry.service /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable --now fleetmesh-strfry
+```
+
+Edit `NODE_DIR`, `STRFRY_URL` and `PYTHONPATH` in it to match the host.
+
+For strfry's own write policy, point `strfry.conf` at the stdio runner.
+`--policy FILE` takes a JSON object of `StrfryPolicyConfig.from_dict` keys
+(`allowed_kinds`, `max_event_bytes`, `rate_limit_per_ip`, ...); `--no-ingest`
+evaluates without copying accepted events into the node's `store.sqlite`, for a
+relay where strfry is the only store:
+
+```
+relay {
+    writePolicy {
+        plugin = "/usr/bin/env PYTHONPATH=/opt/fleetmesh/strfry-bridge:/opt/fleetmesh/meshnode:/opt/fleetmesh/core:/opt/fleetmesh/schema python3 -m fleetmesh_strfry plugin --dir /var/lib/meshnode --policy /etc/fleetmesh/policy.json --no-ingest"
+    }
+}
+```
+
+## Tests
+
+Scripts, as in meshnode; each prints `N passed, M failed` and exits non-zero on
+a failure. With meshnode a sibling checkout:
+
+```
+PYTHONPATH=.:../meshnode:../core:../schema python3 tests/test_strfry_bridge.py   # policy, runner, pipe, live bridge, CLI
+PYTHONPATH=.:../meshnode:../core:../schema python3 tests/test_plugin.py          # plugin lifecycle, stdio subprocess, service loop, a node with the plugin
+```
+
+CI (`.gitlab-ci.yml`) clones meshnode, core and schema beside the checkout and
+runs the same.
+
+## License
+
+CC0-1.0, as meshnode (`LICENSE`).

fleetmesh_strfry-0.1.0/README.md

@@ -0,0 +1,134 @@
+# fleetmesh-strfry
+
+The strfry relay bridge for a Fleetmesh node, in its own repo. It was
+`node/strfry_bridge.py` and `meshnode strfry` inside meshnode; the code is the
+same, moved, with two ways to run it.
+
+What it does:
+
+- **StrfryRelayBridge** (`fleetmesh_strfry.bridge`): a WebSocket client that
+  subscribes to a running [strfry](https://github.com/hoytech/strfry) relay,
+  verifies and stores what arrives in the node's event store, and publishes
+  the node's egress to strfry; egress that could not be sent is queued and
+  drained on every tick / `flush_egress()`.
+- **StrfryPolicyEngine / StrfryPluginRunner** (`fleetmesh_strfry.policy`): the
+  strfry [write-policy plugin](https://github.com/hoytech/strfry/blob/master/docs/plugins.md)
+  protocol over stdin/stdout - signature, id, clock-skew, NIP-40 expiry, size,
+  kind/shard/pubkey lists, rate limits, and optional bilateral peering-grant
+  enforcement against the node's `grants.sqlite` - plus the symmetric egress
+  policy (drop / redact).
+- **StrfryPipe** (`fleetmesh_strfry.pipe`): bulk JSONL export/import between
+  the node store and `strfry export` / `strfry import`.
+
+## Where it runs
+
+Standard library only, but it imports the node package at runtime
+(`node.protocols.nostr.eventstore`, `node.protocols.nostr.client`,
+`node.storage.grants`, `node.keystore`, `node.interfaces`, `node.compartment`,
+`node.commands.base`) and, through it, the
+reference `fleetmesh_core` and the schema package `fleetmesh_schema`. It runs
+**on the node host** with those packages importable:
+
+```
+pip install fleetmesh-strfry      # pulls in fleetmesh-node and, through it, core, schema, protocols
+```
+
+or, developing from checkouts, as sibling repos on `PYTHONPATH`:
+
+```
+/opt/fleetmesh/meshnode        # node/
+/opt/fleetmesh/core            # fleetmesh_core/
+/opt/fleetmesh/schema          # fleetmesh_schema/ (+ schema/, schemas/)
+/opt/fleetmesh/strfry-bridge   # this repo
+export PYTHONPATH=/opt/fleetmesh/strfry-bridge:/opt/fleetmesh/meshnode:/opt/fleetmesh/core:/opt/fleetmesh/schema
+```
+
+## Mode 1: in-process plugin
+
+The node loads `StrfryBridgePlugin` as a compartment (meshnode
+`docs/extending.md`): it starts and stops with the node, drains its egress
+queue on every node tick, and reports under `health.subsystems.strfry` /
+`meshnode status`. In the node's `config.json`:
+
+```json
+{
+  "plugins": [{"ref": "fleetmesh_strfry.plugin:StrfryBridgePlugin", "after": "bridge"}],
+  "extensions": {
+    "strfry": {
+      "url": "ws://127.0.0.1:7777",
+      "policy": {"enforce_grants": false, "shadow_reject": false},
+      "kinds": [0, 1, 3, 6, 7, 1059, 11801, 11802, 11803, 30801, 30802, 30803]
+    }
+  }
+}
+```
+
+`after` is optional; `policy` takes every `StrfryPolicyConfig.from_dict` key
+(`max_event_bytes`, `allowed_kinds`, `blocked_kinds`, `quarantine_kinds`,
+`allowed_shards`, `blocked_pubkeys`, `rate_limit_per_min`, ...); `kinds` is the
+strfry subscription filter. The plugin does not *require* the node's `bridge`
+compartment: when the node has one it binds to it, when not it still runs.
+
+With the plugin named in `config.json`, `meshnode` grows the verb back:
+
+```
+meshnode strfry DIR status|plugin|export|import|eval [--url] [--out] [--in] [--event] [--enforce-grants] [--shadow] [--json]
+```
+
+A `bridge.strfry` block left over from before the move is refused by the node's
+config check with a message naming this plugin.
+
+## Mode 2: standalone service
+
+```
+python -m fleetmesh_strfry run    --dir NODE_DIR [--url ws://127.0.0.1:7777] [--every 30]
+python -m fleetmesh_strfry plugin --dir NODE_DIR            # strfry writePolicy stdio runner
+python -m fleetmesh_strfry status|export|import|eval --dir NODE_DIR [flags]
+```
+
+`run` opens the node directory's `store.sqlite` / `grants.sqlite` the way
+`meshnode strfry` did, runs a `StrfryRelayBridge` against `--url`, and
+flushes the egress queue every `--every` seconds until SIGTERM/SIGINT. Exit
+codes: 0 on a clean stop or an accepted `eval`, 1 when `eval` rejects, 2 when
+the arguments are unusable (no such directory, no `keys.json`).
+
+`contrib/fleetmesh-strfry.service` is the systemd unit:
+
+```
+install -m 644 contrib/fleetmesh-strfry.service /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable --now fleetmesh-strfry
+```
+
+Edit `NODE_DIR`, `STRFRY_URL` and `PYTHONPATH` in it to match the host.
+
+For strfry's own write policy, point `strfry.conf` at the stdio runner.
+`--policy FILE` takes a JSON object of `StrfryPolicyConfig.from_dict` keys
+(`allowed_kinds`, `max_event_bytes`, `rate_limit_per_ip`, ...); `--no-ingest`
+evaluates without copying accepted events into the node's `store.sqlite`, for a
+relay where strfry is the only store:
+
+```
+relay {
+    writePolicy {
+        plugin = "/usr/bin/env PYTHONPATH=/opt/fleetmesh/strfry-bridge:/opt/fleetmesh/meshnode:/opt/fleetmesh/core:/opt/fleetmesh/schema python3 -m fleetmesh_strfry plugin --dir /var/lib/meshnode --policy /etc/fleetmesh/policy.json --no-ingest"
+    }
+}
+```
+
+## Tests
+
+Scripts, as in meshnode; each prints `N passed, M failed` and exits non-zero on
+a failure. With meshnode a sibling checkout:
+
+```
+PYTHONPATH=.:../meshnode:../core:../schema python3 tests/test_strfry_bridge.py   # policy, runner, pipe, live bridge, CLI
+PYTHONPATH=.:../meshnode:../core:../schema python3 tests/test_plugin.py          # plugin lifecycle, stdio subprocess, service loop, a node with the plugin
+```
+
+CI (`.gitlab-ci.yml`) clones meshnode, core and schema beside the checkout and
+runs the same.
+
+## License
+
+CC0-1.0, as meshnode (`LICENSE`).

fleetmesh_strfry-0.1.0/fleetmesh_strfry/__init__.py

@@ -0,0 +1,36 @@
+"""fleetmesh-strfry: the strfry relay bridge for a Fleetmesh node.
+
+Two ways to run it, both over the same classes:
+
+- in the node's process: `fleetmesh_strfry.plugin:StrfryBridgePlugin` in the
+  node's `plugins` config block;
+- beside the node: `python -m fleetmesh_strfry run --dir NODE_DIR`.
+
+This package imports `node.protocols.nostr` (`client`, `eventstore`),
+`node.storage.grants`, `node.keystore`, `node.interfaces`, `node.compartment`
+and `fleetmesh_core` at runtime: it runs on the node host with the meshnode
+and core checkouts on PYTHONPATH. It has no other dependency beyond the standard library.
+"""
+from __future__ import annotations
+
+from .bridge import StrfryRelayBridge
+from .pipe import StrfryPipe
+from .plugin import PLUGIN_REF, StrfryBridgePlugin, cmd_strfry, register_cli
+from .policy import (
+    DEFAULT_STRFRY_URL,
+    MESH_CONTROL_KINDS,
+    RateLimiter,
+    StrfryPluginRunner,
+    StrfryPolicyConfig,
+    StrfryPolicyEngine,
+    StrfryPolicyError,
+)
+
+__version__ = '0.1.0'
+
+__all__ = [
+    'DEFAULT_STRFRY_URL', 'MESH_CONTROL_KINDS', 'PLUGIN_REF', 'RateLimiter',
+    'StrfryBridgePlugin', 'StrfryPipe', 'StrfryPluginRunner', 'StrfryPolicyConfig',
+    'StrfryPolicyEngine', 'StrfryPolicyError', 'StrfryRelayBridge',
+    'cmd_strfry', 'register_cli', '__version__',
+]

fleetmesh_strfry-0.1.0/fleetmesh_strfry/__main__.py

@@ -0,0 +1,122 @@
+"""`python -m fleetmesh_strfry`: the strfry bridge as its own service.
+
+    python -m fleetmesh_strfry run    --dir NODE_DIR [--url ws://127.0.0.1:7777] [--every 30]
+    python -m fleetmesh_strfry plugin --dir NODE_DIR          # strfry writePolicy stdio runner
+    python -m fleetmesh_strfry status|export|import|eval --dir NODE_DIR [flags]
+
+`run` opens the node directory's stores the way `meshnode strfry` did, runs
+a StrfryRelayBridge against the strfry URL, and drains the egress queue
+every `--every` seconds until SIGTERM/SIGINT. The other verbs are the
+former `meshnode strfry DIR ACTION` with `--dir` instead of a positional.
+
+Exit codes: 0 on a clean stop or an accepted `eval`; 1 when `eval` rejects;
+2 when the arguments are unusable (no such directory, no keys).
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import signal
+import sys
+import threading
+from typing import Optional, Sequence
+
+from .bridge import StrfryRelayBridge
+from .plugin import ACTIONS, STORE_FILE, add_strfry_arguments, cmd_strfry, open_stores
+from .policy import DEFAULT_STRFRY_URL, StrfryPolicyConfig, StrfryPolicyEngine
+
+EXIT_OK = 0
+EXIT_USAGE = 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog='python -m fleetmesh_strfry',
+                                 description=(__doc__ or '').split('\n\n')[0])
+    sub = ap.add_subparsers(dest='action', required=True)
+
+    run = sub.add_parser('run', help='bridge the node store and a strfry relay until stopped')
+    run.add_argument('--dir', required=True, help='the node directory (keys.json, store.sqlite, grants.sqlite)')
+    run.add_argument('--url', default=DEFAULT_STRFRY_URL, help='strfry WebSocket URL')
+    run.add_argument('--every', type=float, default=30.0, help='seconds between egress flushes')
+    run.add_argument('--store-file', default=STORE_FILE, help=argparse.SUPPRESS)
+    run.add_argument('--enforce-grants', action='store_true', help='enforce bilateral peering grants')
+    run.add_argument('--shadow', action='store_true', help='use shadowReject instead of reject')
+    run.add_argument('--iterations', type=int, default=0, help=argparse.SUPPRESS)   # tests: stop after N flushes
+
+    for action in ACTIONS:
+        p = sub.add_parser(action, help='the former `meshnode strfry DIR %s`' % action)
+        p.add_argument('--dir', required=True, help='the node directory')
+        p.add_argument('--store-file', default=STORE_FILE, help=argparse.SUPPRESS)
+        p.add_argument('--json', action='store_true', help='print the structure, for scripts')
+        add_strfry_arguments(p)
+    return ap
+
+
+def _usable(directory: str) -> Optional[str]:
+    if not os.path.isdir(directory):
+        return 'no such directory: %s' % directory
+    if not os.path.exists(os.path.join(directory, 'keys.json')):
+        return 'not a node directory (no keys.json): %s' % directory
+    return None
+
+
+def serve(directory: str, url: str, every: float, store_file: str = STORE_FILE,
+          enforce_grants: bool = False, shadow: bool = False, iterations: int = 0,
+          stop: Optional[threading.Event] = None) -> int:
+    """Run the bridge until `stop` is set (SIGTERM/SIGINT set it) or `iterations` flushes are done."""
+    st, gr = open_stores(directory, store_file)
+    engine = StrfryPolicyEngine(config=StrfryPolicyConfig(enforce_grants=enforce_grants, shadow_reject=shadow),
+                                store_backend=st, grant_store=gr)
+    bridge = StrfryRelayBridge(store_backend=st, strfry_url=url, policy_engine=engine)
+    stop = stop or threading.Event()
+
+    def _on_signal(signum: int, _frame: object) -> None:
+        stop.set()
+
+    main_thread = threading.current_thread() is threading.main_thread()
+    if main_thread:
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            signal.signal(sig, _on_signal)
+
+    print('fleetmesh-strfry: bridging %s <-> %s every %gs' % (directory, url, every), file=sys.stderr, flush=True)
+    bridge.start()
+    done = 0
+    try:
+        while not stop.is_set():
+            if stop.wait(every):
+                break
+            sent = bridge.flush_egress()
+            done += 1
+            if sent:
+                print('fleetmesh-strfry: flushed %d egress events' % sent, file=sys.stderr, flush=True)
+            if iterations and done >= iterations:
+                break
+    finally:
+        bridge.stop()
+        for s in (st, gr):
+            close = getattr(s, 'close', None)
+            if callable(close):
+                try:
+                    close()
+                except Exception:
+                    pass
+    print('fleetmesh-strfry: stopped; %s' % bridge.stats(), file=sys.stderr, flush=True)
+    return EXIT_OK
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    ap = build_parser()
+    a = ap.parse_args(argv)
+    why = _usable(a.dir)
+    if why is not None:
+        print('fleetmesh-strfry: %s' % why, file=sys.stderr)
+        return EXIT_USAGE
+    if a.action == 'run':
+        return serve(a.dir, a.url, a.every, store_file=a.store_file, enforce_grants=a.enforce_grants,
+                     shadow=a.shadow, iterations=a.iterations)
+    code = cmd_strfry(a)
+    return int(code) if isinstance(code, int) else EXIT_OK
+
+
+if __name__ == '__main__':
+    sys.exit(main())