Import the acceptor code from Cowboy

Modules were renamed. The 'cowboy_' prefix became 'ranch_'.
At the same time, ranch_ssl_transport became ranch_ssl,
and ranch_tcp_transport became ranch_tcp, because appending
'_transport' felt a bit redundant considering SSL and TCP
clearly are transports.

One test has been added to make sure everything is working.

1 files changed, 88 insertions, 2 deletions

diff --git a/README.md b/README.md
index 551c502..2fbe9cd 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,91 @@
 Ranch
 =====
 
-Ranch is a socket acceptor pool, able to accept connections for any kind
-of TCP protocol.
+Ranch is a socket acceptor pool for TCP protocols.
+
+Goals
+-----
+
+Ranch aims to provide everything you need to accept TCP connections with
+a **small** code base and **low latency** while being easy to use directly
+as an application or to **embed** into your own.
+
+Ranch provides a **modular** design, letting you choose which transport
+and protocol are going to be used for a particular listener. Listeners
+accept and manage connections on one port, and include facilities to
+limit the number of **concurrent** connections. Connections are sorted
+into **pools**, each pool having a different configurable limit.
+
+Ranch also allows you to **upgrade** the acceptor pool without having
+to close any of the currently opened sockets.
+
+The project is currently in early development. Comments and suggestions are
+more than welcome. To contribute, either open bug reports, or fork the project
+and send us pull requests with new or improved functionality. You should
+discuss your plans with us before doing any serious work, though, to avoid
+duplicating efforts.
+
+Quick start
+-----------
+
+* Add Ranch as a rebar or agner dependency to your application.
+* Start Ranch and add one or more listeners.
+* Write protocol handlers for your application.
+
+Getting Started
+---------------
+
+Ranch accepts connections received on a given port and using a given
+transport, like TCP or SSL, and forward them to a given protocol
+handler. Acceptors and protocol handler processes are of course
+supervised automatically.
+
+Ranch does nothing by default. You need to explicitly request Ranch
+to listen on a port with your chosen transport and protocol handlers.
+To do so, you must start a listener.
+
+A listener is a special kind of supervisor that manages both the
+acceptor pool and the protocol processes. It is named and can thus be
+started and stopped at will.
+
+An acceptor pool is a pool of processes whose only role is to accept
+new connections. It's good practice to have many of these processes
+as they are very cheap and allow much quicker response when you get
+many connections. Of course, as with everything else, you should
+**benchmark** before you decide what's best for you.
+
+Ranch includes both TCP and SSL transport handlers, abstracted through
+a single common interface.
+
+You can start and stop listeners by calling `ranch:start_listener/6` and
+`ranch:stop_listener/1` respectively.
+
+The following example demonstrates the startup of a very simple listener.
+
+``` erlang
+application:start(ranch),
+%% Name, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts
+ranch:start_listener(my_echo_listener, 100,
+    ranch_tcp, [{port, 1234}],
+    my_echo_protocol, [{log, "echo.log"}]
+).
+```
+
+Writing a protocol handler
+--------------------------
+
+The only exported function a protocol handler needs is the start_link/4
+function, with arguments ListenerPid, Socket, Transport and Opts. ListenerPid
+is the pid to the listener's gen_server, managing the connections. Socket is of
+course the client socket; Transport is the module name of the chosen transport
+handler and Opts is protocol options defined when starting the listener.
+
+After initializing your protocol, it is recommended to call the
+function ranch:accept_ack/1 with the ListenerPid as argument,
+as it will ensure Ranch has been able to fully initialize the socket.
+Anything you do past this point is up to you!
+
+If you need to change some socket options, like enabling raw mode for example,
+you can call the <em>Transport:setopts/2</em> function. It is the protocol's
+responsability to manage the socket usage, there should be no need for an user
+to specify that kind of options while starting a listener.