wenay-common2 1.0.70 → 1.0.74

package/replay/peer-call.test.ts

@@ -0,0 +1,226 @@
+// Acceptance oracle for the call system (ROADMAP "Call system" candidate):
+// presence + ring/accept/decline/hangup over the EXISTING signal hub, media
+// frames over the relay lines while the call is active — all on a real
+// Socket.IO/RPC wire, next to the peer fragment, with zero new server routes
+// beyond the fragment keys (presence) and the media relay object.
+import express from 'express'
+import {createServer} from 'http'
+import type {AddressInfo} from 'net'
+import {Server as SocketIOServer} from 'socket.io'
+import {io} from 'socket.io-client'
+import {listen as createListenPair} from '../src/Common/events/Listen'
+import {createSignalHub, SignalEnvelope} from '../src/Common/events/route-signal-webrtc'
+import {createPeerHost} from '../src/Common/peer/peer-host'
+import {callPortOf, createCallManager} from '../src/Common/peer/peer-call'
+import {createMediaRelay} from '../src/Common/peer/peer-media-relay'
+import {createRpcClientHub} from '../src/Common/rcp/rpc-clientHub'
+import {createRpcServerAuto} from '../src/Common/rcp/rpc-server-auto'
+
+let fails = 0
+const ok = (condition: any, message: string) => {
+    if (!condition) { fails++; console.log('  FAIL', message) }
+    else console.log('  OK  ', message)
+}
+const delay = (ms: number) => new Promise<void>(r => setTimeout(r, ms))
+
+async function waitFor(label: string, cond: () => boolean) {
+    for (let i = 0; i < 200; i++) {
+        if (cond()) return
+        await delay(20)
+    }
+    throw new Error(`timeout: ${label}`)
+}
+
+async function main() {
+    console.log('\n[peer-call] presence + ring/accept/decline + media over the relay')
+
+    // ================= lifecycle regressions (in-process, deterministic) =================
+    const signalHub = createSignalHub()
+    const firstA = signalHub.register('same')
+    const newestA = signalHub.register('same')
+    const sender = signalHub.register('sender')
+    let firstHits = 0
+    let newestHits = 0
+    firstA.signals.on(() => firstHits++)
+    newestA.signals.on(() => newestHits++)
+    await sender.send({type: 'ring', pair: 'multi:1', from: 'sender', to: 'same'})
+    newestA.close()
+    const fallbackSent = await sender.send({type: 'ring', pair: 'multi:2', from: 'sender', to: 'same'})
+    ok(newestHits == 1 && firstHits == 1 && fallbackSent == true,
+        'closing the newest same-account signal port restores the previous live port')
+    signalHub.close()
+
+    const [emitLocalSignal, localSignals] = createListenPair<[SignalEnvelope]>()
+    const localSends: SignalEnvelope[] = []
+    const localCalls = createCallManager({
+        self: 'callee',
+        port: {
+            signals: localSignals,
+            send: function captureLocalSend(env) { localSends.push(env); return true },
+        },
+    })
+    let localRings = 0
+    localCalls.rings.on(() => localRings++)
+    emitLocalSignal({type: 'ring', pair: 'call:x:1', from: 'x', to: 'callee'})
+    emitLocalSignal({type: 'ring', pair: 'call:y:1', from: 'y', to: 'callee'})
+    await delay(0)
+    ok(localRings == 1 && localSends.some(env => env.type == 'decline' && env.reason == 'busy'),
+        'back-to-back incoming rings reserve admission: one rings, one is busy')
+    localCalls.close()
+
+    // ================= SERVER: peer fragment + media relay, no call-specific code =================
+    // Watch ACL as APP code: media access follows call state — the policy set is
+    // maintained by the clients below on 'active'/'ended' (via a legacy-style rpc key).
+    const allowedWatch = new Set<string>()
+    const host = createPeerHost()
+    const media = createMediaRelay({
+        lines: {cam: 'video', mic: 'audio'},
+        canWatch: (watcher, owner) => allowedWatch.has(watcher + '|' + owner),
+    })
+    const app = express()
+    const httpServer = createServer(app)
+    const ioServer = new SocketIOServer(httpServer)
+    ioServer.on('connection', socket => {
+        const account = String(socket.handshake.auth?.account)
+        const peer = host.connection(account)
+        const [disconnect, disconnectListen] = createListenPair<[]>()
+        socket.on('disconnect', () => { disconnect(); peer.close() })
+        createRpcServerAuto({
+            socket: {emit: (key, data) => socket.emit(key, data), on: (key, cb) => socket.on(key, cb)},
+            socketKey: 'app',
+            object: {
+                peer: peer.fragment,
+                media: {publish: media.publishOf(account), watch: media.watchOf(account)},
+                // app-level grant hook (a real app would derive this from its own call registry)
+                grantWatch: (a: string, b: string, on: boolean) => {
+                    if (on) { allowedWatch.add(a + '|' + b); allowedWatch.add(b + '|' + a) }
+                    else { allowedWatch.delete(a + '|' + b); allowedWatch.delete(b + '|' + a) }
+                },
+            },
+            disconnectListen,
+        })
+    })
+    await new Promise<void>((resolve, reject) => {
+        httpServer.once('error', reject)
+        httpServer.listen(0, '127.0.0.1', resolve)
+    })
+    const port = (httpServer.address() as AddressInfo).port
+
+    async function connect(account: string) {
+        const hub = createRpcClientHub(
+            () => io(`http://127.0.0.1:${port}`, {transports: ['websocket'], forceNew: true, auth: {account}}),
+            r => ({api: r<any>('app')}) as const,
+        )
+        const clients = await hub.setToken(null)
+        await clients.api.readyStrict()
+        return {func: clients.api.func, closeSocket: () => hub.socket?.disconnect?.()}
+    }
+
+    const connA = await connect('a')
+    const connB = await connect('b')
+
+    // ================= presence =================
+    const presenceLog: any[] = []
+    connA.func.peer.presence.changes.on((ch: any) => presenceLog.push(ch))
+    const online = await connA.func.peer.presence.list()
+    ok(online.includes('a') && online.includes('b'), `presence list sees both accounts: ${JSON.stringify(online)}`)
+
+    // ================= happy path: ring -> accept -> active =================
+    const callsA = createCallManager({port: callPortOf(connA.func.peer), self: 'a'})
+    const callsB = createCallManager({port: callPortOf(connB.func.peer), self: 'b'})
+    await Promise.all([callsA.ready, callsB.ready])
+    let ringAtB: any = null
+    callsB.rings.on((h: any) => { ringAtB = h })
+
+    const out = callsA.call('b', {kinds: ['cam', 'mic']})
+    await waitFor('ring reaches b', () => ringAtB != null)
+    ok(ringAtB.peer == 'a' && ringAtB.direction == 'in', 'incoming handle points back at the caller')
+    ok(JSON.stringify(ringAtB.meta) == JSON.stringify({kinds: ['cam', 'mic']}), 'caller meta rides the ring envelope opaquely')
+    ok(out.state() == 'ringing' && ringAtB.state() == 'ringing', 'both sides are ringing')
+
+    // ================= watch ACL: denied OUTSIDE a call =================
+    let deniedBefore = false
+    try { await connB.func.media.watch.a.cam.keyframe() } catch { deniedBefore = true }
+    ok(deniedBefore, 'watch is DENIED outside a call (canWatch gates path resolution)')
+
+    ringAtB.accept()
+    await waitFor('caller sees accept', () => out.state() == 'active')
+    ok(callsB.active() == ringAtB && callsA.active() == out, 'both sides report the active call')
+
+    // ================= media while active: grant -> publish -> relay line -> watcher =================
+    await connA.func.grantWatch('a', 'b', true) // app code: access follows the call
+    const got: any[] = []
+    connB.func.media.watch.a.cam.on((frame: any, sentAt: number) => got.push([frame, sentAt]))
+    await connA.func.media.publish('cam', new Uint8Array([1, 2, 3]), 12345)
+    await waitFor('cam frame lands at b', () => got.length > 0)
+    ok(got[0][1] == 12345, 'sentAt stamp rides along the media frame')
+    const kf = await connB.func.media.watch.a.cam.keyframe()
+    ok(kf != null && kf.event[1] == 12345, 'video line is keep-latest: a late joiner pulls the last frame via keyframe()')
+
+    // ================= busy gate: third account calls into an active call =================
+    const connC = await connect('c')
+    const callsC = createCallManager({port: callPortOf(connC.func.peer), self: 'c'})
+    await callsC.ready
+    const cToB = callsC.call('b')
+    ok(await cToB.ended == 'busy', 'default gate auto-declines with busy while b is on a call')
+    let deniedThird = false
+    try { await connC.func.media.watch.a.cam.keyframe() } catch { deniedThird = true }
+    ok(deniedThird, 'a third account is still denied while a<->b are on a call')
+
+    // ================= hangup: media access is revoked with the call =================
+    out.hangup()
+    await waitFor('callee sees hangup', () => ringAtB.state() == 'ended')
+    ok(ringAtB.reason() == 'hangup' && await out.ended == 'hangup', 'hangup ends both sides with the reason')
+    await connA.func.grantWatch('a', 'b', false) // app code: revoke with the call
+    const framesBeforeRevoke = got.length
+    await connA.func.media.publish('cam', new Uint8Array([9]), 54321)
+    await delay(50)
+    ok(got.length == framesBeforeRevoke, 'ACL revocation blocks frames on an already-open media subscription')
+    let deniedAfter = false
+    try { await connB.func.media.watch.a.cam.keyframe() } catch { deniedAfter = true }
+    ok(deniedAfter, 'watch is denied again after the call ends (new resolutions blocked)')
+    media.dropAccount('c')
+    ok(!media.accounts().includes('c') && media.accounts().includes('a'), 'dropAccount retires the account keyspace (server-side cleanup hook)')
+
+    // ================= decline =================
+    let ringAtA: any = null
+    callsA.rings.on((h: any) => { ringAtA = h })
+    const bToA = callsB.call('a')
+    await waitFor('ring reaches a', () => ringAtA != null)
+    ringAtA.decline()
+    ok(await bToA.ended == 'declined', 'decline propagates to the caller')
+
+    // ================= offline callee: fails fast, no timeout wait =================
+    const t0 = Date.now()
+    const toGhost = callsA.call('ghost')
+    ok(await toGhost.ended == 'offline' && Date.now() - t0 < 2000, 'calling an offline account fails fast with offline')
+
+    // ================= ring timeout =================
+    const callsA2 = createCallManager({port: callPortOf(connA.func.peer), self: 'a', ringTimeoutMs: 300})
+    await callsA2.ready
+    let unanswered: any = null
+    const offRings = callsB.rings.on((h: any) => { unanswered = h })
+    const timedOut = callsA2.call('b')
+    ok(await timedOut.ended == 'timeout', 'unanswered ring times out on the caller')
+    await waitFor('callee ring cleaned up', () => unanswered != null && unanswered.state() == 'ended')
+    ok(unanswered.reason() == 'canceled', 'the callee ring is canceled by the caller timeout')
+    if (typeof offRings == 'function') offRings()
+
+    // ================= presence offline edge =================
+    connC.closeSocket()
+    await waitFor('presence offline edge', () => presenceLog.some(ch => ch.account == 'c' && ch.online == false))
+    ok(true, 'presence emits the offline edge on disconnect')
+
+    // ================= teardown =================
+    callsA.close(); callsA2.close(); callsB.close(); callsC.close()
+    connA.closeSocket(); connB.closeSocket()
+    media.close()
+    host.close()
+    ioServer.close()
+    await new Promise<void>(resolve => httpServer.close(() => resolve()))
+
+    console.log(fails ? `\n${fails} FAILED` : '\nall passed')
+    if (fails) process.exit(1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })

