Skip to main content

Replication

This page describes FLUX replication semantics as implemented today.

Replication Status (Current)​

FLUX replication currently combines:

  1. in-memory replication manager for ISR/high watermark/ack semantics
  2. local replica segment mirroring (same node) for storage visibility
  3. broker-to-broker replication RPC scaffold (BROKER_FETCH, BROKER_REPLICA_ACK) and follower fetch/apply/ack worker flow

This is partial multi-broker replication scaffolding, not yet full production-grade network replication/failover.

Implemented Behavior​

  • leader offset tracking per partition
  • follower progress updates through REPLICA_FETCH
  • broker-fetch contract for follower pull replication (BROKER_FETCH)
  • replica acknowledgement contract from follower to leader (BROKER_REPLICA_ACK)
  • ISR membership computed from lag + freshness
  • high watermark computed from ISR offsets
  • acks=1 and acks=all produce handling
  • committed-read behavior (CONSUME only up to high watermark)
  • under-replicated partition signaling
  • partition role transitions (leader / follower)
  • produce rejection on follower role (NOT_LEADER)

Key Semantics​

  • leader replica id is implicit 0
  • follower ids are 1..(replication_factor-1)
  • acks=all succeeds only when:
    • high watermark reaches produced offset
    • ISR size is at least min.insync.replicas
  • ISR eligibility requires:
    • follower ack seen within replica lag timeout
    • offset lag <= max replica lag

TypeScript SDK View​

In normal application usage, replication behavior is consumed through TypeScript producer APIs:

import { FLUXClient } from '@flux/typescript-sdk';

const client = new FLUXClient({ host: '127.0.0.1', port: 9092 });
await client.connect();

await client.produce('orders', 'user1', 'created', 'all');

If replication cannot satisfy acks=all, the produce call surfaces REPLICATION_TIMEOUT.

Not Implemented Yet​

  • fully orchestrated broker-to-broker replication lifecycle across cluster nodes
  • quorum-backed replica metadata
  • cross-node failover with automatic leadership transfer
  • persistent replication state across clustered brokers

Planned Direction​

Replication will graduate from scaffolded network contracts to fully automated true networked replication with failover behavior and control-plane metadata quorum in Phase 5+.