react-native-ble-mesh 1.0.1

package/src/protocol/message.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * @fileoverview Message container class combining header and payload.
+ * @module protocol/message
+ */
+
+const { MessageHeader, HEADER_SIZE, generateUuid } = require('./header');
+const { MESSAGE_FLAGS, MESH_CONFIG } = require('../constants');
+const { MessageError } = require('../errors');
+
+/**
+ * Message class representing a complete mesh network message.
+ * @class Message
+ */
+class Message {
+  /**
+   * Creates a new Message instance.
+   * @param {MessageHeader} header - Message header
+   * @param {Uint8Array} payload - Message payload
+   */
+  constructor(header, payload) {
+    /** @type {MessageHeader} */
+    this.header = header;
+    /** @type {Uint8Array} */
+    this.payload = payload;
+  }
+
+  /**
+   * Creates a new message with the given options.
+   * @param {Object} options - Message options
+   * @param {number} options.type - Message type from MESSAGE_TYPE
+   * @param {Uint8Array|string} options.payload - Message payload
+   * @param {number} [options.flags=0] - Message flags
+   * @param {number} [options.maxHops=7] - Maximum hops
+   * @param {number} [options.ttlMs] - Time-to-live in ms
+   * @param {number} [options.fragmentIndex=0] - Fragment index
+   * @param {number} [options.fragmentTotal=1] - Total fragments
+   * @param {Uint8Array} [options.messageId] - Optional message ID
+   * @returns {Message} New message instance
+   */
+  static create(options) {
+    let payload = options.payload;
+
+    // Convert string payload to bytes
+    if (typeof payload === 'string') {
+      payload = new TextEncoder().encode(payload);
+    }
+
+    if (!(payload instanceof Uint8Array)) {
+      payload = new Uint8Array(0);
+    }
+
+    const now = Date.now();
+    const ttl = options.ttlMs ?? MESH_CONFIG.MESSAGE_TTL_MS;
+
+    const header = new MessageHeader({
+      type: options.type,
+      flags: options.flags ?? MESSAGE_FLAGS.NONE,
+      maxHops: options.maxHops ?? MESH_CONFIG.MAX_HOPS,
+      messageId: options.messageId ?? generateUuid(),
+      timestamp: now,
+      expiresAt: now + ttl,
+      payloadLength: payload.length,
+      fragmentIndex: options.fragmentIndex ?? 0,
+      fragmentTotal: options.fragmentTotal ?? 1
+    });
+
+    return new Message(header, payload);
+  }
+
+  /**
+   * Deserializes a message from bytes.
+   * @param {Uint8Array} data - Raw message bytes
+   * @returns {Message} Parsed message
+   * @throws {MessageError} If data is invalid
+   */
+  static fromBytes(data) {
+    if (!(data instanceof Uint8Array)) {
+      throw MessageError.invalidFormat(null, { reason: 'Data must be Uint8Array' });
+    }
+
+    if (data.length < HEADER_SIZE) {
+      throw MessageError.invalidFormat(null, {
+        reason: 'Message too small',
+        size: data.length,
+        minSize: HEADER_SIZE
+      });
+    }
+
+    const header = MessageHeader.fromBytes(data);
+    const expectedLength = HEADER_SIZE + header.payloadLength;
+
+    if (data.length < expectedLength) {
+      throw MessageError.invalidFormat(header.getMessageIdHex(), {
+        reason: 'Incomplete payload',
+        expected: expectedLength,
+        actual: data.length
+      });
+    }
+
+    const payload = data.slice(HEADER_SIZE, HEADER_SIZE + header.payloadLength);
+
+    return new Message(header, payload);
+  }
+
+  /**
+   * Serializes the message to bytes.
+   * @returns {Uint8Array} Complete message bytes
+   */
+  toBytes() {
+    const headerBytes = this.header.toBytes();
+    const result = new Uint8Array(headerBytes.length + this.payload.length);
+    result.set(headerBytes, 0);
+    result.set(this.payload, headerBytes.length);
+    return result;
+  }
+
+  /**
+   * Checks if the message has expired.
+   * @returns {boolean} True if expired
+   */
+  isExpired() {
+    return Date.now() > this.header.expiresAt;
+  }
+
+  /**
+   * Checks if the message is a fragment.
+   * @returns {boolean} True if this is a fragment
+   */
+  isFragment() {
+    return this.header.fragmentTotal > 1 ||
+      (this.header.flags & MESSAGE_FLAGS.IS_FRAGMENT) !== 0;
+  }
+
+  /**
+   * Checks if the message payload is encrypted.
+   * @returns {boolean} True if encrypted
+   */
+  isEncrypted() {
+    return (this.header.flags & MESSAGE_FLAGS.ENCRYPTED) !== 0;
+  }
+
+  /**
+   * Checks if the message requires acknowledgment.
+   * @returns {boolean} True if ACK required
+   */
+  requiresAck() {
+    return (this.header.flags & MESSAGE_FLAGS.REQUIRES_ACK) !== 0;
+  }
+
+  /**
+   * Checks if the message is a broadcast.
+   * @returns {boolean} True if broadcast
+   */
+  isBroadcast() {
+    return (this.header.flags & MESSAGE_FLAGS.IS_BROADCAST) !== 0;
+  }
+
+  /**
+   * Checks if the message is high priority.
+   * @returns {boolean} True if high priority
+   */
+  isHighPriority() {
+    return (this.header.flags & MESSAGE_FLAGS.HIGH_PRIORITY) !== 0;
+  }
+
+  /**
+   * Gets the payload content as a UTF-8 string.
+   * Only meaningful for text message types.
+   * @returns {string} Decoded payload content
+   */
+  getContent() {
+    return new TextDecoder().decode(this.payload);
+  }
+
+  /**
+   * Gets the message ID as a hex string.
+   * @returns {string} Message ID hex string
+   */
+  getMessageId() {
+    return this.header.getMessageIdHex();
+  }
+
+  /**
+   * Gets the total size of the message in bytes.
+   * @returns {number} Total message size
+   */
+  getSize() {
+    return HEADER_SIZE + this.payload.length;
+  }
+
+  /**
+   * Increments the hop count. Used when relaying messages.
+   * @throws {MessageError} If max hops exceeded
+   */
+  incrementHopCount() {
+    if (this.header.hopCount >= this.header.maxHops) {
+      throw MessageError.maxHopsExceeded(this.getMessageId(), {
+        hopCount: this.header.hopCount,
+        maxHops: this.header.maxHops
+      });
+    }
+    this.header.hopCount++;
+  }
+
+  /**
+   * Creates a clone of this message.
+   * @returns {Message} Cloned message
+   */
+  clone() {
+    const headerClone = new MessageHeader({
+      version: this.header.version,
+      type: this.header.type,
+      flags: this.header.flags,
+      hopCount: this.header.hopCount,
+      maxHops: this.header.maxHops,
+      messageId: new Uint8Array(this.header.messageId),
+      timestamp: this.header.timestamp,
+      expiresAt: this.header.expiresAt,
+      payloadLength: this.header.payloadLength,
+      fragmentIndex: this.header.fragmentIndex,
+      fragmentTotal: this.header.fragmentTotal,
+      checksum: this.header.checksum
+    });
+
+    return new Message(headerClone, new Uint8Array(this.payload));
+  }
+}
+
+module.exports = {
+  Message
+};

