Orbit-RS Architecture

Security and Durability Invariants

Project Overview

Orbit-RS is a next-generation distributed actor system framework built in Rust, providing a comprehensive multi-model database platform with advanced query capabilities. It extends the original Orbit concept with native support for graph databases, time series analytics, and unified query processing.

Key Features

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                          Protocol Adapter Layer                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   RESP      │  │ PostgreSQL  │  │    MySQL    │  │     CQL     │         │
│  │  (Redis)    │  │   Wire      │  │    Wire     │  │ (Cassandra) │         │
│  │             │  │  Protocol   │  │  Protocol   │  │             │         │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Cypher    │  │     AQL     │  │  OrbitQL    │  │    REST     │         │
│  │  / Bolt     │  │ (ArangoDB)  │  │  (Native)   │  │    API      │         │
│  │  (Neo4j)    │  │             │  │             │  │  + WebSocket│         │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                                             │
│  ┌─────────────┐  ┌─────────────┐                                           │
│  │     MCP     │  │    gRPC     │                                           │
│  │  (LLM/NLP)  │  │  (Actors)   │                                           │
│  └─────────────┘  └─────────────┘                                           │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         AI-Native Layer (NEW)                               │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐  │
│  │  AI Master      │  │  Intelligent    │  │  Predictive Resource        │  │
│  │  Controller     │  │  Query Optimizer│  │  Manager                    │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐  │
│  │  Smart Storage  │  │  Adaptive TX    │  │  Learning & Decision        │  │
│  │  Manager        │  │  Manager        │  │  Engines + Knowledge Base   │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           Query Engine Layer                                │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐  │
│  │ Query Planner & │  │  Execution      │  │    Query Optimization &     │  │
│  │   Optimizer     │  │    Engine       │  │    Distributed Routing      │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        Multi-Model Storage Layer                            │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐  │
│  │  Graph Database │  │  Time Series    │  │   Document & Key-Value      │  │
│  │                 │  │    Engine       │  │       Storage               │  │
│  │ • Node Storage  │  │ • In-Memory     │  │ • JSON Documents            │  │
│  │ • Relationship  │  │ • Redis TS      │  │ • Relational Tables         │  │
│  │   Storage       │  │ • Timescale     │  │ • Actor State Storage       │  │
│  │ • Graph ML      │  │ • Compression   │  │                             │  │
│  │ • Analytics     │  │ • Partitioning  │  │                             │  │
│  │ • GraphRAG      │  │                 │  │                             │  │
│  │   Persistence   │  │                 │  │                             │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    Hybrid Storage Tier Management                           │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │  HOT TIER (0-48h)       │  WARM TIER (2-30d)   │  COLD TIER (>30d)    │  │
│  │  • Row-based (RocksDB)  │  • Columnar batches  │  • Apache Iceberg    │  │
│  │  • HashMap index        │  • In-memory         │  • Parquet files     │  │
│  │  • OLTP optimized       │  • Hybrid format     │  • S3/Azure          │  │
│  │  • Point queries        │  • Mixed workloads   │  • Metadata prune    │  │
│  │  • Writes/Updates       │  • Analytics ready   │  • Time travel       │  │
│  │                         │                      │  • Schema evolution  │  │
│  │                         │                      │  • 100-1000x plan    │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          Actor System Layer                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐  │
│  │ Virtual Actors  │  │   Persistence   │  │    Cluster Management       │  │
│  │                 │  │                 │  │                             │  │
│  │ • Addressable   │  │ • COW B-Tree    │  │ • Node Discovery            │  │
│  │   Leasing       │  │ • LSM Tree      │  │ • Load Balancing            │  │
│  │ • State Mgmt    │  │ • RocksDB       │  │ • Fault Tolerance           │  │
│  │ • Lifecycle     │  │ • Memory        │  │ • Health Monitoring         │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    Cluster Coordination & Distributed Storage               │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │  CLUSTER COORDINATION         │  DISTRIBUTED STORAGE                  │  │
│  │  • Raft Consensus             │  • Data Partitioning                  │  │
│  │  • Leader Election            │  • Replication (3x factor)            │  │
│  │  • Node Membership            │  • Consistency Levels                 │  │
│  │  • Health Monitoring          │  • Quorum-based Writes                │  │
│  │  • Failure Detection          │  • Cross-node Shuffling               │  │
│  │  • Network Transport          │  • Actor-aware Placement              │  │
│  │                               │  • Distributed Transactions           │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │  STORAGE BACKENDS (Multi-Cloud)                                       │  │
│  │  • S3 (AWS)                       • Azure Blob Storage                │  │
│  │  • Local Filesystem               • MinIO (S3-compatible)             │  │
│  │  • Iceberg Catalog (REST)         • FileIO abstraction                │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

Module Architecture

Orbit-RS is structured as a Rust workspace with the following main crates:

Core Crates

orbit-shared

orbit-server

orbit-protocols

orbit-engine

Specialized Modules

orbit-operator

Examples and Testing

Core Concepts

Addressables (Virtual Actors)

Addressables are the core abstraction in Orbit. They are virtual actors that:

use async_trait::async_trait;
use orbit_shared::{Addressable, AddressableReference, Key, OrbitResult};

#[derive(Debug, Clone)]
pub struct GreeterActor {
    name: String,
}

#[async_trait]
impl Addressable for GreeterActor {
    fn addressable_type() -> &'static str {
        "GreeterActor"
    }
}

impl GreeterActor {
    pub async fn greet(&self, name: String) -> OrbitResult<String> {
        Ok(format!("Hello {}", name))
    }
}

Node Management

Nodes in the cluster are identified by:

Message System

Communication uses a structured message system:

Invocation Model

Actor method calls are handled through:

  1. AddressableReference: Type-safe actor references with compile-time checking
  2. AddressableInvocation: Structured representation of method calls
  3. InvocationSystem: Routes calls to appropriate nodes via gRPC
  4. Serialization/deserialization of arguments and results using Protocol Buffers

Lease Management

Both actors and nodes use lease-based management:

Dependencies

Core Rust Dependencies

Build and Testing

Communication Flow

  1. Client Invocation: Client calls method on actor via AddressableReference
  2. Reference Resolution: AddressableReference provides type-safe actor access
  3. Message Creation: Call is serialized into AddressableInvocation using Protocol Buffers
  4. Routing: System determines which node hosts the actor via directory lookup
  5. Network Transport: Message sent via gRPC (Tonic) to target node
  6. Server Processing: Target node deserializes and executes call on actor instance
  7. Response: Result serialized and sent back to client
  8. Completion: Client receives response and completes the async future

Scalability Features

Advanced Transaction Features

The Rust implementation extends the original architecture with a comprehensive transaction system:

Transaction Module Architecture

The transaction system is organized into specialized modules:

orbit/shared/src/transactions/
├── core.rs         - 2-Phase Commit protocol implementation
├── locks.rs        - Distributed locks with deadlock detection
├── metrics.rs      - Prometheus metrics integration
├── security.rs     - Authentication, authorization, audit logging
└── performance.rs  - Batching, connection pooling, resource management

Distributed Lock System

Components:

Deadlock Detection:

Lock Lifecycle:

Request → Wait Queue → Deadlock Check → Acquire → Hold → Release → Cleanup

Metrics and Observability

