Rush Sync Server

Crates.io

🛠 NOTE: Version 0.2.2 on crates.io has a critical bug in language file loading (*.json not embedded correctly). Please use version 0.2.3+ for a stable release!

Rush Sync Server is a modern, modular terminal application written in Rust, featuring an interactive TUI, internationalized interface, color-coded logging, and flexible configuration. Perfect for developers who need a customizable, scriptable terminal UI.

🚀 Installation & Usage

📦 As Binary (End Users) - Version 0.2.3+

# Install directly from crates.io
cargo install rush-sync-server

# Run the application
rush-sync

📚 As Library (Developers) - Version 0.2.3+

Add to your Cargo.toml:

[dependencies]
rush-sync-server = "0.2.3"
tokio = { version = "1.36", features = ["full"] }

Quick Start Examples:

use rush_sync_server::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Option 1: Run with default configuration
    run().await?;
    Ok(())
}

use rush_sync_server::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Option 2: Load config and run
    let config = load_config().await?;
    run_with_config(config).await?;
    Ok(())
}

use rush_sync_server::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Option 3: Use as command handler only
    let handler = create_handler();

    let result = handler.handle_input("version");
    println!("Result: {}", result.message);

    let result = handler.handle_input("perf");
    println!("Performance: {}", result.message);

    Ok(())
}

Advanced Library Usage:

use rush_sync_server::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Custom configuration
    let mut config = load_config().await?;
    config.poll_rate = std::time::Duration::from_millis(8); // 125 FPS
    config.typewriter_delay = std::time::Duration::from_millis(1); // Ultra-fast

    // Run with custom screen manager
    let mut screen = ScreenManager::new(&config).await?;
    screen.run().await?;

    Ok(())
}

🛠 From Source (Development)

git clone https://github.com/LEVOGNE/rush.sync.server
cd rush.sync.server
cargo build --release

# Run as binary
cargo run --release

# Or install locally
cargo install --path .
rush-sync

✅ Features

Interactive terminal UI with an asynchronous event loop (Tokio)
Color-coded logging with level detection (ERROR, WARN, INFO, DEBUG, TRACE)
Runtime log-level switching with persistent config saving
Performance monitoring with real-time FPS & config analysis
Internationalization (i18n):
- Multilingual markers are automatically mapped to standard colors ([SPRACHE], [IDIOMA] → lang → Cyan)
- Dynamic language switching at runtime (German/English)
- Automatic language detection and config persistence
Typewriter effect & blinking cursor (configurable/disableable)
Auto-scroll & scrollable message history
Input history & full cursor navigation
Modular command handler with extensible plugin system
Configurable design & prompt via TOML with performance optimization
Unicode support (grapheme-based)
Restart function without external process restart
Smart bounds checking with automatic config correction

💻 Available Commands

Command	Description	Examples
`version` / `ver`	Show application version	`version`
`lang` / `language`	Switch language (EN/DE) with config persistence	`lang de`, `lang en`
`clear` / `cls`	Clear all messages	`clear`
`exit` / `q`	Exit with confirmation	`exit`
`restart`	Internal restart (reloads config)	`restart`, `restart --force`
`history -c`	Clear input history	`history -c`
`log-level`	Change log level (runtime + persistent)	`log-level 3`, `log-level debug`
`perf` / `performance`	Show performance & config status	`perf`, `performance`

Log-Level Command Details

log-level           # Show current level
log-level 3         # Set to INFO level
log-level DEBUG     # Set to DEBUG level
log-level -h        # Show help

# Available levels:
# 1 = ERROR   (Only critical errors)
# 2 = WARN    (Warnings and errors)
# 3 = INFO    (General information) [DEFAULT]
# 4 = DEBUG   (Debug information)
# 5 = TRACE   (Very detailed tracing)

Performance Command Details

perf                # Show full performance report
performance         # Same as perf
stats               # Same as perf
perf -h             # Show help

Performance Report includes:

Current FPS (based on poll_rate)
Typewriter speed (chars/second)
Config values & file location
Performance recommendations
Related commands

