appium-ios-tuntap 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.2.1](https://github.com/appium/appium-ios-tuntap/compare/v0.2.0...v0.2.1) (2026-04-13)
+
+### Miscellaneous Chores
+
+* Refactor native tuntap implementation ([#33](https://github.com/appium/appium-ios-tuntap/issues/33)) ([c24636e](https://github.com/appium/appium-ios-tuntap/commit/c24636ed054dd37a36a08b6b5c09bfd7f40d55b1))
+
 ## [0.2.0](https://github.com/appium/appium-ios-tuntap/compare/v0.1.10...v0.2.0) (2026-04-13)
 
 ### Features

package/binding.gyp

@@ -2,7 +2,11 @@
   "targets": [
     {
       "target_name": "tuntap",
-      "sources": [ "src/tuntap.cc" ],
+      "sources": [
+        "src/tuntap.cc",
+        "src/native/file_descriptor.cc",
+        "src/native/tun_backend_common.cc"
+      ],
       "include_dirs": [
         "<!@(node -p \"require('node-addon-api').include\")"
       ],
@@ -60,6 +64,9 @@
       ],
       "conditions": [
         ["OS=='linux'", {
+          "sources": [
+            "src/native/tun_backend_linux.cc"
+          ],
           "cflags": [
             "-pthread"
           ],
@@ -71,6 +78,9 @@
           ]
         }],
         ["OS=='mac'", {
+          "sources": [
+            "src/native/tun_backend_darwin.cc"
+          ],
           "xcode_settings": {
             "OTHER_LDFLAGS": [
               "-framework", "SystemConfiguration",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-tuntap",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Native TUN/TAP interface module for Node.js",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -22,6 +22,7 @@
   },
   "files": [
     "src/tuntap.cc",
+    "src/native",
     "lib",
     "prebuilds",
     "binding.gyp",

package/src/native/file_descriptor.cc

@@ -0,0 +1,49 @@
+#include "file_descriptor.h"
+
+#include <unistd.h>
+
+FileDescriptor::FileDescriptor() : fd_(-1) {}
+
+FileDescriptor::FileDescriptor(int fd) : fd_(fd) {}
+
+FileDescriptor::~FileDescriptor() {
+  if (fd_ >= 0) {
+    ::close(fd_);
+  }
+}
+
+FileDescriptor::FileDescriptor(FileDescriptor&& other) noexcept : fd_(other.fd_) {
+  other.fd_ = -1;
+}
+
+FileDescriptor& FileDescriptor::operator=(FileDescriptor&& other) noexcept {
+  if (this != &other) {
+    if (fd_ >= 0) {
+      ::close(fd_);
+    }
+    fd_ = other.fd_;
+    other.fd_ = -1;
+  }
+  return *this;
+}
+
+int FileDescriptor::get() const {
+  return fd_;
+}
+
+int FileDescriptor::release() {
+  int temp = fd_;
+  fd_ = -1;
+  return temp;
+}
+
+bool FileDescriptor::is_valid() const {
+  return fd_ >= 0;
+}
+
+void FileDescriptor::reset(int fd) {
+  if (fd_ >= 0) {
+    ::close(fd_);
+  }
+  fd_ = fd;
+}

package/src/native/file_descriptor.h

@@ -0,0 +1,22 @@
+#pragma once
+
+class FileDescriptor {
+public:
+  FileDescriptor();
+  explicit FileDescriptor(int fd);
+  ~FileDescriptor();
+
+  FileDescriptor(const FileDescriptor&) = delete;
+  FileDescriptor& operator=(const FileDescriptor&) = delete;
+
+  FileDescriptor(FileDescriptor&& other) noexcept;
+  FileDescriptor& operator=(FileDescriptor&& other) noexcept;
+
+  int get() const;
+  int release();
+  bool is_valid() const;
+  void reset(int fd = -1);
+
+private:
+  int fd_;
+};

package/src/native/tun_backend.h

@@ -0,0 +1,38 @@
+#pragma once
+
+#if !defined(__linux__) && !defined(__APPLE__)
+#error "appium-ios-tuntap native addon supports only Linux and macOS"
+#endif
+
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <sys/types.h>
+#include <vector>
+
+#include "file_descriptor.h"
+
+struct OpenResult {
+  FileDescriptor fd;
+  std::string interface_name;
+};
+
+enum class ReadPacketStatus {
+  Data,
+  NoData,
+  Closed,
+  Error,
+};
+
+class TunPlatformBackend {
+public:
+  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;
+};
+
+bool SetNonBlocking(int fd, std::string& error);
+std::unique_ptr<TunPlatformBackend> CreatePlatformBackend();
+

package/src/native/tun_backend_common.cc

@@ -0,0 +1,27 @@
+#include "tun_backend.h"
+
+#include <errno.h>
+#include <fcntl.h>
+#include <string.h>
+
+std::unique_ptr<TunPlatformBackend> CreatePlatformTunBackend();
+
+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;
+}
+
+std::unique_ptr<TunPlatformBackend> CreatePlatformBackend() {
+  return CreatePlatformTunBackend();
+}
+

package/src/native/tun_backend_darwin.cc

@@ -0,0 +1,152 @@
+#ifdef __APPLE__
+
+#include "tun_backend.h"
+
+#include <errno.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/kern_control.h>
+#include <sys/socket.h>
+#include <sys/sys_domain.h>
+#include <unistd.h>
+
+#include <net/if_utun.h>
+#include <netinet/in.h>
+#include <netinet6/in6_var.h>
+
+#define UTUN_CONTROL_NAME "com.apple.net.utun_control"
+
+namespace {
+
+class DarwinTunBackend : public TunPlatformBackend {
+public:
+  static constexpr size_t kUtunHeaderSize = 4;
+
+  bool OpenDevice(const std::string& requested_name, OpenResult& out, std::string& error) override {
+    struct ctl_info ctl_info;
+    struct sockaddr_ctl socket_addr;
+
+    FileDescriptor temp_fd(socket(PF_SYSTEM, SOCK_DGRAM, SYSPROTO_CONTROL));
+    if (!temp_fd.is_valid()) {
+      error = std::string("Failed to create control socket: ") + strerror(errno);
+      return false;
+    }
+
+    memset(&ctl_info, 0, sizeof(ctl_info));
+    strncpy(ctl_info.ctl_name, UTUN_CONTROL_NAME, sizeof(ctl_info.ctl_name) - 1);
+    ctl_info.ctl_name[sizeof(ctl_info.ctl_name) - 1] = '\0';
+
+    if (ioctl(temp_fd.get(), CTLIOCGINFO, &ctl_info) < 0) {
+      error = std::string("Failed to get utun control info: ") + strerror(errno);
+      return false;
+    }
+
+    memset(&socket_addr, 0, sizeof(socket_addr));
+    socket_addr.sc_len = sizeof(socket_addr);
+    socket_addr.sc_family = AF_SYSTEM;
+    socket_addr.ss_sysaddr = SYSPROTO_CONTROL;
+    socket_addr.sc_id = ctl_info.ctl_id;
+
+    int utun_unit = ParseRequestedUtunUnit(requested_name);
+    if (utun_unit > 0) {
+      socket_addr.sc_unit = utun_unit;
+      if (connect(temp_fd.get(), reinterpret_cast<struct sockaddr*>(&socket_addr), sizeof(socket_addr)) < 0) {
+        error = std::string("Failed to connect to utun with specified unit: ") + strerror(errno);
+        return false;
+      }
+    } else if (!ConnectFirstAvailableUnit(temp_fd.get(), socket_addr, error)) {
+      return false;
+    }
+
+    char interface_name[20];
+    socklen_t interface_name_len = sizeof(interface_name);
+    if (getsockopt(temp_fd.get(), SYSPROTO_CONTROL, UTUN_OPT_IFNAME, interface_name, &interface_name_len) < 0) {
+      error = std::string("Failed to get utun interface name: ") + strerror(errno);
+      return false;
+    }
+
+    out.fd = std::move(temp_fd);
+    out.interface_name = std::string(interface_name);
+    return true;
+  }
+
+  ReadPacketStatus ReadPacket(int fd, size_t max_payload_size, std::vector<uint8_t>& out, std::string& error) override {
+    out.resize(max_payload_size + kUtunHeaderSize);
+    ssize_t bytes_read = read(fd, out.data(), out.size());
+    if (bytes_read < 0) {
+      if (errno == EAGAIN || errno == EWOULDBLOCK) {
+        out.clear();
+        return ReadPacketStatus::NoData;
+      }
+      error = std::string("Read error: ") + strerror(errno);
+      return ReadPacketStatus::Error;
+    }
+    if (bytes_read == 0) {
+      out.clear();
+      return ReadPacketStatus::Closed;
+    }
+    if (bytes_read <= static_cast<ssize_t>(kUtunHeaderSize)) {
+      out.clear();
+      return ReadPacketStatus::NoData;
+    }
+
+    const auto payload_len = static_cast<size_t>(bytes_read - kUtunHeaderSize);
+    // Collapse the utun 4-byte address-family prefix in-place.
+    memmove(out.data(), out.data() + kUtunHeaderSize, payload_len);
+    out.resize(payload_len);
+    return ReadPacketStatus::Data;
+  }
+
+  ssize_t WritePacket(int fd, const uint8_t* data, size_t length, std::string& error) override {
+    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());
+    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;
+  }
+
+private:
+  static int ParseRequestedUtunUnit(const std::string& requested_name) {
+    if (requested_name.empty() || requested_name.find("utun") != 0) {
+      return 0;
+    }
+    try {
+      return std::stoi(requested_name.substr(4)) + 1;
+    } catch (...) {
+      return 0;
+    }
+  }
+
+  static bool ConnectFirstAvailableUnit(int fd, struct sockaddr_ctl& socket_addr, std::string& error) {
+    for (socket_addr.sc_unit = 1; socket_addr.sc_unit < 255; socket_addr.sc_unit++) {
+      if (connect(fd, reinterpret_cast<struct sockaddr*>(&socket_addr), sizeof(socket_addr)) == 0) {
+        return true;
+      }
+      if (errno != EBUSY) {
+        error = std::string("Failed to connect to utun control socket: ") + strerror(errno);
+        return false;
+      }
+    }
+
+    error = "Could not find an available utun device";
+    return false;
+  }
+};
+
+} // namespace
+
+std::unique_ptr<TunPlatformBackend> CreatePlatformTunBackend() {
+  return std::make_unique<DarwinTunBackend>();
+}
+
+#endif
+

package/src/native/tun_backend_linux.cc

@@ -0,0 +1,94 @@
+#ifdef __linux__
+
+#include "tun_backend.h"
+
+#include <errno.h>
+#include <fcntl.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <linux/if.h>
+#include <linux/if_tun.h>
+
+namespace {
+constexpr const char* kTunDevicePath = "/dev/net/tun";
+
+class LinuxTunBackend : public TunPlatformBackend {
+public:
+  bool OpenDevice(const std::string& requested_name, OpenResult& out, 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).";
+      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.";
+      return false;
+    }
+
+    struct ifreq ifr;
+    memset(&ifr, 0, sizeof(ifr));
+    ifr.ifr_flags = IFF_TUN | IFF_NO_PI;
+
+    if (!requested_name.empty()) {
+      strncpy(ifr.ifr_name, requested_name.c_str(), IFNAMSIZ - 1);
+      ifr.ifr_name[IFNAMSIZ - 1] = '\0';
+    }
+
+    if (ioctl(temp_fd.get(), TUNSETIFF, &ifr) < 0) {
+      error = std::string("Failed to configure TUN device: ") + strerror(errno);
+      return false;
+    }
+
+    out.fd = std::move(temp_fd);
+    out.interface_name = std::string(ifr.ifr_name);
+    return true;
+  }
+
+  ReadPacketStatus ReadPacket(int fd, size_t max_payload_size, std::vector<uint8_t>& out, std::string& error) override {
+    out.resize(max_payload_size);
+    ssize_t bytes_read = read(fd, out.data(), out.size());
+    if (bytes_read < 0) {
+      if (errno == EAGAIN || errno == EWOULDBLOCK) {
+        out.clear();
+        return ReadPacketStatus::NoData;
+      }
+      error = std::string("Read error: ") + strerror(errno);
+      return ReadPacketStatus::Error;
+    }
+    if (bytes_read == 0) {
+      out.clear();
+      return ReadPacketStatus::Closed;
+    }
+
+    out.resize(static_cast<size_t>(bytes_read));
+    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);
+    if (bytes_written < 0) {
+      error = std::string("Write error: ") + strerror(errno);
+      return -1;
+    }
+    return bytes_written;
+  }
+};
+
+} // namespace
+
+std::unique_ptr<TunPlatformBackend> CreatePlatformTunBackend() {
+  return std::make_unique<LinuxTunBackend>();
+}
+
+#endif
+

package/src/tuntap.cc

@@ -1,82 +1,15 @@
 #include <napi.h>
-#include <unistd.h>
-#include <fcntl.h>
+#include <uv.h>
+
 #include <string>
-#include <string.h>
-#include <errno.h>
-#include <sys/ioctl.h>
 #include <vector>
 #include <memory>
 #include <mutex>
 #include <atomic>
-#include <uv.h>
-
-#ifdef __APPLE__
-#include <sys/kern_control.h>
-#include <sys/socket.h>
-#include <sys/sys_domain.h>
-#include <net/if_utun.h>
-#include <netinet/in.h>
-#include <netinet6/in6_var.h>
-#define UTUN_CONTROL_NAME "com.apple.net.utun_control"
-#define UTUN_HEADER_SIZE 4
-#else
-#include <linux/if.h>
-#include <linux/if_tun.h>
-#include <sys/stat.h>
-#define UTUN_HEADER_SIZE 0
-#endif
-
-// RAII wrapper for file descriptors
-class FileDescriptor {
-private:
-  int fd_;
-
-public:
-  FileDescriptor() : fd_(-1) {}
-  explicit FileDescriptor(int fd) : fd_(fd) {}
-
-  ~FileDescriptor() {
-    if (fd_ >= 0) {
-      ::close(fd_);
-    }
-  }
-
-  FileDescriptor(const FileDescriptor&) = delete;
-  FileDescriptor& operator=(const FileDescriptor&) = delete;
-
-  FileDescriptor(FileDescriptor&& other) noexcept : fd_(other.fd_) {
-    other.fd_ = -1;
-  }
-
-  FileDescriptor& operator=(FileDescriptor&& other) noexcept {
-    if (this != &other) {
-      if (fd_ >= 0) {
-        ::close(fd_);
-      }
-      fd_ = other.fd_;
-      other.fd_ = -1;
-    }
-    return *this;
-  }
+#include <cstdio>
 
-  int get() const { return fd_; }
-
-  int release() {
-    int temp = fd_;
-    fd_ = -1;
-    return temp;
-  }
-
-  bool is_valid() const { return fd_ >= 0; }
-
-  void reset(int fd = -1) {
-    if (fd_ >= 0) {
-      ::close(fd_);
-    }
-    fd_ = fd;
-  }
-};
+#include "native/file_descriptor.h"
+#include "native/tun_backend.h"
 
 class TunDevice : public Napi::ObjectWrap<TunDevice> {
 public:
@@ -99,6 +32,7 @@ private:
 
   FileDescriptor fd_;
   std::string name_;
+  std::unique_ptr<TunPlatformBackend> backend_;
   std::atomic<bool> is_open_;
   std::mutex device_mutex_;
 
@@ -113,6 +47,7 @@ private:
 
 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);
 
@@ -133,8 +68,9 @@ 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), is_open_(false) {
+  : Napi::ObjectWrap<TunDevice>(info), backend_(CreatePlatformBackend()), is_open_(false) {
   Napi::Env env = info.Env();
   Napi::HandleScope scope(env);
 
@@ -143,18 +79,14 @@ TunDevice::TunDevice(const Napi::CallbackInfo& info)
   }
 }
 
+// Ensures fd/poll resources are closed when object is destroyed.
 TunDevice::~TunDevice() {
   std::lock_guard<std::mutex> lock(device_mutex_);
   CloseInternal();
 }
 
-void TunDevice::CloseInternal() {
-  if (is_open_.exchange(false)) {
-    StopPolling();
-    fd_.reset();
-  }
-}
-
+// 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_);
@@ -162,140 +94,33 @@ Napi::Value TunDevice::Open(const Napi::CallbackInfo& info) {
   if (is_open_) {
     return Napi::Boolean::New(env, true);
   }
-
-#ifdef __APPLE__
-  // macOS: create utun interface via PF_SYSTEM control socket
-  struct ctl_info ctlInfo;
-  struct sockaddr_ctl sc;
-
-  FileDescriptor temp_fd(socket(PF_SYSTEM, SOCK_DGRAM, SYSPROTO_CONTROL));
-  if (!temp_fd.is_valid()) {
-    Napi::Error::New(env, std::string("Failed to create control socket: ") + strerror(errno))
+  if (!backend_) {
+    Napi::Error::New(env, "Unsupported platform: no native TUN backend available")
       .ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
-  memset(&ctlInfo, 0, sizeof(ctlInfo));
-  strncpy(ctlInfo.ctl_name, UTUN_CONTROL_NAME, sizeof(ctlInfo.ctl_name) - 1);
-  ctlInfo.ctl_name[sizeof(ctlInfo.ctl_name) - 1] = '\0';
-
-  if (ioctl(temp_fd.get(), CTLIOCGINFO, &ctlInfo) < 0) {
-    Napi::Error::New(env, std::string("Failed to get utun control info: ") + strerror(errno))
-      .ThrowAsJavaScriptException();
+  OpenResult result;
+  std::string error;
+  if (!backend_->OpenDevice(name_, result, error)) {
+    Napi::Error::New(env, error).ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
-  memset(&sc, 0, sizeof(sc));
-  sc.sc_len = sizeof(sc);
-  sc.sc_family = AF_SYSTEM;
-  sc.ss_sysaddr = SYSPROTO_CONTROL;
-  sc.sc_id = ctlInfo.ctl_id;
-
-  // Parse utun number if provided, otherwise auto-select (utun0 = unit 1)
-  int utun_unit = 0;
-  if (!name_.empty() && name_.find("utun") == 0) {
-    try {
-      utun_unit = std::stoi(name_.substr(4)) + 1; // +1 because kernel uses unit=1 for utun0
-    } catch(...) {
-      utun_unit = 0;
-    }
-  }
-
-  if (utun_unit > 0) {
-    sc.sc_unit = utun_unit;
-    if (connect(temp_fd.get(), (struct sockaddr*)&sc, sizeof(sc)) < 0) {
-      Napi::Error::New(env, std::string("Failed to connect to utun with specified unit: ") + strerror(errno))
-        .ThrowAsJavaScriptException();
-      return Napi::Boolean::New(env, false);
-    }
-  } else {
-    bool connected = false;
-    for (sc.sc_unit = 1; sc.sc_unit < 255; sc.sc_unit++) {
-      if (connect(temp_fd.get(), (struct sockaddr*)&sc, sizeof(sc)) == 0) {
-        connected = true;
-        break;
-      } else if (errno != EBUSY) {
-        Napi::Error::New(env, std::string("Failed to connect to utun control socket: ") + strerror(errno))
-          .ThrowAsJavaScriptException();
-        return Napi::Boolean::New(env, false);
-      }
-    }
-
-    if (!connected) {
-      Napi::Error::New(env, "Could not find an available utun device").ThrowAsJavaScriptException();
-      return Napi::Boolean::New(env, false);
-    }
-  }
-
-  char utunname[20];
-  socklen_t utunname_len = sizeof(utunname);
-  if (getsockopt(temp_fd.get(), SYSPROTO_CONTROL, UTUN_OPT_IFNAME, utunname, &utunname_len) < 0) {
-    Napi::Error::New(env, std::string("Failed to get utun interface name: ") + strerror(errno))
-      .ThrowAsJavaScriptException();
-    return Napi::Boolean::New(env, false);
-  }
-
-  name_ = std::string(utunname);
-
-#else
-  // Linux: create TUN device via /dev/net/tun
-  struct stat statbuf;
-  if (stat("/dev/net/tun", &statbuf) != 0) {
-    Napi::Error::New(env,
-      "TUN/TAP device not available: /dev/net/tun does not exist. "
-      "Please ensure the TUN/TAP kernel module is loaded (modprobe tun).")
-      .ThrowAsJavaScriptException();
+  if (!SetNonBlocking(result.fd.get(), error)) {
+    Napi::Error::New(env, error).ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
-  FileDescriptor temp_fd(open("/dev/net/tun", O_RDWR));
-  if (!temp_fd.is_valid()) {
-    Napi::Error::New(env,
-      std::string("Failed to open /dev/net/tun: ") + strerror(errno) +
-      ". This usually means you don't have sufficient permissions. "
-      "Try running with sudo or add your user to the 'tun' group.")
-      .ThrowAsJavaScriptException();
-    return Napi::Boolean::New(env, false);
-  }
-
-  struct ifreq ifr;
-  memset(&ifr, 0, sizeof(ifr));
-  ifr.ifr_flags = IFF_TUN | IFF_NO_PI;
-
-  if (!name_.empty()) {
-    strncpy(ifr.ifr_name, name_.c_str(), IFNAMSIZ - 1);
-    ifr.ifr_name[IFNAMSIZ - 1] = '\0';
-  }
-
-  if (ioctl(temp_fd.get(), TUNSETIFF, &ifr) < 0) {
-    Napi::Error::New(env, std::string("Failed to configure TUN device: ") + strerror(errno))
-      .ThrowAsJavaScriptException();
-    return Napi::Boolean::New(env, false);
-  }
-
-  name_ = std::string(ifr.ifr_name);
-#endif
-
-  // Set non-blocking mode
-  int flags = fcntl(temp_fd.get(), F_GETFL, 0);
-  if (flags < 0) {
-    Napi::Error::New(env, std::string("Failed to get file descriptor flags: ") + strerror(errno))
-      .ThrowAsJavaScriptException();
-    return Napi::Boolean::New(env, false);
-  }
-
-  if (fcntl(temp_fd.get(), F_SETFL, flags | O_NONBLOCK) < 0) {
-    Napi::Error::New(env, std::string("Failed to set non-blocking mode: ") + strerror(errno))
-      .ThrowAsJavaScriptException();
-    return Napi::Boolean::New(env, false);
-  }
-
-  fd_ = std::move(temp_fd);
+  fd_ = std::move(result.fd);
+  name_ = result.interface_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_);
@@ -303,6 +128,8 @@ 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_);
@@ -321,38 +148,22 @@ Napi::Value TunDevice::Read(const Napi::CallbackInfo& info) {
     }
   }
 
-#ifdef __APPLE__
-  // macOS: reads include a 4-byte protocol family prefix that must be stripped
-  std::vector<uint8_t> raw(buffer_size + 4);
-  ssize_t n = read(fd_.get(), raw.data(), raw.size());
-  if (n <= 0) {
-    if (errno == EAGAIN || errno == EWOULDBLOCK) {
-      return Napi::Buffer<uint8_t>::New(env, 0);
-    }
-    Napi::Error::New(env, std::string("Read error: ") + strerror(errno))
-      .ThrowAsJavaScriptException();
+  std::vector<uint8_t> packet;
+  std::string error;
+  ReadPacketStatus read_status = backend_->ReadPacket(fd_.get(), buffer_size, packet, error);
+  if (read_status == ReadPacketStatus::Error) {
+    Napi::Error::New(env, error).ThrowAsJavaScriptException();
     return env.Null();
   }
-  if (n <= 4) {
+  if (read_status == ReadPacketStatus::NoData || read_status == ReadPacketStatus::Closed) {
     return Napi::Buffer<uint8_t>::New(env, 0);
   }
-  return Napi::Buffer<uint8_t>::Copy(env, raw.data() + 4, n - 4);
-#else
-  // Linux: raw IP packets directly
-  std::vector<uint8_t> raw(buffer_size);
-  ssize_t n = read(fd_.get(), raw.data(), raw.size());
-  if (n < 0) {
-    if (errno == EAGAIN || errno == EWOULDBLOCK) {
-      return Napi::Buffer<uint8_t>::New(env, 0);
-    }
-    Napi::Error::New(env, std::string("Read error: ") + strerror(errno))
-      .ThrowAsJavaScriptException();
-    return env.Null();
-  }
-  return Napi::Buffer<uint8_t>::Copy(env, raw.data(), n);
-#endif
+
+  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_);
@@ -371,41 +182,31 @@ Napi::Value TunDevice::Write(const Napi::CallbackInfo& info) {
   uint8_t* data = buffer.Data();
   size_t length = buffer.Length();
 
-#ifdef __APPLE__
-  // macOS: prepend 4-byte AF_INET6 protocol family header
-  std::vector<uint8_t> frame(length + 4);
-  uint32_t family = htonl(AF_INET6);
-  memcpy(frame.data(), &family, 4);
-  memcpy(frame.data() + 4, data, length);
-
-  ssize_t bytes_written = write(fd_.get(), frame.data(), frame.size());
-  if (bytes_written < 0) {
-    Napi::Error::New(env, std::string("Write error: ") + strerror(errno))
-      .ThrowAsJavaScriptException();
-    return Napi::Number::New(env, -1);
-  }
-  return Napi::Number::New(env, bytes_written > 4 ? bytes_written - 4 : 0);
-#else
-  ssize_t bytes_written = write(fd_.get(), data, length);
+  std::string error;
+  ssize_t bytes_written = backend_->WritePacket(fd_.get(), data, length, error);
   if (bytes_written < 0) {
-    Napi::Error::New(env, std::string("Write error: ") + strerror(errno))
-      .ThrowAsJavaScriptException();
+    Napi::Error::New(env, error).ThrowAsJavaScriptException();
     return Napi::Number::New(env, -1);
   }
   return Napi::Number::New(env, bytes_written);
-#endif
 }
 
+// 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_);
 }
 
+// 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());
 }
 
+// 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_);
@@ -474,6 +275,23 @@ Napi::Value TunDevice::StartPolling(const Napi::CallbackInfo& info) {
   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();
+  }
+}
+
 void TunDevice::StopPolling() {
   if (poll_handle_) {
     uv_poll_stop(poll_handle_);
@@ -508,33 +326,29 @@ void TunDevice::PollCallback(uv_poll_t* handle, int status, int events) {
     return;
   }
 
-  std::vector<uint8_t> buffer(self->poll_buffer_size_ + UTUN_HEADER_SIZE);
-  ssize_t bytes_read = read(self->fd_.get(), buffer.data(), buffer.size());
-
-  if (bytes_read == 0) {
+  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;
   }
-  if (bytes_read < 0) {
-    if (errno != EAGAIN && errno != EWOULDBLOCK) {
-      fprintf(stderr, "tuntap read error: %s\n", strerror(errno));
-      self->StopPolling();
-    }
+  // EOF/peer close: device is no longer readable, so tear down polling.
+  if (read_status == ReadPacketStatus::Closed) {
+    self->StopPolling();
     return;
   }
-
-  if (bytes_read > UTUN_HEADER_SIZE) {
-    self->tsfn_.BlockingCall(
-      [buf = std::move(buffer), bytes_read](Napi::Env env, Napi::Function jsCallback) {
-        if (env == nullptr || jsCallback.IsEmpty()) return;
-        jsCallback.Call({ Napi::Buffer<uint8_t>::Copy(env, buf.data() + UTUN_HEADER_SIZE, bytes_read - UTUN_HEADER_SIZE) });
-      }
-    );
+  // Transient empty read (e.g. EAGAIN): keep poll active and wait for next event.
+  if (read_status == ReadPacketStatus::NoData) {
+    return;
   }
-}
 
-Napi::Object Init(Napi::Env env, Napi::Object exports) {
-  return TunDevice::Init(env, exports);
+  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()) });
+    }
+  );
 }
-
-NODE_API_MODULE(tuntap, Init)