@cero-base/cero 2.1.8 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "2.1.8",
+  "version": "2.2.0",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "sideEffects": false,
@@ -99,8 +99,8 @@
     "test:node": "find test -name '*.test.js' | sort | xargs -P4 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^2.1.8",
-    "b4a": "^1.8.1",
+    "@cero-base/core": "^2.2.0",
+    "b4a": "^1.9.0",
     "bare-abort-controller": "^1.1.2",
     "bare-crypto": "^1.15.3",
     "bare-fs": "^4.8.1",
@@ -112,10 +112,10 @@
     "hypercore": "^11.36.1",
     "hypercore-crypto": "^3.7.0",
     "hypercore-id-encoding": "^1.3.0",
-    "hypercore-storage": "^3.2.1",
+    "hypercore-storage": "^3.3.1",
     "hyperdb": "^6.9.0",
     "hyperdispatch": "^1.6.0",
-    "hyperschema": "^1.26.1",
+    "hyperschema": "^1.26.2",
     "ready-resource": "^1.2.0",
     "safety-catch": "^1.0.3",
     "streamx": "^2.28.1",
@@ -125,7 +125,7 @@
   "devDependencies": {
     "@hyperswarm/testnet": "^3.1.4",
     "bare-events": "^2.9.2",
-    "bare-fetch": "^3.3.0",
+    "bare-fetch": "^3.4.0",
     "bare-process": "^4.5.1",
     "bare-url": "^2.5.4",
     "brittle": "^4.2.0",

package/src/build/internal.js

@@ -111,7 +111,8 @@ const COMMANDS = [
   ['rotate', 'req-handle', 'res-epoch'],
   ['set-active', 'req-set-active', 'res-ok'],
   ['suspend', 'req-empty', 'res-ok'],
-  ['resume', 'req-empty', 'res-ok']
+  ['resume', 'req-empty', 'res-ok'],
+  ['errors', 'req-empty', 'res-error', true]
 ]
 
 export function commands(ns) {

package/src/build/schemas.js

@@ -203,5 +203,10 @@ export const rpc = {
   },
   'res-epoch': {
     epoch: required(uint)
+  },
+  'res-error': {
+    message: required(string),
+    code: string,
+    stack: string
   }
 }

package/src/handle/index.js

@@ -116,7 +116,7 @@ export class Handle extends ReadyResource {
     this._opts = opts.opts || {}
     this.extensions = parent?.extensions || extensionsOf(spec, this._opts.extensions)
     this.operators = parent?.operators || operatorsOf(spec, this._opts.operators)
-    this._onerror = this._opts.onerror || safetyCatch
+    this._onerror = this._opts.onerror || ((err) => console.error(err))
     this.children = parent ? null : new Set()
     this._typeHooks = parent ? null : new Set()
     this._loading = parent ? null : new Map()
@@ -260,36 +260,40 @@ export class Handle extends ReadyResource {
     for (const hex of this._blobKeys || []) this.root._coreKeys.delete(hex)
     for (const r of [...this._owned]) r.destroy?.()
     this._owned.clear()
-    if (this._blobs) await this._blobs.close()
-    for (const b of this._epochBlobs?.values() || []) await b.close().catch(safetyCatch)
-    this._epochBlobs = null
-    if (this.children) {
-      for (const c of [...this.children]) await c.close()
-      this.children.clear()
-    }
     if (this._invitesSync) {
       this.store.off('update', this._invitesSync)
       this._invitesSync = null
     }
-    if (this.pair) await this.pair.close()
+    if (this._discovery) this._discovery.destroy().catch(safetyCatch)
+
+    const steps = [
+      () => this._blobs?.close(),
+      ...[...(this._epochBlobs?.values() || [])].map((b) => () => b.close()),
+      ...[...(this.children || [])].map((c) => () => c.close()),
+      () => this.pair?.close()
+    ]
+    this._epochBlobs = null
+    this.children?.clear()
 
     if (this.parent) {
       this.parent.children?.delete(this)
-      await this.store.close()
-      return
-    }
-
-    if (this.local) await this.local.close()
-    if (this._fileServer) {
-      await this._fileServer.close()
-      this._fileServer = null
+      steps.push(() => this.store.close())
+    } else {
+      const store = this.store.store
+      steps.push(
+        () => this.bluetooth?.close(),
+        () => this.local?.close(),
+        async () => {
+          await this._fileServer?.close()
+          this._fileServer = null
+        },
+        () => this.store.close(),
+        () => this.network.close(),
+        () => store.close(),
+        () => this._storage?.close()
+      )
     }
-    const store = this.store.store
-    await this.store.close()
-    if (this._discovery) this._discovery.destroy().catch(safetyCatch)
-    await this.network.close()
-    await store.close()
-    if (this._storage) await this._storage.close()
+    await settle(steps)
   }
 
   /**
@@ -862,26 +866,18 @@ export class Handle extends ReadyResource {
 
   async _suspend() {
     if (this.closing || this.closed) return
-    await Promise.all([...this.children].map((c) => c.pair?.suspend()))
-    await this.bluetooth?.suspend()
-    await this.network.suspend()
-    try {
-      await this.store.store.suspend()
-    } catch (err) {
-      this._onerror(err)
-    }
+    await Promise.all([...this.children].map((c) => c.pair?.suspend().catch(this._onerror)))
+    await this.bluetooth?.suspend().catch(this._onerror)
+    await this.network.suspend().catch(this._onerror)
+    await this.store.store.suspend().catch(this._onerror)
   }
 
   async _resume() {
     if (this.closing || this.closed) return
-    try {
-      await this.store.store.resume()
-    } catch (err) {
-      this._onerror(err)
-    }
-    await this.network.resume()
-    await this.bluetooth?.resume()
-    await Promise.all([...this.children].map((child) => child.pair?.resume()))
+    await this.store.store.resume().catch(this._onerror)
+    await this.network.resume().catch(this._onerror)
+    await this.bluetooth?.resume().catch(this._onerror)
+    await Promise.all([...this.children].map((c) => c.pair?.resume().catch(this._onerror)))
   }
 
   // a child is a child once it has its operators, the hooks declared for its type, and a slot
@@ -1019,3 +1015,16 @@ function pickHandle(spec, type) {
 function randomNs() {
   return z32.encode(Identity.randomBytes(8))
 }
+
+// run every teardown step, then surface the first failure: a bug must not leak the storage lock
+async function settle(steps) {
+  let failed = null
+  for (const step of steps) {
+    try {
+      await step()
+    } catch (err) {
+      failed ??= err
+    }
+  }
+  if (failed) throw failed
+}

package/src/index.js

@@ -67,7 +67,7 @@ export { t, schema } from './lib/spec.js'
  * @property {Uint8Array} [key]                        Existing database key to recover into, skipping the pointer lookup.
  * @property {Uint8Array} [encryptionKey]              Pre-existing encryption key.
  * @property {Record<string, Function>} [routes]       Custom RPC routes for the database dispatcher.
- * @property {(err: any) => void} [onerror]            Background-task error handler.
+ * @property {(err: any) => void} [onerror]            Background-task error handler; without one, errors emit 'error' on the root handle.
  * @property {number} [recoveryTimeout]                Max wait to find another device and be admitted, in ms. Defaults to 30000.
  * @property {Uint8Array} [storageKey]                 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it.
  * @property {import('./extensions/index.js').Extension[]} [extensions]  The extensions this instance runs, instead of the ones the spec carries. Build with the same list.
@@ -93,12 +93,23 @@ export async function cero(dir, spec, opts = {}) {
   let network = null
   let discovery = null
   let me = null
+  // background failures reach the app through opts.onerror or the root's 'error' event, never silence
+  const onerror =
+    opts.onerror ||
+    ((err) => (me?.listenerCount('error') ? me.emit('error', err) : console.error(err)))
+  opts = { ...opts, onerror }
   // any failure during open must close what opened, or the storage lock leaks
   try {
     await storage.ready()
     await fs.promises.chmod(`${dir}/main`, 0o700)
     store = new Corestore(storage, { manifestVersion: 2 })
     await store.ready()
+    store.watch((core) => {
+      const session = new Hypercore({ core, weak: true })
+      session.on('verification-error', onerror)
+      session.on('invalid-request', onerror)
+      session.on('conflict', () => onerror(CeroError.CONFLICT(`fork on core ${session.id}`)))
+    })
 
     if (spec.local && spec.meta?.local) {
       local = new Local(null, spec, { store, storageKey: opts.storageKey })
@@ -126,7 +137,8 @@ export async function cero(dir, spec, opts = {}) {
       channel: opts.channel,
       store,
       mirrors: opts.mirrors,
-      presence: opts.presence
+      presence: opts.presence,
+      onerror
     })
     await network.ready()
     discovery = network.join(identity.topic)
@@ -200,7 +212,6 @@ export async function cero(dir, spec, opts = {}) {
         maxInbound: bt.maxInbound,
         pipe: bt.pipe
       })
-      me.once('close', () => me.bluetooth.close().catch(safetyCatch))
       await me.bluetooth.ready()
     }
 

package/src/rpc/client.js

@@ -457,6 +457,20 @@ export class Client extends RPCClient {
     this.local = null
   }
 
+  // the worker's background errors, delivered the way a local root delivers them
+  _pumpErrors() {
+    const report = (err) =>
+      this.listenerCount('error') ? this.emit('error', err) : console.error(err)
+    const pump = async () => {
+      for await (const { message, code, stack } of this.rpc.errors({})) {
+        report(Object.assign(new Error(message), code && { code }, stack && { stack }))
+      }
+    }
+    pump().catch((err) => {
+      if (err.code !== 'PREMATURE_CLOSE' && err.code !== 'CHANNEL_CLOSED') report(err)
+    })
+  }
+
   async _open() {
     await super._open()
     const { id, deviceId, fileBase, fileToken } = await this.rpc.init({})
@@ -468,6 +482,7 @@ export class Client extends RPCClient {
     Ref.attach(this, /** @type {Spec} */ (this.spec).meta.refs)
     bind(this, null, this.operators)
     if (/** @type {Spec} */ (this.spec).meta.local?.refs) this.local = new LocalRefs(this)
+    this._pumpErrors()
   }
 
   /** Pause networking and storage on the server. Idempotent. */

