wire-mesh-core 1.48.0 → 1.48.1

package/dist/adapters/frame-codec.cjs

@@ -5,6 +5,14 @@ let cbor2 = require("cbor2");
 function messageFromFrame(frame) {
 	return new Uint8Array((0, cbor2.encode)(frame, cbor2.cdeEncodeOptions));
 }
+/** Wraps frame as a relay-data-frame's own opaque payload, stamping to-device when the caller knows which established pairing to address it to (wire-mesh#30) -- the outbound counterpart to tryDecodeFrame's own doc comment below, which describes the inbound side of the same relay-data envelope. Omitting toDevice leaves the frame unaddressed, which the receiving hub then routes via its own most-recently-established-pairing fallback. */
+function wrapRelayData(frame, toDevice) {
+	return {
+		type: "relay-data",
+		payload: messageFromFrame(frame),
+		...toDevice !== void 0 ? { "to-device": toDevice } : {}
+	};
+}
 /** A frame that fails schema validation, caught separately from a decode failure so it can be dropped without disconnecting. */
 var SchemaInvalidFrameError = class extends Error {
 	constructor(message) {
@@ -35,3 +43,4 @@ exports.SchemaInvalidFrameError = SchemaInvalidFrameError;
 exports.decodeMessage = decodeMessage;
 exports.messageFromFrame = messageFromFrame;
 exports.tryDecodeFrame = tryDecodeFrame;
+exports.wrapRelayData = wrapRelayData;

package/dist/adapters/frame-codec.d.cts

@@ -1,6 +1,8 @@
-import { N as Frame } from "../protocol-CNFRVx9w.cjs";
+import { D as DeviceId, N as Frame, ft as RelayDataFrame } from "../protocol-CNFRVx9w.cjs";
 //#region src/adapters/frame-codec.d.ts
 export declare function messageFromFrame(frame: Frame): Uint8Array<ArrayBuffer>;
+/** Wraps frame as a relay-data-frame's own opaque payload, stamping to-device when the caller knows which established pairing to address it to (wire-mesh#30) -- the outbound counterpart to tryDecodeFrame's own doc comment below, which describes the inbound side of the same relay-data envelope. Omitting toDevice leaves the frame unaddressed, which the receiving hub then routes via its own most-recently-established-pairing fallback. */
+export declare function wrapRelayData(frame: Frame, toDevice?: DeviceId): RelayDataFrame;
 /** A frame that fails schema validation, caught separately from a decode failure so it can be dropped without disconnecting. */
 export declare class SchemaInvalidFrameError extends Error {
   constructor(message: string);

package/dist/adapters/frame-codec.d.mts

@@ -1,6 +1,8 @@
-import { N as Frame } from "../protocol-CNFRVx9w.mjs";
+import { D as DeviceId, N as Frame, ft as RelayDataFrame } from "../protocol-CNFRVx9w.mjs";
 //#region src/adapters/frame-codec.d.ts
 export declare function messageFromFrame(frame: Frame): Uint8Array<ArrayBuffer>;
+/** Wraps frame as a relay-data-frame's own opaque payload, stamping to-device when the caller knows which established pairing to address it to (wire-mesh#30) -- the outbound counterpart to tryDecodeFrame's own doc comment below, which describes the inbound side of the same relay-data envelope. Omitting toDevice leaves the frame unaddressed, which the receiving hub then routes via its own most-recently-established-pairing fallback. */
+export declare function wrapRelayData(frame: Frame, toDevice?: DeviceId): RelayDataFrame;
 /** A frame that fails schema validation, caught separately from a decode failure so it can be dropped without disconnecting. */
 export declare class SchemaInvalidFrameError extends Error {
   constructor(message: string);

package/dist/adapters/frame-codec.mjs

@@ -4,6 +4,14 @@ import { cdeDecodeOptions, cdeEncodeOptions, decode, encode } from "cbor2";
 function messageFromFrame(frame) {
 	return new Uint8Array(encode(frame, cdeEncodeOptions));
 }
+/** Wraps frame as a relay-data-frame's own opaque payload, stamping to-device when the caller knows which established pairing to address it to (wire-mesh#30) -- the outbound counterpart to tryDecodeFrame's own doc comment below, which describes the inbound side of the same relay-data envelope. Omitting toDevice leaves the frame unaddressed, which the receiving hub then routes via its own most-recently-established-pairing fallback. */
+function wrapRelayData(frame, toDevice) {
+	return {
+		type: "relay-data",
+		payload: messageFromFrame(frame),
+		...toDevice !== void 0 ? { "to-device": toDevice } : {}
+	};
+}
 /** A frame that fails schema validation, caught separately from a decode failure so it can be dropped without disconnecting. */
 var SchemaInvalidFrameError = class extends Error {
 	constructor(message) {
@@ -30,4 +38,4 @@ function tryDecodeFrame(bytes) {
 	return result.success ? result.data : null;
 }
 //#endregion
-export { SchemaInvalidFrameError, decodeMessage, messageFromFrame, tryDecodeFrame };
+export { SchemaInvalidFrameError, decodeMessage, messageFromFrame, tryDecodeFrame, wrapRelayData };

package/dist/domain/mesh-session.cjs

@@ -2,6 +2,17 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_domain_device_id = require("./device-id.cjs");
 const require_domain_handshake = require("./handshake.cjs");
 const require_adapters_frame_codec = require("../adapters/frame-codec.cjs");
+//#region src/domain/relay-pairing.ts
+function createRelayPairings() {
+	const established = /* @__PURE__ */ new Map();
+	return {
+		has: (device) => established.has(require_domain_device_id.deviceIdToHex(device)),
+		add: (device) => {
+			established.set(require_domain_device_id.deviceIdToHex(device), device);
+		}
+	};
+}
+//#endregion
 //#region src/domain/mesh-session.ts
 const MS_PER_SECOND = 1e3;
 /** peer-advert's own three typed fields -- reserved so a `sendGossipUpdate` caller can never override the session's own device-id, address list, or freshness timestamp by supplying an extension of the same name. */
@@ -45,7 +56,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 	let attempt = 0;
 	let currentToken = null;
 	let nextRequestId = 0;
-	let relayPeerDevice = null;
+	const relayPairings = createRelayPairings();
 	const pendingManageRequests = /* @__PURE__ */ new Map();
 	const incomingWaiters = [];
 	const incomingBacklog = [];
@@ -90,15 +101,11 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			...token !== null ? { token } : {}
 		};
 	}
-	/** Sends a frame, wrapping it as relay-data first when viaRelay is set -- the single choke point every outbound manage-request/manage-response passes through, so a consumer of sendManageRequest/respond never needs its own relay-wrapping logic. */
-	async function transmit(frame, viaRelay) {
+	/** Sends a frame, wrapping it as relay-data first when viaRelay is set -- the single choke point every outbound manage-request/manage-response passes through, so a consumer of sendManageRequest/respond never needs its own relay-wrapping logic. When relaying, toDevice is stamped onto the outer relay-data-frame's own `to-device` field so the hub addresses it to the correct pairing directly (wire-mesh#30) rather than falling back to whichever pairing it last saw -- the one case this is omitted is a response to a request that itself arrived with no from-device to echo back, which is left to that same hub fallback exactly as an unaddressed relay-data always has been. */
+	async function transmit(frame, viaRelay, toDevice) {
 		if (connection === null) throw new Error("not connected");
 		if (viaRelay) {
-			const relayFrame = {
-				type: "relay-data",
-				payload: require_adapters_frame_codec.messageFromFrame(frame)
-			};
-			await connection.send(relayFrame);
+			await connection.send(require_adapters_frame_codec.wrapRelayData(frame, toDevice));
 			return;
 		}
 		await connection.send(frame);
@@ -111,15 +118,18 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			pending.resolve(frame.outcome);
 		}
 	}
-	function applyManageRequest(frame, viaRelay) {
+	/** relayFrame is present only for a manage-request that arrived wrapped in relay-data, and is that same outer relay-data-frame -- its own to-device/from-device fields carry whatever addressing it received. See IncomingManageRequest's own fromDevice/toDevice doc comments for what each means and why neither is ever guessed from pairing state. */
+	function applyManageRequest(frame, relayFrame) {
 		const requestId = frame["request-id"];
-		const fromDevice = viaRelay && relayPeerDevice !== null ? relayPeerDevice : void 0;
+		const fromDevice = relayFrame?.["from-device"];
+		const toDevice = relayFrame?.["to-device"];
 		emitIncomingManageRequest({
 			requestId,
 			command: frame.command,
 			scope: frame.scope,
 			...frame.token !== void 0 ? { token: frame.token } : {},
 			...fromDevice !== void 0 ? { fromDevice } : {},
+			...toDevice !== void 0 ? { toDevice } : {},
 			respond: async (outcome) => {
 				const response = {
 					type: "manage-response",
@@ -130,7 +140,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 					direction: "sent",
 					frame: response
 				});
-				await transmit(response, viaRelay);
+				await transmit(response, relayFrame !== void 0, fromDevice);
 				emit();
 			}
 		});
@@ -144,7 +154,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 					frame: inner
 				});
 				if (inner.type === "manage-response") applyManageResponse(inner);
-				else applyManageRequest(inner, true);
+				else applyManageRequest(inner, frame);
 				return;
 			}
 			frameLog.push({
@@ -165,15 +175,15 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			});
 			onPeerAdvert?.(advert);
 		}
-		else if (frame.type === "relay-inbound") relayPeerDevice = frame["source-device"];
+		else if (frame.type === "relay-inbound") relayPairings.add(frame["source-device"]);
 		else if (frame.type === "manage-response") applyManageResponse(frame);
-		else if (frame.type === "manage-request") applyManageRequest(frame, false);
+		else if (frame.type === "manage-request") applyManageRequest(frame);
 		else if (frame.type === "revocation-announce") for (const entry of frame.entries) emitRevocationEntry(entry);
 	}
