TinyKV

Embedded Bitcask Key-Value Engine (Java 21)

Live instance: https://kv.wavebeef.com

System Status

Status: checking...
Active Keys: -
Total Disk Usage: -
Active Segments: -
Dead / Obsolete Space: - (-)
Sync Policy: SYNC_EVERY_APPEND (Group Commit fsync)

Console

Presets:

Response

Status: - | Latency: -

(no query executed yet)

API Endpoints

Method	Endpoint	Description	Status Codes
`GET`	`/`	This console	200 OK
`GET`	`/healthz`	Kubernetes liveness probe	200 OK
`GET`	`/readyz`	Kubernetes readiness probe	200 OK
`GET`	`/api/v1/keys/{key}`	Retrieve value for key	200 OK, 404 Not Found
`PUT`	`/api/v1/keys/{key}`	Store value for key	200 OK
`DELETE`	`/api/v1/keys/{key}`	Delete key (append tombstone)	204 No Content, 404 Not Found
`GET`	`/api/v1/stats`	Storage engine telemetry	200 OK
`POST`	`/api/v1/compact`	Trigger background compaction	200 OK

cURL Examples

# Store a key
curl -X PUT https://kv.wavebeef.com/api/v1/keys/user:101 -d '{"name":"Julian"}'

# Read a key
curl https://kv.wavebeef.com/api/v1/keys/user:101

# View database metrics
curl https://kv.wavebeef.com/api/v1/stats

# Delete key
curl -X DELETE https://kv.wavebeef.com/api/v1/keys/user:101

# Run compaction
curl -X POST https://kv.wavebeef.com/api/v1/compact

Architecture Notes

Bitcask Engine: Active Write-Ahead Log (WAL) for append-only sequential writes + in-memory hash index mapping keys to segment file offsets.
O(1) Reads: Single disk seek directly to byte coordinates without scanning files.
Crash Safety: 22-byte binary framing with CRC-32 checksum per record. Partial/torn writes auto-truncated on boot.
Group Commit: Coalesces concurrent fsync requests into micro-batches for high durable write throughput.
Online Compaction: Dead space reclaimed into consolidated segments with companion .hint files for millisecond cold boots.
Zero Dependencies: Implemented purely on Java 21 standard library and Virtual Threads.

Repository: github.com/ParcivalLTD/TinyKV | Runtime: Java 21 Temurin | Deployment: Coolify / kind