Skip to main content

Data Consistency

Warrant is a distributed service deployed to multiple cloud regions. All traffic (reads and writes) flows through a single endpoint (api.warrant.dev). By default, data is replicated across regions to maximize performance and reliability. In order to balance performance and consistency, Warrant implements a 'bounded staleness protocol' similar to Google Zanzibar's 'Zookie' protocol.

Warrant-Tokens​

Each 'write' operation in Warrant (e.g. creating or deleting a new warrant, modifying an object type) is atomic and generates a unique transaction id known as a 'Warrant Token'. The server returns this token as a response header in all API writes:

'Warrant-Token: MjM0fDM0MzQyM3wyMTM0MzM0MzY0NQ=='

User-specified consistency​

Unlike traditional, eventually-consistent distributed systems, Warrant allows users to specify their desired 'consistency level' via the Warrant-Token. More specifically, on reads (checks and queries), clients may pass a previously generated Warrant-Token as a header to instruct the server to only process the request using data no older than the transaction identified by the client-passed Warrant-Token. This ensures that clients can dictate an exact level of consistency on a per-request basis.

In practice, clients can store Warrant-Tokens in their system on a per-subject basis, and pass that token on each read for that subject for optimal performance. For example, if creating a new warrant (e.g. user:x is an editor of report:y) generates a Warrant-Token with value 45f87sdf=, that token can then be stored in the client's db along with 'user:x'. Subsequent checks or queries to Warrant can then include that stored Warrant-Token for optimal performance.

latest token​

It's possible that a situation might arise where a client needs an up-to-date result as of some specific transaction but doesn't have the accompanying Warrant-Token for that transaction. In such a scenario, the client can pass the latest Warrant-Token in their read op to instruct the server to use the most up-to-date data it has on record:

'Warrant-Token: latest'

Note that using the latest token effectively instructs the server to bypass all caches in favor of hitting the database for the most up-to-date result. Therefore, it's recommended to use latest only when necessary and instead use server-provided Warrant-Tokens or no token at all (instead relying on server defaults) to maximize performance in most cases.

Default consistency​

As briefly mentioned above, passing a Warrant-Token on reads is optional. If a Warrant-Token is not provided, the server uses a default 'staleness window' to fulfill check and query requests. This window is cache-optimized and thus the recommended approach for the 90-95% of read requests that can tolerate short replication lag.