content/common/websocket_messages.h

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Multiply-included message file, hence no include guard.
   6
   7 // This file defines the IPCs for the browser-side implementation of
   8 // WebSockets.
   9 //
  10 // This IPC interface is based on the WebSocket multiplexing draft spec,
  11 // http://tools.ietf.org/html/draft-ietf-hybi-websocket-multiplexing-09
  12
  13 #include <string>
  14 #include <vector>
  15
  16 #include "base/basictypes.h"
  17 #include "content/common/content_export.h"
  18 #include "content/common/websocket.h"
  19 #include "ipc/ipc_message_macros.h"
  20 #include "url/gurl.h"
  21 #include "url/origin.h"
  22
  23 #undef IPC_MESSAGE_EXPORT
  24 #define IPC_MESSAGE_EXPORT CONTENT_EXPORT
  25 #define IPC_MESSAGE_START WebSocketMsgStart
  26
  27 IPC_ENUM_TRAITS_MAX_VALUE(content::WebSocketMessageType,
  28                           content::WEB_SOCKET_MESSAGE_TYPE_LAST)
  29
  30 IPC_STRUCT_TRAITS_BEGIN(content::WebSocketHandshakeRequest)
  31   IPC_STRUCT_TRAITS_MEMBER(url)
  32   IPC_STRUCT_TRAITS_MEMBER(headers)
  33   IPC_STRUCT_TRAITS_MEMBER(headers_text)
  34   IPC_STRUCT_TRAITS_MEMBER(request_time)
  35 IPC_STRUCT_TRAITS_END()
  36
  37 IPC_STRUCT_TRAITS_BEGIN(content::WebSocketHandshakeResponse)
  38   IPC_STRUCT_TRAITS_MEMBER(url)
  39   IPC_STRUCT_TRAITS_MEMBER(status_code)
  40   IPC_STRUCT_TRAITS_MEMBER(status_text)
  41   IPC_STRUCT_TRAITS_MEMBER(headers)
  42   IPC_STRUCT_TRAITS_MEMBER(headers_text)
  43   IPC_STRUCT_TRAITS_MEMBER(response_time)
  44 IPC_STRUCT_TRAITS_END()
  45
  46 // WebSocket messages sent from the renderer to the browser.
  47
  48 // Open new virtual WebSocket connection to |socket_url|. |channel_id| is an
  49 // identifier chosen by the renderer for the new channel. It cannot correspond
  50 // to an existing open channel, and must be between 1 and
  51 // 0x7FFFFFFF. |requested_protocols| is a list of tokens identifying
  52 // sub-protocols the renderer would like to use, as described in RFC6455
  53 // "Subprotocols Using the WebSocket Protocol".
  54 //
  55 // The browser process will not send |channel_id| as-is to the remote server; it
  56 // will try to use a short id on the wire. This saves the renderer from
  57 // having to try to choose the ids cleverly.
  58 IPC_MESSAGE_ROUTED4(WebSocketHostMsg_AddChannelRequest,
  59                     GURL /* socket_url */,
  60                     std::vector<std::string> /* requested_protocols */,
  61                     url::Origin /* origin */,
  62                     int /* render_frame_id */)
  63
  64 // WebSocket messages sent from the browser to the renderer.
  65
  66 // Respond to an AddChannelRequest for channel |channel_id|. |channel_id| is
  67 // scoped to the renderer process; while it is unique per-renderer, the browser
  68 // may have multiple renderers using the same id. If |fail| is true, the channel
  69 // could not be established (the cause of the failure is not provided to the
  70 // renderer in order to limit its ability to abuse WebSockets to perform network
  71 // probing, etc.). If |fail| is set then the |channel_id| is available for
  72 // re-use. |selected_protocol| is the sub-protocol the server selected,
  73 // or empty if no sub-protocol was selected. |extensions| is the list of
  74 // extensions negotiated for the connection.
  75 IPC_MESSAGE_ROUTED3(WebSocketMsg_AddChannelResponse,
  76                     bool /* fail */,
  77                     std::string /* selected_protocol */,
  78                     std::string /* extensions */)
  79
  80 // Notify the renderer that the browser has started an opening handshake.
  81 // This message is for showing the request in the inspector and
  82 // can be omitted if the inspector is not active.
  83 IPC_MESSAGE_ROUTED1(WebSocketMsg_NotifyStartOpeningHandshake,
  84                     content::WebSocketHandshakeRequest /* request */)
  85
  86 // Notify the renderer that the browser has finished an opening handshake.
  87 // This message precedes AddChannelResponse.
  88 // This message is for showing the response in the inspector and
  89 // can be omitted if the inspector is not active.
  90 IPC_MESSAGE_ROUTED1(WebSocketMsg_NotifyFinishOpeningHandshake,
  91                     content::WebSocketHandshakeResponse /* response */)
  92
  93 // Notify the renderer that the browser is required to fail the connection
  94 // (see RFC6455 7.1.7 for details).
  95 // When the renderer process receives this messages it does the following:
  96 // 1. Fire an error event.
  97 // 2. Show |message| to the inspector.
  98 // 3. Close the channel immediately uncleanly, as if it received
  99 //    DropChannel(was_clean = false, code = 1006, reason = "").
 100 // |message| will be shown in the inspector and won't be passed to the script.
 101 // TODO(yhirano): Find the way to pass |message| directly to the inspector
 102 // process.
 103 IPC_MESSAGE_ROUTED1(WebSocketMsg_NotifyFailure,
 104                     std::string /* message */)
 105
 106 // WebSocket messages that can be sent in either direction.
 107
 108 // Send a non-control frame on |channel_id|. If the sender is the renderer, it
 109 // will be sent to the remote server. If the sender is the browser, it comes
 110 // from the remote server. |fin| indicates that this frame is the last in the
 111 // current message. |type| is the type of the message. On the first frame of a
 112 // message, it must be set to either WEB_SOCKET_MESSAGE_TYPE_TEXT or
 113 // WEB_SOCKET_MESSAGE_TYPE_BINARY. On subsequent frames, it must be set to
 114 // WEB_SOCKET_MESSAGE_TYPE_CONTINUATION, and the type is the same as that of the
 115 // first message. If |type| is WEB_SOCKET_MESSAGE_TYPE_TEXT, then the
 116 // concatenation of the |data| from every frame in the message must be valid
 117 // UTF-8. If |fin| is not set, |data| must be non-empty.
 118 IPC_MESSAGE_ROUTED3(WebSocketMsg_SendFrame,
 119                     bool /* fin */,
 120                     content::WebSocketMessageType /* type */,
 121                     std::vector<char> /* data */)
 122
 123 // Add |quota| tokens of send quota for channel |channel_id|. |quota| must be a
 124 // positive integer. Both the browser and the renderer set send quota for the
 125 // other side, and check that quota has not been exceeded when receiving
 126 // messages. Both sides start a new channel with a quota of 0, and must wait for
 127 // a FlowControl message before calling SendFrame. The total available quota on
 128 // one side must never exceed 0x7FFFFFFFFFFFFFFF tokens.
 129 IPC_MESSAGE_ROUTED1(WebSocketMsg_FlowControl,
 130                     int64 /* quota */)
 131
 132 // Drop the channel.
 133 // When sent by the renderer, this will cause a DropChannel message to be sent
 134 // if the multiplex extension is in use, otherwise a Close message will be sent
 135 // and the TCP/IP connection will be closed.
 136 // When sent by the browser, this indicates that a Close or DropChannel has been
 137 // received, the connection was closed, or a network or protocol error
 138 // occurred. On receiving DropChannel, the renderer process may consider the
 139 // |channel_id| available for reuse by a new AddChannelRequest.
 140 // |code| is one of the reason codes specified in RFC6455 or
 141 // draft-ietf-hybi-websocket-multiplexing-09. |reason|, if non-empty, is a
 142 // UTF-8 encoded string which may be useful for debugging but is not necessarily
 143 // human-readable, as supplied by the server in the Close or DropChannel
 144 // message.
 145 // If |was_clean| is false on a message from the browser, then the WebSocket
 146 // connection was not closed cleanly. If |was_clean| is false on a message from
 147 // the renderer, then the connection should be closed immediately without a
 148 // closing handshake and the renderer cannot accept any new messages on this
 149 // connection.
 150 IPC_MESSAGE_ROUTED3(WebSocketMsg_DropChannel,
 151                     bool /* was_clean */,
 152                     unsigned short /* code */,
 153                     std::string /* reason */)
 154
 155 // Notify the renderer that a closing handshake has been initiated by the
 156 // server, so that it can set the Javascript readyState to CLOSING.
 157 IPC_MESSAGE_ROUTED0(WebSocketMsg_NotifyClosing)