SYSTEM Cited by 1 source

pingora-ketama

pingora-ketama is Cloudflare's open-source Rust library for consistent hashing, part of the Pingora project (crate, source). It implements the ketama weighted consistent-hashing scheme (the lineage descends from last.fm's 2007 systems/libketama) and is the ring backing Pingora Backend Router's cacheable-request routing (Source: sources/2026-09-18-cloudflare-saving-another-100tb-of-ram-with-math-and-rust).

Ring model

• Servers and tasks are hashed onto a 32-bit number line; a task is served by the first server to its left.
• Default 160 hashes per server (the same value NGINX hardcodes), scaled by a per-server weight so higher-capacity servers take proportionally more load. Cloudflare weights by disk space.
• Hashes are stored as Point structs sorted for O(log n) lookup.

The v1 Point (before)

struct Point {
    hash: u32,
    index: u32,   // index into a separate server array
}

Eight bytes: 4 for the hash (unavoidable), 4 for the server index.

The v2 packing fix

index never needs more than 16 bits — PBR won't coordinate more than 2^16 ≈ 65k servers — but simply changing it to u16 saves nothing: Rust alignment rules round the struct up to a multiple of its largest field (4-byte hash), keeping it at 8 bytes. Storing both fields in a raw 6-byte array with getters avoids the padding without the hazards of #[repr(packed)]:

struct Point([u8; 6]);

impl Point {
    fn hash(&self) -> u32 {
        u32::from_ne_bytes(self.0[0..4].try_into().unwrap())
    }
    fn index(&self) -> u16 {
        u16::from_ne_bytes(self.0[4..6].try_into().unwrap())
    }
}

Both forms compile to the same code. Net: 8 → 6 bytes (25 %) less memory for consistent hashing, with no behavior change.

The v2 ring

Shipped as a v2 ring behind a (for now) unadvertised cargo feature:

• Compacted 6-byte storage format (above).
• Faster sorting method for ring construction.
• Tunable base number of hashes per node — lets Cloudflare drop the per-server hash count by 90 % (justified by the coefficient-of- variation math + 32-bit collision analysis; see concepts/consistent-hashing).

v1 remains byte-for-byte identical to historical behavior, and the library can run both v1 and v2 simultaneously, deciding request-by-request which to use — the primitive PBR's migration depended on.

Seen in

• sources/2026-09-18-cloudflare-saving-another-100tb-of-ram-with-math-and-rust — canonical wiki instance: the struct-packing fix, the fewer-hashes change, and the dual-v1/v2 ring capability.

Related

• systems/pingora — parent project.
• systems/pingora-backend-router — the service that consumes this library at scale.
• systems/libketama — the 2007 ancestor of the ketama weighting scheme.
• concepts/consistent-hashing — the algorithm and the balancing math.
• concepts/memory-safety — the Rust alignment/packing trade-off the fix navigated.
• companies/cloudflare — parent org.