@cc-remote/iroh 1.0.0-rc.3

package/src/services.rs

@@ -0,0 +1,167 @@
+use std::time::Duration;
+
+use iroh_services::{Client, ClientBuilder};
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::Endpoint;
+
+/// Build options for [`ServicesClient`].
+#[derive(Debug, Default)]
+#[napi(object)]
+pub struct ServicesOptions {
+    /// Encoded API secret string (`services1...`).
+    pub api_secret: Option<String>,
+    /// If true, read the API secret from `IROH_SERVICES_API_SECRET`.
+    pub api_secret_from_env: Option<bool>,
+    /// Unencrypted PEM-encoded OpenSSH ed25519 private key.
+    pub ssh_key_pem: Option<String>,
+    /// Optional endpoint name to register cloud-side.
+    pub name: Option<String>,
+    /// Metrics push interval (ms). `0` disables interval pushes.
+    pub metrics_interval_ms: Option<i64>,
+}
+
+/// Flattened summary of an `iroh_services` diagnostics report.
+#[derive(Debug, Clone)]
+#[napi(object)]
+pub struct DiagnosticsSummary {
+    pub endpoint_id: String,
+    pub direct_addrs: Vec<String>,
+    pub iroh_version: String,
+    pub iroh_services_version: String,
+    pub has_net_report: bool,
+    pub upnp: Option<bool>,
+    pub pcp: Option<bool>,
+    pub nat_pmp: Option<bool>,
+}
+
+impl From<iroh_services::net_diagnostics::DiagnosticsReport> for DiagnosticsSummary {
+    fn from(r: iroh_services::net_diagnostics::DiagnosticsReport) -> Self {
+        let (upnp, pcp, nat_pmp) = match r.portmap_probe {
+            Some(p) => (Some(p.upnp), Some(p.pcp), Some(p.nat_pmp)),
+            None => (None, None, None),
+        };
+        Self {
+            endpoint_id: r.endpoint_id.to_string(),
+            direct_addrs: r.direct_addrs.into_iter().map(|s| s.to_string()).collect(),
+            iroh_version: r.iroh_version,
+            iroh_services_version: r.iroh_services_version,
+            has_net_report: r.net_report.is_some(),
+            upnp,
+            pcp,
+            nat_pmp,
+        }
+    }
+}
+
+/// Client for services.iroh.computer.
+#[napi]
+pub struct ServicesClient {
+    inner: Client,
+}
+
+#[napi]
+impl ServicesClient {
+    /// Build a new client bound to the given endpoint.
+    #[napi(factory)]
+    pub async fn create(endpoint: &Endpoint, options: ServicesOptions) -> Result<ServicesClient> {
+        let mut builder: ClientBuilder = Client::builder(endpoint.raw());
+
+        let creds = [
+            options.api_secret.is_some(),
+            options.api_secret_from_env.unwrap_or(false),
+            options.ssh_key_pem.is_some(),
+        ]
+        .into_iter()
+        .filter(|x| *x)
+        .count();
+        if creds != 1 {
+            return Err(anyhow::anyhow!(
+                "ServicesOptions requires exactly one of api_secret / api_secret_from_env / ssh_key_pem"
+            )
+            .into());
+        }
+
+        if let Some(secret) = options.api_secret {
+            builder = builder
+                .api_secret_from_str(&secret)
+                .map_err(|e| anyhow::anyhow!("invalid api secret: {e:?}"))?;
+        } else if options.api_secret_from_env.unwrap_or(false) {
+            builder = builder
+                .api_secret_from_env()
+                .map_err(|e| anyhow::anyhow!("api secret env var: {e:?}"))?;
+        } else if let Some(pem) = options.ssh_key_pem {
+            builder = builder
+                .ssh_key(&pem)
+                .map_err(|e| anyhow::anyhow!("invalid ssh key: {e:?}"))?;
+        }
+
+        if let Some(name) = options.name {
+            builder = builder
+                .name(name)
+                .map_err(|e| anyhow::anyhow!("invalid name: {e:?}"))?;
+        }
+        if let Some(ms) = options.metrics_interval_ms {
+            if ms == 0 {
+                builder = builder.disable_metrics_interval();
+            } else {
+                builder = builder.metrics_interval(Duration::from_millis(ms as u64));
+            }
+        }
+
+        let inner = builder
+            .build()
+            .await
+            .map_err(|e| anyhow::anyhow!("services build failed: {e:?}"))?;
+        Ok(ServicesClient { inner })
+    }
+
+    /// Read the current endpoint name from the local client.
+    #[napi]
+    pub async fn name(&self) -> Result<Option<String>> {
+        self.inner
+            .name()
+            .await
+            .map_err(|e| anyhow::anyhow!("{e:?}").into())
+    }
+
+    /// Set the endpoint name cloud-side.
+    #[napi]
+    pub async fn set_name(&self, name: String) -> Result<()> {
+        self.inner
+            .set_name(name)
+            .await
+            .map_err(|e| anyhow::anyhow!("{e:?}").into())
+    }
+
+    /// Ping the remote service.
+    #[napi]
+    pub async fn ping(&self) -> Result<()> {
+        self.inner
+            .ping()
+            .await
+            .map(|_| ())
+            .map_err(|e| anyhow::anyhow!("{e:?}").into())
+    }
+
+    /// Force a metrics flush.
+    #[napi]
+    pub async fn push_metrics(&self) -> Result<()> {
+        self.inner
+            .push_metrics()
+            .await
+            .map_err(|e| anyhow::anyhow!("{e:?}").into())
+    }
+
+    /// Run a network-diagnostics report, optionally submitting it.
+    #[napi]
+    pub async fn submit_network_diagnostics(&self, send: bool) -> Result<DiagnosticsSummary> {
+        let report = self
+            .inner
+            .net_diagnostics(send)
+            .await
+            .map_err(|e| anyhow::anyhow!("{e:?}"))?;
+        Ok(report.into())
+    }
+}