Metric Types:

  1. Transaction Metrics
    • Counters: started, committed, aborted, failed, timeout
    • Gauges: active transactions, queued operations
    • Histograms: duration, prepare time, commit time, participant count
  2. Saga Metrics
    • Counters: started, completed, failed, compensated, step execution
    • Gauges: active sagas, queued sagas
    • Histograms: saga duration, step duration, compensation duration
  3. Lock Metrics
    • Counters: acquired, released, timeout, deadlock detected/resolved
    • Gauges: held locks, waiting requests
    • Histograms: wait duration, hold duration

Prometheus Integration:

Security Architecture

Authentication:

Authorization:

Audit Logging:

Security Context:

Request → Authenticate → Authorize → Execute → Audit Log

✨ AI-Native Database Architecture (NEW - Nov 2025)

Overview:

Orbit-RS includes a production-ready AI-Native layer that autonomously optimizes database operations through 8 intelligent subsystems working in concert. This is not experimental ML integration - it’s a complete, tested, zero-warning implementation with 100% test coverage.

AI Master Controller (orbit/server/src/ai/controller.rs):

Intelligent Query Optimizer (orbit/server/src/ai/optimizer/):

Predictive Resource Manager (orbit/server/src/ai/resource/):

Smart Storage Manager (orbit/server/src/ai/storage/):

Adaptive Transaction Manager (orbit/server/src/ai/transaction/):

Learning Engine (orbit/server/src/ai/learning.rs):

Decision Engine (orbit/server/src/ai/decision.rs):

Knowledge Base (orbit/server/src/ai/knowledge.rs):

AI System Integration:

┌───────────────────────────────────────────────────────────────┐
│                    AI Master Controller                       │
│              (10-second control loop)                         │
└───────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  Query          │  │  Resource       │  │  Storage        │
│  Optimizer      │  │  Manager        │  │  Manager        │
└─────────────────┘  └─────────────────┘  └─────────────────┘
         │                    │                    │
         └────────────┬───────┴──────────┬─────────┘
                      ▼                  ▼
            ┌─────────────────┐  ┌─────────────────┐
            │  Transaction    │  │  Learning &     │
            │  Manager        │  │  Knowledge Base │
            └─────────────────┘  └─────────────────┘

Production Statistics:

Performance Optimization System

Batch Processing:

Connection Pooling:

Resource Management:

Saga Pattern Implementation

Orchestration:

Compensation:

State Management:

Saga States: NotStarted → Running → Completed | Compensating → Compensated | Failed

Transaction Recovery

Coordinator Failover:

Persistence:

Protocol Support Details

Production-Ready Protocols

  1. RESP (Redis Protocol) - Port 6379
    • Status: ✅ Production-Ready
    • Implementation: Complete RESP2 protocol implementation with 50+ Redis commands
    • Features:
      • All core Redis data types (String, Hash, List, Set, Sorted Set)
      • Pub/Sub messaging with pattern matching
      • Connection management (PING, ECHO, AUTH, QUIT)
      • Server commands (INFO, DBSIZE, FLUSHDB)
      • TTL and expiration support
      • Full redis-cli compatibility
    • Command Coverage: 50+ commands including GET, SET, DEL, HSET, HGETALL, LPUSH, RPUSH, PUBLISH, SUBSCRIBE, SADD, ZADD, and more
    • Actor Integration: Maps Redis commands to Orbit actors (KeyValueActor, HashActor, ListActor, PubSubActor)
    • Extensions: Vector operations (VECTOR.), Time Series (TS.), Graph DB (GRAPH.) - *Planned
    • Test Coverage: Comprehensive integration tests with redis-cli validation
  2. PostgreSQL Wire Protocol - Port 5432
    • Status: Production-Ready
    • Implementation: Complete PostgreSQL v3.0 wire protocol implementation
    • Features:
      • Full protocol message types (Startup, Query, Parse, Bind, Execute, Describe, Close, Sync, Terminate)
      • Simple query protocol (Query → RowDescription → DataRow → CommandComplete)
      • Extended query protocol with prepared statements
      • Trust authentication (MD5/SCRAM-SHA-256 planned)
      • Transaction status tracking
      • Error handling with PostgreSQL-compatible error responses
    • SQL Support: SELECT, INSERT, UPDATE, DELETE with WHERE clauses, JSON state management
    • PostgreSQL 18 clone-control compatibility: session-level file_copy_method values (copy and clone) are persisted and CREATE DATABASE ... STRATEGY = FILE_COPY is represented in database metadata. Orbit-RS does not use a PostgreSQL data directory, so filesystem reflink/CoW behavior is not implied; logical snapshot isolation will be implemented in the durable storage layer.
    • Integration: 9 integration tests (100% passing) with psql client validation
    • Compatibility: Works with standard PostgreSQL clients (psql, pgAdmin, DataGrip, etc.)
    • Future Enhancements: JOINs, aggregates, window functions, pgvector extension support

    Durable compatibility boundaries: CHECK expressions are stored with table metadata and evaluated for every durable INSERT and UPDATE; false results return SQLSTATE 23514, while NULL follows PostgreSQL check semantics. The legacy wire catalog handlers expose primary-key and secondary-index metadata through pg_catalog.pg_index and pg_catalog.pg_indexes. Durable writes use a single writer gate, the dataset is memory-resident, and Raft snapshots currently travel as one bounded frame. Arbitrary system-catalog joins and universal index-backed query lookup remain future compatibility work.

  3. OrbitQL - Port 8081 (or 8080 via REST)
    • Status: Production-Ready (90% core functionality complete)
    • Implementation: Native query language with comprehensive SQL support
    • Features:
      • SQL-compatible queries (SELECT, INSERT, UPDATE, DELETE)
      • Multi-model operations (Document, Graph, Time-Series)
      • Advanced query processing (JOINs, GROUP BY, ORDER BY, LIMIT/OFFSET)
      • Graph traversal and relationship queries
      • Time-series analysis with temporal queries
      • Query optimization with cost-based optimizer
      • Query profiling (EXPLAIN ANALYZE)
      • Intelligent query caching with dependency tracking
      • Live query streaming with change notifications
    • ML Extensions: ML function autocompletion, neural network integration
    • Developer Experience: Language Server Protocol (LSP) with VS Code extension
    • Test Coverage: 20+ integration tests covering all major functionality
  4. REST API - Port 8080
    • Status: ✅ Production-Ready
    • Implementation: Complete HTTP/JSON interface with OpenAPI documentation
    • Features:
      • RESTful actor management endpoints
      • Transaction management APIs
      • Natural language query endpoints
      • WebSocket support for real-time updates
      • OpenAPI/Swagger documentation
      • Authentication and authorization
    • Endpoints: Actor CRUD operations, transaction coordination, query execution
    • Use Cases: Web applications, API integration, MCP server backend
  5. gRPC - Port 50051
    • Status: Production-Ready (Core Protocol)
    • Implementation: Complete gRPC framework using Tonic
    • Features:
      • Actor system management
      • Inter-node communication
      • Cluster coordination
      • Protocol Buffer serialization
      • Streaming support
    • Use Cases: Cluster coordination, actor invocation, internal node communication

