@dtudury/streamo 0.1.0

package/public/streamo/utils/testing.js

@@ -0,0 +1,90 @@
+/**
+ * Universal test utility for stream/ tests.
+ *
+ * In Node.js:   wraps node:test describe/test — tests actually execute via `node --test`
+ * In browser:   no-op for now; browser test runner to be rebuilt as a stream module
+ *
+ * Usage in test files:
+ *
+ *   import { describe, assert } from './utils/testing.js'
+ *
+ *   describe(import.meta.url, ({ test }) => {
+ *     test('my case', () => {
+ *       assert.equal(actual, expected)
+ *     })
+ *     test('async case', async () => {
+ *       const result = await someAsyncThing()
+ *       assert.ok(result)
+ *     })
+ *   })
+ */
+
+const IS_NODE = typeof process !== 'undefined' && process.versions?.node != null
+
+// ── Assertions ────────────────────────────────────────────────────────────
+// Throws on failure, works in any environment.
+
+class AssertionError extends Error {
+  constructor (message) {
+    super(message)
+    this.name = 'AssertionError'
+  }
+}
+
+function fmt (v) {
+  try {
+    if (v instanceof Uint8Array) return `Uint8Array[${[...v]}]`
+    return JSON.stringify(v)
+  } catch {
+    return String(v)
+  }
+}
+
+export const assert = {
+  ok (val, msg) {
+    if (!val) throw new AssertionError(msg ?? `expected truthy, got ${fmt(val)}`)
+  },
+  equal (actual, expected, msg) {
+    if (actual !== expected) throw new AssertionError(msg ?? `${fmt(actual)} !== ${fmt(expected)}`)
+  },
+  notEqual (actual, expected, msg) {
+    if (actual === expected) throw new AssertionError(msg ?? `expected values to differ, both were ${fmt(actual)}`)
+  },
+  deepEqual (actual, expected, msg) {
+    if (fmt(actual) !== fmt(expected)) throw new AssertionError(msg ?? `${fmt(actual)} !== ${fmt(expected)}`)
+  },
+  throws (fn, msg) {
+    let threw = false
+    try { fn() } catch { threw = true }
+    if (!threw) throw new AssertionError(msg ?? 'expected function to throw')
+  }
+}
+
+// ── describe / test ───────────────────────────────────────────────────────
+
+let _impl
+
+if (IS_NODE) {
+  const { describe: nodeDescribe, test: nodeTest } = await import('node:test')
+  _impl = {
+    describe (name, fn) {
+      nodeDescribe(name, () => fn({
+        test: (testName, testFn) => nodeTest(testName, () => testFn({ assert }))
+      }))
+    }
+  }
+} else {
+  // Browser test runner: TODO rebuild as a first-class stream module
+  _impl = { describe () {} }
+}
+
+/**
+ * Declare a group of tests. Pass import.meta.url as the name so the
+ * test runner can show which file each group came from.
+ *
+ * @param {string} name  typically import.meta.url
+ * @param {function({ test: function }): void} fn
+ */
+export function describe (name, fn) {
+  _impl.describe(name, fn)
+}

package/public/streamo/utils.js

@@ -0,0 +1,57 @@
+/**
+ * Encode a Uint8Array as a lowercase hex string.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export function bytesToHex (bytes) {
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('')
+}
+
+/**
+ * Decode a hex string to a Uint8Array.
+ * @param {string} hex
+ * @returns {Uint8Array}
+ */
+export function hexToBytes (hex) {
+  const bytes = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
+  return bytes
+}
+
+/**
+ * Encode a non-negative integer as a little-endian byte array.
+ * The number of bytes needed is the minimum to represent the value.
+ * @param {number} n
+ * @returns {Uint8Array}
+ */
+export function numberToVar (n) {
+  if (n < 0) throw new Error('n must be non-negative')
+  if (!n) return new Uint8Array([0])
+  const bytes = []
+  while (n) {
+    bytes.push(n & 0xff)
+    n >>>= 8
+  }
+  return new Uint8Array(bytes)
+}
+
+/**
+ * Decode a little-endian byte array back to a number.
+ * @param {Uint8Array} bytes
+ * @returns {number}
+ */
+export function varToNumber (bytes) {
+  let n = 0
+  for (let i = bytes.length - 1; i >= 0; i--) {
+    n = (n * 256 + bytes[i]) >>> 0
+  }
+  return n
+}
+
+/**
+ * @param {number} length
+ * @returns {Array.<number>}
+ */
+export function range (length) {
+  return Array.from({ length }, (_, i) => i)
+}

package/public/streamo/webSync.js

