react-native-ble-mesh 1.0.1

package/src/mesh/peer/Peer.js

@@ -0,0 +1,242 @@
+'use strict';
+
+/**
+ * @fileoverview Peer class representing a network participant
+ * @module mesh/peer/Peer
+ */
+
+const { CONNECTION_STATE } = require('../../constants');
+const { ValidationError } = require('../../errors');
+
+/**
+ * Represents a peer in the mesh network
+ * @class Peer
+ */
+class Peer {
+  /**
+   * Creates a new Peer
+   * @param {Object} options - Peer options
+   * @param {string} options.id - Unique peer identifier
+   * @param {Uint8Array} [options.publicKey] - Peer's public key
+   * @param {string} [options.name] - Display name
+   * @param {number} [options.rssi] - Signal strength
+   * @param {number} [options.hopCount] - Distance in hops
+   */
+  constructor(options) {
+    if (!options || typeof options.id !== 'string' || options.id.length === 0) {
+      throw ValidationError.invalidArgument('id', options?.id, {
+        reason: 'Peer ID must be a non-empty string'
+      });
+    }
+
+    /**
+     * Unique peer identifier
+     * @type {string}
+     */
+    this.id = options.id;
+
+    /**
+     * Peer's public key
+     * @type {Uint8Array|null}
+     */
+    this.publicKey = options.publicKey || null;
+
+    /**
+     * Display name
+     * @type {string}
+     */
+    this.name = options.name || '';
+
+    /**
+     * Received signal strength indicator
+     * @type {number}
+     */
+    this.rssi = typeof options.rssi === 'number' ? options.rssi : 0;
+
+    /**
+     * Distance in hops (0 = direct connection)
+     * @type {number}
+     */
+    this.hopCount = typeof options.hopCount === 'number' ? options.hopCount : 0;
+
+    /**
+     * Timestamp of last interaction
+     * @type {number}
+     */
+    this.lastSeen = Date.now();
+
+    /**
+     * Timestamp when peer was first discovered
+     * @type {number}
+     */
+    this.discoveredAt = Date.now();
+
+    /**
+     * Current connection state
+     * @type {string}
+     */
+    this.connectionState = CONNECTION_STATE.DISCONNECTED;
+
+    /**
+     * Whether a secure session has been established
+     * @type {boolean}
+     */
+    this.hasSecureSession = false;
+
+    /**
+     * Additional metadata
+     * @type {Object}
+     */
+    this.metadata = options.metadata || {};
+  }
+
+  /**
+   * Checks if peer is currently connected
+   * @returns {boolean} True if connected
+   */
+  isConnected() {
+    return this.connectionState === CONNECTION_STATE.CONNECTED ||
+           this.connectionState === CONNECTION_STATE.SECURING ||
+           this.connectionState === CONNECTION_STATE.SECURED;
+  }
+
+  /**
+   * Checks if peer has a secure session
+   * @returns {boolean} True if secured
+   */
+  isSecured() {
+    return this.hasSecureSession &&
+           this.connectionState === CONNECTION_STATE.SECURED;
+  }
+
+  /**
+   * Checks if peer is directly connected (not via relay)
+   * @returns {boolean} True if directly connected
+   */
+  isDirect() {
+    return this.hopCount === 0 && this.isConnected();
+  }
+
+  /**
+   * Updates the last seen timestamp
+   * @param {number} [timestamp] - Custom timestamp, defaults to now
+   */
+  updateLastSeen(timestamp = Date.now()) {
+    this.lastSeen = timestamp;
+  }
+
+  /**
+   * Updates the connection state
+   * @param {string} state - New connection state
+   */
+  setConnectionState(state) {
+    if (!Object.values(CONNECTION_STATE).includes(state)) {
+      throw ValidationError.invalidArgument('state', state, {
+        validValues: Object.values(CONNECTION_STATE)
+      });
+    }
+    this.connectionState = state;
+    this.updateLastSeen();
+  }
+
+  /**
+   * Marks the peer as having a secure session
+   */
+  markSecured() {
+    this.hasSecureSession = true;
+    this.connectionState = CONNECTION_STATE.SECURED;
+    this.updateLastSeen();
+  }
+
+  /**
+   * Updates the public key
+   * @param {Uint8Array} publicKey - New public key
+   */
+  setPublicKey(publicKey) {
+    if (!(publicKey instanceof Uint8Array)) {
+      throw ValidationError.invalidType('publicKey', publicKey, 'Uint8Array');
+    }
+    this.publicKey = publicKey;
+  }
+
+  /**
+   * Gets the age of the peer since last seen
+   * @returns {number} Milliseconds since last seen
+   */
+  getAge() {
+    return Date.now() - this.lastSeen;
+  }
+
+  /**
+   * Checks if the peer has gone stale
+   * @param {number} maxAge - Maximum age in milliseconds
+   * @returns {boolean} True if stale
+   */
+  isStale(maxAge) {
+    return this.getAge() > maxAge;
+  }
+
+  /**
+   * Creates a copy of the peer
+   * @returns {Peer} New Peer instance
+   */
+  clone() {
+    const peer = new Peer({
+      id: this.id,
+      publicKey: this.publicKey ? new Uint8Array(this.publicKey) : null,
+      name: this.name,
+      rssi: this.rssi,
+      hopCount: this.hopCount,
+      metadata: { ...this.metadata }
+    });
+    peer.lastSeen = this.lastSeen;
+    peer.discoveredAt = this.discoveredAt;
+    peer.connectionState = this.connectionState;
+    peer.hasSecureSession = this.hasSecureSession;
+    return peer;
+  }
+
+  /**
+   * Converts peer to a JSON-serializable object
+   * @returns {Object} JSON representation
+   */
+  toJSON() {
+    return {
+      id: this.id,
+      publicKey: this.publicKey ? Array.from(this.publicKey) : null,
+      name: this.name,
+      rssi: this.rssi,
+      hopCount: this.hopCount,
+      lastSeen: this.lastSeen,
+      discoveredAt: this.discoveredAt,
+      connectionState: this.connectionState,
+      hasSecureSession: this.hasSecureSession,
+      isConnected: this.isConnected(),
+      isSecured: this.isSecured(),
+      metadata: this.metadata
+    };
+  }
+
+  /**
+   * Creates a Peer from JSON data
+   * @param {Object} data - JSON data
+   * @returns {Peer} New Peer instance
+   */
+  static fromJSON(data) {
+    const peer = new Peer({
+      id: data.id,
+      publicKey: data.publicKey ? new Uint8Array(data.publicKey) : null,
+      name: data.name,
+      rssi: data.rssi,
+      hopCount: data.hopCount,
+      metadata: data.metadata || {}
+    });
+    if (data.lastSeen) { peer.lastSeen = data.lastSeen; }
+    if (data.discoveredAt) { peer.discoveredAt = data.discoveredAt; }
+    if (data.connectionState) { peer.connectionState = data.connectionState; }
+    if (data.hasSecureSession) { peer.hasSecureSession = data.hasSecureSession; }
+    return peer;
+  }
+}
+
+module.exports = Peer;