Supported Protocols (In Development)

  1. MySQL Wire Protocol - Port 3306
    • Status: In progress; compatibility not yet measured
    • Implementation: MySQL wire protocol 4.1+ with full query execution
    • Features:
      • ✅ MySQL wire protocol (packet encoding/decoding, all major commands)
      • ✅ Complete query execution (SELECT, INSERT, UPDATE, DELETE)
      • ✅ Prepared statements with parameter binding and metadata
      • ✅ Result set building with type inference
      • ✅ Error handling with complete SQL→MySQL error code mapping (20+ error codes)
      • ✅ Authentication with password verification (native password, clear password)
      • ✅ Metrics and monitoring (query counts, error tracking, connection stats)
      • ✅ Edge case handling and input validation
      • ✅ Comprehensive test coverage (unit, integration, query execution)
      • ✅ All MySQL commands implemented (COM_QUERY, COM_STMT_PREPARE, COM_STMT_EXECUTE, COM_STMT_CLOSE, COM_STMT_RESET, COM_FIELD_LIST, COM_STATISTICS, COM_CREATE_DB, COM_DROP_DB, COM_REFRESH, COM_PING, COM_QUIT, COM_INIT_DB)
    • Current State:
      • ✅ Query Execution: 100% complete (all DML operations working)
      • ✅ Prepared Statements: 100% complete (parameter binding, metadata encoding, reset support)
      • ✅ Result Sets: 100% complete (type inference, proper encoding)
      • ✅ Error Handling: 100% complete (20+ error codes mapped, comprehensive error reporting)
      • ✅ Authentication: 100% complete (password verification implemented)
      • ✅ Metrics: 100% complete (comprehensive metrics implemented)
      • ✅ Test Coverage: 100% complete (unit, integration, query execution tests)
      • ✅ Edge Cases: 100% complete (empty queries, invalid inputs, error handling)
      • ✅ Command Support: 100% complete (all 13 MySQL commands implemented)
    • Use Cases: MySQL client compatibility, migration from MySQL, standard SQL access
    • Test Coverage:
      • Unit Tests: 16/16 passing (authentication, error codes, types, parameters, new commands)
      • Integration Tests: 11/11 passing (auth flow, prepared statements, error handling, new commands)
      • Query Execution Tests: 5/5 passing (100% pass rate)
      • Syntax Tests: 36/36 passing (100% pass rate)
      • Total: 68+ tests passing
    • Production Readiness: 100% - Fully production ready, all commands implemented
    • Documentation: See MySQL Complete Documentation
  2. CQL (Cassandra Query Language) - Port 9042
    • Status: In progress; compatibility not yet measured
    • Implementation: Complete CQL 3.x wire protocol v4 with full query execution
    • Features:
      • ✅ Full CQL wire protocol (frame encoding/decoding, all 16 opcodes)
      • ✅ Complete parser for SELECT, INSERT, UPDATE, DELETE, CREATE/DROP TABLE/KEYSPACE
      • ✅ WHERE clause parsing with all operators (=, >, <, >=, <=, !=, IN, CONTAINS, CONTAINS KEY)
      • ✅ Query execution via SQL engine integration (SELECT, INSERT, UPDATE, DELETE)
      • ✅ Result set building with proper CQL protocol encoding and metadata
      • ✅ Prepared statements with metadata encoding (column types, variable metadata)
      • ✅ Batch operations with execution (LOGGED, UNLOGGED, COUNTER)
      • ✅ Type system with complete CQL to SQL value conversion
      • ✅ Error handling with complete SQL→CQL error code mapping (all 15 error codes)
      • ✅ WHERE clause support in DELETE and UPDATE (MVCC executor integration)
      • ✅ Authentication with password verification (AUTH_RESPONSE handling, password authenticator)
      • ✅ Metrics and monitoring (query counts, error tracking, connection stats)
      • ✅ Collection types support (List, Map, Set, Tuple with JSON encoding)
      • ✅ Production deployment guide (complete deployment documentation)
    • Current State:
      • ✅ Parser: 95% complete (all major statements, WHERE clauses, value parsing)
      • ✅ Query Execution: 100% complete (all DML operations working)
      • ✅ Result Sets: 100% complete (proper protocol encoding with metadata)
      • ✅ Prepared Statements: 90% complete (metadata encoding implemented)
      • ✅ Batch Operations: 80% complete (execution implemented, transaction handling pending)
      • ✅ Error Handling: 100% complete (complete error code mapping, all ProtocolError types mapped)
      • ✅ Authentication: 100% complete (password verification implemented)
      • ✅ Metrics: 100% complete (metrics implemented, production hooks ready)
      • ✅ Collection Types: 100% complete (List, Map, Set, Tuple support)
      • ✅ Deployment Guide: 100% complete (production deployment documentation)
      • ✅ Test Infrastructure: Integration test framework with shared storage
    • Use Cases: Cassandra client compatibility, wide-column store access, cqlsh integration
    • Test Coverage: 38/38 tests passing (100% pass rate) - All tests passing!
      • Unit Tests: 8/8 (100%)
      • Integration Tests: 7/7 (100%)
      • Query Execution Tests: 23/23 (100%)
    • Production Readiness: 100% ✅ - Fully production ready, all tests passing (38/38), complete feature set including collection types, authentication, and deployment guide
    • Documentation: See CQL Complete Documentation for comprehensive details
  3. Cypher/Bolt Protocol (Neo4j) - Port 7687
    • Status: ✅ Production-Ready (Full Bolt v4.4 + 70+ Cypher Functions)
    • Features: Complete Neo4j Bolt v4.4 protocol, comprehensive Cypher query language, RocksDB persistence
    • Bolt Protocol v4.4:
      • ✅ PackStream encoding/decoding (Null, Bool, Int, Float, String, List, Map, Structure)
      • ✅ Connection handshake and version negotiation
      • ✅ Authentication (HELLO with auth token)
      • ✅ Transaction management (BEGIN/COMMIT/ROLLBACK)
      • ✅ Streaming results (RUN/PULL/DISCARD)
      • ✅ Connection routing (ROUTE message)
    • Cypher Query Language:
      • ✅ All clauses: MATCH, CREATE, MERGE, DELETE, SET, REMOVE, RETURN, WITH, WHERE
      • ✅ Advanced clauses: UNWIND, FOREACH, CASE expressions
      • ✅ Variable-length path patterns (*1..3)
      • ✅ ORDER BY, SKIP, LIMIT
      • ✅ 70+ built-in functions (string, list, math, date/time, type, path)
    • Graph Engine:
      • ✅ Pattern matching with node/relationship filters
      • ✅ Graph algorithms (PageRank, Community Detection, Shortest Path)
      • ✅ GraphRAG integration for AI-enhanced graph queries
    • Storage:
      • ✅ RocksDB persistence at data/cypher/rocksdb/
      • ✅ CypherGraphStorage with nodes, relationships, metadata column families
      • ✅ Automatic data loading on startup
      • ✅ In-memory caching for fast access
    • Tests: 68+ tests passing
    • Use Cases: Graph database queries, Neo4j client compatibility, persistent graph storage
    • Documentation: See Protocol Persistence Status
  4. AQL (ArangoDB Query Language) - Port 8529
    • Status: ✅ Production-Ready (RocksDB Persistence)
    • Features: ArangoDB-compatible query language, RocksDB persistence
    • Current State:
      • ✅ Server initialized in main.rs
      • ✅ RocksDB persistence at data/aql/rocksdb/
      • ✅ AqlStorage with collections, documents, edges, graphs, metadata column families
      • ✅ Automatic data loading on startup
      • ✅ In-memory caching for fast access
    • Persistence: Full RocksDB persistence with column families
    • Use Cases: Multi-model database queries, ArangoDB client compatibility, persistent document/graph storage
    • Documentation: See Protocol Persistence Status

