Updates

messaging-pubsub/hyper-p2p-topic-channel/docs/architecture.md

@@ -1,15 +1,22 @@
 # hyper-p2p-topic-channel architecture
 
-**Tier:** scaffold · **Category:** `messaging-pubsub`
+**Tier:** production · **Category:** `messaging-pubsub` · **Protocol:** `topic-channel/v1`
 
 ## Role
 
-Named topic channels.
+Named topic channels over Hyperswarm + Protomux: subscribe, publish, optional retained messages per channel.
+
+## Wire messages
+
+| type | Direction | Fields |
+|------|-----------|--------|
+| `subscribe` | gossip | `channel`, `peer` |
+| `unsubscribe` | gossip | `channel`, `peer` |
+| `publish` | gossip | `channel`, `payload`, `from`, `at`, `qos`, `retain` |
+| `retained-sync` | gossip | `channel`, `payload`, `from`, `at` |
 
 ## Composition
 
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with `hyper-p2p-gossip-mesh`, `hyper-p2p-topic-lease`, `hyper-p2p-subscription-lease`.
 
-## Holepunch boundary
-
-Inspiration: n/a
+Uses `../../_shared/p2p-bare.js` (`initModuleSwarm`, `gossipSend`).

messaging-pubsub/hyper-p2p-topic-channel/examples/basic.js

@@ -2,7 +2,11 @@ require('bare-process/global')
 const { HyperP2PTopicChannel } = require('../index.js')
 
 async function main () {
-  const m = new HyperP2PTopicChannel()
-  console.log('[scaffold]', m.getStats())
+  const ch = new HyperP2PTopicChannel({ retainMessages: true })
+  ch.subscribe('demo', (m) => console.log('[topic-channel]', m))
+  ch.publish('demo', { hello: 'wave9' }, { retain: true })
+  console.log(ch.getStats())
+  await ch.close()
 }
+
 main().catch(console.error)

messaging-pubsub/hyper-p2p-topic-channel/index.js

@@ -1,7 +1,8 @@
 require('bare-process/global')
 const EventEmitter = require('bare-events')
+const b4a = require('b4a')
 const { assertNonEmpty } = require('../../_shared/lib/errors.js')
-const { attachGossip, sendGossip } = require('../../_shared/storage-gossip-base.js')
+const { initModuleSwarm, gossipSend } = require('../../_shared/p2p-bare.js')
 
 const PROTOCOL = 'topic-channel/v1'
 
@@ -10,50 +11,138 @@ class HyperP2PTopicChannel extends EventEmitter {
     super()
     this.topic = opts.topic || null
     this.keyPair = opts.keyPair || require('hypercore-crypto').keyPair()
-    this._store = new Map()
-    this._stats = { ops: 0, gossipIn: 0, gossipOut: 0 }
+    this.peerHex = b4a.toString(this.keyPair.publicKey, 'hex')
+    this.retainMessages = opts.retainMessages !== false
+    this._subs = new Map()
+    this._retained = new Map()
+    this._stats = { published: 0, received: 0, subscriptions: 0, gossipIn: 0, gossipOut: 0 }
     this.swarm = null
+    this._peerMsgs = null
   }
 
