[Phase 6] Define Cluster and Node interfaces/traits (API Contract)

[konard]

Summary

Define the interfaces/traits for multi-node clustering, including node discovery, partition management, and replication.

Background

This establishes the API contract for distributed operation, enabling both `multi-memory` and `multi-stored` modes.

Requirements

Node Interface/Trait

// TypeScript
interface ClusterNode {
  readonly id: string;
  readonly address: string;
  readonly port: number;
  readonly status: NodeStatus;
  
  ping(): Promise<number>;  // Returns latency in ms
  isHealthy(): boolean;
}

type NodeStatus = 'healthy' | 'suspect' | 'dead' | 'joining' | 'leaving';

ClusterCoordinator Interface/Trait

interface ClusterCoordinator {
  // Node management
  join(nodes: string[]): Promise<void>;
  leave(): Promise<void>;
  getNodes(): ClusterNode[];
  getLeader(): ClusterNode | null;
  
  // Partition management
  getPartitionOwner(key: string): ClusterNode;
  rebalance(): Promise<void>;
  
  // Events
  on(event: 'node-joined', handler: (node: ClusterNode) => void): void;
  on(event: 'node-left', handler: (node: ClusterNode) => void): void;
  on(event: 'leader-changed', handler: (node: ClusterNode) => void): void;
}

ReplicationManager Interface/Trait

interface ReplicationManager {
  readonly replicationFactor: number;
  readonly syncMode: 'sync' | 'async';
  
  replicate(link: Link): Promise<void>;
  getReplicaNodes(linkId: LinkId): ClusterNode[];
  ensureConsistency(linkId: LinkId): Promise<void>;
}

Configuration

interface ClusterConfig {
  nodes: string[];              // Initial node list
  discovery: 'static' | 'dns';  // Discovery method
  replication?: {
    factor: number;             // Number of replicas
    sync: boolean;              // Sync vs async replication
  };
}

Deliverables

1. TypeScript interface definitions in src/cluster/types.ts
2. Rust trait definitions in src/cluster/traits.rs
3. Documentation with clustering overview
4. Ensure API parity between JS and Rust

Dependencies

• [Phase 1] Define Link and LinkStore interfaces/traits (API Contract) #7 - Link interfaces
• [Phase 2] Define Queue and QueueManager interfaces/traits (API Contract) #10 - Queue interfaces

Enables Parallel Work

Once completed, the following issues can be worked on in parallel:

• JavaScript clustering implementation
• Rust clustering implementation

References

• ARCHITECTURE.md - Cluster Coordinator section
• REQUIREMENTS.md - REQ-SCALE-001 through REQ-SCALE-022
• ROADMAP.md - Phase 6: Multi-Node Clustering