package/src/ticket.rs

@@ -0,0 +1,46 @@
+use iroh_tickets::Ticket as _;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::EndpointAddr;
+
+/// A token containing information for establishing a connection to an endpoint.
+#[derive(Debug, Clone)]
+#[napi]
+pub struct EndpointTicket(iroh_tickets::endpoint::EndpointTicket);
+
+impl From<iroh_tickets::endpoint::EndpointTicket> for EndpointTicket {
+    fn from(t: iroh_tickets::endpoint::EndpointTicket) -> Self {
+        EndpointTicket(t)
+    }
+}
+
+#[napi]
+impl EndpointTicket {
+    /// Wrap an [`EndpointAddr`] into a ticket.
+    #[napi(factory)]
+    pub fn from_addr(addr: &EndpointAddr) -> Result<Self> {
+        let inner: iroh::EndpointAddr = addr.try_into()?;
+        Ok(iroh_tickets::endpoint::EndpointTicket::new(inner).into())
+    }
+
+    /// Parse a ticket from its base32 string form.
+    #[napi(factory)]
+    pub fn from_string(s: String) -> Result<Self> {
+        let ticket = iroh_tickets::endpoint::EndpointTicket::decode_string(&s)
+            .map_err(anyhow::Error::from)?;
+        Ok(EndpointTicket(ticket))
+    }
+
+    /// The [`EndpointAddr`] embedded in this ticket.
+    #[napi]
+    pub fn endpoint_addr(&self) -> EndpointAddr {
+        self.0.endpoint_addr().clone().into()
+    }
+
+    /// Base32 string form.
+    #[napi]
+    pub fn to_string(&self) -> String {
+        self.0.to_string()
+    }
+}

package/src/watch.rs

