1 //
2 // Copyright 2022 gRPC authors.
3 //
4 // Licensed under the Apache License, Version 2.0 (the "License");
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
7 //
8 //     http://www.apache.org/licenses/LICENSE-2.0
9 //
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
15 //
16 
17 #ifndef GRPC_SRC_CORE_EXT_XDS_XDS_TRANSPORT_H
18 #define GRPC_SRC_CORE_EXT_XDS_XDS_TRANSPORT_H
19 
20 #include <grpc/support/port_platform.h>
21 
22 #include <functional>
23 #include <memory>
24 #include <string>
25 
26 #include "absl/status/status.h"
27 #include "absl/strings/string_view.h"
28 
29 #include "src/core/ext/xds/xds_bootstrap.h"
30 #include "src/core/lib/gprpp/orphanable.h"
31 
32 namespace grpc_core {
33 
34 // A factory for creating new XdsTransport instances.
35 class XdsTransportFactory : public InternallyRefCounted<XdsTransportFactory> {
36  public:
37   // Represents a transport for xDS communication (e.g., a gRPC channel).
38   class XdsTransport : public InternallyRefCounted<XdsTransport> {
39    public:
40     // Represents a bidi streaming RPC call.
41     class StreamingCall : public InternallyRefCounted<StreamingCall> {
42      public:
43       // An interface for handling events on a streaming call.
44       class EventHandler {
45        public:
46         virtual ~EventHandler() = default;
47 
48         // Called when a SendMessage() operation completes.
49         virtual void OnRequestSent(bool ok) = 0;
50         // Called when a message is received on the stream.
51         virtual void OnRecvMessage(absl::string_view payload) = 0;
52         // Called when status is received on the stream.
53         virtual void OnStatusReceived(absl::Status status) = 0;
54       };
55 
56       // Sends a message on the stream.  When the message has been sent,
57       // the EventHandler::OnRequestSent() method will be called.
58       // Only one message will be in flight at a time; subsequent
59       // messages will not be sent until this one is done.
60       virtual void SendMessage(std::string payload) = 0;
61     };
62 
63     // Create a streaming call on this transport for the specified method.
64     // Events on the stream will be reported to event_handler.
65     virtual OrphanablePtr<StreamingCall> CreateStreamingCall(
66         const char* method,
67         std::unique_ptr<StreamingCall::EventHandler> event_handler) = 0;
68 
69     // Resets connection backoff for the transport.
70     virtual void ResetBackoff() = 0;
71   };
72 
73   // Creates a new transport for the specified server.
74   // The on_connectivity_failure callback will be invoked whenever there is
75   // a connectivity failure on the transport.
76   // *status will be set if there is an error creating the channel,
77   // although the returned channel must still accept calls (which may fail).
78   virtual OrphanablePtr<XdsTransport> Create(
79       const XdsBootstrap::XdsServer& server,
80       std::function<void(absl::Status)> on_connectivity_failure,
81       absl::Status* status) = 0;
82 };
83 
84 }  // namespace grpc_core
85 
86 #endif  // GRPC_SRC_CORE_EXT_XDS_XDS_TRANSPORT_H
87