appium-ios-tuntap 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.4.2](https://github.com/appium/appium-ios-tuntap/compare/v0.4.1...v0.4.2) (2026-06-01)
+
+### Miscellaneous Chores
+
+* Tune further tunnel perf ([#46](https://github.com/appium/appium-ios-tuntap/issues/46)) ([d422937](https://github.com/appium/appium-ios-tuntap/commit/d422937a47b16bf1c984030772d1de6e555609e6))
+
+## [0.4.1](https://github.com/appium/appium-ios-tuntap/compare/v0.4.0...v0.4.1) (2026-05-31)
+
+### Bug Fixes
+
+* Improve tunnel performance ([#45](https://github.com/appium/appium-ios-tuntap/issues/45)) ([576d353](https://github.com/appium/appium-ios-tuntap/commit/576d3535137bb0cf79634ab820b3675db6cbbb86))
+
 ## [0.4.0](https://github.com/appium/appium-ios-tuntap/compare/v0.3.0...v0.4.0) (2026-05-30)
 
 ### Features

package/lib/index.d.ts

@@ -1,3 +1,3 @@
 export { TunTapDeviceError, TunTapError, TunTapPermissionError } from './errors.js';
 export { TunTap, type PacketCallback } from './TunTap.js';
-export * from './tunnel.js';
+export * from './tunnel/index.js';

package/lib/index.js

@@ -1,3 +1,3 @@
 export { TunTapDeviceError, TunTapError, TunTapPermissionError } from './errors.js';
 export { TunTap } from './TunTap.js';
-export * from './tunnel.js';
+export * from './tunnel/index.js';

package/lib/tunnel/buffer-utils.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Append socket/TUN chunks without repeated Buffer.concat growth copies.
+ */
+export declare function appendBuffer(existing: Buffer, chunk: Buffer): Buffer;

package/lib/tunnel/buffer-utils.js

@@ -0,0 +1,15 @@
+/**
+ * Append socket/TUN chunks without repeated Buffer.concat growth copies.
+ */
+export function appendBuffer(existing, chunk) {
+    if (chunk.length === 0) {
+        return existing;
+    }
+    if (existing.length === 0) {
+        return Buffer.from(chunk);
+    }
+    const combined = Buffer.allocUnsafe(existing.length + chunk.length);
+    existing.copy(combined, 0);
+    chunk.copy(combined, existing.length);
+    return combined;
+}

package/lib/tunnel/constants.d.ts

@@ -0,0 +1,10 @@
+/** CDTunnel lockdown handshake MTU (IPv6 minimum). */
+export declare const CD_TUNNEL_MTU = 1280;
+export declare const CD_TUNNEL_MAGIC = "CDTunnel";
+export declare const CD_TUNNEL_MAGIC_SIZE = 8;
+export declare const CD_TUNNEL_HEADER_SIZE: number;
+export declare const CD_TUNNEL_HANDSHAKE_TIMEOUT_MS = 30000;
+export declare const IPV6_HEADER_SIZE = 40;
+export declare const IPV6_VERSION = 6;
+export declare const IPPROTO_TCP = 6;
+export declare const IPPROTO_UDP = 17;

package/lib/tunnel/constants.js

@@ -0,0 +1,10 @@
+/** CDTunnel lockdown handshake MTU (IPv6 minimum). */
+export const CD_TUNNEL_MTU = 1280;
+export const CD_TUNNEL_MAGIC = 'CDTunnel';
+export const CD_TUNNEL_MAGIC_SIZE = 8;
+export const CD_TUNNEL_HEADER_SIZE = CD_TUNNEL_MAGIC_SIZE + 2;
+export const CD_TUNNEL_HANDSHAKE_TIMEOUT_MS = 30_000;
+export const IPV6_HEADER_SIZE = 40;
+export const IPV6_VERSION = 6;
+export const IPPROTO_TCP = 6;
+export const IPPROTO_UDP = 17;

package/lib/tunnel/index.d.ts

@@ -0,0 +1,2 @@
+export type { PacketConsumer, PacketData, TunnelConnection, TunnelManagerEvents } from './types.js';
+export { TunnelManager, connectToTunnelLockdown, exchangeCoreTunnelParameters } from './manager.js';

package/lib/tunnel/index.js

@@ -0,0 +1 @@
+export { TunnelManager, connectToTunnelLockdown, exchangeCoreTunnelParameters } from './manager.js';

package/lib/{tunnel.d.ts → tunnel/manager.d.ts}

@@ -1,57 +1,7 @@
-import { TunTap } from './TunTap.js';
+import { TunTap } from '../TunTap.js';
 import { EventEmitter } from 'node:events';
 import type { Socket } from 'node:net';
-import { Buffer } from 'node:buffer';
-export interface PacketData {
-    protocol: 'TCP' | 'UDP';
-    src: string;
-    dst: string;
-    sourcePort: number;
-    destPort: number;
-    payload: Buffer;
-}
-/**
- * Event names and listener argument tuples for {@link TunnelManager}
- * (matches Node’s `EventEmitter` event map shape).
- *
- * @example
- * tunnelManager.on('data', (packet) => {
- *   // `packet` is PacketData
- * });
- */
-export interface PacketConsumer {
-    /**
-     * Invoked for each parsed TCP/UDP payload extracted from the tunnel stream.
-     *
-     * @param packet — decoded addresses, ports, and payload
-     */
-    onPacket(packet: PacketData): void;
-}
-export interface TunnelManagerEvents {
-    data: [packet: PacketData];
-}
-export interface TunnelConnection {
-    Address: string;
-    RsdPort?: number;
-    tunnelManager: TunnelManager;
-    /** Tear down the tunnel, close the TUN device, and end the socket when appropriate. */
-    closer: () => Promise<void>;
-    /** @param consumer — receives packets for the lifetime of the registration */
-    addPacketConsumer(consumer: PacketConsumer): void;
-    /** @param consumer — must be the same reference passed to {@link TunnelConnection.addPacketConsumer} */
-    removePacketConsumer(consumer: PacketConsumer): void;
-    /** @returns async iterator of packets until the tunnel is stopped */
-    getPacketStream(): AsyncIterable<PacketData>;
-}
-interface TunnelClientParameters {
-    address: string;
-    mtu: number;
-}
-interface TunnelInfo {
-    clientParameters: TunnelClientParameters;
-    serverAddress: string;
-    serverRSDPort?: number;
-}
+import type { PacketConsumer, PacketData, TunnelConnection, TunnelInfo, TunnelManagerEvents } from './types.js';
 /**
  * Bridges a CoreDevice tunnel `Socket` and a {@link TunTap} interface: IPv6 framing, TUN I/O, and packet fan-out.
  * Emits {@link TunnelManagerEvents} (currently `data` with {@link PacketData}) for TCP/UDP packets, same as registered consumers.
@@ -59,14 +9,11 @@ interface TunnelInfo {
 export declare class TunnelManager extends EventEmitter<TunnelManagerEvents> {
     private tun;
     private cancelled;
-    private readInterval;
+    private mtu;
     private buffer;
-    private packetConsumers;
-    private packetQueue;
+    private readonly packetConsumers;
     private deviceConn;
     private cleanupPromise;
-    /** Creates a manager with no TUN device until {@link TunnelManager.setupInterface} succeeds. */
-    constructor();
     /**
      * Register a listener for parsed tunnel packets (in addition to the `data` event).
      *
@@ -108,7 +55,11 @@ export declare class TunnelManager extends EventEmitter<TunnelManagerEvents> {
      * @returns the same promise if already stopping/stopped
      */
     stop(): Promise<void>;
+    private hasPacketTap;
     private processBuffer;
+    private writeDeviceFrameToTun;
+    private tapL4Packet;
+    private dispatchPacketData;
     private startTunReadLoop;
     private _performStop;
 }
@@ -126,4 +77,3 @@ export declare function exchangeCoreTunnelParameters(socket: Socket): Promise<Tu
  * @returns connection handle with {@link TunnelConnection.closer} and packet APIs
  */
 export declare function connectToTunnelLockdown(secureServiceSocket: Socket): Promise<TunnelConnection>;
-export {};

package/lib/{tunnel.js → tunnel/manager.js}

@@ -1,32 +1,21 @@
-import { log } from './logger.js';
-import { TunTap } from './TunTap.js';
+import { log } from '../logger.js';
+import { TunTap } from '../TunTap.js';
 import { EventEmitter } from 'node:events';
 import { Buffer } from 'node:buffer';
+import { CD_TUNNEL_HANDSHAKE_TIMEOUT_MS, CD_TUNNEL_HEADER_SIZE, CD_TUNNEL_MAGIC, CD_TUNNEL_MAGIC_SIZE, CD_TUNNEL_MTU, IPV6_HEADER_SIZE, IPV6_VERSION, IPPROTO_TCP, IPPROTO_UDP, } from './constants.js';
+import { appendBuffer } from './buffer-utils.js';
 /**
  * Bridges a CoreDevice tunnel `Socket` and a {@link TunTap} interface: IPv6 framing, TUN I/O, and packet fan-out.
  * Emits {@link TunnelManagerEvents} (currently `data` with {@link PacketData}) for TCP/UDP packets, same as registered consumers.
  */
 export class TunnelManager extends EventEmitter {
-    tun;
-    cancelled;
-    readInterval;
-    buffer;
-    packetConsumers;
-    packetQueue;
-    deviceConn;
-    cleanupPromise;
-    /** Creates a manager with no TUN device until {@link TunnelManager.setupInterface} succeeds. */
-    constructor() {
-        super();
-        this.tun = null;
-        this.cancelled = false;
-        this.readInterval = null;
-        this.buffer = Buffer.alloc(0);
-        this.packetConsumers = new Set();
-        this.packetQueue = [];
-        this.deviceConn = null;
-        this.cleanupPromise = null;
-    }
+    tun = null;
+    cancelled = false;
+    mtu = CD_TUNNEL_MTU;
+    buffer = Buffer.alloc(0);
+    packetConsumers = new Set();
+    deviceConn = null;
+    cleanupPromise = null;
     /**
      * Register a listener for parsed tunnel packets (in addition to the `data` event).
      *
@@ -99,6 +88,7 @@ export class TunnelManager extends EventEmitter {
                 throw new Error('Failed to open TUN device');
             }
             log.debug(`Opened TUN device: ${this.tun.name}`);
+            this.mtu = tunnelInfo.clientParameters.mtu;
             // Configure the TUN device with IPv6 address and MTU
             await this.tun.configure(tunnelInfo.clientParameters.address, tunnelInfo.clientParameters.mtu);
             // Add route for the server address
@@ -136,14 +126,15 @@ export class TunnelManager extends EventEmitter {
         }
         this.deviceConn = deviceConn;
         log.debug(`Starting bidirectional data forwarding for ${this.tun.name}`);
+        deviceConn.setNoDelay(true);
+        deviceConn.setKeepAlive(true, 1000);
         // Handle data from the device connection
         deviceConn.on('data', (data) => {
             if (this.cancelled) {
                 return;
             }
             try {
-                // Add data to buffer
-                this.buffer = Buffer.concat([this.buffer, data]);
+                this.buffer = appendBuffer(this.buffer, data);
                 // Process IPv6 packets
                 this.processBuffer();
             }
@@ -182,162 +173,107 @@ export class TunnelManager extends EventEmitter {
         this.cleanupPromise = this._performStop();
         return this.cleanupPromise;
     }
+    hasPacketTap() {
+        return this.packetConsumers.size > 0 || this.listenerCount('data') > 0;
+    }
     processBuffer() {
         let offset = 0;
-        // Process as many complete packets as available
-        while (offset + 40 <= this.buffer.length) {
-            // Extract IPv6 header (fixed 40 bytes)
-            const header = this.buffer.slice(offset, offset + 40);
-            // Ensure this is an IPv6 packet (version 6)
-            const version = (header[0] >> 4) & 0x0f;
-            if (version !== 6) {
+        while (offset + IPV6_HEADER_SIZE <= this.buffer.length) {
+            const frame = nextIpv6Frame(this.buffer, offset);
+            if (frame.kind === 'incomplete') {
+                break;
+            }
+            if (frame.kind === 'resync') {
                 offset++;
                 continue;
             }
-            // Get payload length from the IPv6 header
-            const payloadLength = header.readUInt16BE(4);
-            // Ensure we have the full packet (IPv6 header + payload)
-            if (offset + 40 + payloadLength > this.buffer.length) {
-                break; // Wait for more data
+            if (!this.tun) {
+                log.error('TUN device is null during packet processing');
+                break;
             }
-            // Extract the complete IPv6 packet
-            const packet = this.buffer.slice(offset, offset + 40 + payloadLength);
-            // Extract source and destination IPv6 addresses
-            const src = formatIPv6Address(packet.slice(8, 24));
-            const dst = formatIPv6Address(packet.slice(24, 40));
-            // Get the IPv6 next header value
-            const nextHeader = header[6];
-            log.debug(`Processing packet: nextHeader=${nextHeader}, totalLength=${40 + payloadLength}`);
             try {
-                if (!this.tun) {
-                    log.error('TUN device is null during packet processing');
-                    break;
-                }
-                const bytesWritten = this.tun.write(packet);
-                log.debug(`Device → TUN: ${bytesWritten} bytes, IPv6 src=${src}, dst=${dst}`);
-                // Handle UDP packets (nextHeader === 17)
-                if (nextHeader === 17) {
-                    const payload = packet.slice(40);
-                    log.debug(`UDP packet detected: payload length=${payload.length}`);
-                    if (payload.length < 8) {
-                        log.debug('UDP payload too short, not emitting event.');
-                    }
-                    else {
-                        const sourcePort = payload.readUInt16BE(0);
-                        const destPort = payload.readUInt16BE(2);
-                        const udpPayload = payload.slice(8);
-                        const packetData = {
-                            protocol: 'UDP',
-                            src,
-                            dst,
-                            sourcePort,
-                            destPort,
-                            payload: udpPayload,
-                        };
-                        this.emit('data', packetData);
-                        this.packetConsumers.forEach((consumer) => {
-                            try {
-                                consumer.onPacket(packetData);
-                            }
-                            catch (err) {
-                                log.error('Error in packet consumer:', err);
-                            }
-                        });
-                        log.debug('Emitted data event for UDP packet');
-                    }
-                }
-                // Handle TCP packets (nextHeader === 6)
-                else if (nextHeader === 6) {
-                    const tcpHeaderStart = 40;
-                    if (packet.length < tcpHeaderStart + 20) {
-                        log.debug('TCP packet too short for minimum header, skipping.');
-                    }
-                    else {
-                        const sourcePort = packet.readUInt16BE(tcpHeaderStart);
-                        const destPort = packet.readUInt16BE(tcpHeaderStart + 2);
-                        const dataOffsetByte = packet.readUInt8(tcpHeaderStart + 12);
-                        const tcpHeaderLength = (dataOffsetByte >> 4) * 4;
-                        if (packet.length < tcpHeaderStart + tcpHeaderLength) {
-                            log.debug('TCP header length exceeds packet length, skipping.');
-                        }
-                        else {
-                            const tcpPayload = packet.slice(tcpHeaderStart + tcpHeaderLength);
-                            log.debug(`TCP packet detected: headerLength=${tcpHeaderLength}, payload length=${tcpPayload.length}`);
-                            const packetData = {
-                                protocol: 'TCP',
-                                src,
-                                dst,
-                                sourcePort,
-                                destPort,
-                                payload: tcpPayload,
-                            };
-                            this.emit('data', packetData);
-                            this.packetConsumers.forEach((consumer) => {
-                                try {
-                                    consumer.onPacket(packetData);
-                                }
-                                catch (err) {
-                                    log.error('Error in packet consumer:', err);
-                                }
-                            });
-                            log.debug('Emitted data event for TCP packet');
-                        }
-                    }
-                }
-                else {
-                    log.debug('Packet is not UDP or TCP (nextHeader !== 17 and !== 6)');
-                }
+                this.writeDeviceFrameToTun(this.tun, frame.packet, frame.nextHeader);
             }
             catch (err) {
                 log.error(`Error writing to TUN: ${err.message}`);
             }
-            // Move to the next packet
-            offset += 40 + payloadLength;
+            offset += frame.length;
         }
-        // Keep any remaining partial data
         if (offset > 0) {
-            this.buffer = this.buffer.slice(offset);
+            this.buffer = this.buffer.subarray(offset);
         }
     }
-    startTunReadLoop(deviceConn) {
-        this.readInterval = setInterval(() => {
-            if (this.cancelled || !this.tun) {
-                return;
+    writeDeviceFrameToTun(tun, packet, nextHeader) {
+        const bytesWritten = tun.write(packet);
+        if (!this.hasPacketTap()) {
+            log.debug(`Device → TUN: ${bytesWritten} bytes`);
+            return;
+        }
+        const { src, dst } = ipv6Endpoints(packet);
+        log.debug(`Device → TUN: ${bytesWritten} bytes, IPv6 src=${src}, dst=${dst}`);
+        this.tapL4Packet(packet, nextHeader, src, dst);
+    }
+    tapL4Packet(packet, nextHeader, src, dst) {
+        let packetData = null;
+        if (nextHeader === IPPROTO_UDP) {
+            packetData = parseUdpPacketData(packet, src, dst);
+            if (!packetData) {
+                log.debug('UDP payload too short, not emitting event.');
+            }
+            else {
+                log.debug(`UDP packet detected: payload length=${packetData.payload.length}`);
+            }
+        }
+        else if (nextHeader === IPPROTO_TCP) {
+            packetData = parseTcpPacketData(packet, src, dst);
+            if (!packetData) {
+                log.debug('TCP packet too short or malformed, skipping.');
             }
+            else {
+                log.debug(`TCP packet detected: payload length=${packetData.payload.length}`);
+            }
+        }
+        else {
+            log.debug('Packet is not UDP or TCP (nextHeader !== 17 and !== 6)');
+        }
+        if (packetData) {
+            this.dispatchPacketData(packetData);
+        }
+    }
+    dispatchPacketData(packetData) {
+        this.emit('data', packetData);
+        for (const consumer of this.packetConsumers) {
             try {
-                // Read from TUN
-                const data = this.tun.read(16384); // A large buffer for MTU
-                // If we got data, send it to the device
-                if (data && data.length > 0) {
-                    if (data.length >= 40) {
-                        // Minimum IPv6 header size
-                        log.debug(`TUN → Device: ${data.length} bytes, IPv6 src=${formatIPv6Address(data.slice(8, 24))}, dst=${formatIPv6Address(data.slice(24, 40))}`);
-                    }
-                    else {
-                        log.debug(`TUN → Device: ${data.length} bytes (too small for IPv6 header)`);
-                    }
-                    if (!deviceConn.destroyed) {
-                        deviceConn.write(data);
-                    }
-                }
+                consumer.onPacket(packetData);
             }
             catch (err) {
-                if (!this.cancelled) {
-                    log.error('Error reading from TUN:', err.message);
-                }
+                log.error('Error in packet consumer:', err);
             }
-        }, 5); // Poll every 5ms
+        }
+        log.debug(`Emitted data event for ${packetData.protocol} packet`);
+    }
+    startTunReadLoop(deviceConn) {
+        if (!this.tun) {
+            return;
+        }
+        this.tun.startPolling((data) => {
+            if (this.cancelled || !data.length || deviceConn.destroyed) {
+                return;
+            }
+            if (this.hasPacketTap() && data.length >= IPV6_HEADER_SIZE) {
+                log.debug(`TUN → Device: ${data.length} bytes, IPv6 src=${formatIPv6Address(data.subarray(8, 24))}, dst=${formatIPv6Address(data.subarray(24, 40))}`);
+            }
+            else if (this.hasPacketTap()) {
+                log.debug(`TUN → Device: ${data.length} bytes (too small for IPv6 header)`);
+            }
+            deviceConn.write(data);
+        }, this.mtu);
     }
     async _performStop() {
         const tunName = this.tun ? this.tun.name : 'unknown';
         log.debug(`Stopping tunnel manager for ${tunName}`);
         // Signal cancellation
         this.cancelled = true;
-        // Clear read interval
-        if (this.readInterval) {
-            clearInterval(this.readInterval);
-            this.readInterval = null;
-        }
         // Close device connection if exists
         if (this.deviceConn && !this.deviceConn.destroyed) {
             this.deviceConn.destroy();
@@ -369,81 +305,14 @@ export class TunnelManager extends EventEmitter {
  * @returns parsed tunnel parameters from the device response
  */
 export async function exchangeCoreTunnelParameters(socket) {
-    return new Promise((resolve, reject) => {
-        const request = {
-            type: 'clientHandshakeRequest',
-            mtu: 16000,
-        };
-        const requestJSON = JSON.stringify(request);
-        const jsonBuffer = Buffer.from(requestJSON);
-        const magic = Buffer.from('CDTunnel');
-        const length = Buffer.alloc(2);
-        length.writeUInt16BE(jsonBuffer.length);
-        const message = Buffer.concat([magic, length, jsonBuffer]);
-        log.debug(`Sending CDTunnel packet: magic=${magic.toString()}, length=${jsonBuffer.length}, body=${requestJSON}`);
-        socket.write(message);
-        // For receiving the response
-        let buffer = Buffer.alloc(0);
-        function cleanup() {
-            socket.removeListener('data', handleData);
-            socket.removeListener('error', handleError);
-            socket.removeListener('end', handleEnd);
-            if (timeoutHandle) {
-                clearTimeout(timeoutHandle);
-            }
-        }
-        function handleData(data) {
-            log.debug('Received data chunk:', data.length, 'bytes');
-            buffer = Buffer.concat([buffer, data]);
-            if (buffer.length < 10) {
-                return;
-            }
-            const receivedMagic = buffer.slice(0, 8).toString();
-            if (receivedMagic !== 'CDTunnel') {
-                log.error('Invalid magic header:', receivedMagic);
-                cleanup();
-                return reject(new Error('Invalid packet format'));
-            }
-            const payloadLength = buffer.readUInt16BE(8);
-            const totalLength = 8 + 2 + payloadLength;
-            log.debug('Expected total packet length:', totalLength, 'current buffer:', buffer.length);
-            if (buffer.length >= totalLength) {
-                const payload = buffer.slice(10, totalLength);
-                try {
-                    const response = JSON.parse(payload.toString());
-                    log.debug('Parsed CDTunnel response:', response);
-                    cleanup();
-                    resolve(response);
-                }
-                catch (err) {
-                    log.error('Failed to parse JSON:', err);
-                    cleanup();
-                    reject(new Error('Invalid JSON response'));
-                }
-            }
-        }
-        function handleError(err) {
-            log.error('Socket error:', err);
-            cleanup();
-            reject(err);
-        }
-        function handleEnd() {
-            log.debug('Connection ended');
-            if (buffer.length > 0) {
-                log.debug('Buffer at end:', buffer.toString('hex'));
-            }
-            cleanup();
-            reject(new Error('Connection closed before receiving complete response'));
-        }
-        // Set a timeout for the handshake
-        const timeoutHandle = setTimeout(() => {
-            cleanup();
-            reject(new Error('Tunnel handshake timeout'));
-        }, 30000); // 30 second timeout
-        socket.on('data', handleData);
-        socket.on('error', handleError);
-        socket.on('end', handleEnd);
+    const requestJson = JSON.stringify({
+        type: 'clientHandshakeRequest',
+        mtu: CD_TUNNEL_MTU,
     });
+    const message = encodeCdTunnelMessage(requestJson);
+    log.debug(`Sending CDTunnel packet: magic=${CD_TUNNEL_MAGIC}, length=${message.length - CD_TUNNEL_HEADER_SIZE}, body=${requestJson}`);
+    socket.write(message);
+    return readCdTunnelResponse(socket, CD_TUNNEL_HANDSHAKE_TIMEOUT_MS);
 }
 /**
  * End-to-end setup: handshake, TUN configuration, route, and forwarding on `secureServiceSocket`.
@@ -489,6 +358,144 @@ export async function connectToTunnelLockdown(secureServiceSocket) {
         throw err;
     }
 }
+function encodeCdTunnelMessage(json) {
+    const body = Buffer.from(json);
+    const header = Buffer.alloc(CD_TUNNEL_HEADER_SIZE);
+    header.write(CD_TUNNEL_MAGIC, 0, CD_TUNNEL_MAGIC_SIZE, 'ascii');
+    header.writeUInt16BE(body.length, CD_TUNNEL_MAGIC_SIZE);
+    return Buffer.concat([header, body]);
+}
+function tryParseCdTunnelResponse(buffer) {
+    if (buffer.length < CD_TUNNEL_HEADER_SIZE) {
+        return { kind: 'incomplete' };
+    }
+    const magic = buffer.subarray(0, CD_TUNNEL_MAGIC_SIZE).toString();
+    if (magic !== CD_TUNNEL_MAGIC) {
+        log.error('Invalid magic header:', magic);
+        return { kind: 'error', error: new Error('Invalid packet format') };
+    }
+    const payloadLength = buffer.readUInt16BE(CD_TUNNEL_MAGIC_SIZE);
+    const totalLength = CD_TUNNEL_HEADER_SIZE + payloadLength;
+    if (buffer.length < totalLength) {
+        return { kind: 'incomplete' };
+    }
+    try {
+        const value = JSON.parse(buffer.subarray(CD_TUNNEL_HEADER_SIZE, totalLength).toString());
+        return { kind: 'ok', value };
+    }
+    catch (err) {
+        log.error('Failed to parse JSON:', err);
+        return { kind: 'error', error: new Error('Invalid JSON response') };
+    }
+}
+function readCdTunnelResponse(socket, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let buffer = Buffer.alloc(0);
+        const cleanup = () => {
+            socket.removeListener('data', onData);
+            socket.removeListener('error', onError);
+            socket.removeListener('end', onEnd);
+            clearTimeout(timeoutHandle);
+        };
+        const finish = (action) => {
+            cleanup();
+            action();
+        };
+        const onData = (chunk) => {
+            log.debug('Received data chunk:', chunk.length, 'bytes');
+            buffer = appendBuffer(buffer, chunk);
+            if (buffer.length >= CD_TUNNEL_HEADER_SIZE) {
+                const payloadLength = buffer.readUInt16BE(CD_TUNNEL_MAGIC_SIZE);
+                log.debug('Expected total packet length:', CD_TUNNEL_HEADER_SIZE + payloadLength, 'current buffer:', buffer.length);
+            }
+            const result = tryParseCdTunnelResponse(buffer);
+            if (result.kind === 'incomplete') {
+                return;
+            }
+            if (result.kind === 'error') {
+                finish(() => reject(result.error));
+                return;
+            }
+            log.debug('Parsed CDTunnel response:', result.value);
+            finish(() => resolve(result.value));
+        };
+        const onError = (err) => {
+            log.error('Socket error:', err);
+            finish(() => reject(err));
+        };
+        const onEnd = () => {
+            log.debug('Connection ended');
+            if (buffer.length > 0) {
+                log.debug('Buffer at end:', buffer.toString('hex'));
+            }
+            finish(() => reject(new Error('Connection closed before receiving complete response')));
+        };
+        const timeoutHandle = setTimeout(() => {
+            finish(() => reject(new Error('Tunnel handshake timeout')));
+        }, timeoutMs);
+        socket.on('data', onData);
+        socket.on('error', onError);
+        socket.on('end', onEnd);
+    });
+}
+function nextIpv6Frame(buffer, offset) {
+    if (offset + IPV6_HEADER_SIZE > buffer.length) {
+        return { kind: 'incomplete' };
+    }
+    const header = buffer.subarray(offset, offset + IPV6_HEADER_SIZE);
+    if (((header[0] >> 4) & 0x0f) !== IPV6_VERSION) {
+        return { kind: 'resync' };
+    }
+    const payloadLength = header.readUInt16BE(4);
+    const length = IPV6_HEADER_SIZE + payloadLength;
+    if (offset + length > buffer.length) {
+        return { kind: 'incomplete' };
+    }
+    return {
+        kind: 'frame',
+        packet: buffer.subarray(offset, offset + length),
+        nextHeader: header[6],
+        length,
+    };
+}
+function ipv6Endpoints(packet) {
+    return {
+        src: formatIPv6Address(packet.subarray(8, 24)),
+        dst: formatIPv6Address(packet.subarray(24, 40)),
+    };
+}
+function parseUdpPacketData(packet, src, dst) {
+    const payload = packet.subarray(IPV6_HEADER_SIZE);
+    if (payload.length < 8) {
+        return null;
+    }
+    return {
+        protocol: 'UDP',
+        src,
+        dst,
+        sourcePort: payload.readUInt16BE(0),
+        destPort: payload.readUInt16BE(2),
+        payload: payload.subarray(8),
+    };
+}
+function parseTcpPacketData(packet, src, dst) {
+    const tcpStart = IPV6_HEADER_SIZE;
+    if (packet.length < tcpStart + 20) {
+        return null;
+    }
+    const tcpHeaderLength = (packet.readUInt8(tcpStart + 12) >> 4) * 4;
+    if (packet.length < tcpStart + tcpHeaderLength) {
+        return null;
+    }
+    return {
+        protocol: 'TCP',
+        src,
+        dst,
+        sourcePort: packet.readUInt16BE(tcpStart),
+        destPort: packet.readUInt16BE(tcpStart + 2),
+        payload: packet.subarray(tcpStart + tcpHeaderLength),
+    };
+}
 function formatIPv6Address(buffer) {
     if (!buffer || buffer.length !== 16) {
         return 'invalid-address';

package/lib/tunnel/types.d.ts

@@ -0,0 +1,71 @@
+import type { Buffer } from 'node:buffer';
+import type { TunnelManager } from './manager.js';
+export interface PacketData {
+    protocol: 'TCP' | 'UDP';
+    src: string;
+    dst: string;
+    sourcePort: number;
+    destPort: number;
+    payload: Buffer;
+}
+/**
+ * Event names and listener argument tuples for {@link TunnelManager}
+ * (matches Node’s `EventEmitter` event map shape).
+ *
+ * @example
+ * tunnelManager.on('data', (packet) => {
+ *   // `packet` is PacketData
+ * });
+ */
+export interface PacketConsumer {
+    /**
+     * Invoked for each parsed TCP/UDP payload extracted from the tunnel stream.
+     *
+     * @param packet — decoded addresses, ports, and payload
+     */
+    onPacket(packet: PacketData): void;
+}
+export interface TunnelManagerEvents {
+    data: [packet: PacketData];
+}
+export interface TunnelConnection {
+    Address: string;
+    RsdPort?: number;
+    tunnelManager: TunnelManager;
+    /** Tear down the tunnel, close the TUN device, and end the socket when appropriate. */
+    closer: () => Promise<void>;
+    /** @param consumer — receives packets for the lifetime of the registration */
+    addPacketConsumer(consumer: PacketConsumer): void;
+    /** @param consumer — must be the same reference passed to {@link TunnelConnection.addPacketConsumer} */
+    removePacketConsumer(consumer: PacketConsumer): void;
+    /** @returns async iterator of packets until the tunnel is stopped */
+    getPacketStream(): AsyncIterable<PacketData>;
+}
+export interface TunnelClientParameters {
+    address: string;
+    mtu: number;
+}
+export interface TunnelInfo {
+    clientParameters: TunnelClientParameters;
+    serverAddress: string;
+    serverRSDPort?: number;
+}
+export type Ipv6Frame = {
+    kind: 'frame';
+    packet: Buffer;
+    nextHeader: number;
+    length: number;
+} | {
+    kind: 'incomplete';
+} | {
+    kind: 'resync';
+};
+export type CdTunnelParseResult = {
+    kind: 'incomplete';
+} | {
+    kind: 'ok';
+    value: TunnelInfo;
+} | {
+    kind: 'error';
+    error: Error;
+};

package/lib/tunnel/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-tuntap",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Native TUN/TAP interface module for Node.js",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -49,7 +49,7 @@
   "license": "Apache-2.0",
   "gypfile": true,
   "dependencies": {
-    "@appium/support": "^7.0.0-rc.1",
+    "@appium/support": "^7.2.0",
     "node-addon-api": "^8.5.0",
     "node-gyp-build": "^4.8.4",
     "typescript": "^6.0.2"

package/src/native/posix_uv_poll_loop.cc

@@ -96,24 +96,27 @@ void PosixUvPollLoop::OnPoll(uv_poll_t* handle, int status, int events) {
     return;
   }
 
-  std::vector<uint8_t> packet;
-  std::string error;
-  ReadPacketStatus rs = state->read_fn(state->buffer_size, packet, error);
-
-  switch (rs) {
-    case ReadPacketStatus::Data:
-      if (state->on_packet) {
-        state->on_packet(std::move(packet));
-      }
-      return;
-    case ReadPacketStatus::NoData:
-      return;
-    case ReadPacketStatus::Closed:
-      handle_terminal("Device closed");
-      return;
-    case ReadPacketStatus::Error:
-      handle_terminal(error);
-      return;
+  // Drain all readable packets before returning to libuv (match WinTun worker).
+  while (true) {
+    std::vector<uint8_t> packet;
+    std::string error;
+    ReadPacketStatus rs = state->read_fn(state->buffer_size, packet, error);
+
+    switch (rs) {
+      case ReadPacketStatus::Data:
+        if (state->on_packet) {
+          state->on_packet(std::move(packet));
+        }
+        break;
+      case ReadPacketStatus::NoData:
+        return;
+      case ReadPacketStatus::Closed:
+        handle_terminal("Device closed");
+        return;
+      case ReadPacketStatus::Error:
+        handle_terminal(error);
+        return;
+    }
   }
 }
 

package/src/native/tun_backend_darwin.cc

@@ -91,8 +91,11 @@ public:
       return ReadPacketStatus::Error;
     }
 
-    out.resize(max_payload_size + kUtunHeaderSize);
-    ssize_t bytes_read = read(fd_.get(), out.data(), out.size());
+    const size_t read_cap = max_payload_size + kUtunHeaderSize;
+    if (read_frame_.size() < read_cap) {
+      read_frame_.resize(read_cap);
+    }
+    ssize_t bytes_read = read(fd_.get(), read_frame_.data(), read_cap);
     if (bytes_read < 0) {
       if (errno == EAGAIN || errno == EWOULDBLOCK) {
         out.clear();
@@ -111,9 +114,8 @@ public:
     }
 
     const auto payload_len = static_cast<size_t>(bytes_read - kUtunHeaderSize);
-    // Collapse the utun 4-byte address-family prefix in-place.
-    memmove(out.data(), out.data() + kUtunHeaderSize, payload_len);
     out.resize(payload_len);
+    memcpy(out.data(), read_frame_.data() + kUtunHeaderSize, payload_len);
     return ReadPacketStatus::Data;
   }
 
@@ -125,12 +127,12 @@ public:
       return -1;
     }
 
-    std::vector<uint8_t> frame(length + kUtunHeaderSize);
+    write_frame_.resize(length + kUtunHeaderSize);
     uint32_t family = htonl(AF_INET6);
-    memcpy(frame.data(), &family, kUtunHeaderSize);
-    memcpy(frame.data() + kUtunHeaderSize, data, length);
+    memcpy(write_frame_.data(), &family, kUtunHeaderSize);
+    memcpy(write_frame_.data() + kUtunHeaderSize, data, length);
 
-    ssize_t bytes_written = write(fd_.get(), frame.data(), frame.size());
+    ssize_t bytes_written = write(fd_.get(), write_frame_.data(), write_frame_.size());
     if (bytes_written < 0) {
       error = std::string("Write error: ") + strerror(errno);
       return -1;
@@ -167,6 +169,9 @@ private:
     error = "Could not find an available utun device";
     return false;
   }
+
+  std::vector<uint8_t> read_frame_;
+  std::vector<uint8_t> write_frame_;
 };
 
 } // namespace

package/src/tuntap.cc

@@ -209,12 +209,14 @@ Napi::Value TunDevice::StartPolling(const Napi::CallbackInfo& info) {
     buffer_size = size;
   }
 
+  // Queue depth > 1 lets the poll thread post the next packet while JS is still
+  // handling the previous callback (still serialized on the main thread).
   tsfn_ = Napi::ThreadSafeFunction::New(
       env,
       info[0].As<Napi::Function>(),
       "TunDeviceDataCallback",
       0,
-      1);
+      8);
 
   uv_loop_t* loop = nullptr;
   napi_status napi_st = napi_get_uv_event_loop(env, &loop);
@@ -227,11 +229,18 @@ Napi::Value TunDevice::StartPolling(const Napi::CallbackInfo& info) {
   Napi::ThreadSafeFunction tsfn = tsfn_;
   auto packet_cb = [tsfn](std::vector<uint8_t> packet) mutable {
     tsfn.BlockingCall(
-        [packet = std::move(packet)](Napi::Env env, Napi::Function jsCallback) {
+        [packet = std::move(packet)](Napi::Env env, Napi::Function jsCallback) mutable {
           if (env == nullptr || jsCallback.IsEmpty()) {
             return;
           }
-          jsCallback.Call({Napi::Buffer<uint8_t>::Copy(env, packet.data(), packet.size())});
+          auto* backing = new std::vector<uint8_t>(std::move(packet));
+          Napi::Buffer<uint8_t> buf = Napi::Buffer<uint8_t>::New(
+              env,
+              backing->data(),
+              backing->size(),
+              [](Napi::Env, uint8_t*, std::vector<uint8_t>* vec) { delete vec; },
+              backing);
+          jsCallback.Call({buf});
         });
   };
   // Terminal errors from the receive loop (poll error, device closed, read