react-native-ble-mesh 1.1.1 → 2.0.0

package/src/service/file/FileManager.js

@@ -0,0 +1,307 @@
+'use strict';
+
+/**
+ * @fileoverview File transfer manager for mesh network
+ * @module service/file/FileManager
+ */
+
+const EventEmitter = require('../../utils/EventEmitter');
+const FileChunker = require('./FileChunker');
+const FileAssembler = require('./FileAssembler');
+const { FileMessage, FILE_TRANSFER_STATE } = require('./FileMessage');
+
+/**
+ * Default file transfer configuration
+ * @constant {Object}
+ */
+const DEFAULT_CONFIG = Object.freeze({
+  chunkSize: 4096,
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+  transferTimeoutMs: 5 * 60 * 1000, // 5 minutes
+  maxConcurrentTransfers: 5
+});
+
+/**
+ * Manages file transfers over the mesh network.
+ * Handles chunking, reassembly, progress tracking, and timeouts.
+ *
+ * @class FileManager
+ * @extends EventEmitter
+ *
+ * @fires FileManager#sendProgress - When send progress updates
+ * @fires FileManager#receiveProgress - When receive progress updates
+ * @fires FileManager#fileReceived - When a complete file is received
+ * @fires FileManager#transferFailed - When a transfer fails
+ * @fires FileManager#transferCancelled - When a transfer is cancelled
+ */
+class FileManager extends EventEmitter {
+  /**
+   * @param {Object} [config={}]
+   */
+  constructor(config = {}) {
+    super();
+    this._config = { ...DEFAULT_CONFIG, ...config };
+    this._chunker = new FileChunker({
+      chunkSize: this._config.chunkSize,
+      maxFileSize: this._config.maxFileSize
+    });
+
+    /** @type {Map<string, Object>} Active outgoing transfers */
+    this._outgoing = new Map();
+    /** @type {Map<string, Object>} Active incoming transfers */
+    this._incoming = new Map();
+    /** @type {Map<string, NodeJS.Timeout>} Transfer timeouts */
+    this._timeouts = new Map();
+  }
+
+  /**
+   * Prepares a file for sending. Returns the transfer object with chunks.
+   * The caller (MeshNetwork) is responsible for actually sending chunks via transport.
+   *
+   * @param {string} peerId - Target peer ID
+   * @param {Object} fileInfo - File information
+   * @param {Uint8Array} fileInfo.data - File data
+   * @param {string} fileInfo.name - File name
+   * @param {string} [fileInfo.mimeType='application/octet-stream'] - MIME type
+   * @returns {Object} Transfer object with id, offer, and chunks
+   */
+  prepareSend(peerId, fileInfo) {
+    if (this._outgoing.size >= this._config.maxConcurrentTransfers) {
+      throw new Error('Max concurrent transfers reached');
+    }
+
+    const transferId = `ft-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const chunks = this._chunker.chunk(fileInfo.data, transferId);
+
+    const fileMeta = new FileMessage({
+      id: transferId,
+      name: fileInfo.name,
+      mimeType: fileInfo.mimeType || 'application/octet-stream',
+      size: fileInfo.data.length,
+      totalChunks: chunks.length,
+      chunkSize: this._chunker.chunkSize
+    });
+
+    const transfer = {
+      id: transferId,
+      peerId,
+      meta: fileMeta,
+      chunks,
+      sentChunks: 0,
+      state: FILE_TRANSFER_STATE.PENDING
+    };
+
+    this._outgoing.set(transferId, transfer);
+    this._setTransferTimeout(transferId);
+
+    return {
+      id: transferId,
+      offer: fileMeta.toOffer(),
+      chunks,
+      totalChunks: chunks.length
+    };
+  }
+
+  /**
+   * Marks a chunk as sent and emits progress
+   * @param {string} transferId - Transfer ID
+   * @param {number} chunkIndex - Chunk index that was sent
+   */
+  markChunkSent(transferId, _chunkIndex) {
+    const transfer = this._outgoing.get(transferId);
+    if (!transfer) { return; }
+
+    transfer.sentChunks++;
+    if (!transfer.meta.startedAt) {
+      transfer.meta.startedAt = Date.now();
+    }
+    transfer.state = FILE_TRANSFER_STATE.TRANSFERRING;
+
+    const progress = Math.round((transfer.sentChunks / transfer.chunks.length) * 100);
+    this.emit('sendProgress', {
+      transferId,
+      peerId: transfer.peerId,
+      name: transfer.meta.name,
+      percent: progress
+    });
+
+    if (transfer.sentChunks >= transfer.chunks.length) {
+      transfer.state = FILE_TRANSFER_STATE.COMPLETE;
+      transfer.meta.completedAt = Date.now();
+      this._clearTransferTimeout(transferId);
+      this._outgoing.delete(transferId);
+      this.emit('sendComplete', {
+        transferId,
+        peerId: transfer.peerId,
+        name: transfer.meta.name,
+        elapsedMs: transfer.meta.elapsedMs
+      });
+    }
+  }
+
+  /**
+   * Handles an incoming file offer
+   * @param {Object} offer - File offer metadata
+   * @param {string} senderId - Sender peer ID
+   * @returns {string} Transfer ID
+   */
+  handleOffer(offer, senderId) {
+    if (this._incoming.size >= this._config.maxConcurrentTransfers) {
+      throw new Error('Max concurrent incoming transfers reached');
+    }
+
+    // Validate offer fields
+    if (!offer || !offer.id || !offer.name) {
+      throw new Error('Invalid file offer: missing id or name');
+    }
+    if (typeof offer.totalChunks !== 'number' || offer.totalChunks <= 0) {
+      throw new Error('Invalid file offer: invalid totalChunks');
+    }
+    if (typeof offer.size !== 'number' || offer.size <= 0) {
+      throw new Error('Invalid file offer: invalid size');
+    }
+    if (offer.size > this._config.maxFileSize) {
+      throw new Error(`File too large: ${offer.size} bytes exceeds ${this._config.maxFileSize} byte limit`);
+    }
+
+    const fileMeta = FileMessage.fromOffer(offer, senderId);
+    const assembler = new FileAssembler(offer.id, offer.totalChunks, offer.size);
+
+    this._incoming.set(offer.id, {
+      meta: fileMeta,
+      assembler,
+      senderId
+    });
+
+    this._setTransferTimeout(offer.id);
+    return offer.id;
+  }
+
+  /**
+   * Handles an incoming file chunk
+   * @param {string} transferId - Transfer ID
+   * @param {number} index - Chunk index
+   * @param {Uint8Array} data - Chunk data
+   */
+  handleChunk(transferId, index, data) {
+    const transfer = this._incoming.get(transferId);
+    if (!transfer) { return; }
+
+    if (!transfer.meta.startedAt) {
+      transfer.meta.startedAt = Date.now();
+    }
+    transfer.meta.state = FILE_TRANSFER_STATE.TRANSFERRING;
+
+    const isNew = transfer.assembler.addChunk(index, data);
+    if (!isNew) { return; }
+
+    transfer.meta.receivedChunks = transfer.assembler.receivedChunks;
+
+    this.emit('receiveProgress', {
+      transferId,
+      from: transfer.senderId,
+      name: transfer.meta.name,
+      percent: transfer.assembler.progress
+    });
+
+    if (transfer.assembler.isComplete()) {
+      const fileData = transfer.assembler.assemble();
+      transfer.meta.state = FILE_TRANSFER_STATE.COMPLETE;
+      transfer.meta.completedAt = Date.now();
+      this._clearTransferTimeout(transferId);
+      this._incoming.delete(transferId);
+
+      this.emit('fileReceived', {
+        transferId,
+        from: transfer.senderId,
+        file: {
+          name: transfer.meta.name,
+          mimeType: transfer.meta.mimeType,
+          size: transfer.meta.size,
+          data: fileData
+        },
+        elapsedMs: transfer.meta.elapsedMs
+      });
+    }
+  }
+
+  /**
+   * Cancels a transfer (incoming or outgoing)
+   * @param {string} transferId - Transfer ID
+   */
+  cancelTransfer(transferId) {
+    this._clearTransferTimeout(transferId);
+
+    if (this._outgoing.has(transferId)) {
+      const transfer = this._outgoing.get(transferId);
+      transfer.state = FILE_TRANSFER_STATE.CANCELLED;
+      this._outgoing.delete(transferId);
+      this.emit('transferCancelled', { transferId, direction: 'outgoing' });
+    }
+
+    if (this._incoming.has(transferId)) {
+      const transfer = this._incoming.get(transferId);
+      transfer.meta.state = FILE_TRANSFER_STATE.CANCELLED;
+      transfer.assembler.clear();
+      this._incoming.delete(transferId);
+      this.emit('transferCancelled', { transferId, direction: 'incoming' });
+    }
+  }
+
+  /**
+   * Gets active transfers
+   * @returns {Object} { outgoing: [], incoming: [] }
+   */
+  getActiveTransfers() {
+    return {
+      outgoing: Array.from(this._outgoing.values()).map(t => ({
+        id: t.id, peerId: t.peerId, name: t.meta.name,
+        progress: Math.round((t.sentChunks / t.chunks.length) * 100),
+        state: t.state
+      })),
+      incoming: Array.from(this._incoming.values()).map(t => ({
+        id: t.meta.id, from: t.senderId, name: t.meta.name,
+        progress: t.assembler.progress,
+        state: t.meta.state
+      }))
+    };
+  }
+
+  /**
+   * Destroys and cleans up
+   */
+  destroy() {
+    for (const id of this._timeouts.keys()) {
+      this._clearTransferTimeout(id);
+    }
+    this._outgoing.clear();
+    for (const t of this._incoming.values()) {
+      t.assembler.clear();
+    }
+    this._incoming.clear();
+    this.removeAllListeners();
+  }
+
+  /** @private */
+  _setTransferTimeout(transferId) {
+    const timer = setTimeout(() => {
+      this.cancelTransfer(transferId);
+      this.emit('transferFailed', {
+        transferId,
+        reason: 'timeout'
+      });
+    }, this._config.transferTimeoutMs);
+    this._timeouts.set(transferId, timer);
+  }
+
+  /** @private */
+  _clearTransferTimeout(transferId) {
+    const timer = this._timeouts.get(transferId);
+    if (timer) {
+      clearTimeout(timer);
+      this._timeouts.delete(transferId);
+    }
+  }
+}
+
+module.exports = FileManager;

package/src/service/file/FileMessage.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * @fileoverview File message metadata
+ * @module service/file/FileMessage
+ */
+
+/**
+ * File transfer message types
+ * @constant {Object}
+ */
+const FILE_MESSAGE_TYPE = Object.freeze({
+  /** Initial file offer with metadata */
+  OFFER: 'file:offer',
+  /** File chunk data */
+  CHUNK: 'file:chunk',
+  /** Transfer complete acknowledgment */
+  COMPLETE: 'file:complete',
+  /** Transfer cancelled */
+  CANCEL: 'file:cancel'
+});
+
+/**
+ * File transfer states
+ * @constant {Object}
+ */
+const FILE_TRANSFER_STATE = Object.freeze({
+  PENDING: 'pending',
+  TRANSFERRING: 'transferring',
+  COMPLETE: 'complete',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled'
+});
+
+/**
+ * Represents a file being transferred over the mesh.
+ * @class FileMessage
+ */
+class FileMessage {
+  /**
+   * @param {Object} options
+   * @param {string} options.id - Transfer ID
+   * @param {string} options.name - File name
+   * @param {string} options.mimeType - MIME type
+   * @param {number} options.size - Total size in bytes
+   * @param {number} options.totalChunks - Total number of chunks
+   * @param {number} [options.chunkSize=4096] - Chunk size in bytes
+   * @param {string} [options.senderId] - Sender peer ID
+   */
+  constructor(options) {
+    this.id = options.id;
+    this.name = options.name;
+    this.mimeType = options.mimeType || 'application/octet-stream';
+    this.size = options.size;
+    this.totalChunks = options.totalChunks;
+    this.chunkSize = options.chunkSize || 4096;
+    this.senderId = options.senderId || null;
+    this.receivedChunks = 0;
+    this.state = FILE_TRANSFER_STATE.PENDING;
+    this.startedAt = null;
+    this.completedAt = null;
+  }
+
+  /**
+   * Gets transfer progress as percentage
+   * @returns {number} 0-100
+   */
+  get progress() {
+    if (this.totalChunks === 0) { return 100; }
+    return Math.round((this.receivedChunks / this.totalChunks) * 100);
+  }
+
+  /**
+   * Gets elapsed transfer time in ms
+   * @returns {number}
+   */
+  get elapsedMs() {
+    if (!this.startedAt) { return 0; }
+    const end = this.completedAt || Date.now();
+    return end - this.startedAt;
+  }
+
+  /**
+   * Serializes the file offer metadata
+   * @returns {Object}
+   */
+  toOffer() {
+    return {
+      type: FILE_MESSAGE_TYPE.OFFER,
+      id: this.id,
+      name: this.name,
+      mimeType: this.mimeType,
+      size: this.size,
+      totalChunks: this.totalChunks,
+      chunkSize: this.chunkSize
+    };
+  }
+
+  /**
+   * Creates a FileMessage from an offer
+   * @param {Object} offer
+   * @param {string} senderId
+   * @returns {FileMessage}
+   */
+  static fromOffer(offer, senderId) {
+    return new FileMessage({
+      id: offer.id,
+      name: offer.name,
+      mimeType: offer.mimeType,
+      size: offer.size,
+      totalChunks: offer.totalChunks,
+      chunkSize: offer.chunkSize,
+      senderId
+    });
+  }
+}
+
+module.exports = {
+  FileMessage,
+  FILE_MESSAGE_TYPE,
+  FILE_TRANSFER_STATE
+};

package/src/service/file/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const FileManager = require('./FileManager');
+const FileChunker = require('./FileChunker');
+const FileAssembler = require('./FileAssembler');
+const { FileMessage, FILE_MESSAGE_TYPE, FILE_TRANSFER_STATE } = require('./FileMessage');
+
+module.exports = {
+  FileManager,
+  FileChunker,
+  FileAssembler,
+  FileMessage,
+  FILE_MESSAGE_TYPE,
+  FILE_TRANSFER_STATE
+};

package/src/service/text/broadcast/BroadcastManager.js

@@ -45,6 +45,17 @@ class BroadcastManager extends EventEmitter {
     this._senderId = null;
     /** @private */
     this._sendCallback = null;
+    /** @private */
+    this._cleanupTimer = null;
+
+    // Auto-cleanup every 5 minutes
+    this._cleanupTimer = setInterval(() => {
+      this.cleanup();
+    }, 5 * 60 * 1000);
+
+    if (this._cleanupTimer && typeof this._cleanupTimer.unref === 'function') {
+      this._cleanupTimer.unref();
+    }
   }
 
   /**
@@ -160,6 +171,11 @@ class BroadcastManager extends EventEmitter {
   clear() {
     this._recentBroadcasts = [];
     this._seenMessageIds.clear();
+
+    if (this._cleanupTimer) {
+      clearInterval(this._cleanupTimer);
+      this._cleanupTimer = null;
+    }
   }
 
   /**

package/src/transport/BLETransport.js

@@ -30,6 +30,7 @@ class BLETransport extends Transport {
    * @param {string} [options.powerMode='BALANCED'] - Power mode
    * @param {number} [options.maxPeers=8] - Maximum peers
    * @param {number} [options.connectTimeoutMs=10000] - Connection timeout
+   * @param {number} [options.mtu=23] - Default BLE MTU
    */
   constructor(adapter, options = {}) {
     super(options);
@@ -59,6 +60,13 @@ class BLETransport extends Transport {
      */
     this._connectTimeoutMs = options.connectTimeoutMs || 10000;
 
+    /**
+     * BLE MTU (Maximum Transmission Unit)
+     * @type {number}
+     * @private
+     */
+    this._mtu = options.mtu || 23; // Default BLE MTU
+
     /**
      * Whether scanning is active
      * @type {boolean}
@@ -66,6 +74,20 @@ class BLETransport extends Transport {
      */
     this._isScanning = false;
 
+    /**
+     * Per-peer write queues for serializing BLE writes
+     * @type {Map<string, Array>}
+     * @private
+     */
+    this._writeQueue = new Map();
+
+    /**
+     * Per-peer write locks
+     * @type {Map<string, boolean>}
+     * @private
+     */
+    this._writing = new Map();
+
     /**
      * Bound event handlers for cleanup
      * @type {Object}
@@ -86,6 +108,14 @@ class BLETransport extends Transport {
     return this._isScanning;
   }
 
+  /**
+   * Gets the current BLE MTU
+   * @returns {number} Current MTU in bytes
+   */
+  get mtu() {
+    return this._mtu;
+  }
+
   /**
    * Starts the BLE transport
    * @returns {Promise<void>}
@@ -107,7 +137,18 @@ class BLETransport extends Transport {
       }
 
       this._adapter.onStateChange(this._handlers.onStateChange);
+
+      // Register disconnect callback if adapter supports it
+      if (typeof this._adapter.onDeviceDisconnected === 'function') {
+        this._adapter.onDeviceDisconnected((peerId) => {
+          this._handleDeviceDisconnected(peerId);
+        });
+      }
+
       this._setState(Transport.STATE.RUNNING);
+
+      // Auto-start scanning for peers
+      await this.startScanning();
     } catch (error) {
       this._setState(Transport.STATE.ERROR);
       throw error;
@@ -191,11 +232,28 @@ class BLETransport extends Transport {
     }
 
     try {
+      let timeoutId;
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error('Connection timeout')), this._connectTimeoutMs);
+      });
       const device = await Promise.race([
-        this._adapter.connect(peerId),
-        this._createTimeout(this._connectTimeoutMs, 'Connection timeout')
+        this._adapter.connect(peerId).then(d => { clearTimeout(timeoutId); return d; }),
+        timeoutPromise
       ]);
 
+      // Negotiate MTU for larger payloads
+      let negotiatedMtu = this._mtu;
+      try {
+        if (typeof this._adapter.requestMTU === 'function') {
+          const mtu = await this._adapter.requestMTU(peerId, 512);
+          if (mtu) {
+            negotiatedMtu = mtu;
+          }
+        }
+      } catch (mtuError) {
+        // MTU negotiation failure is non-fatal, continue with default MTU
+      }
+
       // Subscribe to notifications
       await this._adapter.subscribe(
         peerId,
@@ -207,7 +265,8 @@ class BLETransport extends Transport {
       const connectionInfo = {
         peerId,
         device,
-        connectedAt: Date.now()
+        connectedAt: Date.now(),
+        mtu: negotiatedMtu
       };
 
       this._peers.set(peerId, connectionInfo);
@@ -254,12 +313,21 @@ class BLETransport extends Transport {
       throw ConnectionError.fromCode('E207', peerId);
     }
 
-    await this._adapter.write(
-      peerId,
-      BLE_SERVICE_UUID,
-      BLE_CHARACTERISTIC_TX,
-      data
-    );
+    const peerInfo = this._peers.get(peerId);
+    const mtu = peerInfo.mtu || this._mtu || 23;
+    const chunkSize = Math.max(mtu - 3, 20); // ATT header overhead, minimum 20
+
+    if (data.length <= chunkSize) {
+      // Single write
+      await this._queuedWrite(peerId, data);
+      return;
+    }
+
+    // Chunk data for BLE MTU compliance
+    for (let offset = 0; offset < data.length; offset += chunkSize) {
+      const chunk = data.slice(offset, Math.min(offset + chunkSize, data.length));
+      await this._queuedWrite(peerId, chunk);
+    }
   }
 
   /**
@@ -326,6 +394,15 @@ class BLETransport extends Transport {
   _handleDeviceDisconnected(peerId) {
     if (this._peers.has(peerId)) {
       this._peers.delete(peerId);
+
+      // Clean up write queue
+      const queue = this._writeQueue.get(peerId);
+      if (queue) {
+        queue.forEach(({ reject }) => reject(new Error('Peer disconnected')));
+        this._writeQueue.delete(peerId);
+      }
+      this._writing.delete(peerId);
+
       this.emit('peerDisconnected', { peerId, reason: 'connection_lost' });
     }
   }
@@ -352,6 +429,51 @@ class BLETransport extends Transport {
       setTimeout(() => reject(new Error(message)), ms);
     });
   }
+
+  /**
+   * Queues a write operation to serialize BLE writes
+   * @param {string} peerId - Target peer ID
+   * @param {Uint8Array} data - Data to write
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _queuedWrite(peerId, data) {
+    if (!this._writeQueue.has(peerId)) {
+      this._writeQueue.set(peerId, []);
+    }
+
+    return new Promise((resolve, reject) => {
+      this._writeQueue.get(peerId).push({ data, resolve, reject });
+      this._processWriteQueue(peerId);
+    });
+  }
+
+  /**
+   * Processes the write queue for a peer
+   * @param {string} peerId - Target peer ID
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _processWriteQueue(peerId) {
+    if (this._writing.get(peerId)) { return; } // Already processing
+
+    const queue = this._writeQueue.get(peerId);
+    if (!queue || queue.length === 0) { return; }
+
+    this._writing.set(peerId, true);
+
+    while (queue.length > 0) {
+      const { data, resolve, reject } = queue.shift();
+      try {
+        await this._adapter.write(peerId, BLE_SERVICE_UUID, BLE_CHARACTERISTIC_TX, data);
+        resolve();
+      } catch (err) {
+        reject(err);
+      }
+    }
+
+    this._writing.set(peerId, false);
+  }
 }
 
 module.exports = BLETransport;

package/src/transport/MockTransport.js

@@ -50,7 +50,7 @@ class MockTransport extends Transport {
      * @type {string|null}
      * @private
      */
-    this._localPeerId = options.localPeerId || null;
+    this._localPeerId = options.localPeerId || `mock-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   }
 
   /**