@cnhongwei/react-native-mqtt 0.0.0-stage → 0.1.0

package/src/errors.ts

@@ -0,0 +1,51 @@
+export type MqttErrorCode =
+  | 'ERR_INVALID_OPTIONS'
+  | 'ERR_INVALID_PAYLOAD'
+  | 'ERR_NATIVE_UNAVAILABLE'
+  | 'ERR_CONTRACT_MISMATCH'
+  | 'ERR_NOT_CONNECTED'
+  | 'ERR_DISPOSED'
+  | 'ERR_OPERATION_IN_PROGRESS'
+  | 'ERR_OPERATION_SUPERSEDED'
+  | 'ERR_CONNECT_TIMEOUT'
+  | 'ERR_OPERATION_TIMEOUT'
+  | 'ERR_CONNECTION_REFUSED'
+  | 'ERR_CONNECTION_LOST'
+  | 'ERR_SUBSCRIPTION_CONFLICT'
+  | 'ERR_SUBSCRIBE_FAILED'
+  | 'ERR_UNSUBSCRIBE_FAILED'
+  | 'ERR_PUBLISH_FAILED'
+  | 'ERR_TLS'
+  | 'ERR_CLEANUP_FAILED'
+  | 'ERR_UNKNOWN';
+export class MqttError extends Error {
+  readonly code: MqttErrorCode;
+  readonly operation?: string;
+  readonly generation?: number;
+  readonly reasonCode?: number;
+  readonly reasonString?: string;
+  readonly outcome?: 'not-sent' | 'rejected' | 'unknown';
+  constructor(
+    code: MqttErrorCode,
+    message: string,
+    details: {
+      operation?: string;
+      generation?: number;
+      reasonCode?: number;
+      reasonString?: string;
+      outcome?: 'not-sent' | 'rejected' | 'unknown';
+    } = {}
+  ) {
+    super(message);
+    this.name = 'MqttError';
+    this.code = code;
+    this.operation = details.operation;
+    this.generation = details.generation;
+    this.reasonCode = details.reasonCode;
+    this.reasonString = details.reasonString;
+    this.outcome = details.outcome;
+  }
+}
+export function invalidOptions(message: string): MqttError {
+  return new MqttError('ERR_INVALID_OPTIONS', message, { outcome: 'not-sent' });
+}

package/src/helpers.ts

