Architecture & The Ring

Gossip State for Each Node:
═══════════════════════════════════════════════════════════
Field              | Description
═══════════════════════════════════════════════════════════
STATUS             | NORMAL, LEAVING, JOINING, MOVING
LOAD               | Data size on disk (bytes)
SCHEMA             | Schema version UUID
DC                 | Datacenter name
RACK               | Rack name
TOKENS             | Token ranges owned
SEVERITY           | I/O pressure (0.0 - 1.0)
HOST_ID            | Unique node identifier
RPC_ADDRESS        | Address for client connections
RELEASE_VERSION    | Cassandra version running
═══════════════════════════════════════════════════════════

Failure Detection (Phi Accrual):
  - Not binary (alive/dead) but probabilistic
  - Phi value increases as heartbeats are missed
  - Threshold (default 8) determines "down" declaration
  - Adapts to network conditions automatically

Token Ring (simplified with 4 nodes, range 0-100):

              Node A (0-25)
                 ╱          ╲
        Node D              Node B
        (75-100)              (25-50)
                 ╲          ╱
              Node C (50-75)

Write: INSERT INTO users (id, name) VALUES ('alice', 'Alice')
  1. Hash partition key: murmur3('alice') → token 37
  2. Token 37 falls in range 25-50 → Node B owns this data
  3. With RF=3: replicas on Node B, Node C, Node D (clockwise)

The partitioner (Murmur3) produces a uniform distribution,
so data spreads evenly across the ring.

# cassandra.yaml vnode configuration
num_tokens: 16    # Cassandra 4.0+ recommendation (was 256)

# Why 16 instead of 256?
# - 256 vnodes = 256 token ranges in system tables = overhead
# - 16 vnodes with allocate_tokens_for_local_replication_factor
#   provides nearly as good distribution with less overhead
# - Fewer ranges = faster streaming during repairs

# For Cassandra 3.x clusters:
num_tokens: 256   # The traditional default

// DataStax Node.js driver with token-aware routing
import { Client, policies } from 'cassandra-driver';

const client = new Client({
  contactPoints: ['10.0.1.1', '10.0.1.2', '10.0.1.3'],
  localDataCenter: 'dc1',
  keyspace: 'my_app',
  policies: {
    loadBalancing: new policies.loadBalancing.TokenAwarePolicy(
      new policies.loadBalancing.DCAwareRoundRobinPolicy('dc1')
    ),
    // Retry on next host if coordinator fails
    retry: new policies.retry.RetryPolicy()
  }
});

// The driver routes this directly to the node owning partition 'user-123'
await client.execute(
  'SELECT * FROM users WHERE user_id = ?',
  ['user-123'],
  { prepare: true }  // Prepared statements enable token-aware routing
);

# GossipingPropertyFileSnitch configuration
# Each node declares its own DC and rack
dc=us-east-1
rack=rack1

# This is gossiped to all other nodes
# The replication strategy uses this to place replicas
# across different racks within a DC

# Seed node configuration
seed_provider:
  - class_name: org.apache.cassandra.locator.SimpleSeedProvider
    parameters:
      - seeds: "10.0.1.1,10.0.1.2,10.0.2.1"

# Best practices for seed selection:
# - 2-3 seeds per datacenter
# - Choose stable, long-lived nodes
# - Don't make all nodes seeds (slows gossip convergence)
# - Seeds should be in different racks for resilience
# - Never bootstrap a seed node (it won't auto-stream data)