Skip to main content

arrow_flight/
client.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5use crate::{
6    Action, ActionType, Criteria, Empty, FlightData, FlightDescriptor, FlightEndpoint, FlightInfo,
7    HandshakeRequest, PollInfo, PutResult, Ticket,
8    decode::FlightRecordBatchStream,
9    flight_service_client::FlightServiceClient,
10    r#gen::{CancelFlightInfoRequest, CancelFlightInfoResult, RenewFlightEndpointRequest},
11    trailers::extract_lazy_trailers,
12};
13use arrow_schema::Schema;
14use bytes::Bytes;
15use futures::{
16    Stream, StreamExt, TryStreamExt,
17    future::ready,
18    stream::{self, BoxStream},
19};
20use prost::Message;
21use tonic::codegen::{Body, StdError};
22use tonic::{metadata::MetadataMap, transport::Channel};
23
24use crate::error::{FlightError, Result};
25use crate::streams::{FallibleRequestStream, FallibleTonicResponseStream};
26
27/// A "Mid level" [Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html) client.
28///
29/// [`FlightClient`] is intended as a convenience for interactions
30/// with Arrow Flight servers. For more direct control, such as access
31/// to the response headers, use  [`FlightServiceClient`] directly
32/// via methods such as [`Self::inner`] or [`Self::into_inner`].
33///
34/// # Example:
35/// ```no_run
36/// # async fn run() {
37/// # use arrow_flight::FlightClient;
38/// # use bytes::Bytes;
39/// use tonic::transport::Channel;
40/// let channel = Channel::from_static("http://localhost:1234")
41///   .connect()
42///   .await
43///   .expect("error connecting");
44///
45/// let mut client = FlightClient::new(channel);
46///
47/// // Send 'Hi' bytes as the handshake request to the server
48/// let response = client
49///   .handshake(Bytes::from("Hi"))
50///   .await
51///   .expect("error handshaking");
52///
53/// // Expect the server responded with 'Ho'
54/// assert_eq!(response, Bytes::from("Ho"));
55/// # }
56/// ```
57#[derive(Debug)]
58pub struct FlightClient<T = Channel> {
59    /// Optional grpc header metadata to include with each request
60    metadata: MetadataMap,
61
62    /// The inner client
63    inner: FlightServiceClient<T>,
64}
65
66impl<T> FlightClient<T>
67where
68    T: tonic::client::GrpcService<tonic::body::Body>,
69    T::Error: Into<StdError>,
70    T::ResponseBody: Body<Data = Bytes> + std::marker::Send + 'static,
71    <T::ResponseBody as Body>::Error: Into<StdError> + std::marker::Send,
72{
73    /// Creates a client with the provided transport
74    pub fn new(inner: T) -> Self {
75        Self::new_from_inner(FlightServiceClient::new(inner))
76    }
77
78    /// Creates a new higher level client with the provided lower level client
79    pub fn new_from_inner(inner: FlightServiceClient<T>) -> Self {
80        Self {
81            metadata: MetadataMap::new(),
82            inner,
83        }
84    }
85
86    /// Return a reference to gRPC metadata included with each request
87    pub fn metadata(&self) -> &MetadataMap {
88        &self.metadata
89    }
90
91    /// Return a reference to gRPC metadata included with each request
92    ///
93    /// These headers can be used, for example, to include
94    /// authorization or other application specific headers.
95    pub fn metadata_mut(&mut self) -> &mut MetadataMap {
96        &mut self.metadata
97    }
98
99    /// Add the specified header with value to all subsequent
100    /// requests. See [`Self::metadata_mut`] for fine grained control.
101    pub fn add_header(&mut self, key: &str, value: &str) -> Result<()> {
102        let key = tonic::metadata::MetadataKey::<_>::from_bytes(key.as_bytes())
103            .map_err(|e| FlightError::ExternalError(Box::new(e)))?;
104
105        let value = value
106            .parse()
107            .map_err(|e| FlightError::ExternalError(Box::new(e)))?;
108
109        // ignore previous value
110        self.metadata.insert(key, value);
111
112        Ok(())
113    }
114
115    /// Return a reference to the underlying tonic
116    /// [`FlightServiceClient`]
117    pub fn inner(&self) -> &FlightServiceClient<T> {
118        &self.inner
119    }
120
121    /// Return a mutable reference to the underlying tonic
122    /// [`FlightServiceClient`]
123    pub fn inner_mut(&mut self) -> &mut FlightServiceClient<T> {
124        &mut self.inner
125    }
126
127    /// Consume this client and return the underlying tonic
128    /// [`FlightServiceClient`]
129    pub fn into_inner(self) -> FlightServiceClient<T> {
130        self.inner
131    }
132
133    /// Perform an Arrow Flight handshake with the server, sending
134    /// `payload` as the [`HandshakeRequest`] payload and returning
135    /// the [`HandshakeResponse`](crate::HandshakeResponse)
136    /// bytes returned from the server
137    ///
138    /// See [`FlightClient`] docs for an example.
139    pub async fn handshake(&mut self, payload: impl Into<Bytes>) -> Result<Bytes> {
140        let request = HandshakeRequest {
141            protocol_version: 0,
142            payload: payload.into(),
143        };
144
145        // apply headers, etc
146        let request = self.make_request(stream::once(ready(request)));
147
148        let mut response_stream = self.inner.handshake(request).await?.into_inner();
149
150        if let Some(response) = response_stream.next().await.transpose()? {
151            // check if there is another response
152            if response_stream.next().await.is_some() {
153                return Err(FlightError::protocol(
154                    "Got unexpected second response from handshake",
155                ));
156            }
157
158            Ok(response.payload)
159        } else {
160            Err(FlightError::protocol("No response from handshake"))
161        }
162    }
163
164    /// Make a `DoGet` call to the server with the provided ticket,
165    /// returning a [`FlightRecordBatchStream`] for reading
166    /// [`RecordBatch`](arrow_array::RecordBatch)es.
167    ///
168    /// # Note
169    ///
170    /// To access the returned [`FlightData`] use
171    /// [`FlightRecordBatchStream::into_inner()`]
172    ///
173    /// # Example:
174    /// ```no_run
175    /// # async fn run() {
176    /// # use bytes::Bytes;
177    /// # use arrow_flight::FlightClient;
178    /// # use arrow_flight::Ticket;
179    /// # use arrow_array::RecordBatch;
180    /// # use futures::stream::TryStreamExt;
181    /// # let channel: tonic::transport::Channel = unimplemented!();
182    /// # let ticket = Ticket { ticket: Bytes::from("foo") };
183    /// let mut client = FlightClient::new(channel);
184    ///
185    /// // Invoke a do_get request on the server with a previously
186    /// // received Ticket
187    ///
188    /// let response = client
189    ///    .do_get(ticket)
190    ///    .await
191    ///    .expect("error invoking do_get");
192    ///
193    /// // Use try_collect to get the RecordBatches from the server
194    /// let batches: Vec<RecordBatch> = response
195    ///    .try_collect()
196    ///    .await
197    ///    .expect("no stream errors");
198    /// # }
199    /// ```
200    pub async fn do_get(&mut self, ticket: Ticket) -> Result<FlightRecordBatchStream> {
201        let request = self.make_request(ticket);
202
203        let (md, response_stream, _ext) = self.inner.do_get(request).await?.into_parts();
204        let (response_stream, trailers) = extract_lazy_trailers(response_stream);
205
206        Ok(FlightRecordBatchStream::new_from_flight_data(
207            response_stream.map_err(|status| status.into()),
208        )
209        .with_headers(md)
210        .with_trailers(trailers))
211    }
212
213    /// Make a `GetFlightInfo` call to the server with the provided
214    /// [`FlightDescriptor`] and return the [`FlightInfo`] from the
215    /// server. The [`FlightInfo`] can be used with [`Self::do_get`]
216    /// to retrieve the requested batches.
217    ///
218    /// # Example:
219    /// ```no_run
220    /// # async fn run() {
221    /// # use arrow_flight::FlightClient;
222    /// # use arrow_flight::FlightDescriptor;
223    /// # let channel: tonic::transport::Channel = unimplemented!();
224    /// let mut client = FlightClient::new(channel);
225    ///
226    /// // Send a 'CMD' request to the server
227    /// let request = FlightDescriptor::new_cmd(b"MOAR DATA".to_vec());
228    /// let flight_info = client
229    ///   .get_flight_info(request)
230    ///   .await
231    ///   .expect("error handshaking");
232    ///
233    /// // retrieve the first endpoint from the returned flight info
234    /// let ticket = flight_info
235    ///   .endpoint[0]
236    ///   // Extract the ticket
237    ///   .ticket
238    ///   .clone()
239    ///   .expect("expected ticket");
240    ///
241    /// // Retrieve the corresponding RecordBatch stream with do_get
242    /// let data = client
243    ///   .do_get(ticket)
244    ///   .await
245    ///   .expect("error fetching data");
246    /// # }
247    /// ```
248    pub async fn get_flight_info(&mut self, descriptor: FlightDescriptor) -> Result<FlightInfo> {
249        let request = self.make_request(descriptor);
250
251        let response = self.inner.get_flight_info(request).await?.into_inner();
252        Ok(response)
253    }
254
255    /// Make a `PollFlightInfo` call to the server with the provided
256    /// [`FlightDescriptor`] and return the [`PollInfo`] from the
257    /// server.
258    ///
259    /// The `info` field of the [`PollInfo`] can be used with
260    /// [`Self::do_get`] to retrieve the requested batches.
261    ///
262    /// If the `flight_descriptor` field of the [`PollInfo`] is
263    /// `None` then the `info` field represents the complete results.
264    ///
265    /// If the `flight_descriptor` field is some [`FlightDescriptor`]
266    /// then the `info` field has incomplete results, and the client
267    /// should call this method again with the new `flight_descriptor`
268    /// to get the updated status.
269    ///
270    /// The `expiration_time`, if set, represents the expiration time
271    /// of the `flight_descriptor`, after which the server may not accept
272    /// this retry descriptor and may cancel the query.
273    ///
274    /// # Example:
275    /// ```no_run
276    /// # async fn run() {
277    /// # use arrow_flight::FlightClient;
278    /// # use arrow_flight::FlightDescriptor;
279    /// # let channel: tonic::transport::Channel = unimplemented!();
280    /// let mut client = FlightClient::new(channel);
281    ///
282    /// // Send a 'CMD' request to the server
283    /// let request = FlightDescriptor::new_cmd(b"MOAR DATA".to_vec());
284    /// let poll_info = client
285    ///   .poll_flight_info(request)
286    ///   .await
287    ///   .expect("error handshaking");
288    ///
289    /// // retrieve the first endpoint from the returned poll info
290    /// let ticket = poll_info
291    ///   .info
292    ///   .expect("expected flight info")
293    ///   .endpoint[0]
294    ///   // Extract the ticket
295    ///   .ticket
296    ///   .clone()
297    ///   .expect("expected ticket");
298    ///
299    /// // Retrieve the corresponding RecordBatch stream with do_get
300    /// let data = client
301    ///   .do_get(ticket)
302    ///   .await
303    ///   .expect("error fetching data");
304    /// # }
305    /// ```
306    pub async fn poll_flight_info(&mut self, descriptor: FlightDescriptor) -> Result<PollInfo> {
307        let request = self.make_request(descriptor);
308
309        let response = self.inner.poll_flight_info(request).await?.into_inner();
310        Ok(response)
311    }
312
313    /// Make a `DoPut` call to the server with the provided
314    /// [`Stream`] of [`FlightData`] and returning a
315    /// stream of [`PutResult`].
316    ///
317    /// # Note
318    ///
319    /// The input stream is [`Result`] so that this can be connected
320    /// to a streaming data source, such as [`FlightDataEncoder`](crate::encode::FlightDataEncoder),
321    /// without having to buffer. If the input stream returns an error
322    /// that error will not be sent to the server, instead it will be
323    /// placed into the result stream and the server connection
324    /// terminated.
325    ///
326    /// # Example:
327    /// ```no_run
328    /// # async fn run() {
329    /// # use futures::{TryStreamExt, StreamExt};
330    /// # use std::sync::Arc;
331    /// # use arrow_array::UInt64Array;
332    /// # use arrow_array::RecordBatch;
333    /// # use arrow_flight::{FlightClient, FlightDescriptor, PutResult};
334    /// # use arrow_flight::encode::FlightDataEncoderBuilder;
335    /// # let batch = RecordBatch::try_from_iter(vec![
336    /// #  ("col2", Arc::new(UInt64Array::from_iter([10, 23, 33])) as _)
337    /// # ]).unwrap();
338    /// # let channel: tonic::transport::Channel = unimplemented!();
339    /// let mut client = FlightClient::new(channel);
340    ///
341    /// // encode the batch as a stream of `FlightData`
342    /// let flight_data_stream = FlightDataEncoderBuilder::new()
343    ///   .build(futures::stream::iter(vec![Ok(batch)]));
344    ///
345    /// // send the stream and get the results as `PutResult`
346    /// let response: Vec<PutResult>= client
347    ///   .do_put(flight_data_stream)
348    ///   .await
349    ///   .unwrap()
350    ///   .try_collect() // use TryStreamExt to collect stream
351    ///   .await
352    ///   .expect("error calling do_put");
353    /// # }
354    /// ```
355    pub async fn do_put<S: Stream<Item = Result<FlightData>> + Send + 'static>(
356        &mut self,
357        request: S,
358    ) -> Result<BoxStream<'static, Result<PutResult>>> {
359        let (sender, receiver) = futures::channel::oneshot::channel();
360
361        // Intercepts client errors and sends them to the oneshot channel above
362        let request = Box::pin(request); // Pin to heap
363        let request_stream = FallibleRequestStream::new(sender, request);
364
365        let request = self.make_request(request_stream);
366        let response_stream = self.inner.do_put(request).await?.into_inner();
367
368        // Forwards errors from the error oneshot with priority over responses from server
369        let response_stream = Box::pin(response_stream);
370        let error_stream = FallibleTonicResponseStream::new(receiver, response_stream);
371
372        // combine the response from the server and any error from the client
373        Ok(error_stream.boxed())
374    }
375
376    /// Make a `DoExchange` call to the server with the provided
377    /// [`Stream`] of [`FlightData`] and returning a
378    /// stream of [`FlightData`].
379    ///
380    /// # Example:
381    /// ```no_run
382    /// # async fn run() {
383    /// # use futures::{TryStreamExt, StreamExt};
384    /// # use std::sync::Arc;
385    /// # use arrow_array::UInt64Array;
386    /// # use arrow_array::RecordBatch;
387    /// # use arrow_flight::{FlightClient, FlightDescriptor, PutResult};
388    /// # use arrow_flight::encode::FlightDataEncoderBuilder;
389    /// # let batch = RecordBatch::try_from_iter(vec![
390    /// #  ("col2", Arc::new(UInt64Array::from_iter([10, 23, 33])) as _)
391    /// # ]).unwrap();
392    /// # let channel: tonic::transport::Channel = unimplemented!();
393    /// let mut client = FlightClient::new(channel);
394    ///
395    /// // encode the batch as a stream of `FlightData`
396    /// let flight_data_stream = FlightDataEncoderBuilder::new()
397    ///   .build(futures::stream::iter(vec![Ok(batch)]));
398    ///
399    /// // send the stream and get the results as `RecordBatches`
400    /// let response: Vec<RecordBatch> = client
401    ///   .do_exchange(flight_data_stream)
402    ///   .await
403    ///   .unwrap()
404    ///   .try_collect() // use TryStreamExt to collect stream
405    ///   .await
406    ///   .expect("error calling do_exchange");
407    /// # }
408    /// ```
409    pub async fn do_exchange<S: Stream<Item = Result<FlightData>> + Send + 'static>(
410        &mut self,
411        request: S,
412    ) -> Result<FlightRecordBatchStream> {
413        let (sender, receiver) = futures::channel::oneshot::channel();
414
415        let request = Box::pin(request);
416        // Intercepts client errors and sends them to the oneshot channel above
417        let request_stream = FallibleRequestStream::new(sender, request);
418
419        let request = self.make_request(request_stream);
420        let response_stream = self.inner.do_exchange(request).await?.into_inner();
421
422        let response_stream = Box::pin(response_stream);
423        let error_stream = FallibleTonicResponseStream::new(receiver, response_stream);
424
425        // combine the response from the server and any error from the client
426        Ok(FlightRecordBatchStream::new_from_flight_data(error_stream))
427    }
428
429    /// Make a `ListFlights` call to the server with the provided
430    /// criteria and returning a [`Stream`] of [`FlightInfo`].
431    ///
432    /// # Example:
433    /// ```no_run
434    /// # async fn run() {
435    /// # use futures::TryStreamExt;
436    /// # use bytes::Bytes;
437    /// # use arrow_flight::{FlightInfo, FlightClient};
438    /// # let channel: tonic::transport::Channel = unimplemented!();
439    /// let mut client = FlightClient::new(channel);
440    ///
441    /// // Send 'Name=Foo' bytes as the "expression" to the server
442    /// // and gather the returned FlightInfo
443    /// let responses: Vec<FlightInfo> = client
444    ///   .list_flights(Bytes::from("Name=Foo"))
445    ///   .await
446    ///   .expect("error listing flights")
447    ///   .try_collect() // use TryStreamExt to collect stream
448    ///   .await
449    ///   .expect("error gathering flights");
450    /// # }
451    /// ```
452    pub async fn list_flights(
453        &mut self,
454        expression: impl Into<Bytes>,
455    ) -> Result<BoxStream<'static, Result<FlightInfo>>> {
456        let request = Criteria {
457            expression: expression.into(),
458        };
459
460        let request = self.make_request(request);
461
462        let response = self
463            .inner
464            .list_flights(request)
465            .await?
466            .into_inner()
467            .map_err(|status| status.into());
468
469        Ok(response.boxed())
470    }
471
472    /// Make a `GetSchema` call to the server with the provided
473    /// [`FlightDescriptor`] and returning the associated [`Schema`].
474    ///
475    /// # Example:
476    /// ```no_run
477    /// # async fn run() {
478    /// # use bytes::Bytes;
479    /// # use arrow_flight::{FlightDescriptor, FlightClient};
480    /// # use arrow_schema::Schema;
481    /// # let channel: tonic::transport::Channel = unimplemented!();
482    /// let mut client = FlightClient::new(channel);
483    ///
484    /// // Request the schema result of a 'CMD' request to the server
485    /// let request = FlightDescriptor::new_cmd(b"MOAR DATA".to_vec());
486    ///
487    /// let schema: Schema = client
488    ///   .get_schema(request)
489    ///   .await
490    ///   .expect("error making request");
491    /// # }
492    /// ```
493    pub async fn get_schema(&mut self, flight_descriptor: FlightDescriptor) -> Result<Schema> {
494        let request = self.make_request(flight_descriptor);
495
496        let schema_result = self.inner.get_schema(request).await?.into_inner();
497
498        // attempt decode from IPC
499        let schema: Schema = schema_result.try_into()?;
500
501        Ok(schema)
502    }
503
504    /// Make a `ListActions` call to the server and returning a
505    /// [`Stream`] of [`ActionType`].
506    ///
507    /// # Example:
508    /// ```no_run
509    /// # async fn run() {
510    /// # use futures::TryStreamExt;
511    /// # use arrow_flight::{ActionType, FlightClient};
512    /// # use arrow_schema::Schema;
513    /// # let channel: tonic::transport::Channel = unimplemented!();
514    /// let mut client = FlightClient::new(channel);
515    ///
516    /// // List available actions on the server:
517    /// let actions: Vec<ActionType> = client
518    ///   .list_actions()
519    ///   .await
520    ///   .expect("error listing actions")
521    ///   .try_collect() // use TryStreamExt to collect stream
522    ///   .await
523    ///   .expect("error gathering actions");
524    /// # }
525    /// ```
526    pub async fn list_actions(&mut self) -> Result<BoxStream<'static, Result<ActionType>>> {
527        let request = self.make_request(Empty {});
528
529        let action_stream = self
530            .inner
531            .list_actions(request)
532            .await?
533            .into_inner()
534            .map_err(|status| status.into());
535
536        Ok(action_stream.boxed())
537    }
538
539    /// Make a `DoAction` call to the server and returning a
540    /// [`Stream`] of opaque [`Bytes`].
541    ///
542    /// # Example:
543    /// ```no_run
544    /// # async fn run() {
545    /// # use bytes::Bytes;
546    /// # use futures::TryStreamExt;
547    /// # use arrow_flight::{Action, FlightClient};
548    /// # use arrow_schema::Schema;
549    /// # let channel: tonic::transport::Channel = unimplemented!();
550    /// let mut client = FlightClient::new(channel);
551    ///
552    /// let request = Action::new("my_action", "the body");
553    ///
554    /// // Make a request to run the action on the server
555    /// let results: Vec<Bytes> = client
556    ///   .do_action(request)
557    ///   .await
558    ///   .expect("error executing acton")
559    ///   .try_collect() // use TryStreamExt to collect stream
560    ///   .await
561    ///   .expect("error gathering action results");
562    /// # }
563    /// ```
564    pub async fn do_action(&mut self, action: Action) -> Result<BoxStream<'static, Result<Bytes>>> {
565        let request = self.make_request(action);
566
567        let result_stream = self
568            .inner
569            .do_action(request)
570            .await?
571            .into_inner()
572            .map_err(|status| status.into())
573            .map(|r| {
574                r.map(|r| {
575                    // unwrap inner bytes
576                    let crate::Result { body } = r;
577                    body
578                })
579            });
580
581        Ok(result_stream.boxed())
582    }
583
584    /// Make a `CancelFlightInfo` call to the server and return
585    /// a [`CancelFlightInfoResult`].
586    ///
587    /// # Example:
588    /// ```no_run
589    /// # async fn run() {
590    /// # use arrow_flight::{CancelFlightInfoRequest, FlightClient, FlightDescriptor};
591    /// # let channel: tonic::transport::Channel = unimplemented!();
592    /// let mut client = FlightClient::new(channel);
593    ///
594    /// // Send a 'CMD' request to the server
595    /// let request = FlightDescriptor::new_cmd(b"MOAR DATA".to_vec());
596    /// let flight_info = client
597    ///   .get_flight_info(request)
598    ///   .await
599    ///   .expect("error handshaking");
600    ///
601    /// // Cancel the query
602    /// let request = CancelFlightInfoRequest::new(flight_info);
603    /// let result = client
604    ///   .cancel_flight_info(request)
605    ///   .await
606    ///   .expect("error cancelling");
607    /// # }
608    /// ```
609    pub async fn cancel_flight_info(
610        &mut self,
611        request: CancelFlightInfoRequest,
612    ) -> Result<CancelFlightInfoResult> {
613        let action = Action::new("CancelFlightInfo", request.encode_to_vec());
614        let response = self.do_action(action).await?.try_next().await?;
615        let response = response.ok_or_else(|| {
616            FlightError::protocol("Received no response for cancel_flight_info call")
617        })?;
618        CancelFlightInfoResult::decode(response)
619            .map_err(|e| FlightError::DecodeError(e.to_string()))
620    }
621
622    /// Make a `RenewFlightEndpoint` call to the server and return
623    /// the renewed [`FlightEndpoint`].
624    ///
625    /// # Example:
626    /// ```no_run
627    /// # async fn run() {
628    /// # use arrow_flight::{FlightClient, FlightDescriptor, RenewFlightEndpointRequest};
629    /// # let channel: tonic::transport::Channel = unimplemented!();
630    /// let mut client = FlightClient::new(channel);
631    ///
632    /// // Send a 'CMD' request to the server
633    /// let request = FlightDescriptor::new_cmd(b"MOAR DATA".to_vec());
634    /// let flight_endpoint = client
635    ///   .get_flight_info(request)
636    ///   .await
637    ///   .expect("error handshaking")
638    ///   .endpoint[0];
639    ///
640    /// // Renew the endpoint
641    /// let request = RenewFlightEndpointRequest::new(flight_endpoint);
642    /// let flight_endpoint = client
643    ///   .renew_flight_endpoint(request)
644    ///   .await
645    ///   .expect("error renewing");
646    /// # }
647    /// ```
648    pub async fn renew_flight_endpoint(
649        &mut self,
650        request: RenewFlightEndpointRequest,
651    ) -> Result<FlightEndpoint> {
652        let action = Action::new("RenewFlightEndpoint", request.encode_to_vec());
653        let response = self.do_action(action).await?.try_next().await?;
654        let response = response.ok_or_else(|| {
655            FlightError::protocol("Received no response for renew_flight_endpoint call")
656        })?;
657        FlightEndpoint::decode(response).map_err(|e| FlightError::DecodeError(e.to_string()))
658    }
659
660    /// return a Request, adding any configured metadata
661    fn make_request<R>(&self, t: R) -> tonic::Request<R> {
662        // Pass along metadata
663        let mut request = tonic::Request::new(t);
664        *request.metadata_mut() = self.metadata.clone();
665        request
666    }
667}
668
669#[cfg(test)]
670mod tests {
671    use super::FlightClient;
672    use crate::encode::FlightDataEncoderBuilder;
673    use crate::flight_service_server::{FlightService, FlightServiceServer};
674    use crate::{
675        Action, ActionType, Criteria, Empty, FlightData, FlightDescriptor, FlightInfo,
676        HandshakeRequest, HandshakeResponse, PollInfo, PutResult, SchemaResult, Ticket,
677    };
678    use arrow_array::{RecordBatch, UInt64Array};
679    use bytes::Bytes;
680    use futures::{StreamExt, TryStreamExt, stream::BoxStream};
681    use std::net::SocketAddr;
682    use std::sync::{Arc, Mutex};
683    use std::time::Duration;
684    use tokio::net::TcpListener;
685    use tokio::task::JoinHandle;
686    use tonic::metadata::MetadataMap;
687    use tonic::service::interceptor::InterceptedService;
688    use tonic::transport::Channel;
689    use tonic::{Request, Response, Status, Streaming};
690    use uuid::Uuid;
691
692    /// Minimal `FlightService` that records request metadata and serves a
693    /// configured `do_get` response. Other RPCs return `Unimplemented`.
694    #[derive(Debug, Clone, Default)]
695    struct InterceptorTestServer {
696        state: Arc<Mutex<InterceptorTestState>>,
697    }
698
699    #[derive(Debug, Default)]
700    struct InterceptorTestState {
701        do_get_request: Option<Ticket>,
702        do_get_response: Option<Vec<Result<RecordBatch, Status>>>,
703        last_request_metadata: Option<MetadataMap>,
704    }
705
706    impl InterceptorTestServer {
707        fn save_metadata<T>(&self, request: &Request<T>) {
708            self.state.lock().unwrap().last_request_metadata = Some(request.metadata().clone());
709        }
710
711        fn set_do_get_response(&self, response: Vec<Result<RecordBatch, Status>>) {
712            self.state.lock().unwrap().do_get_response = Some(response);
713        }
714
715        fn take_do_get_request(&self) -> Option<Ticket> {
716            self.state.lock().unwrap().do_get_request.take()
717        }
718
719        fn take_last_request_metadata(&self) -> Option<MetadataMap> {
720            self.state.lock().unwrap().last_request_metadata.take()
721        }
722    }
723
724    #[tonic::async_trait]
725    impl FlightService for InterceptorTestServer {
726        type HandshakeStream = BoxStream<'static, Result<HandshakeResponse, Status>>;
727        type ListFlightsStream = BoxStream<'static, Result<FlightInfo, Status>>;
728        type DoGetStream = BoxStream<'static, Result<FlightData, Status>>;
729        type DoPutStream = BoxStream<'static, Result<PutResult, Status>>;
730        type DoActionStream = BoxStream<'static, Result<crate::Result, Status>>;
731        type ListActionsStream = BoxStream<'static, Result<ActionType, Status>>;
732        type DoExchangeStream = BoxStream<'static, Result<FlightData, Status>>;
733
734        async fn do_get(
735            &self,
736            request: Request<Ticket>,
737        ) -> Result<Response<Self::DoGetStream>, Status> {
738            self.save_metadata(&request);
739            let mut state = self.state.lock().unwrap();
740            state.do_get_request = Some(request.into_inner());
741
742            let batches = state
743                .do_get_response
744                .take()
745                .ok_or_else(|| Status::internal("no do_get response configured"))?;
746            let batch_stream = futures::stream::iter(batches).map_err(Into::into);
747            let stream = FlightDataEncoderBuilder::new()
748                .build(batch_stream)
749                .map_err(Into::into);
750            Ok(Response::new(stream.boxed()))
751        }
752
753        async fn handshake(
754            &self,
755            _: Request<Streaming<HandshakeRequest>>,
756        ) -> Result<Response<Self::HandshakeStream>, Status> {
757            Err(Status::unimplemented(""))
758        }
759        async fn list_flights(
760            &self,
761            _: Request<Criteria>,
762        ) -> Result<Response<Self::ListFlightsStream>, Status> {
763            Err(Status::unimplemented(""))
764        }
765        async fn get_flight_info(
766            &self,
767            _: Request<FlightDescriptor>,
768        ) -> Result<Response<FlightInfo>, Status> {
769            Err(Status::unimplemented(""))
770        }
771        async fn poll_flight_info(
772            &self,
773            _: Request<FlightDescriptor>,
774        ) -> Result<Response<PollInfo>, Status> {
775            Err(Status::unimplemented(""))
776        }
777        async fn get_schema(
778            &self,
779            _: Request<FlightDescriptor>,
780        ) -> Result<Response<SchemaResult>, Status> {
781            Err(Status::unimplemented(""))
782        }
783        async fn do_put(
784            &self,
785            _: Request<Streaming<FlightData>>,
786        ) -> Result<Response<Self::DoPutStream>, Status> {
787            Err(Status::unimplemented(""))
788        }
789        async fn do_action(
790            &self,
791            _: Request<Action>,
792        ) -> Result<Response<Self::DoActionStream>, Status> {
793            Err(Status::unimplemented(""))
794        }
795        async fn list_actions(
796            &self,
797            _: Request<Empty>,
798        ) -> Result<Response<Self::ListActionsStream>, Status> {
799            Err(Status::unimplemented(""))
800        }
801        async fn do_exchange(
802            &self,
803            _: Request<Streaming<FlightData>>,
804        ) -> Result<Response<Self::DoExchangeStream>, Status> {
805            Err(Status::unimplemented(""))
806        }
807    }
808
809    /// Spawns the test server on a background task and exposes a connected channel.
810    struct InterceptorTestFixture {
811        shutdown: Option<tokio::sync::oneshot::Sender<()>>,
812        addr: SocketAddr,
813        handle: Option<JoinHandle<Result<(), tonic::transport::Error>>>,
814    }
815
816    impl InterceptorTestFixture {
817        async fn new(server: FlightServiceServer<InterceptorTestServer>) -> Self {
818            let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
819            let addr = listener.local_addr().unwrap();
820            let (tx, rx) = tokio::sync::oneshot::channel();
821            let shutdown_future = async move {
822                rx.await.ok();
823            };
824            let serve = tonic::transport::Server::builder()
825                .timeout(Duration::from_secs(30))
826                .add_service(server)
827                .serve_with_incoming_shutdown(
828                    tokio_stream::wrappers::TcpListenerStream::new(listener),
829                    shutdown_future,
830                );
831            let handle = tokio::task::spawn(serve);
832            Self {
833                shutdown: Some(tx),
834                addr,
835                handle: Some(handle),
836            }
837        }
838
839        async fn channel(&self) -> Channel {
840            let url = format!("http://{}", self.addr);
841            tonic::transport::Endpoint::from_shared(url)
842                .expect("valid endpoint")
843                .timeout(Duration::from_secs(30))
844                .connect()
845                .await
846                .expect("error connecting to server")
847        }
848
849        async fn shutdown_and_wait(mut self) {
850            if let Some(tx) = self.shutdown.take() {
851                tx.send(()).expect("server quit early");
852            }
853            if let Some(handle) = self.handle.take() {
854                handle
855                    .await
856                    .expect("task join error (panic?)")
857                    .expect("server error at shutdown");
858            }
859        }
860    }
861
862    /// Integration test: a tonic [`Channel`] wrapped in an [`InterceptedService`]
863    /// that injects a custom header is passed to [`FlightClient`], and the server
864    /// observes the header on the request.
865    #[tokio::test]
866    async fn test_flight_client_with_intercepted_channel_passes_custom_header() {
867        let test_server = InterceptorTestServer::default();
868        let fixture =
869            InterceptorTestFixture::new(FlightServiceServer::new(test_server.clone())).await;
870
871        let channel = fixture.channel().await;
872
873        let header_name = "x-random-header";
874        let header_value = format!("random-{}", Uuid::new_v4());
875        let header_value_for_interceptor = header_value.clone();
876
877        let interceptor = move |mut req: Request<()>| -> Result<Request<()>, Status> {
878            req.metadata_mut().insert(
879                header_name,
880                header_value_for_interceptor
881                    .parse()
882                    .expect("valid metadata value"),
883            );
884            Ok(req)
885        };
886
887        let intercepted = InterceptedService::new(channel, interceptor);
888        let mut client = FlightClient::new(intercepted);
889
890        let ticket = Ticket {
891            ticket: Bytes::from("dummy-ticket"),
892        };
893
894        let batch = RecordBatch::try_from_iter(vec![(
895            "col",
896            Arc::new(UInt64Array::from_iter([1, 2, 3, 4])) as _,
897        )])
898        .unwrap();
899
900        test_server.set_do_get_response(vec![Ok(batch.clone())]);
901
902        let response_stream = client
903            .do_get(ticket.clone())
904            .await
905            .expect("error making do_get request");
906
907        let response: Vec<RecordBatch> = response_stream
908            .try_collect()
909            .await
910            .expect("error streaming data");
911
912        assert_eq!(response, vec![batch]);
913        assert_eq!(test_server.take_do_get_request(), Some(ticket));
914
915        let metadata = test_server
916            .take_last_request_metadata()
917            .expect("server received headers")
918            .into_headers();
919
920        let received = metadata
921            .get(header_name)
922            .expect("interceptor header missing on server")
923            .to_str()
924            .expect("ascii header value");
925        assert_eq!(received, header_value);
926
927        fixture.shutdown_and_wait().await;
928    }
929}