Experimental Protocols

  1. MCP (Model Context Protocol) - Via REST API
    • Status: ✅ Production-Ready (100% Complete)
    • Features: LLM integration, natural language to SQL conversion, schema discovery
    • Current State:
      • ✅ MCP server initialized in main.rs
      • ✅ Connected to PostgreSQL storage (TieredTableStorage)
      • ✅ Connected to query engine (QueryEngine)
      • ✅ Schema discovery with real-time updates
      • ✅ NLP processor (intent classification, entity extraction)
      • ✅ SQL generator (schema-aware query building)
      • ✅ Result processor (data summarization, statistics)
      • ✅ Orbit-RS integration layer
      • ✅ MCP tools (query_data, describe_schema, analyze_data, list_tables)
      • ✅ All handlers implemented (resources/read, prompts/get, tools/call)
      • ✅ Dynamic resource fetching with server integration
      • ✅ Enhanced prompt system with context-aware prompts
      • ✅ 25+ comprehensive tests
    • Capabilities: SQL query execution, vector search, actor management, natural language queries
    • Use Cases: AI agent integration, conversational queries, LLM tool access
    • Documentation: See MCP Implementation Status

MCP Architecture Details

The MCP server provides a complete natural language to SQL pipeline for LLM integration:

┌─────────────────────────────────────────────────────────┐
│                    LLM Client                           │
│              (Claude, GPT-4, etc.)                      │
└────────────────────┬────────────────────────────────────┘
                     │ MCP Protocol
                     ↓
┌─────────────────────────────────────────────────────────┐
│                  MCP Server                             │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Natural Language Query Processor                │   │
│  │  - Intent Classification (Rule-based + ML)       │   │
│  │  - Entity Recognition                            │   │
│  │  - Condition Extraction                          │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  SQL Generation Engine                           │   │
│  │  - Schema-aware building                         │   │
│  │  - Parameter binding                             │   │
│  │  - Optimization hints                            │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Orbit-RS Integration Layer                      │   │
│  │  - Query execution                               │   │
│  │  - Schema discovery                              │   │
│  │  - Result conversion                             │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Result Processor                                │   │
│  │  - Summarization                                 │   │
│  │  - Statistics                                    │   │
│  │  - Visualization hints                           │   │
│  └──────────────────────────────────────────────────┘   │
└────────────────────┬────────────────────────────────────┘
                     │
                     ↓
┌─────────────────────────────────────────────────────────┐
│              Orbit-RS Query Engine                      │
│         (PostgreSQL Wire Protocol)                      │
└─────────────────────────────────────────────────────────┘

MCP Components:

  1. Natural Language Processing (nlp.rs - 651 lines)
    • Intent classification (SELECT, INSERT, UPDATE, DELETE, ANALYZE)
    • Entity recognition (tables, columns, values, functions)
    • Condition extraction (WHERE clauses)
    • Projection extraction (SELECT columns)
    • Confidence scoring
    • Aggregation detection
    • Limit extraction
    • Ordering extraction
  2. SQL Generation (sql_generator.rs - 450 lines)
    • Schema-aware query building
    • Parameter binding for SQL injection protection
    • Query type detection (Read/Write/Analysis)
    • Complexity estimation (Low/Medium/High)
    • Optimization hints (indexes, partitioning, etc.)
    • Support for all SQL operations
  3. Result Processing (result_processor.rs - 485 lines)
    • Data summarization
    • Statistical analysis (min, max, mean, median, quartiles)
    • Visualization hints (bar charts, line charts, scatter plots)
    • Data preview formatting
    • Pagination support
    • Column statistics
  4. Schema Management (schema.rs - 327 lines, schema_discovery.rs - 220 lines)
    • Thread-safe schema cache with TTL
    • Real-time schema discovery
    • Background refresh mechanism
    • Schema change notifications
    • Cache statistics
    • Table and column metadata
  5. Orbit-RS Integration (integration.rs - 247 lines)
    • Query execution via PostgreSQL wire protocol
    • Schema discovery from Orbit-RS
    • Result conversion (PostgreSQL → MCP format)
    • Type mapping and conversion
    • Error handling and recovery
  6. ML Framework (ml_nlp.rs - 320 lines)
    • ML model integration framework
    • Hybrid ML + rule-based processing
    • Model manager
    • Confidence-based fallback
    • Model configuration management
    • Ready for actual model integration

MCP Performance Characteristics:

MCP Security Features:

MCP Implementation Statistics:

Transaction Layer Architecture

MVCC (Multi-Version Concurrency Control)

Orbit-RS uses MVCC to provide snapshot isolation and high concurrency without read-write conflicts.

Transaction Timeline:

T1: BEGIN (snapshot_id=100)
    │
    ├─ Read row X (sees version with xmin<100, xmax>100)
    │
T2: BEGIN (snapshot_id=101)
    │
    ├─ Update row X (creates new version: xmin=101, xmax=∞)
    │
T1: ├─ Read row X (still sees old version: xmin<100)
    │
T2: ├─ COMMIT (version xmin=101 becomes visible to new txns)
    │
T1: ├─ Read row X (still sees old version: snapshot isolation)
    │
    └─ COMMIT

T3: BEGIN (snapshot_id=102)
    └─ Read row X (sees new version: xmin=101 < snapshot_id=102)

Row Versioning

pub struct RowVersion {
    pub data: HashMap<String, SqlValue>,
    pub xmin: TransactionId,  // Creating transaction
    pub xmax: Option<TransactionId>,  // Deleting transaction
    pub created_at: DateTime<Utc>,
    pub committed: bool,
}

// Visibility rules
fn is_visible(version: &RowVersion, snapshot: SnapshotId) -> bool {
    version.committed
        && version.xmin < snapshot
        && (version.xmax.is_none() || version.xmax.unwrap() > snapshot)
}

Benefits:

Trade-offs:

Distributed Transactions (2PC)

Two-Phase Commit protocol for distributed ACID transactions across multiple nodes.

Coordinator                    Participant A              Participant B
    │                              │                          │
    ├─ BEGIN                       │                          │
    ├─ Prepare ────────────────────┼──────────────────────────┤
    │                              │                          │
    │                          PREPARE                    PREPARE
    │                              │                          │
    │                          Vote YES                   Vote YES
    │  ◄─────────────────────────┼──────────────────────────┤
    │                              │                          │
    ├─ Decision: COMMIT            │                          │
    ├─ Commit ─────────────────────┼──────────────────────────┤
    │                              │                          │
    │                          COMMIT                     COMMIT
    │  ◄─────────────────────────┼──────────────────────────┤
    │                              │                          │
    ├─ DONE                        │                          │

Implementation Features:

Deadlock Detection

pub struct DeadlockDetector {
    // Wait-for graph: transaction -> waiting for transaction
    wait_graph: Arc<RwLock<HashMap<TransactionId, HashSet<TransactionId>>>>,
}

impl DeadlockDetector {
    // Detect cycles using DFS
    pub fn detect_deadlock(&self, tx_id: TransactionId)
        -> Option<Vec<TransactionId>> {
        // Returns cycle if deadlock detected
    }

    // Resolve by aborting youngest transaction
    pub fn resolve_deadlock(&self, cycle: Vec<TransactionId>)
        -> TransactionId {
        // Returns transaction to abort
    }
}

Deadlock Detection:

Lock Lifecycle:

Request → Wait Queue → Deadlock Check → Acquire → Hold → Release → Cleanup

Saga Pattern Implementation

Long-running distributed transactions with compensation.

Orchestration:

Compensation:

State Management:

Saga States: NotStarted → Running → Completed | Compensating → Compensated | Failed

Transaction Metrics and Observability

Metric Types:

  1. Transaction Metrics
    • Counters: started, committed, aborted, failed, timeout
    • Gauges: active transactions, queued operations
    • Histograms: duration, prepare time, commit time, participant count
  2. Saga Metrics
    • Counters: started, completed, failed, compensated, step execution
    • Gauges: active sagas, queued sagas
    • Histograms: saga duration, step duration, compensation duration
  3. Lock Metrics
    • Counters: acquired, released, timeout, deadlock detected/resolved
    • Gauges: held locks, waiting requests
    • Histograms: wait duration, hold duration

Prometheus Integration:

Query Execution Architecture

Vectorized Execution

Orbit-RS uses vectorized execution for high-performance analytical queries.

Traditional Row-at-a-Time:
┌─────┐    ┌──────┐   ┌─────┐
│ Row │ →  │Filter│ → │ Agg │
└─────┘    └──────┘   └─────┘
  1 row      1 row     1 row

Vectorized Batch-at-a-Time:
┌──────────┐    ┌──────────┐    ┌──────────┐
│ Batch    │ →  │ Filter   │ →  │   Agg    │
│ 1024 rows│    │ 1024 rows│    │ 1024 rows│
└──────────┘    └──────────┘    └──────────┘

Benefits:

SIMD Optimization

// Scalar (1 comparison at a time)
for i in 0..values.len() {
    if values[i] > threshold {
        results.push(i);
    }
}

// SIMD (8 comparisons at a time with AVX2)
for chunk in values.chunks(8) {
    let vec = _mm256_loadu_si256(chunk);
    let threshold_vec = _mm256_set1_epi32(threshold);
    let mask = _mm256_cmpgt_epi32(vec, threshold_vec);
    // Process mask to extract matching indices
}

Performance Gains:

Columnar Format

Row-Based Storage:
┌────┬──────┬───────┐
│ id │ name │ price │
├────┼──────┼───────┤
│ 1  │ A    │ 10.0  │
│ 2  │ B    │ 20.0  │
│ 3  │ C    │ 15.0  │
└────┴──────┴───────┘
[1,A,10.0][2,B,20.0][3,C,15.0]

Columnar Storage:
┌────┬────┬────┐
│ id │ id │ id │
├────┼────┼────┤
│ 1  │ 2  │ 3  │
└────┴────┴────┘
[1,2,3]

┌──────┬──────┬──────┐
│ name │ name │ name │
├──────┼──────┼──────┤
│ A    │ B    │ C    │
└──────┴──────┴──────┘
[A,B,C]

┌───────┬───────┬───────┐
│ price │ price │ price │
├───────┼───────┼───────┤
│ 10.0  │ 20.0  │ 15.0  │
└───────┴───────┴───────┘
[10.0,20.0,15.0]

Benefits:

Clustering and Replication

Raft Consensus

Leader Election:

Node A (Leader)     Node B (Follower)   Node C (Follower)
    │                      │                    │
    ├─ Heartbeat ──────────┼────────────────────┤
    │  (term=5)            │                    │
    │                      │                    │
    │                   (timeout)               │
    │                      │                    │
    │                  RequestVote              │
    │  ◄───────────────────┤                    │
    │                  (term=6)                 │
    │                      │                    │
    ├─ Vote Granted ───────┤                    │
    │                      │                    │
    │                      ├─ RequestVote ──────┤
    │                      │   (term=6)         │
    │                      │                    │
    │                      │  Vote Granted ─────┤
    │                      │                    │
    │                 (becomes leader)          │

Replication

Write Path with Replication:

Client
  │
  ├─ Write Request
  │
  ▼
Leader (Node A)
  │
  ├─ 1. Write to local log
  ├─ 2. Replicate to followers
  │     │
  │     ├─────────────────┬─────────────────┐
  │     ▼                 ▼                 ▼
  │  Node B           Node C           Node D
  │     │                 │                 │
  │     ├─ Write log      ├─ Write log      ├─ Write log
  │     ├─ ACK            ├─ ACK            ├─ ACK
  │     │                 │                 │
  │  ◄──┴─────────────────┴─────────────────┘
  │
  ├─ 3. Wait for quorum (2 of 3)
  ├─ 4. Commit
  │
  ▼
Response to Client

Change Data Capture (CDC)

pub enum CdcEvent {
    Insert { table: String, row: Row },
    Update { table: String, old: Row, new: Row },
    Delete { table: String, row: Row },
    Ddl { statement: String },
}

// Subscribe to changes
let mut stream = cdc.subscribe("users", CdcFilter::All).await?;
while let Some(event) = stream.next().await {
    match event {
        CdcEvent::Insert { table, row } => {
            // Handle insert
        }
        _ => {}
    }
}

Protocol Test Coverage Summary

Protocol Test Coverage Production Status Notes
RESP (Redis) High ✅ Production-Ready 50+ commands, full compatibility
PostgreSQL High In progress Conformance: 789 of 816 records (96.7%), 2026-10-27
OrbitQL High In progress Conformance to the OrbitQL 1.0 specification not yet measured; 20+ tests
REST API High ✅ Production-Ready OpenAPI documentation, WebSocket support
gRPC High ✅ Production-Ready Core protocol, fully integrated
MySQL High In progress Compatibility not yet measured; 68+ tests passing. See MySQL Complete Documentation
CQL High In progress Compatibility not yet measured; 38/38 tests passing. See CQL Complete Documentation
Cypher/Bolt High ✅ Production-Ready 100% complete: Bolt protocol server, WHERE clause, 10+ tests, RocksDB persistence
AQL High In progress Compatibility not yet measured; HTTP server, query engine, 30+ tests, RocksDB persistence
MCP High ✅ Production-Ready 100% complete: All handlers, dynamic resources, 25+ tests

Network Layer Architecture

gRPC Services

Orbit-RS uses gRPC for high-performance inter-node communication and actor invocation.

ConnectionService

Bidirectional streaming service for actor communication.

service ConnectionService {
    rpc OpenStream(stream MessageProto) returns (stream MessageProto);
    rpc GetConnectionInfo(ConnectionInfoRequestProto) returns (ConnectionInfoResponseProto);
}

Implementation:

pub struct OrbitConnectionService {
    connections: Arc<Mutex<HashMap<String, mpsc::UnboundedSender<MessageProto>>>>,
}

impl connection_service_server::ConnectionService for OrbitConnectionService {
    type OpenStreamStream = tokio_stream::wrappers::UnboundedReceiverStream<Result<MessageProto, Status>>;

    async fn open_stream(
        &self,
        request: Request<Streaming<MessageProto>>,
    ) -> Result<Response<Self::OpenStreamStream>, Status> {
        // Bidirectional message streaming
    }
}

HealthService

Standard health check service for monitoring.

service HealthService {
    rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
    rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);
}

enum ServingStatus {
    UNKNOWN = 0;
    SERVING = 1;
    NOT_SERVING = 2;
    SERVICE_UNKNOWN = 3;
}

Protocol Buffer Definitions

Message Protocol

message MessageProto {
    int64 message_id = 1;
    NodeIdProto source = 2;
    MessageTargetProto target = 3;
    MessageContentProto content = 4;
    int64 attempts = 5;
}