@@ -0,0 +1,111 @@
+use n0_future::{StreamExt, task::AbortOnDropHandle};
+use napi::threadsafe_function::{ThreadsafeFunction, ThreadsafeFunctionCallMode};
+use napi_derive::napi;
+use tokio::sync::Mutex;
+
+use crate::{EndpointAddr, PathEvent, PathSnapshot};
+
+/// Handle to a running watcher task. Call `stop()` (or drop) to unregister.
+#[napi]
+pub struct WatchHandle {
+    task: Mutex<Option<AbortOnDropHandle<()>>>,
+}
+
+impl WatchHandle {
+    pub(crate) fn new(task: AbortOnDropHandle<()>) -> Self {
+        Self {
+            task: Mutex::new(Some(task)),
+        }
+    }
+}
+
+#[napi]
+impl WatchHandle {
+    /// Stop the watcher, aborting the background task.
+    #[napi]
+    pub async fn stop(&self) {
+        self.task.lock().await.take();
+    }
+}
+
+pub(crate) fn spawn_watch_addr(
+    endpoint: iroh::Endpoint,
+    cb: ThreadsafeFunction<EndpointAddr>,
+) -> WatchHandle {
+    let task = n0_future::task::spawn(async move {
+        use iroh::Watcher;
+        let mut stream = endpoint.watch_addr().stream();
+        while let Some(addr) = stream.next().await {
+            let mapped: EndpointAddr = addr.into();
+            cb.call(Ok(mapped), ThreadsafeFunctionCallMode::NonBlocking);
+        }
+    });
+    WatchHandle::new(AbortOnDropHandle::new(task))
+}
+
+pub(crate) fn spawn_home_relay_watch(
+    endpoint: iroh::Endpoint,
+    cb: ThreadsafeFunction<Vec<String>>,
+) -> WatchHandle {
+    let task = n0_future::task::spawn(async move {
+        use iroh::Watcher;
+        let mut stream = endpoint.home_relay_status().stream();
+        while let Some(statuses) = stream.next().await {
+            let urls: Vec<String> = statuses.into_iter().map(|s| s.url().to_string()).collect();
+            cb.call(Ok(urls), ThreadsafeFunctionCallMode::NonBlocking);
+        }
+    });
+    WatchHandle::new(AbortOnDropHandle::new(task))
+}
+
+pub(crate) fn spawn_network_change_watch(
+    endpoint: iroh::Endpoint,
+    cb: ThreadsafeFunction<()>,
+) -> WatchHandle {
+    let task = n0_future::task::spawn(async move {
+        loop {
+            endpoint.network_change().await;
+            cb.call(Ok(()), ThreadsafeFunctionCallMode::NonBlocking);
+        }
+    });
+    WatchHandle::new(AbortOnDropHandle::new(task))
+}
+
+pub(crate) fn spawn_paths_watch(
+    conn: iroh::endpoint::Connection,
+    cb: ThreadsafeFunction<Vec<PathSnapshot>>,
+) -> WatchHandle {
+    let task = n0_future::task::spawn(async move {
+        let mut stream = conn.paths_stream();
+        while let Some(snapshot) = stream.next().await {
+            let mapped: Vec<PathSnapshot> = snapshot
+                .iter()
+                .map(|p| PathSnapshot {
+                    id: p.id().to_string(),
+                    is_selected: p.is_selected(),
+                    remote_addr: crate::path::transport_addr_to_string(p.remote_addr()),
+                    is_ip: p.is_ip(),
+                    is_relay: p.is_relay(),
+                    rtt_ms: p.rtt().as_millis() as i64,
+                    stats: p.stats().into(),
+                })
+                .collect();
+            cb.call(Ok(mapped), ThreadsafeFunctionCallMode::NonBlocking);
+        }
+    });
+    WatchHandle::new(AbortOnDropHandle::new(task))
+}
+
+pub(crate) fn spawn_path_events_watch(
+    conn: iroh::endpoint::Connection,
+    cb: ThreadsafeFunction<PathEvent>,
+) -> WatchHandle {
+    let task = n0_future::task::spawn(async move {
+        let mut stream = conn.path_events();
+        while let Some(event) = stream.next().await {
+            let mapped: PathEvent = event.into();
+            cb.call(Ok(mapped), ThreadsafeFunctionCallMode::NonBlocking);
+        }
+    });
+    WatchHandle::new(AbortOnDropHandle::new(task))
+}

package/test/endpoint.mjs