-  put (key, value) {
-    assertNonEmpty(key, 'key')
-    this._store.set(key, value)
-    this._stats.ops++
-    sendGossip(this, { type: 'topic-channel-sync', key, value })
-    this.emit('update', { key, value })
+  subscribe (channel, handler) {
+    assertNonEmpty(channel, 'channel')
+    if (typeof handler !== 'function') throw new Error('handler must be a function')
+    this._subs.set(channel, handler)
+    this._stats.subscriptions++
+    if (this._peerMsgs) {
+      gossipSend(this, { type: 'subscribe', channel, peer: this.peerHex })
+      this._stats.gossipOut++
+    }
+    if (this.retainMessages && this._retained.has(channel)) {
+      const r = this._retained.get(channel)
+      handler({ channel, payload: r.payload, retained: true, from: r.from })
+    }
+    return () => this.unsubscribe(channel)
+  }
+
+  unsubscribe (channel) {
+    if (!this._subs.has(channel)) return false
+    this._subs.delete(channel)
+    if (this._peerMsgs) {
+      gossipSend(this, { type: 'unsubscribe', channel, peer: this.peerHex })
+      this._stats.gossipOut++
+    }
     return true
   }
 
-  get (key) { return this._store.get(key) }
-
-  delete (key) {
-    const ok = this._store.delete(key)
-    if (ok) sendGossip(this, { type: 'topic-channel-sync', key, value: null })
-    return ok
+  publish (channel, payload, opts = {}) {
+    assertNonEmpty(channel, 'channel')
+    const msg = {
+      type: 'publish',
+      channel,
+      payload,
+      from: this.peerHex,
+      at: Date.now(),
+      qos: opts.qos || 0,
+      retain: !!(opts.retain || this.retainMessages)
+    }
+    if (msg.retain) {
+      this._retained.set(channel, { payload, from: this.peerHex, at: msg.at })
+    }
+    this._deliverLocal(channel, payload, { from: this.peerHex, local: true })
+    if (this._peerMsgs) {
+      gossipSend(this, msg)
+      this._stats.gossipOut++
+    }
+    this._stats.published++
+    return msg
   }
 
-  entries () { return [...this._store.entries()] }
+  getRetained (channel) {
+    return this._retained.get(channel) || null
+  }
 
-  _onGossip (d) {
-    if (!d || d.type !== 'topic-channel-sync') return
+  _deliverLocal (channel, payload, meta) {
+    const handler = this._subs.get(channel)
+    if (handler) {
+      this._stats.received++
+      handler({ channel, payload, ...meta })
+    }
+    this.emit('message', { channel, payload, ...meta })
+  }
+
+  _onGossip (data, peerInfo) {
+    if (!data || !data.type) return
     this._stats.gossipIn++
-    if (d.key !== undefined) {
-      if (d.value === null) this._store.delete(d.key)
-      else this._store.set(d.key, d.value)
+    const from = data.from || (peerInfo && peerInfo.publicKey
+      ? b4a.toString(peerInfo.publicKey, 'hex')
+      : null)
+
+    if (data.type === 'publish' && data.channel) {
+      if (data.retain) {
+        this._retained.set(data.channel, {
+          payload: data.payload,
+          from,
+          at: data.at || Date.now()
+        })
+      }
+      this._deliverLocal(data.channel, data.payload, { from, qos: data.qos })
+    }
+
+    if (data.type === 'retained-sync' && data.channel && data.payload !== undefined) {
+      this._retained.set(data.channel, {
+        payload: data.payload,
+        from: data.from,
+        at: data.at || Date.now()
+      })
     }
   }
 
-  getStats () { return { ...this._stats, size: this._store.size, protocol: PROTOCOL } }
+  syncRetained (channel) {
+    assertNonEmpty(channel, 'channel')
+    const r = this._retained.get(channel)
+    if (!r || !this._peerMsgs) return false
+    gossipSend(this, { type: 'retained-sync', channel, payload: r.payload, from: r.from, at: r.at })
+    this._stats.gossipOut++
+    return true
+  }
+
+  getStats () {
+    return {
+      ...this._stats,
+      channels: this._subs.size,
+      retained: this._retained.size,
+      protocol: PROTOCOL
+    }
+  }
 
   async ready () {
     if (this.swarm || !this.topic) return this
-    await attachGossip(this, { keyPair: this.keyPair, topic: this.topic, protocol: PROTOCOL, onmessage: (d) => this._onGossip(d) })
+    await initModuleSwarm(this, {
+      keyPair: this.keyPair,
+      topic: this.topic,
+      protocol: PROTOCOL,
+      onmessage: (data, peerInfo) => this._onGossip(data, peerInfo)
+    })
     return this
   }
 
   async close () {
+    this._subs.clear()
     if (this.swarm) await this.swarm.destroy().catch(() => {})
     this.swarm = null
+    this.emit('closed')
   }
 }
 

messaging-pubsub/hyper-p2p-topic-channel/test/test.js

@@ -4,23 +4,45 @@ const { HyperP2PTopicChannel, PROTOCOL } = require('../index.js')
 
 test('exports', (t) => {
   t.ok(HyperP2PTopicChannel)
-  t.ok(PROTOCOL)
+  t.is(PROTOCOL, 'topic-channel/v1')
 })
 
-test('basic operation', async (t) => {
-  const m = new HyperP2PTopicChannel()
-  m.put('k', 1); t.is(m.get('k'), 1)
-  await m.close()
+test('subscribe and publish local', async (t) => {
+  const ch = new HyperP2PTopicChannel()
+  let got = null
+  ch.subscribe('news', (m) => { got = m })
+  ch.publish('news', { hello: 1 })
+  t.is(got.payload.hello, 1)
+  t.ok(got.local)
+  await ch.close()
+})
+
+test('retained message on subscribe', async (t) => {
+  const ch = new HyperP2PTopicChannel({ retainMessages: true })
+  ch.publish('alerts', { n: 1 }, { retain: true })
+  let got = null
+  ch.subscribe('alerts', (m) => { got = m })
+  t.is(got.payload.n, 1)
+  t.ok(got.retained)
+  await ch.close()
 })
 
 test('validation', async (t) => {
-  const m = new HyperP2PTopicChannel()
-  try { m.put(null, 1) } catch (e) { t.ok(e) }
-  await m.close()
+  const ch = new HyperP2PTopicChannel()
+  try {
+    ch.subscribe(null, () => {})
+    t.fail('expected throw')
+  } catch (e) {
+    t.ok(e instanceof Error)
+  }
+  await ch.close()
 })
 
 test('getStats', async (t) => {
-  const m = new HyperP2PTopicChannel()
-  t.ok(m.getStats().protocol)
-  await m.close()
+  const ch = new HyperP2PTopicChannel()
+  ch.publish('x', 1)
+  const s = ch.getStats()
+  t.is(s.protocol, 'topic-channel/v1')
+  t.is(s.published, 1)
+  await ch.close()
 })