message MessageContentProto {
    oneof content {
        ErrorProto error = 1;
        ConnectionInfoRequestProto info_request = 2;
        ConnectionInfoResponseProto info_response = 3;
        InvocationRequestProto invocation_request = 4;
        InvocationResponseProto invocation_response = 5;
        InvocationResponseErrorProto invocation_response_error = 6;
    }
}

Node Protocol

message NodeInfoProto {
    NodeIdProto id = 1;
    string url = 2;
    uint32 port = 3;
    NodeCapabilitiesProto capabilities = 4;
    NodeStatusProto status = 5;
    optional NodeLeaseProto lease = 6;
}

enum NodeStatusProto {
    ACTIVE = 0;
    DRAINING = 1;
    STOPPED = 2;
}

Transport Layer

Connection Pooling

use orbit_shared::transport::TransportConfig;

let config = TransportConfig {
    max_connections_per_endpoint: 10,  // Pool size per endpoint
    connect_timeout: Duration::from_secs(5),
    request_timeout: Duration::from_secs(30),
    keep_alive_interval: Some(Duration::from_secs(30)),
    keep_alive_timeout: Some(Duration::from_secs(10)),
    max_message_size: 16 * 1024 * 1024, // 16MB
    retry_attempts: 3,
    retry_backoff_initial: Duration::from_millis(100),
    retry_backoff_multiplier: 2.0,
    tcp_keepalive: Some(Duration::from_secs(10)),
    http2_adaptive_window: true,
};

Benefits:

Retry Logic

// Automatic retry with exponential backoff:
// Attempt 1: immediate
// Attempt 2: +100ms
// Attempt 3: +200ms
// Attempt 4: +400ms

Retry Strategy:

Connection Metrics

let stats = pool.get_stats().await;
println!("Total connections: {}", stats.total_connections);
println!("Total requests: {}", stats.total_requests);
println!("Total errors: {}", stats.total_errors);
println!("Average latency: {}ms", stats.average_latency_ms);

Metrics Tracked:

Raft Transport

Specialized gRPC transport for Raft consensus protocol.

#[async_trait]
pub trait RaftTransport: Send + Sync {
    async fn send_vote_request(
        &self,
        target: &NodeId,
        request: VoteRequest,
    ) -> OrbitResult<VoteResponse>;

    async fn send_append_entries(
        &self,
        target: &NodeId,
        request: AppendEntriesRequest,
    ) -> OrbitResult<AppendEntriesResponse>;

    async fn broadcast_heartbeat(
        &self,
        nodes: &[NodeId],
        request: AppendEntriesRequest,
    ) -> OrbitResult<Vec<AppendEntriesResponse>>;
}

Hybrid Storage Architecture

Orbit-RS uses a hybrid approach combining actors and direct storage based on protocol requirements.

RESP/Redis Protocol - Actor-Based with Persistence

Architecture:

RESP Command
    ↓
SimpleLocalRegistry (in-memory actors)
    ├─ KeyValueActor (cache)
    ├─ ListActor (cache)
    ├─ SetActor (cache)
    ├─ SortedSetActor (cache)
    └─ RedisDataProvider (RocksDB persistence)

How it works:

  1. In-Memory Actors: SimpleLocalRegistry maintains in-memory actor instances as a cache
  2. Persistent Backing: All data is persisted to RocksDB via RocksDbRedisDataProvider
  3. Cache-First: Reads check actors first, then fall back to RocksDB if not in cache
  4. Write-Through: Writes update both actors (cache) and RocksDB (persistence)

Initialization (from main.rs lines 1046-1074):

// Create RocksDB storage for Redis persistence
let redis_data_path = args.data_dir.join("redis").join("rocksdb");
let redis_provider = RocksDbRedisDataProvider::new(
    redis_data_path.to_str().unwrap(),
    RedisDataConfig::default(),
)?;

// Create RESP server with BOTH actors and persistence
let redis_server = RespServer::new_with_persistence(
    bind_addr, 
    orbit_client, 
    Some(Arc::new(redis_provider))  // ← RocksDB persistence enabled
);

Data Structure (from simple_local.rs lines 16-29):

pub struct SimpleLocalRegistry {
    /// KeyValue actors (in-memory cache)
    keyvalue_actors: Arc<RwLock<HashMap<String, KeyValueActor>>>,
    /// Hash actors
    hash_actors: Arc<RwLock<HashMap<String, HashActor>>>,
    /// List actors
    list_actors: Arc<RwLock<HashMap<String, ListActor>>>,
    /// Set actors
    set_actors: Arc<RwLock<HashMap<String, SetActor>>>,
    /// Sorted set actors
    sorted_set_actors: Arc<RwLock<HashMap<String, SortedSetActor>>>,
    /// Optional persistent storage provider
    persistent_storage: Option<Arc<dyn RedisDataProvider>>,  // ← RocksDB
}

Write-Through Pattern (from simple_local.rs lines 128-148):

// On SET: Update both cache and persistence
"set_value" => {
    let value: String = serde_json::from_value(args[0].clone())?;
    actor.set_value(value.clone());  // ← Update actor (in-memory cache)

    // Persist to storage if available
    if let Some(provider) = &self.persistent_storage {
        let redis_value = RedisValue::new(value);
        provider.set(key, redis_value).await?;  // ← Write to RocksDB
    }

    Ok(serde_json::to_value(())?)
}

Cache-First Reads (from simple_local.rs lines 92-113):

// On GET: Check persistent storage first, then cache
if method == "get_value" {
    if let Some(provider) = &self.persistent_storage {
        if let Ok(Some(redis_value)) = provider.get(key).await {
            // Update in-memory cache from RocksDB
            let mut actors = self.keyvalue_actors.write().await;
            let actor = actors.entry(key.to_string()).or_insert_with(KeyValueActor::new);
            actor.set_value(redis_value.data.clone());
            return Ok(serde_json::to_value(Some(redis_value.data))?);
        }
    }
}
// Fall back to in-memory actor if not in RocksDB

Startup Data Loading (from main.rs lines 1019-1027):

// Load data from RocksDB into actors on startup
if let Some(provider) = redis_provider.as_ref() {
    info!("Loading existing Redis data from RocksDB...");
    match provider.load_all_data().await {
        Ok(data_map) => {
            info!("Loaded {} keys from RocksDB", data_map.len());
            // Populate actors with loaded data
        }
        Err(e) => warn!("Failed to load data from RocksDB: {}", e),
    }
}

This hybrid approach provides:

Geospatial Architecture

Status: ✅ Production Ready (November 2025)

Orbit-RS provides comprehensive geospatial data support across all protocols through a unified spatial engine. The architecture enables PostGIS-compatible operations, real-time geofencing, and GPU-accelerated spatial analytics.

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│              Multi-Protocol Clients                     │
│  PostgreSQL │ Redis │ AQL │ Cypher │ OrbitQL            │
└─────────────────────────────────────────────────────────┘
                        │
┌─────────────────────────────────────────────────────────┐
│         Unified Geospatial Engine                       │
│  ┌───────────────────────────────────────────────────┐  │
│  │     Shared Spatial Operations & Functions         │  │
│  │  • SpatialOperations (8 relationship functions)   │  │
│  │  • SpatialFunctions (25+ PostGIS functions)       │  │
│  │  • WKT/GeoJSON parsing                            │  │
│  └───────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────┐  │
│  │     Spatial Indexing (R-tree, QuadTree)           │  │
│  └───────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────┐  │
│  │     Spatial Streaming (Geofencing, Analytics)     │  │
│  └───────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────┐  │
│  │     GPU Acceleration (CPU fallback)               │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                        │
┌─────────────────────────────────────────────────────────┐
│         Orbit-RS Storage Engine                         │
│  • RocksDB persistence for all protocols                │
│  • Spatial data types (Point, LineString, Polygon)      │
└─────────────────────────────────────────────────────────┘

