@cero-base/core 0.2.0 → 0.4.0

package/src/lib/utils.js

@@ -1,60 +1,65 @@
-import { SCOPE_LOCAL, SCOPE_PRIVATE, SCOPE_SHARED } from './constants.js'
-
-/** Map user-facing scope to cero namespace */
-const SCOPE_NS = {
-  [SCOPE_LOCAL]: 'local',
-  [SCOPE_PRIVATE]: 'identity',
-  [SCOPE_SHARED]: 'room'
-}
+import crypto from 'crypto'
+import { Readable } from 'streamx'
+import z32 from 'z32'
+import { encode, decode, isValid } from 'hypercore-id-encoding'
 
 /**
- * Convert plural collection name to singular type name
- * tasks -> task, categories -> category
+ * Generate a short opaque id (z32-encoded 16 random bytes).
+ *
+ * @returns {string}
  */
-export function singular(name) {
-  if (name.endsWith('ies')) return name.slice(0, -3) + 'y'
-  if (name.endsWith('s')) return name.slice(0, -1)
-  return name
-}
-
-/** Get cero namespace for a scope */
-export function scopeNs(scope) {
-  return SCOPE_NS[scope]
-}
-
-/** Get dispatch/collection path: @ns/name */
-export function scopePath(scope, name) {
-  return `@${SCOPE_NS[scope]}/${name}`
-}
-
-export function isLocal(scope) {
-  return scope === SCOPE_LOCAL
+export function genId() {
+  return z32.encode(crypto.randomBytes(16))
 }
 
-export function isPrivate(scope) {
-  return scope === SCOPE_PRIVATE
-}
+/**
+ * z32-encode a 32-byte key into a canonical string id.
+ *
+ * @type {(key: Uint8Array) => string}
+ */
+export const toId = encode
 
-export function isShared(scope) {
-  return scope === SCOPE_SHARED
-}
+/**
+ * Decode a canonical string id back into a 32-byte key.
+ *
+ * @type {(id: string) => Uint8Array}
+ */
+export const toKey = decode
 
-export function debounce(fn, ms = 0) {
-  let timer
-  return (...args) => {
-    clearTimeout(timer)
-    timer = setTimeout(() => fn(...args), ms)
-  }
-}
+/**
+ * Test whether a string is a well-formed canonical id.
+ *
+ * @type {(id: string) => boolean}
+ */
+export const isKeyId = isValid
 
 /**
- * Convert field definitions to hyperschema field array
+ * Stream-of-snapshots primitive. Couples a `get` (returns the latest value)
+ * with a `watch` (re-fires on change) and emits the newest snapshot every
+ * time `watch` ticks.
+ *
+ * @template T
+ * @param {object} args
+ * @param {() => Promise<T> | T} args.get
+ * @param {(fn: () => void) => (() => void) | void} args.watch  Returns an unsubscribe.
+ * @returns {import('streamx').Readable<T>}
  */
-export function toFields(fields) {
-  return Object.entries(fields).map(([name, def]) => ({
-    name,
-    type: def.type,
-    required: def.required ?? true,
-    array: def.array ?? false
-  }))
+export function subscribe({ get, watch }) {
+  let stop = null
+  const stream = new Readable({
+    destroy(cb) {
+      Promise.resolve(stop?.()).then(() => cb(null), cb)
+    }
+  })
+  const push = async () => {
+    if (stream.destroyed) return
+    try {
+      stream.push(await get())
+    } catch (e) {
+      stream.destroy(e)
+    }
+  }
+  stop = watch(push)
+  push()
+  return stream
 }

package/src/network/discovery.js

@@ -0,0 +1,80 @@
+import safetyCatch from 'safety-catch'
+
+import { ACTIVE, PASSIVE } from '../lib/constants.js'
+import { CeroError } from '../lib/errors.js'
+
+/**
+ * Handle for a single topic membership on a {@link Network}. Wraps a hyperswarm
+ * PeerDiscovery session and lets it switch between active/passive announce/lookup.
+ */
+export class Discovery {
+  /**
+   * @param {import('./index.js').Network} network  Owning network.
+   * @param {any} session  Hyperswarm PeerDiscovery session from `swarm.join()`.
+   * @param {'active' | 'passive'} mode
+   */
+  constructor(network, session, mode) {
+    this.network = network
+    this.session = session
+    this._mode = mode
+    this._destroyed = false
+  }
+
+  /** @returns {'active' | 'passive'} */
+  get mode() {
+    return this._mode
+  }
+
+  /** @returns {boolean} */
+  get destroyed() {
+    return this._destroyed
+  }
+
+  /**
+   * Switch to active (client+server) announce/lookup.
+   *
+   * @returns {Promise<void>}
+   */
+  async activate() {
+    if (this._destroyed) throw CeroError.DESTROYED('Discovery')
+    this._mode = ACTIVE
+    await this.session.refresh({ client: true, server: true })
+  }
+
+  /**
+   * Switch to passive announce.
+   *
+   * @returns {Promise<void>}
+   */
+  async deactivate() {
+    if (this._destroyed) throw CeroError.DESTROYED('Discovery')
+    this._mode = PASSIVE
+    await this.session.refresh({ client: false, server: true })
+  }
+
+  /**
+   * Wait for the current announce/lookup to settle.
+   *
+   * @returns {Promise<void>}
+   */
+  async flush() {
+    if (this._destroyed) return
+    await this.session.flushed()
+  }
+
+  /**
+   * Leave the topic and tear down the session. Idempotent.
+   *
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    if (this._destroyed) return
+    this._destroyed = true
+    this.network._discoveries.delete(this)
+    try {
+      await this.session.destroy()
+    } catch (err) {
+      safetyCatch(err)
+    }
+  }
+}

package/src/network/index.js

@@ -0,0 +1,231 @@
+import Hyperswarm from 'hyperswarm'
+import ProtomuxWakeup from 'protomux-wakeup'
+import ReadyResource from 'ready-resource'
+import safetyCatch from 'safety-catch'
+import b4a from 'b4a'
+
+import { ACTIVE, PASSIVE } from '../lib/constants.js'
+import { CeroError } from '../lib/errors.js'
+import { Discovery } from './discovery.js'
+
+/**
+ * @typedef {object} NetworkOpts
+ * @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.
+ *
+ * @typedef {{ replicate: (stream: any) => any }} Replicable
+ */
+
+/**
+ * Hyperswarm peer-discovery + replication multiplexer. Wraps a swarm and a
+ * shared wakeup channel, replicating any attached resource onto every peer.
+ */
+export class Network extends ReadyResource {
+  /** @param {NetworkOpts} [opts] */
+  constructor({ identity, bootstrap, firewall, relayThrough } = {}) {
+    super()
+    this.identity = identity || null
+    this.bootstrap = bootstrap || null
+    this.firewall = firewall || null
+    this.relayThrough = relayThrough || null
+
+    this.swarm = null
+    this.wakeup = new ProtomuxWakeup()
+
+    this._replicateables = new Set()
+    this._discoveries = new Set()
+  }
+
+  /** @returns {Map<string, any>} Known peers keyed by public-key string. */
+  get peers() {
+    return this.swarm ? this.swarm.peers : new Map()
+  }
+
+  /** @returns {Set<any>} Live connection streams. */
+  get connections() {
+    return this.swarm ? this.swarm.connections : new Set()
+  }
+
+  /** @returns {boolean} */
+  get suspended() {
+    return this.swarm?.suspended === true
+  }
+
+  async _open() {
+    const opts = {}
+    if (this.identity)
+      opts.keyPair = { publicKey: this.identity.publicKey, secretKey: this.identity.secretKey }
+    if (this.bootstrap) opts.bootstrap = this.bootstrap
+    if (this.firewall) opts.firewall = this.firewall
+    if (this.relayThrough) opts.relayThrough = this.relayThrough
+
+    this.swarm = new Hyperswarm(opts)
+
+    this.swarm.on('connection', (stream, info) => {
+      if (this.closing || this.closed) {
+        stream.destroy()
+        return
+      }
+      this.wakeup.addStream(stream)
+      for (const r of this._replicateables) replicateInto(r, stream)
+      this.emit('connection', stream, info)
+    })
+    this.swarm.on('peer-add', (peer) => this.emit('peer-add', peer))
+    this.swarm.on('peer-remove', (peer) => this.emit('peer-remove', peer))
+  }
+
+  /**
+   * 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.closing || this.closed) return
+    if (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.closing || this.closed) return
+    if (!this.swarm.suspended) return
+    try {
+      await this.swarm.resume()
+    } catch (err) {
+      safetyCatch(err)
+    }
+  }
+
+  async _close() {
+    for (const d of [...this._discoveries]) {
+      try {
+        await d.destroy()
+      } catch (err) {
+        safetyCatch(err)
+      }
+    }
+
+    if (this.swarm) {
+      try {
+        await this.flush()
+      } catch (err) {
+        safetyCatch(err)
+      }
+      try {
+        await this.swarm.destroy()
+      } catch (err) {
+        safetyCatch(err)
+      }
+      this.swarm = null
+    }
+
+    if (this.wakeup) {
+      try {
+        await this.wakeup.destroy()
+      } catch (err) {
+        safetyCatch(err)
+      }
+    }
+  }
+
+  /**
+   * Announce/lookup on a 32-byte topic and return a Discovery handle.
+   *
+   * @param {Uint8Array} topic
+   * @param {{ mode?: 'active' | 'passive' }} [opts]  `active` = client+server, `passive` = server-only
+   * @returns {Discovery}
+   */
+  join(topic, { mode = ACTIVE } = {}) {
+    if (mode !== ACTIVE && mode !== PASSIVE) {
+      throw CeroError.INVALID('mode must be "active" or "passive"')
+    }
+    if (this.closing || this.closed) throw CeroError.CLOSED('Network')
+    if (!this.swarm) throw CeroError.NOT_READY('Network', 'network')
+    if (!isTopic(topic)) throw CeroError.INVALID('topic must be a 32-byte buffer')
+
+    const session =
+      mode === ACTIVE
+        ? this.swarm.join(topic, { client: true, server: true })
+        : this.swarm.join(topic, { client: false, server: true })
+
+    const discovery = new Discovery(this, session, mode)
+    this._discoveries.add(discovery)
+    return discovery
+  }
+
+  /**
+   * Register a replicable resource (hypercore, autobee, hyperdb).
+   * It is replicated on every current and future swarm connection.
+   *
+   * @param {Replicable} core
+   * @returns {void}
+   */
+  attach(core) {
+    if (!core) throw CeroError.REQUIRED('core')
+    this._replicateables.add(core)
+    if (this.swarm) {
+      for (const stream of this.swarm.connections) replicateInto(core, stream)
+    }
+  }
+
+  /**
+   * Unregister a previously attached resource. New connections will no
+   * longer replicate it (existing replication streams continue).
+   *
+   * @param {Replicable} core
+   * @returns {void}
+   */
+  detach(core) {
+    if (!core) throw CeroError.REQUIRED('core')
+    this._replicateables.delete(core)
+  }
+
+  /**
+   * Replicate a one-off resource onto every current swarm connection
+   * without registering it as a long-lived attachment.
+   *
+   * @param {Replicable} target
+   * @returns {void}
+   */
+  replicate(target) {
+    if (!target || typeof target.replicate !== 'function') {
+      throw CeroError.INVALID('target must be an object with a replicate(stream) method')
+    }
+    if (this.swarm) {
+      for (const stream of this.swarm.connections) replicateInto(target, stream)
+    }
+  }
+}
+
+function replicateInto(core, stream) {
+  try {
+    core.replicate(stream)
+  } catch (err) {
+    safetyCatch(err)
+  }
+}
+
+function isTopic(x) {
+  return (b4a.isBuffer(x) || x instanceof Uint8Array) && x.length === 32
+}