@@ -0,0 +1,118 @@
+import { createServer } from 'http'
+import { WebSocketServer } from 'ws'
+import express from 'express'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { attachStreamSync } from './outletSync.js'
+
+const publicDir = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+/**
+ * Start an HTTP + WebSocket server that exposes a RepoRegistry to browsers
+ * and other peers.
+ *
+ * HTTP endpoints:
+ *   GET /                         → 200 JSON: current value of the primary streamo
+ *   GET /streams/:key             → 200 JSON: current value of streamo `key`
+ *   GET /streams/:key/raw         → 200 application/octet-stream: full wire-format archive
+ *
+ * WebSocket (same port, upgraded from HTTP):
+ *   Uses the same handshake + full-duplex wire protocol as outletSync, so any
+ *   originSync client can connect here directly.
+ *
+ * @param {import('./RepoRegistry.js').RepoRegistry} registry
+ * @param {string} primaryKeyHex   public key of the "main" streamo for GET /
+ * @param {number} port
+ * @returns {Promise<import('http').Server>}
+ */
+export async function webSync (registry, primaryKeyHex, port, name, keyIterations = 100000) {
+  const app = express()
+
+  app.use(express.static(publicDir))
+
+  app.use(express.json())
+
+  // Expose primary key so the browser app knows which streamo to open
+  app.get('/api/info', (req, res) => {
+    res.json({ primaryKeyHex, name, keyIterations })
+  })
+
+  // Write a single file to the primary streamo's latest commit
+  app.post('/api/file', async (req, res) => {
+    try {
+      const { path, content, message } = req.body
+      if (typeof path !== 'string' || typeof content !== 'string') {
+        return res.status(400).json({ error: 'path and content must be strings' })
+      }
+      const repo = await registry.open(primaryKeyHex)
+      const working = repo.checkout()
+      // Store JSON files as parsed objects so they round-trip cleanly with fileSync
+      let value = content
+      if (path.endsWith('.json')) {
+        try { value = JSON.parse(content) } catch {}
+      }
+      working.set(path, value)
+      repo.commit(working, message || `edit ${path}`)
+      res.json({ ok: true })
+    } catch (e) {
+      res.status(500).json({ error: e.message })
+    }
+  })
+
+  // Current value of the primary streamo as JSON
+  app.get('/', async (req, res) => {
+    try {
+      const streamo = await registry.open(primaryKeyHex)
+      res.json(streamo.byteLength > 0 ? streamo.get() : null)
+    } catch (e) {
+      res.status(500).json({ error: e.message })
+    }
+  })
+
+  // Current value of any streamo as JSON
+  app.get('/streams/:key', async (req, res) => {
+    try {
+      const streamo = await registry.open(req.params.key)
+      res.json(streamo.byteLength > 0 ? streamo.get() : null)
+    } catch (e) {
+      res.status(500).json({ error: e.message })
+    }
+  })
+
+  // Full wire-format snapshot of a streamo's current chunks (finite — does not
+  // stream future appends). Used by browsers to bootstrap before WebSocket sync
+  // so both sides share the same address space.
+  app.get('/streams/:key/raw', async (req, res) => {
+    try {
+      const streamo = await registry.open(req.params.key)
+      res.set('Content-Type', 'application/octet-stream')
+      const target = streamo.byteLength  // snapshot length; stop here
+      if (target === 0) { res.end(); return }
+      const reader = streamo.makeReadableStream().getReader()
+      res.on('close', () => reader.cancel().catch(() => {}))
+      let contentSent = 0
+      const pump = async () => {
+        if (contentSent >= target) { reader.cancel().catch(() => {}); res.end(); return }
+        const { value, done } = await reader.read()
+        if (done || !res.writable) { res.end(); return }
+        // wire frame: [4-byte LE length][chunk bytes] — read length to track progress
+        contentSent += (value[0]) | (value[1] << 8) | (value[2] << 16) | (value[3] << 24)
+        res.write(Buffer.from(value))
+        pump()
+      }
+      pump()
+    } catch (e) {
+      res.status(500).json({ error: e.message })
+    }
+  })
+
+  const server = createServer(app)
+
+  attachStreamSync(new WebSocketServer({ server }), registry, 'web')
+
+  await new Promise((resolve, reject) => {
+    server.listen(port, err => err ? reject(err) : resolve())
+  })
+
+  return server
+}

package/scripts/serve.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * Serve public/ as a static site.
+ * Usage: node scripts/serve.js [port]
+ */
+import express from 'express'
+import { fileURLToPath } from 'url'
+import { join, dirname } from 'path'
+
+const port = Number(process.argv[2] ?? process.env.PORT ?? 3000)
+const root = join(dirname(fileURLToPath(import.meta.url)), '../public')
+
+const app = express()
+app.use(express.static(root))
+app.listen(port, () => console.log(`http://localhost:${port}`))

package/smoke.test.js

