@solidrt/flux-types 0.0.13 → 0.0.14

package/index.d.ts

@@ -5,6 +5,8 @@
 /// <reference path="./modules/sqlite.d.ts" />
 /// <reference path="./modules/subprocess.d.ts" />
 /// <reference path="./modules/p2p.d.ts" />
+/// <reference path="./modules/net.d.ts" />
+/// <reference path="./modules/mdns.d.ts" />
 
 // Web-standard globals. The runtime is QuickJS, not a browser or Node, so it
 // ships no lib.dom / @types/bun: these declarations are the sole source for

package/modules/mdns.d.ts

@@ -0,0 +1,54 @@
+declare module "flux:mdns" {
+  /** Options common to {@link resolve}, {@link browse}, and {@link services}. */
+  type MdnsOptions = {
+    /** How long (ms) to collect multicast answers before resolving. Default 1500. */
+    timeoutMs?: number
+  }
+
+  /** A reverse-resolved address, from {@link resolve}. */
+  type Resolved = {
+    /** The queried IPv4 address. */
+    ip: string
+    /** Its mDNS hostname, e.g. "printer.local". */
+    host: string
+  }
+
+  /** One discovered DNS-SD service instance, from {@link browse}. */
+  type ServiceInstance = {
+    /** The human instance label, e.g. "Office Printer". */
+    instance: string
+    /** The service type, e.g. "_ipp._tcp". */
+    service: string
+    /** The target host the SRV record points at, e.g. "printer.local". */
+    host: string
+    /** The advertised port. */
+    port: number
+    /** A/AAAA addresses for `host`, when the responder bundled them. */
+    addrs: string[]
+    /** TXT attributes (a bare flag attribute has an empty-string value). */
+    txt: Record<string, string>
+  }
+
+  /**
+   * Reverse-resolve IPv4 addresses to their mDNS `.local` hostnames over the
+   * link-local multicast group (a PTR query against `in-addr.arpa`). `.local`
+   * names are mDNS, not unicast DNS, so this works with no `nss-mdns` resolver and
+   * no external binary. Addresses that do not answer within the window — and any
+   * IPv6 inputs — are simply absent from the result; an empty input resolves to
+   * `[]` without touching the network. Needs a Bonjour/avahi responder on the LAN.
+   */
+  export function resolve(ips: string[], opts?: MdnsOptions): Promise<Resolved[]>
+
+  /**
+   * Browse a DNS-SD service type for the instances on the LAN. `service` may be
+   * bare (`"_http._tcp"`) or fully qualified. Resolves to `[]` if nothing answers
+   * within the window.
+   */
+  export function browse(service: string, opts?: MdnsOptions): Promise<ServiceInstance[]>
+
+  /**
+   * Enumerate the service types advertised on the LAN (the
+   * `_services._dns-sd._udp.local` meta-query), e.g. `["_http._tcp", "_ipp._tcp"]`.
+   */
+  export function services(opts?: MdnsOptions): Promise<string[]>
+}

package/modules/net.d.ts

