appium-ios-tuntap 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

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,15 +6,23 @@ 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;
 export declare const IPPROTO_UDP = 17;
-/** Pause device ingress when the reassembly buffer exceeds this size. */
-export declare const MAX_DEVICE_INGRESS_BUFFER: number;

package/lib/tunnel/constants.js

@@ -6,15 +6,23 @@ 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;
 export const IPPROTO_UDP = 17;
-/** Pause device ingress when the reassembly buffer exceeds this size. */
-export const MAX_DEVICE_INGRESS_BUFFER = 8 * 1024 * 1024;

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

package/lib/tunnel/manager.js

@@ -2,8 +2,11 @@ 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, DEFAULT_TUN_POLL_QUEUE_DEPTH, FAST_TUN_POLL_QUEUE_DEPTH, IPV6_HEADER_SIZE, LARGE_TUN_POLL_BUFFER, MAX_DEVICE_INGRESS_BUFFER, MAX_TUN_POLL_BUFFER, IPV6_VERSION, IPPROTO_TCP, IPPROTO_UDP, } from './constants.js';
+import { CD_TUNNEL_HANDSHAKE_TIMEOUT_MS, CD_TUNNEL_HEADER_SIZE, CD_TUNNEL_MAGIC, CD_TUNNEL_MAGIC_SIZE, CD_TUNNEL_MTU, IPV6_HEADER_SIZE, MAX_DEVICE_INGRESS_BUFFER, IPV6_VERSION, IPPROTO_TCP, IPPROTO_UDP, } from './constants.js';
 import { appendBuffer } from './buffer-utils.js';