-	/** Establishes a relay-connect pairing to targetDevice if this session isn't already paired with it -- a no-op when it already is, whether that pairing was established by this session's own prior relay-connect (initiator role) or learned from an incoming relay-inbound (target role, replying back to whoever dialed it). relay-connect has no ack frame: the initiator proceeds to relay-data right after sending it. */
+	/** Establishes a relay-connect pairing to targetDevice if this session isn't already paired with it -- a no-op when it already is, whether that pairing was established by this session's own prior relay-connect (initiator role) or learned from an incoming relay-inbound (target role, replying back to whoever dialed it). Pairing with a new target never tears down an existing pairing with a different one: this connection can hold several simultaneously (wire-mesh#30's own multiplexed adjacency map), so a later request back to an already-paired target must not re-send relay-connect for it. relay-connect has no ack frame: the initiator proceeds to relay-data right after sending it. */
 	async function ensureRelayPairing(targetDevice) {
 		if (connection === null) throw new Error("not connected");
-		if (relayPeerDevice !== null && require_domain_device_id.deviceIdToHex(relayPeerDevice) === require_domain_device_id.deviceIdToHex(targetDevice)) return;
+		if (relayPairings.has(targetDevice)) return;
 		const relayConnect = {
 			type: "relay-connect",
 			"target-device": targetDevice
@@ -183,7 +193,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			frame: relayConnect
 		});
 		await connection.send(relayConnect);
