CLI Tools: Clock & Relay
Relevant source files
The following files were used as context for generating this wiki page:
The clock and relay tools are essential command-line utilities provided by the SeaStreamer ecosystem to facilitate the generation, redirection, and testing of real-time data streams. These tools demonstrate the power of SeaStreamer's backend-agnostic architecture, allowing developers to move data seamlessly between standard I/O (stdio), Kafka, Redis, and local files.
clock serves as a synthetic data generator, producing periodic heartbeat-like messages, while relay acts as a sophisticated bridge that can consume from one streaming backend and produce to another. Together, they provide a powerful mechanism for replaying streams, re-routing traffic between different message brokers, or sinking server-side data to local environments for debugging.
Sources: README.md:144-156, src/lib.rs:161-173
The Clock Tool
The clock utility is a specialized producer tool primarily located within the sea-streamer-stdio package. Its main purpose is to generate a steady stream of messages in a structured JSON format, typically used for heartbeats or interval-based triggering in a stream processing pipeline.
Functionality and Output
The clock program generates messages in the form of { "tick": N }, where N is an incrementing integer. It supports configurable intervals, such as 1s, to control the frequency of message generation.
Sources: README.md:144-147, sea-streamer-stdio/Cargo.toml:48-51
Data Flow
When executed, clock typically outputs to standard out (stdout). This allows it to be piped into other unix utilities or other SeaStreamer CLI tools like relay.
The diagram above shows how the Clock tool acts as a data source for the rest of a SeaStreamer pipeline. Sources: README.md:150-155
The Relay Tool
The relay utility is a backend-agnostic tool located in the sea-streamer-socket package. It leverages the generic trait interfaces of SeaStreamer to provide a "bridge" between any two supported backends.
Architecture and Redirection
The relay program takes an --input URI and an --output URI. Because it is built on sea-streamer-socket, it can resolve these URIs at runtime to the appropriate backend (Kafka, Redis, Stdio, or File) without needing to be recompiled for specific broker types.
Sources: README.md:113-125, sea-streamer-socket/Cargo.toml:35-37
Supported Redirection Patterns
The following table summarizes common patterns used with the relay tool:
| Pattern | Input URI Example | Output URI Example | Use Case |
|---|---|---|---|
| Stdio to Redis | stdio:///clock | redis://localhost:6379/clock | Ingesting local logs/data into Redis |
| Redis to Kafka | redis://localhost:6379/clock | kafka://localhost:9092/clock | Migrating data between brokers |
| Kafka to Stdio | kafka://localhost:9092/clock | stdio:///clock | Replaying server data to local console |
Sources: README.md:150-164
Sequence Flow of Redirection
The following sequence diagram illustrates how relay moves a message from a source (e.g., Kafka) to a destination (e.g., Redis).
Sources: README.md:158-160, src/lib.rs:175-177
Configuration and Execution
Both tools rely on clap for command-line argument parsing and require specific features to be enabled during compilation to function.
Feature Requirements
The CLI binaries are excluded from the default library build to keep the dependency tree lean. They are gated behind the executables feature flag.
| Crate | Binary | Required Features |
|---|---|---|
sea-streamer-stdio | clock | executables |
sea-streamer-socket | relay | executables, backend-kafka, backend-redis |
Sources: sea-streamer-stdio/Cargo.toml:47-51, sea-streamer-socket/Cargo.toml:29-37
Common Command Line Options
While specific options vary, the tools share a common logic for identifying stream locations:
--stream/--input/--output: URIs following the formatscheme://host:port/path. Schemes includekafka,redis,stdio, andfile.--offset: Used byrelayduring consumption (e.g.,startto replay from the beginning of a stream).--interval: Specific toclock, defining the delay between ticks.
Sources: README.md:150-164, sea-streamer-file/src/lib.rs:37-43
Usage Example: Replaying a Stream
A common use case for these tools is replaying a stream from a remote server to a local terminal for inspection. This is achieved by setting the input to a broker URI and the output to a stdio URI.
# Replay the stream from Kafka starting from the earliest available message
relay -- --input kafka://localhost:9092/my_topic --output stdio:///my_topic --offset start
Sources: README.md:162-164
Summary
The clock and relay tools provide the operational "glue" for the SeaStreamer ecosystem. By abstracting the complexities of different streaming protocols into simple CLI commands, they enable rapid prototyping, testing, and data migration across Redis, Kafka, and local environments. Their implementation within the sea-streamer-stdio and sea-streamer-socket crates highlights the project's commitment to backend-agnostic stream processing.