Behavior & Limits

Guarantees

On cloud platforms (AWS, GCP, Azure), Alien provisions and manages the KV backing service. These guarantees apply:

Strong Single-Key Consistency. A get() after a successful set() on the same key returns the new value immediately. Firestore is always strongly consistent, DynamoDB uses strongly consistent reads, and Table Storage is strongly consistent within a region.

Atomic Conditional Writes. set() with ifVersion and delete() with ifVersion are atomic across all platforms — see Versions & Conditional Writes below. If two concurrent callers race on the same key, exactly one wins and the other resolves false. Safe for distributed locks, idempotency checks, and read-modify-write loops.

Durability. Data is replicated across multiple availability zones by the cloud provider.

TTL is a Soft Hint. When you set a TTL, the key becomes invisible on read after expiry — get() returns null and exists() returns false. Physical deletion of the underlying data is eventual and varies by platform (see below). Do not rely on storage being reclaimed at a specific time.

Delete Idempotency. Deleting a non-existent key succeeds silently (a conditional delete resolves false when the key is absent, expired, or changed).

Versions & Conditional Writes

Every read (get, getText, getJson, scan) returns an opaque, key-bound version alongside the value. It changes on every applied write.

• Create if absent. set(key, value, { ifVersion: null }) creates the key only when it is absent or logically expired. Exactly one of several concurrent creators succeeds.
• Compare-and-set. set(key, value, { ifVersion: entry.version }) replaces the value only when the key still has the version you read. If another writer got there first, the write resolves false — re-read and retry.
• Compare-and-delete. delete(key, { ifVersion: entry.version }) removes the key only when it is unchanged since your read.

A failed precondition is not an error: the call resolves false and nothing is written. Errors are reserved for real problems — passing a version that belongs to a different key throws an invalid-input error, since versions are bound to the key they were read from.

Versions are opaque strings. Do not parse, compare, or order them; the only valid use is passing one back as ifVersion. A version read from an entry that has since expired never matches — conditional writes treat expired keys as absent.

Under the hood, Alien maps conditions onto each backend's native atomic primitive: DynamoDB condition expressions, Firestore update-time preconditions, Azure Table Storage entity tags (ETags), and a conditional update in the local database. There is no client-side locking.

Rows written by SDK versions that predate versioned KV (before v3.3.10) lack version metadata and are rejected on read rather than migrated.

Limits

These are enforced by Alien on all platforms:

Scan Semantics

Scan operations have intentionally weak guarantees to remain portable:

• Unordered. Results may arrive in any order.
• May contain duplicates. Your application must deduplicate.
• Cursors are ephemeral. Do not persist or share cursors.
• Not a snapshot. Concurrent writes may or may not appear in results.

Platform Details

AWS (DynamoDB)

• On-demand billing (pay-per-request). No capacity planning needed.
• 16 hash buckets for load distribution (transparent to your code).
• TTL: physical deletion within ~48 hours of expiry.
• Per-partition throughput: 3,000 RCU + 1,000 WCU/second.

GCP (Firestore)

• Always strongly consistent. Only the default database is used.
• TTL: physical deletion within ~24 hours of expiry.
• Ramp-up required: starts at ~500 writes/sec, increases 50% every 5 minutes.

Azure (Table Storage)

• 16 partition buckets for load distribution.
• No native TTL. Alien filters expired items on read, but they are never physically deleted.
• Per-partition throughput: 2,000 entities/second.

Kubernetes / On-Prem

KV is not provisioned by Alien on Kubernetes. The cluster operator provides the backing service (Redis, DynamoDB, etc.) and configures it via Helm values.

The guarantees above (consistency, durability, TTL behavior) depend entirely on the backing service. Alien enforces the limits (key size, value size, charset) regardless of platform.

Local

• Backed by an embedded SQLite database (localkv.sqlite in the data directory). Data persists across restarts and is safe across multiple processes (WAL mode).
• TTL: exact lazy deletion — expired items removed when accessed.
• Scan returns sorted results. This is a local implementation detail — do not rely on ordering in production code.
• Local stores written before v3.3.10 use an older on-disk format and are rejected rather than migrated — delete the local data directory to start fresh.

Design Decisions

512-byte key limit. DynamoDB supports 2,048-byte keys, but Azure Table Storage is more constrained. Alien enforces 512 bytes for portability.

24 KiB value limit. DynamoDB allows 400 KB, Firestore 1 MiB. Alien enforces 24 KiB to encourage small, fast lookups and Storage for larger objects.

Restricted key charset. Azure Table Storage disallows many special characters. Alien restricts the charset globally so keys are valid on every platform.