@cc-remote/iroh 1.0.0-rc.3

package/.yarnrc.yml

@@ -0,0 +1,3 @@
+nodeLinker: node-modules
+
+yarnPath: .yarn/releases/yarn-4.4.0.cjs

package/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+edition = "2024"
+name = "number0_iroh"
+version = "1.0.0"
+license = "MIT OR Apache-2.0"
+authors = ["n0 team"]
+repository = "https://github.com/n0-computer/iroh-ffi"
+rust-version = "1.91"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+napi = { version = "3", default-features = false, features = ["napi8", "error_anyhow", "async"] }
+napi-derive = "3"
+anyhow = "1.0.69"
+iroh = "1.0.0"
+iroh-base = "1.0.0"
+iroh-metrics = "1.0.0"
+iroh-relay = { version = "1.0.0", default-features = false }
+iroh-services = { version = "1.0.0", default-features = false }
+iroh-tickets = "1.0.0"
+n0-future = "0.3"
+tokio = "1.25.0"
+url = "2.4"
+tracing = "0.1.40"
+tracing-subscriber = { version = "0.3.17" }
+
+[build-dependencies]
+napi-build = "2.2"

package/README.md

@@ -0,0 +1,38 @@
+# `@number0/iroh`
+
+> A toolkit for building distributed applications
+
+## Install
+
+```sh
+> npm i --save @number0/iroh
+```
+
+
+## Development
+
+```sh
+# debug build
+> yarn build:debug
+
+# run tests
+> yarn test
+```
+
+
+## License
+
+This project is licensed under either of
+
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
+ * MIT license ([LICENSE-MIT](LICENSE-MIT) or
+   http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this project by you, as defined in the Apache-2.0 license,
+shall be dual licensed as above, without any additional terms or conditions.

package/index.d.ts

@@ -0,0 +1,478 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/** A server-side handshake in progress. */
+export declare class Accepting {
+  connect(): Promise<Connection>
+  alpn(): Promise<Array<number>>
+}
+
+/** A bidirectional QUIC stream pair. */
+export declare class BiStream {
+  get send(): SendStream
+  get recv(): RecvStream
+}
+
+/** A client-side handshake in progress. */
+export declare class Connecting {
+  connect(): Promise<Connection>
+  alpn(): Promise<Array<number>>
+  remoteId(): Promise<EndpointId>
+}
+
+/** An active QUIC connection. */
+export declare class Connection {
+  alpn(): Array<number>
+  remoteId(): EndpointId
+  side(): Side
+  openUni(): Promise<SendStream>
+  acceptUni(): Promise<RecvStream>
+  openBi(): Promise<BiStream>
+  acceptBi(): Promise<BiStream>
+  readDatagram(): Promise<Array<number>>
+  closed(): Promise<string>
+  closeReason(): string | null
+  close(errorCode: bigint, reason: Array<number>): void
+  sendDatagram(data: Array<number>): void
+  sendDatagramWait(data: Array<number>): Promise<void>
+  maxDatagramSize(): number | null
+  datagramSendBufferSpace(): number
+  stableId(): number
+  rtt(): number | null
+  stats(): ConnectionStats
+  paths(): Array<PathSnapshot>
+  watchPaths(callback: (paths: Array<PathSnapshot>) => void): WatchHandle
+  watchPathEvents(callback: (event: PathEvent) => void): WatchHandle
+  setMaxConcurrentUniStreams(count: bigint): void
+  setReceiveWindow(count: bigint): void
+  setMaxConcurrentBiStreams(count: bigint): void
+}
+
+/** An iroh endpoint. */
+export declare class Endpoint {
+  /** Create an endpoint builder (starts empty — apply a preset). */
+  static builder(): EndpointBuilder
+  /**
+   * Bind a new endpoint. Applies the n0 preset, then the given options.
+   * For a custom preset use [`Endpoint::builder`].
+   */
+  static bind(options?: EndpointOptions | undefined | null, relayMode?: RelayMode | undefined | null): Promise<Endpoint>
+  /** This endpoint's id. */
+  id(): EndpointId
+  /** The [`EndpointAddr`] for this endpoint. */
+  addr(): EndpointAddr
+  /** Look up cached information about a remote endpoint, if any. */
+  remoteAddr(id: EndpointId): Promise<EndpointAddr | null>
+  /** Current statistics for this endpoint. */
+  stats(): Record<string, CounterStats>
+  /** The secret key backing this endpoint's identity. */
+  secretKey(): SecretKey
+  /** Replace the set of advertised ALPNs. */
+  setAlpns(alpns: Array<Array<number>>): void
+  /** Add an external (manually-known) socket address. */
+  addExternalAddr(addr: string): Promise<void>
+  /** Remove a previously-added external address. */
+  removeExternalAddr(addr: string): Promise<boolean>
+  /** The local socket addresses this endpoint is bound to. */
+  boundSockets(): Array<string>
+  /** Resolves once the endpoint has a usable home relay. */
+  online(): Promise<void>
+  /** Insert (or replace) a relay configuration at runtime. */
+  insertRelay(config: RelayConfig): Promise<void>
+  /** Remove a relay configuration at runtime. */
+  removeRelay(url: string): Promise<boolean>
+  /** Connect to a remote endpoint via the given ALPN. */
+  connect(addr: EndpointAddr, alpn: Array<number>): Promise<Connection>
+  /** Begin a connection attempt, returning the in-progress handle. */
+  connectPending(addr: EndpointAddr, alpn: Array<number>): Promise<Connecting>
+  /** Pull the next incoming connection attempt. */
+  acceptNext(): Promise<Incoming | null>
+  /** Watch for changes to this endpoint's address. */
+  watchAddr(callback: (addr: EndpointAddr) => void): WatchHandle
+  /** Watch for changes to the connected relays. */
+  watchHomeRelay(callback: (relayUrls: Array<string>) => void): WatchHandle
+  /** Watch for network-stack changes. */
+  watchNetworkChange(callback: () => void): WatchHandle
+  /** Close the endpoint. */
+  close(): Promise<void>
+  /** True if the endpoint is closed. */
+  isClosed(): boolean
+}
+
+/**
+ * An endpoint's id together with the network-level addresses where it can be
+ * reached. Mirrors the uniffi `EndpointAddr` object surface.
+ */
+export declare class EndpointAddr {
+  /** Create a new [`EndpointAddr`]. */
+  constructor(id: EndpointId, relayUrl?: string | undefined | null, addresses?: Array<string> | undefined | null)
+  /** The endpoint id. */
+  id(): EndpointId
+  /** The direct (ip:port) addresses of this peer. */
+  directAddresses(): Array<string>
+  /** The home relay URL for this peer, if known. */
+  relayUrl(): string | null
+  /** Returns true if both [`EndpointAddr`]s have the same values. */
+  equal(other: EndpointAddr): boolean
+  /** Clean string representation. */
+  toString(): string
+}
+
+/**
+ * A mutable handle to an endpoint builder.
+ *
+ * Mirrors the uniffi `EndpointBuilder`. A "preset" in JS is simply any
+ * function `(builder: EndpointBuilder) => void` — call one of the built-in
+ * [`presetN0`] / [`presetMinimal`] / [`presetN0DisableRelay`] helpers (which
+ * install the crypto provider) and then layer on your own configuration.
+ *
+ * ```js
+ * const b = Endpoint.builder()
+ * presetMinimal(b)
+ * b.alpns([alpn])
+ * const ep = await b.bind()
+ * ```
+ */
+export declare class EndpointBuilder {
+  /** Replay the n0 production preset (relays + discovery + crypto provider). */
+  applyN0(): void
+  /** Replay the minimal preset (crypto provider only, no external deps). */
+  applyMinimal(): void
+  /** Replay the n0 preset with relays disabled. */
+  applyN0DisableRelay(): void
+  /** Set the endpoint secret key (32 bytes). */
+  secretKey(bytes: Array<number>): void
+  /** Set the advertised ALPNs. */
+  alpns(alpns: Array<Array<number>>): void
+  /** Set the relay mode. */
+  relayMode(mode: RelayMode): void
+  /**
+   * Remove all IP based transports, forcing all traffic over relays.
+   *
+   * This must be called *after* any preset (e.g. [`applyN0`]) that
+   * installs IP transports, otherwise the preset will re-add them.
+   */
+  clearIpTransports(): void
+  /**
+   * Only publish relay addresses (no direct IPs) to discovery.
+   *
+   * Installs `AddrFilter::relay_only()` so the addresses published to
+   * discovery (pkarr/DNS) are limited to relay URLs.
+   */
+  addrFilterRelayOnly(): void
+  /** Set the address the endpoint binds to (`host:port`). */
+  bindAddr(addr: string): void
+  /** Bind the endpoint. */
+  bind(): Promise<Endpoint>
+}
+
+/** An endpoint's identifier, a 32-byte ed25519 public key. */
+export declare class EndpointId {
+  /** Returns true if both [`EndpointId`]s are equal. */
+  equals(other: EndpointId): boolean
+  /** Get the underlying 32 bytes. */
+  toBytes(): Array<number>
+  /** Parse an [`EndpointId`] from its base32 representation. */
+  static fromString(s: string): EndpointId
+  /** Construct an [`EndpointId`] from raw bytes (32 bytes). */
+  static fromBytes(bytes: Array<number>): EndpointId
+  /** Short base32 prefix. */
+  fmtShort(): string
+  /** Base32 string form. */
+  toString(): string
+  /** Verify a signature on `message` against this endpoint's key. */
+  verify(message: Array<number>, signature: Signature): void
+}
+
+/** A token containing information for establishing a connection to an endpoint. */
+export declare class EndpointTicket {
+  /** Wrap an [`EndpointAddr`] into a ticket. */
+  static fromAddr(addr: EndpointAddr): EndpointTicket
+  /** Parse a ticket from its base32 string form. */
+  static fromString(s: string): EndpointTicket
+  /** The [`EndpointAddr`] embedded in this ticket. */
+  endpointAddr(): EndpointAddr
+  /** Base32 string form. */
+  toString(): string
+}
+
+/** An incoming connection that has not yet begun its server-side handshake. */
+export declare class Incoming {
+  accept(): Promise<Accepting>
+  refuse(): Promise<void>
+  retry(): Promise<void>
+  ignore(): Promise<void>
+  localAddr(): Promise<IncomingLocalAddr>
+  remoteAddr(): Promise<IncomingAddr>
+  remoteAddrValidated(): Promise<boolean>
+}
+
+/** The incoming half of a QUIC stream. */
+export declare class RecvStream {
+  read(sizeLimit: number): Promise<Array<number>>
+  readExact(size: number): Promise<Array<number>>
+  readToEnd(sizeLimit: number): Promise<Array<number>>
+  id(): Promise<string>
+  bytesRead(): Promise<number>
+  stop(errorCode: bigint): Promise<void>
+  receivedReset(): Promise<number | null>
+}
+
+/** A collection of relay servers an endpoint should consider. */
+export declare class RelayMap {
+  /** Create an empty relay map. */
+  static empty(): RelayMap
+  /** Build a relay map from a list of relay URLs. */
+  static fromUrls(urls: Array<string>): RelayMap
+  /** Insert a relay (replacing any prior entry for the same URL). */
+  insert(config: RelayConfig): void
+  /** Remove the entry for the given relay URL. Returns true if removed. */
+  remove(url: string): boolean
+  /** Check whether the given relay URL is in the map. */
+  contains(url: string): boolean
+  /** Look up the configuration for the given relay URL. */
+  get(url: string): RelayConfig | null
+  /** All relay URLs currently in the map. */
+  urls(): Array<string>
+  /** Number of relays in the map. */
+  len(): number
+  /** True if the map has no relays. */
+  isEmpty(): boolean
+  /** Clean string representation. */
+  toString(): string
+}
+
+/** Configuration for which relay servers an endpoint uses. */
+export declare class RelayMode {
+  /** No relays. */
+  static disabled(): RelayMode
+  /** Use the n0 production relay map. */
+  static defaultMode(): RelayMode
+  /** Use the n0 staging relay map. */
+  static staging(): RelayMode
+  /** Use a custom relay map. */
+  static custom(map: RelayMap): RelayMode
+  /** Build a custom relay mode from a list of relay URLs. */
+  static customFromUrls(urls: Array<string>): RelayMode
+  /** The relay map this mode resolves to. */
+  relayMap(): RelayMap
+  /** Clean string representation. */
+  toString(): string
+}
+
+/** The secret key half of an endpoint identity. */
+export declare class SecretKey {
+  /** Generate a new random secret key. */
+  static generate(): SecretKey
+  /** Construct from raw bytes (32 bytes). */
+  static fromBytes(bytes: Array<number>): SecretKey
+  /** Raw 32-byte form. */
+  toBytes(): Array<number>
+  /** The public [`EndpointId`] derived from this secret key. */
+  public(): EndpointId
+  /** Sign a message, producing an ed25519 signature. */
+  sign(message: Array<number>): Signature
+}
+
+/** The outgoing half of a QUIC stream. */
+export declare class SendStream {
+  write(buf: Array<number>): Promise<number>
+  writeAll(buf: Array<number>): Promise<void>
+  finish(): Promise<void>
+  reset(errorCode: bigint): Promise<void>
+  setPriority(p: number): Promise<void>
+  priority(): Promise<number>
+  stopped(): Promise<number | null>
+  id(): Promise<string>
+}
+
+/** Client for services.iroh.computer. */
+export declare class ServicesClient {
+  /** Build a new client bound to the given endpoint. */
+  static create(endpoint: Endpoint, options: ServicesOptions): Promise<ServicesClient>
+  /** Read the current endpoint name from the local client. */
+  name(): Promise<string | null>
+  /** Set the endpoint name cloud-side. */
+  setName(name: string): Promise<void>
+  /** Ping the remote service. */
+  ping(): Promise<void>
+  /** Force a metrics flush. */
+  pushMetrics(): Promise<void>
+  /** Run a network-diagnostics report, optionally submitting it. */
+  submitNetworkDiagnostics(send: boolean): Promise<DiagnosticsSummary>
+}
+
+/** An ed25519 signature over a message. */
+export declare class Signature {
+  /** Construct from raw bytes (64 bytes). */
+  static fromBytes(bytes: Array<number>): Signature
+  /** Raw 64-byte form. */
+  toBytes(): Array<number>
+  /** Lowercase hex representation. */
+  toString(): string
+}
+
+/** Handle to a running watcher task. Call `stop()` (or drop) to unregister. */
+export declare class WatchHandle {
+  /** Stop the watcher, aborting the background task. */
+  stop(): Promise<void>
+}
+
+/** Flat snapshot of headline connection statistics. */
+export interface ConnectionStats {
+  udpTxDatagrams: number
+  udpTxBytes: number
+  udpRxDatagrams: number
+  udpRxBytes: number
+  lostPackets: number
+  lostBytes: number
+}
+
+/** A snapshot value for a single endpoint metric. */
+export interface CounterStats {
+  value: number
+  description: string
+}
+
+/** Flattened summary of an `iroh_services` diagnostics report. */
+export interface DiagnosticsSummary {
+  endpointId: string
+  directAddrs: Array<string>
+  irohVersion: string
+  irohServicesVersion: string
+  hasNetReport: boolean
+  upnp?: boolean
+  pcp?: boolean
+  natPmp?: boolean
+}
+
+/**
+ * Options passed to [`Endpoint::bind`].
+ *
+ * `bind` applies the n0 preset by default. For a custom preset use
+ * [`Endpoint::builder`] + the `EndpointBuilder` surface.
+ */
+export interface EndpointOptions {
+  bindAddr?: string
+  secretKey?: Array<number>
+  alpns?: Array<Array<number>>
+  /**
+   * Force all traffic over relays ("relay-only" mode).
+   *
+   * When `true`, removes all IP based transports (no direct connections or
+   * hole punching) and limits the addresses published to discovery to relay
+   * URLs only. Defaults to `false` (n0 preset behaviour unchanged).
+   */
+  relayOnly?: boolean
+}
+
+/** Where an incoming connection came from. */
+export interface IncomingAddr {
+  /** One of "ip" | "relay" | "custom". */
+  kind: string
+  /** `ip:port` for ip, relay URL for relay. */
+  addr?: string
+  /** Remote endpoint id (relay only). */
+  endpointId?: string
+  /** Debug description (custom only). */
+  description?: string
+}
+
+/** The local address that received an incoming connection. */
+export interface IncomingLocalAddr {
+  /** One of "ip" | "relay" | "custom". */
+  kind: string
+  addr?: string
+  description?: string
+}
+
+/** The logging level. See the rust (log crate)[https://docs.rs/log] for more information. */
+export declare const enum LogLevel {
+  Trace = 'Trace',
+  Debug = 'Debug',
+  Info = 'Info',
+  Warn = 'Warn',
+  Error = 'Error',
+  Off = 'Off'
+}
+
+/** A path event with its associated data. */
+export interface PathEvent {
+  kind: PathEventKind
+  id?: string
+  remoteAddr?: string
+  localAddr?: string
+  lastStats?: PathStatsRecord
+  missed?: number
+}
+
+/** An event from `Connection::watchPathEvents`. */
+export declare const enum PathEventKind {
+  Opened = 'Opened',
+  Closed = 'Closed',
+  Selected = 'Selected',
+  Lagged = 'Lagged'
+}
+
+/** A flat snapshot of an open path's state. */
+export interface PathSnapshot {
+  id: string
+  isSelected: boolean
+  remoteAddr: string
+  isIp: boolean
+  isRelay: boolean
+  rttMs: number
+  stats: PathStatsRecord
+}
+
+/** Flattened headline numbers from `noq::PathStats`. */
+export interface PathStatsRecord {
+  rttMs: number
+  udpTxDatagrams: number
+  udpTxBytes: number
+  udpRxDatagrams: number
+  udpRxBytes: number
+  cwnd: number
+  congestionEvents: number
+  lostPackets: number
+  lostBytes: number
+  currentMtu: number
+}
+
+/** The minimal preset (no external dependencies; good for tests / offline). */
+export declare function presetMinimal(builder: EndpointBuilder): void
+
+/** The n0 production preset (relays + discovery). */
+export declare function presetN0(builder: EndpointBuilder): void
+
+/** The n0 preset with relays disabled. */
+export declare function presetN0DisableRelay(builder: EndpointBuilder): void
+
+/** Config for a single relay server. */
+export interface RelayConfig {
+  url: string
+  quicPort?: number
+  authToken?: string
+}
+
+/** Build options for [`ServicesClient`]. */
+export interface ServicesOptions {
+  /** Encoded API secret string (`services1...`). */
+  apiSecret?: string
+  /** If true, read the API secret from `IROH_SERVICES_API_SECRET`. */
+  apiSecretFromEnv?: boolean
+  /** Unencrypted PEM-encoded OpenSSH ed25519 private key. */
+  sshKeyPem?: string
+  /** Optional endpoint name to register cloud-side. */
+  name?: string
+  /** Metrics push interval (ms). `0` disables interval pushes. */
+  metricsIntervalMs?: number
+}
+
+/** Set the logging level. */
+export declare function setLogLevel(level: LogLevel): void
+
+/** Which side of a connection we are. */
+export declare const enum Side {
+  Client = 'Client',
+  Server = 'Server'
+}