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

ppapi/api/ppb_websocket.idl

 /* 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.
  */
 
 /**
  * This file defines the <code>PPB_WebSocket</code> interface providing
  * bi-directional, full-duplex, communications over a single TCP socket.
  */
 label Chrome {
@@ skipping 38 matching lines @@
  * This enumeration contains status codes. These codes are used in Close() and
  * GetCloseCode(). Refer to RFC 6455, The WebSocket Protocol, for further
  * information.
  * <code>PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE</code> and codes in the range
  * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN</code> to
  * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX</code>, and
  * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN</code> to
  * <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.
    */
 
   /**
    * Indicates a normal closure.
    */
   PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE = 1000,
 
   /**
@@ skipping 167 matching lines @@
                   [in] uint32_t protocol_count,
                   [in] PP_CompletionCallback callback);
 
   /**
    * Close() closes the specified WebSocket connection by specifying
    * <code>code</code> and <code>reason</code>.
    *
    * @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
    * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX</code>, and in the range
    * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN</code> to
    * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX</code> are available.
    *
    * @param[in] reason A <code>PP_Var</code> representing the WebSocket
    * close reason. This is ignored if it is <code>PP_VARTYPE_UNDEFINED</code>.
    * Otherwise, its <code>PP_VarType</code> must be
    * <code>PP_VARTYPE_STRING</code>.
    *
    * @param[in] callback A <code>PP_CompletionCallback</code> called
    * when the connection is closed or an error occurs in closing the
    * connection.
    *
    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
    * Returns <code>PP_ERROR_BADARGUMENT</code> if <code>reason</code> contains
    * an invalid character as a UTF-8 string, or is longer than 123 bytes.
    * <code>PP_ERROR_BADARGUMENT</code> corresponds to a JavaScript SyntaxError
    * in the WebSocket API specification.
    * Returns <code>PP_ERROR_NOACCESS</code> if the code is not an integer
    * equal to 1000 or in the range 3000 to 4999. <code>PP_ERROR_NOACCESS</code>
    * corresponds to an InvalidAccessError in the WebSocket API specification.
    * Returns <code>PP_ERROR_INPROGRESS</code> if a previous call to Close() is
    * 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);
 
   /**
    * ReceiveMessage() receives a message from the WebSocket server.
    * This interface only returns a single message. That is, this interface must
    * be called at least N times to receive N messages, no matter the size of
    * each message.
    *
    * @param[in] web_socket A <code>PP_Resource</code> corresponding to a
@@ skipping 139 matching lines @@
    * @param[in] web_socket A <code>PP_Resource</code> corresponding to a
    * WebSocket.
    *
    * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the
    * connection is established, the var contains the empty string. Returns a
    * <code>PP_VARTYPE_UNDEFINED</code> if this function is called on an
    * invalid resource.
    */
   PP_Var GetURL([in] PP_Resource web_socket);
 };