@threadedstack/wmd-web 0.0.0-stage → 0.1.12

package/src/fs/graph.js

@@ -0,0 +1,380 @@
+// P-B9: a small binary codec for an object graph with shared references and cycles (the
+// 9P service's Overlay tree and its fid table), so the service's state can leave its Worker,
+// go to OPFS and come back after a page reload.
+//
+// It is not a general serializer. It knows what the file server holds: undefined, null,
+// booleans, numbers, BigInts, strings, Uint8Array, Array, Map, Set, plain objects, and
+// instances of the classes a caller registers. Functions are never written.
+//
+//   encodeGraph(root, {classes, special}) -> {segments: Uint8Array[], bytes}
+//   decodeGraph(bytes, {classes, special}) -> root
+//
+//   classes: {Name: {ctor, make?, skip?}}.  ctor identifies instances on the way out (an
+//     instance's constructor must be the registered one); make() builds the object that
+//     decode fills (default: new ctor() with no arguments... classes with private members
+//     must be built by their constructor, never by Object.create). skip: field names
+//     that are not written (set by the constructor in the new process: a function, a
+//     reference to a live Pack, a cap).
+//   special: {pack(obj) -> token|undefined, revive(token) -> obj}: values that are not data
+//     (a live Pack) are written as a token and revived to the new process's object.
+//
+// Wire format: a tag byte, then the value. Objects (Array, Map, Set, plain, instance) take
+// an id when first written (pre-order); a later reference is tag REF + id. A decoded
+// object is registered before its children are read, so cycles close.
+
+const T_UNDEF = 0
+const T_NULL = 1
+const T_FALSE = 2
+const T_TRUE = 3
+const T_INT = 4 // zig-zag varint, |x| <= 2^53
+const T_FLOAT = 5
+const T_BIG = 6 // i64
+const T_BIGSTR = 7 // beyond i64: decimal string
+const T_STR = 8
+const T_BYTES = 9
+const T_ARRAY = 10
+const T_MAP = 11
+const T_SET = 12
+const T_OBJ = 13
+const T_INST = 14
+const T_REF = 15
+const T_SPECIAL = 16
+
+const MAGIC = 0x47524631 // "GRF1"
+const BIG_SEGMENT = 1 << 18
+const BUF = 1 << 20
+
+class Writer {
+  constructor() {
+    this.segments = []
+    this.buf = new Uint8Array(BUF)
+    this.dv = new DataView(this.buf.buffer)
+    this.pos = 0
+    this.bytes = 0
+  }
+
+  #room(n) {
+    if (this.pos + n <= this.buf.length) return
+    this.#flush()
+    if (n > this.buf.length) {
+      this.buf = new Uint8Array(n)
+      this.dv = new DataView(this.buf.buffer)
+    }
+  }
+
+  #flush() {
+    if (this.pos) {
+      this.segments.push(this.buf.slice(0, this.pos))
+      this.bytes += this.pos
+      this.pos = 0
+    }
+  }
+
+  byte(b) {
+    this.#room(1)
+    this.buf[this.pos++] = b
+  }
+
+  uvarint(n) {
+    this.#room(10)
+    while (n >= 0x80) {
+      this.buf[this.pos++] = (n % 0x80) | 0x80
+      n = Math.floor(n / 0x80)
+    }
+    this.buf[this.pos++] = n
+  }
+
+  svarint(n) {
+    this.uvarint(n < 0 ? -2 * n - 1 : 2 * n)
+  }
+
+  f64(x) {
+    this.#room(8)
+    this.dv.setFloat64(this.pos, x)
+    this.pos += 8
+  }
+
+  i64(x) {
+    this.#room(8)
+    this.dv.setBigInt64(this.pos, x)
+    this.pos += 8
+  }
+
+  raw(u8) {
+    if (u8.length >= BIG_SEGMENT) {
+      this.#flush()
+      this.segments.push(u8.slice())
+      this.bytes += u8.length
+      return
+    }
+    this.#room(u8.length)
+    this.buf.set(u8, this.pos)
+    this.pos += u8.length
+  }
+
+  finish() {
+    this.#flush()
+    return { segments: this.segments, bytes: this.bytes }
+  }
+}
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+const I64_MIN = -(1n << 63n)
+const I64_MAX = (1n << 63n) - 1n
+
+export function encodeGraph(root, { classes = {}, special = null } = {}) {
+  const w = new Writer()
+  const ids = new Map()
+  const names = new Map(Object.entries(classes).map(([n, c]) => [c.ctor, n]))
+  const skip = new Map(Object.entries(classes).map(([n, c]) => [n, new Set(c.skip || [])]))
+  w.i64(BigInt(MAGIC))
+
+  function value(v) {
+    switch (typeof v) {
+      case 'undefined':
+        return w.byte(T_UNDEF)
+      case 'boolean':
+        return w.byte(v ? T_TRUE : T_FALSE)
+      case 'number':
+        if (Number.isInteger(v) && Math.abs(v) <= Number.MAX_SAFE_INTEGER && !Object.is(v, -0)) {
+          w.byte(T_INT)
+          return w.svarint(v)
+        }
+        w.byte(T_FLOAT)
+        return w.f64(v)
+      case 'bigint':
+        if (v >= I64_MIN && v <= I64_MAX) {
+          w.byte(T_BIG)
+          return w.i64(v)
+        }
+        w.byte(T_BIGSTR)
+        return str(v.toString())
+      case 'string':
+        w.byte(T_STR)
+        return str(v)
+      case 'function':
+        throw new Error('graph: a function cannot be written')
+      case 'symbol':
+        throw new Error('graph: a symbol cannot be written')
+    }
+    if (v === null) return w.byte(T_NULL)
+    if (v instanceof Uint8Array) {
+      w.byte(T_BYTES)
+      w.uvarint(v.length)
+      return w.raw(v)
+    }
+    const had = ids.get(v)
+    if (had !== undefined) {
+      w.byte(T_REF)
+      return w.uvarint(had)
+    }
+    const tok = special?.pack?.(v)
+    if (tok !== undefined) {
+      w.byte(T_SPECIAL)
+      return value(tok)
+    }
+    ids.set(v, ids.size)
+    if (Array.isArray(v)) {
+      w.byte(T_ARRAY)
+      w.uvarint(v.length)
+      for (const x of v) value(x)
+    } else if (v instanceof Map) {
+      w.byte(T_MAP)
+      w.uvarint(v.size)
+      for (const [k, x] of v) {
+        value(k)
+        value(x)
+      }
+    } else if (v instanceof Set) {
+      w.byte(T_SET)
+      w.uvarint(v.size)
+      for (const x of v) value(x)
+    } else {
+      const proto = Object.getPrototypeOf(v)
+      const name = names.get(v.constructor)
+      if (name !== undefined && proto === v.constructor.prototype) {
+        w.byte(T_INST)
+        str(name)
+        fields(v, skip.get(name))
+      } else if (proto === Object.prototype || proto === null) {
+        w.byte(T_OBJ)
+        fields(v, null)
+      } else {
+        throw new Error(`graph: an instance of ${v.constructor?.name || 'an unregistered class'} cannot be written`)
+      }
+    }
+  }
+
+  function fields(o, skipSet) {
+    const keys = Object.keys(o).filter(k => !skipSet?.has(k) && typeof o[k] !== 'function')
+    w.uvarint(keys.length)
+    for (const k of keys) {
+      str(k)
+      value(o[k])
+    }
+  }
+
+  function str(s) {
+    const b = enc.encode(s)
+    w.uvarint(b.length)
+    w.raw(b)
+  }
+
+  value(root)
+  return w.finish()
+}
+
+class Reader {
+  constructor(b) {
+    this.b = b
+    this.p = 0
+    this.dv = new DataView(b.buffer, b.byteOffset, b.byteLength)
+  }
+
+  need(n) {
+    if (this.p + n > this.b.length) throw new Error('graph: truncated')
+  }
+
+  byte() {
+    this.need(1)
+    return this.b[this.p++]
+  }
+
+  uvarint() {
+    let x = 0
+    let mul = 1
+    for (let i = 0; i < 8; i++) {
+      const c = this.byte()
+      x += (c & 0x7f) * mul
+      if (!(c & 0x80)) return x
+      mul *= 0x80
+    }
+    throw new Error('graph: bad varint')
+  }
+
+  svarint() {
+    const u = this.uvarint()
+    return u % 2 ? -(u + 1) / 2 : u / 2
+  }
+
+  f64() {
+    this.need(8)
+    const x = this.dv.getFloat64(this.p)
+    this.p += 8
+    return x
+  }
+
+  i64() {
+    this.need(8)
+    const x = this.dv.getBigInt64(this.p)
+    this.p += 8
+    return x
+  }
+
+  take(n) {
+    this.need(n)
+    const out = this.b.subarray(this.p, this.p + n)
+    this.p += n
+    return out
+  }
+}
+
+export function decodeGraph(bytes, { classes = {}, special = null } = {}) {
+  const r = new Reader(bytes)
+  if (r.i64() !== BigInt(MAGIC)) throw new Error('graph: bad magic')
+  const objs = []
+
+  const str = () => dec.decode(r.take(r.uvarint()))
+
+  function value() {
+    const t = r.byte()
+    switch (t) {
+      case T_UNDEF:
+        return undefined
+      case T_NULL:
+        return null
+      case T_FALSE:
+        return false
+      case T_TRUE:
+        return true
+      case T_INT:
+        return r.svarint()
+      case T_FLOAT:
+        return r.f64()
+      case T_BIG:
+        return r.i64()
+      case T_BIGSTR:
+        return BigInt(str())
+      case T_STR:
+        return str()
+      case T_BYTES: {
+        const n = r.uvarint()
+        return r.take(n).slice()
+      }
+      case T_REF: {
+        const id = r.uvarint()
+        if (id >= objs.length) throw new Error('graph: bad reference')
+        return objs[id]
+      }
+      case T_SPECIAL: {
+        const tok = value()
+        if (!special?.revive) throw new Error('graph: a special value and no reviver')
+        return special.revive(tok) // the token took its own id if it is an object; the revived value takes none
+      }
+      case T_ARRAY: {
+        const n = r.uvarint()
+        const a = []
+        objs.push(a)
+        for (let i = 0; i < n; i++) a.push(value())
+        return a
+      }
+      case T_MAP: {
+        const n = r.uvarint()
+        const m = new Map()
+        objs.push(m)
+        for (let i = 0; i < n; i++) {
+          const k = value()
+          m.set(k, value())
+        }
+        return m
+      }
+      case T_SET: {
+        const n = r.uvarint()
+        const s = new Set()
+        objs.push(s)
+        for (let i = 0; i < n; i++) s.add(value())
+        return s
+      }
+      case T_OBJ: {
+        const o = {}
+        objs.push(o)
+        readFields(o)
+        return o
+      }
+      case T_INST: {
+        const name = str()
+        const c = classes[name]
+        if (!c) throw new Error(`graph: unknown class ${name}`)
+        const o = c.make ? c.make() : new c.ctor()
+        objs.push(o)
+        readFields(o)
+        return o
+      }
+      default:
+        throw new Error(`graph: bad tag ${t}`)
+    }
+  }
+
+  function readFields(o) {
+    const n = r.uvarint()
+    for (let i = 0; i < n; i++) {
+      const k = str()
+      // a hostile file must not reach Object.prototype (o.__proto__ = {...} would replace the prototype of an instance)
+      if (k === '__proto__') throw new Error('graph: field name __proto__')
+      o[k] = value()
+    }
+  }
+
+  return value()
+}