nodedb_cluster/forward.rs
1//! Query forwarding trait for leader-based request routing.
2//!
3//! When a client connects to a non-leader node, the query is forwarded
4//! to the leader for the target vShard. The [`RequestForwarder`] trait
5//! abstracts local execution so the cluster crate doesn't depend on the
6//! main binary's SharedState or pgwire infrastructure.
7
8use crate::rpc_codec::{ForwardRequest, ForwardResponse};
9
10/// Trait for executing forwarded SQL queries on the local Data Plane.
11///
12/// Implemented by the main binary crate using SharedState + QueryContext.
13/// The cluster RPC handler calls this when it receives a `ForwardRequest`.
14pub trait RequestForwarder: Send + Sync + 'static {
15 /// Execute a forwarded SQL query locally and return the result.
16 ///
17 /// The implementation should:
18 /// 1. Create a synthetic identity from the tenant_id (trusted node-to-node)
19 /// 2. Plan the SQL through DataFusion
20 /// 3. Dispatch to the local Data Plane
21 /// 4. Collect response payloads
22 /// 5. Return them in a ForwardResponse
23 fn execute_forwarded(
24 &self,
25 req: ForwardRequest,
26 ) -> impl std::future::Future<Output = ForwardResponse> + Send;
27}
28
29/// No-op forwarder for single-node mode or testing.
30pub struct NoopForwarder;
31
32impl RequestForwarder for NoopForwarder {
33 async fn execute_forwarded(&self, _req: ForwardRequest) -> ForwardResponse {
34 ForwardResponse {
35 success: false,
36 payloads: vec![],
37 error_message: "query forwarding not available (single-node mode)".into(),
38 }
39 }
40}