Add TCP socket mojo interfaces

mojo/services/public/interfaces/network/tcp_socket.mojom

+// Copyright 2014 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.
+
+import "mojo/services/public/interfaces/network/net_address.mojom"
+import "mojo/services/public/interfaces/network/network_error.mojom"
+
+module mojo {
+
+struct TCPSocketInfo {
+  NetAddress local_address;
+  NetAddress remote_address;
+};
+
+// Represents a TCP socket. A socket can represent either a connection to a
+// remote host, or a local server socket waiting for incoming connections.
+//
+// For client connections:
+//  - Connect(), providing a pair of streams to use for data transfer.
+//  - Read and write from the streams as desired.
+//  - Close().
+//
+// For server connections:
+//  - Bind() to allocate a port.
+//  - Listen() to start listening for incoming connections.
+//  - For as long as you want to accept incoming connections:
+//    - Accept() to wait for and initiate a connection once one is available.
+//  - Close().
+interface TCPSocket {
+  // Binds this connection to a local port. The TCPSocket must not be bound,
+  // listening, or connected.
+  //
+  // This function is required to initialize a server socket for using Listen(),
+  // but is optional when using Connect() to initiate a client connection. On
+  // success, bound_to will indicate the local address that was bound.
+  Bind(NetAddress addr) => (NetworkError result, NetAddress? bound_to);
+
+  // Starts listening on this socket for incoming connection requests. The
+  // socket must be bound and not connected.
+  //
+  // The backlog is a hint indicating the number of incoming connections that
+  // can be queued up at one time waiting for Accept(). This queuing will
+  // happen when connections are incoming faster than Accept() can be called.
+  Listen(int32 backlog) => (NetworkError result);
+
+  // Accepts a connection. The socket must be listening.
+  //
+  // This function is called to accept an incoming connection.  The caller
+  // provides the streams that will be used to send and receive data on the
+  // connection.
+  //
+  // On success, the callback will be provided with the new socket that
+  // represents the connection. It will already be in a connected state and the
+  // data streams will be ready to use.
+  Accept(handle<data_pipe_consumer> send_stream,
+         handle<data_pipe_producer> receive_stream) =>
+      (NetworkError result, TCPSocket? socket, TCPSocketInfo? info);
+
+  // Connects the socket to the given address. The socket must not be listening
+  // or previously connected. Binding the socket beforehand is optional.
+  Connect(NetAddress addr,
+          handle<data_pipe_consumer> send_stream,
+          handle<data_pipe_producer> receive_stream) =>
+      (NetworkError result, TCPSocketInfo? info);
+
+  // Closes the connection or stops listening for connections, depending on
+  // whether this socket is in server or client mode. If Close() is not called,
+  // the connection will be implicitly closes when the TCPSocket has been
+  // deleted.
+  Close();
+
+  // Controls whether small writes are coalesced to make TCP segments (Nagle's
+  // algorithm). The default value is true (coalescing enabled).
+  SetCoaleseWrites(bool coalesce);

[Ryan Sleevi, 2014/10/01 03:54:01]

typo: Coalesce 

That said, in further thinking about this API, I think it's somewhat weird when
compared to your data_pipe API.

That is, Nagling is necessary when you're writing discrete chunks, but this
doesn't, you have a direct stream API. As such, the semantics of what it means
to coalesce writes is weird, and I have trouble predicting what will happen one
way or the other.

That is, I don't expect a write to the data pipe to IMMEDIATELY trigger a TCP
write, just by virtue of IPC / mojo semantics. Instead, what I'd (naively)
expect to happen is that internally the stream is going to buffer until an event
loop begins processing messages and then send.

Maybe I'm over-thinking, as I can see lots of ways of implementing the data
pipes, each with different semantics. For example, you might IPC a message over
each time someone writes to the send_stream (like our current Pepper sockets).
Or you might write into a shared memory buffer, appending data to the pending
list (like the kernel's underlying socket implementation). In both of these
cases, saying nagling at the transport layer ignores the latencies involved in
the IPC layer that nagling is meant to address.

I realize right now I'm relying on the interface-as-the-documentation, and I
guess I don't know what to predict what will happen.

+};
+
+}