@cero-base/cero 0.4.0

package/src/rpc/server.js

@@ -0,0 +1,290 @@
+import { RPCServer, bindCodec } from '@cero-base/core/rpc'
+import { CeroError } from '@cero-base/core/errors'
+
+import { cero, restore } from '../index.js'
+import { put, set, get, del, count, watch, call } from '../lib/operators.js'
+
+/**
+ * @typedef {import('@cero-base/core/rpc').RPCServer} BaseRPCServer
+ *
+ * @typedef {object} ServerOpts
+ * @property {string} storage   Directory passed to `cero()` for the local store.
+ * @property {object} spec      Compiled cero spec (schema + rpc + handles).
+ * @property {string} [name]    Optional display name forwarded to `cero()`.
+ * @property {Array<{ host: string, port: number }>} [bootstrap]  Custom DHT bootstrap.
+ * @property {boolean} [isMobile]
+ * @property {(err: Error) => void} [onerror]
+ *
+ * @typedef {object} Identity
+ * @property {string} id        Long-lived cero identity id.
+ * @property {string} deviceId  Per-device id (empty when no `local` spec).
+ * @property {string|null} phrase  BIP39 recovery phrase for the identity.
+ *
+ * @typedef {{ ref: any, codec: any }} RefAndCodec
+ *
+ * @typedef {{ data: any, total?: number, size?: number }} GetResult  Single-ref get omits `total`/`size`; list/handle refs include them.
+ */
+
+/**
+ * IPC-side RPC server for cero. Bridges an `hrpc` channel to a live
+ * `Handle` tree: lazy-initializes the root via `cero()` on the first
+ * `init` call, then exposes data ops, pairing, and handle lifecycle
+ * over the wire using the spec-bound codec.
+ */
+export class Server extends RPCServer {
+  /**
+   * @param {any} ipc                Framed IPC stream (must be writable).
+   * @param {Partial<ServerOpts>} [opts]
+   */
+  constructor(ipc, { storage, spec, ...opts } = {}) {
+    if (!storage) throw CeroError.REQUIRED('storage')
+    if (!spec) throw CeroError.REQUIRED('spec')
+    super(ipc, spec)
+    this.storage = storage
+    this.opts = opts
+    this.me = null
+    this.handles = new Map()
+    this._wireInit()
+  }
+
+  /**
+   * Root cero id (null until `init` has run).
+   *
+   * @returns {string|undefined}
+   */
+  get id() {
+    return this.me?.id
+  }
+
+  /**
+   * Root identity object (null until `init` has run).
+   *
+   * @returns {any}
+   */
+  get identity() {
+    return this.me?.identity
+  }
+
+  async _close() {
+    if (this.me) {
+      try {
+        await this.me.close()
+      } catch {}
+    }
+    await super._close()
+  }
+
+  /** Wire the `init` handler that lazily constructs the root cero handle. */
+  _wireInit() {
+    this.rpc.onInit(async () => {
+      if (this.me) throw new CeroError('CONFLICT', 'already initialized')
+      this.me = await cero(this.storage, this.spec, this.opts)
+      this.handles.set(this.me.id, this.me)
+      this._wireData()
+      this._wirePairing()
+      this._wireHandles()
+      this._wireRestore()
+      return this._identity()
+    })
+  }
+
+  /** Wire the `restore` handler that rebuilds the local store from a phrase. */
+  _wireRestore() {
+    this.rpc.onRestore(async ({ phrase }) => {
+      if (!this.me) throw new CeroError('NOT_READY', 'init')
+      this.me = await restore(this.me, phrase)
+      this.handles = new Map([[this.me.id, this.me]])
+      return this._identity()
+    })
+  }
+
+  /** Register the row-level RPC handlers (put/set/get/del/count/watch/call). */
+  _wireData() {
+    this.rpc.onAddRow(async ({ handle, ref, data }) => {
+      const { ref: r, codec } = this._refOf(handle, ref)
+      const { data: row } = await put(r, codec.decodeRow(r.schema, data))
+      return { data: codec.encodeRow(r.schema, row) }
+    })
+
+    this.rpc.onSet(async ({ handle, ref, data }) => {
+      const { ref: r, codec } = this._refOf(handle, ref)
+      const { data: row } = await set(r, codec.decodeRow(r.schema, data))
+      return { data: codec.encodeRow(r.schema, row) }
+    })
+
+    this.rpc.onGet(async ({ handle, ref, query }) => {
+      const { ref: r, codec } = this._refOf(handle, ref)
+      const result = /** @type {GetResult} */ (await get(r, codec.decodeQuery(query)))
+      const data =
+        r.kind === 'single'
+          ? codec.encodeRow(r.schema, result.data)
+          : codec.encodeRows(r.schema, result.data)
+      return { data, total: result.total ?? 0, size: result.size ?? 0 }
+    })
+
+    this.rpc.onGetOne(async ({ handle, ref, id }) => {
+      const { ref: r, codec } = this._refOf(handle, ref)
+      const { data } = await get(r, id)
+      return { data: data ? codec.encodeRow(r.schema, data) : null }
+    })
+
+    this.rpc.onDel(async ({ handle, ref, id }) => {
+      await del(this._refOf(handle, ref).ref, id)
+      return {}
+    })
+
+    this.rpc.onCount(async ({ handle, ref, query }) => {
+      const { ref: r, codec } = this._refOf(handle, ref)
+      const { data } = await count(r, codec.decodeQuery(query))
+      return { count: data }
+    })
+
+    this.rpc.onWatch((stream) => {
+      const { handle, ref, query } = stream.data
+      let r, codec, live
+      try {
+        ;({ ref: r, codec } = this._refOf(handle, ref))
+        live = watch(r, codec.decodeQuery(query))
+      } catch (err) {
+        stream.destroy(err)
+        return
+      }
+      const onData = (snap) => {
+        const data =
+          r.kind === 'single'
+            ? codec.encodeRow(r.schema, snap.data)
+            : codec.encodeRows(r.schema, snap.data)
+        stream.write({ data, total: snap.total ?? 0, size: snap.size ?? 0 })
+      }
+      live.on('data', onData)
+      stream.on('close', () => {
+        live.off('data', onData)
+        live.destroy()
+      })
+    })
+
+    this.rpc.onCall(async ({ handle, op, data }) => {
+      const h = this._resolve(handle)
+      const r = h[op]
+      if (!r) throw CeroError.UNKNOWN('ref', op)
+      await call(r, h.spec.codec.decodeAction(h, op, data))
+      return { data: null }
+    })
+  }
+
+  /** Register invite/revoke/join RPC handlers. */
+  _wirePairing() {
+    this.rpc.onInvite(async ({ handle, role }) => {
+      const h = this._resolve(handle)
+      const invite = await h.invite({ role: role || undefined })
+      return { invite }
+    })
+
+    this.rpc.onRevoke(async ({ handle, invite }) => {
+      const ok = this._resolve(handle).revoke(invite)
+      return { ok }
+    })
+
+    this.rpc.onJoin(async ({ parent, ref, invite }) => {
+      if (this._resolve(parent) !== this.me) throw CeroError.UNSUPPORTED('nested handles')
+      const child = await this.me._join(invite, ref)
+      const id = child.id
+      this.handles.set(id, child)
+      return { id, type: ref, name: '' }
+    })
+  }
+
+  /** Register add/open/close/leave RPC handlers for child handles. */
+  _wireHandles() {
+    this.rpc.onAddHandle(async ({ handle, ref, data }) => {
+      const parent = this._resolve(handle)
+      const info = parent.spec.meta.refs?.[ref] || parent.spec.handles?.[ref]
+      if (!info) throw CeroError.UNKNOWN('handle type', ref)
+      const opts = parent.spec.codec.decodeCreate(data) || {}
+      const child = await this.me._create(ref, opts)
+      const id = child.id
+      this.handles.set(id, child)
+      return { id, type: ref, name: opts.name || '' }
+    })
+
+    this.rpc.onOpenHandle(async ({ parent, row }) => {
+      if (this._resolve(parent) !== this.me) throw CeroError.UNSUPPORTED('nested handles')
+      const { data } = await this.me.store.get('handles', row)
+      if (!data) throw CeroError.UNKNOWN('handle', row)
+      const child = await this.me._load(data.type, row)
+      this.handles.set(row, child)
+      return { id: row, type: data.type, name: data.name || '' }
+    })
+
+    this.rpc.onCloseHandle(async ({ handle }) => {
+      const h = this.handles.get(handle)
+      if (!h || h === this.me) return {}
+      this.handles.delete(handle)
+      await h.close()
+      return {}
+    })
+
+    this.rpc.onLeave(async ({ handle }) => {
+      const h = this.handles.get(handle)
+      if (!h || h === this.me) return {}
+      await this.me.store.call('del-handle', { id: handle })
+      this.handles.delete(handle)
+      await h.close()
+      return {}
+    })
+  }
+
+  /**
+   * Look up a live handle by id, throwing if unknown. Binds the handle's
+   * codec on first use.
+   *
+   * @param {string} id
+   * @returns {any}
+   */
+  _resolve(id) {
+    const h = this.handles.get(id)
+    if (!h) throw CeroError.UNKNOWN('handle', id)
+    if (!h.spec.codec) bindCodec(h.spec)
+    return h
+  }
+
+  /**
+   * Resolve a `{ handle, ref }` pair to its `Ref` and the handle's codec.
+   *
+   * @param {string} id
+   * @param {string} name
+   * @returns {RefAndCodec}
+   */
+  _refOf(id, name) {
+    const h = this._resolve(id)
+    const r = h[name]
+    if (!r) throw CeroError.UNKNOWN('ref', name)
+    return { ref: r, codec: h.spec.codec }
+  }
+
+  /**
+   * Snapshot the current identity for return to the client.
+   *
+   * @returns {Identity}
+   */
+  _identity() {
+    return {
+      id: this.me.id,
+      deviceId: this.me.device?.id || '',
+      phrase: this.me.identity.toPhrase()
+    }
+  }
+}
+
+/**
+ * Construct a `Server`, wait for it to be ready, and return it.
+ *
+ * @param {any} ipc
+ * @param {ServerOpts} opts
+ * @returns {Promise<Server>}
+ */
+export async function serve(ipc, opts) {
+  const server = new Server(ipc, opts)
+  await server.ready()
+  return server
+}