⌨️ Keyboard Shortcuts

Key	Function
`↑ / ↓`	Navigate input history
`← / →`	Move cursor in text
`Home / End`	Jump to start / end of input
`Shift + ↑ / ↓`	Scroll line by line
`Page Up / Down`	Scroll page by page
`Enter`	Confirm input
`ESC` (twice)	Exit the program

⚙️ Configuration

The rush.toml file is automatically created in the .rss directory on first start.

Complete Default Configuration

[general]
max_messages = 100
# Typewriter-Effekt: 50ms = 20 Zeichen/Sekunde (empfohlen: 30-100ms)
typewriter_delay = 50
input_max_length = 100
max_history = 30
# Poll-Rate: 16ms = 60 FPS (empfohlen: 16-33ms, NICHT unter 16!)
poll_rate = 16
log_level = "info"

[theme]
input_text = "Black"
input_bg = "White"
cursor = "Black"
output_text = "DarkGray"
output_bg = "Black"

[prompt]
text = "/// "
color = "Black"

[language]
current = "en"

# =================================================================
# PERFORMANCE-HINWEISE:
# =================================================================
# poll_rate:
#   - 16ms = 60 FPS (EMPFOHLEN für flüssiges UI)
#   - 33ms = 30 FPS (akzeptabel für langsamere Systeme)
#   - 1-15ms = NICHT empfohlen (hohe CPU-Last!)
#   - 0ms = CRASH! (Tokio interval panic)
#
# typewriter_delay:
#   - 50ms = 20 Zeichen/Sekunde (gut lesbar)
#   - 30ms = 33 Zeichen/Sekunde (schnell)
#   - 100ms = 10 Zeichen/Sekunde (langsam)
#   - 0ms = Typewriter-Effekt deaktiviert
# =================================================================

Performance Optimization

Recommended Values:

poll_rate = 16 (60 FPS - optimal)
poll_rate = 33 (30 FPS - good for slower systems)
typewriter_delay = 0 (disabled) or 30-100 (enabled)

Automatic Bounds Checking:

Invalid values are automatically corrected on startup
Corrected values are saved back to config
Performance warnings for critical settings

Colors (COLOR_MAP)

Supported: Black, White, Gray, DarkGray, Red, Green, Blue, Yellow, Magenta, Cyan, LightRed, LightGreen, LightBlue, LightYellow, LightMagenta, LightCyan

Smart Color Categories:

error → Red
warning / warn → Yellow
info → Green
debug → Blue
lang / language → Cyan
version → LightBlue

i18n translations are automatically mapped to standard keys (e.g., "Sprache", "Idioma", "Язык" → lang → Cyan).

🗂 Project Structure

src/
├── core/        # Core logic (Config, Error, Prelude, Constants)
├── ui/          # Terminal UI (ScreenManager, TerminalManager, Widgets)
├── input/       # Input handling (Keyboard, EventHandler)
├── output/      # Logging, MessageManager, Color, Performance
├── commands/    # Modular commands (exit, lang, history, restart, log-level, performance)
├── setup/       # Auto-configuration (TOML setup)
└── i18n/        # Internationalization (German/English)
    └── langs/   # Language files (de.json, en.json)

🛠 Technical Details

Event loop: Asynchronous (Tokio) → split into:
- handle_input_event
- handle_tick_event
- handle_resize_event
Logging:
- Global AppLogger (intercepts all log::* calls)
- Runtime log-level switching with config persistence
- LogMessage stores level + text → color-coded output
Performance Monitoring:
- Real-time FPS calculation based on poll_rate
- Typewriter speed analysis (chars/second)
- Config value validation with automatic correction
- Performance recommendations based on system capabilities
Internationalization:
- get_marker_color automatically maps translated markers to standard categories
- Smart fallback for unknown display categories
- Persistent language switching with config save
Restart: Internal, without external process restart
Memory Management: Bounded message buffers with automatic cleanup

🧪 Testing

cargo test
RUST_LOG=debug cargo test

