herolib-clients

A unified client library providing database clients, messaging clients, and API clients.

Documentation

• API Documentation (docs.rs)
• Crates.io

Features

• Pure Rust: No C dependencies, safe and portable
• Builder Pattern: All clients use fluent builder APIs for configuration
• Async Support: Built on Tokio for efficient async operations
• Rhai Integration: Full scripting support for all clients
• Connection Management: Automatic connection handling, pooling, and reconnection

Clients

Installation

Add to your Cargo.toml:

[dependencies]
herolib-clients = "0.1"

Interactive TUI REPL

The package includes a full-featured interactive REPL with:

• Tab Completion - Complete functions, methods, and Rhai keywords
• Syntax Highlighting - Color-coded keywords, functions, strings, and more
• Command History - Persistent history saved to ~/.herolib_clients_history
• Multi-line Input - End lines with \ or use unclosed braces
• Module-specific Help - Detailed help for each client module

# Build and run the REPL
cargo run --bin repl

# Or use the run.sh script
./run.sh

Example session:

  herolib-clients REPL v0.1.5

Type /help for commands, Tab to complete, /quit to exit

>> let client = redis_client().host("localhost").port(6379).build()
>> client.set("key", "value")
>> print(client.get("key"))
value
>> /redis        # Show Redis-specific help
>> /functions    # List all available functions
>> /methods      # List all builder and client methods
>> /quit

REPL Commands:

Quick Start

Rust Usage

use herolib_clients::{mqtt, redis, postgres};

// MQTT - Publish with reliable delivery
use herolib_clients::mqtt::{MqttClient, MqttClientConfigBuilder, DeliveryMode};

let config = MqttClientConfigBuilder::new()
    .host("localhost")
    .port(1883)
    .credentials("user", "pass")
    .clean_session(false)
    .build();

let client = MqttClient::new(config)?;
client.connect().await?;
client.publish_with_delivery("topic", "message", DeliveryMode::ExactlyOnce).await?;

// Redis - Key-value operations
use herolib_clients::redis::{RedisConfigBuilder, execute};

let config = RedisConfigBuilder::new()
    .host("localhost")
    .port(6379)
    .password("secret")
    .build()?;

let mut cmd = redis::cmd("SET");
cmd.arg("key").arg("value");
execute(&mut cmd)?;

// PostgreSQL - Query execution
use herolib_clients::postgres::{PostgresConfigBuilder, query};

let config = PostgresConfigBuilder::new()
    .host("localhost")
    .port(5432)
    .user("postgres")
    .password("secret")
    .database("mydb")
    .build()?;

let rows = query("SELECT * FROM users WHERE id = $1", &[&1])?;

Rhai Scripting

All clients use the builder pattern for configuration in Rhai scripts:

// MQTT with QoS 2 (exactly once delivery)
let mqtt = mqtt_client()
    .host("localhost")
    .port(1883)
    .credentials("user", "pass")
    .clean_session(false)
    .build();
mqtt.connect();
mqtt.subscribe("orders/#", 2);
mqtt.publish("orders/new", "order-123", 2);
mqtt.disconnect();

// Redis with builder pattern
let redis = redis_client()
    .host("localhost")
    .port(6379)
    .password("secret")
    .db(0)
    .build();
redis.set("key", "value");
let value = redis.get("key");
redis.hset("hash", "field", "value");

// PostgreSQL with builder pattern
let pg = postgres_client()
    .host("localhost")
    .port(5432)
    .user("postgres")
    .password("secret")
    .database("mydb")
    .build();
let rows = pg.query("SELECT * FROM users");
pg.execute("INSERT INTO users (name) VALUES ('John')");

// Hetzner with builder pattern
let hetzner = hetzner_client()
    .username("user")
    .password("pass")
    .build();
let servers = hetzner.get_servers();
for server in servers {
    print(`Server: ${server.server_name}`);
}

// Vast.ai GPU search with builder pattern
let query = search_query()
    .available()
    .gpu_name("RTX_4090")
    .min_reliability(0.95)
    .limit(10)
    .order_by("dph_total", "asc");

let offers = search_offers(query);
for offer in offers {
    print(`${offer.num_gpus}x ${offer.gpu_name} @ $${offer.dph_total}/hr`);
}

// Instance management
let instances = list_instances();
let ssh_keys = list_ssh_keys();

// OpenCode - AI coding assistant
opencode_url_set("http://127.0.0.1:2467");
let project = opencode_project_current();
print(`Project: ${project.worktree}`);

let session = opencode_session_create_with_title("My Session");
let response = opencode_prompt(session.id, "Write a hello world function");

let files = opencode_file_list_path("src");
for f in files {
    print(`${f.name}`);
}

// HeroDB - Modular database with multiple backends
herodb_connect_default();
herodb_create_instance("my_cache", "INMEMORY", "");
herodb_select(1);
herodb_set("key", "value");
let val = herodb_get("key");

// Vector search with LanceDB backend
herodb_create_instance("vectors", "LANCEDB", "/tmp/vectors");
herodb_lancedb_add("doc:1", [0.1, 0.2, 0.3, 0.4]);
let results = herodb_lancedb_search([0.1, 0.2, 0.3, 0.4], 5);

// Full-text search with Tantivy backend
herodb_create_instance("search", "TANTIVY", "/tmp/search");
herodb_tantivy_index("doc:1", #{ title: "Hello", body: "World" });
let matches = herodb_tantivy_search("Hello", 10);

Running Rhai Scripts

Use hero-clients to run Rhai scripts directly:

# Build the binary
cargo build --release

# Run a script
./target/release/hero-clients path/to/script.rhai

# With environment variables
VAST_API_KEY=your-key ./target/release/hero-clients rhaiexamples/vastai/search_gpus.rhai

Example scripts are provided in rhaiexamples/:

• herodb/ - HeroDB modular database operations
• hetzner/ - Dedicated server management
• mqtt/ - Message broker operations
• mycelium/ - Mesh network operations
• opencode/ - AI coding assistant operations
• postgres/ - Database operations
• redis/ - Key-value store operations
• vastai/ - GPU marketplace operations

Configuration

All clients support configuration through:

1. Builder Pattern (recommended)
2. Environment Variables

Environment Variables

License

Apache-2.0