@@ -0,0 +1,151 @@
+import { MqttError } from './errors';
+type TextEncoderLike = { encode(input: string): Uint8Array };
+type TextDecoderLike = { decode(input: Uint8Array): string };
+const textEncoder = (): TextEncoderLike | undefined => {
+  const ctor = (
+    globalThis as unknown as { TextEncoder?: new () => TextEncoderLike }
+  ).TextEncoder;
+  return ctor === undefined ? undefined : new ctor();
+};
+const textDecoder = (): TextDecoderLike | undefined => {
+  const ctor = (
+    globalThis as unknown as {
+      TextDecoder?: new (
+        label?: string,
+        options?: { fatal?: boolean }
+      ) => TextDecoderLike;
+    }
+  ).TextDecoder;
+  return ctor === undefined ? undefined : new ctor('utf-8', { fatal: true });
+};
+function invalidPayload(message: string): MqttError {
+  return new MqttError('ERR_INVALID_PAYLOAD', message, { outcome: 'not-sent' });
+}
+export function encodeUtf8(text: string): Uint8Array {
+  const encoder = textEncoder();
+  if (encoder === undefined) throw invalidPayload('TextEncoder is unavailable');
+  return encoder.encode(text);
+}
+export function decodeUtf8(bytes: Uint8Array): string {
+  const decoder = textDecoder();
+  if (decoder !== undefined) {
+    try {
+      return decoder.decode(bytes);
+    } catch {
+      throw invalidPayload('Payload is not valid UTF-8');
+    }
+  }
+
+  // Hermes/RN versions without TextDecoder still need a deterministic,
+  // strict decoder for incoming MQTT payloads.
+  let result = '';
+  const codePoints: number[] = [];
+  const flush = (): void => {
+    if (codePoints.length === 0) return;
+    result += String.fromCodePoint(...codePoints);
+    codePoints.length = 0;
+  };
+  const continuation = (index: number): number => {
+    const value = bytes[index];
+    if (value === undefined || (value & 0xc0) !== 0x80)
+      throw invalidPayload('Payload is not valid UTF-8');
+    return value & 0x3f;
+  };
+  for (let index = 0; index < bytes.length; index += 1) {
+    const first = bytes[index];
+    if (first === undefined) throw invalidPayload('Payload is not valid UTF-8');
+    if (first <= 0x7f) {
+      codePoints.push(first);
+      continue;
+    }
+    let codePoint: number;
+    if (first >= 0xc2 && first <= 0xdf) {
+      codePoint = ((first & 0x1f) << 6) | continuation(index + 1);
+      index += 1;
+    } else if (first >= 0xe0 && first <= 0xef) {
+      const second = bytes[index + 1];
+      if (
+        second === undefined ||
+        (second & 0xc0) !== 0x80 ||
+        (first === 0xe0 && second < 0xa0) ||
+        (first === 0xed && second > 0x9f)
+      )
+        throw invalidPayload('Payload is not valid UTF-8');
+      codePoint =
+        ((first & 0x0f) << 12) |
+        ((second & 0x3f) << 6) |
+        continuation(index + 2);
+      index += 2;
+    } else if (first >= 0xf0 && first <= 0xf4) {
+      const second = bytes[index + 1];
+      if (
+        second === undefined ||
+        (second & 0xc0) !== 0x80 ||
+        (first === 0xf0 && second < 0x90) ||
+        (first === 0xf4 && second > 0x8f)
+      )
+        throw invalidPayload('Payload is not valid UTF-8');
+      codePoint =
+        ((first & 0x07) << 18) |
+        ((second & 0x3f) << 12) |
+        (continuation(index + 2) << 6) |
+        continuation(index + 3);
+      index += 3;
+    } else {
+      throw invalidPayload('Payload is not valid UTF-8');
+    }
+    codePoints.push(codePoint);
+    if (codePoints.length >= 0x4000) flush();
+  }
+  flush();
+  return result;
+}
+const base64Alphabet =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+export function encodeBase64(bytes: Uint8Array): string {
+  let result = '';
+  for (let index = 0; index < bytes.length; index += 3) {
+    const a = bytes[index] ?? 0;
+    const b = bytes[index + 1];
+    const c = bytes[index + 2];
+    result += base64Alphabet[a >> 2];
+    result += base64Alphabet[((a & 3) << 4) | ((b ?? 0) >> 4)];
+    result +=
+      b === undefined ? '=' : base64Alphabet[((b & 15) << 2) | ((c ?? 0) >> 6)];
+    result += c === undefined ? '=' : base64Alphabet[c & 63];
+  }
+  return result;
+}
+export function decodeBase64(text: string): Uint8Array {
+  if (text.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(text))
+    throw invalidPayload('Base64 must use RFC 4648 alphabet and padding');
+  const padding = text.endsWith('==') ? 2 : text.endsWith('=') ? 1 : 0;
+  const firstPadding = text.indexOf('=');
+  if (firstPadding >= 0 && firstPadding < text.length - padding)
+    throw invalidPayload('Base64 padding is invalid');
+  const output = new Uint8Array((text.length / 4) * 3 - padding);
+  let outputIndex = 0;
+  for (let index = 0; index < text.length; index += 4) {
+    const chars = text.slice(index, index + 4);
+    const values = chars
+      .split('')
+      .map((char) => (char === '=' ? 0 : base64Alphabet.indexOf(char)));
+    const v0 = values[0] ?? -1;
+    const v1 = values[1] ?? -1;
+    const v2 = values[2] ?? -1;
+    const v3 = values[3] ?? -1;
+    if ([v0, v1, v2, v3].some((value) => value < 0))
+      throw invalidPayload('Base64 contains an invalid character');
+    if (chars[2] === '=' && (v1 & 15) !== 0)
+      throw invalidPayload('Base64 has non-zero trailing bits');
+    if (chars[3] === '=' && chars[2] !== '=' && (v2 & 3) !== 0)
+      throw invalidPayload('Base64 has non-zero trailing bits');
+    const combined = (v0 << 18) | (v1 << 12) | (v2 << 6) | v3;
+    if (outputIndex < output.length)
+      output[outputIndex++] = (combined >> 16) & 255;
+    if (outputIndex < output.length)
+      output[outputIndex++] = (combined >> 8) & 255;
+    if (outputIndex < output.length) output[outputIndex++] = combined & 255;
+  }
+  return output;
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export type { Spec as NativeReactNativeMqttSpec } from './NativeReactNativeMqtt';
+export { MqttError } from './errors';
+export type { MqttErrorCode } from './errors';
+export { createMqttClient } from './client';
+export { decodeBase64, decodeUtf8, encodeBase64, encodeUtf8 } from './helpers';
+export type {
+  ConnAck,
+  ConnectionState,
+  DeliveryOptions,
+  Diagnostic,
+  Listener,
+  Message,
+  Mqtt4Options,
+  Mqtt5Options,
+  MqttClient,
+  MqttOptions,
+  PublishOptions,
+  QoS,
+  ReconnectOptions,
+  SessionSnapshot,
+  SubscribeOptions,
+  Subscription,
+  TlsOptions,
+  Transport,
+  UserProperty,
+  WillOptions,
+} from './types';
+
+export const packageName = '@cnhongwei/react-native-mqtt' as const;
+export const packageVersion = '0.1.0' as const;

package/src/types.ts

@@ -0,0 +1,184 @@
+export type QoS = 0 | 1 | 2;
+export type Transport = 'tcp' | 'tls' | 'ws' | 'wss';
+export type ConnectionState =
+  | 'idle'
+  | 'connecting'
+  | 'connected'
+  | 'reconnecting'
+  | 'disconnecting'
+  | 'disconnected'
+  | 'closed';
+export type UserProperty = { key: string; value: string };
+export type TlsOptions = {
+  caBase64?: string;
+  p12Base64?: string;
+  p12Password?: string;
+  insecure?: boolean;
+  allowInvalidHostnameForTesting?: boolean;
+};
+export type ReconnectOptions = {
+  enabled?: boolean;
+  initialDelayMs?: number;
+  maxDelayMs?: number;
+  jitterRatio?: number;
+};
+export type DeliveryOptions = {
+  maxQueuedMessages?: number;
+  maxQueuedBytes?: number;
+  maxMessageBytes?: number;
+  batchMaxMessages?: number;
+  batchMaxBytes?: number;
+  batchAckTimeoutMs?: number;
+  overflowPolicy?: 'disconnect' | 'drop-newest';
+};
+export type WillOptions = {
+  topic: string;
+  payloadBase64: string;
+  qos?: QoS;
+  retained?: boolean;
+};
+
+export type CommonMqttOptions = {
+  host: string;
+  port: number;
+  transport?: Transport;
+  path?: string;
+  clientId?: string;
+  username?: string;
+  password?: string;
+  keepAliveSeconds?: number;
+  connectTimeoutMs?: number;
+  operationTimeoutMs?: number;
+  disconnectTimeoutMs?: number;
+  reconnect?: ReconnectOptions;
+  tls?: TlsOptions;
+  will?: WillOptions;
+  delivery?: DeliveryOptions;
+};
+export type Mqtt4Options = CommonMqttOptions & {
+  /** MQTT 3.1.1 (default). MQTT 3.1 / protocol level 3 is unsupported. */
+  protocolVersion?: 4;
+  cleanSession?: boolean;
+  cleanStart?: never;
+  sessionExpiryIntervalSeconds?: never;
+  receiveMaximum?: never;
+  userProperties?: never;
+};
+export type Mqtt5Options = CommonMqttOptions & {
+  /** MQTT 5.0. Only protocol levels 4 and 5 are supported on Android/iOS. */
+  protocolVersion: 5;
+  cleanSession?: never;
+  cleanStart?: boolean;
+  sessionExpiryIntervalSeconds?: number;
+  receiveMaximum?: number;
+  userProperties?: UserProperty[];
+};
+export type MqttOptions = Mqtt4Options | Mqtt5Options;
+
+export type SubscribeOptions = {
+  qos?: QoS;
+  noLocal?: boolean;
+  retainAsPublished?: boolean;
+  retainHandling?: 0 | 1 | 2;
+};
+export type PublishOptions = {
+  qos?: QoS;
+  retained?: boolean;
+  userProperties?: UserProperty[];
+  contentType?: string;
+  responseTopic?: string;
+  correlationDataBase64?: string;
+  messageExpiryIntervalSeconds?: number;
+  payloadFormatIndicator?: 0 | 1;
+};
+export type ConnAck = {
+  sessionPresent: boolean;
+  assignedClientId?: string;
+  reasonCode?: number;
+  reasonString?: string;
+  userProperties?: UserProperty[];
+};
+export type SessionSnapshot = {
+  instanceId: string;
+  revision: number;
+  generation: number;
+  state: ConnectionState;
+  lastConnAck: ConnAck | null;
+  subscriptionsRevision: number;
+  subscriptionsStatus: 'pending' | 'ready' | 'failed';
+  deliveryStatus: 'active' | 'stalled' | 'closed';
+};
+export type Message = {
+  instanceId: string;
+  generation: number;
+  topic: string;
+  bytes: Uint8Array;
+  qos: QoS;
+  retained: boolean;
+  userProperties?: UserProperty[];
+  contentType?: string;
+  responseTopic?: string;
+  correlationData?: Uint8Array;
+  messageExpiryIntervalSeconds?: number;
+  payloadFormatIndicator?: 0 | 1;
+};
+export type Diagnostic = {
+  instanceId: string;
+  generation: number;
+  code:
+    | 'SUBSCRIPTION_SYNC_FAILED'
+    | 'DELIVERY_STALLED'
+    | 'QUEUE_OVERFLOW'
+    | 'LISTENER_ERROR'
+    | 'INSECURE_TLS';
+  message: string;
+  operation?: string;
+  reasonCode?: number;
+  reasonString?: string;
+  metrics?: {
+    queuedMessages: number;
+    queuedBytes: number;
+    pendingOperations: number;
+    droppedMessages: number;
+    reconnectAttempts: number;
+  };
+};
+export type Listener = { remove(): void };
+export type Subscription = {
+  readonly topicFilter: string;
+  readonly qos: QoS;
+  unsubscribe(): Promise<void>;
+};
+export type MqttClient = {
+  readonly instanceId: string;
+  readonly clientId: string;
+  readonly state: ConnectionState;
+  connect(): Promise<ConnAck>;
+  disconnect(): Promise<void>;
+  dispose(): Promise<void>;
+  ready(): Promise<void>;
+  getSnapshot(): Promise<SessionSnapshot>;
+  subscribe(
+    topicFilter: string,
+    options?: SubscribeOptions
+  ): Promise<Subscription>;
+  publishText(
+    topic: string,
+    text: string,
+    options?: PublishOptions
+  ): Promise<void>;
+  publishBytes(
+    topic: string,
+    bytes: Uint8Array,
+    options?: PublishOptions
+  ): Promise<void>;
+  publishBase64(
+    topic: string,
+    base64: string,
+    options?: PublishOptions
+  ): Promise<void>;
+  onStateChange(listener: (snapshot: SessionSnapshot) => void): Listener;
+  onMessage(listener: (message: Message) => void): Listener;
+  onDiagnostic(listener: (diagnostic: Diagnostic) => void): Listener;
+  readonly [Symbol.asyncDispose]?: () => Promise<void>;
+};