wire-mesh-core 3.6.0 → 3.6.1

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

@@ -81,7 +81,17 @@ export interface MeshSession {
   readonly coordinatorFrames: AsyncIterable<CoordinatorFrame>;
   connect: (address: string, localDomains: readonly string[]) => Promise<void>;
   sendPing: () => Promise<void>;
-  /** Sends a ping-frame and resolves with the round-trip time in milliseconds once the correlated pong-frame arrives -- FIFO-paired against this call's own ping, since ping-frame carries no correlation id of its own (spec/transport.cddl): the Nth call's own promise resolves against the Nth pong received after it, never matched by any other means. Rejects if the connection closes, or (when timeoutMs is given) if no pong arrives within timeoutMs, rather than resolving a sentinel value the way sendManageRequest's own timeout does -- there is no natural "no answer" value for a bare millisecond count to double as. Unlike sendPing (fire-and-forget, answered by nothing on an ordinary peer connection), this is answered only by a peer that replies to ping with pong -- today, relay-hub's own frame handling (wire-mesh#181) -- so calling this against a connection to a plain peer that never sends pong hangs until timeoutMs (if given) or forever. Exists to isolate the sender-to-hub leg of a relayed path.trace round trip: time this over the same connection a relayed manage-request travelled, then subtract it from path.trace's own end-to-end RTT to recover the hub-to-target leg. */
+  /**
+   * Sends a ping-frame and resolves with the round-trip time in milliseconds once the correlated pong-frame arrives.
+   *
+   * The pairing is FIFO because ping-frame carries no correlation id of its own (spec/transport.cddl): the Nth call's promise resolves against the Nth pong received after it, never matched by any other means.
+   *
+   * Rejects with a plain Error if the connection closes, and with a PingTimeoutError (from ping-round-trips.ts) when `timeoutMs` is given and no pong arrives within it, so a caller can tell an unanswered ping from a dropped connection. It never resolves a sentinel the way sendManageRequest's own timeout does, because there is no natural "no answer" value for a bare millisecond count to double as.
+   *
+   * Unlike sendPing (fire-and-forget, answered by nothing on an ordinary peer connection), this is answered only by a peer that replies to ping with pong, which today means relay-hub's own frame handling (wire-mesh#181). Called against a plain peer that never sends pong it hangs until `timeoutMs` if given, or forever.
+   *
+   * It exists to isolate the sender-to-hub leg of a relayed path.trace round trip: time it over the same connection a relayed manage-request travelled, then subtract it from path.trace's own end-to-end RTT to recover the hub-to-target leg.
+   */
   sendPingMeasureRtt: (timeoutMs?: number) => Promise<number>;
   /** Attaches this token to every `manage-request` sent from now on. */
   setToken: (token: CapabilityToken) => void;

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

@@ -81,7 +81,17 @@ export interface MeshSession {
   readonly coordinatorFrames: AsyncIterable<CoordinatorFrame>;
   connect: (address: string, localDomains: readonly string[]) => Promise<void>;
   sendPing: () => Promise<void>;
-  /** Sends a ping-frame and resolves with the round-trip time in milliseconds once the correlated pong-frame arrives -- FIFO-paired against this call's own ping, since ping-frame carries no correlation id of its own (spec/transport.cddl): the Nth call's own promise resolves against the Nth pong received after it, never matched by any other means. Rejects if the connection closes, or (when timeoutMs is given) if no pong arrives within timeoutMs, rather than resolving a sentinel value the way sendManageRequest's own timeout does -- there is no natural "no answer" value for a bare millisecond count to double as. Unlike sendPing (fire-and-forget, answered by nothing on an ordinary peer connection), this is answered only by a peer that replies to ping with pong -- today, relay-hub's own frame handling (wire-mesh#181) -- so calling this against a connection to a plain peer that never sends pong hangs until timeoutMs (if given) or forever. Exists to isolate the sender-to-hub leg of a relayed path.trace round trip: time this over the same connection a relayed manage-request travelled, then subtract it from path.trace's own end-to-end RTT to recover the hub-to-target leg. */
+  /**
+   * Sends a ping-frame and resolves with the round-trip time in milliseconds once the correlated pong-frame arrives.
+   *
+   * The pairing is FIFO because ping-frame carries no correlation id of its own (spec/transport.cddl): the Nth call's promise resolves against the Nth pong received after it, never matched by any other means.
+   *
+   * Rejects with a plain Error if the connection closes, and with a PingTimeoutError (from ping-round-trips.ts) when `timeoutMs` is given and no pong arrives within it, so a caller can tell an unanswered ping from a dropped connection. It never resolves a sentinel the way sendManageRequest's own timeout does, because there is no natural "no answer" value for a bare millisecond count to double as.
+   *
+   * Unlike sendPing (fire-and-forget, answered by nothing on an ordinary peer connection), this is answered only by a peer that replies to ping with pong, which today means relay-hub's own frame handling (wire-mesh#181). Called against a plain peer that never sends pong it hangs until `timeoutMs` if given, or forever.
+   *
+   * It exists to isolate the sender-to-hub leg of a relayed path.trace round trip: time it over the same connection a relayed manage-request travelled, then subtract it from path.trace's own end-to-end RTT to recover the hub-to-target leg.
+   */
   sendPingMeasureRtt: (timeoutMs?: number) => Promise<number>;
   /** Attaches this token to every `manage-request` sent from now on. */
   setToken: (token: CapabilityToken) => void;

package/dist/domain/ping-round-trips.cjs

@@ -1,5 +1,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/domain/ping-round-trips.ts
+/** Why a ping was given up on: no pong arrived within the caller's `timeoutMs`. A call rejected for any other reason (the connection dropped or closed first) rejects with a plain Error, so a caller counting unanswered pings tells the two apart by this class rather than by message text. */
+var PingTimeoutError = class extends Error {
+	constructor() {
+		super("timed out waiting for pong");
+		this.name = "PingTimeoutError";
+	}
+};
 function createPingRoundTrips() {
 	const pending = [];
 	function cancel(sentAt) {
@@ -28,11 +35,12 @@ function createPingRoundTrips() {
 			if (timeoutMs === void 0) return rtt;
 			return Promise.race([rtt, new Promise((_resolve, reject) => {
 				setTimeout(() => {
-					if (cancel(sentAt)) reject(/* @__PURE__ */ new Error("timed out waiting for pong"));
+					if (cancel(sentAt)) reject(new PingTimeoutError());
 				}, timeoutMs);
 			})]);
 		}
 	};
 }
 //#endregion
+exports.PingTimeoutError = PingTimeoutError;
 exports.createPingRoundTrips = createPingRoundTrips;

package/dist/domain/ping-round-trips.d.cts

@@ -1,4 +1,8 @@
 //#region src/domain/ping-round-trips.d.ts
+/** Why a ping was given up on: no pong arrived within the caller's `timeoutMs`. A call rejected for any other reason (the connection dropped or closed first) rejects with a plain Error, so a caller counting unanswered pings tells the two apart by this class rather than by message text. */
+export declare class PingTimeoutError extends Error {
+  constructor();
+}
 export interface PingRoundTrips {
   /** Resolves the oldest still-pending call with (nowMs - itsOwnSentAt) -- called once per pong-frame received. A no-op if nothing is pending (a stray pong with no outstanding call). */
   resolveOldest: (nowMs: number) => void;

package/dist/domain/ping-round-trips.d.mts

@@ -1,4 +1,8 @@
 //#region src/domain/ping-round-trips.d.ts
+/** Why a ping was given up on: no pong arrived within the caller's `timeoutMs`. A call rejected for any other reason (the connection dropped or closed first) rejects with a plain Error, so a caller counting unanswered pings tells the two apart by this class rather than by message text. */
+export declare class PingTimeoutError extends Error {
+  constructor();
+}
 export interface PingRoundTrips {
   /** Resolves the oldest still-pending call with (nowMs - itsOwnSentAt) -- called once per pong-frame received. A no-op if nothing is pending (a stray pong with no outstanding call). */
   resolveOldest: (nowMs: number) => void;

package/dist/domain/ping-round-trips.mjs

@@ -1,4 +1,11 @@
 //#region src/domain/ping-round-trips.ts
+/** Why a ping was given up on: no pong arrived within the caller's `timeoutMs`. A call rejected for any other reason (the connection dropped or closed first) rejects with a plain Error, so a caller counting unanswered pings tells the two apart by this class rather than by message text. */
+var PingTimeoutError = class extends Error {
+	constructor() {
+		super("timed out waiting for pong");
+		this.name = "PingTimeoutError";
+	}
+};
 function createPingRoundTrips() {
 	const pending = [];
 	function cancel(sentAt) {
@@ -27,11 +34,11 @@ function createPingRoundTrips() {
 			if (timeoutMs === void 0) return rtt;
 			return Promise.race([rtt, new Promise((_resolve, reject) => {
 				setTimeout(() => {
-					if (cancel(sentAt)) reject(/* @__PURE__ */ new Error("timed out waiting for pong"));
+					if (cancel(sentAt)) reject(new PingTimeoutError());
 				}, timeoutMs);
 			})]);
 		}
 	};
 }
 //#endregion
-export { createPingRoundTrips };
+export { PingTimeoutError, createPingRoundTrips };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "dependencies": {
     "cbor2": "2.3.0",
     "cddl.js": "1.0.1",