What it does
The gtm crate is a pure function. Given a request and the known endpoints it returns the endpoint the request may go to, or a typed refusal. It does no input or output and reads no clock. Nothing in the server, the command line or an edge adapter calls it today.
How it works
An endpoint is chosen when it passes every filter, applied in a fixed order, and not otherwise; the survivors are ranked after that. It must serve the request's shard. It must be ready and not draining. It must satisfy the request's residency requirement, such as a country tag. Its role must be permitted for the request's class. Preference, meaning the request's region order and then the endpoint id, never makes an ineligible endpoint eligible, and no refusal falls back to one.
The function does not elect leaders; shard consensus does. For one shard, the authoritative leader is the leader claim with the highest term among all of that shard's endpoints, ready or not. Two claims at the same top term are an ambiguous-leader refusal and nothing is picked. A lower-term leader is a deposed leader and is never used, even while the authoritative leader is draining or down, so writes wait for consensus to settle instead of landing on a deposed leader.
Mutations, transactions and control-plane requests go to the authoritative leader. A point read may go to the leader or to a replica that is fresh: it has applied at least the position the caller has already seen, and it is within a policy-set number of positions of the leader. Positions are compared within a single shard and never across shards. Multi-shard queries, streaming, health and discovery are not decided here and return a class-not-routed refusal, so a scatter layer would ask once per shard.
The result lists the chosen endpoint and the other eligible endpoints in order as fallbacks. Refusals carry per-endpoint exclusion reasons, such as wrong shard, draining, not ready, residency mismatch, superseded leader, below the minimum position or beyond the staleness bound. The same JSON fixtures are meant to drive this crate and a later edge adapter.
Where you reach it
- Library
kynetra_gtm::decide(request, endpoints, policy) (engine library, not wired to the server)
Limits
- Not reachable from the server or the command line, and no edge adapter exists in the repository.
- It decides placement from endpoint facts that something else must collect and keep current: it does no health checking, discovery or traffic steering. Readiness, role, leader term, positions and residency are values the caller asserts and the function does not verify; the tenant is recorded and not authorised.
- It depends on the partition map and request classes of the routing library, and the server does not shard data, so there is no multi-shard deployment for it to steer.
Evidence
- TestsCovered in the engine repository by 9 tests, including a table of 34 annotated fixture cases that cover every refusal and every exclusion reason, an order-independence test, and property tests that a decision never returns an endpoint that fails a filter and is deterministic
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
This is not available in the preview. Request a preview to discuss the current scope.