@@ -0,0 +1,139 @@
+declare module "flux:net" {
+  /** Options for {@link probe} and {@link connect}. */
+  type ConnectOptions = {
+    /** Give up after this many ms. Default 1000 for {@link probe}, 10000 for {@link connect}. */
+    timeoutMs?: number
+  }
+
+  /** Options for {@link listen}. */
+  type ListenOptions = {
+    /** Local address to bind. Default "0.0.0.0" (all interfaces). */
+    host?: string
+  }
+
+  /** Options for {@link udp}. */
+  type UdpOptions = {
+    /** Local port to bind. Default 0 (OS-assigned). */
+    port?: number
+    /** Set SO_REUSEADDR/REUSEPORT so several sockets can share the port. */
+    reuse?: boolean
+  }
+
+  /**
+   * Outcome of a {@link probe}. `closed` (a refusal) still means the host is up —
+   * something answered; only `filtered` (a timeout/unreachable) is no evidence.
+   */
+  type Liveness = "open" | "closed" | "filtered"
+
+  /** One address on a {@link NetInterface}. */
+  type InterfaceAddr = {
+    /** The IP address. */
+    ip: string
+    /** CIDR prefix length (e.g. 24). */
+    prefix: number
+    /** Address family. */
+    family: "v4" | "v6"
+  }
+
+  /** A local network interface, from {@link interfaces}. */
+  type NetInterface = {
+    /** Interface name, e.g. "wlan0". */
+    name: string
+    /** Hardware (MAC) address, or `null` if none. */
+    mac: string | null
+    /** Whether the interface is up. */
+    up: boolean
+    /** Whether it is a loopback interface. */
+    loopback: boolean
+    /** Whether it supports multicast. */
+    multicast: boolean
+    /** The interface's bound addresses. */
+    addrs: InterfaceAddr[]
+  }
+
+  /** A received datagram, from {@link Udp.recv}. */
+  type Datagram = {
+    /** The payload bytes. */
+    data: Uint8Array
+    /** Sender IP. */
+    host: string
+    /** Sender port. */
+    port: number
+  }
+
+  /**
+   * A connected TCP stream: a byte duplex. It is its own async iterator, so
+   * `for await (let chunk of conn)` reads it until end-of-stream.
+   */
+  export class Conn implements AsyncIterable<Uint8Array> {
+    /** The remote peer's address, e.g. "192.168.2.37:445". */
+    readonly peer: string
+    /** Write all of `data`. Resolves once it is handed to the OS. */
+    write(data: string | Uint8Array): Promise<void>
+    /** Stop reading and close the connection. */
+    close(): void
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>
+  }
+
+  /**
+   * A bound TCP listener: an async-iterable of incoming connections, so
+   * `for await (let conn of listener)` accepts them. Drop it to stop.
+   */
+  export class Listener implements AsyncIterable<Conn> {
+    /** The bound local address (with the OS-assigned port when 0 was requested). */
+    readonly localAddr: string
+    [Symbol.asyncIterator](): AsyncIterator<Conn>
+  }
+
+  /** A bound UDP socket with the broadcast/multicast controls a peer beacon needs. */
+  export class Udp {
+    /** The bound local address (with the OS-assigned port when 0 was requested). */
+    readonly localAddr: string
+    /** Send a datagram to `host:port` — a unicast peer, a broadcast address, or a multicast group. */
+    send(data: string | Uint8Array, host: string, port: number): Promise<void>
+    /** Receive the next datagram. */
+    recv(): Promise<Datagram>
+    /** Allow sending to the broadcast address (SO_BROADCAST). */
+    setBroadcast(on: boolean): void
+    /** TTL for outgoing multicast (1 keeps it on the local link). */
+    setMulticastTtl(ttl: number): void
+    /** Whether multicast this socket sends loops back to sockets on this host. */
+    setMulticastLoop(on: boolean): void
+    /**
+     * Join multicast `group` on the interface with address `iface`
+     * (default "0.0.0.0", OS-chosen). Required to receive that group's datagrams.
+     */
+    joinMulticast(group: string, iface?: string): void
+    /** Leave a multicast group previously joined with {@link joinMulticast}. */
+    leaveMulticast(group: string, iface?: string): void
+  }
+
+  /**
+   * Probe `host:port` with a TCP connect and report what it says about the host.
+   * Infallible — every outcome maps to a {@link Liveness}, so a sweep never has to
+   * catch. The connect-scan primitive: count `open` or `closed` as a live host.
+   *
+   * @param opts  timeoutMs (default 1000).
+   */
+  export function probe(host: string, port: number, opts?: ConnectOptions): Promise<Liveness>
+
+  /**
+   * Open a TCP connection. Unlike {@link probe} this returns a live {@link Conn}
+   * for app protocols / banner grabs.
+   *
+   * @param opts  timeoutMs (default 10000).
+   */
+  export function connect(host: string, port: number, opts?: ConnectOptions): Promise<Conn>
+
+  /** Bind a TCP {@link Listener} on `port` (0 = OS-assigned). */
+  export function listen(port: number, opts?: ListenOptions): Promise<Listener>
+
+  /** Bind a {@link Udp} socket. */
+  export function udp(opts?: UdpOptions): Promise<Udp>
+
+  /**
+   * Enumerate local network interfaces and their addresses — the no-subprocess
+   * way to find the subnet to scan (replaces parsing `ip addr`). Synchronous.
+   */
+  export function interfaces(): NetInterface[]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "license": "MIT",
   "author": "Antoine van Wel",
   "types": "index.d.ts",