@dtudury/streamo 0.1.0

package/public/streamo/Streamo.test.js

@@ -0,0 +1,205 @@
+import { describe } from './utils/testing.js'
+import { Streamo, ConflictError } from './Streamo.js'
+import { Signer } from './Signer.js'
+import { Signature } from './Signature.js'
+
+describe(import.meta.url, ({ test }) => {
+  test('encodes and decodes primitive values', ({ assert }) => {
+    const s = new Streamo()
+    const values = [
+      undefined, null, false, true,
+      0, 1, 127,
+      128, -1, 3.14, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY,
+      new Uint8Array([1, 2, 3]),
+      new Uint8Array([4, 5, 6, 7]),
+      new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]),
+      'hello',
+      'a longer string that definitely does not fit in four bytes',
+      new Date('1969-07-21T22:56:15Z'),
+      { a: 1, b: 2, c: 3 },
+      { x: 'hello' },
+      {},
+      [1, 2, 3],
+      [],
+      ['a', 'b'],
+      new Signature(0, new Uint8Array(64))
+    ]
+    for (const value of values) {
+      const code = s.encodeVariable(value)
+      const decoded = s.decode(code)
+      assert.deepEqual(decoded, value, `round-trips ${Object.prototype.toString.call(value)}`)
+    }
+  })
+
+  test('negative addresses for single-byte primitives', ({ assert }) => {
+    const s = new Streamo()
+    for (const v of [undefined, null, false, true, 0, 1, 127]) {
+      const code = s.encode(v)
+      assert.equal(code.length, 1, `${String(v)} encodes to 1 byte`)
+      const addr = -(code[0] + 1)
+      assert.ok(addr < 0, `${String(v)} has a negative address`)
+      assert.deepEqual(s.decode(addr), v, `negative address resolves back to ${String(v)}`)
+    }
+  })
+
+  test('deduplication: same value always gets the same address', ({ assert }) => {
+    const s = new Streamo()
+    const a1 = s.append(s.encode(42))
+    s.append(s.encode({ x: 42 }))
+    const code42 = s.encode(42)
+    assert.equal(s.addressOf(code42), a1, 'second encode of 42 reuses the existing address')
+  })
+
+  test('reactive get/set/watch', async ({ assert }) => {
+    const s = new Streamo()
+    let callCount = 0
+    let lastValue
+
+    s.watch('test', () => {
+      lastValue = s.get('greeting')
+      callCount++
+    })
+    assert.equal(callCount, 1, 'watch runs immediately')
+    assert.equal(lastValue, undefined, 'no value yet')
+
+    s.set({ greeting: 'hello' })
+    await new Promise(resolve => setTimeout(resolve, 20))
+    assert.equal(callCount, 2, 'watch re-ran after set')
+    assert.equal(lastValue, 'hello', 'updated value seen')
+
+    s.set('greeting', 'world')
+    await new Promise(resolve => setTimeout(resolve, 20))
+    assert.equal(callCount, 3, 'watch re-ran after path set')
+    assert.equal(lastValue, 'world', 'path update seen')
+  })
+
+  test('asRefs returns addresses for object values and names', ({ assert }) => {
+    const s = new Streamo()
+    const code = s.encode({ a: 1 })
+
+    // asRefs=true: values become addresses, names stay as strings
+    const withTrue = s.decode(code, true)
+    assert.deepEqual(Object.keys(withTrue), ['a'])
+    assert.equal(typeof withTrue.a, 'number', 'value is an address')
+    assert.equal(s.decode(withTrue.a), 1, 'address decodes to original value')
+
+    // asRefs=[true, false]: same — value is address, name is string
+    const withValueRef = s.decode(code, [true, false])
+    assert.equal(typeof withValueRef.a, 'number')
+    assert.equal(s.decode(withValueRef.a), 1)
+
+    // asRefs=[false, true]: value decoded, name is address
+    const withNameRef = s.decode(code, [false, true])
+    assert.deepEqual(Object.values(withNameRef), [1])
+    const nameAddr = Number(Object.keys(withNameRef)[0])
+    assert.equal(s.decode(nameAddr), 'a', 'key address decodes to the name string')
+  })
+
+  test('asRefs: object returns name/address map', ({ assert }) => {
+    const s = new Streamo()
+    s.set({ x: 1, y: 2 })
+    const refs = s.asRefs(s.byteLength - 1)
+    assert.deepEqual(Object.keys(refs), ['x', 'y'])
+    assert.equal(typeof refs.x, 'number')
+    assert.equal(typeof refs.y, 'number')
+    assert.equal(s.decode(refs.x), 1)
+    assert.equal(s.decode(refs.y), 2)
+  })
+
+  test('asRefs: array returns element addresses', ({ assert }) => {
+    const s = new Streamo()
+    s.set(['a', 'b', 'c'])
+    const refs = s.asRefs(s.byteLength - 1)
+    assert.ok(Array.isArray(refs))
+    assert.equal(refs.length, 3)
+    refs.forEach(addr => assert.equal(typeof addr, 'number'))
+    assert.equal(s.decode(refs[0]), 'a')
+    assert.equal(s.decode(refs[1]), 'b')
+    assert.equal(s.decode(refs[2]), 'c')
+  })
+
+  test('asRefs: non-object returns the address itself', ({ assert }) => {
+    const s = new Streamo()
+    s.set('hello')
+    const address = s.byteLength - 1
+    assert.equal(s.asRefs(address), address)
+  })
+
+  test('encode(asRefs(addr), true) round-trips an object', ({ assert }) => {
+    const s = new Streamo()
+    s.set({ a: 1, b: 'hello' })
+    const addr = s.byteLength - 1
+    const refs = s.asRefs(addr)
+    const code = s.encode(refs, true)
+    assert.deepEqual(s.decode(code), { a: 1, b: 'hello' })
+  })
+
+  test('encode(asRefs(addr), true) round-trips an array', ({ assert }) => {
+    const s = new Streamo()
+    s.set([10, 20, 30])
+    const addr = s.byteLength - 1
+    const refs = s.asRefs(addr)
+    const code = s.encode(refs, true)
+    assert.deepEqual(s.decode(code), [10, 20, 30])
+  })
+
+  test('encode(asRefs(addr), true) round-trips a primitive', ({ assert }) => {
+    const s = new Streamo()
+    s.set('hello')
+    const addr = s.byteLength - 1
+    const refs = s.asRefs(addr)  // returns addr itself for non-objects
+    const code = s.encode(refs, true)  // resolves addr → string code
+    assert.equal(s.decode(code), 'hello')
+  })
+
+  test('sign and verify', async ({ assert }) => {
+    const s = new Streamo()
+    s.set({ hello: 'world' })
+    s.set('hello', 'signed')
+
+    const signer = new Signer('alice', 'secret')
+    const name = 'my-streamo'
+    const keys = await signer.keysFor(name)
+    const sig = await s.sign(signer, name)
+
+    assert.ok(sig instanceof Signature)
+    assert.ok(await s.verify(sig, keys.publicKey), 'signature verifies with correct key')
+
+    const other = new Signer('bob', 'different')
+    const otherKeys = await other.keysFor(name)
+    assert.ok(!(await s.verify(sig, otherKeys.publicKey)), 'wrong key does not verify')
+  })
+
+  test('conditionalSet rejects stale edits and accepts fresh ones', ({ assert }) => {
+    const s = new Streamo()
+    s.set({ x: 1 })
+    const tip = s.byteLength
+
+    // A concurrent write advances the streamo past tip
+    s.set({ x: 2 })
+
+    // Stale edit is rejected
+    let caught
+    try { s.conditionalSet(tip, { x: 3 }) } catch (e) { caught = e }
+    assert.ok(caught instanceof ConflictError, 'throws ConflictError')
+    assert.equal(caught.expectedTip, tip)
+    assert.equal(caught.actualTip, s.byteLength)
+    assert.equal(s.get('x'), 2, 'streamo unchanged after rejection')
+
+    // Fresh edit at current tip succeeds
+    const freshTip = s.byteLength
+    s.conditionalSet(freshTip, { x: 3 })
+    assert.equal(s.get('x'), 3, 'fresh conditional set applied')
+  })
+
+  test('clone snapshots state at a given address', ({ assert }) => {
+    const s = new Streamo()
+    s.set({ v: 1 })
+    const addr1 = s.byteLength - 1
+    s.set({ v: 2 })
+
+    const snap = s.clone(addr1)
+    assert.equal(snap.get('v'), 1, 'clone reflects state at snapshot address')
+    assert.equal(s.get('v'), 2, 'original still reflects latest state')
+  })
+})