package/src/protocol/serializer.js

@@ -0,0 +1,186 @@
+'use strict';
+
+/**
+ * @fileoverview Binary serialization for mesh protocol messages.
+ * @module protocol/serializer
+ */
+
+const { HEADER_SIZE } = require('./header');
+const { Message } = require('./message');
+const { crc32 } = require('./crc32');
+const { PROTOCOL_VERSION, MESSAGE_FLAGS, MESH_CONFIG } = require('../constants');
+const { MessageError } = require('../errors');
+
+/**
+ * Serializes a message header to bytes.
+ * Calculates CRC32 checksum and includes it in the output.
+ *
+ * @param {MessageHeader|Object} header - Header to serialize
+ * @returns {Uint8Array} 48-byte serialized header
+ * @throws {MessageError} If header is invalid
+ *
+ * @example
+ * const header = MessageHeader.create({ type: MESSAGE_TYPE.TEXT, payloadLength: 5 });
+ * const bytes = serializeHeader(header);
+ */
+function serializeHeader(header) {
+  if (!header || typeof header !== 'object') {
+    throw MessageError.invalidFormat(null, { reason: 'Header must be an object' });
+  }
+
+  const buffer = new Uint8Array(HEADER_SIZE);
+  const view = new DataView(buffer.buffer);
+
+  // Validate required fields
+  if (header.messageId === null || header.messageId === undefined || header.messageId.length !== 16) {
+    throw new Error('Invalid messageId');
+  }
+
+  // Byte 0: version
+  buffer[0] = header.version ?? PROTOCOL_VERSION;
+
+  // Byte 1: type
+  buffer[1] = header.type;
+
+  // Byte 2: flags
+  buffer[2] = header.flags ?? MESSAGE_FLAGS.NONE;
+
+  // Byte 3: hopCount
+  buffer[3] = header.hopCount ?? 0;
+
+  // Byte 4: maxHops
+  buffer[4] = header.maxHops ?? MESH_CONFIG.MAX_HOPS;
+
+  // Bytes 5-7: reserved (already zeros)
+
+  // Bytes 8-23: messageId (16 bytes)
+  buffer.set(header.messageId, 8);
+
+  // Bytes 24-31: timestamp (big-endian uint64)
+  writeUint64BE(view, 24, header.timestamp);
+
+  // Bytes 32-39: expiresAt (big-endian uint64)
+  writeUint64BE(view, 32, header.expiresAt);
+
+  // Bytes 40-41: payloadLength (big-endian uint16)
+  view.setUint16(40, header.payloadLength, false);
+
+  // Byte 42: fragmentIndex
+  buffer[42] = header.fragmentIndex ?? 0;
+
+  // Byte 43: fragmentTotal
+  buffer[43] = header.fragmentTotal ?? 1;
+
+  // Bytes 44-47: checksum (calculated over bytes 0-43)
+  const checksumData = buffer.slice(0, 44);
+  const checksum = crc32(checksumData);
+  view.setUint32(44, checksum, false);
+
+  return buffer;
+}
+
+/**
+ * Serializes a complete message (header + payload) to bytes.
+ *
+ * @param {Message|Object} message - Message to serialize
+ * @returns {Uint8Array} Serialized message bytes
+ * @throws {MessageError} If message is invalid
+ *
+ * @example
+ * const message = Message.create({ type: MESSAGE_TYPE.TEXT, payload: 'Hello' });
+ * const bytes = serialize(message);
+ */
+function serialize(message) {
+  if (!message || typeof message !== 'object') {
+    throw MessageError.invalidFormat(null, { reason: 'Message must be an object' });
+  }
+
+  // Handle Message instances
+  if (message instanceof Message) {
+    return message.toBytes();
+  }
+
+  // Handle plain objects with header and payload
+  const header = message.header;
+  let payload = message.payload;
+
+  if (!header) {
+    throw MessageError.invalidFormat(null, { reason: 'Message must have a header' });
+  }
+
+  // Convert string payload to bytes
+  if (typeof payload === 'string') {
+    payload = new TextEncoder().encode(payload);
+  }
+
+  // Default to empty payload
+  if (!payload) {
+    payload = new Uint8Array(0);
+  }
+
+  if (!(payload instanceof Uint8Array)) {
+    throw MessageError.invalidFormat(null, { reason: 'Payload must be Uint8Array or string' });
+  }
+
+  // Update payloadLength in header
+  const headerWithLength = {
+    ...header,
+    payloadLength: payload.length
+  };
+
+  const headerBytes = serializeHeader(headerWithLength);
+  const result = new Uint8Array(headerBytes.length + payload.length);
+
+  result.set(headerBytes, 0);
+  result.set(payload, headerBytes.length);
+
+  return result;
+}
+
+/**
+ * Writes a 64-bit unsigned integer in big-endian format.
+ * JavaScript numbers can safely represent integers up to 2^53.
+ *
+ * @param {DataView} view - DataView to write to
+ * @param {number} offset - Byte offset
+ * @param {number} value - Value to write
+ */
+function writeUint64BE(view, offset, value) {
+  // Split into high and low 32-bit parts
+  const high = Math.floor(value / 0x100000000);
+  const low = value >>> 0;
+
+  view.setUint32(offset, high, false);
+  view.setUint32(offset + 4, low, false);
+}
+
+/**
+ * Serializes multiple messages into a single buffer.
+ * Useful for batch transmission.
+ *
+ * @param {Array<Message>} messages - Array of messages
+ * @returns {Uint8Array} Concatenated message bytes
+ */
+function serializeBatch(messages) {
+  if (!Array.isArray(messages)) {
+    throw MessageError.invalidFormat(null, { reason: 'Messages must be an array' });
+  }
+
+  const serialized = messages.map(msg => serialize(msg));
+  const totalLength = serialized.reduce((sum, arr) => sum + arr.length, 0);
+  const result = new Uint8Array(totalLength);
+
+  let offset = 0;
+  for (const bytes of serialized) {
+    result.set(bytes, offset);
+    offset += bytes.length;
+  }
+
+  return result;
+}
+
+module.exports = {
+  serialize,
+  serializeHeader,
+  serializeBatch
+};

