Integrating Following Graphs

Integrating Following Graphs with StratoClient

The In-Network (Thunder) component of the X recommendation engine identifies relevant posts by analyzing the "following" graph of a user. The StratoClient serves as the primary interface for fetching these social graphs and providing the necessary user context to the retrieval service.

This guide walks you through initializing the StratoClient, integrating it into the Thunder service, and using it to retrieve the list of accounts a user follows.

Overview

In the Thunder architecture, the StratoClient is responsible for:

Graph Retrieval: Querying the upstream Strato storage layer for a user's follow list.
Hydration: Providing the list of IDs to the PostStore to filter for recent, relevant content.
Efficiency: Working alongside concurrency semaphores to prevent overloading downstream services during high-traffic retrieval requests.

Initializing the StratoClient

In your service's entry point (typically main.rs), you must first create a thread-safe instance of the StratoClient. Wrap it in an Arc to allow shared access across the asynchronous gRPC service.

use std::sync::Arc;
use thunder::strato_client::StratoClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Initialize the StratoClient for fetching following lists
    let strato_client = Arc::new(StratoClient::new());
    
    log::info!("Initialized StratoClient");
    
    // ... further service setup
    Ok(())
}

Injecting the Client into ThunderService

Once initialized, the StratoClient must be passed to the ThunderServiceImpl. This service acts as the gRPC handler for GetInNetworkPosts requests.

The ThunderServiceImpl requires three main components for construction:

PostStore: The in-memory storage for recent posts.
StratoClient: The interface for user graphs.
Concurrency Limit: A usize defining the maximum number of simultaneous requests.

use thunder::thunder_service::ThunderServiceImpl;

// Create the service implementation
let thunder_service = ThunderServiceImpl::new(
    Arc::clone(&post_store),     // Your initialized PostStore
    Arc::clone(&strato_client),  // The client initialized above
    args.max_concurrent_requests // e.g., 500
);

// Start the gRPC server
let routes = tonic::service::Routes::new(thunder_service.server());

Fetching Graphs during Retrieval Requests

The ThunderService automatically uses the StratoClient when a GetInNetworkPostsRequest is received. While the client handles the fetch internally, it's important to understand how the data flows through the service.

If a request is made without a pre-provided list of "following" IDs, the service uses the client to hydrate the request:

// Internal logic within ThunderServiceImpl (simplified)
async fn get_in_network_posts(
    &self,
    request: Request<GetInNetworkPostsRequest>
) -> Result<Response<GetInNetworkPostsResponse>, Status> {
    let req = request.into_inner();
    
    // 1. Acquire semaphore to manage load
    let _permit = self.request_semaphore.acquire().await;
    
    // 2. Fetch following IDs if not provided in the request
    let following_ids = if !req.following_ids.is_empty() {
        req.following_ids
    } else {
        self.strato_client.get_following(req.user_id).await
            .map_err(|e| Status::internal("Failed to fetch social graph"))?
    };

    // 3. Query PostStore using the retrieved IDs
    let posts = self.post_store.get_posts_by_authors(&following_ids).await;
    
    Ok(Response::new(GetInNetworkPostsResponse { posts }))
}

Configuration and Limits

To ensure system stability when fetching large social graphs, the Thunder service applies several hard limits defined in the configuration layer. When integrating the client, be aware of these constraints:

Monitoring Integration

The integration automatically reports metrics via the analyze_and_report_post_statistics helper. When the StratoClient successfully retrieves a graph, the system tracks:

GET_IN_NETWORK_POSTS_FOLLOWING_SIZE: The number of accounts the user follows.
GET_IN_NETWORK_POSTS_DURATION_WITHOUT_STRATO: Latency of the retrieval excluding the graph fetch time.

These metrics allow you to distinguish between delays caused by social graph retrieval and delays caused by post-ranking logic.