@cero-base/core 1.2.0 → 1.4.0

package/src/network/transports/dht.js

@@ -0,0 +1,110 @@
+import Hyperswarm from 'hyperswarm'
+import b4a from 'b4a'
+import { hash } from 'hypercore-crypto'
+import safetyCatch from 'safety-catch'
+
+/**
+ * @typedef {object} DHTTransportOpts
+ * @property {import('../../identity/index.js').Identity} [identity]  Long-lived keypair used as the swarm identity.
+ * @property {Array<{ host: string, port: number }>} [bootstrap]      Custom DHT bootstrap nodes.
+ * @property {(remotePublicKey: Uint8Array, payload: any) => boolean} [firewall]  Incoming-connection filter.
+ * @property {Uint8Array[]} [relayThrough]                            Relay public keys to tunnel through.
+ * @property {string} [channel]                                       Optional network-isolation label; only same-channel peers meet.
+ */
+
+/**
+ * The internet transport: a Hyperswarm that finds peers over the DHT. Owns the
+ * swarm's whole lifecycle — construction (identity keyPair, bootstrap, firewall,
+ * relay), the channel-topic join/leave wrapping, flush, suspend/resume, and
+ * teardown. {@link Network} subscribes to `this.swarm`'s connection/peer events
+ * and drives topic joins; the swarm-specific wiring lives here.
+ */
+export class DHTTransport {
+  /** @param {DHTTransportOpts} [opts] */
+  constructor({ identity, bootstrap, firewall, relayThrough, channel } = {}) {
+    const opts = {}
+    if (identity) opts.keyPair = { publicKey: identity.publicKey, secretKey: identity.secretKey }
+    if (bootstrap) opts.bootstrap = bootstrap
+    if (firewall) opts.firewall = firewall
+    if (relayThrough) opts.relayThrough = relayThrough
+
+    this.swarm = new Hyperswarm(opts)
+
+    if (channel) {
+      const join = this.swarm.join.bind(this.swarm)
+      const leave = this.swarm.leave.bind(this.swarm)
+      this.swarm.join = (topic, opts) => join(channelTopic(topic, channel), opts)
+      this.swarm.leave = (topic) => leave(channelTopic(topic, channel))
+    }
+  }
+
+  /** @returns {boolean} */
+  get suspended() {
+    return this.swarm?.suspended === true
+  }
+
+  /**
+   * Wait for pending DHT announces and lookups to settle, bounded by timeout.
+   *
+   * @param {{ timeout?: number }} [opts]
+   * @returns {Promise<void>}
+   */
+  async flush({ timeout = 500 } = {}) {
+    if (!this.swarm) return
+    await Promise.race([this.swarm.flush(), new Promise((r) => setTimeout(r, timeout))])
+  }
+
+  /**
+   * Pause the swarm — keeps state, drops sockets. Idempotent.
+   *
+   * @returns {Promise<void>}
+   */
+  async suspend() {
+    if (!this.swarm || this.swarm.suspended) return
+    try {
+      await this.swarm.suspend()
+    } catch (err) {
+      safetyCatch(err)
+    }
+  }
+
+  /**
+   * Resume a suspended swarm. Idempotent.
+   *
+   * @returns {Promise<void>}
+   */
+  async resume() {
+    if (!this.swarm || !this.swarm.suspended) return
+    try {
+      await this.swarm.resume()
+    } catch (err) {
+      safetyCatch(err)
+    }
+  }
+
+  /**
+   * Flush pending discovery, then tear down the swarm. Idempotent.
+   *
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    if (!this.swarm) return
+    try {
+      await this.flush()
+    } catch (err) {
+      safetyCatch(err)
+    }
+    try {
+      await this.swarm.destroy()
+    } catch (err) {
+      safetyCatch(err)
+    }
+    this.swarm = null
+  }
+}
+
+// A channel re-namespaces every swarm topic so only same-channel peers meet.
+// No channel → identity (unchanged, back-compat).
+export function channelTopic(topic, channel) {
+  return channel ? hash([topic, b4a.from(channel)]) : topic
+}

package/src/network/transports/gatt.js

@@ -0,0 +1,57 @@
+import { Duplex } from 'streamx'
+
+// A single GATT write/notify caps at ATT_MTU − 3 ≈ 182 bytes; 150 stays under
+// that without negotiating an MTU.
+const PAYLOAD = 150
+
+/**
+ * A dumb byte-carrying duplex for the GATT transport. Framing and session logic
+ * live in BLETransport; this only fragments outbound writes to fit a GATT
+ * write and pushes inbound payload bytes.
+ *
+ * @extends Duplex
+ */
+export class GattStream extends Duplex {
+  /**
+   * @param {object} opts
+   * @param {(buffer: Uint8Array) => Promise<void>} opts.send  Transmit one payload piece (transport frames it).
+   * @param {() => void} [opts.onclose]  Called once on teardown (send a close frame, disconnect).
+   */
+  constructor({ send, onclose } = {}) {
+    super()
+    this._send = send
+    this._onclose = onclose || null
+  }
+
+  async _write(chunk, cb) {
+    try {
+      for (let offset = 0; offset < chunk.byteLength; offset += PAYLOAD) {
+        await this._send(chunk.subarray(offset, offset + PAYLOAD))
+      }
+      cb(null)
+    } catch (err) {
+      cb(err)
+    }
+  }
+
+  receive(buffer) {
+    this.push(buffer)
+  }
+
+  remoteEnd() {
+    this.push(null)
+  }
+
+  _destroy(cb) {
+    const onclose = this._onclose
+    this._onclose = null
+    if (onclose) {
+      try {
+        onclose()
+      } catch {
+        // teardown is best-effort
+      }
+    }
+    cb(null)
+  }
+}

package/types/network/index.d.ts

@@ -1,4 +1,4 @@
-export function channelTopic(topic: any, channel: any): any;
+export { channelTopic };
 /**
  * @typedef {object} NetworkOpts
  * @property {import('../identity/index.js').Identity} [identity]  Long-lived keypair used as the swarm identity.
@@ -24,12 +24,14 @@ export class Network extends ReadyResource {
     firewall: (remotePublicKey: Uint8Array, payload: any) => boolean;
     relayThrough: Uint8Array<ArrayBufferLike>[];
     channel: string;
-    swarm: any;
+    _dht: DHTTransport;
     wakeup: any;
     _replicateables: Set<any>;
     _discoveries: Set<any>;
     _injected: Set<any>;
     _blind: any;
+    /** @returns {any} The underlying hyperswarm, or null before ready / after close. */
+    get swarm(): any;
     /**
      * Feed an externally-established connection — a Bluetooth L2CAP channel, a
      * serial link, an in-process pair, any duplex — into the network. A raw
@@ -75,7 +77,7 @@ export class Network extends ReadyResource {
      * @param {{ timeout?: number }} [opts]
      * @returns {Promise<void>}
      */
-    flush({ timeout }?: {
+    flush(opts?: {
         timeout?: number;
     }): Promise<void>;
     /**
@@ -153,5 +155,7 @@ export type NetworkOpts = {
 export type Replicable = {
     replicate: (stream: any) => any;
 };
+import { channelTopic } from './transports/dht.js';
 import ReadyResource from 'ready-resource';
+import { DHTTransport } from './transports/dht.js';
 import { Discovery } from './discovery.js';

package/types/network/{bluetooth.d.ts → transports/ble.d.ts}

@@ -8,35 +8,34 @@
  */
 export function toServiceUUID(topic: Uint8Array, tag?: string): string;
 /**
- * Dual-role BLE transport: advertises + scans one service UUID, opens an L2CAP
- * channel to each discovered peer, and feeds it into `network.inject`. From
+ * Dual-role BLE transport: advertises + scans one service UUID, opens a GATT
+ * byte-stream to each discovered peer, and feeds it into `network.inject`. From
  * there replication and pairing are transport-agnostic (see Network.inject).
  *
- * Choreography mirrors the proven bare-mobile-doctor worklet: server adds a
- * readable PSM characteristic at startup and answers reads dynamically; the
- * central connects, reads "<psm>:<nodeId>", tie-breaks, then opens the channel.
- * `backend` is bare-bluetooth in production and a mock in tests.
- *
- * ponytail: capability-handshake DoS link-scoring is deferred — it needs a
- * replication-progress signal (design §4b). v1 caps links + times out dials.
+ * The server adds one data characteristic (write + notify) and advertises. The
+ * central connects, discovers the characteristic, subscribes, then framed bytes
+ * flow both ways — central→server as GATT writes, server→central as
+ * notifications — each tagged with an 8-byte session id. `backend` is
+ * bare-bluetooth in production and a mock in tests.
  *
  * @extends ReadyResource
  */
-export class BluetoothTransport extends ReadyResource {
+export class BLETransport extends ReadyResource {
     /**
      * @param {object} opts
      * @param {any} opts.backend            bare-bluetooth-shaped module (Central, Server, Service, Characteristic).
-     * @param {import('./index.js').Network} opts.network
+     * @param {import('../index.js').Network} opts.network
      * @param {Uint8Array} opts.uuid        The 32-byte topic the service UUID derives from.
      * @param {Uint8Array} opts.nodeId      Stable local id (identity/device key) for the initiate tie-break.
      * @param {string} [opts.tag]           UUID namespace (channel mesh vs invite mesh).
      * @param {number} [opts.cap]           Max concurrent links; gossip covers the rest.
      * @param {{ scanMode?: any }} [opts.scanOptions]  Platform scan options (e.g. Android low-power).
      * @param {boolean} [opts.keepLinks]    On close, stop the radio but leave established links alive (invite rendezvous: the link outlives the QR and carries the initial replication).
+     * @param {string} [opts.name]          Local app-user display name, sent to peers over a hello frame.
      */
-    constructor({ backend, network, uuid, nodeId, tag, cap, scanOptions, keepLinks }: {
+    constructor({ backend, network, uuid, nodeId, tag, cap, scanOptions, keepLinks, name }: {
         backend: any;
-        network: import("./index.js").Network;
+        network: import("../index.js").Network;
         uuid: Uint8Array;
         nodeId: Uint8Array;
         tag?: string;
@@ -45,9 +44,11 @@ export class BluetoothTransport extends ReadyResource {
             scanMode?: any;
         };
         keepLinks?: boolean;
+        name?: string;
     });
     backend: any;
-    network: import("./index.js").Network;
+    network: import("../index.js").Network;
+    name: string;
     nodeId: Uint8Array<ArrayBufferLike>;
     nodeHex: any;
     serviceUUID: string;
@@ -59,12 +60,20 @@ export class BluetoothTransport extends ReadyResource {
     state: string;
     central: any;
     server: any;
-    psm: any;
+    _dataChar: any;
+    /** sessionId hex → { stream, sid } for server-side (peripheral) sessions */
+    _sessions: Map<any, any>;
+    /** serialized server notify queue: { frame, resolve, reject } */
+    _notifyQueue: any[];
     _scanning: boolean;
     _advertising: boolean;
     _serviceAdded: boolean;
-    /** peripheral id being dialed → its connect-timeout timer */
-    _dialing: Map<any, any>;
+    /** peripheral id → per-peer dial state { timer, linked, coolUntil, failures, peerKey, peripheral } */
+    _devices: Map<any, any>;
+    /** last central.connect timestamp — global inter-dial rate limit */
+    _lastDial: number;
+    _scanTimer: any;
+    _suspended: boolean;
     /** live injected links keyed by remote node id hex */
     peers: Map<any, any>;
     /**
@@ -77,17 +86,48 @@ export class BluetoothTransport extends ReadyResource {
      */
     shouldInitiate(peerNodeId: Uint8Array): boolean;
     get linkCount(): number;
+    _device(id: any): any;
+    _prune(id: any): void;
     _startServer(Service: any, Characteristic: any): void;
     _maybeAdvertise(): void;
+    _onWriteRequests(requests: any): void;
+    _onServerFrame(data: any): void;
+    _closeServerSession(sidHex: any, sid: any): void;
+    _helloPayload(): any;
+    _parseHello(payload: any): string;
+    _applyPeerName(session: any, payload: any): void;
+    _enqueueNotify(f: any): Promise<any>;
+    _drainNotify(): void;
     _startScan(): void;
+    _armScanRestart(): void;
+    _stopScan(): void;
     _onState(raw: any): void;
     _onDiscover(peripheral: any): void;
     _onConnect(peripheral: any): void;
+    _startCentralSession(peripheral: any, char: any): void;
+    _onCentralNotify(peripheral: any, data: any): void;
+    _centralSend(peripheral: any, char: any, f: any): any;
+    _writeOnce(peripheral: any, char: any, f: any): Promise<any>;
     _abortDial(peripheral: any, _reason: any): void;
     _clearDial(id: any): void;
+    _isDialing(): boolean;
     _onCentralError(err: any): void;
-    _onChannel(l2cap: any, isInitiator: any, peripheralId: any): void;
-    _track(conn: any, peripheralId: any): void;
+    _onChannel(stream: any, isInitiator: any, peripheralId: any): any;
+    _track(conn: any, peripheralId: any, isInitiator: any): void;
     _untrack(conn: any): void;
+    _sayGoodbye(): Promise<void>;
+    /**
+     * Pause radio activity but KEEP the Server/Central instances and the
+     * registered GATT service alive — the toggle-friendly counterpart to _close.
+     * CoreBluetooth managers can't be destroy()ed (native double-free), so one
+     * transport is reused across toggles rather than recreated. Idempotent.
+     */
+    suspend(): Promise<void>;
+    /**
+     * Restart advertising + scanning on the SAME Server/Central. `_serviceAdded`
+     * is still true (the service was never removed) so advertising resumes
+     * immediately. Safe to call repeatedly; no-op once closing/closed.
+     */
+    resume(): void;
 }
 import ReadyResource from 'ready-resource';

package/types/network/transports/dht.d.ts

@@ -0,0 +1,75 @@
+export function channelTopic(topic: any, channel: any): any;
+/**
+ * @typedef {object} DHTTransportOpts
+ * @property {import('../../identity/index.js').Identity} [identity]  Long-lived keypair used as the swarm identity.
+ * @property {Array<{ host: string, port: number }>} [bootstrap]      Custom DHT bootstrap nodes.
+ * @property {(remotePublicKey: Uint8Array, payload: any) => boolean} [firewall]  Incoming-connection filter.
+ * @property {Uint8Array[]} [relayThrough]                            Relay public keys to tunnel through.
+ * @property {string} [channel]                                       Optional network-isolation label; only same-channel peers meet.
+ */
+/**
+ * The internet transport: a Hyperswarm that finds peers over the DHT. Owns the
+ * swarm's whole lifecycle — construction (identity keyPair, bootstrap, firewall,
+ * relay), the channel-topic join/leave wrapping, flush, suspend/resume, and
+ * teardown. {@link Network} subscribes to `this.swarm`'s connection/peer events
+ * and drives topic joins; the swarm-specific wiring lives here.
+ */
+export class DHTTransport {
+    /** @param {DHTTransportOpts} [opts] */
+    constructor({ identity, bootstrap, firewall, relayThrough, channel }?: DHTTransportOpts);
+    swarm: any;
+    /** @returns {boolean} */
+    get suspended(): boolean;
+    /**
+     * Wait for pending DHT announces and lookups to settle, bounded by timeout.
+     *
+     * @param {{ timeout?: number }} [opts]
+     * @returns {Promise<void>}
+     */
+    flush({ timeout }?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Pause the swarm — keeps state, drops sockets. Idempotent.
+     *
+     * @returns {Promise<void>}
+     */
+    suspend(): Promise<void>;
+    /**
+     * Resume a suspended swarm. Idempotent.
+     *
+     * @returns {Promise<void>}
+     */
+    resume(): Promise<void>;
+    /**
+     * Flush pending discovery, then tear down the swarm. Idempotent.
+     *
+     * @returns {Promise<void>}
+     */
+    destroy(): Promise<void>;
+}
+export type DHTTransportOpts = {
+    /**
+     * Long-lived keypair used as the swarm identity.
+     */
+    identity?: import("../../identity/index.js").Identity;
+    /**
+     * Custom DHT bootstrap nodes.
+     */
+    bootstrap?: Array<{
+        host: string;
+        port: number;
+    }>;
+    /**
+     * Incoming-connection filter.
+     */
+    firewall?: (remotePublicKey: Uint8Array, payload: any) => boolean;
+    /**
+     * Relay public keys to tunnel through.
+     */
+    relayThrough?: Uint8Array[];
+    /**
+     * Optional network-isolation label; only same-channel peers meet.
+     */
+    channel?: string;
+};

package/types/network/transports/gatt.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A dumb byte-carrying duplex for the GATT transport. Framing and session logic
+ * live in BLETransport; this only fragments outbound writes to fit a GATT
+ * write and pushes inbound payload bytes.
+ *
+ * @extends Duplex
+ */
+export class GattStream extends Duplex<import("streamx").DuplexEvents> {
+    /**
+     * @param {object} opts
+     * @param {(buffer: Uint8Array) => Promise<void>} opts.send  Transmit one payload piece (transport frames it).
+     * @param {() => void} [opts.onclose]  Called once on teardown (send a close frame, disconnect).
+     */
+    constructor({ send, onclose }?: {
+        send: (buffer: Uint8Array) => Promise<void>;
+        onclose?: () => void;
+    });
+    _send: (buffer: Uint8Array) => Promise<void>;
+    _onclose: () => void;
+    _write(chunk: any, cb: any): Promise<void>;
+    receive(buffer: any): void;
+    remoteEnd(): void;
+    _destroy(cb: any): void;
+}
+import { Duplex } from 'streamx';