-		relayPeerDevice = targetDevice;
+		relayPairings.add(targetDevice);
 		emit();
 	}
 	let localHandshakeSent = localHandshake([]);
@@ -395,7 +405,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 					direction: "sent",
 					frame
 				});
-				await transmit(frame, targetDevice !== void 0);
+				await transmit(frame, targetDevice !== void 0, targetDevice);
 				emit();
 				if (timeoutMs === void 0) return outcome;
 				return Promise.race([outcome, new Promise((resolve) => {

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

@@ -38,8 +38,10 @@ export interface IncomingManageRequest {
   command: ManageCommand;
   scope: CapabilityScope;
   token?: CapabilityToken;
-  /** The device-id of the peer this request was relayed on behalf of, present only when the request arrived wrapped in a relay-data frame rather than directly over this session's own connection. A caller that needs to address a further request back to the same peer (one not sent via respond(), which already routes back correctly on its own) passes this as sendManageRequest's targetDevice. */
+  /** The device-id of the peer this request was relayed on behalf of, read directly from the enclosing relay-data-frame's own `from-device` field (stamped by the hub on every frame it forwards, wire-mesh#30) -- present only when the request arrived wrapped in a relay-data frame that carried one. A caller that needs to address a further request back to the same peer (one not sent via respond(), which already routes back correctly on its own) passes this as sendManageRequest's targetDevice. Never inferred from which relay pairing happens to be most recently established: a connection can hold several concurrent pairings (wire-mesh#30's own multiplexed adjacency map), so only the frame's own per-message addressing can say who actually sent it. */
   fromDevice?: DeviceId;
+  /** The device-id this request's relay-data frame was explicitly addressed to, read from its own `to-device` field -- present only when the request arrived relay-wrapped and the frame carried one. A caller fronting more than one locally-addressable device behind a single hub connection (a gateway advertising several local peers through the same relay pairing) uses this to decide whether the request is for this device or should be routed on to a different local peer it also advertises; this session has no such routing logic of its own, since it represents exactly one identity. */
+  toDevice?: DeviceId;
   respond: (outcome: ManageOutcome) => Promise<void>;
 }
 export type HandshakeStatus = {

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

@@ -38,8 +38,10 @@ export interface IncomingManageRequest {
   command: ManageCommand;
   scope: CapabilityScope;
   token?: CapabilityToken;
-  /** The device-id of the peer this request was relayed on behalf of, present only when the request arrived wrapped in a relay-data frame rather than directly over this session's own connection. A caller that needs to address a further request back to the same peer (one not sent via respond(), which already routes back correctly on its own) passes this as sendManageRequest's targetDevice. */
+  /** The device-id of the peer this request was relayed on behalf of, read directly from the enclosing relay-data-frame's own `from-device` field (stamped by the hub on every frame it forwards, wire-mesh#30) -- present only when the request arrived wrapped in a relay-data frame that carried one. A caller that needs to address a further request back to the same peer (one not sent via respond(), which already routes back correctly on its own) passes this as sendManageRequest's targetDevice. Never inferred from which relay pairing happens to be most recently established: a connection can hold several concurrent pairings (wire-mesh#30's own multiplexed adjacency map), so only the frame's own per-message addressing can say who actually sent it. */
   fromDevice?: DeviceId;
+  /** The device-id this request's relay-data frame was explicitly addressed to, read from its own `to-device` field -- present only when the request arrived relay-wrapped and the frame carried one. A caller fronting more than one locally-addressable device behind a single hub connection (a gateway advertising several local peers through the same relay pairing) uses this to decide whether the request is for this device or should be routed on to a different local peer it also advertises; this session has no such routing logic of its own, since it represents exactly one identity. */
+  toDevice?: DeviceId;
   respond: (outcome: ManageOutcome) => Promise<void>;
 }
 export type HandshakeStatus = {

package/dist/domain/mesh-session.mjs

@@ -1,6 +1,17 @@
 import { deviceIdToHex } from "./device-id.mjs";
 import { negotiate } from "./handshake.mjs";
-import { messageFromFrame, tryDecodeFrame } from "../adapters/frame-codec.mjs";
+import { tryDecodeFrame, wrapRelayData } from "../adapters/frame-codec.mjs";
+//#region src/domain/relay-pairing.ts
+function createRelayPairings() {
+	const established = /* @__PURE__ */ new Map();
+	return {
+		has: (device) => established.has(deviceIdToHex(device)),
+		add: (device) => {
+			established.set(deviceIdToHex(device), device);
+		}
+	};
+}
+//#endregion
 //#region src/domain/mesh-session.ts
 const MS_PER_SECOND = 1e3;
 /** peer-advert's own three typed fields -- reserved so a `sendGossipUpdate` caller can never override the session's own device-id, address list, or freshness timestamp by supplying an extension of the same name. */
@@ -44,7 +55,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 	let attempt = 0;
 	let currentToken = null;
 	let nextRequestId = 0;
-	let relayPeerDevice = null;
+	const relayPairings = createRelayPairings();
 	const pendingManageRequests = /* @__PURE__ */ new Map();
 	const incomingWaiters = [];
 	const incomingBacklog = [];
@@ -89,15 +100,11 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			...token !== null ? { token } : {}
 		};
 	}
-	/** Sends a frame, wrapping it as relay-data first when viaRelay is set -- the single choke point every outbound manage-request/manage-response passes through, so a consumer of sendManageRequest/respond never needs its own relay-wrapping logic. */
-	async function transmit(frame, viaRelay) {
+	/** Sends a frame, wrapping it as relay-data first when viaRelay is set -- the single choke point every outbound manage-request/manage-response passes through, so a consumer of sendManageRequest/respond never needs its own relay-wrapping logic. When relaying, toDevice is stamped onto the outer relay-data-frame's own `to-device` field so the hub addresses it to the correct pairing directly (wire-mesh#30) rather than falling back to whichever pairing it last saw -- the one case this is omitted is a response to a request that itself arrived with no from-device to echo back, which is left to that same hub fallback exactly as an unaddressed relay-data always has been. */
+	async function transmit(frame, viaRelay, toDevice) {
 		if (connection === null) throw new Error("not connected");
 		if (viaRelay) {
-			const relayFrame = {
-				type: "relay-data",
-				payload: messageFromFrame(frame)
-			};
-			await connection.send(relayFrame);
+			await connection.send(wrapRelayData(frame, toDevice));
 			return;
 		}
 		await connection.send(frame);
@@ -110,15 +117,18 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			pending.resolve(frame.outcome);
 		}
 	}
-	function applyManageRequest(frame, viaRelay) {
+	/** relayFrame is present only for a manage-request that arrived wrapped in relay-data, and is that same outer relay-data-frame -- its own to-device/from-device fields carry whatever addressing it received. See IncomingManageRequest's own fromDevice/toDevice doc comments for what each means and why neither is ever guessed from pairing state. */
+	function applyManageRequest(frame, relayFrame) {
 		const requestId = frame["request-id"];
-		const fromDevice = viaRelay && relayPeerDevice !== null ? relayPeerDevice : void 0;
+		const fromDevice = relayFrame?.["from-device"];
+		const toDevice = relayFrame?.["to-device"];
 		emitIncomingManageRequest({
 			requestId,
 			command: frame.command,
 			scope: frame.scope,
 			...frame.token !== void 0 ? { token: frame.token } : {},
 			...fromDevice !== void 0 ? { fromDevice } : {},
+			...toDevice !== void 0 ? { toDevice } : {},
 			respond: async (outcome) => {
 				const response = {
 					type: "manage-response",
@@ -129,7 +139,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 					direction: "sent",
 					frame: response
 				});
-				await transmit(response, viaRelay);
+				await transmit(response, relayFrame !== void 0, fromDevice);
 				emit();
 			}
 		});
@@ -143,7 +153,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 					frame: inner
 				});
 				if (inner.type === "manage-response") applyManageResponse(inner);
-				else applyManageRequest(inner, true);
+				else applyManageRequest(inner, frame);
 				return;
 			}
 			frameLog.push({
@@ -164,15 +174,15 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			});
 			onPeerAdvert?.(advert);
 		}
-		else if (frame.type === "relay-inbound") relayPeerDevice = frame["source-device"];
+		else if (frame.type === "relay-inbound") relayPairings.add(frame["source-device"]);
 		else if (frame.type === "manage-response") applyManageResponse(frame);
-		else if (frame.type === "manage-request") applyManageRequest(frame, false);
+		else if (frame.type === "manage-request") applyManageRequest(frame);
 		else if (frame.type === "revocation-announce") for (const entry of frame.entries) emitRevocationEntry(entry);
 	}
