lidavidm commented on code in PR #50407: URL: https://github.com/apache/arrow/pull/50407#discussion_r4204394866
########## cpp/src/arrow/flight/transport/grpc/grpc_server_internal.cc: ########## @@ -0,0 +1,89 @@ +// 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 +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// 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. + +#include "arrow/flight/transport/grpc/grpc_server_internal.h" + +#include <sstream> + +#include <grpcpp/support/server_callback.h> + +namespace arrow::flight::transport::grpc { + +Status AddServerListeningPort(const FlightServerOptions& options, Review Comment: nit: it might make a little more sense for this to parse a URI and return the creds/location/address instead of just taking a builder, in case we want to unit test this later ########## cpp/src/arrow/flight/transport_server_internal.h: ########## @@ -0,0 +1,304 @@ +// 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 +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// 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. + +#pragma once + +#include <atomic> +#include <chrono> +#include <memory> +#include <thread> +#include <utility> +#include <vector> + +#include "arrow/flight/platform.h" +#include "arrow/flight/server.h" +#include "arrow/flight/visibility.h" +#include "arrow/result.h" +#include "arrow/status.h" +#include "arrow/util/io_util.h" +#include "arrow/util/logging.h" +#include "arrow/util/uri.h" + +namespace arrow::flight::internal { + +class ServerDataStream; +class PeekableFlightDataReader; + +/// \brief Adapt TransportDataStream to the FlightMessageReader +/// interface for DoPut. +class TransportMessageReader final : public FlightMessageReader { + public: + TransportMessageReader(ServerDataStream* stream, + std::shared_ptr<MemoryManager> memory_manager); + + Status Init(); + + const FlightDescriptor& descriptor() const override; + + arrow::Result<std::shared_ptr<Schema>> GetSchema() override; + + arrow::Result<FlightStreamChunk> Next() override; + + ipc::ReadStats stats() const override; + + private: + /// Ensure we are set up to read data. + Status EnsureDataStarted(); + + FlightDescriptor descriptor_; + std::shared_ptr<PeekableFlightDataReader> peekable_reader_; + std::shared_ptr<MemoryManager> memory_manager_; + std::shared_ptr<ipc::RecordBatchStreamReader> batch_reader_; + std::shared_ptr<Buffer> app_metadata_; +}; + +/// \brief A writer for IPC payloads to a ServerDataStream. +class TransportMessageWriter final : public FlightMessageWriter { + public: + explicit TransportMessageWriter(ServerDataStream* stream); + + Status Begin(const std::shared_ptr<Schema>& schema, + const ipc::IpcWriteOptions& options) override; + + Status WriteRecordBatch(const RecordBatch& batch) override; + + Status WriteMetadata(std::shared_ptr<Buffer> app_metadata) override; + + Status WriteWithMetadata(const RecordBatch& batch, + std::shared_ptr<Buffer> app_metadata) override; + + Status Close() override; + + ipc::WriteStats stats() const override; + + private: + Status CheckStarted(); + + ServerDataStream* stream_; + std::unique_ptr<ipc::RecordBatchWriter> batch_writer_; + std::shared_ptr<Buffer> app_metadata_; + ::arrow::ipc::IpcWriteOptions ipc_options_; +}; + +/// \brief A writer for application-defined metadata to a ServerDataStream. +class TransportMetadataWriter final : public FlightMetadataWriter { + public: + explicit TransportMetadataWriter(ServerDataStream* stream); + + Status WriteMetadata(const Buffer& buffer) override; + + private: + ServerDataStream* stream_; +}; + +/// \brief Base class for server transport implementations. +/// +/// Provides shared helpers for constructing message readers/writers from a +/// transport-level data stream, and for writing a FlightDataStream to a +/// transport-level stream (used by DoGet/DoExchange). +class ARROW_FLIGHT_EXPORT ServerTransportBase { Review Comment: Does this really need to be a base class? It seems WriteDataStream could just be a helper function ########## cpp/src/arrow/flight/transport_server_internal.h: ########## @@ -0,0 +1,304 @@ +// 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 +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// 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. + +#pragma once + +#include <atomic> +#include <chrono> +#include <memory> +#include <thread> +#include <utility> +#include <vector> + +#include "arrow/flight/platform.h" +#include "arrow/flight/server.h" +#include "arrow/flight/visibility.h" +#include "arrow/result.h" +#include "arrow/status.h" +#include "arrow/util/io_util.h" +#include "arrow/util/logging.h" +#include "arrow/util/uri.h" + +namespace arrow::flight::internal { + +class ServerDataStream; +class PeekableFlightDataReader; + +/// \brief Adapt TransportDataStream to the FlightMessageReader +/// interface for DoPut. +class TransportMessageReader final : public FlightMessageReader { + public: + TransportMessageReader(ServerDataStream* stream, + std::shared_ptr<MemoryManager> memory_manager); + + Status Init(); + + const FlightDescriptor& descriptor() const override; + + arrow::Result<std::shared_ptr<Schema>> GetSchema() override; + + arrow::Result<FlightStreamChunk> Next() override; + + ipc::ReadStats stats() const override; + + private: + /// Ensure we are set up to read data. + Status EnsureDataStarted(); + + FlightDescriptor descriptor_; + std::shared_ptr<PeekableFlightDataReader> peekable_reader_; + std::shared_ptr<MemoryManager> memory_manager_; + std::shared_ptr<ipc::RecordBatchStreamReader> batch_reader_; + std::shared_ptr<Buffer> app_metadata_; +}; + +/// \brief A writer for IPC payloads to a ServerDataStream. +class TransportMessageWriter final : public FlightMessageWriter { + public: + explicit TransportMessageWriter(ServerDataStream* stream); + + Status Begin(const std::shared_ptr<Schema>& schema, + const ipc::IpcWriteOptions& options) override; + + Status WriteRecordBatch(const RecordBatch& batch) override; + + Status WriteMetadata(std::shared_ptr<Buffer> app_metadata) override; + + Status WriteWithMetadata(const RecordBatch& batch, + std::shared_ptr<Buffer> app_metadata) override; + + Status Close() override; + + ipc::WriteStats stats() const override; + + private: + Status CheckStarted(); + + ServerDataStream* stream_; + std::unique_ptr<ipc::RecordBatchWriter> batch_writer_; + std::shared_ptr<Buffer> app_metadata_; + ::arrow::ipc::IpcWriteOptions ipc_options_; +}; + +/// \brief A writer for application-defined metadata to a ServerDataStream. +class TransportMetadataWriter final : public FlightMetadataWriter { + public: + explicit TransportMetadataWriter(ServerDataStream* stream); + + Status WriteMetadata(const Buffer& buffer) override; + + private: + ServerDataStream* stream_; +}; + +/// \brief Base class for server transport implementations. +/// +/// Provides shared helpers for constructing message readers/writers from a +/// transport-level data stream, and for writing a FlightDataStream to a +/// transport-level stream (used by DoGet/DoExchange). +class ARROW_FLIGHT_EXPORT ServerTransportBase { + public: + explicit ServerTransportBase(std::shared_ptr<MemoryManager> memory_manager) + : memory_manager_(std::move(memory_manager)) {} + virtual ~ServerTransportBase() = default; + + protected: + /// \brief Write a FlightDataStream to a transport-level stream. + /// + /// Used by DoGet and DoExchange to stream results back to the client. + /// The schema is written first, followed by record batches until the + /// stream is exhausted. + /// + /// \param[in] data_stream The Arrow data stream to read from. + /// \param[in] stream The transport-specific data stream to write to. + Status WriteDataStream(std::unique_ptr<FlightDataStream> data_stream, + ServerDataStream* stream) const; + + std::shared_ptr<MemoryManager> memory_manager_; +}; + +/// \brief Manages a background thread that waits for OS signals. +/// +/// Creates a signal-safe SelfPipe and spawns a thread that blocks on it. +/// When a signal is received, the signal handler writes to the SelfPipe +/// to wake the thread. The destructor ensures the thread is joined. +class ServerSignalHandler { + public: + ARROW_DISALLOW_COPY_AND_ASSIGN(ServerSignalHandler); + ServerSignalHandler() = default; + + /// \brief Initialize the signal handler and start the background thread. + /// + /// \param[in] handler A callable that will be invoked on the background + /// thread, receiving the SelfPipe as an argument. + /// \return The SelfPipe, which can be used to signal the handler thread. + template <typename Fn> + arrow::Result<std::shared_ptr<::arrow::internal::SelfPipe>> Init(Fn handler) { + ARROW_ASSIGN_OR_RAISE(self_pipe_, + ::arrow::internal::SelfPipe::Make(/*signal_safe=*/true)); + handle_signals_ = std::thread(handler, self_pipe_); + return self_pipe_; + } + + /// \brief Shut down the signal handler and join the background thread. + Status Shutdown() { + RETURN_NOT_OK(self_pipe_->Shutdown()); + handle_signals_.join(); + return Status::OK(); + } + + ~ServerSignalHandler() { ARROW_CHECK_OK(Shutdown()); } + + private: + std::shared_ptr<::arrow::internal::SelfPipe> self_pipe_; + std::thread handle_signals_; +}; + +/// \brief Manages signal-driven graceful shutdown for server transports. +/// +/// Installs signal handlers for the given set of signals. When a signal is +/// received, the registered shutdown callback is invoked. Uses a SelfPipe +/// to safely bridge the signal handler (which runs in a restricted context) +/// to a background thread that performs the actual shutdown. +class ARROW_FLIGHT_EXPORT ServerSignalState { + public: + ServerSignalState() = default; + + /// \brief Configure which signals should trigger shutdown. + /// + /// \param[in] sigs List of signal numbers (e.g. SIGINT, SIGTERM). + Status SetShutdownOnSignals(const std::vector<int>& sigs); + /// \brief Return the last signal that was received, or 0 if none. + int GotSignal() const; + + /// \brief Run the server with signal-aware lifecycle management. + /// + /// Installs signal handlers, calls \p wait (which should block until the + /// server stops), and restores original signal handlers on return. + /// If a signal is received during \p wait, \p shutdown is called first. + /// + /// \param[in] wait A callable that blocks until the server stops. + /// \param[in] shutdown A callable invoked on signal receipt to stop the server. + /// \param[in] not_started_message Logged if shutdown is called before the server + /// starts. \param[in] shutdown_warning Logged if shutdown itself fails. + template <typename WaitFn, typename ShutdownFn> + Status Serve(WaitFn&& wait, ShutdownFn&& shutdown, const char* not_started_message, + const char* shutdown_warning) { + got_signal_ = 0; + old_signal_handlers_.clear(); + running_instance_ = this; + + ServerSignalHandler signal_handler; + ARROW_ASSIGN_OR_RAISE(self_pipe_, + signal_handler.Init(&ServerSignalState::WaitForSignals)); + for (size_t i = 0; i < signals_.size(); ++i) { + int signum = signals_[i]; + ::arrow::internal::SignalHandler new_handler(&ServerSignalState::HandleSignal), + old_handler; + ARROW_ASSIGN_OR_RAISE(old_handler, + ::arrow::internal::SetSignalHandler(signum, new_handler)); + old_signal_handlers_.push_back(std::move(old_handler)); + } + + shutdown_ = [shutdown = std::forward<ShutdownFn>(shutdown)]() mutable { + return shutdown(nullptr); + }; + shutdown_warning_ = shutdown_warning; + auto status = wait(); + if (!status.ok()) { + running_instance_ = nullptr; + shutdown_ = nullptr; + shutdown_warning_ = nullptr; + return status; + } + running_instance_ = nullptr; + shutdown_ = nullptr; + shutdown_warning_ = nullptr; + + for (size_t i = 0; i < signals_.size(); ++i) { + RETURN_NOT_OK( + ::arrow::internal::SetSignalHandler(signals_[i], old_signal_handlers_[i]) + .status()); + } + return Status::OK(); + } + + /// \brief Shut down the server through the given callback. + /// + /// Clears the running instance pointer, then invokes \p shutdown. + /// + /// \param[in] shutdown A callable that performs the transport-specific shutdown. + /// \param[in] deadline Optional deadline for the shutdown. + template <typename ShutdownFn> + Status Shutdown(ShutdownFn&& shutdown, + const std::chrono::system_clock::time_point* deadline) { + running_instance_ = nullptr; + return shutdown(deadline); + } + + /// \brief Wait for the server to stop without initiating shutdown. + /// + /// \param[in] wait A callable that blocks until the server stops. + template <typename WaitFn> + Status Wait(WaitFn&& wait) { + RETURN_NOT_OK(wait()); + running_instance_ = nullptr; + return Status::OK(); + } + + private: + /// \brief Static entry point for the OS signal handler. + static void HandleSignal(int signum); + + /// \brief Record the received signal and wake the background thread. + void DoHandleSignal(int signum); + + /// \brief Background thread that blocks on the SelfPipe, then invokes shutdown. + static void WaitForSignals(std::shared_ptr<::arrow::internal::SelfPipe> self_pipe); + + // Signal handlers (on Windows) and the shutdown handler (other platforms) + // are executed in a separate thread, so getting the current thread instance + // wouldn't make sense. This means only a single instance can receive signals. + static std::atomic<ServerSignalState*> running_instance_; + + // We'll use the self-pipe trick to notify a thread from the signal + // handler. The thread will then shut down the server. + std::shared_ptr<::arrow::internal::SelfPipe> self_pipe_; + + // Signal handling + std::vector<int> signals_; + std::vector<::arrow::internal::SignalHandler> old_signal_handlers_; + std::atomic<int> got_signal_{0}; + std::function<Status()> shutdown_; + const char* shutdown_warning_ = nullptr; +}; + +/// \brief Parse a Flight Location into a URI. +/// +/// \param[in] location The Flight location to parse. +ARROW_FLIGHT_EXPORT +arrow::Result<arrow::util::Uri> ParseLocationUri(const Location& location); + +/// \brief Extract the port number from a Flight Location. +/// +/// Returns -1 if the location cannot be parsed or has no port. +/// +/// \param[in] location The Flight location. +ARROW_FLIGHT_EXPORT +int PortFromLocation(const Location& location); Review Comment: Could this just be a method on Location? ########## cpp/src/arrow/flight/transport/grpc/grpc_server_internal.h: ########## @@ -0,0 +1,205 @@ +// 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 +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// 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. + +#pragma once + +#include <memory> +#include <string> +#include <unordered_map> +#include <utility> +#include <vector> + +#include <grpcpp/grpcpp.h> + +#include "arrow/flight/server.h" +#include "arrow/flight/server_middleware.h" +#include "arrow/flight/transport/grpc/util_internal.h" +#include "arrow/util/uri.h" + +namespace arrow::flight::transport::grpc { + +using MiddlewareFactoryList = + std::vector<std::pair<std::string, std::shared_ptr<ServerMiddlewareFactory>>>; + +template <typename GrpcContext> +class GrpcAddServerHeaders : public AddCallHeaders { + public: + explicit GrpcAddServerHeaders(GrpcContext* context) : context_(context) {} + ~GrpcAddServerHeaders() override = default; + + void AddHeader(const std::string& key, const std::string& value) override { + context_->AddInitialMetadata(key, value); + } + + private: + GrpcContext* context_; +}; + +template <typename GrpcContext> +class GrpcServerCallContext : public ServerCallContext { + public: + explicit GrpcServerCallContext(GrpcContext* context) + : context_(context), peer_(context->peer()) { + for (const auto& entry : context->client_metadata()) { + incoming_headers_.insert( + {std::string_view(entry.first.data(), entry.first.length()), + std::string_view(entry.second.data(), entry.second.length())}); + } + } + + const std::string& peer_identity() const override { return peer_identity_; } + const std::string& peer() const override { return peer_; } + bool is_cancelled() const override { return context_->IsCancelled(); } + const CallHeaders& incoming_headers() const override { return incoming_headers_; } + + // Helper method that runs interceptors given the result of an RPC, + // then returns the final gRPC status to send to the client + ::grpc::Status FinishRequest(const ::grpc::Status& status) { + // Don't double-convert status - return the original one here + FinishRequest(FromGrpcStatus(status)); + return status; + } + + ::grpc::Status FinishRequest(const Status& status) { + for (const auto& instance : middleware_) { + instance->CallCompleted(status); + } + return ToGrpcStatus(status, context_); + } + + void AddHeader(const std::string& key, const std::string& value) const override { + context_->AddInitialMetadata(key, value); + } + + void AddTrailer(const std::string& key, const std::string& value) const override { + context_->AddTrailingMetadata(key, value); + } + + ServerMiddleware* GetMiddleware(const std::string& key) const override { + const auto& instance = middleware_map_.find(key); + if (instance == middleware_map_.end()) { + return nullptr; + } + return instance->second.get(); + } + + private: + template <typename> + friend class GrpcServerCallContextHelper; + + GrpcContext* context_; + std::string peer_; + std::string peer_identity_; + std::vector<std::shared_ptr<ServerMiddleware>> middleware_; + std::unordered_map<std::string, std::shared_ptr<ServerMiddleware>> middleware_map_; + CallHeaders incoming_headers_; +}; + +template <typename GrpcContext> +class GrpcServerCallContextHelper { + public: + GrpcServerCallContextHelper(std::shared_ptr<ServerAuthHandler> auth_handler, + MiddlewareFactoryList middleware) + : auth_handler_(std::move(auth_handler)), middleware_(std::move(middleware)) {} + + // Authenticate the client (if applicable) and construct the call context + ::grpc::Status MakeCallContext(FlightMethod method, GrpcContext* context, + GrpcServerCallContext<GrpcContext>* flight_context, + bool skip_headers = false) const { + // Run server middleware + const CallInfo info{method}; + for (const auto& factory : middleware_) { + std::shared_ptr<ServerMiddleware> instance; + Status result = factory.second->StartCall(info, *flight_context, &instance); + if (!result.ok()) { + // Interceptor rejected call, end the request on all existing + // interceptors + return flight_context->FinishRequest(result); + } + if (instance != nullptr) { + flight_context->middleware_.push_back(instance); + flight_context->middleware_map_.insert({factory.first, instance}); + } + } + // TODO factor this out after fixing all streaming and non-streaming handlers + if (!skip_headers) { + AddMiddlewareHeaders(context, flight_context); + } + + return ::grpc::Status::OK; + } + + void AddMiddlewareHeaders(GrpcContext* context, + GrpcServerCallContext<GrpcContext>* flight_context) const { + GrpcAddServerHeaders<GrpcContext> outgoing_headers(context); + for (const auto& instance : flight_context->middleware_) { + instance->SendingHeaders(&outgoing_headers); + } + } + + // Authenticate the client (if applicable) and construct the call context + ::grpc::Status CheckAuth(FlightMethod method, GrpcContext* context, + GrpcServerCallContext<GrpcContext>* flight_context) const { + if (!auth_handler_) { + const auto auth_context = context->auth_context(); + if (auth_context && auth_context->IsPeerAuthenticated()) { + auto peer_identity = auth_context->GetPeerIdentity(); + flight_context->peer_identity_ = + peer_identity.empty() + ? "" + : std::string(peer_identity.front().begin(), peer_identity.front().end()); + } else { + flight_context->peer_identity_ = ""; + } + } else { + const auto client_metadata = context->client_metadata(); + const auto [auth_header, auth_header_end] = + client_metadata.equal_range(kGrpcAuthHeader); + std::string token; + if (auth_header != auth_header_end) { + token = std::string(auth_header->second.data(), auth_header->second.length()); + } + auto auth_status = + auth_handler_->IsValid(*flight_context, token, &flight_context->peer_identity_); + if (!auth_status.ok()) { + return flight_context->FinishRequest(auth_status); + } + } + return MakeCallContext(method, context, flight_context); + } + + const std::shared_ptr<ServerAuthHandler>& auth_handler() const { return auth_handler_; } + + private: + std::shared_ptr<ServerAuthHandler> auth_handler_; + MiddlewareFactoryList middleware_; +}; + +ARROW_FLIGHT_EXPORT +Status AddServerListeningPort(const FlightServerOptions& options, + const arrow::util::Uri& uri, ::grpc::ServerBuilder* builder, + Location* location, int* port); + +ARROW_FLIGHT_EXPORT +void ConfigureServerBuilderOptions(const FlightServerOptions& options, + ::grpc::ServerBuilder* builder); + +ARROW_FLIGHT_EXPORT +Status SetServerLocationFromUri(const arrow::util::Uri& uri, int port, + Location* location); Review Comment: nit: this should return Result; it's also not really clear to me why it's factored out ########## cpp/src/arrow/flight/transport_server_internal.h: ########## @@ -0,0 +1,304 @@ +// 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 +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// 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. + +#pragma once + +#include <atomic> +#include <chrono> +#include <memory> +#include <thread> +#include <utility> +#include <vector> + +#include "arrow/flight/platform.h" +#include "arrow/flight/server.h" +#include "arrow/flight/visibility.h" +#include "arrow/result.h" +#include "arrow/status.h" +#include "arrow/util/io_util.h" +#include "arrow/util/logging.h" +#include "arrow/util/uri.h" + +namespace arrow::flight::internal { + +class ServerDataStream; +class PeekableFlightDataReader; + +/// \brief Adapt TransportDataStream to the FlightMessageReader +/// interface for DoPut. +class TransportMessageReader final : public FlightMessageReader { + public: + TransportMessageReader(ServerDataStream* stream, + std::shared_ptr<MemoryManager> memory_manager); + + Status Init(); + + const FlightDescriptor& descriptor() const override; + + arrow::Result<std::shared_ptr<Schema>> GetSchema() override; + + arrow::Result<FlightStreamChunk> Next() override; + + ipc::ReadStats stats() const override; + + private: + /// Ensure we are set up to read data. + Status EnsureDataStarted(); + + FlightDescriptor descriptor_; + std::shared_ptr<PeekableFlightDataReader> peekable_reader_; + std::shared_ptr<MemoryManager> memory_manager_; + std::shared_ptr<ipc::RecordBatchStreamReader> batch_reader_; + std::shared_ptr<Buffer> app_metadata_; +}; + +/// \brief A writer for IPC payloads to a ServerDataStream. +class TransportMessageWriter final : public FlightMessageWriter { + public: + explicit TransportMessageWriter(ServerDataStream* stream); + + Status Begin(const std::shared_ptr<Schema>& schema, + const ipc::IpcWriteOptions& options) override; + + Status WriteRecordBatch(const RecordBatch& batch) override; + + Status WriteMetadata(std::shared_ptr<Buffer> app_metadata) override; + + Status WriteWithMetadata(const RecordBatch& batch, + std::shared_ptr<Buffer> app_metadata) override; + + Status Close() override; + + ipc::WriteStats stats() const override; + + private: + Status CheckStarted(); + + ServerDataStream* stream_; + std::unique_ptr<ipc::RecordBatchWriter> batch_writer_; + std::shared_ptr<Buffer> app_metadata_; + ::arrow::ipc::IpcWriteOptions ipc_options_; +}; + +/// \brief A writer for application-defined metadata to a ServerDataStream. +class TransportMetadataWriter final : public FlightMetadataWriter { + public: + explicit TransportMetadataWriter(ServerDataStream* stream); + + Status WriteMetadata(const Buffer& buffer) override; + + private: + ServerDataStream* stream_; +}; + +/// \brief Base class for server transport implementations. +/// +/// Provides shared helpers for constructing message readers/writers from a +/// transport-level data stream, and for writing a FlightDataStream to a +/// transport-level stream (used by DoGet/DoExchange). +class ARROW_FLIGHT_EXPORT ServerTransportBase { + public: + explicit ServerTransportBase(std::shared_ptr<MemoryManager> memory_manager) + : memory_manager_(std::move(memory_manager)) {} + virtual ~ServerTransportBase() = default; + + protected: + /// \brief Write a FlightDataStream to a transport-level stream. + /// + /// Used by DoGet and DoExchange to stream results back to the client. + /// The schema is written first, followed by record batches until the + /// stream is exhausted. + /// + /// \param[in] data_stream The Arrow data stream to read from. + /// \param[in] stream The transport-specific data stream to write to. + Status WriteDataStream(std::unique_ptr<FlightDataStream> data_stream, + ServerDataStream* stream) const; + + std::shared_ptr<MemoryManager> memory_manager_; +}; + +/// \brief Manages a background thread that waits for OS signals. +/// +/// Creates a signal-safe SelfPipe and spawns a thread that blocks on it. +/// When a signal is received, the signal handler writes to the SelfPipe +/// to wake the thread. The destructor ensures the thread is joined. +class ServerSignalHandler { + public: + ARROW_DISALLOW_COPY_AND_ASSIGN(ServerSignalHandler); + ServerSignalHandler() = default; + + /// \brief Initialize the signal handler and start the background thread. + /// + /// \param[in] handler A callable that will be invoked on the background + /// thread, receiving the SelfPipe as an argument. + /// \return The SelfPipe, which can be used to signal the handler thread. + template <typename Fn> + arrow::Result<std::shared_ptr<::arrow::internal::SelfPipe>> Init(Fn handler) { + ARROW_ASSIGN_OR_RAISE(self_pipe_, + ::arrow::internal::SelfPipe::Make(/*signal_safe=*/true)); + handle_signals_ = std::thread(handler, self_pipe_); + return self_pipe_; + } + + /// \brief Shut down the signal handler and join the background thread. + Status Shutdown() { + RETURN_NOT_OK(self_pipe_->Shutdown()); + handle_signals_.join(); + return Status::OK(); + } + + ~ServerSignalHandler() { ARROW_CHECK_OK(Shutdown()); } + + private: + std::shared_ptr<::arrow::internal::SelfPipe> self_pipe_; + std::thread handle_signals_; +}; + +/// \brief Manages signal-driven graceful shutdown for server transports. +/// +/// Installs signal handlers for the given set of signals. When a signal is +/// received, the registered shutdown callback is invoked. Uses a SelfPipe +/// to safely bridge the signal handler (which runs in a restricted context) +/// to a background thread that performs the actual shutdown. +class ARROW_FLIGHT_EXPORT ServerSignalState { + public: + ServerSignalState() = default; + + /// \brief Configure which signals should trigger shutdown. + /// + /// \param[in] sigs List of signal numbers (e.g. SIGINT, SIGTERM). + Status SetShutdownOnSignals(const std::vector<int>& sigs); + /// \brief Return the last signal that was received, or 0 if none. + int GotSignal() const; + + /// \brief Run the server with signal-aware lifecycle management. + /// + /// Installs signal handlers, calls \p wait (which should block until the + /// server stops), and restores original signal handlers on return. + /// If a signal is received during \p wait, \p shutdown is called first. + /// + /// \param[in] wait A callable that blocks until the server stops. + /// \param[in] shutdown A callable invoked on signal receipt to stop the server. + /// \param[in] not_started_message Logged if shutdown is called before the server + /// starts. \param[in] shutdown_warning Logged if shutdown itself fails. + template <typename WaitFn, typename ShutdownFn> + Status Serve(WaitFn&& wait, ShutdownFn&& shutdown, const char* not_started_message, + const char* shutdown_warning) { + got_signal_ = 0; + old_signal_handlers_.clear(); + running_instance_ = this; + + ServerSignalHandler signal_handler; + ARROW_ASSIGN_OR_RAISE(self_pipe_, + signal_handler.Init(&ServerSignalState::WaitForSignals)); + for (size_t i = 0; i < signals_.size(); ++i) { + int signum = signals_[i]; + ::arrow::internal::SignalHandler new_handler(&ServerSignalState::HandleSignal), + old_handler; + ARROW_ASSIGN_OR_RAISE(old_handler, + ::arrow::internal::SetSignalHandler(signum, new_handler)); + old_signal_handlers_.push_back(std::move(old_handler)); + } + + shutdown_ = [shutdown = std::forward<ShutdownFn>(shutdown)]() mutable { + return shutdown(nullptr); + }; + shutdown_warning_ = shutdown_warning; + auto status = wait(); + if (!status.ok()) { + running_instance_ = nullptr; + shutdown_ = nullptr; + shutdown_warning_ = nullptr; + return status; + } + running_instance_ = nullptr; + shutdown_ = nullptr; + shutdown_warning_ = nullptr; + + for (size_t i = 0; i < signals_.size(); ++i) { + RETURN_NOT_OK( + ::arrow::internal::SetSignalHandler(signals_[i], old_signal_handlers_[i]) + .status()); + } + return Status::OK(); + } + + /// \brief Shut down the server through the given callback. + /// + /// Clears the running instance pointer, then invokes \p shutdown. + /// + /// \param[in] shutdown A callable that performs the transport-specific shutdown. + /// \param[in] deadline Optional deadline for the shutdown. + template <typename ShutdownFn> + Status Shutdown(ShutdownFn&& shutdown, + const std::chrono::system_clock::time_point* deadline) { + running_instance_ = nullptr; + return shutdown(deadline); + } + + /// \brief Wait for the server to stop without initiating shutdown. + /// + /// \param[in] wait A callable that blocks until the server stops. + template <typename WaitFn> + Status Wait(WaitFn&& wait) { + RETURN_NOT_OK(wait()); + running_instance_ = nullptr; + return Status::OK(); + } + + private: + /// \brief Static entry point for the OS signal handler. + static void HandleSignal(int signum); + + /// \brief Record the received signal and wake the background thread. + void DoHandleSignal(int signum); + + /// \brief Background thread that blocks on the SelfPipe, then invokes shutdown. + static void WaitForSignals(std::shared_ptr<::arrow::internal::SelfPipe> self_pipe); + + // Signal handlers (on Windows) and the shutdown handler (other platforms) + // are executed in a separate thread, so getting the current thread instance + // wouldn't make sense. This means only a single instance can receive signals. + static std::atomic<ServerSignalState*> running_instance_; + + // We'll use the self-pipe trick to notify a thread from the signal + // handler. The thread will then shut down the server. + std::shared_ptr<::arrow::internal::SelfPipe> self_pipe_; + + // Signal handling + std::vector<int> signals_; + std::vector<::arrow::internal::SignalHandler> old_signal_handlers_; + std::atomic<int> got_signal_{0}; + std::function<Status()> shutdown_; + const char* shutdown_warning_ = nullptr; +}; + +/// \brief Parse a Flight Location into a URI. +/// +/// \param[in] location The Flight location to parse. +ARROW_FLIGHT_EXPORT +arrow::Result<arrow::util::Uri> ParseLocationUri(const Location& location); Review Comment: Possibly a method on Location? That would also help resolve the name, which I found a bit confusing -- 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]