@@ -0,0 +1,176 @@
+import { test, suite } from 'node:test'
+import assert from 'node:assert'
+
+import pkg from '../index.js'
+const { Endpoint, EndpointTicket, RelayMode, presetMinimal } = pkg
+
+const ALPN = Array.from(Buffer.from('iroh-ffi/test/0', 'utf8'))
+
+// A "preset" in JS is any function that configures an EndpointBuilder.
+async function bindMinimal() {
+  const b = Endpoint.builder()
+  presetMinimal(b)
+  return await b.bind()
+}
+
+async function bindServer() {
+  const b = Endpoint.builder()
+  b.applyN0()
+  b.alpns([ALPN])
+  b.relayMode(RelayMode.disabled())
+  return await b.bind()
+}
+
+async function bindClient() {
+  const b = Endpoint.builder()
+  b.applyN0()
+  b.relayMode(RelayMode.disabled())
+  return await b.bind()
+}
+
+suite('endpoint', () => {
+  test('builder + preset: id, addr, sockets, secretKey, close', async () => {
+    const ep = await bindMinimal()
+    const id = ep.id()
+    assert.ok(id.toString().length > 0)
+
+    const addr = ep.addr()
+    assert.ok(addr.id().equals(id))
+
+    assert.ok(ep.boundSockets().length > 0)
+    assert.deepEqual(ep.secretKey().public().toBytes(), id.toBytes())
+
+    await ep.close()
+    assert.ok(ep.isClosed())
+  })
+
+  test('builder.bind() consumes — second call errors', async () => {
+    const b = Endpoint.builder()
+    presetMinimal(b)
+    const ep = await b.bind()
+    await ep.close()
+    await assert.rejects(() => b.bind(), /already consumed/)
+  })
+
+  test('custom preset function', async () => {
+    // A user-defined preset is just a function over the builder.
+    const myPreset = (b) => {
+      b.applyMinimal()
+      b.alpns([ALPN])
+    }
+    const b = Endpoint.builder()
+    myPreset(b)
+    const ep = await b.bind()
+    assert.ok(ep.id().toString().length > 0)
+    await ep.close()
+  })
+
+  test('endpoint ticket round trip', async () => {
+    const ep = await bindMinimal()
+    const addr = ep.addr()
+
+    const ticket = EndpointTicket.fromAddr(addr)
+    const str = ticket.toString()
+    assert.ok(str.startsWith('endpoint'))
+
+    const parsed = EndpointTicket.fromString(str)
+    assert.ok(parsed.endpointAddr().id().equals(addr.id()))
+
+    await ep.close()
+  })
+
+  test('endpoint ticket rejects garbage', () => {
+    assert.throws(() => EndpointTicket.fromString('not-a-ticket'))
+  })
+
+  test('connect / echo / datagram round trip', async () => {
+    const server = await bindServer()
+    const serverAddr = server.addr()
+    const serverId = server.id()
+
+    const serverTask = (async () => {
+      const incoming = await server.acceptNext()
+      assert.ok(incoming)
+      const accepting = await incoming.accept()
+      const conn = await accepting.connect()
+      assert.deepEqual(conn.alpn(), ALPN)
+      const bi = await conn.acceptBi()
+      const recv = bi.recv
+      const send = bi.send
+      const msg = await recv.readToEnd(64)
+      await send.writeAll(msg)
+      await send.finish()
+      const dg = await conn.readDatagram()
+      conn.sendDatagram(dg)
+      await conn.closed()
+    })()
+
+    const client = await bindClient()
+    const conn = await client.connect(serverAddr, ALPN)
+    assert.ok(conn.remoteId().equals(serverId))
+    assert.ok(conn.paths().length > 0)
+
+    const bi = await conn.openBi()
+    await bi.send.writeAll(Array.from(Buffer.from('hello iroh')))
+    await bi.send.finish()
+    const echoed = await bi.recv.readToEnd(64)
+    assert.equal(Buffer.from(echoed).toString('utf8'), 'hello iroh')
+
+    conn.sendDatagram(Array.from(Buffer.from('ping')))
+    const pong = await conn.readDatagram()
+    assert.equal(Buffer.from(pong).toString('utf8'), 'ping')
+
+    const stats = conn.stats()
+    assert.ok(stats.udpTxDatagrams > 0)
+
+    conn.close(0n, Array.from(Buffer.from('bye')))
+    await serverTask
+    await client.close()
+    await server.close()
+  })
+
+  test('relay-only mode binds without IP transports', async () => {
+    // A normal n0 endpoint binds at least one local UDP socket for direct
+    // (IP) connectivity.
+    const direct = await Endpoint.bind({ alpns: [ALPN] }, RelayMode.disabled())
+    assert.ok(
+      direct.boundSockets().length > 0,
+      'default endpoint should bind IP sockets',
+    )
+    await direct.close()
+
+    // With relayOnly: true the IP transports are cleared, so the endpoint
+    // has no bound IP sockets — all traffic is forced over relays.
+    const relayOnly = await Endpoint.bind({ alpns: [ALPN], relayOnly: true })
+    assert.equal(
+      relayOnly.boundSockets().length,
+      0,
+      'relay-only endpoint should have no direct IP sockets',
+    )
+    assert.ok(relayOnly.id().toString().length > 0)
+    await relayOnly.close()
+  })
+
+  test('unidirectional stream', async () => {
+    const server = await bindServer()
+    const serverAddr = server.addr()
+
+    const serverTask = (async () => {
+      const incoming = await server.acceptNext()
+      const conn = await (await incoming.accept()).connect()
+      const recv = await conn.acceptUni()
+      const msg = await recv.readToEnd(32)
+      assert.equal(Buffer.from(msg).toString('utf8'), 'unidirectional')
+    })()
+
+    const client = await bindClient()
+    const conn = await client.connect(serverAddr, ALPN)
+    const send = await conn.openUni()
+    await send.writeAll(Array.from(Buffer.from('unidirectional')))
+    await send.finish()
+
+    await serverTask
+    await client.close()
+    await server.close()
+  })
+})

