Quickstart

harness embeds StreamStack server, runs end-to-end scenarios over HTTP against S3 bucket. Confirms bucket, credentials, and local build are working.

Prerequisites are in Installation: JDK 21, S3 bucket, and AWS credentials (Supports SSO).

Run Harness

./gradlew :harness:run --args="--bucket my-bucket --region us-east-1 matrix"

Harness starts server on random local port, exercises API against bucket, and prints PASS or FAIL for each scenario. Bucket objects removed at end unless --keep is set.

Successful run ends with:

matrix passed (11 scenarios)

Scenarios

Scenario	Checks
append-seal-read	Open a stream, append, seal, read back by cursor
keyed-dedup-latest	Keyed records, deduplicated and latest-per-key reads
paging	Cursor paging across a large append
subscription	Named subscription, poll, and advance
long-poll	Subscription wait until a new commit lands
fencing	Writer fencing rejects stale appends
resume-after-restart	Resume an unsealed stream after server restart
discard-and-repair	Discard unsealed streams and repair a partial seal
compaction	Compact the commit log prefix
retention-and-export	Retention policy and object-store export

Harness Flags

Flag	Purpose
--bucket	S3 bucket name (required)
--region	AWS region (defaults to the SDK region chain)
--endpoint	S3 endpoint override for MinIO or other compatible stores
--keep	Leave bucket objects after the run
--lease-ttl	Writer lease TTL in seconds (default 10)

Optional Smoke Test

Short ingest and read-back smoke test after matrix:

./gradlew :harness:run --args="--bucket my-bucket --region us-east-1 load --records 10000"

The load command reports ingest throughput, seal latency, heap use, SQLite size, and a read-back verification pass.

Flag	Purpose
--records	Total records to ingest (default 10,000)
--batch	Records per append batch (default 500)
--record-bytes	Payload size per record in bytes (default 256)
--commit-records	Records per sealed commit (default 100,000)
--keyed	Distinct key space; 0 for keyless records (default 0)
--in-flight-bytes	Max unacked payload bytes for pipelined appends; 0 syncs each append (default 0)
--skip-read	Skip the read-back verification pass