wire-mesh-core 1.54.0 → 1.55.0

package/dist/domain/gossip-expansion.cjs

@@ -0,0 +1,44 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_domain_device_id = require("./device-id.cjs");
+//#region src/domain/gossip-expansion.ts
+function toError(value) {
+	return value instanceof Error ? value : new Error(String(value));
+}
+/** Builds the per-device expansion state machine: ask once, dial every advertised address in order on approval, report exactly one outcome. */
+function createGossipExpansion(options) {
+	const selfHex = require_domain_device_id.deviceIdToHex(options.selfDeviceId);
+	const considered = /* @__PURE__ */ new Set();
+	async function expand(candidate) {
+		let approved;
+		try {
+			approved = await options.shouldExpand(candidate);
+		} catch (error) {
+			options.onExpansionFailed?.(candidate, [toError(error)]);
+			return;
+		}
+		if (!approved) {
+			options.onExpansionDeclined?.(candidate);
+			return;
+		}
+		const errors = [];
+		for (const address of candidate.addresses) try {
+			const session = await options.dial(address);
+			options.onExpanded(candidate, address, session);
+			return;
+		} catch (error) {
+			errors.push(toError(error));
+		}
+		options.onExpansionFailed?.(candidate, errors);
+	}
+	return { considerAdvert(advert) {
+		const hex = require_domain_device_id.deviceIdToHex(advert.device);
+		if (hex === selfHex || considered.has(hex) || advert.addresses.length === 0) return;
+		considered.add(hex);
+		expand({
+			device: advert.device,
+			addresses: advert.addresses
+		});
+	} };
+}
+//#endregion
+exports.createGossipExpansion = createGossipExpansion;

package/dist/domain/gossip-expansion.d.cts

@@ -0,0 +1,29 @@
+import { D as DeviceId, et as PeerAdvert } from "../protocol-PhUVprXA.cjs";
+import { MeshSession } from "./mesh-session.cjs";
+//#region src/domain/gossip-expansion.d.ts
+/** One not-yet-considered device this session's gossip directory has surfaced, carrying only what a dial/trust decision needs: the device-id to decide identity, and the "host:port" addresses its own peer-advert claims are directly reachable at, in the order it advertised them. */
+export interface GossipExpansionCandidate {
+  readonly device: DeviceId;
+  readonly addresses: readonly string[];
+}
+export interface GossipExpansionOptions {
+  /** This session's own device-id, so its own self-advert (looped back through gossip forwarding or a hub's catch-up frame) is never offered to shouldExpand as if it were a distinct peer. */
+  selfDeviceId: DeviceId;
+  /** Decides whether to attempt a direct connection to a newly-discovered device at all -- called at most once per device for this GossipExpansion instance's lifetime, never re-asked if the same device later re-adverts (an address change, a fresher snapshot-seconds). Returning true does not guarantee a connection: dial may still fail for every one of the candidate's addresses, reported via onExpansionFailed. */
+  shouldExpand: (candidate: Readonly<GossipExpansionCandidate>) => Promise<boolean> | boolean;
+  /** Attempts one direct connection to `address`, resolving with a fully connected MeshSession or rejecting if the dial/handshake fails. Typically wraps createMeshSession(transport, identity, ...) followed by session.connect(address, localDomains). Called once per address of an approved candidate, in the order it advertised them, stopping at the first that succeeds -- the caller owns cleanup of any partially-established session behind a rejected dial, since this module never holds a reference to one that didn't resolve. */
+  dial: (address: string) => Promise<MeshSession>;
+  /** Called once a candidate's dial succeeds, with the specific address that connected (one of candidate.addresses, not necessarily the first -- earlier ones may have failed) and the now-connected session, so the caller can wire it into whatever it already does for its own sessions (render it, merge its directory, route messages). */
+  onExpanded: (candidate: Readonly<GossipExpansionCandidate>, address: string, session: MeshSession) => void;
+  /** Called when shouldExpand itself declines a candidate. */
+  onExpansionDeclined?: (candidate: Readonly<GossipExpansionCandidate>) => void;
+  /** Called once every one of an approved candidate's addresses has failed to connect, or shouldExpand itself rejected -- in the latter case, errors holds exactly the one rejection reason, so a caller doesn't need two separate failure channels to observe every way expansion can fail short of success. */
+  onExpansionFailed?: (candidate: Readonly<GossipExpansionCandidate>, errors: readonly Error[]) => void;
+}
+export interface GossipExpansion {
+  /** Feed one just-received peer-advert -- from the session whose peer-adverts this expansion watches, via its own onPeerAdvert hook -- to decide whether it names a newly-discoverable peer worth expanding to, and if so kick off an expansion attempt for it. Never awaits a dial to completion inline: expansion happens in the background, observable only through onExpanded/onExpansionDeclined/onExpansionFailed. */
+  considerAdvert: (advert: Readonly<PeerAdvert>) => void;
+}
+/** Builds the per-device expansion state machine: ask once, dial every advertised address in order on approval, report exactly one outcome. */
+export declare function createGossipExpansion(options: Readonly<GossipExpansionOptions>): GossipExpansion;
+//#endregion

