Add WebSocketStream interface.

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 "base/basictypes.h"
+#include "base/memory/scoped_vector.h"
+#include "net/base/completion_callback.h"
+
+namespace net {
+
+class BoundNetLog;
+class HttpRequestHeaders;
+struct HttpRequestInfo;
+class HttpResponseInfo;
+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.
+
+class WebSocketStream {
+ public:
+  WebSocketStream() {}
+  virtual ~WebSocketStream() {}

[willchan no longer on Chromium, 2012/07/23 21:28:52]

Document that ~WebSocketStream will Close() the stream.

[Yuta Kitamura, 2012/08/06 11:34:29]

Done.

+
+  // Initialize stream. Must be called before calling SendHandshakeRequest().
+  // Returns a net error code, possibly ERR_IO_PENDING. If return value is
+  // ERR_IO_PENDING, |callback| is called when the operation is finished. This

[willchan no longer on Chromium, 2012/07/23 21:28:52]

In all these APIs, document that !callback.is_null().

[Yuta Kitamura, 2012/08/06 11:34:29]

Done. Requirement for asynchronous operations is moved to
the top of the class.

+  // convention applies to other functions defined in this class.
+  //
+  // |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,

[willchan no longer on Chromium, 2012/07/23 21:28:52]

const HttpRequestInfo&? I don't think it should be possible to be NULL, right?

[Yuta Kitamura, 2012/08/06 11:34:29]

Correct. Fixed. (I just copied this from HttpStream, and
am not sure if there's some history here...)

+                               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.
+  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;

[willchan no longer on Chromium, 2012/07/23 21:28:52]

Why is this split out from SendHandshakeRequest()?

[Yuta Kitamura, 2012/08/06 11:34:29]

Good point, there is not much reason except that HttpStream
has both SendRequest() and ReadResponseHeaders().

Having both Send and Read functions will probably make
the implementation a little bit easier. Otherwise we need
a state machine in Stream implementation.

Also, users might want to distinguish whether a failure comes
from write or read.

+
+  // 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.

[willchan no longer on Chromium, 2012/07/23 21:28:52]

or canceled via Close()

[Yuta Kitamura, 2012/08/06 11:34:29]

Done.

+  //
+  // This function can be called after ReadHandshakeResponse(). This function
+  // should not be called while previous call of ReadFrames() is still pending.
+  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. It is allowed to
+  // send part of WebSocket frame data.
+  //
+  // This function can be called after ReadHandshakeResponse(). This function
+  // should not be called while previous call of WriteFrames() is still pending.
+  virtual int WriteFrames(ScopedVector<WebSocketFrameChunk>* frame_chunks,
+                          const CompletionCallback& callback) = 0;

[mmenke, 2012/07/23 17:46:05]

How is this supposed to work when it sends only part of the WebSocket frame
data?  How do you send the rest?

[Yuta Kitamura, 2012/08/06 11:34:29]

Users are expected to send one or more WebSocketFrameChunks
with |final_chunk| set to false, followed by
a WebSocketFrameChunk with |final_chunk| set to true. These
chunks collectively represent a WebSocket frame.

I clarified this point in the updated patch.

[mmenke, 2012/08/06 16:15:37]

Thanks.  You're right - the old comment had confused me.

+
+  // Disconnects the underlying connection. We don't support reuse of
+  // connections for now, because it is not clear whether existing WebSocket
+  // servers really support it.
+  virtual int Disconnect() = 0;

[mmenke, 2012/07/23 17:46:05]

Should this be Close()?  Also, what about the multiplexing extension?  Wouldn't
that result in having two WebSocketStreams with the same underlying connection?

[mmenke, 2012/07/23 17:46:05]

Why do we need a return value?

[willchan no longer on Chromium, 2012/07/23 21:28:52]

Yeah, this should be called closing the WebSocketStream. It shouldn't reference
the underlying connection at all.

You also need to document that all IO operations are canceled at this point, so
|frame_chunks| can be freed.

[Yuta Kitamura, 2012/08/06 11:34:29]

OK, fixed.

+
+  // TODO(yutak): Add following interfaces:
+  // - RenewStreamForAuth for authentication (is this necessary?)
+  // - GetSSLInfo, GetSSLCertRequsetInfo for SSL
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(WebSocketStream);
+};
+
+}  // namespace net
+
+#endif  // NET_WEBSOCKETS_WEBSOCKET_STREAM_H_