appium-ios-tuntap 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.5.0](https://github.com/appium/appium-ios-tuntap/compare/v0.4.4...v0.5.0) (2026-06-13)
+
+### Features
+
+* Switch to a different tunnelling architecture ([#51](https://github.com/appium/appium-ios-tuntap/issues/51)) ([7267755](https://github.com/appium/appium-ios-tuntap/commit/726775526d50d1976192bf3ebfbae6cb81883631))
+
+## [0.4.4](https://github.com/appium/appium-ios-tuntap/compare/v0.4.3...v0.4.4) (2026-06-12)
+
+### Bug Fixes
+
+* Update tunnel backpressure handling ([#50](https://github.com/appium/appium-ios-tuntap/issues/50)) ([28b8bce](https://github.com/appium/appium-ios-tuntap/commit/28b8bce8edcf2a0446a653bbec759e6b4a199827))
+
 ## [0.4.3](https://github.com/appium/appium-ios-tuntap/compare/v0.4.2...v0.4.3) (2026-06-10)
 
 ### Bug Fixes

package/README.md

@@ -272,13 +272,13 @@ Most tests for this module require **root privileges** (sudo) to create and mana
 From the project root, run:
 
 ```sh
-sudo npx mocha test/tuntap-unit.spec.js
+sudo npm run test:unit
 ```
 
-Or, to run all tests in the `test/` directory:
+Or, to run all tests:
 
 ```sh
-sudo npx mocha
+sudo npm test
 ```
 
 If you are **not** running as root, you will see a message that tests are skipped.

package/lib/platform/windows.js

@@ -1,5 +1,6 @@
 import { TunTapError } from '../errors.js';
 import { log } from '../logger.js';
+import { tunDebug } from '../tunnel/debug-log.js';
 import { assertAdminOnWindows } from './require-admin.js';
 import { execFileAsync } from './exec.js';
 /** Tightly-restricted character set for adapter names passed into PowerShell. */
@@ -19,7 +20,7 @@ export class WindowsTunTapPlatform {
     async configure(interfaceName, address, mtu) {
         await assertAdminOnWindows();
         assertSafeAdapterName(interfaceName);
-        log.debug(`[win] configure: interface=${interfaceName} address=${address} mtu=${mtu}`);
+        tunDebug(`[win] configure: interface=${interfaceName} address=${address} mtu=${mtu}`);
         await addIpv6Address(interfaceName, address);
         await setIpv6Mtu(interfaceName, mtu);
     }
@@ -27,7 +28,7 @@ export class WindowsTunTapPlatform {
     async addRoute(interfaceName, destination) {
         await assertAdminOnWindows();
         assertSafeAdapterName(interfaceName);
-        log.debug(`[win] addRoute: interface=${interfaceName} destination=${destination}`);
+        tunDebug(`[win] addRoute: interface=${interfaceName} destination=${destination}`);
         await addIpv6Route(interfaceName, destination);
         // WinTun presents as an Ethernet adapter, so Windows requires Neighbor
         // Discovery (NDP) before it will send packets through the interface.
@@ -102,7 +103,7 @@ async function addIpv6Address(interfaceName, address) {
             `address=${address}/64`,
             'store=active',
         ]);
-        log.debug(`[win] add address ok: ${r.stdout.trim() || '(no output)'}`);
+        tunDebug(`[win] add address ok: ${r.stdout.trim() || '(no output)'}`);
     }
     catch (err) {
         const message = err.message ?? '';
@@ -124,7 +125,7 @@ async function setIpv6Mtu(interfaceName, mtu) {
             `mtu=${mtu}`,
             'store=active',
         ]);
-        log.debug(`[win] set mtu ok: ${r.stdout.trim() || '(no output)'}`);
+        tunDebug(`[win] set mtu ok: ${r.stdout.trim() || '(no output)'}`);
     }
     catch (err) {
         log.warn(`[win] set mtu err: ${err.message ?? err}`);
@@ -142,13 +143,13 @@ async function addIpv6Route(interfaceName, destination) {
             interfaceName,
             'store=active',
         ]);
-        log.debug(`[win] add route ok: ${r.stdout.trim() || '(no output)'}`);
+        tunDebug(`[win] add route ok: ${r.stdout.trim() || '(no output)'}`);
     }
     catch (err) {
         const message = err.message ?? '';
         log.warn(`[win] add route err: ${message}`);
         if (/already exists|object already/i.test(message)) {
-            log.debug(`Route to ${destination} already exists`);
+            tunDebug(`Route to ${destination} already exists`);
             return;
         }
         throw err;
@@ -174,7 +175,7 @@ async function deleteIpv6Route(interfaceName, destination) {
     }
 }
 async function addStaticNeighbor(interfaceName, address) {
-    log.debug(`[win] addStaticNeighbor: interface=${interfaceName} address=${address}`);
+    tunDebug(`[win] addStaticNeighbor: interface=${interfaceName} address=${address}`);
     try {
         const r = await execFileAsync('netsh', [
             'interface',
@@ -186,7 +187,7 @@ async function addStaticNeighbor(interfaceName, address) {
             '00-00-00-00-00-01',
             'store=active',
         ]);
-        log.debug(`[win] add neighbor ok: ${r.stdout.trim() || '(no output)'}`);
+        tunDebug(`[win] add neighbor ok: ${r.stdout.trim() || '(no output)'}`);
     }
     catch (err) {
         const msg = err.message ?? String(err);

package/lib/tunnel/constants.d.ts

@@ -6,12 +6,22 @@ export declare const MAX_TUN_POLL_BUFFER = 65535;
 export declare const LARGE_TUN_POLL_BUFFER: number;
 /** Default ThreadSafeFunction queue depth for TUN polling. */
 export declare const DEFAULT_TUN_POLL_QUEUE_DEPTH = 8;
-/** Deeper TSFN queue when packet tap is off (bulk transfer). */
-export declare const FAST_TUN_POLL_QUEUE_DEPTH = 16;
+/** One in-flight TUN read for sequential pump forwarding. */
+export declare const SEQUENTIAL_TUN_POLL_QUEUE_DEPTH = 1;
+/** Max utun packets buffered on the JS side before TLS write. */
+export declare const MAX_TUN_INGRESS_QUEUE = 256;
+/** Max ThreadSafeFunction queue depth (native addon limit). */
+export declare const MAX_TUN_POLL_TSFN_QUEUE_DEPTH = 64;
+/** ThreadSafeFunction queue depth passed to {@link TunTap.startPolling}. */
+export declare const TUN_POLL_TSFN_QUEUE_DEPTH = 64;
+/** Yield device→TUN loop periodically so utun poll callbacks can run. */
+export declare const DEVICE_PUMP_YIELD_EVERY_FRAMES = 64;
 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;
+/** Pause device ingress when the reassembly buffer exceeds this size. */
+export declare const MAX_DEVICE_INGRESS_BUFFER: number;
 export declare const IPV6_HEADER_SIZE = 40;
 export declare const IPV6_VERSION = 6;
 export declare const IPPROTO_TCP = 6;

package/lib/tunnel/constants.js

@@ -6,12 +6,22 @@ export const MAX_TUN_POLL_BUFFER = 65_535;
 export const LARGE_TUN_POLL_BUFFER = 64 * 1024;
 /** Default ThreadSafeFunction queue depth for TUN polling. */
 export const DEFAULT_TUN_POLL_QUEUE_DEPTH = 8;
-/** Deeper TSFN queue when packet tap is off (bulk transfer). */
-export const FAST_TUN_POLL_QUEUE_DEPTH = 16;
+/** One in-flight TUN read for sequential pump forwarding. */
+export const SEQUENTIAL_TUN_POLL_QUEUE_DEPTH = 1;
+/** Max utun packets buffered on the JS side before TLS write. */
+export const MAX_TUN_INGRESS_QUEUE = 256;
+/** Max ThreadSafeFunction queue depth (native addon limit). */
+export const MAX_TUN_POLL_TSFN_QUEUE_DEPTH = 64;
+/** ThreadSafeFunction queue depth passed to {@link TunTap.startPolling}. */
+export const TUN_POLL_TSFN_QUEUE_DEPTH = MAX_TUN_POLL_TSFN_QUEUE_DEPTH;
+/** Yield device→TUN loop periodically so utun poll callbacks can run. */
+export const DEVICE_PUMP_YIELD_EVERY_FRAMES = 64;
 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;
+/** Pause device ingress when the reassembly buffer exceeds this size. */
+export const MAX_DEVICE_INGRESS_BUFFER = 8 * 1024 * 1024;
 export const IPV6_HEADER_SIZE = 40;
 export const IPV6_VERSION = 6;
 export const IPPROTO_TCP = 6;

package/lib/tunnel/debug-log.d.ts

@@ -0,0 +1,12 @@
+import { log } from '../logger.js';
+/** Tunnel debug logging — set APPIUM_TUNTAP_DEBUG=1 on the tunnel process. */
+export declare const APPIUM_TUNTAP_DEBUG: boolean;
+/** {@link log.debug} when {@link APPIUM_TUNTAP_DEBUG} is enabled. */
+export declare function tunDebug(...args: Parameters<typeof log.debug>): void;
+/** Log a numbered tunnel forward diagnostic when {@link APPIUM_TUNTAP_DEBUG} is enabled. */
+export declare function fwdDebug(event: string, detail?: Record<string, string | number | boolean>): void;
+/** Summarize reassembly buffer state for debug logs. */
+export declare function fwdBufferState(buffer: Buffer): {
+    buf: number;
+    tailKind: string;
+};

package/lib/tunnel/debug-log.js

@@ -0,0 +1,44 @@
+import { log } from '../logger.js';
+/** Tunnel debug logging — set APPIUM_TUNTAP_DEBUG=1 on the tunnel process. */
+export const APPIUM_TUNTAP_DEBUG = process.env.APPIUM_TUNTAP_DEBUG === '1' || process.env.APPIUM_TUNTAP_DEBUG === 'true';
+let seq = 0;
+/** {@link log.debug} when {@link APPIUM_TUNTAP_DEBUG} is enabled. */
+export function tunDebug(...args) {
+    if (!APPIUM_TUNTAP_DEBUG) {
+        return;
+    }
+    log.debug(...args);
+}
+/** Log a numbered tunnel forward diagnostic when {@link APPIUM_TUNTAP_DEBUG} is enabled. */
+export function fwdDebug(event, detail) {
+    if (!APPIUM_TUNTAP_DEBUG) {
+        return;
+    }
+    seq += 1;
+    const parts = [`#${seq}`, event];
+    if (detail) {
+        for (const [key, value] of Object.entries(detail)) {
+            parts.push(`${key}=${value}`);
+        }
+    }
+    log.info(`[fwd] ${parts.join(' ')}`);
+}
+/** Summarize reassembly buffer state for debug logs. */
+export function fwdBufferState(buffer) {
+    if (buffer.length === 0) {
+        return { buf: 0, tailKind: 'empty' };
+    }
+    if (buffer.length < 40) {
+        return { buf: buffer.length, tailKind: 'short' };
+    }
+    const version = (buffer[0] >> 4) & 0x0f;
+    if (version !== 6) {
+        return { buf: buffer.length, tailKind: 'resync-needed' };
+    }
+    const payloadLength = buffer.readUInt16BE(4);
+    const frameLength = 40 + payloadLength;
+    if (buffer.length >= frameLength) {
+        return { buf: buffer.length, tailKind: 'has-complete-frame' };
+    }
+    return { buf: buffer.length, tailKind: 'incomplete-tail' };
+}

package/lib/tunnel/device-to-tun-pump.d.ts

@@ -0,0 +1,36 @@
+import type { Socket } from 'node:net';
+import type { TunTap } from '../TunTap.js';
+export type DeviceToTunProgressHook = () => void;
+/**
+ * Device→TUN forwarding: read one exact IPv6 frame from the socket, write to TUN,
+ * repeat. Yields only when TUN write blocks (via notifyTunWritable from the TUN→device pump).
+ */
+export declare class DeviceToTunPump {
+    private readonly onFrameWritten?;
+    private cancelled;
+    private running;
+    private buffer;
+    private frameWaiter;
+    private frameReject;
+    private tunWritableWaiter;
+    private loopPromise;
+    private fwdFrames;
+    private deviceIngressPaused;
+    private deviceConn;
+    private pendingDeviceChunks;
+    private deviceDrainScheduled;
+    constructor(onFrameWritten?: DeviceToTunProgressHook | undefined);
+    start(deviceConn: Socket, tun: TunTap): void;
+    notifyTunWritable(): void;
+    stop(): Promise<void>;
+    private enqueueDeviceData;
+    private onDeviceData;
+    private maybeResumeDeviceIngress;
+    private tryDeliverFrame;
+    private readOneFrame;
+    private pauseDeviceIngress;
+    private resumeDeviceIngress;
+    private waitTunWritable;
+    private writeFrameToTun;
+    private runLoop;
+}

package/lib/tunnel/device-to-tun-pump.js

@@ -0,0 +1,229 @@
+import { Buffer } from 'node:buffer';
+import { appendBuffer } from './buffer-utils.js';
+import { fwdDebug } from './debug-log.js';
+import { IPV6_HEADER_SIZE, IPV6_VERSION, MAX_DEVICE_INGRESS_BUFFER, DEVICE_PUMP_YIELD_EVERY_FRAMES, } from './constants.js';
+/**
+ * Device→TUN forwarding: read one exact IPv6 frame from the socket, write to TUN,
+ * repeat. Yields only when TUN write blocks (via notifyTunWritable from the TUN→device pump).
+ */
+export class DeviceToTunPump {
+    onFrameWritten;
+    cancelled = false;
+    running = false;
+    buffer = Buffer.alloc(0);
+    frameWaiter = null;
+    frameReject = null;
+    tunWritableWaiter = null;
+    loopPromise = null;
+    fwdFrames = 0;
+    deviceIngressPaused = false;
+    deviceConn = null;
+    pendingDeviceChunks = [];
+    deviceDrainScheduled = false;
+    constructor(onFrameWritten) {
+        this.onFrameWritten = onFrameWritten;
+    }
+    start(deviceConn, tun) {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        this.cancelled = false;
+        this.deviceConn = deviceConn;
+        deviceConn.on('data', (chunk) => this.enqueueDeviceData(chunk));
+        fwdDebug('device-pump-start', {});
+        this.loopPromise = this.runLoop(deviceConn, tun);
+    }
+    notifyTunWritable() {
+        const waiter = this.tunWritableWaiter;
+        if (waiter) {
+            this.tunWritableWaiter = null;
+            waiter();
+        }
+    }
+    async stop() {
+        this.cancelled = true;
+        if (this.frameReject) {
+            this.frameReject(new Error(DEVICE_PUMP_CANCELLED));
+        }
+        if (this.tunWritableWaiter) {
+            this.tunWritableWaiter();
+        }
+        this.frameWaiter = null;
+        this.frameReject = null;
+        this.tunWritableWaiter = null;
+        if (this.loopPromise) {
+            await this.loopPromise.catch(() => undefined);
+            this.loopPromise = null;
+        }
+        this.buffer = Buffer.alloc(0);
+        this.deviceConn = null;
+        this.running = false;
+    }
+    enqueueDeviceData(chunk) {
+        if (this.cancelled || chunk.length === 0) {
+            return;
+        }
+        this.pendingDeviceChunks.push(chunk);
+        if (this.deviceDrainScheduled) {
+            return;
+        }
+        this.deviceDrainScheduled = true;
+        setImmediate(() => {
+            this.deviceDrainScheduled = false;
+            const chunks = this.pendingDeviceChunks;
+            this.pendingDeviceChunks = [];
+            for (const pending of chunks) {
+                this.onDeviceData(pending);
+            }
+        });
+    }
+    onDeviceData(chunk) {
+        if (this.cancelled || chunk.length === 0) {
+            return;
+        }
+        this.buffer = appendBuffer(this.buffer, chunk);
+        if (this.deviceConn &&
+            this.buffer.length > MAX_DEVICE_INGRESS_BUFFER &&
+            !this.deviceIngressPaused) {
+            this.pauseDeviceIngress(this.deviceConn, 'max-buffer');
+        }
+        this.tryDeliverFrame();
+    }
+    maybeResumeDeviceIngress() {
+        if (!this.deviceConn ||
+            !this.deviceIngressPaused ||
+            this.buffer.length > MAX_DEVICE_INGRESS_BUFFER) {
+            return;
+        }
+        this.resumeDeviceIngress(this.deviceConn);
+    }
+    tryDeliverFrame() {
+        const waiter = this.frameWaiter;
+        if (!waiter) {
+            return;
+        }
+        const taken = takeOneIpv6Frame(this.buffer);
+        if (taken.kind === 'incomplete' || taken.kind === 'resync') {
+            if (taken.kind === 'resync') {
+                this.buffer = this.buffer.subarray(1);
+                this.tryDeliverFrame();
+            }
+            return;
+        }
+        this.buffer = shrinkBuffer(this.buffer, taken.length);
+        this.frameWaiter = null;
+        this.frameReject = null;
+        waiter(taken.packet);
+        this.maybeResumeDeviceIngress();
+    }
+    readOneFrame() {
+        if (this.cancelled) {
+            return Promise.reject(new Error(DEVICE_PUMP_CANCELLED));
+        }
+        const taken = takeOneIpv6Frame(this.buffer);
+        if (taken.kind === 'frame') {
+            this.buffer = shrinkBuffer(this.buffer, taken.length);
+            return Promise.resolve(taken.packet);
+        }
+        if (taken.kind === 'resync') {
+            this.buffer = this.buffer.subarray(1);
+            return this.readOneFrame();
+        }
+        return new Promise((resolve, reject) => {
+            this.frameWaiter = resolve;
+            this.frameReject = reject;
+        });
+    }
+    pauseDeviceIngress(deviceConn, reason) {
+        if (this.deviceIngressPaused || deviceConn.destroyed) {
+            return;
+        }
+        this.deviceIngressPaused = true;
+        deviceConn.pause();
+        fwdDebug('ingress-pause', { reason, buf: this.buffer.length });
+    }
+    resumeDeviceIngress(deviceConn) {
+        if (!this.deviceIngressPaused || deviceConn.destroyed) {
+            return;
+        }
+        this.deviceIngressPaused = false;
+        deviceConn.resume();
+        fwdDebug('ingress-resume', { buf: this.buffer.length });
+    }
+    waitTunWritable() {
+        if (this.cancelled) {
+            return Promise.reject(new Error(DEVICE_PUMP_CANCELLED));
+        }
+        return new Promise((resolve) => {
+            this.tunWritableWaiter = resolve;
+        });
+    }
+    async writeFrameToTun(deviceConn, tun, packet) {
+        while (!this.cancelled) {
+            const bytesWritten = tun.write(packet);
+            if (bytesWritten > 0) {
+                this.maybeResumeDeviceIngress();
+                return;
+            }
+            // Block on tun.write() without pausing the TLS stream — keep reading into the
+            // reassembly buffer while waiting for TUN→device progress to free utun capacity.
+            fwdDebug('tun-write-blocked', { frameLen: packet.length, buf: this.buffer.length });
+            await this.waitTunWritable();
+        }
+    }
+    async runLoop(deviceConn, tun) {
+        try {
+            while (!this.cancelled && !deviceConn.destroyed) {
+                const packet = await this.readOneFrame();
+                if (this.cancelled) {
+                    break;
+                }
+                await this.writeFrameToTun(deviceConn, tun, packet);
+                this.fwdFrames += 1;
+                if (this.fwdFrames === 1 || this.fwdFrames % 200 === 0) {
+                    fwdDebug('device-pump-write', { len: packet.length, frames: this.fwdFrames });
+                }
+                this.onFrameWritten?.();
+                if (this.fwdFrames % DEVICE_PUMP_YIELD_EVERY_FRAMES === 0) {
+                    await new Promise((resolve) => setImmediate(resolve));
+                }
+            }
+        }
+        catch (err) {
+            if (!isPumpCancelled(err)) {
+                throw err;
+            }
+        }
+        fwdDebug('device-pump-stop', { frames: this.fwdFrames });
+    }
+}
+const DEVICE_PUMP_CANCELLED = 'device pump cancelled';
+function isPumpCancelled(err) {
+    return err instanceof Error && err.message === DEVICE_PUMP_CANCELLED;
+}
+function takeOneIpv6Frame(buffer) {
+    if (buffer.length < IPV6_HEADER_SIZE) {
+        return { kind: 'incomplete' };
+    }
+    const version = (buffer[0] >> 4) & 0x0f;
+    if (version !== IPV6_VERSION) {
+        return { kind: 'resync' };
+    }
+    const payloadLength = buffer.readUInt16BE(4);
+    const length = IPV6_HEADER_SIZE + payloadLength;
+    if (buffer.length < length) {
+        return { kind: 'incomplete' };
+    }
+    return {
+        kind: 'frame',
+        packet: buffer.subarray(0, length),
+        length,
+    };
+}
+function shrinkBuffer(buffer, consumed) {
+    if (consumed >= buffer.length) {
+        return Buffer.alloc(0);
+    }
+    return buffer.subarray(consumed);
+}

package/lib/tunnel/manager.d.ts

@@ -14,7 +14,10 @@ export declare class TunnelManager extends EventEmitter<TunnelManagerEvents> {
     private readonly packetConsumers;
     private deviceConn;
     private cleanupPromise;
-    private tunReadPausedForBackpressure;
+    private tunToDevicePump;
+    private deviceToTunPump;
+    private deviceIngressPaused;
+    private fwdDeviceDataChunks;
     /**
      * Register a listener for parsed tunnel packets (in addition to the `data` event).
      *
@@ -57,12 +60,14 @@ export declare class TunnelManager extends EventEmitter<TunnelManagerEvents> {
      */
     stop(): Promise<void>;
     private hasPacketTap;
+    private pauseDeviceIngress;
+    private resumeDeviceIngress;
     private processBuffer;
     private writeDeviceFrameToTun;
     private tapL4Packet;
     private dispatchPacketData;
-    private startTunReadLoop;
-    private writeTunPacketToDevice;
+    private startDeviceToTunPump;
+    private startTunToDevicePump;
     private _performStop;
 }
 /**