package/dist/domain/gossip-expansion.d.mts

@@ -0,0 +1,29 @@
+import { D as DeviceId, et as PeerAdvert } from "../protocol-PhUVprXA.mjs";
+import { MeshSession } from "./mesh-session.mjs";
+//#region src/domain/gossip-expansion.d.ts
+/** One not-yet-considered device this session's gossip directory has surfaced, carrying only what a dial/trust decision needs: the device-id to decide identity, and the "host:port" addresses its own peer-advert claims are directly reachable at, in the order it advertised them. */
+export interface GossipExpansionCandidate {
+  readonly device: DeviceId;
+  readonly addresses: readonly string[];
+}
+export interface GossipExpansionOptions {
+  /** This session's own device-id, so its own self-advert (looped back through gossip forwarding or a hub's catch-up frame) is never offered to shouldExpand as if it were a distinct peer. */
+  selfDeviceId: DeviceId;
+  /** Decides whether to attempt a direct connection to a newly-discovered device at all -- called at most once per device for this GossipExpansion instance's lifetime, never re-asked if the same device later re-adverts (an address change, a fresher snapshot-seconds). Returning true does not guarantee a connection: dial may still fail for every one of the candidate's addresses, reported via onExpansionFailed. */
+  shouldExpand: (candidate: Readonly<GossipExpansionCandidate>) => Promise<boolean> | boolean;
+  /** Attempts one direct connection to `address`, resolving with a fully connected MeshSession or rejecting if the dial/handshake fails. Typically wraps createMeshSession(transport, identity, ...) followed by session.connect(address, localDomains). Called once per address of an approved candidate, in the order it advertised them, stopping at the first that succeeds -- the caller owns cleanup of any partially-established session behind a rejected dial, since this module never holds a reference to one that didn't resolve. */
+  dial: (address: string) => Promise<MeshSession>;
+  /** Called once a candidate's dial succeeds, with the specific address that connected (one of candidate.addresses, not necessarily the first -- earlier ones may have failed) and the now-connected session, so the caller can wire it into whatever it already does for its own sessions (render it, merge its directory, route messages). */
+  onExpanded: (candidate: Readonly<GossipExpansionCandidate>, address: string, session: MeshSession) => void;
+  /** Called when shouldExpand itself declines a candidate. */
+  onExpansionDeclined?: (candidate: Readonly<GossipExpansionCandidate>) => void;
+  /** Called once every one of an approved candidate's addresses has failed to connect, or shouldExpand itself rejected -- in the latter case, errors holds exactly the one rejection reason, so a caller doesn't need two separate failure channels to observe every way expansion can fail short of success. */
+  onExpansionFailed?: (candidate: Readonly<GossipExpansionCandidate>, errors: readonly Error[]) => void;
+}
+export interface GossipExpansion {
+  /** Feed one just-received peer-advert -- from the session whose peer-adverts this expansion watches, via its own onPeerAdvert hook -- to decide whether it names a newly-discoverable peer worth expanding to, and if so kick off an expansion attempt for it. Never awaits a dial to completion inline: expansion happens in the background, observable only through onExpanded/onExpansionDeclined/onExpansionFailed. */
+  considerAdvert: (advert: Readonly<PeerAdvert>) => void;
+}
+/** Builds the per-device expansion state machine: ask once, dial every advertised address in order on approval, report exactly one outcome. */
+export declare function createGossipExpansion(options: Readonly<GossipExpansionOptions>): GossipExpansion;
+//#endregion

