feat: Add Headscale support for WAN peer discovery

Cargo.toml

@@ -75,9 +75,14 @@ ahash = "0.8"
 # Tracing/logging
 log = "0.4"
 
+# Serialization
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
 # networking
 libp2p = "0.56"
 libp2p-tcp = "0.44"
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
 
 [workspace.lints.rust]
 static_mut_refs = "warn"      # Or use "warn" instead of deny

rust/exo_pyo3_bindings/exo_pyo3_bindings.pyi

@@ -11,6 +11,34 @@ class AllQueuesFullError(builtins.Exception):
     def __repr__(self) -> builtins.str: ...
     def __str__(self) -> builtins.str: ...
 
+@typing.final
+class HeadscaleConfig:
+    r"""
+    Configuration for Headscale-based peer discovery.
+    """
+    @property
+    def api_base_url(self) -> builtins.str:
+        r"""
+        Base URL for the Headscale API (e.g., "https://headscale.example.com")
+        """
+    @property
+    def api_key(self) -> builtins.str:
+        r"""
+        API key for authenticating with the Headscale API
+        """
+    @property
+    def poll_interval_secs(self) -> builtins.int:
+        r"""
+        How often to poll the Headscale API for peer updates (in seconds)
+        """
+    @property
+    def exo_port(self) -> builtins.int:
+        r"""
+        The port that exo is listening on
+        """
+    def __new__(cls, api_base_url: builtins.str, api_key: builtins.str, poll_interval_secs: builtins.int = 5, exo_port: builtins.int = 52415) -> HeadscaleConfig: ...
+    def __repr__(self) -> builtins.str: ...
+
 @typing.final
 class ConnectionUpdate:
     @property
@@ -130,7 +158,16 @@ class Multiaddr:
 
 @typing.final
 class NetworkingHandle:
-    def __new__(cls, identity: Keypair) -> NetworkingHandle: ...
+    def __new__(cls, identity: Keypair, headscale_config: HeadscaleConfig | None = None) -> NetworkingHandle:
+        r"""
+        Create a new NetworkingHandle.
+
+        Args:
+            identity: The keypair identity for this node
+            headscale_config: Optional Headscale configuration for WAN peer discovery.
+                              If provided, peers will be discovered via the Headscale API
+                              in addition to local mDNS discovery.
+        """
     async def connection_update_recv(self) -> ConnectionUpdate:
         r"""
         Receives the next `ConnectionUpdate` from networking.

rust/exo_pyo3_bindings/src/allow_threading.rs

@@ -6,7 +6,7 @@ use pyo3::marker::Ungil;
 use pyo3::prelude::*;
 use std::{
     future::Future,
-    pin::{Pin, pin},
+    pin::{pin, Pin},
     task::{Context, Poll},
 };
 

rust/exo_pyo3_bindings/src/examples/mod.rs

@@ -11,12 +11,12 @@
 //!  - For sync code: take `&mut self` and `.get_mut()`
 
 use crate::ext::{PyResultExt as _, ResultExt as _, TokioRuntimeExt as _};
-use futures::FutureExt as _;
 use futures::future::BoxFuture;
+use futures::FutureExt as _;
 use pyo3::exceptions::PyRuntimeError;
 use pyo3::prelude::{PyModule, PyModuleMethods as _};
 use pyo3::{
-    Bound, Py, PyAny, PyErr, PyResult, PyTraverseError, PyVisit, Python, pyclass, pymethods,
+    pyclass, pymethods, Bound, Py, PyAny, PyErr, PyResult, PyTraverseError, PyVisit, Python,
 };
 use std::time::Duration;
 use tokio::sync::mpsc;

rust/exo_pyo3_bindings/src/lib.rs

@@ -26,7 +26,7 @@ use crate::pylibp2p::ident::ident_submodule;
 use crate::pylibp2p::multiaddr::multiaddr_submodule;
 use pyo3::prelude::PyModule;
 use pyo3::prelude::*;
-use pyo3::{Bound, PyResult, pyclass, pymodule};
+use pyo3::{pyclass, pymodule, Bound, PyResult};
 use pyo3_stub_gen::define_stub_info_gatherer;
 
 /// Namespace for all the constants used by this crate.