appium-ios-tuntap 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.3.0](https://github.com/appium/appium-ios-tuntap/compare/v0.2.5...v0.3.0) (2026-05-22)
+
+### Features
+
+* add Windows (WinTun) native backend ([#43](https://github.com/appium/appium-ios-tuntap/issues/43)) ([565b4c1](https://github.com/appium/appium-ios-tuntap/commit/565b4c1cfd2ddf4956ed32ade4f8208cd0d4f0f6)), closes [#ifdef](https://github.com/appium/appium-ios-tuntap/issues/ifdef)
+
+## [0.2.5](https://github.com/appium/appium-ios-tuntap/compare/v0.2.4...v0.2.5) (2026-05-14)
+
+### Code Refactoring
+
+* backends own fd, polling, and lifecycle ([#42](https://github.com/appium/appium-ios-tuntap/issues/42)) ([f089944](https://github.com/appium/appium-ios-tuntap/commit/f08994477cb9909b597386d0893abbf9b6a3c137))
+
 ## [0.2.4](https://github.com/appium/appium-ios-tuntap/compare/v0.2.3...v0.2.4) (2026-05-13)
 
 ### Code Refactoring

package/binding.gyp

@@ -3,8 +3,7 @@
     {
       "target_name": "tuntap",
       "sources": [
-        "src/tuntap.cc",
-        "src/native/file_descriptor.cc"
+        "src/tuntap.cc"
       ],
       "include_dirs": [
         "<!@(node -p \"require('node-addon-api').include\")"
@@ -21,7 +20,7 @@
         "-Wno-unused-parameter",
         "-fPIC"
       ],
-      "cflags_cc": [ 
+      "cflags_cc": [
         "-std=c++17",
         "-Wno-vla-extension",
         "-O3",
@@ -49,7 +48,7 @@
         ]
       },
       "msvs_settings": {
-        "VCCLCompilerTool": { 
+        "VCCLCompilerTool": {
           "ExceptionHandling": 1,
           "AdditionalOptions": [
             "/std:c++17",
@@ -57,13 +56,15 @@
           ]
         }
       },
-      "defines": [ 
+      "defines": [
         "NAPI_CPP_EXCEPTIONS",
         "NAPI_VERSION=8"
       ],
       "conditions": [
         ["OS=='linux'", {
           "sources": [
+            "src/native/file_descriptor.cc",
+            "src/native/posix_uv_poll_loop.cc",
             "src/native/tun_backend_linux.cc"
           ],
           "cflags": [
@@ -78,6 +79,8 @@
         }],
         ["OS=='mac'", {
           "sources": [
+            "src/native/file_descriptor.cc",
+            "src/native/posix_uv_poll_loop.cc",
             "src/native/tun_backend_darwin.cc"
           ],
           "xcode_settings": {
@@ -86,6 +89,22 @@
               "-framework", "CoreFoundation"
             ]
           }
+        }],
+        ["OS=='win'", {
+          "sources": [
+            "src/native/handle.cc",
+            "src/native/wintun_loader.cc",
+            "src/native/tun_backend_windows.cc"
+          ],
+          "libraries": [
+            "iphlpapi.lib",
+            "ws2_32.lib"
+          ],
+          "defines": [
+            "_WIN32_WINNT=0x0A00",
+            "WIN32_LEAN_AND_MEAN",
+            "NOMINMAX"
+          ]
         }]
       ]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-tuntap",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Native TUN/TAP interface module for Node.js",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/native/handle.cc

@@ -0,0 +1,59 @@
+#ifdef _WIN32
+
+#include "handle.h"
+
+namespace {
+
+bool IsRealHandle(HANDLE handle) {
+  return handle != nullptr && handle != INVALID_HANDLE_VALUE;
+}
+
+} // namespace
+
+Handle::Handle() : handle_(nullptr) {}
+
+Handle::Handle(HANDLE handle) : handle_(handle) {}
+
+Handle::~Handle() {
+  if (IsRealHandle(handle_)) {
+    ::CloseHandle(handle_);
+  }
+}
+
+Handle::Handle(Handle&& other) noexcept : handle_(other.handle_) {
+  other.handle_ = nullptr;
+}
+
+Handle& Handle::operator=(Handle&& other) noexcept {
+  if (this != &other) {
+    if (IsRealHandle(handle_)) {
+      ::CloseHandle(handle_);
+    }
+    handle_ = other.handle_;
+    other.handle_ = nullptr;
+  }
+  return *this;
+}
+
+HANDLE Handle::get() const {
+  return handle_;
+}
+
+HANDLE Handle::release() {
+  HANDLE temp = handle_;
+  handle_ = nullptr;
+  return temp;
+}
+
+bool Handle::is_valid() const {
+  return IsRealHandle(handle_);
+}
+
+void Handle::reset(HANDLE handle) {
+  if (IsRealHandle(handle_)) {
+    ::CloseHandle(handle_);
+  }
+  handle_ = handle;
+}
+
+#endif

package/src/native/handle.h

@@ -0,0 +1,30 @@
+#pragma once
+
+#ifdef _WIN32
+
+#include <windows.h>
+
+// RAII wrapper for a Win32 `HANDLE`. Mirrors `FileDescriptor` so backends can
+// rely on the same lifetime semantics regardless of OS.
+class Handle {
+public:
+  Handle();
+  explicit Handle(HANDLE handle);
+  ~Handle();
+
+  Handle(const Handle&) = delete;
+  Handle& operator=(const Handle&) = delete;
+
+  Handle(Handle&& other) noexcept;
+  Handle& operator=(Handle&& other) noexcept;
+
+  HANDLE get() const;
+  HANDLE release();
+  bool is_valid() const;
+  void reset(HANDLE handle = nullptr);
+
+private:
+  HANDLE handle_;
+};
+
+#endif

package/src/native/posix_tun_backend.h

@@ -0,0 +1,58 @@
+#pragma once
+
+#if defined(__APPLE__) || defined(__linux__)
+
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "file_descriptor.h"
+#include "posix_uv_poll_loop.h"
+#include "tun_backend.h"
+
+// Shared base class for POSIX TUN backends (Darwin, Linux). Owns the file
+// descriptor, the assigned interface name, and the libuv poll loop. Concrete
+// subclasses implement only the platform-specific OpenDevice, ReadPacket, and
+// WritePacket.
+class PosixTunBackend : public TunPlatformBackend {
+public:
+  void CloseDevice() override {
+    poll_loop_.Stop();
+    fd_.reset();
+    interface_name_.clear();
+  }
+
+  bool IsOpen() const override { return fd_.is_valid(); }
+
+  bool StartReceiveLoop(uv_loop_t* loop,
+                        size_t buffer_size,
+                        PacketCallback on_packet,
+                        ErrorCallback on_error,
+                        std::string& error) override {
+    if (!fd_.is_valid()) {
+      error = "Device not open";
+      return false;
+    }
+    return poll_loop_.Start(
+        loop,
+        fd_.get(),
+        buffer_size,
+        [this](size_t size, std::vector<uint8_t>& out, std::string& err) {
+          return ReadPacket(size, out, err);
+        },
+        std::move(on_packet),
+        std::move(on_error),
+        error);
+  }
+
+  void StopReceiveLoop() override { poll_loop_.Stop(); }
+
+  int GetNativeFd() const override { return fd_.get(); }
+
+protected:
+  FileDescriptor fd_;
+  std::string interface_name_;
+  PosixUvPollLoop poll_loop_;
+};
+
+#endif

package/src/native/posix_uv_poll_loop.cc

@@ -0,0 +1,137 @@
+#if defined(__APPLE__) || defined(__linux__)
+
+#include "posix_uv_poll_loop.h"
+
+#include <cstdio>
+#include <errno.h>
+#include <fcntl.h>
+#include <string.h>
+#include <utility>
+
+PosixUvPollLoop::~PosixUvPollLoop() {
+  Stop();
+}
+
+bool PosixUvPollLoop::Start(uv_loop_t* loop,
+                            int fd,
+                            size_t buffer_size,
+                            ReadFn read_fn,
+                            TunPlatformBackend::PacketCallback on_packet,
+                            TunPlatformBackend::ErrorCallback on_error,
+                            std::string& error) {
+  if (handle_) {
+    error = "Receive loop already started";
+    return false;
+  }
+  if (!loop || fd < 0 || buffer_size == 0) {
+    error = "Invalid receive-loop parameters";
+    return false;
+  }
+
+  auto state = std::make_unique<State>();
+  state->buffer_size = buffer_size;
+  state->read_fn = std::move(read_fn);
+  state->on_packet = std::move(on_packet);
+  state->on_error = std::move(on_error);
+  state->owner = this;
+
+  auto handle = std::make_unique<uv_poll_t>();
+  if (uv_poll_init(loop, handle.get(), fd) != 0) {
+    error = "Failed to initialize poll handle";
+    return false;
+  }
+
+  handle->data = state.get();
+  if (uv_poll_start(handle.get(), UV_READABLE, &PosixUvPollLoop::OnPoll) != 0) {
+    uv_close(reinterpret_cast<uv_handle_t*>(handle.release()),
+             [](uv_handle_t* h) { delete reinterpret_cast<uv_poll_t*>(h); });
+    error = "Failed to start polling";
+    return false;
+  }
+
+  state_ = std::move(state);
+  handle_ = handle.release();
+  return true;
+}
+
+void PosixUvPollLoop::Stop() {
+  if (!handle_) {
+    return;
+  }
+
+  uv_poll_stop(handle_);
+  handle_->data = nullptr;
+  uv_close(reinterpret_cast<uv_handle_t*>(handle_),
+           &PosixUvPollLoop::OnHandleClosed);
+  handle_ = nullptr;
+  state_.reset();
+}
+
+void PosixUvPollLoop::OnPoll(uv_poll_t* handle, int status, int events) {
+  auto* state = static_cast<State*>(handle->data);
+  if (!state) {
+    return;
+  }
+
+  // Tear down the loop and notify the owner of a terminal condition. The
+  // callback is copied locally first because Stop() destroys `state` (and the
+  // std::function it owns) synchronously.
+  auto handle_terminal = [&](const std::string& msg) {
+    auto cb = state->on_error;
+    PosixUvPollLoop* owner = state->owner;
+    if (owner) {
+      owner->Stop();
+    }
+    if (cb) {
+      cb(msg);
+    }
+  };
+
+  if (status < 0) {
+    handle_terminal(std::string("Poll error: ") + uv_strerror(status));
+    return;
+  }
+
+  if (!(events & UV_READABLE) || !state->read_fn) {
+    return;
+  }
+
+  std::vector<uint8_t> packet;
+  std::string error;
+  ReadPacketStatus rs = state->read_fn(state->buffer_size, packet, error);
+
+  switch (rs) {
+    case ReadPacketStatus::Data:
+      if (state->on_packet) {
+        state->on_packet(std::move(packet));
+      }
+      return;
+    case ReadPacketStatus::NoData:
+      return;
+    case ReadPacketStatus::Closed:
+      handle_terminal("Device closed");
+      return;
+    case ReadPacketStatus::Error:
+      handle_terminal(error);
+      return;
+  }
+}
+
+void PosixUvPollLoop::OnHandleClosed(uv_handle_t* handle) {
+  delete reinterpret_cast<uv_poll_t*>(handle);
+}
+
+bool SetNonBlocking(int fd, std::string& error) {
+  int flags = fcntl(fd, F_GETFL, 0);
+  if (flags < 0) {
+    error = std::string("Failed to get file descriptor flags: ") + strerror(errno);
+    return false;
+  }
+  if (fcntl(fd, F_SETFL, flags | O_NONBLOCK) < 0) {
+    error = std::string("Failed to set non-blocking mode: ") + strerror(errno);
+    return false;
+  }
+  return true;
+}
+
+#endif

package/src/native/posix_uv_poll_loop.h

@@ -0,0 +1,55 @@
+#pragma once
+
+#if defined(__APPLE__) || defined(__linux__)
+
+#include <cstddef>
+#include <functional>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include <uv.h>
+
+#include "tun_backend.h"
+
+class PosixUvPollLoop {
+public:
+  using ReadFn = std::function<ReadPacketStatus(size_t,
+                                                std::vector<uint8_t>&,
+                                                std::string&)>;
+
+  PosixUvPollLoop() = default;
+  ~PosixUvPollLoop();
+
+  PosixUvPollLoop(const PosixUvPollLoop&) = delete;
+  PosixUvPollLoop& operator=(const PosixUvPollLoop&) = delete;
+
+  bool Start(uv_loop_t* loop,
+             int fd,
+             size_t buffer_size,
+             ReadFn read_fn,
+             TunPlatformBackend::PacketCallback on_packet,
+             TunPlatformBackend::ErrorCallback on_error,
+             std::string& error);
+
+  void Stop();
+
+private:
+  struct State {
+    size_t buffer_size = 0;
+    ReadFn read_fn;
+    TunPlatformBackend::PacketCallback on_packet;
+    TunPlatformBackend::ErrorCallback on_error;
+    PosixUvPollLoop* owner = nullptr;
+  };
+
+  static void OnPoll(uv_poll_t* handle, int status, int events);
+  static void OnHandleClosed(uv_handle_t* handle);
+
+  uv_poll_t* handle_ = nullptr;
+  std::unique_ptr<State> state_;
+};
+
+bool SetNonBlocking(int fd, std::string& error);
+
+#endif

package/src/native/tun_backend.h

@@ -1,22 +1,24 @@
 #pragma once
 
-#if !defined(__linux__) && !defined(__APPLE__)
-#error "appium-ios-tuntap native addon supports only Linux and macOS"
+#if !defined(__linux__) && !defined(__APPLE__) && !defined(_WIN32)
+#error "appium-ios-tuntap native addon supports only Linux, macOS, and Windows"
 #endif
 
 #include <cstddef>
 #include <cstdint>
+#include <functional>
 #include <memory>
 #include <string>
-#include <sys/types.h>
 #include <vector>
 
-#include "file_descriptor.h"
+#ifdef _WIN32
+#include <BaseTsd.h>
+using ssize_t = SSIZE_T;
+#else
+#include <sys/types.h>
+#endif
 
-struct OpenResult {
-  FileDescriptor fd;
-  std::string interface_name;
-};
+#include <uv.h>
 
 enum class ReadPacketStatus {
   Data,
@@ -25,13 +27,54 @@ enum class ReadPacketStatus {
   Error,
 };
 
+/**
+ * Backend abstraction that hides OS-specific TUN device handling from the
+ * N-API surface.
+ *
+ * Each backend owns:
+ * - its native handle (POSIX file descriptor or Win32 `HANDLE`)
+ * - the receive-loop primitive it needs (libuv `uv_poll_t` on POSIX, a
+ *   dedicated worker thread plus a Win32 event on Windows)
+ */
 class TunPlatformBackend {
 public:
+  // Invoked once per packet read by the receive loop. Always called on a
+  // 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>)>;
+
+  // Invoked at most once when the receive loop encounters a fatal error and
+  // stops. The receive loop must not deliver any further packets afterwards.
+  using ErrorCallback = std::function<void(const std::string&)>;
+
   virtual ~TunPlatformBackend() = default;
-  virtual bool OpenDevice(const std::string& requested_name, OpenResult& out, std::string& error) = 0;
-  virtual ReadPacketStatus ReadPacket(int fd, size_t max_payload_size, std::vector<uint8_t>& out, std::string& error) = 0;
-  virtual ssize_t WritePacket(int fd, const uint8_t* data, size_t length, std::string& error) = 0;
+
+  virtual bool OpenDevice(const std::string& requested_name,
+                          std::string& out_interface_name,
+                          std::string& error) = 0;
+  virtual void CloseDevice() = 0;
+  virtual bool IsOpen() const = 0;
+
+  virtual ReadPacketStatus ReadPacket(size_t max_payload_size,
+                                      std::vector<uint8_t>& out,
+                                      std::string& error) = 0;
+  virtual ssize_t WritePacket(const uint8_t* data,
+                              size_t length,
+                              std::string& error) = 0;
+
+  // Begin asynchronous packet delivery. `loop` is supplied by Node-API and is
+  // used by POSIX backends for `uv_poll_init`; Windows ignores it.
+  virtual bool StartReceiveLoop(uv_loop_t* loop,
+                                size_t buffer_size,
+                                PacketCallback on_packet,
+                                ErrorCallback on_error,
+                                std::string& error) = 0;
+  virtual void StopReceiveLoop() = 0;
+
+  // 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; }
 };
 
 std::unique_ptr<TunPlatformBackend> CreatePlatformBackend();
-

package/src/native/tun_backend_darwin.cc

@@ -14,30 +14,23 @@
 #include <netinet/in.h>
 #include <netinet6/in6_var.h>
 
-#include <fcntl.h>
+#include <utility>
+
+#include "file_descriptor.h"
+#include "posix_tun_backend.h"
+#include "posix_uv_poll_loop.h"
 
 #define UTUN_CONTROL_NAME "com.apple.net.utun_control"
 
 namespace {
 
-bool SetNonBlocking(int fd, std::string& error) {
-  int flags = fcntl(fd, F_GETFL, 0);
-  if (flags < 0) {
-    error = std::string("Failed to get file descriptor flags: ") + strerror(errno);
-    return false;
-  }
-  if (fcntl(fd, F_SETFL, flags | O_NONBLOCK) < 0) {
-    error = std::string("Failed to set non-blocking mode: ") + strerror(errno);
-    return false;
-  }
-  return true;
-}
-
-class DarwinTunBackend : public TunPlatformBackend {
+class DarwinTunBackend : public PosixTunBackend {
 public:
   static constexpr size_t kUtunHeaderSize = 4;
 
-  bool OpenDevice(const std::string& requested_name, OpenResult& out, std::string& error) override {
+  bool OpenDevice(const std::string& requested_name,
+                  std::string& out_interface_name,
+                  std::string& error) override {
     struct ctl_info ctl_info;
     struct sockaddr_ctl socket_addr;
 
@@ -84,14 +77,22 @@ public:
       return false;
     }
 
-    out.fd = std::move(temp_fd);
-    out.interface_name = std::string(interface_name);
+    fd_ = std::move(temp_fd);
+    interface_name_ = std::string(interface_name);
+    out_interface_name = interface_name_;
     return true;
   }
 
-  ReadPacketStatus ReadPacket(int fd, size_t max_payload_size, std::vector<uint8_t>& out, std::string& error) override {
+  ReadPacketStatus ReadPacket(size_t max_payload_size,
+                              std::vector<uint8_t>& out,
+                              std::string& error) override {
+    if (!fd_.is_valid()) {
+      error = "Device not open";
+      return ReadPacketStatus::Error;
+    }
+
     out.resize(max_payload_size + kUtunHeaderSize);
-    ssize_t bytes_read = read(fd, out.data(), out.size());
+    ssize_t bytes_read = read(fd_.get(), out.data(), out.size());
     if (bytes_read < 0) {
       if (errno == EAGAIN || errno == EWOULDBLOCK) {
         out.clear();
@@ -116,21 +117,28 @@ public:
     return ReadPacketStatus::Data;
   }
 
-  ssize_t WritePacket(int fd, const uint8_t* data, size_t length, std::string& error) override {
+  ssize_t WritePacket(const uint8_t* data,
+                      size_t length,
+                      std::string& error) override {
+    if (!fd_.is_valid()) {
+      error = "Device not open";
+      return -1;
+    }
+
     std::vector<uint8_t> frame(length + kUtunHeaderSize);
     uint32_t family = htonl(AF_INET6);
     memcpy(frame.data(), &family, kUtunHeaderSize);
     memcpy(frame.data() + kUtunHeaderSize, data, length);
 
-    ssize_t bytes_written = write(fd, frame.data(), frame.size());
+    ssize_t bytes_written = write(fd_.get(), frame.data(), frame.size());
     if (bytes_written < 0) {
       error = std::string("Write error: ") + strerror(errno);
       return -1;
     }
 
     return bytes_written > static_cast<ssize_t>(kUtunHeaderSize)
-      ? bytes_written - static_cast<ssize_t>(kUtunHeaderSize)
-      : 0;
+               ? bytes_written - static_cast<ssize_t>(kUtunHeaderSize)
+               : 0;
   }
 
 private:
@@ -168,4 +176,3 @@ std::unique_ptr<TunPlatformBackend> CreatePlatformBackend() {
 }
 
 #endif
-