Add WebSocketStream factory function

net/websockets/websocket_stream.h

 // Copyright (c) 2012 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 NET_WEBSOCKETS_WEBSOCKET_STREAM_H_
 #define NET_WEBSOCKETS_WEBSOCKET_STREAM_H_
 
+#include <string>
+
 #include "base/basictypes.h"
+#include "base/callback_forward.h"
+#include "base/memory/scoped_ptr.h"
 #include "base/memory/scoped_vector.h"
 #include "net/base/completion_callback.h"
+#include "net/base/net_export.h"
 #include "net/websockets/websocket_stream_base.h"
 
+class GURL;
+
 namespace net {
 
 class BoundNetLog;
 class HttpRequestHeaders;
-struct HttpRequestInfo;
 class HttpResponseInfo;
+class URLRequestContext;
 struct WebSocketFrameChunk;
 
+// WebSocketStreamRequest is the caller's handle to the process of creation of a
+// WebSocketStream. Deleting the object before the OnSuccess or OnFailure
+// callbacks are called will cancel the request (and neither callback will be
+// called). After OnSuccess or OnFailure have been called, this object may be
+// safely deleted without side-effects.
+class NET_EXPORT_PRIVATE WebSocketStreamRequest {
+public:

[mmenke1, 2013/06/27 16:56:23]

nit:  indent 1

[Adam Rice, 2013/06/27 17:47:32]

Fixed in a future patch.

+  virtual ~WebSocketStreamRequest();
+};
+
 // WebSocketStream is a transport-agnostic interface for reading and writing
 // WebSocket frames. This class provides an abstraction for WebSocket streams
-// based on various transport layer, such as normal WebSocket connections
+// based on various transport layers, such as normal WebSocket connections
 // (WebSocket protocol upgraded from HTTP handshake), SPDY transports, or
 // WebSocket connections with multiplexing extension. Subtypes of
 // WebSocketStream are responsible for managing the underlying transport
 // appropriately.
 //
 // All functions except Close() can be asynchronous. If an operation cannot
 // be finished synchronously, the function returns ERR_IO_PENDING, and
 // |callback| will be called when the operation is finished. Non-null |callback|
 // must be provided to these functions.
 
-class WebSocketStream : public WebSocketStreamBase {
+class NET_EXPORT_PRIVATE WebSocketStream : public WebSocketStreamBase {
  public:
-  WebSocketStream() {}
+  // A concrete object derived from ConnectDelegate is supplied by the caller to
+  // CreateAndConnectStream() to receive the result of the connection.
+  class ConnectDelegate {
+   public:
+    // Called on successful connection. The parameter is an object derived from
+    // WebSocketStream.
+    virtual void OnSuccess(scoped_ptr<WebSocketStream> stream) = 0;
+
+    // Called on failure to connect. The parameter is either one of the values
+    // defined in net::WebSocketError, or an error defined by some WebSocket
+    // extension protocol that we implement.
+    virtual void OnFailure(unsigned short websocket_error) = 0;
+  };

[mmenke, 2013/06/27 15:25:09]

Do we even need ConnectDelegate or WebSocketStreamRequest?  We have
HttpStreamRequest and HttpStreamRequest::Delegate, both of which now handle
WebSockets.  Seems like we can just take in an HttpStreamRequest::Delegate and
return an HttpStreamRequest.

Or is there some subtlety in the difference between a WebSocketStream and a
WebSocketStreamBase that I'm missing?  I don't think we get a whole lot from the
separation of the two classes.

With this arrangement, we'd presumably need to duplicate the SSL cert/proxy auth
handlers HttpStreamRequest::Delegate has for WebSocketStreamRequest as well, if
we want to handle those cases.

[Adam Rice, 2013/06/27 16:27:08]

To be honest, I'm not sure at the moment. In the case where we start a new
logical channel on an existing physical multiplexed WebSocketStream, I am
guessing that we won't use HttpStreamRequest at all.

WebSockets will only use existing authentication details or client certificates
that the user has established with HTTP/HTTPS connections to the same site or
proxy. We will never popup UI saying "Enter password" or "Select certificate". I
think this means that the SSL cert/proxy auth handler stuff can be kept out of
the higher-level APIs.

[mmenke1, 2013/06/27 16:56:23]

Good point.  May want to think about modelling things after how SpdySessionPool
works, to make it easier for people who deal with both classes.

+
+  // Create and connect a WebSocketStream of an appropriate type. The actual
+  // concrete type returned depends on whether multiplexing or SPDY are being
+  // used to communicate with the remote server. If the handshake completed
+  // successfully, then the on_success callback is called with a subclass of
+  // WebSocketStream. If it failed, then the on_failure callback is called with

[mmenke1, 2013/06/27 16:56:23]

"on_success callback" -> "OnSuccess", same for on_failure.

[Adam Rice, 2013/06/27 17:47:32]

I rewrote this comment.

+  // a WebSocket result code corresponding to the error.
+  static scoped_ptr<WebSocketStreamRequest> CreateAndConnectStream(
+      const GURL& socket_url,
+      const std::vector<std::string>& requested_subprotocols,
+      const GURL& origin,
+      URLRequestContext* url_request_context,
+      const BoundNetLog& net_log,
+      scoped_ptr<ConnectDelegate> connect_delegate);
 
   // Derived classes must make sure Close() is called when the stream is not
   // closed on destruction.
-  virtual ~WebSocketStream() {}
-
-  // Initializes stream. Must be called before calling SendHandshakeRequest().
-  // Returns a net error code, possibly ERR_IO_PENDING, as stated above.
-  //
-  // |request_info.url| must be a URL starting with "ws://" or "wss://".
-  // |request_info.method| must be "GET". |request_info.upload_data| is
-  // ignored.
-  virtual int InitializeStream(const HttpRequestInfo& request_info,
-                               const BoundNetLog& net_log,
-                               const CompletionCallback& callback) = 0;
-
-  // Writes WebSocket handshake request to the underlying socket. Must be
-  // called after InitializeStream() completes and before
-  // ReadHandshakeResponse() is called.
-  //
-  // |response_info| must remain valid until the stream is destroyed.
-  virtual int SendHandshakeRequest(const HttpRequestHeaders& headers,
-                                   HttpResponseInfo* response_info,
-                                   const CompletionCallback& callback) = 0;
-
-  // Reads WebSocket handshake response from the underlying socket. This
-  // function completes when the response headers have been completely
-  // received. Must be called after SendHandshakeRequest() completes.
-  virtual int ReadHandshakeResponse(const CompletionCallback& callback) = 0;
+  virtual ~WebSocketStream();
 
   // Reads WebSocket frame data. This operation finishes when new frame data
   // becomes available. Each frame message might be chopped off in the middle
   // as specified in the description of WebSocketFrameChunk struct.
-  // |frame_chunks| must be valid until the operation completes or Close()
-  // is called.
+  // |frame_chunks| remains owned by the caller and must be valid until the
+  // operation completes or Close() is called. |frame_chunks| must be empty on
+  // calling.
   //
-  // This function can be called after ReadHandshakeResponse(). This function
-  // should not be called while the previous call of ReadFrames() is still
-  // pending.
+  // This function should not be called while the previous call of ReadFrames()
+  // is still pending.
+  //
+  // Returns net::OK or one of the net::ERR_* codes.
+  //
+  // frame_chunks->size() >= 1 if the result is OK.
+  //
+  // A frame with an incomplete header will never be inserted into
+  // |frame_chunks|. If the currently available bytes of a new frame do not form
+  // a complete frame header, then the implementation will buffer them until all
+  // the fields in the WebSocketFrameHeader object can be filled. If
+  // ReadFrames() is freshly called in this situation, it will return
+  // ERR_IO_PENDING exactly as if no data was available.
+  //
+  // Every WebSocketFrameChunk in the vector except the first and last is
+  // guaranteed to be a complete frame. The first chunk may be the final part
+  // of the previous frame. The last chunk may be the first part of a new
+  // frame. If there is only one chunk, then it may consist of data from the
+  // middle part of a frame.
+  //
+  // When the socket is closed on the remote side, this method will return
+  // ERR_CONNECTION_CLOSED. It will not return OK with an empty vector.
+  //
+  // If the connection is closed in the middle of receiving an incomplete frame,
+  // ReadFrames may discard the incomplete frame. Since the renderer will
+  // discard any incomplete messages when the connection is closed, this makes
+  // no difference to the overall semantics.
   virtual int ReadFrames(ScopedVector<WebSocketFrameChunk>* frame_chunks,
                          const CompletionCallback& callback) = 0;
 
   // Writes WebSocket frame data. |frame_chunks| must obey the rule specified
   // in the documentation of WebSocketFrameChunk struct: the first chunk of
   // a WebSocket frame must contain non-NULL |header|, and the last chunk must
   // have |final_chunk| field set to true. Series of chunks representing a
   // WebSocket frame must be consistent (the total length of |data| fields must
   // match |header->payload_length|). |frame_chunks| must be valid until the
   // operation completes or Close() is called.
   //
-  // This function can be called after ReadHandshakeResponse(). This function
-  // should not be called while previous call of WriteFrames() is still pending.
+  // This function should not be called while previous call of WriteFrames() is
+  // still pending.
+  //
+  // Support for incomplete frames is not guaranteed and may be removed from
+  // future iterations of the API.
+  //
+  // This method will only return OK if all frames were written completely.
+  // Otherwise it will return an appropriate ERR_ code.

[mmenke1, 2013/06/27 16:56:23]

suggest "ERR_ code" -> "net error code"

   virtual int WriteFrames(ScopedVector<WebSocketFrameChunk>* frame_chunks,
                           const CompletionCallback& callback) = 0;
 
-  // Closes the stream. All pending I/O operations (if any) are canceled
+  // Closes the stream. All pending I/O operations (if any) are cancelled
   // at this point, so |frame_chunks| can be freed.
   virtual void Close() = 0;
 
+  // The subprotocol that was negotiated for the stream. If no protocol was
+  // negotiated, then the empty string is returned.
+  virtual std::string GetSubProtocol() = 0;
+
+  // The extensions that were negotiated for the stream. Since WebSocketStreams
+  // can be layered, this may be different from what this particular
+  // WebSocketStream implements. The primary purpose of this accessor is to make

[mmenke1, 2013/06/27 16:56:23]

So WebSocketStream::GetExtensions is not what the WebSocketStream implements,
but rather what the WebSocketSession (Or whatever we choose to call it)
implements?

Suggest renaming it to something along the lines of GetExtensionsForSession().

[Adam Rice, 2013/06/27 17:47:32]

Yes. The whole thing seems like a gross layering violation to me. Maybe I should
just name it GetExtensionsForJavascript().

+  // the data available to Javascript. The format of the string is identical to
+  // the contents of the Sec-WebSocket-Extensions header supplied by the server,
+  // with some canonicalisations applied (leading and trailing whitespace
+  // removed, multiple headers concatenated into one comma-separated list). See
+  // RFC6455 section 9.1 for the exact format specification. If no
+  // extensions were negotiated, the empty string is returned.
+  virtual std::string GetExtensions() = 0;

[mmenke1, 2013/06/27 16:56:23]

Didn't you say you were going to make this and GetSubProtocol() const?

[Adam Rice, 2013/06/27 17:47:32]

Yes, there was a race condition between my fingers and my brain and git won.

+
   // TODO(yutak): Add following interfaces:
   // - RenewStreamForAuth for authentication (is this necessary?)
-  // - GetSSLInfo, GetSSLCertRequsetInfo for SSL
+  // - GetSSLInfo, GetSSLCertRequestInfo for SSL
 
   // WebSocketStreamBase derived functions
-  virtual WebSocketStream* AsWebSocketStream() { return this; }
+  virtual WebSocketStream* AsWebSocketStream() OVERRIDE;
+
+  ////////////////////////////////////////////////////////////////////////////
+  // Methods used during the stream handshake. These must not be called once a
+  // WebSocket protocol stream has been established (ie. after the
+  // SuccessCallback or FailureCallback has been called.)
+
+  // Writes WebSocket handshake request to the underlying socket. Must be called
+  // before ReadHandshakeResponse().
+  //
+  // |callback| will only be called if this method returns ERR_IO_PENDING.
+  //
+  // |response_info| must remain valid until the callback from
+  // ReadHandshakeResponse has been called.
+  //
+  // TODO(ricea): This function is only used during the handshake and is
+  // probably only applicable to certain subclasses of WebSocketStream. Move it
+  // somewhere else? Also applies to ReadHandshakeResponse.
+  virtual int SendHandshakeRequest(const GURL& url,
+                                   const HttpRequestHeaders& headers,
+                                   HttpResponseInfo* response_info,
+                                   const CompletionCallback& callback) = 0;
+
+  // Reads WebSocket handshake response from the underlying socket. Must be
+  // called after SendHandshakeRequest() completes.
+  //
+  // |callback| will only be called if this method returns ERR_IO_PENDING.
+  virtual int ReadHandshakeResponse(const CompletionCallback& callback) = 0;
+
+ protected:
+  WebSocketStream();
 
  private:
   DISALLOW_COPY_AND_ASSIGN(WebSocketStream);
 };
 
 }  // namespace net
 
 #endif  // NET_WEBSOCKETS_WEBSOCKET_STREAM_H_