@superhero/eventflow-hub 4.0.2

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Erik Landvall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# Eventflow Hub
+
+Eventflow Hub is a central component of the Eventflow system that manages mTLS-secured connections between spokes and peer hubs, facilitating message publishing, subscription handling, and event scheduling.
+
+> [!NOTE]
+> This module is still under development and in activing testing.
+
+## Features
+
+- **TLS-Secured Communication:** Ensures secure connections using certificates for both server and client communication.
+- **Event Management:** Publishes and broadcasts events to subscribed spokes and peer hubs.
+- **Subscriber Management:** Tracks spokes subscribing to specific events.
+- **Scheduled Events:** Executes scheduled tasks with error handling and persistence.
+- **Scalable Architecture:** Supports multi-hub communication for distributed systems.
+
+## Testing
+
+Run the test suite using:
+
+```bash
+npm run test-build
+npm test
+```
+
+### Test Coverage
+
+```
+▶ @superhero/eventflow-hub
+  ▶ Lifecycle
+    ✔ Can initialize EventflowHub correctly (239.24859ms)
+  ✔ Lifecycle (240.434564ms)
+
+  ▶ Connections and Communication
+    ▶ Handles spoke connections
+      ✔ Broadcasts peer hub online event (6422.456966ms)
+    ✔ Handles spoke connections (12880.167996ms)
+  ✔ Connections and Communication (12880.634724ms)
+✔ @superhero/eventflow-hub/hub (13122.085188ms)
+
+▶ @superhero/eventflow-hub/manager/spokes
+  ✔ Add and retrieve all sockets (3.451128ms)
+  ✔ Delete a socket (0.227951ms)
+  ✔ Destroy all sockets (0.352411ms)
+  ✔ Handle deleting non-existent socket gracefully (0.275818ms)
+  ✔ Return empty array if no sockets exist (0.165647ms)
+✔ @superhero/eventflow-hub/manager/spokes (6.103143ms)
+
+▶ @superhero/eventflow-hub/manager/subscribers
+  ✔ Add and retrieve subscribers (2.384233ms)
+  ✔ Handle wildcard subscribers (0.308446ms)
+  ✔ Return empty array if no subscribers exist (0.152296ms)
+  ✔ Delete a subscriber and clean up empty structures (0.243432ms)
+  ✔ Clean up domain and event mappings after deletion (0.226052ms)
+  ✔ Not throw errors when deleting non-existent subscribers (0.362547ms)
+✔ @superhero/eventflow-hub/manager/subscribers (5.36466ms)
+
+tests 14
+suites 5
+pass 14
+
+-------------------------------------------------------------------------------------------------------------------------
+file                    | line % | branch % | funcs % | uncovered lines
+-------------------------------------------------------------------------------------------------------------------------
+config.js               | 100.00 |   100.00 |  100.00 | 
+index.js                |  73.36 |    74.42 |   74.07 | 40-43 134-136 140-144 147-151 173-175 244-247 253-256 259-262 26…
+index.test.js           | 100.00 |   100.00 |  100.00 | 
+manager                 |        |          |         | 
+ spokes.js              | 100.00 |   100.00 |  100.00 | 
+ spokes.test.js         | 100.00 |   100.00 |  100.00 | 
+ subscribers.js         |  78.21 |   100.00 |   83.33 | 61-77
+ subscribers.test.js    | 100.00 |   100.00 |  100.00 | 
+-------------------------------------------------------------------------------------------------------------------------
+all files               |  84.20 |    88.89 |   87.88 | 
+-------------------------------------------------------------------------------------------------------------------------
+```
+
+## License
+
+This project is licensed under the MIT License.
+
+## Contributing
+
+Feel free to submit issues or pull requests for improvements or additional features.

package/config.js

