aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2012-10-15 14:35:52 +0200
committerLoïc Hoguin <[email protected]>2012-10-15 14:35:52 +0200
commitf59ee550ad9c8b8a57453d35cb6ad44ec03b5f1d (patch)
treecd263e5b4a7c8addaebeb07981b40a66f2d5e462
parent09914c4693562bfde644b73a2ed5e6bac7362b4c (diff)
downloadcowboy-f59ee550ad9c8b8a57453d35cb6ad44ec03b5f1d.tar.gz
cowboy-f59ee550ad9c8b8a57453d35cb6ad44ec03b5f1d.tar.bz2
cowboy-f59ee550ad9c8b8a57453d35cb6ad44ec03b5f1d.zip
Add Introduction chapter to the guide
-rw-r--r--README.md43
-rw-r--r--guide/introduction.md114
-rw-r--r--guide/toc.md47
3 files changed, 185 insertions, 19 deletions
diff --git a/README.md b/README.md
index e6556be..418ed57 100644
--- a/README.md
+++ b/README.md
@@ -6,35 +6,40 @@ Cowboy is a small, fast and modular HTTP server written in Erlang.
Goals
-----
-Cowboy aims to provide the following advantages:
-
-* **Small** code base.
-* Damn **fast**.
-* **Modular**: transport and protocol handlers are replaceable.
-* **Binary HTTP** for greater speed and lower memory usage.
-* Easy to **embed** inside another application.
-* Selectively **dispatch** requests to handlers, allowing you to send some
- requests to your embedded code and others to a FastCGI application in
- PHP or Ruby.
-* No parameterized module. No process dictionary. **Clean** Erlang code.
-
-The server 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.
+Cowboy aims to provide a **complete** HTTP stack in a **small** code base.
+It is optimized for **low latency** and **low memory usage**, in parts
+because it uses **binary strings**.
+
+Cowboy provides **routing** capabilities, selectively dispatching requests
+to handlers written in Erlang.
+
+Because it uses Ranch for managing connections, Cowboy can easily be
+**embedded** in any other application.
+
+No parameterized module. No process dictionary. **Clean** Erlang code.
Quick start
-----------
-* Add Cowboy as a rebar or agner dependency to your application.
+* Add Cowboy as a rebar dependency to your application.
* Start Cowboy and add one or more listeners.
* Write handlers for your application.
-* Check out the `examples/` directory!
Getting Started
---------------
+* [Read the guide](https://github.com/extend/cowboy/blob/master/guide/toc.md)
+* Look at the examples in the ```examples/``` directory
+* Build API documentation with ```make docs```; open ```doc/index.html```
+
+
+
+Old README
+----------
+
+This and all following sections will be removed as soon as their
+equivalent appear in the Cowboy guide.
+
Cowboy does nothing by default.
Cowboy uses Ranch for handling connections, and provides convenience
diff --git a/guide/introduction.md b/guide/introduction.md
new file mode 100644
index 0000000..871e243
--- /dev/null
+++ b/guide/introduction.md
@@ -0,0 +1,114 @@
+Introduction
+============
+
+Purpose
+-------
+
+Cowboy is a small, fast and modular HTTP server written in Erlang.
+
+Cowboy aims to provide a complete HTTP stack, including its derivatives
+SPDY, Websocket and REST. Cowboy currently supports HTTP/1.0, HTTP/1.1,
+Websocket (all implemented drafts + standard) and Webmachine-based REST.
+
+Cowboy is a high quality project. It has a small code base, is very
+efficient (both in latency and memory use) and can easily be embedded
+in another application.
+
+Cowboy is clean Erlang code. It bans the use of parameterized modules
+and the process dictionary. It includes documentation and typespecs
+for all public interfaces.
+
+Prerequisites
+-------------
+
+It is assumed the developer already knows Erlang and has basic knowledge
+about the HTTP protocol.
+
+In order to run the examples available in this user guide, you will need
+Erlang and rebar installed and in your $PATH.
+
+Please see the [rebar repository](https://github.com/basho/rebar) for
+downloading and building instructions. Please look up the environment
+variables documentation of your system for details on how to update the
+$PATH information.
+
+Conventions
+-----------
+
+In the HTTP protocol, the method name is case sensitive. All standard
+method names are uppercase.
+
+Header names are case insensitive. Cowboy converts all the request
+header names to lowercase, and expects your application to provide
+lowercase header names in the response.
+
+Getting started
+---------------
+
+Cowboy does nothing by default.
+
+Cowboy requires the `crypto` and `ranch` applications to be started.
+
+``` erlang
+ok = application:start(crypto).
+ok = application:start(ranch).
+ok = application:start(cowboy).
+```
+
+Cowboy uses Ranch for handling the connections and provides convenience
+functions to start Ranch listeners.
+
+The `cowboy:start_http/4` function starts a listener for HTTP connections
+using the TCP transport. The `cowboy:start_https/4` function starts a
+listener for HTTPS connections using the SSL transport.
+
+Listeners are named. They spawn a given number of acceptors, listen for
+connections using the given transport options and pass along the protocol
+options to the connection processes. The protocol options must include
+the dispatch list for routing requests to handlers.
+
+The dispatch list is explained in greater details in the Routing section
+of the guide.
+
+``` erlang
+Dispatch = [
+ %% {URIHost, list({URIPath, Handler, Opts})}
+ {'_', [{'_', my_handler, []}]}
+],
+%% Name, NbAcceptors, TransOpts, ProtoOpts
+cowboy:start_http(my_http_listener, 100,
+ [{port, 8080}],
+ [{dispatch, Dispatch}]
+).
+```
+
+Cowboy features many kinds of handlers. It has plain HTTP handlers, loop
+handlers, Websocket handlers, REST handlers and static handlers. Their
+usage is documented in the respective sections of the guide.
+
+Most applications use the plain HTTP handler, which has three callback
+functions: init/3, handle/2 and terminate/2. Following is an example of
+a simple handler module.
+
+``` erlang
+-module(my_handler).
+-behaviour(cowboy_http_handler).
+
+-export([init/3]).
+-export([handle/2]).
+-export([terminate/2]).
+
+init({tcp, http}, Req, Opts) ->
+ {ok, Req, undefined_state}.
+
+handle(Req, State) ->
+ {ok, Req2} = cowboy_req:reply(200, [], <<"Hello World!">>, Req),
+ {ok, Req2, State}.
+
+terminate(Req, State) ->
+ ok.
+```
+
+The `Req` variable above is the Req object, which allows the developer
+to obtain informations about the request and to perform a reply. Its usage
+is explained in its respective section of the guide.
diff --git a/guide/toc.md b/guide/toc.md
new file mode 100644
index 0000000..ea543d1
--- /dev/null
+++ b/guide/toc.md
@@ -0,0 +1,47 @@
+Cowboy User Guide
+=================
+
+ * [Introduction](introduction.md)
+ * Purpose
+ * Prerequisites
+ * Conventions
+ * Getting started
+ * Routing
+ * Purpose
+ * Dispatch rule
+ * Match rules
+ * Bindings
+ * Handlers
+ * Purpose
+ * Protocol upgrades
+ * HTTP handlers
+ * Purpose
+ * Callbacks
+ * Usage
+ * Loop handlers
+ * Purpose
+ * Callbacks
+ * Usage
+ * Websocket handlers
+ * Purpose
+ * Callbacks
+ * Usage
+ * REST handlers
+ * Purpose
+ * Flow diagram
+ * Callbacks
+ * Usage
+ * Static handlers
+ * Purpose
+ * Usage
+ * Request object
+ * Purpose
+ * Request
+ * Request body
+ * Reply
+ * Hooks
+ * On request
+ * On response
+ * Internals
+ * Architecture
+ * Efficiency considerations