Arrow Flight RPC

Arrow Flight 是一个基于 Arrow 数据的高性能数据服务 RPC 框架，构建于 gRPC 和 IPC 格式 之上。

Flight 围绕 Arrow 记录批次的流进行组织，可以从其他服务下载或上传到其他服务。一组元数据方法提供了流的发现和自省功能，以及实现特定于应用程序的方法的能力。

方法和消息线路格式由 Protobuf 定义，使其能够与可能分别支持 gRPC 和 Arrow 但不支持 Flight 的客户端进行互操作。但是，Flight 实现包含进一步的优化，以避免 Protobuf 的使用开销（主要是避免过多的内存复制）。

RPC 方法和请求模式

Flight 定义了一组 RPC 方法，用于上传/下载数据、检索有关数据流的元数据、列出可用数据流以及实现特定于应用程序的 RPC 方法。 Flight 服务实现这些方法的某个子集，而 Flight 客户端可以调用任何这些方法。

数据流由描述符（FlightDescriptor 消息）标识，这些描述符是路径或任意二进制命令。例如，描述符可以编码 SQL 查询、分布式文件系统上的文件路径，甚至 pickled Python 对象；应用程序可以根据需要使用此消息。

因此，一个 Flight 客户端可以连接到任何服务并执行基本操作。为了方便起见，期望 Flight 服务支持一些常见的请求模式，接下来将进行描述。当然，应用程序可能会忽略兼容性，只是将 Flight RPC 方法视为其自身用途的低级构建块。

有关所涉及方法和消息的完整详细信息，请参阅Protocol Buffer 定义。

下载数据

希望下载数据的客户端将

通过 DoGet 检索数据。

1. 为他们感兴趣的数据集构造或获取 FlightDescriptor。

   客户端可能已经知道他们想要的描述符，或者他们可以使用 ListFlights 之类的方法来发现它们。

2. 调用 GetFlightInfo(FlightDescriptor) 以获取 FlightInfo 消息。

   Flight 不要求数据与元数据位于同一服务器上。因此，FlightInfo 包含有关数据位置的详细信息，以便客户端可以从适当的服务器获取数据。这被编码为 FlightInfo 内部的一系列 FlightEndpoint 消息。 每个端点代表包含响应数据子集的某个位置。

   端点包含可以从中检索此数据的 location 列表（服务器地址）以及 Ticket，这是一个不透明的二进制令牌，服务器将使用它来标识所请求的数据。

   如果 FlightInfo.ordered 为 true，则表示来自不同端点的数据之间存在某种顺序。客户端应产生与将每个端点返回的数据按顺序从前到后连接起来时相同的结果。

   如果 FlightInfo.ordered 为 false，则客户端可以按任意顺序返回来自任何端点的数据。来自任何特定端点的数据必须按顺序返回，但来自不同端点的数据可以交错以允许并行获取。

   请注意，由于某些客户端可能会忽略 FlightInfo.ordered，如果顺序很重要并且无法确保客户端支持，则服务器应返回单个端点。

   响应还包含其他元数据，例如模式，以及可选的数据集大小估计。