package/test/key.mjs

@@ -0,0 +1,71 @@
+import { test, suite } from 'node:test'
+import assert from 'node:assert'
+
+import pkg from '../index.js'
+const { EndpointId, SecretKey, Signature } = pkg
+
+const keyStr = '523c7996bad77424e96786cf7a7205115337a5b4565cd25506a0f297b191a5ea'
+const fmtStr = '523c7996ba'
+const bytes = Array.from(new Uint8Array([
+  0x52, 0x3c, 0x79, 0x96, 0xba, 0xd7, 0x74, 0x24,
+  0xe9, 0x67, 0x86, 0xcf, 0x7a, 0x72, 0x05, 0x11,
+  0x53, 0x37, 0xa5, 0xb4, 0x56, 0x5c, 0xd2, 0x55,
+  0x06, 0xa0, 0xf2, 0x97, 0xb1, 0x91, 0xa5, 0xea,
+]))
+
+suite('endpoint id', () => {
+  test('from string', () => {
+    const id = EndpointId.fromString(keyStr)
+    assert.equal(id.toString(), keyStr)
+    assert.deepEqual(id.toBytes(), bytes)
+    assert.equal(id.fmtShort(), fmtStr)
+  })
+
+  test('from bytes', () => {
+    const id = EndpointId.fromBytes(bytes)
+    assert.equal(id.toString(), keyStr)
+    assert.deepEqual(id.toBytes(), bytes)
+    assert.equal(id.fmtShort(), fmtStr)
+  })
+
+  test('equality', () => {
+    assert.ok(EndpointId.fromString(keyStr).equals(EndpointId.fromBytes(bytes)))
+  })
+
+  test('rejects bad bytes', () => {
+    assert.throws(() => EndpointId.fromBytes([1, 2, 3]))
+  })
+})
+
+suite('secret key', () => {
+  test('bytes round trip', () => {
+    const secret = SecretKey.generate()
+    const raw = secret.toBytes()
+    assert.equal(raw.length, 32)
+    const secret2 = SecretKey.fromBytes(raw)
+    assert.deepEqual(secret.toBytes(), secret2.toBytes())
+    assert.deepEqual(secret.public().toBytes(), secret2.public().toBytes())
+  })
+
+  test('sign / verify round trip', () => {
+    const secret = SecretKey.generate()
+    const pub = secret.public()
+    const msg = Array.from(Buffer.from('hello iroh', 'utf8'))
+    const sig = secret.sign(msg)
+
+    const raw = sig.toBytes()
+    assert.equal(raw.length, 64)
+    const sig2 = Signature.fromBytes(raw)
+    assert.deepEqual(sig2.toBytes(), raw)
+
+    pub.verify(msg, sig)
+    pub.verify(msg, sig2)
+  })
+
+  test('verify rejects tampered message', () => {
+    const secret = SecretKey.generate()
+    const pub = secret.public()
+    const sig = secret.sign(Array.from(Buffer.from('original')))
+    assert.throws(() => pub.verify(Array.from(Buffer.from('tampered')), sig))
+  })
+})