package/replay/peer-repair.test.ts

@@ -0,0 +1,184 @@
+// Publish-path reconnect correctness (peer SDK): the relay journal never lies
+// after a publisher gap. Gap matrix on createPatchRelayJournal + rejection-driven
+// repair in createPeerClient ('tail' | 'keyframe'), sacred eviction, resync().
+import {flushReactive} from '../src/Common/Observe/reactive'
+import {applyStorePatch, createStore, StorePatch} from '../src/Common/Observe/store'
+import {syncStoreReplay} from '../src/Common/Observe/store-replay'
+import {createPatchRelayJournal, createPeerClient, PatchEnvelope, PeerRemote} from '../src/Common/peer/peer-index'
+
+let fails = 0
+const ok = (condition: any, message: string) => {
+    if (!condition) { fails++; console.log('  FAIL', message) }
+    else console.log('  OK  ', message)
+}
+const delay = (ms: number) => new Promise<void>(r => setTimeout(r, ms))
+const json = (v: any) => JSON.stringify(v)
+
+async function waitFor(label: string, cond: () => boolean) {
+    for (let i = 0; i < 100; i++) {
+        if (cond()) return
+        await delay(10)
+    }
+    throw new Error(`timeout: ${label}`)
+}
+
+const env = (seq: number, path: PropertyKey[], value: any): PatchEnvelope =>
+    ({seq, ts: seq, event: [{path, value, exists: value !== undefined}]})
+const root = (seq: number, value: any) => env(seq, [], value)
+
+type World = {n: number, tag?: string}
+
+// lossy transport wrapper: drops pushes while `offline` is true — the client's
+// next successful delivery gets the {seq} verdict and repairs the gap
+function makeLossyRemote(journal: ReturnType<typeof createPatchRelayJournal>, account: string) {
+    const state = {offline: false, dropped: 0}
+    const remote: PeerRemote = {
+        signal: {send: async () => false, signals: {on: () => () => {}}},
+        publish: (e: PatchEnvelope) => {
+            if (state.offline) { state.dropped++; return true }
+            return journal.push(e)
+        },
+        peers: {[account]: journal.remote as any},
+    }
+    return {remote, state}
+}
+
+async function main() {
+    console.log('\n[peer-repair] gap matrix on the relay journal')
+    {
+        const j = createPatchRelayJournal({history: 16})
+        ok(j.push(env(0, ['n'], 1)) != true && json(j.push(env(0, ['n'], 1))) == json({seq: -1}),
+            'folding journal refuses a non-root FIRST envelope (partial-state lie) with repair coord -1')
+        ok(j.push(root(0, {n: 1})) == true, 'root first envelope accepted')
+        ok(j.push(env(1, ['n'], 2)) == true && j.push(env(2, ['n'], 3)) == true, 'contiguous envelopes accepted')
+        ok(j.push(env(2, ['n'], 99)) == true && j.seq() == 2 && j.snapshot().n == 3,
+            'duplicate is an idempotent no-op (reconnect overlap)')
+        ok(json(j.push(env(5, ['n'], 6))) == json({seq: 2}), 'non-root gap rejected WITH the repair coordinate')
+        ok(j.seq() == 2 && j.snapshot().n == 3, 'rejected gap does not corrupt the fold')
+        ok(j.push(root(7, {n: 7})) == true && j.seq() == 7 && j.snapshot().n == 7,
+            'root patch with a gap = legitimate reset point (keyframe repair / owner restart)')
+        ok(j.push(root(3, {n: 3})) == true && j.seq() == 3,
+            'root patch with a LOWER seq = owner restart reset')
+        ok(json(j.remote.keyframe()?.event[0].value) == json({n: 3}), 'folded keyframe stays truthful throughout')
+    }
+
+    console.log('\n[peer-repair] sacred journal: never invents, strict contiguity')
+    {
+        const j = createPatchRelayJournal({history: 2, gap: 'sacred'})
+        ok(j.push(root(0, {n: 0})) == true && j.push(env(1, ['n'], 1)) == true, 'sacred accepts a contiguous line')
+        ok(json(j.push(root(5, {n: 5}))) == json({seq: 1}), 'sacred rejects even a ROOT patch with a gap (no reset semantics)')
+        ok(j.remote.keyframe() == null, 'sacred never folds a keyframe')
+        j.push(env(2, ['n'], 2)); j.push(env(3, ['n'], 3)) // history 2 -> seq 0,1 evicted
+        let threw = false
+        try { j.remote.frame!(0) } catch { threw = true }
+        ok(threw, 'sacred frame() on an evicted tail THROWS (loud, never a silent seq jump)')
+        ok(json(j.remote.since(1)?.map(e => e.seq)) == json([2, 3]), 'covered tail is still served exactly')
+    }
+
+    console.log('\n[peer-repair] tail repair: lossless catch-up after an offline window')
+    {
+        const j = createPatchRelayJournal({history: 64})
+        const net = makeLossyRemote(j, 'a')
+        const errors: unknown[] = []
+        const a = createPeerClient<World>({
+            remote: net.remote, account: 'a', initial: {n: 0},
+            repair: 'tail', drain: 'micro', onPublishError: e => errors.push(e),
+        })
+        await waitFor('warmup', () => j.seq() >= 0)
+
+        a.store.state.n = 1
+        await flushReactive(a.store.state)
+        await waitFor('live publish', () => j.snapshot().n == 1)
+
+        net.state.offline = true
+        a.store.state.n = 2
+        a.store.state.tag = 'missed'
+        await flushReactive(a.store.state)
+        a.store.state.n = 3
+        await flushReactive(a.store.state)
+        await delay(20)
+        net.state.offline = false
+        ok(net.state.dropped >= 2 && j.snapshot().n == 1, 'offline window: relay is behind, fold untouched')
+
+        a.store.state.n = 4
+        await flushReactive(a.store.state)
+        await waitFor('tail repair', () => j.snapshot().n == 4)
+        ok(j.snapshot().tag == 'missed', 'tail repair delivered the MISSED envelopes verbatim (lossless)')
+        ok(json(j.snapshot()) == json(a.store.snapshot()), 'relay converged with the owner')
+        // ring integrity: a late joiner can fold the line from any covered coordinate
+        const late = createStore<World>({n: -1}, {drain: 'micro'})
+        const sub = syncStoreReplay(late, j.remote)
+        await sub.ready
+        ok(json(late.state) == json(a.store.snapshot()), 'late joiner folds a truthful state after repair')
+        ok(errors.length == 0, 'no publish errors on the happy repair path')
+        sub(); a.close()
+    }
+
+    console.log('\n[peer-repair] keyframe repair: cheap reset for ephemeral state')
+    {
+        const j = createPatchRelayJournal({history: 64})
+        const net = makeLossyRemote(j, 'a')
+        const a = createPeerClient<World>({
+            remote: net.remote, account: 'a', initial: {n: 0},
+            repair: 'keyframe', drain: 'micro',
+        })
+        await waitFor('warmup', () => j.seq() >= 0)
+        net.state.offline = true
+        a.store.state.n = 100
+        await flushReactive(a.store.state)
+        await delay(20)
+        net.state.offline = false
+        a.store.state.n = 101
+        await flushReactive(a.store.state)
+        await waitFor('keyframe repair', () => j.snapshot().n == 101)
+        ok(json(j.snapshot()) == json(a.store.snapshot()), 'keyframe repair resets the relay to current state')
+        a.close()
+    }
+
+    console.log('\n[peer-repair] sacred + local eviction: loud publisher fault, journal stays truthful')
+    {
+        const j = createPatchRelayJournal({history: 64, gap: 'sacred'})
+        const net = makeLossyRemote(j, 'a')
+        const errors: unknown[] = []
+        const a = createPeerClient<World, 'sacred'>({
+            remote: net.remote, account: 'a', initial: {n: 0},
+            journal: 'sacred', repair: 'tail', history: 2, // tiny local journal -> eviction
+            drain: 'micro', onPublishError: e => errors.push(e),
+        })
+        await waitFor('warmup', () => j.seq() >= 0)
+        const seqBefore = j.seq()
+        net.state.offline = true
+        for (let i = 1; i <= 6; i++) { a.store.state.n = i; await flushReactive(a.store.state) }
+        net.state.offline = false
+        a.store.state.n = 7
+        await flushReactive(a.store.state)
+        await waitFor('sacred repair failure surfaces', () => errors.length > 0)
+        ok(String(errors[0]).includes('unrepairable'), `publisher fault is loud: ${String(errors[0]).slice(0, 90)}`)
+        ok(j.seq() == seqBefore, 'sacred journal stayed truthful (nothing invented, nothing gapped)')
+        a.close()
+    }
+
+    console.log('\n[peer-repair] resync(): repair without waiting for the next write')
+    {
+        const j = createPatchRelayJournal({history: 64})
+        const net = makeLossyRemote(j, 'a')
+        const a = createPeerClient<World>({remote: net.remote, account: 'a', initial: {n: 0}, drain: 'micro'})
+        await waitFor('warmup', () => j.seq() >= 0)
+        net.state.offline = true
+        a.store.state.n = 5
+        a.store.state.tag = 'silent'
+        await flushReactive(a.store.state)
+        await delay(20)
+        net.state.offline = false
+        ok(j.snapshot().n == 0, 'relay is behind and no further writes are coming')
+        await a.resync()
+        ok(json(j.snapshot()) == json(a.store.snapshot()) && j.snapshot().tag == 'silent',
+            'resync() repaired the journal without a new write')
+        a.close()
+    }
+
+    console.log(fails ? `\n${fails} FAILED` : '\nall passed')
+    if (fails) process.exit(1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })

