Skip to content

Architectural Challenges

Jump to bottom
Sathishkumar edited this page Aug 14, 2026 · 1 revision

Architectural Challenges

Overview

Several architectural limitations have emerged as Firebolt adoption and API complexity continue to increase.

Problem 1: Synchronous Client API Built on Async Transport

Challenges

  • Promise creation for every request
  • Request correlation complexity
  • Additional synchronization overhead
  • Blocked application threads

Impact

  • Increased complexity
  • Reduced scalability
  • More difficult lifecycle management
sequenceDiagram
    participant App
    participant Client
    participant Gateway
    participant Server

    App->>Client: getProperty()

    Client->>Gateway: invoke()

    Gateway->>Gateway: Create Promise
    Gateway->>Gateway: Store Promise by Request Id

    Gateway->>Server: JSON-RPC Request

    Note over App,Gateway: Application thread blocked waiting for response

    Server-->>Gateway: JSON-RPC Response

    Gateway->>Gateway: Lookup Promise
    Gateway->>Gateway: Resolve Promise

    Gateway-->>Client: Result
    Client-->>App: Return Value
Loading

Problem 2: Gateway Watchdog Thread

Current Design

The Gateway owns a dedicated watchdog thread responsible for timeout monitoring. To support request timeout processing, the Gateway creates a dedicated watchdog thread during connection establishment. The watchdog periodically wakes at a configurable interval, scans pending requests, resolves expired operations, and removes completed entries from the correlation queue.

While this design successfully provides timeout monitoring, it introduces an unintended coupling between timeout processing and connection lifecycle management.

Challenges

  • Periodic queue scanning
  • Dedicated thread lifecycle management
  • Disconnect latency tied to timeout interval
sequenceDiagram

    participant Client
    participant Gateway
    participant Watchdog

    Client->>Gateway: connect()

    Gateway->>Watchdog: Start Thread

    loop Timeout Monitoring
        Watchdog->>Watchdog: sleep_for(timeoutInterval)
        Watchdog->>Gateway: Scan Pending Requests
    end

    Client->>Gateway: disconnect()

    Gateway->>Watchdog: Request Shutdown

    Note over Watchdog: Thread may still be sleeping

    Watchdog->>Watchdog: Wake After Timeout

    Watchdog->>Watchdog: Detect Shutdown

    Watchdog-->>Gateway: Exit

    Gateway-->>Client: Disconnect Complete
Loading

Disconnect Path

sequenceDiagram

    participant App
    participant Gateway
    participant Watchdog

    App->>Gateway: disconnect()

    Gateway->>Watchdog: shutdown = true

    rect rgb(255,240,240)
        Note over Watchdog: Still sleeping
        Note over Gateway: Waiting in join()
    end

    Watchdog->>Watchdog: sleep_for() expires

    Watchdog->>Watchdog: Check shutdown flag

    Watchdog-->>Gateway: Thread exits

    Gateway-->>App: Disconnect Complete
Loading

Problem 3: Cloud Latency

Several APIs depend on external services:

  • Authentication
  • Token refresh
  • Cloud communication
  • Remote processing

Transport infrastructure continues managing these requests despite having no control over remote delays.

Impact

  • Larger pending request queues
  • Longer-lived promises
  • Additional monitoring overhead

Clone this wiki locally