@cero-base/cero 0.8.9 → 1.0.1

package/src/rpc/server.js

@@ -1,5 +1,6 @@
 import { RPCServer, bindCodec } from '@cero-base/core/rpc'
 import { CeroError } from '@cero-base/core/errors'
+import { encodeId } from '@cero-base/core/blobs/codec'
 
 import { cero, restore } from '../index.js'
 import { put, set, get, del, count, watch, call } from '../lib/operators.js'
@@ -18,7 +19,6 @@ import { put, set, get, del, count, watch, call } from '../lib/operators.js'
  * @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
  *
@@ -45,9 +45,19 @@ export class Server extends RPCServer {
     this.opts = opts
     this.me = null
     this.handles = new Map()
+    /** @type {Map<string, Set<object>>} handle id → its open watch streams */
+    this._watchStreams = new Map()
     this._wireInit()
   }
 
+  /** End every watch stream bound to a handle (e.g. when it closes or leaves). */
+  _endWatches(handle) {
+    const set = this._watchStreams.get(handle)
+    if (!set) return
+    for (const s of set) s.destroy()
+    this._watchStreams.delete(handle)
+  }
+
   /**
    * Root cero id (null until `init` has run).
    *
@@ -81,10 +91,12 @@ export class Server extends RPCServer {
       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)
+      await this.me.fileServer.listen()
       this._wireData()
       this._wirePairing()
       this._wireHandles()
       this._wireRestore()
+      this._wireSeed()
       return this._identity()
     })
   }
@@ -101,16 +113,28 @@ export class Server extends RPCServer {
 
   /** Register the row-level RPC handlers (put/set/get/del/count/watch/call). */
   _wireData() {
+    this.rpc.onAddFile(async ({ handle, data, name, type }) => {
+      const h = this._resolve(handle)
+      await h.blobs.ready()
+      const blobId = await h.blobs.put(data)
+      const id = encodeId(h.blobs.key, blobId, type || '')
+      const codec = h.spec.codec
+      await h.store.call('add-file', { id, name: name || null })
+      const { data: row } = await get(h.files, id)
+      return { data: codec.encodeRow(h.files.schema, row) }
+    })
+
     this.rpc.onAddRow(async ({ handle, ref, data, local }) => {
       const { ref: r, codec } = this._refOf(handle, ref, local)
       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, local }) => {
+    this.rpc.onSet(async ({ handle, ref, data, local, noUpsert }) => {
       const { ref: r, codec } = this._refOf(handle, ref, local)
-      const { data: row } = await set(r, codec.decodeRow(r.schema, data))
-      return { data: codec.encodeRow(r.schema, row) }
+      const result = await set(r, codec.decodeRow(r.schema, data), { upsert: !noUpsert })
+      // an update-only miss returns null — encode an empty row back
+      return { data: codec.encodeRow(r.schema, result?.data ?? null) }
     })
 
     this.rpc.onGet(async ({ handle, ref, query, local }) => {
@@ -147,7 +171,12 @@ export class Server extends RPCServer {
         ;({ ref: r, codec } = this._refOf(handle, ref, local))
         live = watch(r, codec.decodeQuery(query))
       } catch (err) {
-        stream.destroy(err)
+        // Forward the error to the client over the wire by destroying the
+        // underlying response stream with it (emits a CLOSE|ERROR frame). The
+        // local RPCStream's 'error' is swallowed so it doesn't crash the server.
+        stream.once('error', () => {})
+        stream.writeStream.destroy(err)
+        stream.destroy()
         return
       }
       const onData = (snap) => {
@@ -157,10 +186,14 @@ export class Server extends RPCServer {
             : codec.encodeRows(r.schema, snap.data)
         stream.write({ data, total: snap.total ?? 0, size: snap.size ?? 0 })
       }
+      let set = this._watchStreams.get(handle)
+      if (!set) this._watchStreams.set(handle, (set = new Set()))
+      set.add(stream)
       live.on('data', onData)
       stream.on('close', () => {
         live.off('data', onData)
         live.destroy()
+        this._watchStreams.get(handle)?.delete(stream)
       })
     })
 
@@ -201,7 +234,9 @@ export class Server extends RPCServer {
       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 wire = parent.spec.codec.decodeCreate(data) || {}
+      // routes can't cross the wire (functions) — both sides register them via define()
+      const opts = { name: wire.name, role: wire.role, accept: wire.noAccept ? false : undefined }
       const child = await this.me._create(ref, opts)
       const id = child.id
       this.handles.set(id, child)
@@ -220,6 +255,7 @@ export class Server extends RPCServer {
     this.rpc.onCloseHandle(async ({ handle }) => {
       const h = this.handles.get(handle)
       if (!h || h === this.me) return {}
+      this._endWatches(handle)
       this.handles.delete(handle)
       await h.close()
       return {}
@@ -228,6 +264,7 @@ export class Server extends RPCServer {
     this.rpc.onLeave(async ({ handle }) => {
       const h = this.handles.get(handle)
       if (!h || h === this.me) return {}
+      this._endWatches(handle)
       await this.me.store.call('del-handle', { id: handle })
       this.handles.delete(handle)
       await h.close()
@@ -279,12 +316,22 @@ export class Server extends RPCServer {
    * @returns {Identity}
    */
   _identity() {
+    const fs = this.me.fileServer
     return {
       id: this.me.id,
       deviceId: this.me.device?.id || '',
-      phrase: this.me.identity.toPhrase()
+      fileBase: `http://127.0.0.1:${fs.port}`,
+      fileToken: fs.server.token || ''
     }
   }
+
+  /** Wire the on-demand `seed` handler — surfaces the recovery phrase only when asked. */
+  _wireSeed() {
+    this.rpc.onSeed(async () => {
+      if (!this.me) throw new CeroError('NOT_READY', 'init')
+      return { phrase: this.me.identity.toPhrase() }
+    })
+  }
 }
 
 /**

package/types/build/builtins.d.ts

@@ -15,6 +15,10 @@ export namespace refs {
             let type_3: string;
             export { type_3 as type };
         }
+        namespace files {
+            let type_4: string;
+            export { type_4 as type };
+        }
     }
     let local: {
         master: {
@@ -30,7 +34,7 @@ export namespace refs {
         };
     };
 }
-export function hyperdbType(prim: any): any;
+export function getHyperdbType(prim: any): any;
 export function builtinRefs(ns: any, scope: any): {
     [k: string]: {
         schema: string;

package/types/build/index.d.ts

@@ -1,24 +1,7 @@
-/**
- * @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 function build(specDir: any, schema: any, { ns }?: {
+    ns?: string;
+}): Promise<void>;
+export { getHyperdbType } from "./builtins.js";
 export type Schema = import("@cero-base/core/schema").Schema;
 export type SchemaDefs = import("@cero-base/core/schema").SchemaDefs;
 export type SchemaInput = Schema | (SchemaDefs & {

package/types/build/schemas.d.ts

@@ -52,6 +52,14 @@ export const main: {
         updatedAt: import("@cero-base/core").Prim;
         index: import("@cero-base/core").Prim;
     };
+    file: {
+        id: import("@cero-base/core").Prim;
+        memberId: import("@cero-base/core").Prim;
+        name: import("@cero-base/core").Prim;
+        createdAt: import("@cero-base/core").Prim;
+        updatedAt: import("@cero-base/core").Prim;
+        index: import("@cero-base/core").Prim;
+    };
     claim: {
         identity: import("@cero-base/core").Prim;
         writer: import("@cero-base/core").Prim;
@@ -85,6 +93,7 @@ export const rpc: {
         ref: import("@cero-base/core").Prim;
         data: import("@cero-base/core").Prim;
         local: import("@cero-base/core").Prim;
+        noUpsert: import("@cero-base/core").Prim;
     };
     'req-id': {
         handle: import("@cero-base/core").Prim;
@@ -142,9 +151,19 @@ export const rpc: {
         type: import("@cero-base/core").Prim;
         name: import("@cero-base/core").Prim;
     };
+    'req-add-file': {
+        handle: import("@cero-base/core").Prim;
+        data: import("@cero-base/core").Prim;
+        name: import("@cero-base/core").Prim;
+        type: import("@cero-base/core").Prim;
+    };
     'res-identity': {
         id: import("@cero-base/core").Prim;
         deviceId: import("@cero-base/core").Prim;
+        fileBase: import("@cero-base/core").Prim;
+        fileToken: import("@cero-base/core").Prim;
+    };
+    'res-seed': {
         phrase: import("@cero-base/core").Prim;
     };
     'res-ok': {

package/types/handle/index.d.ts

@@ -43,7 +43,7 @@ export { Ref } from "../lib/utils.js";
  * @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} [role]   Role to grant the joining peer. Falls back to the invite's role, then `'member'`.
  * @property {string | null} [name]
  *
  * @typedef {object} RecoverOpts
@@ -55,6 +55,8 @@ export { Ref } from "../lib/utils.js";
  * @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.
+ *
+ * @typedef {Handle & Record<string, import('../lib/utils.js').Ref>} CeroHandle  A handle with every schema ref reachable as a `Ref` property (e.g. `me.profile`, `room.messages`).
  */
 /**
  * A cero handle — a single writable database session attached to a swarm.
@@ -87,6 +89,9 @@ export class Handle extends ReadyResource {
     _onerror: any;
     children: Set<any>;
     _loading: Map<any, any>;
+    _coreKeys: Map<any, any>;
+    _fileServer: FileServer;
+    _blobs: Blobs;
     _owned: Set<any>;
     store: Database;
     pair: Pairing;
@@ -125,6 +130,40 @@ export class Handle extends ReadyResource {
     on(event: string, fn: (...args: any[]) => void, opts?: {
         signal?: AbortSignal;
     }): this;
+    /** The top-most handle in the parent chain — itself for a root handle. */
+    get root(): this;
+    /**
+     * Lazily-built file server for this identity. Root-only — child handles
+     * reach it through `this.root.fileServer`.
+     *
+     * @returns {FileServer}
+     */
+    get fileServer(): FileServer;
+    /**
+     * @param {Uint8Array} coreKey
+     * @param {object} info
+     * @returns {{ key: Uint8Array, encryptionKey: Uint8Array } | null}
+     */
+    _resolveCore(coreKey: Uint8Array, info: object): {
+        key: Uint8Array;
+        encryptionKey: Uint8Array;
+    } | null;
+    /**
+     * Resolve a durable file id to an ephemeral download url via this identity's
+     * file server.
+     *
+     * @param {string} id
+     * @returns {string}
+     */
+    getLink(id: string): string;
+    /**
+     * Lazily-built blob store for THIS handle's writing device. One core per
+     * writer, encrypted with the handle's encryptionKey and attached to the
+     * shared network for replication.
+     *
+     * @returns {Blobs}
+     */
+    get blobs(): Blobs;
     /** Canonical id — identity id for the root handle, store key for children. */
     get id(): any;
     /** This device's id + name. `null` on child handles. */
@@ -145,13 +184,9 @@ export class Handle extends ReadyResource {
      * 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(): Promise<void>;
     /**
      * Claim + wait until this peer becomes a writer + bring the bee up to date.
      * Used by `restore()` after wiping local state.
@@ -360,7 +395,7 @@ export type StaticJoinOpts = {
 };
 export type AcceptOpts = {
     /**
-     * Role to grant the joining peer. Falls back to the invite's role, then `'write'`.
+     * Role to grant the joining peer. Falls back to the invite's role, then `'member'`.
      */
     role?: string;
     name?: string | null;
@@ -386,8 +421,14 @@ export type HandleExtra = {
  * A child handle plus its dynamically-attached refs.
  */
 export type Child = Handle & HandleExtra;
+/**
+ * A handle with every schema ref reachable as a `Ref` property (e.g. `me.profile`, `room.messages`).
+ */
+export type CeroHandle = Handle & Record<string, import("../lib/utils.js").Ref>;
 import ReadyResource from 'ready-resource';
+import { FileServer } from '@cero-base/core/blobs/server';
+import { Blobs } from '@cero-base/core/blobs';
 import { Database } from '@cero-base/core/database';
 import { Pairing } from '@cero-base/core/pairing';
-import AbortController from 'abort-controller';
+import AbortController from 'bare-abort-controller';
 import { Identity } from '@cero-base/core/identity';

package/types/index.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import('./handle/index.js').CeroHandle} CeroHandle
+ */
 /**
  * @typedef {object} CeroOpts
  * @property {Identity} [identity]                     Pre-resolved identity. If absent, derived from `seed`/`phrase` or generated.
@@ -22,9 +25,9 @@
  * @param {string} dir       Data directory.
  * @param {any} spec         Built spec — output of `cero/build`.
  * @param {CeroOpts} [opts]
- * @returns {Promise<Handle>}
+ * @returns {Promise<CeroHandle>}
  */
-export function cero(dir: string, spec: any, opts?: CeroOpts): Promise<Handle>;
+export function cero(dir: string, spec: any, opts?: CeroOpts): Promise<CeroHandle>;
 export namespace cero {
     export { t };
     export { put };
@@ -55,6 +58,8 @@ export namespace cero {
  * @returns {Promise<Handle>}  Freshly restored root handle.
  */
 export function restore(me: Handle, phrase: string): Promise<Handle>;
+export { peek } from "./lib/peek.js";
+export type CeroHandle = import("./handle/index.js").CeroHandle;
 export type CeroOpts = {
     /**
      * Pre-resolved identity. If absent, derived from `seed`/`phrase` or generated.
@@ -112,7 +117,6 @@ export type CeroOpts = {
      */
     recoveryTimeout?: number;
 };
-import { Handle } from './handle/index.js';
 import { t } from './lib/spec.js';
 import { put } from './lib/operators.js';
 import { set } from './lib/operators.js';
@@ -124,14 +128,15 @@ import { call } from './lib/operators.js';
 import { open } from './lib/operators.js';
 import { before } from './lib/operators.js';
 import { after } from './lib/operators.js';
-import { peek } from './lib/operators.js';
+import { peek } from './lib/peek.js';
 import { schema } from './lib/spec.js';
 import { bind } from './lib/operators.js';
 import { define } from './lib/operators.js';
 import { internal } from './lib/internal.js';
+import { Handle } from './handle/index.js';
 import { Ref } from './handle/index.js';
 import { Local } from './local/index.js';
 import { Identity } from '@cero-base/core/identity';
 export { Handle, Ref, Local };
-export { put, set, get, del, count, watch, call, open, before, after, bind, define, peek } from "./lib/operators.js";
+export { put, set, get, del, count, watch, call, open, before, after, bind, define } from "./lib/operators.js";
 export { t, schema } from "./lib/spec.js";

package/types/lib/constants.d.ts

@@ -11,4 +11,5 @@ export namespace DB_TYPE {
     let json: string;
     let fixed32: string;
     let fixed64: string;
+    let file: string;
 }

package/types/lib/operators.d.ts

@@ -1,13 +1,26 @@
 /**
- * Quickly check whether the on-disk directory at `dir` already holds an
- * initialised cero identity (i.e. a stored master seed). Opens the local store
- * read-only and closes everything before returning.
+ * @typedef {import('./utils.js').Ref} Ref
+ * @typedef {import('../handle/index.js').CeroHandle} CeroHandle
+ * @typedef {{ data: any }} SingleResult
+ * @typedef {{ data: any[], total: number, size: number }} ListResult
+ * @typedef {{ data: any | null }} GetByIdResult
+ */
+/**
+ * Resolve a durable file id (+ optional name) to the read shape returned
+ * everywhere: `{ id, name?, type, size, url }`.
  *
- * @param {string} dir   Cero data directory.
- * @param {any} spec     Built spec — same value passed to `cero(dir, spec)`.
- * @returns {Promise<boolean>}  `true` if a master seed exists on disk.
+ * @param {object} handle
+ * @param {string} id
+ * @param {string} [name]
+ * @returns {{ id: string, type: string, size: number, url: string, name?: string }}
  */
-export function peek(dir: string, spec: any): Promise<boolean>;
+export function resolveFile(handle: object, id: string, name?: string): {
+    id: string;
+    type: string;
+    size: number;
+    url: string;
+    name?: string;
+};
 /**
  * Put custom operators on `handle`, currying it as their first argument so
  * `handle.ns.fn(args)` calls `fn(handle, args)`. `arg` is either:
@@ -32,7 +45,13 @@ export function bind(handle: any, arg: Record<string, any> | string | null): any
 export function define(map: Record<string, any>): void;
 /** Test seam: clear all registered operators. */
 export function _clearDefined(): void;
-export function put(ref: Ref, row: Record<string, any>): Promise<SingleResult>;
+export function put(ref: Ref, row: Record<string, any>): Promise<SingleResult | {
+    id: string;
+    name?: string;
+    type: string;
+    size: number;
+    url: string;
+}>;
 export function set(ref: Ref, row: Record<string, any>, opts?: {
     upsert?: boolean;
 }): Promise<SingleResult>;
@@ -58,7 +77,7 @@ export function after(ref: Ref, fn: (ctx: {
 export function get(ref: Ref, q?: string | Record<string, any>): Promise<SingleResult | ListResult | GetByIdResult>;
 export function watch(ref: Ref, q?: Record<string, any>, opts?: {
     signal?: AbortSignal;
-}): any;
+}): import("streamx").Readable;
 export function open(ref: Ref, arg?: string | {
     invite?: string;
     id?: string;
@@ -66,8 +85,9 @@ export function open(ref: Ref, arg?: string | {
     routes?: any;
     role?: string;
     accept?: boolean;
-} | undefined): Promise<any>;
+} | undefined): Promise<CeroHandle>;
 export type Ref = import("./utils.js").Ref;
+export type CeroHandle = import("../handle/index.js").CeroHandle;
 export type SingleResult = {
     data: any;
 };

package/types/lib/peek.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Quickly check whether the on-disk directory at `dir` already holds an
+ * initialised cero identity (i.e. a stored master seed). Opens the local store
+ * read-only and closes everything before returning.
+ *
+ * @param {string} dir   Cero data directory.
+ * @param {any} spec     Built spec — same value passed to `cero(dir, spec)`.
+ * @returns {Promise<boolean>}  `true` if a master seed exists on disk.
+ */
+export function peek(dir: string, spec: any): Promise<boolean>;

package/types/lib/utils.d.ts

@@ -9,12 +9,15 @@
 export function attachRefs(target: any, refs: Record<string, RefInfo>): void;
 /**
  * Run `cb` when `signal` aborts — or immediately if it already has. No-op
- * without a signal. The listener removes itself on fire.
+ * without a signal. The listener removes itself on fire. Returns a disposer that
+ * detaches the listener early, so a manual unsubscribe doesn't leave it lingering
+ * on a long-lived signal.
  *
- * @param {AbortSignal} [signal]
+ * @param {AbortSignal | undefined} signal
  * @param {() => void} cb
+ * @returns {(() => void) | undefined}
  */
-export function onAbort(signal?: AbortSignal, cb: () => void): void;
+export function onAbort(signal: AbortSignal | undefined, cb: () => void): (() => void) | undefined;
 /**
  * @typedef {'collection' | 'single' | 'action' | 'handle'} RefKind
  * @typedef {{ kind?: string, schema?: string }} RefInfo

package/types/rpc/client.d.ts

@@ -60,9 +60,11 @@ export class Client extends RPCClient {
     deviceId: any;
     store: this;
     local: LocalRefs;
+    _fileBase: any;
+    _fileToken: any;
     identity: {
         id: any;
-        toPhrase: () => any;
+        toPhrase: () => Promise<any>;
     };
     /**
      * Create a new child handle of the given type.

package/types/rpc/server.d.ts

@@ -20,7 +20,6 @@ export function serve(ipc: any, opts: ServerOpts): Promise<Server>;
  * @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
  *
@@ -56,6 +55,10 @@ export class Server extends RPCServer {
     };
     me: any;
     handles: Map<any, any>;
+    /** @type {Map<string, Set<object>>} handle id → its open watch streams */
+    _watchStreams: Map<string, Set<object>>;
+    /** End every watch stream bound to a handle (e.g. when it closes or leaves). */
+    _endWatches(handle: any): void;
     /**
      * Root cero id (null until `init` has run).
      *
@@ -103,6 +106,8 @@ export class Server extends RPCServer {
      * @returns {Identity}
      */
     _identity(): Identity;
+    /** Wire the on-demand `seed` handler — surfaces the recovery phrase only when asked. */
+    _wireSeed(): void;
 }
 export type BaseRPCServer = import("@cero-base/core/rpc").RPCServer;
 export type ServerOpts = {
@@ -137,10 +142,6 @@ export type Identity = {
      * Per-device id (empty when no `local` spec).
      */
     deviceId: string;
-    /**
-     * BIP39 recovery phrase for the identity.
-     */
-    phrase: string | null;
 };
 export type RefAndCodec = {
     ref: any;