Complete API documentation for Orbit-RS distributed database system

Getting Started with the API

Orbit-RS provides multiple API interfaces for different use cases:

Client APIs

Protocol APIs

API Documentation Sections

Orbit Client API

The primary Rust client library for interacting with Orbit-RS clusters.

use orbit_client::{OrbitClient, OrbitClientConfig};

// Create a client
let client = OrbitClient::builder()
    .with_namespace("my-app")
    .with_server_urls(vec!["http://localhost:8080".to_string()])
    .build()
    .await?;

// Get an actor reference
let actor_ref = client.actor_reference::<MyActor>(
    Key::StringKey { key: "actor-id".to_string() }
).await?;

Key Features:

Actor System API

Distributed actor framework for building scalable applications.

use orbit_shared::{Addressable, ActorImplementation};

#[async_trait]
trait MyActor: Addressable {
    async fn process_message(&self, data: String) -> Result<String>;
}

// Actors are automatically distributed across cluster nodes

Key Features:

Transaction API

ACID distributed transactions with 2-phase commit and Saga patterns.

use orbit_shared::transactions::*;

// Begin distributed transaction
let tx_id = coordinator.begin_transaction(Some(timeout)).await?;

// Add operations
coordinator.add_operation(&tx_id, operation).await?;

// Commit transaction
coordinator.commit_transaction(&tx_id).await?;

Key Features:

Protocol APIs

PostgreSQL API

Full PostgreSQL wire protocol compatibility for SQL operations.

-- Standard SQL operations
CREATE TABLE users (id SERIAL, name TEXT, email TEXT);
INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');
SELECT * FROM users WHERE name = 'Alice';

-- Vector operations (pgvector compatible)  
CREATE TABLE documents (id SERIAL, content TEXT, embedding VECTOR(384));
SELECT content FROM documents ORDER BY embedding <-> '[0.1, 0.2, 0.3]' LIMIT 5;

Supported Features:

Redis API

Redis RESP protocol compatibility for key-value operations.


# String operations
SET key "value"
GET key
MGET key1 key2 key3

# Hash operations
HSET user:123 name "Alice" email "alice@example.com"
HGET user:123 name

# List operations
LPUSH queue item1 item2
RPOP queue

# Vector operations (Redis Stack compatible)
FT.CREATE idx ON hash PREFIX 1 "doc:" SCHEMA embedding VECTOR FLAT 6 DIM 384
FT.SEARCH idx "*=>[KNN 5 @embedding $query]" PARAMS 2 query "[0.1, 0.2, 0.3]"

Supported Commands:

MCP API

Model Context Protocol for AI agent integration.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "query_database",
    "arguments": {
      "sql": "SELECT * FROM users WHERE age > 21"
    }
  }
}

Key Features:

Reference Documentation

Configuration


#[derive(Debug, Clone)]
pub struct OrbitClientConfig {
    pub namespace: String,
    pub server_urls: Vec<String>, 
    pub connection_timeout: Duration,
    pub retry_attempts: u32,
    pub actor_timeout: Duration,
}

Error Handling

pub enum OrbitError {
    NetworkError(String),
    ActorError(String),
    TransactionError(TransactionError),
    SerializationError(String),
    TimeoutError(String),
}

Performance Monitoring

pub struct ClientStats {
    pub namespace: String,
    pub server_connections: usize,
    pub node_id: Option<NodeId>,
    pub active_actors: usize,
    pub pending_transactions: usize,
}

Development Tools

Code Generation

Generate actor proxies and protocol bindings:


# Generate actor proxies
orbit-codegen actors --input src/actors.rs --output src/generated/

# Generate protocol bindings
orbit-codegen protocols --proto schemas/ --output src/protocols/

Testing

use orbit_testing::MockOrbitClient;

#[tokio::test]
async fn test_actor_interaction() {
    let client = MockOrbitClient::new();
    let actor_ref = client.mock_actor::<MyActor>("test-actor");
    
    let result = actor_ref.process_message("test".to_string()).await?;
    assert_eq!(result, "processed: test");
}

Debugging


# Enable debug logging
export RUST_LOG=orbit_client=debug,orbit_shared=debug

# Monitor actor lifecycle
export ORBIT_DEBUG_ACTORS=true

# Trace transaction execution  
export ORBIT_TRACE_TRANSACTIONS=true

Language Bindings

Rust (Native)

Java/Spring Boot

Python (Planned)

TypeScript/Node.js (Planned)

Performance Characteristics

Throughput

Latency

Scalability

Support & Community

Documentation

Community

Issue Reporting

License

This API documentation is part of the Orbit-RS project and is licensed under the Apache License 2.0.

** Last Updated: October 2024
** Version: 0.1.0
** Status**: Production Ready