@cero-base/rpc 0.0.1

package/README.md

@@ -0,0 +1,68 @@
+# @cero-base/rpc
+
+RPC client/server for [@cero-base/core](../core).
+
+## Install
+
+```
+npm install @cero-base/rpc
+```
+
+## Usage
+
+### Client (renderer / UI process)
+
+```js
+import { Client, getRpc } from '@cero-base/rpc'
+
+const rpc = getRpc(ipcStream, spec)
+const client = new Client(rpc, schema, spec)
+await client.ready()
+
+// Profile
+const profile = await client.profile.get()
+client.profile.set({ name: 'Alice' })
+
+// Rooms
+const room = await client.rooms.open(null, { name: 'My Room' })
+const messages = room.collection('messages')
+await messages.put({ id: '1', text: 'Hello' })
+
+// Devices
+const devices = await client.devices.get()
+const invite = await client.devices.invite()
+```
+
+### Server (worker / backend process)
+
+```js
+import { Server, getRpc } from '@cero-base/rpc'
+
+const rpc = getRpc(ipcStream, spec)
+const server = new Server(db, rpc)
+await server.ready()
+```
+
+### Build (generate RPC spec)
+
+```js
+import { build } from '@cero-base/rpc'
+
+await build('./spec', schema)
+```
+
+## Exports
+
+| Export       | Description                                             |
+| ------------ | ------------------------------------------------------- |
+| `Client`     | RPC client proxy (rooms, collections, profile, devices) |
+| `Server`     | RPC server that wires handlers to a CeroBase db         |
+| `Room`       | Client-side room with collections, members, invites     |
+| `Collection` | Client-side collection with put/get/del/sub             |
+| `getRpc`     | Create an RPC instance from an IPC stream + spec        |
+| `rpc`        | Register RPC types into a hyperschema build             |
+| `build`      | Build spec with RPC types included                      |
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@cero-base/rpc",
+  "version": "0.0.1",
+  "description": "RPC client/server for cero-base",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./utils": "./src/utils.js",
+    "./server": "./src/server.js",
+    "./build": "./src/build.js"
+  },
+  "scripts": {
+    "build:test": "rm -rf test/fixture/spec && node test/fixture/build.js",
+    "pretest": "npm run build:test",
+    "test": "brittle test/*.js"
+  },
+  "dependencies": {
+    "@cero-base/core": "^0.0.1",
+    "compact-encoding": "^2.19.1",
+    "framed-stream": "^1.0.1",
+    "ms": "^2.1.3",
+    "ready-resource": "^1.0.2",
+    "safety-catch": "^1.0.2",
+    "streamx": "^2.22.0"
+  },
+  "devDependencies": {
+    "brittle": "^3.7.0",
+    "duplex-through": "^1.0.2"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lekinox/cero-base.git",
+    "directory": "packages/rpc"
+  }
+}

package/src/build.js

@@ -0,0 +1,6 @@
+import { build as coreBuild } from '@cero-base/core/builder'
+import { rpc } from './schema.js'
+
+export async function build(dir, schema) {
+  return coreBuild(dir, schema, { rpc })
+}

package/src/client.js

