REGISTER Command

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nubskr/walrus/llms.txt

Use this file to discover all available pages before exploring further.

​

Syntax

REGISTER <topic>

​

Wire Format

[4 bytes: length] REGISTER <topic>

[4 bytes: 2] OK

[4 bytes: length] ERR <error message>

​

Behavior

​

Topic Creation

1. The request is routed to the Raft leader
2. A new topic entry is proposed to the Raft cluster
3. Once committed, the topic metadata is replicated to all nodes
4. The first segment (segment 0) is created with an assigned leader node
5. Leadership for the topic rotates round-robin as segments roll over

​

Idempotency

• No duplicate topics are created
• Existing segment assignments remain unchanged
• Safe to call multiple times

​

Examples

​

Interactive Shell

🦭 > REGISTER logs
OK

🦭 > REGISTER metrics
OK

🦭 > REGISTER logs
OK  # Idempotent - succeeds even though topic exists

​

One-off Command

# Register a topic
cargo run --bin walrus-cli -- register logs

# Register with custom node address
cargo run --bin walrus-cli -- --addr 127.0.0.1:9092 register events

​

Programmatic Usage (Rust)

use distributed_walrus::cli_client::CliClient;

#[tokio::main]
async fn main() -> Result<()> {
    let client = CliClient::new("127.0.0.1:9091");
    
    // Register a topic
    client.register("logs").await?;
    
    Ok(())
}

​

Error Cases

​

Missing Topic Name

REGISTER

ERR REGISTER requires a topic

​

Invalid Topic Name

# This will create a topic named "my"
🦭 > REGISTER my topic
OK

​

Cluster Errors

• Raft not ready: ERR raft cluster not initialized
• Connection timeout: ERR connect to 127.0.0.1:9091
• Node unavailable: Connection refused or timeout

​

Cluster Behavior

​

Request Routing

1. Client connects to any node in the cluster
2. If the node is not the Raft leader, it forwards the request
3. Leader commits the topic creation through Raft consensus
4. Response is returned to the client through the original node

​

Metadata Replication

• Metadata is replicated to all nodes via Raft
• All nodes can answer STATE queries for the topic
• The assigned leader node accepts PUT operations
• Segment leadership rotates automatically on rollover

​

Related Commands

• PUT - Append data to a registered topic
• GET - Read data from a topic
• STATE - View topic metadata and segments