@serfab/cadre-core 0.11.0 → 0.13.0

package/README.md

@@ -168,9 +168,10 @@ The main entry point for cadre participation.
 | `stop()` | Gracefully disconnect from all networks |
 | `getStrands()` | Get all active strand instances |
 | `getStrand(id)` | Get a specific strand instance |
-| `addStrand(row)` | Manually add a strand (testing/direct API) |
+| `foundStrand(config)` | **Create a strand**: publish its `Strand` row and start it locally as founder, in one call that is safe to re-run after an interruption. Returns the instance plus the row it actually runs under — for a closed strand read the membership key from there, since a resumed founding keeps the stored key |
+| `addStrand(row)` | Attach only — start a local instance for a row that already exists (the join path; also testing/direct API). Does **not** publish |
 | `stopStrand(id)` | Stop a strand on this node only (the shared `Strand` row stays; rediscovered on restart) |
-| `publishStrand(id, type?, memberKey?)` | Owner-signed `Strand` row insert — makes the strand visible cadre-wide |
+| `publishStrand(id, type?, memberKey?)` | Owner-signed `Strand` row insert — makes the strand visible cadre-wide. Idempotent: a live row with the same `(Type, MemberPrivateKey)` is returned unwritten; different content on the same id throws. Prefer `foundStrand` when creating a strand |
 | `unpublishStrand(id)` | Owner-signed party-wide removal — deletes this party's `Strand` row; every node stops the strand. Destroys a closed strand's `MemberPrivateKey` |
 | `getEnrollmentService()` | Access peer enrollment API |
 

package/dist/announce-addrs.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Translate `network.announceAddrs` / `network.appendAnnounceAddrs` — the operator-facing
+ * "advertise these addresses" settings — into the two `@optimystic/db-p2p` `NodeOptions`
+ * fields of the same names, which reach libp2p's `addresses.announce` /
+ * `addresses.appendAnnounce`.
+ *
+ * Two jobs, both of which the control node and every strand node need identically, hence
+ * one module rather than the same conditional spread written twice:
+ *
+ * - **Empty means unset.** libp2p treats `announce: []` as "no override", and forwarding
+ *   `[]` would still be forwarding a field. An empty config array is dropped so it cannot
+ *   land as an explicit empty announce set.
+ * - **Validate the multiaddrs here, at start.** libp2p does NOT validate announce addrs
+ *   at construction: `AddressManager` stores them as raw strings and only parses them on
+ *   the first `getAnnounceAddrs()`. A typo therefore produces a node that starts
+ *   cleanly, then throws `InvalidMultiaddrError` out of every `getMultiaddrs()` call —
+ *   including an UNHANDLED one from the debounced peer-store update libp2p runs on
+ *   `transport:listening`. Verified against libp2p's `address-manager` (its constructor
+ *   does `announce.map(ma => ma.toString())`; `getAnnounceAddrs()` does `multiaddr(a)`).
+ *   Parsing each entry up front converts that into a loud failure at node start, which is
+ *   what {@link relayCircuitAddrs} already does for `network.relayAddrs`.
+ *
+ *   Parsing alone is not enough, though: `''` and `'/'` both parse into a component-less
+ *   multiaddr, and a set holding only those is non-empty by the rule above — so it would
+ *   replace every advertised address with nothing at all. An entry naming no address is
+ *   therefore rejected alongside one that fails to parse.
+ */
+import type { NetworkConfig } from './types.js';
+/**
+ * The announce fields to spread into `createLibp2pNode` options. A field is present
+ * only when the operator configured a non-empty list for it, so a node that configures
+ * neither passes neither.
+ */
+export interface ResolvedAnnounceAddrs {
+    announceAddrs?: string[];
+    appendAnnounceAddrs?: string[];
+}
+/**
+ * Resolve both announce fields off a `NetworkConfig`. Throws — naming the offending
+ * config field and entry — when any entry is not a parsable multiaddr.
+ */
+export declare function resolveAnnounceAddrs(network: NetworkConfig | undefined): ResolvedAnnounceAddrs;
+/**
+ * Whether this node's advertised set will be REPLACED rather than extended — i.e.
+ * whether {@link ResolvedAnnounceAddrs.announceAddrs} is in play at all. The single
+ * predicate behind `CadreNode.start()`'s operator warning, kept here so the warning
+ * and the forwarding agree on what "set" means (non-empty, not merely present).
+ */
+export declare function replacesAdvertisedAddrs(network: NetworkConfig | undefined): boolean;

package/dist/announce-addrs.js

