What it does
A replica pulls the primary's log over HTTP, writes each record verbatim into its own log and applies it. It refuses local writes, forwards write requests to the primary, and takes itself out of service if its log ever differs from the primary's. Replication is asynchronous unless quorum commit is enabled, and there is no automatic failover.
How it works
The primary serves GET /v1/replica/stream?since=<seq>&limit=<n>, a newline-delimited stream of log records at or above the given sequence number. The request needs the instance service key, and any node can serve the stream, so a replica can feed another from its own prefix. The response header x-kynetra-next-seq reports the source's position so followers can report honest lag. A replica started with KYNETRA_ROLE=replica and KYNETRA_PRIMARY_URL polls this endpoint, backs off on errors, and ingests each batch with a call that persists the records verbatim into its own segmented log before applying them. After a restart it replays its own disk and resumes where it stopped. With the PostgreSQL backend the replica instead tails the shared table.
Safety rules are enforced in the engine. Ingest is idempotent and gap-safe: a record at a position the replica already holds must carry identical bytes, otherwise it is a divergence and nothing from that batch is applied. By default each pull also compares the replica's tail with the primary's, and a replica that finds divergence stops serving as a replica until an operator reseeds it. A replica opens with a follower fence: every put, delete, transaction and destructive recovery operation is refused at the single writer before it is staged, and local schedulers do not start.
Requests that reach a replica are handled by a proxy: writes, and reads from non-platform callers, are forwarded to the primary, with a cap on concurrent proxied requests and a cap on streamed body size. Read-your-writes controls are described in the read-consistency entry. On first boot a replica obtains the same signing, vault and audit secrets as the primary instead of generating its own.
Replica pulls can run over mutually authenticated TLS. A bundle named by KYNETRA_REPLICATION_TLS_CONFIG supplies the node identity, the roots and the allowed workload identities. In strict mode the primary refuses plaintext WAL streams on its public listener and serves them on a dedicated internal listener, and the replica pins the primary's workload identity.
Measured: replica staleness of 5 ms at p50 and 17 ms at p99, with replica lag at 0 records for both p50 and p99, under 16 concurrent writers. This is local scope, one host (Apple M5, 32 GB RAM). Two engines on one host over the engine path — the HTTP wire is covered separately by the server smoke test, not by this run. Staleness is the age of the oldest unapplied record at each 50 ms poll. A network between the nodes will add to it.
Where you reach it
- Config
KYNETRA_ROLE=replica, KYNETRA_PRIMARY_URL (file backend) - HTTP
GET /v1/replica/stream?since=<seq>&limit=<n>; POST /v1/replica/ingest - Config
KYNETRA_REPLICA_VERIFY_TAIL, KYNETRA_REPLICA_PROXY_CONCURRENCY, KYNETRA_REPLICATION_TLS_CONFIG
Example
KYNETRA_ROLE=replica \
KYNETRA_PRIMARY_URL=https://primary.example.com:8080 \
KYNETRA_API_KEY="$SERVICE_KEY" \
kynetra-serverLimits
- Replication is asynchronous by default. If the primary fails before records are streamed, those writes are not on the replica. Quorum commit makes the primary wait for a replica.
- There is no automatic failover or promotion in this path. The Raft entry covers automatic leadership change and is a research item.
- Without the replication TLS bundle, the pull carries the instance service key as a bearer token over whatever transport the primary URL names. Use https or a private network.
- Replication copies the log. File bytes are not in the log and are not replicated.
- The published staleness figure is for two engines on one host; a real network adds to it.
- A replica that has diverged stays out of service until it is reseeded by hand.
Evidence
- ArtifactReplication-lag artifact (local scope, one host)
- On this siteReliability
- TestsCovered in the engine repository by engine tests for ingest, divergence (6), the follower fence (6) and injected faults (6), more than 40 server tests, 12 HTTP tests for the TLS runtime, 4 for the replica fence and 4 for the minimum-position gate
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
Every figure on this site is local-scope: one host, one operator, no third-party reproduction. Artifacts are linked next to each number, and gates that were missed are published beside the gates that were met.
KynetraDB is in private preview
Request a preview to talk through the limits above against your own workload.