]>
Commit | Line | Data |
---|---|---|
1d09f67e TL |
1 | .. Licensed to the Apache Software Foundation (ASF) under one |
2 | .. or more contributor license agreements. See the NOTICE file | |
3 | .. distributed with this work for additional information | |
4 | .. regarding copyright ownership. The ASF licenses this file | |
5 | .. to you under the Apache License, Version 2.0 (the | |
6 | .. "License"); you may not use this file except in compliance | |
7 | .. with the License. You may obtain a copy of the License at | |
8 | ||
9 | .. http://www.apache.org/licenses/LICENSE-2.0 | |
10 | ||
11 | .. Unless required by applicable law or agreed to in writing, | |
12 | .. software distributed under the License is distributed on an | |
13 | .. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
14 | .. KIND, either express or implied. See the License for the | |
15 | .. specific language governing permissions and limitations | |
16 | .. under the License. | |
17 | ||
18 | .. default-domain:: cpp | |
19 | .. highlight:: cpp | |
20 | ||
21 | ================ | |
22 | Arrow Flight RPC | |
23 | ================ | |
24 | ||
25 | Arrow Flight is an RPC framework for efficient transfer of Flight data | |
26 | over the network. See :doc:`../format/Flight` for full details on | |
27 | the protocol, or :doc:`./api/flight` for API docs. | |
28 | ||
29 | Writing a Flight Service | |
30 | ======================== | |
31 | ||
32 | Servers are subclasses of :class:`arrow::flight::FlightServerBase`. To | |
33 | implement individual RPCs, override the RPC methods on this class. | |
34 | ||
35 | .. code-block:: cpp | |
36 | ||
37 | class MyFlightServer : public FlightServerBase { | |
38 | Status ListFlights(const ServerCallContext& context, const Criteria* criteria, | |
39 | std::unique_ptr<FlightListing>* listings) override { | |
40 | std::vector<FlightInfo> flights = ...; | |
41 | *listings = std::unique_ptr<FlightListing>(new SimpleFlightListing(flights)); | |
42 | return Status::OK(); | |
43 | } | |
44 | }; | |
45 | ||
46 | Each RPC method always takes a | |
47 | :class:`arrow::flight::ServerCallContext` for common parameters and | |
48 | returns a :class:`arrow::Status` to indicate success or | |
49 | failure. Flight-specific error codes can be returned via | |
50 | :func:`arrow::flight::MakeFlightError`. | |
51 | ||
52 | RPC methods that return a value in addition to a status will use an | |
53 | out parameter, as shown above. Often, there are helper classes | |
54 | providing basic implementations of these out parameters. For instance, | |
55 | above, :class:`arrow::flight::SimpleFlightListing` uses a vector of | |
56 | :class:`arrow::flight::FlightInfo` objects as the result of a | |
57 | ``ListFlights`` RPC. | |
58 | ||
59 | To start a server, create a :class:`arrow::flight::Location` to | |
60 | specify where to listen, and call | |
61 | :func:`arrow::flight::FlightServerBase::Init`. This will start the | |
62 | server, but won't block the rest of the program. Use | |
63 | :func:`arrow::flight::FlightServerBase::SetShutdownOnSignals` to | |
64 | enable stopping the server if an interrupt signal is received, then | |
65 | call :func:`arrow::flight::FlightServerBase::Serve` to block until the | |
66 | server stops. | |
67 | ||
68 | .. code-block:: cpp | |
69 | ||
70 | std::unique_ptr<arrow::flight::FlightServerBase> server; | |
71 | // Initialize server | |
72 | arrow::flight::Location location; | |
73 | // Listen to all interfaces on a free port | |
74 | ARROW_CHECK_OK(arrow::flight::Location::ForGrpcTcp("0.0.0.0", 0, &location)); | |
75 | arrow::flight::FlightServerOptions options(location); | |
76 | ||
77 | // Start the server | |
78 | ARROW_CHECK_OK(server->Init(options)); | |
79 | // Exit with a clean error code (0) on SIGTERM | |
80 | ARROW_CHECK_OK(server->SetShutdownOnSignals({SIGTERM})); | |
81 | ||
82 | std::cout << "Server listening on localhost:" << server->port() << std::endl; | |
83 | ARROW_CHECK_OK(server->Serve()); | |
84 | ||
85 | ||
86 | Enabling TLS and Authentication | |
87 | ------------------------------- | |
88 | ||
89 | TLS can be enabled by providing a certificate and key pair to | |
90 | :func:`FlightServerBase::Init | |
91 | <arrow::flight::FlightServerBase::Init>`. Additionally, use | |
92 | :func:`Location::ForGrpcTls <arrow::flight::Location::ForGrpcTls>` to | |
93 | construct the :class:`arrow::flight::Location` to listen on. | |
94 | ||
95 | Similarly, authentication can be enabled by providing an | |
96 | implementation of :class:`ServerAuthHandler | |
97 | <arrow::flight::ServerAuthHandler>`. Authentication consists of two | |
98 | parts: on initial client connection, the server and client | |
99 | authentication implementations can perform any negotiation needed; | |
100 | then, on each RPC thereafter, the client provides a token. The server | |
101 | authentication handler validates the token and provides the identity | |
102 | of the client. This identity can be obtained from the | |
103 | :class:`arrow::flight::ServerCallContext`. | |
104 | ||
105 | Using the Flight Client | |
106 | ======================= | |
107 | ||
108 | To connect to a Flight service, create an instance of | |
109 | :class:`arrow::flight::FlightClient` by calling :func:`Connect | |
110 | <arrow::flight::FlightClient::Connect>`. This takes a Location and | |
111 | returns the client through an out parameter. To authenticate, call | |
112 | :func:`Authenticate <arrow::flight::FlightClient::Authenticate>` with | |
113 | the desired client authentication implementation. | |
114 | ||
115 | Each RPC method returns :class:`arrow::Status` to indicate the | |
116 | success/failure of the request. Any other return values are specified | |
117 | through out parameters. They also take an optional :class:`options | |
118 | <arrow::flight::FlightCallOptions>` parameter that allows specifying a | |
119 | timeout for the call. |