appium-ios-tuntap 0.1.10 → 0.2.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* Supply the package with prebuilt addon ([#31](https://github.com/appium/appium-ios-tuntap/issues/31)) ([c475d1c](https://github.com/appium/appium-ios-tuntap/commit/c475d1ce89a4b44d0ebed90f9b4b8fc519241079))
+
 ## [0.1.10](https://github.com/appium/appium-ios-tuntap/compare/v0.1.9...v0.1.10) (2026-04-13)
 
 ### Bug Fixes

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/lib/TunTap.js

@@ -1,14 +1,18 @@
 import { createRequire } from 'node:module';
 import { isIPv6 } from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { TunTapDeviceError, TunTapError, TunTapPermissionError } from './errors.js';
 import { log } from './logger.js';
 import { createTunTapPlatform } from './platform/create-platform.js';
 const require = createRequire(import.meta.url);
+/** Package root (contains binding.gyp, prebuilds/, or build/ after compile). */
+const pkgRoot = path.join(fileURLToPath(new URL('.', import.meta.url)), '..');
 const DEFAULT_READ_BUFFER_SIZE = 4096;
 const MAX_BUFFER_SIZE = 0xffff; // 65535
 const DEFAULT_MTU = 1500;
 const MIN_MTU = 1280;
-const nativeTuntap = require('../build/Release/tuntap.node');
+const nativeTuntap = require('node-gyp-build')(pkgRoot);
 /**
  * Validates an IPv6 route destination (address with optional CIDR prefix).
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-tuntap",
-  "version": "0.1.10",
+  "version": "0.2.1",
   "description": "Native TUN/TAP interface module for Node.js",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -9,19 +9,22 @@
     "clean": "rm -rf build node_modules lib",
     "build": "npx tsc",
     "build:addon": "node-gyp rebuild",
+    "build:prebuilds": "prebuildify --napi --strip",
     "lint": "eslint .",
     "lint:fix": "npm run lint -- --fix",
     "format": "prettier -w ./src ./test",
     "format:check": "prettier --check ./src ./test",
-    "prepare": "npm run build:addon && npm run build",
+    "install": "node-gyp-build",
+    "prepare": "npm run build",
     "test": "sudo npm run test:integration && npm run test:unit",
     "test:unit": "sudo npx mocha 'test/tuntap-unit.spec.mjs' --exit --timeout 2m",
     "test:integration": "sudo npx mocha 'test/tuntap-integration.spec.mjs' --exit --timeout 2m"
   },
   "files": [
     "src/tuntap.cc",
+    "src/native",
     "lib",
-    "build",
+    "prebuilds",
     "binding.gyp",
     "package.json",
     "README.md",
@@ -45,6 +48,7 @@
   "dependencies": {
     "@appium/support": "^7.0.0-rc.1",
     "node-addon-api": "^8.5.0",
+    "node-gyp-build": "^4.8.4",
     "typescript": "^6.0.2"
   },
   "devDependencies": {
@@ -54,7 +58,8 @@
     "@types/node": "^25.0.1",
     "conventional-changelog-conventionalcommits": "^9.0.0",
     "semantic-release": "^25.0.2",
-    "prettier": "^3.0.0"
+    "prettier": "^3.0.0",
+    "prebuildify": "^6.0.1"
   },
   "prettier": {
     "bracketSpacing": false,

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
+