3. 使用服务器返回的每个端点。

   要使用端点，客户端应连接到端点中的其中一个 location，然后使用端点中的 ticket 调用 DoGet(Ticket)。这将为客户端提供 Arrow 记录批次流。

   如果服务器希望指示数据位于本地服务器上而不是其他位置，则它可以返回一个空的 location 列表。然后客户端可以重用与原始服务器的现有连接来获取数据。否则，客户端必须连接到指示的 location 之一。

   服务器可以将“自身”列为 location，与其他服务器 location 并列。通常这需要服务器知道其公共地址，但它也可以使用特殊 URI 字符串 arrow-flight-reuse-connection://? 来告诉客户端它们可以重用与同一服务器的现有连接，而无需能够命名自身。请参阅下面的连接重用。

   这样，端点内的 location 也可以被认为是执行旁路负载平衡或服务发现功能。端点可以表示分区或以其他方式分布的数据。

   客户端必须使用所有端点才能检索完整的数据集。客户端可以以任何顺序甚至并行使用端点，或者将端点分发到多台机器进行使用；这取决于应用程序的实现。客户端还可以使用 FlightInfo.ordered。有关 FlightInfo.ordered 的详细信息，请参阅上一项。

   每个端点可能都有过期时间（FlightEndpoint.expiration_time）。如果端点有过期时间，客户端可以通过 DoGet 多次获取数据，直到达到过期时间。否则，DoGet 请求是否可以重试由应用程序定义。过期时间表示为 google.protobuf.Timestamp。

   如果过期时间很短，客户端可以通过 RenewFlightEndpoint 操作延长过期时间。客户端需要使用 DoAction 和 RenewFlightEndpoint 操作类型来延长过期时间。Action.body 必须是具有要续订的 FlightEndpoint 的 RenewFlightEndpointRequest。

   客户端可以通过 CancelFlightInfo 操作取消返回的 FlightInfo。客户端需要使用带有 CancelFlightInfo 操作类型的 DoAction 来取消 FlightInfo。

通过运行耗时查询下载数据

客户端可能需要请求耗时查询以下载数据。但是，GetFlightInfo 在查询完成之前不会返回，因此客户端会被阻塞。在这种情况下，客户端可以使用 PollFlightInfo 代替 GetFlightInfo

通过 PollFlightInfo 轮询长时间运行的查询。

1. 与以前一样，构造或获取 FlightDescriptor。

2. 调用 PollFlightInfo(FlightDescriptor) 以获取 PollInfo 消息。

   服务器应在第一次调用时尽快响应。因此客户端不应该等待第一个 PollInfo 响应。

   如果查询未完成，PollInfo.flight_descriptor 将具有 FlightDescriptor。客户端应使用描述符（而不是原始的 FlightDescriptor）来调用下一个 PollFlightInfo()。如果客户端错过了两次更新之间，服务器应该能够识别不一定是最新 PollInfo.flight_descriptor。

   如果查询已完成，则 PollInfo.flight_descriptor 将未设置。

   PollInfo.info 是迄今为止可用的最新结果。每次它都是一个完整的 FlightInfo，而不仅仅是前一个和当前 FlightInfo 之间的增量。服务器应该每次只追加到 PollInfo.info 中的端点。因此，即使查询尚未完成，客户端也可以使用 PollInfo.info 中的 Ticket 运行 DoGet(Ticket)。 FlightInfo.ordered 也是有效的。

   服务器不应该响应，直到结果与上次不同。这样，客户端可以“长轮询”更新，而无需不断发出请求。客户端可以设置一个短超时，以避免在需要时阻塞调用。

   可以设置 PollInfo.progress。它表示查询的进度。如果设置了，则值必须在 [0.0, 1.0] 范围内。该值不一定是单调的或非递减的。服务器可能只通过更新 PollInfo.progress 值来响应，但它不应该用更新来刷屏客户端。

   PollInfo.timestamp 是此请求的到期时间。超过此时间后，服务器可能不再接受轮询描述符，并且查询可能会被取消。这可能会在调用 PollFlightInfo 时更新。到期时间表示为 google.protobuf.Timestamp。

   客户端可以通过 CancelFlightInfo 操作取消查询。

   如果查询失败，服务器应该返回错误状态而不是响应。客户端不应该轮询请求，除非是 TIMED_OUT 和 UNAVAILABLE，这两种错误可能并非源自服务器。

3. 像以前一样使用服务器返回的每个端点。

上传数据

要上传数据，客户端需要

通过 DoPut 上传数据。

1. 与以前一样，构造或获取 FlightDescriptor。

2. 调用 DoPut(FlightData) 并上传 Arrow 记录批次的流。

   FlightDescriptor 包含在第一条消息中，以便服务器可以识别数据集。