package/public/streamo/archiveSync.js

@@ -0,0 +1,62 @@
+import { mkdir, open, readFile } from 'fs/promises'
+import { join } from 'path'
+
+/**
+ * Load a stream from disk and keep it in sync as new chunks arrive.
+ *
+ * On startup, reads `<dir>/<publicKeyHex>.bin` (wire format: 4-byte LE length
+ * prefix per chunk) and feeds it into the stream via makeWritableStream().
+ *
+ * Then opens the file for writing and drains makeReadableStream() into it —
+ * re-emitting all loaded chunks first, then appending new ones as they arrive.
+ * This means the file is always a complete, valid wire-format snapshot.
+ *
+ * @param {import('./Stream.js').Stream} stream
+ * @param {string} dir  directory to store archive files in
+ * @param {string} publicKeyHex  hex-encoded public key, used as filename
+ */
+export async function archiveSync (stream, dir, publicKeyHex) {
+  await mkdir(dir, { recursive: true })
+  const filePath = join(dir, `${publicKeyHex}.bin`)
+
+  // Load existing data
+  try {
+    const bytes = await readFile(filePath)
+    if (bytes.length > 0) {
+      const writer = stream.makeWritableStream().getWriter()
+      await writer.write(bytes)
+    }
+  } catch {
+    // No existing archive — start fresh
+  }
+
+  // Compact plain Streams: discard accumulated history and keep only the
+  // current value. Skipped for Repository subclasses whose commit records
+  // embed dataAddress pointers that would become invalid after a reset.
+  if (stream.byteLength > 0 && typeof stream.commit !== 'function') {
+    try {
+      const value = stream.get()
+      if (value !== undefined) {
+        stream._reset()
+        stream.set(value)
+      }
+    } catch { /* not compactable */ }
+  }
+
+  // Rewrite file from chunk 0 and keep appending as new chunks arrive.
+  // makeReadableStream() emits all existing chunks then waits indefinitely,
+  // so this loop runs for the lifetime of the process.
+  const fileHandle = await open(filePath, 'w')
+  const reader = stream.makeReadableStream().getReader();
+  (async () => {
+    try {
+      while (true) {
+        const { value, done } = await reader.read()
+        if (done) break
+        await fileHandle.write(value)
+      }
+    } finally {
+      await fileHandle.close()
+    }
+  })()
+}

