Durability & recovery

Partition map and routing epochs

Gives routers and clients one versioned answer to which shard owns a key, and refuses a request that was routed with an out-of-date view.

BetaEngine edition 5f8ea3af

What it does

GET and PUT /v1/routing/map serve and publish an epoch-versioned partition map that assigns the 64-bit hash space to shards. A caller that sends x-kynetra-routing-epoch is admitted at the current epoch and is refused with a 412 that carries the fresh map otherwise. The map is metadata: one engine serves every key today, and splitting or moving data between shards is not built.

How it works

The map is a list of inclusive hash ranges, each owned by one shard, plus an epoch that rises by one on every change. A key is hashed to the first eight bytes of its SHA-256, read big-endian, and belongs to the one range that contains the hash. That hash is stable by contract, because changing it would be a data migration. Validation requires the ranges to cover the whole hash space exactly once and rejects gaps, overlaps and duplicate shard ids. With no stored map the server uses a single shard that owns the whole space.

GET /v1/routing/map returns the current map to a caller with the Viewer role. PUT publishes a new one and needs an administrator. The proposed epoch must be exactly the current epoch plus one, and the publish is a conditional transaction on the stored epoch, so two concurrent publishers cannot fork the topology: one wins and the other gets a 409 with the fresh map. The map is a single record in the log, so it inherits durability, checkpoints, backups and replication, and it survives a restart. At boot, a stored map that cannot be read, decoded or validated stops the server from starting, with an error that names the record; the default map is never seeded over it.

A router that sends x-kynetra-routing-epoch is admitted at the current epoch and at no other. A stale epoch, a future epoch and a value that is not an integer are each refused with a 412 and the current map in the body, so one round trip resynchronises a stale router. The same check runs ahead of every /v1 data request that carries the header. A caller that sends no header passes untouched, so single-cell clients are unaffected.

The routing library also defines a split of one range, which bumps the epoch and keeps the map total, and a table of eight request classes (point read, mutation, transaction, multi-shard query, control plane, streaming, health and discovery). For each class the table records whether it needs an epoch, belongs to one shard, may be forwarded and may scatter. The server does not consult the class table; the Global Traffic Manager entry uses it.

Where you reach it

  • HTTPGET /v1/routing/map (Viewer), PUT /v1/routing/map (administrator; body {"map": {...}})
  • HTTPRequest header x-kynetra-routing-epoch on /v1 routes; 412 response carries the current map

Limits

  • This is the map and the refusal contract, not sharding. The server never routes a key by the map, there is one engine for the whole instance, and publishing a map with several shards moves no data. The routing library names online split and move, dual-read validation, scatter-gather, placement constraints and hotspot detection as not built.
  • The epoch header is optional and is checked on /v1 routes. The server does not require clients to send it.
  • Raft shard groups exist as simulated code; they do not distribute data across a running cluster.

Evidence

  • On this siteHTTP API reference
  • TestsCovered in the engine repository by 12 routing-library tests (total routing, malformed maps rejected, exact epoch admission, split keeps the map total, class table), 5 loader tests (an absent map is the default; a read fault, a fence or an invalid record is an error and never the default), tests for admission, publishing, restart survival, concurrent publishers and a stale router refused on the data plane, and boot tests (4) for unreadable seed state, including an undecodable or invalid routing map

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to talk through the limits above against your own workload.