react-native-ble-mesh 1.0.1

package/src/mesh/fragment/Assembler.js

@@ -0,0 +1,281 @@
+'use strict';
+
+/**
+ * @fileoverview Fragment assembler for reconstructing fragmented messages
+ * @module mesh/fragment/Assembler
+ */
+
+const { MESH_CONFIG } = require('../../constants');
+const { MessageError, ValidationError } = require('../../errors');
+const { getFragmentInfo, isValidFragment } = require('./Fragmenter');
+
+/**
+ * Default assembly timeout
+ * @constant
+ * @private
+ */
+const DEFAULT_TIMEOUT = MESH_CONFIG.FRAGMENT_TIMEOUT_MS;
+
+/**
+ * Pending fragment set
+ * @class PendingFragmentSet
+ * @private
+ */
+class PendingFragmentSet {
+  /**
+   * Creates a new PendingFragmentSet
+   * @param {string} messageId - Message ID
+   * @param {number} total - Total expected fragments
+   * @param {number} timeout - Timeout in milliseconds
+   */
+  constructor(messageId, total, timeout) {
+    this.messageId = messageId;
+    this.total = total;
+    this.received = new Map();
+    this.createdAt = Date.now();
+    this.expiresAt = this.createdAt + timeout;
+    this.totalPayloadLength = 0;
+  }
+
+  /**
+   * Checks if the fragment set is complete
+   * @returns {boolean} True if all fragments received
+   */
+  isComplete() {
+    return this.received.size === this.total;
+  }
+
+  /**
+   * Checks if the fragment set has expired
+   * @returns {boolean} True if expired
+   */
+  isExpired() {
+    return Date.now() > this.expiresAt;
+  }
+
+  /**
+   * Adds a fragment to the set
+   * @param {number} index - Fragment index
+   * @param {Uint8Array} payload - Fragment payload
+   * @returns {boolean} True if fragment was new
+   */
+  addFragment(index, payload) {
+    if (this.received.has(index)) {
+      return false;
+    }
+    this.received.set(index, payload);
+    this.totalPayloadLength += payload.length;
+    return true;
+  }
+
+  /**
+   * Assembles all fragments into complete payload
+   * @returns {Uint8Array} Complete assembled payload
+   */
+  assemble() {
+    const result = new Uint8Array(this.totalPayloadLength);
+    let offset = 0;
+
+    for (let i = 0; i < this.total; i++) {
+      const payload = this.received.get(i);
+      if (!payload) {
+        throw MessageError.fromCode('E508', this.messageId, {
+          reason: `Missing fragment ${i}`
+        });
+      }
+      result.set(payload, offset);
+      offset += payload.length;
+    }
+
+    return result;
+  }
+
+  /**
+   * Gets progress information
+   * @returns {Object} Progress { received, total, percent }
+   */
+  getProgress() {
+    return {
+      received: this.received.size,
+      total: this.total,
+      percent: Math.round((this.received.size / this.total) * 100)
+    };
+  }
+}
+
+/**
+ * Fragment assembler for reconstructing fragmented messages
+ * @class Assembler
+ */
+class Assembler {
+  /**
+   * Creates a new Assembler
+   * @param {number} [timeout] - Timeout for incomplete fragment sets
+   */
+  constructor(timeout = DEFAULT_TIMEOUT) {
+    if (!Number.isInteger(timeout) || timeout <= 0) {
+      throw ValidationError.outOfRange('timeout', timeout, { min: 1 });
+    }
+
+    /**
+     * Timeout for incomplete fragment sets
+     * @type {number}
+     */
+    this.timeout = timeout;
+
+    /**
+     * Pending fragment sets by message ID
+     * @type {Map<string, PendingFragmentSet>}
+     * @private
+     */
+    this._pending = new Map();
+
+    /**
+     * Statistics
+     * @type {Object}
+     * @private
+     */
+    this._stats = {
+      fragmentsReceived: 0,
+      messagesAssembled: 0,
+      duplicateFragments: 0,
+      expiredSets: 0
+    };
+  }
+
+  /**
+   * Adds a fragment and returns assembled payload if complete
+   * @param {string} messageId - Message ID
+   * @param {Uint8Array} fragmentData - Fragment data with header
+   * @returns {Uint8Array|null} Assembled payload or null if incomplete
+   */
+  addFragment(messageId, fragmentData) {
+    if (typeof messageId !== 'string' || messageId.length === 0) {
+      throw ValidationError.invalidArgument('messageId', messageId);
+    }
+    if (!isValidFragment(fragmentData)) {
+      throw MessageError.invalidFormat(messageId, {
+        reason: 'Invalid fragment data'
+      });
+    }
+
+    const info = getFragmentInfo(fragmentData);
+    this._stats.fragmentsReceived++;
+
+    // Get or create pending set
+    let pendingSet = this._pending.get(messageId);
+    if (!pendingSet) {
+      pendingSet = new PendingFragmentSet(messageId, info.total, this.timeout);
+      this._pending.set(messageId, pendingSet);
+    }
+
+    // Validate fragment belongs to this set
+    if (info.total !== pendingSet.total) {
+      throw MessageError.invalidFormat(messageId, {
+        reason: 'Fragment total mismatch'
+      });
+    }
+
+    // Add fragment
+    const isNew = pendingSet.addFragment(info.index, info.payload);
+    if (!isNew) {
+      this._stats.duplicateFragments++;
+    }
+
+    // Check if complete
+    if (pendingSet.isComplete()) {
+      const payload = pendingSet.assemble();
+      this._pending.delete(messageId);
+      this._stats.messagesAssembled++;
+      return payload;
+    }
+
+    return null;
+  }
+
+  /**
+   * Cleans up expired pending fragment sets
+   * @returns {string[]} Array of expired message IDs
+   */
+  cleanup() {
+    const expired = [];
+
+    for (const [messageId, pendingSet] of this._pending) {
+      if (pendingSet.isExpired()) {
+        expired.push(messageId);
+        this._pending.delete(messageId);
+        this._stats.expiredSets++;
+      }
+    }
+
+    return expired;
+  }
+
+  /**
+   * Gets the number of pending fragment sets
+   * @returns {number} Count of pending sets
+   */
+  getPendingCount() {
+    return this._pending.size;
+  }
+
+  /**
+   * Checks if there are pending fragments for a message
+   * @param {string} messageId - Message ID to check
+   * @returns {boolean} True if there are pending fragments
+   */
+  hasPending(messageId) {
+    return this._pending.has(messageId);
+  }
+
+  /**
+   * Gets progress for a pending message
+   * @param {string} messageId - Message ID
+   * @returns {Object|null} Progress or null if not found
+   */
+  getProgress(messageId) {
+    const pendingSet = this._pending.get(messageId);
+    return pendingSet ? pendingSet.getProgress() : null;
+  }
+
+  /**
+   * Removes a pending fragment set
+   * @param {string} messageId - Message ID to remove
+   * @returns {boolean} True if removed
+   */
+  removePending(messageId) {
+    return this._pending.delete(messageId);
+  }
+
+  /**
+   * Gets assembler statistics
+   * @returns {Object} Statistics
+   */
+  getStats() {
+    return {
+      ...this._stats,
+      pendingCount: this._pending.size
+    };
+  }
+
+  /**
+   * Resets statistics
+   */
+  resetStats() {
+    this._stats = {
+      fragmentsReceived: 0,
+      messagesAssembled: 0,
+      duplicateFragments: 0,
+      expiredSets: 0
+    };
+  }
+
+  /**
+   * Clears all pending fragment sets
+   */
+  clear() {
+    this._pending.clear();
+  }
+}
+
+module.exports = Assembler;