package/public/streamo/chat-cli.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * streamo chat CLI
+ *
+ * Usage:
+ *   node public/streamo/chat-cli.js [username] [password] [host] [port]
+ *
+ * Joins the chat room, prints incoming messages, and reads outgoing messages
+ * from stdin (one line = one message).
+ *
+ * Example for Claude to join and help debug:
+ *   node public/streamo/chat-cli.js claude claude localhost 8080
+ */
+import readline from 'node:readline'
+import { Signer } from './Signer.js'
+import { RepoRegistry } from './RepoRegistry.js'
+import { registrySync } from './registrySync.js'
+import { bytesToHex } from './utils.js'
+
+const [,, username = 'claude', password = 'claude', host = 'localhost', portStr = '8080'] = process.argv
+const port = Number(portStr)
+
+// Derive identity from username + password (1 iteration = fast for dev)
+const signer = new Signer(username, password, 1)
+const { publicKey } = await signer.keysFor('chat')
+const myKey = bytesToHex(publicKey)
+
+// Fetch root key from server
+let rootKey
+try {
+  const res = await fetch(`http://${host}:${port}/api/chat-info`)
+  ;({ rootKey } = await res.json())
+} catch (e) {
+  console.error(`could not reach server at http://${host}:${port}: ${e.message}`)
+  process.exit(1)
+}
+
+console.log(`\njoining as ${username}`)
+console.log(`my key  : ${myKey.slice(0, 16)}…`)
+console.log(`root key: ${rootKey.slice(0, 16)}…`)
+console.log('─'.repeat(40))
+
+const registry = new RepoRegistry()
+const session = await registrySync(registry, host, port, {
+  filter: k => k === rootKey,
+  follow: (keyHex, repo, subscribe) => {
+    // Auto-follow all members listed in the root repo
+    for (const memberKey of repo.get('members') ?? []) subscribe(memberKey)
+  },
+  onAnnounce: (key) => {
+    // When someone announces directly, subscribe to their repo immediately
+    session.subscribe(key)
+  }
+})
+
+// Open my own repo, set profile if first time
+const myRepo = await registry.open(myKey)
+if (!myRepo.get('name')) {
+  myRepo.set({ name: username, messages: [] })
+}
+
+// Announce and express interest
+session.interest(rootKey)
+session.announce(myKey, rootKey)
+
+// ── Message rendering ──────────────────────────────────────────────────────
+
+// Track last-seen message count per repo so we only print new messages
+const seen = new Map()
+
+function printNewMessages (keyHex, repo) {
+  const name = repo.get('name')
+  if (!name || keyHex === myKey) return  // skip unnamed repos and self
+  const messages = repo.get('messages') ?? []
+  const prev = seen.get(keyHex) ?? 0
+  for (let i = prev; i < messages.length; i++) {
+    const msg = messages[i]
+    const text = typeof msg === 'string' ? msg : msg?.text ?? String(msg)
+    const time = msg?.at ? new Date(msg.at).toLocaleTimeString() : ''
+    console.log(`\n${time ? `[${time}] ` : ''}${name}: ${text}`)
+    process.stdout.write('> ')  // re-print prompt
+  }
+  seen.set(keyHex, messages.length)
+}
+
+function watchRepo (keyHex, repo) {
+  if (seen.has(keyHex)) return
+  seen.set(keyHex, 0)
+  repo.watch(`chat-cli:${keyHex}`, () => printNewMessages(keyHex, repo))
+}
+
+// Watch all repos already in registry
+for (const [k, r] of registry) watchRepo(k, r)
+
+// Watch repos that open later
+registry.onOpen((keyHex, repo) => watchRepo(keyHex, repo))
+
+// ── Stdin → outgoing messages ──────────────────────────────────────────────
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  prompt: '> '
+})
+
+rl.prompt()
+
+rl.on('line', async line => {
+  const text = line.trim()
+  if (!text) { rl.prompt(); return }
+  const messages = myRepo.get('messages') ?? []
+  myRepo.set({ name: username, messages: [...messages, { text, at: Date.now() }] })
+  rl.prompt()
+})
+
+rl.on('close', () => {
+  console.log('\nbye')
+  process.exit(0)
+})
+
+console.log('ready — type a message and press enter\n')
+rl.prompt()