package/types/builder.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @typedef {import('@cero-base/core/schema').Schema} Schema
+ * @typedef {import('@cero-base/core/schema').SchemaDefs} SchemaDefs
+ * @typedef {Schema | (SchemaDefs & { local?: SchemaDefs })} SchemaInput
+ *
+ * @typedef {object} BuildOpts
+ * @property {string} [ns]  Namespace prefix for emitted schema ids. Defaults to `'cero'`.
+ */
+/**
+ * Compile a cero schema into wire-level artifacts and write them to disk.
+ *
+ * Emits a `main/` tree (schema + hyperdb + dispatch + rpc), a `local/` tree
+ * for per-device data, one `handles/<name>/` tree per child handle type, and
+ * an `index.js` that re-exports a ready-to-use `spec` object.
+ *
+ * @param {string} specDir          Output directory.
+ * @param {SchemaInput} schema      Either a `schema(...)` wrapper or its raw defs object.
+ * @param {BuildOpts} [opts]
+ * @returns {Promise<void>}
+ */
+export function build(specDir: string, schema: SchemaInput, { ns }?: BuildOpts): Promise<void>;
+export type Schema = import("@cero-base/core/schema").Schema;
+export type SchemaDefs = import("@cero-base/core/schema").SchemaDefs;
+export type SchemaInput = Schema | (SchemaDefs & {
+    local?: SchemaDefs;
+});
+export type BuildOpts = {
+    /**
+     * Namespace prefix for emitted schema ids. Defaults to `'cero'`.
+     */
+    ns?: string;
+};