package/test/relay.mjs

@@ -0,0 +1,40 @@
+import { test, suite } from 'node:test'
+import assert from 'node:assert'
+
+import pkg from '../index.js'
+const { RelayMap, RelayMode } = pkg
+
+suite('relay map', () => {
+  test('crud', () => {
+    const map = RelayMap.empty()
+    assert.ok(map.isEmpty())
+
+    const cfg = {
+      url: 'https://relay.example.org/',
+      quicPort: 7842,
+      authToken: 'hunter2',
+    }
+    map.insert(cfg)
+    assert.equal(map.len(), 1)
+    assert.ok(map.contains('https://relay.example.org/'))
+
+    const got = map.get('https://relay.example.org/')
+    assert.equal(got.url, cfg.url)
+    assert.equal(got.quicPort, cfg.quicPort)
+    assert.equal(got.authToken, cfg.authToken)
+
+    assert.ok(map.remove('https://relay.example.org/'))
+    assert.ok(map.isEmpty())
+  })
+})
+
+suite('relay mode', () => {
+  test('constructors', () => {
+    RelayMode.disabled()
+    RelayMode.defaultMode()
+    RelayMode.staging()
+    const map = RelayMap.fromUrls(['https://r1.example.org/'])
+    RelayMode.custom(map)
+    RelayMode.customFromUrls(['https://r2.example.org/'])
+  })
+})

package/test/services.mjs

@@ -0,0 +1,47 @@
+import { test, suite } from 'node:test'
+import assert from 'node:assert'
+
+import pkg from '../index.js'
+const { Endpoint, ServicesClient, presetMinimal } = pkg
+
+// Well-formed (but fake) API secret — the remote does not exist, but the
+// client connects lazily so construction still succeeds. Validates the
+// options -> builder -> client plumbing without network.
+const FAKE_API_SECRET =
+  'servicesaaqaobyha4dqobyha4dqobyha4dqobyha4dqobyha4dqobyha4dqob' +
+  '75c4sdqwvay5nwj63yzvqc7iozsh66x53lcpcy5vyc5ledl2pwdaaa'
+
+async function endpoint() {
+  const b = Endpoint.builder()
+  presetMinimal(b)
+  return await b.bind()
+}
+
+suite('services client', () => {
+  test('boots with fake secret', async () => {
+    const ep = await endpoint()
+    const client = await ServicesClient.create(ep, { apiSecret: FAKE_API_SECRET })
+    assert.ok(client)
+    await ep.close()
+  })
+
+  test('rejects no credentials', async () => {
+    const ep = await endpoint()
+    await assert.rejects(ServicesClient.create(ep, {}))
+    await ep.close()
+  })
+
+  test('rejects two credentials', async () => {
+    const ep = await endpoint()
+    await assert.rejects(
+      ServicesClient.create(ep, { apiSecret: FAKE_API_SECRET, apiSecretFromEnv: true }),
+    )
+    await ep.close()
+  })
+
+  test('rejects malformed secret', async () => {
+    const ep = await endpoint()
+    await assert.rejects(ServicesClient.create(ep, { apiSecret: 'not-a-valid-ticket' }))
+    await ep.close()
+  })
+})

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "declaration": true,
+    "skipLibCheck": true,
+    "strict": false
+  },
+  "include": ["index.d.ts"]
+}

package/typedoc.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["index.d.ts"],
+  "out": "../site/js",
+  "skipErrorChecking": true,
+  "readme": "none",
+  "name": "@cc-remote/iroh",
+  "excludeExternals": true
+}