package/dist/domain/gossip-expansion.mjs

@@ -0,0 +1,43 @@
+import { deviceIdToHex } from "./device-id.mjs";
+//#region src/domain/gossip-expansion.ts
+function toError(value) {
+	return value instanceof Error ? value : new Error(String(value));
+}
+/** Builds the per-device expansion state machine: ask once, dial every advertised address in order on approval, report exactly one outcome. */
+function createGossipExpansion(options) {
+	const selfHex = deviceIdToHex(options.selfDeviceId);
+	const considered = /* @__PURE__ */ new Set();
+	async function expand(candidate) {
+		let approved;
+		try {
+			approved = await options.shouldExpand(candidate);
+		} catch (error) {
+			options.onExpansionFailed?.(candidate, [toError(error)]);
+			return;
+		}
+		if (!approved) {
+			options.onExpansionDeclined?.(candidate);
+			return;
+		}
+		const errors = [];
+		for (const address of candidate.addresses) try {
+			const session = await options.dial(address);
+			options.onExpanded(candidate, address, session);
+			return;
+		} catch (error) {
+			errors.push(toError(error));
+		}
+		options.onExpansionFailed?.(candidate, errors);
+	}
+	return { considerAdvert(advert) {
+		const hex = deviceIdToHex(advert.device);
+		if (hex === selfHex || considered.has(hex) || advert.addresses.length === 0) return;
+		considered.add(hex);
+		expand({
+			device: advert.device,
+			addresses: advert.addresses
+		});
+	} };
+}
+//#endregion
+export { createGossipExpansion };

package/dist/domain/mesh-session.cjs

@@ -530,8 +530,8 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 		}
 	};
 }