@@ -0,0 +1,97 @@
+import ReadyResource from 'ready-resource'
+import safetyCatch from 'safety-catch'
+import { useTimeout, pipeStream } from './utils.js'
+import { Room } from './room.js'
+import { Collection } from './collection.js'
+
+const SEED_WORD_COUNT = 12
+
+export class Client extends ReadyResource {
+  constructor(rpc, schema, spec) {
+    super()
+    this.rpc = rpc
+    this.schema = schema
+    this.spec = spec
+    this.id = null
+    this.deviceId = null
+
+    this.profile = {
+      get: async () => {
+        const { data } = await rpc.getProfile({})
+        return data || null
+      },
+      set: (data) => rpc.setProfile({ data }),
+      sub: () => pipeStream(rpc.watchProfile({}), ({ data }) => data || null)
+    }
+
+    this.devices = {
+      get: async () => {
+        const { data } = await rpc.getDevices({})
+        return data || []
+      },
+      sub: () => pipeStream(rpc.watchDevices({}), ({ data }) => data || []),
+      invite: async () => {
+        const { invite } = await rpc.createDeviceInvite({})
+        return invite
+      }
+    }
+
+    this.rooms = {
+      get: async () => {
+        const { data } = await rpc.getRooms({})
+        return data || []
+      },
+      open: (arg, opts = {}) =>
+        useTimeout(async () => {
+          let res
+          if (!arg) {
+            res = await rpc.createRoom({ name: opts?.name || '' })
+          } else if (arg.length > 64) {
+            res = await rpc.joinRoom({ invite: arg })
+          } else {
+            res = await rpc.openRoom({ roomId: arg })
+          }
+          return new Room(rpc, schema, spec, res.data.id)
+        }, opts),
+      sub: () => pipeStream(rpc.watchRooms({}), ({ data }) => data || [])
+    }
+
+    this.ready().catch(safetyCatch)
+  }
+
+  async _open() {
+    const res = await this.rpc.ready({})
+    this.id = res.id
+    this.deviceId = res.deviceId
+    const updates = this.rpc.updatesSubscribe({})
+    updates.on('data', () => this.emit('update'))
+    if (this.rpc.resume) this.rpc.resume()
+  }
+
+  async _close() {
+    this.rpc.destroy?.()
+  }
+
+  seed() {
+    return this.rpc.getSeed({}).then(({ seed }) => seed || null)
+  }
+
+  async join(input, opts = {}) {
+    return useTimeout(async () => {
+      const isSeed =
+        typeof input === 'string' && input.trim().split(/\s+/).length >= SEED_WORD_COUNT
+      if (isSeed) {
+        await this.rpc.recover({ seed: input })
+      } else {
+        await this.rpc.pairDevice({ invite: input })
+      }
+      const info = await this.rpc.getInfo({})
+      this.id = info.id
+      this.deviceId = info.deviceId
+    }, opts)
+  }
+
+  collection(name) {
+    return new Collection(this.rpc, this.schema, this.spec, name, null)
+  }
+}

package/src/collection.js

@@ -0,0 +1,69 @@
+import c from 'compact-encoding'
+import { pipeStream } from './utils.js'
+
+export class Collection {
+  constructor(rpc, schema, spec, name, roomId) {
+    this.rpc = rpc
+    this.schema = schema
+    this.spec = spec
+    this.name = name
+    this.roomId = roomId || null
+
+    const { spec: key, path } = schema.resolve(name)
+    this._enc = spec[key]
+    this._path = path
+
+    const { spec: inputKey, path: inputPath } = schema.resolve(name, 'input')
+    this._inputEnc = spec[inputKey]
+    this._inputPath = inputPath
+  }
+
+  async put(doc) {
+    const { data } = await this.rpc.collectionInsert({
+      collection: this.name,
+      roomId: this.roomId,
+      doc: this._inputEnc.encode(this._inputPath, doc)
+    })
+    return this._enc.decode(this._path, data)
+  }
+
+  async get(query = {}, opts = {}) {
+    const encoding = this._enc.getEncoding(this._path)
+    const { data } = await this.rpc.collectionFind({
+      collection: this.name,
+      roomId: this.roomId,
+      query: Object.keys(query).length > 0 ? c.encode(c.json, query) : null,
+      limit: opts.limit || null,
+      reverse: opts.reverse || null
+    })
+    return c.decode(c.array(encoding), data)
+  }
+
+  async count() {
+    const results = await this.get()
+    return results.length
+  }
+
+  async del(query) {
+    const { ok } = await this.rpc.collectionDelete({
+      collection: this.name,
+      roomId: this.roomId,
+      query: c.encode(c.json, query)
+    })
+    return ok
+  }
+
+  sub(query = {}, opts = {}) {
+    const encoding = this._enc.getEncoding(this._path)
+    return pipeStream(
+      this.rpc.collectionSubscribe({
+        collection: this.name,
+        roomId: this.roomId,
+        query: Object.keys(query).length > 0 ? c.encode(c.json, query) : null,
+        limit: opts.limit || null,
+        reverse: opts.reverse || null
+      }),
+      ({ data }) => c.decode(c.array(encoding), data)
+    )
+  }
+}