@@ -0,0 +1,132 @@
+import { describe } from './public/streamo/utils/testing.js'
+import { Streamo } from './public/streamo/Streamo.js'
+import { Repo } from './public/streamo/Repo.js'
+import { RepoRegistry } from './public/streamo/RepoRegistry.js'
+import { archiveSync } from './public/streamo/archiveSync.js'
+import { webSync } from './public/streamo/webSync.js'
+import { Signer } from './public/streamo/Signer.js'
+import WebSocket from 'ws'
+import { rm, mkdtemp } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+// 1 iteration keeps key derivation fast without compromising what we're testing
+const KEY_ITERATIONS = 1
+const toHex = bytes => Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('')
+
+async function makeKey (name = 'smoke') {
+  const signer = new Signer('test', 'test', KEY_ITERATIONS)
+  const { publicKey } = await signer.keysFor(name)
+  return { signer, publicKey, publicKeyHex: toHex(publicKey) }
+}
+
+async function startServer (publicKeyHex, stream) {
+  const registry = new RepoRegistry(() => stream)
+  const server = await webSync(registry, publicKeyHex, 0, 'smoke-test', KEY_ITERATIONS)
+  const { port } = server.address()
+  const close = () => new Promise(resolve => server.close(resolve))
+  return { port, close }
+}
+
+describe(import.meta.url, ({ test }) => {
+  test('GET /api/info returns primaryKeyHex and name', async ({ assert }) => {
+    const { publicKeyHex } = await makeKey()
+    const { port, close } = await startServer(publicKeyHex, new Streamo())
+    try {
+      const info = await fetch(`http://localhost:${port}/api/info`).then(r => r.json())
+      assert.equal(info.primaryKeyHex, publicKeyHex)
+      assert.equal(info.name, 'smoke-test')
+    } finally {
+      await close()
+    }
+  })
+
+  test('GET /streams/:key/raw loads into a fresh Streamo', async ({ assert }) => {
+    const { publicKeyHex } = await makeKey()
+    const stream = new Streamo()
+    stream.set({ hello: 'world' })
+    const { port, close } = await startServer(publicKeyHex, stream)
+    try {
+      const buf = await fetch(`http://localhost:${port}/streams/${publicKeyHex}/raw`)
+        .then(r => r.arrayBuffer())
+      const fresh = new Streamo()
+      await fresh.makeWritableStream().getWriter().write(new Uint8Array(buf))
+      assert.deepEqual(fresh.get(), { hello: 'world' })
+    } finally {
+      await close()
+    }
+  })
+
+  test('WebSocket syncs existing chunks to a connecting client', async ({ assert }) => {
+    const { publicKeyHex } = await makeKey()
+    const stream = new Streamo()
+    stream.set({ synced: true })
+    const { port, close } = await startServer(publicKeyHex, stream)
+    try {
+      const client = new Streamo()
+      const writer = client.makeWritableStream().getWriter()
+      const ws = new WebSocket(`ws://localhost:${port}`)
+
+      await new Promise((resolve, reject) => {
+        ws.on('open', () => ws.send(publicKeyHex))
+        ws.on('message', async data => {
+          await writer.write(new Uint8Array(data))
+          if (client.byteLength >= stream.byteLength) resolve()
+        })
+        ws.on('error', reject)
+        setTimeout(() => reject(new Error('WS sync timed out')), 2000)
+      })
+
+      ws.close()
+      assert.deepEqual(client.get(), { synced: true })
+    } finally {
+      await close()
+    }
+  })
+
+  test('set() with a path works when root is VARIABLE-encoded (old server data)', ({ assert }) => {
+    // Old server archives encoded the root value as VARIABLE (a boxed address).
+    // asRefs() previously returned the VARIABLE address number rather than the
+    // inner object's refs, causing refs['toggle'] === undefined → crash.
+    const stream = new Streamo()
+    // encodeVariable to simulate old-style encoded root
+    const rootCode = stream.encodeVariable({ toggle: { value: false, label: 'enabled' }, counter: { value: 0 } })
+    stream.append(rootCode)
+    // get() should see through VARIABLE
+    assert.equal(stream.get('toggle', 'value'), false)
+    // set() with a 2-level path must not crash
+    stream.set('toggle', 'value', true)
+    assert.equal(stream.get('toggle', 'value'), true)
+    assert.equal(stream.get('counter', 'value'), 0)
+  })
+
+  test('set() after sign() reads/writes user data, not the signature chunk', async ({ assert }) => {
+    const { signer } = await makeKey()
+    const stream = new Streamo()
+    stream.set({ count: 0 })
+    await stream.sign(signer, 'smoke')
+    // Before the fix, set() with a path would crash here because byteLength - 1
+    // pointed to the signature chunk instead of the data chunk.
+    stream.set('count', stream.get('count') + 1)
+    assert.equal(stream.get('count'), 1)
+    // get() must also skip past the signature
+    assert.deepEqual(stream.get(), { count: 1 })
+  })
+
+  test('archiveSync persists data and reloads it on a fresh Streamo', async ({ assert }) => {
+    const { publicKeyHex } = await makeKey('archive')
+    const dir = await mkdtemp(join(tmpdir(), 'smoke-'))
+    try {
+      const stream1 = new Streamo()
+      await archiveSync(stream1, dir, publicKeyHex)
+      stream1.set({ persisted: true })
+      await new Promise(r => setTimeout(r, 100))  // let write loop flush
+
+      const stream2 = new Streamo()
+      await archiveSync(stream2, dir, publicKeyHex)
+      assert.deepEqual(stream2.get(), { persisted: true })
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})