Fluss Gateway Testbed

A Rust black-box test tool for Fluss Gateway correctness, durable write verification, resource-limited performance measurement, and reproducible evidence.

What works today

• One self-contained YAML defines one performance test: target, image identity, resource budget, table, data model, load, assertions, outputs, and cleanup.
• Deterministic Rust generators implement YCSB-style KV, Apache Beam Nexmark-style Log, and Apache Fluss IoT-style KV workloads.
• The open-loop runner measures request/row/byte throughput, latency, scheduler lag, errors, drops, and container CPU/memory/PID/network usage.
• A separate fluss-rs-oracle reads persisted Log and KV state directly while the Gateway is stopped.
• All drivers, generators, collectors, and report writers are Rust. Python is not required.

Rust 1.88 or newer and Docker Compose are required for the checked-in local topology.

Performance test quick start

Each file under tests/ is runnable as-is and is also a copyable template. ycsb-kv is the recommended first test.

cargo run --bin fluss-testbed -- list
cargo run --bin fluss-testbed -- validate tests/ycsb-kv.yaml
cargo run --bin fluss-testbed -- plan tests/ycsb-kv.yaml

docker compose -f profiles/limited-local.compose.yaml up -d --wait --wait-timeout 180
cargo run --release --bin fluss-testbed -- run tests/ycsb-kv.yaml
docker compose -f profiles/limited-local.compose.yaml down

To create a custom test, copy one YAML and edit it. The schema is strict: unknown fields and invalid combinations fail during validate, before any target state is changed. plan shows the rate ladder, preload size, scheduled rows, maximum offered throughput, and estimated duration without contacting Docker or Gateway.

The runner refuses to measure if the running Gateway image does not match the configured tag/architecture/revision, or if effective cgroup CPU, memory, and PID limits differ from the YAML. It writes the original and resolved test specs alongside JSON, optional JSONL/Prometheus snapshots, and an optional Markdown resource/maximum-throughput report.

See Single-file performance tests for the YAML model and workload recommendations.

Independent persisted read-back

The durable flow writes through Gateway, stops Gateway, and reads the resulting Log and Primary Key state through the pinned fluss-rs client. See Durable read-back for the exact commands and assertions.

Design references

• Current V1 design
• API E2E design
• Write benchmark behavior

License

Licensed under the Apache License, Version 2.0.