-	/** Establishes a relay-connect pairing to targetDevice if this session isn't already paired with it -- a no-op when it already is, whether that pairing was established by this session's own prior relay-connect (initiator role) or learned from an incoming relay-inbound (target role, replying back to whoever dialed it). relay-connect has no ack frame: the initiator proceeds to relay-data right after sending it. */
+	/** Establishes a relay-connect pairing to targetDevice if this session isn't already paired with it -- a no-op when it already is, whether that pairing was established by this session's own prior relay-connect (initiator role) or learned from an incoming relay-inbound (target role, replying back to whoever dialed it). Pairing with a new target never tears down an existing pairing with a different one: this connection can hold several simultaneously (wire-mesh#30's own multiplexed adjacency map), so a later request back to an already-paired target must not re-send relay-connect for it. relay-connect has no ack frame: the initiator proceeds to relay-data right after sending it. */
 	async function ensureRelayPairing(targetDevice) {
 		if (connection === null) throw new Error("not connected");
-		if (relayPeerDevice !== null && deviceIdToHex(relayPeerDevice) === deviceIdToHex(targetDevice)) return;
+		if (relayPairings.has(targetDevice)) return;
 		const relayConnect = {
 			type: "relay-connect",
 			"target-device": targetDevice
@@ -182,7 +192,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			frame: relayConnect
 		});
 		await connection.send(relayConnect);
-		relayPeerDevice = targetDevice;
+		relayPairings.add(targetDevice);
 		emit();
 	}
 	let localHandshakeSent = localHandshake([]);
@@ -394,7 +404,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 					direction: "sent",
 					frame
 				});
-				await transmit(frame, targetDevice !== void 0);
+				await transmit(frame, targetDevice !== void 0, targetDevice);
 				emit();
 				if (timeoutMs === void 0) return outcome;
 				return Promise.race([outcome, new Promise((resolve) => {

package/package.json

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