@@ -0,0 +1,38 @@
+/**
+ * @memberof Eventflow.Hub
+ */
+export default
+{
+  dependency : { '@superhero/eventflow-db'  : '@superhero/eventflow-db' },
+  bootstrap  : { '@superhero/eventflow-hub' : 'eventflow/hub' },
+  locator    : { '@superhero/eventflow-hub' : './index.js' },
+  eventflow  :
+  {
+    hub:
+    {
+      NAME                      : process.env.EVENTFLOW_HUB_NAME                      ?? 'EVENTFLOW-HUB',
+      SIGNAL_QUIT               : process.env.EVENTFLOW_HUB_SIGNAL_QUIT               ?? 'SIGTERM',
+      INTERNAL_IP               : process.env.EVENTFLOW_HUB_INTERNAL_IP               ?? '127.0.0.1',
+      INTERNAL_PORT             : process.env.EVENTFLOW_HUB_INTERNAL_PORT             ?? 50001,
+      EXTERNAL_IP               : process.env.EVENTFLOW_HUB_EXTERNAL_IP               ?? '127.0.0.1',
+      EXTERNAL_PORT             : process.env.EVENTFLOW_HUB_EXTERNAL_PORT             ?? 50001,
+      TCP_SOCKET_SERVER_OPTIONS : process.env.EVENTFLOW_HUB_TCP_SOCKET_SERVER_OPTIONS ?? {},
+      TCP_SOCKET_CLIENT_OPTIONS : process.env.EVENTFLOW_HUB_TCP_SOCKET_CLIENT_OPTIONS ?? {},
+      KEEP_ALIVE_INTERVAL       : process.env.EVENTFLOW_HUB_KEEP_ALIVE_INTERVAL       ?? 60e3,
+      PEER_HUB_ONLINE_TIMEOUT   : process.env.EVENTFLOW_HUB_PEER_HUB_ONLINE_TIMEOUT   ?? 5e3,
+      SPOKE_ID_MESSAGE_TIMEOUT  : process.env.EVENTFLOW_HUB_SPOKE_ID_MESSAGE_TIMEOUT  ?? 5e3,
+      SHEDULED_INTERVAL_DELAY   : process.env.EVENTFLOW_HUB_SHEDULED_INTERVAL_DELAY   ?? 1e3,
+
+      certificates:
+      {
+        CERT_ALGORITHM              : process.env.EVENTFLOW_HUB_CERT_ALGORITHM,
+        CERT_HASH                   : process.env.EVENTFLOW_HUB_CERT_HASH,
+        CERT_PASS_CIPHER            : process.env.EVENTFLOW_HUB_CERT_PASS_CIPHER,
+        CERT_PASS_ENCRYPTION_KEY    : process.env.EVENTFLOW_HUB_CERT_PASS_ENCRYPTION_KEY,
+        CERT_PASS_PBKDF2_HASH       : process.env.EVENTFLOW_HUB_CERT_PASS_PBKDF2_HASH,
+        CERT_PASS_PBKDF2_BYTES      : process.env.EVENTFLOW_HUB_CERT_PASS_PBKDF2_BYTES,
+        CERT_PASS_PBKDF2_ITERATIONS : process.env.EVENTFLOW_HUB_CERT_PASS_PBKDF2_ITERATIONS,
+      }
+    }
+  }
+}

package/index.js