DoPut 允许服务器向客户端发送带有自定义元数据的响应消息。这可以用来实现诸如可恢复写入之类的事情（例如，服务器可以定期发送一条消息，指示到目前为止已提交了多少行）。

交换数据

某些用例可能需要在单个调用中上传和下载数据。虽然这可以通过多次调用来模拟，但如果应用程序是有状态的，这可能会很困难。例如，应用程序可能希望实现一个调用，客户端上传数据，服务器响应数据的转换；如果使用 DoGet 和 DoPut 实现，这将需要是有状态的。相反，DoExchange 允许将其作为单个调用实现。客户端需要

使用 DoExchange 进行复杂的数据流。

1. 与以前一样，构造或获取 FlightDescriptor。

2. 调用 DoExchange(FlightData)。

   与 DoPut 一样，FlightDescriptor 包含在第一条消息中。此时，客户端和服务器都可以同时向对方传输数据流。

身份验证

Flight 支持各种身份验证方法，应用程序可以根据其需求进行自定义。

“握手”身份验证

这分为两部分实现。在连接时，客户端调用 Handshake RPC 方法，应用程序定义的身份验证处理程序可以与其在服务器上的对应方交换任意数量的消息。然后，处理程序提供一个二进制令牌。然后，Flight 客户端将在所有未来调用的标头中包含此令牌，服务器身份验证处理程序将对其进行验证。

应用程序可以使用其中的任何部分；例如，它们可以忽略初始握手并在每次调用时发送一个外部获取的令牌（例如，承载令牌），或者它们可以在握手期间建立信任并且不为每次调用验证令牌，将连接视为有状态的（“登录”模式）。

警告

除非每次调用都验证令牌，否则此模式不安全，尤其是在存在第 7 层负载均衡器（gRPC 常见）或 gRPC 透明地重新连接客户端的情况下。

基于标头/基于中间件的身份验证

客户端可以在调用中包含自定义标头。然后可以实现自定义中间件，以在服务器端验证和接受/拒绝调用。

双向 TLS (mTLS)

客户端在连接建立期间提供证书，服务器验证该证书。应用程序不需要实现任何身份验证代码，但必须配置和分发证书。

这可能仅在某些实现中可用，并且仅在启用 TLS 时才可用。

某些 Flight 实现也可能公开底层 gRPC API，在这种情况下，可以使用 gRPC 支持的任何身份验证方法。

位置 URI

Flight 主要根据其 Protobuf 和下面的 gRPC 规范定义，但 Arrow 实现也可能支持替代传输（请参阅 Flight RPC）。客户端和服务器需要知道对 Location 中的给定 URI 使用哪种传输，因此 Flight 实现应为给定传输使用以下 URI 方案

传输	URI 方案
gRPC（明文）	grpc: 或 grpc+tcp
gRPC (TLS)	grpc+tls
gRPC（Unix 域套接字）	grpc+unix
（重用连接）	arrow-flight-reuse-connection
UCX（明文） (1)	ucx

备注

• (1) Flight UCX 传输已在 19.0.0 版本中弃用。分离式 IPC 协议 部分提出了替代方案。

连接重用

上面的“重用连接”不是一种特定的传输方式。相反，这意味着客户端可以尝试对最初从中获取 FlightInfo 的同一服务器（并通过同一连接）执行 DoGet（即，它针对该服务器调用了 GetFlightInfo）。这与没有返回特定 Location 时的解释方式相同。

这允许服务器将“自身”作为获取数据的可能位置之一返回，而无需知道自己的公共地址，这在难以或不可能知道这一点的部署中非常有用。例如，开发人员可以在云环境中将远程服务转发到他们的本地机器；在这种情况下，远程服务将无法知道它正在被访问的本地主机名和端口。

出于兼容性原因，URI 应始终为 arrow-flight-reuse-connection://?，并带有尾随的空查询字符串。Java 的 URI 实现不接受 scheme: 或 scheme://，而 C++ 的实现不接受空字符串，因此显而易见的候选项不兼容。所选的表示可以被这两种实现以及 Go 的 net/url 和 Python 的 urllib.parse 解析。

