From f59ee550ad9c8b8a57453d35cb6ad44ec03b5f1d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 15 Oct 2012 14:35:52 +0200
Subject: Add Introduction chapter to the guide

---
 guide/introduction.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++
 guide/toc.md          |  47 +++++++++++++++++++++
 2 files changed, 161 insertions(+)
 create mode 100644 guide/introduction.md
 create mode 100644 guide/toc.md

(limited to 'guide')

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