package/src/index.js

@@ -0,0 +1,5 @@
+export * from './client.js'
+export * from './room.js'
+export * from './collection.js'
+export * from './utils.js'
+export * from './schema.js'

package/src/room.js

@@ -0,0 +1,50 @@
+import { pipeStream } from './utils.js'
+import { Collection } from './collection.js'
+
+export class Room {
+  constructor(rpc, schema, spec, id) {
+    this.rpc = rpc
+    this.schema = schema
+    this.spec = spec
+    this.id = id
+
+    this.profile = null // TODO: add RPC methods for room profile
+
+    this.members = {
+      get: async () => {
+        const { data } = await rpc.getMembers({ roomId: id })
+        return data || []
+      },
+      sub: (query) =>
+        pipeStream(rpc.watchMembers({ roomId: id }), ({ data }) => {
+          let members = data || []
+          if (query) {
+            const entries = Object.entries(query)
+            members = members.filter((m) => entries.every(([k, v]) => m[k] === v))
+          }
+          return members
+        })
+    }
+
+    this.invites = {
+      create: async () => {
+        const { invite } = await rpc.createInvite({ roomId: id })
+        return { invite }
+      },
+      get: async () => []
+    }
+  }
+
+  collection(name) {
+    return new Collection(this.rpc, this.schema, this.spec, name, this.id)
+  }
+
+  async invite() {
+    const { invite } = await this.rpc.createInvite({ roomId: this.id })
+    return invite
+  }
+
+  async close() {
+    await this.rpc.closeRoom({ roomId: this.id })
+  }
+}

package/src/schema.js

@@ -0,0 +1,125 @@
+export function rpc({ register, ns = 'cero' }) {
+  const ref = (name) => `@${ns}/${name}`
+
+  // === Collection types ===
+
+  register.type({
+    name: 'ok-result',
+    compact: false,
+    fields: [{ name: 'ok', type: 'bool', required: true }]
+  })
+
+  register.type({
+    name: 'collection-insert',
+    compact: false,
+    fields: [
+      { name: 'collection', type: 'string', required: true },
+      { name: 'roomId', type: 'string', required: false },
+      { name: 'doc', type: 'buffer', required: true }
+    ]
+  })
+
+  register.type({
+    name: 'collection-query',
+    compact: false,
+    fields: [
+      { name: 'collection', type: 'string', required: true },
+      { name: 'roomId', type: 'string', required: false },
+      { name: 'query', type: 'buffer', required: false },
+      { name: 'limit', type: 'uint', required: false },
+      { name: 'reverse', type: 'bool', required: false }
+    ]
+  })
+
+  register.type({
+    name: 'collection-update',
+    compact: false,
+    fields: [
+      { name: 'collection', type: 'string', required: true },
+      { name: 'roomId', type: 'string', required: false },
+      { name: 'query', type: 'buffer', required: true },
+      { name: 'changes', type: 'buffer', required: true }
+    ]
+  })
+
+  register.type({
+    name: 'document-result',
+    compact: false,
+    fields: [{ name: 'data', type: 'buffer', required: false }]
+  })
+  register.type({
+    name: 'document-list',
+    compact: false,
+    fields: [{ name: 'data', type: 'buffer', required: true }]
+  })
+
+  // === Override cero's profile types ===
+
+  register.type({
+    name: 'profile-data',
+    compact: false,
+    fields: [
+      { name: 'name', type: 'string', required: false },
+      { name: 'theme', type: 'string', required: false }
+    ]
+  })
+  register.type({
+    name: 'profile-info',
+    compact: false,
+    fields: [{ name: 'data', type: ref('profile-data'), required: false }]
+  })
+  register.type({
+    name: 'profile-update',
+    compact: false,
+    fields: [{ name: 'data', type: ref('profile-data'), required: true }]
+  })
+
+  // === Update signal ===
+
+  register.type({
+    name: 'update-signal',
+    compact: false,
+    fields: [{ name: 'type', type: 'string', required: false }]
+  })
+
+  // === Collection RPCs ===
+
+  register.rpc({
+    name: 'collection-insert',
+    request: { name: ref('collection-insert') },
+    response: { name: ref('document-result') }
+  })
+  register.rpc({
+    name: 'collection-find',
+    request: { name: ref('collection-query') },
+    response: { name: ref('document-list') }
+  })
+  register.rpc({
+    name: 'collection-get',
+    request: { name: ref('collection-query') },
+    response: { name: ref('document-result') }
+  })
+  register.rpc({
+    name: 'collection-update',
+    request: { name: ref('collection-update') },
+    response: { name: ref('document-result') }
+  })
+  register.rpc({
+    name: 'collection-delete',
+    request: { name: ref('collection-query') },
+    response: { name: ref('ok-result') }
+  })
+  register.rpc({
+    name: 'collection-subscribe',
+    request: { name: ref('collection-query') },
+    response: { name: ref('document-list'), stream: true }
+  })
+
+  // === Updates ===
+
+  register.rpc({
+    name: 'updates-subscribe',
+    request: { name: ref('empty-data') },
+    response: { name: ref('update-signal'), stream: true }
+  })
+}

