@superhero/eventflow-spoke 4.0.0

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,233 @@
+# Eventflow Spoke
+
+Eventflow Spoke is the client component in the Eventflow ecosystem. It enables communication with hubs in the Eventflow network, allowing events to be published, consumed, subscribed to, and managed efficiently.
+
+## Features
+
+- Publish and subscribe to events.
+- Consume events with callback support.
+- Schedule events for future execution.
+- Wait for specific event outcomes.
+- Manage event logs and their states.
+- Communicates with hubs via secure TLS connections.
+
+## Installation
+
+Install the package using npm:
+
+```bash
+npm install @superhero/eventflow-spoke
+```
+
+## Usage
+
+### Initialization
+
+To initialize a Spoke instance:
+
+```javascript
+import { locate } from '@superhero/eventflow-spoke'
+
+const locator = new Locator()
+locator.set('@superhero/config', config)
+locator.eagerload('@superhero/eventflow-db')
+locator.eagerload(config.find('locator'))
+
+const spoke = locate(locator)
+await spoke.bootstrap()
+```
+
+### Publishing Events
+
+Publish an event to the Eventflow network:
+
+```javascript
+await spoke.publish(
+{
+  domain : 'example-domain',
+  name   : 'example-event',
+  pid    : 'example-pid',
+  data   : { key: 'value' }
+})
+```
+
+### Subscribing to Events
+
+Subscribe to specific events:
+
+```javascript
+await spoke.subscribe('example-domain', 'example-event', (event) => 
+{
+  console.log('Event received:', event)
+})
+```
+
+### Consuming Events
+
+Consume events with a callback:
+
+```javascript
+await spoke.consume('example-domain', 'example-event', (event) => 
+{
+  console.log('Consuming event:', event)
+})
+```
+
+### Waiting for Events
+
+Wait for a specific event outcome:
+
+```javascript
+const result = await spoke.wait('example-domain', 'example-pid', ['success', 'failed'], 10000)
+console.log('Event result:', result) // result = "success" or "failed"
+```
+
+### Scheduling Events
+
+Schedule an event to be executed at a later time:
+
+```javascript
+const scheduledTime = new Date(Date.now() + 60e3) // 1 minute from now
+await spoke.schedule(scheduledTime.toISOString(), 
+{
+  domain : 'example-domain',
+  name   : 'example-event',
+  pid    : 'example-pid',
+  data   : { key: 'value' }
+})
+```
+
+### Managing Event Logs
+
+#### Deleting Event Logs
+
+```javascript
+await spoke.deleteEventlog('example-domain', 'example-pid')
+```
+
+#### Reading Event Logs
+
+```javascript
+const events = await spoke.readEventlog('example-domain', 'example-pid')
+console.log('Event log:', events)
+```
+
+#### Reading Event Log State
+
+```javascript
+const state = await spoke.readEventlogState('example-domain', 'example-pid')
+console.log('Event log state:', state)
+```
+
+#### Composing Event Log State
+
+Manual composition of an eventlog state.
+
+```javascript
+const eventlog = 
+[
+  { data: { key1: 'value1' } },
+  { data: { key2: 'value2' } }
+]
+const state = spoke.composeEventlogState(eventlog)
+console.log('Composed state:', state)
+```
+
+## API Reference
+
+### Methods
+
+- `bootstrap()` - Initializes the spoke and connects to online hubs.
+- `destroy()` - Cleans up resources and disconnects from hubs.
+- `publish(event)` - Publishes an event.
+- `subscribe(domain, name, callback)` - Subscribes to a specific event.
+- `consume(domain, name, callback)` - Consumes a specific event.
+- `wait(domain, pid, eventNames, timeout)` - Waits for specific event outcomes.
+- `schedule(scheduled, event)` - Schedules an event for future execution.
+- `delete(eventID)` - Deletes an event by ID.
+- `deleteEventlog(domain, pid)` - Deletes an event log by domain and PID.
+- `read(eventID)` - Reads a specific event by ID.
+- `readEventlog(domain, pid)` - Reads all events for a domain and PID.
+- `readEventlogState(domain, pid)` - Reads the state of an event log.
+- `composeEventlogState(eventlog, size)` - Composes the state from a series of event logs.
+
+## Testing
+
+Run the test suite using:
+
+```bash
+npm run test-build
+npm test
+```
+
+### Test Coverage
+
+```
+▶ @superhero/eventflow-spoke
+  ▶ Lifecycle
+    ✔ Can initialize EventflowSpoke correctly (2.456916ms)
+  ✔ Lifecycle (3.674219ms)
+
+  ▶ Event Management
+    ✔ Subscribe (25.140172ms)
+    ✔ Consume (27.952574ms)
+    ✔ Wait for event (22.296145ms)
+    ✔ Schedule events (19.80376ms)
+    ✔ Delete event (13.513563ms)
+    ✔ Delete event log (18.829043ms)
+    ✔ Read event (7.612599ms)
+    ✔ Read event log (12.595032ms)
+    ✔ Read event log state (16.270482ms)
+    ✔ Compose event log state (0.206373ms)
+  ✔ Event Management (165.303115ms)
+✔ @superhero/eventflow-spoke (11673.269989ms)
+
+▶ @superhero/eventflow-spoke/manager/hubs
+  ✔ Add and retrieve sockets (1.926647ms)
+  ✔ Check size and has methods (0.425031ms)
+  ✔ Retrieve socket by IP and port (0.242366ms)
+  ✔ Delete a socket (0.22056ms)
+  ✔ Handle deleting non-existent socket gracefully (0.322003ms)
+  ✔ Return empty array if no sockets exist (0.194319ms)
+✔ @superhero/eventflow-spoke/manager/hubs (5.00919ms)
+
+▶ ListenersManager
+  ✔ Add and retrieve listeners by domain (1.716958ms)
+  ✔ Throw error when overwriting existing domain (1.135766ms)
+  ✔ Throw error when setting invalid listener instance (0.246827ms)
+  ✔ Lazy-load listener for non-existent domain (0.365931ms)
+  ✔ Delete listener by domain (0.345558ms)
+  ✔ Wildcard event emission (1.018036ms)
+  ✔ Emit specific event if listeners exist (0.530123ms)
+✔ ListenersManager (7.564682ms)
+
+tests 24
+suites 5
+pass 24
+
+-------------------------------------------------------------------------------------------------------------------------
+file                 | line % | branch % | funcs % | uncovered lines
+-------------------------------------------------------------------------------------------------------------------------
+config.js            | 100.00 |   100.00 |  100.00 | 
+consume.js           |  42.24 |   100.00 |   42.86 | 43-55 58-91 94-103 106-115
+index.js             |  86.26 |    80.43 |   88.89 | 34-36 44-47 100-104 111-112 148-151 179-183 205-210 219-231 287-29…
+index.test.js        | 100.00 |   100.00 |  100.00 | 
+manager              |        |          |         | 
+ hubs.js             | 100.00 |   100.00 |  100.00 | 
+ hubs.test.js        | 100.00 |   100.00 |  100.00 | 
+ listeners.js        | 100.00 |   100.00 |   88.89 | 
+ listeners.test.js   | 100.00 |   100.00 |  100.00 | 
+-------------------------------------------------------------------------------------------------------------------------
+all files            |  88.17 |    92.44 |   91.00 | 
+-------------------------------------------------------------------------------------------------------------------------
+```
+
+---
+
+## 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,36 @@
+/**
+ * @memberof Eventflow.Spoke
+ */
+export default
+{
+  dependency:
+  {
+    '@superhero/eventflow-db' : '@superhero/eventflow-db'
+  },
+  bootstrap:
+  {
+    '@superhero/eventflow-spoke'         : true,
+    '@superhero/eventflow-spoke/consume' : true
+  },
+  locator:
+  {
+    '@superhero/eventflow-spoke'         : './index.js',
+    '@superhero/eventflow-spoke/consume' : './consume.js'
+  },
+  eventflow:
+  {
+    spoke:
+    {
+      NAME                      : process.env.EVENTFLOW_SPOKE_NAME                   ?? 'EVENTFLOW-SPOKE',
+      CONNECT_TO_HUB_TIMEOUT    : process.env.EVENTFLOW_SPOKE_CONNECT_TO_HUB_TIMEOUT ?? 5e3,
+      KEEP_ALIVE_INTERVAL       : process.env.EVENTFLOW_SPOKE_KEEP_ALIVE_INTERVAL    ?? 60e3,
+      TCP_SOCKET_CLIENT_OPTIONS : process.env.EVENTFLOW_SPOKE_TCP_SOCKET_CLIENT_OPTIONS,
+
+      consume:
+      {
+        // '<event_domain>' : '*',
+        // '<event_domain>' : '<event_name>'
+      }
+    }
+  }
+}