package/src/protocol/validator.js

@@ -0,0 +1,276 @@
+'use strict';
+
+/**
+ * @fileoverview Message and header validation for mesh protocol.
+ * @module protocol/validator
+ */
+
+const { HEADER_SIZE } = require('./header');
+const { crc32 } = require('./crc32');
+const { PROTOCOL_VERSION, MESSAGE_TYPE, MESH_CONFIG } = require('../constants');
+
+/**
+ * Set of valid message type values for fast lookup.
+ * @type {Set<number>}
+ */
+const VALID_MESSAGE_TYPES = new Set(Object.values(MESSAGE_TYPE));
+
+/**
+ * Validates a message header.
+ *
+ * @param {MessageHeader|Object} header - Header to validate
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ *
+ * @example
+ * const result = validateHeader(header);
+ * if (!result.valid) {
+ *   console.error('Header errors:', result.errors);
+ * }
+ */
+function validateHeader(header) {
+  const errors = [];
+
+  if (!header || typeof header !== 'object') {
+    return { valid: false, errors: ['Header must be an object'] };
+  }
+
+  // Validate protocol version
+  if (header.version !== PROTOCOL_VERSION) {
+    errors.push(`Unsupported protocol version: ${header.version}, expected: ${PROTOCOL_VERSION}`);
+  }
+
+  // Validate message type
+  if (!VALID_MESSAGE_TYPES.has(header.type)) {
+    errors.push(`Invalid message type: 0x${header.type?.toString(16) ?? 'undefined'}`);
+  }
+
+  // Validate hop count
+  if (typeof header.hopCount !== 'number' || header.hopCount < 0) {
+    errors.push(`Invalid hop count: ${header.hopCount}`);
+  }
+
+  // Validate max hops
+  if (typeof header.maxHops !== 'number' || header.maxHops < 1) {
+    errors.push(`Invalid max hops: ${header.maxHops}`);
+  }
+
+  // Validate hop count vs max hops
+  if (header.hopCount > header.maxHops) {
+    errors.push(`Hop count (${header.hopCount}) exceeds max hops (${header.maxHops})`);
+  }
+
+  // Validate message ID
+  if (!header.messageId || !(header.messageId instanceof Uint8Array)) {
+    errors.push('Message ID must be a Uint8Array');
+  } else if (header.messageId.length !== 16) {
+    errors.push(`Message ID must be 16 bytes, got ${header.messageId.length}`);
+  }
+
+  // Validate timestamps
+  if (typeof header.timestamp !== 'number' || header.timestamp <= 0) {
+    errors.push(`Invalid timestamp: ${header.timestamp}`);
+  }
+
+  if (typeof header.expiresAt !== 'number' || header.expiresAt <= 0) {
+    errors.push(`Invalid expiresAt: ${header.expiresAt}`);
+  }
+
+  // Check if expired
+  if (header.expiresAt <= Date.now()) {
+    errors.push('Message has expired');
+  }
+
+  // Validate payload length
+  if (typeof header.payloadLength !== 'number' || header.payloadLength < 0) {
+    errors.push(`Invalid payload length: ${header.payloadLength}`);
+  }
+
+  if (header.payloadLength > MESH_CONFIG.MAX_MESSAGE_SIZE) {
+    errors.push(`Payload too large: ${header.payloadLength} > ${MESH_CONFIG.MAX_MESSAGE_SIZE}`);
+  }
+
+  // Validate fragment fields
+  if (typeof header.fragmentIndex !== 'number' || header.fragmentIndex < 0) {
+    errors.push(`Invalid fragment index: ${header.fragmentIndex}`);
+  }
+
+  if (typeof header.fragmentTotal !== 'number' || header.fragmentTotal < 1) {
+    errors.push(`Invalid fragment total: ${header.fragmentTotal}`);
+  }
+
+  if (header.fragmentIndex >= header.fragmentTotal) {
+    errors.push(`Fragment index (${header.fragmentIndex}) >= total (${header.fragmentTotal})`);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Validates a complete message (header + payload).
+ *
+ * @param {Message|Object} message - Message to validate
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ *
+ * @example
+ * const result = validateMessage(message);
+ * if (!result.valid) {
+ *   console.error('Message errors:', result.errors);
+ * }
+ */
+function validateMessage(message) {
+  const errors = [];
+
+  if (!message || typeof message !== 'object') {
+    return { valid: false, errors: ['Message must be an object'] };
+  }
+
+  // Validate header exists
+  if (!message.header) {
+    errors.push('Message must have a header');
+    return { valid: false, errors };
+  }
+
+  // Validate header
+  const headerResult = validateHeader(message.header);
+  errors.push(...headerResult.errors);
+
+  // Validate payload exists
+  if (!message.payload) {
+    errors.push('Message must have a payload');
+  } else if (!(message.payload instanceof Uint8Array)) {
+    errors.push('Payload must be a Uint8Array');
+  } else {
+    // Validate payload length matches header
+    if (message.payload.length !== message.header.payloadLength) {
+      errors.push(
+        `Payload length mismatch: header says ${message.header.payloadLength}, ` +
+        `actual is ${message.payload.length}`
+      );
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Validates message checksum against the header data.
+ *
+ * @param {Uint8Array} headerBytes - Raw 48-byte header
+ * @returns {{ valid: boolean, expected: number, actual: number }} Checksum result
+ */
+function validateChecksum(headerBytes) {
+  if (!(headerBytes instanceof Uint8Array) || headerBytes.length < HEADER_SIZE) {
+    return { valid: false, expected: 0, actual: 0 };
+  }
+
+  const view = new DataView(headerBytes.buffer, headerBytes.byteOffset, HEADER_SIZE);
+  const storedChecksum = view.getUint32(44, false);
+  const checksumData = headerBytes.slice(0, 44);
+  const calculatedChecksum = crc32(checksumData);
+
+  return {
+    valid: storedChecksum === calculatedChecksum,
+    expected: storedChecksum,
+    actual: calculatedChecksum
+  };
+}
+
+/**
+ * Checks if a message type is valid.
+ *
+ * @param {number} type - Message type to check
+ * @returns {boolean} True if valid
+ */
+function isValidMessageType(type) {
+  return VALID_MESSAGE_TYPES.has(type);
+}
+
+/**
+ * Checks if a message is expired.
+ *
+ * @param {Message|MessageHeader|Object} messageOrHeader - Message or header
+ * @returns {boolean} True if expired
+ */
+function isExpired(messageOrHeader) {
+  const header = messageOrHeader.header || messageOrHeader;
+  return header.expiresAt <= Date.now();
+}
+
+/**
+ * Checks if hop count has exceeded maximum.
+ *
+ * @param {Message|MessageHeader|Object} messageOrHeader - Message or header
+ * @returns {boolean} True if exceeded
+ */
+function hasExceededMaxHops(messageOrHeader) {
+  const header = messageOrHeader.header || messageOrHeader;
+  return header.hopCount > header.maxHops;
+}
+
+/**
+ * Validates raw bytes can be parsed as a valid message.
+ * Does not fully parse, just validates structure.
+ *
+ * @param {Uint8Array} data - Raw message bytes
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ */
+function validateRawMessage(data) {
+  const errors = [];
+
+  if (!(data instanceof Uint8Array)) {
+    return { valid: false, errors: ['Data must be a Uint8Array'] };
+  }
+
+  if (data.length < HEADER_SIZE) {
+    return { valid: false, errors: [`Data too short: ${data.length} < ${HEADER_SIZE}`] };
+  }
+
+  // Check version
+  if (data[0] !== PROTOCOL_VERSION) {
+    errors.push(`Unsupported version: ${data[0]}`);
+  }
+
+  // Check message type
+  if (!VALID_MESSAGE_TYPES.has(data[1])) {
+    errors.push(`Invalid message type: 0x${data[1].toString(16)}`);
+  }
+
+  // Validate checksum
+  const checksumResult = validateChecksum(data.slice(0, HEADER_SIZE));
+  if (!checksumResult.valid) {
+    errors.push(
+      `Checksum mismatch: expected 0x${checksumResult.expected.toString(16)}, ` +
+      `got 0x${checksumResult.actual.toString(16)}`
+    );
+  }
+
+  // Check payload length
+  const view = new DataView(data.buffer, data.byteOffset, HEADER_SIZE);
+  const payloadLength = view.getUint16(40, false);
+  const expectedTotal = HEADER_SIZE + payloadLength;
+
+  if (data.length < expectedTotal) {
+    errors.push(`Incomplete message: expected ${expectedTotal} bytes, got ${data.length}`);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+module.exports = {
+  validateMessage,
+  validateHeader,
+  validateChecksum,
+  validateRawMessage,
+  isValidMessageType,
+  isExpired,
+  hasExceededMaxHops
+};