package/src/mesh/fragment/Fragmenter.js

@@ -0,0 +1,176 @@
+'use strict';
+
+/**
+ * @fileoverview Message fragmenter for splitting large payloads
+ * @module mesh/fragment/Fragmenter
+ */
+
+const { MESH_CONFIG } = require('../../constants');
+const { ValidationError } = require('../../errors');
+
+/**
+ * Default fragment size
+ * @constant
+ * @private
+ */
+const DEFAULT_FRAGMENT_SIZE = MESH_CONFIG.FRAGMENT_SIZE;
+
+/**
+ * Fragment header overhead (4 bytes: index, total, length high, length low)
+ * @constant
+ * @private
+ */
+const FRAGMENT_HEADER_SIZE = 4;
+
+/**
+ * Checks if a payload needs fragmentation
+ * @param {Uint8Array} payload - Payload to check
+ * @param {number} [maxSize] - Maximum fragment payload size
+ * @returns {boolean} True if fragmentation is needed
+ */
+function needsFragmentation(payload, maxSize = DEFAULT_FRAGMENT_SIZE) {
+  if (!(payload instanceof Uint8Array)) {
+    throw ValidationError.invalidType('payload', payload, 'Uint8Array');
+  }
+  return payload.length > maxSize;
+}
+
+/**
+ * Calculates the number of fragments needed
+ * @param {number} payloadLength - Total payload length
+ * @param {number} maxSize - Maximum fragment payload size
+ * @returns {number} Number of fragments required
+ * @private
+ */
+function calculateFragmentCount(payloadLength, maxSize) {
+  return Math.ceil(payloadLength / maxSize);
+}
+
+/**
+ * Creates a fragment header
+ * @param {number} index - Fragment index (0-based)
+ * @param {number} total - Total number of fragments
+ * @param {number} payloadLength - Length of this fragment's payload
+ * @returns {Uint8Array} 4-byte fragment header
+ * @private
+ */
+function createFragmentHeader(index, total, payloadLength) {
+  const header = new Uint8Array(FRAGMENT_HEADER_SIZE);
+  header[0] = index;
+  header[1] = total;
+  header[2] = (payloadLength >> 8) & 0xff;
+  header[3] = payloadLength & 0xff;
+  return header;
+}
+
+/**
+ * Parses a fragment header
+ * @param {Uint8Array} data - Fragment data
+ * @returns {Object} Parsed header { index, total, payloadLength }
+ */
+function parseFragmentHeader(data) {
+  if (data.length < FRAGMENT_HEADER_SIZE) {
+    throw ValidationError.invalidArgument('data', null, {
+      reason: 'Fragment data too short for header'
+    });
+  }
+  return {
+    index: data[0],
+    total: data[1],
+    payloadLength: (data[2] << 8) | data[3]
+  };
+}
+
+/**
+ * Fragments a payload into multiple chunks
+ * @param {Uint8Array} payload - Payload to fragment
+ * @param {string} messageId - Message ID for the fragments
+ * @param {number} [maxSize] - Maximum fragment payload size
+ * @returns {Uint8Array[]} Array of fragment data chunks
+ */
+function fragment(payload, messageId, maxSize = DEFAULT_FRAGMENT_SIZE) {
+  if (!(payload instanceof Uint8Array)) {
+    throw ValidationError.invalidType('payload', payload, 'Uint8Array');
+  }
+  if (typeof messageId !== 'string' || messageId.length === 0) {
+    throw ValidationError.invalidArgument('messageId', messageId, {
+      reason: 'Message ID must be a non-empty string'
+    });
+  }
+  if (!Number.isInteger(maxSize) || maxSize <= FRAGMENT_HEADER_SIZE) {
+    throw ValidationError.outOfRange('maxSize', maxSize, {
+      min: FRAGMENT_HEADER_SIZE + 1
+    });
+  }
+
+  // Calculate actual payload capacity per fragment
+  const payloadCapacity = maxSize - FRAGMENT_HEADER_SIZE;
+  const fragmentCount = calculateFragmentCount(payload.length, payloadCapacity);
+
+  // Validate fragment count limit (single byte index)
+  if (fragmentCount > 255) {
+    throw ValidationError.outOfRange('payload.length', payload.length, {
+      max: payloadCapacity * 255,
+      reason: 'Payload too large, would exceed maximum fragment count'
+    });
+  }
+
+  const fragments = [];
+  let offset = 0;
+
+  for (let i = 0; i < fragmentCount; i++) {
+    const remainingLength = payload.length - offset;
+    const chunkLength = Math.min(payloadCapacity, remainingLength);
+    const chunk = payload.slice(offset, offset + chunkLength);
+
+    // Create fragment with header
+    const header = createFragmentHeader(i, fragmentCount, chunkLength);
+    const fragmentData = new Uint8Array(FRAGMENT_HEADER_SIZE + chunkLength);
+    fragmentData.set(header, 0);
+    fragmentData.set(chunk, FRAGMENT_HEADER_SIZE);
+
+    fragments.push(fragmentData);
+    offset += chunkLength;
+  }
+
+  return fragments;
+}
+
+/**
+ * Gets fragment information without parsing full data
+ * @param {Uint8Array} fragmentData - Fragment data
+ * @returns {Object} Fragment info { index, total, payloadLength, payload }
+ */
+function getFragmentInfo(fragmentData) {
+  const header = parseFragmentHeader(fragmentData);
+  return {
+    ...header,
+    payload: fragmentData.slice(FRAGMENT_HEADER_SIZE, FRAGMENT_HEADER_SIZE + header.payloadLength)
+  };
+}
+
+/**
+ * Validates fragment data structure
+ * @param {Uint8Array} fragmentData - Fragment data to validate
+ * @returns {boolean} True if valid
+ */
+function isValidFragment(fragmentData) {
+  if (!(fragmentData instanceof Uint8Array)) { return false; }
+  if (fragmentData.length < FRAGMENT_HEADER_SIZE) { return false; }
+
+  const header = parseFragmentHeader(fragmentData);
+  if (header.index >= header.total) { return false; }
+  if (header.total === 0) { return false; }
+  if (fragmentData.length < FRAGMENT_HEADER_SIZE + header.payloadLength) { return false; }
+
+  return true;
+}
+
+module.exports = {
+  fragment,
+  needsFragmentation,
+  parseFragmentHeader,
+  getFragmentInfo,
+  isValidFragment,
+  FRAGMENT_HEADER_SIZE
+};

package/src/mesh/fragment/index.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * @fileoverview Fragment module exports
+ * @module mesh/fragment
+ */
+
+const Fragmenter = require('./Fragmenter');
+const Assembler = require('./Assembler');
+
+module.exports = {
+  // Fragmenter exports
+  fragment: Fragmenter.fragment,
+  needsFragmentation: Fragmenter.needsFragmentation,
+  parseFragmentHeader: Fragmenter.parseFragmentHeader,
+  getFragmentInfo: Fragmenter.getFragmentInfo,
+  isValidFragment: Fragmenter.isValidFragment,
+  FRAGMENT_HEADER_SIZE: Fragmenter.FRAGMENT_HEADER_SIZE,
+  // Assembler class
+  Assembler
+};

package/src/mesh/index.js

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Mesh module exports
+ * @module mesh
+ */
+
+'use strict';
+
+const dedup = require('./dedup');
+const fragment = require('./fragment');
+const peer = require('./peer');
+const router = require('./router');
+
+module.exports = {
+  ...dedup,
+  ...fragment,
+  ...peer,
+  ...router
+};