PPB_TCPSocket: add support for TCP server socket operations.

ppapi/api/ppb_tcp_socket.idl

Index: ppapi/api/ppb_tcp_socket.idl
diff --git a/ppapi/api/ppb_tcp_socket.idl b/ppapi/api/ppb_tcp_socket.idl
index 833879c67e1eb5a354a79e2d3fed041299c8b540..2cc9f39fdd1d72b9b932b849782204e87c5cb85a 100644
--- a/ppapi/api/ppb_tcp_socket.idl
+++ b/ppapi/api/ppb_tcp_socket.idl
@@ -7,10 +7,9 @@
  * This file defines the <code>PPB_TCPSocket</code> interface.
  */
 
-[generate_thunk]
-
 label Chrome {
-  M29 = 1.0
+  M29 = 1.0,
+  M31 = 1.1
 };
 
 /**
@@ -45,14 +44,23 @@ enum PP_TCPSocket_Option {
    * 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
  */
@@ -69,6 +77,19 @@ interface PPB_TCPSocket {
   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.
@@ -79,7 +100,26 @@ interface PPB_TCPSocket {
   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.
@@ -98,13 +138,18 @@ interface PPB_TCPSocket {
    * - <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.
@@ -162,13 +207,53 @@ interface PPB_TCPSocket {
                 [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);
+
+  /**
+   * 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 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.
+   * 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.