PPB_TCPSocket: add support for TCP server socket operations.

ppapi/api/ppb_tcp_socket.idl

 /* Copyright 2013 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_TCPSocket</code> interface.
  */
 
-[generate_thunk]
-
 label Chrome {
-  M29 = 1.0
+  M29 = 1.0,
+  M31 = 1.1
 };
 
 /**
  * Option names used by <code>SetOption()</code>.
  */
 [assert_size(4)]
 enum PP_TCPSocket_Option {
   /**
    * Disables coalescing of small writes to make TCP segments, and instead
    * delivers data immediately. Value's type is <code>PP_VARTYPE_BOOL</code>.
@@ skipping 14 matching lines @@
 
   /**
    * Specifies the total per-socket buffer space reserved for receives. Value's
    * type should be <code>PP_VARTYPE_INT32</code>.
    * This option can only be set after a successful <code>Connect()</code> call.
    *
    * Note: This is only treated as a hint for the browser to set the buffer
    * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
    * guarantee it will conform to the size.
    */
-  PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2
+  PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2,
+
+  /**
+   * Allows the socket to share the local address to which it will be bound.
+   * Value's type should be <code>PP_VARTYPE_BOOL</code>.
+   * This option can only be set before calling <code>Bind()</code>.
+   * Supported since version 1.1.
+   */
+  PP_TCPSOCKET_OPTION_ADDRESS_REUSE = 3
 };
 
 /**
  * The <code>PPB_TCPSocket</code> interface provides TCP socket operations.
  *
  * Permissions: Apps permission <code>socket</code> with subrule
- * <code>tcp-connect</code> is required for <code>Connect()</code>.
+ * <code>tcp-connect</code> is required for <code>Connect()</code>; subrule
+ * <code>tcp-listen</code> is required for <code>Listen()</code>.
  * For more details about network communication permissions, please see:
  * http://developer.chrome.com/apps/app_network.html
  */
 interface PPB_TCPSocket {
   /**
    * Creates a TCP socket resource.
    *
    * @param[in] instance A <code>PP_Instance</code> identifying one instance of
    * a module.
    *
    * @return A <code>PP_Resource</code> corresponding to a TCP socket or 0
    * on failure.
    */
   PP_Resource Create([in] PP_Instance instance);
 
   /**
+   * Creates a TCP socket resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   * @param[in] faimly The address family type for the socket.

[bbudge, 2013/09/17 19:42:18]

s/faimly/family

[yzshen1, 2013/09/18 16:56:26]

Done.

+   * @return A <code>PP_Resource</code> corresponding to a TCP socket or 0
+   * on failure.
+   */
+  [version=1.1]
+  PP_Resource Create([in] PP_Instance instance,
+                     [in] PP_NetAddress_Family family);

[yzshen1, 2013/09/17 18:30:58]

This is needed to create the underlying OS socket.
We cannot deduce it from the address passed into Bind() or Connect(), because
PP_TCPSOCKET_OPTION_ADDRESS_REUSE needs to be set before Bind().

[bbudge, 2013/09/17 19:42:18]

Is there any way that address family could be specified by SetOption?

[noelallen1, 2013/09/18 04:08:51]

tcp::Create(inst, family) = socket(family, SOCK_STREAM, 0)
So specifying the family at create makes sense from the POSIX side, where as
SetOption for picking family seams strange IMO.

[yzshen1, 2013/09/18 16:56:26]

I agree with Noel here. It seems natural to have family in Create() because that
is a parameter needed for creating OS socket.
What do you think?

[bbudge, 2013/09/18 17:46:35]

I was looking at the API without considering implementation. I see that Create
needs family and version when creating the platform socket, so I guess we have
to add the new Create function.

Just looking at the API, the family seems like just another option and it would
be cleaner to add options than to add new Create functions. I'm assuming
SetOption must be called after Create but before anything else. Some comments to
this effect are needed, I think.

Would it be difficult to defer creation of the socket until necessary, say in
Bind? The downside of this is that it postpones any error in creating the OS
socket but how likely is that?

[yzshen1, 2013/09/18 18:06:56]

IMO, it seems unusual to most POSIX develop to consider family as an option.
We will need to have an extra step for every socket creation:

...
Create();
SetOption(FAMILY, IPv4);
Bind()/Connect();
...
We will need to create socket at three different places:
- SetOption() for ADDRESS_REUSE (unless we want to cache it).
- Bind().
- Connect() (because Connect() can be called without Bind().

It complicates the logic IMO.

+
+  /**
    * Determines if a given resource is a TCP socket.
    *
    * @param[in] resource A <code>PP_Resource</code> to check.
    *
    * @return <code>PP_TRUE</code> if the input is a
    * <code>PPB_TCPSocket</code> resource; <code>PP_FALSE</code> otherwise.
    */
   PP_Bool IsTCPSocket([in] PP_Resource resource);
 
   /**
-   * Connects the socket to the given address.
+   * Binds the socket to the given address. The socket must not be bound.
    *
    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
    * socket.
+   * @param[in] addr A <code>PPB_NetAddress</code> resource.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>,
+   * including (but not limited to):
+   * - <code>PP_ERROR_ADDRESS_IN_USE</code>: the address is already in use.
+   * - <code>PP_ERROR_ADDRESS_INVALID</code>: the address is invalid.
+   */
+  [version=1.1]
+  int32_t Bind([in] PP_Resource tcp_socket,
+               [in] PP_Resource addr,
+               [in] PP_CompletionCallback callback);
+
+  /**
+   * Connects the socket to the given address. The socket must not be listening.
+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
    * @param[in] addr A <code>PPB_NetAddress</code> resource.
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
    * completion.
    *
    * @return An int32_t containing an error code from <code>pp_errors.h</code>,
    * including (but not limited to):
    * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
    *   permissions.
    * - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is
    *   unreachable.
    * - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was
    *   refused.
    * - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed.
    * - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed
    *   out.
+   *
+   * If the socket is listening/connected or has a pending listen/connect
+   * request, <code>Connect()</code> will fail without starting a connection
+   * attempt. Otherwise, any failure during the connection attempt will cause
+   * the socket to be closed.

[yzshen1, 2013/09/17 18:30:58]

According to POSIX:
"""If connect() fails, the state of the socket is unspecified. Conforming
applications should close the file descriptor and create a new socket before
attempting to reconnect."""

In v1.0, we always create a new OS socket when Connect() is called. So it is
okay to allow multiple connection attempts.

In v1.1, however, we cannot easily create a new OS socket for the second
connection attempt. Because Bind() and SetOption() may have been called,
creating a new OS socket will lose the bound address or some options that have
been set.

Therefore, I changed the behavior of v1.1 to close the socket if a connection
attempt failed. I also made sure that the behavior of v1.0 doesn't change after
this CL.

What do you think?

[bbudge, 2013/09/17 19:42:18]

This seems OK to me. We can add this capability later on if we want (by saving
the address and options that have been set).

    */
   int32_t Connect([in] PP_Resource tcp_socket,
                   [in] PP_Resource addr,
                   [in] PP_CompletionCallback callback);
 
   /**
-   * Gets the local address of the socket, if it is connected.
+   * Gets the local address of the socket, if it is bound.
    *
    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
    * socket.
    *
    * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure.
    */
   PP_Resource GetLocalAddress([in] PP_Resource tcp_socket);
 
   /**
    * Gets the remote address of the socket, if it is connected.
@@ skipping 37 matching lines @@
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
    * completion.
    *
    * @return A non-negative number on success to indicate how many bytes have
    * been written; otherwise, an error code from <code>pp_errors.h</code>.
    */
   int32_t Write([in] PP_Resource tcp_socket,
                 [in] str_t buffer,
                 [in] int32_t bytes_to_write,
                 [in] PP_CompletionCallback callback);
+  /**
+   * Starts listening. The socket must be bound and not connected.
+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
+   * @param[in] backlog A hint to determine the maximum length to which the
+   * queue of pending connections may grow.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>,
+   * including (but not limited to):
+   * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
+   *   permissions.
+   * - <code>PP_ERROR_ADDRESS_IN_USE</code>: Another socket is already listening
+   *   on the same port.
+   */
+  [version=1.1]
+  int32_t Listen([in] PP_Resource tcp_socket,
+                 [in] int32_t backlog,
+                 [in] PP_CompletionCallback callback);
 
   /**
-   * Cancels all pending reads and writes and disconnects the socket. Any
-   * pending callbacks will still run, reporting <code>PP_ERROR_ABORTED</code>
-   * if pending IO was interrupted. After a call to this method, no output
-   * buffer pointers passed into previous <code>Read()</code> calls will be
-   * accessed. It is not valid to call <code>Connect()</code> again.
+   * Accepts a connection. The socket must be listening.
+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
+   * @param[out] accepted_tcp_socket Stores the accepted TCP socket on success.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>,
+   * including (but not limited to):
+   * - <code>PP_ERROR_CONNECTION_ABORTED</code>: A connection has been aborted.
+   */
+  [version=1.1]
+  int32_t Accept([in] PP_Resource tcp_socket,
+                 [out] PP_Resource accepted_tcp_socket,
+                 [in] PP_CompletionCallback callback);
+
+  /**
+   * Cancels all pending operations and closes the socket. Any pending callbacks
+   * will still run, reporting <code>PP_ERROR_ABORTED</code> if pending IO was
+   * interrupted. After a call to this method, no output buffer pointers passed
+   * into previous <code>Read()</code> or <code>Accept()</code> calls will be
+   * accessed. It is not valid to call <code>Connect()</code> or
+   * <code>Listen()</code> again.
    *
    * The socket is implicitly closed if it is destroyed, so you are not required
    * to call this method.
    *
    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
    * socket.
    */
   void Close([in] PP_Resource tcp_socket);
 
   /**
    * Sets a socket option on the TCP socket.
    * Please see the <code>PP_TCPSocket_Option</code> description for option
    * names, value types and allowed values.
    *
    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
    * socket.
    * @param[in] name The option to set.
    * @param[in] value The option value to set.
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
    * completion.
    *
    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
    */
   int32_t SetOption([in] PP_Resource tcp_socket,
                     [in] PP_TCPSocket_Option name,
                     [in] PP_Var value,
                     [in] PP_CompletionCallback callback);
 };