alamb commented on code in PR #40084: URL: https://github.com/apache/arrow/pull/40084#discussion_r1492839972
########## docs/source/format/Flight.rst: ########## @@ -307,29 +310,55 @@ well, in which case any `authentication method supported by gRPC .. _Mutual TLS (mTLS): https://grpc.io/docs/guides/auth/#supported-auth-mechanisms -Transport Implementations -========================= +Location URIs +============= Flight is primarily defined in terms of its Protobuf and gRPC specification below, but Arrow implementations may also support -alternative transports (see :ref:`status-flight-rpc`). In that case, -implementations should use the following URI schemes for the given -transport implementations: - -+----------------------------+----------------------------+ -| Transport | URI Scheme | -+============================+============================+ -| gRPC (plaintext) | grpc: or grpc+tcp: | -+----------------------------+----------------------------+ -| gRPC (TLS) | grpc+tls: | -+----------------------------+----------------------------+ -| gRPC (Unix domain socket) | grpc+unix: | -+----------------------------+----------------------------+ -| UCX_ (plaintext) | ucx: | -+----------------------------+----------------------------+ +alternative transports (see :ref:`status-flight-rpc`). Clients and +servers need to know which transport to use for a given URI in a +Location, so Flight implementations should use the following URI +schemes for the given transports: + ++----------------------------+--------------------------------+ +| Transport | URI Scheme | ++============================+================================+ +| Fallback | arrow-flight-reuse-connection: | ++----------------------------+--------------------------------+ +| gRPC (plaintext) | grpc: or grpc+tcp: | ++----------------------------+--------------------------------+ +| gRPC (TLS) | grpc+tls: | ++----------------------------+--------------------------------+ +| gRPC (Unix domain socket) | grpc+unix: | ++----------------------------+--------------------------------+ +| UCX_ (plaintext) | ucx: | ++----------------------------+--------------------------------+ .. _UCX: https://openucx.org/ +Fallback URIs +------------- + +"Fallback" above is not a particular transport. Instead, it means +that the client may try to execute DoGet against the same server (and +through the same connection) that it originally obtained the +FlightInfo from (i.e., that it called GetFlightInfo against). Review Comment: ```suggestion "Fallback" above is not a particular transport. Instead, it means that the client may try to execute DoGet against the same server (and through the same connection) that it originally obtained the FlightInfo from (i.e., that it called GetFlightInfo against). This is interpreted the same way as when no specific `Location`s are returned. ``` ########## docs/source/format/Flight.rst: ########## @@ -307,29 +310,55 @@ well, in which case any `authentication method supported by gRPC .. _Mutual TLS (mTLS): https://grpc.io/docs/guides/auth/#supported-auth-mechanisms -Transport Implementations -========================= +Location URIs +============= Flight is primarily defined in terms of its Protobuf and gRPC specification below, but Arrow implementations may also support -alternative transports (see :ref:`status-flight-rpc`). In that case, -implementations should use the following URI schemes for the given -transport implementations: - -+----------------------------+----------------------------+ -| Transport | URI Scheme | -+============================+============================+ -| gRPC (plaintext) | grpc: or grpc+tcp: | -+----------------------------+----------------------------+ -| gRPC (TLS) | grpc+tls: | -+----------------------------+----------------------------+ -| gRPC (Unix domain socket) | grpc+unix: | -+----------------------------+----------------------------+ -| UCX_ (plaintext) | ucx: | -+----------------------------+----------------------------+ +alternative transports (see :ref:`status-flight-rpc`). Clients and +servers need to know which transport to use for a given URI in a +Location, so Flight implementations should use the following URI +schemes for the given transports: + ++----------------------------+--------------------------------+ +| Transport | URI Scheme | ++============================+================================+ +| Fallback | arrow-flight-reuse-connection: | ++----------------------------+--------------------------------+ +| gRPC (plaintext) | grpc: or grpc+tcp: | ++----------------------------+--------------------------------+ +| gRPC (TLS) | grpc+tls: | ++----------------------------+--------------------------------+ +| gRPC (Unix domain socket) | grpc+unix: | ++----------------------------+--------------------------------+ +| UCX_ (plaintext) | ucx: | ++----------------------------+--------------------------------+ .. _UCX: https://openucx.org/ +Fallback URIs +------------- + +"Fallback" above is not a particular transport. Instead, it means +that the client may try to execute DoGet against the same server (and +through the same connection) that it originally obtained the +FlightInfo from (i.e., that it called GetFlightInfo against). + +For compatibility reasons, the URI should always be +``arrow-flight-reuse-connection://?``. (Java's URI implementation +does not accept ``scheme:`` or ``scheme://``, and C++'s implementation +does not accept an empty string; the chosen representation can be +parsed by both implementations, as well as Go's ``net/url`` and +Python's ``urllib.parse``.) + +This allows the server to return "itself" as one possible location to Review Comment: I recommend we put this context and use directly into the Flight protobuf as well so that the spec can be implemented directly from the .proto spec https://github.com/apache/arrow/blob/e83295b1aafbea985f0be61983b0b4fc9094854c/format/Flight.proto#L436-L452 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