-function createMeshSession(transport, identity, clock = { now: () => Date.now() }, reconnect = null, addresses = []) {
-	const { session } = createSessionCore(identity, clock, reconnect, async (address) => transport.connect(address), void 0, addresses);
+function createMeshSession(transport, identity, clock = { now: () => Date.now() }, reconnect = null, addresses = [], onPeerAdvert) {
+	const { session } = createSessionCore(identity, clock, reconnect, async (address) => transport.connect(address), onPeerAdvert, addresses);
 	return session;
 }
 /** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
@@ -543,9 +543,11 @@ async function acceptMeshSession(connection, identity, localDomains, options = {
 	});
 	let peerDeviceIdResolved = false;
 	const { session, wireUpConnection } = createSessionCore(identity, clock, null, null, (advert) => {
-		if (peerDeviceIdResolved) return;
-		peerDeviceIdResolved = true;
-		resolvePeerDeviceId?.(advert.device);
+		if (!peerDeviceIdResolved) {
+			peerDeviceIdResolved = true;
+			resolvePeerDeviceId?.(advert.device);
+		}
+		options.onPeerAdvert?.(advert);
 	}, options.addresses, options.onFrame, options.onSessionEnd);
 	await wireUpConnection(connection, options.label ?? "accepted", localDomains);
 	return {

package/dist/domain/mesh-session.d.cts

@@ -95,7 +95,9 @@ export interface MeshSession {
 }
 export declare function createMeshSession(transport: Readonly<Transport>, identity: Readonly<IdentityPort>, clock?: Readonly<Clock>, reconnect?: ReconnectPolicy | null,
 /** This node's own directly-reachable "host:port" candidates (wire-mesh#38), advertised in this session's self-advert so other peers can attempt a direct connection instead of always falling back to a relay. Omit (or pass none) for a caller with nothing to offer, e.g. a browser client. */
-addresses?: readonly string[]): MeshSession;
+addresses?: readonly string[],
+/** Fired for every peer-advert entry as it's applied to the directory, regardless of source -- the hook a gossip-expansion consumer (wire-mesh#187, gossip-expansion.ts's own createGossipExpansion) uses to observe newly-gossiped peers without becoming a second, competing consumer of this session's own single-reader events stream (each emitted SessionEvent wakes at most one waiter, so a second for-await loop over events would silently steal events from whichever consumer already reads it). Omit for a caller with no use for it, exactly today's behaviour. */
+onPeerAdvert?: (advert: PeerAdvert) => void): MeshSession;
 /** A MeshSession built over a connection that already exists (a Transport's own listen() handed it to onConnection), extended with the one thing a dial-side session can't offer: the device-id of the specific peer at the other end. Unlike createMeshSession, which may end up talking to a relay gossiping about many devices at once, an accepted connection is the agent-comms case -- exactly two peers, directly connected -- so "the peer" is well-defined here in a way it structurally isn't for the dial side. */
 export interface AcceptedMeshSession extends MeshSession {
   /** Resolves with the device-id carried by the first peer-advert this connection's remote sends -- the same self-advertisement mechanism createMeshSession's own directory already relies on for every peer, just narrowed to "the one peer this specific connection is with" rather than accumulated into a directory of possibly many. There is no transport-level authentication behind this yet (see wire-mesh#45's own createTlsTransport item): it is only as trustworthy as the remote's own gossip, exactly the same trust level the dial-side directory already has for every entry in it. */
@@ -111,6 +113,8 @@ export interface AcceptedMeshSessionOptions {
   onFrame?: (connection: Readonly<Connection>, frame: Frame) => void | Promise<void>;
   /** Fired once this session's own connection.receive() stream ends -- the counterpart a RelayHub's own forgetConnection needs, since its registry is keyed by this exact Connection and must be cleaned up when it specifically ends. */
   onSessionEnd?: (connection: Readonly<Connection>) => void;
+  /** Fired for every peer-advert entry as it's applied to the directory, regardless of source -- alongside (never instead of) this session's own internal peerDeviceId resolution, which uses this identical hook internally and keeps working unchanged. See createMeshSession's own onPeerAdvert doc comment for why this exists: a gossip-expansion consumer (wire-mesh#187) needs to observe every advert without becoming a second, competing consumer of this session's own single-reader events stream. */
+  onPeerAdvert?: (advert: PeerAdvert) => void;
 }
 /** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
 export declare function acceptMeshSession(connection: Readonly<Connection>, identity: Readonly<IdentityPort>, localDomains: readonly string[], options?: Readonly<AcceptedMeshSessionOptions>): Promise<AcceptedMeshSession>;

package/dist/domain/mesh-session.d.mts

@@ -95,7 +95,9 @@ export interface MeshSession {
 }
 export declare function createMeshSession(transport: Readonly<Transport>, identity: Readonly<IdentityPort>, clock?: Readonly<Clock>, reconnect?: ReconnectPolicy | null,
 /** This node's own directly-reachable "host:port" candidates (wire-mesh#38), advertised in this session's self-advert so other peers can attempt a direct connection instead of always falling back to a relay. Omit (or pass none) for a caller with nothing to offer, e.g. a browser client. */
-addresses?: readonly string[]): MeshSession;
+addresses?: readonly string[],
+/** Fired for every peer-advert entry as it's applied to the directory, regardless of source -- the hook a gossip-expansion consumer (wire-mesh#187, gossip-expansion.ts's own createGossipExpansion) uses to observe newly-gossiped peers without becoming a second, competing consumer of this session's own single-reader events stream (each emitted SessionEvent wakes at most one waiter, so a second for-await loop over events would silently steal events from whichever consumer already reads it). Omit for a caller with no use for it, exactly today's behaviour. */
+onPeerAdvert?: (advert: PeerAdvert) => void): MeshSession;
 /** A MeshSession built over a connection that already exists (a Transport's own listen() handed it to onConnection), extended with the one thing a dial-side session can't offer: the device-id of the specific peer at the other end. Unlike createMeshSession, which may end up talking to a relay gossiping about many devices at once, an accepted connection is the agent-comms case -- exactly two peers, directly connected -- so "the peer" is well-defined here in a way it structurally isn't for the dial side. */
 export interface AcceptedMeshSession extends MeshSession {
   /** Resolves with the device-id carried by the first peer-advert this connection's remote sends -- the same self-advertisement mechanism createMeshSession's own directory already relies on for every peer, just narrowed to "the one peer this specific connection is with" rather than accumulated into a directory of possibly many. There is no transport-level authentication behind this yet (see wire-mesh#45's own createTlsTransport item): it is only as trustworthy as the remote's own gossip, exactly the same trust level the dial-side directory already has for every entry in it. */
@@ -111,6 +113,8 @@ export interface AcceptedMeshSessionOptions {
   onFrame?: (connection: Readonly<Connection>, frame: Frame) => void | Promise<void>;
   /** Fired once this session's own connection.receive() stream ends -- the counterpart a RelayHub's own forgetConnection needs, since its registry is keyed by this exact Connection and must be cleaned up when it specifically ends. */
   onSessionEnd?: (connection: Readonly<Connection>) => void;
+  /** Fired for every peer-advert entry as it's applied to the directory, regardless of source -- alongside (never instead of) this session's own internal peerDeviceId resolution, which uses this identical hook internally and keeps working unchanged. See createMeshSession's own onPeerAdvert doc comment for why this exists: a gossip-expansion consumer (wire-mesh#187) needs to observe every advert without becoming a second, competing consumer of this session's own single-reader events stream. */
+  onPeerAdvert?: (advert: PeerAdvert) => void;
 }
 /** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
 export declare function acceptMeshSession(connection: Readonly<Connection>, identity: Readonly<IdentityPort>, localDomains: readonly string[], options?: Readonly<AcceptedMeshSessionOptions>): Promise<AcceptedMeshSession>;

package/dist/domain/mesh-session.mjs

@@ -529,8 +529,8 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 		}
 	};
 }
-function createMeshSession(transport, identity, clock = { now: () => Date.now() }, reconnect = null, addresses = []) {
-	const { session } = createSessionCore(identity, clock, reconnect, async (address) => transport.connect(address), void 0, addresses);
+function createMeshSession(transport, identity, clock = { now: () => Date.now() }, reconnect = null, addresses = [], onPeerAdvert) {
+	const { session } = createSessionCore(identity, clock, reconnect, async (address) => transport.connect(address), onPeerAdvert, addresses);
 	return session;
 }
 /** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
@@ -542,9 +542,11 @@ async function acceptMeshSession(connection, identity, localDomains, options = {
 	});
 	let peerDeviceIdResolved = false;
 	const { session, wireUpConnection } = createSessionCore(identity, clock, null, null, (advert) => {
-		if (peerDeviceIdResolved) return;
-		peerDeviceIdResolved = true;
-		resolvePeerDeviceId?.(advert.device);
+		if (!peerDeviceIdResolved) {
+			peerDeviceIdResolved = true;
+			resolvePeerDeviceId?.(advert.device);
+		}
+		options.onPeerAdvert?.(advert);
 	}, options.addresses, options.onFrame, options.onSessionEnd);
 	await wireUpConnection(connection, options.label ?? "accepted", localDomains);
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "1.54.0",
+  "version": "1.55.0",
   "dependencies": {
     "cbor2": "2.3.0",
     "cddl.js": "1.0.1",
@@ -91,6 +91,10 @@
       "import": "./dist/domain/erasure-coding.mjs",
       "require": "./dist/domain/erasure-coding.cjs"
     },
+    "./domain/gossip-expansion": {
+      "import": "./dist/domain/gossip-expansion.mjs",
+      "require": "./dist/domain/gossip-expansion.cjs"
+    },
     "./domain/grant-candidates": {
       "import": "./dist/domain/grant-candidates.mjs",
       "require": "./dist/domain/grant-candidates.cjs"