package/src/rpc/server.js

@@ -43,7 +43,10 @@ export class Server extends RPCServer {
     super(ipc, spec)
     if (spec.local?.schema && !spec.local.codec) bindCodec(spec.local)
     this.storage = storage
-    this.opts = opts
+    this._report = opts.onerror || ((err) => console.error(err))
+    this.opts = { ...opts, onerror: (err) => this._onerror(err) }
+    /** @type {Set<object>} open error streams, one per connected client */
+    this._errors = new Set()
     this.me = null
     this.handles = new Map()
     /** @type {Map<string, Set<object>>} handle id → its open watch streams */
@@ -87,7 +90,22 @@ export class Server extends RPCServer {
   }
 
   /** Wire the `init` handler that lazily constructs the root cero handle. */
+  _onerror(err) {
+    if (!this._errors.size) return this._report(err)
+    const frame = {
+      message: err?.message || String(err),
+      code: err?.code || '',
+      stack: err?.stack || ''
+    }
+    for (const stream of this._errors) stream.write(frame)
+  }
+
   _wireInit() {
+    this.rpc.onErrors((stream) => {
+      this._errors.add(stream)
+      stream.on('error', safetyCatch)
+      stream.on('close', () => this._errors.delete(stream))
+    })
     this.rpc.onInit(async () => {
       // a reloaded UI is a new client on the same worker: it re-attaches, its old streams end
       if (this.me) {

package/types/build/schemas.d.ts

@@ -196,4 +196,9 @@ export declare const rpc: {
     'res-epoch': {
         epoch: import("@cero-base/core").Prim;
     };
+    'res-error': {
+        message: import("@cero-base/core").Prim;
+        code: import("@cero-base/core").Prim;
+        stack: import("@cero-base/core").Prim;
+    };
 };

package/types/index.d.ts

@@ -74,7 +74,7 @@ export type CeroOpts = {
      */
     routes?: Record<string, Function>;
     /**
-     * Background-task error handler.
+     * Background-task error handler; without one, errors emit 'error' on the root handle.
      */
     onerror?: (err: any) => void;
     /**
@@ -123,7 +123,7 @@ export type CeroOpts = {
  * @property {Uint8Array} [key]                        Existing database key to recover into, skipping the pointer lookup.
  * @property {Uint8Array} [encryptionKey]              Pre-existing encryption key.
  * @property {Record<string, Function>} [routes]       Custom RPC routes for the database dispatcher.
- * @property {(err: any) => void} [onerror]            Background-task error handler.
+ * @property {(err: any) => void} [onerror]            Background-task error handler; without one, errors emit 'error' on the root handle.
  * @property {number} [recoveryTimeout]                Max wait to find another device and be admitted, in ms. Defaults to 30000.
  * @property {Uint8Array} [storageKey]                 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it.
  * @property {import('./extensions/index.js').Extension[]} [extensions]  The extensions this instance runs, instead of the ones the spec carries. Build with the same list.

package/types/rpc/client.d.ts

@@ -89,6 +89,7 @@ export declare class Client extends RPCClient {
     constructor(ipc: any, spec: Spec, opts?: {
         operators?: Record<string, any>;
     });
+    _pumpErrors(): void;
     _open(): Promise<void>;
     /** Pause networking and storage on the server. Idempotent. */
     suspend(): Promise<void>;

package/types/rpc/server.d.ts

@@ -63,6 +63,7 @@ export type GetResult = {
  */
 export declare class Server extends RPCServer {
     storage: string;
+    _report: (err: Error) => void;
     opts: {
         name?: string;
         bootstrap?: Array<{
@@ -70,8 +71,10 @@ export declare class Server extends RPCServer {
             port: number;
         }>;
         isMobile?: boolean;
-        onerror?: (err: Error) => void;
+        onerror: (err: any) => void;
     };
+    /** @type {Set<object>} open error streams, one per connected client */
+    _errors: Set<object>;
     me: import("../handle/index.js").CeroHandle;
     handles: Map<any, any>;
     /** @type {Map<string, Set<object>>} handle id → its open watch streams */
@@ -98,6 +101,7 @@ export declare class Server extends RPCServer {
     /** End every watch stream bound to a handle (e.g. when it closes or leaves). */
     _endWatches(handle: any): void;
     /** Wire the `init` handler that lazily constructs the root cero handle. */
+    _onerror(err: any): void;
     _wireInit(): void;
     /** Wire the `restore` handler that rebuilds the local store from a phrase. */
     _wireRestore(): void;