Blimp: define HeliumTransport/HeliumStream interfaces.

blimp/net/helium/helium_stream.h

Index: blimp/net/helium/helium_stream.h
diff --git a/blimp/net/helium/helium_stream.h b/blimp/net/helium/helium_stream.h
new file mode 100644
index 0000000000000000000000000000000000000000..99bbb3478afda9899555cb80a56302510b12cb18
--- /dev/null
+++ b/blimp/net/helium/helium_stream.h
@@ -0,0 +1,76 @@
+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef BLIMP_NET_HELIUM_HELIUM_STREAM_H_
+#define BLIMP_NET_HELIUM_HELIUM_STREAM_H_
+
+#include <memory>
+
+#include "base/observer_list.h"
+#include "blimp/net/helium/helium_result.h"
+#include "net/base/completion_callback.h"
+
+namespace blimp {
+
+class HeliumMessage;
+
+// Abstract base class for HeliumMessage-oriented transport streams.
+// Details about how the HeliumStream is bound to the network layer are handled
+// by subclasses of HeliumStream.
+class HeliumStream {
+ public:
+  class Observer {
+   public:
+    // Informs observers that the HeliumStream is disconnected.
+    // Any outstanding read or write callbacks will be dropped and never
+    // invoked.
+    //
+    // An observer which owns |this| may delete the HeliumStream in response to
+    // receiving an OnStreamDisconnected() notification. The deletion method
+    // must be asynchronously posted to occur *after* the OnStreamDisconnected()
+    // handler, not during.
+    virtual void OnStreamDisconnected(HeliumStream* stream) = 0;
+  };
+
+  HeliumStream();
+  virtual ~HeliumStream();
+
+  // Sends |helium_message| over the Stream. |callback| is invoked when the
+  // message is sent (or otherwise moved to the low-level write buffers),
+  // which signals the caller that it is clear to send another message.
+  //
+  // The caller is responsible for ensuring that only one outstanding
+  // SendMessage() call is made at a time.
+  virtual void SendMessage(
+      std::unique_ptr<HeliumMessage> helium_message,
+      const base::Callback<void(HeliumResult)>& callback) = 0;
+
+  // Asynchronously reads a HeliumMessage from the stream.
+  // The caller is responsible for ensuring that only one outstanding
+  // ReceiveMessage() call is made at a time.
+  // The implementation classes should refrain from preemptively buffering
+  // incoming messages to ensure proper pushback w/transport-level flow control.
+  virtual void ReceiveMessage(

[perumaal, 2016/10/05 20:40:44]

I think this would be better suited as SetMessageReadCallback(...) *once* and
not to 'pull' messages repeatedly.
If you really want to 'pull' message (i.e. force the engine to send you
message), then I would recommend SendMessage'ing of some sort and waiting for
the callback.

Also, based on the current ongoing implementation of grpc stack, the pull
wouldn't quite work because it's a callback when the Stream has a message not
when you call ReceiveMessage.

[Garrett Casto, 2016/10/05 20:53:07]

Note that we originally had this as a callback that would always be called when
you a message was received. We changed this to allow for flow control on the
recievers side. However, after a conversation I had with Matt earlier this week,
it's possible we may want to change this back. Let me add the two of you to the
thread on the design doc discussing this.

+      base::Callback<void(std::unique_ptr<HeliumMessage>, HeliumResult)>
+          on_receive_cb) = 0;
+
+  // Lets other objects observe the Stream for major state changes (e.g.
+  // connectivity).
+  void AddObserver(Observer* observer);
+
+ protected:
+  // Notifies observers that the underlying transport for this Stream is no
+  // longer connected. Must be called by a subclass before the HeliumStream
+  // can be torn down.
+  void NotifyStreamDisconnected();
+
+ private:
+  base::ObserverList<HeliumStream::Observer> observers_;
+
+  DISALLOW_COPY_AND_ASSIGN(HeliumStream);
+};
+
+}  // namespace blimp
+
+#endif  // BLIMP_NET_HELIUM_HELIUM_STREAM_H_