# Test specific components
cargo test command_system_tests
cargo test performance
cargo test config

Available tests: ✔ Commands (including new log-level & performance) ✔ Event loop ✔ Config setup & bounds checking ✔ i18n translations (German/English) ✔ Performance monitoring ✔ Language switching

🎛 Advanced Usage

Performance Monitoring

# Show detailed performance report
perf

# Output example:
📊 PERFORMANCE & CONFIG STATUS:
🎯 Poll Rate: 16ms (60.0 FPS) ✅ Optimal
⌨️ Typewriter: 50ms (20.0 chars/sec)
📈 Max Messages: 100
📜 Max History: 30
🎨 Log Level: INFO
📍 Config: rush.toml

💡 EMPFEHLUNGEN:
• poll_rate: 16ms (optimal) oder 33ms (gut)
• typewriter_delay: 0ms (aus) oder 30-100ms
• Für beste Performance: poll_rate >= 16ms

Dynamic Log-Level Management

# Runtime log-level switching (saved to config)
log-level debug    # Switch to debug mode
log-level 1        # Switch to error-only
log-level info     # Back to default

Language Switching

lang de            # Switch to German
lang en            # Switch to English
lang               # Show current language & available options

Library Integration Examples

Create Custom Commands

use rush_sync_server::*;

// Define a custom command
#[derive(Debug)]
struct HelloCommand;

impl Command for HelloCommand {
    fn name(&self) -> &'static str { "hello" }
    fn description(&self) -> &'static str { "Say hello" }
    fn matches(&self, command: &str) -> bool { command == "hello" }

    fn execute_sync(&self, args: &[&str]) -> Result<String> {
        let name = args.first().unwrap_or(&"World");
        Ok(format!("Hello, {}!", name))
    }
}

#[tokio::main]
async fn main() -> Result<()> {
    // Add custom command to existing registry
    let mut handler = create_handler();
    handler.add_command(HelloCommand);

    let result = handler.handle_input("hello Rust");
    println!("{}", result.message); // "Hello, Rust!"

    Ok(())
}

Use with Custom UI

use rush_sync_server::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Load config
    let config = load_config().await?;

    // Create handler for command processing
    let handler = create_handler();

    // Simple CLI loop (instead of full TUI)
    loop {
        let mut input = String::new();
        std::io::stdin().read_line(&mut input).unwrap();

        let result = handler.handle_input(&input.trim());
        println!("{}", result.message);

        if result.should_exit {
            break;
        }
    }

    Ok(())
}

🗺 Roadmap

Mouse support (scroll & selection)
Split-screen & tabs
Syntax highlighting
~~Plugin system for custom commands~~ ✓ Implemented
~~Live log-level configuration~~ ✓ Implemented
~~Performance monitoring~~ ✓ Implemented
~~Binary & Library distribution~~ ✓ Implemented (v0.2.3+)
Live UI configuration changes
Config hot-reload without restart
Custom color themes
Command aliases & macros

📊 What's New in v0.2.3

✅ Binary distribution: Install with cargo install rush-sync-server
✅ Library API: Use as dependency in your Rust projects
✅ Convenience functions: run(), load_config(), create_handler()
✅ Public exports: Access to Config, CommandHandler, ScreenManager
✅ Custom command support: Extend functionality with your own commands
✅ Hybrid usage: Use as standalone app OR integrate into your project

📜 License

Dual-Licensing Model

This project is distributed under a dual license:

Community License (GPLv3) – free for private and non-commercial use. See LICENSE.
Commercial License – required for any commercial use. See COMMERCIAL_LICENSE.md.

Contact for commercial licensing: 📧 l.ersen@icloud.com

🤝 Contributing

Fork this repository
Create a feature branch
Commit changes + add tests
Submit a pull request

Development Guidelines:

Follow performance recommendations (poll_rate >= 16ms)
Add i18n support for new features (de.json + en.json)
Include performance tests for new commands
Update config bounds checking for new parameters

rush-sync-server 0.2.4