Skip to content

feat: cluster mode with leader election & WebSocket worker mesh#59

Merged
jbiskur merged 4 commits intomainfrom
feat/cluster-leader-election
Mar 19, 2026
Merged

feat: cluster mode with leader election & WebSocket worker mesh#59
jbiskur merged 4 commits intomainfrom
feat/cluster-leader-election

Conversation

@jbiskur
Copy link
Contributor

@jbiskur jbiskur commented Mar 19, 2026

Summary

  • Adds FlowcoreDataPumpCluster class for HA failover and horizontal scaling of event processing across multiple instances
  • Leader election via lease-based FlowcoreDataPumpCoordinator interface (user implements against their DB, same pattern as stateManager)
  • Leader fetches events via existing FlowcoreDataPump, distributes to workers over persistent WebSocket connections
  • Workers process events using user's handler, ack back over WS; leader advances cursor only after ack
  • Falls back to local processing when no workers available (single-instance mode)
  • No changes to existing FlowcoreDataPump class -- cluster wraps it

New files

  • src/data-pump/types.ts - FlowcoreDataPumpCoordinator interface
  • src/data-pump/ws-protocol.ts - WS message types, serialization, WsConnection, DeliveryTracker
  • src/data-pump/data-pump-cluster.ts - FlowcoreDataPumpCluster class
  • src/data-pump/metrics.ts - cluster metrics (active workers, leader status, distribution counters)
  • test/tests/data-pump-cluster.test.ts - tests for WS protocol, DeliveryTracker, MockCoordinator

Test plan

  • Existing tests pass (deno test)
  • WS protocol serialization round-trip tests
  • DeliveryTracker: ack, fail, timeout, rejectAll
  • MockCoordinator: lease acquisition, renewal, expiry, release, instance registry
  • Manual: run 2+ instances, verify events distributed across workers

🤖 Generated with Claude Code

jbiskur and others added 4 commits March 19, 2026 14:31
Adds FlowcoreDataPumpCluster for HA failover and horizontal scaling
of event processing. Leader fetches events and distributes to workers
via persistent WebSocket connections. Uses abstract coordinator
interface (user-implemented against their DB) for lease-based leader
election and instance discovery. Falls back to local processing when
no workers available.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace Deno-specific Deno.serve/upgradeWebSocket with a public
handleConnection(ws: WebSocket) method. Users wire up their own
HTTP server and call handleConnection on upgrade. Works with both
Deno and Node.js (via ws package).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@jbiskur jbiskur merged commit d2e2e47 into main Mar 19, 2026
1 check passed
@jbiskur jbiskur deleted the feat/cluster-leader-election branch March 19, 2026 14:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant