Skip to main content

hyprstream_flight/
client.rs

1//! Flight SQL client for querying datasets
2//!
3//! This module provides a client for connecting to a Flight SQL server
4//! and executing queries. Used by the `hyprstream flight` CLI command.
5
6use arrow_array::{Array, RecordBatch, StringArray};
7use arrow_flight::{
8    decode::FlightRecordBatchStream,
9    flight_service_client::FlightServiceClient,
10    sql::{CommandStatementQuery, ProstMessageExt},
11    FlightDescriptor,
12};
13use arrow_schema::SchemaRef;
14use futures::TryStreamExt;
15use prost::Message;
16use std::sync::Arc;
17use tonic::transport::{Certificate, Channel, ClientTlsConfig, Endpoint};
18use tracing::{debug, info};
19
20/// Error type for Flight client operations
21#[derive(Debug, thiserror::Error)]
22pub enum FlightClientError {
23    #[error("Connection failed: {0}")]
24    Connection(String),
25
26    #[error("Query failed: {0}")]
27    Query(String),
28
29    #[error("Transport error: {0}")]
30    Transport(#[from] tonic::transport::Error),
31
32    #[error("Flight error: {0}")]
33    Flight(#[from] arrow_flight::error::FlightError),
34
35    #[error("Status error: {0}")]
36    Status(#[from] tonic::Status),
37}
38
39/// Configuration for the Flight client
40#[derive(Debug, Clone, Default)]
41pub struct FlightClientConfig {
42    /// TLS CA certificate for server verification (PEM)
43    pub tls_ca: Option<Vec<u8>>,
44    /// TLS client certificate (PEM)
45    pub tls_cert: Option<Vec<u8>>,
46    /// TLS client key (PEM)
47    pub tls_key: Option<Vec<u8>>,
48}
49
50impl FlightClientConfig {
51    pub fn with_tls_ca(mut self, ca: Vec<u8>) -> Self {
52        self.tls_ca = Some(ca);
53        self
54    }
55
56    pub fn with_client_cert(mut self, cert: Vec<u8>, key: Vec<u8>) -> Self {
57        self.tls_cert = Some(cert);
58        self.tls_key = Some(key);
59        self
60    }
61}
62
63/// Flight SQL client for querying datasets
64pub struct FlightClient {
65    client: FlightServiceClient<Channel>,
66    addr: String,
67}
68
69impl FlightClient {
70    /// Connect to a Flight SQL server
71    ///
72    /// # Arguments
73    ///
74    /// * `addr` - Server address (e.g., "127.0.0.1:50051" or "https://server:50051")
75    ///
76    /// # Example
77    ///
78    /// ```rust,ignore
79    /// let client = FlightClient::connect("127.0.0.1:50051").await?;
80    /// let results = client.query("SELECT * FROM metrics").await?;
81    /// ```
82    pub async fn connect(addr: &str) -> Result<Self, FlightClientError> {
83        Self::connect_with_config(addr, FlightClientConfig::default()).await
84    }
85
86    /// Connect to a Flight SQL server with TLS configuration
87    pub async fn connect_with_config(
88        addr: &str,
89        config: FlightClientConfig,
90    ) -> Result<Self, FlightClientError> {
91        let uri = if addr.starts_with("http://") || addr.starts_with("https://") {
92            addr.to_owned()
93        } else {
94            format!("http://{addr}")
95        };
96
97        debug!(uri = %uri, "Connecting to Flight SQL server");
98
99        let mut endpoint = Endpoint::from_shared(uri.clone())
100            .map_err(|e| FlightClientError::Connection(e.to_string()))?;
101
102        // Configure TLS if provided
103        if let Some(ca) = config.tls_ca {
104            let mut tls_config = ClientTlsConfig::new().ca_certificate(Certificate::from_pem(&ca));
105
106            if let (Some(cert), Some(key)) = (config.tls_cert, config.tls_key) {
107                let identity = tonic::transport::Identity::from_pem(&cert, &key);
108                tls_config = tls_config.identity(identity);
109            }
110
111            endpoint = endpoint.tls_config(tls_config)?;
112        }
113
114        let channel = endpoint.connect().await?;
115        let client = FlightServiceClient::new(channel);
116
117        info!(addr = %addr, "Connected to Flight SQL server");
118
119        Ok(Self {
120            client,
121            addr: addr.to_owned(),
122        })
123    }
124
125    /// Get the server address
126    pub fn addr(&self) -> &str {
127        &self.addr
128    }
129
130    /// Execute a SQL query and return all results as record batches
131    ///
132    /// # Arguments
133    ///
134    /// * `sql` - SQL query string
135    ///
136    /// # Returns
137    ///
138    /// A vector of record batches containing the query results
139    pub async fn query(&mut self, sql: &str) -> Result<Vec<RecordBatch>, FlightClientError> {
140        debug!(sql = %sql, "Executing query");
141
142        // Create the Flight SQL command
143        let cmd = CommandStatementQuery {
144            query: sql.to_owned(),
145            transaction_id: None,
146        };
147
148        // Encode using prost Message trait
149        let cmd_bytes = cmd.as_any().encode_to_vec();
150
151        // Get flight info (schema and endpoints)
152        let descriptor = FlightDescriptor::new_cmd(cmd_bytes);
153        let flight_info = self.client.get_flight_info(descriptor).await?.into_inner();
154
155        // Get the ticket from the first endpoint
156        let ticket = flight_info
157            .endpoint
158            .first()
159            .and_then(|ep| ep.ticket.clone())
160            .ok_or_else(|| FlightClientError::Query("No endpoint in flight info".to_owned()))?;
161
162        // Execute do_get to retrieve data
163        let stream = self.client.do_get(ticket).await?.into_inner();
164
165        // Convert to record batches
166        let flight_stream = FlightRecordBatchStream::new_from_flight_data(
167            stream.map_err(|e| arrow_flight::error::FlightError::Tonic(Box::new(e))),
168        );
169
170        let batches: Vec<RecordBatch> = flight_stream.try_collect().await?;
171
172        debug!(batch_count = batches.len(), "Query complete");
173
174        Ok(batches)
175    }
176
177    /// Execute a SQL query and return results with schema
178    pub async fn query_with_schema(
179        &mut self,
180        sql: &str,
181    ) -> Result<(SchemaRef, Vec<RecordBatch>), FlightClientError> {
182        let batches = self.query(sql).await?;
183        let schema = if let Some(batch) = batches.first() {
184            batch.schema()
185        } else {
186            Arc::new(arrow_schema::Schema::empty())
187        };
188        Ok((schema, batches))
189    }
190
191    /// Execute a statement that doesn't return results (INSERT, CREATE TABLE, etc.)
192    pub async fn execute(&mut self, sql: &str) -> Result<(), FlightClientError> {
193        let _ = self.query(sql).await?;
194        Ok(())
195    }
196
197    /// Check if the server is reachable
198    pub async fn health_check(&mut self) -> Result<(), FlightClientError> {
199        // Simple health check - list actions
200        let _actions = self.client.list_actions(arrow_flight::Empty {}).await?;
201        Ok(())
202    }
203}
204
205/// Get the string value from an array at a given index
206fn get_array_value(array: &dyn Array, row_idx: usize) -> String {
207    // Try to downcast to StringArray first (most common)
208    if let Some(string_array) = array.as_any().downcast_ref::<StringArray>() {
209        if string_array.is_null(row_idx) {
210            return "NULL".to_owned();
211        }
212        return string_array.value(row_idx).to_owned();
213    }
214
215    // For other types, use debug format
216    format!("{:?}", array.slice(row_idx, 1))
217}
218
219/// Format record batches as a table for display
220pub fn format_batches_as_table(batches: &[RecordBatch]) -> String {
221    use std::fmt::Write;
222
223    if batches.is_empty() {
224        return "No results".to_owned();
225    }
226
227    let schema = batches[0].schema();
228    let mut output = String::new();
229
230    // Calculate column widths
231    let mut widths: Vec<usize> = schema.fields().iter().map(|f| f.name().len()).collect();
232
233    for batch in batches {
234        for (col_idx, col) in batch.columns().iter().enumerate() {
235            for row_idx in 0..col.len() {
236                let value = get_array_value(col.as_ref(), row_idx);
237                widths[col_idx] = widths[col_idx].max(value.len());
238            }
239        }
240    }
241
242    // Header
243    let header: Vec<String> = schema
244        .fields()
245        .iter()
246        .zip(&widths)
247        .map(|(f, w)| format!("{:width$}", f.name(), width = *w))
248        .collect();
249    let _ = writeln!(output, "| {} |", header.join(" | "));
250
251    // Separator
252    let sep: Vec<String> = widths.iter().map(|w| "-".repeat(*w)).collect();
253    let _ = writeln!(output, "|-{}-|", sep.join("-|-"));
254
255    // Rows
256    for batch in batches {
257        for row_idx in 0..batch.num_rows() {
258            let row: Vec<String> = batch
259                .columns()
260                .iter()
261                .zip(&widths)
262                .map(|(col, w)| {
263                    let value = get_array_value(col.as_ref(), row_idx);
264                    format!("{:width$}", value, width = *w)
265                })
266                .collect();
267            let _ = writeln!(output, "| {} |", row.join(" | "));
268        }
269    }
270
271    // Row count
272    let total_rows: usize = batches.iter().map(arrow_array::RecordBatch::num_rows).sum();
273    let _ = writeln!(output, "\n({total_rows} rows)");
274
275    output
276}
277
278/// Format record batches as CSV
279pub fn format_batches_as_csv(batches: &[RecordBatch]) -> String {
280    use std::fmt::Write;
281
282    if batches.is_empty() {
283        return String::new();
284    }
285
286    let schema = batches[0].schema();
287    let mut output = String::new();
288
289    // Header
290    let header: Vec<&str> = schema.fields().iter().map(|f| f.name().as_str()).collect();
291    let _ = writeln!(output, "{}", header.join(","));
292
293    // Rows
294    for batch in batches {
295        for row_idx in 0..batch.num_rows() {
296            let row: Vec<String> = batch
297                .columns()
298                .iter()
299                .map(|col| {
300                    let val = get_array_value(col.as_ref(), row_idx);
301                    if val.contains(',') || val.contains('"') {
302                        format!("\"{}\"", val.replace('"', "\"\""))
303                    } else {
304                        val
305                    }
306                })
307                .collect();
308            let _ = writeln!(output, "{}", row.join(","));
309        }
310    }
311
312    output
313}
314
315/// Format record batches as JSON
316pub fn format_batches_as_json(batches: &[RecordBatch]) -> Result<String, serde_json::Error> {
317    let mut rows = Vec::new();
318
319    for batch in batches {
320        let schema = batch.schema();
321        for row_idx in 0..batch.num_rows() {
322            let mut row = serde_json::Map::new();
323            for (col_idx, col) in batch.columns().iter().enumerate() {
324                let field_name = schema.field(col_idx).name();
325                let value = get_array_value(col.as_ref(), row_idx);
326                row.insert(field_name.clone(), serde_json::Value::String(value));
327            }
328            rows.push(serde_json::Value::Object(row));
329        }
330    }
331
332    serde_json::to_string_pretty(&rows)
333}
334
335#[cfg(test)]
336mod tests {
337    use super::*;
338
339    #[test]
340    fn test_flight_client_config_builder() {
341        let config = FlightClientConfig::default()
342            .with_tls_ca(vec![1, 2, 3])
343            .with_client_cert(vec![4, 5, 6], vec![7, 8, 9]);
344
345        assert!(config.tls_ca.is_some());
346        assert!(config.tls_cert.is_some());
347        assert!(config.tls_key.is_some());
348    }
349
350    #[test]
351    fn test_flight_config_builder() {
352        let config = crate::FlightConfig::default()
353            .with_host("0.0.0.0")
354            .with_port(50052);
355
356        assert_eq!(config.host, "0.0.0.0");
357        assert_eq!(config.port, 50052);
358    }
359}