错误处理

Arrow Flight 定义了自己的错误代码集。不同语言的实现方式不同（例如，在 C++ 中，Unimplemented 是一般的 Arrow 错误状态，而在 Java 中它是特定于 Flight 的异常），但会公开以下错误代码集

错误代码	说明
UNKNOWN	未知错误。如果没有其他错误适用，则为默认值。
INTERNAL	服务实现内部发生错误。
INVALID_ARGUMENT	客户端向 RPC 传递了无效参数。
TIMED_OUT	操作超过了超时时间或截止日期。
NOT_FOUND	找不到请求的资源（操作、数据流）。
ALREADY_EXISTS	资源已存在。
CANCELLED	操作被取消（由客户端或服务器取消）。
UNAUTHENTICATED	客户端未通过身份验证。
UNAUTHORIZED	客户端已通过身份验证，但没有执行请求操作的权限。
UNIMPLEMENTED	未实现 RPC。
UNAVAILABLE	服务器不可用。客户端可能由于连接原因发出此错误。

外部资源

• https://arrow.apache.org/blog/2019/10/13/introducing-arrow-flight/

• https://arrow.apache.org/blog/2018/10/09/0.11.0-release/

• https://www.slideshare.net/JacquesNadeau5/apache-arrow-flight-overview

协议缓冲区定义

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 * <p>
 * https://apache.org/licenses/LICENSE-2.0
 * <p>
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

syntax = "proto3";
import "google/protobuf/timestamp.proto";

option java_package = "org.apache.arrow.flight.impl";
option go_package = "github.com/apache/arrow-go/arrow/flight/gen/flight";
option csharp_namespace = "Apache.Arrow.Flight.Protocol";

package arrow.flight.protocol;

/*
 * A flight service is an endpoint for retrieving or storing Arrow data. A
 * flight service can expose one or more predefined endpoints that can be
 * accessed using the Arrow Flight Protocol. Additionally, a flight service
 * can expose a set of actions that are available.
 */
