@hive-p2p/server 1.0.19 → 1.0.21

package/core/peer-store.mjs

@@ -0,0 +1,252 @@
+import { CLOCK, SIMULATION, NODE, DISCOVERY, LOG_CSS } from './config.mjs';
+const { SANDBOX, ICE_CANDIDATE_EMITTER, TEST_WS_EVENT_MANAGER } = SIMULATION.ENABLED ? await import('../simulation/test-transports.mjs') : {};
+
+export class KnownPeer { // known peer, not necessarily connected
+	neighbors; connectionsCount;
+
+	/** CAUTION: Call this one only in PeerStore.unlinkPeers() @param {Record<string, number>} neighbors key: peerId, value: timestamp */
+	constructor(neighbors = {}) { this.neighbors = neighbors; this.connectionsCount = Object.keys(neighbors).length; }
+
+	/** Set or update neighbor @param {string} peerId @param {number} [timestamp] */
+	setNeighbor(peerId, timestamp = CLOCK.time) {
+		if (!this.neighbors[peerId]) this.connectionsCount++;
+		this.neighbors[peerId] = timestamp;
+	}
+	/** Unset neighbor @param {string} peerId */
+	unsetNeighbor(peerId) {
+		if (this.neighbors[peerId]) this.connectionsCount--;
+		delete this.neighbors[peerId];
+	}
+}
+
+export class PeerConnection { // WebSocket or WebRTC connection wrapper
+	peerId; transportInstance; isWebSocket; direction; pendingUntil; connStartTime;
+
+	/** Connection to a peer, can be WebSocket or WebRTC, can be connecting or connected
+	 * @param {string} peerId
+	 * @param {import('simple-peer').Instance | import('ws').WebSocket} transportInstance
+	 * @param {'in' | 'out'} direction @param {boolean} [isWebSocket] default: false */
+	constructor(peerId, transportInstance, direction, isWebSocket = false) {
+		this.peerId = peerId; this.transportInstance = transportInstance;
+		this.isWebSocket = isWebSocket; this.direction = direction;
+		this.pendingUntil = CLOCK.time + NODE.CONNECTION_UPGRADE_TIMEOUT;
+	}
+	setConnected() { this.connStartTime = CLOCK.time; this.pendingUntil = 0; }
+	getConnectionDuration() { return this.connStartTime ? CLOCK.time - this.connStartTime : 0; }
+	close() { this.isWebSocket ? this.transportInstance?.close() : this.transportInstance?.destroy(); }
+}
+
+/** @typedef {{ in: PeerConnection, out: PeerConnection }} PeerConnecting */
+export class PeerStore { // Manages all peers informations and connections (WebSocket and WebRTC)
+	id; cryptoCodex; offerManager; arbiter; verbose; isDestroy = false;
+
+	/** @type {string[]} The neighbors IDs */ 		neighborsList = []; // faster access
+	/** @type {Record<string, PeerConnecting>} */ 	connecting = {};
+	/** @type {Record<string, PeerConnection>} */ 	connected = {};
+	/** @type {Record<string, KnownPeer>} */ 	  	known = {}; // known peers store
+	/** @type {number} */							knownCount = 0;
+	/** @type {Record<string, number>} */ 			kick = {}; // peerId, timestamp until kick expires
+	/** @type {Record<string, Function[]>} */ 		callbacks = {
+		'connect': [(peerId, direction) => this.#handleConnect(peerId, direction)],
+		'disconnect': [(peerId, direction) => this.#handleDisconnect(peerId, direction)],
+		'signal': [],
+		'data': []
+	};
+
+	/** @param {string} selfId @param {import('./crypto-codex.mjs').CryptoCodex} cryptoCodex @param {import('./ice-offer-manager.mjs').OfferManager} offerManager @param {import('./arbiter.mjs').Arbiter} arbiter @param {number} [verbose] default: 0 */
+	constructor(selfId, cryptoCodex, offerManager, arbiter, verbose = 0) { // SETUP SDP_OFFER_MANAGER CALLBACKS
+		this.id = selfId;
+		this.cryptoCodex = cryptoCodex;
+		this.offerManager = offerManager;
+		this.arbiter = arbiter;
+		this.verbose = verbose; 
+
+		/** @param {string} remoteId @param {any} signalData @param {string} [offerHash] answer only */
+		this.offerManager.onSignalAnswer = (remoteId, signalData, offerHash) => { // answer only
+			if (this.isDestroy || this.isKicked(remoteId) || this.arbiter.isBanished(remoteId)) return; // not accepted
+			for (const cb of this.callbacks.signal) cb(remoteId, { signal: signalData, offerHash });
+		};
+		/** @param {string | undefined} remoteId @param {import('simple-peer').Instance} instance */
+		this.offerManager.onConnect = (remoteId, instance) => {
+			if (this.isDestroy) return instance?.destroy();
+			if (remoteId === this.id) throw new Error(`Refusing to connect to self (${this.id}).`);
+
+			let peerId = remoteId;
+			instance.on('close', () => { if (peerId) for (const cb of this.callbacks.disconnect) cb(peerId, instance.initiator ? 'out' : 'in'); });
+			instance.on('data', data => {
+				if (peerId) for (const cb of this.callbacks.data) cb(peerId, data);
+				else { // FIRST MESSAGE SHOULD BE HANDSHAKE WITH ID
+					const d = new Uint8Array(data); if (d[0] > 127) return; // not unicast, ignore
+					const { route, type, neighborsList } = cryptoCodex.readUnicastMessage(d) || {};
+					if (type !== 'handshake' || route.length !== 2 || route[1] !== this.id) return;
+					
+					peerId = route[0];
+					this.digestPeerNeighbors(peerId, neighborsList); // Update known store
+					for (const cb of this.callbacks.connect) cb(peerId, 'out');
+				}
+			});
+			// IF WE KNOW PEER ID, WE CAN LINK IT (SHOULD BE IN CONNECTING)
+			if (remoteId) for (const cb of this.callbacks.connect) cb(remoteId, 'in');
+		};
+	}
+
+	// GETTERS
+	get publicNeighborsList() { return this.neighborsList.filter(id => this.cryptoCodex.isPublicNode(id)); }
+	get standardNeighborsList() { return this.neighborsList.filter(id => !this.cryptoCodex.isPublicNode(id)); }
+
+	// PRIVATE METHODS
+	/** @param {string} peerId @param {'in' | 'out'} direction */
+	#handleConnect(peerId, direction) { // First callback assigned in constructor
+		if (!this.connecting[peerId]?.[direction]) return this.verbose >= 3 ? console.info(`%cPeer with ID ${peerId} is not connecting.`, LOG_CSS.PEER_STORE) : null;
+		
+		const peerConn = this.connecting[peerId][direction];
+		this.#removePeer(peerId, 'connecting', direction); // remove from connecting now, we are connected or will fail
+		if (this.isKicked(peerId)) {
+			if (this.verbose >= 3) console.info(`%c(${this.id}) Connect => Peer with ID ${peerId} is kicked. => close()`, LOG_CSS.PEER_STORE);
+			return peerConn.close();
+		}
+
+		if (this.connected[peerId]) {
+			if (this.verbose > 1) console.warn(`%c(${this.id}) Connect => Peer with ID ${peerId} is already connected. => close()`, LOG_CSS.PEER_STORE);
+			return peerConn.close();
+		}
+	
+		peerConn.setConnected(); // set connStartTime
+		this.connected[peerId] = peerConn;
+		this.neighborsList.push(peerId);
+		this.#linkPeers(this.id, peerId); // Add link in self store
+		//if (this.verbose > (this.cryptoCodex.isPublicNode(peerId) ? 3 : 2)) console.log(`(${this.id}) ${direction === 'in' ? 'Incoming' : 'Outgoing'} ${peerConn.isWebSocket ? 'WebSocket' : 'WRTC'} connection established with peer ${peerId}`);
+	}
+	#handleDisconnect(peerId, direction) { // First callback assigned in constructor
+		this.#removePeer(peerId, 'connected', direction);
+	}
+	/** Remove a peer from our connections, and unlink from known store
+	 * @param {string} remoteId @param {'connected' | 'connecting' | 'both'} [status] default: both @param {'in' | 'out' | 'both'} [direction] default: both */
+	#removePeer(remoteId, status = 'both', direction = 'both') {
+		if (!remoteId && remoteId === this.id) return;
+
+		const [ connectingConns, connectedConn ] = [ this.connecting[remoteId], this.connected[remoteId] ];
+		//if (connectingConns && connectedConn) throw new Error(`Peer ${remoteId} is both connecting and connected.`);
+		if (!connectingConns && !connectedConn) return;
+		
+		// use negation to apply to 'both' too
+		if (status !== 'connecting' && (connectedConn?.direction === direction || direction === 'both')) {
+			connectedConn?.close();
+			delete this.connected[remoteId];
+			this.neighborsList = Object.keys(this.connected);
+			this.#unlinkPeers(this.id, remoteId); // Remove link in self known store
+		}
+		if (status === 'connected') return; // only remove connected
+		
+		const directionToRemove = direction === 'both' ? ['out', 'in'] : [direction];
+		for (const dir of directionToRemove) delete connectingConns?.[dir];
+
+		if (this.connecting[remoteId]?.['in'] || this.connecting[remoteId]?.['out']) return;
+		delete this.connecting[remoteId]; // no more connection direction => remove entirely
+	}
+	/** Associate two peers as neighbors in known store */
+	#linkPeers(peerId1 = 'toto', peerId2 = 'tutu') {
+		for (const pid of [peerId1, peerId2]) {
+			if (!this.known[pid]) { this.known[pid] = new KnownPeer(); this.knownCount++; }
+			this.known[pid].setNeighbor(pid === peerId1 ? peerId2 : peerId1); // set/update neighbor
+		}
+	}
+	/** Unassociate two peers and remove them from known store if they have no more connections */
+	#unlinkPeers(peerId1 = 'toto', peerId2 = 'tutu') {
+		for (const pid of [peerId1, peerId2]) {
+			if (!this.known[pid]) continue;
+			this.known[pid].unsetNeighbor(pid === peerId1 ? peerId2 : peerId1);
+			if (this.known[pid].connectionsCount > 0) continue;
+			delete this.known[pid];
+			this.knownCount--;
+		}
+	}
+	cleanupExpired(andUpdateKnownBasedOnNeighbors = true) { // Clean up expired pending connections and pending links
+		const now = CLOCK.time;
+		for (const dir of ['in', 'out'])
+			for (const peerId in this.connecting) {
+				if (!this.connecting[peerId][dir]) continue;
+				const bonusTime = this.connected[peerId] ? 10000 : 0; // give some extra time if we are already connected to this peer
+				if (this.connecting[peerId][dir].pendingUntil + bonusTime > now) continue;
+				if (this.verbose >= 4 && !this.connected[peerId]) console.info(`%c(${this.id}) Pending ${dir} connection to peer ${peerId} expired.`, LOG_CSS.PEER_STORE);
+				if (this.verbose > 0 && this.connected[peerId]?.direction === dir) console.info(`%c(${this.id}) Pending ${dir} connection to peer ${peerId} expired (already connected WARNING!).`, 'color: white;');
+				//if (!this.connecting[peerId]?.in?.isWebSocket) this.connecting[peerId]?.in?.close(); // close only in connection => out conn can be used by others answers
+				//else this.connecting[peerId]?.close();
+				if (this.connecting[peerId]?.out?.isWebSocket) this.connecting[peerId].out.close();
+				this.connecting[peerId]?.in?.close();
+				this.#removePeer(peerId, 'connecting', dir);
+			}
+
+		if (!andUpdateKnownBasedOnNeighbors) return;
+		this.neighborsList = Object.keys(this.connected);
+		this.digestPeerNeighbors(this.id, this.neighborsList); // Update self known store
+	}
+
+	// API
+	/** @param {string} callbackType @param {Function} callback */
+	on(callbackType, callback) {
+		if (!this.callbacks[callbackType]) throw new Error(`Unknown callback type: ${callbackType}`);
+		this.callbacks[callbackType].push(callback);
+	}
+	/** Cleanup expired neighbors and return the updated connections count @param {string} peerId */
+	getUpdatedPeerConnectionsCount(peerId, includesPublic = true) {
+		const time = CLOCK.time; let count = 0;
+		const peerNeighbors = this.known[peerId]?.neighbors || {};
+		for (const id in peerNeighbors) {// clean expired links (except self and non-expired)
+			if (id !== this.id && time - peerNeighbors[id] > DISCOVERY.PEER_LINK_EXPIRATION) {
+				this.#unlinkPeers(peerId, id);
+				continue;
+			}
+			if (includesPublic) count++;
+			else if (!this.cryptoCodex.isPublicNode(id)) count++;
+		}
+		return count;
+	}
+	/** Initialize/Get a connecting peer WebRTC connection (SimplePeer Instance)
+	 * @param {string} remoteId @param {{type: 'offer' | 'answer', sdp: Record<string, string>}} signal
+	 * @param {string} [offerHash] offer only */
+	addConnectingPeer(remoteId, signal, offerHash) {
+		if (remoteId === this.id) throw new Error(`Refusing to connect to self (${this.id}).`);
+		
+		const direction = signal.type === 'offer' ? 'in' : 'out';
+		if (this.connecting[remoteId]?.[direction]) return; // already connecting out (should not happen)
+
+		const instance = this.offerManager.getTransportInstanceForSignal(remoteId, signal, offerHash);
+		if (!instance) return this.verbose > 3 ? console.info(`%cFailed to get transport instance for signal from ${remoteId}.`, LOG_CSS.PEER_STORE) : null;
+
+		if (!this.connecting[remoteId]) this.connecting[remoteId] = {};
+		this.connecting[remoteId][direction] = new PeerConnection(remoteId, instance, direction);
+		return true;
+	}
+	/** @param {string} remoteId @param {{type: 'offer' | 'answer', sdp: Record<string, string>}} signal @param {string} [offerHash] answer only @param {number} timestamp Answer reception timestamp */
+	assignSignal(remoteId, signal, offerHash, timestamp) {
+		const peerConn = this.connecting[remoteId]?.[signal.type === 'offer' ? 'in' : 'out'];
+		try {
+			if (peerConn?.isWebSocket) throw new Error(`Cannot assign signal for ID ${remoteId}. (WebSocket)`);
+			if (signal.type === 'answer') this.offerManager.addSignalAnswer(remoteId, signal, offerHash, timestamp);
+			else peerConn.transportInstance.signal(signal);
+		} catch (error) { console.error(`Error signaling ${signal?.type} for ${remoteId}:`, error.stack); }
+	}
+	/** Avoid peer connection @param {string} peerId @param {number} duration default: 60_000ms @param {string} [reason] */
+	kickPeer(peerId, duration = 60_000, reason) {
+		if (duration) this.kick[peerId] = CLOCK.time + duration;
+		this.#removePeer(peerId, 'both');
+		if (this.verbose > 1) console.log(`%c(${this.id}) Kicked peer ${peerId} for ${duration / 1000}s. ${reason ? '| Reason: ' + reason : ''}`, 'color: green;');
+	}
+	isKicked(peerId) { return this.kick[peerId] && this.kick[peerId] > CLOCK.time; }
+	/** Improve discovery by considering used route as peer links @param {string[]} route */
+	digestValidRoute(route = []) { for (let i = 1; i < route.length; i++) this.#linkPeers(route[i - 1], route[i]); }
+	/** @param {string} peerId @param {string[]} neighbors */
+	digestPeerNeighbors(peerId, neighbors = []) { // Update known neighbors
+		if (!peerId || !Array.isArray(neighbors)) return;
+		for (const id in this.known[peerId]?.neighbors || {}) // remove old links
+			if (!neighbors.includes(id)) this.#unlinkPeers(peerId, id);
+		for (const p of neighbors) this.#linkPeers(peerId, p);
+	}
+	destroy() {
+		this.isDestroy = true;
+		for (const [peerId, conn] of Object.entries(this.connected)) { this.#removePeer(peerId); conn.close(); }
+		for (const [peerId, connObj] of Object.entries(this.connecting)) { this.#removePeer(peerId); connObj['in']?.close(); connObj['out']?.close(); }
+		this.offerManager.destroy();
+	}
+}

package/core/route-builder.mjs

@@ -0,0 +1,176 @@
+/**
+ * @typedef {import('./peer-store.mjs').PeerStore} PeerStore
+ * 
+ * @typedef {Object} RouteInfo
+ * @property {string[]} path - Array of peer IDs forming the route [from, ..., remoteId]
+ * @property {number} hops - Number of hops/relays in the route (path.length - 1)
+ *
+ * @typedef {Object} RouteResult
+ * @property {RouteInfo[]} routes - Array of found routes, sorted by quality (best first)
+ * @property {boolean | 'blind'} success - Whether at least one route was found
+ * @property {number} nodesExplored - Number of nodes visited during search
+ */
+
+/** Optimized route finder using bidirectional BFS and early stopping
+ * Much more efficient than V1 for longer paths by searching from both ends */
+export class RouteBuilder_V2 {
+	/** @type {Record<string, RouteInfo[]>} */
+	cache = {}; // key: remoteId, value: paths
+	peerStore;
+
+	/** @param {string} selfId @param {PeerStore} peerStore */
+	constructor(selfId, peerStore) {
+		this.id = selfId;
+		this.peerStore = peerStore;
+	}
+
+	/** Find routes using bidirectional BFS with early stopping
+	 * @param {string} remoteId - Destination peer ID
+	 * @param {number} maxRoutes - Maximum number of routes to return (default: 5)
+	 * @param {number} maxHops - Maximum relays allowed (default: 3)
+	 * @param {number} maxNodes - Maximum nodes to explore (default: 1728)
+	 * @param {boolean} sortByScore - Whether to sort routes by score (default: true)
+	 * @param {number} goodEnoughHops - Early stop threshold (default: 3 hops)
+	 * @returns {RouteResult} Result containing found routes and metadata */
+	buildRoutes(remoteId, maxRoutes = 5, maxHops = 3, maxNodes = 1728, sortByHops = true, goodEnoughHops = 3) {
+		if (this.id === remoteId) throw new Error('Cannot build route to self');
+		if (this.peerStore.connected[remoteId]) return { routes: [{ path: [this.id, remoteId]}], success: true, nodesExplored: 1 };
+		if (!this.peerStore.known[remoteId]) return this.#buildBlindRoutes(remoteId);
+
+		if (this.cache[remoteId] && this.#verifyRoutesStillValid(this.cache[remoteId]))
+			return { routes: this.cache[remoteId], success: true, nodesExplored: 0 };
+
+		const result = this.#bidirectionalSearch(remoteId, maxHops, maxNodes, goodEnoughHops);
+		if (!result.success) return { routes: [], success: false, nodesExplored: result.nodesExplored };
+		
+		const routes = this.#buildRoutesFromPathsAndSortByHops(result.paths, sortByHops);
+		const selectedRoutes = routes.slice(0, maxRoutes);
+		this.cache[remoteId] = selectedRoutes;
+		return { routes: selectedRoutes, success: true, nodesExplored: result.nodesExplored };
+	}
+	/** @param {RouteInfo[]} routes */
+	#verifyRoutesStillValid(routes) {
+		// Check if all nodes are still known and connections still exist
+		for (const { path } of routes) {
+			for (let i = 1; i < path.length; i++) {
+				const from = path[i - 1];
+				const to = path[i];
+				if (from === this.id) {
+					if (!this.peerStore.connected[to]) return false;
+				} else {
+					if (!this.peerStore.known[from]?.neighbors?.[to]) return false;
+				}
+			}
+		}
+		return true;
+	}
+	#buildRoutesFromPathsAndSortByHops(paths, sortByHops) {
+		const routes = [];
+		for (const path of paths) routes.push({ path, hops: path.length - 1 });
+		if (sortByHops) routes.sort((a, b) => a.hops - b.hops);
+		return routes;
+	}
+	// Build blind routes via all connected peers in shuffled order
+	#buildBlindRoutes(remoteId) {
+		const routes = [];
+		const connected = this.peerStore.neighborsList;
+		const shuffledIndexes = [...Array(connected.length).keys()].sort(() => Math.random() - 0.5);
+		for (const i of shuffledIndexes) routes.push({ path: [this.id, connected[i], remoteId], hops: 0, score: 0 });
+
+		if (routes.length === 0) return { routes: [], success: false, nodesExplored: 0 };
+		else return { routes, success: 'blind', nodesExplored: routes.length };
+	}
+
+	/** Bidirectional BFS: search from both ends until they meet
+	 * @param {string} remoteId - Target peer
+	 * @param {number} maxHops - Max hops allowed
+	 * @param {number} maxNodes - Max nodes to explore
+	 * @param {number} goodEnoughHops - Early stop threshold
+	 * @returns {{success: boolean, paths: string[][], nodesExplored: number}} */
+	#bidirectionalSearch(remoteId, maxHops, maxNodes, goodEnoughHops) {
+		const foundPaths = [];
+		let nodesExplored = 0;
+
+		// Forward: from id outward
+		const forwardQueue = [{ node: this.id, path: [this.id], pathSet: new Set([this.id]), depth: 0 }];
+		const forwardVisited = new Map(); // node -> path from id
+		forwardVisited.set(this.id, [this.id]);
+
+		// Backward: from remoteId outward
+		const backwardQueue = [{ node: remoteId, path: [remoteId], pathSet: new Set([remoteId]), depth: 0 }];
+		const backwardVisited = new Map(); // node -> path from remoteId
+		backwardVisited.set(remoteId, [remoteId]);
+
+		const maxDepthPerSide = Math.ceil(maxHops / 2);
+		while ((forwardQueue.length > 0 || backwardQueue.length > 0) && nodesExplored < maxNodes) {
+			if (forwardQueue.length > 0) { // Expand forward search
+				const meetings = this.#expandOneSide(forwardQueue, forwardVisited, backwardVisited, maxDepthPerSide);
+				for (const meetingNode of meetings) {
+					const completePath = this.#buildCompletePath(forwardVisited.get(meetingNode), backwardVisited.get(meetingNode));
+					foundPaths.push(completePath);
+					if (completePath.length - 1 > goodEnoughHops) continue;
+					return { success: true, paths: foundPaths, nodesExplored };
+				}
+				nodesExplored++;
+			}
+
+			if (backwardQueue.length > 0) { // Expand backward search
+				const meetings = this.#expandOneSide(backwardQueue, backwardVisited, forwardVisited, maxDepthPerSide);
+				for (const meetingNode of meetings) {
+					const completePath = this.#buildCompletePath(forwardVisited.get(meetingNode), backwardVisited.get(meetingNode));
+					foundPaths.push(completePath);
+					if (completePath.length - 1 > goodEnoughHops) continue;
+					return { success: true, paths: foundPaths, nodesExplored };
+				}
+				nodesExplored++;
+			}
+		}
+
+		return { success: foundPaths.length > 0, paths: foundPaths, nodesExplored };
+	}
+
+	/** Expand one side of the search and return meeting nodes
+ * @param {Array} queue - Search queue for this side
+ * @param {Map} visited - This side's visited nodes (node -> path)
+ * @param {Map} otherVisited - Other side's visited nodes
+ * @param {number} maxDepth - Max depth for this side
+ * @returns {string[]} Array of meeting node IDs found this iteration */
+	#expandOneSide(queue, visited, otherVisited, maxDepth) {
+		if (queue.length === 0) return [];
+
+		const { node: current, path, pathSet, depth } = queue.shift();
+		if (depth >= maxDepth) return [];
+
+		const meetings = [];
+		function processNeighbor(neighborId) {
+			if (pathSet.has(neighborId)) return;
+			
+			const newDepth = depth + 1;
+			if (otherVisited.has(neighborId)) meetings.push(neighborId);
+			if (visited.has(neighborId)) return;
+
+			const newPath = [...path, neighborId];
+			const newPathSet = new Set(pathSet).add(neighborId);
+			visited.set(neighborId, newPath);
+			queue.push({ node: neighborId, path: newPath, pathSet: newPathSet, depth: newDepth });
+		}
+
+		if (current === this.id) for (const neighborId of this.peerStore.neighborsList) processNeighbor(neighborId);
+		else for (const neighborId in this.peerStore.known[current]?.neighbors || {}) processNeighbor(neighborId);
+
+		return meetings;
+	}
+
+	/** Build complete path from meeting point
+	 * @param {string[]} forwardPath - Path from selfId to meeting point
+	 * @param {string[]} backwardPath - Path from remoteId to meeting point  
+	 * @returns {string[]} Complete path from selfId to remoteId */
+	#buildCompletePath(forwardPath, backwardPath) {
+		const totalLength = forwardPath.length + backwardPath.length - 1;
+		const result = new Array(totalLength);
+		let index = 0;
+		for (const node of forwardPath) result[index++] = node;
+		for (let i = backwardPath.length - 2; i >= 0; i--) result[index++] = backwardPath[i];
+		return result;
+	}
+}