scoutquest-rust 1.4.0

Rust SDK for ScoutQuest Service Discovery - Universal service discovery for microservices architectures
Documentation

ScoutQuest Rust SDK

Crates.io Documentation License: MIT

Rust SDK for ScoutQuest Service Discovery - Universal service discovery for microservices architectures.

Features

  • 🔍 Service Discovery: Find and connect to services dynamically
  • 📝 Service Registration: Register your services with health checks
  • ⚖️ Load Balancing: Multiple strategies (Random, Round-Robin, Healthy-Only)
  • 🌐 HTTP Client: Built-in HTTP client with automatic service discovery
  • 🏷️ Metadata & Tags: Rich service metadata and tag-based filtering
  • 💓 Health Monitoring: Automatic heartbeat and health check support
  • 🔄 Retry Logic: Configurable retry mechanism for resilience
  • 📊 Tracing Support: Built-in logging and tracing integration

Installation

Add this to your Cargo.toml:

[dependencies]
scoutquest-rust = "1.0.0"

Quick Start

use scoutquest_rust::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client
    let client = ServiceDiscoveryClient::new("http://localhost:8080")?;

    // Register a service
    let options = ServiceRegistrationOptions::new()
        .with_tags(vec!["api".to_string(), "v1".to_string()])
        .with_metadata({
            let mut metadata = std::collections::HashMap::new();
            metadata.insert("version".to_string(), "1.2.3".to_string());
            metadata
        });

    client.register_service("user-service", "localhost", 3000, Some(options)).await?;

    // Discover services
    let instances = client.discover_service("payment-service", None).await?;

    // Make HTTP calls to discovered services
    let response: serde_json::Value = client.get("payment-service", "/api/balance").await?;

    // Graceful shutdown
    client.deregister().await?;
    Ok(())
}

Advanced Usage

Load Balancing Strategies

use scoutquest_rust::*;

let client = ServiceDiscoveryClient::new("http://localhost:8080")?;

// Service discovery returns a ready-to-use service instance
let instance = client.discover_service("api-service", None).await?;

// Use the instance to make HTTP calls
let response = client.get(&instance, "/users", None).await?;

Service Discovery with Filters

let discovery_options = ServiceDiscoveryOptions::new()
    .with_healthy_only(true)
    .with_tags(vec!["production".to_string(), "api".to_string()])
    .with_limit(5);

let instances = client.discover_service("user-service", Some(discovery_options)).await?;

HTTP Client with Custom Configuration

// GET request
let users: serde_json::Value = client.get("user-service", "/api/users").await?;

// POST request
let new_user = serde_json::json!({
    "name": "John Doe",
    "email": "john@example.com"
});
let response: serde_json::Value = client.post("user-service", "/api/users", new_user).await?;

// Custom request with specific load balancing
let response: serde_json::Value = client.call_service(
    "user-service",
    "/api/health",
    reqwest::Method::GET,
    None,
    LoadBalancingStrategy::HealthyOnly
).await?;

Health Checks

use scoutquest_rust::*;

let health_check = HealthCheck {
    url: "/health".to_string(),
    interval_seconds: 30,
    timeout_seconds: 5,
    method: "GET".to_string(),
    expected_status: 200,
    headers: None,
};

let options = ServiceRegistrationOptions::new()
    .with_health_check(health_check);

client.register_service("api-service", "localhost", 8080, Some(options)).await?;

Configuration

Create a client with custom configuration:

use std::time::Duration;

let client = ServiceDiscoveryClient::with_config(
    "http://localhost:8080",
    Duration::from_secs(30),  // HTTP timeout
    3,                        // Retry attempts
    Duration::from_secs(1),   // Retry delay
)?;

Examples

See the examples/ directory for complete examples:

Run examples with:

cargo run --example basic_usage
cargo run --example http_client
cargo run --example load_balancing

Error Handling

The SDK provides comprehensive error types:

use scoutquest_rust::ScoutQuestError;

match client.discover_service("unknown-service", None).await {
    Ok(instances) => println!("Found {} instances", instances.len()),
    Err(ScoutQuestError::ServiceNotFound { service_name }) => {
        println!("Service {} not found", service_name);
    }
    Err(ScoutQuestError::NetworkError(e)) => {
        println!("Network error: {}", e);
    }
    Err(e) => println!("Other error: {}", e),
}

Testing

Run the test suite:

# Unit tests
cargo test

# Integration tests
cargo test --test integration_tests

# All tests with output
cargo test -- --nocapture

Benchmarks

Run performance benchmarks:

cargo bench

This will benchmark load balancing strategies and other performance-critical operations.

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Support