service FlightService {

  /*
   * Handshake between client and server. Depending on the server, the
   * handshake may be required to determine the token that should be used for
   * future operations. Both request and response are streams to allow multiple
   * round-trips depending on auth mechanism.
   */
  rpc Handshake(stream HandshakeRequest) returns (stream HandshakeResponse) {}

  /*
   * Get a list of available streams given a particular criteria. Most flight
   * services will expose one or more streams that are readily available for
   * retrieval. This api allows listing the streams available for
   * consumption. A user can also provide a criteria. The criteria can limit
   * the subset of streams that can be listed via this interface. Each flight
   * service allows its own definition of how to consume criteria.
   */
  rpc ListFlights(Criteria) returns (stream FlightInfo) {}

  /*
   * For a given FlightDescriptor, get information about how the flight can be
   * consumed. This is a useful interface if the consumer of the interface
   * already can identify the specific flight to consume. This interface can
   * also allow a consumer to generate a flight stream through a specified
   * descriptor. For example, a flight descriptor might be something that
   * includes a SQL statement or a Pickled Python operation that will be
   * executed. In those cases, the descriptor will not be previously available
   * within the list of available streams provided by ListFlights but will be
   * available for consumption for the duration defined by the specific flight
   * service.
   */
  rpc GetFlightInfo(FlightDescriptor) returns (FlightInfo) {}

  /*
   * For a given FlightDescriptor, start a query and get information
   * to poll its execution status. This is a useful interface if the
   * query may be a long-running query. The first PollFlightInfo call
   * should return as quickly as possible. (GetFlightInfo doesn't
   * return until the query is complete.)
   *
   * A client can consume any available results before
   * the query is completed. See PollInfo.info for details.
   *
   * A client can poll the updated query status by calling
   * PollFlightInfo() with PollInfo.flight_descriptor. A server
   * should not respond until the result would be different from last
   * time. That way, the client can "long poll" for updates
   * without constantly making requests. Clients can set a short timeout
   * to avoid blocking calls if desired.
   *
   * A client can't use PollInfo.flight_descriptor after
   * PollInfo.expiration_time passes. A server might not accept the
   * retry descriptor anymore and the query may be cancelled.
   *
   * A client may use the CancelFlightInfo action with
   * PollInfo.info to cancel the running query.
   */
  rpc PollFlightInfo(FlightDescriptor) returns (PollInfo) {}

  /*
   * For a given FlightDescriptor, get the Schema as described in Schema.fbs::Schema
   * This is used when a consumer needs the Schema of flight stream. Similar to
   * GetFlightInfo this interface may generate a new flight that was not previously
   * available in ListFlights.
   */
   rpc GetSchema(FlightDescriptor) returns (SchemaResult) {}

  /*
   * Retrieve a single stream associated with a particular descriptor
   * associated with the referenced ticket. A Flight can be composed of one or
   * more streams where each stream can be retrieved using a separate opaque
   * ticket that the flight service uses for managing a collection of streams.
   */
  rpc DoGet(Ticket) returns (stream FlightData) {}

  /*
   * Push a stream to the flight service associated with a particular
   * flight stream. This allows a client of a flight service to upload a stream
   * of data. Depending on the particular flight service, a client consumer
   * could be allowed to upload a single stream per descriptor or an unlimited
   * number. In the latter, the service might implement a 'seal' action that
   * can be applied to a descriptor once all streams are uploaded.
   */
  rpc DoPut(stream FlightData) returns (stream PutResult) {}

  /*
   * Open a bidirectional data channel for a given descriptor. This
   * allows clients to send and receive arbitrary Arrow data and
   * application-specific metadata in a single logical stream. In
   * contrast to DoGet/DoPut, this is more suited for clients
   * offloading computation (rather than storage) to a Flight service.
   */
  rpc DoExchange(stream FlightData) returns (stream FlightData) {}

  /*
   * Flight services can support an arbitrary number of simple actions in
   * addition to the possible ListFlights, GetFlightInfo, DoGet, DoPut
   * operations that are potentially available. DoAction allows a flight client
   * to do a specific action against a flight service. An action includes
   * opaque request and response objects that are specific to the type action
   * being undertaken.
   */
  rpc DoAction(Action) returns (stream Result) {}

  /*
   * A flight service exposes all of the available action types that it has
   * along with descriptions. This allows different flight consumers to
   * understand the capabilities of the flight service.
   */
  rpc ListActions(Empty) returns (stream ActionType) {}
}

/*
 * The request that a client provides to a server on handshake.
 */
message HandshakeRequest {

  /*
   * A defined protocol version
   */
  uint64 protocol_version = 1;

  /*
   * Arbitrary auth/handshake info.
   */
  bytes payload = 2;
}

message HandshakeResponse {

  /*
   * A defined protocol version
   */
  uint64 protocol_version = 1;

  /*
   * Arbitrary auth/handshake info.
   */
  bytes payload = 2;
}

/*
 * A message for doing simple auth.
 */
message BasicAuth {
  string username = 2;
  string password = 3;
}

message Empty {}

/*
 * Describes an available action, including both the name used for execution
 * along with a short description of the purpose of the action.
 */
message ActionType {
  string type = 1;
  string description = 2;
}

/*
 * A service specific expression that can be used to return a limited set
 * of available Arrow Flight streams.
 */
message Criteria {
  bytes expression = 1;
}

/*
 * An opaque action specific for the service.
 */
message Action {
  string type = 1;
  bytes body = 2;
}

/*
 * An opaque result returned after executing an action.
 */
message Result {
  bytes body = 1;
}

/*
 * Wrap the result of a getSchema call
 */
message SchemaResult {
  // The schema of the dataset in its IPC form:
  //   4 bytes - an optional IPC_CONTINUATION_TOKEN prefix
  //   4 bytes - the byte length of the payload
  //   a flatbuffer Message whose header is the Schema
  bytes schema = 1;
}

