WebSocket Pepper API: allow to close connection without code and reason

ppapi/api/ppb_websocket.idl

Index: ppapi/api/ppb_websocket.idl
diff --git a/ppapi/api/ppb_websocket.idl b/ppapi/api/ppb_websocket.idl
index 1e138bb80b47bf8a405a99177edef010c7321f7d..2d80b51097ca64661e996fcc01db3d851030a6a2 100644
--- a/ppapi/api/ppb_websocket.idl
+++ b/ppapi/api/ppb_websocket.idl
@@ -56,7 +56,14 @@ enum PP_WebSocketReadyState {
  * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX</code> are valid for Close().
  */
 [assert_size(4)]
-enum PP_WebSocketCloseCode {
+enum PP_WebSocketStatusCode {
+  /**
+   * Indicates to request closing connection without status code. This code is
+   * internally assigned in WebKit, and not based on any WebSocket related
+   * specification.
+   */
+  PP_WEBSOCKETSTATUSCODE_NOT_SPECIFIED = -1,
+
   /**
    * Status codes in the range 0-999 are not used.
    */
@@ -244,7 +251,8 @@ interface PPB_WebSocket {
    * @param[in] web_socket A <code>PP_Resource</code> corresponding to a
    * WebSocket.
    *
-   * @param[in] code The WebSocket close code. This is ignored if it is 0.

[dmichael (off chromium), 2012/05/15 15:18:33]

So, what does ignored mean in this case? When the close event fires, what is the
close code that JavaScript gets? I'm trying to find it in the spec...  I think ,
and I don't see it.
The WhatWG WebSocket spec says:
"Create an event that uses the CloseEvent interface, with the event type close
[...] whose code attribute is initialized to the WebSocket connection close
code,"
And RFC6455 says:
"   If this Close control frame contains no status code, _The WebSocket
   Connection Close Code_ is considered to be 1005."

So can we just say that the caller should provide 1005
(PP_WEBSOCKETSTATUSCODE_NO_STATUS_RECEIVED)? Or possibly provide another name
for it that maps to the same value, if you think that makes sense.

I see that the RFC says endpoints "must not" pass 1005, but...  I think that's
intended for JS, and I can't see the harm in using it this way. What do you
think?

[Takashi Toyoshima, 2012/05/16 09:20:32]

When I defined this API, I think I can use '0' to specify no status code and
reason because spec want to use only codes >= 1000. I think using '0' as
_NOT_SPECIFIED instead of '-1' is still acceptable another plan.

As you said, 1005, 1006, and 1015 are defined as pseudo code to represent
network framing layer's exceptions and spec explicitly forbid to use them from
endpoints. But, I think it will be acceptable to use them as an internal
intermediate code from the viewpoint of spec. On the other hand, these values
will be defined in ppapi header files and users (developers) can check the
actual values. I guess users who see 1005 will be confused at specifying a
forbidden value. I must write some comments on this. Our WebSocket team's tech
lead also agreed reusing 1005. So 1005 looks best solution.

+   * @param[in] code The WebSocket close code. This is ignored if it is
+   * <code>PP_WEBSOCKETSTATUSCODE_NOT_SPECIFIED</code>.
    * <code>PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE</code> must be used for the
    * usual case. To indicate some specific error cases, codes in the range
    * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN</code> to
@@ -273,7 +281,7 @@ interface PPB_WebSocket {
    * not finished.
    */
   int32_t Close([in] PP_Resource web_socket,
-                [in] uint16_t code,

[dmichael (off chromium), 2012/05/15 15:18:33]

Ack...  I'm sorry, I didn't realize you were using uint16_t in the C API, or I
wouldn't have suggested this change. If we change it here, we have to provide
backwards compatibility and support both interfaces. It may not be worth the
effort to do that.

We should probably have used an enum here from the beginning :-(.

[Takashi Toyoshima, 2012/05/16 09:20:32]

I guess uint16_t argument is compatible to one of int32_t and enum in i686 and
x86_64 ABIs because compiler generates the same caller codes for both of old and
new API definitions.
But I'm not super familiar to NaCl's ABI. As you said, reusing 1005 will be
safe.

+                [in] PP_WebSocketStatusCode code,
                 [in] PP_Var reason,
                 [in] PP_CompletionCallback callback);