feat: enable network interface selection

impit-node/src/impit_builder.rs

@@ -2,9 +2,9 @@ use std::time::Duration;
 
 use impit::{
   emulation::Browser as ImpitBrowser,
-  impit::{ImpitBuilder, RedirectBehavior},
+  impit::{ImpitBuilder, Interface as InnerInterface, IpKind as InnerIpKind, RedirectBehavior},
 };
-use napi::{bindgen_prelude::Object, Env};
+use napi::{bindgen_prelude::Object, Either, Env};
 use napi_derive::napi;
 
 use crate::request::NodeCookieJar;
@@ -27,6 +27,27 @@ impl From<Browser> for ImpitBrowser {
   }
 }
 
+#[napi(string_enum = "lowercase")]
+pub enum IpKind {
+  V4,
+  V6,
+}
+
+impl From<IpKind> for InnerIpKind {
+  fn from(val: IpKind) -> Self {
+    match val {
+      IpKind::V4 => InnerIpKind::V4,
+      IpKind::V6 => InnerIpKind::V6,
+    }
+  }
+}
+
+#[napi(object)]
+pub struct Interface {
+  pub name: String,
+  pub kind: Option<IpKind>,
+}
+
 /// Options for configuring an {@link Impit} instance.
 ///
 /// These options allow you to customize the behavior of the Impit instance, including browser emulation, TLS settings, proxy configuration, timeouts, and more.
@@ -94,6 +115,13 @@ pub struct ImpitOptions<'a> {
   ///
   /// @default `undefined` (the OS will choose the local address)
   pub local_address: Option<String>,
+  /// Network interface to bind the client to.
+  ///
+  /// Can be a name of the interface (e.g. "eth0") or a more complex structure
+  /// describing the interface.
+  ///
+  /// Note that `interface` is mutually exclusive with `localAddress`, i.e. only one of them can be set at a time.
+  pub interface: Option<Either<String, Interface>>,
 }
 
 impl ImpitOptions<'_> {
@@ -140,12 +168,36 @@ impl ImpitOptions<'_> {
       config = config.with_redirect(RedirectBehavior::FollowRedirect(max_redirects));
     }
 
-    if let Some(local_address) = self.local_address {
+    if let Some(local_address) = self.local_address.clone() {
       config = config
         .with_local_address(local_address)
         .map_err(|e| napi::Error::from_reason(e.to_string()))?;
     }
 
+    if let Some(interface) = self.interface {
+      if self.local_address.is_some() {
+        return Err(napi::Error::from_reason(
+          "Both interface and local_address cannot be provided at the same time.".to_string(),
+        ));
+      }
+
+      match interface {
+        Either::A(name) => {
+          config = config
+            .with_interface(InnerInterface { name, kind: None })
+            .map_err(|e| napi::Error::from_reason(e.to_string()))?;
+        }
+        Either::B(interface) => {
+          config = config
+            .with_interface(InnerInterface {
+              name: interface.name,
+              kind: interface.kind.map(|f| f.into()),
+            })
+            .map_err(|e| napi::Error::from_reason(e.to_string()))?;
+        }
+      }
+    }
+
     Ok(config)
   }
 }

impit-node/test/basics.test.ts

@@ -265,6 +265,24 @@ describe.each([
 
             expect(json.ip).toBe(remoteAddress);
         });
+
+        test.each([
+            ['ipv4', '::ffff:127.0.0.1'],
+            ['ipv6', '::1']
+        ])('interface family works', async (family, remoteAddress) => {
+            const impit = new Impit({
+                browser,
+                interface: {
+                    name: 'lo',
+                    kind: family
+                }
+            });
+
+            const response = await impit.fetch(new URL('/socket', "http://localhost:3001").href);
+            const json = await response.json();
+
+            expect(json.ip).toBe(remoteAddress);
+        });
     });
 
     describe('Request body', () => {