package/doc/changes/1.0.63.md

@@ -1,8 +0,0 @@
-# 1.0.63
-
-- Add `Observe.createStoreManager` and `Observe.managedStore` resource builders for declarative mirror/replay/offline store startup.
-- Add manager planning with priority, tags, usage scoring, `large`, and `explicitOnly` gates.
-- Add manager lifecycle helpers: `start`, `startPlanned`, `stop`, `stopAll`, `get`, `touch`, `usage`, `statusListen`, and typed `handles`.
-- Rename public-facing Observe oracle folder from `observable2` to `observe` and make `Listen.ts` / `reactive.ts` the canonical source files, leaving numbered files as compatibility shims.
-- Update brief and extended API docs for the store manager and current naming.
-- Publish package `wenay-common2@1.0.63`.

package/doc/changes/1.0.64.md

@@ -1,10 +0,0 @@
-# 1.0.64
-
-- Make `README.md` navigation-only and point it to the brief docs, rare docs, naming migrations, recent changes, and project rules.
-- Add the `doc/changes/` release-note catalog rule to `CLAUDE.md`: one file per published version, commit-style summary, latest 10 versions only.
-- Add the recent changes catalog README and keep the current release notes under `doc/changes/`.
-- Package documentation, `CLAUDE.md`, and `rpc.md` into `dist` so README links work in the npm package.
-- Restore the `noStrict` dynamic-map contract in the extended docs after removing a duplicated store-manager block.
-- Move regression oracles to the canonical `observe/reactive` names after the `observable2/reactive2` rename.
-- Normalize npm repository metadata.
-- Publish package `wenay-common2@1.0.64`.