appium-ios-tuntap 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* Improve raw transfer performance ([#48](https://github.com/appium/appium-ios-tuntap/issues/48)) ([f5cf38f](https://github.com/appium/appium-ios-tuntap/commit/f5cf38f1156fec4dfbd8a71840d616a17f728106))
+
 ## [0.4.2](https://github.com/appium/appium-ios-tuntap/compare/v0.4.1...v0.4.2) (2026-06-01)
 
 ### Miscellaneous Chores

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/TunTap.d.ts

@@ -73,7 +73,15 @@ export declare class TunTap {
      * @throws {TypeError} if `callback` is not a function
      * @throws {RangeError} if `bufferSize` is out of range
      */
-    startPolling(callback: PacketCallback, bufferSize?: number): void;
+    startPolling(callback: PacketCallback, bufferSize?: number, queueDepth?: number): void;
+    /**
+     * Pause libuv-driven polling without tearing down the receive callback.
+     */
+    pausePolling(): void;
+    /**
+     * Resume polling after {@link TunTap.pausePolling}.
+     */
+    resumePolling(): void;
     /**
      * Configure IPv6 address and MTU on this interface using the platform backend (must run as root on Darwin/Linux).
      *

package/lib/TunTap.js

@@ -184,7 +184,7 @@ export class TunTap {
      * @throws {TypeError} if `callback` is not a function
      * @throws {RangeError} if `bufferSize` is out of range
      */
-    startPolling(callback, bufferSize = MAX_BUFFER_SIZE) {
+    startPolling(callback, bufferSize = MAX_BUFFER_SIZE, queueDepth = 8) {
         this.assertReady();
         if (typeof callback !== 'function') {
             throw new TypeError('Callback must be a function');
@@ -192,7 +192,24 @@ export class TunTap {
         if (bufferSize <= 0 || bufferSize > MAX_BUFFER_SIZE) {
             throw new RangeError(`Buffer size must be between 1 and ${MAX_BUFFER_SIZE} bytes`);
         }
-        this.device.startPolling(callback, bufferSize);
+        if (queueDepth <= 0 || queueDepth > 64) {
+            throw new RangeError('Queue depth must be between 1 and 64');
+        }
+        this.device.startPolling(callback, bufferSize, queueDepth);
+    }
+    /**
+     * Pause libuv-driven polling without tearing down the receive callback.
+     */
+    pausePolling() {
+        this.assertReady();
+        this.device.pausePolling();
+    }
+    /**
+     * Resume polling after {@link TunTap.pausePolling}.
+     */
+    resumePolling() {
+        this.assertReady();
+        this.device.resumePolling();
     }
     /**
      * Configure IPv6 address and MTU on this interface using the platform backend (must run as root on Darwin/Linux).

package/lib/tunnel/constants.d.ts

@@ -1,5 +1,13 @@
 /** CDTunnel lockdown handshake MTU (IPv6 minimum). */
 export declare const CD_TUNNEL_MTU = 1280;
+/** Upper bound for native TUN poll read size (matches N-API addon). */
+export declare const MAX_TUN_POLL_BUFFER = 65535;
+/** Preferred poll read size when L4 packet tap is off. */
+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;
 export declare const CD_TUNNEL_MAGIC = "CDTunnel";
 export declare const CD_TUNNEL_MAGIC_SIZE = 8;
 export declare const CD_TUNNEL_HEADER_SIZE: number;
@@ -8,3 +16,5 @@ 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

@@ -1,5 +1,13 @@
 /** CDTunnel lockdown handshake MTU (IPv6 minimum). */
 export const CD_TUNNEL_MTU = 1280;
+/** Upper bound for native TUN poll read size (matches N-API addon). */
+export const MAX_TUN_POLL_BUFFER = 65_535;
+/** Preferred poll read size when L4 packet tap is off. */
+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;
 export const CD_TUNNEL_MAGIC = 'CDTunnel';
 export const CD_TUNNEL_MAGIC_SIZE = 8;
 export const CD_TUNNEL_HEADER_SIZE = CD_TUNNEL_MAGIC_SIZE + 2;
@@ -8,3 +16,5 @@ 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/manager.d.ts

@@ -14,6 +14,8 @@ export declare class TunnelManager extends EventEmitter<TunnelManagerEvents> {
     private readonly packetConsumers;
     private deviceConn;
     private cleanupPromise;
+    private tunReadPausedForBackpressure;
+    private deviceIngressPausedForTun;
     /**
      * Register a listener for parsed tunnel packets (in addition to the `data` event).
      *
@@ -58,9 +60,13 @@ export declare class TunnelManager extends EventEmitter<TunnelManagerEvents> {
     private hasPacketTap;
     private processBuffer;
     private writeDeviceFrameToTun;
+    private shouldResumeDeviceIngress;
+    private pauseDeviceIngress;
+    private resumeDeviceIngress;
     private tapL4Packet;
     private dispatchPacketData;
     private startTunReadLoop;
+    private writeTunPacketToDevice;
     private _performStop;
 }
 /**

package/lib/tunnel/manager.js

@@ -2,7 +2,7 @@ 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 { 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 { appendBuffer } from './buffer-utils.js';
 /**
  * Bridges a CoreDevice tunnel `Socket` and a {@link TunTap} interface: IPv6 framing, TUN I/O, and packet fan-out.
@@ -16,6 +16,8 @@ export class TunnelManager extends EventEmitter {
     packetConsumers = new Set();
     deviceConn = null;
     cleanupPromise = null;
+    tunReadPausedForBackpressure = false;
+    deviceIngressPausedForTun = false;
     /**
      * Register a listener for parsed tunnel packets (in addition to the `data` event).
      *
@@ -135,7 +137,9 @@ export class TunnelManager extends EventEmitter {
             }
             try {
                 this.buffer = appendBuffer(this.buffer, data);
-                // Process IPv6 packets
+                if (this.buffer.length > MAX_DEVICE_INGRESS_BUFFER) {
+                    this.pauseDeviceIngress();
+                }
                 this.processBuffer();
             }
             catch (err) {
@@ -200,19 +204,47 @@ export class TunnelManager extends EventEmitter {
             offset += frame.length;
         }
         if (offset > 0) {
-            this.buffer = this.buffer.subarray(offset);
+            if (offset >= this.buffer.length) {
+                this.buffer = Buffer.alloc(0);
+            }
+            else {
+                this.buffer = this.buffer.subarray(offset);
+            }
+        }
+        if (this.deviceIngressPausedForTun && this.shouldResumeDeviceIngress()) {
+            this.resumeDeviceIngress();
         }
     }
     writeDeviceFrameToTun(tun, packet, nextHeader) {
-        const bytesWritten = tun.write(packet);
+        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}`);
+        log.debug(`Device → TUN: ${packet.length} 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();
+    }
     tapL4Packet(packet, nextHeader, src, dst) {
         let packetData = null;
         if (nextHeader === IPPROTO_UDP) {
@@ -256,18 +288,42 @@ export class TunnelManager extends EventEmitter {
         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 (this.hasPacketTap() && data.length >= IPV6_HEADER_SIZE) {
+            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 (this.hasPacketTap()) {
+            else if (tapOn) {
                 log.debug(`TUN → Device: ${data.length} bytes (too small for IPv6 header)`);
             }
-            deviceConn.write(data);
-        }, this.mtu);
+            this.writeTunPacketToDevice(deviceConn, data);
+        }, pollBuffer, queueDepth);
+    }
+    writeTunPacketToDevice(deviceConn, data) {
+        if (deviceConn.destroyed) {
+            return;
+        }
+        const canWriteMore = deviceConn.write(data);
+        if (canWriteMore || this.tunReadPausedForBackpressure || !this.tun) {
+            return;
+        }
+        this.tunReadPausedForBackpressure = true;
+        this.tun.pausePolling();
+        const onDrain = () => {
+            if (this.cancelled || deviceConn.destroyed) {
+                return;
+            }
+            this.tunReadPausedForBackpressure = false;
+            this.tun?.resumePolling();
+        };
+        deviceConn.once('drain', onDrain);
     }
     async _performStop() {
         const tunName = this.tun ? this.tun.name : 'unknown';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-tuntap",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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": "mocha \"test/unit/**/*.spec.mjs\" --exit --timeout 2m",
-    "test:integration": "mocha \"test/integration/**/*.spec.mjs\" --exit --timeout 2m"
+    "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\""
   },
   "files": [
     "src/tuntap.cc",
@@ -61,7 +61,6 @@
     "@types/node": "^25.0.1",
     "commander": "^14.0.3",
     "conventional-changelog-conventionalcommits": "^9.0.0",
-    "mocha": "^11.7.5",
     "prebuildify": "^6.0.1",
     "prettier": "^3.0.0",
     "semantic-release": "^25.0.2"

package/src/native/posix_tun_backend.h

@@ -47,6 +47,10 @@ public:
 
   void StopReceiveLoop() override { poll_loop_.Stop(); }
 
+  void PauseReceiveLoop() override { poll_loop_.Pause(); }
+
+  void ResumeReceiveLoop() override { poll_loop_.Resume(); }
+
   int GetNativeFd() const override { return fd_.get(); }
 
 protected:

package/src/native/posix_uv_poll_loop.cc

@@ -59,6 +59,7 @@ void PosixUvPollLoop::Stop() {
     return;
   }
 
+  paused_ = false;
   uv_poll_stop(handle_);
   handle_->data = nullptr;
   uv_close(reinterpret_cast<uv_handle_t*>(handle_),
@@ -67,6 +68,22 @@ void PosixUvPollLoop::Stop() {
   state_.reset();
 }
 
+void PosixUvPollLoop::Pause() {
+  if (!handle_ || paused_) {
+    return;
+  }
+  paused_ = true;
+  uv_poll_stop(handle_);
+}
+
+void PosixUvPollLoop::Resume() {
+  if (!handle_ || !paused_) {
+    return;
+  }
+  paused_ = false;
+  uv_poll_start(handle_, UV_READABLE, &PosixUvPollLoop::OnPoll);
+}
+
 void PosixUvPollLoop::OnPoll(uv_poll_t* handle, int status, int events) {
   auto* state = static_cast<State*>(handle->data);
   if (!state) {

package/src/native/posix_uv_poll_loop.h

@@ -33,8 +33,11 @@ public:
              std::string& error);
 
   void Stop();
+  void Pause();
+  void Resume();
 
 private:
+  bool paused_ = false;
   struct State {
     size_t buffer_size = 0;
     ReadFn read_fn;

package/src/native/tun_backend.h

@@ -72,6 +72,10 @@ public:
                                 std::string& error) = 0;
   virtual void StopReceiveLoop() = 0;
 
+  // Temporarily stop delivering packets without tearing down the receive loop.
+  virtual void PauseReceiveLoop() {}
+  virtual void ResumeReceiveLoop() {}
+
   // Returns the underlying POSIX file descriptor when one exists. Backends
   // without a numeric fd (e.g. Wintun on Windows) return `-1`.
   virtual int GetNativeFd() const { return -1; }

package/src/native/tun_backend_darwin.cc

@@ -134,6 +134,9 @@ public:
 
     ssize_t bytes_written = write(fd_.get(), write_frame_.data(), write_frame_.size());
     if (bytes_written < 0) {
+      if (errno == EAGAIN || errno == EWOULDBLOCK) {
+        return 0;
+      }
       error = std::string("Write error: ") + strerror(errno);
       return -1;
     }

package/src/native/tun_backend_linux.cc

@@ -104,6 +104,9 @@ public:
     }
     ssize_t bytes_written = write(fd_.get(), data, length);
     if (bytes_written < 0) {
+      if (errno == EAGAIN || errno == EWOULDBLOCK) {
+        return 0;
+      }
       error = std::string("Write error: ") + strerror(errno);
       return -1;
     }

package/src/native/tun_backend_windows.cc

@@ -238,9 +238,11 @@ public:
       // Either never started or already cleaned up. Reset the event in case
       // it was created without ever spawning a thread.
       quit_event_.reset();
+      receive_paused_.store(false);
       return;
     }
     worker_running_.store(false);
+    receive_paused_.store(false);
     if (quit_event_.is_valid()) {
       ::SetEvent(quit_event_.get());
     }
@@ -248,6 +250,10 @@ public:
     quit_event_.reset();
   }
 
+  void PauseReceiveLoop() override { receive_paused_.store(true); }
+
+  void ResumeReceiveLoop() override { receive_paused_.store(false); }
+
   // WinTun exposes no POSIX file descriptor: its readable object is a Win32
   // event `HANDLE`, not a numeric fd. Always -1 — the N-API layer treats -1
   // as "no pollable fd" and drives delivery through `StartReceiveLoop`.
@@ -293,11 +299,18 @@ private:
     HANDLE wait_handles[2] = {read_event_, quit_event_.get()};
 
     while (worker_running_.load()) {
+      while (receive_paused_.load() && worker_running_.load()) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+      }
+      if (!worker_running_.load()) {
+        return;
+      }
+
       // Drain everything available before going back to wait. WinTun's
       // read-wait event is auto-reset on signal, so we must consume all
       // queued packets before re-arming.
       bool drained = false;
-      while (worker_running_.load()) {
+      while (worker_running_.load() && !receive_paused_.load()) {
         DWORD packet_size = 0;
         BYTE* packet = api.ReceivePacket(session_, &packet_size);
         if (packet) {
@@ -358,6 +371,7 @@ private:
   Handle quit_event_;
   std::thread worker_;
   std::atomic<bool> worker_running_{false};
+  std::atomic<bool> receive_paused_{false};
   std::string interface_name_;
 };
 

package/src/tuntap.cc

@@ -28,6 +28,8 @@ private:
   Napi::Value GetName(const Napi::CallbackInfo& info);
   Napi::Value GetFd(const Napi::CallbackInfo& info);
   Napi::Value StartPolling(const Napi::CallbackInfo& info);
+  Napi::Value PausePolling(const Napi::CallbackInfo& info);
+  Napi::Value ResumePolling(const Napi::CallbackInfo& info);
 
   std::unique_ptr<TunPlatformBackend> backend_;
   std::string requested_name_;
@@ -56,6 +58,8 @@ Napi::Object TunDevice::Init(Napi::Env env, Napi::Object exports) {
     InstanceMethod("getName", &TunDevice::GetName),
     InstanceMethod("getFd", &TunDevice::GetFd),
     InstanceMethod("startPolling", &TunDevice::StartPolling),
+    InstanceMethod("pausePolling", &TunDevice::PausePolling),
+    InstanceMethod("resumePolling", &TunDevice::ResumePolling),
   });
 
   constructor = Napi::Persistent(func);
@@ -209,6 +213,15 @@ Napi::Value TunDevice::StartPolling(const Napi::CallbackInfo& info) {
     buffer_size = size;
   }
 
+  size_t queue_depth = 8;
+  if (info.Length() > 2 && info[2].IsNumber()) {
+    queue_depth = info[2].As<Napi::Number>().Uint32Value();
+    if (queue_depth == 0 || queue_depth > 64) {
+      Napi::RangeError::New(env, "Queue depth must be between 1 and 64").ThrowAsJavaScriptException();
+      return env.Null();
+    }
+  }
+
   // 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(
@@ -216,7 +229,7 @@ Napi::Value TunDevice::StartPolling(const Napi::CallbackInfo& info) {
       info[0].As<Napi::Function>(),
       "TunDeviceDataCallback",
       0,
-      8);
+      queue_depth);
 
   uv_loop_t* loop = nullptr;
   napi_status napi_st = napi_get_uv_event_loop(env, &loop);
@@ -265,6 +278,30 @@ Napi::Value TunDevice::StartPolling(const Napi::CallbackInfo& info) {
   return env.Undefined();
 }
 
+Napi::Value TunDevice::PausePolling(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  std::lock_guard<std::mutex> lock(device_mutex_);
+
+  if (!polling_ || !backend_ || !backend_->IsOpen()) {
+    return env.Undefined();
+  }
+
+  backend_->PauseReceiveLoop();
+  return env.Undefined();
+}
+
+Napi::Value TunDevice::ResumePolling(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  std::lock_guard<std::mutex> lock(device_mutex_);
+
+  if (!polling_ || !backend_ || !backend_->IsOpen()) {
+    return env.Undefined();
+  }
+
+  backend_->ResumeReceiveLoop();
+  return env.Undefined();
+}
+
 Napi::Object Init(Napi::Env env, Napi::Object exports) {
   return TunDevice::Init(env, exports);
 }