Writing a Flight Service#

Servers are subclasses ofFlightServerBase. To implementindividual RPCs, override the RPC methods on this class.

importpyarrow.flightasflightclassMyFlightServer(flight.FlightServerBase):deflist_flights(self,context,criteria):info=flight.FlightInfo(...)yieldinfo

Each RPC method always takes aServerCallContext for commonparameters. To indicate failure, raise an exception; Flight-specificerrors can be indicated by raising one of the subclasses ofFlightError.

To start a server, create aLocation to specify where tolisten, and create an instance of the server. (A string will beconverted into a location.) This will start the server, but won’tblock the rest of the program. CallFlightServerBase.serve() toblock until the server stops.

# Listen to all interfaces on a free portserver=MyFlightServer("grpc://0.0.0.0:0")print("Server listening on port",server.port)server.serve()

Using the Flight Client#

To connect to a Flight service, callpyarrow.flight.connect()with a location.

Cancellation and Timeouts#

When making a call, clients can optionally provideFlightCallOptions. This allows clients to set a timeout oncalls or provide custom HTTP headers, among other features. Also, someobjects returned by client RPC calls expose acancel method whichallows terminating a call early.

On the server side, timeouts are transparent. For cancellation, theserver needs to manually pollServerCallContext.is_cancelled()to check if the client has cancelled the call, and if so, break out ofany processing the server is currently doing.

Enabling TLS#

TLS can be enabled when setting up a server by providing a certificateand key pair toFlightServerBase.

On the client side, useLocation.for_grpc_tls() to construct theLocation to listen on.

Enabling Authentication#

Handshake-based authentication can be enabled by implementingServerAuthHandler. Authentication consists of two parts: oninitial client connection, the server and client authenticationimplementations can perform any negotiation needed; then, on each RPCthereafter, the client provides a token. The server authenticationhandler validates the token and provides the identity of theclient. This identity can be obtained from theServerCallContext.

Custom Middleware#

Servers and clients support custom middleware (or interceptors) thatare called on every request and can modify the request in a limitedfashion. These can be implemented by subclassingServerMiddleware andClientMiddleware, thenproviding them when creating the client or server.

Middleware are fairly limited, but they can add headers to arequest/response. On the server, they can inspect incoming headers andfail the request; hence, they can be used to implement customauthentication methods.

Flight best practices#