@@ -0,0 +1,428 @@
+import tls                  from 'node:tls'
+import deepmerge            from '@superhero/deep/merge'
+import Channel              from '@superhero/tcp-record-channel'
+import IdNameGenerator      from '@superhero/id-name-generator'
+import Log                  from '@superhero/log'
+import SpokesManager        from '@superhero/eventflow-hub/manager/spokes'
+import SubscribersManager   from '@superhero/eventflow-hub/manager/subscribers'
+import CertificatesManager  from '@superhero/eventflow-certificates'
+import { setInterval as asyncInterval } from 'node:timers/promises'
+
+export function locate(locator)
+{
+  const
+    config = locator('@superhero/config').find('eventflow/hub', {}),
+    db     = locator('@superhero/eventflow-db'),
+    hub    = new Hub(config, db)
+
+  return hub
+}
+
+/**
+ * @memberof Eventflow
+ */
+export default class Hub
+{
+  #hubID
+  channel = new Channel()
+
+  get hubID()
+  {
+    return this.#hubID
+  }
+
+  constructor(config, db)
+  {
+    if('string' !== typeof config.NAME
+    || 0 === config.NAME.length
+    || (/[^a-z0-9\-\.]/i).test(config.NAME))
+    {
+      const error = new Error(`invalid config.NAME (${config.NAME})`)
+      error.code  = 'E_EVENTFLOW_HUB_INVALID_CONFIG_NAME'
+      throw error
+    }
+
+    this.#hubID       = (new IdNameGenerator().generateId() + '.' + config.NAME).toUpperCase()
+    this.config       = config
+    this.db           = db
+    this.abortion     = new AbortController()
+    this.log          = new Log({ label: `[${config.NAME}]` })
+    this.certificates = new CertificatesManager(config.NAME, this.#hubID, config.certificates, db, this.log)
+    this.spokes       = new SpokesManager()
+    this.subscribers  = new SubscribersManager()
+
+    this.channel.on('record', this.#onRecord.bind(this))
+  }
+
+  async bootstrap()
+  {
+    await this.db.setupTableSchemas()
+    await this.#bootstrapServer()
+    setImmediate(this.#sheduledInterval.bind(this, this.config.SHEDULED_INTERVAL_DELAY))
+  }
+
+  async destroy()
+  {
+    this.abortion.abort()
+    this.server?.close()
+    this.spokes.destroy()
+    this.subscribers.destroy()
+    this.log.warn`hub has quit`
+    await this.db.updateHubToQuit(this.#hubID)
+    setImmediate(() => this.db.close())
+  }
+
+  #bootstrapServer()
+  {
+    return new Promise(async (accept, reject) =>
+    {
+      const conf = Object.assign({}, this.config.TCP_SOCKET_SERVER_OPTIONS)
+
+      conf.requestCert    = true
+      conf.pauseOnConnect = true
+      conf.SNICallback    = this.#serverSNICallback.bind(this)
+
+      this.server = this.channel.createTlsServer(conf, this.#onClientConnection.bind(this))
+      this.server.on('error', reject)
+      this.server.on('close', reject)
+      this.server.listen(this.config.INTERNAL_PORT, this.config.INTERNAL_IP, async () =>
+      {
+        this.server.off('error', reject)
+        this.server.off('close', reject)
+
+        this.server.on('error', this.#onServerError.bind(this))
+        this.server.on('close', this.#onServerClose.bind(this))
+
+        await this.#persistHubOnline()
+        await this.#broadcastHubOnlineToPeerHubs()
+
+        this.log.info`listen on ${this.config.INTERNAL_IP}:${this.config.INTERNAL_PORT}`
+
+        accept()
+      })
+    })
+  }
+
+  async #serverSNICallback(hostname, cb)
+  {
+    if(hostname !== this.#hubID)
+    {
+      const error = new Error('invalid hostname')
+      error.code  = 'E_EVENTFLOW_INVALID_HOSTNAME'
+      error.cause = `hostname ${hostname} mismatch with hub id ${this.#hubID}`
+      return cb(error)
+    }
+
+    try
+    {
+      const
+        root = await this.certificates.root,
+        ica  = await this.certificates.intermediate,
+        leaf = await this.certificates.leaf
+  
+      const ctx = tls.createSecureContext(
+      {
+        ca          : root.cert,
+        cert        : leaf.cert + ica.cert,
+        key         : leaf.key,
+        passphrase  : leaf.pass
+      })
+
+      cb(null, ctx)
+    }
+    catch(error)
+    {
+      return cb(error)
+    }
+  }
+
+  async #onServerError(error)
+  {
+    this.log.fail`server error [${error.code}] ${error.message}`
+    const message = `server error [${error.code}] ${error.message}`
+    await this.db.persistLog({ agent:this.#hubID, message, error })
+  }
+
+  async #onClientError(client, error)
+  {
+    this.log.fail`observed client error [${error.code}] ${error.message} in ${client.id}`
+    const message = `observed client error [${error.code}] ${error.message} in ${client.id}`
+    await this.db.persistLog({ agent:this.#hubID, message, error })
+  }
+
+  async #onServerClose()
+  {
+    this.log.warn`server closed`
+  }
+
+  async #persistHubOnline()
+  {
+    const
+      internal_ip   = this.config.INTERNAL_IP,
+      internal_port = this.config.INTERNAL_PORT,
+      external_ip   = this.config.EXTERNAL_IP,
+      external_port = this.config.EXTERNAL_PORT
+
+    await this.db.persistHub({ id:this.#hubID, internal_ip, internal_port, external_ip, external_port })
+  }
+
+  async #onClientConnection(client)
+  {
+    if(false === client.authorized)
+    {
+      this.log.warn`unauthorized client connection rejected`
+      return client.authorized = false
+    }
+
+    this.spokes.add(client)
+
+    client.id         = client.getPeerCertificate().subject.UID
+    client.authorized = true
+
+    client.on('close', this.#onClientDisconnected.bind(this, client))
+    client.on('error', this.#onClientError.bind(this, client))
+
+    client.setKeepAlive(true, this.config.KEEP_ALIVE_INTERVAL)
+    client.resume()
+
+    this.log.info`connected ${client.id}`
+    const message = `connected ${client.id}`
+    await this.db.persistLog({ agent:this.#hubID, message })
+  }
+
+  async #onClientDisconnected(client)
+  {
+    this.spokes.delete(client)
+    this.subscribers.deleteBySocket(client)
+    this.log.info`disconnected ${client.id}`
+    const message = `disconnected ${client.id}`
+    await this.db.persistLog({ agent:this.#hubID, message })
+  }
+
+  /**
+   * @see @superhero/tcp-record-channel
+   * @param {String[]} record The unit seperated record
+   * @param {node:tls.TLSSocket} client A spoke or peer hub client
+   */
+  async #onRecord([ event, ...args ], client)
+  {
+    switch(event)
+    {
+      case 'online'      : return this.#onPeerHubOnlineMessage    (client, ...args)
+      case 'publish'     : return this.#onSpokePublishMessage     (client, ...args)
+      case 'subscribe'   : return this.#onSpokeSubscribeMessage   (client, ...args)
+      case 'unsubscribe' : return this.#onSpokeUnsubscribeMessage (client, ...args)
+      // only recognize the above listed events
+      default: this.log.fail`observed invalid message ${event} from spoke ${client.id}`
+    }
+  }
+
+  /**
+   * Broadcasts the online status of a peer hub to all connected spokes of this hub.
+   * The intent is to inform all connected spokes that a peer hub is online so that 
+   * they can connect to that hub as well. Spokes are not expected to poll for online
+   * hubs, but rather rely on a reactional architecture.
+   * 
+   * @param {node:tls.TLSSocket} peerHub
+   * @param {string} peerHubID
+   * @param {string} peerHubIP 
+   * @param {string} peerHubPort
+   */
+  async #onPeerHubOnlineMessage(peerHub, peerHubID, peerHubIP, peerHubPort)
+  {
+    // prevent possible loop
+    if(peerHubID === this.#hubID)
+    {
+      return
+    }
+
+    try
+    {
+      this.channel.broadcast(this.spokes.all, [ 'online', peerHubID, peerHubIP, peerHubPort ])
+    }
+    catch(error)
+    {
+      this.log.fail`failed to broadcast peer hub ${peerHubID} online event [${error.code}] ${error.message}`
+      return
+    }
+
+    this.log.info`broadcasted peer hub ${peerHubID} › ${peerHubIP}:${peerHubPort} online event`
+  }
+
+  #onSpokeSubscribeMessage(spoke, domain, name)
+  {
+    this.subscribers.add(spoke, domain, name)
+    this.log.info`spoke ${spoke.id} subscribes to events: ${domain} › ${name}`
+  }
+
+  #onSpokeUnsubscribeMessage(spoke, domain, name)
+  {
+    this.subscribers.deleteBySocketAndDomainAndName(spoke, domain, name)
+    this.log.info`spoke ${spoke.id} unsubscribed to events: ${domain} › ${name}`
+  }
+
+  async #onSpokePublishMessage(spoke, domain, id, name, pid)
+  {
+    this.log.info`spoke ${spoke.id} published event ${id}: ${domain} › ${name} › ${pid}`
+    await this.#attemptToConsumeAndBroadcastPublishedMessage(domain, id, name, pid)
+  }
+
+  async #attemptToConsumeAndBroadcastPublishedMessage(domain, id, name, pid)
+  {
+    const consumed = await this.db.updateEventPublishedToConsumedByHub(domain, id, this.#hubID)
+
+    if(consumed)
+    {
+      this.log.info`consumed event ${id}: ${domain} › ${name} › ${pid}`
+      await this.#broadcastPublishedMessage(domain, id, name, pid)
+    }
+
+    return consumed
+  }
+
+  async #broadcastPublishedMessage(domain, id, name, pid)
+  {
+    const sockets = this.subscribers.get(domain, name)
+
+    if(sockets.length === 0)
+    {
+      this.log.warn`observed an orphan event ${id}: ${domain} › ${name} › ${pid}`
+      await this.db.updateEventPublishedToOrphan(domain, id)
+    }
+    else
+    {
+      try
+      {
+        this.channel.broadcast(sockets, [ 'publish', domain, id, name, pid ])
+      }
+      catch(error)
+      {
+        this.log.fail`failed to broadcast event ${id}: ${domain} › ${name} › ${pid} [${error.code}] ${error.message}`
+        return
+      }
+
+      this.log.info`broadcasted event ${id}: ${domain} › ${name} › ${pid}`
+    }
+  }
+
+  async #broadcastHubOnlineToPeerHubs()
+  {
+    for(const { id:hubID, external_ip:ip, external_port:port } of await this.db.readOnlineHubs())
+    {
+      // prevent possible loop
+      if(hubID === this.#hubID
+      || this.abortion.signal.aborted)
+      {
+        continue
+      }
+
+      try
+      {
+        await this.#transmitHubOnlineToPeerHub(hubID, ip, port)
+      }
+      catch(error)
+      {
+        this.log.fail`failed to connect to peer hub ${hubID} [${error.code}] ${error.message}`
+        const message = `failed to connect to peer hub ${hubID} [${error.code}] ${error.message}`
+        await this.db.persistLog({ agent:this.#hubID, message, error })
+      }
+    }
+  }
+
+  async #transmitHubOnlineToPeerHub(hubID, ip, port)
+  {
+    const
+      rootCA        = await this.certificates.root,
+      hubICA        = await this.certificates.intermediate,
+      hubLeaf       = await this.certificates.leaf,
+      ca            = rootCA.cert,
+      certChain     = hubLeaf.cert + hubICA.cert,
+      dynamicConfig = { servername:hubID, host:ip, port, ca, cert:certChain, key:hubLeaf.key, passphrase:hubLeaf.pass },
+      peerHubConfig = deepmerge(dynamicConfig, this.config.TCP_SOCKET_CLIENT_OPTIONS),
+      peerHub       = await this.channel.createTlsClient(peerHubConfig)
+
+    peerHub.id = peerHub.getPeerCertificate().subject.UID
+    this.channel.transmit(peerHub, [ 'online', this.#hubID, this.config.EXTERNAL_IP, this.config.EXTERNAL_PORT ])
+    this.log.info`broadcasted online status to peer hub ${peerHub.id}`
+    const message = `broadcasted online status to peer hub ${peerHub.id}`
+    await this.db.persistLog({ agent:this.#hubID, message })
+
+    peerHub.end()
+  }
+
+  /**
+   * Polls the database for scheduled events and attempts to execute them.
+   * TODO: This method should be refactored to use a more reactive approach.
+   * @param {number} delay interval in milliseconds
+   */
+  async #sheduledInterval(delay)
+  {
+    try
+    {
+      const
+        readScheduledEvents = this.db.readEventsScheduled.bind(this.db),
+        signal              = this.abortion.signal,
+        asyncIterator       = asyncInterval(delay, readScheduledEvents, { signal })
+
+      for await (const sheduledEvents of asyncIterator) 
+      {
+        for(const scheduledEvent of await sheduledEvents())
+        {
+          if(signal.aborted)
+          {
+            return
+          }
+
+          const { domain, id, name } = scheduledEvent
+          const executed = await this.db.updateEventScheduledExecuted(domain, id)
+    
+          if(executed === false)
+          {
+            continue
+          }
+
+          let consumed
+  
+          try 
+          {
+            this.log.info`executed scheduled event ${id}: ${domain} › ${name}`
+            consumed = await this.#attemptToConsumeAndBroadcastPublishedMessage(domain, id, name)
+          }
+          catch (error)
+          {
+            this.log.fail`failed to execute scheduled event ${id}: ${domain} › ${name} [${error.code}] ${error.message}`
+            const message = `failed to execute scheduled event ${id}: ${domain} › ${name} [${error.code}] ${error.message}`
+            await this.db.updateEventScheduledFailed(domain, id)
+            await this.db.persistLog({ agent:this.#hubID, message, error })
+            throw error
+          }
+  
+          if(consumed)
+          {
+            await this.db.updateEventScheduledSuccess(domain, id)
+          }
+          else
+          {
+            this.log.fail`failed to execute already consumed scheduled event ${id}: ${domain} › ${name}`
+            const message = `failed to execute already consumed scheduled event ${id}: ${domain} › ${name}`
+            await this.db.updateEventScheduledFailed(domain, id)
+            await this.db.persistLog({ agent:this.#hubID, message, error })
+          }
+        }
+      }
+    }
+    catch(error)
+    {
+      this.log.fail`failed to execute scheduled interval ${error.message} [${error.code}]`
+      const message = `failed to execute scheduled interval ${error.message} [${error.code}]`
+      await this.db.persistLog({ agent:this.#hubID, message, error })
+    }
+    finally
+    {
+      if(this.abortion.signal.aborted === false)
+      {
+        setImmediate(this.#sheduledInterval.bind(this, delay))
+      }
+    }
+  }
+}

package/index.test.js

@@ -0,0 +1,110 @@
+import assert  from 'node:assert'
+import util    from 'node:util'
+import Config  from '@superhero/config'
+import Locator from '@superhero/locator'
+import Channel from '@superhero/tcp-record-channel'
+import { suite, test, beforeEach, afterEach } from 'node:test'
+
+util.inspect.defaultOptions.depth = 5
+
+suite('@superhero/eventflow-hub', () => 
+{
+  let locator, hub
+
+  beforeEach(async () => 
+  {
+    if(beforeEach.skip) return
+    locator = new Locator()
+    locator.log.config.mute = true
+    const config = new Config()
+    await config.add('@superhero/eventflow-db')
+    await config.add('./config.js')
+    config.assign({ eventflow: { hub: { certificates: { CERT_PASS_ENCRYPTION_KEY: 'encryptionKey123' }}}})
+    locator.set('@superhero/config', config)
+    await locator.eagerload('@superhero/eventflow-db')
+    await locator.eagerload(config.find('locator'))
+    hub = locator('@superhero/eventflow-hub')
+    hub.log.config.mute = true
+    await hub.bootstrap()
+  })
+
+  afterEach(async () => 
+  {
+    if(afterEach.skip) return
+    await locator.destroy()
+    locator.clear()
+  })
+
+  suite('Lifecycle', () => 
+  {
+    test('Can initialize EventflowHub correctly', () => 
+    {
+      assert.strictEqual(hub.config.NAME, 'EVENTFLOW-HUB')
+      assert.ok(hub.channel)
+      assert.ok(hub.certificates)
+      assert.ok(hub.spokes)
+      assert.ok(hub.subscribers)
+      assert.strictEqual(hub.config.INTERNAL_IP, '127.0.0.1')
+      assert.strictEqual(hub.config.INTERNAL_PORT, 50001)
+    })
+  })
+
+  suite('Connections and Communication', () => 
+  {
+    test('Handles spoke connections', async (sub) => 
+    {
+      assert.equal(hub.spokes.all.length, 0)
+
+      const 
+        root    = await hub.certificates.root,
+        ica     = await hub.certificates.intermediate,
+        leaf    = await hub.certificates.leaf,
+        chain   = leaf.cert + ica.cert,
+        host    = hub.config.INTERNAL_IP, 
+        port    = hub.config.INTERNAL_PORT,
+        config  = { servername:hub.hubID, host, port, cert:chain, key:leaf.key, ca:root.cert, passphrase:leaf.pass },
+        channel = new Channel(),
+        spoke   = await channel.createTlsClient(config)
+
+      assert.ok(hub.spokes.all.length)
+
+      beforeEach.skip = true
+      afterEach.skip  = true
+
+      await sub.test('Broadcasts peer hub online event', async () => await new Promise(async (accept) => 
+      {
+        channel.on('record', ([ type, id ,, port ]) => 'online'   === type 
+                                                    && hub2.hubID === id
+                                                    && '50002'    === port 
+                                                    && hub2.destroy().then(accept))
+
+        const 
+          locator2  = new Locator(),
+          config2   = new Config()
+
+        locator2.log.config.mute = true
+        await config2.add('@superhero/eventflow-db')
+        await config2.add('./config.js')
+        config2.assign(
+        { eventflow:
+          { hub:
+            { INTERNAL_PORT:50002,
+              EXTERNAL_PORT:50002,
+              certificates:
+              { CERT_PASS_ENCRYPTION_KEY: 'encryptionKey123' }}}})
+
+        locator2.set('@superhero/config', config2)
+        await locator2.eagerload('@superhero/eventflow-db')
+        await locator2.eagerload(config2.find('locator'))
+        const hub2 = locator2('@superhero/eventflow-hub')
+        hub2.log.config.mute = true
+        await hub2.bootstrap()
+      }))
+
+      beforeEach.skip = false
+      afterEach.skip  = false
+
+      await new Promise((accept) => spoke.end(accept))
+    })
+  })
+})

package/manager/spokes.js

@@ -0,0 +1,31 @@
+/**
+ * Manage spoke sockets.
+ * @memberof Eventflow.Hub
+ */
+export default class SpokesManager
+{
+  #set = new Set
+
+  destroy()
+  {
+    for(const socket of this.#set.values())
+    {
+      socket.end()
+    }
+  }
+
+  add(socket)
+  {
+    this.#set.add(socket)
+  }
+
+  get all()
+  {
+    return [...this.#set]
+  }
+
+  delete(socket)
+  {
+    this.#set.delete(socket)
+  }
+}

package/manager/spokes.test.js

@@ -0,0 +1,66 @@
+import assert           from 'node:assert/strict'
+import { suite, test }  from 'node:test'
+import SpokesManager    from '@superhero/eventflow-hub/manager/spokes'
+
+suite('@superhero/eventflow-hub/manager/spokes', () =>
+{
+  test('Add and retrieve all sockets', async () =>
+  {
+    const manager = new SpokesManager()
+    const socket1 = { id: 'socket1' }
+    const socket2 = { id: 'socket2' }
+
+    manager.add(socket1)
+    manager.add(socket2)
+
+    const allSockets = manager.all
+    assert.deepStrictEqual(allSockets, [socket1, socket2])
+  })
+
+  test('Delete a socket', async () =>
+  {
+    const manager = new SpokesManager()
+    const socket1 = { id: 'socket1' }
+    const socket2 = { id: 'socket2' }
+
+    manager.add(socket1)
+    manager.add(socket2)
+    manager.delete(socket1)
+
+    const allSockets = manager.all
+    assert.deepStrictEqual(allSockets, [socket2])
+  })
+
+  test('Destroy all sockets', async () =>
+  {
+    const manager = new SpokesManager()
+    const socket1 = { id: 'socket1', end: () => socket1.destroyed = true }
+    const socket2 = { id: 'socket2', end: () => socket2.destroyed = true }
+
+    manager.add(socket1)
+    manager.add(socket2)
+    manager.destroy()
+
+    assert.strictEqual(socket1.destroyed, true)
+    assert.strictEqual(socket2.destroyed, true)
+  })
+
+  test('Handle deleting non-existent socket gracefully', async () =>
+  {
+    const manager = new SpokesManager()
+    const socket = { id: 'socket1' }
+
+    assert.doesNotThrow(() =>
+    {
+      manager.delete(socket)
+    })
+  })
+
+  test('Return empty array if no sockets exist', async () =>
+  {
+    const manager = new SpokesManager()
+
+    const allSockets = manager.all
+    assert.deepStrictEqual(allSockets, [])
+  })
+})

package/manager/subscribers.js

@@ -0,0 +1,78 @@
+/**
+ * Manage subscribers to events by event domain and event name
+ * @memberof Eventflow.Hub
+ */
+export default class SubscribersManager
+{
+  #map = new Map
+
+  destroy()
+  {
+    this.#map.clear()
+  }
+
+  add(socket, domain, name)
+  {
+    if(false === this.#map.has(domain))
+    {
+      this.#map.set(domain, new Map)
+    }
+
+    if(false === this.#map.get(domain).has(name))
+    {
+      this.#map.get(domain).set(name, new Set)
+    }
+
+    this.#map.get(domain).get(name).add(socket)
+  }
+
+  get(domain, name)
+  {
+    const
+      domainMap   = this.#map.get(domain) || new Map,
+      namedSet    = domainMap.get(name)   || new Set,
+      wildcardSet = domainMap.get('*')    || new Set
+
+    return [...new Set([...namedSet, ...wildcardSet])]
+  }
+
+  deleteBySocket(socket)
+  {
+    for(const domain of this.#map.keys())
+    {
+      for(const name of this.#map.get(domain).keys())
+      {
+        this.#map.get(domain).get(name).delete(socket)
+
+        if(0 === this.#map.get(domain).get(name).size)
+        {
+          this.#map.get(domain).delete(name)
+
+          if(0 === this.#map.get(domain).size)
+          {
+            this.#map.delete(domain)
+          }
+        }
+      }
+    }
+  }
+
+  deleteBySocketAndDomainAndName(socket, domain, name)
+  {
+    const 
+      domainMap = this.#map.get(domain) || new Map,
+      namedSet  = domainMap.get(name)   || new Set
+
+    namedSet.delete(socket)
+
+    if(0 === namedSet.size)
+    {
+      domainMap.delete(name)
+
+      if(0 === domainMap.size)
+      {
+        this.#map.delete(domain)
+      }
+    }
+  }
+}

package/manager/subscribers.test.js

@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict'
+import { suite, test } from 'node:test'
+import SubscribersManager from '@superhero/eventflow-hub/manager/subscribers'
+
+suite('@superhero/eventflow-hub/manager/subscribers', () =>
+{
+  test('Add and retrieve subscribers', async () =>
+  {
+    const manager = new SubscribersManager()
+    const socket1 = { id: 'socket1' }
+    const socket2 = { id: 'socket2' }
+
+    manager.add(socket1, 'domain1', 'event1')
+    manager.add(socket2, 'domain1', 'event1')
+
+    const subscribers = manager.get('domain1', 'event1')
+    assert.deepStrictEqual(subscribers, [socket1, socket2])
+  })
+
+  test('Handle wildcard subscribers', async () =>
+  {
+    const manager = new SubscribersManager()
+    const socket1 = { id: 'socket1' }
+    const socket2 = { id: 'socket2' }
+
+    manager.add(socket1, 'domain1', '*')
+    manager.add(socket2, 'domain1', 'event1')
+
+    const subscribers = manager.get('domain1', 'event1')
+    assert.deepStrictEqual(subscribers, [socket2, socket1])
+  })
+
+  test('Return empty array if no subscribers exist', async () =>
+  {
+    const manager = new SubscribersManager()
+    const subscribers = manager.get('domain1', 'event1')
+    assert.deepStrictEqual(subscribers, [])
+  })
+
+  test('Delete a subscriber and clean up empty structures', async () =>
+  {
+    const manager = new SubscribersManager()
+    const socket1 = { id: 'socket1' }
+    const socket2 = { id: 'socket2' }
+
+    manager.add(socket1, 'domain1', 'event1')
+    manager.add(socket2, 'domain1', 'event1')
+
+    manager.deleteBySocket(socket1)
+
+    let subscribers = manager.get('domain1', 'event1')
+    assert.deepStrictEqual(subscribers, [socket2])
+
+    manager.deleteBySocket(socket2)
+    subscribers = manager.get('domain1', 'event1')
+    assert.deepStrictEqual(subscribers, [])
+  })
+
+  test('Clean up domain and event mappings after deletion', async () =>
+  {
+    const manager = new SubscribersManager()
+    const socket = { id: 'socket1' }
+
+    manager.add(socket, 'domain1', 'event1')
+    manager.deleteBySocket(socket)
+
+    assert.strictEqual(manager.get('domain1', 'event1').length, 0)
+    assert.strictEqual(manager.get('domain1', '*').length, 0)
+  })
+
+  test('Not throw errors when deleting non-existent subscribers', async () =>
+  {
+    const manager = new SubscribersManager()
+    const socket = { id: 'socket1' }
+
+    assert.doesNotThrow(() => manager.deleteBySocket(socket))
+  })
+})

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@superhero/eventflow-hub",
+  "version": "4.0.2",
+  "description": "Eventflow hub is the central server component in the eventflow ecosystem.",
+  "keywords": [
+    "eventflow",
+    "hub",
+    "bus"
+  ],
+  "main": "config.js",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./manager/*": "./manager/*.js"
+  },
+  "dependencies": {
+    "@superhero/eventflow-db": "^4.1.1",
+    "@superhero/id-name-generator": "^4.0.0",
+    "@superhero/log": "^4.0.0",
+    "@superhero/eventflow-certificates": "^4.0.2",
+    "@superhero/openssl": "^4.0.2",
+    "@superhero/tcp-record-channel": "^4.2.1",
+    "@superhero/deep": "^4.2.0"
+  },
+  "devDependencies": {
+    "@superhero/config": "^4.1.2",
+    "@superhero/locator": "^4.2.0"
+  },
+  "scripts": {
+    "test-build": "npm explore @superhero/eventflow-db -- npm run test-build",
+    "test-only": "node --test-only --trace-warnings --test --experimental-test-coverage",
+    "test": "node --test --experimental-test-coverage"
+  },
+  "author": {
+    "name": "Erik Landvall",
+    "email": "erik@landvall.se"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superhero/eventflow-hub.git"
+  }
+}