+import { fwdBufferState, fwdDebug, tunDebug } from './debug-log.js';
+import { TunToDevicePump } from './tun-to-device-pump.js';
+import { DeviceToTunPump } from './device-to-tun-pump.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.
@@ -16,8 +19,10 @@ export class TunnelManager extends EventEmitter {
     packetConsumers = new Set();
     deviceConn = null;
     cleanupPromise = null;
-    tunReadPausedForBackpressure = false;
-    deviceIngressPausedForTun = false;
+    tunToDevicePump = null;
+    deviceToTunPump = null;
+    deviceIngressPaused = false;
+    fwdDeviceDataChunks = 0;
     /**
      * Register a listener for parsed tunnel packets (in addition to the `data` event).
      *
@@ -82,20 +87,20 @@ export class TunnelManager extends EventEmitter {
      * @returns interface name, MTU, and the live {@link TunTap} instance
      */
     async setupInterface(tunnelInfo) {
-        log.debug(`Setting up tunnel with parameters:`, tunnelInfo);
+        tunDebug(`Setting up tunnel with parameters:`, tunnelInfo);
         try {
             this.tun = new TunTap();
             // Open the TUN device
             if (!this.tun.open()) {
                 throw new Error('Failed to open TUN device');
             }
-            log.debug(`Opened TUN device: ${this.tun.name}`);
+            tunDebug(`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
             await this.tun.addRoute(`${tunnelInfo.serverAddress}/128`);
-            log.debug(`Configured TUN interface ${this.tun.name} with address ${tunnelInfo.clientParameters.address} and MTU ${tunnelInfo.clientParameters.mtu}`);
+            tunDebug(`Configured TUN interface ${this.tun.name} with address ${tunnelInfo.clientParameters.address} and MTU ${tunnelInfo.clientParameters.mtu}`);
             return {
                 name: this.tun.name,
                 mtu: tunnelInfo.clientParameters.mtu,
@@ -127,32 +132,47 @@ export class TunnelManager extends EventEmitter {
             return;
         }
         this.deviceConn = deviceConn;
-        log.debug(`Starting bidirectional data forwarding for ${this.tun.name}`);
+        tunDebug(`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 {
-                this.buffer = appendBuffer(this.buffer, data);
-                if (this.buffer.length > MAX_DEVICE_INGRESS_BUFFER) {
-                    this.pauseDeviceIngress();
+        if (this.hasPacketTap()) {
+            deviceConn.on('data', (data) => {
+                if (this.cancelled) {
+                    return;
                 }
-                this.processBuffer();
-            }
-            catch (err) {
-                if (!this.cancelled) {
-                    log.error('Error processing device data:', err.message);
+                try {
+                    this.fwdDeviceDataChunks += 1;
+                    this.buffer = appendBuffer(this.buffer, data);
+                    if (this.buffer.length > MAX_DEVICE_INGRESS_BUFFER) {
+                        this.pauseDeviceIngress('max-buffer');
+                    }
+                    if (this.fwdDeviceDataChunks === 1 || this.fwdDeviceDataChunks % 200 === 0) {
+                        fwdDebug('device-data', {
+                            chunk: data.length,
+                            ...fwdBufferState(this.buffer),
+                            ingressPaused: this.deviceIngressPaused,
+                            chunks: this.fwdDeviceDataChunks,
+                        });
+                    }
+                    this.processBuffer('data');
                 }
-            }
+                catch (err) {
+                    if (!this.cancelled) {
+                        log.error('Error processing device data:', err.message);
+                    }
+                }
+            });
+        }
+        else {
+            this.startDeviceToTunPump(deviceConn);
+        }
+        deviceConn.on('drain', () => {
+            this.deviceToTunPump?.notifyTunWritable();
         });
-        // Set up TUN read loop
-        this.startTunReadLoop(deviceConn);
+        this.startTunToDevicePump(deviceConn);
         // Listen for device connection close
         deviceConn.on('close', async () => {
-            log.debug('Device connection closed, stopping tunnel');
+            tunDebug('Device connection closed, stopping tunnel');
             try {
                 await this.stop();
             }
@@ -180,8 +200,32 @@ export class TunnelManager extends EventEmitter {
     hasPacketTap() {
         return this.packetConsumers.size > 0 || this.listenerCount('data') > 0;
     }
-    processBuffer() {
+    pauseDeviceIngress(reason) {
+        if (this.deviceIngressPaused || !this.deviceConn || this.deviceConn.destroyed) {
+            return;
+        }
+        this.deviceIngressPaused = true;
+        this.deviceConn.pause();
+        fwdDebug('ingress-pause', {
+            reason,
+            ...fwdBufferState(this.buffer),
+        });
+    }
+    resumeDeviceIngress() {
+        if (!this.deviceIngressPaused || !this.deviceConn || this.deviceConn.destroyed) {
+            return;
+        }
+        this.deviceIngressPaused = false;
+        this.deviceConn.resume();
+        fwdDebug('ingress-resume', {
+            ...fwdBufferState(this.buffer),
+        });
+    }
+    processBuffer(trigger = 'unknown') {
         let offset = 0;
+        let tunWriteBlocked = false;
+        let framesWritten = 0;
+        const bufBefore = this.buffer.length;
         while (offset + IPV6_HEADER_SIZE <= this.buffer.length) {
             const frame = nextIpv6Frame(this.buffer, offset);
             if (frame.kind === 'incomplete') {
@@ -196,11 +240,22 @@ export class TunnelManager extends EventEmitter {
                 break;
             }
             try {
-                this.writeDeviceFrameToTun(this.tun, frame.packet, frame.nextHeader);
+                const bytesWritten = this.writeDeviceFrameToTun(this.tun, frame.packet, frame.nextHeader);
+                if (bytesWritten === 'blocked') {
+                    tunWriteBlocked = true;
+                    fwdDebug('tun-write-blocked', {
+                        trigger,
+                        frameLen: frame.length,
+                        ...fwdBufferState(this.buffer),
+                        ingressPaused: this.deviceIngressPaused,
+                    });
+                    break;
+                }
             }
             catch (err) {
                 log.error(`Error writing to TUN: ${err.message}`);
             }
+            framesWritten += 1;
             offset += frame.length;
         }
         if (offset > 0) {
@@ -211,62 +266,63 @@ export class TunnelManager extends EventEmitter {
                 this.buffer = this.buffer.subarray(offset);
             }
         }
-        if (this.deviceIngressPausedForTun && this.shouldResumeDeviceIngress()) {
-            this.resumeDeviceIngress();
+        if (this.deviceIngressPaused) {
+            const mayResume = !tunWriteBlocked &&
+                (this.buffer.length === 0 || this.buffer.length <= MAX_DEVICE_INGRESS_BUFFER / 2);
+            if (mayResume) {
+                this.resumeDeviceIngress();
+            }
+            else if (tunWriteBlocked || framesWritten > 0 || bufBefore > 0) {
+                fwdDebug('process-buffer', {
+                    trigger,
+                    bufBefore,
+                    bufAfter: this.buffer.length,
+                    offset,
+                    framesWritten,
+                    tunWriteBlocked,
+                    mayResume,
+                    ingressPaused: this.deviceIngressPaused,
+                    ...fwdBufferState(this.buffer),
+                });
+            }
         }
     }
     writeDeviceFrameToTun(tun, packet, nextHeader) {
-        tun.write(packet);
+        const bytesWritten = tun.write(packet);
+        if (bytesWritten <= 0) {
+            this.pauseDeviceIngress('tun-write-blocked');
+            return 'blocked';
+        }
         if (!this.hasPacketTap()) {
-            return;
+            return bytesWritten;
         }
         const { src, dst } = ipv6Endpoints(packet);
-        log.debug(`Device → TUN: ${packet.length} bytes, IPv6 src=${src}, dst=${dst}`);
+        tunDebug(`Device → TUN: ${bytesWritten} bytes, IPv6 src=${src}, dst=${dst}`);
         this.tapL4Packet(packet, nextHeader, src, dst);
-    }
-    shouldResumeDeviceIngress() {
-        if (this.buffer.length === 0) {
-            return true;
-        }
-        // All complete frames were written; waiting on more socket bytes to finish the tail frame.
-        return nextIpv6Frame(this.buffer, 0).kind === 'incomplete';
-    }
-    pauseDeviceIngress() {
-        if (this.deviceIngressPausedForTun || !this.deviceConn || this.deviceConn.destroyed) {
-            return;
-        }
-        this.deviceIngressPausedForTun = true;
-        this.deviceConn.pause();
-    }
-    resumeDeviceIngress() {
-        if (!this.deviceIngressPausedForTun || !this.deviceConn || this.deviceConn.destroyed) {
-            return;
-        }
-        this.deviceIngressPausedForTun = false;
-        this.deviceConn.resume();
+        return bytesWritten;
     }
     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.');
+                tunDebug('UDP payload too short, not emitting event.');
             }
             else {
-                log.debug(`UDP packet detected: payload length=${packetData.payload.length}`);
+                tunDebug(`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.');
+                tunDebug('TCP packet too short or malformed, skipping.');
             }
             else {
-                log.debug(`TCP packet detected: payload length=${packetData.payload.length}`);
+                tunDebug(`TCP packet detected: payload length=${packetData.payload.length}`);
             }
         }
         else {
-            log.debug('Packet is not UDP or TCP (nextHeader !== 17 and !== 6)');
+            tunDebug('Packet is not UDP or TCP (nextHeader !== 17 and !== 6)');
         }
         if (packetData) {
             this.dispatchPacketData(packetData);
@@ -282,54 +338,54 @@ export class TunnelManager extends EventEmitter {
                 log.error('Error in packet consumer:', err);
             }
         }
-        log.debug(`Emitted data event for ${packetData.protocol} packet`);
+        tunDebug(`Emitted data event for ${packetData.protocol} packet`);
     }
-    startTunReadLoop(deviceConn) {
+    startDeviceToTunPump(deviceConn) {
         if (!this.tun) {
             return;
         }
-        const tapOn = this.hasPacketTap();
-        const pollBuffer = tapOn
-            ? this.mtu
-            : Math.min(MAX_TUN_POLL_BUFFER, Math.max(this.mtu, LARGE_TUN_POLL_BUFFER));
-        const queueDepth = tapOn ? DEFAULT_TUN_POLL_QUEUE_DEPTH : FAST_TUN_POLL_QUEUE_DEPTH;
-        this.tun.startPolling((data) => {
-            if (this.cancelled || !data.length || deviceConn.destroyed) {
-                return;
-            }
-            if (tapOn && 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 (tapOn) {
-                log.debug(`TUN → Device: ${data.length} bytes (too small for IPv6 header)`);
-            }
-            this.writeTunPacketToDevice(deviceConn, data);
-        }, pollBuffer, queueDepth);
+        this.deviceToTunPump = new DeviceToTunPump();
+        this.deviceToTunPump.start(deviceConn, this.tun);
     }
-    writeTunPacketToDevice(deviceConn, data) {
-        if (deviceConn.destroyed) {
-            return;
-        }
-        const canWriteMore = deviceConn.write(data);
-        if (canWriteMore || this.tunReadPausedForBackpressure || !this.tun) {
+    startTunToDevicePump(deviceConn) {
+        if (!this.tun) {
             return;
         }
-        this.tunReadPausedForBackpressure = true;
-        this.tun.pausePolling();
-        const onDrain = () => {
-            if (this.cancelled || deviceConn.destroyed) {
-                return;
+        const tapOn = this.hasPacketTap();
+        this.tunToDevicePump = new TunToDevicePump(this.tun, this.mtu, tapOn
+            ? (data) => {
+                if (data.length >= IPV6_HEADER_SIZE) {
+                    tunDebug(`TUN → Device: ${data.length} bytes, IPv6 src=${formatIPv6Address(data.subarray(8, 24))}, dst=${formatIPv6Address(data.subarray(24, 40))}`);
+                }
+                else {
+                    tunDebug(`TUN → Device: ${data.length} bytes (too small for IPv6 header)`);
+                }
             }
-            this.tunReadPausedForBackpressure = false;
-            this.tun?.resumePolling();
-        };
-        deviceConn.once('drain', onDrain);
+            : undefined, () => {
+            this.deviceToTunPump?.notifyTunWritable();
+            if (this.deviceIngressPaused) {
+                fwdDebug('forward-progress', {
+                    ingressPaused: this.deviceIngressPaused,
+                    ...fwdBufferState(this.buffer),
+                });
+                this.processBuffer('forward-progress');
+            }
+        });
+        this.tunToDevicePump.start(deviceConn);
     }
     async _performStop() {
         const tunName = this.tun ? this.tun.name : 'unknown';
-        log.debug(`Stopping tunnel manager for ${tunName}`);
+        tunDebug(`Stopping tunnel manager for ${tunName}`);
         // Signal cancellation
         this.cancelled = true;
+        if (this.tunToDevicePump) {
+            await this.tunToDevicePump.stop();
+            this.tunToDevicePump = null;
+        }
+        if (this.deviceToTunPump) {
+            await this.deviceToTunPump.stop();
+            this.deviceToTunPump = null;
+        }
         // Close device connection if exists
         if (this.deviceConn && !this.deviceConn.destroyed) {
             this.deviceConn.destroy();
@@ -351,7 +407,7 @@ export class TunnelManager extends EventEmitter {
             }
             this.tun = null;
         }
-        log.debug(`Tunnel for ${tunName} closed successfully`);
+        tunDebug(`Tunnel for ${tunName} closed successfully`);
     }
 }
 /**
@@ -366,7 +422,7 @@ export async function exchangeCoreTunnelParameters(socket) {
         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}`);
+    tunDebug(`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);
 }
@@ -381,15 +437,15 @@ export async function connectToTunnelLockdown(secureServiceSocket) {
     try {
         // Exchange tunnel parameters with the device
         const tunnelInfo = await exchangeCoreTunnelParameters(secureServiceSocket);
-        log.debug('Tunnel parameters exchanged:', tunnelInfo);
+        tunDebug('Tunnel parameters exchanged:', tunnelInfo);
         // Setup tunnel interface
         const tunInterfaceInfo = await tunnelManager.setupInterface(tunnelInfo);
-        log.debug('Tunnel interface set up:', tunInterfaceInfo.name);
+        tunDebug('Tunnel interface set up:', tunInterfaceInfo.name);
         // Start bidirectional forwarding
         tunnelManager.startForwarding(secureServiceSocket);
         // Create close function
         const closeFunc = async () => {
-            log.debug('Closing tunnel connection');
+            tunDebug('Closing tunnel connection');
             await tunnelManager.stop();
             if (!secureServiceSocket.destroyed) {
                 secureServiceSocket.end();
@@ -458,11 +514,11 @@ function readCdTunnelResponse(socket, timeoutMs) {
             action();
         };
         const onData = (chunk) => {
-            log.debug('Received data chunk:', chunk.length, 'bytes');
+            tunDebug('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);
+                tunDebug('Expected total packet length:', CD_TUNNEL_HEADER_SIZE + payloadLength, 'current buffer:', buffer.length);
             }
             const result = tryParseCdTunnelResponse(buffer);
             if (result.kind === 'incomplete') {
@@ -472,7 +528,7 @@ function readCdTunnelResponse(socket, timeoutMs) {
                 finish(() => reject(result.error));
                 return;
             }
-            log.debug('Parsed CDTunnel response:', result.value);
+            tunDebug('Parsed CDTunnel response:', result.value);
             finish(() => resolve(result.value));
         };
         const onError = (err) => {
@@ -480,9 +536,9 @@ function readCdTunnelResponse(socket, timeoutMs) {
             finish(() => reject(err));
         };
         const onEnd = () => {
-            log.debug('Connection ended');
+            tunDebug('Connection ended');
             if (buffer.length > 0) {
-                log.debug('Buffer at end:', buffer.toString('hex'));
+                tunDebug('Buffer at end:', buffer.toString('hex'));
             }
             finish(() => reject(new Error('Connection closed before receiving complete response')));
         };

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

@@ -0,0 +1,30 @@
+import type { Socket } from 'node:net';
+import type { TunTap } from '../TunTap.js';
+export type TunToDeviceProgressHook = () => void;
+/**
+ * TUN→device forwarding: utun poll fills an ingress queue; a writer loop drains
+ * the queue to TLS with backpressure (await drain).
+ */
+export declare class TunToDevicePump {
+    private readonly tun;
+    private readonly mtu;
+    private readonly onPacketRead?;
+    private readonly onForwardProgress?;
+    private cancelled;
+    private running;
+    private tunIngressQueue;
+    private ingressWaiter;
+    private ingressReject;
+    private drainAbort;
+    private loopPromise;
+    private fwdPumpPackets;
+    constructor(tun: TunTap, mtu: number, onPacketRead?: ((data: Buffer) => void) | undefined, onForwardProgress?: TunToDeviceProgressHook | undefined);
+    start(deviceConn: Socket): void;
+    stop(): Promise<void>;
+    private onTunPollData;
+    private signalIngress;
+    private maybeResumeTunPolling;
+    private waitForIngress;
+    private writeAndDrain;
+    private runLoop;
+}

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

@@ -0,0 +1,166 @@
+import { once } from 'node:events';
+import { MAX_TUN_INGRESS_QUEUE, TUN_POLL_TSFN_QUEUE_DEPTH } from './constants.js';
+import { fwdDebug } from './debug-log.js';
+/**
+ * TUN→device forwarding: utun poll fills an ingress queue; a writer loop drains
+ * the queue to TLS with backpressure (await drain).
+ */
+export class TunToDevicePump {
+    tun;
+    mtu;
+    onPacketRead;
+    onForwardProgress;
+    cancelled = false;
+    running = false;
+    tunIngressQueue = [];
+    ingressWaiter = null;
+    ingressReject = null;
+    drainAbort = null;
+    loopPromise = null;
+    fwdPumpPackets = 0;
+    constructor(tun, mtu, onPacketRead, onForwardProgress) {
+        this.tun = tun;
+        this.mtu = mtu;
+        this.onPacketRead = onPacketRead;
+        this.onForwardProgress = onForwardProgress;
+    }
+    start(deviceConn) {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        this.cancelled = false;
+        this.tun.startPolling((data) => this.onTunPollData(data), this.mtu, TUN_POLL_TSFN_QUEUE_DEPTH);
+        this.tun.resumePolling();
+        fwdDebug('pump-start', { mtu: this.mtu, queueDepth: TUN_POLL_TSFN_QUEUE_DEPTH });
+        this.loopPromise = this.runLoop(deviceConn);
+    }
+    async stop() {
+        this.cancelled = true;
+        this.drainAbort?.abort();
+        this.drainAbort = null;
+        this.tun.pausePolling();
+        if (this.ingressReject) {
+            this.ingressReject(new Error(TUN_PUMP_CANCELLED));
+        }
+        else if (this.ingressWaiter) {
+            this.ingressWaiter();
+        }
+        this.ingressWaiter = null;
+        this.ingressReject = null;
+        this.tunIngressQueue = [];
+        if (this.loopPromise) {
+            await this.loopPromise.catch(() => undefined);
+            this.loopPromise = null;
+        }
+        this.running = false;
+    }
+    onTunPollData(data) {
+        if (this.cancelled || !data.length) {
+            return;
+        }
+        this.onPacketRead?.(data);
+        this.tunIngressQueue.push(data);
+        if (this.tunIngressQueue.length >= MAX_TUN_INGRESS_QUEUE) {
+            this.tun.pausePolling();
+            fwdDebug('tun-ingress-pause', { queued: this.tunIngressQueue.length });
+        }
+        this.signalIngress();
+    }
+    signalIngress() {
+        const waiter = this.ingressWaiter;
+        if (!waiter) {
+            return;
+        }
+        this.ingressWaiter = null;
+        this.ingressReject = null;
+        waiter();
+    }
+    maybeResumeTunPolling() {
+        if (this.tunIngressQueue.length < MAX_TUN_INGRESS_QUEUE) {
+            this.tun.resumePolling();
+        }
+    }
+    waitForIngress() {
+        if (this.cancelled) {
+            return Promise.reject(new Error(TUN_PUMP_CANCELLED));
+        }
+        if (this.tunIngressQueue.length > 0) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            this.ingressWaiter = resolve;
+            this.ingressReject = reject;
+        });
+    }
+    async writeAndDrain(deviceConn, data) {
+        if (deviceConn.destroyed) {
+            return;
+        }
+        const canWriteMore = deviceConn.write(data);
+        if (this.fwdPumpPackets === 1 || this.fwdPumpPackets % 200 === 0 || !canWriteMore) {
+            fwdDebug('pump-write', {
+                len: data.length,
+                canWriteMore,
+                writableLength: deviceConn.writableLength,
+                packets: this.fwdPumpPackets,
+            });
+        }
+        if (!canWriteMore || deviceConn.writableNeedDrain) {
+            this.onForwardProgress?.();
+            fwdDebug('pump-drain-wait', {
+                writableLength: deviceConn.writableLength,
+                len: data.length,
+                tunQueued: this.tunIngressQueue.length,
+            });
+            this.drainAbort = new AbortController();
+            try {
+                await once(deviceConn, 'drain', { signal: this.drainAbort.signal });
+            }
+            catch {
+                return;
+            }
+            finally {
+                this.drainAbort = null;
+            }
+            fwdDebug('pump-drain-done', {
+                writableLength: deviceConn.writableLength,
+                tunQueued: this.tunIngressQueue.length,
+            });
+        }
+        if (this.cancelled) {
+            return;
+        }
+        this.onForwardProgress?.();
+    }
+    async runLoop(deviceConn) {
+        try {
+            while (!this.cancelled && !deviceConn.destroyed) {
+                await this.waitForIngress();
+                while (this.tunIngressQueue.length > 0 && !this.cancelled && !deviceConn.destroyed) {
+                    const packet = this.tunIngressQueue.shift();
+                    if (!packet) {
+                        break;
+                    }
+                    this.maybeResumeTunPolling();
+                    this.fwdPumpPackets += 1;
+                    if (this.fwdPumpPackets === 1 || this.fwdPumpPackets % 200 === 0) {
+                        fwdDebug('pump-read', { len: packet.length, packets: this.fwdPumpPackets });
+                    }
+                    this.onForwardProgress?.();
+                    await this.writeAndDrain(deviceConn, packet);
+                }
+            }
+        }
+        catch (err) {
+            if (!isPumpCancelled(err)) {
+                throw err;
+            }
+        }
+        fwdDebug('pump-stop', { packets: this.fwdPumpPackets });
+    }
+}
+const TUN_PUMP_CANCELLED = 'pump cancelled';
+function isPumpCancelled(err) {
+    return err instanceof Error && err.message === TUN_PUMP_CANCELLED;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-tuntap",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Native TUN/TAP interface module for Node.js",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,8 +18,8 @@
     "refresh:wintun": "node scripts/fetch-wintun.mjs",
     "prepare": "npm run build",
     "test": "npm run test:integration && npm run test:unit",
-    "test:unit": "node --test --test-force-exit --test-timeout=120000 \"test/unit/**/*.spec.mjs\"",
-    "test:integration": "node --test --test-force-exit --test-timeout=120000 \"test/integration/**/*.spec.mjs\""
+    "test:unit": "node --test --test-force-exit --test-timeout=5000 \"test/unit/**/*.spec.mjs\"",
+    "test:integration": "node --test --test-force-exit --test-timeout=15000 \"test/integration/**/*.spec.mjs\""
   },
   "files": [
     "src/tuntap.cc",

package/src/native/posix_uv_poll_loop.cc

@@ -121,8 +121,8 @@ void PosixUvPollLoop::OnPoll(uv_poll_t* handle, int status, int events) {
 
     switch (rs) {
       case ReadPacketStatus::Data:
-        if (state->on_packet) {
-          state->on_packet(std::move(packet));
+        if (state->on_packet && !state->on_packet(std::move(packet))) {
+          return;
         }
         break;
       case ReadPacketStatus::NoData:

package/src/native/tun_backend.h

@@ -42,7 +42,7 @@ public:
   // background thread (libuv loop thread on POSIX, worker thread on Windows);
   // the caller in `tuntap.cc` is responsible for marshalling onto the JS
   // thread via `Napi::ThreadSafeFunction`.
-  using PacketCallback = std::function<void(std::vector<uint8_t>)>;
+  using PacketCallback = std::function<bool(std::vector<uint8_t>)>;
 
   // Invoked at most once when the receive loop encounters a fatal error and
   // stops. The receive loop must not deliver any further packets afterwards.

package/src/native/tun_backend_windows.cc

@@ -319,8 +319,8 @@ private:
                                       : static_cast<size_t>(packet_size);
           std::vector<uint8_t> data(packet, packet + copy_len);
           api.ReleaseReceivePacket(session_, packet);
-          if (on_packet) {
-            on_packet(std::move(data));
+          if (on_packet && !on_packet(std::move(data))) {
+            break;
           }
           continue;
         }

package/src/tuntap.cc

@@ -6,10 +6,74 @@
 #include <mutex>
 #include <string>
 #include <utility>
-#include <vector>
+#include <deque>
 
 #include "native/tun_backend.h"
 
+struct TunPollDispatch {
+  Napi::ThreadSafeFunction tsfn;
+  std::mutex mutex;
+  std::deque<std::vector<uint8_t>> pending;
+  static constexpr size_t MAX_PENDING = 512;
+
+  struct PacketJob {
+    TunPollDispatch* dispatch;
+    std::vector<uint8_t>* packet;
+  };
+
+  static void CallJs(Napi::Env env,
+                     Napi::Function jsCallback,
+                     TunPollDispatch* self,
+                     std::vector<uint8_t>* packet) {
+    if (env == nullptr || jsCallback.IsEmpty() || packet == nullptr) {
+      delete packet;
+      return;
+    }
+    auto* backing = 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});
+    if (self != nullptr) {
+      self->FlushPending();
+    }
+  }
+
+  void FlushPending() {
+    std::lock_guard<std::mutex> lock(mutex);
+    while (!pending.empty()) {
+      auto* packet = new std::vector<uint8_t>(std::move(pending.front()));
+      auto* job = new PacketJob{this, packet};
+      napi_status status = tsfn.NonBlockingCall(
+          job,
+          [](Napi::Env env, Napi::Function jsCallback, PacketJob* job) {
+            CallJs(env, jsCallback, job->dispatch, job->packet);
+            delete job;
+          });
+      if (status != napi_ok) {
+        delete packet;
+        delete job;
+        break;
+      }
+      pending.pop_front();
+    }
+  }
+
+  bool PostPacket(std::vector<uint8_t> packet) {
+    {
+      std::lock_guard<std::mutex> lock(mutex);
+      pending.push_back(std::move(packet));
+    }
+    FlushPending();
+    std::lock_guard<std::mutex> lock(mutex);
+    // Stop reading more from utun until JS drains the backlog.
+    return pending.size() < MAX_PENDING;
+  }
+};
+
 class TunDevice : public Napi::ObjectWrap<TunDevice> {
 public:
   static Napi::Object Init(Napi::Env env, Napi::Object exports);
@@ -38,6 +102,7 @@ private:
   std::mutex device_mutex_;
 
   Napi::ThreadSafeFunction tsfn_;
+  TunPollDispatch* poll_dispatch_ = nullptr;
   std::atomic<bool> polling_;
   static constexpr size_t MAX_POLL_BUFFER = 65535;
 
@@ -240,21 +305,11 @@ 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) mutable {
-          if (env == nullptr || jsCallback.IsEmpty()) {
-            return;
-          }
-          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});
-        });
+  auto* dispatch = new TunPollDispatch();
+  dispatch->tsfn = tsfn;
+  poll_dispatch_ = dispatch;
+  auto packet_cb = [dispatch](std::vector<uint8_t> packet) mutable -> bool {
+    return dispatch->PostPacket(std::move(packet));
   };
   // Terminal errors from the receive loop (poll error, device closed, read
   // error) call back here so the JS-side polling_ flag and TSFN are released
@@ -326,8 +381,14 @@ void TunDevice::StopPollingLocked() {
 }
 
 void TunDevice::ReleaseTsfnLocked() {
+  // Release TSFN first — it blocks until queued callbacks finish. Those callbacks
+  // may still dereference poll_dispatch_, so it must outlive the TSFN drain.
   if (tsfn_) {
     tsfn_.Release();
     tsfn_ = nullptr;
   }
+  if (poll_dispatch_ != nullptr) {
+    delete poll_dispatch_;
+    poll_dispatch_ = nullptr;
+  }
 }