Core Components

1. Spatial Operations (orbit/shared/src/spatial/operations.rs)

8 OGC-Compliant Relationship Functions:

Measurement Functions:

2. PostGIS-Compatible Functions (orbit/shared/src/spatial/functions.rs)

25+ ST_* Functions:

Construction:

Measurement:

Relationships:

Accessors:

Transformations:

Output:

3. Spatial Indexing

R-tree Implementation (orbit/shared/src/spatial/rtree.rs):

QuadTree (for high-density points):

4. Real-Time Spatial Streaming (orbit/shared/src/spatial/streaming.rs)

Geofencing Engine:

Analytics:

Performance:

5. GPU-Accelerated Operations (orbit/compute/src/spatial_distance.rs)

CPU Fallbacks (Production-Ready):

GPU Backends (Optional, Feature-Gated):

Operations:

Protocol Integration

PostgreSQL Wire Protocol

Full PostGIS Compatibility:

-- Create spatial data
SELECT ST_Point(-122.4194, 37.7749);

-- Spatial relationships
SELECT ST_Within(
    ST_Point(-122.4194, 37.7749),
    ST_GeomFromText('POLYGON((...))') 
);

-- Distance queries
SELECT name, ST_Distance_Sphere(location, ST_Point(lng, lat))
FROM locations
WHERE ST_DWithin(location, ST_Point(lng, lat), 1000);

Implementation:

Redis RESP Protocol

Standard GEO Commands:

GEOADD locations -122.4194 37.7749 "San Francisco"
GEODIST locations "San Francisco" "Oakland"
GEORADIUS locations -122.4194 37.7749 10 km

Extended Spatial Commands:

GEO.POLYGON.ADD locations zone1 "POLYGON((...))"
GEO.WITHIN locations "POLYGON((...))"
GEO.INTERSECTS locations point1 polygon1
GEO.CONTAINS locations polygon1 point1

Implementation:

AQL (ArangoDB) Protocol

Spatial Functions:

RETURN GEO_CONTAINS(
    GEO_POLYGON([[lng1, lat1], [lng2, lat2], ...]),
    GEO_POINT(lng, lat)
)

RETURN GEO_DISTANCE(point1, point2)
RETURN GEO_AREA(polygon)

Implementation:

The AQL parser also covers LET arithmetic, COLLECT grouping, graph traversal, logical expressions, and object keys that overlap with reserved function names. These parser cases are part of the normal regression suite; graph metrics, full-text indexing, and several extended built-ins still require their backing engine integrations.

Cypher (Neo4j) Protocol

Graph-Based Spatial Queries:

MATCH (n:Location)
WHERE within(n.location, $polygon)
RETURN n

MATCH (a:Place)-[:NEAR]->(b:Place)
WHERE distance(a.location, b.location) < 1000
RETURN a, b

Implementation:

OrbitQL Native Syntax

Spatial Function Registry:

SELECT * FROM locations
WHERE ST_Within(location, ST_GeomFromText('POLYGON((...))'))

SELECT name, ST_Distance(location, ST_Point(-122, 37))
FROM places
ORDER BY ST_Distance(location, ST_Point(-122, 37))
LIMIT 10

Implementation:

Performance Characteristics

Spatial Operations:

Spatial Indexing:

Real-Time Streaming:

GPU Acceleration (when available):

Storage and Persistence

RocksDB Integration:

Data Types:

Use Cases

  1. Location-Based Services
    • Store and query points of interest
    • Radius searches (find nearby)
    • Geofencing and alerts
  2. Logistics and Routing
    • Route optimization
    • Delivery zone management
    • Real-time vehicle tracking
  3. Real Estate and GIS
    • Property boundaries
    • Zoning analysis
    • Spatial analytics
  4. IoT and Telemetry
    • Device location tracking
    • Geofence monitoring
    • Spatial event processing

Testing and Quality

Test Coverage:

Documentation:

Future Enhancements

Planned Features:

GPU Acceleration:

See Geospatial Implementation Complete for comprehensive details.

Multi-Protocol Architecture

Specialized gRPC transport for Raft consensus protocol.

#[async_trait]
pub trait RaftTransport: Send + Sync {
    async fn send_vote_request(
        &self,
        target: &NodeId,
        request: VoteRequest,
    ) -> OrbitResult<VoteResponse>;

    async fn send_append_entries(
        &self,
        target: &NodeId,
        request: AppendEntriesRequest,
    ) -> OrbitResult<AppendEntriesResponse>;

    async fn broadcast_heartbeat(
        &self,
        nodes: &[NodeId],
        request: AppendEntriesRequest,
    ) -> OrbitResult<Vec<AppendEntriesResponse>>;
}

Hybrid Storage Architecture

Orbit-RS uses a hybrid approach combining actors and direct storage based on protocol requirements.

RESP/Redis Protocol - Actor-Based with Persistence

Architecture:

RESP Command
    ↓
SimpleLocalRegistry (in-memory actors)
    ├─ KeyValueActor (cache)
    ├─ ListActor (cache)
    ├─ SetActor (cache)
    ├─ SortedSetActor (cache)
    └─ RedisDataProvider (RocksDB persistence)

How it works:

  1. In-Memory Actors: SimpleLocalRegistry maintains in-memory actor instances as a cache
  2. Persistent Backing: All data is persisted to RocksDB via RocksDbRedisDataProvider
  3. Cache-First: Reads check actors first, then fall back to RocksDB if not in cache
  4. Write-Through: Writes update both actors (cache) and RocksDB (persistence)

Initialization (from main.rs lines 1046-1074):

// Create RocksDB storage for Redis persistence
let redis_data_path = args.data_dir.join("redis").join("rocksdb");
let redis_provider = RocksDbRedisDataProvider::new(
    redis_data_path.to_str().unwrap(),
    RedisDataConfig::default(),
)?;

// Create RESP server with BOTH actors and persistence
let redis_server = RespServer::new_with_persistence(
    bind_addr, 
    orbit_client, 
    Some(Arc::new(redis_provider))  // ← RocksDB persistence enabled
);

Data Structure (from simple_local.rs lines 16-29):

pub struct SimpleLocalRegistry {
    /// KeyValue actors (in-memory cache)
    keyvalue_actors: Arc<RwLock<HashMap<String, KeyValueActor>>>,
    /// Hash actors
    hash_actors: Arc<RwLock<HashMap<String, HashActor>>>,
    /// List actors
    list_actors: Arc<RwLock<HashMap<String, ListActor>>>,
    /// Set actors
    set_actors: Arc<RwLock<HashMap<String, SetActor>>>,
    /// Sorted set actors
    sorted_set_actors: Arc<RwLock<HashMap<String, SortedSetActor>>>,
    /// Optional persistent storage provider
    persistent_storage: Option<Arc<dyn RedisDataProvider>>,  // ← RocksDB
}

Write-Through Pattern (from simple_local.rs lines 128-148):

// On SET: Update both cache and persistence
"set_value" => {
    let value: String = serde_json::from_value(args[0].clone())?;
    actor.set_value(value.clone());  // ← Update actor (in-memory cache)

    // Persist to storage if available
    if let Some(provider) = &self.persistent_storage {
        let redis_value = RedisValue::new(value);
        provider.set(key, redis_value).await?;  // ← Write to RocksDB
    }

    Ok(serde_json::to_value(())?)
}

