Skip to content

v1.3.0

Latest

Choose a tag to compare

@github-actions github-actions released this 20 Aug 11:50
641f282

#Tellstone v1.3.0

This release adds WAL encryption, snapshot compaction, and transparent plaintext-to-encrypted migration — bringing full at-rest encryption to the persistence layer with zero-downtime upgrades.

Highlights

  • Encrypted WAL: Every write-ahead log record is encrypted with ChaCha20-Poly1305 when --enable-encryption is active. Encrypted WALs carry a 4-byte TSW\x01 magic header and use counter-based nonces with a durable sidecar file (shard_NNN.nonce) for crash-safe nonce management.
  • Snapshot compaction: Fork-based background snapshots capture the full in-memory engine state to a compact binary file, then truncate the WAL. Configurable via --snapshot-interval (time-based) and --snapshot-bytes (size-based). On startup, snapshots are loaded first, then only the post-snapshot WAL is replayed — dramatically reducing warm-up time.
  • Encrypted snapshots: Snapshot files store encrypted values when at-rest encryption is active. A 16-byte key fingerprint in the snapshot header prevents restoring a snapshot taken with a different encryption key.
  • Plaintext-to-encrypted migration: Existing plaintext WALs are automatically migrated to encrypted format on startup when --enable-encryption is enabled. The migration replays all plaintext records, rewrites them as encrypted entries in an atomic temp-file swap, and resumes normal encrypted operation. No manual intervention required.
  • Zero-copy replay: New SetFromBuffer and SetRaw engine methods eliminate allocations during WAL replay and encrypted snapshot restore, reducing GC pressure on cold start.

Install

APT (Debian/Ubuntu)

curl -fsSL https://saxy.github.io/tellstone-apt/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/tellstone.gpg
echo "deb [signed-by=/usr/share/keyrings/tellstone.gpg] https://saxy.github.io/tellstone-apt stable main" \
  | sudo tee /etc/apt/sources.list.d/tellstone.list
sudo apt update && sudo apt install tellstone

Homebrew (macOS/Linux)

brew tap Saxy/tellstone-tap
brew install --cask tellstone

Container images

# Production (distroless, single listener)
docker pull ghcr.io/saxy/tellstone:1.3.0
docker run -d -p 9988:9988 ghcr.io/saxy/tellstone:1.3.0

# Development (multi-stage, binary + RESP)
docker pull ghcr.io/saxy/tellstone:1.3.0-dev
docker run -d -p 9988:9988 -p 6379:6379 ghcr.io/saxy/tellstone:1.3.0-dev

Binary downloads

Pre-built binaries for Linux, macOS, and Windows (amd64/arm64) are available on the GitHub Releases page.

Build from source

git clone https://github.com/Saxy/Tellstone
cd Tellstone
task build   # -> ./bin/tellstone

What's included

Binaries

OS Arch Archive
Linux amd64 tellstone_v1.3.0_linux_amd64.tar.gz
Linux arm64 tellstone_v1.3.0_linux_arm64.tar.gz
macOS amd64 tellstone_v1.3.0_darwin_amd64.tar.gz
macOS arm64 tellstone_v1.3.0_darwin_arm64.tar.gz
Windows amd64 tellstone_v1.3.0_windows_amd64.zip

Packages

  • .deb for Debian/Ubuntu (amd64, arm64)

Container images

  • ghcr.io/saxy/tellstone:1.3.0 — production (distroless)
  • ghcr.io/saxy/tellstone:1.3.0-dev — development (multi-stage)
  • Platforms: linux/amd64, linux/arm64

Checksums

SHA-256 checksums are provided in checksums.txt.

Configuration

New flags and settings in v1.3.0 (all previous flags remain unchanged):

Flag Env Default Description
--snapshot-interval TSD_SNAPSHOT_INTERVAL 0 (disabled) Time between periodic snapshots (e.g. 5m)
--snapshot-bytes TSD_SNAPSHOT_BYTES 64MiB WAL size threshold that triggers a snapshot

Both flags require --enable-persistence. Setting both to zero disables snapshot compaction entirely (the default).

Upgrading from v1.2.0

v1.3.0 is fully backward-compatible with v1.2.0 data files:

  • Plaintext WALs (written by v1.2.0 without --enable-encryption) are automatically migrated to encrypted format when --enable-encryption is enabled. No manual steps required.
  • Snapshot files from v1.2.0 do not exist (snapshots are new in v1.3.0). On first startup, the full WAL is replayed into memory, and the first snapshot is created automatically if snapshots are configured.
  • Encrypted WALs are not affected by the snapshot feature and continue to work as before.
  • Nonce sidecar files (shard_NNN.nonce) are created automatically on first encrypted write. Existing encrypted WALs recover the nonce counter from WAL replay.

If you are upgrading from a version earlier than v1.2.0, upgrade to v1.2.0 first.

Changelog

Features

  • Encrypted WAL: ChaCha20-Poly1305 encryption for all WAL records (TSW\x01 magic header, counter-based nonces)
  • Nonce counter sidecar files (shard_NNN.nonce) for crash-safe nonce durability
  • Snapshot compaction: fork-based background snapshots with atomic writes and WAL truncation
  • Encrypted snapshots with key fingerprint header to prevent cross-key restores
  • Automatic plaintext-to-encrypted WAL migration on startup (atomic temp-file swap, crash-safe)
  • Time-based snapshot trigger (--snapshot-interval)
  • Size-based snapshot trigger (--snapshot-bytes)
  • Zero-copy SetFromBuffer for WAL replay and SetRaw for encrypted snapshot restore
  • Two-phase startup: load snapshot first, then replay post-snapshot WAL

Bug fixes

  • CloseShard only removes from shard map if the caller holds the current handle, preserving replacement handles during migration

Infrastructure

  • Backward-compatibility unit tests for v1.2.0 plaintext WALs
  • Manual backward-compatibility test script (8 phases, 26 assertions): v1.2.0→dev upgrade, crash recovery, plaintext-to-encrypted migration

Links

License

Apache-2.0