Distributed Lock Service  ·  View 09 of 26  ·  3 · Structure

How a Key Finds Its Class and Its Cluster

The class decides the tier, the tier decides the cluster, and the caller never names either.

Editable source SVG draw.io All views
Request Lock key tenant/ns/path Classify Class match longest prefix No class: refuse Tier Class tier Home Coord tier leader election Shard map rendezvous hash Commit Lock log · coord Lock log · entity-01 Lock log · entity-02 unmatched class coarse entity How a Key Finds Its Class and Its Cluster Application we own Security / platform Risk / gap Decision point Data store synchronous failure / alternate The class decides the tier. A caller never names a cluster, so a caller cannot get routing wrong. v 1.0 · owner Platform Architecture · date 2026-09

Decisions

  • A key with no matching class is refused. There is no default class, because a default class is where an unreviewed correctness lock ends up.
  • Coarse locks, leader election and control-plane singletons, live on a five-member coord cluster that entity churn cannot touch. Entity locks live on three-member shards sized for write throughput.
  • Entity keys are homed by rendezvous hashing on the namespace and path prefix. Adding a shard moves only the keys that hash to it, and each move is fenced by an epoch advance on the destination.

Why routing lives in configuration

  • The requirement warns that a routing rule between two clusters will eventually be got wrong. Putting the tier on the class makes the owner decide once, in review, rather than every caller deciding on every request.

Risks

  • A class moved from entity tier to coord tier is a rehome, not a relabel. The class controller refuses the change while any key under the prefix is held.