/*
 * The name or tag for a Flight. May be used as a way to retrieve or generate
 * a flight or be used to expose a set of previously defined flights.
 */
message FlightDescriptor {

  /*
   * Describes what type of descriptor is defined.
   */
  enum DescriptorType {

    // Protobuf pattern, not used.
    UNKNOWN = 0;

    /*
     * A named path that identifies a dataset. A path is composed of a string
     * or list of strings describing a particular dataset. This is conceptually
     *  similar to a path inside a filesystem.
     */
    PATH = 1;

    /*
     * An opaque command to generate a dataset.
     */
    CMD = 2;
  }

  DescriptorType type = 1;

  /*
   * Opaque value used to express a command. Should only be defined when
   * type = CMD.
   */
  bytes cmd = 2;

  /*
   * List of strings identifying a particular dataset. Should only be defined
   * when type = PATH.
   */
  repeated string path = 3;
}

/*
 * The access coordinates for retrieval of a dataset. With a FlightInfo, a
 * consumer is able to determine how to retrieve a dataset.
 */
message FlightInfo {
  // The schema of the dataset in its IPC form:
  //   4 bytes - an optional IPC_CONTINUATION_TOKEN prefix
  //   4 bytes - the byte length of the payload
  //   a flatbuffer Message whose header is the Schema
  bytes schema = 1;

  /*
   * The descriptor associated with this info.
   */
  FlightDescriptor flight_descriptor = 2;

  /*
   * A list of endpoints associated with the flight. To consume the
   * whole flight, all endpoints (and hence all Tickets) must be
   * consumed. Endpoints can be consumed in any order.
   *
   * In other words, an application can use multiple endpoints to
   * represent partitioned data.
   *
   * If the returned data has an ordering, an application can use
   * "FlightInfo.ordered = true" or should return the all data in a
   * single endpoint. Otherwise, there is no ordering defined on
   * endpoints or the data within.
   *
   * A client can read ordered data by reading data from returned
   * endpoints, in order, from front to back.
   *
   * Note that a client may ignore "FlightInfo.ordered = true". If an
   * ordering is important for an application, an application must
   * choose one of them:
   *
   * * An application requires that all clients must read data in
   *   returned endpoints order.
   * * An application must return the all data in a single endpoint.
   */
  repeated FlightEndpoint endpoint = 3;

  // Set these to -1 if unknown.
  int64 total_records = 4;
  int64 total_bytes = 5;

  /*
   * FlightEndpoints are in the same order as the data.
   */
  bool ordered = 6;

  /*
   * Application-defined metadata.
   *
   * There is no inherent or required relationship between this
   * and the app_metadata fields in the FlightEndpoints or resulting
   * FlightData messages. Since this metadata is application-defined,
   * a given application could define there to be a relationship,
   * but there is none required by the spec.
   */
  bytes app_metadata = 7;
}

/*
 * The information to process a long-running query.
 */
message PollInfo {
  /*
   * The currently available results.
   *
   * If "flight_descriptor" is not specified, the query is complete
   * and "info" specifies all results. Otherwise, "info" contains
   * partial query results.
   *
   * Note that each PollInfo response contains a complete
   * FlightInfo (not just the delta between the previous and current
   * FlightInfo).
   *
   * Subsequent PollInfo responses may only append new endpoints to
   * info.
   *
   * Clients can begin fetching results via DoGet(Ticket) with the
   * ticket in the info before the query is
   * completed. FlightInfo.ordered is also valid.
   */
  FlightInfo info = 1;

  /*
   * The descriptor the client should use on the next try.
   * If unset, the query is complete.
   */
  FlightDescriptor flight_descriptor = 2;

  /*
   * Query progress. If known, must be in [0.0, 1.0] but need not be
   * monotonic or nondecreasing. If unknown, do not set.
   */
  optional double progress = 3;

  /*
   * Expiration time for this request. After this passes, the server
   * might not accept the retry descriptor anymore (and the query may
   * be cancelled). This may be updated on a call to PollFlightInfo.
   */
  google.protobuf.Timestamp expiration_time = 4;
}

