Arrow Flight RPC¶

Arrow Flight is an RPC framework for efficient transfer of Flight data over the network. See Arrow Flight RPC for full details on the protocol, or Arrow Flight RPC for API docs.

Writing a Flight Service¶

Servers are subclasses of arrow::flight::FlightServerBase. To implement individual RPCs, override the RPC methods on this class.

class MyFlightServer : public FlightServerBase {
  Status ListFlights(const ServerCallContext& context, const Criteria* criteria,
                     std::unique_ptr<FlightListing>* listings) override {
    std::vector<FlightInfo> flights = ...;
    *listings = std::unique_ptr<FlightListing>(new SimpleFlightListing(flights));
    return Status::OK();
  }
};

Each RPC method always takes a arrow::flight::ServerCallContext for common parameters and returns a arrow::Status to indicate success or failure. Flight-specific error codes can be returned via arrow::flight::MakeFlightError().

RPC methods that return a value in addition to a status will use an out parameter, as shown above. Often, there are helper classes providing basic implementations of these out parameters. For instance, above, arrow::flight::SimpleFlightListing uses a vector of arrow::flight::FlightInfo objects as the result of a ListFlights RPC.

To start a server, create a arrow::flight::Location to specify where to listen, and call arrow::flight::FlightServerBase::Init(). This will start the server, but won’t block the rest of the program. Use arrow::flight::FlightServerBase::SetShutdownOnSignals() to enable stopping the server if an interrupt signal is received, then call arrow::flight::FlightServerBase::Serve() to block until the server stops.

std::unique_ptr<arrow::flight::FlightServerBase> server;
// Initialize server
arrow::flight::Location location;
// Listen to all interfaces on a free port
ARROW_CHECK_OK(arrow::flight::Location::ForGrpcTcp("0.0.0.0", 0, &location));
arrow::flight::FlightServerOptions options(location);

// Start the server
ARROW_CHECK_OK(server->Init(options));
// Exit with a clean error code (0) on SIGTERM
ARROW_CHECK_OK(server->SetShutdownOnSignals({SIGTERM}));

std::cout << "Server listening on localhost:" << server->port() << std::endl;
ARROW_CHECK_OK(server->Serve());

Enabling TLS and Authentication¶

TLS can be enabled by providing a certificate and key pair to FlightServerBase::Init. Additionally, use Location::ForGrpcTls to construct the arrow::flight::Location to listen on.

Similarly, authentication can be enabled by providing an implementation of ServerAuthHandler. Authentication consists of two parts: on initial client connection, the server and client authentication implementations can perform any negotiation needed; then, on each RPC thereafter, the client provides a token. The server authentication handler validates the token and provides the identity of the client. This identity can be obtained from the arrow::flight::ServerCallContext.

Using the Flight Client¶

To connect to a Flight service, create an instance of arrow::flight::FlightClient by calling Connect. This takes a Location and returns the client through an out parameter. To authenticate, call Authenticate with the desired client authentication implementation.

Each RPC method returns arrow::Status to indicate the success/failure of the request. Any other return values are specified through out parameters. They also take an optional options parameter that allows specifying a timeout for the call.

Tabular Datasets

Examples