CLI Reference

The TopGun Rust server currently provides a test-server binary for integration testing. The primary configuration surface is programmatic via Rust structs (NetworkConfig and ServerConfig) for embedding the server in applications.

Future Production Binary

A production binary with full CLI argument parsing (e.g., —port, —db-url, —cluster-peers) is planned for a future release. Currently, the server is configured via environment variables and programmatic Rust structs.

test-server Binary

Integration test binary that wires all 7 domain services with in-memory storage.

terminal

# Build and run the test server
cargo run --bin test-server --release

# Output: PORT=<assigned-port>
# The server prints the bound port to stdout for test harness consumption.

The test-server binary:

Wires all 7 domain services (CRDT, Sync, Query, Messaging, Coordination, Search, Persistence)
Uses NullDataStore for in-memory storage (no PostgreSQL dependency)
Uses a hardcoded JWT secret (test-e2e-secret) for authentication
Prints PORT=<number> to stdout so the test harness can connect
Listens for SIGTERM/SIGINT for graceful shutdown

Environment Variables

The server reads three environment variables at startup:

terminal

# Custom port (default: 0 = OS-assigned)
PORT=8080 cargo run --bin test-server --release

# Debug logging for the server module
RUST_LOG=topgun_server=debug cargo run --bin test-server --release

# Custom admin dashboard path
TOPGUN_ADMIN_DIR=/path/to/dashboard cargo run --bin test-server --release

Variable	Description	Default
PORT	TCP port for the server. `0` means OS-assigned ephemeral port.	0
TOPGUN_ADMIN_DIR	Path to the admin dashboard static files served at `/admin/*`.	./admin-dashboard/dist
RUST_LOG	Tracing filter directive for `tracing-subscriber`. Supports module-specific filters like `topgun_server=debug`.	info

Programmatic Configuration

For embedding the TopGun server in a Rust application, configuration is done via two structs:

NetworkConfig

Controls the HTTP/WebSocket server: bind address, TLS, CORS, timeouts, and per-connection settings.

config.rs

use topgun_server::network::config::{NetworkConfig, TlsConfig, ConnectionConfig};
use std::time::Duration;
use std::path::PathBuf;

// Default configuration (port 0 = OS-assigned)
let config = NetworkConfig::default();

// Custom configuration
let config = NetworkConfig {
    host: "0.0.0.0".to_string(),
    port: 8080,
    tls: Some(TlsConfig {
        cert_path: PathBuf::from("/etc/tls/cert.pem"),
        key_path: PathBuf::from("/etc/tls/key.pem"),
        ca_cert_path: None,
    }),
    connection: ConnectionConfig {
        outbound_channel_capacity: 256,
        send_timeout: Duration::from_secs(5),
        idle_timeout: Duration::from_secs(60),
        ws_write_buffer_size: 131_072,     // 128 KB
        ws_max_write_buffer_size: 524_288, // 512 KB
    },
    cors_origins: vec!["https://myapp.com".to_string()],
    request_timeout: Duration::from_secs(30),
};

ServerConfig

Controls the operation routing framework: node identity, timeouts, concurrency, and partitioning.

config.rs

use topgun_server::service::config::ServerConfig;

let config = ServerConfig {
    node_id: "node-1".to_string(),
    default_operation_timeout_ms: 30_000,
    max_concurrent_operations: 1000,
    gc_interval_ms: 60_000,
    partition_count: 271, // default PARTITION_COUNT
    ..ServerConfig::default()
};

Docker

Run the server as a Docker container using environment variables for configuration:

terminal

docker run -d \
  -p 8080:8080 \
  -e PORT=8080 \
  -e RUST_LOG=topgun_server=info \
  -e TOPGUN_ADMIN_DIR=/app/admin-dashboard/dist \
  topgunbuild/topgun-server:latest

Server API

Adapters