Port WebSockets to Mojo IPC

content/common/websocket.mojom

+// 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.
+
+module content.mojom;
+
+import "url/mojo/origin.mojom";
+import "url/mojo/url.mojom";
+
+enum WebSocketMessageType {
+  CONTINUATION,
+  TEXT,
+  BINARY,
+  LAST = BINARY
+};
+
+// TODO(darin): Move to a more general location.
+struct HttpHeader {
+  string name;
+  string value;
+};
+
+// TODO(darin): Remove redundancy b/w |headers| and |headers_text|.
+
+struct WebSocketHandshakeRequest {
+  url.mojom.Url url;
+  array<HttpHeader> headers;
+  string headers_text;
+};
+
+struct WebSocketHandshakeResponse {
+  url.mojom.Url url;
+  int32 status_code;
+  string status_text;
+  array<HttpHeader> headers;
+  string headers_text;
+};
+
+interface WebSocketClient {
+  OnFailChannel(string reason);
+
+  // Notify the renderer that the browser has started an opening handshake.
+  // This message is for showing the request in the inspector and
+  // can be omitted if the inspector is not active.
+  OnStartOpeningHandshake(WebSocketHandshakeRequest request);
+
+  // Notify the renderer that the browser has finished an opening handshake.
+  // This message precedes AddChannelResponse.
+  // This message is for showing the response in the inspector and
+  // can be omitted if the inspector is not active.
+  OnFinishOpeningHandshake(WebSocketHandshakeResponse response);
+
+  // Response to an AddChannelRequest. |selected_protocol| is the sub-protocol
+  // the server selected, or empty if no sub-protocol was selected.
+  // |extensions| is the list of extensions negotiated for the connection.
+  OnAddChannelResponse(string selected_protocol, string extensions);
+
+  // Indicates tbat the current Blob has finished sending. The renderer can
+  // release its reference on the Blob, and may now use SendFrame or SendBlob to
+  // send more messages.
+  OnBlobSent();
+
+  // Send a non-control frame to the channel.
+  // - If the sender is the renderer, it will be sent to the remote server.
+  // - If the sender is the browser, it comes from the remote server.
+  //
+  // - |fin| indicates that this frame is the last in the current message.
+  // - |type| is the type of the message. On the first frame of a message, it
+  //   must be set to either WEB_SOCKET_MESSAGE_TYPE_TEXT or
+  //   WEB_SOCKET_MESSAGE_TYPE_BINARY. On subsequent frames, it must be set to
+  //   WEB_SOCKET_MESSAGE_TYPE_CONTINUATION, and the type is the same as that of
+  //   the first message. If |type| is WEB_SOCKET_MESSAGE_TYPE_TEXT, then the
+  //   concatenation of the |data| from every frame in the message must be valid
+  //   UTF-8. If |fin| is not set, |data| must be non-empty.
+  OnDataFrame(bool fin, WebSocketMessageType type, array<uint8> data);
+
+  // Add |quota| tokens of send quota for the channel. |quota| must be a positive
+  // integer. Both the browser and the renderer set send quota for the other
+  // side, and check that quota has not been exceeded when receiving messages.
+  // Both sides start a new channel with a quota of 0, and must wait for a
+  // FlowControl message before calling SendFrame. The total available quota on
+  // one side must never exceed 0x7FFFFFFFFFFFFFFF tokens.
+  //
+  // During "blob sending mode", ie. between the renderer sending a
+  // WebSocketHostMsg_SendBlob IPC and receiving a WebSocketMsg_BlobSendComplete
+  // IPC, quota is used up in the browser process to send the blob, but
+  // FlowControl IPCs for that quota are still sent to the renderer. The render
+  // process needs to take into account that quota equal to the size of the Blob
+  // has already been used when calculating how much send quota it has left after
+  // receiving BlobSendComplete.
+  OnFlowControl(int64 quota);
+
+  // Drop the channel.
+  //
+  // When sent by the renderer, this will cause a Close message will be sent and
+  // the TCP/IP connection will be closed.
+  //
+  // When sent by the browser, this indicates that a Close has been received, the
+  // connection was closed, or a network or protocol error occurred.
+  //
+  // - |code| is one of the reason codes specified in RFC6455.
+  // - |reason|, if non-empty, is a UTF-8 encoded string which may be useful for
+  //   debugging but is not necessarily human-readable, as supplied by the server
+  //   in the Close message.
+  // - If |was_clean| is false, then the WebSocket connection was not closed
+  //   cleanly.
+  OnDropChannel(bool was_clean, uint16 code, string reason);
+
+  // Notify the renderer that a closing handshake has been initiated by the
+  // server, so that it can set the Javascript readyState to CLOSING.
+  OnClosingHandshake();
+};
+
+interface WebSocket {
+  // Must be called prior to any of the other methods.
+  Initialize(WebSocketClient client);
+
+  // Open new WebSocket connection to |socket_url|. |requested_protocols| is a
+  // list of tokens identifying sub-protocols the renderer would like to use,
+  // as described in RFC6455 "Subprotocols Using the WebSocket Protocol".
+  AddChannelRequest(url.mojom.Url url,
+                    array<string> requested_protocols,
+                    url.mojom.Origin origin);
+
+  // Send a complete binary WebSocket message consisting of the Blob identified
+  // by |uuid|. The message will be split into frames as necessary.
+  // |expected_size| must match the browser's idea of the size of the Blob to
+  // prevent flow control from becoming desynchronised. If it does not match
+  // the connection will be terminated with a NotifyFailure message. On
+  // success, the browser will have consumed |expected_size| bytes of flow
+  // control send quota and the renderer needs to subtract that from its
+  // running total of flow control send quota. See the design doc at
+  // https://docs.google.com/document/d/1CDiXB9pBumhFVVfmIn1CRI6v6byxyqWu2urEE9xp714/edit
+  // SendFrame or SendBlob messages must not be sent by the renderer until the
+  // BlobSendComplete message has been received from the browser. The renderer
+  // should retain a reference to the Blob until either a BlobSendComplete or
+  // NotifyFailure IPC is received.
+  // XXX need to handle race condition with Blob registration
+  SendBlob(string uuid, uint64 expected_size);
+
+  // Send a non-control frame to the channel.
+  // - If the sender is the renderer, it will be sent to the remote server.
+  // - If the sender is the browser, it comes from the remote server.
+  //
+  // - |fin| indicates that this frame is the last in the current message.
+  // - |type| is the type of the message. On the first frame of a message, it
+  //   must be set to either WEB_SOCKET_MESSAGE_TYPE_TEXT or
+  //   WEB_SOCKET_MESSAGE_TYPE_BINARY. On subsequent frames, it must be set to
+  //   WEB_SOCKET_MESSAGE_TYPE_CONTINUATION, and the type is the same as that of
+  //   the first message. If |type| is WEB_SOCKET_MESSAGE_TYPE_TEXT, then the
+  //   concatenation of the |data| from every frame in the message must be valid
+  //   UTF-8. If |fin| is not set, |data| must be non-empty.
+  SendFrame(bool fin, WebSocketMessageType type, array<uint8> data);
+
+  // Add |quota| tokens of send quota for the channel. |quota| must be a positive
+  // integer. Both the browser and the renderer set send quota for the other
+  // side, and check that quota has not been exceeded when receiving messages.
+  // Both sides start a new channel with a quota of 0, and must wait for a
+  // FlowControl message before calling SendFrame. The total available quota on
+  // one side must never exceed 0x7FFFFFFFFFFFFFFF tokens.
+  //
+  // During "blob sending mode", ie. between the renderer sending a
+  // WebSocketHostMsg_SendBlob IPC and receiving a WebSocketMsg_BlobSendComplete
+  // IPC, quota is used up in the browser process to send the blob, but
+  // FlowControl IPCs for that quota are still sent to the renderer. The render
+  // process needs to take into account that quota equal to the size of the Blob
+  // has already been used when calculating how much send quota it has left after
+  // receiving BlobSendComplete.
+  SendFlowControl(int64 quota);
+
+  // Close the channel gracefully.
+  //
+  // When sent by the renderer, this will cause a Close message will be sent and
+  // the TCP/IP connection will be closed.
+  //
+  // - |code| is one of the reason codes specified in RFC6455.
+  // - |reason|, if non-empty, is a UTF-8 encoded string which may be useful for
+  //   debugging but is not necessarily human-readable, as supplied by the server
+  //   in the Close message.
+  StartClosingHandshake(uint16 code, string reason);
+};