package/src/mesh/peer/PeerDiscovery.js

@@ -0,0 +1,280 @@
+'use strict';
+
+/**
+ * @fileoverview Peer discovery protocol handler
+ * @module mesh/peer/PeerDiscovery
+ */
+
+const EventEmitter = require('events');
+const { MESSAGE_TYPE, EVENTS } = require('../../constants');
+const { ValidationError } = require('../../errors');
+
+/**
+ * Discovery message payload structure
+ * @typedef {Object} DiscoveryPayload
+ * @property {string} peerId - Announcing peer's ID
+ * @property {string} [name] - Display name
+ * @property {number[]} [publicKey] - Public key bytes
+ * @property {number} [hopCount] - Hop count
+ * @property {Object} [capabilities] - Peer capabilities
+ */
+
+/**
+ * Handles peer discovery protocol messages
+ * @class PeerDiscovery
+ * @extends EventEmitter
+ */
+class PeerDiscovery extends EventEmitter {
+  /**
+   * Creates a new PeerDiscovery handler
+   * @param {Object} options - Configuration options
+   * @param {string} options.localPeerId - Local peer's ID
+   * @param {Uint8Array} [options.publicKey] - Local peer's public key
+   * @param {string} [options.displayName] - Local display name
+   */
+  constructor(options = {}) {
+    super();
+
+    if (!options.localPeerId || typeof options.localPeerId !== 'string') {
+      throw ValidationError.invalidArgument('localPeerId', options.localPeerId);
+    }
+
+    /**
+     * Local peer ID
+     * @type {string}
+     */
+    this.localPeerId = options.localPeerId;
+
+    /**
+     * Local public key
+     * @type {Uint8Array|null}
+     */
+    this.publicKey = options.publicKey || null;
+
+    /**
+     * Display name
+     * @type {string}
+     */
+    this.displayName = options.displayName || '';
+
+    /**
+     * Capabilities advertised to peers
+     * @type {Object}
+     */
+    this.capabilities = options.capabilities || {};
+
+    /**
+     * Discovery statistics
+     * @type {Object}
+     * @private
+     */
+    this._stats = {
+      announcesSent: 0,
+      announcesReceived: 0,
+      requestsSent: 0,
+      requestsReceived: 0,
+      responsesSent: 0,
+      responsesReceived: 0
+    };
+  }
+
+  /**
+   * Creates an announce message payload
+   * @returns {Object} Announce payload
+   */
+  createAnnouncePayload() {
+    const payload = {
+      peerId: this.localPeerId,
+      name: this.displayName,
+      timestamp: Date.now(),
+      capabilities: this.capabilities
+    };
+
+    if (this.publicKey) {
+      payload.publicKey = Array.from(this.publicKey);
+    }
+
+    return payload;
+  }
+
+  /**
+   * Creates a peer request payload
+   * @param {string} [targetPeerId] - Specific peer to request (null for broadcast)
+   * @returns {Object} Request payload
+   */
+  createRequestPayload(targetPeerId = null) {
+    return {
+      requesterId: this.localPeerId,
+      targetPeerId: targetPeerId,
+      timestamp: Date.now()
+    };
+  }
+
+  /**
+   * Creates a peer response payload
+   * @param {string} requesterId - ID of requesting peer
+   * @returns {Object} Response payload
+   */
+  createResponsePayload(requesterId) {
+    return {
+      responderId: this.localPeerId,
+      requesterId: requesterId,
+      name: this.displayName,
+      publicKey: this.publicKey ? Array.from(this.publicKey) : null,
+      timestamp: Date.now(),
+      capabilities: this.capabilities
+    };
+  }
+
+  /**
+   * Processes an incoming discovery message
+   * @param {number} type - Message type
+   * @param {Object} payload - Message payload
+   * @param {string} sourcePeerId - Source peer ID
+   * @returns {Object|null} Response to send, or null
+   */
+  processMessage(type, payload, sourcePeerId) {
+    // Ignore our own messages
+    if (payload.peerId === this.localPeerId ||
+        payload.requesterId === this.localPeerId ||
+        payload.responderId === this.localPeerId) {
+      return null;
+    }
+
+    switch (type) {
+      case MESSAGE_TYPE.PEER_ANNOUNCE:
+        return this._handleAnnounce(payload, sourcePeerId);
+
+      case MESSAGE_TYPE.PEER_REQUEST:
+        return this._handleRequest(payload, sourcePeerId);
+
+      case MESSAGE_TYPE.PEER_RESPONSE:
+        return this._handleResponse(payload, sourcePeerId);
+
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Handles a peer announce message
+   * @param {Object} payload - Announce payload
+   * @param {string} sourcePeerId - Source peer ID
+   * @returns {null} No response needed
+   * @private
+   */
+  _handleAnnounce(payload, sourcePeerId) {
+    this._stats.announcesReceived++;
+
+    const peerInfo = {
+      id: payload.peerId,
+      name: payload.name || '',
+      publicKey: payload.publicKey ? new Uint8Array(payload.publicKey) : null,
+      capabilities: payload.capabilities || {},
+      hopCount: payload.hopCount || 0,
+      discoveredVia: sourcePeerId
+    };
+
+    this.emit(EVENTS.PEER_DISCOVERED, peerInfo);
+    return null;
+  }
+
+  /**
+   * Handles a peer request message
+   * @param {Object} payload - Request payload
+   * @param {string} sourcePeerId - Source peer ID
+   * @returns {Object|null} Response payload or null
+   * @private
+   */
+  _handleRequest(payload, _sourcePeerId) {
+    this._stats.requestsReceived++;
+
+    // Check if request is for us or broadcast
+    if (payload.targetPeerId && payload.targetPeerId !== this.localPeerId) {
+      return null;
+    }
+
+    this._stats.responsesSent++;
+    return {
+      type: MESSAGE_TYPE.PEER_RESPONSE,
+      payload: this.createResponsePayload(payload.requesterId)
+    };
+  }
+
+  /**
+   * Handles a peer response message
+   * @param {Object} payload - Response payload
+   * @param {string} sourcePeerId - Source peer ID
+   * @returns {null} No response needed
+   * @private
+   */
+  _handleResponse(payload, sourcePeerId) {
+    // Only process responses to our requests
+    if (payload.requesterId !== this.localPeerId) {
+      return null;
+    }
+
+    this._stats.responsesReceived++;
+
+    const peerInfo = {
+      id: payload.responderId,
+      name: payload.name || '',
+      publicKey: payload.publicKey ? new Uint8Array(payload.publicKey) : null,
+      capabilities: payload.capabilities || {},
+      discoveredVia: sourcePeerId
+    };
+
+    this.emit(EVENTS.PEER_DISCOVERED, peerInfo);
+    return null;
+  }
+
+  /**
+   * Updates local peer information
+   * @param {Object} info - New info
+   */
+  updateLocalInfo(info) {
+    if (info.displayName !== undefined) { this.displayName = info.displayName; }
+    if (info.publicKey !== undefined) { this.publicKey = info.publicKey; }
+    if (info.capabilities !== undefined) {
+      Object.assign(this.capabilities, info.capabilities);
+    }
+  }
+
+  /**
+   * Gets discovery statistics
+   * @returns {Object} Statistics
+   */
+  getStats() {
+    return { ...this._stats };
+  }
+
+  /**
+   * Resets statistics
+   */
+  resetStats() {
+    this._stats = {
+      announcesSent: 0,
+      announcesReceived: 0,
+      requestsSent: 0,
+      requestsReceived: 0,
+      responsesSent: 0,
+      responsesReceived: 0
+    };
+  }
+
+  /**
+   * Records an announce sent
+   */
+  recordAnnounceSent() {
+    this._stats.announcesSent++;
+  }
+
+  /**
+   * Records a request sent
+   */
+  recordRequestSent() {
+    this._stats.requestsSent++;
+  }
+}
+
+module.exports = PeerDiscovery;