@@ -0,0 +1,78 @@
+/**
+ * Translate `network.announceAddrs` / `network.appendAnnounceAddrs` — the operator-facing
+ * "advertise these addresses" settings — into the two `@optimystic/db-p2p` `NodeOptions`
+ * fields of the same names, which reach libp2p's `addresses.announce` /
+ * `addresses.appendAnnounce`.
+ *
+ * Two jobs, both of which the control node and every strand node need identically, hence
+ * one module rather than the same conditional spread written twice:
+ *
+ * - **Empty means unset.** libp2p treats `announce: []` as "no override", and forwarding
+ *   `[]` would still be forwarding a field. An empty config array is dropped so it cannot
+ *   land as an explicit empty announce set.
+ * - **Validate the multiaddrs here, at start.** libp2p does NOT validate announce addrs
+ *   at construction: `AddressManager` stores them as raw strings and only parses them on
+ *   the first `getAnnounceAddrs()`. A typo therefore produces a node that starts
+ *   cleanly, then throws `InvalidMultiaddrError` out of every `getMultiaddrs()` call —
+ *   including an UNHANDLED one from the debounced peer-store update libp2p runs on
+ *   `transport:listening`. Verified against libp2p's `address-manager` (its constructor
+ *   does `announce.map(ma => ma.toString())`; `getAnnounceAddrs()` does `multiaddr(a)`).
+ *   Parsing each entry up front converts that into a loud failure at node start, which is
+ *   what {@link relayCircuitAddrs} already does for `network.relayAddrs`.
+ *
+ *   Parsing alone is not enough, though: `''` and `'/'` both parse into a component-less
+ *   multiaddr, and a set holding only those is non-empty by the rule above — so it would
+ *   replace every advertised address with nothing at all. An entry naming no address is
+ *   therefore rejected alongside one that fails to parse.
+ */
+import { multiaddr } from '@multiformats/multiaddr';
+/**
+ * Resolve both announce fields off a `NetworkConfig`. Throws — naming the offending
+ * config field and entry — when any entry is not a parsable multiaddr.
+ */
+export function resolveAnnounceAddrs(network) {
+    const announceAddrs = configuredAddrs('network.announceAddrs', network?.announceAddrs);
+    const appendAnnounceAddrs = configuredAddrs('network.appendAnnounceAddrs', network?.appendAnnounceAddrs);
+    return {
+        ...(announceAddrs && { announceAddrs }),
+        ...(appendAnnounceAddrs && { appendAnnounceAddrs })
+    };
+}
+/**
+ * Whether this node's advertised set will be REPLACED rather than extended — i.e.
+ * whether {@link ResolvedAnnounceAddrs.announceAddrs} is in play at all. The single
+ * predicate behind `CadreNode.start()`'s operator warning, kept here so the warning
+ * and the forwarding agree on what "set" means (non-empty, not merely present).
+ */
+export function replacesAdvertisedAddrs(network) {
+    return (network?.announceAddrs?.length ?? 0) > 0;
+}
+/** The entries to forward for one announce field, or `undefined` when it is unset or empty. */
+function configuredAddrs(field, addrs) {
+    if (!addrs || addrs.length === 0) {
+        return undefined;
+    }
+    return addrs.map((addr) => validated(field, addr));
+}
+/** `addr` unchanged, having proved it names a real address — config field named on failure. */
+function validated(field, addr) {
+    if (parsed(field, addr).getComponents().length === 0) {
+        // `''` and `'/'` PARSE: both yield a component-less multiaddr that stringifies to
+        // `/`. Forwarded, they make an announce set that is non-empty but names nothing —
+        // which by the replacement rule above costs the node every address it would
+        // otherwise advertise, silently. A templated `cadre.yaml` whose address variable went
+        // unsubstituted is the realistic way in, so it is rejected rather than forwarded.
+        throw new Error(`${field} entry names no address: ${JSON.stringify(addr)}`);
+    }
+    return addr;
+}
+/** `addr` as a multiaddr, with the config field named on a parse failure. */
+function parsed(field, addr) {
+    try {
+        return multiaddr(addr);
+    }
+    catch (err) {
+        throw new Error(`${field} entry is not a valid multiaddr: ${addr}`, { cause: err });
+    }
+}
+//# sourceMappingURL=announce-addrs.js.map

package/dist/announce-addrs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"announce-addrs.js","sourceRoot":"","sources":["../src/announce-addrs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAkB,MAAM,yBAAyB,CAAC;AAapE;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAkC;IACrE,MAAM,aAAa,GAAG,eAAe,CAAC,uBAAuB,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;IACvF,MAAM,mBAAmB,GAAG,eAAe,CAAC,6BAA6B,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC;IACzG,OAAO;QACL,GAAG,CAAC,aAAa,IAAI,EAAE,aAAa,EAAE,CAAC;QACvC,GAAG,CAAC,mBAAmB,IAAI,EAAE,mBAAmB,EAAE,CAAC;KACpD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAkC;IACxE,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;AACnD,CAAC;AAED,+FAA+F;AAC/F,SAAS,eAAe,CAAC,KAAa,EAAE,KAAoC;IAC1E,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,+FAA+F;AAC/F,SAAS,SAAS,CAAC,KAAa,EAAE,IAAY;IAC5C,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,kFAAkF;QAClF,kFAAkF;QAClF,4EAA4E;QAC5E,sFAAsF;QACtF,kFAAkF;QAClF,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,4BAA4B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6EAA6E;AAC7E,SAAS,MAAM,CAAC,KAAa,EAAE,IAAY;IACzC,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,oCAAoC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACtF,CAAC;AACH,CAAC"}