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}