Partitioning & Sharding

LoomCache uses stable partition routing, membership-slot ownership planning, and a consistent hash ring for routing and placement. Today the default data model is full replication: every node in the single Raft group holds every partition, so partitioning is primarily an affinity and routing hint rather than a sharded placement strategy. The ingredients for per-partition Raft groups ship as a development/validation surface and are exercised by tests; production activation is unsupported and fail-closed until per-group WAL, Raft metadata, snapshot, install-snapshot, and restart recovery are proven with durable migration chunk ACKs, consensus-backed ownership cutover, and an explicit sharding release gate.

Consistent Hash Ring

Keys are hashed to 271 partitions mapped cleanly across virtual nodes, decoupling data from physical servers.

N-1

N-2

N-3

Hash(Key)

Physical Node

Active Slot Route

Slot Management

Rather than hashing keys directly to nodes, LoomCache hashes sharded-Raft keys to one of 271 routing partitions by default. That count matches Hazelcast’s default partition count and is intentionally small enough for compact client routing-table refreshes.

Note

Because LoomCache maps through routing partitions and server-side ownership slots instead of hashing directly to nodes, adding or removing a node only requires moving specific slices of the keyspace. That minimizes network impact compared to a traditional mod-N hash ring.

How Keys Map to Partitions

The following formula maps a key to a routing partition:

partition = unsignedRemainder(stableKeyHash(key), 271)

LoomCache computes an unsigned remainder rather than using the signed % operator. The stable key hash is a signed 32-bit value that can be negative, and the unsigned remainder ensures a valid [0, 271) partition index.

The server publishes routing snapshots to clients. The client SDK uses the same hash function for smart routing: it sends requests directly to the owning group without an extra redirect hop. Membership-slot planning and the consistent hash ring handle server-side ownership planning during membership changes.

Slot Count Tradeoff

LoomCache separates three counts that older comparisons sometimes collapsed into “1024 vs 271”:

• 271 routing partitions control smart-client and multi-Raft-group routing.
• 16,384 membership slots control membership-migration ownership planning.
• 256 virtual positions per physical member feed the consistent hash ring; a four-member cluster therefore has 1,024 ring positions.

More slots or virtual nodes make rebalancing smoother because ownership can move in smaller chunks and hot keys are less likely to cluster on one member. The cost is larger metadata: every owner table, migration preview, and membership broadcast grows linearly with the slot count. As a rule of thumb, an int routing table is about 1 KiB at 271 entries, about 4 KiB at 1,024 entries, and about 64 KiB at 16,384 entries before protocol and JVM object overhead. LoomCache keeps the client-facing routing table at 271 entries and uses the larger slot table only for server-side migration planning.

Partition Distribution

Under the sharded model (fail-closed in production today), the 271 routing partitions spread evenly across the Raft groups — roughly 271 / N. In the default full-replication model, every node still holds every partition; the counts below describe routing-partition spread, not disjoint per-node ownership. Quorum is the Raft majority, floor(N / 2) + 1.

Cluster Size	Routing Partitions per Group	Quorum
3 nodes	~90 each	2
5 nodes	~54 each	3
7 nodes	~38 each	4

Partition Migration

Partition Migration (Gated Sharding Path)

Illustrative rebalance sequence for sharding validation; production dynamic scaling remains release-gated

GATED PATH IDLE

Group 1

Part 1

Part 2

Group 2

Part 3

Part 4

Group 3

Part 5

Part 6

When a development sharded cluster scales out, the validation rebalance path computes a redistribution plan and executes migration. See Sharding Design for the full behavior. This is not a production sharding claim; production must stay on the single-group model until the recovery gaps above are closed.

Migration Sequence

1. An operator changes the configured group count, triggering a validation rebalance.
2. The membership-slot table computes the optimal redistribution across the 16,384 membership slots.
3. The routing cutover is committed through raft-0 consensus (submitMappingCommit) in the sharded validation path; production deployments keep sharding disabled until the documented recovery gaps are closed.
4. Data streams in the background: the source node sends slot data to the target.
5. Individual slots are briefly paused during the ownership handoff.
6. Client routing tables are updated, and subsequent requests go to the new owner.

Per-Slot Metrics

LoomCache tracks fine-grained metrics for each hash slot:

• Access count — requests hitting this slot
• Key count — number of keys stored in this slot
• Memory usage — bytes consumed by this slot’s data

Use slot hot-spot reports to identify the busiest membership slots (slot IDs 0–16,383) and rebalance proactively. Note that these are 16,384 membership-layer slots, not the 271 routing partitions used for smart routing.

Client-Side Smart Routing

The client SDK keeps a refreshed partition table and uses the same stable key hash as the server to route requests to the best known owning group or leader. Partitions map to Raft group IDs, not directly to nodes; the client then resolves that group’s leader endpoint:

// Client internally computes the owning group from the refreshed partition table:
int ownerGroup = partitionTable.ownerGroupForKey(key);
// ownerGroupForKey hashes the key, maps it to a routing partition,
// and indexes partitionToGroup[partition].
String endpoint = partitionTable.leaderEndpointForOwnerGroup(ownerGroup);
// Sends request directly to that owner group's leader — zero redirects

Redirects remain part of the correctness path when leadership or ownership information is stale.

To learn how writes replicate within each Raft group, see Raft Clustering.