package/public/streamo/chat-server.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * streamo chat server
+ *
+ * Usage:
+ *   node public/streamo/chat-server.js [port]
+ *
+ * Starts an HTTP + WebSocket server.  Auto-accepts any participant that
+ * announces their repo key to the root chat topic.
+ *
+ * The root key is printed on startup — pass it to clients via the
+ * /api/chat-info endpoint or by copying it into the config.
+ */
+import { createServer } from 'http'
+import { WebSocketServer } from 'ws'
+import { fileURLToPath } from 'url'
+import { join, dirname } from 'path'
+import express from 'express'
+import { Signer } from './Signer.js'
+import { RepoRegistry } from './RepoRegistry.js'
+import { attachStreamSync } from './outletSync.js'
+import { bytesToHex } from './utils.js'
+
+const port = Number(process.argv[2] ?? process.env.PORT ?? 8080)
+const __dir = dirname(fileURLToPath(import.meta.url))
+
+// Derive a stable, well-known root key for this chat room.
+// Using 1 PBKDF2 iteration so startup is instant; this is fine for a demo.
+const rootSigner = new Signer('streamo-chat-room', 'streamo-chat', 1)
+const { publicKey: rootPubKey } = await rootSigner.keysFor('v1')
+const ROOT_KEY = bytesToHex(rootPubKey)
+
+const registry = new RepoRegistry()
+const rootRepo = await registry.open(ROOT_KEY)
+if (!rootRepo.get('members')) rootRepo.set({ name: 'chat-root', members: [] })
+
+// Auto-accept: when a client announces their key to the root topic, add them.
+function onAnnounce (key, topic) {
+  if (topic !== ROOT_KEY) return
+  const members = rootRepo.get('members') ?? []
+  if (!members.includes(key)) {
+    rootRepo.set({ name: 'chat-root', members: [...members, key] })
+    console.log(`[chat] new member: ${key.slice(0, 12)}…`)
+  }
+}
+
+const app = express()
+app.use(express.static(join(__dir, '../../apps/chat')))
+// Also serve public/streamo/ so the browser can import streamo modules
+app.use('/streamo', express.static(__dir))
+app.get('/api/chat-info', (_req, res) => res.json({ rootKey: ROOT_KEY }))
+
+const server = createServer(app)
+const wss = new WebSocketServer({ server })
+attachStreamSync(wss, registry, 'chat', { onAnnounce })
+
+server.listen(port, () => {
+  console.log(`chat server → http://localhost:${port}`)
+  console.log(`root key   → ${ROOT_KEY}`)
+})