package/consume.js

@@ -0,0 +1,116 @@
+export function locate(locator)
+{
+  const
+    spoke   = locator('@superhero/eventflow-spoke'),
+    consume = new ConsumeService(locator, spoke)
+
+  return consume
+}
+
+/**
+ * Attaches consumers on bootstrap according to a consumer map 
+ * routed to be handled by an aligned domain service method.
+ * 
+ * The event name is transformed into a camelcase method name
+ * by removing any non-alphanumeric characters and capitalizing
+ * the first letter of each word.
+ * 
+ * The consumer method is called with the event as an argument.
+ * 
+ * If the consumer method does not exist in the domain service,
+ * an error is composed and forwarded to the domain service error
+ * handler method, if it exists. Otherwise, the error is thrown.
+ * 
+ * If the domain service error handler method fails to handle the
+ * error, a new error describing the failure is composed and 
+ * thrown.
+ * 
+ * @memberof Eventflow.Spoke
+ */
+export default class ConsumeService
+{
+  #locator
+  #spoke
+  #lookupConsumerMap = new Map
+
+  constructor(locator, spoke)
+  {
+    this.#locator = locator
+    this.#spoke   = spoke
+  }
+
+  async bootstrap(consumerMap)
+  {
+    for(const domain in consumerMap)
+    {
+      const
+        service   = this.#locator.locate(domain),
+        consumer  = this.#consumer.bind(this, service)
+
+      for(const name of consumerMap[domain])
+      {
+        await this.#spoke.consume(domain, name, consumer)
+      }
+    }
+  }
+
+  async #consumer(service, event)
+  {
+    const consumer = this.#lazyloadConsumerName(event.name)
+
+    try
+    {
+      await service[consumer](event)
+    }
+    catch(reason)
+    {
+      const error     = new Error('consumer failed to handle event')
+      error.code      = 'E_EVENTFLOW_SPOKE_CONSUMER_FAILED'
+      error.cause     = reason
+      error.consumer  = consumer
+
+      if('function' === typeof service.onError)
+      {
+        try
+        {
+          await service.onError(error, event)
+        }
+        catch(onErrorReason)
+        {
+          const onErrorFailed = new Error('error handler failed')
+          onErrorFailed.code  = 'E_EVENTFLOW_SPOKE_CONSUMER_ERROR_HANDLER_FAILED'
+          onErrorFailed.cause = [ onErrorReason, error ]
+          throw onErrorFailed
+        }
+      }
+      else
+      {
+        throw error
+      }
+    }
+  }
+
+  #lazyloadConsumerName(eventName)
+  {
+    if(this.#lookupConsumerMap.has(eventName))
+    {
+      return this.#lookupConsumerMap.get(eventName)
+    }
+
+    const consumer = this.#composeConsumerName(eventName)
+    this.#lookupConsumerMap.set(eventName, consumer)
+    return consumer
+  }
+
+  #composeConsumerName(eventName)
+  {
+    const
+      observerLowercase  = eventName.toLowerCase(),
+      observerSeperated  = observerLowercase.replace(/\W+/g, ' '),
+      observerDivided    = observerSeperated.split(' '),
+      observerCamelcase  = observerDivided.map((s) => s[0].toUpperCase() + s.slice(1)),
+      observerName       = 'on' + observerCamelcase.join('')
+
+    return observerName
+  }
+}

package/index.js

@@ -0,0 +1,393 @@
+import { setTimeout as wait } from 'node:timers/promises'
+import Channel                from '@superhero/tcp-record-channel'
+import IdNameGenerator        from '@superhero/id-name-generator'
+import Log                    from '@superhero/log'
+import deepmerge              from '@superhero/deep/merge'
+import deepassign             from '@superhero/deep/assign'
+import CertificatesManager    from '@superhero/eventflow-certificates'
+import HubsManager            from '@superhero/eventflow-spoke/manager/hubs'
+import ListenersManager       from '@superhero/eventflow-spoke/manager/listeners'
+
+export function locate(locator)
+{
+  const
+    config = locator('@superhero/config').find('eventflow/spoke'),
+    db     = locator('@superhero/eventflow-db')
+
+  return new Spoke(config, db)
+}
+
+/**
+ * @memberof Eventflow
+ */
+export default class Spoke
+{
+  #spokeID
+
+  abortion      = new AbortController()
+  channel       = new Channel()
+  hubs          = new HubsManager()
+  subscriptions = new ListenersManager()
+  consumers     = new ListenersManager()
+
+  get spokeID()
+  {
+    return this.#spokeID
+  }
+
+  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.#spokeID     = (new IdNameGenerator().generateId() + '.' + config.NAME).toUpperCase()
+    this.config       = config
+    this.db           = db
+    this.log          = new Log({ label: `[${config.NAME}]` })
+    this.certificates = new CertificatesManager(config.NAME, this.#spokeID, config.certificates, db, this.log)
+
+    this.channel.on('record', this.#onRecord.bind(this))
+  }
+
+  async bootstrap()
+  {
+    await this.#pollOnlineHubs()
+  }
+
+  async destroy()
+  {
+    const reason = new Error('hub is destroyed')
+    reason.code  = 'E_EVENTFLOW_HUB_DESTROYED'
+
+    this.abortion.abort(reason)
+
+    for(const socket of this.hubs.all)
+    {
+      socket.end()
+    }
+
+    this.hubs.destroy()
+    this.log.warn`destroyed`
+    // setTimeout(() => this.db.close(), 5000)
+  }
+
+  async #pollOnlineHubs()
+  {
+    if(this.abortion.signal.aborted)
+    {
+      return
+    }
+
+    this.log.warn`polling for online hubs`
+
+    const hubs = await this.db.readOnlineHubs()
+
+    for(const hub of hubs)
+    {
+      await this.#connectToHub(hub)
+    }
+
+    if(this.hubs.size)
+    {
+      this.log.info`polling for online hubs completed`
+    }
+    else
+    {
+      await wait(3e3)
+      await this.#pollOnlineHubs()
+    }
+  }
+
+  async #connectToHub({ id:hubID, external_ip:hubIP, external_port:hubPort })
+  {
+    if(this.abortion.signal.aborted)
+    {
+      return
+    }
+
+    try
+    {
+      if(this.hubs.hasSocket(hubIP, hubPort))
+      {
+        const error = new Error('already connected to hub')
+        error.code  = 'E_EVENTFLOW_SPOKE_ALREADY_CONNECTED_TO_HUB'
+        reject(error)
+      }
+      else
+      {
+        this.log.info`connecting to hub ${hubID} › ${hubIP}:${hubPort}`
+
+        const
+          rootCA          = await this.certificates.root,
+          spokeICA        = await this.certificates.intermediate,
+          spokeLeaf       = await this.certificates.leaf,
+          ca              = rootCA.cert,
+          certChain       = spokeLeaf.cert + spokeICA.cert,
+          dynamicConfig   = { servername:hubID, host:hubIP, port:hubPort, ca, cert:certChain, key:spokeLeaf.key, passphrase:spokeLeaf.pass },
+          peerHubConfig   = deepmerge(dynamicConfig, this.config.TCP_SOCKET_CLIENT_OPTIONS),
+          hub             = await this.channel.createTlsClient(peerHubConfig)
+
+        hub.id = hubID
+        this.hubs.add(hubIP, hubPort, hub)
+        hub.on('close', this.#onHubDisconnected .bind(this, hub))
+        hub.on('error', this.#onHubError        .bind(this, hub))
+        this.log.info`connected to hub ${hubID} › ${hubIP}:${hubPort}`
+      }
+    }
+    catch(error)
+    {
+      switch(error.code)
+      {
+        case 'E_EVENTFLOW_SPOKE_ALREADY_CONNECTED_TO_HUB':
+        {
+          this.log.warn`already connected to hub ${hubID} › ${hubIP}:${hubPort}`
+          break
+        }
+        default:
+        {
+          const message = `failed to connect to hub ${hubID} › ${hubIP}:${hubPort} [${error.code}] ${error.message}`
+          this.log.fail`failed to connect to hub ${hubID} › ${hubIP}:${hubPort} [${error.code}] ${error.message}`
+          await this.db.persistLog({ agent:this.#spokeID, message, error })
+        }
+      }
+    }
+  }
+
+  /**
+   * @see @superhero/tcp-record-channel
+   * @param {String[]} record The unit seperated record
+   * @param {node:tls.TLSSocket} hub A hub tls socket
+   */
+  async #onRecord([ event, ...args ], hub)
+  {
+    switch(event)
+    {
+      case 'online'  : return this.#onHubOnlineMessage  (hub, ...args)
+      case 'publish' : return this.#onHubPublishMessage (hub, ...args)
+      // only recognize the above listed events
+      default: this.log.fail`observed invalid message ${event} from hub ${hub.id}`
+    }
+  }
+
+  async #onHubError(hub, error)
+  {
+    const message = `hub socket error ${hub.id} [${error.code}] ${error.message}`
+    this.log.fail`hub socket error ${hub.id} [${error.code}] ${error.message}`
+    await this.db.persistLog({ agent:this.#spokeID, message, error })
+  }
+
+  async #onHubDisconnected(hub)
+  {
+    this.hubs.delete(hub)
+
+    this.log.warn`disconnected from hub ${hub.id}`
+
+    if(this.hubs.size === 0)
+    {
+      await this.#pollOnlineHubs()
+    }
+  }
+
+  async #onHubPublishMessage(_, domain, id, name, pid)
+  {
+    this.subscriptions[domain].emit(name, { domain, id, name, pid })
+    await this.db.updateEventPublishedToConsumedBySpoke(id, this.#spokeID)
+    && this.consumers[domain].emit(name, { domain, id, name, pid })
+  }
+
+  async #onHubOnlineMessage(hub, hubID, hubIP, hubPort)
+  {
+    const message = `recieved hub online message ${hubID} › ${hubIP}:${hubPort} from hub ${hub.id}`
+    this.log.info`recieved hub online message ${hubID} › ${hubIP}:${hubPort} from hub ${hub.id}`
+    await this.db.persistLog({ agent:this.#spokeID, message })
+    await this.#connectToHub({ id:hubID, external_ip:hubIP, external_port:hubPort })
+  }
+
+  async #onConsumed(callback, event)
+  {
+    try
+    {
+      await callback(event)
+    }
+    catch(reason)
+    {
+      const error = new Error(`spoke callback failed to consume event ${event.domain} › ${event.name} › ${event.pid} › ${event.id}`)
+      error.code  = 'E_EVENTFLOW_SPOKE_CONSUME_OBSERVER_ERROR'
+      error.cause = reason
+      error.event = event
+
+      await this.db.updateEventPublishedToFailed(event.id)
+      const message = `failed to consume event ${event.domain} › ${event.name} › ${event.pid} › ${event.id}`
+      this.log.fail`failed to consume event ${event.domain} › ${event.name} › ${event.pid} › ${event.id}`
+      await this.db.persistLog({ agent:this.#spokeID, message, error })
+
+      return
+    }
+
+    await this.db.updateEventPublishedToSuccess(event.id)
+  }
+
+  #broadcast(type, ...args)
+  {
+    return this.channel.broadcast(this.hubs.all, [ type, ...args ])
+  }
+
+  consume(domain, name, callback)
+  {
+    this.consumers[domain].on(name, this.#onConsumed.bind(this, callback))
+    this.#broadcast('subscribe', domain, name)
+    this.log.info`consuming: ${domain} › ${name}`
+  }
+
+  subscribe(domain, name, callback)
+  {
+    this.subscriptions[domain].on(name, callback)
+    this.#broadcast('subscribe', domain, name)
+    this.log.info`subscribes to: ${domain} › ${name}`
+  }
+
+  unsubscribe(domain, name, callback)
+  {
+    this.subscriptions[domain].off(name, callback)
+
+    // If there are no listeners for the domain and name
+    // then broadcast an unsubscribe message.
+    if(0 === this.subscriptions[domain].listenerCount(name)
+    && 0 === this.consumers    [domain].listenerCount(name))
+    {
+      this.#broadcast('unsubscribe', domain, name)
+      delete this.subscriptions[domain]
+      delete this.consumers    [domain]
+    }
+  }
+
+  /**
+   * @param {string} domain
+   * @param {string} pid
+   * @param {string} [eventNames=["success","failed"]] string or array of event names that will be waited for
+   * @param {number} [timeout=10e3] milliseconds to wait before throwing a timeout error
+   * @throws E_EVENTFLOW_WAIT_TIMEOUT
+   */
+  wait(domain, pid, eventNames=['success','failed'], timeout=10e3)
+  {
+    if(false === Array.isArray(eventNames))
+    {
+      eventNames = [eventNames]
+    }
+
+    return new Promise(async (accept, reject) =>
+    {
+      const waitTimeout = setTimeout(() =>
+      {
+        const error = new Error(`wait timed out (${timeout}) for ${domain} › ${pid} › ${eventNames.join(' | ')}`)
+        error.code  = 'E_EVENTFLOW_WAIT_TIMEOUT'
+        reject(error)
+      }, timeout)
+
+      const subscriber = (event) =>
+      {
+        if(event.pid === pid)
+        {
+          Promise.allSettled(eventNames.map((name) => this.unsubscribe(domain, name, subscriber)))
+            .then(() => 
+            {
+              clearTimeout(waitTimeout)
+              accept(event)
+            })
+        }
+      }
+
+      await Promise.allSettled(eventNames.map((name) => this.subscribe(domain, name, subscriber)))
+    })
+  }
+
+  async publish(event)
+  {
+    const eventID = await this.persist(event)
+    await this.db.persistEventPublished({ event_id:eventID, publisher:this.#spokeID })
+    this.#broadcast('publish', event.domain, eventID, event.name, event.pid)
+    this.log.info`published event ${eventID} › ${event.domain} › ${event.name} › ${event.pid}`
+  }
+
+  async schedule(scheduled, event)
+  {
+    const scheduledDate = new Date(scheduled)
+
+    if(isNaN(scheduledDate))
+    {
+      const error = new Error(`invalid scheduled date ${scheduled}`)
+      error.code  = 'E_EVENTFLOW_SPOKE_SCHEDULE_INVALID_DATE'
+      error.event = event
+      throw error
+    }
+
+    scheduled = scheduledDate.toJSON().replace('T', ' ').substring(0, 19)
+
+    const eventID = await this.persist(event)
+    await this.db.persistEventPublished({ event_id:eventID, publisher:this.#spokeID })
+    await this.db.persistEventScheduled({ event_id:eventID, scheduled })
+    this.log.info`scheduled event ${eventID} › ${event.domain} › ${event.name} › ${scheduled}`
+  }
+
+  async persist(event)
+  {
+    return await this.db.persistEvent(event)
+  }
+
+  async delete(eventID)
+  {
+    return await this.db.deleteEvent(eventID)
+  }
+
+  async deleteEventlog(domain, pid)
+  {
+    return await this.db.deleteEventByDomainAndPid(domain, pid)
+  }
+
+  async read(eventID)
+  {
+    return await this.db.readEvent(eventID)
+  }
+
+  async readEventlog(domain, pid)
+  {
+    return await this.db.readEventsByDomainAndPid(domain, pid)
+  }
+
+  async readEventlogState(domain, pid)
+  {
+    const
+      eventlog = await this.readEventlog(domain, pid),
+      state    = this.composeEventlogState(eventlog)
+
+    return state
+  }
+
+  composeEventlogState(eventlog, size=10)
+  {
+    const
+      merge   = (start, end) => deepmerge(...eventlog.slice(start, end).map((event) => event.data)),
+      state   = {},
+      length  = eventlog.length
+
+    for(let i = size; i < length; i += size)
+    {
+      const segment = merge(i - size, i)
+      deepassign(state, segment)
+    }
+
+    const
+      spare   = length % size,
+      segment = merge(length - spare, length)
+
+    deepassign(state, segment)
+
+    return state
+  }
+}

package/index.test.js

@@ -0,0 +1,147 @@
+import assert  from 'node:assert/strict'
+import util    from 'node:util'
+import Config  from '@superhero/config'
+import Locator from '@superhero/locator'
+import { suite, test, before, after } from 'node:test'
+
+util.inspect.defaultOptions.depth = 5
+
+suite('@superhero/eventflow-spoke', () =>
+{
+  let locator, spoke, hub
+
+  before(async () =>
+  {
+    locator = new Locator()
+
+    const config = new Config()
+    await config.add('@superhero/eventflow-db')
+    await config.add('@superhero/eventflow-hub')
+    await config.add('./config.js')
+    config.assign({ eventflow: { spoke: { certificates: { CERT_PASS_ENCRYPTION_KEY: 'encryptionKey123' }}}})
+    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'))
+
+    spoke = locator('@superhero/eventflow-spoke')
+    hub   = locator('@superhero/eventflow-hub')
+
+    await hub.bootstrap()
+    await spoke.bootstrap()
+  })
+
+  after(async () =>
+  {
+    await locator.destroy()
+    locator.clear()
+  })
+
+  suite('Lifecycle', () => 
+  {
+    test('Can initialize EventflowSpoke correctly', () =>
+    {
+      assert.strictEqual(spoke.config.NAME, 'EVENTFLOW-SPOKE')
+      assert.ok(spoke.channel)
+      assert.ok(spoke.certificates)
+      assert.ok(spoke.hubs)
+      assert.ok(spoke.subscriptions)
+      assert.ok(spoke.consumers)
+    })
+  })
+
+  suite('Event Management', () => 
+  {
+    test('Subscribe', async () =>
+    {
+      await spoke.publish({ domain: 'domain1', name: 'event1', pid: 'pid1', data: {} })
+      const event = await new Promise((accept) => spoke.subscribe('domain1', 'event1', accept))
+      assert.ok(event)
+      assert.strictEqual(event.name, 'event1')
+    })
+
+    test('Consume', async () =>
+    {
+      await spoke.publish({ domain: 'domain1', name: 'event1', pid: 'pid1', data: {} })
+      const event = await new Promise((accept) => spoke.consume('domain1', 'event1', accept))
+      assert.ok(event)
+      assert.strictEqual(event.name, 'event1')
+    })
+
+    test('Wait for event', async () =>
+    {
+      const event = { domain: 'domain1', name: 'success', pid: 'pid1', data: {} }
+      await spoke.publish(event)
+      const waitPromise = await spoke.wait('domain1', 'pid1', 'success', 1e3)
+      const result = await waitPromise
+      assert.strictEqual(result.name, 'success')
+    })
+
+    test('Schedule events', async () =>
+    {
+      const scheduled = Date.now()
+      await spoke.schedule(scheduled, { domain: 'domain1', name: 'event1', pid: 'pid1', data: {} })
+    })
+
+    test('Delete event', async () =>
+    {
+      const id = await spoke.persist({ domain: 'domain1', name: 'event1', pid: 'pid1', data: {} })
+      await spoke.delete(id)
+      await assert.rejects(spoke.read(id), { code:'E_EVENTFLOW_DB_EVENT_NOT_FOUND' })
+    })
+
+    test('Delete event log', async () =>
+    {
+      await spoke.deleteEventlog('domain1', 'pid1')
+      await spoke.persist({ domain: 'domain1', name: 'event1', pid: 'pid1', data: {} })
+      const preEvents = await spoke.readEventlog('domain1', 'pid1')
+      assert.strictEqual(preEvents.length, 1)
+      await spoke.deleteEventlog('domain1', 'pid1')
+      const postEvents = await spoke.readEventlog('domain1', 'pid1')
+      assert.strictEqual(postEvents.length, 0)
+    })
+
+    test('Read event', async () =>
+    {
+      const 
+        id    = await spoke.persist({ domain: 'domain1', name: 'event1', pid: 'pid1', data: {} }),
+        event = await spoke.read(id)
+
+      assert.strictEqual(event.id, id)
+    })
+
+    test('Read event log', async () =>
+    {
+      await spoke.deleteEventlog('domain1', 'pid1')
+      await spoke.persist({ domain: 'domain1', name: 'event1', pid: 'pid1', data: {} })
+      const events = await spoke.readEventlog('domain1', 'pid1')
+      assert.strictEqual(events.length, 1)
+      assert.strictEqual(events[0].name, 'event1')
+    })
+
+    test('Read event log state', async () =>
+    {
+      await spoke.deleteEventlog('domain1', 'pid1')
+      await spoke.persist({ domain: 'domain1', name: 'event1', pid: 'pid1', data: { key1: 'value1' } })
+      await spoke.persist({ domain: 'domain1', name: 'event2', pid: 'pid1', data: { key2: 'value2' } })
+      const state = await spoke.readEventlogState('domain1', 'pid1')
+      assert.strictEqual(state.key1, 'value1')
+      assert.strictEqual(state.key2, 'value2')
+    })
+
+    test('Compose event log state', () =>
+    {
+      const eventlog = 
+      [
+        { data: { key1: 'value1' } },
+        { data: { key2: 'value2' } },
+        { data: { key3: 'value3' } }
+      ]
+      const state = spoke.composeEventlogState(eventlog)
+      assert.strictEqual(state.key1, 'value1')
+      assert.strictEqual(state.key2, 'value2')
+      assert.strictEqual(state.key3, 'value3')
+    })
+  })
+})

package/manager/hubs.js

@@ -0,0 +1,63 @@
+/**
+ * Manage eventflow hub sockets.
+ * @memberof Eventflow.Spoke
+ */
+export default class HubsManager
+{
+  #socketMap = new Map
+  #ipPortMap = new Map
+
+  destroy()
+  {
+    this.#socketMap.clear()
+    this.#ipPortMap.clear()
+  }
+
+  #serialize(ip, port)
+  {
+    return `${ip.replace(/^::ffff:/, '')}:${port}`
+  }
+
+  get size()
+  {
+    return this.#socketMap.size
+  }
+
+  add(ip, port, socket)
+  {
+    const ipPort = this.#serialize(ip, port)
+
+    this.#socketMap.set(socket, ipPort)
+    this.#ipPortMap.set(ipPort, socket)
+  }
+
+  hasSocket(ip, port)
+  {
+    const ipPort = this.#serialize(ip, port)
+    return this.#ipPortMap.has(ipPort)
+  }
+
+  has(socket)
+  {
+    return this.#socketMap.has(socket)
+  }
+
+  get all()
+  {
+    return [...this.#ipPortMap.values()]
+  }
+
+  getSocket(ip, port)
+  {
+    const ipPort = this.#serialize(ip, port)
+    return this.#ipPortMap.get(ipPort)
+  }
+
+  delete(socket)
+  {
+    const ipPort = this.#socketMap.get(socket)
+
+    this.#socketMap.delete(socket)
+    this.#ipPortMap.delete(ipPort)
+  }
+}

package/manager/hubs.test.js

@@ -0,0 +1,78 @@
+import assert           from 'node:assert/strict'
+import { suite, test }  from 'node:test'
+import HubsManager      from '@superhero/eventflow-spoke/manager/hubs'
+
+suite('@superhero/eventflow-spoke/manager/hubs', () =>
+{
+  test('Add and retrieve sockets', async () =>
+  {
+    const 
+      hubs    = new HubsManager(),
+      socket1 = {},
+      socket2 = {}
+
+    hubs.add('127.0.0.1', 8080, socket1)
+    hubs.add('127.0.0.1', 8081, socket2)
+
+    assert.deepStrictEqual(hubs.all, [socket1, socket2])
+  })
+
+  test('Check size and has methods', async () =>
+  {
+    const 
+      hubs    = new HubsManager(),
+      socket  = {}
+
+    hubs.add('192.168.1.1', 9090, socket)
+
+    assert.strictEqual(hubs.size, 1)
+    assert.strictEqual(hubs.has(socket), true)
+    assert.strictEqual(hubs.hasSocket('192.168.1.1', 9090), true)
+    assert.strictEqual(hubs.hasSocket('192.168.1.2', 9090), false)
+  })
+
+  test('Retrieve socket by IP and port', async () =>
+  {
+    const 
+      hubs    = new HubsManager(),
+      socket  = {}
+
+    hubs.add('10.0.0.1', 8080, socket)
+
+    const retrievedSocket = hubs.getSocket('10.0.0.1', 8080)
+    assert.strictEqual(retrievedSocket, socket)
+
+    const nonExistentSocket = hubs.getSocket('10.0.0.2', 8080)
+    assert.strictEqual(nonExistentSocket, undefined)
+  })
+
+  test('Delete a socket', async () =>
+  {
+    const 
+      hubs    = new HubsManager(),
+      socket1 = {},
+      socket2 = {}
+
+    hubs.add('172.16.0.1', 3000, socket1)
+    hubs.add('172.16.0.2', 3001, socket2)
+    hubs.delete(socket1)
+
+    assert.deepStrictEqual(hubs.all, [socket2])
+    assert.strictEqual(hubs.size, 1)
+  })
+
+  test('Handle deleting non-existent socket gracefully', async () =>
+  {
+    const 
+      hubs    = new HubsManager(),
+      socket  = {}
+
+    assert.doesNotThrow(() => hubs.delete(socket))
+  })
+
+  test('Return empty array if no sockets exist', async () =>
+  {
+    const hubs = new HubsManager()
+    assert.deepStrictEqual(hubs.all, [])
+  })
+})

package/manager/listeners.js

@@ -0,0 +1,72 @@
+import EventEmitter from 'node:events'
+
+/**
+ * A class that extends EventEmitter and emits events by name. If there are no listeners 
+ * for the event name, the event will be emitted to the wildcard event name '*'.
+ * 
+ * @memberof Eventflow.Spoke
+ */
+export class Listener extends EventEmitter
+{
+  emit(name, ...args)
+  {
+    return this.listenerCount(name)
+         ? super.emit(name, ...args)
+         : super.emit('*',  ...args)
+  }
+}
+
+/**
+ * Manage event emitters for listeners to events by domain and name.
+ * Each domain has it's own listener/event-emitter which is expected to emit events by name.
+ * 
+ * @memberof Eventflow.Spoke
+ */
+export default class ListenersManager
+{
+  static Listener = Listener
+
+  #map = new Map
+
+  constructor()
+  {
+    return new Proxy(this, 
+    {
+      set: (_, domain, listener) =>
+      {
+        if(this.#map.has(domain))
+        {
+          const error = new Error(`cannot overwrite an existing domain listener: ${domain}`)
+          error.code  = 'E_EVENTFLOW_LISTENERS_DOMAIN_ALREADY_EXISTS'
+          throw error
+        }
+
+        if(listener instanceof Listener)
+        {
+          this.#map.set(domain, listener)
+          return true
+        }
+        else
+        {
+          const error = new Error('can only set a listener that is of instance Listener')
+          error.code  = 'E_EVENTFLOW_LISTENERS_INVLAID_INSTANCE_OF_LISTENER'
+          throw error
+        }
+      },
+      get             : (target, domain) => this.#map.get(domain) ?? target.lazyload(domain),
+      has             : (_, domain) => this.#map.has(domain),
+      deleteProperty  : (_, domain) => this.#map.delete(domain)
+    })
+  }
+
+  lazyload(domain)
+  {
+    if(false === this.#map.has(domain))
+    {
+      const listener = new Listener()
+      this.#map.set(domain, listener)
+    }
+
+    return this.#map.get(domain)
+  }
+}

package/manager/listeners.test.js

@@ -0,0 +1,118 @@
+import assert           from 'node:assert/strict'
+import { suite, test }  from 'node:test'
+import ListenersManager from '@superhero/eventflow-spoke/manager/listeners'
+
+suite('ListenersManager', () =>
+{
+  test('Add and retrieve listeners by domain', async () =>
+  {
+    const 
+      manager   = new ListenersManager(),
+      domain1   = 'domain1',
+      domain2   = 'domain2',
+      listener1 = new ListenersManager.Listener(),
+      listener2 = new ListenersManager.Listener()
+
+    manager[domain1] = listener1
+    manager[domain2] = listener2
+
+    assert.strictEqual(manager[domain1], listener1)
+    assert.strictEqual(manager[domain2], listener2)
+  })
+
+  test('Throw error when overwriting existing domain', async () =>
+  {
+    const 
+      manager  = new ListenersManager(),
+      domain   = 'domain1',
+      listener = new ListenersManager.Listener()
+
+    manager[domain] = listener
+
+    assert.throws(() => 
+    {
+      manager[domain] = new ListenersManager.Listener()
+    }, 
+    {
+      code: 'E_EVENTFLOW_LISTENERS_DOMAIN_ALREADY_EXISTS'
+    })
+  })
+
+  test('Throw error when setting invalid listener instance', async () =>
+  {
+    const 
+      manager = new ListenersManager(),
+      domain  = 'domain1'
+
+    assert.throws(() => 
+    {
+      manager[domain] = {}
+    }, 
+    {
+      code: 'E_EVENTFLOW_LISTENERS_INVLAID_INSTANCE_OF_LISTENER'
+    })
+  })
+
+  test('Lazy-load listener for non-existent domain', async () =>
+  {
+    const 
+      manager = new ListenersManager(),
+      domain  = 'domain1'
+
+    const listener = manager[domain]
+    assert.ok(listener instanceof ListenersManager.Listener)
+    assert.strictEqual(manager[domain], listener)
+  })
+
+  test('Delete listener by domain', async () =>
+  {
+    const 
+      manager  = new ListenersManager(),
+      domain   = 'domain1',
+      listener = new ListenersManager.Listener()
+
+    manager[domain] = listener
+    assert.strictEqual(manager[domain], listener)
+
+    delete manager[domain]
+    assert.ok(manager[domain] instanceof ListenersManager.Listener)
+
+    assert.notStrictEqual(manager[domain], listener)
+  })
+
+  test('Wildcard event emission', async () =>
+  {
+    const 
+      listener      = new ListenersManager.Listener(),
+      emittedEvents = []
+
+    listener.on('*', (...args) => emittedEvents.push({ event: '*', args }))
+    listener.emit('nonexistentEvent', 'arg1', 'arg2')
+
+    assert.deepStrictEqual(emittedEvents, 
+    [
+      {
+        event : '*',
+        args  : ['arg1', 'arg2']
+      }
+    ])
+  })
+
+  test('Emit specific event if listeners exist', async () =>
+  {
+    const 
+      listener      = new ListenersManager.Listener(),
+      emittedEvents = []
+
+    listener.on('specificEvent', (...args) => emittedEvents.push({ event: 'specificEvent', args }))
+    listener.emit('specificEvent', 'arg1', 'arg2')
+
+    assert.deepStrictEqual(emittedEvents, 
+    [
+      {
+        event : 'specificEvent',
+        args  : ['arg1', 'arg2']
+      }
+    ])
+  })
+})

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@superhero/eventflow-spoke",
+  "version": "4.0.0",
+  "description": "Eventflow spoke is the client component in the eventflow ecosystem.",
+  "keywords": [
+    "eventflow",
+    "spoke"
+  ],
+  "main": "config.js",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./consume": "./consume.js",
+    "./manager/*": "./manager/*.js"
+  },
+  "dependencies": {
+    "@superhero/deep": "^4.2.0",
+    "@superhero/eventflow-certificates": "^4.0.2",
+    "@superhero/eventflow-db": "^4.1.0",
+    "@superhero/id-name-generator": "^4.0.0",
+    "@superhero/log": "^4.0.0",
+    "@superhero/tcp-record-channel": "^4.2.1"
+  },
+  "devDependencies": {
+    "@superhero/config": "^4.1.3",
+    "@superhero/locator": "^4.2.1",
+    "@superhero/eventflow-hub": "^4.0.4"
+  },
+  "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-spoke.git"
+  }
+}