[simoncion]

My first attempt at making a simple Cowboy application was less than successful. I found the documentation spotty, inconsistent, and very difficult to understand. After about 45 minutes of really frustrated dicking around, I figured out how to make a simple HTTP server that allowed me to handle simple HTTP requests. I had to write code to switch on the passed-in HTTP verb, but everything worked, more or less. I could serve HTTP requests, but my code crashed after every request. (This was -of course- not fatal, but a bit of a performance killer.) Pipelined requests didn't work due to server connection resets. (Again, not fatal, just perf-diminishing.) I was utterly unable to get cowboy_rest to work.

Several months later, with a lot of additional Erlang experience under my belt, I come back to the documentation, and it's -somehow- 60->70% comprehensible. I figured out what was wrong with my simple HTTP server. (I was calling my request handler in init, rather than returning {ok, Req, []}, and letting Cowboy call my request handler later.) I still can't get cowboy_rest to work, but (OTOH) I haven't spent more than five minutes trying to get it to work since my first attempt way back when.

I don't know how much experience you have with Erlang, so I'll give you some basic advice that might be entirely unhelpful. Feel free to ask additional questions. Also feel free to ask questions on the erlang-questions mailing list. [0] Everyone who regularly posts there is very helpful. Many (most?) of them use Erlang professionally.

Anyway. Advice:

Projects/frameworks like OTP and Cowboy provide a callback API that application code is expected to conform to. Cowboy's documentation for this API is kind of all over the place, [1] but OTP's is well organized. [2]

Because Erlang tries to eschew global state as much as it can, OTP has a convention that one of the values in the tuple returned from an callback is the state for that particular instance of your application code. This State variable seems to always be the last element in the returned tuple, and the last argument to your callback function. State can be any Erlang term; it only has meaning to your application code. If your callbacks don't care about state, then you can pass anything as state. Many other frameworks have adopted this convention; it's a pretty good one.

Cowboy appears to be a pretty good HTTP/SPDY server. The beginner's documentation needs a LOT of love. (Even now, I had difficulty trying to piece together that walk through the docs in the footnote.) Given that it's a one-man shop, it's surprising that the docs are in as good a shape as they are; documentation isn't easy. :) But, still...

Anyway, questions? Comments? Ask away either here, or on the erlang-questions mailing list. :)

[0] http://erlang.org/mailman/listinfo/erlang-questions

[1] First you have to read the examples shipped with the source code https://github.com/ninenines/cowboy/blob/1.0.x/examples/hell... https://github.com/ninenines/cowboy/blob/1.0.x/examples/hell... to kind of get the impression that you need to use the cowboy_http_handler API (kinda introduced here http://ninenines.eu/docs/en/cowboy/1.0/guide/http_handlers/ and documented here http://ninenines.eu/docs/en/cowboy/1.0/manual/cowboy_http_ha... ) in order to handle plain HTTP requests. If there's a better way to arrive at this conclusion, I overlooked it. :(

[2] For example, the docs for OTP's application API: http://www.erlang.org/doc/man/application.html or the gen_server API: http://www.erlang.org/doc/man/gen_server.html The parts before the "CALLBACK FUNCTIONS" section are functions you use to manipulate an application or gen_server. The bits after are functions you implement in your module that the application or gen_server machinery will call.

[swhipple]

Just curious, was erlang.mk around and did you use the bootstrapped release / cowboy_http template [1] when creating your first application? Based on some things you mention, it makes it sound like you were writing from scratch while referencing the docs. :-)

I also got started from the cowboy user guide (with prior Erlang experience), but found it relatively easier, as I used the template, then cross-referenced the idiomatic template with the docs as I worked through them (tweaking 'knobs' as I went along), which worked well in helping me understand the design.

Along with the Erlang mailing list you've mentioned, I would also like to mention #ninenines (and #erlang for more general questions) on freenode. Very helpful communities!

[1] This page describes the setup: http://ninenines.eu/docs/en/cowboy/HEAD/guide/getting_starte...

[simoncion]

I was using Cowboy 1.x with my project.

erlang.mk was around. My two gripes with it:

* It enforces warnings-as-errors. This is a personal preference, but I hate this while developing. I want to iterate, not have to clean up unused variables that I already know about.

* It -until very recently- failed so, so, so hard when run with parallel make. I -at first- idly wondered if -somehow- Cowboy application builds were just non-deterministic. I then remembered that I aliased 'make' to 'make -j3'. Building with 'make -j1' fixed the build and put me squarely in the Rebar camp.

Rebar is just a far better fit for how I work.

> ...did you use the cowboy_http / bootstrapped release template...

Nah.

When learning new things, if I'm not in a rush, I tend -at first- to avoid templates. I've been burned by boilerplate code in the past, and have had boilerplate code cover up the true crawling horror that was more than a couple of APIs.

I'd rather initially do things "from scratch" [0] so that I can better evaluate the thing I'm learning, and the quality of its supporting documentation, or -if the documentation is inadequate- the explanatory power of its test suite and other sample code.

I did -however- read Cowboy's Getting Started guide, along with a huge chunk of the documentation. I actually started with the API documentation, figuring that it was going to be like erlang.org's documentation. Whoops! [1]

[0] And by that, I don't mean "from first principles". I'm quite happy to read an example, partially or fully digest it, then paste it into my text editor.

[1] Again, I know how good erlang.org's documentation is and how very much work it is to make such high-quality documentation. I don't mean to slight Loïc Hoguin. :)