package/src/server.js

@@ -0,0 +1,257 @@
+import c from 'compact-encoding'
+import { Room } from '@cero-base/core'
+
+export class Server {
+  constructor(db, rpc) {
+    this.db = db
+    this.rpc = rpc
+    this.rooms = new Map()
+    this._registerHandlers()
+  }
+
+  async ready() {
+    await this.db.ready()
+    this.rpc.resume()
+    return this
+  }
+
+  async close() {
+    for (const room of this.rooms.values()) {
+      await room.close()
+    }
+    this.rooms.clear()
+    this.rpc.destroy?.()
+    await this.db.close()
+  }
+
+  _enc(collection, prefix) {
+    const { spec: key, path } = this.db.schema.resolve(collection, prefix)
+    return { spec: this.db.spec[key], path }
+  }
+
+  _registerHandlers() {
+    const { db, rpc, rooms } = this
+
+    // === System ===
+
+    rpc.onReady(async () => {
+      return { id: db.id, deviceId: db.deviceId }
+    })
+
+    // === Collection ===
+
+    rpc.onCollectionInsert(async ({ collection, roomId, doc }) => {
+      const { spec: iSpec, path: iPath } = this._enc(collection, 'input')
+      const { spec, path } = this._enc(collection)
+      const owner = roomId ? rooms.get(roomId) : db
+      const col = owner.collection(collection)
+      const input = iSpec.decode(iPath, doc)
+      for (const k in input) {
+        if (input[k] == null) delete input[k]
+      }
+      const result = await col.put(input)
+      return { data: spec.encode(path, result) }
+    })
+
+    rpc.onCollectionFind(async ({ collection, roomId, query: queryBuf, limit, reverse }) => {
+      const { spec, path } = this._enc(collection)
+      const owner = roomId ? rooms.get(roomId) : db
+      const query = queryBuf ? c.decode(c.json, queryBuf) : {}
+      const findOpts = {}
+      if (limit) findOpts.limit = limit
+      if (reverse) findOpts.reverse = reverse
+      const results = await owner.collection(collection).get(query, findOpts)
+      return { data: c.encode(c.array(spec.getEncoding(path)), results) }
+    })
+
+    rpc.onCollectionGet(async ({ collection, roomId, query: queryBuf }) => {
+      const { spec, path } = this._enc(collection)
+      const owner = roomId ? rooms.get(roomId) : db
+      const query = queryBuf ? c.decode(c.json, queryBuf) : {}
+      const results = await owner.collection(collection).get(query)
+      return { data: results.length ? spec.encode(path, results[0]) : null }
+    })
+
+    rpc.onCollectionUpdate(async ({ collection, roomId, query: queryBuf, changes: changesBuf }) => {
+      const { spec, path } = this._enc(collection)
+      const owner = roomId ? rooms.get(roomId) : db
+      const col = owner.collection(collection)
+      const query = c.decode(c.json, queryBuf)
+      const changes = c.decode(c.json, changesBuf)
+      const [existing] = await col.get(query)
+      if (!existing) return { data: null }
+      const updated = { ...existing, ...changes }
+      if (col.timestamps) updated.updatedAt = Date.now()
+      await col._write(`set-${col.type}`, updated)
+      return { data: spec.encode(path, updated) }
+    })
+
+    rpc.onCollectionDelete(async ({ collection, roomId, query: queryBuf }) => {
+      const owner = roomId ? rooms.get(roomId) : db
+      const query = queryBuf ? c.decode(c.json, queryBuf) : {}
+      const ok = await owner.collection(collection).del(query)
+      return { ok }
+    })
+
+    rpc.onCollectionSubscribe(async (stream) => {
+      const { collection, roomId, query: queryBuf, limit, reverse } = stream.data
+      const { spec, path } = this._enc(collection)
+      const owner = roomId ? rooms.get(roomId) : db
+      const query = queryBuf ? c.decode(c.json, queryBuf) : {}
+      const findOpts = {}
+      if (limit) findOpts.limit = limit
+      if (reverse) findOpts.reverse = reverse
+
+      const sub = owner.collection(collection).sub(query, findOpts)
+      sub.on('data', (docs) => {
+        stream.write({ data: c.encode(c.array(spec.getEncoding(path)), docs) })
+      })
+      stream.on('close', () => sub.destroy())
+    })
+
+    // === Rooms ===
+
+    rpc.onCreateRoom(async ({ name }) => {
+      const room = await Room.from(db, undefined, name ? { name } : {})
+      rooms.set(room.id, room)
+      return { data: { id: room.id, name } }
+    })
+
+    rpc.onJoinRoom(async ({ invite }) => {
+      const room = await Room.from(db, invite)
+      rooms.set(room.id, room)
+      return { data: { id: room.id } }
+    })
+
+    rpc.onOpenRoom(async ({ roomId }) => {
+      const existing = rooms.get(roomId)
+      if (existing) return { data: { id: existing.id } }
+      const room = await Room.from(db, roomId)
+      rooms.set(room.id, room)
+      return { data: { id: room.id } }
+    })
+
+    rpc.onCloseRoom(({ roomId }) => {
+      const room = rooms.get(roomId)
+      if (room) {
+        rooms.delete(roomId)
+        room.close()
+      }
+    })
+
+    rpc.onGetRooms(async () => {
+      const list = await db.rooms.list()
+      return { data: list || [] }
+    })
+
+    rpc.onWatchRooms(async (stream) => {
+      const load = async () => {
+        const list = await db.rooms.list()
+        stream.write({ data: list || [] })
+      }
+      load()
+      db.on('rooms:added', load)
+      db.on('rooms:removed', load)
+      stream.on('close', () => {
+        db.removeListener('rooms:added', load)
+        db.removeListener('rooms:removed', load)
+      })
+    })
+
+    // === Profile ===
+
+    rpc.onGetProfile(async () => {
+      return { data: (await db.profile?.get()) || null }
+    })
+
+    rpc.onSetProfile(({ data }) => {
+      db.profile.set(data)
+    })
+
+    rpc.onWatchProfile(async (stream) => {
+      const sub = db.profile.sub()
+      sub.on('data', (profile) => stream.write({ data: profile || null }))
+      stream.on('close', () => sub.destroy())
+    })
+
+    // === Members ===
+
+    rpc.onGetMembers(async ({ roomId }) => {
+      const room = rooms.get(roomId)
+      if (!room) return { data: [] }
+      const members = await room.members.get()
+      return { data: members || [] }
+    })
+
+    rpc.onWatchMembers(async (stream) => {
+      const { roomId } = stream.data
+      const room = rooms.get(roomId)
+      if (!room) return
+
+      const sub = room.members.sub()
+      sub.on('data', (members) => stream.write({ data: members || [] }))
+      stream.on('close', () => sub.destroy())
+    })
+
+    // === Invites ===
+
+    rpc.onCreateInvite(async ({ roomId }) => {
+      const room = rooms.get(roomId)
+      const { invite } = await room.invites.create()
+      return { invite }
+    })
+
+    // === Identity ===
+
+    rpc.onGetInfo(async () => {
+      return { id: db.id, deviceId: db.deviceId }
+    })
+
+    rpc.onGetSeed(async () => {
+      return { seed: db.seed() || '' }
+    })
+
+    rpc.onGetDevices(async () => {
+      const data = await db.devices?.get()
+      return { data: data || [] }
+    })
+
+    rpc.onWatchDevices(async (stream) => {
+      if (!db.devices?.sub) return
+      const sub = db.devices.sub()
+      sub.on('data', (devices) => stream.write({ data: devices || [] }))
+      stream.on('close', () => sub.destroy())
+    })
+
+    rpc.onCreateDeviceInvite(async () => {
+      const invite = await db.devices.invite()
+      return { invite }
+    })
+
+    rpc.onPairDevice(async ({ invite }) => {
+      await db.join(invite)
+      return { id: db.id, deviceId: db.deviceId }
+    })
+
+    rpc.onRecover(async ({ seed }) => {
+      await db.join(seed)
+      return { id: db.id, deviceId: db.deviceId }
+    })
+
+    // === Updates ===
+
+    rpc.onUpdatesSubscribe(async (stream) => {
+      const onUpdate = () => stream.write({ type: 'update' })
+      const onAdded = () => stream.write({ type: 'rooms:added' })
+      const onRemoved = () => stream.write({ type: 'rooms:removed' })
+      db.on('update', onUpdate)
+      db.on('rooms:added', onAdded)
+      db.on('rooms:removed', onRemoved)
+      stream.on('close', () => {
+        db.removeListener('update', onUpdate)
+        db.removeListener('rooms:added', onAdded)
+        db.removeListener('rooms:removed', onRemoved)
+      })
+    })
+  }
+}

