Blimp: define HeliumTransport/HeliumStream interfaces.

blimp/net/helium/helium_transport.h

+// 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_TRANSPORT_H_
+#define BLIMP_NET_HELIUM_HELIUM_TRANSPORT_H_
+
+#include <memory>
+
+#include "base/callback.h"
+#include "blimp/net/helium/helium_result.h"
+
+namespace blimp {
+
+// Abstract interface for a HeliumStream factory. Subclasses can use this
+// interface to encapsulate transport-specific stream connection semantics.
+class HeliumTransport {
+ public:
+  // Callback invoked with the stream and result code of a Connect or Accept
+  // attempt.
+  // The HeliumStream is assumed to be authenticated and ready to use.
+  // If the connection attempt failed, the value of |stream| will be null and
+  // |result| will be set to the relevant error code.
+  using StreamCreatedCallback =
+      base::Callback<void(std::unique_ptr<HeliumStream> stream,
+                          HeliumResult result)>;
+
+  class Delegate {
+   public:
+    // Called when the transport transitions between an offline/unusable state
+    // and an online/usable state.
+    virtual void OnAvailabilityChanged(bool available) = 0;

[Wez, 2016/10/08 01:02:29]

nit: Since this has only a single method right now, how about using a Callback
and switching to Delegate if/when we add further Transport-level notifications?

[Kevin M, 2016/10/11 20:02:37]

Done.

+  };
+
+  virtual void SetDelegate(std::unique_ptr<Delegate> delegate);
+
+  // Asynchronously attempts to connect a new HeliumStream.
+  // Multiple overlapping connection attempts are permitted.
+  virtual void Connect(const StreamCreatedCallback& cb) = 0;

[Wez, 2016/10/08 01:02:29]

As discussed previously, I think we need a way to cancel a pending Connect -
otherwise if we try to Connect a new stream for an object, and receive a stream
assigned to it before the Connect succeeds, we have to actually wait for the
Connect to complete before we can close the redundant stream.

[Kevin M, 2016/10/11 20:02:37]

I switched to CancelableCallback. The Stream that is std::move'd to the callback
will be destroyed when the CancelableCallback no-ops Run().

As an optimization, the Transport can GC cancelled callbacks prior to
invocation, so the Stream is given to a worthier live callback.

+
+  // Accepts an incoming connection from the peer.
+  // Only one Accept() call may be issued at a time.

[Wez, 2016/10/08 01:02:30]

Do we need that restriction, really? We could make this symmetric with Connect
simply by maintaining a queue of StreamCreatedCallback calls to satisfy with
received connections. :)

[Kevin M, 2016/10/11 20:02:37]

Done.

+  virtual void Accept(const StreamCreatedCallback& cb) = 0;
+
+  // Returns true if the underlying transport has the necessary resources
+  // and connectivity for Connect and Accept operations.
+  virtual bool IsAvailable() = 0;

[Wez, 2016/10/08 01:02:29]

nit: Do we need both a notification *and* this?

[Kevin M, 2016/10/11 20:02:37]

I think it's useful for querying the initial connected state from the Transport.
The notification as it is specified now is only fired for state transitions,
which IMO makes the execution flow more straightforward for the notification
recipient.

+};
+
+}  // namespace blimp
+
+#endif  // BLIMP_NET_HELIUM_HELIUM_TRANSPORT_H_