aboutsummaryrefslogtreecommitdiffstats
path: root/guide
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 /guide
parent09914c4693562bfde644b73a2ed5e6bac7362b4c (diff)
downloadcowboy-f59ee550ad9c8b8a57453d35cb6ad44ec03b5f1d.tar.gz
cowboy-f59ee550ad9c8b8a57453d35cb6ad44ec03b5f1d.tar.bz2
cowboy-f59ee550ad9c8b8a57453d35cb6ad44ec03b5f1d.zip
Add Introduction chapter to the guide
Diffstat (limited to 'guide')
-rw-r--r--guide/introduction.md114
-rw-r--r--guide/toc.md47
2 files changed, 161 insertions, 0 deletions
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