package/src/utils.js

@@ -0,0 +1,46 @@
+import ms from 'ms'
+import { Readable } from 'streamx'
+import FramedStream from 'framed-stream'
+
+export function getRpc(ipc, spec) {
+  const stream = new FramedStream(ipc)
+  stream.pause()
+  const rpc = new spec.rpc(stream)
+  rpc.resume = () => stream.resume()
+  return rpc
+}
+
+if (typeof AbortSignal !== 'undefined' && !AbortSignal.timeout) {
+  AbortSignal.timeout = (ms) => {
+    const controller = new AbortController()
+    setTimeout(() => controller.abort(new Error('Timeout')), ms)
+    return controller.signal
+  }
+}
+
+export function useTimeout(fn, opts = {}) {
+  const timeout = typeof opts.timeout === 'string' ? ms(opts.timeout) : opts.timeout
+  if (!timeout && !opts.signal) return fn()
+  if (typeof AbortSignal !== 'undefined' && AbortSignal.timeout) {
+    const signal = opts.signal || AbortSignal.timeout(timeout)
+    return new Promise((resolve, reject) => {
+      if (signal.aborted) return reject(signal.reason)
+      signal.addEventListener('abort', () => reject(signal.reason), { once: true })
+      fn().then(resolve, reject)
+    })
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('Timeout')), timeout)
+    fn()
+      .then(resolve, reject)
+      .finally(() => clearTimeout(timer))
+  })
+}
+
+export function pipeStream(source, transform) {
+  const readable = new Readable()
+  source.on('data', (d) => readable.push(transform(d)))
+  source.on('close', () => readable.destroy())
+  readable.on('close', () => source.destroy())
+  return readable
+}