appium-ios-tuntap 0.4.2 → 0.4.3

package/CHANGELOG.md

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

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;

package/lib/tunnel/manager.d.ts

@@ -14,6 +14,7 @@ export declare class TunnelManager extends EventEmitter<TunnelManagerEvents> {
     private readonly packetConsumers;
     private deviceConn;
     private cleanupPromise;
+    private tunReadPausedForBackpressure;
     /**
      * Register a listener for parsed tunnel packets (in addition to the `data` event).
      *
@@ -61,6 +62,7 @@ export declare class TunnelManager extends EventEmitter<TunnelManagerEvents> {
     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_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,7 @@ export class TunnelManager extends EventEmitter {
     packetConsumers = new Set();
     deviceConn = null;
     cleanupPromise = null;
+    tunReadPausedForBackpressure = false;
     /**
      * Register a listener for parsed tunnel packets (in addition to the `data` event).
      *
@@ -200,15 +201,20 @@ 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);
+            }
         }
     }
     writeDeviceFrameToTun(tun, packet, nextHeader) {
-        const bytesWritten = tun.write(packet);
+        tun.write(packet);
         if (!this.hasPacketTap()) {
-            log.debug(`Device → TUN: ${bytesWritten} bytes`);
             return;
         }
+        const bytesWritten = packet.length;
         const { src, dst } = ipv6Endpoints(packet);
         log.debug(`Device → TUN: ${bytesWritten} bytes, IPv6 src=${src}, dst=${dst}`);
         this.tapL4Packet(packet, nextHeader, src, dst);
@@ -256,18 +262,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.3",
   "description": "Native TUN/TAP interface module for Node.js",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

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_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);
 }