From f59ee550ad9c8b8a57453d35cb6ad44ec03b5f1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 15 Oct 2012 14:35:52 +0200 Subject: Add Introduction chapter to the guide --- README.md | 43 ++++++++++--------- guide/introduction.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++ guide/toc.md | 47 +++++++++++++++++++++ 3 files changed, 185 insertions(+), 19 deletions(-) create mode 100644 guide/introduction.md create mode 100644 guide/toc.md 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 -- cgit v1.2.3