appium-ios-tuntap 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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\")"
@@ -64,6 +63,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": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-tuntap",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "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

@@ -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

@@ -6,17 +6,19 @@
 
 #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,
@@ -27,11 +29,32 @@ enum class ReadPacketStatus {
 
 class TunPlatformBackend {
 public:
+  using PacketCallback = std::function<void(std::vector<uint8_t>)>;
+  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;
+
+  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;
+
+  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
-

package/src/native/tun_backend_linux.cc

@@ -12,40 +12,35 @@
 #include <linux/if.h>
 #include <linux/if_tun.h>
 
-namespace {
+#include <utility>
 
-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;
-}
+#include "file_descriptor.h"
+#include "posix_tun_backend.h"
+#include "posix_uv_poll_loop.h"
+
+namespace {
 
 constexpr const char* kTunDevicePath = "/dev/net/tun";
 
-class LinuxTunBackend : public TunPlatformBackend {
+class LinuxTunBackend : public PosixTunBackend {
 public:
-  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 stat statbuf;
     if (stat(kTunDevicePath, &statbuf) != 0) {
       error =
-        "TUN/TAP device not available: /dev/net/tun does not exist. "
-        "Please ensure the TUN/TAP kernel module is loaded (modprobe tun).";
+          "TUN/TAP device not available: /dev/net/tun does not exist. "
+          "Please ensure the TUN/TAP kernel module is loaded (modprobe tun).";
       return false;
     }
 
     FileDescriptor temp_fd(open(kTunDevicePath, O_RDWR));
     if (!temp_fd.is_valid()) {
       error =
-        std::string("Failed to open ") + kTunDevicePath + ": " + strerror(errno) +
-        ". This usually means you don't have sufficient permissions. "
-        "Try running with sudo or add your user to the 'tun' group.";
+          std::string("Failed to open ") + kTunDevicePath + ": " + strerror(errno) +
+          ". This usually means you don't have sufficient permissions. "
+          "Try running with sudo or add your user to the 'tun' group.";
       return false;
     }
 
@@ -67,14 +62,22 @@ public:
       return false;
     }
 
-    out.fd = std::move(temp_fd);
-    out.interface_name = std::string(ifr.ifr_name);
+    fd_ = std::move(temp_fd);
+    interface_name_ = std::string(ifr.ifr_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);
-    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();
@@ -92,8 +95,14 @@ public:
     return ReadPacketStatus::Data;
   }
 
-  ssize_t WritePacket(int fd, const uint8_t* data, size_t length, std::string& error) override {
-    ssize_t bytes_written = write(fd, data, length);
+  ssize_t WritePacket(const uint8_t* data,
+                      size_t length,
+                      std::string& error) override {
+    if (!fd_.is_valid()) {
+      error = "Device not open";
+      return -1;
+    }
+    ssize_t bytes_written = write(fd_.get(), data, length);
     if (bytes_written < 0) {
       error = std::string("Write error: ") + strerror(errno);
       return -1;
@@ -109,4 +118,3 @@ std::unique_ptr<TunPlatformBackend> CreatePlatformBackend() {
 }
 
 #endif
-

package/src/tuntap.cc

@@ -1,14 +1,13 @@
 #include <napi.h>
-#include <uv.h>
 
-#include <string>
-#include <vector>
-#include <memory>
-#include <mutex>
 #include <atomic>
 #include <cstdio>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <utility>
+#include <vector>
 
-#include "native/file_descriptor.h"
 #include "native/tun_backend.h"
 
 class TunDevice : public Napi::ObjectWrap<TunDevice> {
@@ -30,24 +29,22 @@ private:
   Napi::Value GetFd(const Napi::CallbackInfo& info);
   Napi::Value StartPolling(const Napi::CallbackInfo& info);
 
-  FileDescriptor fd_;
-  std::string name_;
   std::unique_ptr<TunPlatformBackend> backend_;
+  std::string requested_name_;
+  std::string interface_name_;
   std::atomic<bool> is_open_;
   std::mutex device_mutex_;
 
-  uv_poll_t* poll_handle_ = nullptr;
   Napi::ThreadSafeFunction tsfn_;
+  std::atomic<bool> polling_;
   static constexpr size_t MAX_POLL_BUFFER = 65535;
-  size_t poll_buffer_size_ = MAX_POLL_BUFFER;
 
-  void StopPolling();
-  static void PollCallback(uv_poll_t* handle, int status, int events);
+  void StopPollingLocked();
+  void ReleaseTsfnLocked();
 };
 
 Napi::FunctionReference TunDevice::constructor;
 
-// Defines and exports the JS class constructor: new TunDevice(name?)
 Napi::Object TunDevice::Init(Napi::Env env, Napi::Object exports) {
   Napi::HandleScope scope(env);
 
@@ -68,25 +65,24 @@ Napi::Object TunDevice::Init(Napi::Env env, Napi::Object exports) {
   return exports;
 }
 
-// Creates a TunDevice wrapper; optional first arg is requested interface name.
 TunDevice::TunDevice(const Napi::CallbackInfo& info)
-  : Napi::ObjectWrap<TunDevice>(info), backend_(CreatePlatformBackend()), is_open_(false) {
+    : Napi::ObjectWrap<TunDevice>(info),
+      backend_(CreatePlatformBackend()),
+      is_open_(false),
+      polling_(false) {
   Napi::Env env = info.Env();
   Napi::HandleScope scope(env);
 
   if (info.Length() > 0 && info[0].IsString()) {
-    name_ = info[0].As<Napi::String>().Utf8Value();
+    requested_name_ = info[0].As<Napi::String>().Utf8Value();
   }
 }
 
-// Ensures fd/poll resources are closed when object is destroyed.
 TunDevice::~TunDevice() {
   std::lock_guard<std::mutex> lock(device_mutex_);
   CloseInternal();
 }
 
-// JS: open() -> boolean
-// Opens the backend device and configures the fd as non-blocking.
 Napi::Value TunDevice::Open(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   std::lock_guard<std::mutex> lock(device_mutex_);
@@ -100,22 +96,18 @@ Napi::Value TunDevice::Open(const Napi::CallbackInfo& info) {
     return Napi::Boolean::New(env, false);
   }
 
-  OpenResult result;
   std::string error;
-  if (!backend_->OpenDevice(name_, result, error)) {
+  std::string assigned_name;
+  if (!backend_->OpenDevice(requested_name_, assigned_name, error)) {
     Napi::Error::New(env, error).ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
-  fd_ = std::move(result.fd);
-  name_ = result.interface_name;
+  interface_name_ = std::move(assigned_name);
   is_open_ = true;
-
   return Napi::Boolean::New(env, true);
 }
 
-// JS: close() -> boolean
-// Safely closes device resources; calling multiple times is allowed.
 Napi::Value TunDevice::Close(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   std::lock_guard<std::mutex> lock(device_mutex_);
@@ -123,13 +115,11 @@ Napi::Value TunDevice::Close(const Napi::CallbackInfo& info) {
   return Napi::Boolean::New(env, true);
 }
 
-// JS: read(bufferSize?) -> Buffer
-// Reads one payload packet, or returns an empty Buffer when no data is available.
 Napi::Value TunDevice::Read(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   std::lock_guard<std::mutex> lock(device_mutex_);
 
-  if (!is_open_ || !fd_.is_valid()) {
+  if (!is_open_ || !backend_ || !backend_->IsOpen()) {
     Napi::Error::New(env, "Device not open").ThrowAsJavaScriptException();
     return env.Null();
   }
@@ -145,25 +135,22 @@ Napi::Value TunDevice::Read(const Napi::CallbackInfo& info) {
 
   std::vector<uint8_t> packet;
   std::string error;
-  ReadPacketStatus read_status = backend_->ReadPacket(fd_.get(), buffer_size, packet, error);
-  if (read_status == ReadPacketStatus::Error) {
+  ReadPacketStatus rs = backend_->ReadPacket(buffer_size, packet, error);
+  if (rs == ReadPacketStatus::Error) {
     Napi::Error::New(env, error).ThrowAsJavaScriptException();
     return env.Null();
   }
-  if (read_status == ReadPacketStatus::NoData || read_status == ReadPacketStatus::Closed) {
+  if (rs == ReadPacketStatus::NoData || rs == ReadPacketStatus::Closed) {
     return Napi::Buffer<uint8_t>::New(env, 0);
   }
-
   return Napi::Buffer<uint8_t>::Copy(env, packet.data(), packet.size());
 }
 
-// JS: write(buffer) -> number
-// Writes one packet and returns payload bytes accepted by the backend.
 Napi::Value TunDevice::Write(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   std::lock_guard<std::mutex> lock(device_mutex_);
 
-  if (!is_open_ || !fd_.is_valid()) {
+  if (!is_open_ || !backend_ || !backend_->IsOpen()) {
     Napi::Error::New(env, "Device not open").ThrowAsJavaScriptException();
     return Napi::Number::New(env, -1);
   }
@@ -178,35 +165,29 @@ Napi::Value TunDevice::Write(const Napi::CallbackInfo& info) {
   size_t length = buffer.Length();
 
   std::string error;
-  ssize_t bytes_written = backend_->WritePacket(fd_.get(), data, length, error);
+  ssize_t bytes_written = backend_->WritePacket(data, length, error);
   if (bytes_written < 0) {
     Napi::Error::New(env, error).ThrowAsJavaScriptException();
     return Napi::Number::New(env, -1);
   }
-  return Napi::Number::New(env, bytes_written);
+  return Napi::Number::New(env, static_cast<double>(bytes_written));
 }
 
-// JS: getName() -> string
-// Returns the assigned interface name after open().
 Napi::Value TunDevice::GetName(const Napi::CallbackInfo& info) {
   std::lock_guard<std::mutex> lock(device_mutex_);
-  return Napi::String::New(info.Env(), name_);
+  return Napi::String::New(info.Env(), interface_name_);
 }
 
-// JS: getFd() -> number
-// Returns the native file descriptor, or -1 before open()/after close().
 Napi::Value TunDevice::GetFd(const Napi::CallbackInfo& info) {
   std::lock_guard<std::mutex> lock(device_mutex_);
-  return Napi::Number::New(info.Env(), fd_.get());
+  return Napi::Number::New(info.Env(), backend_ ? backend_->GetNativeFd() : -1);
 }
 
-// JS: startPolling(callback, bufferSize?) -> void
-// Starts libuv polling and invokes callback with packet payload Buffers.
 Napi::Value TunDevice::StartPolling(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   std::lock_guard<std::mutex> lock(device_mutex_);
 
-  if (!is_open_ || !fd_.is_valid()) {
+  if (!is_open_ || !backend_ || !backend_->IsOpen()) {
     Napi::Error::New(env, "Device not open").ThrowAsJavaScriptException();
     return env.Null();
   }
@@ -216,134 +197,91 @@ Napi::Value TunDevice::StartPolling(const Napi::CallbackInfo& info) {
     return env.Null();
   }
 
-  StopPolling();
+  StopPollingLocked();
 
-  // Optional buffer size as second argument (default: MAX_POLL_BUFFER)
-  poll_buffer_size_ = MAX_POLL_BUFFER;
+  size_t buffer_size = MAX_POLL_BUFFER;
   if (info.Length() > 1 && info[1].IsNumber()) {
     auto size = info[1].As<Napi::Number>().Uint32Value();
     if (size == 0 || size > MAX_POLL_BUFFER) {
       Napi::RangeError::New(env, "Buffer size must be between 1 and " + std::to_string(MAX_POLL_BUFFER)).ThrowAsJavaScriptException();
       return env.Null();
     }
-    poll_buffer_size_ = size;
+    buffer_size = size;
   }
 
   tsfn_ = Napi::ThreadSafeFunction::New(
-    env,
-    info[0].As<Napi::Function>(),
-    "TunDeviceDataCallback",
-    0,
-    1
-  );
+      env,
+      info[0].As<Napi::Function>(),
+      "TunDeviceDataCallback",
+      0,
+      1);
 
   uv_loop_t* loop = nullptr;
   napi_status napi_st = napi_get_uv_event_loop(env, &loop);
   if (napi_st != napi_ok || loop == nullptr) {
-    tsfn_.Release();
-    tsfn_ = nullptr;
+    ReleaseTsfnLocked();
     Napi::Error::New(env, "Failed to acquire event loop").ThrowAsJavaScriptException();
     return env.Null();
   }
 
-  auto handle = std::make_unique<uv_poll_t>();
-  if (uv_poll_init(loop, handle.get(), fd_.get()) != 0) {
-    tsfn_.Release();
-    tsfn_ = nullptr;
-    Napi::Error::New(env, "Failed to initialize poll handle").ThrowAsJavaScriptException();
-    return env.Null();
-  }
-
-  handle->data = this;
-  if (uv_poll_start(handle.get(), UV_READABLE, PollCallback) != 0) {
-    // Properly close the initialized-but-not-started handle
-    uv_close(reinterpret_cast<uv_handle_t*>(handle.release()), [](uv_handle_t* h) {
-      delete reinterpret_cast<uv_poll_t*>(h);
-    });
-    tsfn_.Release();
-    tsfn_ = nullptr;
-    Napi::Error::New(env, "Failed to start polling").ThrowAsJavaScriptException();
+  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) {
+          if (env == nullptr || jsCallback.IsEmpty()) {
+            return;
+          }
+          jsCallback.Call({Napi::Buffer<uint8_t>::Copy(env, packet.data(), packet.size())});
+        });
+  };
+  // 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
+  // promptly. Callback runs on the libuv thread, which only fires between JS
+  // ticks, so acquiring `device_mutex_` is safe.
+  auto error_cb = [this](const std::string& message) {
+    fprintf(stderr, "tuntap receive loop error: %s\n", message.c_str());
+    std::lock_guard<std::mutex> lock(device_mutex_);
+    polling_ = false;
+    ReleaseTsfnLocked();
+  };
+
+  std::string start_error;
+  if (!backend_->StartReceiveLoop(loop, buffer_size, std::move(packet_cb), std::move(error_cb), start_error)) {
+    ReleaseTsfnLocked();
+    Napi::Error::New(env, start_error).ThrowAsJavaScriptException();
     return env.Null();
   }
 
-  poll_handle_ = handle.release();
+  polling_ = true;
   return env.Undefined();
 }
 
-// Node-API module entrypoint.
 Napi::Object Init(Napi::Env env, Napi::Object exports) {
   return TunDevice::Init(env, exports);
 }
 
 NODE_API_MODULE(tuntap, Init)
-// #endregion
-
-// #region Private implementation details
 
 void TunDevice::CloseInternal() {
   if (is_open_.exchange(false)) {
-    StopPolling();
-    fd_.reset();
+    StopPollingLocked();
+    if (backend_) {
+      backend_->CloseDevice();
+    }
+    interface_name_.clear();
   }
 }
 
-void TunDevice::StopPolling() {
-  if (poll_handle_) {
-    uv_poll_stop(poll_handle_);
-    // Must use uv_close before freeing a libuv handle
-    uv_close(reinterpret_cast<uv_handle_t*>(poll_handle_), [](uv_handle_t* handle) {
-      delete reinterpret_cast<uv_poll_t*>(handle);
-    });
-    poll_handle_ = nullptr;
+void TunDevice::StopPollingLocked() {
+  if (polling_.exchange(false) && backend_) {
+    backend_->StopReceiveLoop();
   }
+  ReleaseTsfnLocked();
+}
+
+void TunDevice::ReleaseTsfnLocked() {
   if (tsfn_) {
     tsfn_.Release();
     tsfn_ = nullptr;
   }
 }
-
-void TunDevice::PollCallback(uv_poll_t* handle, int status, int events) {
-  if (status < 0) {
-    fprintf(stderr, "tuntap poll error: %s\n", uv_strerror(status));
-    auto* self = static_cast<TunDevice*>(handle->data);
-    if (self) {
-      self->StopPolling();
-    }
-    return;
-  }
-
-  if (!(events & UV_READABLE)) {
-    return;
-  }
-
-  auto* self = static_cast<TunDevice*>(handle->data);
-  if (!self || !self->is_open_.load() || !self->fd_.is_valid()) {
-    return;
-  }
-
-  std::vector<uint8_t> packet;
-  std::string error;
-  ReadPacketStatus read_status = self->backend_->ReadPacket(self->fd_.get(), self->poll_buffer_size_, packet, error);
-  // Backend reported an unrecoverable read failure; stop polling this fd.
-  if (read_status == ReadPacketStatus::Error) {
-    fprintf(stderr, "tuntap read error: %s\n", error.c_str());
-    self->StopPolling();
-    return;
-  }
-  // EOF/peer close: device is no longer readable, so tear down polling.
-  if (read_status == ReadPacketStatus::Closed) {
-    self->StopPolling();
-    return;
-  }
-  // Transient empty read (e.g. EAGAIN): keep poll active and wait for next event.
-  if (read_status == ReadPacketStatus::NoData) {
-    return;
-  }
-
-  self->tsfn_.BlockingCall(
-    [packet = std::move(packet)](Napi::Env env, Napi::Function jsCallback) {
-      if (env == nullptr || jsCallback.IsEmpty()) return;
-      jsCallback.Call({ Napi::Buffer<uint8_t>::Copy(env, packet.data(), packet.size()) });
-    }
-  );
-}