Cache-First Reads (from simple_local.rs lines 92-113):

// On GET: Check persistent storage first, then cache
if method == "get_value" {
    if let Some(provider) = &self.persistent_storage {
        if let Ok(Some(redis_value)) = provider.get(key).await {
            // Update in-memory cache from RocksDB
            let mut actors = self.keyvalue_actors.write().await;
            let actor = actors.entry(key.to_string()).or_insert_with(KeyValueActor::new);
            actor.set_value(redis_value.data.clone());
            return Ok(serde_json::to_value(Some(redis_value.data))?);
        }
    }
}
// Fall back to in-memory actor if not in RocksDB

Startup Data Loading (from simple_local.rs lines 56-82):

/// Load all keys from persistent storage on startup
pub async fn load_from_persistence(&self) -> OrbitResult<()> {
    if let Some(provider) = &self.persistent_storage {
        debug!("Loading keys from persistent storage");
        let keys = provider.keys("*").await?;
        let mut actors = self.keyvalue_actors.write().await;

        for key in keys {
            if let Some(value) = provider.get(&key).await? {
                let mut actor = KeyValueActor::new();
                actor.set_value(value.data);
                // Restore expiration if set
                if let Some(expiration) = value.expiration {
                    let now = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_secs();
                    if expiration > now {
                        actor.set_expiration(expiration - now);
                    }
                }
                actors.insert(key, actor);
            }
        }
        debug!("Loaded {} keys from persistent storage", actors.len());
    }
    Ok(())
}

Why Actors for RESP?

PostgreSQL, MySQL, CQL - Direct Storage

Architecture:

SQL Query
    ↓
TieredTableStorage
    └─ RocksDB (direct storage)

How it works:

Code Example:

// orbit/server/src/main.rs
let postgres_storage = Arc::new(TieredTableStorage::with_data_dir(
    postgres_data_dir,
    tiered_config.clone(),
));
// No actors - direct storage

Storage Comparison

Protocol Storage Type Uses Actors? Persistence Data Directory
RESP/Redis Hybrid (Actors + RocksDB) ✅ Yes (cache layer) ✅ RocksDB data/redis/rocksdb/
PostgreSQL Direct Storage ❌ No ✅ RocksDB data/postgresql/rocksdb/
MySQL Direct Storage ❌ No ✅ RocksDB data/mysql/rocksdb/
CQL Direct Storage ❌ No ✅ RocksDB data/cql/rocksdb/
Cypher Direct Storage ❌ No ✅ RocksDB data/cypher/rocksdb/
AQL Direct Storage ❌ No ✅ RocksDB data/aql/rocksdb/
GraphRAG Direct Storage ❌ No ✅ RocksDB data/graphrag/rocksdb/

Why This Architecture?

RESP Uses Actors Because:

  1. Redis Semantics: Keys naturally map to actors
  2. Distributed Future: Enables distributed actor system integration
  3. Performance: In-memory cache for hot data
  4. Compatibility: Maintains Redis-like behavior

Other Protocols Use Direct Storage Because:

  1. SQL/Query Semantics: Tables/collections don’t map well to actors
  2. Performance: Direct storage is more efficient for bulk operations
  3. Simplicity: No need for actor abstraction layer
  4. Consistency: All protocols use the same RocksDB persistence pattern

Storage Architecture Details

Three-Tier Hybrid Storage

Orbit-RS implements a sophisticated three-tier storage architecture optimized for different data access patterns:

Hot Tier (0-48 hours)

Warm Tier (2-30 days)

Cold Tier (>30 days)

Iceberg Integration Benefits

Time Travel SQL Syntax

Orbit-RS supports multiple time travel query syntaxes for accessing historical data in Iceberg cold tier tables:

Snowflake-Compatible Syntax

-- Query by timestamp
SELECT * FROM orders AT(TIMESTAMP => '2025-01-01 00:00:00') WHERE status = 'active';

-- Query by version/snapshot ID
SELECT * FROM orders AT(VERSION => 123456789);

-- Query by snapshot
SELECT * FROM orders AT(SNAPSHOT => 987654321);

-- With table alias and JOINs
SELECT o.*, c.name
FROM orders AT(TIMESTAMP => '2025-01-01') o
JOIN customers c ON o.customer_id = c.id;

SQL:2011 Temporal Syntax

-- FOR SYSTEM_TIME AS OF (standard temporal query)
SELECT * FROM orders FOR SYSTEM_TIME AS OF TIMESTAMP '2025-01-01 00:00:00';

-- Also supports underscore form
SELECT * FROM orders FOR SYSTEM_TIME AS OF '2025-01-01';

UNDROP TABLE (Data Recovery)

-- Restore a recently dropped table from Iceberg snapshots
UNDROP TABLE deleted_orders;
UNDROP TABLE myschema.archived_data;

Implementation Status:

Cluster Coordination

The cluster layer provides distributed system capabilities:

Distributed Storage Features

Configuration and Deployment

Performance Characteristics

Transaction System:

Resource Usage:

Protocol Performance:

Protocol Integration Benefits

The multi-protocol architecture provides several key advantages:

  1. Seamless Migration: Existing applications can connect using familiar protocols without code changes
    • Production-Ready: Redis (RESP), PostgreSQL, MySQL, CQL, Cypher/Bolt, AQL, OrbitQL, REST API, gRPC
    • Experimental: MCP (AI agent integration)
  2. Tool Compatibility: Standard database tools work out of the box
    • redis-cli: Full compatibility with 50+ Redis commands
    • psql: Complete PostgreSQL wire protocol support
    • pgAdmin, DataGrip: Standard PostgreSQL clients supported
    • MySQL clients: Full MySQL wire protocol support
    • Neo4j clients: Complete Bolt v4.4 protocol with Cypher support
  3. Ecosystem Integration: Leverage existing drivers and libraries from various ecosystems
    • Redis ecosystem: All Redis client libraries (redis-py, node-redis, etc.)
    • PostgreSQL ecosystem: All PostgreSQL drivers (psycopg2, JDBC, etc.)
    • Graph ecosystem: Neo4j drivers (Python, Java, .NET, JavaScript) and ArangoDB clients
  4. Flexible Access: Choose the protocol that best fits your use case
    • SQL (PostgreSQL/OrbitQL): Complex queries, analytics, ACID transactions
    • RESP (Redis): Caching, session storage, pub/sub messaging
    • REST API: Web applications, microservices, API integration
    • gRPC: High-performance inter-service communication
    • MCP: AI agent integration and natural language queries
  5. Unified Backend: All protocols access the same distributed actor system and storage layer
    • Consistent Data Model: All protocols operate on the same actor-based data
    • Multi-Model Support: Graph, document, time-series, and relational data
    • Distributed Architecture: Automatic load balancing and fault tolerance
    • Transaction Support: ACID transactions across all protocols
  6. Production Readiness: Five protocols are production-ready with comprehensive testing
    • High Test Coverage: Production protocols have extensive integration tests
    • Client Compatibility: Validated with standard client tools
    • Performance Optimized: Each protocol optimized for its specific use case
    • Enterprise Features: Authentication, authorization, monitoring, and observability

This architecture provides a solid foundation for building distributed, fault-tolerant, and scalable applications using the virtual actor model with production-ready transaction support and comprehensive multi-protocol access.