/*
 * The request of the CancelFlightInfo action.
 *
 * The request should be stored in Action.body.
 */
message CancelFlightInfoRequest {
  FlightInfo info = 1;
}

/*
 * The result of a cancel operation.
 *
 * This is used by CancelFlightInfoResult.status.
 */
enum CancelStatus {
  // The cancellation status is unknown. Servers should avoid using
  // this value (send a NOT_FOUND error if the requested query is
  // not known). Clients can retry the request.
  CANCEL_STATUS_UNSPECIFIED = 0;
  // The cancellation request is complete. Subsequent requests with
  // the same payload may return CANCELLED or a NOT_FOUND error.
  CANCEL_STATUS_CANCELLED = 1;
  // The cancellation request is in progress. The client may retry
  // the cancellation request.
  CANCEL_STATUS_CANCELLING = 2;
  // The query is not cancellable. The client should not retry the
  // cancellation request.
  CANCEL_STATUS_NOT_CANCELLABLE = 3;
}

/*
 * The result of the CancelFlightInfo action.
 *
 * The result should be stored in Result.body.
 */
message CancelFlightInfoResult {
  CancelStatus status = 1;
}

/*
 * An opaque identifier that the service can use to retrieve a particular
 * portion of a stream.
 *
 * Tickets are meant to be single use. It is an error/application-defined
 * behavior to reuse a ticket.
 */
message Ticket {
  bytes ticket = 1;
}

/*
 * A location where a Flight service will accept retrieval of a particular
 * stream given a ticket.
 */
message Location {
  string uri = 1;
}

/*
 * A particular stream or split associated with a flight.
 */
message FlightEndpoint {

  /*
   * Token used to retrieve this stream.
   */
  Ticket ticket = 1;

  /*
   * A list of URIs where this ticket can be redeemed via DoGet().
   *
   * If the list is empty, the expectation is that the ticket can only
   * be redeemed on the current service where the ticket was
   * generated.
   *
   * If the list is not empty, the expectation is that the ticket can be
   * redeemed at any of the locations, and that the data returned will be
   * equivalent. In this case, the ticket may only be redeemed at one of the
   * given locations, and not (necessarily) on the current service. If one
   * of the given locations is "arrow-flight-reuse-connection://?", the
   * client may redeem the ticket on the service where the ticket was
   * generated (i.e., the same as above), in addition to the other
   * locations. (This URI was chosen to maximize compatibility, as 'scheme:'
   * or 'scheme://' are not accepted by Java's java.net.URI.)
   *
   * In other words, an application can use multiple locations to
   * represent redundant and/or load balanced services.
   */
  repeated Location location = 2;

  /*
   * Expiration time of this stream. If present, clients may assume
   * they can retry DoGet requests. Otherwise, it is
   * application-defined whether DoGet requests may be retried.
   */
  google.protobuf.Timestamp expiration_time = 3;

  /*
   * Application-defined metadata.
   *
   * There is no inherent or required relationship between this
   * and the app_metadata fields in the FlightInfo or resulting
   * FlightData messages. Since this metadata is application-defined,
   * a given application could define there to be a relationship,
   * but there is none required by the spec.
   */
  bytes app_metadata = 4;
}

/*
 * The request of the RenewFlightEndpoint action.
 *
 * The request should be stored in Action.body.
 */
message RenewFlightEndpointRequest {
  FlightEndpoint endpoint = 1;
}

/*
 * A batch of Arrow data as part of a stream of batches.
 */