package/types/handle/index.d.ts

@@ -0,0 +1,353 @@
+export { Ref } from "../lib/utils.js";
+/**
+ * @typedef {import('@cero-base/core/network').Network} Network
+ * @typedef {import('../local/index.js').Local} Local
+ * @typedef {import('@cero-base/core/identity').KeyPair} KeyPair
+ *
+ * @typedef {object} HandleOpts
+ * @property {Handle} [parent]                 Parent handle when this is a child slot.
+ * @property {Identity} [identity]             Long-lived user identity. Inherited from `parent` if omitted.
+ * @property {Network} [network]               Shared swarm. Inherited from `parent` if omitted.
+ * @property {any} [store]                     Pre-existing Corestore. Falls back to `parent.store.store`.
+ * @property {any} [spec]                      Built cero spec.
+ * @property {Local} [local]                   Local store for per-handle keypairs.
+ * @property {any} [storage]                   Owned HypercoreStorage to close on shutdown.
+ * @property {any} [discovery]                 Owned identity Discovery to destroy on shutdown.
+ * @property {string} [dir]                    Data directory (root handles only).
+ * @property {any} [opts]                      Pass-through cero(...) options.
+ * @property {Record<string, Function>} [routes]
+ * @property {Uint8Array} [key]                Existing database key.
+ * @property {Uint8Array} [encryptionKey]      Existing encryption key.
+ * @property {string} [namespace]              Corestore namespace.
+ * @property {KeyPair} [keyPair]               Writer keypair.
+ * @property {boolean} [pair]                  When `false`, skips creating a `Pairing` session.
+ *
+ * @typedef {object} CreateChildOpts
+ * @property {string | null} [name]
+ * @property {Record<string, Function>} [routes]
+ * @property {string} [role]
+ * @property {boolean} [accept]
+ *
+ * @typedef {object} JoinChildOpts
+ * @property {Record<string, Function>} [routes]
+ * @property {number} [timeout]
+ *
+ * @typedef {object} StaticJoinOpts
+ * @property {Handle} [parent]
+ * @property {Network} [network]
+ * @property {Identity} [identity]
+ * @property {any} [store]
+ * @property {any} [spec]
+ * @property {string} [namespace]
+ * @property {Record<string, Function>} [routes]
+ * @property {number} [timeout]
+ *
+ * @typedef {object} AcceptOpts
+ * @property {string} [role]   Role to grant the joining peer. Falls back to the invite's role, then `'write'`.
+ * @property {string | null} [name]
+ *
+ * @typedef {object} RecoverOpts
+ * @property {number} [timeout]
+ * @property {string | null} [name]
+ * @property {boolean} [isMobile]
+ *
+ * @typedef {object} HandleExtra
+ * @property {string | null} [name]                       Display name; set on child handles by the owner flow.
+ * @property {import('../lib/utils.js').Ref} [profile]    `profile` ref, attached dynamically when the schema declares one.
+ * @property {import('../lib/utils.js').Ref} [members]    `members` ref, attached dynamically when the schema declares one.
+ *
+ * @typedef {Handle & HandleExtra} Child  A child handle plus its dynamically-attached refs.
+ */
+/**
+ * A cero handle — a single writable database session attached to a swarm.
+ * The "root" handle is the user's facade; child handles (created via
+ * `_create`/`_join`/`_load`) live under it and share the same identity,
+ * network and corestore. Ref properties (`profile`, `members`, ...) are
+ * attached dynamically per the schema; child handles also carry a `name`.
+ */
+export class Handle extends ReadyResource {
+    /**
+     * Pair into an existing handle via an invite, returning a brand-new
+     * `Handle` already configured with the resolved key + encryption key.
+     *
+     * @param {string} invite
+     * @param {StaticJoinOpts} [opts]
+     * @returns {Promise<Handle>}
+     */
+    static join(invite: string, { parent, network, identity, store, spec, namespace, routes, timeout }?: StaticJoinOpts): Promise<Handle>;
+    /** @param {HandleOpts} [opts] */
+    constructor(opts?: HandleOpts);
+    identity: any;
+    network: any;
+    spec: any;
+    parent: Handle;
+    local: import("../index.js").Local;
+    _storage: any;
+    _discovery: any;
+    _dir: string;
+    _opts: any;
+    _onerror: any;
+    children: Set<any>;
+    store: Database;
+    pair: Pairing;
+    _wantsPair: boolean;
+    _offUpdate: () => void;
+    /** Canonical id — identity id for the root handle, store key for children. */
+    get id(): any;
+    /** This device's id + name. `null` on child handles. */
+    get device(): {
+        id: string;
+        name: any;
+    };
+    get suspended(): boolean;
+    /**
+     * Initialise a fresh database: write the genesis claim, derive the writer.
+     * Forwards to `Database.bootstrap`.
+     *
+     * @param {any} [opts]
+     * @returns {Promise<any>}
+     */
+    bootstrap(opts?: any): Promise<any>;
+    /**
+     * Claim writer capability on an existing database (paired-device flow).
+     * Forwards to `Database.claim`.
+     *
+     * @param {{ name?: string | null, isMobile?: boolean }} [opts]
+     * @returns {Promise<void>}
+     */
+    claim(opts?: {
+        name?: string | null;
+        isMobile?: boolean;
+    }): Promise<void>;
+    /**
+     * Claim + wait until this peer becomes a writer + bring the bee up to date.
+     * Used by `restore()` after wiping local state.
+     *
+     * @param {RecoverOpts} [opts]
+     * @returns {Promise<void>}
+     */
+    recover({ timeout, name, isMobile }?: RecoverOpts): Promise<void>;
+    /**
+     * Mint a pairing invite for this handle.
+     *
+     * @param {{ role?: string, expiresIn?: number, data?: any }} [opts]
+     * @returns {Promise<string>}  Z32-encoded invite string.
+     */
+    invite(opts?: {
+        role?: string;
+        expiresIn?: number;
+        data?: any;
+    }): Promise<string>;
+    /**
+     * Revoke a previously-minted invite by its string form.
+     *
+     * @param {string} invite
+     * @returns {boolean}  `true` if the invite was found and removed.
+     */
+    revoke(invite: string): boolean;
+    /**
+     * Accept a paired candidate — adds them as a writer (or read-only member)
+     * and confirms the pairing so they receive this handle's keys.
+     *
+     * @param {any} candidate
+     * @param {AcceptOpts} [opts]
+     * @returns {Promise<void>}
+     */
+    accept(candidate: any, { role, name }?: AcceptOpts): Promise<void>;
+    /**
+     * Leave a child handle — removes it from the parent's `handles` collection
+     * and closes the session. No-op on root handles.
+     *
+     * @returns {Promise<void>}
+     */
+    leave(): Promise<void>;
+    /**
+     * Create a new child handle of `type`. Owner-flow — generates a fresh
+     * writer, adds it as a writer + member, and registers the child on the
+     * parent's `handles` collection.
+     *
+     * @param {string} type
+     * @param {CreateChildOpts} [opts]
+     * @returns {Promise<Handle>}
+     */
+    _create(type: string, { name, routes, role, accept }?: CreateChildOpts): Promise<Handle>;
+    /**
+     * Join a child handle by invite (joiner-flow). Waits for writer
+     * capability and registers the child on the parent's `handles`
+     * collection.
+     *
+     * @param {string} invite
+     * @param {string} type
+     * @param {JoinChildOpts} [opts]
+     * @returns {Promise<Handle>}
+     */
+    _join(invite: string, type: string, { routes, timeout }?: JoinChildOpts): Promise<Handle>;
+    /**
+     * Re-open an existing child handle by id. Reuses the stored writer
+     * keypair if available; otherwise generates a fresh one and claims
+     * writer capability.
+     *
+     * @param {string} type
+     * @param {string} id
+     * @returns {Promise<Handle>}
+     */
+    _load(type: string, id: string): Promise<Handle>;
+    /**
+     * Pause networking + storage. Idempotent; no-op on child handles.
+     *
+     * @returns {Promise<void>}
+     */
+    suspend(): Promise<void>;
+    _suspended: boolean;
+    /**
+     * Resume a suspended root handle. Idempotent; no-op on child handles.
+     *
+     * @returns {Promise<void>}
+     */
+    resume(): Promise<void>;
+    _syncMember(child: any): Promise<void>;
+    /**
+     * @param {Handle} child
+     * @param {{ role?: string }} [opts]
+     */
+    _wireAccept(child: Handle, { role }?: {
+        role?: string;
+    }): void;
+    /**
+     * @param {string} id
+     * @param {KeyPair | { publicKey: Uint8Array, secretKey: Uint8Array } | null} keyPair
+     * @returns {Promise<void>}
+     */
+    _saveKeyPair(id: string, keyPair: KeyPair | {
+        publicKey: Uint8Array;
+        secretKey: Uint8Array;
+    } | null): Promise<void>;
+    /**
+     * @param {string} id
+     * @returns {Promise<{ publicKey: Uint8Array, secretKey: Uint8Array } | null>}
+     */
+    _loadKeyPair(id: string): Promise<{
+        publicKey: Uint8Array;
+        secretKey: Uint8Array;
+    } | null>;
+}
+export type Network = import("@cero-base/core/network").Network;
+export type Local = import("../local/index.js").Local;
+export type KeyPair = import("@cero-base/core/identity").KeyPair;
+export type HandleOpts = {
+    /**
+     * Parent handle when this is a child slot.
+     */
+    parent?: Handle;
+    /**
+     * Long-lived user identity. Inherited from `parent` if omitted.
+     */
+    identity?: Identity;
+    /**
+     * Shared swarm. Inherited from `parent` if omitted.
+     */
+    network?: Network;
+    /**
+     * Pre-existing Corestore. Falls back to `parent.store.store`.
+     */
+    store?: any;
+    /**
+     * Built cero spec.
+     */
+    spec?: any;
+    /**
+     * Local store for per-handle keypairs.
+     */
+    local?: Local;
+    /**
+     * Owned HypercoreStorage to close on shutdown.
+     */
+    storage?: any;
+    /**
+     * Owned identity Discovery to destroy on shutdown.
+     */
+    discovery?: any;
+    /**
+     * Data directory (root handles only).
+     */
+    dir?: string;
+    /**
+     * Pass-through cero(...) options.
+     */
+    opts?: any;
+    routes?: Record<string, Function>;
+    /**
+     * Existing database key.
+     */
+    key?: Uint8Array;
+    /**
+     * Existing encryption key.
+     */
+    encryptionKey?: Uint8Array;
+    /**
+     * Corestore namespace.
+     */
+    namespace?: string;
+    /**
+     * Writer keypair.
+     */
+    keyPair?: KeyPair;
+    /**
+     * When `false`, skips creating a `Pairing` session.
+     */
+    pair?: boolean;
+};
+export type CreateChildOpts = {
+    name?: string | null;
+    routes?: Record<string, Function>;
+    role?: string;
+    accept?: boolean;
+};
+export type JoinChildOpts = {
+    routes?: Record<string, Function>;
+    timeout?: number;
+};
+export type StaticJoinOpts = {
+    parent?: Handle;
+    network?: Network;
+    identity?: Identity;
+    store?: any;
+    spec?: any;
+    namespace?: string;
+    routes?: Record<string, Function>;
+    timeout?: number;
+};
+export type AcceptOpts = {
+    /**
+     * Role to grant the joining peer. Falls back to the invite's role, then `'write'`.
+     */
+    role?: string;
+    name?: string | null;
+};
+export type RecoverOpts = {
+    timeout?: number;
+    name?: string | null;
+    isMobile?: boolean;
+};
+export type HandleExtra = {
+    /**
+     * Display name; set on child handles by the owner flow.
+     */
+    name?: string | null;
+    /**
+     * `profile` ref, attached dynamically when the schema declares one.
+     */
+    profile?: import("../lib/utils.js").Ref;
+    /**
+     * `members` ref, attached dynamically when the schema declares one.
+     */
+    members?: import("../lib/utils.js").Ref;
+};
+/**
+ * A child handle plus its dynamically-attached refs.
+ */
+export type Child = Handle & HandleExtra;
+import ReadyResource from 'ready-resource';
+import { Database } from '@cero-base/core/database';
+import { Pairing } from '@cero-base/core/pairing';
+import { Identity } from '@cero-base/core/identity';