Architecture

RESP-compatible clients talk to a Kronotop member over TCP. The member hosts two data models: Bucket for documents and ZMap for ordered key-value data. Both use the same sessions, namespaces, and transactions. FoundationDB stores metadata, indexes, ZMap data, and cluster state. Volume, Kronotop’s storage engine, keeps document bodies on the member’s local disk.

Wire protocol and sessions

Kronotop speaks RESP2 and RESP3 and works with existing RESP-compatible clients. Every operation, including cluster administration, is a RESP command. There is no separate query endpoint or admin protocol. Each member listens on two ports: one for clients and one for cluster administration.

Every client connection belongs to a session. The session holds its attributes, its current namespace, the open transaction if there is one, and its cursors.

Kronotop and FoundationDB

Every Kronotop transaction is a FoundationDB transaction. Strict serializability, conflict detection, and the ordered keyspace come from FoundationDB. Kronotop adds the RESP front end, the document layer with its query engine and indexes, and the Volume storage engine.

FoundationDB holds all data that is small and must be transactional: bucket metadata and index entries, ZMap data, namespace directories, volume metadata, and cluster state. Document bodies are different. FoundationDB is built for small key-value pairs and limits a value to 100 KB, and document bodies often exceed that limit. Volume stores them in append-only segment files on the member’s local disk and keeps only pointers in FoundationDB.

Transactional guarantees still hold across this split. Kronotop first appends the document body to a segment file and flushes it to disk. It commits the metadata to FoundationDB only after the flush succeeds, so metadata never points to content that is not on disk.

Sharding

Bucket data is split into shards. Each shard owns exactly one volume, named after the shard (bucket-shard-0, bucket-shard-1, and so on). A bucket spans one or more shards, so its documents are spread across one or more volumes. Inside a volume, a prefix keeps each bucket’s data separate.

Cluster routing assigns shard ownership. One member is the primary and serves all Bucket commands. Standby members replicate from the primary and can be promoted. Each shard also has a status that controls traffic: READWRITE, READONLY, or INOPERABLE. You manage routing and status with the admin command interface.

Kronotop does not shard ZMap data. ZMap data lives directly in FoundationDB, which partitions its own keyspace automatically.

Replication

Volume replication is asynchronous and goes from the primary to the standbys. Each shard’s volume replicates on its own. A standby pulls from the primary. It first copies the existing segment data in chunks until it reaches the primary’s current write position. After that, it streams new changes from a changelog stored in FoundationDB. Replication progress is also stored in FoundationDB, so a standby can restart and continue from the point where it stopped.

Replication starts automatically when cluster routing assigns a standby. An operator must promote a standby or reassign shards by hand. See Volume replication for how replication works and the operations guide for the commands.

Cluster coordination

All coordination state lives in FoundationDB. Kronotop has no separate consensus layer or gossip protocol. Members do not talk to each other to agree on cluster state. They read and write it in FoundationDB.

Failure detection uses FoundationDB too. Each member increments a heartbeat counter in FoundationDB at regular intervals, and other members expect the counter to keep growing. If a member’s counter stops for longer than the configured silent period, other members suspect that it is dead. Each member makes this decision by itself, with no cluster-wide agreement. A suspected member drops off the list as soon as its heartbeats start again. See health monitoring for details.