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_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;
 
 // 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
 // (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() {}
+  // The type the callback that should be supplied to handle successful
+  // connection. This must be supplied by the caller. It must take a scoped_ptr
+  // to a WebSocketStream as a parameter.
+  typedef base::Callback<void(scoped_ptr<WebSocketStream>)> SuccessCallback;
+
+  // The type of the callback that should be supplied to handle failed
+  // connection. The parameter is a net::WebSocketError, but it is passed as
+  // unsigned short as it is not guaranteed to actually be defined in that enum.
+  typedef base::Callback<void(unsigned short)> FailureCallback;
+
+  // Create and connect a WebSocketStream of an appropriate type. 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 a WebSocket result code corresponding to the
+  // error.
+  static void CreateAndConnectStream(
+      const GURL& socket_url,
+      const std::vector<std::string>& requested_protocols,
+      const GURL& origin,
+      URLRequestContext* url_request_context,
+      const SuccessCallback& on_success,
+      const FailureCallback& on_failure);
 
   // Derived classes must make sure Close() is called when the stream is not
   // closed on destruction.
-  virtual ~WebSocketStream() {}
+  virtual ~WebSocketStream();
 
-  // Initializes stream. Must be called before calling SendHandshakeRequest().
-  // Returns a net error code, possibly ERR_IO_PENDING, as stated above.
+  // Writes WebSocket handshake request to the underlying socket. Must be called
+  // before ReadHandshakeResponse().
   //
-  // |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.
+  // "callback" will only be called if this method returns ERR_IO_PENDING.
   //
-  // |response_info| must remain valid until the stream is destroyed.
-  virtual int SendHandshakeRequest(const HttpRequestHeaders& headers,
+  // |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. This
-  // function completes when the response headers have been completely
-  // received. Must be called after SendHandshakeRequest() completes.
+  // 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;
 
   // 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()

[yhirano, 2013/06/25 07:51:40]

Can this function be called before ReadHandshakeResponse?

[Adam Rice, 2013/06/25 09:48:10]

No, I have moved ReadHandshakeResponse() and SendHandshakeResponse() down below
to try to make it clear that they are not used after the session is established.

+  // is still pending.
+  //
+  // Returns net::OK or one of the net::ERR_* codes.
+  //
+  // frame_chunks->size() >= 1 if the result is OK.
+  // The callback will not be called until the entire frame header is

[yhirano, 2013/06/25 07:51:40]

How about "This function will not complete until the entire frame header is
available."?

[Adam Rice, 2013/06/25 09:48:10]

I have tried to make the comment clearer. Please take another look.

+  // available. If only the first byte is available, the callback will not be
+  // called until the rest arrives. If ReadFrames() is freshly called while only
+  // the first byte is available, it will return ERR_IO_PENDING exactly as if no
+  // data was available.
+  //
+  // Every WebSocketFrameChunk in the vector except the last one is guaranteed
+  // to be a complete 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

[yhirano, 2013/06/25 07:51:40]

Can this function be called before ReadHandshakeResponse?

[Adam Rice, 2013/06/25 09:48:10]

No, but WebSocketFactory will not attempt to call it so it should not be a
problem.

+  // 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.
   virtual int WriteFrames(ScopedVector<WebSocketFrameChunk>* frame_chunks,
                           const CompletionCallback& callback) = 0;
 
   // Closes the stream. All pending I/O operations (if any) are canceled
   // at this point, so |frame_chunks| can be freed.
+  // TODO(ricea): Is this actually needed?

[yhirano, 2013/06/25 07:51:40]

Isn't it? I think it is necessary.

[Adam Rice, 2013/06/25 09:48:10]

Yes, I wrote that comment before implementing WebSocketChannel. WebSocketChannel
uses Close() when there is an IO error. In normal operation the channel is
always closed from the server side, so this method is only used on error.

   virtual void Close() = 0;
 
+  // The protocol that was negotiated for the stream. If no protocol was
+  // negotiated, then the empty string is returned.
+  virtual std::string Protocol() = 0;
+
+  // The extensions that were negotiated for the stream. Since WebSocketStreams
+  // can be layered, this may be different from what this particular
+  // WebSocketStream implements.
+  virtual std::string Extensions() = 0;
+
   // TODO(yutak): Add following interfaces:
   // - RenewStreamForAuth for authentication (is this necessary?)
   // - GetSSLInfo, GetSSLCertRequsetInfo for SSL
 
   // WebSocketStreamBase derived functions
   virtual WebSocketStream* AsWebSocketStream() { return this; }
 
+ protected:
+  WebSocketStream();
+
  private:
   DISALLOW_COPY_AND_ASSIGN(WebSocketStream);
 };
 
 }  // namespace net
 
 #endif  // NET_WEBSOCKETS_WEBSOCKET_STREAM_H_