message FlightData {

  /*
   * The descriptor of the data. This is only relevant when a client is
   * starting a new DoPut stream.
   */
  FlightDescriptor flight_descriptor = 1;

  /*
   * Header for message data as described in Message.fbs::Message.
   */
  bytes data_header = 2;

  /*
   * Application-defined metadata.
   */
  bytes app_metadata = 3;

  /*
   * The actual batch of Arrow data. Preferably handled with minimal-copies
   * coming last in the definition to help with sidecar patterns (it is
   * expected that some implementations will fetch this field off the wire
   * with specialized code to avoid extra memory copies).
   */
  bytes data_body = 1000;
}

/**
 * The response message associated with the submission of a DoPut.
 */
message PutResult {
  bytes app_metadata = 1;
}

/*
 * EXPERIMENTAL: Union of possible value types for a Session Option to be set to.
 *
 * By convention, an attempt to set a valueless SessionOptionValue should
 * attempt to unset or clear the named option value on the server.
 */
message SessionOptionValue {
  message StringListValue {
    repeated string values = 1;
  }

  oneof option_value {
    string string_value = 1;
    bool bool_value = 2;
    sfixed64 int64_value = 3;
    double double_value = 4;
    StringListValue string_list_value = 5;
  }
}

/*
 * EXPERIMENTAL: A request to set session options for an existing or new (implicit)
 * server session.
 *
 * Sessions are persisted and referenced via a transport-level state management, typically
 * RFC 6265 HTTP cookies when using an HTTP transport.  The suggested cookie name or state
 * context key is 'arrow_flight_session_id', although implementations may freely choose their
 * own name.
 *
 * Session creation (if one does not already exist) is implied by this RPC request, however
 * server implementations may choose to initiate a session that also contains client-provided
 * session options at any other time, e.g. on authentication, or when any other call is made
 * and the server wishes to use a session to persist any state (or lack thereof).
 */
message SetSessionOptionsRequest {
  map<string, SessionOptionValue> session_options = 1;
}

/*
 * EXPERIMENTAL: The results (individually) of setting a set of session options.
 *
 * Option names should only be present in the response if they were not successfully
 * set on the server; that is, a response without an Error for a name provided in the
 * SetSessionOptionsRequest implies that the named option value was set successfully.
 */
message SetSessionOptionsResult {
  enum ErrorValue {
    // Protobuf deserialization fallback value: The status is unknown or unrecognized.
    // Servers should avoid using this value. The request may be retried by the client.
    UNSPECIFIED = 0;
    // The given session option name is invalid.
    INVALID_NAME = 1;
    // The session option value or type is invalid.
    INVALID_VALUE = 2;
    // The session option cannot be set.
    ERROR = 3;
  }

  message Error {
    ErrorValue value = 1;
  }

  map<string, Error> errors = 1;
}

/*
 * EXPERIMENTAL: A request to access the session options for the current server session.
 *
 * The existing session is referenced via a cookie header or similar (see
 * SetSessionOptionsRequest above); it is an error to make this request with a missing,
 * invalid, or expired session cookie header or other implementation-defined session
 * reference token.
 */
message GetSessionOptionsRequest {
}

/*
 * EXPERIMENTAL: The result containing the current server session options.
 */
message GetSessionOptionsResult {
    map<string, SessionOptionValue> session_options = 1;
}

/*
 * Request message for the "Close Session" action.
 *
 * The exiting session is referenced via a cookie header.
 */
message CloseSessionRequest {
}

/*
 * The result of closing a session.
 */
message CloseSessionResult {
  enum Status {
    // Protobuf deserialization fallback value: The session close status is unknown or
    // not recognized. Servers should avoid using this value (send a NOT_FOUND error if
    // the requested session is not known or expired). Clients can retry the request.
    UNSPECIFIED = 0;
    // The session close request is complete. Subsequent requests with
    // the same session produce a NOT_FOUND error.
    CLOSED = 1;
    // The session close request is in progress. The client may retry
    // the close request.
    CLOSING = 2;
    // The session is not closeable. The client should not retry the
    // close request.
    NOT_CLOSEABLE = 3;
  }

  Status status = 1;
}