From fe3492a98de29942477b061cd02c92246f4bf85a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 28 Mar 2016 15:36:42 +0200 Subject: Initial commit, new website system --- docs/db.json | 1 + docs/en/cowboy/1.0/guide/architecture/index.html | 202 ++ docs/en/cowboy/1.0/guide/broken_clients/index.html | 212 ++ docs/en/cowboy/1.0/guide/cookies/index.html | 273 ++ .../cowboy/1.0/guide/erlang_beginners/index.html | 196 ++ docs/en/cowboy/1.0/guide/erlang_web/index.html | 248 ++ .../en/cowboy/1.0/guide/getting_started/index.html | 299 ++ docs/en/cowboy/1.0/guide/hooks/index.html | 239 ++ docs/en/cowboy/1.0/guide/http_handlers/index.html | 279 ++ docs/en/cowboy/1.0/guide/http_req_life/index.html | 251 ++ docs/en/cowboy/1.0/guide/http_req_resp.png | Bin 0 -> 33228 bytes docs/en/cowboy/1.0/guide/http_req_resp.svg | 558 ++++ docs/en/cowboy/1.0/guide/index.html | 250 ++ docs/en/cowboy/1.0/guide/introduction/index.html | 212 ++ docs/en/cowboy/1.0/guide/loop_handlers/index.html | 264 ++ docs/en/cowboy/1.0/guide/middlewares/index.html | 226 ++ docs/en/cowboy/1.0/guide/modern_web/index.html | 282 ++ .../en/cowboy/1.0/guide/multipart_intro/index.html | 198 ++ docs/en/cowboy/1.0/guide/multipart_req/index.html | 261 ++ docs/en/cowboy/1.0/guide/req/index.html | 390 +++ docs/en/cowboy/1.0/guide/req_body/index.html | 296 ++ .../en/cowboy/1.0/guide/resource_design/index.html | 294 ++ docs/en/cowboy/1.0/guide/resp/index.html | 327 +++ docs/en/cowboy/1.0/guide/rest_cond.png | Bin 0 -> 111628 bytes docs/en/cowboy/1.0/guide/rest_cond.svg | 1656 ++++++++++++ docs/en/cowboy/1.0/guide/rest_conneg.png | Bin 0 -> 78133 bytes docs/en/cowboy/1.0/guide/rest_conneg.svg | 1135 ++++++++ docs/en/cowboy/1.0/guide/rest_delete.png | Bin 0 -> 122185 bytes docs/en/cowboy/1.0/guide/rest_delete.svg | 1718 ++++++++++++ .../en/cowboy/1.0/guide/rest_flowcharts/index.html | 304 +++ docs/en/cowboy/1.0/guide/rest_get_head.png | Bin 0 -> 99942 bytes docs/en/cowboy/1.0/guide/rest_get_head.svg | 1523 +++++++++++ docs/en/cowboy/1.0/guide/rest_handlers/index.html | 289 ++ docs/en/cowboy/1.0/guide/rest_options.png | Bin 0 -> 8539 bytes docs/en/cowboy/1.0/guide/rest_options.svg | 387 +++ .../en/cowboy/1.0/guide/rest_principles/index.html | 238 ++ docs/en/cowboy/1.0/guide/rest_put_post_patch.png | Bin 0 -> 218656 bytes docs/en/cowboy/1.0/guide/rest_put_post_patch.svg | 2856 ++++++++++++++++++++ docs/en/cowboy/1.0/guide/rest_start.png | Bin 0 -> 118210 bytes docs/en/cowboy/1.0/guide/rest_start.svg | 1468 ++++++++++ docs/en/cowboy/1.0/guide/routing/index.html | 365 +++ .../en/cowboy/1.0/guide/static_handlers/index.html | 280 ++ .../cowboy/1.0/guide/upgrade_protocol/index.html | 200 ++ docs/en/cowboy/1.0/guide/ws_handlers/index.html | 327 +++ docs/en/cowboy/1.0/guide/ws_protocol/index.html | 194 ++ docs/en/cowboy/1.0/index.html | 1 + docs/en/cowboy/1.0/manual/cowboy/index.html | 273 ++ docs/en/cowboy/1.0/manual/cowboy_app/index.html | 188 ++ .../en/cowboy/1.0/manual/cowboy_handler/index.html | 199 ++ .../1.0/manual/cowboy_http_handler/index.html | 229 ++ .../1.0/manual/cowboy_loop_handler/index.html | 245 ++ .../cowboy/1.0/manual/cowboy_middleware/index.html | 213 ++ .../cowboy/1.0/manual/cowboy_protocol/index.html | 244 ++ docs/en/cowboy/1.0/manual/cowboy_req/index.html | 854 ++++++ docs/en/cowboy/1.0/manual/cowboy_rest/index.html | 698 +++++ docs/en/cowboy/1.0/manual/cowboy_router/index.html | 247 ++ docs/en/cowboy/1.0/manual/cowboy_spdy/index.html | 212 ++ docs/en/cowboy/1.0/manual/cowboy_static/index.html | 194 ++ .../1.0/manual/cowboy_sub_protocol/index.html | 203 ++ .../cowboy/1.0/manual/cowboy_websocket/index.html | 208 ++ .../1.0/manual/cowboy_websocket_handler/index.html | 273 ++ .../cowboy/1.0/manual/http_status_codes/index.html | 305 +++ docs/en/cowboy/1.0/manual/index.html | 197 ++ docs/en/cowboy/2.0/guide/architecture.asciidoc | 48 + docs/en/cowboy/2.0/guide/architecture/index.html | 191 ++ docs/en/cowboy/2.0/guide/broken_clients.asciidoc | 61 + docs/en/cowboy/2.0/guide/broken_clients/index.html | 205 ++ docs/en/cowboy/2.0/guide/constraints.asciidoc | 54 + docs/en/cowboy/2.0/guide/constraints/index.html | 211 ++ docs/en/cowboy/2.0/guide/cookies.asciidoc | 163 ++ docs/en/cowboy/2.0/guide/cookies/index.html | 303 +++ docs/en/cowboy/2.0/guide/erlang_beginners.asciidoc | 36 + .../cowboy/2.0/guide/erlang_beginners/index.html | 175 ++ docs/en/cowboy/2.0/guide/erlang_web.asciidoc | 176 ++ docs/en/cowboy/2.0/guide/erlang_web/index.html | 300 ++ docs/en/cowboy/2.0/guide/getting_started.asciidoc | 141 + .../en/cowboy/2.0/guide/getting_started/index.html | 289 ++ docs/en/cowboy/2.0/guide/handlers.asciidoc | 105 + docs/en/cowboy/2.0/guide/handlers/index.html | 242 ++ docs/en/cowboy/2.0/guide/hooks.asciidoc | 46 + docs/en/cowboy/2.0/guide/hooks/index.html | 185 ++ docs/en/cowboy/2.0/guide/http_req_resp.png | Bin 0 -> 28370 bytes docs/en/cowboy/2.0/guide/http_req_resp.svg | 520 ++++ docs/en/cowboy/2.0/guide/index.html | 326 +++ docs/en/cowboy/2.0/guide/introduction.asciidoc | 56 + docs/en/cowboy/2.0/guide/introduction/index.html | 193 ++ docs/en/cowboy/2.0/guide/loop_handlers.asciidoc | 146 + docs/en/cowboy/2.0/guide/loop_handlers/index.html | 284 ++ docs/en/cowboy/2.0/guide/middlewares.asciidoc | 69 + docs/en/cowboy/2.0/guide/middlewares/index.html | 228 ++ docs/en/cowboy/2.0/guide/modern_web.asciidoc | 200 ++ docs/en/cowboy/2.0/guide/modern_web/index.html | 329 +++ docs/en/cowboy/2.0/guide/multipart.asciidoc | 169 ++ docs/en/cowboy/2.0/guide/multipart/index.html | 305 +++ docs/en/cowboy/2.0/guide/overview.asciidoc | 150 + docs/en/cowboy/2.0/guide/overview/index.html | 285 ++ docs/en/cowboy/2.0/guide/req.asciidoc | 247 ++ docs/en/cowboy/2.0/guide/req/index.html | 443 +++ docs/en/cowboy/2.0/guide/req_body.asciidoc | 152 ++ docs/en/cowboy/2.0/guide/req_body/index.html | 312 +++ docs/en/cowboy/2.0/guide/resource_design.asciidoc | 221 ++ .../en/cowboy/2.0/guide/resource_design/index.html | 350 +++ docs/en/cowboy/2.0/guide/resp.asciidoc | 201 ++ docs/en/cowboy/2.0/guide/resp/index.html | 357 +++ docs/en/cowboy/2.0/guide/rest_cond.png | Bin 0 -> 111628 bytes docs/en/cowboy/2.0/guide/rest_cond.svg | 1656 ++++++++++++ docs/en/cowboy/2.0/guide/rest_conneg.png | Bin 0 -> 78133 bytes docs/en/cowboy/2.0/guide/rest_conneg.svg | 1135 ++++++++ docs/en/cowboy/2.0/guide/rest_delete.png | Bin 0 -> 122185 bytes docs/en/cowboy/2.0/guide/rest_delete.svg | 1718 ++++++++++++ docs/en/cowboy/2.0/guide/rest_flowcharts.asciidoc | 248 ++ .../en/cowboy/2.0/guide/rest_flowcharts/index.html | 380 +++ docs/en/cowboy/2.0/guide/rest_get_head.png | Bin 0 -> 99942 bytes docs/en/cowboy/2.0/guide/rest_get_head.svg | 1523 +++++++++++ docs/en/cowboy/2.0/guide/rest_handlers.asciidoc | 133 + docs/en/cowboy/2.0/guide/rest_handlers/index.html | 231 ++ docs/en/cowboy/2.0/guide/rest_options.png | Bin 0 -> 8539 bytes docs/en/cowboy/2.0/guide/rest_options.svg | 387 +++ docs/en/cowboy/2.0/guide/rest_principles.asciidoc | 160 ++ .../en/cowboy/2.0/guide/rest_principles/index.html | 289 ++ docs/en/cowboy/2.0/guide/rest_put_post_patch.png | Bin 0 -> 218656 bytes docs/en/cowboy/2.0/guide/rest_put_post_patch.svg | 2856 ++++++++++++++++++++ docs/en/cowboy/2.0/guide/rest_start.png | Bin 0 -> 105640 bytes docs/en/cowboy/2.0/guide/rest_start.svg | 1356 ++++++++++ docs/en/cowboy/2.0/guide/routing.asciidoc | 224 ++ docs/en/cowboy/2.0/guide/routing/index.html | 397 +++ docs/en/cowboy/2.0/guide/static_files.asciidoc | 171 ++ docs/en/cowboy/2.0/guide/static_files/index.html | 316 +++ docs/en/cowboy/2.0/guide/sub_protocols.asciidoc | 68 + docs/en/cowboy/2.0/guide/sub_protocols/index.html | 206 ++ docs/en/cowboy/2.0/guide/ws_handlers.asciidoc | 196 ++ docs/en/cowboy/2.0/guide/ws_handlers/index.html | 339 +++ docs/en/cowboy/2.0/guide/ws_protocol.asciidoc | 43 + docs/en/cowboy/2.0/guide/ws_protocol/index.html | 182 ++ docs/en/cowboy/2.0/index.html | 1 + docs/en/cowboy/2.0/manual/cowboy/index.html | 328 +++ docs/en/cowboy/2.0/manual/cowboy_app/index.html | 171 ++ .../en/cowboy/2.0/manual/cowboy_handler/index.html | 365 +++ docs/en/cowboy/2.0/manual/cowboy_loop/index.html | 289 ++ .../cowboy/2.0/manual/cowboy_middleware/index.html | 230 ++ .../cowboy/2.0/manual/cowboy_protocol/index.html | 279 ++ docs/en/cowboy/2.0/manual/cowboy_req/index.html | 1423 ++++++++++ docs/en/cowboy/2.0/manual/cowboy_rest/index.html | 508 ++++ docs/en/cowboy/2.0/manual/cowboy_router/index.html | 247 ++ docs/en/cowboy/2.0/manual/cowboy_static/index.html | 188 ++ .../2.0/manual/cowboy_sub_protocol/index.html | 224 ++ .../cowboy/2.0/manual/cowboy_websocket/index.html | 352 +++ .../cowboy/2.0/manual/http_status_codes/index.html | 407 +++ docs/en/cowboy/2.0/manual/index.html | 209 ++ docs/en/cowboy/HEAD/guide/index.html | 1 + docs/en/cowboy/HEAD/index.html | 1 + docs/en/cowboy/HEAD/manual/index.html | 1 + docs/en/cowboy/index.html | 1 + docs/en/erlang.mk/1/guide/app.asciidoc | 426 +++ docs/en/erlang.mk/1/guide/app/index.html | 699 +++++ docs/en/erlang.mk/1/guide/asciidoc.asciidoc | 82 + docs/en/erlang.mk/1/guide/asciidoc/index.html | 230 ++ docs/en/erlang.mk/1/guide/ci.asciidoc | 6 + docs/en/erlang.mk/1/guide/ci/index.html | 137 + docs/en/erlang.mk/1/guide/common_test.asciidoc | 91 + docs/en/erlang.mk/1/guide/common_test/index.html | 249 ++ docs/en/erlang.mk/1/guide/compat.asciidoc | 90 + docs/en/erlang.mk/1/guide/compat/index.html | 220 ++ docs/en/erlang.mk/1/guide/contributing.asciidoc | 116 + docs/en/erlang.mk/1/guide/contributing/index.html | 261 ++ docs/en/erlang.mk/1/guide/coverage.asciidoc | 6 + docs/en/erlang.mk/1/guide/coverage/index.html | 137 + docs/en/erlang.mk/1/guide/deps.asciidoc | 472 ++++ docs/en/erlang.mk/1/guide/deps/index.html | 768 ++++++ docs/en/erlang.mk/1/guide/dialyzer.asciidoc | 73 + docs/en/erlang.mk/1/guide/dialyzer/index.html | 207 ++ docs/en/erlang.mk/1/guide/edoc.asciidoc | 48 + docs/en/erlang.mk/1/guide/edoc/index.html | 193 ++ docs/en/erlang.mk/1/guide/escripts.asciidoc | 6 + docs/en/erlang.mk/1/guide/escripts/index.html | 137 + docs/en/erlang.mk/1/guide/eunit.asciidoc | 122 + docs/en/erlang.mk/1/guide/eunit/index.html | 279 ++ .../en/erlang.mk/1/guide/external_plugins.asciidoc | 77 + .../erlang.mk/1/guide/external_plugins/index.html | 215 ++ .../1/guide/external_plugins_list.asciidoc | 48 + .../1/guide/external_plugins_list/index.html | 197 ++ docs/en/erlang.mk/1/guide/getting_started.asciidoc | 299 ++ .../erlang.mk/1/guide/getting_started/index.html | 462 ++++ docs/en/erlang.mk/1/guide/history.asciidoc | 66 + docs/en/erlang.mk/1/guide/history/index.html | 191 ++ docs/en/erlang.mk/1/guide/index.html | 298 ++ docs/en/erlang.mk/1/guide/installation.asciidoc | 124 + docs/en/erlang.mk/1/guide/installation/index.html | 256 ++ docs/en/erlang.mk/1/guide/limitations.asciidoc | 46 + docs/en/erlang.mk/1/guide/limitations/index.html | 179 ++ docs/en/erlang.mk/1/guide/overview.asciidoc | 87 + docs/en/erlang.mk/1/guide/overview/index.html | 224 ++ docs/en/erlang.mk/1/guide/ports.asciidoc | 100 + docs/en/erlang.mk/1/guide/ports/index.html | 288 ++ docs/en/erlang.mk/1/guide/releases.asciidoc | 70 + docs/en/erlang.mk/1/guide/releases/index.html | 221 ++ docs/en/erlang.mk/1/guide/shell.asciidoc | 46 + docs/en/erlang.mk/1/guide/shell/index.html | 193 ++ docs/en/erlang.mk/1/guide/updating.asciidoc | 63 + docs/en/erlang.mk/1/guide/updating/index.html | 198 ++ docs/en/erlang.mk/1/guide/why.asciidoc | 81 + docs/en/erlang.mk/1/guide/why/index.html | 216 ++ docs/en/erlang.mk/1/guide/xref.asciidoc | 6 + docs/en/erlang.mk/1/guide/xref/index.html | 137 + docs/en/erlang.mk/1/index.html | 1 + docs/en/erlang.mk/index.html | 1 + docs/en/gun/1.0/guide/connect.asciidoc | 154 ++ docs/en/gun/1.0/guide/connect/index.html | 302 +++ docs/en/gun/1.0/guide/http.asciidoc | 362 +++ docs/en/gun/1.0/guide/http/index.html | 515 ++++ docs/en/gun/1.0/guide/index.html | 172 ++ docs/en/gun/1.0/guide/introduction.asciidoc | 28 + docs/en/gun/1.0/guide/introduction/index.html | 168 ++ docs/en/gun/1.0/guide/protocols.asciidoc | 119 + docs/en/gun/1.0/guide/protocols/index.html | 395 +++ docs/en/gun/1.0/guide/start.asciidoc | 67 + docs/en/gun/1.0/guide/start/index.html | 216 ++ docs/en/gun/1.0/guide/websocket.asciidoc | 112 + docs/en/gun/1.0/guide/websocket/index.html | 259 ++ docs/en/gun/1.0/index.html | 1 + docs/en/gun/1.0/manual/gun/index.html | 1734 ++++++++++++ docs/en/gun/1.0/manual/gun_app/index.html | 168 ++ docs/en/gun/1.0/manual/index.html | 152 ++ docs/en/gun/index.html | 1 + docs/en/index.html | 1 + docs/en/ranch/1.2/guide/embedded.asciidoc | 48 + docs/en/ranch/1.2/guide/embedded/index.html | 182 ++ docs/en/ranch/1.2/guide/index.html | 182 ++ docs/en/ranch/1.2/guide/internals.asciidoc | 94 + docs/en/ranch/1.2/guide/internals/index.html | 227 ++ docs/en/ranch/1.2/guide/introduction.asciidoc | 25 + docs/en/ranch/1.2/guide/introduction/index.html | 166 ++ docs/en/ranch/1.2/guide/listeners.asciidoc | 251 ++ docs/en/ranch/1.2/guide/listeners/index.html | 421 +++ docs/en/ranch/1.2/guide/parsers.asciidoc | 92 + docs/en/ranch/1.2/guide/parsers/index.html | 243 ++ docs/en/ranch/1.2/guide/protocols.asciidoc | 125 + docs/en/ranch/1.2/guide/protocols/index.html | 263 ++ docs/en/ranch/1.2/guide/ssl_auth.asciidoc | 120 + docs/en/ranch/1.2/guide/ssl_auth/index.html | 292 ++ docs/en/ranch/1.2/guide/transports.asciidoc | 169 ++ docs/en/ranch/1.2/guide/transports/index.html | 323 +++ docs/en/ranch/1.2/index.html | 1 + docs/en/ranch/1.2/manual/index.html | 172 ++ docs/en/ranch/1.2/manual/ranch/index.html | 557 ++++ docs/en/ranch/1.2/manual/ranch_app/index.html | 177 ++ docs/en/ranch/1.2/manual/ranch_protocol/index.html | 217 ++ docs/en/ranch/1.2/manual/ranch_ssl/index.html | 483 ++++ docs/en/ranch/1.2/manual/ranch_tcp/index.html | 408 +++ .../en/ranch/1.2/manual/ranch_transport/index.html | 628 +++++ docs/en/ranch/index.html | 1 + docs/index.html | 203 ++ docs/index.xml | 2001 ++++++++++++++ 253 files changed, 74036 insertions(+) create mode 100644 docs/db.json create mode 100644 docs/en/cowboy/1.0/guide/architecture/index.html create mode 100644 docs/en/cowboy/1.0/guide/broken_clients/index.html create mode 100644 docs/en/cowboy/1.0/guide/cookies/index.html create mode 100644 docs/en/cowboy/1.0/guide/erlang_beginners/index.html create mode 100644 docs/en/cowboy/1.0/guide/erlang_web/index.html create mode 100644 docs/en/cowboy/1.0/guide/getting_started/index.html create mode 100644 docs/en/cowboy/1.0/guide/hooks/index.html create mode 100644 docs/en/cowboy/1.0/guide/http_handlers/index.html create mode 100644 docs/en/cowboy/1.0/guide/http_req_life/index.html create mode 100644 docs/en/cowboy/1.0/guide/http_req_resp.png create mode 100644 docs/en/cowboy/1.0/guide/http_req_resp.svg create mode 100644 docs/en/cowboy/1.0/guide/index.html create mode 100644 docs/en/cowboy/1.0/guide/introduction/index.html create mode 100644 docs/en/cowboy/1.0/guide/loop_handlers/index.html create mode 100644 docs/en/cowboy/1.0/guide/middlewares/index.html create mode 100644 docs/en/cowboy/1.0/guide/modern_web/index.html create mode 100644 docs/en/cowboy/1.0/guide/multipart_intro/index.html create mode 100644 docs/en/cowboy/1.0/guide/multipart_req/index.html create mode 100644 docs/en/cowboy/1.0/guide/req/index.html create mode 100644 docs/en/cowboy/1.0/guide/req_body/index.html create mode 100644 docs/en/cowboy/1.0/guide/resource_design/index.html create mode 100644 docs/en/cowboy/1.0/guide/resp/index.html create mode 100644 docs/en/cowboy/1.0/guide/rest_cond.png create mode 100644 docs/en/cowboy/1.0/guide/rest_cond.svg create mode 100644 docs/en/cowboy/1.0/guide/rest_conneg.png create mode 100644 docs/en/cowboy/1.0/guide/rest_conneg.svg create mode 100644 docs/en/cowboy/1.0/guide/rest_delete.png create mode 100644 docs/en/cowboy/1.0/guide/rest_delete.svg create mode 100644 docs/en/cowboy/1.0/guide/rest_flowcharts/index.html create mode 100644 docs/en/cowboy/1.0/guide/rest_get_head.png create mode 100644 docs/en/cowboy/1.0/guide/rest_get_head.svg create mode 100644 docs/en/cowboy/1.0/guide/rest_handlers/index.html create mode 100644 docs/en/cowboy/1.0/guide/rest_options.png create mode 100644 docs/en/cowboy/1.0/guide/rest_options.svg create mode 100644 docs/en/cowboy/1.0/guide/rest_principles/index.html create mode 100644 docs/en/cowboy/1.0/guide/rest_put_post_patch.png create mode 100644 docs/en/cowboy/1.0/guide/rest_put_post_patch.svg create mode 100644 docs/en/cowboy/1.0/guide/rest_start.png create mode 100644 docs/en/cowboy/1.0/guide/rest_start.svg create mode 100644 docs/en/cowboy/1.0/guide/routing/index.html create mode 100644 docs/en/cowboy/1.0/guide/static_handlers/index.html create mode 100644 docs/en/cowboy/1.0/guide/upgrade_protocol/index.html create mode 100644 docs/en/cowboy/1.0/guide/ws_handlers/index.html create mode 100644 docs/en/cowboy/1.0/guide/ws_protocol/index.html create mode 100644 docs/en/cowboy/1.0/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_app/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_handler/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_http_handler/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_loop_handler/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_middleware/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_protocol/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_req/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_rest/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_router/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_spdy/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_static/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_sub_protocol/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_websocket/index.html create mode 100644 docs/en/cowboy/1.0/manual/cowboy_websocket_handler/index.html create mode 100644 docs/en/cowboy/1.0/manual/http_status_codes/index.html create mode 100644 docs/en/cowboy/1.0/manual/index.html create mode 100644 docs/en/cowboy/2.0/guide/architecture.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/architecture/index.html create mode 100644 docs/en/cowboy/2.0/guide/broken_clients.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/broken_clients/index.html create mode 100644 docs/en/cowboy/2.0/guide/constraints.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/constraints/index.html create mode 100644 docs/en/cowboy/2.0/guide/cookies.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/cookies/index.html create mode 100644 docs/en/cowboy/2.0/guide/erlang_beginners.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/erlang_beginners/index.html create mode 100644 docs/en/cowboy/2.0/guide/erlang_web.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/erlang_web/index.html create mode 100644 docs/en/cowboy/2.0/guide/getting_started.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/getting_started/index.html create mode 100644 docs/en/cowboy/2.0/guide/handlers.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/handlers/index.html create mode 100644 docs/en/cowboy/2.0/guide/hooks.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/hooks/index.html create mode 100644 docs/en/cowboy/2.0/guide/http_req_resp.png create mode 100644 docs/en/cowboy/2.0/guide/http_req_resp.svg create mode 100644 docs/en/cowboy/2.0/guide/index.html create mode 100644 docs/en/cowboy/2.0/guide/introduction.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/introduction/index.html create mode 100644 docs/en/cowboy/2.0/guide/loop_handlers.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/loop_handlers/index.html create mode 100644 docs/en/cowboy/2.0/guide/middlewares.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/middlewares/index.html create mode 100644 docs/en/cowboy/2.0/guide/modern_web.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/modern_web/index.html create mode 100644 docs/en/cowboy/2.0/guide/multipart.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/multipart/index.html create mode 100644 docs/en/cowboy/2.0/guide/overview.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/overview/index.html create mode 100644 docs/en/cowboy/2.0/guide/req.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/req/index.html create mode 100644 docs/en/cowboy/2.0/guide/req_body.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/req_body/index.html create mode 100644 docs/en/cowboy/2.0/guide/resource_design.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/resource_design/index.html create mode 100644 docs/en/cowboy/2.0/guide/resp.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/resp/index.html create mode 100644 docs/en/cowboy/2.0/guide/rest_cond.png create mode 100644 docs/en/cowboy/2.0/guide/rest_cond.svg create mode 100644 docs/en/cowboy/2.0/guide/rest_conneg.png create mode 100644 docs/en/cowboy/2.0/guide/rest_conneg.svg create mode 100644 docs/en/cowboy/2.0/guide/rest_delete.png create mode 100644 docs/en/cowboy/2.0/guide/rest_delete.svg create mode 100644 docs/en/cowboy/2.0/guide/rest_flowcharts.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/rest_flowcharts/index.html create mode 100644 docs/en/cowboy/2.0/guide/rest_get_head.png create mode 100644 docs/en/cowboy/2.0/guide/rest_get_head.svg create mode 100644 docs/en/cowboy/2.0/guide/rest_handlers.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/rest_handlers/index.html create mode 100644 docs/en/cowboy/2.0/guide/rest_options.png create mode 100644 docs/en/cowboy/2.0/guide/rest_options.svg create mode 100644 docs/en/cowboy/2.0/guide/rest_principles.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/rest_principles/index.html create mode 100644 docs/en/cowboy/2.0/guide/rest_put_post_patch.png create mode 100644 docs/en/cowboy/2.0/guide/rest_put_post_patch.svg create mode 100644 docs/en/cowboy/2.0/guide/rest_start.png create mode 100644 docs/en/cowboy/2.0/guide/rest_start.svg create mode 100644 docs/en/cowboy/2.0/guide/routing.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/routing/index.html create mode 100644 docs/en/cowboy/2.0/guide/static_files.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/static_files/index.html create mode 100644 docs/en/cowboy/2.0/guide/sub_protocols.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/sub_protocols/index.html create mode 100644 docs/en/cowboy/2.0/guide/ws_handlers.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/ws_handlers/index.html create mode 100644 docs/en/cowboy/2.0/guide/ws_protocol.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/ws_protocol/index.html create mode 100644 docs/en/cowboy/2.0/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_app/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_handler/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_loop/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_middleware/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_protocol/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_rest/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_router/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_static/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_sub_protocol/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_websocket/index.html create mode 100644 docs/en/cowboy/2.0/manual/http_status_codes/index.html create mode 100644 docs/en/cowboy/2.0/manual/index.html create mode 100644 docs/en/cowboy/HEAD/guide/index.html create mode 100644 docs/en/cowboy/HEAD/index.html create mode 100644 docs/en/cowboy/HEAD/manual/index.html create mode 100644 docs/en/cowboy/index.html create mode 100644 docs/en/erlang.mk/1/guide/app.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/app/index.html create mode 100644 docs/en/erlang.mk/1/guide/asciidoc.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/asciidoc/index.html create mode 100644 docs/en/erlang.mk/1/guide/ci.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/ci/index.html create mode 100644 docs/en/erlang.mk/1/guide/common_test.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/common_test/index.html create mode 100644 docs/en/erlang.mk/1/guide/compat.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/compat/index.html create mode 100644 docs/en/erlang.mk/1/guide/contributing.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/contributing/index.html create mode 100644 docs/en/erlang.mk/1/guide/coverage.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/coverage/index.html create mode 100644 docs/en/erlang.mk/1/guide/deps.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/deps/index.html create mode 100644 docs/en/erlang.mk/1/guide/dialyzer.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/dialyzer/index.html create mode 100644 docs/en/erlang.mk/1/guide/edoc.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/edoc/index.html create mode 100644 docs/en/erlang.mk/1/guide/escripts.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/escripts/index.html create mode 100644 docs/en/erlang.mk/1/guide/eunit.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/eunit/index.html create mode 100644 docs/en/erlang.mk/1/guide/external_plugins.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/external_plugins/index.html create mode 100644 docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/external_plugins_list/index.html create mode 100644 docs/en/erlang.mk/1/guide/getting_started.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/getting_started/index.html create mode 100644 docs/en/erlang.mk/1/guide/history.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/history/index.html create mode 100644 docs/en/erlang.mk/1/guide/index.html create mode 100644 docs/en/erlang.mk/1/guide/installation.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/installation/index.html create mode 100644 docs/en/erlang.mk/1/guide/limitations.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/limitations/index.html create mode 100644 docs/en/erlang.mk/1/guide/overview.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/overview/index.html create mode 100644 docs/en/erlang.mk/1/guide/ports.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/ports/index.html create mode 100644 docs/en/erlang.mk/1/guide/releases.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/releases/index.html create mode 100644 docs/en/erlang.mk/1/guide/shell.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/shell/index.html create mode 100644 docs/en/erlang.mk/1/guide/updating.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/updating/index.html create mode 100644 docs/en/erlang.mk/1/guide/why.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/why/index.html create mode 100644 docs/en/erlang.mk/1/guide/xref.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/xref/index.html create mode 100644 docs/en/erlang.mk/1/index.html create mode 100644 docs/en/erlang.mk/index.html create mode 100644 docs/en/gun/1.0/guide/connect.asciidoc create mode 100644 docs/en/gun/1.0/guide/connect/index.html create mode 100644 docs/en/gun/1.0/guide/http.asciidoc create mode 100644 docs/en/gun/1.0/guide/http/index.html create mode 100644 docs/en/gun/1.0/guide/index.html create mode 100644 docs/en/gun/1.0/guide/introduction.asciidoc create mode 100644 docs/en/gun/1.0/guide/introduction/index.html create mode 100644 docs/en/gun/1.0/guide/protocols.asciidoc create mode 100644 docs/en/gun/1.0/guide/protocols/index.html create mode 100644 docs/en/gun/1.0/guide/start.asciidoc create mode 100644 docs/en/gun/1.0/guide/start/index.html create mode 100644 docs/en/gun/1.0/guide/websocket.asciidoc create mode 100644 docs/en/gun/1.0/guide/websocket/index.html create mode 100644 docs/en/gun/1.0/index.html create mode 100644 docs/en/gun/1.0/manual/gun/index.html create mode 100644 docs/en/gun/1.0/manual/gun_app/index.html create mode 100644 docs/en/gun/1.0/manual/index.html create mode 100644 docs/en/gun/index.html create mode 100644 docs/en/index.html create mode 100644 docs/en/ranch/1.2/guide/embedded.asciidoc create mode 100644 docs/en/ranch/1.2/guide/embedded/index.html create mode 100644 docs/en/ranch/1.2/guide/index.html create mode 100644 docs/en/ranch/1.2/guide/internals.asciidoc create mode 100644 docs/en/ranch/1.2/guide/internals/index.html create mode 100644 docs/en/ranch/1.2/guide/introduction.asciidoc create mode 100644 docs/en/ranch/1.2/guide/introduction/index.html create mode 100644 docs/en/ranch/1.2/guide/listeners.asciidoc create mode 100644 docs/en/ranch/1.2/guide/listeners/index.html create mode 100644 docs/en/ranch/1.2/guide/parsers.asciidoc create mode 100644 docs/en/ranch/1.2/guide/parsers/index.html create mode 100644 docs/en/ranch/1.2/guide/protocols.asciidoc create mode 100644 docs/en/ranch/1.2/guide/protocols/index.html create mode 100644 docs/en/ranch/1.2/guide/ssl_auth.asciidoc create mode 100644 docs/en/ranch/1.2/guide/ssl_auth/index.html create mode 100644 docs/en/ranch/1.2/guide/transports.asciidoc create mode 100644 docs/en/ranch/1.2/guide/transports/index.html create mode 100644 docs/en/ranch/1.2/index.html create mode 100644 docs/en/ranch/1.2/manual/index.html create mode 100644 docs/en/ranch/1.2/manual/ranch/index.html create mode 100644 docs/en/ranch/1.2/manual/ranch_app/index.html create mode 100644 docs/en/ranch/1.2/manual/ranch_protocol/index.html create mode 100644 docs/en/ranch/1.2/manual/ranch_ssl/index.html create mode 100644 docs/en/ranch/1.2/manual/ranch_tcp/index.html create mode 100644 docs/en/ranch/1.2/manual/ranch_transport/index.html create mode 100644 docs/en/ranch/index.html create mode 100644 docs/index.html create mode 100644 docs/index.xml (limited to 'docs') diff --git a/docs/db.json b/docs/db.json new file mode 100644 index 00000000..368e78f0 --- /dev/null +++ b/docs/db.json @@ -0,0 +1 @@ +[{"n":"cowboy_static:extra_mimetypes","l":"/docs/en/cowboy/1.0/manual/cowboy_static/index.html#extra_mimetypes"},{"n":"cowboy_static:extra","l":"/docs/en/cowboy/1.0/manual/cowboy_static/index.html#extra"},{"n":"cowboy_static:opts","l":"/docs/en/cowboy/1.0/manual/cowboy_static/index.html#opts"},{"n":"cowboy_static:extra_etag","l":"/docs/en/cowboy/1.0/manual/cowboy_static/index.html#extra_etag"},{"n":"http_status_codes:304 Not Modified","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#304 not modified"},{"n":"http_status_codes:500 Internal Server Error","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#500 internal server error"},{"n":"http_status_codes:201 Created","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#201 created"},{"n":"http_status_codes:413 Request Entity Too Large","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#413 request entity too large"},{"n":"http_status_codes:300 Multiple Choices","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#300 multiple choices"},{"n":"http_status_codes:412 Precondition Failed","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#412 precondition failed"},{"n":"http_status_codes:200 OK","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#200 ok"},{"n":"http_status_codes:101 Switching Protocols","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#101 switching protocols"},{"n":"http_status_codes:501 Not Implemented","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#501 not implemented"},{"n":"http_status_codes:505 HTTP Version Not Supported","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#505 http version not supported"},{"n":"http_status_codes:204 No Content","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#204 no content"},{"n":"http_status_codes:406 Not Acceptable","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#406 not acceptable"},{"n":"http_status_codes:415 Unsupported Media Type","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#415 unsupported media type"},{"n":"http_status_codes:503 Service Unavailable","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#503 service unavailable"},{"n":"http_status_codes:410 Gone","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#410 gone"},{"n":"http_status_codes:400 Bad Request","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#400 bad request"},{"n":"http_status_codes:401 Unauthorized","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#401 unauthorized"},{"n":"http_status_codes:301 Moved Permanently","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#301 moved permanently"},{"n":"http_status_codes:100 Continue","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#100 continue"},{"n":"http_status_codes:414 Request-URI Too Long","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#414 request-uri too long"},{"n":"http_status_codes:307 Temporary Redirect","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#307 temporary redirect"},{"n":"http_status_codes:409 Conflict","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#409 conflict"},{"n":"http_status_codes:202 Accepted","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#202 accepted"},{"n":"http_status_codes:404 Not Found","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#404 not found"},{"n":"http_status_codes:303 See Other","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#303 see other"},{"n":"http_status_codes:405 Method Not Allowed","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#405 method not allowed"},{"n":"http_status_codes:403 Forbidden","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#403 forbidden"},{"n":"http_status_codes:408 Request Timeout","l":"/docs/en/cowboy/1.0/manual/http_status_codes/index.html#408 request timeout"},{"n":"cowboy:http_version","l":"/docs/en/cowboy/1.0/manual/cowboy/index.html#http_version"},{"n":"cowboy:http_status","l":"/docs/en/cowboy/1.0/manual/cowboy/index.html#http_status"},{"n":"cowboy:onrequest_fun","l":"/docs/en/cowboy/1.0/manual/cowboy/index.html#onrequest_fun"},{"n":"cowboy:onresponse_fun","l":"/docs/en/cowboy/1.0/manual/cowboy/index.html#onresponse_fun"},{"n":"cowboy:start_http","l":"/docs/en/cowboy/1.0/manual/cowboy/index.html#start_http"},{"n":"cowboy:http_headers","l":"/docs/en/cowboy/1.0/manual/cowboy/index.html#http_headers"},{"n":"cowboy:start_https","l":"/docs/en/cowboy/1.0/manual/cowboy/index.html#start_https"},{"n":"cowboy:start_spdy","l":"/docs/en/cowboy/1.0/manual/cowboy/index.html#start_spdy"},{"n":"cowboy:stop_listener","l":"/docs/en/cowboy/1.0/manual/cowboy/index.html#stop_listener"},{"n":"cowboy:set_env","l":"/docs/en/cowboy/1.0/manual/cowboy/index.html#set_env"},{"n":"cowboy_http_handler:handle","l":"/docs/en/cowboy/1.0/manual/cowboy_http_handler/index.html#handle"},{"n":"cowboy_http_handler:init","l":"/docs/en/cowboy/1.0/manual/cowboy_http_handler/index.html#init"},{"n":"cowboy_http_handler:terminate","l":"/docs/en/cowboy/1.0/manual/cowboy_http_handler/index.html#terminate"},{"n":"cowboy_loop_handler:info","l":"/docs/en/cowboy/1.0/manual/cowboy_loop_handler/index.html#info"},{"n":"cowboy_loop_handler:init","l":"/docs/en/cowboy/1.0/manual/cowboy_loop_handler/index.html#init"},{"n":"cowboy_loop_handler:terminate","l":"/docs/en/cowboy/1.0/manual/cowboy_loop_handler/index.html#terminate"},{"n":"cowboy_middleware:env","l":"/docs/en/cowboy/1.0/manual/cowboy_middleware/index.html#env"},{"n":"cowboy_middleware:execute","l":"/docs/en/cowboy/1.0/manual/cowboy_middleware/index.html#execute"},{"n":"cowboy_protocol:max_header_name_length ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#max_header_name_length "},{"n":"cowboy_protocol:max_keepalive ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#max_keepalive "},{"n":"cowboy_protocol:max_request_line_length ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#max_request_line_length "},{"n":"cowboy_protocol:middlewares ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#middlewares "},{"n":"cowboy_protocol:onresponse ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#onresponse "},{"n":"cowboy_protocol:timeout ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#timeout "},{"n":"cowboy_protocol:max_header_value_length ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#max_header_value_length "},{"n":"cowboy_protocol:max_headers ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#max_headers "},{"n":"cowboy_protocol:max_empty_lines ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#max_empty_lines "},{"n":"cowboy_protocol:compress ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#compress "},{"n":"cowboy_protocol:onrequest ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#onrequest "},{"n":"cowboy_protocol:env ","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#env "},{"n":"cowboy_protocol:opts","l":"/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html#opts"},{"n":"cowboy_req:has_resp_body","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#has_resp_body"},{"n":"cowboy_req:body_length","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#body_length"},{"n":"cowboy_req:headers","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#headers"},{"n":"cowboy_req:chunk","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#chunk"},{"n":"cowboy_req:parse_header","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#parse_header"},{"n":"cowboy_req:req","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#req"},{"n":"cowboy_req:cookie","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#cookie"},{"n":"cowboy_req:reply","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#reply"},{"n":"cowboy_req:method","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#method"},{"n":"cowboy_req:body_qs","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#body_qs"},{"n":"cowboy_req:set_resp_cookie","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#set_resp_cookie"},{"n":"cowboy_req:set_resp_header","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#set_resp_header"},{"n":"cowboy_req:port","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#port"},{"n":"cowboy_req:peer","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#peer"},{"n":"cowboy_req:part","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#part"},{"n":"cowboy_req:meta","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#meta"},{"n":"cowboy_req:continue","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#continue"},{"n":"cowboy_req:delete_resp_header","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#delete_resp_header"},{"n":"cowboy_req:set_meta","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#set_meta"},{"n":"cowboy_req:chunked_reply","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#chunked_reply"},{"n":"cowboy_req:host","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#host"},{"n":"cowboy_req:host_url","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#host_url"},{"n":"cowboy_req:qs_val","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#qs_val"},{"n":"cowboy_req:body","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#body"},{"n":"cowboy_req:cookies","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#cookies"},{"n":"cowboy_req:host_info","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#host_info"},{"n":"cowboy_req:cookie_opts","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#cookie_opts"},{"n":"cowboy_req:version","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#version"},{"n":"cowboy_req:qs","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#qs"},{"n":"cowboy_req:body_opts","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#body_opts"},{"n":"cowboy_req:bindings","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#bindings"},{"n":"cowboy_req:header","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#header"},{"n":"cowboy_req:binding","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#binding"},{"n":"cowboy_req:path_info","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#path_info"},{"n":"cowboy_req:compact","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#compact"},{"n":"cowboy_req:has_body","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#has_body"},{"n":"cowboy_req:path","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#path"},{"n":"cowboy_req:set_resp_body","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#set_resp_body"},{"n":"cowboy_req:has_resp_header","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#has_resp_header"},{"n":"cowboy_req:url","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#url"},{"n":"cowboy_req:qs_vals","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#qs_vals"},{"n":"cowboy_req:set_resp_body_fun","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#set_resp_body_fun"},{"n":"cowboy_req:part_body","l":"/docs/en/cowboy/1.0/manual/cowboy_req/index.html#part_body"},{"n":"cowboy_rest:valid_content_headers","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#valid_content_headers"},{"n":"cowboy_rest:generate_etag","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#generate_etag"},{"n":"cowboy_rest:forbidden","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#forbidden"},{"n":"cowboy_rest:valid_entity_length","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#valid_entity_length"},{"n":"cowboy_rest:expires","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#expires"},{"n":"cowboy_rest:resource_exists","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#resource_exists"},{"n":"cowboy_rest:last_modified","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#last_modified"},{"n":"cowboy_rest:delete_completed","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#delete_completed"},{"n":"cowboy_rest:is_conflict","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#is_conflict"},{"n":"cowboy_rest:moved_permanently","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#moved_permanently"},{"n":"cowboy_rest:media_type","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#media_type"},{"n":"cowboy_rest:charsets_provided","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#charsets_provided"},{"n":"cowboy_rest:content_types_provided","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#content_types_provided"},{"n":"cowboy_rest:content_types_accepted","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#content_types_accepted"},{"n":"cowboy_rest:previously_existed","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#previously_existed"},{"n":"cowboy_rest:languages_provided","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#languages_provided"},{"n":"cowboy_rest:uri_too_long","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#uri_too_long"},{"n":"cowboy_rest:moved_temporarily","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#moved_temporarily"},{"n":"cowboy_rest:charset","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#charset"},{"n":"cowboy_rest:rest_init","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#rest_init"},{"n":"cowboy_rest:rest_terminate","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#rest_terminate"},{"n":"cowboy_rest:known_content_type","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#known_content_type"},{"n":"cowboy_rest:allow_missing_post","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#allow_missing_post"},{"n":"cowboy_rest:options","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#options"},{"n":"cowboy_rest:multiple_choices","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#multiple_choices"},{"n":"cowboy_rest:language","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#language"},{"n":"cowboy_rest:allowed_methods","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#allowed_methods"},{"n":"cowboy_rest:malformed_request","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#malformed_request"},{"n":"cowboy_rest:known_methods","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#known_methods"},{"n":"cowboy_rest:Callback","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#callback"},{"n":"cowboy_rest:delete_resource","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#delete_resource"},{"n":"cowboy_rest:service_available","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#service_available"},{"n":"cowboy_rest:is_authorized","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#is_authorized"},{"n":"cowboy_rest:variances","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#variances"},{"n":"cowboy_rest:init","l":"/docs/en/cowboy/1.0/manual/cowboy_rest/index.html#init"},{"n":"cowboy_router:constraints","l":"/docs/en/cowboy/1.0/manual/cowboy_router/index.html#constraints"},{"n":"cowboy_router:routes","l":"/docs/en/cowboy/1.0/manual/cowboy_router/index.html#routes"},{"n":"cowboy_router:tokens","l":"/docs/en/cowboy/1.0/manual/cowboy_router/index.html#tokens"},{"n":"cowboy_router:bindings","l":"/docs/en/cowboy/1.0/manual/cowboy_router/index.html#bindings"},{"n":"cowboy_router:compile","l":"/docs/en/cowboy/1.0/manual/cowboy_router/index.html#compile"},{"n":"cowboy_router:dispatch_rules","l":"/docs/en/cowboy/1.0/manual/cowboy_router/index.html#dispatch_rules"},{"n":"cowboy_spdy:middlewares ","l":"/docs/en/cowboy/1.0/manual/cowboy_spdy/index.html#middlewares "},{"n":"cowboy_spdy:onresponse ","l":"/docs/en/cowboy/1.0/manual/cowboy_spdy/index.html#onresponse "},{"n":"cowboy_spdy:onrequest ","l":"/docs/en/cowboy/1.0/manual/cowboy_spdy/index.html#onrequest "},{"n":"cowboy_spdy:opts","l":"/docs/en/cowboy/1.0/manual/cowboy_spdy/index.html#opts"},{"n":"cowboy_spdy:env ","l":"/docs/en/cowboy/1.0/manual/cowboy_spdy/index.html#env "},{"n":"cowboy_sub_protocol:upgrade","l":"/docs/en/cowboy/1.0/manual/cowboy_sub_protocol/index.html#upgrade"},{"n":"cowboy_websocket:websocket_compress","l":"/docs/en/cowboy/1.0/manual/cowboy_websocket/index.html#websocket_compress"},{"n":"cowboy_websocket:websocket_version","l":"/docs/en/cowboy/1.0/manual/cowboy_websocket/index.html#websocket_version"},{"n":"cowboy_websocket:close_code","l":"/docs/en/cowboy/1.0/manual/cowboy_websocket/index.html#close_code"},{"n":"cowboy_websocket:frame","l":"/docs/en/cowboy/1.0/manual/cowboy_websocket/index.html#frame"},{"n":"cowboy_websocket_handler:websocket_info","l":"/docs/en/cowboy/1.0/manual/cowboy_websocket_handler/index.html#websocket_info"},{"n":"cowboy_websocket_handler:websocket_terminate","l":"/docs/en/cowboy/1.0/manual/cowboy_websocket_handler/index.html#websocket_terminate"},{"n":"cowboy_websocket_handler:websocket_handle","l":"/docs/en/cowboy/1.0/manual/cowboy_websocket_handler/index.html#websocket_handle"},{"n":"cowboy_websocket_handler:init","l":"/docs/en/cowboy/1.0/manual/cowboy_websocket_handler/index.html#init"},{"n":"cowboy_websocket_handler:websocket_init","l":"/docs/en/cowboy/1.0/manual/cowboy_websocket_handler/index.html#websocket_init"},{"n":"cowboy_static:extra_mimetypes","l":"/docs/en/cowboy/HEAD/manual/cowboy_static/index.html#extra_mimetypes"},{"n":"cowboy_static:extra","l":"/docs/en/cowboy/HEAD/manual/cowboy_static/index.html#extra"},{"n":"cowboy_static:opts","l":"/docs/en/cowboy/HEAD/manual/cowboy_static/index.html#opts"},{"n":"cowboy_static:extra_etag","l":"/docs/en/cowboy/HEAD/manual/cowboy_static/index.html#extra_etag"},{"n":"http_status_codes:304 Not Modified","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#304 not modified"},{"n":"http_status_codes:500 Internal Server Error","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#500 internal server error"},{"n":"http_status_codes:201 Created","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#201 created"},{"n":"http_status_codes:413 Request Entity Too Large","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#413 request entity too large"},{"n":"http_status_codes:300 Multiple Choices","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#300 multiple choices"},{"n":"http_status_codes:412 Precondition Failed","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#412 precondition failed"},{"n":"http_status_codes:200 OK","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#200 ok"},{"n":"http_status_codes:101 Switching Protocols","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#101 switching protocols"},{"n":"http_status_codes:501 Not Implemented","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#501 not implemented"},{"n":"http_status_codes:505 HTTP Version Not Supported","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#505 http version not supported"},{"n":"http_status_codes:204 No Content","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#204 no content"},{"n":"http_status_codes:406 Not Acceptable","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#406 not acceptable"},{"n":"http_status_codes:415 Unsupported Media Type","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#415 unsupported media type"},{"n":"http_status_codes:503 Service Unavailable","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#503 service unavailable"},{"n":"http_status_codes:410 Gone","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#410 gone"},{"n":"http_status_codes:400 Bad Request","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#400 bad request"},{"n":"http_status_codes:401 Unauthorized","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#401 unauthorized"},{"n":"http_status_codes:301 Moved Permanently","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#301 moved permanently"},{"n":"http_status_codes:100 Continue","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#100 continue"},{"n":"http_status_codes:414 Request-URI Too Long","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#414 request-uri too long"},{"n":"http_status_codes:307 Temporary Redirect","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#307 temporary redirect"},{"n":"http_status_codes:409 Conflict","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#409 conflict"},{"n":"http_status_codes:202 Accepted","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#202 accepted"},{"n":"http_status_codes:404 Not Found","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#404 not found"},{"n":"http_status_codes:303 See Other","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#303 see other"},{"n":"http_status_codes:405 Method Not Allowed","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#405 method not allowed"},{"n":"http_status_codes:403 Forbidden","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#403 forbidden"},{"n":"http_status_codes:408 Request Timeout","l":"/docs/en/cowboy/HEAD/manual/http_status_codes/index.html#408 request timeout"},{"n":"cowboy:http_version","l":"/docs/en/cowboy/HEAD/manual/cowboy/index.html#http_version"},{"n":"cowboy:fields","l":"/docs/en/cowboy/HEAD/manual/cowboy/index.html#fields"},{"n":"cowboy:http_status","l":"/docs/en/cowboy/HEAD/manual/cowboy/index.html#http_status"},{"n":"cowboy:onresponse_fun","l":"/docs/en/cowboy/HEAD/manual/cowboy/index.html#onresponse_fun"},{"n":"cowboy:start_http","l":"/docs/en/cowboy/HEAD/manual/cowboy/index.html#start_http"},{"n":"cowboy:http_headers","l":"/docs/en/cowboy/HEAD/manual/cowboy/index.html#http_headers"},{"n":"cowboy:start_https","l":"/docs/en/cowboy/HEAD/manual/cowboy/index.html#start_https"},{"n":"cowboy:start_spdy","l":"/docs/en/cowboy/HEAD/manual/cowboy/index.html#start_spdy"},{"n":"cowboy:stop_listener","l":"/docs/en/cowboy/HEAD/manual/cowboy/index.html#stop_listener"},{"n":"cowboy:set_env","l":"/docs/en/cowboy/HEAD/manual/cowboy/index.html#set_env"},{"n":"cowboy_handler:{crash, Class, Reason}","l":"/docs/en/cowboy/HEAD/manual/cowboy_handler/index.html#{crash, class, reason}"},{"n":"cowboy_handler:normal","l":"/docs/en/cowboy/HEAD/manual/cowboy_handler/index.html#normal"},{"n":"cowboy_handler:init","l":"/docs/en/cowboy/HEAD/manual/cowboy_handler/index.html#init"},{"n":"cowboy_handler:terminate","l":"/docs/en/cowboy/HEAD/manual/cowboy_handler/index.html#terminate"},{"n":"cowboy_loop:{error, Reason}","l":"/docs/en/cowboy/HEAD/manual/cowboy_loop/index.html#{error, reason}"},{"n":"cowboy_loop:stop","l":"/docs/en/cowboy/HEAD/manual/cowboy_loop/index.html#stop"},{"n":"cowboy_loop:timeout","l":"/docs/en/cowboy/HEAD/manual/cowboy_loop/index.html#timeout"},{"n":"cowboy_loop:{crash, Class, Reason}","l":"/docs/en/cowboy/HEAD/manual/cowboy_loop/index.html#{crash, class, reason}"},{"n":"cowboy_loop:{error, closed}","l":"/docs/en/cowboy/HEAD/manual/cowboy_loop/index.html#{error, closed}"},{"n":"cowboy_loop:info","l":"/docs/en/cowboy/HEAD/manual/cowboy_loop/index.html#info"},{"n":"cowboy_loop:{error, overflow}","l":"/docs/en/cowboy/HEAD/manual/cowboy_loop/index.html#{error, overflow}"},{"n":"cowboy_loop:normal","l":"/docs/en/cowboy/HEAD/manual/cowboy_loop/index.html#normal"},{"n":"cowboy_middleware:env","l":"/docs/en/cowboy/HEAD/manual/cowboy_middleware/index.html#env"},{"n":"cowboy_middleware:execute","l":"/docs/en/cowboy/HEAD/manual/cowboy_middleware/index.html#execute"},{"n":"cowboy_protocol:max_header_name_length ","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#max_header_name_length "},{"n":"cowboy_protocol:max_keepalive ","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#max_keepalive "},{"n":"cowboy_protocol:max_request_line_length ","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#max_request_line_length "},{"n":"cowboy_protocol:middlewares ","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#middlewares "},{"n":"cowboy_protocol:onresponse ","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#onresponse "},{"n":"cowboy_protocol:timeout ","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#timeout "},{"n":"cowboy_protocol:max_header_value_length ","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#max_header_value_length "},{"n":"cowboy_protocol:max_headers ","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#max_headers "},{"n":"cowboy_protocol:max_empty_lines ","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#max_empty_lines "},{"n":"cowboy_protocol:compress ","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#compress "},{"n":"cowboy_protocol:env ","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#env "},{"n":"cowboy_protocol:opts","l":"/docs/en/cowboy/HEAD/manual/cowboy_protocol/index.html#opts"},{"n":"cowboy_req:has_resp_body","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#has_resp_body"},{"n":"cowboy_req:body_length","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#body_length"},{"n":"cowboy_req:headers","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#headers"},{"n":"cowboy_req:chunk","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#chunk"},{"n":"cowboy_req:parse_header","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#parse_header"},{"n":"cowboy_req:req","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#req"},{"n":"cowboy_req:match_qs","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#match_qs"},{"n":"cowboy_req:reply","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#reply"},{"n":"cowboy_req:method","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#method"},{"n":"cowboy_req:parse_cookies","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#parse_cookies"},{"n":"cowboy_req:body_qs","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#body_qs"},{"n":"cowboy_req:parse_qs","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#parse_qs"},{"n":"cowboy_req:set_resp_cookie","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#set_resp_cookie"},{"n":"cowboy_req:set_resp_header","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#set_resp_header"},{"n":"cowboy_req:port","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#port"},{"n":"cowboy_req:peer","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#peer"},{"n":"cowboy_req:part","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#part"},{"n":"cowboy_req:meta","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#meta"},{"n":"cowboy_req:continue","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#continue"},{"n":"cowboy_req:delete_resp_header","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#delete_resp_header"},{"n":"cowboy_req:set_meta","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#set_meta"},{"n":"cowboy_req:chunked_reply","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#chunked_reply"},{"n":"cowboy_req:host","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#host"},{"n":"cowboy_req:host_url","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#host_url"},{"n":"cowboy_req:body","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#body"},{"n":"cowboy_req:host_info","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#host_info"},{"n":"cowboy_req:cookie_opts","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#cookie_opts"},{"n":"cowboy_req:version","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#version"},{"n":"cowboy_req:qs","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#qs"},{"n":"cowboy_req:body_opts","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#body_opts"},{"n":"cowboy_req:bindings","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#bindings"},{"n":"cowboy_req:header","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#header"},{"n":"cowboy_req:binding","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#binding"},{"n":"cowboy_req:match_cookies","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#match_cookies"},{"n":"cowboy_req:path_info","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#path_info"},{"n":"cowboy_req:has_body","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#has_body"},{"n":"cowboy_req:path","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#path"},{"n":"cowboy_req:set_resp_body","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#set_resp_body"},{"n":"cowboy_req:has_resp_header","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#has_resp_header"},{"n":"cowboy_req:url","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#url"},{"n":"cowboy_req:set_resp_body_fun","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#set_resp_body_fun"},{"n":"cowboy_req:part_body","l":"/docs/en/cowboy/HEAD/manual/cowboy_req/index.html#part_body"},{"n":"cowboy_rest:valid_content_headers","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#valid_content_headers"},{"n":"cowboy_rest:generate_etag","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#generate_etag"},{"n":"cowboy_rest:forbidden","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#forbidden"},{"n":"cowboy_rest:valid_entity_length","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#valid_entity_length"},{"n":"cowboy_rest:resource_exists","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#resource_exists"},{"n":"cowboy_rest:expires","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#expires"},{"n":"cowboy_rest:last_modified","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#last_modified"},{"n":"cowboy_rest:{crash, Class, Reason}","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#{crash, class, reason}"},{"n":"cowboy_rest:delete_completed","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#delete_completed"},{"n":"cowboy_rest:is_conflict","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#is_conflict"},{"n":"cowboy_rest:moved_permanently","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#moved_permanently"},{"n":"cowboy_rest:media_type","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#media_type"},{"n":"cowboy_rest:charsets_provided","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#charsets_provided"},{"n":"cowboy_rest:content_types_accepted","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#content_types_accepted"},{"n":"cowboy_rest:content_types_provided","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#content_types_provided"},{"n":"cowboy_rest:normal","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#normal"},{"n":"cowboy_rest:previously_existed","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#previously_existed"},{"n":"cowboy_rest:languages_provided","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#languages_provided"},{"n":"cowboy_rest:uri_too_long","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#uri_too_long"},{"n":"cowboy_rest:moved_temporarily","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#moved_temporarily"},{"n":"cowboy_rest:charset","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#charset"},{"n":"cowboy_rest:allow_missing_post","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#allow_missing_post"},{"n":"cowboy_rest:options","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#options"},{"n":"cowboy_rest:multiple_choices","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#multiple_choices"},{"n":"cowboy_rest:language","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#language"},{"n":"cowboy_rest:allowed_methods","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#allowed_methods"},{"n":"cowboy_rest:malformed_request","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#malformed_request"},{"n":"cowboy_rest:known_methods","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#known_methods"},{"n":"cowboy_rest:Callback","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#callback"},{"n":"cowboy_rest:delete_resource","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#delete_resource"},{"n":"cowboy_rest:service_available","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#service_available"},{"n":"cowboy_rest:is_authorized","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#is_authorized"},{"n":"cowboy_rest:variances","l":"/docs/en/cowboy/HEAD/manual/cowboy_rest/index.html#variances"},{"n":"cowboy_router:routes","l":"/docs/en/cowboy/HEAD/manual/cowboy_router/index.html#routes"},{"n":"cowboy_router:tokens","l":"/docs/en/cowboy/HEAD/manual/cowboy_router/index.html#tokens"},{"n":"cowboy_router:bindings","l":"/docs/en/cowboy/HEAD/manual/cowboy_router/index.html#bindings"},{"n":"cowboy_router:compile","l":"/docs/en/cowboy/HEAD/manual/cowboy_router/index.html#compile"},{"n":"cowboy_router:dispatch_rules","l":"/docs/en/cowboy/HEAD/manual/cowboy_router/index.html#dispatch_rules"},{"n":"cowboy_spdy:middlewares ","l":"/docs/en/cowboy/HEAD/manual/cowboy_spdy/index.html#middlewares "},{"n":"cowboy_spdy:onresponse ","l":"/docs/en/cowboy/HEAD/manual/cowboy_spdy/index.html#onresponse "},{"n":"cowboy_spdy:opts","l":"/docs/en/cowboy/HEAD/manual/cowboy_spdy/index.html#opts"},{"n":"cowboy_spdy:env ","l":"/docs/en/cowboy/HEAD/manual/cowboy_spdy/index.html#env "},{"n":"cowboy_sub_protocol:upgrade","l":"/docs/en/cowboy/HEAD/manual/cowboy_sub_protocol/index.html#upgrade"},{"n":"cowboy_websocket:{remote, Code, Payload}","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#{remote, code, payload}"},{"n":"cowboy_websocket:{error, Reason}","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#{error, reason}"},{"n":"cowboy_websocket:stop","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#stop"},{"n":"cowboy_websocket:timeout","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#timeout"},{"n":"cowboy_websocket:{crash, Class, Reason}","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#{crash, class, reason}"},{"n":"cowboy_websocket:websocket_compress","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#websocket_compress"},{"n":"cowboy_websocket:{error, closed}","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#{error, closed}"},{"n":"cowboy_websocket:websocket_info","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#websocket_info"},{"n":"cowboy_websocket:{error, badframe}","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#{error, badframe}"},{"n":"cowboy_websocket:websocket_version","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#websocket_version"},{"n":"cowboy_websocket:remote","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#remote"},{"n":"cowboy_websocket:normal","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#normal"},{"n":"cowboy_websocket:websocket_handle","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#websocket_handle"},{"n":"cowboy_websocket:{error, badencoding}","l":"/docs/en/cowboy/HEAD/manual/cowboy_websocket/index.html#{error, badencoding}"},{"n":"ranch:start_listener","l":"/docs/en/ranch/1.1/manual/ranch/index.html#start_listener"},{"n":"ranch:set_protocol_options","l":"/docs/en/ranch/1.1/manual/ranch/index.html#set_protocol_options"},{"n":"ranch:set_max_connections","l":"/docs/en/ranch/1.1/manual/ranch/index.html#set_max_connections"},{"n":"ranch:get_protocol_options","l":"/docs/en/ranch/1.1/manual/ranch/index.html#get_protocol_options"},{"n":"ranch:accept_ack","l":"/docs/en/ranch/1.1/manual/ranch/index.html#accept_ack"},{"n":"ranch:remove_connection","l":"/docs/en/ranch/1.1/manual/ranch/index.html#remove_connection"},{"n":"ranch:max_conns","l":"/docs/en/ranch/1.1/manual/ranch/index.html#max_conns"},{"n":"ranch:child_spec","l":"/docs/en/ranch/1.1/manual/ranch/index.html#child_spec"},{"n":"ranch:ref","l":"/docs/en/ranch/1.1/manual/ranch/index.html#ref"},{"n":"ranch:get_max_connections","l":"/docs/en/ranch/1.1/manual/ranch/index.html#get_max_connections"},{"n":"ranch:get_port","l":"/docs/en/ranch/1.1/manual/ranch/index.html#get_port"},{"n":"ranch:stop_listener","l":"/docs/en/ranch/1.1/manual/ranch/index.html#stop_listener"},{"n":"ranch_protocol:start_link","l":"/docs/en/ranch/1.1/manual/ranch_protocol/index.html#start_link"},{"n":"ranch_ssl:opts","l":"/docs/en/ranch/1.1/manual/ranch_ssl/index.html#opts"},{"n":"ranch_tcp:opts","l":"/docs/en/ranch/1.1/manual/ranch_tcp/index.html#opts"},{"n":"ranch_transport:accept_ack","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#accept_ack"},{"n":"ranch_transport:controlling_process","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#controlling_process"},{"n":"ranch_transport:shutdown","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#shutdown"},{"n":"ranch_transport:sendfile_opts","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#sendfile_opts"},{"n":"ranch_transport:sendfile","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#sendfile"},{"n":"ranch_transport:send","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#send"},{"n":"ranch_transport:accept","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#accept"},{"n":"ranch_transport:recv","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#recv"},{"n":"ranch_transport:name","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#name"},{"n":"ranch_transport:close","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#close"},{"n":"ranch_transport:listen","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#listen"},{"n":"ranch_transport:setopts","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#setopts"},{"n":"ranch_transport:peername","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#peername"},{"n":"ranch_transport:messages","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#messages"},{"n":"ranch_transport:sockname","l":"/docs/en/ranch/1.1/manual/ranch_transport/index.html#sockname"},{"n":"ranch:start_listener","l":"/docs/en/ranch/1.0/manual/ranch/index.html#start_listener"},{"n":"ranch:set_protocol_options","l":"/docs/en/ranch/1.0/manual/ranch/index.html#set_protocol_options"},{"n":"ranch:set_max_connections","l":"/docs/en/ranch/1.0/manual/ranch/index.html#set_max_connections"},{"n":"ranch:get_protocol_options","l":"/docs/en/ranch/1.0/manual/ranch/index.html#get_protocol_options"},{"n":"ranch:accept_ack","l":"/docs/en/ranch/1.0/manual/ranch/index.html#accept_ack"},{"n":"ranch:remove_connection","l":"/docs/en/ranch/1.0/manual/ranch/index.html#remove_connection"},{"n":"ranch:max_conns","l":"/docs/en/ranch/1.0/manual/ranch/index.html#max_conns"},{"n":"ranch:child_spec","l":"/docs/en/ranch/1.0/manual/ranch/index.html#child_spec"},{"n":"ranch:ref","l":"/docs/en/ranch/1.0/manual/ranch/index.html#ref"},{"n":"ranch:get_max_connections","l":"/docs/en/ranch/1.0/manual/ranch/index.html#get_max_connections"},{"n":"ranch:get_port","l":"/docs/en/ranch/1.0/manual/ranch/index.html#get_port"},{"n":"ranch:stop_listener","l":"/docs/en/ranch/1.0/manual/ranch/index.html#stop_listener"},{"n":"ranch_protocol:start_link","l":"/docs/en/ranch/1.0/manual/ranch_protocol/index.html#start_link"},{"n":"ranch_ssl:opts","l":"/docs/en/ranch/1.0/manual/ranch_ssl/index.html#opts"},{"n":"ranch_tcp:opts","l":"/docs/en/ranch/1.0/manual/ranch_tcp/index.html#opts"},{"n":"ranch_transport:accept_ack","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#accept_ack"},{"n":"ranch_transport:controlling_process","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#controlling_process"},{"n":"ranch_transport:shutdown","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#shutdown"},{"n":"ranch_transport:sendfile_opts","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#sendfile_opts"},{"n":"ranch_transport:sendfile","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#sendfile"},{"n":"ranch_transport:send","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#send"},{"n":"ranch_transport:accept","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#accept"},{"n":"ranch_transport:recv","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#recv"},{"n":"ranch_transport:name","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#name"},{"n":"ranch_transport:close","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#close"},{"n":"ranch_transport:listen","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#listen"},{"n":"ranch_transport:setopts","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#setopts"},{"n":"ranch_transport:peername","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#peername"},{"n":"ranch_transport:messages","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#messages"},{"n":"ranch_transport:sockname","l":"/docs/en/ranch/1.0/manual/ranch_transport/index.html#sockname"},{"n":"ranch:start_listener","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#start_listener"},{"n":"ranch:set_protocol_options","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#set_protocol_options"},{"n":"ranch:set_max_connections","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#set_max_connections"},{"n":"ranch:get_protocol_options","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#get_protocol_options"},{"n":"ranch:accept_ack","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#accept_ack"},{"n":"ranch:remove_connection","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#remove_connection"},{"n":"ranch:max_conns","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#max_conns"},{"n":"ranch:child_spec","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#child_spec"},{"n":"ranch:ref","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#ref"},{"n":"ranch:get_max_connections","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#get_max_connections"},{"n":"ranch:get_port","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#get_port"},{"n":"ranch:stop_listener","l":"/docs/en/ranch/HEAD/manual/ranch/index.html#stop_listener"},{"n":"ranch_protocol:start_link","l":"/docs/en/ranch/HEAD/manual/ranch_protocol/index.html#start_link"},{"n":"ranch_ssl:opts","l":"/docs/en/ranch/HEAD/manual/ranch_ssl/index.html#opts"},{"n":"ranch_tcp:opts","l":"/docs/en/ranch/HEAD/manual/ranch_tcp/index.html#opts"},{"n":"ranch_transport:accept_ack","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#accept_ack"},{"n":"ranch_transport:controlling_process","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#controlling_process"},{"n":"ranch_transport:shutdown","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#shutdown"},{"n":"ranch_transport:sendfile_opts","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#sendfile_opts"},{"n":"ranch_transport:sendfile","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#sendfile"},{"n":"ranch_transport:send","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#send"},{"n":"ranch_transport:accept","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#accept"},{"n":"ranch_transport:recv","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#recv"},{"n":"ranch_transport:name","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#name"},{"n":"ranch_transport:close","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#close"},{"n":"ranch_transport:listen","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#listen"},{"n":"ranch_transport:setopts","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#setopts"},{"n":"ranch_transport:peername","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#peername"},{"n":"ranch_transport:messages","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#messages"},{"n":"ranch_transport:sockname","l":"/docs/en/ranch/HEAD/manual/ranch_transport/index.html#sockname"}] \ No newline at end of file diff --git a/docs/en/cowboy/1.0/guide/architecture/index.html b/docs/en/cowboy/1.0/guide/architecture/index.html new file mode 100644 index 00000000..ad14c180 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/architecture/index.html @@ -0,0 +1,202 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Architecture

+ +

Cowboy is a lightweight HTTP server.

+ +

It is built on top of Ranch. Please see the Ranch guide for more information.

+ +

One process per connection

+ +

It uses only one process per connection. The process where your code runs is the process controlling the socket. Using one process instead of two allows for lower memory usage.

+ +

Because there can be more than one request per connection with the keepalive feature of HTTP/1.1, that means the same process will be used to handle many requests.

+ +

Because of this, you are expected to make sure your process cleans up before terminating the handling of the current request. This may include cleaning up the process dictionary, timers, monitoring and more.

+ +

Binaries

+ +

It uses binaries. Binaries are more efficient than lists for representing strings because they take less memory space. Processing performance can vary depending on the operation. Binaries are known for generally getting a great boost if the code is compiled natively. Please see the HiPE documentation for more details.

+ +

Date header

+ +

Because querying for the current date and time can be expensive, Cowboy generates one Date header value every second, shares it to all other processes, which then simply copy it in the response. This allows compliance with HTTP/1.1 with no actual performance loss.

+ +

Max connections

+ +

By default the maximum number of active connections is set to a generally accepted big enough number. This is meant to prevent having too many processes performing potentially heavy work and slowing everything else down, or taking up all the memory.

+ +

Disabling this feature, by setting the {max_connections, infinity} protocol option, would give you greater performance when you are only processing short-lived requests.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/broken_clients/index.html b/docs/en/cowboy/1.0/guide/broken_clients/index.html new file mode 100644 index 00000000..d0046439 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/broken_clients/index.html @@ -0,0 +1,212 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Dealing with broken clients

+ +

There exists a very large number of implementations for the HTTP protocol. Most widely used clients, like browsers, follow the standard quite well, but others may not. In particular custom enterprise clients tend to be very badly written.

+ +

Cowboy tries to follow the standard as much as possible, but is not trying to handle every possible special cases. Instead Cowboy focuses on the cases reported in the wild, on the public Web.

+ +

That means clients that ignore the HTTP standard completely may fail to understand Cowboy's responses. There are of course workarounds. This chapter aims to cover them.

+ +

Lowercase headers

+ +

Cowboy converts all headers it receives to lowercase, and similarly sends back headers all in lowercase. Some broken HTTP clients have issues with that.

+ +

A simple way to solve this is to create an onresponse hook that will format the header names with the expected case.

+ + + +

Note that SPDY clients do not have that particular issue because the specification explicitly says all headers are lowercase, unlike HTTP which allows any case but treats them as case insensitive.

+ +

Camel-case headers

+ +

Sometimes it is desirable to keep the actual case used by clients, for example when acting as a proxy between two broken implementations. There is no easy solution for this other than forking the project and editing the cowboy_protocol file directly.

+ +

Chunked transfer-encoding

+ +

Sometimes an HTTP client advertises itself as HTTP/1.1 but does not support chunked transfer-encoding. This is invalid behavior, as HTTP/1.1 clients are required to support it.

+ +

A simple workaround exists in these cases. By changing the Req object response state to waiting_stream, Cowboy will understand that it must use the identity transfer-encoding when replying, just like if it was an HTTP/1.0 client.

+ + + + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/cookies/index.html b/docs/en/cowboy/1.0/guide/cookies/index.html new file mode 100644 index 00000000..fd9e0519 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/cookies/index.html @@ -0,0 +1,273 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Using cookies

+ +

Cookies are a mechanism allowing applications to maintain state on top of the stateless HTTP protocol.

+ +

Cowboy provides facilities for handling cookies. It is highly recommended to use them instead of writing your own, as the implementation of cookies can vary greatly between clients.

+ +

Cookies are stored client-side and sent with every subsequent request that matches the domain and path for which they were stored, including requests for static files. For this reason they can incur a cost which must be taken in consideration.

+ +

Also consider that, regardless of the options used, cookies are not to be trusted. They may be read and modified by any program on the user's computer, but also by proxies. You should always validate cookie values before using them. Do not store any sensitive information in cookies either.

+ +

When explicitly setting the domain, the cookie will be sent for the domain and all subdomains from that domain. Otherwise the current domain will be used. The same is true for the path.

+ +

When the server sets cookies, they will only be available for requests that are sent after the client receives the response.

+ +

Cookies are sent in HTTP headers, therefore they must have text values. It is your responsibility to encode any other data type. Also note that cookie names are de facto case sensitive.

+ +

Cookies can be set for the client session (which generally means until the browser is closed), or it can be set for a number of seconds. Once it expires, or when the server says the cookie must exist for up to 0 seconds, the cookie is deleted by the client. To avoid this while the user is browsing your site, you should set the cookie for every request, essentially resetting the expiration time.

+ +

Cookies can be restricted to secure channels. This typically means that such a cookie will only be sent over HTTPS, and that it will only be available by client-side scripts that run from HTTPS webpages.

+ +

Finally, cookies can be restricted to HTTP and HTTPS requests, essentially disabling their access from client-side scripts.

+ +

Setting cookies

+ +

By default, cookies you set are defined for the session.

+ + + +

You can also make them expire at a specific point in the future.

+ + + +

You can delete cookies that have already been set. The value is ignored.

+ + + +

You can restrict them to a specific domain and path. For example, the following cookie will be set for the domain my.example.org and all its subdomains, but only on the path /account and all its subdirectories.

+ + + +

You can restrict the cookie to secure channels, typically HTTPS.

+ + + +

You can restrict the cookie to client-server communication only. Such a cookie will not be available to client-side scripts.

+ + + +

Cookies may also be set client-side, for example using Javascript.

+ +

Reading cookies

+ +

As we said, the client sends cookies with every request. But unlike the server, the client only sends the cookie name and value.

+ +

You can read the value of a cookie.

+ + + +

You can also get a default value returned when the cookie isn't set.

+ + + +

And you can obtain all cookies at once as a list of key/value tuples.

+ + + + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/erlang_beginners/index.html b/docs/en/cowboy/1.0/guide/erlang_beginners/index.html new file mode 100644 index 00000000..b57aaf94 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/erlang_beginners/index.html @@ -0,0 +1,196 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Erlang for beginners

+ +

Chances are you are interested in using Cowboy, but have no idea how to write an Erlang program. Fear not! This chapter will help you get started.

+ +

We recommend two books for beginners. You should read them both at some point, as they cover Erlang from two entirely different perspectives.

+ +

Learn You Some Erlang for Great Good!

+ +

The quickest way to get started with Erlang is by reading a book with the funny name of LYSE, as we affectionately call it.

+ +

It will get right into the syntax and quickly answer the questions a beginner would ask themselves, all the while showing funny pictures and making insightful jokes.

+ +

You can read an early version of the book online for free, but you really should buy the much more refined paper and ebook versions.

+ +

Programming Erlang

+ +

After writing some code, you will probably want to understand the very concepts that make Erlang what it is today. These are best explained by Joe Armstrong, the godfather of Erlang, in his book Programming Erlang.

+ +

Instead of going into every single details of the language, Joe focuses on the central concepts behind Erlang, and shows you how they can be used to write a variety of different applications.

+ +

At the time of writing, the 2nd edition of the book is in beta, and includes a few details about upcoming Erlang features that cannot be used today. Choose the edition you want, then get reading!

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/erlang_web/index.html b/docs/en/cowboy/1.0/guide/erlang_web/index.html new file mode 100644 index 00000000..96ba79b1 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/erlang_web/index.html @@ -0,0 +1,248 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Erlang and the Web

+ +

The Web is concurrent

+ +

When you access a website there is little concurrency involved. A few connections are opened and requests are sent through these connections. Then the web page is displayed on your screen. Your browser will only open up to 4 or 8 connections to the server, depending on your settings. This isn't much.

+ +

But think about it. You are not the only one accessing the server at the same time. There can be hundreds, if not thousands, if not millions of connections to the same server at the same time.

+ +

Even today a lot of systems used in production haven't solved the C10K problem (ten thousand concurrent connections). And the ones who did are trying hard to get to the next step, C100K, and are pretty far from it.

+ +

Erlang meanwhile has no problem handling millions of connections. At the time of writing there are application servers written in Erlang that can handle more than two million connections on a single server in a real production application, with spare memory and CPU!

+ +

The Web is concurrent, and Erlang is a language designed for concurrency, so it is a perfect match.

+ +

Of course, various platforms need to scale beyond a few million connections. This is where Erlang's built-in distribution mechanisms come in. If one server isn't enough, add more! Erlang allows you to use the same code for talking to local processes or to processes in other parts of your cluster, which means you can scale very quickly if the need arises.

+ +

The Web has large userbases, and the Erlang platform was designed to work in a distributed setting, so it is a perfect match.

+ +

Or is it? Surely you can find solutions to handle that many concurrent connections with your favorite language... But all these solutions will break down in the next few years. Why? Firstly because servers don't get any more powerful, they instead get a lot more cores and memory. This is only useful if your application can use them properly, and Erlang is light-years away from anything else in that area. Secondly, today your computer and your phone are online, tomorrow your watch, goggles, bike, car, fridge and tons of other devices will also connect to various applications on the Internet.

+ +

Only Erlang is prepared to deal with what's coming.

+ +

The Web is soft real time

+ +

What does soft real time mean, you ask? It means we want the operations done as quickly as possible, and in the case of web applications, it means we want the data propagated fast.

+ +

In comparison, hard real time has a similar meaning, but also has a hard time constraint, for example an operation needs to be done in under N milliseconds otherwise the system fails entirely.

+ +

Users aren't that needy yet, they just want to get access to their content in a reasonable delay, and they want the actions they make to register at most a few seconds after they submitted them, otherwise they'll start worrying about whether it successfully went through.

+ +

The Web is soft real time because taking longer to perform an operation would be seen as bad quality of service.

+ +

Erlang is a soft real time system. It will always run processes fairly, a little at a time, switching to another process after a while and preventing a single process to steal resources from all others. This means that Erlang can guarantee stable low latency of operations.

+ +

Erlang provides the guarantees that the soft real time Web requires.

+ +

The Web is asynchronous

+ +

Long ago, the Web was synchronous because HTTP was synchronous. You fired a request, and then waited for a response. Not anymore. It all began when XmlHttpRequest started being used. It allowed the client to perform asynchronous calls to the server.

+ +

Then Websocket appeared and allowed both the server and the client to send data to the other endpoint completely asynchronously. The data is contained within frames and no response is necessary.

+ +

Erlang processes work the same. They send each other data contained within messages and then continue running without needing a response. They tend to spend most of their time inactive, waiting for a new message, and the Erlang VM happily activate them when one is received.

+ +

It is therefore quite easy to imagine Erlang being good at receiving Websocket frames, which may come in at unpredictable times, pass the data to the responsible processes which are always ready waiting for new messages, and perform the operations required by only activating the required parts of the system.

+ +

The more recent Web technologies, like Websocket of course, but also SPDY and HTTP/2.0, are all fully asynchronous protocols. The concept of requests and responses is retained of course, but anything could be sent in between, by both the client or the browser, and the responses could also be received in a completely different order.

+ +

Erlang is by nature asynchronous and really good at it thanks to the great engineering that has been done in the VM over the years. It's only natural that it's so good at dealing with the asynchronous Web.

+ +

The Web is omnipresent

+ +

The Web has taken a very important part of our lives. We're connected at all times, when we're on our phone, using our computer, passing time using a tablet while in the bathroom... And this isn't going to slow down, every single device at home or on us will be connected.

+ +

All these devices are always connected. And with the number of alternatives to give you access to the content you seek, users tend to not stick around when problems arise. Users today want their applications to be always available and if it's having too many issues they just move on.

+ +

Despite this, when developers choose a product to use for building web applications, their only concern seem to be "Is it fast?", and they look around for synthetic benchmarks showing which one is the fastest at sending "Hello world" with only a handful concurrent connections. Web benchmarks haven't been representative of reality in a long time, and are drifting further away as time goes on.

+ +

What developers should really ask themselves is "Can I service all my users with no interruption?" and they'd find that they have two choices. They can either hope for the best, or they can use Erlang.

+ +

Erlang is built for fault tolerance. When writing code in any other language, you have to check all the return values and act accordingly to avoid any unforeseen issues. If you're lucky, you won't miss anything important. When writing Erlang code, you can just check the success condition and ignore all errors. If an error happen, the Erlang process crashes and is then restarted by a special process called a supervisor.

+ +

The Erlang developer thus has no need to fear about unhandled errors, and can focus on handling only the errors that should give some feedback to the user and let the system take care of the rest. This also has the advantage of allowing him to write a lot less code, and letting him sleep at night.

+ +

Erlang's fault tolerance oriented design is the first piece of what makes it the best choice for the omnipresent, always available Web.

+ +

The second piece is Erlang's built-in distribution. Distribution is a key part of building a fault tolerant system, because it allows you to handle bigger failures, like a whole server going down, or even a data center entirely.

+ +

Fault tolerance and distribution are important today, and will be vital in the future of the Web. Erlang is ready.

+ +

Erlang is the ideal platform for the Web

+ +

Erlang provides all the important features that the Web requires or will require in the near future. Erlang is a perfect match for the Web, and it only makes sense to use it to build web applications.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/getting_started/index.html b/docs/en/cowboy/1.0/guide/getting_started/index.html new file mode 100644 index 00000000..810fd358 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/getting_started/index.html @@ -0,0 +1,299 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Getting started

+ +

Erlang is more than a language, it is also an operating system for your applications. Erlang developers rarely write standalone modules, they write libraries or applications, and then bundle those into what is called a release. A release contains the Erlang VM plus all applications required to run the node, so it can be pushed to production directly.

+ +

This chapter walks you through all the steps of setting up Cowboy, writing your first application and generating your first release. At the end of this chapter you should know everything you need to push your first Cowboy application to production.

+ +

Bootstrap

+ +

We are going to use the erlang.mk build system. It also offers bootstrap features allowing us to quickly get started without having to deal with minute details.

+ +

First, let's create the directory for our application.

+ + + +

Then we need to download erlang.mk. Either use the following command or download it manually.

+ + + +

We can now bootstrap our application. Since we are going to generate a release, we will also bootstrap it at the same time.

+ + + +

This creates a Makefile, a base application, and the release files necessary for creating the release. We can already build and start this release.

+ + + +

Entering the command i(). will show the running processes, including one called hello_erlang_sup. This is the supervisor for our application.

+ +

The release currently does nothing. In the rest of this chapter we will add Cowboy as a dependency and write a simple "Hello world!" handler.

+ +

Cowboy setup

+ +

To add Cowboy as a dependency to your application, you need to modify two files: the Makefile and the application resource file.

+ +

Modifying the Makefile allows the build system to know it needs to fetch and compile Cowboy. To do that we simply need to add one line to our Makefile to make it look like this:

+ + + +

Modifying the application resource file, src/hello_erlang.app.src, allows the build system to know it needs to include Cowboy in the release and start it automatically. This is a different step because some dependencies are only needed during development.

+ +

We are simply going to add cowboy to the list of applications, right after stdlib. Don't forget the comma separator.

+ + + +

You may want to set a description for the application while you are editing the file.

+ +

If you run make now and start the release, Cowboy will be included and started automatically. This is not enough however, as Cowboy doesn't do anything by default. We still need to tell Cowboy to listen for connections.

+ +

Listening for connections

+ +

We will do this when our application starts. It's a two step process. First we need to define and compile the dispatch list, a list of routes that Cowboy will use to map requests to handler modules. Then we tell Cowboy to listen for connections.

+ +

Open the src/hello_erlang_app.erl file and add the necessary code to the start/2 function to make it look like this:

+ + + +

The dispatch list is explained in great details in the Routing chapter. For this tutorial we map the path / to the handler module hello_handler. This module doesn't exist yet, we still have to write it.

+ +

If you build the release, start it and open http://localhost:8080 now, you will get an error because the module is missing. Any other URL, like http://localhost:8080/test, will result in a 404 error.

+ +

Handling requests

+ +

Cowboy features different kinds of handlers, including REST and Websocket handlers. For this tutorial we will use a plain HTTP handler.

+ +

First, let's generate a handler from a template.

+ + + +

You can then open the src/hello_handler.erl file and modify the handle/2 function like this to send a reply.

+ + + +

What the above code does is send a 200 OK reply, with the content-type header set to text/plain and the response body set to Hello Erlang!.

+ +

If you build the release, start it and open http://localhost:8080 in your browser, you should get a nice Hello Erlang! displayed!

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/hooks/index.html b/docs/en/cowboy/1.0/guide/hooks/index.html new file mode 100644 index 00000000..13079057 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/hooks/index.html @@ -0,0 +1,239 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Hooks

+ +

Cowboy provides two hooks. onrequest is called once the request line and headers have been received. onresponse is called just before sending the response.

+ +

Onrequest

+ +

The onrequest hook is called as soon as Cowboy finishes fetching the request headers. It occurs before any other processing, including routing. It can be used to perform any modification needed on the request object before continuing with the processing. If a reply is sent inside this hook, then Cowboy will move on to the next request, skipping any subsequent handling.

+ +

This hook is a function that takes a request object as argument, and returns a request object. This function MUST NOT crash. Cowboy will not send any reply if a crash occurs in this function.

+ +

You can specify the onrequest hook when creating the listener, inside the request options.

+ + + +

The following hook function prints the request object everytime a request is received. This can be useful for debugging, for example.

+ + + +

Make sure to always return the last request object obtained.

+ +

Onresponse

+ +

The onresponse hook is called right before sending the response to the socket. It can be used for the purposes of logging responses, or for modifying the response headers or body. The best example is providing custom error pages.

+ +

Note that like the onrequest hook, this function MUST NOT crash. Cowboy may or may not send a reply if this function crashes. If a reply is sent, the hook MUST explicitly provide all headers that are needed.

+ +

You can specify the onresponse hook when creating the listener.

+ + + +

The following hook function will provide a custom body for 404 errors when it has not been provided before, and will let Cowboy proceed with the default response otherwise.

+ + + +

Again, make sure to always return the last request object obtained.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/http_handlers/index.html b/docs/en/cowboy/1.0/guide/http_handlers/index.html new file mode 100644 index 00000000..31a6c135 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/http_handlers/index.html @@ -0,0 +1,279 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Handling plain HTTP requests

+ +

The simplest way to handle a request is by writing a plain HTTP handler. It is modeled after Erlang/OTP's gen_server behaviour, although simplified, as Cowboy will simply call the three callbacks sequentially.

+ +

Initialization

+ +

The first callback, init/3, is common to all handlers, as it is used to identify the type of handler. Plain HTTP handlers just return ok.

+ + + +

This function receives the name of the transport and protocol modules used for processing the request. They can be used to quickly dismiss requests. For example the following handler will crash when accessed using TCP instead of SSL.

+ + + +

This function also receives the options associated with this route that you configured previously. If your handler does not use options, then it is recommended you match the value [] directly to quickly detect configuration errors.

+ + + +

You do not need to validate the options unless they are user configured. If they are, and there's a configuration error, you may choose to crash. For example, this will crash if the required lang option is not found.

+ + + +

If your users are unlikely to figure out the issue without explanations, then you should send a more meaningful error back to the user. Since we already replied to the user, there's no need for us to continue with the handler code, so we use the shutdown return value to stop early.

+ + + +

Once the options have been validated, we can use them safely. So we need to pass them onward to the rest of the handler. That's what the third element of the return tuple, the state, is for.

+ +

We recommend that you create a state record for this. The record will make your handler code clearer and will allow you to better use Dialyzer for type checking.

+ + + +

Handling the request

+ +

The second callback, handle/2, is specific to plain HTTP handlers. It's where you, wait for it, handle the request.

+ +

A handle function that does nothing would look like this:

+ + + +

There's no other return value. To obtain information about the request, or send a response, you would use the Req object here. The Req object is documented in its own chapter.

+ +

The following handle function will send a fairly original response.

+ + + +

Cleaning up

+ +

The third and last callback, terminate/3, will most likely be empty in your handler.

+ + + +

This callback is strictly reserved for any required cleanup. You cannot send a response from this function. There is no other return value.

+ +

If you used the process dictionary, timers, monitors or may be receiving messages, then you can use this function to clean them up, as Cowboy might reuse the process for the next keep-alive request.

+ +

The chances of any of this happening in your handler are pretty thin however. The use of the process dictionary is discouraged in Erlang code in general. And if you need to use timers, monitors or to receive messages, you are better off with a loop handler, a different kind of handler meant specifically for this use.

+ +

This function is still available should you need it. It will always be called.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/http_req_life/index.html b/docs/en/cowboy/1.0/guide/http_req_life/index.html new file mode 100644 index 00000000..90d5d466 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/http_req_life/index.html @@ -0,0 +1,251 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

The life of a request

+ +

This chapter explains the different steps a request goes through until a response is sent, along with details of the Cowboy implementation.

+ +

Request/response

+ +

As you already know, HTTP clients connect to the server and send a request for a resource; the server then sends a response containing the resource if it could obtain it.

+ +

Before the server can send the resource, however, it needs to perform many different operations to read the request, find the resource, prepare the response being sent and often other related operations the user can add like writing logs.

+ +

Requests take the following route in Cowboy:

+ +

+ +

This shows the default middlewares, but they may be configured differently in your setup. The dark green indicates the points where you can hook your own code, the light green is the Cowboy code that you can of course configure as needed.

+ +

The acceptor is the part of the server that accepts the connection and create an Erlang process to handle it. The parser then starts reading from the socket and handling requests as they come until the socket is closed.

+ +

A response may be sent at many different points in the life of the request. If Cowboy can't parse the request, it gives up with an error response. If the router can't find the resource, it sends a not found error. Your own code can of course send a response at any time.

+ +

When a response is sent, you can optionally modify it or act upon it by enabling the onresponse hook. By default the response is sent directly to the client.

+ +

And then?

+ +

Behavior depends on what protocol is in use.

+ +

HTTP/1.0 can only process one request per connection, so Cowboy will close the connection immediately after it sends the response.

+ +

HTTP/1.1 allows the client to request that the server keeps the connection alive. This mechanism is described in the next section.

+ +

SPDY is designed to allow sending multiple requests asynchronously on the same connection. Details on what this means for your application is described in this chapter.

+ +

Keep-alive (HTTP/1.1)

+ +

With HTTP/1.1, the connection may be left open for subsequent requests to come. This mechanism is called keep-alive.

+ +

When the client sends a request to the server, it includes a header indicating whether it would like to leave the socket open. The server may or may not accept, indicating its choice by sending the same header in the response.

+ +

Cowboy will include this header automatically in all responses to HTTP/1.1 requests. You can however force the closing of the socket if you want. When Cowboy sees you want to send a connection: close header, it will not override it and will close the connection as soon as the reply is sent.

+ +

This snippet will force Cowboy to close the connection.

+ + + +

Cowboy will only accept a certain number of new requests on the same connection. By default it will run up to 100 requests. This number can be changed by setting the max_keepalive configuration value when starting an HTTP listener.

+ + + +

Cowboy implements the keep-alive mechanism by reusing the same process for all requests. This allows Cowboy to save memory. This works well because most code will not have any side effect impacting subsequent requests. But it also means you need to clean up if you do have code with side effects. The terminate/3 function can be used for this purpose.

+ +

Pipelining (HTTP/1.1)

+ +

While HTTP is designed as a sequential protocol, with the client sending a request and then waiting for the response from the server, nothing prevents the client from sending more requests to the server without waiting for the response, due to how sockets work. The server still handles the requests sequentially and sends the responses in the same order.

+ +

This mechanism is called pipelining. It allows reducing latency when a client needs to request many resources at the same time. This is used by browsers when requesting static files for example.

+ +

This is handled automatically by the server.

+ +

Asynchronous requests (SPDY)

+ +

In SPDY, the client can send a request at any time. And the server can send a response at any time too.

+ +

This means for example that the client does not need to wait for a request to be fully sent to send another, it is possible to interleave a request with the request body of another request. The same is true with responses. Responses may also be sent in a different order.

+ +

Because requests and responses are fully asynchronous, Cowboy creates a new process for each request, and these processes are managed by another process that handles the connection itself.

+ +

SPDY servers may also decide to send resources to the client before the client requests them. This is especially useful for sending static files associated with the HTML page requested, as this reduces the latency of the overall response. Cowboy does not support this particular mechanism at this point, however.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/http_req_resp.png b/docs/en/cowboy/1.0/guide/http_req_resp.png new file mode 100644 index 00000000..e38935f3 Binary files /dev/null and b/docs/en/cowboy/1.0/guide/http_req_resp.png differ diff --git a/docs/en/cowboy/1.0/guide/http_req_resp.svg b/docs/en/cowboy/1.0/guide/http_req_resp.svg new file mode 100644 index 00000000..0cfa0ae9 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/http_req_resp.svg @@ -0,0 +1,558 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + acceptor + parser + router + some text + onrequest + handler + middlewares + some text + client + + + + + reply + onresponse + + diff --git a/docs/en/cowboy/1.0/guide/index.html b/docs/en/cowboy/1.0/guide/index.html new file mode 100644 index 00000000..f03e8f67 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/index.html @@ -0,0 +1,250 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Cowboy User Guide

+ +

The Cowboy User Guide explores the modern Web and how to make best use of Cowboy for writing powerful web applications.

+ +

Introducing Cowboy

+ + + +

HTTP

+ + + +

Multipart

+ + + +

Static files

+ + + +

REST

+ + + +

Websocket

+ + + +

Server push

+ + + +

Pluggable interface

+ + + +

Internals

+ + + + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/introduction/index.html b/docs/en/cowboy/1.0/guide/introduction/index.html new file mode 100644 index 00000000..fa7f48f5 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/introduction/index.html @@ -0,0 +1,212 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Introduction

+ +

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 includes hundreds of tests and its code is fully compliant with the Dialyzer. It is also well documented and features both a Function Reference and a User Guide.

+ +

Prerequisites

+ +

No Erlang knowledge is required for reading this guide. The reader will be introduced to Erlang concepts and redirected to reference material whenever necessary.

+ +

Knowledge of the HTTP protocol is recommended but not required, as it will be detailed throughout the guide.

+ +

Supported platforms

+ +

Cowboy is tested and supported on Linux.

+ +

Cowboy has been reported to work on other platforms, but we make no guarantee that the experience will be safe and smooth. You are advised to perform the necessary testing and security audits prior to deploying on other platforms.

+ +

Cowboy is developed for Erlang/OTP R16B01, R16B02, R16B03-1, 17.0 and 17.1.2.

+ +

Cowboy may be compiled on other Erlang versions with small source code modifications but there is no guarantee that it will work as expected.

+ +

Versioning

+ +

Cowboy uses Semantic Versioning 2.0.0.

+ +

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.

+ +

The same applies to any other case insensitive value.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/loop_handlers/index.html b/docs/en/cowboy/1.0/guide/loop_handlers/index.html new file mode 100644 index 00000000..d9d1bb30 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/loop_handlers/index.html @@ -0,0 +1,264 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Loop handlers

+ +

Loop handlers are a special kind of HTTP handlers used when the response can not be sent right away. The handler enters instead a receive loop waiting for the right message before it can send a response.

+ +

Loop handlers are used for requests where a response might not be immediately available, but where you would like to keep the connection open for a while in case the response arrives. The most known example of such practice is known as long-polling.

+ +

Loop handlers can also be used for requests where a response is partially available and you need to stream the response body while the connection is open. The most known example of such practice is known as server-sent events.

+ +

While the same can be accomplished using plain HTTP handlers, it is recommended to use loop handlers because they are well-tested and allow using built-in features like hibernation and timeouts.

+ +

Loop handlers essentially wait for one or more Erlang messages and feed these messages to the info/3 callback. It also features the init/3 and terminate/3 callbacks which work the same as for plain HTTP handlers.

+ +

Initialization

+ +

The init/3 function must return a loop tuple to enable loop handler behavior. This tuple may optionally contain a timeout value and/or the atom hibernate to make the process enter hibernation until a message is received.

+ +

This snippet enables the loop handler.

+ + + +

However it is largely recommended that you set a timeout value. The next example sets a timeout value of 30s and also makes the process hibernate.

+ + + +

Receive loop

+ +

Once initialized, Cowboy will wait for messages to arrive in the process' mailbox. When a message arrives, Cowboy calls the info/3 function with the message, the Req object and the handler's state.

+ +

The following snippet sends a reply when it receives a reply message from another process, or waits for another message otherwise.

+ + + +

Do note that the reply tuple here may be any message and is simply an example.

+ +

This callback may perform any necessary operation including sending all or parts of a reply, and will subsequently return a tuple indicating if more messages are to be expected.

+ +

The callback may also choose to do nothing at all and just skip the message received.

+ +

If a reply is sent, then the ok tuple should be returned. This will instruct Cowboy to end the request.

+ +

Otherwise a loop tuple should be returned.

+ +

Streaming loop

+ +

Another common case well suited for loop handlers is streaming data received in the form of Erlang messages. This can be done by initiating a chunked reply in the init/3 callback and then using cowboy_req:chunk/2 every time a message is received.

+ +

The following snippet does exactly that. As you can see a chunk is sent every time a chunk message is received, and the loop is stopped by sending an eof message.

+ + + +

Cleaning up

+ +

It is recommended that you set the connection header to close when replying, as this process may be reused for a subsequent request.

+ +

Please refer to the HTTP handlers chapter for general instructions about cleaning up.

+ +

Timeout

+ +

By default Cowboy will not attempt to close the connection if there is no activity from the client. This is not always desirable, which is why you can set a timeout. Cowboy will close the connection if no data was received from the client after the configured time. The timeout only needs to be set once and can't be modified afterwards.

+ +

Because the request may have had a body, or may be followed by another request, Cowboy is forced to buffer all data it receives. This data may grow to become too large though, so there is a configurable limit for it. The default buffer size is of 5000 bytes, but it may be changed by setting the loop_max_buffer middleware environment value.

+ +

Hibernate

+ +

To save memory, you may hibernate the process in between messages received. This is done by returning the atom hibernate as part of the loop tuple callbacks normally return. Just add the atom at the end and Cowboy will hibernate accordingly.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/middlewares/index.html b/docs/en/cowboy/1.0/guide/middlewares/index.html new file mode 100644 index 00000000..42410512 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/middlewares/index.html @@ -0,0 +1,226 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Middlewares

+ +

Cowboy delegates the request processing to middleware components. By default, two middlewares are defined, for the routing and handling of the request, as is detailed in most of this guide.

+ +

Middlewares give you complete control over how requests are to be processed. You can add your own middlewares to the mix or completely change the chain of middlewares as needed.

+ +

Cowboy will execute all middlewares in the given order, unless one of them decides to stop processing.

+ +

Usage

+ +

Middlewares only need to implement a single callback: execute/2. It is defined in the cowboy_middleware behavior.

+ +

This callback has two arguments. The first is the Req object. The second is the environment.

+ +

Middlewares can return one of four different values:

+ +
    +
  • {ok, Req, Env} to continue the request processing
    • +
  • {suspend, Module, Function, Args} to hibernate
    • +
  • {halt, Req} to stop processing and move on to the next request
    • +
  • {error, StatusCode, Req} to reply an error and close the socket
    • +
+ +

Of note is that when hibernating, processing will resume on the given MFA, discarding all previous stacktrace. Make sure you keep the Req and Env in the arguments of this MFA for later use.

+ +

If an error happens during middleware processing, Cowboy will not try to send an error back to the socket, the process will just crash. It is up to the middleware to make sure that a reply is sent if something goes wrong.

+ +

Configuration

+ +

The middleware environment is defined as the env protocol option. In the previous chapters we saw it briefly when we needed to pass the routing information. It is a list of tuples with the first element being an atom and the second any Erlang term.

+ +

Two values in the environment are reserved:

+ +
    +
  • listener contains the name of the listener
    • +
  • result contains the result of the processing
    • +
+ +

The listener value is always defined. The result value can be set by any middleware. If set to anything other than ok, Cowboy will not process any subsequent requests on this connection.

+ +

The middlewares that come with Cowboy may define or require other environment values to perform.

+ +

You can update the environment by calling the cowboy:set_env/3 convenience function, adding or replacing a value in the environment.

+ +

Routing middleware

+ +

The routing middleware requires the dispatch value. If routing succeeds, it will put the handler name and options in the handler and handler_opts values of the environment, respectively.

+ +

Handler middleware

+ +

The handler middleware requires the handler and handler_opts values. It puts the result of the request handling into result.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/modern_web/index.html b/docs/en/cowboy/1.0/guide/modern_web/index.html new file mode 100644 index 00000000..1aaba0a0 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/modern_web/index.html @@ -0,0 +1,282 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

The modern Web

+ +

Let's take a look at various technologies from the beginnings of the Web up to this day, and get a preview of what's coming next.

+ +

Cowboy is compatible with all the technology cited in this chapter except of course HTTP/2.0 which has no implementation in the wild at the time of writing.

+ +

The prehistoric Web

+ +

HTTP was initially created to serve HTML pages and only had the GET method for retrieving them. This initial version is documented and is sometimes called HTTP/0.9. HTTP/1.0 defined the GET, HEAD and POST methods, and was able to send data with POST requests.

+ +

HTTP/1.0 works in a very simple way. A TCP connection is first established to the server. Then a request is sent. Then the server sends a response back and closes the connection.

+ +

Suffice to say, HTTP/1.0 is not very efficient. Opening a TCP connection takes some time, and pages containing many assets load much slower than they could because of this.

+ +

Most improvements done in recent years focused on reducing this load time and reducing the latency of the requests.

+ +

HTTP/1.1

+ +

HTTP/1.1 quickly followed and added a keep-alive mechanism to allow using the same connection for many requests, as well as streaming capabilities, allowing an endpoint to send a body in well defined chunks.

+ +

HTTP/1.1 defines the OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE and CONNECT methods. The PATCH method was added in more recent years. It also improves the caching capabilities with the introduction of many headers.

+ +

HTTP/1.1 still works like HTTP/1.0 does, except the connection can be kept alive for subsequent requests. This however allows clients to perform what is called as pipelining: sending many requests in a row, and then processing the responses which will be received in the same order as the requests.

+ +

REST

+ +

The design of HTTP/1.1 was influenced by the REST architectural style. REST, or REpresentational State Transfer, is a style of architecture for loosely connected distributed systems.

+ +

REST defines constraints that systems must obey to in order to be RESTful. A system which doesn't follow all the constraints cannot be considered RESTful.

+ +

REST is a client-server architecture with a clean separation of concerns between the client and the server. They communicate by referencing resources. Resources can be identified, but also manipulated. A resource representation has a media type and information about whether it can be cached and how. Hypermedia determines how resources are related and how they can be used. REST is also stateless. All requests contain the complete information necessary to perform the action.

+ +

HTTP/1.1 defines all the methods, headers and semantics required to implement RESTful systems.

+ +

REST is most often used when designing web application APIs which are generally meant to be used by executable code directly.

+ +

XmlHttpRequest

+ +

Also know as AJAX, this technology allows Javascript code running on a web page to perform asynchronous requests to the server. This is what started the move from static websites to dynamic web applications.

+ +

XmlHttpRequest still performs HTTP requests under the hood, and then waits for a response, but the Javascript code can continue to run until the response arrives. It will then receive the response through a callback previously defined.

+ +

This is of course still requests initiated by the client, the server still had no way of pushing data to the client on its own, so new technology appeared to allow that.

+ +

Long-polling

+ +

Polling was a technique used to overcome the fact that the server cannot push data directly to the client. Therefore the client had to repeatedly create a connection, make a request, get a response, then try again a few seconds later. This is overly expensive and adds an additional delay before the client receives the data.

+ +

Polling was necessary to implement message queues and other similar mechanisms, where a user must be informed of something when it happens, rather than when he refreshes the page next. A typical example would be a chat application.

+ +

Long-polling was created to reduce the server load by creating less connections, but also to improve latency by getting the response back to the client as soon as it becomes available on the server.

+ +

Long-polling works in a similar manner to polling, except the request will not get a response immediately. Instead the server leaves it open until it has a response to send. After getting the response, the client creates a new request and gets back to waiting.

+ +

You probably guessed by now that long-polling is a hack, and like most hacks it can suffer from unforeseen issues, in this case it doesn't always play well with proxies.

+ +

HTML5

+ +

HTML5 is, of course, the HTML version after HTML4. But HTML5 emerged to solve a specific problem: dynamic web applications.

+ +

HTML was initially created to write web pages which compose a website. But soon people and companies wanted to use HTML to write more and more complex websites, eventually known as web applications. They are for example your news reader, your email client in the browser, or your video streaming website.

+ +

Because HTML wasn't enough, they started using proprietary solutions, often implemented using plug-ins. This wasn't perfect of course, but worked well enough for most people.

+ +

However, the needs for a standard solution eventually became apparent. The browser needed to be able to play media natively. It needed to be able to draw anything. It needed an efficient way of streaming events to the server, but also receiving events from the server.

+ +

The solution went on to become HTML5. At the time of writing it is being standardized.

+ +

EventSource

+ +

EventSource, sometimes also called Server-Sent Events, is a technology allowing servers to push data to HTML5 applications.

+ +

EventSource is one-way communication channel from the server to the client. The client has no means to talk to the server other than by using HTTP requests.

+ +

It consists of a Javascript object allowing setting up an EventSource connection to the server, and a very small protocol for sending events to the client on top of the HTTP/1.1 connection.

+ +

EventSource is a lightweight solution that only works for UTF-8 encoded text data. Binary data and text data encoded differently are not allowed by the protocol. A heavier but more generic approach can be found in Websocket.

+ +

Websocket

+ +

Websocket is a protocol built on top of HTTP/1.1 that provides a two-ways communication channel between the client and the server. Communication is asynchronous and can occur concurrently.

+ +

It consists of a Javascript object allowing setting up a Websocket connection to the server, and a binary based protocol for sending data to the server or the client.

+ +

Websocket connections can transfer either UTF-8 encoded text data or binary data. The protocol also includes support for implementing a ping/pong mechanism, allowing the server and the client to have more confidence that the connection is still alive.

+ +

A Websocket connection can be used to transfer any kind of data, small or big, text or binary. Because of this Websocket is sometimes used for communication between systems.

+ +

SPDY

+ +

SPDY is an attempt to reduce page loading time by opening a single connection per server, keeping it open for subsequent requests, and also by compressing the HTTP headers to reduce the size of requests.

+ +

SPDY is compatible with HTTP/1.1 semantics, and is actually just a different way of performing HTTP requests and responses, by using binary frames instead of a text-based protocol. SPDY also allows the server to send extra responses following a request. This is meant to allow sending the resources associated with the request before the client requests them, saving latency when loading websites.

+ +

SPDY is an experiment that has proven successful and is used as the basis for the HTTP/2.0 standard.

+ +

Browsers make use of TLS Next Protocol Negotiation to upgrade to a SPDY connection seamlessly if the protocol supports it.

+ +

The protocol itself has a few shortcomings which are being fixed in HTTP/2.0.

+ +

HTTP/2.0

+ +

HTTP/2.0 is the long-awaited update to the HTTP/1.1 protocol. It is based on SPDY although a lot has been improved at the time of writing.

+ +

HTTP/2.0 is an asynchronous two-ways communication channel between two endpoints.

+ +

It is planned to be ready late 2014.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/multipart_intro/index.html b/docs/en/cowboy/1.0/guide/multipart_intro/index.html new file mode 100644 index 00000000..3a2f5273 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/multipart_intro/index.html @@ -0,0 +1,198 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Introduction to multipart

+ +

Multipart originates from MIME, an Internet standard that extends the format of emails. Multipart messages are a container for parts of any content-type.

+ +

For example, a multipart message may have a part containing text and a second part containing an image. This is what allows you to attach files to emails.

+ +

In the context of HTTP, multipart is most often used with the multipart/form-data content-type. This is the content-type you have to use when you want browsers to be allowed to upload files through HTML forms.

+ +

Multipart is of course not required for uploading files, it is only required when you want to do so through HTML forms.

+ +

Structure

+ +

A multipart message is a list of parts. Parts may contain either a multipart message or a non-multipart content-type. This allows parts to be arranged in a tree structure, although this is a rare case as far as the Web is concerned.

+ +

Form-data

+ +

In the normal case, when a form is submitted, the browser will use the application/x-www-form-urlencoded content-type. This type is just a list of keys and values and is therefore not fit for uploading files.

+ +

That's where the multipart/form-data content-type comes in. When the form is configured to use this content-type, the browser will use one part of the message for each form field. This means that a file input field will be sent in its own part, but the same applies to all other kinds of fields.

+ +

A form with a text input, a file input and a select choice box will result in a multipart message with three parts, one for each field.

+ +

The browser does its best to determine the content-type of the files it sends this way, but you should not rely on it for determining the contents of the file. Proper investigation of the contents is recommended.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/multipart_req/index.html b/docs/en/cowboy/1.0/guide/multipart_req/index.html new file mode 100644 index 00000000..f6301d83 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/multipart_req/index.html @@ -0,0 +1,261 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Multipart requests

+ +

You can read and parse multipart messages using the Req object directly.

+ +

Cowboy defines two functions that allows you to get information about each part and read their contents.

+ +

Checking the content-type

+ +

While there is a variety of multipart messages, the most common on the Web is multipart/form-data. It's the type of message being sent when an HTML form allows uploading files.

+ +

You can quickly figure out if a multipart message has been sent by parsing the content-type header.

+ + + +

Reading a multipart message

+ +

To read a message you have to iterate over all its parts. Then, for each part, you can inspect its headers and read its body.

+ + + +

Parts do not have a size limit. When a part body is too big, Cowboy will return what it read so far and allow you to continue if you wish to do so.

+ +

The function cow_multipart:form_data/1 can be used to quickly obtain information about a part from a multipart/form-data message. This function will tell you if the part is for a normal field or if it is a file being uploaded.

+ +

This can be used for example to allow large part bodies for files but crash when a normal field is too large.

+ + + +

By default the body chunk Cowboy will return is limited to 8MB. This can of course be overriden. Both functions can take a second argument, the same list of options that will be passed to cowboy_req:body/2 function.

+ +

Skipping unwanted parts

+ +

If you do not want to read a part's body, you can skip it. Skipping is easy. If you do not call the function to read the part's body, Cowboy will automatically skip it when you request the next part.

+ +

The following snippet reads all part headers and skips all bodies:

+ + + +

Similarly, if you start reading the body and it ends up being too big, you can simply continue with the next part, Cowboy will automatically skip what remains.

+ +

Note that the skipping rate may not be adequate for your application. If you observe poor performance when skipping, you might want to consider manually skipping by calling the cowboy_req:part_body/1 function directly.

+ +

And if you started reading the message but decide that you do not need the remaining parts, you can simply stop reading entirely and Cowboy will automatically figure out what to do.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/req/index.html b/docs/en/cowboy/1.0/guide/req/index.html new file mode 100644 index 00000000..0b8bb586 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/req/index.html @@ -0,0 +1,390 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

The Req object

+ +

The Req object is this variable that you will use to obtain information about a request, read the body of the request and send a response.

+ +

A special variable

+ +

While we call it an "object", it is not an object in the OOP sense of the term. In fact it is completely opaque to you and the only way you can perform operations using it is by calling the functions from the cowboy_req module.

+ +

Almost all the calls to the cowboy_req module will return an updated request object. Just like you would keep the updated State variable in a gen_server, you MUST keep the updated Req variable in a Cowboy handler. Cowboy will use this object to know whether a response has been sent when the handler has finished executing.

+ +

The Req object allows accessing both immutable and mutable state. This means that calling some of the functions twice will not produce the same result. For example, when streaming the request body, the function will return the body by chunks, one at a time, until there is none left.

+ +

It also caches the result of operations performed on the immutable state. That means that some calls will give a result much faster when called many times.

+ +

Overview of the cowboy_req interface

+ +

The cowboy_req interface is divided in four groups of functions, each having a well defined return type signature common to the entire group.

+ +

The first group, access functions, will always return {Value, Req}. The group includes all the following functions: binding/{2,3}, bindings/1, body_length/1, cookie/{2,3}, cookies/1, header/{2,3}, headers/1, host/1, host_info/1, host_url/1, meta/{2,3}, method/1, path/1, path_info/1, peer/1, port/1, qs/1, qs_val/{2,3}, qs_vals/1, url/1, version/1.

+ +

The second group, question functions, will always return a boolean(). The group includes the following three functions: has_body/1, has_resp_body/1, has_resp_header/2.

+ +

The third group contains the functions that manipulate the socket or perform operations that may legitimately fail. They may return {Result, Req}, {Result, Value, Req} or {error, atom()}. This includes the following functions: body/{1,2}, body_qs/{1,2}, chunked_reply/{2,3}, parse_header/{2,3}, part/{1,2}, part_body/{1,2} and reply/{2,3,4}. Finally, the group also includes the chunk/2 and continue/1 functions which always return ok.

+ +

The final group modifies the Req object state without performing any immediate operations. As these functions can't fail, they always return a new Req directly. This includes the following functions: compact/1, delete_resp_header/2, set_meta/3, set_resp_body/2, set_resp_body_fun/{2,3}, set_resp_cookie/4, set_resp_header/3.

+ +

This chapter covers most of the first group, plus a few other functions. The next few chapters cover cookies handling, reading the request body and sending a response.

+ +

Request

+ +

When a client performs a request, it first sends a few required values. They are sent differently depending on the protocol being used, but the intent is the same. They indicate to the server the type of action it wants to do and how to locate the resource to perform it on.

+ +

The method identifies the action. Standard methods include GET, HEAD, OPTIONS, PATCH, POST, PUT, DELETE. Method names are case sensitive.

+ + + +

The host, port and path parts of the URL identify the resource being accessed. The host and port information may not be available if the client uses HTTP/1.0.

+ + + +

The version used by the client can of course also be obtained.

+ + + +

Do note however that clients claiming to implement one version of the protocol does not mean they implement it fully, or even properly.

+ +

Bindings

+ +

After routing the request, bindings are available. Bindings are these parts of the host or path that you chose to extract when defining the routes of your application.

+ +

You can fetch a single binding. The value will be undefined if the binding doesn't exist.

+ + + +

If you need a different value when the binding doesn't exist, you can change the default.

+ + + +

You can also obtain all bindings in one call. They will be returned as a list of key/value tuples.

+ + + +

If you used ... at the beginning of the route's pattern for the host, you can retrieve the matched part of the host. The value will be undefined otherwise.

+ + + +

Similarly, if you used ... at the end of the route's pattern for the path, you can retrieve the matched part, or get undefined otherwise.

+ + + +

Query string

+ +

The query string can be obtained directly.

+ + + +

You can also requests only one value.

+ + + +

If that value is optional, you can define a default to simplify your task.

+ + + +

Finally, you can obtain all query string values.

+ + + +

Request URL

+ +

You can reconstruct the full URL of the resource.

+ + + +

You can also obtain only the base of the URL, excluding the path and query string.

+ + + +

Headers

+ +

Cowboy allows you to obtain the header values as string, or parsed into a more meaningful representation.

+ +

This will get the string value of a header.

+ + + +

You can of course set a default in case the header is missing.

+ + + +

And also obtain all headers.

+ + + +

To parse the previous header, simply call parse_header/{2,3} where you would call header/{2,3} otherwise. Note that the return value changes and includes the result of the operation as the first element of the returned tuple. A successful parse returns ok.

+ + + +

When Cowboy doesn't know how to parse the given header, the result of the operation will be undefined and the string value will be returned instead.

+ + + +

When parsing fails, {error, Reason} is returned instead.

+ +

You can of course define a default value. Note that the default value you specify here is the parsed value you'd like to get by default.

+ + + +

The list of known headers and default values is defined in the manual. Also note that the result of parsing is cached, so calling this function multiple times for the same values will not have a significant performance impact.

+ +

Meta

+ +

Cowboy will sometimes associate some meta information with the request. Built-in meta values are listed in the manual for their respective modules.

+ +

This will get a meta value. The returned value will be undefined if it isn't defined.

+ + + +

You can change the default value if needed.

+ + + +

You can also define your own meta values. The name must be an atom().

+ + + +

Peer

+ +

You can obtain the peer address and port number. This is not necessarily the actual IP and port of the client, but rather the one of the machine that connected to the server.

+ + + +

Reducing the memory footprint

+ +

When you are done reading information from the request object and know you are not going to access it anymore, for example when using long-polling or Websocket, you can use the compact/1 function to remove most of the data from the request object and free memory.

+ + + +

You will still be able to send a reply if needed.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/req_body/index.html b/docs/en/cowboy/1.0/guide/req_body/index.html new file mode 100644 index 00000000..b6365a8f --- /dev/null +++ b/docs/en/cowboy/1.0/guide/req_body/index.html @@ -0,0 +1,296 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Reading the request body

+ +

The Req object also allows you to read the request body.

+ +

Because the request body can be of any size, all body reading operations will only work once, as Cowboy will not cache the result of these operations.

+ +

Cowboy will not attempt to read the body until you do. If handler execution ends without reading it, Cowboy will simply skip it.

+ +

Cowboy provides different ways to read the request body. You can read it directly, stream it, but also read and parse in a single call for form urlencoded formats or multipart. All of these except multipart are covered in this chapter. Multipart is covered later on in the guide.

+ +

Check for request body

+ +

You can check whether a body was sent with the request.

+ + + +

It will return true if there is a request body, and false otherwise.

+ +

Note that it is generally safe to assume that a body is sent for POST, PUT and PATCH requests, without having to explicitly check for it.

+ +

Request body length

+ +

You can obtain the body length if it was sent with the request.

+ + + +

The value returned will be undefined if the length couldn't be figured out from the request headers. If there's a body but no length is given, this means that the chunked transfer-encoding was used. You can read chunked bodies by using the stream functions.

+ +

Reading the body

+ +

You can read the whole body directly in one call.

+ + + +

By default, Cowboy will attempt to read up to a size of 8MB. You can override this limit as needed.

+ + + +

You can also disable it.

+ + + +

It is recommended that you do not disable it for public facing websites.

+ +

If the body is larger than the limit, then Cowboy will return a more tuple instead, allowing you to stream it if you would like to.

+ +

Streaming the body

+ +

You can stream the request body by chunks.

+ +

Cowboy returns a more tuple when there is more body to be read, and an ok tuple for the last chunk. This allows you to loop over all chunks.

+ + + +

You can of course set the length option to configure the size of chunks.

+ +

Rate of data transmission

+ +

You can control the rate of data transmission by setting options when calling body functions. This applies not only to the functions described in this chapter, but also to the multipart functions.

+ +

The read_length option defines the maximum amount of data to be received from the socket at once, in bytes.

+ +

The read_timeout option defines the time Cowboy waits before that amount is received, in milliseconds.

+ +

Transfer and content decoding

+ +

Cowboy will by default decode the chunked transfer-encoding if any. It will not decode any content-encoding by default.

+ +

The first time you call a body function you can set the transfer_decode and content_decode options. If the body was already started being read these options are simply ignored.

+ +

The following example shows how to set both options.

+ + + +

Reading a form urlencoded body

+ +

You can directly obtain a list of key/value pairs if the body was sent using the application/x-www-form-urlencoded content-type.

+ + + +

You can then retrieve an individual value from that list.

+ + + +

You should not attempt to match on the list as the order of the values is undefined.

+ +

By default Cowboy will reject bodies with a size above 64KB when using this function. You can override this limit by setting the length option.

+ + + + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/resource_design/index.html b/docs/en/cowboy/1.0/guide/resource_design/index.html new file mode 100644 index 00000000..24977abb --- /dev/null +++ b/docs/en/cowboy/1.0/guide/resource_design/index.html @@ -0,0 +1,294 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Designing a resource handler

+ +

This chapter aims to provide you with a list of questions you must answer in order to write a good resource handler. It is meant to be usable as a step by step guide.

+ +

The service

+ +

Can the service become unavailable, and when it does, can we detect it? For example database connectivity problems may be detected early. We may also have planned outages of all or parts of the system. Implement the service_available callback.

+ +

What HTTP methods does the service implement? Do we need more than the standard OPTIONS, HEAD, GET, PUT, POST, PATCH and DELETE? Are we not using one of those at all? Implement the known_methods callback.

+ +

Type of resource handler

+ +

Am I writing a handler for a collection of resources, or for a single resource?

+ +

The semantics for each of these are quite different. You should not mix collection and single resource in the same handler.

+ +

Collection handler

+ +

Skip this section if you are not doing a collection.

+ +

Is the collection hardcoded or dynamic? For example if you use the route /users for the collection of users then the collection is hardcoded; if you use /forums/:category for the collection of threads then it isn't. When the collection is hardcoded you can safely assume the resource always exists.

+ +

What methods should I implement?

+ +

OPTIONS is used to get some information about the collection. It is recommended to allow it even if you do not implement it, as Cowboy has a default implementation built-in.

+ +

HEAD and GET are used to retrieve the collection. If you allow GET, also allow HEAD as there's no extra work required to make it work.

+ +

POST is used to create a new resource inside the collection. Creating a resource by using POST on the collection is useful when resources may be created before knowing their URI, usually because parts of it are generated dynamically. A common case is some kind of auto incremented integer identifier.

+ +

The next methods are more rarely allowed.

+ +

PUT is used to create a new collection (when the collection isn't hardcoded), or replace the entire collection.

+ +

DELETE is used to delete the entire collection.

+ +

PATCH is used to modify the collection using instructions given in the request body. A PATCH operation is atomic. The PATCH operation may be used for such things as reordering; adding, modifying or deleting parts of the collection.

+ +

Single resource handler

+ +

Skip this section if you are doing a collection.

+ +

What methods should I implement?

+ +

OPTIONS is used to get some information about the resource. It is recommended to allow it even if you do not implement it, as Cowboy has a default implementation built-in.

+ +

HEAD and GET are used to retrieve the resource. If you allow GET, also allow HEAD as there's no extra work required to make it work.

+ +

POST is used to update the resource.

+ +

PUT is used to create a new resource (when it doesn't already exist) or replace the resource.

+ +

DELETE is used to delete the resource.

+ +

PATCH is used to modify the resource using instructions given in the request body. A PATCH operation is atomic. The PATCH operation may be used for adding, removing or modifying specific values in the resource.

+ +

The resource

+ +

Following the above discussion, implement the allowed_methods callback.

+ +

Does the resource always exist? If it may not, implement the resource_exists callback.

+ +

Do I need to authenticate the client before they can access the resource? What authentication mechanisms should I provide? This may include form-based, token-based (in the URL or a cookie), HTTP basic, HTTP digest, SSL certificate or any other form of authentication. Implement the is_authorized callback.

+ +

Do I need fine-grained access control? How do I determine that they are authorized access? Handle that in your is_authorized callback.

+ +

Can access to a resource be forbidden regardless of access being authorized? A simple example of that is censorship of a resource. Implement the forbidden callback.

+ +

Is there any constraints on the length of the resource URI? For example the URI may be used as a key in storage and may have a limit in length. Implement uri_too_long.

+ +

Representations

+ +

What media types do I provide? If text based, what charsets are provided? What languages do I provide?

+ +

Implement the mandatory content_types_provided. Prefix the callbacks with to_ for clarity. For example to_html or to_text.

+ +

Implement the languages_provided or charsets_provided callbacks if applicable.

+ +

Is there any other header that may make the representation of the resource vary? Implement the variances callback.

+ +

Depending on your choices for caching content, you may want to implement one or more of the generate_etag, last_modified and expires callbacks.

+ +

Do I want the user or user agent to actively choose a representation available? Send a list of available representations in the response body and implement the multiple_choices callback.

+ +

Redirections

+ +

Do I need to keep track of what resources were deleted? For example you may have a mechanism where moving a resource leaves a redirect link to its new location. Implement the previously_existed callback.

+ +

Was the resource moved, and is the move temporary? If it is explicitly temporary, for example due to maintenance, implement the moved_temporarily callback. Otherwise, implement the moved_permanently callback.

+ +

The request

+ +

Do we need to perform extra checks to make sure the request is valid? Cowboy will do many checks when receiving the request already, do we need more? Note that this only applies to the request-line and headers of the request, and not the body. Implement malformed_request.

+ +

May there be a request body? Will I know its size? What's the maximum size of the request body I'm willing to accept? Implement valid_entity_length.

+ +

Finally, take a look at the sections corresponding to the methods you are implementing.

+ +

OPTIONS method

+ +

Cowboy by default will send back a list of allowed methods. Do I need to add more information to the response? Implement the options method.

+ +

GET and HEAD methods

+ +

If you implement the methods GET and/or HEAD, you must implement one ProvideResource callback for each content-type returned by the content_types_provided callback.

+ +

PUT, POST and PATCH methods

+ +

If you implement the methods PUT, POST and/or PATCH, you must implement the content_types_accepted callback, and one AcceptResource callback for each content-type it returns. Prefix the AcceptResource callback names with from_ for clarity. For example from_html or from_json.

+ +

Do we want to allow the POST method to create individual resources directly through their URI (like PUT)? Implement the allow_missing_post callback. It is recommended to explicitly use PUT in these cases instead.

+ +

May there be conflicts when using PUT to create or replace a resource? Do we want to make sure that two updates around the same time are not cancelling one another? Implement the is_conflict callback.

+ +

DELETE methods

+ +

If you implement the method DELETE, you must implement the delete_resource callback.

+ +

When delete_resource returns, is the resource completely removed from the server, including from any caching service? If not, and/or if the deletion is asynchronous and we have no way of knowing it has been completed yet, implement the delete_completed callback.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/resp/index.html b/docs/en/cowboy/1.0/guide/resp/index.html new file mode 100644 index 00000000..d61be41b --- /dev/null +++ b/docs/en/cowboy/1.0/guide/resp/index.html @@ -0,0 +1,327 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Sending a response

+ +

The Req object also allows you to send a response.

+ +

You can only send one response. Any other attempt will trigger a crash. The response may be sent in one go or with its body streamed by chunks of arbitrary size.

+ +

You can also set headers or the response body in advance and Cowboy will use them when you finally do reply.

+ +

Reply

+ +

You can send a reply with no particular headers or body. Cowboy will make sure to send the mandatory headers with the response.

+ + + +

You can define headers to be sent with the response. Note that header names must be lowercase. Again, Cowboy will make sure to send the mandatory headers with the response.

+ + + +

You can override headers that Cowboy would send otherwise. Any header set by the user will be used over the ones set by Cowboy. For example, you can advertise yourself as a different server.

+ + + +

We also saw earlier how to force close the connection by overriding the connection header.

+ +

Finally, you can also send a body with the response. Cowboy will automatically set the content-length header if you do. We recommend that you set the content-type header so the client may know how to read the body.

+ + + +

Here is the same example but sending HTML this time.

+ + + +

Note that the reply is sent immediately.

+ +

Chunked reply

+ +

You can also stream the response body. First, you need to initiate the reply by sending the response status code. Then you can send the body in chunks of arbitrary size.

+ + + +

You should make sure to match on ok as an error may be returned.

+ +

While it is possible to send a chunked response without a content-type header, it is still recommended. You can set this header or any other just like for normal replies.

+ + + +

Note that the reply and each chunk following it are sent immediately.

+ +

Preset response headers

+ +

You can define response headers in advance. They will be merged into the headers given in the reply call. Headers in the reply call override preset response headers which override the default Cowboy headers.

+ + + +

You can check if a response header has already been set. This will only check the response headers that you set, and not the ones Cowboy will add when actually sending the reply.

+ + + +

It will return true if the header is defined, and false otherwise.

+ +

Finally, you can also delete a preset response header if needed. If you do, it will not be sent.

+ + + +

Preset response body

+ +

You can set the response body in advance. Note that this body will be ignored if you then choose to send a chunked reply, or if you send a reply with an explicit body.

+ + + +

You can also set a fun that will be called when it is time to send the body. There are three different ways of doing that.

+ +

If you know the length of the body that needs to be sent, you should specify it, as it will help clients determine the remaining download time and allow them to inform the user.

+ + + +

If you do not know the length of the body, you should use a chunked response body fun instead.

+ + + +

Finally, you can also send data on the socket directly, without knowing the length in advance. Cowboy may be forced to close the connection at the end of the response though depending on the protocol capabilities.

+ + + +

Sending files

+ +

You can send files directly from disk without having to read them. Cowboy will use the sendfile syscall when possible, which means that the file is sent to the socket directly from the kernel, which is a lot more performant than doing it from userland.

+ +

Again, it is recommended to set the size of the file if it can be known in advance.

+ + + +

Please see the Ranch guide for more information about sending files.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/rest_cond.png b/docs/en/cowboy/1.0/guide/rest_cond.png new file mode 100644 index 00000000..64cda347 Binary files /dev/null and b/docs/en/cowboy/1.0/guide/rest_cond.png differ diff --git a/docs/en/cowboy/1.0/guide/rest_cond.svg b/docs/en/cowboy/1.0/guide/rest_cond.svg new file mode 100644 index 00000000..542ae17d --- /dev/null +++ b/docs/en/cowboy/1.0/guide/rest_cond.svg @@ -0,0 +1,1656 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + has if-unmodified-since? + has if-none-match? + some text + ... + generate_etag + has if-modified-since? + has if-match? + generate_etag + last_modified + + true + match* + true + not modified* + true + no match* + + + + + false + false, orinvalid + modified* + false + + + + + + 412 precondition failed + + middlewares + + + + + + + + + + + + + + + + + no match* + + + + + + date is in the future? + + + + + + + + + + last_modified + + + + + + 304 not modified + + ... + false, orinvalid + match* + + method is GET/HEAD? + true + false + true + false + true + modified* + not modified* + + + + + + generate_etag + + + + + + expires + + diff --git a/docs/en/cowboy/1.0/guide/rest_conneg.png b/docs/en/cowboy/1.0/guide/rest_conneg.png new file mode 100644 index 00000000..65ecdcf3 Binary files /dev/null and b/docs/en/cowboy/1.0/guide/rest_conneg.png differ diff --git a/docs/en/cowboy/1.0/guide/rest_conneg.svg b/docs/en/cowboy/1.0/guide/rest_conneg.svg new file mode 100644 index 00000000..247567a0 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/rest_conneg.svg @@ -0,0 +1,1135 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + has accept-language? + has accept-charset? + some text + start + charsets_provided + variances + has accept? + content_types_provided + languages_provided + + true + provided* + true + provided* + true + provided* + + + + + false + false + not provided* + false + not provided* + + + + + + 406 not acceptable + + middlewares + + + + + + + + + + + + + + + + + not provided* + + ... + + diff --git a/docs/en/cowboy/1.0/guide/rest_delete.png b/docs/en/cowboy/1.0/guide/rest_delete.png new file mode 100644 index 00000000..56a861c0 Binary files /dev/null and b/docs/en/cowboy/1.0/guide/rest_delete.png differ diff --git a/docs/en/cowboy/1.0/guide/rest_delete.svg b/docs/en/cowboy/1.0/guide/rest_delete.svg new file mode 100644 index 00000000..2f5513cd --- /dev/null +++ b/docs/en/cowboy/1.0/guide/rest_delete.svg @@ -0,0 +1,1718 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + delete_completed + has response body? + some text + conneg + multiple_choices + resource_exists + delete_resource + + true + false + + + + + false + + + + + + middlewares + + + + + true + true + + + + + + cond + + 300 multiple choices + + 200 OK + + + + + + has if-match? + false + + + + + + + + + + previously_existed + + 404 not found + false + + + + + + + + + + moved_permanently + + + + + + 412 precondition failed + true + true* + false + + 301 moved permanently + + + + + + + + + + moved_temporarily + true* + false + + 307 moved temporarily + + 410 gone + + + + + false + + 202 accepted + + 204 no content + true + true + + 500 internal server error + false + true + false + + diff --git a/docs/en/cowboy/1.0/guide/rest_flowcharts/index.html b/docs/en/cowboy/1.0/guide/rest_flowcharts/index.html new file mode 100644 index 00000000..24208561 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/rest_flowcharts/index.html @@ -0,0 +1,304 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

REST flowcharts

+ +

This chapter will explain the REST handler state machine through a number of different diagrams.

+ +

There are four main paths that requests may follow. One for the method OPTIONS; one for the methods GET and HEAD; one for the methods PUT, POST and PATCH; and one for the method DELETE.

+ +

All paths start with the "Start" diagram, and all paths excluding the OPTIONS path go through the "Content negotiation" diagram and optionally the "Conditional requests" diagram if the resource exists.

+ +

The red squares refer to another diagram. The light green squares indicate a response. Other squares may be either a callback or a question answered by Cowboy itself. Green arrows tend to indicate the default behavior if the callback is undefined.

+ +

Start

+ +

All requests start from here.

+ +

+ +

A series of callbacks are called in succession to perform a general checkup of the service, the request line and request headers.

+ +

The request body, if any, is not expected to have been received for any of these steps. It is only processed at the end of the "PUT, POST and PATCH methods" diagram, when all conditions have been met.

+ +

The known_methods and allowed_methods callbacks return a list of methods. Cowboy then checks if the request method is in the list, and stops otherwise.

+ +

The is_authorized callback may be used to check that access to the resource is authorized. Authentication may also be performed as needed. When authorization is denied, the return value from the callback must include a challenge applicable to the requested resource, which will be sent back to the client in the www-authenticate header.

+ +

This diagram is immediately followed by either the "OPTIONS method" diagram when the request method is OPTIONS, or the "Content negotiation" diagram otherwise.

+ +

OPTIONS method

+ +

This diagram only applies to OPTIONS requests.

+ +

+ +

The options callback may be used to add information about the resource, such as media types or languages provided; allowed methods; any extra information. A response body may also be set, although clients should not be expected to read it.

+ +

If the options callback is not defined, Cowboy will send a response containing the list of allowed methods by default.

+ +

Content negotiation

+ +

This diagram applies to all request methods other than OPTIONS. It is executed right after the "Start" diagram is completed.

+ +

+ +

The purpose of these steps is to determine an appropriate representation to be sent back to the client.

+ +

The request may contain any of the accept header; the accept-language header; or the accept-charset header. When present, Cowboy will parse the headers and then call the corresponding callback to obtain the list of provided content-type, language or charset for this resource. It then automatically select the best match based on the request.

+ +

If a callback is not defined, Cowboy will select the content-type, language or charset that the client prefers.

+ +

The content_types_provided also returns the name of a callback for every content-type it accepts. This callback will only be called at the end of the "GET and HEAD methods" diagram, when all conditions have been met.

+ +

The selected content-type, language and charset are saved as meta values in the Req object. You should use the appropriate representation if you set a response body manually (alongside an error code, for example).

+ +

This diagram is immediately followed by the "GET and HEAD methods" diagram, the "PUT, POST and PATCH methods" diagram, or the "DELETE method" diagram, depending on the method.

+ +

GET and HEAD methods

+ +

This diagram only applies to GET and HEAD requests.

+ +

For a description of the cond step, please see the "Conditional requests" diagram.

+ +

+ +

When the resource exists, and the conditional steps succeed, the resource can be retrieved.

+ +

Cowboy prepares the response by first retrieving metadata about the representation, then by calling the ProvideResource callback. This is the callback you defined for each content-types you returned from content_types_provided. This callback returns the body that will be sent back to the client, or a fun if the body must be streamed.

+ +

When the resource does not exist, Cowboy will figure out whether the resource existed previously, and if so whether it was moved elsewhere in order to redirect the client to the new URI.

+ +

The moved_permanently and moved_temporarily callbacks must return the new location of the resource if it was in fact moved.

+ +

PUT, POST and PATCH methods

+ +

This diagram only applies to PUT, POST and PATCH requests.

+ +

For a description of the cond step, please see the "Conditional requests" diagram.

+ +

+ +

When the resource exists, first the conditional steps are executed. When that succeeds, and the method is PUT, Cowboy will call the is_conflict callback. This function can be used to prevent potential race conditions, by locking the resource for example.

+ +

Then all three methods reach the content_types_accepted step that we will describe in a few paragraphs.

+ +

When the resource does not exist, and the method is PUT, Cowboy will check for conflicts and then move on to the content_types_accepted step. For other methods, Cowboy will figure out whether the resource existed previously, and if so whether it was moved elsewhere. If the resource is truly non-existent, the method is POST and the call for allow_missing_post returns true, then Cowboy will move on to the content_types_accepted step. Otherwise the request processing ends there.

+ +

The moved_permanently and moved_temporarily callbacks must return the new location of the resource if it was in fact moved.

+ +

The content_types_accepted returns a list of content-types it accepts, but also the name of a callback for each of them. Cowboy will select the appropriate callback for processing the request body and call it.

+ +

This callback may return one of three different return values.

+ +

If an error occurred while processing the request body, it must return false and Cowboy will send an appropriate error response.

+ +

If the method is POST, then you may return true with an URI of where the resource has been created. This is especially useful for writing handlers for collections.

+ +

Otherwise, return true to indicate success. Cowboy will select the appropriate response to be sent depending on whether a resource has been created, rather than modified, and on the availability of a location header or a body in the response.

+ +

DELETE method

+ +

This diagram only applies to DELETE requests.

+ +

For a description of the cond step, please see the "Conditional requests" diagram.

+ +

+ +

When the resource exists, and the conditional steps succeed, the resource can be deleted.

+ +

Deleting the resource is a two steps process. First the callback delete_resource is executed. Use this callback to delete the resource.

+ +

Because the resource may be cached, you must also delete all cached representations of this resource in the system. This operation may take a while though, so you may return before it finished.

+ +

Cowboy will then call the delete_completed callback. If you know that the resource has been completely deleted from your system, including from caches, then you can return true. If any doubts persist, return false. Cowboy will assume true by default.

+ +

To finish, Cowboy checks if you set a response body, and depending on that, sends the appropriate response.

+ +

When the resource does not exist, Cowboy will figure out whether the resource existed previously, and if so whether it was moved elsewhere in order to redirect the client to the new URI.

+ +

The moved_permanently and moved_temporarily callbacks must return the new location of the resource if it was in fact moved.

+ +

Conditional requests

+ +

This diagram applies to all request methods other than OPTIONS. It is executed right after the resource_exists callback, when the resource exists.

+ +

+ +

A request becomes conditional when it includes either of the if-match header; the if-unmodified-since header; the if-none-match header; or the if-modified-since header.

+ +

If the condition fails, the request ends immediately without any retrieval or modification of the resource.

+ +

The generate_etag and last_modified are called as needed. Cowboy will only call them once and then cache the results for subsequent use.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/rest_get_head.png b/docs/en/cowboy/1.0/guide/rest_get_head.png new file mode 100644 index 00000000..efee892a Binary files /dev/null and b/docs/en/cowboy/1.0/guide/rest_get_head.png differ diff --git a/docs/en/cowboy/1.0/guide/rest_get_head.svg b/docs/en/cowboy/1.0/guide/rest_get_head.svg new file mode 100644 index 00000000..c78e9399 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/rest_get_head.svg @@ -0,0 +1,1523 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + last_modified + ProvideResource + some text + conneg + multiple_choices + resource_exists + generate_etag + expires + + true + false + + + + + false + + + + + + middlewares + + + + + true + true + + + + + + cond + + 300 multiple choices + + 200 OK + + + + + + has if-match? + false + + + + + + + + + + previously_existed + + 404 not found + false + + + + + + + + + + moved_permanently + + + + + + 412 precondition failed + true + true* + false + + 301 moved permanently + + + + + + + + + + moved_temporarily + true* + false + + 307 moved temporarily + + 410 gone + + + + + + diff --git a/docs/en/cowboy/1.0/guide/rest_handlers/index.html b/docs/en/cowboy/1.0/guide/rest_handlers/index.html new file mode 100644 index 00000000..69f2b001 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/rest_handlers/index.html @@ -0,0 +1,289 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

REST handlers

+ +

REST is implemented in Cowboy as a protocol upgrade. Once upgraded, the request is handled as a state machine with many optional callbacks describing the resource and modifying the machine's behavior.

+ +

The REST handler is the recommended way to handle requests.

+ +

Initialization

+ +

First, the init/3 callback is called. This callback is common to all handlers. To use REST for the current request, this function must return an upgrade tuple.

+ + + +

Cowboy will then switch to the REST protocol and start executing the state machine, starting from rest_init/2 if it's defined, and ending with rest_terminate/2 also if defined.

+ +

Methods

+ +

The REST component has code for handling the following HTTP methods: HEAD, GET, POST, PATCH, PUT, DELETE and OPTIONS.

+ +

Other methods can be accepted, however they have no specific callback defined for them at this time.

+ +

Callbacks

+ +

All callbacks are optional. Some may become mandatory depending on what other defined callbacks return. The various flowcharts in the next chapter should be a useful to determine which callbacks you need.

+ +

When the request starts being processed, Cowboy will call the rest_init/2 function if it is defined, with the Req object and the handler options as arguments. This function must return {ok, Req, State} where State is the handler's state that all subsequent callbacks will receive.

+ +

At the end of every request, the special callback rest_terminate/2 will be called if it is defined. It cannot be used to send a reply, and must always return ok.

+ +

All other callbacks are resource callbacks. They all take two arguments, the Req object and the State, and return a three-element tuple of the form {Value, Req, State}.

+ +

The following table summarizes the callbacks and their default values. If the callback isn't defined, then the default value will be used. Please look at the flowcharts to find out the result of each return value.

+ +

All callbacks can also return {halt, Req, State} to stop execution of the request, at which point rest_terminate/2 will be called.

+ +

In the following table, "skip" means the callback is entirely skipped if it is undefined, moving directly to the next step. Similarly, "none" means there is no default value for this callback.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Callback nameDefault value
allowed_methods[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]
allow_missing_posttrue
charsets_providedskip
content_types_acceptednone
content_types_provided[{{<<"text">>, <<"html">>, '*'}, to_html}]
delete_completedtrue
delete_resourcefalse
expiresundefined
forbiddenfalse
generate_etagundefined
is_authorizedtrue
is_conflictfalse
known_content_typetrue
known_methods[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]
languages_providedskip
last_modifiedundefined
malformed_requestfalse
moved_permanentlyfalse
moved_temporarilyfalse
multiple_choicesfalse
optionsok
previously_existedfalse
resource_existstrue
service_availabletrue
uri_too_longfalse
valid_content_headerstrue
valid_entity_lengthtrue
variances[]
+ +

As you can see, Cowboy tries to move on with the request whenever possible by using well thought out default values.

+ +

In addition to these, there can be any number of user-defined callbacks that are specified through content_types_accepted/2 and content_types_provided/2. They can take any name, however it is recommended to use a separate prefix for the callbacks of each function. For example, from_html and to_html indicate in the first case that we're accepting a resource given as HTML, and in the second case that we send one as HTML.

+ +

Meta data

+ +

Cowboy will set informative meta values at various points of the execution. You can retrieve them using cowboy_req:meta/{2,3}. The values are defined in the following table.

+ + + + + + + + + + +
Meta keyDetails
media_typeThe content-type negotiated for the response entity.
languageThe language negotiated for the response entity.
charsetThe charset negotiated for the response entity.
+ +

They can be used to send a proper body with the response to a request that used a method other than HEAD or GET.

+ +

Response headers

+ +

Cowboy will set response headers automatically over the execution of the REST code. They are listed in the following table.

+ + + + + + + + + + + + + + +
Header nameDetails
content-languageLanguage used in the response body
content-typeMedia type and charset of the response body
etagEtag of the resource
expiresExpiration date of the resource
last-modifiedLast modification date for the resource
locationRelative or absolute URI to the requested resource
varyList of headers that may change the representation of the resource
+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/rest_options.png b/docs/en/cowboy/1.0/guide/rest_options.png new file mode 100644 index 00000000..90fd6f06 Binary files /dev/null and b/docs/en/cowboy/1.0/guide/rest_options.png differ diff --git a/docs/en/cowboy/1.0/guide/rest_options.svg b/docs/en/cowboy/1.0/guide/rest_options.svg new file mode 100644 index 00000000..496c050c --- /dev/null +++ b/docs/en/cowboy/1.0/guide/rest_options.svg @@ -0,0 +1,387 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + some text + start + options + 200 OK + + + + + + + middlewares + + diff --git a/docs/en/cowboy/1.0/guide/rest_principles/index.html b/docs/en/cowboy/1.0/guide/rest_principles/index.html new file mode 100644 index 00000000..0be16d14 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/rest_principles/index.html @@ -0,0 +1,238 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

REST principles

+ +

This chapter will attempt to define the concepts behind REST and explain what makes a service RESTful.

+ +

REST is often confused with performing a distinct operation depending on the HTTP method, while using more than the GET and POST methods. That's highly misguided at best.

+ +

We will first attempt to define REST and will look at what it means in the context of HTTP and the Web. For a more in-depth explanation of REST, you can read Roy T. Fielding's dissertation as it does a great job explaining where it comes from and what it achieves.

+ +

REST architecture

+ +

REST is a client-server architecture. The client and the server both have a different set of concerns. The server stores and/or manipulates information and makes it available to the user in an efficient manner. The client takes that information and displays it to the user and/or uses it to perform subsequent requests for information. This separation of concerns allows both the client and the server to evolve independently as it only requires that the interface stays the same.

+ +

REST is stateless. That means the communication between the client and the server always contains all the information needed to perform the request. There is no session state in the server, it is kept entirely on the client's side. If access to a resource requires authentication, then the client needs to authenticate itself with every request.

+ +

REST is cacheable. The client, the server and any intermediary components can all cache resources in order to improve performance.

+ +

REST provides a uniform interface between components. This simplifies the architecture, as all components follow the same rules to speak to one another. It also makes it easier to understand the interactions between the different components of the system. A number of constraints are required to achieve this. They are covered in the rest of the chapter.

+ +

REST is a layered system. Individual components cannot see beyond the immediate layer with which they are interacting. This means that a client connecting to an intermediate component, like a proxy, has no knowledge of what lies beyond. This allows components to be independent and thus easily replaceable or extendable.

+ +

REST optionally provides code on demand. Code may be downloaded to extend client functionality. This is optional however because the client may not be able to download or run this code, and so a REST component cannot rely on it being executed.

+ +

Resources and resource identifiers

+ +

A resource is an abstract concept. In a REST system, any information that can be named may be a resource. This includes documents, images, a collection of resources and any other information. Any information that can be the target of an hypertext link can be a resource.

+ +

A resource is a conceptual mapping to a set of entities. The set of entities evolves over time; a resource doesn't. For example a resource can map to "users who have logged in this past month" and another to "all users". At some point in time they may map to the same set of entities, because all users logged in this past month. But they are still different resources. Similarly, if nobody logged in recently, then the first resource may map to the empty set. This resource exists regardless of the information it maps to.

+ +

Resources are identified by uniform resource identifiers, also known as URIs. Sometimes internationalized resource identifiers, or IRIs, may also be used, but these can be directly translated into a URI.

+ +

In practice we will identify two kinds of resources. Individual resources map to a set of one element, for example "user Joe". Collection of resources map to a set of 0 to N elements, for example "all users".

+ +

Resource representations

+ +

The representation of a resource is a sequence of bytes associated with metadata.

+ +

The metadata comes as a list of key-value pairs, where the name corresponds to a standard that defines the value's structure and semantics. With HTTP, the metadata comes in the form of request or response headers. The headers' structure and semantics are well defined in the HTTP standard. Metadata includes representation metadata, resource metadata and control data.

+ +

The representation metadata gives information about the representation, such as its media type, the date of last modification, or even a checksum.

+ +

Resource metadata could be link to related resources or information about additional representations of the resource.

+ +

Control data allows parameterizing the request or response. For example, we may only want the representation returned if it is more recent than the one we have in cache. Similarly, we may want to instruct the client about how it should cache the representation. This isn't restricted to caching. We may for example want to store a new representation of a resource only if it wasn't modified since we first retrieved it.

+ +

The data format of a representation is also known as the media type. Some media types are intended for direct rendering to the user, while others are intended for automated processing. The media type is a key component of the REST architecture.

+ +

Self-descriptive messages

+ +

Messages must be self-descriptive. That means that the data format of a representation must always come with its media type (and similarly requesting a resource involves choosing the media type of the representation returned). If you are sending HTML, then you must say it is HTML by sending the media type with the representation. In HTTP this is done using the content-type header.

+ +

The media type is often an IANA registered media type, like text/html or image/png, but does not need to be. Exactly two things are important for respecting this constraint: that the media type is well specified, and that the sender and recipient agree about what the media type refers to.

+ +

This means that you can create your own media types, like application/x-mine, and that as long as you write the specifications for it and that both endpoints agree about it then the constraint is respected.

+ +

Hypermedia as the engine of application state

+ +

The last constraint is generally where services that claim to be RESTful fail. Interactions with a server must be entirely driven by hypermedia. The client does not need any prior knowledge of the service in order to use it, other than an entry point and of course basic understanding of the media type of the representations, at the very least enough to find and identify hyperlinks and link relations.

+ +

To give a simple example, if your service only works with the application/json media type then this constraint cannot be respected (as there are no concept of links in JSON) and thus your service isn't RESTful. This is the case for the majority of self-proclaimed REST services.

+ +

On the other hand if you create a JSON based media type that has a concept of links and link relations, then your service might be RESTful.

+ +

Respecting this constraint means that the entirety of the service becomes self-discoverable, not only the resources in it, but also the operations you can perform on it. This makes clients very thin as there is no need to implement anything specific to the service to operate on it.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/rest_put_post_patch.png b/docs/en/cowboy/1.0/guide/rest_put_post_patch.png new file mode 100644 index 00000000..4afca9e9 Binary files /dev/null and b/docs/en/cowboy/1.0/guide/rest_put_post_patch.png differ diff --git a/docs/en/cowboy/1.0/guide/rest_put_post_patch.svg b/docs/en/cowboy/1.0/guide/rest_put_post_patch.svg new file mode 100644 index 00000000..263cc942 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/rest_put_post_patch.svg @@ -0,0 +1,2856 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + some text + conneg + resource_exists + + true + + + + + false + + + + + + middlewares + + + + + true + + + + + + + + + + + + + + + cond + + + + + + has if-match? + false + + + + + + method is POST/PATCH? + true + + + + + + + + + + + + + + + + + + + method is POST? + + 412 precondition failed + + + + + + + + + + + + + + previously_existed + + + + + + 404 not found + false + + + + + + + + + true* + false + + 301 moved permanently + + + + + + + + + + moved_temporarily + true* + false + + 307 moved temporarily + + 400 bad request + + + + + true + + + + + + allow_missing_post + + method is POST? + allow_missing_post + + + + + + method is PUT? + + + + + + + + + + is_conflict + true + + 409 conflict + + + + + + content_types_accepted + + AcceptResource + + + + + + + + + + new resource? + + + + + + + + + + new resource? + + 201 created + + 303 see other + + + + + + + + + + has resp location? + + + + + + + + + + + has resp body? + + + + + + + + + + multiple_choices + false + + 300 multiple choices + + 200 OK + 204 no content + true + + + + + true + + moved_permanently + + 410 gone + false + true + false + false + false + false + + + + + true + + + + + true, URI* + + + + + true + false + true + true + false + true + false + true + false + false + false + + + + + + + + true + + + + + false + true + + diff --git a/docs/en/cowboy/1.0/guide/rest_start.png b/docs/en/cowboy/1.0/guide/rest_start.png new file mode 100644 index 00000000..7f264642 Binary files /dev/null and b/docs/en/cowboy/1.0/guide/rest_start.png differ diff --git a/docs/en/cowboy/1.0/guide/rest_start.svg b/docs/en/cowboy/1.0/guide/rest_start.svg new file mode 100644 index 00000000..d75e1cc6 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/rest_start.svg @@ -0,0 +1,1468 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + uri_too_long + malformed_request + some text + init + is_authorized + forbidden + valid_content_headers + known_content_type + valid_entity_length + ... + service_available + known_methods + allowed_methods + + true + known* + false + allowed* + false + true + false + true + true + true + + + + + false + unknown* + true + unallowed* + true + false* + true + false + false + false + + 503 service unavailable + + + + + + + + + + 501 not implemented + 414 request URI too long + 405 method not allowed + 400 bad request + 401 unauthorized + 403 forbidden + 501 not implemented + 415 unsupported media type + 413 request entity too large + + middlewares + + diff --git a/docs/en/cowboy/1.0/guide/routing/index.html b/docs/en/cowboy/1.0/guide/routing/index.html new file mode 100644 index 00000000..9f0923f0 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/routing/index.html @@ -0,0 +1,365 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Routing

+ +

Cowboy does nothing by default.

+ +

To make Cowboy useful, you need to map URLs to Erlang modules that will handle the requests. This is called routing.

+ +

When Cowboy receives a request, it tries to match the requested host and path to the resources given in the dispatch rules. If it matches, then the associated Erlang code will be executed.

+ +

Routing rules are given per host. Cowboy will first match on the host, and then try to find a matching path.

+ +

Routes need to be compiled before they can be used by Cowboy.

+ +

Structure

+ +

The general structure for the routes is defined as follow.

+ + + +

Each host contains matching rules for the host along with optional constraints, and a list of routes for the path component.

+ + + +

The list of routes for the path component is defined similar to the list of hosts.

+ + + +

Finally, each path contains matching rules for the path along with optional constraints, and gives us the handler module to be used along with options that will be given to it on initialization.

+ + + +

Continue reading to learn more about the match syntax and the optional constraints.

+ +

Match syntax

+ +

The match syntax is used to associate host names and paths with their respective handlers.

+ +

The match syntax is the same for host and path with a few subtleties. Indeed, the segments separator is different, and the host is matched starting from the last segment going to the first. All examples will feature both host and path match rules and explain the differences when encountered.

+ +

Excluding special values that we will explain at the end of this section, the simplest match value is a host or a path. It can be given as either a string() or a binary().

+ + + +

As you can see, all paths defined this way must start with a slash character. Note that these two paths are identical as far as routing is concerned.

+ + + +

Hosts with and without a trailing dot are equivalent for routing. Similarly, hosts with and without a leading dot are also equivalent.

+ + + +

It is possible to extract segments of the host and path and to store the values in the Req object for later use. We call these kind of values bindings.

+ +

The syntax for bindings is very simple. A segment that begins with the : character means that what follows until the end of the segment is the name of the binding in which the segment value will be stored.

+ + + +

If these two end up matching when routing, you will end up with two bindings defined, subdomain and name, each containing the segment value where they were defined. For example, the URL http://test.example.org/hats/wild_cowboy_legendary/prices will result in having the value test bound to the name subdomain and the value wild_cowboy_legendary bound to the name name. They can later be retrieved using cowboy_req:binding/{2,3}. The binding name must be given as an atom.

+ +

There is a special binding name you can use to mimic the underscore variable in Erlang. Any match against the _ binding will succeed but the data will be discarded. This is especially useful for matching against many domain names in one go.

+ + + +

Similarly, it is possible to have optional segments. Anything between brackets is optional.

+ + + +

You can also have imbricated optional segments.

+ + + +

You can retrieve the rest of the host or path using [...]. In the case of hosts it will match anything before, in the case of paths anything after the previously matched segments. It is a special case of optional segments, in that it can have zero, one or many segments. You can then find the segments using cowboy_req:host_info/1 and cowboy_req:path_info/1 respectively. They will be represented as a list of segments.

+ + + +

If a binding appears twice in the routing rules, then the match will succeed only if they share the same value. This copies the Erlang pattern matching behavior.

+ + + +

This is also true when an optional segment is present. In this case the two values must be identical only if the segment is available.

+ + + +

If a binding is defined in both the host and path, then they must also share the same value.

+ + + +

Finally, there are two special match values that can be used. The first is the atom '_' which will match any host or path.

+ + + +

The second is the special host match "*" which will match the wildcard path, generally used alongside the OPTIONS method.

+ + + +

Constraints

+ +

After the matching has completed, the resulting bindings can be tested against a set of constraints. Constraints are only tested when the binding is defined. They run in the order you defined them. The match will succeed only if they all succeed.

+ +

They are always given as a two or three elements tuple, where the first element is the name of the binding, the second element is the constraint's name, and the optional third element is the constraint's arguments.

+ +

The following constraints are currently defined:

+ +
    +
  • {Name, int}
    • +
  • {Name, function, fun ((Value) -> true | {true, NewValue} | false)}
    • +
+ +

The int constraint will check if the binding is a binary string representing an integer, and if it is, will convert the value to integer.

+ +

The function constraint will pass the binding value to a user specified function that receives the binary value as its only argument and must return whether it fulfills the constraint, optionally modifying the value. The value thus returned can be of any type.

+ +

Note that constraint functions SHOULD be pure and MUST NOT crash.

+ +

Compilation

+ +

The structure defined in this chapter needs to be compiled before it is passed to Cowboy. This allows Cowboy to efficiently lookup the correct handler to run instead of having to parse the routes repeatedly.

+ +

This can be done with a simple call to cowboy_router:compile/1.

+ + + +

Note that this function will return {error, badarg} if the structure given is incorrect.

+ +

Live update

+ +

You can use the cowboy:set_env/3 function for updating the dispatch list used by routing. This will apply to all new connections accepted by the listener.

+ + + +

Note that you need to compile the routes before updating.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/static_handlers/index.html b/docs/en/cowboy/1.0/guide/static_handlers/index.html new file mode 100644 index 00000000..98e9c833 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/static_handlers/index.html @@ -0,0 +1,280 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Static handler

+ +

The static handler is a built-in REST handler for serving files. It is available as a convenience and provides a quick solution for serving files during development.

+ +

For systems in production, consider using one of the many Content Distribution Network (CDN) available on the market, as they are the best solution for serving files. They are covered in the next chapter. If you decide against using a CDN solution, then please look at the chapter after that, as it explains how to efficiently serve static files on your own.

+ +

The static handler can serve either one file or all files from a given directory. It can also send etag headers for client-side caching.

+ +

To use the static file handler, simply add routes for it with the appropriate options.

+ +

Serve one file

+ +

You can use the static handler to serve one specific file from an application's private directory. This is particularly useful to serve an index.html file when the client requests the / path, for example. The path configured is relative to the given application's private directory.

+ +

The following rule will serve the file static/index.html from the application my_app's priv directory whenever the path / is accessed.

+ + + +

You can also specify the absolute path to a file, or the path to the file relative to the current directory.

+ + + +

Serve all files from a directory

+ +

You can also use the static handler to serve all files that can be found in the configured directory. The handler will use the path_info information to resolve the file location, which means that your route must end with a [...] pattern for it to work. All files are served, including the ones that may be found in subfolders.

+ +

You can specify the directory relative to an application's private directory.

+ +

The following rule will serve any file found in the application my_app's priv directory inside the static/assets folder whenever the requested path begins with /assets/.

+ + + +

You can also specify the absolute path to the directory or set it relative to the current directory.

+ + + +

Customize the mimetype detection

+ +

By default, Cowboy will attempt to recognize the mimetype of your static files by looking at the extension.

+ +

You can override the function that figures out the mimetype of the static files. It can be useful when Cowboy is missing a mimetype you need to handle, or when you want to reduce the list to make lookups faster. You can also give a hard-coded mimetype that will be used unconditionally.

+ +

Cowboy comes with two functions built-in. The default function only handles common file types used when building Web applications. The other function is an extensive list of hundreds of mimetypes that should cover almost any need you may have. You can of course create your own function.

+ +

To use the default function, you should not have to configure anything, as it is the default. If you insist, though, the following will do the job.

+ + + +

As you can see, there is an optional field that may contain a list of less used options, like mimetypes or etag. All option types have this optional field.

+ +

To use the function that will detect almost any mimetype, the following configuration will do.

+ + + +

You probably noticed the pattern by now. The configuration expects a module and a function name, so you can use any of your own functions instead.

+ + + +

The function that performs the mimetype detection receives a single argument that is the path to the file on disk. It is recommended to return the mimetype in tuple form, although a binary string is also allowed (but will require extra processing). If the function can't figure out the mimetype, then it should return {<<"application">>, <<"octet-stream">>, []}.

+ +

When the static handler fails to find the extension in the list, it will send the file as application/octet-stream. A browser receiving such file will attempt to download it directly to disk.

+ +

Finally, the mimetype can be hard-coded for all files. This is especially useful in combination with the file and priv_file options as it avoids needless computation.

+ + + +

Generate an etag

+ +

By default, the static handler will generate an etag header value based on the size and modified time. This solution can not be applied to all systems though. It would perform rather poorly over a cluster of nodes, for example, as the file metadata will vary from server to server, giving a different etag on each server.

+ +

You can however change the way the etag is calculated.

+ + + +

This function will receive three arguments: the path to the file on disk, the size of the file and the last modification time. In a distributed setup, you would typically use the file path to retrieve an etag value that is identical across all your servers.

+ +

You can also completely disable etag handling.

+ + + + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/upgrade_protocol/index.html b/docs/en/cowboy/1.0/guide/upgrade_protocol/index.html new file mode 100644 index 00000000..41aa090e --- /dev/null +++ b/docs/en/cowboy/1.0/guide/upgrade_protocol/index.html @@ -0,0 +1,200 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Protocol upgrades

+ +

Cowboy features many different handlers, each for different purposes. All handlers have a common entry point: the init/3 function.

+ +

The default handler type is the simple HTTP handler.

+ +

To switch to a different protocol, you must perform a protocol upgrade. This is what is done for Websocket and REST and is explained in details in the respective chapters.

+ +

You can also create your own protocol on top of Cowboy and use the protocol upgrade mechanism to switch to it.

+ +

For example, if you create the my_protocol module implementing the cowboy_sub_protocol behavior, then you can upgrade to it by simply returning the module name from init/3.

+ + + +

The cowboy_sub_protocol behavior only requires one callback, upgrade/4. It receives the Req object, the middleware environment, and the handler and options for this request. This is the same module as the init/3 function and the same options that were passed to it.

+ + + +

This callback is expected to behave like a middleware. Please see the corresponding chapter for more information.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/ws_handlers/index.html b/docs/en/cowboy/1.0/guide/ws_handlers/index.html new file mode 100644 index 00000000..e1d3d9a2 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/ws_handlers/index.html @@ -0,0 +1,327 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

Handling Websocket connections

+ +

A special handler is required for handling Websocket connections. Websocket handlers allow you to initialize the connection, handle incoming frames from the socket, handle incoming Erlang messages and then clean up on termination.

+ +

Websocket handlers essentially act as a bridge between the client and the Erlang system. They will typically do little more than socket communication and decoding/encoding of frames.

+ +

Initialization

+ +

First, the init/3 callback is called. This callback is common to all handlers. To establish a Websocket connection, this function must return an upgrade tuple.

+ + + +

It is also possible to return an update Req object and options using the longer form of this tuple.

+ + + +

Upon receiving this tuple, Cowboy will switch to the code that handles Websocket connections. It does not immediately perform the handshake however. First, it calls the websocket_init/3 callback.

+ +

This function must be used to initialize the state, and can also be used to register the process, start a timer, etc. As long as the function returns an ok tuple, then Cowboy performs the Websocket handshake.

+ + + +

A shutdown tuple can be returned to refuse to perform the handshake. When doing so, Cowboy will send a 400 Bad Request response to the client and close the connection.

+ + + +

It is also possible to perform a cowboy_req:reply/{2,3,4} before returning a shutdown tuple, allowing you to override the response sent back to the client.

+ +

Note that browser support for handling Websocket connection failures may vary.

+ +

If the sec-websocket-protocol header was sent with the request for establishing a Websocket connection, then the Websocket handler must select one of these subprotocol and send it back to the client, otherwise the client might decide to close the connection, assuming no correct subprotocol was found.

+ + + +

It is not recommended to wait too long inside the websocket_init/3 function. Any extra initialization may be done after returning by sending yourself a message before doing anything. Any message sent to self() from websocket_init/3 is guaranteed to arrive before any frames from the client.

+ +

It is also very easy to ensure that this message arrives before any message from other processes by sending it before registering or enabling timers.

+ + + +

Handling frames from the client

+ +

Cowboy will call websocket_handle/3 whenever a text, binary, ping or pong frame arrives from the client. Note that in the case of ping and pong frames, no action is expected as Cowboy automatically replies to ping frames.

+ +

The handler can decide to send frames to the socket, shutdown or just continue without sending anything.

+ +

The following snippet echoes back any text frame received and ignores all others.

+ + + +

Handling Erlang messages

+ +

Cowboy will call websocket_info/3 whenever an Erlang message arrives.

+ +

The handler can decide to send frames to the socket, shutdown or just continue without sending anything.

+ +

The following snippet forwards any log message to the socket and ignores all others.

+ + + +

Sending frames to the socket

+ +

Cowboy allows sending either a single frame or a list of frames to the socket. Any frame can be sent: text, binary, ping, pong or close frames.

+ +

The following example sends three frames using a single reply tuple.

+ + + +

Note that the payload for text and binary frames is of type iodata(), meaning it can be either a binary() or an iolist().

+ +

Sending a close frame will immediately initiate the closing of the Websocket connection. Be aware that any additional frames sent by the client or any Erlang messages waiting to be received will not be processed. Also note that when replying a list of frames that includes close, any frame found after the close frame will not be sent.

+ +

Ping and timeout

+ +

The biggest performance improvement you can do when dealing with a huge number of Websocket connections is to reduce the number of timers that are started on the server. A common use of timers when dealing with connections is for sending a ping every once in a while. This should be done exclusively on the client side. Indeed, a server handling one million Websocket connections will perform a lot better when it doesn't have to handle one million extra timers too!

+ +

Cowboy will automatically respond to ping frames sent by the client. It will still forward the frame to the handler for informative purpose, but no further action is required.

+ +

Cowboy can be configured to automatically close the Websocket connection when no data arrives on the socket. It is highly recommended to configure a timeout for it, as otherwise you may end up with zombie "half-connected" sockets that may leave the process alive forever.

+ +

A good timeout value is 60 seconds.

+ + + +

This value cannot be changed once it is set. It defaults to infinity.

+ +

Hibernate

+ +

Most tuples returned from handler callbacks can include an extra value hibernate. After doing any necessary operations following the return of the callback, Cowboy will hibernate the process.

+ +

It is highly recommended to hibernate processes that do not handle much traffic. It is a good idea to hibernate all connections by default and investigate only when you start noticing increased CPU usage.

+ +

Supporting older browsers

+ +

Unfortunately Websocket is a relatively recent technology, which means that not all browsers support it. A library like Bullet can be used to emulate Websocket connections on older browsers.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/guide/ws_protocol/index.html b/docs/en/cowboy/1.0/guide/ws_protocol/index.html new file mode 100644 index 00000000..05d2bdeb --- /dev/null +++ b/docs/en/cowboy/1.0/guide/ws_protocol/index.html @@ -0,0 +1,194 @@ + + + + + Nine Nines Support: Cowboy User Guide + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

The Websocket protocol

+ +

This chapter explains what Websocket is and why it is a vital component of soft realtime Web applications.

+ +

Description

+ +

Websocket is an extension to HTTP that emulates plain TCP connections between the client, typically a Web browser, and the server. It uses the HTTP Upgrade mechanism to establish the connection.

+ +

Websocket connections are asynchronous, unlike HTTP. This means that not only can the client send frames to the server at any time, but the server can also send frames to the client without the client initiating anything other than the Websocket connection itself. This allows the server to push data to the client directly.

+ +

Websocket is an IETF standard. Cowboy supports the standard and all drafts that were previously implemented by browsers, excluding the initial flawed draft sometimes known as "version 0".

+ +

Implementation

+ +

Cowboy implements Websocket as a protocol upgrade. Once the upgrade is performed from the init/3 callback, Cowboy switches to Websocket. Please consult the next chapter for more information on initiating and handling Websocket connections.

+ +

The implementation of Websocket in Cowboy is validated using the Autobahn test suite, which is an extensive suite of tests covering all aspects of the protocol. Cowboy passes the suite with 100% success, including all optional tests.

+ +

Cowboy's Websocket implementation also includes the x-webkit-deflate-frame compression draft which is being used by some browsers to reduce the size of data being transmitted. Cowboy will automatically use compression as long as the compress protocol option is set when starting the listener.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/index.html b/docs/en/cowboy/1.0/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/cowboy/1.0/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/cowboy/1.0/manual/cowboy/index.html b/docs/en/cowboy/1.0/manual/cowboy/index.html new file mode 100644 index 00000000..892103f5 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy/index.html @@ -0,0 +1,273 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy

+ +

The cowboy module provides convenience functions for manipulating Ranch listeners.

+ +

Types

+ +

http_headers() = [{binary(), iodata()}]

+ +

HTTP headers as a list of key/values.

+ +

http_status() = non_neg_integer() | binary()

+ +

HTTP status.

+ +

A binary status can be used to set a custom message.

+ +

http_version() = 'HTTP/1.1' | 'HTTP/1.0'

+ +

HTTP version.

+ +

onrequest_fun() = fun((cowboy_req:req()) -> cowboy_req:req())

+ +

Fun called immediately after receiving a request.

+ +

It can perform any operation on the Req object, including reading the request body or replying. If a reply is sent, the processing of the request ends here, before any middleware is executed.

+ +

onresponse_fun() = fun((http_status(), http_headers(), iodata(), cowboy_req:req()) -> cowboy_req:req())

+ +

Fun called immediately before sending the response.

+ +

It can perform any operation on the Req object, including reading the request body or replying. If a reply is sent, it overrides the reply initially sent. The callback will not be called again for the new reply.

+ +

Exports

+ +

start_http(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()}

+ +

Types:

+ +
    +
  • Ref = ranch:ref()
    • +
  • NbAcceptors = non_neg_integer()
    • +
  • TransOpts = ranch_tcp:opts()
    • +
  • ProtoOpts = cowboy_protocol:opts()
    • +
+ +

Start listening for HTTP connections. Returns the pid for this listener's supervisor.

+ +

start_https(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()}

+ +

Types:

+ +
    +
  • Ref = ranch:ref()
    • +
  • NbAcceptors = non_neg_integer()
    • +
  • TransOpts = ranch_ssl:opts()
    • +
  • ProtoOpts = cowboy_protocol:opts()
    • +
+ +

Start listening for HTTPS connections. Returns the pid for this listener's supervisor.

+ +

start_spdy(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()}

+ +

Types:

+ +
    +
  • Ref = ranch:ref()
    • +
  • NbAcceptors = non_neg_integer()
    • +
  • TransOpts = ranch_ssl:opts()
    • +
  • ProtoOpts = cowboy_spdy:opts()
    • +
+ +

Start listening for SPDY connections. Returns the pid for this listener's supervisor.

+ +

stop_listener(Ref) -> ok | {error, not_found}

+ +

Types:

+ +
    +
  • Ref = ranch:ref()
    • +
+ +

Stop a previously started listener.

+ +

set_env(Ref, Name, Value) -> ok

+ +

Types:

+ +
    +
  • Ref = ranch:ref()
    • +
  • Name = atom()
    • +
  • Value = any()
    • +
+ +

Set or update an environment value for an already running listener. This will take effect on all subsequent connections.

+ +

See also

+ +

The Ranch guide provides detailed information about how listeners work.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_app/index.html b/docs/en/cowboy/1.0/manual/cowboy_app/index.html new file mode 100644 index 00000000..bd353e67 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_app/index.html @@ -0,0 +1,188 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

The Cowboy Application

+ +

Small, fast, modular HTTP server.

+ +

Dependencies

+ +

The cowboy application uses the Erlang applications ranch for listening and accepting TCP connections, crypto for establishing Websocket connections, and cowlib for parsing and building messages for Web protocols. These dependencies must be loaded for the cowboy application to work. In an embedded environment this means that they need to be started with the application:start/{1,2} function before the cowboy application is started.

+ +

The cowboy application also uses the Erlang applications asn1, public_key and ssl when listening for HTTPS connections. These are started automatically if they weren't before.

+ +

Environment

+ +

The cowboy application does not define any application environment configuration parameters.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_handler/index.html b/docs/en/cowboy/1.0/manual/cowboy_handler/index.html new file mode 100644 index 00000000..8761e46d --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_handler/index.html @@ -0,0 +1,199 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_handler

+ +

The cowboy_handler middleware executes the handler passed through the environment values handler and handler_opts, and adds the result of this execution to the environment as the value result, indicating that the request has been handled and received a response.

+ +

Environment input:

+ +
    +
  • handler = module()
    • +
  • handler_opts = any()
    • +
+ +

Environment output:

+ +
    +
  • result = ok
    • +
+ +

Types

+ +

None.

+ +

Exports

+ +

None.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_http_handler/index.html b/docs/en/cowboy/1.0/manual/cowboy_http_handler/index.html new file mode 100644 index 00000000..1791c88e --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_http_handler/index.html @@ -0,0 +1,229 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_http_handler

+ +

The cowboy_http_handler behaviour defines the interface used by plain HTTP handlers.

+ +

Unless noted otherwise, the callbacks will be executed sequentially.

+ +

Types

+ +

None.

+ +

Callbacks

+ +

init({TransportName, ProtocolName}, Req, Opts) -> {ok, Req, State} | {shutdown, Req, State}

+ +

Types:

+ +
    +
  • TransportName = tcp | ssl | atom()
    • +
  • ProtocolName = http | atom()
    • +
  • Req = cowboy_req:req()
    • +
  • Opts = any()
    • +
  • State = any()
    • +
+ +

Initialize the state for this request.

+ +

The shutdown return value can be used to skip the handle/2 call entirely.

+ +

handle(Req, State) -> {ok, Req, State}

+ +

Types:

+ +
    +
  • Req = cowboy_req:req()
    • +
  • State = any()
    • +
+ +

Handle the request.

+ +

This callback is where the request is handled and a response should be sent. If a response is not sent, Cowboy will send a 204 No Content response automatically.

+ +

terminate(Reason, Req, State) -> ok

+ +

Types:

+ +
    +
  • Reason = {normal, shutdown} | {error, atom()}
    • +
  • Req = cowboy_req:req()
    • +
  • State = any()
    • +
+ +

Perform any necessary cleanup of the state.

+ +

This callback should release any resource currently in use, clear any active timer and reset the process to its original state, as it might be reused for future requests sent on the same connection. Typical plain HTTP handlers rarely need to use it.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_loop_handler/index.html b/docs/en/cowboy/1.0/manual/cowboy_loop_handler/index.html new file mode 100644 index 00000000..94fa6f32 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_loop_handler/index.html @@ -0,0 +1,245 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_loop_handler

+ +

The cowboy_loop_handler behaviour defines the interface used by HTTP handlers that do not send a response directly, instead requiring a receive loop to process Erlang messages.

+ +

This interface is best fit for long-polling types of requests.

+ +

The init/3 callback will always be called, followed by zero or more calls to info/3. The terminate/3 callback will always be called last.

+ +

Types

+ +

None.

+ +

Callbacks

+ +

init({TransportName, ProtocolName}, Req, Opts) -> {loop, Req, State} | {loop, Req, State, hibernate} | {loop, Req, State, Timeout} | {loop, Req, State, Timeout, hibernate} | {shutdown, Req, State}

+ +

Types:

+ +
    +
  • TransportName = tcp | ssl | atom()
    • +
  • ProtocolName = http | atom()
    • +
  • Req = cowboy_req:req()
    • +
  • Opts = any()
    • +
  • State = any()
    • +
  • Timeout = timeout()
    • +
+ +

Initialize the state for this request.

+ +

This callback will typically be used to register this process to an event manager or a message queue in order to receive the messages the handler wants to process.

+ +

The receive loop will run for a duration of up to Timeout milliseconds after it last received data from the socket, at which point it will stop and send a 204 No Content reply. By default this value is set to infinity. It is recommended to either set this value or ensure by any other mechanism that the handler will be closed after a certain period of inactivity.

+ +

The hibernate option will hibernate the process until it starts receiving messages.

+ +

The shutdown return value can be used to skip the receive loop entirely.

+ +

info(Info, Req, State) -> {ok, Req, State} | {loop, Req, State} | {loop, Req, State, hibernate}

+ +

Types:

+ +
    +
  • Info = any()
    • +
  • Req = cowboy_req:req()
    • +
  • State = any()
    • +
+ +

Handle the Erlang message received.

+ +

This function will be called every time an Erlang message has been received. The message can be any Erlang term.

+ +

The ok return value can be used to stop the receive loop, typically because a response has been sent.

+ +

The hibernate option will hibernate the process until it receives another message.

+ +

terminate(Reason, Req, State) -> ok

+ +

Types:

+ +
    +
  • Reason = {normal, shutdown} | {normal, timeout} | {error, closed} | {error, overflow} | {error, atom()}
    • +
  • Req = cowboy_req:req()
    • +
  • State = any()
    • +
+ +

Perform any necessary cleanup of the state.

+ +

This callback will typically unregister from any event manager or message queue it registered to in init/3.

+ +

This callback should release any resource currently in use, clear any active timer and reset the process to its original state, as it might be reused for future requests sent on the same connection.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_middleware/index.html b/docs/en/cowboy/1.0/manual/cowboy_middleware/index.html new file mode 100644 index 00000000..5c9189f1 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_middleware/index.html @@ -0,0 +1,213 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_middleware

+ +

The cowboy_middleware behaviour defines the interface used by Cowboy middleware modules.

+ +

Middlewares process the request sequentially in the order they are configured.

+ +

Types

+ +

env() = [{atom(), any()}]

+ +

The environment variable.

+ +

One is created for every request. It is passed to each middleware module executed and subsequently returned, optionally with its contents modified.

+ +

Callbacks

+ +

execute(Req, Env) -> {ok, Req, Env} | {suspend, Module, Function, Args} | {halt, Req} | {error, StatusCode, Req}

+ +

Types:

+ +
    +
  • Req = cowboy_req:req()
    • +
  • Env = env()
    • +
  • Module = module()
    • +
  • Function = atom()
    • +
  • Args = [any()]
    • +
  • StatusCode = cowboy:http_status()
    • +
+ +

Execute the middleware.

+ +

The ok return value indicates that everything went well and that Cowboy should continue processing the request. A response may or may not have been sent.

+ +

The suspend return value will hibernate the process until an Erlang message is received. Note that when resuming, any previous stacktrace information will be gone.

+ +

The halt return value stops Cowboy from doing any further processing of the request, even if there are middlewares that haven't been executed yet. The connection may be left open to receive more requests from the client.

+ +

The error return value sends an error response identified by the StatusCode and then proceeds to terminate the connection. Middlewares that haven't been executed yet will not be called.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html b/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html new file mode 100644 index 00000000..89e549c1 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_protocol/index.html @@ -0,0 +1,244 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_protocol

+ +

The cowboy_protocol module implements HTTP/1.1 and HTTP/1.0 as a Ranch protocol.

+ +

Types

+ +

opts() = [{compress, boolean()} | {env, cowboy_middleware:env()} | {max_empty_lines, non_neg_integer()} | {max_header_name_length, non_neg_integer()} | {max_header_value_length, non_neg_integer()} | {max_headers, non_neg_integer()} | {max_keepalive, non_neg_integer()} | {max_request_line_length, non_neg_integer()} | {middlewares, [module()]} | {onrequest, cowboy:onrequest_fun()} | {onresponse, cowboy:onresponse_fun()} | {timeout, timeout()}]

+ +

Configuration for the HTTP protocol handler.

+ +

This configuration is passed to Cowboy when starting listeners using cowboy:start_http/4 or cowboy:start_https/4 functions.

+ +

It can be updated without restarting listeners using the Ranch functions ranch:get_protocol_options/1 and ranch:set_protocol_options/2.

+ +

Option descriptions

+ +

The default value is given next to the option name.

+ +

compress (false)

+ +

When enabled, Cowboy will attempt to compress the response body.

+ +

env ([{listener, Ref}])

+ +

Initial middleware environment.

+ +

max_empty_lines (5)

+ +

Maximum number of empty lines before a request.

+ +

max_header_name_length (64)

+ +

Maximum length of header names.

+ +

max_header_value_length (4096)

+ +

Maximum length of header values.

+ +

max_headers (100)

+ +

Maximum number of headers allowed per request.

+ +

max_keepalive (100)

+ +

Maximum number of requests allowed per connection.

+ +

max_request_line_length (4096)

+ +

Maximum length of the request line.

+ +

middlewares ([cowboy_router, cowboy_handler])

+ +

List of middlewares to execute for every requests.

+ +

onrequest (undefined)

+ +

Fun called every time a request is received.

+ +

onresponse (undefined)

+ +

Fun called every time a response is sent.

+ +

timeout (5000)

+ +

Time in ms with no requests before Cowboy closes the connection.

+ +

Exports

+ +

None.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_req/index.html b/docs/en/cowboy/1.0/manual/cowboy_req/index.html new file mode 100644 index 00000000..b3e122d4 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_req/index.html @@ -0,0 +1,854 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_req

+ +

The cowboy_req module provides functions to access, manipulate and respond to requests.

+ +

The functions in this module follow patterns for their return types, based on the kind of function.

+ +
    +
  • access: {Value, Req}
    • +
  • action: {Result, Req} | {Result, Value, Req} | {error, atom()}
    • +
  • modification: Req
    • +
  • question: boolean()
    • +
+ +

The only exception is the chunk/2 function which may return ok.

+ +

Whenever Req is returned, you must use this returned value and ignore any previous you may have had. This value contains various state informations which are necessary for Cowboy to do some lazy evaluation or cache results where appropriate.

+ +

All functions which perform an action should only be called once. This includes reading the request body or replying. Cowboy will generally throw an error on the second call.

+ +

It is highly discouraged to pass the Req object to another process. Doing so and calling cowboy_req functions from it leads to undefined behavior.

+ +

Types

+ +

body_opts() = [{continue, boolean()} | {length, non_neg_integer()} | {read_length, non_neg_integer()} | {read_timeout, timeout()} | {transfer_decode, transfer_decode_fun(), any()} | {content_decode, content_decode_fun()}]

+ +

Request body reading options.

+ + + +

Cookie options.

+ +

req() - opaque to the user

+ +

The Req object.

+ +

All functions in this module receive a Req as argument, and most of them return a new object labelled Req2 in the function descriptions below.

+ + + +

binding(Name, Req) -> binding(Name, Req, undefined)

+ +

binding(Name, Req, Default) -> {Value, Req2}

+ +

Types:

+ +
    +
  • Name = atom()
    • +
  • Default = any()
    • +
  • Value = any() | Default
    • +
+ +

Return the value for the given binding.

+ +

By default the value is a binary, however constraints may change the type of this value (for example automatically converting numbers to integer).

+ +

bindings(Req) -> {[{Name, Value}], Req2}

+ +

Types:

+ +
    +
  • Name = atom()
    • +
  • Value = any()
    • +
+ +

Return all bindings.

+ +

By default the value is a binary, however constraints may change the type of this value (for example automatically converting numbers to integer).

+ + + + + +

Types:

+ +
    +
  • Name = binary()
    • +
  • Default = any()
    • +
  • Value = binary() | Default
    • +
+ +

Return the value for the given cookie.

+ +

Cookie names are case sensitive.

+ +

cookies(Req) -> {[{Name, Value}], Req2}

+ +

Types:

+ +
    +
  • Name = binary()
    • +
  • Value = binary()
    • +
+ +

Return all cookies.

+ + + + + +

Types:

+ +
    +
  • Name = binary()
    • +
  • Default = any()
    • +
  • Value = binary() | Default
    • +
+ +

Return the value for the given header.

+ +

While header names are case insensitive, this function expects the name to be a lowercase binary.

+ +

headers(Req) -> {Headers, Req2}

+ +

Types:

+ +
    +
  • Headers = cowboy:http_headers()
    • +
+ +

Return all headers.

+ +

host(Req) -> {Host, Req2}

+ +

Types:

+ +
    +
  • Host = binary()
    • +
+ +

Return the requested host.

+ +

host_info(Req) -> {HostInfo, Req2}

+ +

Types:

+ +
    +
  • HostInfo = cowboy_router:tokens() | undefined
    • +
+ +

Return the extra tokens from matching against ... during routing.

+ +

host_url(Req) -> {HostURL, Req2}

+ +

Types:

+ +
    +
  • HostURL = binary() | undefined
    • +
+ +

Return the requested URL excluding the path component.

+ +

This function will always return undefined until the cowboy_router middleware has been executed. This includes the onrequest hook.

+ +

meta(Name, Req) -> meta(Name, Req, undefined)

+ +

meta(Name, Req, Default) -> {Value, Req2}

+ +

Types:

+ +
    +
  • Name = atom()
    • +
  • Default = any()
    • +
  • Value = any()
    • +
+ +

Return metadata about the request.

+ +

method(Req) -> {Method, Req2}

+ +

Types:

+ +
    +
  • Method = binary()
    • +
+ +

Return the method.

+ +

Methods are case sensitive. Standard methods are always uppercase.

+ +

parse_header(Name, Req) ->

+ +

parse_header(Name, Req, Default) -> {ok, ParsedValue, Req2} | {undefined, Value, Req2} | {error, badarg}

+ +

Types:

+ +
    +
  • Name = binary()
    • +
  • Default = any()
    • +
  • ParsedValue - see below
    • +
  • Value = any()
    • +
+ +

Parse the given header.

+ +

While header names are case insensitive, this function expects the name to be a lowercase binary.

+ +

The parse_header/2 function will call parser_header/3 with a different default value depending on the header being parsed. The following table summarizes the default values used.

+ + + + + + + + + +
Header nameDefault value
transfer-encoding[<<"identity">>]
Any other headerundefined
+ +

The parsed value differs depending on the header being parsed. The following table summarizes the different types returned.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Header nameType
accept[{{Type, SubType, Params}, Quality, AcceptExt}]
accept-charset[{Charset, Quality}]
accept-encoding[{Encoding, Quality}]
accept-language[{LanguageTag, Quality}]
authorization{AuthType, Credentials}
content-lengthnon_neg_integer()
content-type{Type, SubType, ContentTypeParams}
cookie[{binary(), binary()}]
expect[Expect | {Expect, ExpectValue, Params}]
if-match'*' | [{weak | strong, OpaqueTag}]
if-modified-sincecalendar:datetime()
if-none-match'*' | [{weak | strong, OpaqueTag}]
if-unmodified-sincecalendar:datetime()
range{Unit, [Range]}
sec-websocket-protocol[binary()]
transfer-encoding[binary()]
upgrade[binary()]
x-forwarded-for[binary()]
+ +

Types for the above table:

+ +
    +
  • Type = SubType = Charset = Encoding = LanguageTag = binary()
    • +
  • AuthType = Expect = OpaqueTag = Unit = binary()
    • +
  • Params = ContentTypeParams = [{binary(), binary()}]
    • +
  • Quality = 0..1000
    • +
  • AcceptExt = [{binary(), binary()} | binary()]
    • +
  • Credentials - see below
    • +
  • Range = {non_neg_integer(), non_neg_integer() | infinity} | neg_integer()
    • +
+ +

The cookie names and values, the values of the sec-websocket-protocol and x-forwarded-for headers, the values in AcceptExt and Params, the authorization Credentials, the ExpectValue and OpaqueTag are case sensitive. All values in ContentTypeParams are case sensitive except the value of the charset parameter, which is case insensitive. All other values are case insensitive and will be returned as lowercase.

+ +

The headers accept, accept-encoding and cookie headers can return an empty list. Others will return {error, badarg} if the header value is empty.

+ +

The authorization header parsing code currently only supports basic HTTP authentication. The Credentials type is thus {Username, Password} with Username and Password being binary().

+ +

The range header value Range can take three forms:

+ +
    +
  • {From, To}: from From to To units
    • +
  • {From, infinity}: everything after From units
    • +
  • -Final: the final Final units
    • +
+ +

An undefined tuple will be returned if Cowboy doesn't know how to parse the requested header.

+ +

path(Req) -> {Path, Req2}

+ +

Types:

+ +
    +
  • Path = binary()
    • +
+ +

Return the requested path.

+ +

path_info(Req) -> {PathInfo, Req2}

+ +

Types:

+ +
    +
  • PathInfo = cowboy_router:tokens() | undefined
    • +
+ +

Return the extra tokens from matching against ... during routing.

+ +

peer(Req) -> {Peer, Req2}

+ +

Types:

+ +
    +
  • Peer = {inet:ip_address(), inet:port_number()}
    • +
+ +

Return the client's IP address and port number.

+ +

port(Req) -> {Port, Req2}

+ +

Types:

+ +
    +
  • Port = inet:port_number()
    • +
+ +

Return the request's port.

+ +

The port returned by this function is obtained by parsing the host header. It may be different than the actual port the client used to connect to the Cowboy server.

+ +

qs(Req) -> {QueryString, Req2}

+ +

Types:

+ +
    +
  • QueryString = binary()
    • +
+ +

Return the request's query string.

+ +

qs_val(Name, Req) -> qs_val(Name, Req, undefined)

+ +

qs_val(Name, Req, Default) -> {Value, Req2}

+ +

Types:

+ +
    +
  • Name = binary()
    • +
  • Default = any()
    • +
  • Value = binary() | true
    • +
+ +

Return a value from the request's query string.

+ +

The value true will be returned when the name was found in the query string without an associated value.

+ +

qs_vals(Req) -> {[{Name, Value}], Req2}

+ +

Types:

+ +
    +
  • Name = binary()
    • +
  • Value = binary() | true
    • +
+ +

Return the request's query string as a list of tuples.

+ +

The value true will be returned when a name was found in the query string without an associated value.

+ +

set_meta(Name, Value, Req) -> Req2

+ +

Types:

+ +
    +
  • Name = atom()
    • +
  • Value = any()
    • +
+ +

Set metadata about the request.

+ +

An existing value will be overwritten.

+ +

url(Req) -> {URL, Req2}

+ +

Types:

+ +
    +
  • URL = binary() | undefined
    • +
+ +

Return the requested URL.

+ +

This function will always return undefined until the cowboy_router middleware has been executed. This includes the onrequest hook.

+ +

version(Req) -> {Version, Req2}

+ +

Types:

+ +
    +
  • Version = cowboy:http_version()
    • +
+ +

Return the HTTP version used for this request.

+ +

Request body related exports

+ +

body(Req) -> body(Req, [])

+ +

body(Req, Opts) -> {ok, Data, Req2} | {more, Data, Req2} | {error, Reason}

+ +

Types:

+ +
    +
  • Opts = [body_opt()]
    • +
  • Data = binary()
    • +
  • Reason = atom()
    • +
+ +

Read the request body.

+ +

This function will read a chunk of the request body. If there is more data to be read after this function call, then a more tuple is returned. Otherwise an ok tuple is returned.

+ +

Cowboy will automatically send a 100 Continue reply if required. If this behavior is not desirable, it can be disabled by setting the continue option to false.

+ +

Cowboy will by default attempt to read up to 8MB of the body, but in chunks of 1MB. It will use a timeout of 15s per chunk. All these values can be changed using the length, read_length and read_timeout options respectively. Note that the size of the data may not be the same as requested as the decoding functions may grow or shrink it, and Cowboy makes not attempt at returning an exact amount.

+ +

Cowboy will properly handle chunked transfer-encoding by default. If any other transfer-encoding or content-encoding has been used for the request, custom decoding functions can be used. The content_decode and transfer_decode options allow setting the decode functions manually.

+ +

After the body has been streamed fully, Cowboy will remove the transfer-encoding header from the Req object, and add the content-length header if it wasn't already there.

+ +

This function can only be called once. Cowboy will not cache the result of this call.

+ +

body_length(Req) -> {Length, Req2}

+ +

Types:

+ +
    +
  • Length = non_neg_integer() | undefined
    • +
+ +

Return the length of the request body.

+ +

The length will only be returned if the request does not use any transfer-encoding and if the content-length header is present.

+ +

body_qs(Req) -> body_qs(Req, [{length, 64000}, {read_length, 64000}, {read_timeout, 5000}])

+ +

body_qs(Req, Opts) -> {ok, [{Name, Value}], Req2} | {badlength, Req2} | {error, Reason}

+ +

Types:

+ +
    +
  • Opts = [body_opt()]
    • +
  • Name = binary()
    • +
  • Value = binary() | true
    • +
  • Reason = chunked | badlength | atom()
    • +
+ +

Return the request body as a list of tuples.

+ +

This function will parse the body assuming the content-type application/x-www-form-urlencoded, commonly used for the query string.

+ +

This function calls body/2 for reading the body, with the same options it received. By default it will attempt to read a body of 64KB in one chunk, with a timeout of 5s. If the body is larger then a badlength tuple is returned.

+ +

This function can only be called once. Cowboy will not cache the result of this call.

+ +

has_body(Req) -> boolean()

+ +

Return whether the request has a body.

+ +

part(Req) -> part(Req, [{length, 64000}, {read_length, 64000}, {read_timeout, 5000}])

+ +

part(Req, Opts) -> {ok, Headers, Req2} | {done, Req2}

+ +

Types:

+ +
    +
  • Opts = [body_opt()]
    • +
  • Headers = cow_multipart:headers()
    • +
+ +

Read the headers for the next part of the multipart message.

+ +

Cowboy will skip any data remaining until the beginning of the next part. This includes the preamble to the multipart message but also the body of a previous part if it hasn't been read. Both are skipped automatically when calling this function.

+ +

The headers returned are MIME headers, NOT HTTP headers. They can be parsed using the functions from the cow_multipart module. In addition, the cow_multipart:form_data/1 function can be used to quickly figure out multipart/form-data messages. It takes the list of headers and returns whether this part is a simple form field or a file being uploaded.

+ +

Note that once a part has been read, or skipped, it cannot be read again.

+ +

This function calls body/2 for reading the body, with the same options it received. By default it will only read chunks of 64KB with a timeout of 5s. This is tailored for reading part headers, not for skipping the previous part's body. You might want to consider skipping large parts manually.

+ +

part_body(Req) -> part_body(Req, [])

+ +

part_body(Req, Opts) -> {ok, Data, Req2} | {more, Data, Req2}

+ +

Types:

+ +
    +
  • Opts = [body_opt()]
    • +
  • Data = binary()
    • +
+ +

Read the body of the current part of the multipart message.

+ +

This function calls body/2 for reading the body, with the same options it received. It uses the same defaults.

+ +

If there are more data to be read from the socket for this part, the function will return what it could read inside a more tuple. Otherwise, it will return an ok tuple.

+ +

Calling this function again after receiving a more tuple will return another chunk of body. The last chunk will be returned inside an ok tuple.

+ +

Note that once the body has been read, fully or partially, it cannot be read again.

+ + + +

chunk(Data, Req) -> ok | {error, Reason}

+ +

Types:

+ +
    +
  • Data = iodata()
    • +
  • Reason = atom()
    • +
+ +

Send a chunk of data.

+ +

This function should be called as many times as needed to send data chunks after calling chunked_reply/{2,3}.

+ +

When the method is HEAD, no data will actually be sent.

+ +

If the request uses HTTP/1.0, the data is sent directly without wrapping it in an HTTP/1.1 chunk, providing compatibility with older clients.

+ +

chunked_reply(StatusCode, Req) -> chunked_reply(StatusCode, [], Req)

+ +

chunked_reply(StatusCode, Headers, Req) -> {ok, Req2}

+ +

Types:

+ +
    +
  • StatusCode = cowboy:http_status()
    • +
  • Headers = cowboy:http_headers()
    • +
+ +

Send a response using chunked transfer-encoding.

+ +

This function effectively sends the response status line and headers to the client.

+ +

This function will not send any body set previously. After this call the handler must use the chunk/2 function repeatedly to send the body in as many chunks as needed.

+ +

If the request uses HTTP/1.0, the data is sent directly without wrapping it in an HTTP/1.1 chunk, providing compatibility with older clients.

+ +

This function can only be called once, with the exception of overriding the response in the onresponse hook.

+ +

continue(Req) -> ok | {error, Reason}

+ +

Types:

+ +
    +
  • Reason = atom()
    • +
+ +

Send a 100 Continue intermediate reply.

+ +

This reply is required before the client starts sending the body when the request contains the expect header with the 100-continue value.

+ +

Cowboy will send this automatically when required. However you may want to do it manually by disabling this behavior with the continue body option and then calling this function.

+ +

delete_resp_header(Name, Req) -> Req2

+ +

Types:

+ +
    +
  • Name = binary()
    • +
+ +

Delete the given response header.

+ +

While header names are case insensitive, this function expects the name to be a lowercase binary.

+ +

has_resp_body(Req) -> boolean()

+ +

Return whether a response body has been set.

+ +

This function will return false if a response body has been set with a length of 0.

+ +

has_resp_header(Name, Req) -> boolean()

+ +

Types:

+ +
    +
  • Name = binary()
    • +
+ +

Return whether the given response header has been set.

+ +

While header names are case insensitive, this function expects the name to be a lowercase binary.

+ +

reply(StatusCode, Req) -> reply(StatusCode, [], Req)

+ +

reply(StatusCode, Headers, Req) - see below

+ +

reply(StatusCode, Headers, Body, Req) -> {ok, Req2}

+ +

Types:

+ +
    +
  • StatusCode = cowboy:http_status()
    • +
  • Headers = cowboy:http_headers()
    • +
  • Body = iodata()
    • +
+ +

Send a response.

+ +

This function effectively sends the response status line, headers and body to the client, in a single send function call.

+ +

The reply/2 and reply/3 functions will send the body set previously, if any. The reply/4 function overrides any body set previously and sends Body instead.

+ +

If a body function was set, and reply/2 or reply/3 was used, it will be called before returning.

+ +

No more data can be sent to the client after this function returns.

+ +

This function can only be called once, with the exception of overriding the response in the onresponse hook.

+ +

set_resp_body(Body, Req) -> Req2

+ +

Types:

+ +
    +
  • Body = iodata()
    • +
+ +

Set a response body.

+ +

This body will not be sent if chunked_reply/{2,3} or reply/4 is used, as they override it.

+ +

set_resp_body_fun(Fun, Req) -> Req2

+ +

set_resp_body_fun(Length, Fun, Req) -> Req2

+ +

Types:

+ +
    +
  • Fun = fun((Socket, Transport) -> ok)
    • +
  • Socket = inet:socket()
    • +
  • Transport = module()
    • +
  • Length = non_neg_integer()
    • +
+ +

Set a fun for sending the response body.

+ +

If a Length is provided, it will be sent in the content-length header in the response. It is recommended to set the length if it can be known in advance. Otherwise, the transfer-encoding header will be set to identity.

+ +

This function will only be called if the response is sent using the reply/2 or reply/3 function.

+ +

The fun will receive the Ranch Socket and Transport as arguments. Only send and sendfile operations are supported.

+ +

set_resp_body_fun(chunked, Fun, Req) -> Req2

+ +

Types:

+ +
    +
  • Fun = fun((ChunkFun) -> ok)
    • +
  • ChunkFun = fun((iodata()) -> ok | {error, atom()})
    • +
+ +

Set a fun for sending the response body using chunked transfer-encoding.

+ +

This function will only be called if the response is sent using the reply/2 or reply/3 function.

+ +

The fun will receive another fun as argument. This fun is to be used to send chunks in a similar way to the chunk/2 function, except the fun only takes one argument, the data to be sent in the chunk.

+ + + +

Types:

+ +
    +
  • Name = iodata()
    • +
  • Value = iodata()
    • +
  • Opts = cookie_opts()
    • +
+ +

Set a cookie in the response.

+ +

Cookie names are case sensitive.

+ +

set_resp_header(Name, Value, Req) -> Req2

+ +

Types:

+ +
    +
  • Name = binary()
    • +
  • Value = iodata()
    • +
+ +

Set a response header.

+ +

You should use set_resp_cookie/4 instead of this function to set cookies.

+ +

Misc. exports

+ +

compact(Req) -> Req2

+ +

Remove any non-essential data from the Req object.

+ +

Long-lived connections usually only need to manipulate the Req object at initialization. Compacting allows saving up memory by discarding extraneous information.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_rest/index.html b/docs/en/cowboy/1.0/manual/cowboy_rest/index.html new file mode 100644 index 00000000..31af54c0 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_rest/index.html @@ -0,0 +1,698 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_rest

+ +

The cowboy_rest module implements REST semantics on top of the HTTP protocol.

+ +

This module cannot be described as a behaviour due to most of the callbacks it defines being optional. It has the same semantics as a behaviour otherwise.

+ +

The only mandatory callback is init/3, needed to perform the protocol upgrade.

+ +

Types

+ +

None.

+ +

Meta values

+ +

charset

+ +

Type: binary()

+ +

Negotiated charset.

+ +

This value may not be defined if no charset was negotiated.

+ +

language

+ +

Type: binary()

+ +

Negotiated language.

+ +

This value may not be defined if no language was negotiated.

+ +

media_type

+ +

Type: {binary(), binary(), '*' | [{binary(), binary()}]}

+ +

Negotiated media-type.

+ +

The media-type is the content-type, excluding the charset.

+ +

This value is always defined after the call to content_types_provided/2.

+ +

Callbacks

+ +

init({TransportName, ProtocolName}, Req, Opts) -> {upgrade, protocol, cowboy_rest} | {upgrade, protocol, cowboy_rest, Req, Opts}

+ +

Types:

+ +
    +
  • TransportName = tcp | ssl | atom()
    • +
  • ProtocolName = http | atom()
    • +
  • Req = cowboy_req:req()
    • +
  • Opts = any()
    • +
+ +

Upgrade the protocol to cowboy_rest.

+ +

This is the only mandatory callback.

+ +

rest_init(Req, Opts) -> {ok, Req, State}

+ +

Types:

+ +
    +
  • Req = cowboy_req:req()
    • +
  • Opts = any()
    • +
  • State = any()
    • +
+ +

Initialize the state for this request.

+ +

rest_terminate(Req, State) -> ok

+ +

Types:

+ +
    +
  • Req = cowboy_req:req()
    • +
  • State = any()
    • +
+ +

Perform any necessary cleanup of the state.

+ +

This callback should release any resource currently in use, clear any active timer and reset the process to its original state, as it might be reused for future requests sent on the same connection.

+ +

Callback(Req, State) -> {Value, Req, State} | {halt, Req, State}

+ +

Types:

+ +
    +
  • Callback - one of the REST callbacks described below
    • +
  • Req = cowboy_req:req()
    • +
  • State = any()
    • +
  • Value - see the REST callbacks description below
    • +
+ +

Please see the REST callbacks description below for details on the Value type, the default value if the callback is not defined, and more general information on when the callback is called and what its intended use is.

+ +

The halt tuple can be returned to stop REST processing. It is up to the resource code to send a reply before that, otherwise a 204 No Content will be sent.

+ +

REST callbacks description

+ +

allowed_methods

+ +
    +
  • Methods: all
    • +
  • Value type: [binary()]
    • +
  • Default value: [<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]
    • +
+ +

Return the list of allowed methods.

+ +

Methods are case sensitive. Standard methods are always uppercase.

+ +

allow_missing_post

+ +
    +
  • Methods: POST
    • +
  • Value type: boolean()
    • +
  • Default value: true
    • +
+ +

Return whether POST is allowed when the resource doesn't exist.

+ +

Returning true here means that a new resource will be created. The URL to the created resource should also be returned from the AcceptResource callback.

+ +

charsets_provided

+ +
    +
  • Methods: GET, HEAD, POST, PUT, PATCH, DELETE
    • +
  • Value type: [binary()]
    • +
  • Skip to the next step if undefined
    • +
+ +

Return the list of charsets the resource provides.

+ +

The list must be ordered in order of preference.

+ +

If the accept-charset header was not sent, the first charset in the list will be selected. Otherwise Cowboy will select the most appropriate charset from the list.

+ +

The chosen charset will be set in the Req object as the meta value charset.

+ +

While charsets are case insensitive, this callback is expected to return them as lowercase binary.

+ +

content_types_accepted

+ +
    +
  • Methods: POST, PUT, PATCH
    • +
  • No default
    • +
+ +

Types:

+ +
    +
  • Value = [{binary() | {Type, SubType, Params}, AcceptResource}]
    • +
  • Type = SubType = binary()
    • +
  • Params = '*' | [{binary(), binary()}]
    • +
  • AcceptResource = atom()
    • +
+ +

Return the list of content-types the resource accepts.

+ +

The list must be ordered in order of preference.

+ +

Each content-type can be given either as a binary string or as a tuple containing the type, subtype and parameters.

+ +

Cowboy will select the most appropriate content-type from the list. If any parameter is acceptable, then the tuple form should be used with parameters set to '*'. If the parameters value is set to [] only content-type values with no parameters will be accepted. All parameter values are treated in a case sensitive manner except the charset parameter, if present, which is case insensitive.

+ +

This function will be called for POST, PUT and PATCH requests. It is entirely possible to define different callbacks for different methods if the handling of the request differs. Simply verify what the method is with cowboy_req:method/1 and return a different list for each methods.

+ +

The AcceptResource value is the name of the callback that will be called if the content-type matches. It is defined as follow.

+ +
    +
  • Value type: true | {true, URL} | false
    • +
  • No default
    • +
+ +

Process the request body.

+ +

This function should create or update the resource with the information contained in the request body. This information may be full or partial depending on the request method.

+ +

If the request body was processed successfully, true must be returned. If the request method is POST, {true, URL} may be returned instead, and Cowboy will redirect the client to the location of the newly created resource.

+ +

If a response body must be sent, the appropriate media-type, charset and language can be retrieved using the cowboy_req:meta/{2,3} functions. The respective keys are media_type, charset and language. The body can be set using cowboy_req:set_resp_body/2.

+ +

content_types_provided

+ +
    +
  • Methods: GET, HEAD, POST, PUT, PATCH, DELETE
    • +
  • Default value: [{{<<"text">>, <<"html">>, '*'}, to_html}]
    • +
+ +

Types:

+ +
    +
  • Value = [{binary() | {Type, SubType, Params}, ProvideResource}]
    • +
  • Type = SubType = binary()
    • +
  • Params = '*' | [{binary(), binary()}]
    • +
  • ProvideResource = atom()
    • +
+ +

Return the list of content-types the resource provides.

+ +

The list must be ordered in order of preference.

+ +

Each content-type can be given either as a binary string or as a tuple containing the type, subtype and parameters.

+ +

Cowboy will select the most appropriate content-type from the list. If any parameter is acceptable, then the tuple form should be used with parameters set to '*'. If the parameters value is set to [] only content-type values with no parameters will be accepted. All parameter values are treated in a case sensitive manner except the charset parameter, if present, which is case insensitive.

+ +

The ProvideResource value is the name of the callback that will be called if the content-type matches. It will only be called when a representation of the resource needs to be returned. It is defined as follow.

+ +
    +
  • Methods: GET, HEAD
    • +
  • Value type: iodata() | {stream, Fun} | {stream, Len, Fun} | {chunked, ChunkedFun}
    • +
  • No default
    • +
+ +

Return the response body.

+ +

The response body may be provided directly or through a fun. If a fun tuple is returned, the appropriate set_resp_body_fun function will be called. Please refer to the documentation for these functions for more information about the types.

+ +

The call to this callback happens a good time after the call to content_types_provided/2, when it is time to start rendering the response body.

+ +

delete_completed

+ +
    +
  • Methods: DELETE
    • +
  • Value type: boolean()
    • +
  • Default value: true
    • +
+ +

Return whether the delete action has been completed.

+ +

This function should return false if there is no guarantee that the resource gets deleted immediately from the system, including from any internal cache.

+ +

When this function returns false, a 202 Accepted response will be sent instead of a 200 OK or 204 No Content.

+ +

delete_resource

+ +
    +
  • Methods: DELETE
    • +
  • Value type: boolean()
    • +
  • Default value: false
    • +
+ +

Delete the resource.

+ +

The value returned indicates if the action was successful, regardless of whether the resource is immediately deleted from the system.

+ +

expires

+ +
    +
  • Methods: GET, HEAD
    • +
  • Value type: calendar:datetime() | binary() | undefined
    • +
  • Default value: undefined
    • +
+ +

Return the date of expiration of the resource.

+ +

This date will be sent as the value of the expires header.

+ +

forbidden

+ +
    +
  • Methods: all
    • +
  • Value type: boolean()
    • +
  • Default value: false
    • +
+ +

Return whether access to the resource is forbidden.

+ +

A 403 Forbidden response will be sent if this function returns true. This status code means that access is forbidden regardless of authentication, and that the request shouldn't be repeated.

+ +

generate_etag

+ +
    +
  • Methods: GET, HEAD, POST, PUT, PATCH, DELETE
    • +
  • Value type: binary() | {weak | strong, binary()}
    • +
  • Default value: undefined
    • +
+ +

Return the entity tag of the resource.

+ +

This value will be sent as the value of the etag header.

+ +

If a binary is returned, then the value will be parsed to the tuple form automatically. The value must be in the same format as the etag header, including quotes.

+ +

is_authorized

+ +
    +
  • Methods: all
    • +
  • Value type: true | {false, AuthHeader}
    • +
  • Default value: true
    • +
+ +

Return whether the user is authorized to perform the action.

+ +

This function should be used to perform any necessary authentication of the user before attempting to perform any action on the resource.

+ +

If the authentication fails, the value returned will be sent as the value for the www-authenticate header in the 401 Unauthorized response.

+ +

is_conflict

+ +
    +
  • Methods: PUT
    • +
  • Value type: boolean()
    • +
  • Default value: false
    • +
+ +

Return whether the put action results in a conflict.

+ +

A 409 Conflict response will be sent if this function returns true.

+ +

known_content_type

+ +
    +
  • Methods: all
    • +
  • Value type: boolean()
    • +
  • Default value: true
    • +
+ +

Return whether the content-type is known.

+ +

This function determines if the server understands the content-type, regardless of its use by the resource.

+ +

known_methods

+ +
    +
  • Methods: all
    • +
  • Value type: [binary()]
    • +
  • Default value: [<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]
    • +
+ +

Return the list of known methods.

+ +

The full list of methods known by the server should be returned, regardless of their use in the resource.

+ +

The default value lists the methods Cowboy knows and implement in cowboy_rest.

+ +

Methods are case sensitive. Standard methods are always uppercase.

+ +

languages_provided

+ +
    +
  • Methods: GET, HEAD, POST, PUT, PATCH, DELETE
    • +
  • Value type: [binary()]
    • +
  • Skip to the next step if undefined
    • +
+ +

Return the list of languages the resource provides.

+ +

The list must be ordered in order of preference.

+ +

If the accept-language header was not sent, the first language in the list will be selected. Otherwise Cowboy will select the most appropriate language from the list.

+ +

The chosen language will be set in the Req object as the meta value language.

+ +

While languages are case insensitive, this callback is expected to return them as lowercase binary.

+ +

last_modified

+ +
    +
  • Methods: GET, HEAD, POST, PUT, PATCH, DELETE
    • +
  • Value type: calendar:datetime()
    • +
  • Default value: undefined
    • +
+ +

Return the date of last modification of the resource.

+ +

This date will be used to test against the if-modified-since and if-unmodified-since headers, and sent as the last-modified header in the response of GET and HEAD requests.

+ +

malformed_request

+ +
    +
  • Methods: all
    • +
  • Value type: boolean()
    • +
  • Default value: false
    • +
+ +

Return whether the request is malformed.

+ +

Cowboy has already performed all the necessary checks by the time this function is called, so few resources are expected to implement it.

+ +

The check is to be done on the request itself, not on the request body, which is processed later.

+ +

moved_permanently

+ +
    +
  • Methods: GET, HEAD, POST, PUT, PATCH, DELETE
    • +
  • Value type: {true, URL} | false
    • +
  • Default value: false
    • +
+ +

Return whether the resource was permanently moved.

+ +

If it was, its new URL is also returned and sent in the location header in the response.

+ +

moved_temporarily

+ +
    +
  • Methods: GET, HEAD, POST, PATCH, DELETE
    • +
  • Value type: {true, URL} | false
    • +
  • Default value: false
    • +
+ +

Return whether the resource was temporarily moved.

+ +

If it was, its new URL is also returned and sent in the location header in the response.

+ +

multiple_choices

+ +
    +
  • Methods: GET, HEAD, POST, PUT, PATCH, DELETE
    • +
  • Value type: boolean()
    • +
  • Default value: false
    • +
+ +

Return whether there are multiple representations of the resource.

+ +

This function should be used to inform the client if there are different representations of the resource, for example different content-type. If this function returns true, the response body should include information about these different representations using cowboy_req:set_resp_body/2. The content-type of the response should be the one previously negociated and that can be obtained by calling cowboy_req:meta(media_type, Req).

+ +

options

+ +
    +
  • Methods: OPTIONS
    • +
  • Value type: ok
    • +
  • Default value: ok
    • +
+ +

Handle a request for information.

+ +

The response should inform the client the communication options available for this resource.

+ +

By default, Cowboy will send a 200 OK response with the allow header set.

+ +

previously_existed

+ +
    +
  • Methods: GET, HEAD, POST, PATCH, DELETE
    • +
  • Value type: boolean()
    • +
  • Default value: false
    • +
+ +

Return whether the resource existed previously.

+ +

resource_exists

+ +
    +
  • Methods: GET, HEAD, POST, PUT, PATCH, DELETE
    • +
  • Value type: boolean()
    • +
  • Default value: true
    • +
+ +

Return whether the resource exists.

+ +

If it exists, conditional headers will be tested before attempting to perform the action. Otherwise, Cowboy will check if the resource previously existed first.

+ +

service_available

+ +
    +
  • Methods: all
    • +
  • Value type: boolean()
    • +
  • Default value: true
    • +
+ +

Return whether the service is available.

+ +

This function can be used to test that all relevant backend systems are up and able to handle requests.

+ +

A 503 Service Unavailable response will be sent if this function returns false.

+ +

uri_too_long

+ +
    +
  • Methods: all
    • +
  • Value type: boolean()
    • +
  • Default value: false
    • +
+ +

Return whether the requested URI is too long.

+ +

Cowboy has already performed all the necessary checks by the time this function is called, so few resources are expected to implement it.

+ +

A 414 Request-URI Too Long response will be sent if this function returns true.

+ +

valid_content_headers

+ +
    +
  • Methods: all
    • +
  • Value type: boolean()
    • +
  • Default value: true
    • +
+ +

Return whether the content-* headers are valid.

+ +

This also applies to the transfer-encoding header. This function must return false for any unknown content-* headers, or if the headers can't be understood. The function cowboy_req:parse_header/2 can be used to quickly check the headers can be parsed.

+ +

A 501 Not Implemented response will be sent if this function returns false.

+ +

valid_entity_length

+ +
    +
  • Methods: all
    • +
  • Value type: boolean()
    • +
  • Default value: true
    • +
+ +

Return whether the request body length is within acceptable boundaries.

+ +

A 413 Request Entity Too Large response will be sent if this function returns false.

+ +

variances

+ +
    +
  • Methods: GET, HEAD, POST, PUT, PATCH, DELETE
    • +
  • Value type: [binary()]
    • +
  • Default value: []
    • +
+ +

Return the list of headers that affect the representation of the resource.

+ +

These request headers return the same resource but with different parameters, like another language or a different content-type.

+ +

Cowboy will automatically add the accept, accept-language and accept-charset headers to the list if the respective functions were defined in the resource.

+ +

This operation is performed right before the resource_exists/2 callback. All responses past that point will contain the vary header which holds this list.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_router/index.html b/docs/en/cowboy/1.0/manual/cowboy_router/index.html new file mode 100644 index 00000000..fd191650 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_router/index.html @@ -0,0 +1,247 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_router

+ +

The cowboy_router middleware maps the requested host and path to the handler to be used for processing the request. It uses the dispatch rules compiled from the routes given to the compile/1 function for this purpose. It adds the handler name and options to the environment as the values handler and handler_opts respectively.

+ +

Environment input:

+ +
    +
  • dispatch = dispatch_rules()
    • +
+ +

Environment output:

+ +
    +
  • handler = module()
    • +
  • handler_opts = any()
    • +
+ +

Types

+ +

bindings() = [{atom(), binary()}]

+ +

List of bindings found during routing.

+ +

constraints() = [IntConstraint | FunConstraint]

+ +

Types:

+ +
    +
  • IntConstraint = {atom(), int}
    • +
  • FunConstraint = {atom(), function, Fun}
    • +
  • Fun = fun((binary()) -> true | {true, any()} | false)
    • +
+ +

List of constraints to apply to the bindings.

+ +

The int constraint will convert the binding to an integer. The fun constraint allows writing custom code for checking the bindings. Returning a new value from that fun allows replacing the current binding with a new value.

+ +

dispatch_rules() - opaque to the user

+ +

Rules for dispatching request used by Cowboy.

+ +

routes() = [{Host, Paths} | {Host, constraints(), Paths}]

+ +

Types:

+ +
    +
  • Host = Path = '_' | iodata()
    • +
  • Paths = [{Path, Handler, Opts} | {Path, constraints(), Handler, Opts}]
    • +
  • Handler = module()
    • +
  • Opts = any()
    • +
+ +

Human readable list of routes mapping hosts and paths to handlers.

+ +

The syntax for routes is defined in the user guide.

+ +

tokens() = [binary()]

+ +

List of host_info and path_info tokens found during routing.

+ +

Exports

+ +

compile(Routes) -> Dispatch

+ +

Types:

+ +
    +
  • Routes = routes()
    • +
  • Dispatch = dispatch_rules()
    • +
+ +

Compile the routes for use by Cowboy.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_spdy/index.html b/docs/en/cowboy/1.0/manual/cowboy_spdy/index.html new file mode 100644 index 00000000..39f0611c --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_spdy/index.html @@ -0,0 +1,212 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_spdy

+ +

The cowboy_spdy module implements SPDY/3 as a Ranch protocol.

+ +

Types

+ +

opts() = [{env, cowboy_middleware:env()} | {middlewares, [module()]} | {onrequest, cowboy:onrequest_fun()} | {onresponse, cowboy:onresponse_fun()}]

+ +

Configuration for the SPDY protocol handler.

+ +

This configuration is passed to Cowboy when starting listeners using the cowboy:start_spdy/4 function.

+ +

It can be updated without restarting listeners using the Ranch functions ranch:get_protocol_options/1 and ranch:set_protocol_options/2.

+ +

Option descriptions

+ +

The default value is given next to the option name.

+ +

env ([{listener, Ref}])

+ +

Initial middleware environment.

+ +

middlewares ([cowboy_router, cowboy_handler])

+ +

List of middlewares to execute for every requests.

+ +

onrequest (undefined)

+ +

Fun called every time a request is received.

+ +

onresponse (undefined)

+ +

Fun called every time a response is sent.

+ +

Exports

+ +

None.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_static/index.html b/docs/en/cowboy/1.0/manual/cowboy_static/index.html new file mode 100644 index 00000000..8d6dd8a5 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_static/index.html @@ -0,0 +1,194 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_static

+ +

The cowboy_static module implements file serving capabilities by using the REST semantics provided by cowboy_rest.

+ +

Types

+ +

opts() = {priv_file, atom(), string() | binary()} | {priv_file, atom(), string() | binary(), extra()} | {file, string() | binary()} | {file, string() | binary(), extra()} | {priv_dir, atom(), string() | binary()} | {priv_dir, atom(), string() | binary(), extra()} | {dir, string() | binary()} | {dir, string() | binary(), extra()}

+ +

Configuration for the static handler.

+ +

The handler can be configured for sending either one file or a directory (including its subdirectories).

+ +

Extra options allow you to define how the etag should be calculated and how the mimetype of files should be detected. They are defined as follow, but do note that these types are not exported, only the opts/0 type is public.

+ +

extra() = [extra_etag() | extra_mimetypes()]

+ +

extra_etag() = {etag, module(), function()} | {etag, false}

+ +

extra_mimetypes() = {mimetypes, module(), function()} | {mimetypes, binary() | {binary(), binary(), [{binary(), binary()}]}}

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_sub_protocol/index.html b/docs/en/cowboy/1.0/manual/cowboy_sub_protocol/index.html new file mode 100644 index 00000000..53b52bd4 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_sub_protocol/index.html @@ -0,0 +1,203 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_sub_protocol

+ +

The cowboy_sub_protocol behaviour defines the interface used by modules that implement a protocol on top of HTTP.

+ +

Types

+ +

None.

+ +

Callbacks

+ +

upgrade(Req, Env, Handler, Opts) -> {ok, Req, Env} | {suspend, Module, Function, Args} | {halt, Req} | {error, StatusCode, Req}

+ +

Types:

+ +
    +
  • Req = cowboy_req:req()
    • +
  • Env = env()
    • +
  • Handler = module()
    • +
  • Opts = any()
    • +
  • Module = module()
    • +
  • Function = atom()
    • +
  • Args = [any()]
    • +
  • StatusCode = cowboy:http_status()
    • +
+ +

Upgrade the protocol.

+ +

Please refer to the cowboy_middleware manual for a description of the return values.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_websocket/index.html b/docs/en/cowboy/1.0/manual/cowboy_websocket/index.html new file mode 100644 index 00000000..e05e9829 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_websocket/index.html @@ -0,0 +1,208 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_websocket

+ +

The cowboy_websocket module implements the Websocket protocol.

+ +

The callbacks for websocket handlers are defined in the manual for the cowboy_websocket_handler behaviour.

+ +

Types

+ +

close_code() = 1000..4999

+ +

Reason for closing the connection.

+ +

frame() = close | ping | pong | {text | binary | close | ping | pong, iodata()} | {close, close_code(), iodata()}

+ +

Frames that can be sent to the client.

+ +

Meta values

+ +

websocket_compress

+ +

Type: true | false

+ +

Whether a websocket compression extension in in use.

+ +

websocket_version

+ +

Type: 7 | 8 | 13

+ +

The version of the Websocket protocol being used.

+ +

Exports

+ +

None.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/cowboy_websocket_handler/index.html b/docs/en/cowboy/1.0/manual/cowboy_websocket_handler/index.html new file mode 100644 index 00000000..62ddd89a --- /dev/null +++ b/docs/en/cowboy/1.0/manual/cowboy_websocket_handler/index.html @@ -0,0 +1,273 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

cowboy_websocket_handler

+ +

The cowboy_websocket_handler behaviour defines the interface used by Websocket handlers.

+ +

The init/3 and websocket_init/3 callbacks will always be called, followed by zero or more calls to websocket_handle/3 and websocket_info/3. The websocket_terminate/3 will always be called last.

+ +

Types

+ +

None.

+ +

Callbacks

+ +

init({TransportName, ProtocolName}, Req, Opts) -> {upgrade, protocol, cowboy_websocket} | {upgrade, protocol, cowboy_websocket, Req, Opts}

+ +

Types:

+ +
    +
  • TransportName = tcp | ssl | atom()
    • +
  • ProtocolName = http | atom()
    • +
  • Req = cowboy_req:req()
    • +
  • Opts = any()
    • +
+ +

Upgrade the protocol to cowboy_websocket.

+ +

websocket_init(TransportName, Req, Opts) -> {ok, Req, State} | {ok, Req, State, hibernate} | {ok, Req, State, Timeout} | {ok, Req, State, Timeout, hibernate} | {shutdown, Req}

+ +

Types:

+ +
    +
  • TransportName = tcp | ssl | atom()
    • +
  • Req = cowboy_req:req()
    • +
  • Opts = any()
    • +
  • State = any()
    • +
  • Timeout = timeout()
    • +
+ +

Initialize the state for this session.

+ +

This function is called before the upgrade to Websocket occurs. It can be used to negotiate Websocket protocol extensions with the client. It will typically be used to register this process to an event manager or a message queue in order to receive the messages the handler wants to process.

+ +

The connection will stay up for a duration of up to Timeout milliseconds after it last received data from the socket, at which point it will stop and close the connection. By default this value is set to infinity. It is recommended to either set this value or ensure by any other mechanism that the handler will be closed after a certain period of inactivity.

+ +

The hibernate option will hibernate the process until it starts receiving either data from the Websocket connection or Erlang messages.

+ +

The shutdown return value can be used to close the connection before upgrading to Websocket.

+ +

websocket_handle(InFrame, Req, State) -> {ok, Req, State} | {ok, Req, State, hibernate} | {reply, OutFrame | [OutFrame], Req, State} | {reply, OutFrame | [OutFrame], Req, State, hibernate} | {shutdown, Req, State}

+ +

Types:

+ +
    +
  • InFrame = {text | binary | ping | pong, binary()}
    • +
  • Req = cowboy_req:req()
    • +
  • State = any()
    • +
  • OutFrame = cowboy_websocket:frame()
    • +
+ +

Handle the data received from the Websocket connection.

+ +

This function will be called every time data is received from the Websocket connection.

+ +

The shutdown return value can be used to close the connection. A close reply will also result in the connection being closed.

+ +

The hibernate option will hibernate the process until it receives new data from the Websocket connection or an Erlang message.

+ +

websocket_info(Info, Req, State) -> {ok, Req, State} | {ok, Req, State, hibernate} | {reply, OutFrame | [OutFrame], Req, State} | {reply, OutFrame | [OutFrame], Req, State, hibernate} | {shutdown, Req, State}

+ +

Types:

+ +
    +
  • Info = any()
    • +
  • Req = cowboy_req:req()
    • +
  • State = any()
    • +
  • OutFrame = cowboy_websocket:frame()
    • +
+ +

Handle the Erlang message received.

+ +

This function will be called every time an Erlang message has been received. The message can be any Erlang term.

+ +

The shutdown return value can be used to close the connection. A close reply will also result in the connection being closed.

+ +

The hibernate option will hibernate the process until it receives another message or new data from the Websocket connection.

+ +

websocket_terminate(Reason, Req, State) -> ok

+ +

Types:

+ +
    +
  • Reason = {normal, shutdown | timeout} | {remote, closed} | {remote, cowboy_websocket:close_code(), binary()} | {error, badencoding | badframe | closed | atom()}
    • +
  • Req = cowboy_req:req()
    • +
  • State = any()
    • +
+ +

Perform any necessary cleanup of the state.

+ +

The connection will be closed and the process stopped right after this call.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/http_status_codes/index.html b/docs/en/cowboy/1.0/manual/http_status_codes/index.html new file mode 100644 index 00000000..d668474f --- /dev/null +++ b/docs/en/cowboy/1.0/manual/http_status_codes/index.html @@ -0,0 +1,305 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+
+ +

HTTP status codes

+ +

This chapter aims to list all HTTP status codes that Cowboy may return, with details on the reasons why. The list given here only includes the replies that Cowboy sends, not user replies.

+ +

100 Continue

+ +

When the client sends an expect: 100-continue header, Cowboy automatically sends a this status code before trying to read the request body. This behavior can be disabled using the appropriate body option.

+ +

101 Switching Protocols

+ +

This is the status code sent when switching to the Websocket protocol.

+ +

200 OK

+ +

This status code is sent by cowboy_rest.

+ +

201 Created

+ +

This status code is sent by cowboy_rest.

+ +

202 Accepted

+ +

This status code is sent by cowboy_rest.

+ +

204 No Content

+ +

This status code is sent when the processing of a request ends without any reply having been sent. It may also be sent by cowboy_rest under normal conditions.

+ +

300 Multiple Choices

+ +

This status code is sent by cowboy_rest.

+ +

301 Moved Permanently

+ +

This status code is sent by cowboy_rest.

+ +

303 See Other

+ +

This status code is sent by cowboy_rest.

+ +

304 Not Modified

+ +

This status code is sent by cowboy_rest.

+ +

307 Temporary Redirect

+ +

This status code is sent by cowboy_rest.

+ +

400 Bad Request

+ +

Cowboy will send this status code for any of the following reasons:

+ +
    +
  • Too many empty lines were sent before the request.
    • +
  • The request-line could not be parsed.
    • +
  • Too many headers were sent.
    • +
  • A header name was too long.
    • +
  • A header value was too long.
    • +
  • The host header was missing from an HTTP/1.1 request.
    • +
  • The host header could not be parsed.
    • +
  • The requested host was not found.
    • +
  • The requested path could not be parsed.
    • +
  • The accept header could not be parsed when using REST.
    • +
  • REST under normal conditions.
    • +
  • A Websocket upgrade failed.
    • +
+ +

401 Unauthorized

+ +

This status code is sent by cowboy_rest.

+ +

403 Forbidden

+ +

This status code is sent by cowboy_rest.

+ +

404 Not Found

+ +

This status code is sent when the router successfully resolved the host but didn't find a matching path for the request. It may also be sent by cowboy_rest under normal conditions.

+ +

405 Method Not Allowed

+ +

This status code is sent by cowboy_rest.

+ +

406 Not Acceptable

+ +

This status code is sent by cowboy_rest.

+ +

408 Request Timeout

+ +

Cowboy will send this status code to the client if the client started to send a request, indicated by the request-line being received fully, but failed to send all headers in a reasonable time.

+ +

409 Conflict

+ +

This status code is sent by cowboy_rest.

+ +

410 Gone

+ +

This status code is sent by cowboy_rest.

+ +

412 Precondition Failed

+ +

This status code is sent by cowboy_rest.

+ +

413 Request Entity Too Large

+ +

This status code is sent by cowboy_rest.

+ +

414 Request-URI Too Long

+ +

Cowboy will send this status code to the client if the request-line is too long. It may also be sent by cowboy_rest under normal conditions.

+ +

415 Unsupported Media Type

+ +

This status code is sent by cowboy_rest.

+ +

500 Internal Server Error

+ +

This status code is sent when a crash occurs in HTTP, loop or REST handlers, or when an invalid return value is returned. It may also be sent by cowboy_rest under normal conditions.

+ +

501 Not Implemented

+ +

This status code is sent by cowboy_rest.

+ +

503 Service Unavailable

+ +

This status code is sent by cowboy_rest.

+ +

505 HTTP Version Not Supported

+ +

Cowboy only supports the versions 1.0 and 1.1 of HTTP. In all other cases this status code is sent back to the client and the connection is closed.

+ + + +
+ +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/1.0/manual/index.html b/docs/en/cowboy/1.0/manual/index.html new file mode 100644 index 00000000..b5b11489 --- /dev/null +++ b/docs/en/cowboy/1.0/manual/index.html @@ -0,0 +1,197 @@ + + + + + Nine Nines Support: Cowboy Function Reference + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ + +
+
+
+
+ + +
+ + +
+
+
+ + +
+
+ +
+ +

Navigation

+ +

See also

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/architecture.asciidoc b/docs/en/cowboy/2.0/guide/architecture.asciidoc new file mode 100644 index 00000000..416ef36b --- /dev/null +++ b/docs/en/cowboy/2.0/guide/architecture.asciidoc @@ -0,0 +1,48 @@ +[[architecture]] +== Architecture + +Cowboy is a lightweight HTTP server. + +It is built on top of Ranch. Please see the Ranch guide for more +information. + +=== One process per connection + +It uses only one process per connection. The process where your +code runs is the process controlling the socket. Using one process +instead of two allows for lower memory usage. + +Because there can be more than one request per connection with the +keepalive feature of HTTP/1.1, that means the same process will be +used to handle many requests. + +Because of this, you are expected to make sure your process cleans +up before terminating the handling of the current request. This may +include cleaning up the process dictionary, timers, monitoring and +more. + +=== Binaries + +It uses binaries. Binaries are more efficient than lists for +representing strings because they take less memory space. Processing +performance can vary depending on the operation. Binaries are known +for generally getting a great boost if the code is compiled natively. +Please see the HiPE documentation for more details. + +=== Date header + +Because querying for the current date and time can be expensive, +Cowboy generates one `Date` header value every second, shares it +to all other processes, which then simply copy it in the response. +This allows compliance with HTTP/1.1 with no actual performance loss. + +=== Max connections + +By default the maximum number of active connections is set to a +generally accepted big enough number. This is meant to prevent having +too many processes performing potentially heavy work and slowing +everything else down, or taking up all the memory. + +Disabling this feature, by setting the `{max_connections, infinity}` +protocol option, would give you greater performance when you are +only processing short-lived requests. diff --git a/docs/en/cowboy/2.0/guide/architecture/index.html b/docs/en/cowboy/2.0/guide/architecture/index.html new file mode 100644 index 00000000..ef816699 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/architecture/index.html @@ -0,0 +1,191 @@ + + + + + + + + + + + + Nine Nines: Architecture + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Architecture

+ +

Cowboy is a lightweight HTTP server.

+

It is built on top of Ranch. Please see the Ranch guide for more +information.

+
+

One process per connection

+
+

It uses only one process per connection. The process where your +code runs is the process controlling the socket. Using one process +instead of two allows for lower memory usage.

+

Because there can be more than one request per connection with the +keepalive feature of HTTP/1.1, that means the same process will be +used to handle many requests.

+

Because of this, you are expected to make sure your process cleans +up before terminating the handling of the current request. This may +include cleaning up the process dictionary, timers, monitoring and +more.

+
+
+
+

Binaries

+
+

It uses binaries. Binaries are more efficient than lists for +representing strings because they take less memory space. Processing +performance can vary depending on the operation. Binaries are known +for generally getting a great boost if the code is compiled natively. +Please see the HiPE documentation for more details.

+
+
+
+

Date header

+
+

Because querying for the current date and time can be expensive, +Cowboy generates one Date header value every second, shares it +to all other processes, which then simply copy it in the response. +This allows compliance with HTTP/1.1 with no actual performance loss.

+
+
+
+

Max connections

+
+

By default the maximum number of active connections is set to a +generally accepted big enough number. This is meant to prevent having +too many processes performing potentially heavy work and slowing +everything else down, or taking up all the memory.

+

Disabling this feature, by setting the {max_connections, infinity} +protocol option, would give you greater performance when you are +only processing short-lived requests.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/broken_clients.asciidoc b/docs/en/cowboy/2.0/guide/broken_clients.asciidoc new file mode 100644 index 00000000..17bb892f --- /dev/null +++ b/docs/en/cowboy/2.0/guide/broken_clients.asciidoc @@ -0,0 +1,61 @@ +[[broken_clients]] +== Dealing with broken clients + +There exists a very large number of implementations for the +HTTP protocol. Most widely used clients, like browsers, +follow the standard quite well, but others may not. In +particular custom enterprise clients tend to be very badly +written. + +Cowboy tries to follow the standard as much as possible, +but is not trying to handle every possible special cases. +Instead Cowboy focuses on the cases reported in the wild, +on the public Web. + +That means clients that ignore the HTTP standard completely +may fail to understand Cowboy's responses. There are of +course workarounds. This chapter aims to cover them. + +=== Lowercase headers + +Cowboy converts all headers it receives to lowercase, and +similarly sends back headers all in lowercase. Some broken +HTTP clients have issues with that. + +A simple way to solve this is to create an `onresponse` hook +that will format the header names with the expected case. + +[source,erlang] +---- +capitalize_hook(Status, Headers, Body, Req) -> + Headers2 = [{cowboy_bstr:capitalize_token(N), V} + || {N, V} <- Headers], + cowboy_req:reply(Status, Headers2, Body, Req). +---- + +Note that HTTP/2 clients do not have that particular issue +because the specification explicitly says all headers are +lowercase, unlike HTTP which allows any case but treats +them as case insensitive. + +=== Camel-case headers + +Sometimes it is desirable to keep the actual case used by +clients, for example when acting as a proxy between two broken +implementations. There is no easy solution for this other than +forking the project and editing the `cowboy_protocol` file +directly. + +=== Chunked transfer-encoding + +Sometimes an HTTP client advertises itself as HTTP/1.1 but +does not support chunked transfer-encoding. This is invalid +behavior, as HTTP/1.1 clients are required to support it. + +A simple workaround exists in these cases. By changing the +Req object response state to `waiting_stream`, Cowboy will +understand that it must use the identity transfer-encoding +when replying, just like if it was an HTTP/1.0 client. + +[source,erlang] +Req2 = cowboy_req:set(resp_state, waiting_stream). diff --git a/docs/en/cowboy/2.0/guide/broken_clients/index.html b/docs/en/cowboy/2.0/guide/broken_clients/index.html new file mode 100644 index 00000000..049ee878 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/broken_clients/index.html @@ -0,0 +1,205 @@ + + + + + + + + + + + + Nine Nines: Dealing with broken clients + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Dealing with broken clients

+ +

There exists a very large number of implementations for the +HTTP protocol. Most widely used clients, like browsers, +follow the standard quite well, but others may not. In +particular custom enterprise clients tend to be very badly +written.

+

Cowboy tries to follow the standard as much as possible, +but is not trying to handle every possible special cases. +Instead Cowboy focuses on the cases reported in the wild, +on the public Web.

+

That means clients that ignore the HTTP standard completely +may fail to understand Cowboy’s responses. There are of +course workarounds. This chapter aims to cover them.

+
+

Lowercase headers

+
+

Cowboy converts all headers it receives to lowercase, and +similarly sends back headers all in lowercase. Some broken +HTTP clients have issues with that.

+

A simple way to solve this is to create an onresponse hook +that will format the header names with the expected case.

+
+
+
capitalize_hook(Status, Headers, Body, Req) ->
+    Headers2 = [{cowboy_bstr:capitalize_token(N), V}
+        || {N, V} <- Headers],
+    cowboy_req:reply(Status, Headers2, Body, Req).
+

Note that HTTP/2 clients do not have that particular issue +because the specification explicitly says all headers are +lowercase, unlike HTTP which allows any case but treats +them as case insensitive.

+
+
+
+

Camel-case headers

+
+

Sometimes it is desirable to keep the actual case used by +clients, for example when acting as a proxy between two broken +implementations. There is no easy solution for this other than +forking the project and editing the cowboy_protocol file +directly.

+
+
+
+

Chunked transfer-encoding

+
+

Sometimes an HTTP client advertises itself as HTTP/1.1 but +does not support chunked transfer-encoding. This is invalid +behavior, as HTTP/1.1 clients are required to support it.

+

A simple workaround exists in these cases. By changing the +Req object response state to waiting_stream, Cowboy will +understand that it must use the identity transfer-encoding +when replying, just like if it was an HTTP/1.0 client.

+
+
+
Req2 = cowboy_req:set(resp_state, waiting_stream).
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/constraints.asciidoc b/docs/en/cowboy/2.0/guide/constraints.asciidoc new file mode 100644 index 00000000..0ae01d59 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/constraints.asciidoc @@ -0,0 +1,54 @@ +[[constraints]] +== Constraints + +Cowboy provides an optional constraints based validation feature +when interacting with user input. + +Constraints are first used during routing. The router uses +constraints to more accurately match bound values, allowing +to create routes where a segment is an integer for example, +and rejecting the others. + +Constraints are also used when performing a match operation +on input data, like the query string or cookies. There, a +default value can also be provided for optional values. + +Finally, constraints can be used to not only validate input, +but also convert said input into proper Erlang terms, all in +one step. + +=== Structure + +Constraints are provided as a list of fields and for each +field a list of constraints for that field can be provided. + +Fields are either the name of the field; the name and +one or more constraints; or the name, one or more constraints +and a default value. + +When no default value is provided then the field is required. +Otherwise the default value is used. + +All constraints for a field will be used to match its value +in the order they are given. If the value is modified by a +constraint, the next constraint receives the updated value. + +=== Built-in constraints + +[cols="<,<",options="header"] +|=== +| Constraint | Description +| int | Convert binary value to integer. +| nonempty | Ensures the binary value is non-empty. +|=== + +=== Custom constraint + +In addition to the predefined constraints, Cowboy will accept +a fun. This fun must accept one argument and return one of +`true`, `{true, NewValue}` or `false`. The result indicates +whether the value matches the constraint, and if it does it +can optionally be modified. This allows converting the value +to a more appropriate Erlang term. + +Note that constraint functions SHOULD be pure and MUST NOT crash. diff --git a/docs/en/cowboy/2.0/guide/constraints/index.html b/docs/en/cowboy/2.0/guide/constraints/index.html new file mode 100644 index 00000000..f9c072b6 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/constraints/index.html @@ -0,0 +1,211 @@ + + + + + + + + + + + + Nine Nines: Constraints + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Constraints

+ +

Cowboy provides an optional constraints based validation feature +when interacting with user input.

+

Constraints are first used during routing. The router uses +constraints to more accurately match bound values, allowing +to create routes where a segment is an integer for example, +and rejecting the others.

+

Constraints are also used when performing a match operation +on input data, like the query string or cookies. There, a +default value can also be provided for optional values.

+

Finally, constraints can be used to not only validate input, +but also convert said input into proper Erlang terms, all in +one step.

+
+

Structure

+
+

Constraints are provided as a list of fields and for each +field a list of constraints for that field can be provided.

+

Fields are either the name of the field; the name and +one or more constraints; or the name, one or more constraints +and a default value.

+

When no default value is provided then the field is required. +Otherwise the default value is used.

+

All constraints for a field will be used to match its value +in the order they are given. If the value is modified by a +constraint, the next constraint receives the updated value.

+
+
+
+

Built-in constraints

+
+
+ +++ + + + + + + + + + + + + + + + +
Constraint Description

int

Convert binary value to integer.

nonempty

Ensures the binary value is non-empty.

+
+
+
+
+

Custom constraint

+
+

In addition to the predefined constraints, Cowboy will accept +a fun. This fun must accept one argument and return one of +true, {true, NewValue} or false. The result indicates +whether the value matches the constraint, and if it does it +can optionally be modified. This allows converting the value +to a more appropriate Erlang term.

+

Note that constraint functions SHOULD be pure and MUST NOT crash.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/cookies.asciidoc b/docs/en/cowboy/2.0/guide/cookies.asciidoc new file mode 100644 index 00000000..6068db37 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/cookies.asciidoc @@ -0,0 +1,163 @@ +[[cookies]] +== Using cookies + +Cookies are a mechanism allowing applications to maintain +state on top of the stateless HTTP protocol. + +Cowboy provides facilities for handling cookies. It is highly +recommended to use them instead of writing your own, as the +implementation of cookies can vary greatly between clients. + +Cookies are stored client-side and sent with every subsequent +request that matches the domain and path for which they were +stored, including requests for static files. For this reason +they can incur a cost which must be taken in consideration. + +Also consider that, regardless of the options used, cookies +are not to be trusted. They may be read and modified by any +program on the user's computer, but also by proxies. You +should always validate cookie values before using them. Do +not store any sensitive information in cookies either. + +When explicitly setting the domain, the cookie will be sent +for the domain and all subdomains from that domain. Otherwise +the current domain will be used. The same is true for the +path. + +When the server sets cookies, they will only be available +for requests that are sent after the client receives the +response. + +Cookies are sent in HTTP headers, therefore they must have +text values. It is your responsibility to encode any other +data type. Also note that cookie names are de facto case +sensitive. + +Cookies can be set for the client session (which generally +means until the browser is closed), or it can be set for +a number of seconds. Once it expires, or when the server +says the cookie must exist for up to 0 seconds, the cookie +is deleted by the client. To avoid this while the user +is browsing your site, you should set the cookie for +every request, essentially resetting the expiration time. + +Cookies can be restricted to secure channels. This typically +means that such a cookie will only be sent over HTTPS, +and that it will only be available by client-side scripts +that run from HTTPS webpages. + +Finally, cookies can be restricted to HTTP and HTTPS requests, +essentially disabling their access from client-side scripts. + +=== Setting cookies + +By default, cookies you set are defined for the session. + +[source,erlang] +SessionID = generate_session_id(), +Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [], Req). + +You can also make them expire at a specific point in the +future. + +[source,erlang] +---- +SessionID = generate_session_id(), +Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [ + {max_age, 3600} +], Req). +---- + +You can delete cookies that have already been set. The value +is ignored. + +[source,erlang] +---- +Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, <<>>, [ + {max_age, 0} +], Req). +---- + +You can restrict them to a specific domain and path. +For example, the following cookie will be set for the domain +`my.example.org` and all its subdomains, but only on the path +`/account` and all its subdirectories. + +[source,erlang] +---- +Req2 = cowboy_req:set_resp_cookie(<<"inaccount">>, <<"1">>, [ + {domain, "my.example.org"}, + {path, "/account"} +], Req). +---- + +You can restrict the cookie to secure channels, typically HTTPS. + +[source,erlang] +---- +SessionID = generate_session_id(), +Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [ + {secure, true} +], Req). +---- + +You can restrict the cookie to client-server communication +only. Such a cookie will not be available to client-side scripts. + +[source,erlang] +---- +SessionID = generate_session_id(), +Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [ + {http_only, true} +], Req). +---- + +Cookies may also be set client-side, for example using +Javascript. + +=== Reading cookies + +As we said, the client sends cookies with every request. +But unlike the server, the client only sends the cookie +name and value. + +Cowboy provides two different ways to read cookies. You +can either parse them as a list of key/value pairs, or +match them into a map, optionally applying constraints +to the values or providing a default if they are missing. + +You can parse the cookies and then use standard library +functions to access individual values. + +[source,erlang] +Cookies = cowboy_req:parse_cookies(Req), +{_, Lang} = lists:keyfind(<<"lang">>, 1, Cookies). + +You can match the cookies into a map. + +[source,erlang] +#{id := ID, lang := Lang} = cowboy_req:match_cookies([id, lang], Req). + +You can use constraints to validate the values while matching +them. The following snippet will crash if the `id` cookie is +not an integer number or if the `lang` cookie is empty. Additionally +the `id` cookie value will be converted to an integer term, saving +you a conversion step. + +[source,erlang] +CookiesMap = cowboy_req:match_cookies([{id, int}, {lang, nonempty}], Req). + +Note that if two cookies share the same name, then the map value +will be a list of the two cookie values. + +Read more about xref:constraints[constraints]. + +A default value can be provided. The default will be used +if the `lang` cookie is not found. It will not be used if +the cookie is found but has an empty value. + +[source,erlang] +#{lang := Lang} = cowboy_req:match_cookies([{lang, [], <<"en-US">>}], Req). + +If no default is provided and the value is missing, the +query string is deemed invalid and the process will crash. diff --git a/docs/en/cowboy/2.0/guide/cookies/index.html b/docs/en/cowboy/2.0/guide/cookies/index.html new file mode 100644 index 00000000..4aea8eb0 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/cookies/index.html @@ -0,0 +1,303 @@ + + + + + + + + + + + + Nine Nines: Using cookies + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Using cookies

+ +

Cookies are a mechanism allowing applications to maintain +state on top of the stateless HTTP protocol.

+

Cowboy provides facilities for handling cookies. It is highly +recommended to use them instead of writing your own, as the +implementation of cookies can vary greatly between clients.

+

Cookies are stored client-side and sent with every subsequent +request that matches the domain and path for which they were +stored, including requests for static files. For this reason +they can incur a cost which must be taken in consideration.

+

Also consider that, regardless of the options used, cookies +are not to be trusted. They may be read and modified by any +program on the user’s computer, but also by proxies. You +should always validate cookie values before using them. Do +not store any sensitive information in cookies either.

+

When explicitly setting the domain, the cookie will be sent +for the domain and all subdomains from that domain. Otherwise +the current domain will be used. The same is true for the +path.

+

When the server sets cookies, they will only be available +for requests that are sent after the client receives the +response.

+

Cookies are sent in HTTP headers, therefore they must have +text values. It is your responsibility to encode any other +data type. Also note that cookie names are de facto case +sensitive.

+

Cookies can be set for the client session (which generally +means until the browser is closed), or it can be set for +a number of seconds. Once it expires, or when the server +says the cookie must exist for up to 0 seconds, the cookie +is deleted by the client. To avoid this while the user +is browsing your site, you should set the cookie for +every request, essentially resetting the expiration time.

+

Cookies can be restricted to secure channels. This typically +means that such a cookie will only be sent over HTTPS, +and that it will only be available by client-side scripts +that run from HTTPS webpages.

+

Finally, cookies can be restricted to HTTP and HTTPS requests, +essentially disabling their access from client-side scripts.

+
+

Setting cookies

+
+

By default, cookies you set are defined for the session.

+
+
+
SessionID = generate_session_id(),
+Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [], Req).
+

You can also make them expire at a specific point in the +future.

+
+
+
SessionID = generate_session_id(),
+Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [
+    {max_age, 3600}
+], Req).
+

You can delete cookies that have already been set. The value +is ignored.

+
+
+
Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, <<>>, [
+    {max_age, 0}
+], Req).
+

You can restrict them to a specific domain and path. +For example, the following cookie will be set for the domain +my.example.org and all its subdomains, but only on the path +/account and all its subdirectories.

+
+
+
Req2 = cowboy_req:set_resp_cookie(<<"inaccount">>, <<"1">>, [
+    {domain, "my.example.org"},
+    {path, "/account"}
+], Req).
+

You can restrict the cookie to secure channels, typically HTTPS.

+
+
+
SessionID = generate_session_id(),
+Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [
+    {secure, true}
+], Req).
+

You can restrict the cookie to client-server communication +only. Such a cookie will not be available to client-side scripts.

+
+
+
SessionID = generate_session_id(),
+Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [
+    {http_only, true}
+], Req).
+

Cookies may also be set client-side, for example using +Javascript.

+
+
+
+

Reading cookies

+
+

As we said, the client sends cookies with every request. +But unlike the server, the client only sends the cookie +name and value.

+

Cowboy provides two different ways to read cookies. You +can either parse them as a list of key/value pairs, or +match them into a map, optionally applying constraints +to the values or providing a default if they are missing.

+

You can parse the cookies and then use standard library +functions to access individual values.

+
+
+
Cookies = cowboy_req:parse_cookies(Req),
+{_, Lang} = lists:keyfind(<<"lang">>, 1, Cookies).
+

You can match the cookies into a map.

+
+
+
#{id := ID, lang := Lang} = cowboy_req:match_cookies([id, lang], Req).
+

You can use constraints to validate the values while matching +them. The following snippet will crash if the id cookie is +not an integer number or if the lang cookie is empty. Additionally +the id cookie value will be converted to an integer term, saving +you a conversion step.

+
+
+
CookiesMap = cowboy_req:match_cookies([{id, int}, {lang, nonempty}], Req).
+

Note that if two cookies share the same name, then the map value +will be a list of the two cookie values.

+

Read more about constraints.

+

A default value can be provided. The default will be used +if the lang cookie is not found. It will not be used if +the cookie is found but has an empty value.

+
+
+
#{lang := Lang} = cowboy_req:match_cookies([{lang, [], <<"en-US">>}], Req).
+

If no default is provided and the value is missing, the +query string is deemed invalid and the process will crash.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/erlang_beginners.asciidoc b/docs/en/cowboy/2.0/guide/erlang_beginners.asciidoc new file mode 100644 index 00000000..b9a6c655 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/erlang_beginners.asciidoc @@ -0,0 +1,36 @@ +[[erlang_beginners]] +== Erlang for beginners + +Chances are you are interested in using Cowboy, but have +no idea how to write an Erlang program. Fear not! This +chapter will help you get started. + +We recommend two books for beginners. You should read them +both at some point, as they cover Erlang from two entirely +different perspectives. + +=== Learn You Some Erlang for Great Good! + +The quickest way to get started with Erlang is by reading +a book with the funny name of http://learnyousomeerlang.com[LYSE], +as we affectionately call it. + +It will get right into the syntax and quickly answer the questions +a beginner would ask themselves, all the while showing funny +pictures and making insightful jokes. + +You can read an early version of the book online for free, +but you really should buy the much more refined paper and +ebook versions. + +=== Programming Erlang + +After writing some code, you will probably want to understand +the very concepts that make Erlang what it is today. These +are best explained by Joe Armstrong, the godfather of Erlang, +in his book http://pragprog.com/book/jaerlang2/programming-erlang[Programming Erlang]. + +Instead of going into every single details of the language, +Joe focuses on the central concepts behind Erlang, and shows +you how they can be used to write a variety of different +applications. diff --git a/docs/en/cowboy/2.0/guide/erlang_beginners/index.html b/docs/en/cowboy/2.0/guide/erlang_beginners/index.html new file mode 100644 index 00000000..4632dca9 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/erlang_beginners/index.html @@ -0,0 +1,175 @@ + + + + + + + + + + + + Nine Nines: Erlang for beginners + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Erlang for beginners

+ +

Chances are you are interested in using Cowboy, but have +no idea how to write an Erlang program. Fear not! This +chapter will help you get started.

+

We recommend two books for beginners. You should read them +both at some point, as they cover Erlang from two entirely +different perspectives.

+
+

Learn You Some Erlang for Great Good!

+
+

The quickest way to get started with Erlang is by reading +a book with the funny name of LYSE, +as we affectionately call it.

+

It will get right into the syntax and quickly answer the questions +a beginner would ask themselves, all the while showing funny +pictures and making insightful jokes.

+

You can read an early version of the book online for free, +but you really should buy the much more refined paper and +ebook versions.

+
+
+
+

Programming Erlang

+
+

After writing some code, you will probably want to understand +the very concepts that make Erlang what it is today. These +are best explained by Joe Armstrong, the godfather of Erlang, +in his book Programming Erlang.

+

Instead of going into every single details of the language, +Joe focuses on the central concepts behind Erlang, and shows +you how they can be used to write a variety of different +applications.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/erlang_web.asciidoc b/docs/en/cowboy/2.0/guide/erlang_web.asciidoc new file mode 100644 index 00000000..702e0437 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/erlang_web.asciidoc @@ -0,0 +1,176 @@ +[[erlang_web]] +== Erlang and the Web + +=== The Web is concurrent + +When you access a website there is little concurrency +involved. A few connections are opened and requests +are sent through these connections. Then the web page +is displayed on your screen. Your browser will only +open up to 4 or 8 connections to the server, depending +on your settings. This isn't much. + +But think about it. You are not the only one accessing +the server at the same time. There can be hundreds, if +not thousands, if not millions of connections to the +same server at the same time. + +Even today a lot of systems used in production haven't +solved the C10K problem (ten thousand concurrent connections). +And the ones who did are trying hard to get to the next +step, C100K, and are pretty far from it. + +Erlang meanwhile has no problem handling millions of +connections. At the time of writing there are application +servers written in Erlang that can handle more than two +million connections on a single server in a real production +application, with spare memory and CPU! + +The Web is concurrent, and Erlang is a language designed +for concurrency, so it is a perfect match. + +Of course, various platforms need to scale beyond a few +million connections. This is where Erlang's built-in +distribution mechanisms come in. If one server isn't +enough, add more! Erlang allows you to use the same code +for talking to local processes or to processes in other +parts of your cluster, which means you can scale very +quickly if the need arises. + +The Web has large userbases, and the Erlang platform was +designed to work in a distributed setting, so it is a +perfect match. + +Or is it? Surely you can find solutions to handle that many +concurrent connections with your favorite language... But all +these solutions will break down in the next few years. Why? +Firstly because servers don't get any more powerful, they +instead get a lot more cores and memory. This is only useful +if your application can use them properly, and Erlang is +light-years away from anything else in that area. Secondly, +today your computer and your phone are online, tomorrow your +watch, goggles, bike, car, fridge and tons of other devices +will also connect to various applications on the Internet. + +Only Erlang is prepared to deal with what's coming. + +=== The Web is soft real time + +What does soft real time mean, you ask? It means we want the +operations done as quickly as possible, and in the case of +web applications, it means we want the data propagated fast. + +In comparison, hard real time has a similar meaning, but also +has a hard time constraint, for example an operation needs to +be done in under N milliseconds otherwise the system fails +entirely. + +Users aren't that needy yet, they just want to get access +to their content in a reasonable delay, and they want the +actions they make to register at most a few seconds after +they submitted them, otherwise they'll start worrying about +whether it successfully went through. + +The Web is soft real time because taking longer to perform an +operation would be seen as bad quality of service. + +Erlang is a soft real time system. It will always run +processes fairly, a little at a time, switching to another +process after a while and preventing a single process to +steal resources from all others. This means that Erlang +can guarantee stable low latency of operations. + +Erlang provides the guarantees that the soft real time Web +requires. + +=== The Web is asynchronous + +Long ago, the Web was synchronous because HTTP was synchronous. +You fired a request, and then waited for a response. Not anymore. +It all began when XmlHttpRequest started being used. It allowed +the client to perform asynchronous calls to the server. + +Then Websocket appeared and allowed both the server and the client +to send data to the other endpoint completely asynchronously. The +data is contained within frames and no response is necessary. + +Erlang processes work the same. They send each other data contained +within messages and then continue running without needing a response. +They tend to spend most of their time inactive, waiting for a new +message, and the Erlang VM happily activate them when one is received. + +It is therefore quite easy to imagine Erlang being good at receiving +Websocket frames, which may come in at unpredictable times, pass the +data to the responsible processes which are always ready waiting for +new messages, and perform the operations required by only activating +the required parts of the system. + +The more recent Web technologies, like Websocket of course, but also +HTTP/2.0, are all fully asynchronous protocols. The concept +of requests and responses is retained of course, but anything could +be sent in between, by both the client or the browser, and the +responses could also be received in a completely different order. + +Erlang is by nature asynchronous and really good at it thanks to the +great engineering that has been done in the VM over the years. It's +only natural that it's so good at dealing with the asynchronous Web. + +=== The Web is omnipresent + +The Web has taken a very important part of our lives. We're +connected at all times, when we're on our phone, using our computer, +passing time using a tablet while in the bathroom... And this +isn't going to slow down, every single device at home or on us +will be connected. + +All these devices are always connected. And with the number of +alternatives to give you access to the content you seek, users +tend to not stick around when problems arise. Users today want +their applications to be always available and if it's having +too many issues they just move on. + +Despite this, when developers choose a product to use for building +web applications, their only concern seem to be "Is it fast?", +and they look around for synthetic benchmarks showing which one +is the fastest at sending "Hello world" with only a handful +concurrent connections. Web benchmarks haven't been representative +of reality in a long time, and are drifting further away as +time goes on. + +What developers should really ask themselves is "Can I service +all my users with no interruption?" and they'd find that they have +two choices. They can either hope for the best, or they can use +Erlang. + +Erlang is built for fault tolerance. When writing code in any other +language, you have to check all the return values and act accordingly +to avoid any unforeseen issues. If you're lucky, you won't miss +anything important. When writing Erlang code, you can just check +the success condition and ignore all errors. If an error happen, +the Erlang process crashes and is then restarted by a special +process called a supervisor. + +The Erlang developer thus has no need to fear about unhandled +errors, and can focus on handling only the errors that should +give some feedback to the user and let the system take care of +the rest. This also has the advantage of allowing him to write +a lot less code, and letting him sleep at night. + +Erlang's fault tolerance oriented design is the first piece of +what makes it the best choice for the omnipresent, always available +Web. + +The second piece is Erlang's built-in distribution. Distribution +is a key part of building a fault tolerant system, because it +allows you to handle bigger failures, like a whole server going +down, or even a data center entirely. + +Fault tolerance and distribution are important today, and will be +vital in the future of the Web. Erlang is ready. + +=== Erlang is the ideal platform for the Web + +Erlang provides all the important features that the Web requires +or will require in the near future. Erlang is a perfect match +for the Web, and it only makes sense to use it to build web +applications. diff --git a/docs/en/cowboy/2.0/guide/erlang_web/index.html b/docs/en/cowboy/2.0/guide/erlang_web/index.html new file mode 100644 index 00000000..8206392a --- /dev/null +++ b/docs/en/cowboy/2.0/guide/erlang_web/index.html @@ -0,0 +1,300 @@ + + + + + + + + + + + + Nine Nines: Erlang and the Web + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Erlang and the Web

+ +
+

The Web is concurrent

+
+

When you access a website there is little concurrency +involved. A few connections are opened and requests +are sent through these connections. Then the web page +is displayed on your screen. Your browser will only +open up to 4 or 8 connections to the server, depending +on your settings. This isn’t much.

+

But think about it. You are not the only one accessing +the server at the same time. There can be hundreds, if +not thousands, if not millions of connections to the +same server at the same time.

+

Even today a lot of systems used in production haven’t +solved the C10K problem (ten thousand concurrent connections). +And the ones who did are trying hard to get to the next +step, C100K, and are pretty far from it.

+

Erlang meanwhile has no problem handling millions of +connections. At the time of writing there are application +servers written in Erlang that can handle more than two +million connections on a single server in a real production +application, with spare memory and CPU!

+

The Web is concurrent, and Erlang is a language designed +for concurrency, so it is a perfect match.

+

Of course, various platforms need to scale beyond a few +million connections. This is where Erlang’s built-in +distribution mechanisms come in. If one server isn’t +enough, add more! Erlang allows you to use the same code +for talking to local processes or to processes in other +parts of your cluster, which means you can scale very +quickly if the need arises.

+

The Web has large userbases, and the Erlang platform was +designed to work in a distributed setting, so it is a +perfect match.

+

Or is it? Surely you can find solutions to handle that many +concurrent connections with your favorite language… But all +these solutions will break down in the next few years. Why? +Firstly because servers don’t get any more powerful, they +instead get a lot more cores and memory. This is only useful +if your application can use them properly, and Erlang is +light-years away from anything else in that area. Secondly, +today your computer and your phone are online, tomorrow your +watch, goggles, bike, car, fridge and tons of other devices +will also connect to various applications on the Internet.

+

Only Erlang is prepared to deal with what’s coming.

+
+
+
+

The Web is soft real time

+
+

What does soft real time mean, you ask? It means we want the +operations done as quickly as possible, and in the case of +web applications, it means we want the data propagated fast.

+

In comparison, hard real time has a similar meaning, but also +has a hard time constraint, for example an operation needs to +be done in under N milliseconds otherwise the system fails +entirely.

+

Users aren’t that needy yet, they just want to get access +to their content in a reasonable delay, and they want the +actions they make to register at most a few seconds after +they submitted them, otherwise they’ll start worrying about +whether it successfully went through.

+

The Web is soft real time because taking longer to perform an +operation would be seen as bad quality of service.

+

Erlang is a soft real time system. It will always run +processes fairly, a little at a time, switching to another +process after a while and preventing a single process to +steal resources from all others. This means that Erlang +can guarantee stable low latency of operations.

+

Erlang provides the guarantees that the soft real time Web +requires.

+
+
+
+

The Web is asynchronous

+
+

Long ago, the Web was synchronous because HTTP was synchronous. +You fired a request, and then waited for a response. Not anymore. +It all began when XmlHttpRequest started being used. It allowed +the client to perform asynchronous calls to the server.

+

Then Websocket appeared and allowed both the server and the client +to send data to the other endpoint completely asynchronously. The +data is contained within frames and no response is necessary.

+

Erlang processes work the same. They send each other data contained +within messages and then continue running without needing a response. +They tend to spend most of their time inactive, waiting for a new +message, and the Erlang VM happily activate them when one is received.

+

It is therefore quite easy to imagine Erlang being good at receiving +Websocket frames, which may come in at unpredictable times, pass the +data to the responsible processes which are always ready waiting for +new messages, and perform the operations required by only activating +the required parts of the system.

+

The more recent Web technologies, like Websocket of course, but also +HTTP/2.0, are all fully asynchronous protocols. The concept +of requests and responses is retained of course, but anything could +be sent in between, by both the client or the browser, and the +responses could also be received in a completely different order.

+

Erlang is by nature asynchronous and really good at it thanks to the +great engineering that has been done in the VM over the years. It’s +only natural that it’s so good at dealing with the asynchronous Web.

+
+
+
+

The Web is omnipresent

+
+

The Web has taken a very important part of our lives. We’re +connected at all times, when we’re on our phone, using our computer, +passing time using a tablet while in the bathroom… And this +isn’t going to slow down, every single device at home or on us +will be connected.

+

All these devices are always connected. And with the number of +alternatives to give you access to the content you seek, users +tend to not stick around when problems arise. Users today want +their applications to be always available and if it’s having +too many issues they just move on.

+

Despite this, when developers choose a product to use for building +web applications, their only concern seem to be "Is it fast?", +and they look around for synthetic benchmarks showing which one +is the fastest at sending "Hello world" with only a handful +concurrent connections. Web benchmarks haven’t been representative +of reality in a long time, and are drifting further away as +time goes on.

+

What developers should really ask themselves is "Can I service +all my users with no interruption?" and they’d find that they have +two choices. They can either hope for the best, or they can use +Erlang.

+

Erlang is built for fault tolerance. When writing code in any other +language, you have to check all the return values and act accordingly +to avoid any unforeseen issues. If you’re lucky, you won’t miss +anything important. When writing Erlang code, you can just check +the success condition and ignore all errors. If an error happen, +the Erlang process crashes and is then restarted by a special +process called a supervisor.

+

The Erlang developer thus has no need to fear about unhandled +errors, and can focus on handling only the errors that should +give some feedback to the user and let the system take care of +the rest. This also has the advantage of allowing him to write +a lot less code, and letting him sleep at night.

+

Erlang’s fault tolerance oriented design is the first piece of +what makes it the best choice for the omnipresent, always available +Web.

+

The second piece is Erlang’s built-in distribution. Distribution +is a key part of building a fault tolerant system, because it +allows you to handle bigger failures, like a whole server going +down, or even a data center entirely.

+

Fault tolerance and distribution are important today, and will be +vital in the future of the Web. Erlang is ready.

+
+
+
+

Erlang is the ideal platform for the Web

+
+

Erlang provides all the important features that the Web requires +or will require in the near future. Erlang is a perfect match +for the Web, and it only makes sense to use it to build web +applications.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/getting_started.asciidoc b/docs/en/cowboy/2.0/guide/getting_started.asciidoc new file mode 100644 index 00000000..679d9fe3 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/getting_started.asciidoc @@ -0,0 +1,141 @@ +[[getting_started]] +== Getting started + +Erlang is more than a language, it is also an operating system +for your applications. Erlang developers rarely write standalone +modules, they write libraries or applications, and then bundle +those into what is called a release. A release contains the +Erlang VM plus all applications required to run the node, so +it can be pushed to production directly. + +This chapter walks you through all the steps of setting up +Cowboy, writing your first application and generating your first +release. At the end of this chapter you should know everything +you need to push your first Cowboy application to production. + +=== Bootstrap + +We are going to use the https://github.com/ninenines/erlang.mk[Erlang.mk] +build system. It also offers bootstrap features allowing us to +quickly get started without having to deal with minute details. + +First, let's create the directory for our application. + +[source,bash] +$ mkdir hello_erlang +$ cd hello_erlang + +Then we need to download Erlang.mk. Either use the following +command or download it manually. + +[source,bash] +$ wget https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk + +We can now bootstrap our application. Since we are going to generate +a release, we will also bootstrap it at the same time. + +[source,bash] +$ make -f erlang.mk bootstrap bootstrap-rel + +This creates a Makefile, a base application, and the release files +necessary for creating the release. We can already build and start +this release. + +[source,bash] +---- +$ make run +... +(hello_erlang@127.0.0.1)1> +---- + +Entering the command `i().` will show the running processes, including +one called `hello_erlang_sup`. This is the supervisor for our +application. + +The release currently does nothing. In the rest of this chapter we +will add Cowboy as a dependency and write a simple "Hello world!" +handler. + +=== Cowboy setup + +Modifying the 'Makefile' allows the build system to know it needs to +fetch and compile Cowboy. To do that we simply need to add two lines +to our Makefile to make it look like this: + +[source,make] +---- +PROJECT = hello_erlang + +DEPS = cowboy +dep_cowboy_commit = master + +include erlang.mk +---- + +If you run `make run` now, Cowboy will be included in the release +and started automatically. This is not enough however, as Cowboy +doesn't do anything by default. We still need to tell Cowboy to +listen for connections. + +=== Listening for connections + +We will do this when our application starts. It's a two step process. +First we need to define and compile the dispatch list, a list of +routes that Cowboy will use to map requests to handler modules. +Then we tell Cowboy to listen for connections. + +Open the 'src/hello_erlang_app.erl' file and add the necessary +code to the `start/2` function to make it look like this: + +[source,erlang] +---- +start(_Type, _Args) -> + Dispatch = cowboy_router:compile([ + {'_', [{"/", hello_handler, []}]} + ]), + {ok, _} = cowboy:start_http(my_http_listener, 100, [{port, 8080}], + [{env, [{dispatch, Dispatch}]}] + ), + hello_erlang_sup:start_link(). +---- + +The dispatch list is explained in great details in the +xref:routing[Routing] chapter. For this tutorial we map the +path `/` to the handler module `hello_handler`. This module +doesn't exist yet, we still have to write it. + +If you build and start the release, then open http://localhost:8080 +in your browser, you will get an error because the module is missing. +Any other URL, like http://localhost:8080/test, will result in a +404 error. + +=== Handling requests + +Cowboy features different kinds of handlers, including REST +and Websocket handlers. For this tutorial we will use a plain +HTTP handler. + +First, let's generate a handler from a template. + +[source,bash] +$ make new t=cowboy_http n=hello_handler + +You can then open the 'src/hello_handler.erl' file and modify +the `init/2` function like this to send a reply. + +[source,erlang] +---- +init(Req, Opts) -> + Req2 = cowboy_req:reply(200, + [{<<"content-type">>, <<"text/plain">>}], + <<"Hello Erlang!">>, + Req), + {ok, Req2, Opts}. +---- + +What the above code does is send a `200 OK` reply, with the +`content-type` header set to `text/plain` and the response +body set to `Hello Erlang!`. + +If you run the release and open http://localhost:8080 +in your browser, you should get a nice `Hello Erlang!` displayed! diff --git a/docs/en/cowboy/2.0/guide/getting_started/index.html b/docs/en/cowboy/2.0/guide/getting_started/index.html new file mode 100644 index 00000000..065d5572 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/getting_started/index.html @@ -0,0 +1,289 @@ + + + + + + + + + + + + Nine Nines: Getting started + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Getting started

+ +

Erlang is more than a language, it is also an operating system +for your applications. Erlang developers rarely write standalone +modules, they write libraries or applications, and then bundle +those into what is called a release. A release contains the +Erlang VM plus all applications required to run the node, so +it can be pushed to production directly.

+

This chapter walks you through all the steps of setting up +Cowboy, writing your first application and generating your first +release. At the end of this chapter you should know everything +you need to push your first Cowboy application to production.

+
+

Bootstrap

+
+

We are going to use the Erlang.mk +build system. It also offers bootstrap features allowing us to +quickly get started without having to deal with minute details.

+

First, let’s create the directory for our application.

+
+
+
$ mkdir hello_erlang
+$ cd hello_erlang
+

Then we need to download Erlang.mk. Either use the following +command or download it manually.

+
+
+
$ wget https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk
+

We can now bootstrap our application. Since we are going to generate +a release, we will also bootstrap it at the same time.

+
+
+
$ make -f erlang.mk bootstrap bootstrap-rel
+

This creates a Makefile, a base application, and the release files +necessary for creating the release. We can already build and start +this release.

+
+
+
$ make run
+...
+(hello_erlang@127.0.0.1)1>
+

Entering the command i(). will show the running processes, including +one called hello_erlang_sup. This is the supervisor for our +application.

+

The release currently does nothing. In the rest of this chapter we +will add Cowboy as a dependency and write a simple "Hello world!" +handler.

+
+
+
+

Cowboy setup

+
+

Modifying the Makefile allows the build system to know it needs to +fetch and compile Cowboy. To do that we simply need to add two lines +to our Makefile to make it look like this:

+
+
+
PROJECT = hello_erlang
+
+DEPS = cowboy
+dep_cowboy_commit = master
+
+include erlang.mk
+

If you run make run now, Cowboy will be included in the release +and started automatically. This is not enough however, as Cowboy +doesn’t do anything by default. We still need to tell Cowboy to +listen for connections.

+
+
+
+

Listening for connections

+
+

We will do this when our application starts. It’s a two step process. +First we need to define and compile the dispatch list, a list of +routes that Cowboy will use to map requests to handler modules. +Then we tell Cowboy to listen for connections.

+

Open the src/hello_erlang_app.erl file and add the necessary +code to the start/2 function to make it look like this:

+
+
+
start(_Type, _Args) ->
+        Dispatch = cowboy_router:compile([
+                {'_', [{"/", hello_handler, []}]}
+        ]),
+        {ok, _} = cowboy:start_http(my_http_listener, 100, [{port, 8080}],
+                [{env, [{dispatch, Dispatch}]}]
+        ),
+        hello_erlang_sup:start_link().
+

The dispatch list is explained in great details in the +Routing chapter. For this tutorial we map the +path / to the handler module hello_handler. This module +doesn’t exist yet, we still have to write it.

+

If you build and start the release, then open http://localhost:8080 +in your browser, you will get an error because the module is missing. +Any other URL, like http://localhost:8080/test, will result in a +404 error.

+
+
+
+

Handling requests

+
+

Cowboy features different kinds of handlers, including REST +and Websocket handlers. For this tutorial we will use a plain +HTTP handler.

+

First, let’s generate a handler from a template.

+
+
+
$ make new t=cowboy_http n=hello_handler
+

You can then open the src/hello_handler.erl file and modify +the init/2 function like this to send a reply.

+
+
+
init(Req, Opts) ->
+        Req2 = cowboy_req:reply(200,
+                [{<<"content-type">>, <<"text/plain">>}],
+                <<"Hello Erlang!">>,
+                Req),
+        {ok, Req2, Opts}.
+

What the above code does is send a 200 OK reply, with the +content-type header set to text/plain and the response +body set to Hello Erlang!.

+

If you run the release and open http://localhost:8080 +in your browser, you should get a nice Hello Erlang! displayed!

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/handlers.asciidoc b/docs/en/cowboy/2.0/guide/handlers.asciidoc new file mode 100644 index 00000000..b6cefddc --- /dev/null +++ b/docs/en/cowboy/2.0/guide/handlers.asciidoc @@ -0,0 +1,105 @@ +[[handlers]] +== Handlers + +Handlers are Erlang modules that handle HTTP requests. + +=== Plain HTTP handlers + +The most basic handler in Cowboy implements the mandatory +`init/2` callback, manipulates the request, optionally +sends a response and then returns. + +This callback receives the xref:req[Req object] and the options +defined during the xref:routing[router configuration]. + +A handler that does nothing would look like this: + +[source,erlang] +---- +init(Req, _Opts) -> + {ok, Req, #state{}}. +---- + +Despite sending no reply, a `204 No Content` reply will be +sent to the client, as Cowboy makes sure that a reply is +sent for every request. + +We need to use the Req object for sending a reply. + +[source,erlang] +---- +init(Req, _Opts) -> + Req2 = cowboy_req:reply(200, [ + {<<"content-type">>, <<"text/plain">>} + ], <<"Hello World!">>, Req), + {ok, Req2, #state{}}. +---- + +As you can see we return a 3-tuple. `ok` means that the +handler ran successfully. The Req object is returned as +it may have been modified as is the case here: replying +returns a modified Req object that you need to return +back to Cowboy for proper operations. + +The last value of the tuple is a state that will be used +in every subsequent callbacks to this handler. Plain HTTP +handlers only have one additional callback, the optional +`terminate/3`. + +=== Other handlers + +The `init/2` callback can also be used to inform Cowboy +that this is a different kind of handler and that Cowboy +should switch to it. To do this you simply need to return +the module name of the handler type you want to switch to. + +Cowboy comes with three handler types you can switch to: +xref:rest_handlers[cowboy_rest], xref:ws_handlers[cowboy_websocket] +and xref:loop_handlers[cowboy_loop]. In addition to those you +can define your own handler types. + +Switching is simple. Instead of returning `ok`, you simply +return the name of the handler type you want to use. The +following snippet switches to a Websocket handler: + +[source,erlang] +---- +init(Req, _Opts) -> + {cowboy_websocket, Req, #state{}}. +---- + +You can also switch to your own custom handler type: + +[source,erlang] +---- +init(Req, _Opts) -> + {my_handler_type, Req, #state{}}. +---- + +How to implement a custom handler type is described in the +xref:sub_protocols[Sub protocols] chapter. + +=== Cleaning up + +All handlers coming with Cowboy allow the use of the optional +`terminate/3` callback. + +[source,erlang] +---- +terminate(_Reason, Req, State) -> + ok. +---- + +This callback is strictly reserved for any required cleanup. +You cannot send a response from this function. There is no +other return value. + +If you used the process dictionary, timers, monitors or may +be receiving messages, then you can use this function to clean +them up, as Cowboy might reuse the process for the next +keep-alive request. + +Note that while this function may be called in a Websocket +handler, it is generally not useful to do any clean up as +the process terminates immediately after calling this callback +when using Websocket. diff --git a/docs/en/cowboy/2.0/guide/handlers/index.html b/docs/en/cowboy/2.0/guide/handlers/index.html new file mode 100644 index 00000000..4d42be27 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/handlers/index.html @@ -0,0 +1,242 @@ + + + + + + + + + + + + Nine Nines: Handlers + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Handlers

+ +

Handlers are Erlang modules that handle HTTP requests.

+
+

Plain HTTP handlers

+
+

The most basic handler in Cowboy implements the mandatory +init/2 callback, manipulates the request, optionally +sends a response and then returns.

+

This callback receives the Req object and the options +defined during the router configuration.

+

A handler that does nothing would look like this:

+
+
+
init(Req, _Opts) ->
+    {ok, Req, #state{}}.
+

Despite sending no reply, a 204 No Content reply will be +sent to the client, as Cowboy makes sure that a reply is +sent for every request.

+

We need to use the Req object for sending a reply.

+
+
+
init(Req, _Opts) ->
+    Req2 = cowboy_req:reply(200, [
+        {<<"content-type">>, <<"text/plain">>}
+    ], <<"Hello World!">>, Req),
+    {ok, Req2, #state{}}.
+

As you can see we return a 3-tuple. ok means that the +handler ran successfully. The Req object is returned as +it may have been modified as is the case here: replying +returns a modified Req object that you need to return +back to Cowboy for proper operations.

+

The last value of the tuple is a state that will be used +in every subsequent callbacks to this handler. Plain HTTP +handlers only have one additional callback, the optional +terminate/3.

+
+
+
+

Other handlers

+
+

The init/2 callback can also be used to inform Cowboy +that this is a different kind of handler and that Cowboy +should switch to it. To do this you simply need to return +the module name of the handler type you want to switch to.

+

Cowboy comes with three handler types you can switch to: +cowboy_rest, cowboy_websocket +and cowboy_loop. In addition to those you +can define your own handler types.

+

Switching is simple. Instead of returning ok, you simply +return the name of the handler type you want to use. The +following snippet switches to a Websocket handler:

+
+
+
init(Req, _Opts) ->
+        {cowboy_websocket, Req, #state{}}.
+

You can also switch to your own custom handler type:

+
+
+
init(Req, _Opts) ->
+        {my_handler_type, Req, #state{}}.
+

How to implement a custom handler type is described in the +Sub protocols chapter.

+
+
+
+

Cleaning up

+
+

All handlers coming with Cowboy allow the use of the optional +terminate/3 callback.

+
+
+
terminate(_Reason, Req, State) ->
+    ok.
+

This callback is strictly reserved for any required cleanup. +You cannot send a response from this function. There is no +other return value.

+

If you used the process dictionary, timers, monitors or may +be receiving messages, then you can use this function to clean +them up, as Cowboy might reuse the process for the next +keep-alive request.

+

Note that while this function may be called in a Websocket +handler, it is generally not useful to do any clean up as +the process terminates immediately after calling this callback +when using Websocket.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/hooks.asciidoc b/docs/en/cowboy/2.0/guide/hooks.asciidoc new file mode 100644 index 00000000..fc79f8ac --- /dev/null +++ b/docs/en/cowboy/2.0/guide/hooks.asciidoc @@ -0,0 +1,46 @@ +[[hooks]] +== Hooks + +Hooks allow the user to customize Cowboy's behavior during specific +operations. + +=== Onresponse + +The `onresponse` hook is called right before sending the response +to the socket. It can be used for the purposes of logging responses, +or for modifying the response headers or body. The best example is +providing custom error pages. + +Note that this function MUST NOT crash. Cowboy may or may not send a +reply if this function crashes. If a reply is sent, the hook MUST +explicitly provide all headers that are needed. + +You can specify the `onresponse` hook when creating the listener. + +[source,erlang] +---- +cowboy:start_http(my_http_listener, 100, + [{port, 8080}], + [ + {env, [{dispatch, Dispatch}]}, + {onresponse, fun ?MODULE:custom_404_hook/4} + ] +). +---- + +The following hook function will provide a custom body for 404 errors +when it has not been provided before, and will let Cowboy proceed with +the default response otherwise. + +[source,erlang] +---- +custom_404_hook(404, Headers, <<>>, Req) -> + Body = <<"404 Not Found.">>, + Headers2 = lists:keyreplace(<<"content-length">>, 1, Headers, + {<<"content-length">>, integer_to_list(byte_size(Body))}), + cowboy_req:reply(404, Headers2, Body, Req); +custom_404_hook(_, _, _, Req) -> + Req. +---- + +Again, make sure to always return the last request object obtained. diff --git a/docs/en/cowboy/2.0/guide/hooks/index.html b/docs/en/cowboy/2.0/guide/hooks/index.html new file mode 100644 index 00000000..31b73d25 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/hooks/index.html @@ -0,0 +1,185 @@ + + + + + + + + + + + + Nine Nines: Hooks + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Hooks

+ +

Hooks allow the user to customize Cowboy’s behavior during specific +operations.

+
+

Onresponse

+
+

The onresponse hook is called right before sending the response +to the socket. It can be used for the purposes of logging responses, +or for modifying the response headers or body. The best example is +providing custom error pages.

+

Note that this function MUST NOT crash. Cowboy may or may not send a +reply if this function crashes. If a reply is sent, the hook MUST +explicitly provide all headers that are needed.

+

You can specify the onresponse hook when creating the listener.

+
+
+
cowboy:start_http(my_http_listener, 100,
+    [{port, 8080}],
+    [
+        {env, [{dispatch, Dispatch}]},
+        {onresponse, fun ?MODULE:custom_404_hook/4}
+    ]
+).
+

The following hook function will provide a custom body for 404 errors +when it has not been provided before, and will let Cowboy proceed with +the default response otherwise.

+
+
+
custom_404_hook(404, Headers, <<>>, Req) ->
+    Body = <<"404 Not Found.">>,
+    Headers2 = lists:keyreplace(<<"content-length">>, 1, Headers,
+        {<<"content-length">>, integer_to_list(byte_size(Body))}),
+    cowboy_req:reply(404, Headers2, Body, Req);
+custom_404_hook(_, _, _, Req) ->
+    Req.
+

Again, make sure to always return the last request object obtained.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/http_req_resp.png b/docs/en/cowboy/2.0/guide/http_req_resp.png new file mode 100644 index 00000000..8c9cae99 Binary files /dev/null and b/docs/en/cowboy/2.0/guide/http_req_resp.png differ diff --git a/docs/en/cowboy/2.0/guide/http_req_resp.svg b/docs/en/cowboy/2.0/guide/http_req_resp.svg new file mode 100644 index 00000000..d1e7f784 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/http_req_resp.svg @@ -0,0 +1,520 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + acceptor + parser + router + some text + handler + middlewares + some text + client + + + + + reply + onresponse + + diff --git a/docs/en/cowboy/2.0/guide/index.html b/docs/en/cowboy/2.0/guide/index.html new file mode 100644 index 00000000..53dab6d1 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/index.html @@ -0,0 +1,326 @@ + + + + + + + + + + + + Nine Nines: Cowboy User Guide + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Cowboy User Guide

+ +
+

Rationale

+
+
+
+
+
+

Introduction

+
+
+
+
+
+

Configuration

+
+
+
+
+
+

Request and response

+
+
+
+
+
+

REST

+
+
+
+
+
+

Websocket

+
+
+
+
+
+

Internals

+
+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/introduction.asciidoc b/docs/en/cowboy/2.0/guide/introduction.asciidoc new file mode 100644 index 00000000..9cdcbc99 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/introduction.asciidoc @@ -0,0 +1,56 @@ +[[introduction]] +== Introduction + +Cowboy is a small, fast and modular HTTP server written in Erlang. + +Cowboy aims to provide a complete HTTP stack, including its derivatives +Websocket and REST. Cowboy currently supports HTTP/1.0, HTTP/1.1, HTTP/2, +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 includes hundreds of tests and its code +is fully compliant with the Dialyzer. It is also well documented and +features both a Function Reference and a User Guide. + +=== Prerequisites + +Beginner Erlang knowledge is recommended for reading this guide. + +Knowledge of the HTTP protocol is recommended but not required, as it +will be detailed throughout the guide. + +=== Supported platforms + +Cowboy is tested and supported on Linux. + +Cowboy has been reported to work on other platforms, but we make no +guarantee that the experience will be safe and smooth. You are advised +to perform the necessary testing and security audits prior to deploying +on other platforms. + +Cowboy is developed for Erlang/OTP 17.0, 17.1.2 and 17.3. By the time +this branch gets released the target version will probably be 18.0 and +above. + +Cowboy may be compiled on other Erlang versions with small source code +modifications but there is no guarantee that it will work as expected. + +Cowboy uses the maps data type which was introduced in Erlang 17.0. + +=== Versioning + +Cowboy uses http://semver.org/[Semantic Versioning 2.0.0]. + +=== 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. + +The same applies to any other case insensitive value. diff --git a/docs/en/cowboy/2.0/guide/introduction/index.html b/docs/en/cowboy/2.0/guide/introduction/index.html new file mode 100644 index 00000000..1a43c339 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/introduction/index.html @@ -0,0 +1,193 @@ + + + + + + + + + + + + Nine Nines: Introduction + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Introduction

+ +

Cowboy is a small, fast and modular HTTP server written in Erlang.

+

Cowboy aims to provide a complete HTTP stack, including its derivatives +Websocket and REST. Cowboy currently supports HTTP/1.0, HTTP/1.1, HTTP/2, +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 includes hundreds of tests and its code +is fully compliant with the Dialyzer. It is also well documented and +features both a Function Reference and a User Guide.

+
+

Prerequisites

+
+

Beginner Erlang knowledge is recommended for reading this guide.

+

Knowledge of the HTTP protocol is recommended but not required, as it +will be detailed throughout the guide.

+
+
+
+

Supported platforms

+
+

Cowboy is tested and supported on Linux.

+

Cowboy has been reported to work on other platforms, but we make no +guarantee that the experience will be safe and smooth. You are advised +to perform the necessary testing and security audits prior to deploying +on other platforms.

+

Cowboy is developed for Erlang/OTP 17.0, 17.1.2 and 17.3. By the time +this branch gets released the target version will probably be 18.0 and +above.

+

Cowboy may be compiled on other Erlang versions with small source code +modifications but there is no guarantee that it will work as expected.

+

Cowboy uses the maps data type which was introduced in Erlang 17.0.

+
+
+
+

Versioning

+
+

Cowboy uses Semantic Versioning 2.0.0.

+
+
+
+

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.

+

The same applies to any other case insensitive value.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc b/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc new file mode 100644 index 00000000..58c42233 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc @@ -0,0 +1,146 @@ +[[loop_handlers]] +== Loop handlers + +Loop handlers are a special kind of HTTP handlers used when the +response can not be sent right away. The handler enters instead +a receive loop waiting for the right message before it can send +a response. + +Loop handlers are used for requests where a response might not +be immediately available, but where you would like to keep the +connection open for a while in case the response arrives. The +most known example of such practice is known as long polling. + +Loop handlers can also be used for requests where a response is +partially available and you need to stream the response body +while the connection is open. The most known example of such +practice is known as server-sent events. + +While the same can be accomplished using plain HTTP handlers, +it is recommended to use loop handlers because they are well-tested +and allow using built-in features like hibernation and timeouts. + +Loop handlers essentially wait for one or more Erlang messages +and feed these messages to the `info/3` callback. It also features +the `init/2` and `terminate/3` callbacks which work the same as +for plain HTTP handlers. + +=== Initialization + +The `init/2` function must return a `cowboy_loop` tuple to enable +loop handler behavior. This tuple may optionally contain +a timeout value and/or the atom `hibernate` to make the +process enter hibernation until a message is received. + +This snippet enables the loop handler. + +[source,erlang] +---- +init(Req, _Opts) -> + {cowboy_loop, Req, #state{}}. +---- + +However it is largely recommended that you set a timeout +value. The next example sets a timeout value of 30s and +also makes the process hibernate. + +[source,erlang] +---- +init(Req, _Opts) -> + {cowboy_loop, Req, #state{}, 30000, hibernate}. +---- + +=== Receive loop + +Once initialized, Cowboy will wait for messages to arrive +in the process' mailbox. When a message arrives, Cowboy +calls the `info/3` function with the message, the Req object +and the handler's state. + +The following snippet sends a reply when it receives a +`reply` message from another process, or waits for another +message otherwise. + +[source,erlang] +---- +info({reply, Body}, Req, State) -> + Req2 = cowboy_req:reply(200, [], Body, Req), + {stop, Req2, State}; +info(_Msg, Req, State) -> + {ok, Req, State, hibernate}. +---- + +Do note that the `reply` tuple here may be any message +and is simply an example. + +This callback may perform any necessary operation including +sending all or parts of a reply, and will subsequently +return a tuple indicating if more messages are to be expected. + +The callback may also choose to do nothing at all and just +skip the message received. + +If a reply is sent, then the `stop` tuple should be returned. +This will instruct Cowboy to end the request. + +Otherwise an `ok` tuple should be returned. + +=== Streaming loop + +Another common case well suited for loop handlers is +streaming data received in the form of Erlang messages. +This can be done by initiating a chunked reply in the +`init/2` callback and then using `cowboy_req:chunk/2` +every time a message is received. + +The following snippet does exactly that. As you can see +a chunk is sent every time a `chunk` message is received, +and the loop is stopped by sending an `eof` message. + +[source,erlang] +---- +init(Req, _Opts) -> + Req2 = cowboy_req:chunked_reply(200, [], Req), + {cowboy_loop, Req2, #state{}}. + +info(eof, Req, State) -> + {stop, Req, State}; +info({chunk, Chunk}, Req, State) -> + cowboy_req:chunk(Chunk, Req), + {ok, Req, State}; +info(_Msg, Req, State) -> + {ok, Req, State}. +---- + +==== Cleaning up + +It is recommended that you set the connection header to +`close` when replying, as this process may be reused for +a subsequent request. + +Please refer to the xref:handlers[Handlers chapter] +for general instructions about cleaning up. + +=== Timeout + +By default Cowboy will not attempt to close the connection +if there is no activity from the client. This is not always +desirable, which is why you can set a timeout. Cowboy will +close the connection if no data was received from the client +after the configured time. The timeout only needs to be set +once and can't be modified afterwards. + +Because the request may have had a body, or may be followed +by another request, Cowboy is forced to buffer all data it +receives. This data may grow to become too large though, +so there is a configurable limit for it. The default buffer +size is of 5000 bytes, but it may be changed by setting the +`loop_max_buffer` middleware environment value. + +=== Hibernate + +To save memory, you may hibernate the process in between +messages received. This is done by returning the atom +`hibernate` as part of the `loop` tuple callbacks normally +return. Just add the atom at the end and Cowboy will hibernate +accordingly. diff --git a/docs/en/cowboy/2.0/guide/loop_handlers/index.html b/docs/en/cowboy/2.0/guide/loop_handlers/index.html new file mode 100644 index 00000000..d3081aac --- /dev/null +++ b/docs/en/cowboy/2.0/guide/loop_handlers/index.html @@ -0,0 +1,284 @@ + + + + + + + + + + + + Nine Nines: Loop handlers + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Loop handlers

+ +

Loop handlers are a special kind of HTTP handlers used when the +response can not be sent right away. The handler enters instead +a receive loop waiting for the right message before it can send +a response.

+

Loop handlers are used for requests where a response might not +be immediately available, but where you would like to keep the +connection open for a while in case the response arrives. The +most known example of such practice is known as long polling.

+

Loop handlers can also be used for requests where a response is +partially available and you need to stream the response body +while the connection is open. The most known example of such +practice is known as server-sent events.

+

While the same can be accomplished using plain HTTP handlers, +it is recommended to use loop handlers because they are well-tested +and allow using built-in features like hibernation and timeouts.

+

Loop handlers essentially wait for one or more Erlang messages +and feed these messages to the info/3 callback. It also features +the init/2 and terminate/3 callbacks which work the same as +for plain HTTP handlers.

+
+

Initialization

+
+

The init/2 function must return a cowboy_loop tuple to enable +loop handler behavior. This tuple may optionally contain +a timeout value and/or the atom hibernate to make the +process enter hibernation until a message is received.

+

This snippet enables the loop handler.

+
+
+
init(Req, _Opts) ->
+    {cowboy_loop, Req, #state{}}.
+

However it is largely recommended that you set a timeout +value. The next example sets a timeout value of 30s and +also makes the process hibernate.

+
+
+
init(Req, _Opts) ->
+    {cowboy_loop, Req, #state{}, 30000, hibernate}.
+
+
+
+

Receive loop

+
+

Once initialized, Cowboy will wait for messages to arrive +in the process' mailbox. When a message arrives, Cowboy +calls the info/3 function with the message, the Req object +and the handler’s state.

+

The following snippet sends a reply when it receives a +reply message from another process, or waits for another +message otherwise.

+
+
+
info({reply, Body}, Req, State) ->
+    Req2 = cowboy_req:reply(200, [], Body, Req),
+    {stop, Req2, State};
+info(_Msg, Req, State) ->
+    {ok, Req, State, hibernate}.
+

Do note that the reply tuple here may be any message +and is simply an example.

+

This callback may perform any necessary operation including +sending all or parts of a reply, and will subsequently +return a tuple indicating if more messages are to be expected.

+

The callback may also choose to do nothing at all and just +skip the message received.

+

If a reply is sent, then the stop tuple should be returned. +This will instruct Cowboy to end the request.

+

Otherwise an ok tuple should be returned.

+
+
+
+

Streaming loop

+
+

Another common case well suited for loop handlers is +streaming data received in the form of Erlang messages. +This can be done by initiating a chunked reply in the +init/2 callback and then using cowboy_req:chunk/2 +every time a message is received.

+

The following snippet does exactly that. As you can see +a chunk is sent every time a chunk message is received, +and the loop is stopped by sending an eof message.

+
+
+
init(Req, _Opts) ->
+    Req2 = cowboy_req:chunked_reply(200, [], Req),
+    {cowboy_loop, Req2, #state{}}.
+
+info(eof, Req, State) ->
+    {stop, Req, State};
+info({chunk, Chunk}, Req, State) ->
+    cowboy_req:chunk(Chunk, Req),
+    {ok, Req, State};
+info(_Msg, Req, State) ->
+    {ok, Req, State}.
+
+

Cleaning up

+

It is recommended that you set the connection header to +close when replying, as this process may be reused for +a subsequent request.

+

Please refer to the Handlers chapter +for general instructions about cleaning up.

+
+
+
+
+

Timeout

+
+

By default Cowboy will not attempt to close the connection +if there is no activity from the client. This is not always +desirable, which is why you can set a timeout. Cowboy will +close the connection if no data was received from the client +after the configured time. The timeout only needs to be set +once and can’t be modified afterwards.

+

Because the request may have had a body, or may be followed +by another request, Cowboy is forced to buffer all data it +receives. This data may grow to become too large though, +so there is a configurable limit for it. The default buffer +size is of 5000 bytes, but it may be changed by setting the +loop_max_buffer middleware environment value.

+
+
+
+

Hibernate

+
+

To save memory, you may hibernate the process in between +messages received. This is done by returning the atom +hibernate as part of the loop tuple callbacks normally +return. Just add the atom at the end and Cowboy will hibernate +accordingly.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/middlewares.asciidoc b/docs/en/cowboy/2.0/guide/middlewares.asciidoc new file mode 100644 index 00000000..e6be30dd --- /dev/null +++ b/docs/en/cowboy/2.0/guide/middlewares.asciidoc @@ -0,0 +1,69 @@ +[[middlewares]] +== Middlewares + +Cowboy delegates the request processing to middleware components. +By default, two middlewares are defined, for the routing and handling +of the request, as is detailed in most of this guide. + +Middlewares give you complete control over how requests are to be +processed. You can add your own middlewares to the mix or completely +change the chain of middlewares as needed. + +Cowboy will execute all middlewares in the given order, unless one +of them decides to stop processing. + +=== Usage + +Middlewares only need to implement a single callback: `execute/2`. +It is defined in the `cowboy_middleware` behavior. + +This callback has two arguments. The first is the `Req` object. +The second is the environment. + +Middlewares can return one of three different values: + +* `{ok, Req, Env}` to continue the request processing +* `{suspend, Module, Function, Args}` to hibernate +* `{stop, Req}` to stop processing and move on to the next request + +Of note is that when hibernating, processing will resume on the given +MFA, discarding all previous stacktrace. Make sure you keep the `Req` +and `Env` in the arguments of this MFA for later use. + +If an error happens during middleware processing, Cowboy will not try +to send an error back to the socket, the process will just crash. It +is up to the middleware to make sure that a reply is sent if something +goes wrong. + +=== Configuration + +The middleware environment is defined as the `env` protocol option. +In the previous chapters we saw it briefly when we needed to pass +the routing information. It is a list of tuples with the first +element being an atom and the second any Erlang term. + +Two values in the environment are reserved: + +* `listener` contains the name of the listener +* `result` contains the result of the processing + +The `listener` value is always defined. The `result` value can be +set by any middleware. If set to anything other than `ok`, Cowboy +will not process any subsequent requests on this connection. + +The middlewares that come with Cowboy may define or require other +environment values to perform. + +You can update the environment by calling the `cowboy:set_env/3` +convenience function, adding or replacing a value in the environment. + +=== Routing middleware + +The routing middleware requires the `dispatch` value. If routing +succeeds, it will put the handler name and options in the `handler` +and `handler_opts` values of the environment, respectively. + +=== Handler middleware + +The handler middleware requires the `handler` and `handler_opts` +values. It puts the result of the request handling into `result`. diff --git a/docs/en/cowboy/2.0/guide/middlewares/index.html b/docs/en/cowboy/2.0/guide/middlewares/index.html new file mode 100644 index 00000000..09894d10 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/middlewares/index.html @@ -0,0 +1,228 @@ + + + + + + + + + + + + Nine Nines: Middlewares + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Middlewares

+ +

Cowboy delegates the request processing to middleware components. +By default, two middlewares are defined, for the routing and handling +of the request, as is detailed in most of this guide.

+

Middlewares give you complete control over how requests are to be +processed. You can add your own middlewares to the mix or completely +change the chain of middlewares as needed.

+

Cowboy will execute all middlewares in the given order, unless one +of them decides to stop processing.

+
+

Usage

+
+

Middlewares only need to implement a single callback: execute/2. +It is defined in the cowboy_middleware behavior.

+

This callback has two arguments. The first is the Req object. +The second is the environment.

+

Middlewares can return one of three different values:

+
    +
  • +

    +{ok, Req, Env} to continue the request processing +

    +
    • +
  • +

    +{suspend, Module, Function, Args} to hibernate +

    +
    • +
  • +

    +{stop, Req} to stop processing and move on to the next request +

    +
    • +
+

Of note is that when hibernating, processing will resume on the given +MFA, discarding all previous stacktrace. Make sure you keep the Req +and Env in the arguments of this MFA for later use.

+

If an error happens during middleware processing, Cowboy will not try +to send an error back to the socket, the process will just crash. It +is up to the middleware to make sure that a reply is sent if something +goes wrong.

+
+
+
+

Configuration

+
+

The middleware environment is defined as the env protocol option. +In the previous chapters we saw it briefly when we needed to pass +the routing information. It is a list of tuples with the first +element being an atom and the second any Erlang term.

+

Two values in the environment are reserved:

+
    +
  • +

    +listener contains the name of the listener +

    +
    • +
  • +

    +result contains the result of the processing +

    +
    • +
+

The listener value is always defined. The result value can be +set by any middleware. If set to anything other than ok, Cowboy +will not process any subsequent requests on this connection.

+

The middlewares that come with Cowboy may define or require other +environment values to perform.

+

You can update the environment by calling the cowboy:set_env/3 +convenience function, adding or replacing a value in the environment.

+
+
+
+

Routing middleware

+
+

The routing middleware requires the dispatch value. If routing +succeeds, it will put the handler name and options in the handler +and handler_opts values of the environment, respectively.

+
+
+
+

Handler middleware

+
+

The handler middleware requires the handler and handler_opts +values. It puts the result of the request handling into result.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/modern_web.asciidoc b/docs/en/cowboy/2.0/guide/modern_web.asciidoc new file mode 100644 index 00000000..732972f0 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/modern_web.asciidoc @@ -0,0 +1,200 @@ +[[modern_web]] +== The modern Web + +Let's take a look at various technologies from the beginnings +of the Web up to this day, and get a preview of what's +coming next. + +Cowboy is compatible with all the technology cited in this +chapter except of course HTTP/2.0 which has no implementation +in the wild at the time of writing. + +=== The prehistoric Web + +HTTP was initially created to serve HTML pages and only +had the GET method for retrieving them. This initial +version is documented and is sometimes called HTTP/0.9. +HTTP/1.0 defined the GET, HEAD and POST methods, and +was able to send data with POST requests. + +HTTP/1.0 works in a very simple way. A TCP connection +is first established to the server. Then a request is +sent. Then the server sends a response back and closes +the connection. + +Suffice to say, HTTP/1.0 is not very efficient. Opening +a TCP connection takes some time, and pages containing +many assets load much slower than they could because of +this. + +Most improvements done in recent years focused on reducing +this load time and reducing the latency of the requests. + +=== HTTP/1.1 + +HTTP/1.1 quickly followed and added a keep-alive mechanism +to allow using the same connection for many requests, as +well as streaming capabilities, allowing an endpoint to send +a body in well defined chunks. + +HTTP/1.1 defines the OPTIONS, GET, HEAD, POST, PUT, DELETE, +TRACE and CONNECT methods. The PATCH method was added in more +recent years. It also improves the caching capabilities with +the introduction of many headers. + +HTTP/1.1 still works like HTTP/1.0 does, except the connection +can be kept alive for subsequent requests. This however allows +clients to perform what is called as pipelining: sending many +requests in a row, and then processing the responses which will +be received in the same order as the requests. + +=== REST + +The design of HTTP/1.1 was influenced by the REST architectural +style. REST, or REpresentational State Transfer, is a style of +architecture for loosely connected distributed systems. + +REST defines constraints that systems must obey to in order to +be RESTful. A system which doesn't follow all the constraints +cannot be considered RESTful. + +REST is a client-server architecture with a clean separation +of concerns between the client and the server. They communicate +by referencing resources. Resources can be identified, but +also manipulated. A resource representation has a media type +and information about whether it can be cached and how. Hypermedia +determines how resources are related and how they can be used. +REST is also stateless. All requests contain the complete +information necessary to perform the action. + +HTTP/1.1 defines all the methods, headers and semantics required +to implement RESTful systems. + +REST is most often used when designing web application APIs +which are generally meant to be used by executable code directly. + +=== XmlHttpRequest + +Also know as AJAX, this technology allows Javascript code running +on a web page to perform asynchronous requests to the server. +This is what started the move from static websites to dynamic +web applications. + +XmlHttpRequest still performs HTTP requests under the hood, +and then waits for a response, but the Javascript code can +continue to run until the response arrives. It will then receive +the response through a callback previously defined. + +This is of course still requests initiated by the client, +the server still had no way of pushing data to the client +on its own, so new technology appeared to allow that. + +=== Long-polling + +Polling was a technique used to overcome the fact that the server +cannot push data directly to the client. Therefore the client had +to repeatedly create a connection, make a request, get a response, +then try again a few seconds later. This is overly expensive and +adds an additional delay before the client receives the data. + +Polling was necessary to implement message queues and other +similar mechanisms, where a user must be informed of something +when it happens, rather than when he refreshes the page next. +A typical example would be a chat application. + +Long-polling was created to reduce the server load by creating +less connections, but also to improve latency by getting the +response back to the client as soon as it becomes available +on the server. + +Long-polling works in a similar manner to polling, except the +request will not get a response immediately. Instead the server +leaves it open until it has a response to send. After getting +the response, the client creates a new request and gets back +to waiting. + +You probably guessed by now that long-polling is a hack, and +like most hacks it can suffer from unforeseen issues, in this +case it doesn't always play well with proxies. + +=== HTML5 + +HTML5 is, of course, the HTML version after HTML4. But HTML5 +emerged to solve a specific problem: dynamic web applications. + +HTML was initially created to write web pages which compose +a website. But soon people and companies wanted to use HTML +to write more and more complex websites, eventually known as +web applications. They are for example your news reader, your +email client in the browser, or your video streaming website. + +Because HTML wasn't enough, they started using proprietary +solutions, often implemented using plug-ins. This wasn't +perfect of course, but worked well enough for most people. + +However, the needs for a standard solution eventually became +apparent. The browser needed to be able to play media natively. +It needed to be able to draw anything. It needed an efficient +way of streaming events to the server, but also receiving +events from the server. + +The solution went on to become HTML5. At the time of writing +it is being standardized. + +=== EventSource + +EventSource, sometimes also called Server-Sent Events, is a +technology allowing servers to push data to HTML5 applications. + +EventSource is one-way communication channel from the server +to the client. The client has no means to talk to the server +other than by using HTTP requests. + +It consists of a Javascript object allowing setting up an +EventSource connection to the server, and a very small protocol +for sending events to the client on top of the HTTP/1.1 +connection. + +EventSource is a lightweight solution that only works for +UTF-8 encoded text data. Binary data and text data encoded +differently are not allowed by the protocol. A heavier but +more generic approach can be found in Websocket. + +=== Websocket + +Websocket is a protocol built on top of HTTP/1.1 that provides +a two-ways communication channel between the client and the +server. Communication is asynchronous and can occur concurrently. + +It consists of a Javascript object allowing setting up a +Websocket connection to the server, and a binary based +protocol for sending data to the server or the client. + +Websocket connections can transfer either UTF-8 encoded text +data or binary data. The protocol also includes support for +implementing a ping/pong mechanism, allowing the server and +the client to have more confidence that the connection is still +alive. + +A Websocket connection can be used to transfer any kind of data, +small or big, text or binary. Because of this Websocket is +sometimes used for communication between systems. + +=== HTTP/2 + +HTTP/2 is an attempt to reduce page loading time by opening a +single connection per server, keeping it open for subsequent +requests, and also by compressing the HTTP headers to reduce +the size of requests. + +HTTP/2 is compatible with HTTP/1.1 semantics, and is actually +just a different way of performing HTTP requests and responses, +by using binary frames instead of a text-based protocol. +HTTP/2 also allows the server to send extra responses following +a request. This is meant to allow sending the resources +associated with the request before the client requests them, +saving latency when loading websites. + +Browsers make use of TLS Application-Layer Protocol Negotiation +extension to upgrade to an HTTP/2 connection seamlessly if the +server supports it. diff --git a/docs/en/cowboy/2.0/guide/modern_web/index.html b/docs/en/cowboy/2.0/guide/modern_web/index.html new file mode 100644 index 00000000..69761906 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/modern_web/index.html @@ -0,0 +1,329 @@ + + + + + + + + + + + + Nine Nines: The modern Web + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

The modern Web

+ +

Let’s take a look at various technologies from the beginnings +of the Web up to this day, and get a preview of what’s +coming next.

+

Cowboy is compatible with all the technology cited in this +chapter except of course HTTP/2.0 which has no implementation +in the wild at the time of writing.

+
+

The prehistoric Web

+
+

HTTP was initially created to serve HTML pages and only +had the GET method for retrieving them. This initial +version is documented and is sometimes called HTTP/0.9. +HTTP/1.0 defined the GET, HEAD and POST methods, and +was able to send data with POST requests.

+

HTTP/1.0 works in a very simple way. A TCP connection +is first established to the server. Then a request is +sent. Then the server sends a response back and closes +the connection.

+

Suffice to say, HTTP/1.0 is not very efficient. Opening +a TCP connection takes some time, and pages containing +many assets load much slower than they could because of +this.

+

Most improvements done in recent years focused on reducing +this load time and reducing the latency of the requests.

+
+
+
+

HTTP/1.1

+
+

HTTP/1.1 quickly followed and added a keep-alive mechanism +to allow using the same connection for many requests, as +well as streaming capabilities, allowing an endpoint to send +a body in well defined chunks.

+

HTTP/1.1 defines the OPTIONS, GET, HEAD, POST, PUT, DELETE, +TRACE and CONNECT methods. The PATCH method was added in more +recent years. It also improves the caching capabilities with +the introduction of many headers.

+

HTTP/1.1 still works like HTTP/1.0 does, except the connection +can be kept alive for subsequent requests. This however allows +clients to perform what is called as pipelining: sending many +requests in a row, and then processing the responses which will +be received in the same order as the requests.

+
+
+
+

REST

+
+

The design of HTTP/1.1 was influenced by the REST architectural +style. REST, or REpresentational State Transfer, is a style of +architecture for loosely connected distributed systems.

+

REST defines constraints that systems must obey to in order to +be RESTful. A system which doesn’t follow all the constraints +cannot be considered RESTful.

+

REST is a client-server architecture with a clean separation +of concerns between the client and the server. They communicate +by referencing resources. Resources can be identified, but +also manipulated. A resource representation has a media type +and information about whether it can be cached and how. Hypermedia +determines how resources are related and how they can be used. +REST is also stateless. All requests contain the complete +information necessary to perform the action.

+

HTTP/1.1 defines all the methods, headers and semantics required +to implement RESTful systems.

+

REST is most often used when designing web application APIs +which are generally meant to be used by executable code directly.

+
+
+
+

XmlHttpRequest

+
+

Also know as AJAX, this technology allows Javascript code running +on a web page to perform asynchronous requests to the server. +This is what started the move from static websites to dynamic +web applications.

+

XmlHttpRequest still performs HTTP requests under the hood, +and then waits for a response, but the Javascript code can +continue to run until the response arrives. It will then receive +the response through a callback previously defined.

+

This is of course still requests initiated by the client, +the server still had no way of pushing data to the client +on its own, so new technology appeared to allow that.

+
+
+
+

Long-polling

+
+

Polling was a technique used to overcome the fact that the server +cannot push data directly to the client. Therefore the client had +to repeatedly create a connection, make a request, get a response, +then try again a few seconds later. This is overly expensive and +adds an additional delay before the client receives the data.

+

Polling was necessary to implement message queues and other +similar mechanisms, where a user must be informed of something +when it happens, rather than when he refreshes the page next. +A typical example would be a chat application.

+

Long-polling was created to reduce the server load by creating +less connections, but also to improve latency by getting the +response back to the client as soon as it becomes available +on the server.

+

Long-polling works in a similar manner to polling, except the +request will not get a response immediately. Instead the server +leaves it open until it has a response to send. After getting +the response, the client creates a new request and gets back +to waiting.

+

You probably guessed by now that long-polling is a hack, and +like most hacks it can suffer from unforeseen issues, in this +case it doesn’t always play well with proxies.

+
+
+
+

HTML5

+
+

HTML5 is, of course, the HTML version after HTML4. But HTML5 +emerged to solve a specific problem: dynamic web applications.

+

HTML was initially created to write web pages which compose +a website. But soon people and companies wanted to use HTML +to write more and more complex websites, eventually known as +web applications. They are for example your news reader, your +email client in the browser, or your video streaming website.

+

Because HTML wasn’t enough, they started using proprietary +solutions, often implemented using plug-ins. This wasn’t +perfect of course, but worked well enough for most people.

+

However, the needs for a standard solution eventually became +apparent. The browser needed to be able to play media natively. +It needed to be able to draw anything. It needed an efficient +way of streaming events to the server, but also receiving +events from the server.

+

The solution went on to become HTML5. At the time of writing +it is being standardized.

+
+
+
+

EventSource

+
+

EventSource, sometimes also called Server-Sent Events, is a +technology allowing servers to push data to HTML5 applications.

+

EventSource is one-way communication channel from the server +to the client. The client has no means to talk to the server +other than by using HTTP requests.

+

It consists of a Javascript object allowing setting up an +EventSource connection to the server, and a very small protocol +for sending events to the client on top of the HTTP/1.1 +connection.

+

EventSource is a lightweight solution that only works for +UTF-8 encoded text data. Binary data and text data encoded +differently are not allowed by the protocol. A heavier but +more generic approach can be found in Websocket.

+
+
+
+

Websocket

+
+

Websocket is a protocol built on top of HTTP/1.1 that provides +a two-ways communication channel between the client and the +server. Communication is asynchronous and can occur concurrently.

+

It consists of a Javascript object allowing setting up a +Websocket connection to the server, and a binary based +protocol for sending data to the server or the client.

+

Websocket connections can transfer either UTF-8 encoded text +data or binary data. The protocol also includes support for +implementing a ping/pong mechanism, allowing the server and +the client to have more confidence that the connection is still +alive.

+

A Websocket connection can be used to transfer any kind of data, +small or big, text or binary. Because of this Websocket is +sometimes used for communication between systems.

+
+
+
+

HTTP/2

+
+

HTTP/2 is an attempt to reduce page loading time by opening a +single connection per server, keeping it open for subsequent +requests, and also by compressing the HTTP headers to reduce +the size of requests.

+

HTTP/2 is compatible with HTTP/1.1 semantics, and is actually +just a different way of performing HTTP requests and responses, +by using binary frames instead of a text-based protocol. +HTTP/2 also allows the server to send extra responses following +a request. This is meant to allow sending the resources +associated with the request before the client requests them, +saving latency when loading websites.

+

Browsers make use of TLS Application-Layer Protocol Negotiation +extension to upgrade to an HTTP/2 connection seamlessly if the +server supports it.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/multipart.asciidoc b/docs/en/cowboy/2.0/guide/multipart.asciidoc new file mode 100644 index 00000000..20d53d51 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/multipart.asciidoc @@ -0,0 +1,169 @@ +[[multipart]] +== Multipart requests + +Multipart originates from MIME, an Internet standard that +extends the format of emails. Multipart messages are a +container for parts of any content-type. + +For example, a multipart message may have a part +containing text and a second part containing an +image. This is what allows you to attach files +to emails. + +In the context of HTTP, multipart is most often used +with the `multipart/form-data` content-type. This is +the content-type you have to use when you want browsers +to be allowed to upload files through HTML forms. + +Multipart is of course not required for uploading +files, it is only required when you want to do so +through HTML forms. + +You can read and parse multipart messages using the +Req object directly. + +Cowboy defines two functions that allows you to get +information about each part and read their contents. + +=== Structure + +A multipart message is a list of parts. Parts may +contain either a multipart message or a non-multipart +content-type. This allows parts to be arranged in a +tree structure, although this is a rare case as far +as the Web is concerned. + +=== Form-data + +In the normal case, when a form is submitted, the +browser will use the `application/x-www-form-urlencoded` +content-type. This type is just a list of keys and +values and is therefore not fit for uploading files. + +That's where the `multipart/form-data` content-type +comes in. When the form is configured to use this +content-type, the browser will use one part of the +message for each form field. This means that a file +input field will be sent in its own part, but the +same applies to all other kinds of fields. + +A form with a text input, a file input and a select +choice box will result in a multipart message with +three parts, one for each field. + +The browser does its best to determine the content-type +of the files it sends this way, but you should not +rely on it for determining the contents of the file. +Proper investigation of the contents is recommended. + +=== Checking the content-type + +While there is a variety of multipart messages, the +most common on the Web is `multipart/form-data`. It's +the type of message being sent when an HTML form +allows uploading files. + +You can quickly figure out if a multipart message +has been sent by parsing the `content-type` header. + +[source,erlang] +---- +{<<"multipart">>, <<"form-data">>, _} + = cowboy_req:parse_header(<<"content-type">>, Req). +---- + +=== Reading a multipart message + +To read a message you have to iterate over all its +parts. Then, for each part, you can inspect its headers +and read its body. + +[source,erlang] +---- +multipart(Req) -> + case cowboy_req:part(Req) of + {ok, _Headers, Req2} -> + {ok, _Body, Req3} = cowboy_req:part_body(Req2), + multipart(Req3); + {done, Req2} -> + Req2 + end. +---- + +Parts do not have a size limit. When a part body is +too big, Cowboy will return what it read so far and +allow you to continue if you wish to do so. + +The function `cow_multipart:form_data/1` can be used +to quickly obtain information about a part from a +`multipart/form-data` message. This function will +tell you if the part is for a normal field or if it +is a file being uploaded. + +This can be used for example to allow large part bodies +for files but crash when a normal field is too large. + +[source,erlang] +---- +multipart(Req) -> + case cowboy_req:part(Req) of + {ok, Headers, Req2} -> + Req4 = case cow_multipart:form_data(Headers) of + {data, _FieldName} -> + {ok, _Body, Req3} = cowboy_req:part_body(Req2), + Req3; + {file, _FieldName, _Filename, _CType, _CTransferEncoding} -> + stream_file(Req2) + end, + multipart(Req4); + {done, Req2} -> + Req2 + end. + +stream_file(Req) -> + case cowboy_req:part_body(Req) of + {ok, _Body, Req2} -> + Req2; + {more, _Body, Req2} -> + stream_file(Req2) + end. +---- + +By default the body chunk Cowboy will return is limited +to 8MB. This can of course be overriden. Both functions +can take a second argument, the same list of options that +will be passed to `cowboy_req:body/2` function. + +=== Skipping unwanted parts + +If you do not want to read a part's body, you can skip it. +Skipping is easy. If you do not call the function to read +the part's body, Cowboy will automatically skip it when +you request the next part. + +The following snippet reads all part headers and skips +all bodies: + +[source,erlang] +---- +multipart(Req) -> + case cowboy_req:part(Req) of + {ok, _Headers, Req2} -> + multipart(Req2); + {done, Req2} -> + Req2 + end. +---- + +Similarly, if you start reading the body and it ends up +being too big, you can simply continue with the next part, +Cowboy will automatically skip what remains. + +Note that the skipping rate may not be adequate for your +application. If you observe poor performance when skipping, +you might want to consider manually skipping by calling +the `cowboy_req:part_body/1` function directly. + +And if you started reading the message but decide that you +do not need the remaining parts, you can simply stop reading +entirely and Cowboy will automatically figure out what to do. diff --git a/docs/en/cowboy/2.0/guide/multipart/index.html b/docs/en/cowboy/2.0/guide/multipart/index.html new file mode 100644 index 00000000..2a443f10 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/multipart/index.html @@ -0,0 +1,305 @@ + + + + + + + + + + + + Nine Nines: Multipart requests + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Multipart requests

+ +

Multipart originates from MIME, an Internet standard that +extends the format of emails. Multipart messages are a +container for parts of any content-type.

+

For example, a multipart message may have a part +containing text and a second part containing an +image. This is what allows you to attach files +to emails.

+

In the context of HTTP, multipart is most often used +with the multipart/form-data content-type. This is +the content-type you have to use when you want browsers +to be allowed to upload files through HTML forms.

+

Multipart is of course not required for uploading +files, it is only required when you want to do so +through HTML forms.

+

You can read and parse multipart messages using the +Req object directly.

+

Cowboy defines two functions that allows you to get +information about each part and read their contents.

+
+

Structure

+
+

A multipart message is a list of parts. Parts may +contain either a multipart message or a non-multipart +content-type. This allows parts to be arranged in a +tree structure, although this is a rare case as far +as the Web is concerned.

+
+
+
+

Form-data

+
+

In the normal case, when a form is submitted, the +browser will use the application/x-www-form-urlencoded +content-type. This type is just a list of keys and +values and is therefore not fit for uploading files.

+

That’s where the multipart/form-data content-type +comes in. When the form is configured to use this +content-type, the browser will use one part of the +message for each form field. This means that a file +input field will be sent in its own part, but the +same applies to all other kinds of fields.

+

A form with a text input, a file input and a select +choice box will result in a multipart message with +three parts, one for each field.

+

The browser does its best to determine the content-type +of the files it sends this way, but you should not +rely on it for determining the contents of the file. +Proper investigation of the contents is recommended.

+
+
+
+

Checking the content-type

+
+

While there is a variety of multipart messages, the +most common on the Web is multipart/form-data. It’s +the type of message being sent when an HTML form +allows uploading files.

+

You can quickly figure out if a multipart message +has been sent by parsing the content-type header.

+
+
+
{<<"multipart">>, <<"form-data">>, _}
+    = cowboy_req:parse_header(<<"content-type">>, Req).
+
+
+
+

Reading a multipart message

+
+

To read a message you have to iterate over all its +parts. Then, for each part, you can inspect its headers +and read its body.

+
+
+
multipart(Req) ->
+    case cowboy_req:part(Req) of
+        {ok, _Headers, Req2} ->
+            {ok, _Body, Req3} = cowboy_req:part_body(Req2),
+            multipart(Req3);
+        {done, Req2} ->
+            Req2
+    end.
+

Parts do not have a size limit. When a part body is +too big, Cowboy will return what it read so far and +allow you to continue if you wish to do so.

+

The function cow_multipart:form_data/1 can be used +to quickly obtain information about a part from a +multipart/form-data message. This function will +tell you if the part is for a normal field or if it +is a file being uploaded.

+

This can be used for example to allow large part bodies +for files but crash when a normal field is too large.

+
+
+
multipart(Req) ->
+    case cowboy_req:part(Req) of
+        {ok, Headers, Req2} ->
+            Req4 = case cow_multipart:form_data(Headers) of
+                {data, _FieldName} ->
+                    {ok, _Body, Req3} = cowboy_req:part_body(Req2),
+                    Req3;
+                {file, _FieldName, _Filename, _CType, _CTransferEncoding} ->
+                    stream_file(Req2)
+            end,
+            multipart(Req4);
+        {done, Req2} ->
+            Req2
+    end.
+
+stream_file(Req) ->
+    case cowboy_req:part_body(Req) of
+        {ok, _Body, Req2} ->
+            Req2;
+        {more, _Body, Req2} ->
+            stream_file(Req2)
+    end.
+

By default the body chunk Cowboy will return is limited +to 8MB. This can of course be overriden. Both functions +can take a second argument, the same list of options that +will be passed to cowboy_req:body/2 function.

+
+
+
+

Skipping unwanted parts

+
+

If you do not want to read a part’s body, you can skip it. +Skipping is easy. If you do not call the function to read +the part’s body, Cowboy will automatically skip it when +you request the next part.

+

The following snippet reads all part headers and skips +all bodies:

+
+
+
multipart(Req) ->
+    case cowboy_req:part(Req) of
+        {ok, _Headers, Req2} ->
+            multipart(Req2);
+        {done, Req2} ->
+            Req2
+    end.
+

Similarly, if you start reading the body and it ends up +being too big, you can simply continue with the next part, +Cowboy will automatically skip what remains.

+

Note that the skipping rate may not be adequate for your +application. If you observe poor performance when skipping, +you might want to consider manually skipping by calling +the cowboy_req:part_body/1 function directly.

+

And if you started reading the message but decide that you +do not need the remaining parts, you can simply stop reading +entirely and Cowboy will automatically figure out what to do.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/overview.asciidoc b/docs/en/cowboy/2.0/guide/overview.asciidoc new file mode 100644 index 00000000..3e5cbb74 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/overview.asciidoc @@ -0,0 +1,150 @@ +[[overview]] +== Request overview + +This chapter explains the different steps a request +goes through until a response is sent, along with +details of the Cowboy implementation. + +=== Request/response + +As you already know, HTTP clients connect to the server and +send a request for a resource; the server then sends a +response containing the resource if it could obtain it. + +Before the server can send the resource, however, it +needs to perform many different operations to read the +request, find the resource, prepare the response being +sent and often other related operations the user can +add like writing logs. + +Requests take the following route in Cowboy: + +image::http_req_resp.png[HTTP request/response flowchart] + +This shows the default middlewares, but they may be +configured differently in your setup. The dark green +indicates the points where you can hook your own code, +the light green is the Cowboy code that you can of +course configure as needed. + +The `acceptor` is the part of the server that accepts +the connection and create an Erlang process to handle +it. The `parser` then starts reading from the socket +and handling requests as they come until the socket +is closed. + +A response may be sent at many different points in the +life of the request. If Cowboy can't parse the request, +it gives up with an error response. If the router can't +find the resource, it sends a not found error. Your +own code can of course send a response at any time. + +When a response is sent, you can optionally modify it +or act upon it by enabling the `onresponse` hook. By +default the response is sent directly to the client. + +=== And then? + +Behavior depends on what protocol is in use. + +HTTP/1.0 can only process one request per connection, +so Cowboy will close the connection immediately after +it sends the response. + +HTTP/1.1 allows the client to request that the server +keeps the connection alive. This mechanism is described +in the next section. + +HTTP/2 is designed to allow sending multiple requests +asynchronously on the same connection. Details on what +this means for your application is described in this +chapter. + +=== Keep-alive (HTTP/1.1) + +With HTTP/1.1, the connection may be left open for +subsequent requests to come. This mechanism is called +`keep-alive`. + +When the client sends a request to the server, it includes +a header indicating whether it would like to leave the +socket open. The server may or may not accept, indicating +its choice by sending the same header in the response. + +Cowboy will include this header automatically in all +responses to HTTP/1.1 requests. You can however force +the closing of the socket if you want. When Cowboy sees +you want to send a `connection: close` header, it will +not override it and will close the connection as soon +as the reply is sent. + +This snippet will force Cowboy to close the connection. + +[source,erlang] +---- +Req2 = cowboy_req:reply(200, [ + {<<"connection">>, <<"close">>}, +], <<"Closing the socket in 3.. 2.. 1..">>, Req). +---- + +Cowboy will only accept a certain number of new requests +on the same connection. By default it will run up to 100 +requests. This number can be changed by setting the +`max_keepalive` configuration value when starting an +HTTP listener. + +[source,erlang] +---- +cowboy:start_http(my_http_listener, 100, [{port, 8080}], [ + {env, [{dispatch, Dispatch}]}, + {max_keepalive, 5} +]). +---- + +Cowboy implements the keep-alive mechanism by reusing +the same process for all requests. This allows Cowboy +to save memory. This works well because most code will +not have any side effect impacting subsequent requests. +But it also means you need to clean up if you do have +code with side effects. The `terminate/3` function can +be used for this purpose. + +=== Pipelining (HTTP/1.1) + +While HTTP is designed as a sequential protocol, with +the client sending a request and then waiting for the +response from the server, nothing prevents the client +from sending more requests to the server without waiting +for the response, due to how sockets work. The server +still handles the requests sequentially and sends the +responses in the same order. + +This mechanism is called pipelining. It allows reducing +latency when a client needs to request many resources +at the same time. This is used by browsers when requesting +static files for example. + +This is handled automatically by the server. + +=== Asynchronous requests (HTTP/2) + +In HTTP/2, the client can send a request at any time. +And the server can send a response at any time too. + +This means for example that the client does not need +to wait for a request to be fully sent to send another, +it is possible to interleave a request with the request +body of another request. The same is true with responses. +Responses may also be sent in a different order. + +Because requests and responses are fully asynchronous, +Cowboy creates a new process for each request, and these +processes are managed by another process that handles the +connection itself. + +HTTP/2 servers may also decide to send resources to the +client before the client requests them. This is especially +useful for sending static files associated with the HTML +page requested, as this reduces the latency of the overall +response. Cowboy does not support this particular mechanism +at this point, however. diff --git a/docs/en/cowboy/2.0/guide/overview/index.html b/docs/en/cowboy/2.0/guide/overview/index.html new file mode 100644 index 00000000..70a191dd --- /dev/null +++ b/docs/en/cowboy/2.0/guide/overview/index.html @@ -0,0 +1,285 @@ + + + + + + + + + + + + Nine Nines: Request overview + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Request overview

+ +

This chapter explains the different steps a request +goes through until a response is sent, along with +details of the Cowboy implementation.

+
+

Request/response

+
+

As you already know, HTTP clients connect to the server and +send a request for a resource; the server then sends a +response containing the resource if it could obtain it.

+

Before the server can send the resource, however, it +needs to perform many different operations to read the +request, find the resource, prepare the response being +sent and often other related operations the user can +add like writing logs.

+

Requests take the following route in Cowboy:

+
+
+HTTP request/response flowchart +
+
+

This shows the default middlewares, but they may be +configured differently in your setup. The dark green +indicates the points where you can hook your own code, +the light green is the Cowboy code that you can of +course configure as needed.

+

The acceptor is the part of the server that accepts +the connection and create an Erlang process to handle +it. The parser then starts reading from the socket +and handling requests as they come until the socket +is closed.

+

A response may be sent at many different points in the +life of the request. If Cowboy can’t parse the request, +it gives up with an error response. If the router can’t +find the resource, it sends a not found error. Your +own code can of course send a response at any time.

+

When a response is sent, you can optionally modify it +or act upon it by enabling the onresponse hook. By +default the response is sent directly to the client.

+
+
+
+

And then?

+
+

Behavior depends on what protocol is in use.

+

HTTP/1.0 can only process one request per connection, +so Cowboy will close the connection immediately after +it sends the response.

+

HTTP/1.1 allows the client to request that the server +keeps the connection alive. This mechanism is described +in the next section.

+

HTTP/2 is designed to allow sending multiple requests +asynchronously on the same connection. Details on what +this means for your application is described in this +chapter.

+
+
+
+

Keep-alive (HTTP/1.1)

+
+

With HTTP/1.1, the connection may be left open for +subsequent requests to come. This mechanism is called +keep-alive.

+

When the client sends a request to the server, it includes +a header indicating whether it would like to leave the +socket open. The server may or may not accept, indicating +its choice by sending the same header in the response.

+

Cowboy will include this header automatically in all +responses to HTTP/1.1 requests. You can however force +the closing of the socket if you want. When Cowboy sees +you want to send a connection: close header, it will +not override it and will close the connection as soon +as the reply is sent.

+

This snippet will force Cowboy to close the connection.

+
+
+
Req2 = cowboy_req:reply(200, [
+    {<<"connection">>, <<"close">>},
+], <<"Closing the socket in 3.. 2.. 1..">>, Req).
+

Cowboy will only accept a certain number of new requests +on the same connection. By default it will run up to 100 +requests. This number can be changed by setting the +max_keepalive configuration value when starting an +HTTP listener.

+
+
+
cowboy:start_http(my_http_listener, 100, [{port, 8080}], [
+        {env, [{dispatch, Dispatch}]},
+        {max_keepalive, 5}
+]).
+

Cowboy implements the keep-alive mechanism by reusing +the same process for all requests. This allows Cowboy +to save memory. This works well because most code will +not have any side effect impacting subsequent requests. +But it also means you need to clean up if you do have +code with side effects. The terminate/3 function can +be used for this purpose.

+
+
+
+

Pipelining (HTTP/1.1)

+
+

While HTTP is designed as a sequential protocol, with +the client sending a request and then waiting for the +response from the server, nothing prevents the client +from sending more requests to the server without waiting +for the response, due to how sockets work. The server +still handles the requests sequentially and sends the +responses in the same order.

+

This mechanism is called pipelining. It allows reducing +latency when a client needs to request many resources +at the same time. This is used by browsers when requesting +static files for example.

+

This is handled automatically by the server.

+
+
+
+

Asynchronous requests (HTTP/2)

+
+

In HTTP/2, the client can send a request at any time. +And the server can send a response at any time too.

+

This means for example that the client does not need +to wait for a request to be fully sent to send another, +it is possible to interleave a request with the request +body of another request. The same is true with responses. +Responses may also be sent in a different order.

+

Because requests and responses are fully asynchronous, +Cowboy creates a new process for each request, and these +processes are managed by another process that handles the +connection itself.

+

HTTP/2 servers may also decide to send resources to the +client before the client requests them. This is especially +useful for sending static files associated with the HTML +page requested, as this reduces the latency of the overall +response. Cowboy does not support this particular mechanism +at this point, however.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/req.asciidoc b/docs/en/cowboy/2.0/guide/req.asciidoc new file mode 100644 index 00000000..09d442af --- /dev/null +++ b/docs/en/cowboy/2.0/guide/req.asciidoc @@ -0,0 +1,247 @@ +[[req]] +== The Req object + +The Req object is this variable that you will use to obtain +information about a request, read the body of the request +and send a response. + +=== A special variable + +While we call it an "object", it is not an object in the +OOP sense of the term. In fact it is completely opaque +to you and the only way you can perform operations using +it is by calling the functions from the `cowboy_req` +module. + +Almost all the calls to the `cowboy_req` module will +return an updated request object. Just like you would +keep the updated `State` variable in a gen_server, +you MUST keep the updated `Req` variable in a Cowboy +handler. Cowboy will use this object to know whether +a response has been sent when the handler has finished +executing. + +The Req object allows accessing both immutable and +mutable state. This means that calling some of the +functions twice will not produce the same result. +For example, when streaming the request body, the +function will return the body by chunks, one at a +time, until there is none left. + +=== Overview of the cowboy_req interface + +With the exception of functions manipulating the request +body, all functions return a single value. Depending on +the function this can be the requested value (method, +host, path, ...), a boolean (has_body, has_resp_header...) +a new Req object (set_resp_body, set_resp_header...), or +simply the atom `ok` (chunk, continue, ...). + +The request body reading functions may return `{Result, Req}` +or `{Result, Value, Req}`. The functions in this category +are `body/{1,2}`, `body_qs/{1,2}`, `part/{1,2}`, `part_body/{1,2}`. + +This chapter covers the access functions mainly. Cookies, +request body and response functions are covered in their +own chapters. + +=== Request + +When a client performs a request, it first sends a few required +values. They are sent differently depending on the protocol +being used, but the intent is the same. They indicate to the +server the type of action it wants to do and how to locate +the resource to perform it on. + +The method identifies the action. Standard methods include +GET, HEAD, OPTIONS, PATCH, POST, PUT, DELETE. Method names +are case sensitive. + +[source,erlang] +Method = cowboy_req:method(Req). + +The host, port and path parts of the URL identify the resource +being accessed. The host and port information may not be +available if the client uses HTTP/1.0. + +[source,erlang] +Host = cowboy_req:host(Req), +Port = cowboy_req:port(Req), +Path = cowboy_req:path(Req). + +The version used by the client can of course also be obtained. + +[source,erlang] +Version = cowboy_req:version(Req). + +Do note however that clients claiming to implement one version +of the protocol does not mean they implement it fully, or even +properly. + +=== Bindings + +After routing the request, bindings are available. Bindings +are these parts of the host or path that you chose to extract +when defining the routes of your application. + +You can fetch a single binding. The value will be `undefined` +if the binding doesn't exist. + +[source,erlang] +Binding = cowboy_req:binding(my_binding, Req). + +If you need a different value when the binding doesn't exist, +you can change the default. + +[source,erlang] +Binding = cowboy_req:binding(my_binding, Req, 42). + +You can also obtain all bindings in one call. They will be +returned as a list of key/value tuples. + +[source,erlang] +AllBindings = cowboy_req:bindings(Req). + +If you used `...` at the beginning of the route's pattern +for the host, you can retrieve the matched part of the host. +The value will be `undefined` otherwise. + +[source,erlang] +HostInfo = cowboy_req:host_info(Req). + +Similarly, if you used `...` at the end of the route's +pattern for the path, you can retrieve the matched part, +or get `undefined` otherwise. + +[source,erlang] +PathInfo = cowboy_req:path_info(Req). + +=== Query string + +The raw query string can be obtained directly. + +[source,erlang] +Qs = cowboy_req:qs(Req). + +You can parse the query string and then use standard library +functions to access individual values. + +[source,erlang] +QsVals = cowboy_req:parse_qs(Req), +{_, Lang} = lists:keyfind(<<"lang">>, 1, QsVals). + +You can match the query string into a map. + +[source,erlang] +#{id := ID, lang := Lang} = cowboy_req:match_qs([id, lang], Req). + +You can use constraints to validate the values while matching +them. The following snippet will crash if the `id` value is +not an integer number or if the `lang` value is empty. Additionally +the `id` value will be converted to an integer term, saving +you a conversion step. + +[source,erlang] +QsMap = cowboy_req:match_qs([{id, int}, {lang, nonempty}], Req). + +Note that in the case of duplicate query string keys, the map +value will become a list of the different values. + +Read more about ^constraints^. + +A default value can be provided. The default will be used +if the `lang` key is not found. It will not be used if +the key is found but has an empty value. + +[source,erlang] +#{lang := Lang} = cowboy_req:match_qs([{lang, [], <<"en-US">>}], Req). + +If no default is provided and the value is missing, the +query string is deemed invalid and the process will crash. + +=== Request URL + +You can reconstruct the full URL of the resource. + +[source,erlang] +URL = cowboy_req:url(Req). + +You can also obtain only the base of the URL, excluding the +path and query string. + +[source,erlang] +BaseURL = cowboy_req:host_url(Req). + +=== Headers + +Cowboy allows you to obtain the header values as string, +or parsed into a more meaningful representation. + +This will get the string value of a header. + +[source,erlang] +HeaderVal = cowboy_req:header(<<"content-type">>, Req). + +You can of course set a default in case the header is missing. + +[source,erlang] +HeaderVal = cowboy_req:header(<<"content-type">>, Req, <<"text/plain">>). + +And also obtain all headers. + +[source,erlang] +AllHeaders = cowboy_req:headers(Req). + +To parse the previous header, simply call `parse_header/{2,3}` +where you would call `header/{2,3}` otherwise. + +[source,erlang] +ParsedVal = cowboy_req:parse_header(<<"content-type">>, Req). + +Cowboy will crash if it doesn't know how to parse the given +header, or if the value is invalid. + +You can of course define a default value. Note that the default +value you specify here is the parsed value you'd like to get +by default. + +[source,erlang] +---- +ParsedVal = cowboy_req:parse_header(<<"content-type">>, Req, + {<<"text">>, <<"plain">>, []}). +---- + +The list of known headers and default values is defined in the +manual. + +=== Meta + +Cowboy will sometimes associate some meta information with +the request. Built-in meta values are listed in the manual +for their respective modules. + +This will get a meta value. The returned value will be `undefined` +if it isn't defined. + +[source,erlang] +MetaVal = cowboy_req:meta(websocket_version, Req). + +You can change the default value if needed. + +[source,erlang] +MetaVal = cowboy_req:meta(websocket_version, Req, 13). + +You can also define your own meta values. The name must be +an `atom()`. + +[source,erlang] +Req2 = cowboy_req:set_meta(the_answer, 42, Req). + +=== Peer + +You can obtain the peer address and port number. This is +not necessarily the actual IP and port of the client, but +rather the one of the machine that connected to the server. + +[source,erlang] +{IP, Port} = cowboy_req:peer(Req). diff --git a/docs/en/cowboy/2.0/guide/req/index.html b/docs/en/cowboy/2.0/guide/req/index.html new file mode 100644 index 00000000..c3442c64 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/req/index.html @@ -0,0 +1,443 @@ + + + + + + + + + + + + Nine Nines: The Req object + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

The Req object

+ +

The Req object is this variable that you will use to obtain +information about a request, read the body of the request +and send a response.

+
+

A special variable

+
+

While we call it an "object", it is not an object in the +OOP sense of the term. In fact it is completely opaque +to you and the only way you can perform operations using +it is by calling the functions from the cowboy_req +module.

+

Almost all the calls to the cowboy_req module will +return an updated request object. Just like you would +keep the updated State variable in a gen_server, +you MUST keep the updated Req variable in a Cowboy +handler. Cowboy will use this object to know whether +a response has been sent when the handler has finished +executing.

+

The Req object allows accessing both immutable and +mutable state. This means that calling some of the +functions twice will not produce the same result. +For example, when streaming the request body, the +function will return the body by chunks, one at a +time, until there is none left.

+
+
+
+

Overview of the cowboy_req interface

+
+

With the exception of functions manipulating the request +body, all functions return a single value. Depending on +the function this can be the requested value (method, +host, path, …), a boolean (has_body, has_resp_header…) +a new Req object (set_resp_body, set_resp_header…), or +simply the atom ok (chunk, continue, …).

+

The request body reading functions may return {Result, Req} +or {Result, Value, Req}. The functions in this category +are body/{1,2}, body_qs/{1,2}, part/{1,2}, part_body/{1,2}.

+

This chapter covers the access functions mainly. Cookies, +request body and response functions are covered in their +own chapters.

+
+
+
+

Request

+
+

When a client performs a request, it first sends a few required +values. They are sent differently depending on the protocol +being used, but the intent is the same. They indicate to the +server the type of action it wants to do and how to locate +the resource to perform it on.

+

The method identifies the action. Standard methods include +GET, HEAD, OPTIONS, PATCH, POST, PUT, DELETE. Method names +are case sensitive.

+
+
+
Method = cowboy_req:method(Req).
+

The host, port and path parts of the URL identify the resource +being accessed. The host and port information may not be +available if the client uses HTTP/1.0.

+
+
+
Host = cowboy_req:host(Req),
+Port = cowboy_req:port(Req),
+Path = cowboy_req:path(Req).
+

The version used by the client can of course also be obtained.

+
+
+
Version = cowboy_req:version(Req).
+

Do note however that clients claiming to implement one version +of the protocol does not mean they implement it fully, or even +properly.

+
+
+
+

Bindings

+
+

After routing the request, bindings are available. Bindings +are these parts of the host or path that you chose to extract +when defining the routes of your application.

+

You can fetch a single binding. The value will be undefined +if the binding doesn’t exist.

+
+
+
Binding = cowboy_req:binding(my_binding, Req).
+

If you need a different value when the binding doesn’t exist, +you can change the default.

+
+
+
Binding = cowboy_req:binding(my_binding, Req, 42).
+

You can also obtain all bindings in one call. They will be +returned as a list of key/value tuples.

+
+
+
AllBindings = cowboy_req:bindings(Req).
+

If you used ... at the beginning of the route’s pattern +for the host, you can retrieve the matched part of the host. +The value will be undefined otherwise.

+
+
+
HostInfo = cowboy_req:host_info(Req).
+

Similarly, if you used ... at the end of the route’s +pattern for the path, you can retrieve the matched part, +or get undefined otherwise.

+
+
+
PathInfo = cowboy_req:path_info(Req).
+
+
+
+

Query string

+
+

The raw query string can be obtained directly.

+
+
+
Qs = cowboy_req:qs(Req).
+

You can parse the query string and then use standard library +functions to access individual values.

+
+
+
QsVals = cowboy_req:parse_qs(Req),
+{_, Lang} = lists:keyfind(<<"lang">>, 1, QsVals).
+

You can match the query string into a map.

+
+
+
#{id := ID, lang := Lang} = cowboy_req:match_qs([id, lang], Req).
+

You can use constraints to validate the values while matching +them. The following snippet will crash if the id value is +not an integer number or if the lang value is empty. Additionally +the id value will be converted to an integer term, saving +you a conversion step.

+
+
+
QsMap = cowboy_req:match_qs([{id, int}, {lang, nonempty}], Req).
+

Note that in the case of duplicate query string keys, the map +value will become a list of the different values.

+

Read more about constraints.

+

A default value can be provided. The default will be used +if the lang key is not found. It will not be used if +the key is found but has an empty value.

+
+
+
#{lang := Lang} = cowboy_req:match_qs([{lang, [], <<"en-US">>}], Req).
+

If no default is provided and the value is missing, the +query string is deemed invalid and the process will crash.

+
+
+
+

Request URL

+
+

You can reconstruct the full URL of the resource.

+
+
+
URL = cowboy_req:url(Req).
+

You can also obtain only the base of the URL, excluding the +path and query string.

+
+
+
BaseURL = cowboy_req:host_url(Req).
+
+
+
+

Headers

+
+

Cowboy allows you to obtain the header values as string, +or parsed into a more meaningful representation.

+

This will get the string value of a header.

+
+
+
HeaderVal = cowboy_req:header(<<"content-type">>, Req).
+

You can of course set a default in case the header is missing.

+
+
+
HeaderVal = cowboy_req:header(<<"content-type">>, Req, <<"text/plain">>).
+

And also obtain all headers.

+
+
+
AllHeaders = cowboy_req:headers(Req).
+

To parse the previous header, simply call parse_header/{2,3} +where you would call header/{2,3} otherwise.

+
+
+
ParsedVal = cowboy_req:parse_header(<<"content-type">>, Req).
+

Cowboy will crash if it doesn’t know how to parse the given +header, or if the value is invalid.

+

You can of course define a default value. Note that the default +value you specify here is the parsed value you’d like to get +by default.

+
+
+
ParsedVal = cowboy_req:parse_header(<<"content-type">>, Req,
+        {<<"text">>, <<"plain">>, []}).
+

The list of known headers and default values is defined in the +manual.

+
+
+
+

Meta

+
+

Cowboy will sometimes associate some meta information with +the request. Built-in meta values are listed in the manual +for their respective modules.

+

This will get a meta value. The returned value will be undefined +if it isn’t defined.

+
+
+
MetaVal = cowboy_req:meta(websocket_version, Req).
+

You can change the default value if needed.

+
+
+
MetaVal = cowboy_req:meta(websocket_version, Req, 13).
+

You can also define your own meta values. The name must be +an atom().

+
+
+
Req2 = cowboy_req:set_meta(the_answer, 42, Req).
+
+
+
+

Peer

+
+

You can obtain the peer address and port number. This is +not necessarily the actual IP and port of the client, but +rather the one of the machine that connected to the server.

+
+
+
{IP, Port} = cowboy_req:peer(Req).
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/req_body.asciidoc b/docs/en/cowboy/2.0/guide/req_body.asciidoc new file mode 100644 index 00000000..d2a43d24 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/req_body.asciidoc @@ -0,0 +1,152 @@ +[[req_body]] +== Reading the request body + +The Req object also allows you to read the request body. + +Because the request body can be of any size, all body +reading operations will only work once, as Cowboy will +not cache the result of these operations. + +Cowboy will not attempt to read the body until you do. +If handler execution ends without reading it, Cowboy +will simply skip it. + +Cowboy provides different ways to read the request body. +You can read it directly, stream it, but also read and +parse in a single call for form urlencoded formats or +multipart. All of these except multipart are covered in +this chapter. Multipart is covered later on in the guide. + +=== Check for request body + +You can check whether a body was sent with the request. + +[source,erlang] +cowboy_req:has_body(Req). + +It will return `true` if there is a request body, and +`false` otherwise. + +Note that it is generally safe to assume that a body is +sent for `POST`, `PUT` and `PATCH` requests, without +having to explicitly check for it. + +=== Request body length + +You can obtain the body length if it was sent with the +request. + +[source,erlang] +Length = cowboy_req:body_length(Req). + +The value returned will be `undefined` if the length +couldn't be figured out from the request headers. If +there's a body but no length is given, this means that +the chunked transfer-encoding was used. You can read +chunked bodies by using the stream functions. + +=== Reading the body + +You can read the whole body directly in one call. + +[source,erlang] +{ok, Body, Req2} = cowboy_req:body(Req). + +By default, Cowboy will attempt to read up to a +size of 8MB. You can override this limit as needed. + +[source,erlang] +{ok, Body, Req2} = cowboy_req:body(Req, [{length, 100000000}]). + +You can also disable it. + +[source,erlang] +{ok, Body, Req2} = cowboy_req:body(Req, [{length, infinity}]). + +It is recommended that you do not disable it for public +facing websites. + +If the body is larger than the limit, then Cowboy will return +a `more` tuple instead, allowing you to stream it if you +would like to. + +=== Streaming the body + +You can stream the request body by chunks. + +Cowboy returns a `more` tuple when there is more body to +be read, and an `ok` tuple for the last chunk. This allows +you to loop over all chunks. + +[source,erlang] +---- +body_to_console(Req) -> + case cowboy_req:body(Req) of + {ok, Data, Req2} -> + io:format("~s", [Data]), + Req2; + {more, Data, Req2} -> + io:format("~s", [Data]), + body_to_console(Req2) + end. +---- + +You can of course set the `length` option to configure the +size of chunks. + +=== Rate of data transmission + +You can control the rate of data transmission by setting +options when calling body functions. This applies not only +to the functions described in this chapter, but also to +the multipart functions. + +The `read_length` option defines the maximum amount of data +to be received from the socket at once, in bytes. + +The `read_timeout` option defines the time Cowboy waits +before that amount is received, in milliseconds. + +=== Transfer and content decoding + +Cowboy will by default decode the chunked transfer-encoding +if any. It will not decode any content-encoding by default. + +The first time you call a body function you can set the +`transfer_decode` and `content_decode` options. If the body +was already started being read these options are simply +ignored. + +The following example shows how to set both options. + +[source,erlang] +---- +{ok, Data, Req2} = cowboy_req:body(Req, [ + {transfer_decode, fun transfer_decode/2, TransferState}, + {content_decode, fun content_decode/1} +]). +---- + +=== Reading a form urlencoded body + +You can directly obtain a list of key/value pairs if the +body was sent using the application/x-www-form-urlencoded +content-type. + +[source,erlang] +{ok, KeyValues, Req2} = cowboy_req:body_qs(Req). + +You can then retrieve an individual value from that list. + +[source,erlang] +{_, Lang} = lists:keyfind(lang, 1, KeyValues). + +You should not attempt to match on the list as the order +of the values is undefined. + +By default Cowboy will reject bodies with a size above +64KB when using this function. You can override this limit +by setting the `length` option. + +[source,erlang] +{ok, KeyValues, Req2} = cowboy_req:body_qs(Req, [{length, 2000000}]). diff --git a/docs/en/cowboy/2.0/guide/req_body/index.html b/docs/en/cowboy/2.0/guide/req_body/index.html new file mode 100644 index 00000000..ac43be1d --- /dev/null +++ b/docs/en/cowboy/2.0/guide/req_body/index.html @@ -0,0 +1,312 @@ + + + + + + + + + + + + Nine Nines: Reading the request body + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Reading the request body

+ +

The Req object also allows you to read the request body.

+

Because the request body can be of any size, all body +reading operations will only work once, as Cowboy will +not cache the result of these operations.

+

Cowboy will not attempt to read the body until you do. +If handler execution ends without reading it, Cowboy +will simply skip it.

+

Cowboy provides different ways to read the request body. +You can read it directly, stream it, but also read and +parse in a single call for form urlencoded formats or +multipart. All of these except multipart are covered in +this chapter. Multipart is covered later on in the guide.

+
+

Check for request body

+
+

You can check whether a body was sent with the request.

+
+
+
cowboy_req:has_body(Req).
+

It will return true if there is a request body, and +false otherwise.

+

Note that it is generally safe to assume that a body is +sent for POST, PUT and PATCH requests, without +having to explicitly check for it.

+
+
+
+

Request body length

+
+

You can obtain the body length if it was sent with the +request.

+
+
+
Length = cowboy_req:body_length(Req).
+

The value returned will be undefined if the length +couldn’t be figured out from the request headers. If +there’s a body but no length is given, this means that +the chunked transfer-encoding was used. You can read +chunked bodies by using the stream functions.

+
+
+
+

Reading the body

+
+

You can read the whole body directly in one call.

+
+
+
{ok, Body, Req2} = cowboy_req:body(Req).
+

By default, Cowboy will attempt to read up to a +size of 8MB. You can override this limit as needed.

+
+
+
{ok, Body, Req2} = cowboy_req:body(Req, [{length, 100000000}]).
+

You can also disable it.

+
+
+
{ok, Body, Req2} = cowboy_req:body(Req, [{length, infinity}]).
+

It is recommended that you do not disable it for public +facing websites.

+

If the body is larger than the limit, then Cowboy will return +a more tuple instead, allowing you to stream it if you +would like to.

+
+
+
+

Streaming the body

+
+

You can stream the request body by chunks.

+

Cowboy returns a more tuple when there is more body to +be read, and an ok tuple for the last chunk. This allows +you to loop over all chunks.

+
+
+
body_to_console(Req) ->
+    case cowboy_req:body(Req) of
+        {ok, Data, Req2} ->
+            io:format("~s", [Data]),
+            Req2;
+        {more, Data, Req2} ->
+            io:format("~s", [Data]),
+            body_to_console(Req2)
+    end.
+

You can of course set the length option to configure the +size of chunks.

+
+
+
+

Rate of data transmission

+
+

You can control the rate of data transmission by setting +options when calling body functions. This applies not only +to the functions described in this chapter, but also to +the multipart functions.

+

The read_length option defines the maximum amount of data +to be received from the socket at once, in bytes.

+

The read_timeout option defines the time Cowboy waits +before that amount is received, in milliseconds.

+
+
+
+

Transfer and content decoding

+
+

Cowboy will by default decode the chunked transfer-encoding +if any. It will not decode any content-encoding by default.

+

The first time you call a body function you can set the +transfer_decode and content_decode options. If the body +was already started being read these options are simply +ignored.

+

The following example shows how to set both options.

+
+
+
{ok, Data, Req2} = cowboy_req:body(Req, [
+    {transfer_decode, fun transfer_decode/2, TransferState},
+    {content_decode, fun content_decode/1}
+]).
+
+
+
+

Reading a form urlencoded body

+
+

You can directly obtain a list of key/value pairs if the +body was sent using the application/x-www-form-urlencoded +content-type.

+
+
+
{ok, KeyValues, Req2} = cowboy_req:body_qs(Req).
+

You can then retrieve an individual value from that list.

+
+
+
{_, Lang} = lists:keyfind(lang, 1, KeyValues).
+

You should not attempt to match on the list as the order +of the values is undefined.

+

By default Cowboy will reject bodies with a size above +64KB when using this function. You can override this limit +by setting the length option.

+
+
+
{ok, KeyValues, Req2} = cowboy_req:body_qs(Req, [{length, 2000000}]).
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/resource_design.asciidoc b/docs/en/cowboy/2.0/guide/resource_design.asciidoc new file mode 100644 index 00000000..691953f1 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/resource_design.asciidoc @@ -0,0 +1,221 @@ +[[resource_design]] +== Designing a resource handler + +This chapter aims to provide you with a list of questions +you must answer in order to write a good resource handler. +It is meant to be usable as a step by step guide. + +=== The service + +Can the service become unavailable, and when it does, can +we detect it? For example, database connectivity problems +may be detected early. We may also have planned outages +of all or parts of the system. Implement the +`service_available` callback. + +What HTTP methods does the service implement? Do we need +more than the standard OPTIONS, HEAD, GET, PUT, POST, +PATCH and DELETE? Are we not using one of those at all? +Implement the `known_methods` callback. + +=== Type of resource handler + +Am I writing a handler for a collection of resources, +or for a single resource? + +The semantics for each of these are quite different. +You should not mix collection and single resource in +the same handler. + +=== Collection handler + +Skip this section if you are not doing a collection. + +Is the collection hardcoded or dynamic? For example, +if you use the route `/users` for the collection of +users then the collection is hardcoded; if you use +`/forums/:category` for the collection of threads +then it isn't. When the collection is hardcoded you +can safely assume the resource always exists. + +What methods should I implement? + +OPTIONS is used to get some information about the +collection. It is recommended to allow it even if you +do not implement it, as Cowboy has a default +implementation built-in. + +HEAD and GET are used to retrieve the collection. +If you allow GET, also allow HEAD as there's no extra +work required to make it work. + +POST is used to create a new resource inside the +collection. Creating a resource by using POST on +the collection is useful when resources may be +created before knowing their URI, usually because +parts of it are generated dynamically. A common +case is some kind of auto incremented integer +identifier. + +The next methods are more rarely allowed. + +PUT is used to create a new collection (when +the collection isn't hardcoded), or replace +the entire collection. + +DELETE is used to delete the entire collection. + +PATCH is used to modify the collection using +instructions given in the request body. A PATCH +operation is atomic. The PATCH operation may +be used for such things as reordering; adding, +modifying or deleting parts of the collection. + +=== Single resource handler + +Skip this section if you are doing a collection. + +What methods should I implement? + +OPTIONS is used to get some information about the +resource. It is recommended to allow it even if you +do not implement it, as Cowboy has a default +implementation built-in. + +HEAD and GET are used to retrieve the resource. +If you allow GET, also allow HEAD as there's no extra +work required to make it work. + +POST is used to update the resource. + +PUT is used to create a new resource (when it doesn't +already exist) or replace the resource. + +DELETE is used to delete the resource. + +PATCH is used to modify the resource using +instructions given in the request body. A PATCH +operation is atomic. The PATCH operation may +be used for adding, removing or modifying specific +values in the resource. + +=== The resource + +Following the above discussion, implement the +`allowed_methods` callback. + +Does the resource always exist? If it may not, implement +the `resource_exists` callback. + +Do I need to authenticate the client before they can +access the resource? What authentication mechanisms +should I provide? This may include form-based, token-based +(in the URL or a cookie), HTTP basic, HTTP digest, +SSL certificate or any other form of authentication. +Implement the `is_authorized` callback. + +Do I need fine-grained access control? How do I determine +that they are authorized access? Handle that in your +`is_authorized` callback. + +Can access to a resource be forbidden regardless of access +being authorized? A simple example of that is censorship +of a resource. Implement the `forbidden` callback. + +Are there any constraints on the length of the resource URI? +For example, the URI may be used as a key in storage and may +have a limit in length. Implement `uri_too_long`. + +=== Representations + +What media types do I provide? If text based, what charsets +are provided? What languages do I provide? + +Implement the mandatory `content_types_provided`. Prefix +the callbacks with `to_` for clarity. For example, `to_html` +or `to_text`. + +Implement the `languages_provided` or `charsets_provided` +callbacks if applicable. + +Is there any other header that may make the representation +of the resource vary? Implement the `variances` callback. + +Depending on your choices for caching content, you may +want to implement one or more of the `generate_etag`, +`last_modified` and `expires` callbacks. + +Do I want the user or user agent to actively choose a +representation available? Send a list of available +representations in the response body and implement +the `multiple_choices` callback. + +=== Redirections + +Do I need to keep track of what resources were deleted? +For example, you may have a mechanism where moving a +resource leaves a redirect link to its new location. +Implement the `previously_existed` callback. + +Was the resource moved, and is the move temporary? If +it is explicitly temporary, for example due to maintenance, +implement the `moved_temporarily` callback. Otherwise, +implement the `moved_permanently` callback. + +=== The request + +Do we need to perform extra checks to make sure the request +is valid? Cowboy will do many checks when receiving the +request already, do we need more? Note that this only +applies to the request-line and headers of the request, +and not the body. Implement `malformed_request`. + +May there be a request body? Will I know its size? +What's the maximum size of the request body I'm willing +to accept? Implement `valid_entity_length`. + +Finally, take a look at the sections corresponding to the +methods you are implementing. + +=== OPTIONS method + +Cowboy by default will send back a list of allowed methods. +Do I need to add more information to the response? Implement +the `options` method. + +=== GET and HEAD methods + +If you implement the methods GET and/or HEAD, you must +implement one `ProvideResource` callback for each +content-type returned by the `content_types_provided` +callback. + +=== PUT, POST and PATCH methods + +If you implement the methods PUT, POST and/or PATCH, +you must implement the `content_types_accepted` callback, +and one `AcceptResource` callback for each content-type +it returns. Prefix the `AcceptResource` callback names +with `from_` for clarity. For example, `from_html` or +`from_json`. + +Do we want to allow the POST method to create individual +resources directly through their URI (like PUT)? Implement +the `allow_missing_post` callback. It is recommended to +explicitly use PUT in these cases instead. + +May there be conflicts when using PUT to create or replace +a resource? Do we want to make sure that two updates around +the same time are not cancelling one another? Implement the +`is_conflict` callback. + +=== DELETE methods + +If you implement the method DELETE, you must implement +the `delete_resource` callback. + +When `delete_resource` returns, is the resource completely +removed from the server, including from any caching service? +If not, and/or if the deletion is asynchronous and we have +no way of knowing it has been completed yet, implement the +`delete_completed` callback. diff --git a/docs/en/cowboy/2.0/guide/resource_design/index.html b/docs/en/cowboy/2.0/guide/resource_design/index.html new file mode 100644 index 00000000..94d6307e --- /dev/null +++ b/docs/en/cowboy/2.0/guide/resource_design/index.html @@ -0,0 +1,350 @@ + + + + + + + + + + + + Nine Nines: Designing a resource handler + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Designing a resource handler

+ +

This chapter aims to provide you with a list of questions +you must answer in order to write a good resource handler. +It is meant to be usable as a step by step guide.

+
+

The service

+
+

Can the service become unavailable, and when it does, can +we detect it? For example, database connectivity problems +may be detected early. We may also have planned outages +of all or parts of the system. Implement the +service_available callback.

+

What HTTP methods does the service implement? Do we need +more than the standard OPTIONS, HEAD, GET, PUT, POST, +PATCH and DELETE? Are we not using one of those at all? +Implement the known_methods callback.

+
+
+
+

Type of resource handler

+
+

Am I writing a handler for a collection of resources, +or for a single resource?

+

The semantics for each of these are quite different. +You should not mix collection and single resource in +the same handler.

+
+
+
+

Collection handler

+
+

Skip this section if you are not doing a collection.

+

Is the collection hardcoded or dynamic? For example, +if you use the route /users for the collection of +users then the collection is hardcoded; if you use +/forums/:category for the collection of threads +then it isn’t. When the collection is hardcoded you +can safely assume the resource always exists.

+

What methods should I implement?

+

OPTIONS is used to get some information about the +collection. It is recommended to allow it even if you +do not implement it, as Cowboy has a default +implementation built-in.

+

HEAD and GET are used to retrieve the collection. +If you allow GET, also allow HEAD as there’s no extra +work required to make it work.

+

POST is used to create a new resource inside the +collection. Creating a resource by using POST on +the collection is useful when resources may be +created before knowing their URI, usually because +parts of it are generated dynamically. A common +case is some kind of auto incremented integer +identifier.

+

The next methods are more rarely allowed.

+

PUT is used to create a new collection (when +the collection isn’t hardcoded), or replace +the entire collection.

+

DELETE is used to delete the entire collection.

+

PATCH is used to modify the collection using +instructions given in the request body. A PATCH +operation is atomic. The PATCH operation may +be used for such things as reordering; adding, +modifying or deleting parts of the collection.

+
+
+
+

Single resource handler

+
+

Skip this section if you are doing a collection.

+

What methods should I implement?

+

OPTIONS is used to get some information about the +resource. It is recommended to allow it even if you +do not implement it, as Cowboy has a default +implementation built-in.

+

HEAD and GET are used to retrieve the resource. +If you allow GET, also allow HEAD as there’s no extra +work required to make it work.

+

POST is used to update the resource.

+

PUT is used to create a new resource (when it doesn’t +already exist) or replace the resource.

+

DELETE is used to delete the resource.

+

PATCH is used to modify the resource using +instructions given in the request body. A PATCH +operation is atomic. The PATCH operation may +be used for adding, removing or modifying specific +values in the resource.

+
+
+
+

The resource

+
+

Following the above discussion, implement the +allowed_methods callback.

+

Does the resource always exist? If it may not, implement +the resource_exists callback.

+

Do I need to authenticate the client before they can +access the resource? What authentication mechanisms +should I provide? This may include form-based, token-based +(in the URL or a cookie), HTTP basic, HTTP digest, +SSL certificate or any other form of authentication. +Implement the is_authorized callback.

+

Do I need fine-grained access control? How do I determine +that they are authorized access? Handle that in your +is_authorized callback.

+

Can access to a resource be forbidden regardless of access +being authorized? A simple example of that is censorship +of a resource. Implement the forbidden callback.

+

Are there any constraints on the length of the resource URI? +For example, the URI may be used as a key in storage and may +have a limit in length. Implement uri_too_long.

+
+
+
+

Representations

+
+

What media types do I provide? If text based, what charsets +are provided? What languages do I provide?

+

Implement the mandatory content_types_provided. Prefix +the callbacks with to_ for clarity. For example, to_html +or to_text.

+

Implement the languages_provided or charsets_provided +callbacks if applicable.

+

Is there any other header that may make the representation +of the resource vary? Implement the variances callback.

+

Depending on your choices for caching content, you may +want to implement one or more of the generate_etag, +last_modified and expires callbacks.

+

Do I want the user or user agent to actively choose a +representation available? Send a list of available +representations in the response body and implement +the multiple_choices callback.

+
+
+
+

Redirections

+
+

Do I need to keep track of what resources were deleted? +For example, you may have a mechanism where moving a +resource leaves a redirect link to its new location. +Implement the previously_existed callback.

+

Was the resource moved, and is the move temporary? If +it is explicitly temporary, for example due to maintenance, +implement the moved_temporarily callback. Otherwise, +implement the moved_permanently callback.

+
+
+
+

The request

+
+

Do we need to perform extra checks to make sure the request +is valid? Cowboy will do many checks when receiving the +request already, do we need more? Note that this only +applies to the request-line and headers of the request, +and not the body. Implement malformed_request.

+

May there be a request body? Will I know its size? +What’s the maximum size of the request body I’m willing +to accept? Implement valid_entity_length.

+

Finally, take a look at the sections corresponding to the +methods you are implementing.

+
+
+
+

OPTIONS method

+
+

Cowboy by default will send back a list of allowed methods. +Do I need to add more information to the response? Implement +the options method.

+
+
+
+

GET and HEAD methods

+
+

If you implement the methods GET and/or HEAD, you must +implement one ProvideResource callback for each +content-type returned by the content_types_provided +callback.

+
+
+
+

PUT, POST and PATCH methods

+
+

If you implement the methods PUT, POST and/or PATCH, +you must implement the content_types_accepted callback, +and one AcceptResource callback for each content-type +it returns. Prefix the AcceptResource callback names +with from_ for clarity. For example, from_html or +from_json.

+

Do we want to allow the POST method to create individual +resources directly through their URI (like PUT)? Implement +the allow_missing_post callback. It is recommended to +explicitly use PUT in these cases instead.

+

May there be conflicts when using PUT to create or replace +a resource? Do we want to make sure that two updates around +the same time are not cancelling one another? Implement the +is_conflict callback.

+
+
+
+

DELETE methods

+
+

If you implement the method DELETE, you must implement +the delete_resource callback.

+

When delete_resource returns, is the resource completely +removed from the server, including from any caching service? +If not, and/or if the deletion is asynchronous and we have +no way of knowing it has been completed yet, implement the +delete_completed callback.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/resp.asciidoc b/docs/en/cowboy/2.0/guide/resp.asciidoc new file mode 100644 index 00000000..1ffdfbd5 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/resp.asciidoc @@ -0,0 +1,201 @@ +[[resp]] +== Sending a response + +The Req object also allows you to send a response. + +You can only send one response. Any other attempt will +trigger a crash. The response may be sent in one go or +with its body streamed by chunks of arbitrary size. + +You can also set headers or the response body in advance +and Cowboy will use them when you finally do reply. + +=== Reply + +You can send a reply with no particular headers or body. +Cowboy will make sure to send the mandatory headers with +the response. + +[source,erlang] +Req2 = cowboy_req:reply(200, Req). + +You can define headers to be sent with the response. Note +that header names must be lowercase. Again, Cowboy will +make sure to send the mandatory headers with the response. + +[source,erlang] +---- +Req2 = cowboy_req:reply(303, [ + {<<"location">>, <<"http://ninenines.eu">>} +], Req). +---- + +You can override headers that Cowboy would send otherwise. +Any header set by the user will be used over the ones set +by Cowboy. For example, you can advertise yourself as a +different server. + +[source,erlang] +---- +Req2 = cowboy_req:reply(200, [ + {<<"server">>, <<"yaws">>} +], Req). +---- + +We also saw earlier how to force close the connection by +overriding the connection header. + +Finally, you can also send a body with the response. Cowboy +will automatically set the content-length header if you do. +We recommend that you set the content-type header so the +client may know how to read the body. + +[source,erlang] +---- +Req2 = cowboy_req:reply(200, [ + {<<"content-type">>, <<"text/plain">>} +], "Hello world!", Req). +---- + +Here is the same example but sending HTML this time. + +[source,erlang] +---- +Req2 = cowboy_req:reply(200, [ + {<<"content-type">>, <<"text/html">>} +], "Hello world!

Hats off!

", Req). +---- + +Note that the reply is sent immediately. + +=== Chunked reply + +You can also stream the response body. First, you need to +initiate the reply by sending the response status code. +Then you can send the body in chunks of arbitrary size. + +[source,erlang] +Req2 = cowboy_req:chunked_reply(200, Req), +cowboy_req:chunk("Hello...", Req2), +cowboy_req:chunk("chunked...", Req2), +cowboy_req:chunk("world!!", Req2). + +You should make sure to match on `ok` as an error may be +returned. + +While it is possible to send a chunked response without +a content-type header, it is still recommended. You can +set this header or any other just like for normal replies. + +[source,erlang] +---- +Req2 = cowboy_req:chunked_reply(200, [ + {<<"content-type">>, <<"text/html">>} +], Req), +cowboy_req:chunk("Hello world!", Req2), +cowboy_req:chunk("

Hats off!

", Req2). +---- + +Note that the reply and each chunk following it are sent +immediately. + +=== Preset response headers + +You can define response headers in advance. They will be +merged into the headers given in the reply call. Headers +in the reply call override preset response headers which +override the default Cowboy headers. + +[source,erlang] +Req2 = cowboy_req:set_resp_header(<<"allow">>, "GET", Req). + +You can check if a response header has already been set. +This will only check the response headers that you set, +and not the ones Cowboy will add when actually sending +the reply. + +[source,erlang] +cowboy_req:has_resp_header(<<"allow">>, Req). + +It will return `true` if the header is defined, and `false` +otherwise. + +Finally, you can also delete a preset response header if +needed. If you do, it will not be sent. + +[source,erlang] +Req2 = cowboy_req:delete_resp_header(<<"allow">>, Req). + +=== Preset response body + +You can set the response body in advance. Note that this +body will be ignored if you then choose to send a chunked +reply, or if you send a reply with an explicit body. + +[source,erlang] +Req2 = cowboy_req:set_resp_body("Hello world!", Req). + +You can also set a fun that will be called when it is time +to send the body. There are three different ways of doing +that. + +If you know the length of the body that needs to be sent, +you should specify it, as it will help clients determine +the remaining download time and allow them to inform the +user. + +[source,erlang] +---- +F = fun (Socket, Transport) -> + Transport:send(Socket, "Hello world!") +end, +Req2 = cowboy_req:set_resp_body_fun(12, F, Req). +---- + +If you do not know the length of the body, you should use +a chunked response body fun instead. + +[source,erlang] +---- +F = fun (SendChunk) -> + Body = lists:duplicate(random:uniform(1024, $a)), + SendChunk(Body) +end, +Req2 = cowboy_req:set_resp_body_fun(chunked, F, Req). +---- + +Finally, you can also send data on the socket directly, +without knowing the length in advance. Cowboy may be +forced to close the connection at the end of the response +though depending on the protocol capabilities. + +[source,erlang] +---- +F = fun (Socket, Transport) -> + Body = lists:duplicate(random:uniform(1024, $a)), + Transport:send(Socket, Body) +end, +Req2 = cowboy_req:set_resp_body_fun(F, Req). +---- + +=== Sending files + +You can send files directly from disk without having to +read them. Cowboy will use the `sendfile` syscall when +possible, which means that the file is sent to the socket +directly from the kernel, which is a lot more performant +than doing it from userland. + +Again, it is recommended to set the size of the file if it +can be known in advance. + +[source,erlang] +---- +F = fun (Socket, Transport) -> + Transport:sendfile(Socket, "priv/styles.css") +end, +Req2 = cowboy_req:set_resp_body_fun(FileSize, F, Req). +---- + +Please see the Ranch guide for more information about +sending files. diff --git a/docs/en/cowboy/2.0/guide/resp/index.html b/docs/en/cowboy/2.0/guide/resp/index.html new file mode 100644 index 00000000..0baaa4c9 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/resp/index.html @@ -0,0 +1,357 @@ + + + + + + + + + + + + Nine Nines: Sending a response + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Sending a response

+ +

The Req object also allows you to send a response.

+

You can only send one response. Any other attempt will +trigger a crash. The response may be sent in one go or +with its body streamed by chunks of arbitrary size.

+

You can also set headers or the response body in advance +and Cowboy will use them when you finally do reply.

+
+

Reply

+
+

You can send a reply with no particular headers or body. +Cowboy will make sure to send the mandatory headers with +the response.

+
+
+
Req2 = cowboy_req:reply(200, Req).
+

You can define headers to be sent with the response. Note +that header names must be lowercase. Again, Cowboy will +make sure to send the mandatory headers with the response.

+
+
+
Req2 = cowboy_req:reply(303, [
+    {<<"location">>, <<"http://ninenines.eu">>}
+], Req).
+

You can override headers that Cowboy would send otherwise. +Any header set by the user will be used over the ones set +by Cowboy. For example, you can advertise yourself as a +different server.

+
+
+
Req2 = cowboy_req:reply(200, [
+    {<<"server">>, <<"yaws">>}
+], Req).
+

We also saw earlier how to force close the connection by +overriding the connection header.

+

Finally, you can also send a body with the response. Cowboy +will automatically set the content-length header if you do. +We recommend that you set the content-type header so the +client may know how to read the body.

+
+
+
Req2 = cowboy_req:reply(200, [
+    {<<"content-type">>, <<"text/plain">>}
+], "Hello world!", Req).
+

Here is the same example but sending HTML this time.

+
+
+
Req2 = cowboy_req:reply(200, [
+    {<<"content-type">>, <<"text/html">>}
+], "<html><head>Hello world!</head><body><p>Hats off!</p></body></html>", Req).
+

Note that the reply is sent immediately.

+
+
+
+

Chunked reply

+
+

You can also stream the response body. First, you need to +initiate the reply by sending the response status code. +Then you can send the body in chunks of arbitrary size.

+
+
+
Req2 = cowboy_req:chunked_reply(200, Req),
+cowboy_req:chunk("Hello...", Req2),
+cowboy_req:chunk("chunked...", Req2),
+cowboy_req:chunk("world!!", Req2).
+

You should make sure to match on ok as an error may be +returned.

+

While it is possible to send a chunked response without +a content-type header, it is still recommended. You can +set this header or any other just like for normal replies.

+
+
+
Req2 = cowboy_req:chunked_reply(200, [
+    {<<"content-type">>, <<"text/html">>}
+], Req),
+cowboy_req:chunk("<html><head>Hello world!</head>", Req2),
+cowboy_req:chunk("<body><p>Hats off!</p></body></html>", Req2).
+

Note that the reply and each chunk following it are sent +immediately.

+
+
+
+

Preset response headers

+
+

You can define response headers in advance. They will be +merged into the headers given in the reply call. Headers +in the reply call override preset response headers which +override the default Cowboy headers.

+
+
+
Req2 = cowboy_req:set_resp_header(<<"allow">>, "GET", Req).
+

You can check if a response header has already been set. +This will only check the response headers that you set, +and not the ones Cowboy will add when actually sending +the reply.

+
+
+
cowboy_req:has_resp_header(<<"allow">>, Req).
+

It will return true if the header is defined, and false +otherwise.

+

Finally, you can also delete a preset response header if +needed. If you do, it will not be sent.

+
+
+
Req2 = cowboy_req:delete_resp_header(<<"allow">>, Req).
+
+
+
+

Preset response body

+
+

You can set the response body in advance. Note that this +body will be ignored if you then choose to send a chunked +reply, or if you send a reply with an explicit body.

+
+
+
Req2 = cowboy_req:set_resp_body("Hello world!", Req).
+

You can also set a fun that will be called when it is time +to send the body. There are three different ways of doing +that.

+

If you know the length of the body that needs to be sent, +you should specify it, as it will help clients determine +the remaining download time and allow them to inform the +user.

+
+
+
F = fun (Socket, Transport) ->
+    Transport:send(Socket, "Hello world!")
+end,
+Req2 = cowboy_req:set_resp_body_fun(12, F, Req).
+

If you do not know the length of the body, you should use +a chunked response body fun instead.

+
+
+
F = fun (SendChunk) ->
+    Body = lists:duplicate(random:uniform(1024, $a)),
+    SendChunk(Body)
+end,
+Req2 = cowboy_req:set_resp_body_fun(chunked, F, Req).
+

Finally, you can also send data on the socket directly, +without knowing the length in advance. Cowboy may be +forced to close the connection at the end of the response +though depending on the protocol capabilities.

+
+
+
F = fun (Socket, Transport) ->
+    Body = lists:duplicate(random:uniform(1024, $a)),
+    Transport:send(Socket, Body)
+end,
+Req2 = cowboy_req:set_resp_body_fun(F, Req).
+
+
+
+

Sending files

+
+

You can send files directly from disk without having to +read them. Cowboy will use the sendfile syscall when +possible, which means that the file is sent to the socket +directly from the kernel, which is a lot more performant +than doing it from userland.

+

Again, it is recommended to set the size of the file if it +can be known in advance.

+
+
+
F = fun (Socket, Transport) ->
+    Transport:sendfile(Socket, "priv/styles.css")
+end,
+Req2 = cowboy_req:set_resp_body_fun(FileSize, F, Req).
+

Please see the Ranch guide for more information about +sending files.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/rest_cond.png b/docs/en/cowboy/2.0/guide/rest_cond.png new file mode 100644 index 00000000..64cda347 Binary files /dev/null and b/docs/en/cowboy/2.0/guide/rest_cond.png differ diff --git a/docs/en/cowboy/2.0/guide/rest_cond.svg b/docs/en/cowboy/2.0/guide/rest_cond.svg new file mode 100644 index 00000000..542ae17d --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_cond.svg @@ -0,0 +1,1656 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + has if-unmodified-since? + has if-none-match? + some text + ... + generate_etag + has if-modified-since? + has if-match? + generate_etag + last_modified + + true + match* + true + not modified* + true + no match* + + + + + false + false, orinvalid + modified* + false + + + + + + 412 precondition failed + + middlewares + + + + + + + + + + + + + + + + + no match* + + + + + + date is in the future? + + + + + + + + + + last_modified + + + + + + 304 not modified + + ... + false, orinvalid + match* + + method is GET/HEAD? + true + false + true + false + true + modified* + not modified* + + + + + + generate_etag + + + + + + expires + + diff --git a/docs/en/cowboy/2.0/guide/rest_conneg.png b/docs/en/cowboy/2.0/guide/rest_conneg.png new file mode 100644 index 00000000..65ecdcf3 Binary files /dev/null and b/docs/en/cowboy/2.0/guide/rest_conneg.png differ diff --git a/docs/en/cowboy/2.0/guide/rest_conneg.svg b/docs/en/cowboy/2.0/guide/rest_conneg.svg new file mode 100644 index 00000000..247567a0 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_conneg.svg @@ -0,0 +1,1135 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + has accept-language? + has accept-charset? + some text + start + charsets_provided + variances + has accept? + content_types_provided + languages_provided + + true + provided* + true + provided* + true + provided* + + + + + false + false + not provided* + false + not provided* + + + + + + 406 not acceptable + + middlewares + + + + + + + + + + + + + + + + + not provided* + + ... + + diff --git a/docs/en/cowboy/2.0/guide/rest_delete.png b/docs/en/cowboy/2.0/guide/rest_delete.png new file mode 100644 index 00000000..56a861c0 Binary files /dev/null and b/docs/en/cowboy/2.0/guide/rest_delete.png differ diff --git a/docs/en/cowboy/2.0/guide/rest_delete.svg b/docs/en/cowboy/2.0/guide/rest_delete.svg new file mode 100644 index 00000000..2f5513cd --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_delete.svg @@ -0,0 +1,1718 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + delete_completed + has response body? + some text + conneg + multiple_choices + resource_exists + delete_resource + + true + false + + + + + false + + + + + + middlewares + + + + + true + true + + + + + + cond + + 300 multiple choices + + 200 OK + + + + + + has if-match? + false + + + + + + + + + + previously_existed + + 404 not found + false + + + + + + + + + + moved_permanently + + + + + + 412 precondition failed + true + true* + false + + 301 moved permanently + + + + + + + + + + moved_temporarily + true* + false + + 307 moved temporarily + + 410 gone + + + + + false + + 202 accepted + + 204 no content + true + true + + 500 internal server error + false + true + false + + diff --git a/docs/en/cowboy/2.0/guide/rest_flowcharts.asciidoc b/docs/en/cowboy/2.0/guide/rest_flowcharts.asciidoc new file mode 100644 index 00000000..b5697825 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_flowcharts.asciidoc @@ -0,0 +1,248 @@ +[[rest_flowcharts]] +== REST flowcharts + +This chapter will explain the REST handler state machine through +a number of different diagrams. + +There are four main paths that requests may follow. One for the +method OPTIONS; one for the methods GET and HEAD; one for the +methods PUT, POST and PATCH; and one for the method DELETE. + +All paths start with the "Start" diagram, and all paths excluding +the OPTIONS path go through the "Content negotiation" diagram +and optionally the "Conditional requests" diagram if the resource +exists. + +The red squares refer to another diagram. The light green squares +indicate a response. Other squares may be either a callback or a +question answered by Cowboy itself. Green arrows tend to indicate +the default behavior if the callback is undefined. + +=== Start + +All requests start from here. + +image::rest_start.png[REST starting flowchart] + +A series of callbacks are called in succession to perform +a general checkup of the service, the request line and +request headers. + +The request body, if any, is not expected to have been +received for any of these steps. It is only processed +at the end of the "PUT, POST and PATCH methods" diagram, +when all conditions have been met. + +The `known_methods` and `allowed_methods` callbacks +return a list of methods. Cowboy then checks if the request +method is in the list, and stops otherwise. + +The `is_authorized` callback may be used to check that +access to the resource is authorized. Authentication +may also be performed as needed. When authorization is +denied, the return value from the callback must include +a challenge applicable to the requested resource, which +will be sent back to the client in the www-authenticate +header. + +This diagram is immediately followed by either the +"OPTIONS method" diagram when the request method is +OPTIONS, or the "Content negotiation" diagram otherwise. + +=== OPTIONS method + +This diagram only applies to OPTIONS requests. + +image::rest_options.png[REST OPTIONS method flowchart] + +The `options` callback may be used to add information +about the resource, such as media types or languages +provided; allowed methods; any extra information. A +response body may also be set, although clients should +not be expected to read it. + +If the `options` callback is not defined, Cowboy will +send a response containing the list of allowed methods +by default. + +=== Content negotiation + +This diagram applies to all request methods other than +OPTIONS. It is executed right after the "Start" diagram +is completed. + +image::rest_conneg.png[REST content negotiation flowchart] + +The purpose of these steps is to determine an appropriate +representation to be sent back to the client. + +The request may contain any of the accept header; the +accept-language header; or the accept-charset header. +When present, Cowboy will parse the headers and then +call the corresponding callback to obtain the list +of provided content-type, language or charset for this +resource. It then automatically select the best match +based on the request. + +If a callback is not defined, Cowboy will select the +content-type, language or charset that the client +prefers. + +The `content_types_provided` also returns the name of +a callback for every content-type it accepts. This +callback will only be called at the end of the +"GET and HEAD methods" diagram, when all conditions +have been met. + +The selected content-type, language and charset are +saved as meta values in the Req object. You *should* +use the appropriate representation if you set a +response body manually (alongside an error code, +for example). + +This diagram is immediately followed by +the "GET and HEAD methods" diagram, +the "PUT, POST and PATCH methods" diagram, +or the "DELETE method" diagram, depending on the +method. + +=== GET and HEAD methods + +This diagram only applies to GET and HEAD requests. + +For a description of the `cond` step, please see +the "Conditional requests" diagram. + +image::rest_get_head.png[REST GET/HEAD methods flowchart] + +When the resource exists, and the conditional steps +succeed, the resource can be retrieved. + +Cowboy prepares the response by first retrieving +metadata about the representation, then by calling +the `ProvideResource` callback. This is the callback +you defined for each content-types you returned from +`content_types_provided`. This callback returns the body +that will be sent back to the client, or a fun if the +body must be streamed. + +When the resource does not exist, Cowboy will figure out +whether the resource existed previously, and if so whether +it was moved elsewhere in order to redirect the client to +the new URI. + +The `moved_permanently` and `moved_temporarily` callbacks +must return the new location of the resource if it was in +fact moved. + +=== PUT, POST and PATCH methods + +This diagram only applies to PUT, POST and PATCH requests. + +For a description of the `cond` step, please see +the "Conditional requests" diagram. + +image::rest_put_post_patch.png[REST PUT/POST/PATCH methods flowchart] + +When the resource exists, first the conditional steps +are executed. When that succeeds, and the method is PUT, +Cowboy will call the `is_conflict` callback. This function +can be used to prevent potential race conditions, by locking +the resource for example. + +Then all three methods reach the `content_types_accepted` +step that we will describe in a few paragraphs. + +When the resource does not exist, and the method is PUT, +Cowboy will check for conflicts and then move on to the +`content_types_accepted` step. For other methods, Cowboy +will figure out whether the resource existed previously, +and if so whether it was moved elsewhere. If the resource +is truly non-existent, the method is POST and the call +for `allow_missing_post` returns `true`, then Cowboy will +move on to the `content_types_accepted` step. Otherwise +the request processing ends there. + +The `moved_permanently` and `moved_temporarily` callbacks +must return the new location of the resource if it was in +fact moved. + +The `content_types_accepted` returns a list of +content-types it accepts, but also the name of a callback +for each of them. Cowboy will select the appropriate +callback for processing the request body and call it. + +This callback may return one of three different return +values. + +If an error occurred while processing the request body, +it must return `false` and Cowboy will send an +appropriate error response. + +If the method is POST, then you may return `true` with +an URI of where the resource has been created. This is +especially useful for writing handlers for collections. + +Otherwise, return `true` to indicate success. Cowboy +will select the appropriate response to be sent depending +on whether a resource has been created, rather than +modified, and on the availability of a location header +or a body in the response. + +=== DELETE method + +This diagram only applies to DELETE requests. + +For a description of the `cond` step, please see +the "Conditional requests" diagram. + +image::rest_delete.png[REST DELETE method flowchart] + +When the resource exists, and the conditional steps +succeed, the resource can be deleted. + +Deleting the resource is a two steps process. First +the callback `delete_resource` is executed. Use this +callback to delete the resource. + +Because the resource may be cached, you must also +delete all cached representations of this resource +in the system. This operation may take a while though, +so you may return before it finished. + +Cowboy will then call the `delete_completed` callback. +If you know that the resource has been completely +deleted from your system, including from caches, then +you can return `true`. If any doubts persist, return +`false`. Cowboy will assume `true` by default. + +To finish, Cowboy checks if you set a response body, +and depending on that, sends the appropriate response. + +When the resource does not exist, Cowboy will figure out +whether the resource existed previously, and if so whether +it was moved elsewhere in order to redirect the client to +the new URI. + +The `moved_permanently` and `moved_temporarily` callbacks +must return the new location of the resource if it was in +fact moved. + +=== Conditional requests + +This diagram applies to all request methods other than +OPTIONS. It is executed right after the `resource_exists` +callback, when the resource exists. + +image::rest_cond.png[REST conditional requests flowchart] + +A request becomes conditional when it includes either of +the if-match header; the if-unmodified-since header; the +if-none-match header; or the if-modified-since header. + +If the condition fails, the request ends immediately +without any retrieval or modification of the resource. + +The `generate_etag` and `last_modified` are called as +needed. Cowboy will only call them once and then cache +the results for subsequent use. diff --git a/docs/en/cowboy/2.0/guide/rest_flowcharts/index.html b/docs/en/cowboy/2.0/guide/rest_flowcharts/index.html new file mode 100644 index 00000000..c5ca894b --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_flowcharts/index.html @@ -0,0 +1,380 @@ + + + + + + + + + + + + Nine Nines: REST flowcharts + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

REST flowcharts

+ +

This chapter will explain the REST handler state machine through +a number of different diagrams.

+

There are four main paths that requests may follow. One for the +method OPTIONS; one for the methods GET and HEAD; one for the +methods PUT, POST and PATCH; and one for the method DELETE.

+

All paths start with the "Start" diagram, and all paths excluding +the OPTIONS path go through the "Content negotiation" diagram +and optionally the "Conditional requests" diagram if the resource +exists.

+

The red squares refer to another diagram. The light green squares +indicate a response. Other squares may be either a callback or a +question answered by Cowboy itself. Green arrows tend to indicate +the default behavior if the callback is undefined.

+
+

Start

+
+

All requests start from here.

+
+
+REST starting flowchart +
+
+

A series of callbacks are called in succession to perform +a general checkup of the service, the request line and +request headers.

+

The request body, if any, is not expected to have been +received for any of these steps. It is only processed +at the end of the "PUT, POST and PATCH methods" diagram, +when all conditions have been met.

+

The known_methods and allowed_methods callbacks +return a list of methods. Cowboy then checks if the request +method is in the list, and stops otherwise.

+

The is_authorized callback may be used to check that +access to the resource is authorized. Authentication +may also be performed as needed. When authorization is +denied, the return value from the callback must include +a challenge applicable to the requested resource, which +will be sent back to the client in the www-authenticate +header.

+

This diagram is immediately followed by either the +"OPTIONS method" diagram when the request method is +OPTIONS, or the "Content negotiation" diagram otherwise.

+
+
+
+

OPTIONS method

+
+

This diagram only applies to OPTIONS requests.

+
+
+REST OPTIONS method flowchart +
+
+

The options callback may be used to add information +about the resource, such as media types or languages +provided; allowed methods; any extra information. A +response body may also be set, although clients should +not be expected to read it.

+

If the options callback is not defined, Cowboy will +send a response containing the list of allowed methods +by default.

+
+
+
+

Content negotiation

+
+

This diagram applies to all request methods other than +OPTIONS. It is executed right after the "Start" diagram +is completed.

+
+
+REST content negotiation flowchart +
+
+

The purpose of these steps is to determine an appropriate +representation to be sent back to the client.

+

The request may contain any of the accept header; the +accept-language header; or the accept-charset header. +When present, Cowboy will parse the headers and then +call the corresponding callback to obtain the list +of provided content-type, language or charset for this +resource. It then automatically select the best match +based on the request.

+

If a callback is not defined, Cowboy will select the +content-type, language or charset that the client +prefers.

+

The content_types_provided also returns the name of +a callback for every content-type it accepts. This +callback will only be called at the end of the +"GET and HEAD methods" diagram, when all conditions +have been met.

+

The selected content-type, language and charset are +saved as meta values in the Req object. You should +use the appropriate representation if you set a +response body manually (alongside an error code, +for example).

+

This diagram is immediately followed by +the "GET and HEAD methods" diagram, +the "PUT, POST and PATCH methods" diagram, +or the "DELETE method" diagram, depending on the +method.

+
+
+
+

GET and HEAD methods

+
+

This diagram only applies to GET and HEAD requests.

+

For a description of the cond step, please see +the "Conditional requests" diagram.

+
+
+REST GET/HEAD methods flowchart +
+
+

When the resource exists, and the conditional steps +succeed, the resource can be retrieved.

+

Cowboy prepares the response by first retrieving +metadata about the representation, then by calling +the ProvideResource callback. This is the callback +you defined for each content-types you returned from +content_types_provided. This callback returns the body +that will be sent back to the client, or a fun if the +body must be streamed.

+

When the resource does not exist, Cowboy will figure out +whether the resource existed previously, and if so whether +it was moved elsewhere in order to redirect the client to +the new URI.

+

The moved_permanently and moved_temporarily callbacks +must return the new location of the resource if it was in +fact moved.

+
+
+
+

PUT, POST and PATCH methods

+
+

This diagram only applies to PUT, POST and PATCH requests.

+

For a description of the cond step, please see +the "Conditional requests" diagram.

+
+
+REST PUT/POST/PATCH methods flowchart +
+
+

When the resource exists, first the conditional steps +are executed. When that succeeds, and the method is PUT, +Cowboy will call the is_conflict callback. This function +can be used to prevent potential race conditions, by locking +the resource for example.

+

Then all three methods reach the content_types_accepted +step that we will describe in a few paragraphs.

+

When the resource does not exist, and the method is PUT, +Cowboy will check for conflicts and then move on to the +content_types_accepted step. For other methods, Cowboy +will figure out whether the resource existed previously, +and if so whether it was moved elsewhere. If the resource +is truly non-existent, the method is POST and the call +for allow_missing_post returns true, then Cowboy will +move on to the content_types_accepted step. Otherwise +the request processing ends there.

+

The moved_permanently and moved_temporarily callbacks +must return the new location of the resource if it was in +fact moved.

+

The content_types_accepted returns a list of +content-types it accepts, but also the name of a callback +for each of them. Cowboy will select the appropriate +callback for processing the request body and call it.

+

This callback may return one of three different return +values.

+

If an error occurred while processing the request body, +it must return false and Cowboy will send an +appropriate error response.

+

If the method is POST, then you may return true with +an URI of where the resource has been created. This is +especially useful for writing handlers for collections.

+

Otherwise, return true to indicate success. Cowboy +will select the appropriate response to be sent depending +on whether a resource has been created, rather than +modified, and on the availability of a location header +or a body in the response.

+
+
+
+

DELETE method

+
+

This diagram only applies to DELETE requests.

+

For a description of the cond step, please see +the "Conditional requests" diagram.

+
+
+REST DELETE method flowchart +
+
+

When the resource exists, and the conditional steps +succeed, the resource can be deleted.

+

Deleting the resource is a two steps process. First +the callback delete_resource is executed. Use this +callback to delete the resource.

+

Because the resource may be cached, you must also +delete all cached representations of this resource +in the system. This operation may take a while though, +so you may return before it finished.

+

Cowboy will then call the delete_completed callback. +If you know that the resource has been completely +deleted from your system, including from caches, then +you can return true. If any doubts persist, return +false. Cowboy will assume true by default.

+

To finish, Cowboy checks if you set a response body, +and depending on that, sends the appropriate response.

+

When the resource does not exist, Cowboy will figure out +whether the resource existed previously, and if so whether +it was moved elsewhere in order to redirect the client to +the new URI.

+

The moved_permanently and moved_temporarily callbacks +must return the new location of the resource if it was in +fact moved.

+
+
+
+

Conditional requests

+
+

This diagram applies to all request methods other than +OPTIONS. It is executed right after the resource_exists +callback, when the resource exists.

+
+
+REST conditional requests flowchart +
+
+

A request becomes conditional when it includes either of +the if-match header; the if-unmodified-since header; the +if-none-match header; or the if-modified-since header.

+

If the condition fails, the request ends immediately +without any retrieval or modification of the resource.

+

The generate_etag and last_modified are called as +needed. Cowboy will only call them once and then cache +the results for subsequent use.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/rest_get_head.png b/docs/en/cowboy/2.0/guide/rest_get_head.png new file mode 100644 index 00000000..efee892a Binary files /dev/null and b/docs/en/cowboy/2.0/guide/rest_get_head.png differ diff --git a/docs/en/cowboy/2.0/guide/rest_get_head.svg b/docs/en/cowboy/2.0/guide/rest_get_head.svg new file mode 100644 index 00000000..c78e9399 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_get_head.svg @@ -0,0 +1,1523 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + last_modified + ProvideResource + some text + conneg + multiple_choices + resource_exists + generate_etag + expires + + true + false + + + + + false + + + + + + middlewares + + + + + true + true + + + + + + cond + + 300 multiple choices + + 200 OK + + + + + + has if-match? + false + + + + + + + + + + previously_existed + + 404 not found + false + + + + + + + + + + moved_permanently + + + + + + 412 precondition failed + true + true* + false + + 301 moved permanently + + + + + + + + + + moved_temporarily + true* + false + + 307 moved temporarily + + 410 gone + + + + + + diff --git a/docs/en/cowboy/2.0/guide/rest_handlers.asciidoc b/docs/en/cowboy/2.0/guide/rest_handlers.asciidoc new file mode 100644 index 00000000..6bff18d7 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_handlers.asciidoc @@ -0,0 +1,133 @@ +[[rest_handlers]] +== REST handlers + +REST is implemented in Cowboy as a sub protocol. The request +is handled as a state machine with many optional callbacks +describing the resource and modifying the machine's behavior. + +The REST handler is the recommended way to handle HTTP requests. + +=== Initialization + +First, the `init/2` callback is called. This callback is common +to all handlers. To use REST for the current request, this function +must return a `cowboy_rest` tuple. + +[source,erlang] +---- +init(Req, _Opts) -> + {cowboy_rest, Req, #state{}}. +---- + +Cowboy will then switch to the REST protocol and start executing +the state machine. + +After reaching the end of the flowchart, the `terminate/3` callback +will be called if it is defined. + +=== Methods + +The REST component has code for handling the following HTTP methods: +HEAD, GET, POST, PATCH, PUT, DELETE and OPTIONS. + +Other methods can be accepted, however they have no specific callback +defined for them at this time. + +=== Callbacks + +All callbacks are optional. Some may become mandatory depending +on what other defined callbacks return. The various flowcharts +in the next chapter should be a useful to determine which callbacks +you need. + +All callbacks take two arguments, the Req object and the State, +and return a three-element tuple of the form `{Value, Req, State}`. + +All callbacks can also return `{stop, Req, State}` to stop execution +of the request. + +The following table summarizes the callbacks and their default values. +If the callback isn't defined, then the default value will be used. +Please look at the flowcharts to find out the result of each return +value. + +In the following table, "skip" means the callback is entirely skipped +if it is undefined, moving directly to the next step. Similarly, +"none" means there is no default value for this callback. + +[cols="<,^",options="header"] +|=== +| Callback name | Default value +| allowed_methods | `[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]` +| allow_missing_post | `true` +| charsets_provided | skip +| content_types_accepted | none +| content_types_provided | `$$[{{<<"text">>, <<"html">>, '*'}, to_html}]$$` +| delete_completed | `true` +| delete_resource | `false` +| expires | `undefined` +| forbidden | `false` +| generate_etag | `undefined` +| is_authorized | `true` +| is_conflict | `false` +| known_methods | `[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]` +| languages_provided | skip +| last_modified | `undefined` +| malformed_request | `false` +| moved_permanently | `false` +| moved_temporarily | `false` +| multiple_choices | `false` +| options | `ok` +| previously_existed | `false` +| resource_exists | `true` +| service_available | `true` +| uri_too_long | `false` +| valid_content_headers | `true` +| valid_entity_length | `true` +| variances | `[]` +|=== + +As you can see, Cowboy tries to move on with the request whenever +possible by using well thought out default values. + +In addition to these, there can be any number of user-defined +callbacks that are specified through `content_types_accepted/2` +and `content_types_provided/2`. They can take any name, however +it is recommended to use a separate prefix for the callbacks of +each function. For example, `from_html` and `to_html` indicate +in the first case that we're accepting a resource given as HTML, +and in the second case that we send one as HTML. + +=== Meta data + +Cowboy will set informative meta values at various points of the +execution. You can retrieve them using `cowboy_req:meta/{2,3}`. +The values are defined in the following table. + +[cols="<,<",options="header"] +|=== +| Meta key | Details +| media_type | The content-type negotiated for the response entity. +| language | The language negotiated for the response entity. +| charset | The charset negotiated for the response entity. +|=== + +They can be used to send a proper body with the response to a +request that used a method other than HEAD or GET. + +=== Response headers + +Cowboy will set response headers automatically over the execution +of the REST code. They are listed in the following table. + +[cols="<,<",options="header"] +|=== +| Header name | Details +| content-language | Language used in the response body +| content-type | Media type and charset of the response body +| etag | Etag of the resource +| expires | Expiration date of the resource +| last-modified | Last modification date for the resource +| location | Relative or absolute URI to the requested resource +| vary | List of headers that may change the representation of the resource +|=== diff --git a/docs/en/cowboy/2.0/guide/rest_handlers/index.html b/docs/en/cowboy/2.0/guide/rest_handlers/index.html new file mode 100644 index 00000000..15282e5f --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_handlers/index.html @@ -0,0 +1,231 @@ + + + + + + + + + + + + Nine Nines: REST handlers + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

REST handlers

+ +

REST is implemented in Cowboy as a sub protocol. The request +is handled as a state machine with many optional callbacks +describing the resource and modifying the machine’s behavior.

+

The REST handler is the recommended way to handle HTTP requests.

+
+

Initialization

+
+

First, the init/2 callback is called. This callback is common +to all handlers. To use REST for the current request, this function +must return a cowboy_rest tuple.

+
+
+
init(Req, _Opts) ->
+    {cowboy_rest, Req, #state{}}.
+

Cowboy will then switch to the REST protocol and start executing +the state machine.

+

After reaching the end of the flowchart, the terminate/3 callback +will be called if it is defined.

+
+
+
+

Methods

+
+

The REST component has code for handling the following HTTP methods: +HEAD, GET, POST, PATCH, PUT, DELETE and OPTIONS.

+

Other methods can be accepted, however they have no specific callback +defined for them at this time.

+
+
+
+

Callbacks

+
+

All callbacks are optional. Some may become mandatory depending +on what other defined callbacks return. The various flowcharts +in the next chapter should be a useful to determine which callbacks +you need.

+

All callbacks take two arguments, the Req object and the State, +and return a three-element tuple of the form {Value, Req, State}.

+

All callbacks can also return {stop, Req, State} to stop execution +of the request.

+

The following table summarizes the callbacks and their default values. +If the callback isn’t defined, then the default value will be used. +Please look at the flowcharts to find out the result of each return +value.

+

In the following table, "skip" means the callback is entirely skipped +if it is undefined, moving directly to the next step. Similarly, +"none" means there is no default value for this callback.

+
+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Callback name Default value

allowed_methods

[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]

allow_missing_post

true

charsets_provided

skip

content_types_accepted

none

content_types_provided

`$$[

+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/rest_options.png b/docs/en/cowboy/2.0/guide/rest_options.png new file mode 100644 index 00000000..90fd6f06 Binary files /dev/null and b/docs/en/cowboy/2.0/guide/rest_options.png differ diff --git a/docs/en/cowboy/2.0/guide/rest_options.svg b/docs/en/cowboy/2.0/guide/rest_options.svg new file mode 100644 index 00000000..496c050c --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_options.svg @@ -0,0 +1,387 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + some text + start + options + 200 OK + + + + + + + middlewares + + diff --git a/docs/en/cowboy/2.0/guide/rest_principles.asciidoc b/docs/en/cowboy/2.0/guide/rest_principles.asciidoc new file mode 100644 index 00000000..66939cb7 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_principles.asciidoc @@ -0,0 +1,160 @@ +[[rest_principles]] +== REST principles + +This chapter will attempt to define the concepts behind REST +and explain what makes a service RESTful. + +REST is often confused with performing a distinct operation +depending on the HTTP method, while using more than the GET +and POST methods. That's highly misguided at best. + +We will first attempt to define REST and will look at what +it means in the context of HTTP and the Web. +For a more in-depth explanation of REST, you can read +http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm[Roy T. Fielding's dissertation] +as it does a great job explaining where it comes from and +what it achieves. + +=== REST architecture + +REST is a *client-server* architecture. The client and the server +both have a different set of concerns. The server stores and/or +manipulates information and makes it available to the user in +an efficient manner. The client takes that information and +displays it to the user and/or uses it to perform subsequent +requests for information. This separation of concerns allows both +the client and the server to evolve independently as it only +requires that the interface stays the same. + +REST is *stateless*. That means the communication between the +client and the server always contains all the information needed +to perform the request. There is no session state in the server, +it is kept entirely on the client's side. If access to a resource +requires authentication, then the client needs to authenticate +itself with every request. + +REST is *cacheable*. The client, the server and any intermediary +components can all cache resources in order to improve performance. + +REST provides a *uniform interface* between components. This +simplifies the architecture, as all components follow the same +rules to speak to one another. It also makes it easier to understand +the interactions between the different components of the system. +A number of constraints are required to achieve this. They are +covered in the rest of the chapter. + +REST is a *layered system*. Individual components cannot see +beyond the immediate layer with which they are interacting. This +means that a client connecting to an intermediate component, like +a proxy, has no knowledge of what lies beyond. This allows +components to be independent and thus easily replaceable or +extendable. + +REST optionally provides *code on demand*. Code may be downloaded +to extend client functionality. This is optional however because +the client may not be able to download or run this code, and so +a REST component cannot rely on it being executed. + +=== Resources and resource identifiers + +A resource is an abstract concept. In a REST system, any information +that can be named may be a resource. This includes documents, images, +a collection of resources and any other information. Any information +that can be the target of an hypertext link can be a resource. + +A resource is a conceptual mapping to a set of entities. The set of +entities evolves over time; a resource doesn't. For example, a resource +can map to "users who have logged in this past month" and another +to "all users". At some point in time they may map to the same set of +entities, because all users logged in this past month. But they are +still different resources. Similarly, if nobody logged in recently, +then the first resource may map to the empty set. This resource exists +regardless of the information it maps to. + +Resources are identified by uniform resource identifiers, also known +as URIs. Sometimes internationalized resource identifiers, or IRIs, +may also be used, but these can be directly translated into a URI. + +In practice we will identify two kinds of resources. Individual +resources map to a set of one element, for example "user Joe". +Collection of resources map to a set of 0 to N elements, +for example "all users". + +=== Resource representations + +The representation of a resource is a sequence of bytes associated +with metadata. + +The metadata comes as a list of key-value pairs, where the name +corresponds to a standard that defines the value's structure and +semantics. With HTTP, the metadata comes in the form of request +or response headers. The headers' structure and semantics are well +defined in the HTTP standard. Metadata includes representation +metadata, resource metadata and control data. + +The representation metadata gives information about the +representation, such as its media type, the date of last +modification, or even a checksum. + +Resource metadata could be link to related resources or +information about additional representations of the resource. + +Control data allows parameterizing the request or response. +For example, we may only want the representation returned if +it is more recent than the one we have in cache. Similarly, +we may want to instruct the client about how it should cache +the representation. This isn't restricted to caching. We may, +for example, want to store a new representation of a resource +only if it wasn't modified since we first retrieved it. + +The data format of a representation is also known as the media +type. Some media types are intended for direct rendering to the +user, while others are intended for automated processing. The +media type is a key component of the REST architecture. + +=== Self-descriptive messages + +Messages must be self-descriptive. That means that the data +format of a representation must always come with its media +type (and similarly requesting a resource involves choosing +the media type of the representation returned). If you are +sending HTML, then you must say it is HTML by sending the +media type with the representation. In HTTP this is done +using the content-type header. + +The media type is often an IANA registered media type, like +`text/html` or `image/png`, but does not need to be. Exactly +two things are important for respecting this constraint: that +the media type is well specified, and that the sender and +recipient agree about what the media type refers to. + +This means that you can create your own media types, like +`application/x-mine`, and that as long as you write the +specifications for it and that both endpoints agree about +it then the constraint is respected. + +=== Hypermedia as the engine of application state + +The last constraint is generally where services that claim +to be RESTful fail. Interactions with a server must be +entirely driven by hypermedia. The client does not need +any prior knowledge of the service in order to use it, +other than an entry point and of course basic understanding +of the media type of the representations, at the very least +enough to find and identify hyperlinks and link relations. + +To give a simple example, if your service only works with +the `application/json` media type then this constraint +cannot be respected (as there are no concept of links in +JSON) and thus your service isn't RESTful. This is the case +for the majority of self-proclaimed REST services. + +On the other hand if you create a JSON based media type +that has a concept of links and link relations, then +your service might be RESTful. + +Respecting this constraint means that the entirety of the +service becomes self-discoverable, not only the resources +in it, but also the operations you can perform on it. This +makes clients very thin as there is no need to implement +anything specific to the service to operate on it. diff --git a/docs/en/cowboy/2.0/guide/rest_principles/index.html b/docs/en/cowboy/2.0/guide/rest_principles/index.html new file mode 100644 index 00000000..1b4335dd --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_principles/index.html @@ -0,0 +1,289 @@ + + + + + + + + + + + + Nine Nines: REST principles + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

REST principles

+ +

This chapter will attempt to define the concepts behind REST +and explain what makes a service RESTful.

+

REST is often confused with performing a distinct operation +depending on the HTTP method, while using more than the GET +and POST methods. That’s highly misguided at best.

+

We will first attempt to define REST and will look at what +it means in the context of HTTP and the Web. +For a more in-depth explanation of REST, you can read +Roy T. Fielding’s dissertation +as it does a great job explaining where it comes from and +what it achieves.

+
+

REST architecture

+
+

REST is a client-server architecture. The client and the server +both have a different set of concerns. The server stores and/or +manipulates information and makes it available to the user in +an efficient manner. The client takes that information and +displays it to the user and/or uses it to perform subsequent +requests for information. This separation of concerns allows both +the client and the server to evolve independently as it only +requires that the interface stays the same.

+

REST is stateless. That means the communication between the +client and the server always contains all the information needed +to perform the request. There is no session state in the server, +it is kept entirely on the client’s side. If access to a resource +requires authentication, then the client needs to authenticate +itself with every request.

+

REST is cacheable. The client, the server and any intermediary +components can all cache resources in order to improve performance.

+

REST provides a uniform interface between components. This +simplifies the architecture, as all components follow the same +rules to speak to one another. It also makes it easier to understand +the interactions between the different components of the system. +A number of constraints are required to achieve this. They are +covered in the rest of the chapter.

+

REST is a layered system. Individual components cannot see +beyond the immediate layer with which they are interacting. This +means that a client connecting to an intermediate component, like +a proxy, has no knowledge of what lies beyond. This allows +components to be independent and thus easily replaceable or +extendable.

+

REST optionally provides code on demand. Code may be downloaded +to extend client functionality. This is optional however because +the client may not be able to download or run this code, and so +a REST component cannot rely on it being executed.

+
+
+
+

Resources and resource identifiers

+
+

A resource is an abstract concept. In a REST system, any information +that can be named may be a resource. This includes documents, images, +a collection of resources and any other information. Any information +that can be the target of an hypertext link can be a resource.

+

A resource is a conceptual mapping to a set of entities. The set of +entities evolves over time; a resource doesn’t. For example, a resource +can map to "users who have logged in this past month" and another +to "all users". At some point in time they may map to the same set of +entities, because all users logged in this past month. But they are +still different resources. Similarly, if nobody logged in recently, +then the first resource may map to the empty set. This resource exists +regardless of the information it maps to.

+

Resources are identified by uniform resource identifiers, also known +as URIs. Sometimes internationalized resource identifiers, or IRIs, +may also be used, but these can be directly translated into a URI.

+

In practice we will identify two kinds of resources. Individual +resources map to a set of one element, for example "user Joe". +Collection of resources map to a set of 0 to N elements, +for example "all users".

+
+
+
+

Resource representations

+
+

The representation of a resource is a sequence of bytes associated +with metadata.

+

The metadata comes as a list of key-value pairs, where the name +corresponds to a standard that defines the value’s structure and +semantics. With HTTP, the metadata comes in the form of request +or response headers. The headers' structure and semantics are well +defined in the HTTP standard. Metadata includes representation +metadata, resource metadata and control data.

+

The representation metadata gives information about the +representation, such as its media type, the date of last +modification, or even a checksum.

+

Resource metadata could be link to related resources or +information about additional representations of the resource.

+

Control data allows parameterizing the request or response. +For example, we may only want the representation returned if +it is more recent than the one we have in cache. Similarly, +we may want to instruct the client about how it should cache +the representation. This isn’t restricted to caching. We may, +for example, want to store a new representation of a resource +only if it wasn’t modified since we first retrieved it.

+

The data format of a representation is also known as the media +type. Some media types are intended for direct rendering to the +user, while others are intended for automated processing. The +media type is a key component of the REST architecture.

+
+
+
+

Self-descriptive messages

+
+

Messages must be self-descriptive. That means that the data +format of a representation must always come with its media +type (and similarly requesting a resource involves choosing +the media type of the representation returned). If you are +sending HTML, then you must say it is HTML by sending the +media type with the representation. In HTTP this is done +using the content-type header.

+

The media type is often an IANA registered media type, like +text/html or image/png, but does not need to be. Exactly +two things are important for respecting this constraint: that +the media type is well specified, and that the sender and +recipient agree about what the media type refers to.

+

This means that you can create your own media types, like +application/x-mine, and that as long as you write the +specifications for it and that both endpoints agree about +it then the constraint is respected.

+
+
+
+

Hypermedia as the engine of application state

+
+

The last constraint is generally where services that claim +to be RESTful fail. Interactions with a server must be +entirely driven by hypermedia. The client does not need +any prior knowledge of the service in order to use it, +other than an entry point and of course basic understanding +of the media type of the representations, at the very least +enough to find and identify hyperlinks and link relations.

+

To give a simple example, if your service only works with +the application/json media type then this constraint +cannot be respected (as there are no concept of links in +JSON) and thus your service isn’t RESTful. This is the case +for the majority of self-proclaimed REST services.

+

On the other hand if you create a JSON based media type +that has a concept of links and link relations, then +your service might be RESTful.

+

Respecting this constraint means that the entirety of the +service becomes self-discoverable, not only the resources +in it, but also the operations you can perform on it. This +makes clients very thin as there is no need to implement +anything specific to the service to operate on it.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/rest_put_post_patch.png b/docs/en/cowboy/2.0/guide/rest_put_post_patch.png new file mode 100644 index 00000000..4afca9e9 Binary files /dev/null and b/docs/en/cowboy/2.0/guide/rest_put_post_patch.png differ diff --git a/docs/en/cowboy/2.0/guide/rest_put_post_patch.svg b/docs/en/cowboy/2.0/guide/rest_put_post_patch.svg new file mode 100644 index 00000000..263cc942 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_put_post_patch.svg @@ -0,0 +1,2856 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + some text + conneg + resource_exists + + true + + + + + false + + + + + + middlewares + + + + + true + + + + + + + + + + + + + + + cond + + + + + + has if-match? + false + + + + + + method is POST/PATCH? + true + + + + + + + + + + + + + + + + + + + method is POST? + + 412 precondition failed + + + + + + + + + + + + + + previously_existed + + + + + + 404 not found + false + + + + + + + + + true* + false + + 301 moved permanently + + + + + + + + + + moved_temporarily + true* + false + + 307 moved temporarily + + 400 bad request + + + + + true + + + + + + allow_missing_post + + method is POST? + allow_missing_post + + + + + + method is PUT? + + + + + + + + + + is_conflict + true + + 409 conflict + + + + + + content_types_accepted + + AcceptResource + + + + + + + + + + new resource? + + + + + + + + + + new resource? + + 201 created + + 303 see other + + + + + + + + + + has resp location? + + + + + + + + + + + has resp body? + + + + + + + + + + multiple_choices + false + + 300 multiple choices + + 200 OK + 204 no content + true + + + + + true + + moved_permanently + + 410 gone + false + true + false + false + false + false + + + + + true + + + + + true, URI* + + + + + true + false + true + true + false + true + false + true + false + false + false + + + + + + + + true + + + + + false + true + + diff --git a/docs/en/cowboy/2.0/guide/rest_start.png b/docs/en/cowboy/2.0/guide/rest_start.png new file mode 100644 index 00000000..1f1e312e Binary files /dev/null and b/docs/en/cowboy/2.0/guide/rest_start.png differ diff --git a/docs/en/cowboy/2.0/guide/rest_start.svg b/docs/en/cowboy/2.0/guide/rest_start.svg new file mode 100644 index 00000000..076c6195 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/rest_start.svg @@ -0,0 +1,1356 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + some text + some text + uri_too_long + malformed_request + some text + init + is_authorized + forbidden + valid_content_headers + valid_entity_length + ... + service_available + known_methods + allowed_methods + + true + known* + false + allowed* + false + true + false + true + true + + + + + false + unknown* + true + unallowed* + true + false* + true + false + false + + 503 service unavailable + + + + + + + + + 501 not implemented + 414 request URI too long + 405 method not allowed + 400 bad request + 401 unauthorized + 403 forbidden + 501 not implemented + 413 request entity too large + + middlewares + + diff --git a/docs/en/cowboy/2.0/guide/routing.asciidoc b/docs/en/cowboy/2.0/guide/routing.asciidoc new file mode 100644 index 00000000..6ac2ebde --- /dev/null +++ b/docs/en/cowboy/2.0/guide/routing.asciidoc @@ -0,0 +1,224 @@ +[[routing]] +== Routing + +Cowboy does nothing by default. + +To make Cowboy useful, you need to map URLs to Erlang modules that will +handle the requests. This is called routing. + +When Cowboy receives a request, it tries to match the requested host and +path to the resources given in the dispatch rules. If it matches, then +the associated Erlang code will be executed. + +Routing rules are given per host. Cowboy will first match on the host, +and then try to find a matching path. + +Routes need to be compiled before they can be used by Cowboy. + +=== Structure + +The general structure for the routes is defined as follow. + +[source,erlang] +Routes = [Host1, Host2, ... HostN]. + +Each host contains matching rules for the host along with optional +constraints, and a list of routes for the path component. + +[source,erlang] +Host1 = {HostMatch, PathsList}. +Host2 = {HostMatch, Constraints, PathsList}. + +The list of routes for the path component is defined similar to the +list of hosts. + +[source,erlang] +PathsList = [Path1, Path2, ... PathN]. + +Finally, each path contains matching rules for the path along with +optional constraints, and gives us the handler module to be used +along with options that will be given to it on initialization. + +[source,erlang] +Path1 = {PathMatch, Handler, Opts}. +Path2 = {PathMatch, Constraints, Handler, Opts}. + +Continue reading to learn more about the match syntax and the optional +constraints. + +=== Match syntax + +The match syntax is used to associate host names and paths with their +respective handlers. + +The match syntax is the same for host and path with a few subtleties. +Indeed, the segments separator is different, and the host is matched +starting from the last segment going to the first. All examples will +feature both host and path match rules and explain the differences +when encountered. + +Excluding special values that we will explain at the end of this section, +the simplest match value is a host or a path. It can be given as either +a `string()` or a `binary()`. + +[source,erlang] +---- +PathMatch1 = "/". +PathMatch2 = "/path/to/resource". + +HostMatch1 = "cowboy.example.org". +---- + +As you can see, all paths defined this way must start with a slash +character. Note that these two paths are identical as far as routing +is concerned. + +[source,erlang] +PathMatch2 = "/path/to/resource". +PathMatch3 = "/path/to/resource/". + +Hosts with and without a trailing dot are equivalent for routing. +Similarly, hosts with and without a leading dot are also equivalent. + +[source,erlang] +HostMatch1 = "cowboy.example.org". +HostMatch2 = "cowboy.example.org.". +HostMatch3 = ".cowboy.example.org". + +It is possible to extract segments of the host and path and to store +the values in the `Req` object for later use. We call these kind of +values bindings. + +The syntax for bindings is very simple. A segment that begins with +the `:` character means that what follows until the end of the segment +is the name of the binding in which the segment value will be stored. + +[source,erlang] +PathMatch = "/hats/:name/prices". +HostMatch = ":subdomain.example.org". + +If these two end up matching when routing, you will end up with two +bindings defined, `subdomain` and `name`, each containing the +segment value where they were defined. For example, the URL +`http://test.example.org/hats/wild_cowboy_legendary/prices` will +result in having the value `test` bound to the name `subdomain` +and the value `wild_cowboy_legendary` bound to the name `name`. +They can later be retrieved using `cowboy_req:binding/{2,3}`. The +binding name must be given as an atom. + +There is a special binding name you can use to mimic the underscore +variable in Erlang. Any match against the `_` binding will succeed +but the data will be discarded. This is especially useful for +matching against many domain names in one go. + +[source,erlang] +HostMatch = "ninenines.:_". + +Similarly, it is possible to have optional segments. Anything +between brackets is optional. + +[source,erlang] +PathMatch = "/hats/[page/:number]". +HostMatch = "[www.]ninenines.eu". + +You can also have imbricated optional segments. + +[source,erlang] +PathMatch = "/hats/[page/[:number]]". + +You can retrieve the rest of the host or path using `[...]`. +In the case of hosts it will match anything before, in the case +of paths anything after the previously matched segments. It is +a special case of optional segments, in that it can have +zero, one or many segments. You can then find the segments using +`cowboy_req:host_info/1` and `cowboy_req:path_info/1` respectively. +They will be represented as a list of segments. + +[source,erlang] +PathMatch = "/hats/[...]". +HostMatch = "[...]ninenines.eu". + +If a binding appears twice in the routing rules, then the match +will succeed only if they share the same value. This copies the +Erlang pattern matching behavior. + +[source,erlang] +PathMatch = "/hats/:name/:name". + +This is also true when an optional segment is present. In this +case the two values must be identical only if the segment is +available. + +[source,erlang] +PathMatch = "/hats/:name/[:name]". + +If a binding is defined in both the host and path, then they must +also share the same value. + +[source,erlang] +PathMatch = "/:user/[...]". +HostMatch = ":user.github.com". + +Finally, there are two special match values that can be used. The +first is the atom `'_'` which will match any host or path. + +[source,erlang] +PathMatch = '_'. +HostMatch = '_'. + +The second is the special host match `"*"` which will match the +wildcard path, generally used alongside the `OPTIONS` method. + +[source,erlang] +HostMatch = "*". + +=== Constraints + +After the matching has completed, the resulting bindings can be tested +against a set of constraints. Constraints are only tested when the +binding is defined. They run in the order you defined them. The match +will succeed only if they all succeed. If the match fails, then Cowboy +tries the next route in the list. + +The format used for constraints is the same as match functions in +`cowboy_req`: they are provided as a list of fields which may have +one or more constraints. While the router accepts the same format, +it will skip fields with no constraints and will also ignore default +values, if any. + +Read more about xref:constraints[constraints]. + +=== Compilation + +The structure defined in this chapter needs to be compiled before it is +passed to Cowboy. This allows Cowboy to efficiently lookup the correct +handler to run instead of having to parse the routes repeatedly. + +This can be done with a simple call to `cowboy_router:compile/1`. + +[source,erlang] +---- +Dispatch = cowboy_router:compile([ + %% {HostMatch, list({PathMatch, Handler, Opts})} + {'_', [{'_', my_handler, []}]} +]), +%% Name, NbAcceptors, TransOpts, ProtoOpts +cowboy:start_http(my_http_listener, 100, + [{port, 8080}], + [{env, [{dispatch, Dispatch}]}] +). +---- + +Note that this function will return `{error, badarg}` if the structure +given is incorrect. + +=== Live update + +You can use the `cowboy:set_env/3` function for updating the dispatch +list used by routing. This will apply to all new connections accepted +by the listener. + +[source,erlang] +cowboy:set_env(my_http_listener, dispatch, cowboy_router:compile(Dispatch)). + +Note that you need to compile the routes before updating. diff --git a/docs/en/cowboy/2.0/guide/routing/index.html b/docs/en/cowboy/2.0/guide/routing/index.html new file mode 100644 index 00000000..032d8214 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/routing/index.html @@ -0,0 +1,397 @@ + + + + + + + + + + + + Nine Nines: Routing + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Routing

+ +

Cowboy does nothing by default.

+

To make Cowboy useful, you need to map URLs to Erlang modules that will +handle the requests. This is called routing.

+

When Cowboy receives a request, it tries to match the requested host and +path to the resources given in the dispatch rules. If it matches, then +the associated Erlang code will be executed.

+

Routing rules are given per host. Cowboy will first match on the host, +and then try to find a matching path.

+

Routes need to be compiled before they can be used by Cowboy.

+
+

Structure

+
+

The general structure for the routes is defined as follow.

+
+
+
Routes = [Host1, Host2, ... HostN].
+

Each host contains matching rules for the host along with optional +constraints, and a list of routes for the path component.

+
+
+
Host1 = {HostMatch, PathsList}.
+Host2 = {HostMatch, Constraints, PathsList}.
+

The list of routes for the path component is defined similar to the +list of hosts.

+
+
+
PathsList = [Path1, Path2, ... PathN].
+

Finally, each path contains matching rules for the path along with +optional constraints, and gives us the handler module to be used +along with options that will be given to it on initialization.

+
+
+
Path1 = {PathMatch, Handler, Opts}.
+Path2 = {PathMatch, Constraints, Handler, Opts}.
+

Continue reading to learn more about the match syntax and the optional +constraints.

+
+
+
+

Match syntax

+
+

The match syntax is used to associate host names and paths with their +respective handlers.

+

The match syntax is the same for host and path with a few subtleties. +Indeed, the segments separator is different, and the host is matched +starting from the last segment going to the first. All examples will +feature both host and path match rules and explain the differences +when encountered.

+

Excluding special values that we will explain at the end of this section, +the simplest match value is a host or a path. It can be given as either +a string() or a binary().

+
+
+
PathMatch1 = "/".
+PathMatch2 = "/path/to/resource".
+
+HostMatch1 = "cowboy.example.org".
+

As you can see, all paths defined this way must start with a slash +character. Note that these two paths are identical as far as routing +is concerned.

+
+
+
PathMatch2 = "/path/to/resource".
+PathMatch3 = "/path/to/resource/".
+

Hosts with and without a trailing dot are equivalent for routing. +Similarly, hosts with and without a leading dot are also equivalent.

+
+
+
HostMatch1 = "cowboy.example.org".
+HostMatch2 = "cowboy.example.org.".
+HostMatch3 = ".cowboy.example.org".
+

It is possible to extract segments of the host and path and to store +the values in the Req object for later use. We call these kind of +values bindings.

+

The syntax for bindings is very simple. A segment that begins with +the : character means that what follows until the end of the segment +is the name of the binding in which the segment value will be stored.

+
+
+
PathMatch = "/hats/:name/prices".
+HostMatch = ":subdomain.example.org".
+

If these two end up matching when routing, you will end up with two +bindings defined, subdomain and name, each containing the +segment value where they were defined. For example, the URL +http://test.example.org/hats/wild_cowboy_legendary/prices will +result in having the value test bound to the name subdomain +and the value wild_cowboy_legendary bound to the name name. +They can later be retrieved using cowboy_req:binding/{2,3}. The +binding name must be given as an atom.

+

There is a special binding name you can use to mimic the underscore +variable in Erlang. Any match against the _ binding will succeed +but the data will be discarded. This is especially useful for +matching against many domain names in one go.

+
+
+
HostMatch = "ninenines.:_".
+

Similarly, it is possible to have optional segments. Anything +between brackets is optional.

+
+
+
PathMatch = "/hats/[page/:number]".
+HostMatch = "[www.]ninenines.eu".
+

You can also have imbricated optional segments.

+
+
+
PathMatch = "/hats/[page/[:number]]".
+

You can retrieve the rest of the host or path using [...]. +In the case of hosts it will match anything before, in the case +of paths anything after the previously matched segments. It is +a special case of optional segments, in that it can have +zero, one or many segments. You can then find the segments using +cowboy_req:host_info/1 and cowboy_req:path_info/1 respectively. +They will be represented as a list of segments.

+
+
+
PathMatch = "/hats/[...]".
+HostMatch = "[...]ninenines.eu".
+

If a binding appears twice in the routing rules, then the match +will succeed only if they share the same value. This copies the +Erlang pattern matching behavior.

+
+
+
PathMatch = "/hats/:name/:name".
+

This is also true when an optional segment is present. In this +case the two values must be identical only if the segment is +available.

+
+
+
PathMatch = "/hats/:name/[:name]".
+

If a binding is defined in both the host and path, then they must +also share the same value.

+
+
+
PathMatch = "/:user/[...]".
+HostMatch = ":user.github.com".
+

Finally, there are two special match values that can be used. The +first is the atom '_' which will match any host or path.

+
+
+
PathMatch = '_'.
+HostMatch = '_'.
+

The second is the special host match "*" which will match the +wildcard path, generally used alongside the OPTIONS method.

+
+
+
HostMatch = "*".
+
+
+
+

Constraints

+
+

After the matching has completed, the resulting bindings can be tested +against a set of constraints. Constraints are only tested when the +binding is defined. They run in the order you defined them. The match +will succeed only if they all succeed. If the match fails, then Cowboy +tries the next route in the list.

+

The format used for constraints is the same as match functions in +cowboy_req: they are provided as a list of fields which may have +one or more constraints. While the router accepts the same format, +it will skip fields with no constraints and will also ignore default +values, if any.

+

Read more about constraints.

+
+
+
+

Compilation

+
+

The structure defined in this chapter needs to be compiled before it is +passed to Cowboy. This allows Cowboy to efficiently lookup the correct +handler to run instead of having to parse the routes repeatedly.

+

This can be done with a simple call to cowboy_router:compile/1.

+
+
+
Dispatch = cowboy_router:compile([
+    %% {HostMatch, list({PathMatch, Handler, Opts})}
+    {'_', [{'_', my_handler, []}]}
+]),
+%% Name, NbAcceptors, TransOpts, ProtoOpts
+cowboy:start_http(my_http_listener, 100,
+    [{port, 8080}],
+    [{env, [{dispatch, Dispatch}]}]
+).
+

Note that this function will return {error, badarg} if the structure +given is incorrect.

+
+
+
+

Live update

+
+

You can use the cowboy:set_env/3 function for updating the dispatch +list used by routing. This will apply to all new connections accepted +by the listener.

+
+
+
cowboy:set_env(my_http_listener, dispatch, cowboy_router:compile(Dispatch)).
+

Note that you need to compile the routes before updating.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/static_files.asciidoc b/docs/en/cowboy/2.0/guide/static_files.asciidoc new file mode 100644 index 00000000..39197a88 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/static_files.asciidoc @@ -0,0 +1,171 @@ +[[static_files]] +== Static files + +Cowboy comes with a special handler built as a REST handler +and designed specifically for serving static files. It is +provided as a convenience and provides a quick solution for +serving files during development. + +For systems in production, consider using one of the many +Content Distribution Network (CDN) available on the market, +as they are the best solution for serving files. They are +covered in the next chapter. If you decide against using a +CDN solution, then please look at the chapter after that, +as it explains how to efficiently serve static files on +your own. + +The static handler can serve either one file or all files +from a given directory. It can also send etag headers for +client-side caching. + +To use the static file handler, simply add routes for it +with the appropriate options. + +=== Serve one file + +You can use the static handler to serve one specific file +from an application's private directory. This is particularly +useful to serve an 'index.html' file when the client requests +the `/` path, for example. The path configured is relative +to the given application's private directory. + +The following rule will serve the file 'static/index.html' +from the application `my_app`'s priv directory whenever the +path `/` is accessed. + +[source,erlang] +{"/", cowboy_static, {priv_file, my_app, "static/index.html"}} + +You can also specify the absolute path to a file, or the +path to the file relative to the current directory. + +[source,erlang] +{"/", cowboy_static, {file, "/var/www/index.html"}} + +=== Serve all files from a directory + +You can also use the static handler to serve all files that +can be found in the configured directory. The handler will +use the `path_info` information to resolve the file location, +which means that your route must end with a `[...]` pattern +for it to work. All files are served, including the ones that +may be found in subfolders. + +You can specify the directory relative to an application's +private directory. + +The following rule will serve any file found in the application +`my_app`'s priv directory inside the `static/assets` folder +whenever the requested path begins with `/assets/`. + +[source,erlang] +{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets"}} + +You can also specify the absolute path to the directory or +set it relative to the current directory. + +[source,erlang] +{"/assets/[...]", cowboy_static, {dir, "/var/www/assets"}} + +=== Customize the mimetype detection + +By default, Cowboy will attempt to recognize the mimetype +of your static files by looking at the extension. + +You can override the function that figures out the mimetype +of the static files. It can be useful when Cowboy is missing +a mimetype you need to handle, or when you want to reduce +the list to make lookups faster. You can also give a +hard-coded mimetype that will be used unconditionally. + +Cowboy comes with two functions built-in. The default +function only handles common file types used when building +Web applications. The other function is an extensive list +of hundreds of mimetypes that should cover almost any need +you may have. You can of course create your own function. + +To use the default function, you should not have to configure +anything, as it is the default. If you insist, though, the +following will do the job. + +[source,erlang] +---- +{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets", + [{mimetypes, cow_mimetypes, web}]}} +---- + +As you can see, there is an optional field that may contain +a list of less used options, like mimetypes or etag. All option +types have this optional field. + +To use the function that will detect almost any mimetype, +the following configuration will do. + +[source,erlang] +---- +{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets", + [{mimetypes, cow_mimetypes, all}]}} +---- + +You probably noticed the pattern by now. The configuration +expects a module and a function name, so you can use any +of your own functions instead. + +[source,erlang] +---- +{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets", + [{mimetypes, Module, Function}]}} +---- + +The function that performs the mimetype detection receives +a single argument that is the path to the file on disk. It +is recommended to return the mimetype in tuple form, although +a binary string is also allowed (but will require extra +processing). If the function can't figure out the mimetype, +then it should return `{<<"application">>, <<"octet-stream">>, []}`. + +When the static handler fails to find the extension in the +list, it will send the file as `application/octet-stream`. +A browser receiving such file will attempt to download it +directly to disk. + +Finally, the mimetype can be hard-coded for all files. +This is especially useful in combination with the `file` +and `priv_file` options as it avoids needless computation. + +[source,erlang] +---- +{"/", cowboy_static, {priv_file, my_app, "static/index.html", + [{mimetypes, {<<"text">>, <<"html">>, []}}]}} +---- + +=== Generate an etag + +By default, the static handler will generate an etag header +value based on the size and modified time. This solution +can not be applied to all systems though. It would perform +rather poorly over a cluster of nodes, for example, as the +file metadata will vary from server to server, giving a +different etag on each server. + +You can however change the way the etag is calculated. + +[source,erlang] +---- +{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets", + [{etag, Module, Function}]}} +---- + +This function will receive three arguments: the path to the +file on disk, the size of the file and the last modification +time. In a distributed setup, you would typically use the +file path to retrieve an etag value that is identical across +all your servers. + +You can also completely disable etag handling. + +[source,erlang] +---- +{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets", + [{etag, false}]}} +---- diff --git a/docs/en/cowboy/2.0/guide/static_files/index.html b/docs/en/cowboy/2.0/guide/static_files/index.html new file mode 100644 index 00000000..6ef9d782 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/static_files/index.html @@ -0,0 +1,316 @@ + + + + + + + + + + + + Nine Nines: Static files + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Static files

+ +

Cowboy comes with a special handler built as a REST handler +and designed specifically for serving static files. It is +provided as a convenience and provides a quick solution for +serving files during development.

+

For systems in production, consider using one of the many +Content Distribution Network (CDN) available on the market, +as they are the best solution for serving files. They are +covered in the next chapter. If you decide against using a +CDN solution, then please look at the chapter after that, +as it explains how to efficiently serve static files on +your own.

+

The static handler can serve either one file or all files +from a given directory. It can also send etag headers for +client-side caching.

+

To use the static file handler, simply add routes for it +with the appropriate options.

+
+

Serve one file

+
+

You can use the static handler to serve one specific file +from an application’s private directory. This is particularly +useful to serve an index.html file when the client requests +the / path, for example. The path configured is relative +to the given application’s private directory.

+

The following rule will serve the file static/index.html +from the application my_app's priv directory whenever the +path / is accessed.

+
+
+
{"/", cowboy_static, {priv_file, my_app, "static/index.html"}}
+

You can also specify the absolute path to a file, or the +path to the file relative to the current directory.

+
+
+
{"/", cowboy_static, {file, "/var/www/index.html"}}
+
+
+
+

Serve all files from a directory

+
+

You can also use the static handler to serve all files that +can be found in the configured directory. The handler will +use the path_info information to resolve the file location, +which means that your route must end with a [...] pattern +for it to work. All files are served, including the ones that +may be found in subfolders.

+

You can specify the directory relative to an application’s +private directory.

+

The following rule will serve any file found in the application +my_app's priv directory inside the static/assets folder +whenever the requested path begins with /assets/.

+
+
+
{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets"}}
+

You can also specify the absolute path to the directory or +set it relative to the current directory.

+
+
+
{"/assets/[...]", cowboy_static, {dir, "/var/www/assets"}}
+
+
+
+

Customize the mimetype detection

+
+

By default, Cowboy will attempt to recognize the mimetype +of your static files by looking at the extension.

+

You can override the function that figures out the mimetype +of the static files. It can be useful when Cowboy is missing +a mimetype you need to handle, or when you want to reduce +the list to make lookups faster. You can also give a +hard-coded mimetype that will be used unconditionally.

+

Cowboy comes with two functions built-in. The default +function only handles common file types used when building +Web applications. The other function is an extensive list +of hundreds of mimetypes that should cover almost any need +you may have. You can of course create your own function.

+

To use the default function, you should not have to configure +anything, as it is the default. If you insist, though, the +following will do the job.

+
+
+
{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets",
+    [{mimetypes, cow_mimetypes, web}]}}
+

As you can see, there is an optional field that may contain +a list of less used options, like mimetypes or etag. All option +types have this optional field.

+

To use the function that will detect almost any mimetype, +the following configuration will do.

+
+
+
{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets",
+    [{mimetypes, cow_mimetypes, all}]}}
+

You probably noticed the pattern by now. The configuration +expects a module and a function name, so you can use any +of your own functions instead.

+
+
+
{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets",
+    [{mimetypes, Module, Function}]}}
+

The function that performs the mimetype detection receives +a single argument that is the path to the file on disk. It +is recommended to return the mimetype in tuple form, although +a binary string is also allowed (but will require extra +processing). If the function can’t figure out the mimetype, +then it should return {<<"application">>, <<"octet-stream">>, []}.

+

When the static handler fails to find the extension in the +list, it will send the file as application/octet-stream. +A browser receiving such file will attempt to download it +directly to disk.

+

Finally, the mimetype can be hard-coded for all files. +This is especially useful in combination with the file +and priv_file options as it avoids needless computation.

+
+
+
{"/", cowboy_static, {priv_file, my_app, "static/index.html",
+    [{mimetypes, {<<"text">>, <<"html">>, []}}]}}
+
+
+
+

Generate an etag

+
+

By default, the static handler will generate an etag header +value based on the size and modified time. This solution +can not be applied to all systems though. It would perform +rather poorly over a cluster of nodes, for example, as the +file metadata will vary from server to server, giving a +different etag on each server.

+

You can however change the way the etag is calculated.

+
+
+
{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets",
+    [{etag, Module, Function}]}}
+

This function will receive three arguments: the path to the +file on disk, the size of the file and the last modification +time. In a distributed setup, you would typically use the +file path to retrieve an etag value that is identical across +all your servers.

+

You can also completely disable etag handling.

+
+
+
{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets",
+    [{etag, false}]}}
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/sub_protocols.asciidoc b/docs/en/cowboy/2.0/guide/sub_protocols.asciidoc new file mode 100644 index 00000000..63fd52be --- /dev/null +++ b/docs/en/cowboy/2.0/guide/sub_protocols.asciidoc @@ -0,0 +1,68 @@ +[[sub_protocols]] +== Sub protocols + +Sub protocols are used for creating new types of handlers that +provide extra functionality in a reusable way. Cowboy uses this +mechanism to provide its loop, REST and Websocket handlers. + +This chapter will explain how to create your own sub protocols +and handler types. + +=== Usage + +To switch to a sub protocol, the `init/2` callback must return +the name of the sub protocol module. Everything past this point +is handled by the sub protocol. + +[source,erlang] +---- +init(Req, _Opts) -> + {cowboy_websocket, Req, #state{}}. +---- + +The return value may also have a `Timeout` value and/or the +atom `hibernate`. These options are useful for long living +connections. When they are not provided, the timeout value +defaults to `infinity` and the hibernate value to `run`. + +The following snippet switches to the `my_protocol` sub +protocol, sets the timeout value to 5 seconds and enables +hibernation: + +[source,erlang] +---- +init(Req, _Opts) -> + {my_protocol, Req, #state{}, 5000, hibernate}. +---- + +If a sub protocol does not make use of these options, it should +crash if it receives anything other than the default values. + +=== Upgrade + +After the `init/2` function returns, Cowboy will then call the +`upgrade/6` function. This is the only callback defined by the +`cowboy_sub_protocol` behavior. + +The function is named `upgrade` because it mimics the mechanism +of HTTP protocol upgrades. For some sub protocols, like Websocket, +an actual upgrade is performed. For others, like REST, this is +only an upgrade at Cowboy's level and the client has nothing to +do about it. + +The upgrade callback receives the Req object, the middleware +environment, the handler and its options, and the aforementioned +timeout and hibernate values. + +[source,erlang] +---- +upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) -> + %% Sub protocol code here. +---- + +This callback is expected to behave like a middleware and to +return an updated environment and Req object. + +Sub protocols are expected to call the `cowboy_handler:terminate/4` +function when they terminate. This function will make sure that +the optional `terminate/3` callback is called, if present. diff --git a/docs/en/cowboy/2.0/guide/sub_protocols/index.html b/docs/en/cowboy/2.0/guide/sub_protocols/index.html new file mode 100644 index 00000000..c75da6a4 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/sub_protocols/index.html @@ -0,0 +1,206 @@ + + + + + + + + + + + + Nine Nines: Sub protocols + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Sub protocols

+ +

Sub protocols are used for creating new types of handlers that +provide extra functionality in a reusable way. Cowboy uses this +mechanism to provide its loop, REST and Websocket handlers.

+

This chapter will explain how to create your own sub protocols +and handler types.

+
+

Usage

+
+

To switch to a sub protocol, the init/2 callback must return +the name of the sub protocol module. Everything past this point +is handled by the sub protocol.

+
+
+
init(Req, _Opts) ->
+        {cowboy_websocket, Req, #state{}}.
+

The return value may also have a Timeout value and/or the +atom hibernate. These options are useful for long living +connections. When they are not provided, the timeout value +defaults to infinity and the hibernate value to run.

+

The following snippet switches to the my_protocol sub +protocol, sets the timeout value to 5 seconds and enables +hibernation:

+
+
+
init(Req, _Opts) ->
+        {my_protocol, Req, #state{}, 5000, hibernate}.
+

If a sub protocol does not make use of these options, it should +crash if it receives anything other than the default values.

+
+
+
+

Upgrade

+
+

After the init/2 function returns, Cowboy will then call the +upgrade/6 function. This is the only callback defined by the +cowboy_sub_protocol behavior.

+

The function is named upgrade because it mimics the mechanism +of HTTP protocol upgrades. For some sub protocols, like Websocket, +an actual upgrade is performed. For others, like REST, this is +only an upgrade at Cowboy’s level and the client has nothing to +do about it.

+

The upgrade callback receives the Req object, the middleware +environment, the handler and its options, and the aforementioned +timeout and hibernate values.

+
+
+
upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) ->
+        %% Sub protocol code here.
+

This callback is expected to behave like a middleware and to +return an updated environment and Req object.

+

Sub protocols are expected to call the cowboy_handler:terminate/4 +function when they terminate. This function will make sure that +the optional terminate/3 callback is called, if present.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc b/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc new file mode 100644 index 00000000..9ddddf4c --- /dev/null +++ b/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc @@ -0,0 +1,196 @@ +[[ws_handlers]] +== Handling Websocket connections + +A special handler is required for handling Websocket connections. +Websocket handlers allow you to initialize the connection, +handle incoming frames from the socket, handle incoming Erlang +messages and then clean up on termination. + +Websocket handlers essentially act as a bridge between the client +and the Erlang system. They will typically do little more than +socket communication and decoding/encoding of frames. + +=== Initialization + +First, the `init/2` callback is called. This callback is common +to all handlers. To establish a Websocket connection, this function +must return a `ws` tuple. + +[source,erlang] +---- +init(Req, _Opts) -> + {cowboy_websocket, Req, #state{}}. +---- + +Upon receiving this tuple, Cowboy will switch to the code +that handles Websocket connections and perform the handshake +immediately. + +If the sec-websocket-protocol header was sent with the request +for establishing a Websocket connection, then the Websocket +handler *must* select one of these subprotocol and send it +back to the client, otherwise the client might decide to close +the connection, assuming no correct subprotocol was found. + +[source,erlang] +---- +init(Req, _Opts) -> + case cowboy_req:parse_header(<<"sec-websocket-protocol">>, Req) of + undefined -> + {ok, Req, #state{}}; + Subprotocols -> + case lists:keymember(<<"mychat2">>, 1, Subprotocols) of + true -> + Req2 = cowboy_req:set_resp_header(<<"sec-websocket-protocol">>, + <<"mychat2">>, Req), + {ok, Req2, #state{}}; + false -> + {stop, Req, undefined} + end + end. +---- + +It is not recommended to wait too long inside the `init/2` +function. Any extra initialization may be done after returning by +sending yourself a message before doing anything. Any message sent +to `self()` from `init/2` is guaranteed to arrive before +any frames from the client. + +It is also very easy to ensure that this message arrives before +any message from other processes by sending it before registering +or enabling timers. + +[source,erlang] +---- +init(Req, _Opts) -> + self() ! post_init, + %% Register process here... + {cowboy_websocket, Req, #state{}}. + +websocket_info(post_init, Req, State) -> + %% Perform post_init initialization here... + {ok, Req, State}. +---- + +=== Handling frames from the client + +Cowboy will call `websocket_handle/3` whenever a text, binary, +ping or pong frame arrives from the client. Note that in the +case of ping and pong frames, no action is expected as Cowboy +automatically replies to ping frames. + +The handler can decide to send frames to the socket, stop +or just continue without sending anything. + +The following snippet echoes back any text frame received and +ignores all others. + +[source,erlang] +---- +websocket_handle(Frame = {text, _}, Req, State) -> + {reply, Frame, Req, State}; +websocket_handle(_Frame, Req, State) -> + {ok, Req, State}. +---- + +=== Handling Erlang messages + +Cowboy will call `websocket_info/3` whenever an Erlang message +arrives. + +The handler can decide to send frames to the socket, stop +or just continue without sending anything. + +The following snippet forwards any `log` message to the socket +and ignores all others. + +[source,erlang] +---- +websocket_info({log, Text}, Req, State) -> + {reply, {text, Text}, Req, State}; +websocket_info(_Info, Req, State) -> + {ok, Req, State}. +---- + +=== Sending frames to the socket + +Cowboy allows sending either a single frame or a list of +frames to the socket, in which case the frames are sent +sequentially. Any frame can be sent: text, binary, ping, +pong or close frames. + +The following example sends three frames using a single `reply` +tuple. + +[source,erlang] +---- +websocket_info(hello_world, Req, State) -> + {reply, [ + {text, "Hello"}, + {text, <<"world!">>}, + {binary, <<0:8000>>} + ], Req, State}; +%% More websocket_info/3 clauses here... +---- + +Note that the payload for text and binary frames is of type +`iodata()`, meaning it can be either a `binary()` or an +`iolist()`. + +Sending a `close` frame will immediately initiate the closing +of the Websocket connection. Be aware that any additional +frames sent by the client or any Erlang messages waiting to +be received will not be processed. Also note that when replying +a list of frames that includes close, any frame found after the +close frame will not be sent. + +=== Ping and timeout + +The biggest performance improvement you can do when dealing +with a huge number of Websocket connections is to reduce the +number of timers that are started on the server. A common use +of timers when dealing with connections is for sending a ping +every once in a while. This should be done exclusively on the +client side. Indeed, a server handling one million Websocket +connections will perform a lot better when it doesn't have to +handle one million extra timers too! + +Cowboy will automatically respond to ping frames sent by the +client. It will still forward the frame to the handler for +informative purpose, but no further action is required. + +Cowboy can be configured to automatically close the Websocket +connection when no data arrives on the socket. It is highly +recommended to configure a timeout for it, as otherwise you +may end up with zombie "half-connected" sockets that may +leave the process alive forever. + +A good timeout value is 60 seconds. + +[source,erlang] +---- +init(Req, _Opts) -> + {cowboy_websocket, Req, #state{}, 60000}. +---- + +This value cannot be changed once it is set. It defaults to +`infinity`. + +=== Hibernate + +Most tuples returned from handler callbacks can include an +extra value `hibernate`. After doing any necessary operations +following the return of the callback, Cowboy will hibernate +the process. + +It is highly recommended to hibernate processes that do not +handle much traffic. It is a good idea to hibernate all +connections by default and investigate only when you start +noticing increased CPU usage. + +=== Supporting older browsers + +Unfortunately Websocket is a relatively recent technology, +which means that not all browsers support it. A library like +https://github.com/ninenines/bullet[Bullet] can be used to +emulate Websocket connections on older browsers. diff --git a/docs/en/cowboy/2.0/guide/ws_handlers/index.html b/docs/en/cowboy/2.0/guide/ws_handlers/index.html new file mode 100644 index 00000000..4bdd00d9 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/ws_handlers/index.html @@ -0,0 +1,339 @@ + + + + + + + + + + + + Nine Nines: Handling Websocket connections + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Handling Websocket connections

+ +

A special handler is required for handling Websocket connections. +Websocket handlers allow you to initialize the connection, +handle incoming frames from the socket, handle incoming Erlang +messages and then clean up on termination.

+

Websocket handlers essentially act as a bridge between the client +and the Erlang system. They will typically do little more than +socket communication and decoding/encoding of frames.

+
+

Initialization

+
+

First, the init/2 callback is called. This callback is common +to all handlers. To establish a Websocket connection, this function +must return a ws tuple.

+
+
+
init(Req, _Opts) ->
+        {cowboy_websocket, Req, #state{}}.
+

Upon receiving this tuple, Cowboy will switch to the code +that handles Websocket connections and perform the handshake +immediately.

+

If the sec-websocket-protocol header was sent with the request +for establishing a Websocket connection, then the Websocket +handler must select one of these subprotocol and send it +back to the client, otherwise the client might decide to close +the connection, assuming no correct subprotocol was found.

+
+
+
init(Req, _Opts) ->
+        case cowboy_req:parse_header(<<"sec-websocket-protocol">>, Req) of
+                undefined ->
+                        {ok, Req, #state{}};
+                Subprotocols ->
+                        case lists:keymember(<<"mychat2">>, 1, Subprotocols) of
+                                true ->
+                                        Req2 = cowboy_req:set_resp_header(<<"sec-websocket-protocol">>,
+                                                <<"mychat2">>, Req),
+                                        {ok, Req2, #state{}};
+                                false ->
+                                        {stop, Req, undefined}
+                        end
+        end.
+

It is not recommended to wait too long inside the init/2 +function. Any extra initialization may be done after returning by +sending yourself a message before doing anything. Any message sent +to self() from init/2 is guaranteed to arrive before +any frames from the client.

+

It is also very easy to ensure that this message arrives before +any message from other processes by sending it before registering +or enabling timers.

+
+
+
init(Req, _Opts) ->
+        self() ! post_init,
+        %% Register process here...
+        {cowboy_websocket, Req, #state{}}.
+
+websocket_info(post_init, Req, State) ->
+        %% Perform post_init initialization here...
+        {ok, Req, State}.
+
+
+
+

Handling frames from the client

+
+

Cowboy will call websocket_handle/3 whenever a text, binary, +ping or pong frame arrives from the client. Note that in the +case of ping and pong frames, no action is expected as Cowboy +automatically replies to ping frames.

+

The handler can decide to send frames to the socket, stop +or just continue without sending anything.

+

The following snippet echoes back any text frame received and +ignores all others.

+
+
+
websocket_handle(Frame = {text, _}, Req, State) ->
+        {reply, Frame, Req, State};
+websocket_handle(_Frame, Req, State) ->
+        {ok, Req, State}.
+
+
+
+

Handling Erlang messages

+
+

Cowboy will call websocket_info/3 whenever an Erlang message +arrives.

+

The handler can decide to send frames to the socket, stop +or just continue without sending anything.

+

The following snippet forwards any log message to the socket +and ignores all others.

+
+
+
websocket_info({log, Text}, Req, State) ->
+        {reply, {text, Text}, Req, State};
+websocket_info(_Info, Req, State) ->
+        {ok, Req, State}.
+
+
+
+

Sending frames to the socket

+
+

Cowboy allows sending either a single frame or a list of +frames to the socket, in which case the frames are sent +sequentially. Any frame can be sent: text, binary, ping, +pong or close frames.

+

The following example sends three frames using a single reply +tuple.

+
+
+
websocket_info(hello_world, Req, State) ->
+        {reply, [
+                {text, "Hello"},
+                {text, <<"world!">>},
+                {binary, <<0:8000>>}
+        ], Req, State};
+%% More websocket_info/3 clauses here...
+

Note that the payload for text and binary frames is of type +iodata(), meaning it can be either a binary() or an +iolist().

+

Sending a close frame will immediately initiate the closing +of the Websocket connection. Be aware that any additional +frames sent by the client or any Erlang messages waiting to +be received will not be processed. Also note that when replying +a list of frames that includes close, any frame found after the +close frame will not be sent.

+
+
+
+

Ping and timeout

+
+

The biggest performance improvement you can do when dealing +with a huge number of Websocket connections is to reduce the +number of timers that are started on the server. A common use +of timers when dealing with connections is for sending a ping +every once in a while. This should be done exclusively on the +client side. Indeed, a server handling one million Websocket +connections will perform a lot better when it doesn’t have to +handle one million extra timers too!

+

Cowboy will automatically respond to ping frames sent by the +client. It will still forward the frame to the handler for +informative purpose, but no further action is required.

+

Cowboy can be configured to automatically close the Websocket +connection when no data arrives on the socket. It is highly +recommended to configure a timeout for it, as otherwise you +may end up with zombie "half-connected" sockets that may +leave the process alive forever.

+

A good timeout value is 60 seconds.

+
+
+
init(Req, _Opts) ->
+        {cowboy_websocket, Req, #state{}, 60000}.
+

This value cannot be changed once it is set. It defaults to +infinity.

+
+
+
+

Hibernate

+
+

Most tuples returned from handler callbacks can include an +extra value hibernate. After doing any necessary operations +following the return of the callback, Cowboy will hibernate +the process.

+

It is highly recommended to hibernate processes that do not +handle much traffic. It is a good idea to hibernate all +connections by default and investigate only when you start +noticing increased CPU usage.

+
+
+
+

Supporting older browsers

+
+

Unfortunately Websocket is a relatively recent technology, +which means that not all browsers support it. A library like +Bullet can be used to +emulate Websocket connections on older browsers.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/guide/ws_protocol.asciidoc b/docs/en/cowboy/2.0/guide/ws_protocol.asciidoc new file mode 100644 index 00000000..67b2cdf2 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/ws_protocol.asciidoc @@ -0,0 +1,43 @@ +[[ws_protocol]] +== The Websocket protocol + +This chapter explains what Websocket is and why it is +a vital component of soft realtime Web applications. + +=== Description + +Websocket is an extension to HTTP that emulates plain TCP +connections between the client, typically a Web browser, +and the server. It uses the HTTP Upgrade mechanism to +establish the connection. + +Websocket connections are asynchronous, unlike HTTP. This +means that not only can the client send frames to the server +at any time, but the server can also send frames to the client +without the client initiating anything other than the +Websocket connection itself. This allows the server to push +data to the client directly. + +Websocket is an IETF standard. Cowboy supports the standard +and all drafts that were previously implemented by browsers, +excluding the initial flawed draft sometimes known as +"version 0". + +=== Implementation + +Cowboy implements Websocket as a protocol upgrade. Once the +upgrade is performed from the `init/2` callback, Cowboy +switches to Websocket. Please consult the next chapter for +more information on initiating and handling Websocket +connections. + +The implementation of Websocket in Cowboy is validated using +the Autobahn test suite, which is an extensive suite of tests +covering all aspects of the protocol. Cowboy passes the +suite with 100% success, including all optional tests. + +Cowboy's Websocket implementation also includes the +x-webkit-deflate-frame compression draft which is being used +by some browsers to reduce the size of data being transmitted. +Cowboy will automatically use compression as long as the +`compress` protocol option is set when starting the listener. diff --git a/docs/en/cowboy/2.0/guide/ws_protocol/index.html b/docs/en/cowboy/2.0/guide/ws_protocol/index.html new file mode 100644 index 00000000..70ba4917 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/ws_protocol/index.html @@ -0,0 +1,182 @@ + + + + + + + + + + + + Nine Nines: The Websocket protocol + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

The Websocket protocol

+ +

This chapter explains what Websocket is and why it is +a vital component of soft realtime Web applications.

+
+

Description

+
+

Websocket is an extension to HTTP that emulates plain TCP +connections between the client, typically a Web browser, +and the server. It uses the HTTP Upgrade mechanism to +establish the connection.

+

Websocket connections are asynchronous, unlike HTTP. This +means that not only can the client send frames to the server +at any time, but the server can also send frames to the client +without the client initiating anything other than the +Websocket connection itself. This allows the server to push +data to the client directly.

+

Websocket is an IETF standard. Cowboy supports the standard +and all drafts that were previously implemented by browsers, +excluding the initial flawed draft sometimes known as +"version 0".

+
+
+
+

Implementation

+
+

Cowboy implements Websocket as a protocol upgrade. Once the +upgrade is performed from the init/2 callback, Cowboy +switches to Websocket. Please consult the next chapter for +more information on initiating and handling Websocket +connections.

+

The implementation of Websocket in Cowboy is validated using +the Autobahn test suite, which is an extensive suite of tests +covering all aspects of the protocol. Cowboy passes the +suite with 100% success, including all optional tests.

+

Cowboy’s Websocket implementation also includes the +x-webkit-deflate-frame compression draft which is being used +by some browsers to reduce the size of data being transmitted. +Cowboy will automatically use compression as long as the +compress protocol option is set when starting the listener.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/index.html b/docs/en/cowboy/2.0/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/cowboy/2.0/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/cowboy/2.0/manual/cowboy/index.html b/docs/en/cowboy/2.0/manual/cowboy/index.html new file mode 100644 index 00000000..7c866e32 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy/index.html @@ -0,0 +1,328 @@ + + + + + + + + + + + + Nine Nines: cowboy(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy(3)

+ +
+

Name

+
+

cowboy - HTTP server

+
+
+
+

Description

+
+

The cowboy module provides convenience functions for +manipulating Ranch listeners.

+
+
+
+

Types

+
+
+

fields() = [Field]

+
+
+
Field = atom()
+        | {atom(), cowboy_constraints:constraint() | [cowboy_constraints:constraint()]}
+        | {atom(), cowboy_constraints:constraint() | [cowboy_constraints:constraint()], any()}]
+

Fields for match operations. Constraint(s) and default value are optional.

+
+
+

http_headers() = [{binary(), iodata()}]

+

HTTP headers as a list of key/values.

+
+
+

http_status() = non_neg_integer() | binary()

+

HTTP status.

+

A binary status can be used to set a custom message.

+
+
+

http_version() = 'HTTP/1.1' | 'HTTP/1.0'

+

HTTP version.

+
+
+

onresponse_fun() = fun((http_status(), http_headers(), iodata(), cowboy_req:req()) -> cowboy_req:req())

+

Fun called immediately before sending the response.

+

It can perform any operation on the Req object, including +reading the request body or replying. If a reply is sent, it +overrides the reply initially sent. The callback will not be +called again for the new reply.

+
+
+
+
+

Exports

+
+
+

start_http(Ref, NbAcceptors, TransOpts, ProtoOpts) → {ok, pid()}

+
+
+Ref = ranch:ref() +
+
+

+Listener name. +

+
+
+NbAcceptors = non_neg_integer() +
+
+

+Number of acceptor processes. +

+
+
+TransOpts = ranch_tcp:opts() +
+
+

+TCP transport options. +

+
+
+ProtoOpts = cowboy_protocol:opts() +
+
+

+HTTP protocol options. +

+
+
+

Start listening for HTTP connections. Returns the pid for this +listener’s supervisor.

+
+
+

start_https(Ref, NbAcceptors, TransOpts, ProtoOpts) → {ok, pid()}

+
+
+Ref = ranch:ref() +
+
+

+Listener name. +

+
+
+NbAcceptors = non_neg_integer() +
+
+

+Number of acceptor processes. +

+
+
+TransOpts = ranch_ssl:opts() +
+
+

+SSL transport options. +

+
+
+ProtoOpts = cowboy_protocol:opts() +
+
+

+HTTP protocol options. +

+
+
+

Start listening for HTTPS connections. Returns the pid for this +listener’s supervisor.

+
+
+

stop_listener(Ref) → ok | {error, not_found}

+
+
+Ref = ranch:ref() +
+
+

+Listener name. +

+
+
+

Stop a previously started listener.

+
+
+

set_env(Ref, Name, Value) → ok

+
+
+Ref = ranch:ref() +
+
+

+Listener name. +

+
+
+Name = atom() +
+
+

+Name of environment value. +

+
+
+Value = any() +
+
+

+Environment value. +

+
+
+

Set or update an environment value for an already running listener. +This will take effect on all subsequent connections.

+
+
+
+
+

See also

+
+

The Ranch guide +provides detailed information about how listeners work.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_app/index.html b/docs/en/cowboy/2.0/manual/cowboy_app/index.html new file mode 100644 index 00000000..eaba7602 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_app/index.html @@ -0,0 +1,171 @@ + + + + + + + + + + + + Nine Nines: cowboy(7) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy(7)

+ +
+

Name

+
+

cowboy - Small, fast, modular HTTP server.

+
+
+
+

Dependencies

+
+

The cowboy application uses the Erlang applications ranch +for listening and accepting TCP connections, crypto for +establishing Websocket connections, and cowlib for parsing and +building messages for Web protocols. These dependencies must +be loaded for the cowboy application to work. In an embedded +environment this means that they need to be started with the +application:start/{1,2} function before the cowboy +application is started.

+

The cowboy application also uses the Erlang applications +asn1, public_key and ssl when listening for HTTPS connections. +These are started automatically if they weren’t before.

+
+
+
+

Environment

+
+

The cowboy application does not define any application +environment configuration parameters.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_handler/index.html b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html new file mode 100644 index 00000000..5954d21f --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html @@ -0,0 +1,365 @@ + + + + + + + + + + + + Nine Nines: cowboy_handler(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_handler(3)

+ +
+

Name

+
+

cowboy_handler - handler middleware and behaviour

+
+
+
+

Description

+
+

The cowboy_handler middleware executes the handler passed +through the environment values handler and handler_opts, +and adds the result of this execution to the environment as +the value result, indicating that the request has been +handled and received a response.

+

Environment input:

+
+
+handler = module() +
+
+

+Handler to be executed. +

+
+
+handler_opts = any() +
+
+

+Options to be passed to the handler. +

+
+
+

Environment output:

+
+
+result = ok +
+
+

+Result of the request. +

+
+
+

This module also defines the cowboy_handler behaviour that +defines the basic interface for handlers. All Cowboy handlers +implement at least the init/2 callback, and may implement +the terminate/3 callback optionally.

+
+
+
+

Terminate reasons

+
+

The following values may be received as the terminate reason +in the optional terminate/3 callback. Different handler types +may define additional terminate reasons.

+
+
+normal +
+
+

+ The connection was closed normally. +

+
+
+{crash, Class, Reason} +
+
+

+ A crash occurred in the handler. Class and Reason can be + used to obtain more information about the crash. The function + erlang:get_stacktrace/0 can also be called to obtain the + stacktrace of the process when the crash occurred. +

+
+
+
+
+
+

Callbacks

+
+
+

init(Req, Opts) → {ok, Req, State} | {Module, Req, State} | {Module, Req, State, hibernate | Timeout} | {Module, Req, State, Timeout, hibernate}

+
+
+Req = cowboy_req:req() +
+
+

+The Req object. +

+
+
+Opts = any() +
+
+

+Handler options. +

+
+
+State = any() +
+
+

+Handler state. +

+
+
+Module = module() +
+
+

+Module of the sub-protocol to use. +

+
+
+Timeout = timeout() +
+
+

+Timeout passed to the sub-protocol, when applicable. +

+
+
+

Process the request.

+

This function can be used to switch to an alternate handler +type by returning the name of the module to be used, along +with a few options.

+

For basic handlers this is the function where the response +should be sent. If no response is sent, Cowboy will ensure +that a 204 No Content response is sent.

+

A crash in this callback will result in terminate/3 being +called if it is defined, with the State argument set to +the value of Opts originally given to the init/2 callback.

+
+
+

terminate(Reason, Req, State) → ok

+
+
+Reason = any() +
+
+

+Reason for termination. +

+
+
+Req = cowboy_req:req() +
+
+

+The Req object. +

+
+
+State = any() +
+
+

+Handler state. +

+
+
+

Perform any necessary cleanup of the state.

+

This callback should release any resource currently in use, +clear any active timer and reset the process to its original +state, as it might be reused for future requests sent on the +same connection. Typical plain HTTP handlers rarely need to +use it.

+

A crash in this callback or an invalid return value will +result in the closing of the connection and the termination +of the process.

+
+
+
+
+

Exports

+
+
+

terminate(Reason, Req, State, Handler) → ok

+
+
+Reason = any() +
+
+

+Reason for termination. +

+
+
+Req = cowboy_req:req() +
+
+

+The Req object. +

+
+
+State = any() +
+
+

+Handler state. +

+
+
+Handler = module() +
+
+

+Handler module. +

+
+
+

Call the optional terminate/3 callback if it exists.

+

This function should always be called at the end of the execution +of a handler, to give it a chance to clean up or perform +miscellaneous operations.

+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_loop/index.html b/docs/en/cowboy/2.0/manual/cowboy_loop/index.html new file mode 100644 index 00000000..968131fa --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_loop/index.html @@ -0,0 +1,289 @@ + + + + + + + + + + + + Nine Nines: cowboy_loop(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_loop(3)

+ +
+

Name

+
+

cowboy_loop - loop handlers

+
+
+
+

Description

+
+

The cowboy_loop module implements a handler interface for +long running HTTP connections. It is the recommended interface +for long polling and server-sent events, amongst others.

+

This module is a sub protocol that defines three callbacks to +be implemented by handlers. The init/2 and terminate/3 +callbacks are common to all handler types and are documented +in the manual for the cowboy_handler module.

+

The info/3 callback is specific to loop handlers and will be +called as many times as necessary until a reply is sent.

+

It is highly recommended to return a timeout value from the +init/2 callback to ensure that the process is terminated +when no data has been received during that timespan. The +default timeout is infinity, which should only be used if +you have alternate means of ending inactive connections.

+
+
+
+

Terminate reasons

+
+

The following values may be received as the terminate reason +in the optional terminate/3 callback.

+
+
+normal +
+
+

+ The connection was closed normally before switching to the + loop sub protocol. This typically happens if an ok tuple is + returned from the init/2 callback. +

+
+
+stop +
+
+

+ The handler requested to close the connection by returning + a stop tuple. +

+
+
+timeout +
+
+

+ The connection has been closed due to inactivity. The timeout + value can be configured from init/2. The response sent when + this happens is a 204 No Content. +

+
+
+{crash, Class, Reason} +
+
+

+ A crash occurred in the handler. Class and Reason can be + used to obtain more information about the crash. The function + erlang:get_stacktrace/0 can also be called to obtain the + stacktrace of the process when the crash occurred. +

+
+
+{error, overflow} +
+
+

+ The connection is being closed and the process terminated + because the buffer Cowboy uses to keep data sent by the + client has reached its maximum. The buffer size can be + configured through the environment value loop_max_buffer + and defaults to 5000 bytes. +
+ If the long running request comes with a body it is recommended + to process this body before switching to the loop sub protocol. +

+
+
+{error, closed} +
+
+

+ The socket has been closed brutally without a close frame being + received first. +

+
+
+{error, Reason} +
+
+

+ A socket error ocurred. +

+
+
+
+
+
+

Callbacks

+
+
+

info(Info, Req, State) → {ok, Req, State} | {ok, Req, State, hibernate} | {stop, Req, State}

+
+
+Info = any() +
+
+

+Message received by the process. +

+
+
+Req = cowboy_req:req() +
+
+

+The Req object. +

+
+
+State = any() +
+
+

+Handler state. +

+
+
+

Handle the Erlang message received.

+

This function will be called every time an Erlang message +has been received. The message can be any Erlang term.

+

The stop return value can be used to stop the receive loop, +typically because a response has been sent.

+

The hibernate option will hibernate the process until +it receives another message.

+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html b/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html new file mode 100644 index 00000000..64fce84c --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html @@ -0,0 +1,230 @@ + + + + + + + + + + + + Nine Nines: cowboy_middleware(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_middleware(3)

+ +
+

Name

+
+

cowboy_middleware - behaviour for middlewares

+
+
+
+

Description

+
+

The cowboy_middleware behaviour defines the interface used +by Cowboy middleware modules.

+

Middlewares process the request sequentially in the order they +are configured.

+
+
+
+

Types

+
+
+

env() = [{atom(), any()}]

+

The environment variable.

+

One is created for every request. It is passed to each +middleware module executed and subsequently returned, +optionally with its contents modified.

+
+
+
+
+

Callbacks

+
+
+

execute(Req, Env) → {ok, Req, Env} | {suspend, Module, Function, Args} | {stop, Req}

+
+
+Req = cowboy_req:req() +
+
+

+The Req object. +

+
+
+Env = env() +
+
+

+The request environment. +

+
+
+Module = module() +
+
+

+MFA to call when resuming the process. +

+
+
+Function = atom() +
+
+

+MFA to call when resuming the process. +

+
+
+Args = [any()] +
+
+

+MFA to call when resuming the process. +

+
+
+

Execute the middleware.

+

The ok return value indicates that everything went well +and that Cowboy should continue processing the request. A +response may or may not have been sent.

+

The suspend return value will hibernate the process until +an Erlang message is received. Note that when resuming, any +previous stacktrace information will be gone.

+

The stop return value stops Cowboy from doing any further +processing of the request, even if there are middlewares +that haven’t been executed yet. The connection may be left +open to receive more requests from the client.

+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_protocol/index.html b/docs/en/cowboy/2.0/manual/cowboy_protocol/index.html new file mode 100644 index 00000000..4fdda0b9 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_protocol/index.html @@ -0,0 +1,279 @@ + + + + + + + + + + + + Nine Nines: cowboy_protocol(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_protocol(3)

+ +
+

Name

+
+

cowboy_protocol - HTTP protocol

+
+
+
+

Description

+
+

The cowboy_protocol module implements HTTP/1.1 and HTTP/1.0 +as a Ranch protocol.

+
+
+
+

Types

+
+
+

opts() = [Option]

+
+
+
Option = {compress, boolean()}
+        | {env, cowboy_middleware:env()}
+        | {max_empty_lines, non_neg_integer()}
+        | {max_header_name_length, non_neg_integer()}
+        | {max_header_value_length, non_neg_integer()}
+        | {max_headers, non_neg_integer()}
+        | {max_keepalive, non_neg_integer()}
+        | {max_request_line_length, non_neg_integer()}
+        | {middlewares, [module()]}
+        | {onresponse, cowboy:onresponse_fun()}
+        | {timeout, timeout()}
+

Configuration for the HTTP protocol handler.

+

This configuration is passed to Cowboy when starting listeners +using cowboy:start_http/4 or cowboy:start_https/4 functions.

+

It can be updated without restarting listeners using the +Ranch functions ranch:get_protocol_options/1 and +ranch:set_protocol_options/2.

+
+
+

Option descriptions

+

The default value is given next to the option name.

+
+
+compress (false) +
+
+

+ When enabled, Cowboy will attempt to compress the response body. +

+
+
+env ([{listener, Ref}]) +
+
+

+ Initial middleware environment. +

+
+
+max_empty_lines (5) +
+
+

+ Maximum number of empty lines before a request. +

+
+
+max_header_name_length (64) +
+
+

+ Maximum length of header names. +

+
+
+max_header_value_length (4096) +
+
+

+ Maximum length of header values. +

+
+
+max_headers (100) +
+
+

+ Maximum number of headers allowed per request. +

+
+
+max_keepalive (100) +
+
+

+ Maximum number of requests allowed per connection. +

+
+
+max_request_line_length (4096) +
+
+

+ Maximum length of the request line. +

+
+
+middlewares ([cowboy_router, cowboy_handler]) +
+
+

+ List of middlewares to execute for every requests. +

+
+
+onresponse (undefined) +
+
+

+ Fun called every time a response is sent. +

+
+
+timeout (5000) +
+
+

+ Time in ms with no requests before Cowboy closes the connection. +

+
+
+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_req/index.html b/docs/en/cowboy/2.0/manual/cowboy_req/index.html new file mode 100644 index 00000000..99c4915f --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_req/index.html @@ -0,0 +1,1423 @@ + + + + + + + + + + + + Nine Nines: cowboy_req(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req(3)

+ +
+

Name

+
+

cowboy_req - HTTP request and response

+
+
+
+

Description

+
+

The cowboy_req module provides functions to access, manipulate +and respond to requests.

+

The functions in this module follow patterns for their return types, +based on the kind of function.

+
    +
  • +

    +access: Value +

    +
    • +
  • +

    +action: ok | {Result, Req} | {Result, Value, Req} +

    +
    • +
  • +

    +modification: Req +

    +
    • +
  • +

    +question: boolean() +

    +
    • +
+

Whenever Req is returned, you must use this returned value and +ignore any previous you may have had. This value contains various +values which are necessary for Cowboy to keep track of the request +and response states.

+

All functions which perform an action should only be called once. +This includes reading the request body or replying. Cowboy will +throw an error on the second call when it detects suspicious behavior.

+

It is highly discouraged to pass the Req object to another process. +Doing so and calling cowboy_req functions from it leads to +undefined behavior.

+
+
+
+

Types

+
+
+

body_opts() = [Option]

+
+
+
Option = {continue, boolean()}
+        | {length, non_neg_integer()}
+        | {read_length, non_neg_integer()}
+        | {read_timeout, timeout()}
+        | {transfer_decode, transfer_decode_fun(), any()}
+        | {content_decode, content_decode_fun()}
+

Request body reading options.

+
+
+

cookie_opts() = [Option]

+
+
+
Option = {max_age, non_neg_integer()}
+        | {domain, binary()}
+        | {path, binary()}
+        | {secure, boolean()}
+        | {http_only, boolean()}
+

Cookie options.

+
+
+

req() - opaque to the user

+

The Req object.

+

All functions in this module receive a Req as argument, +and some of them return a new object labelled Req2 in +the function descriptions below.

+
+
+
+
+

Request related exports

+
+
+

binding(Name, Req) → binding(Name, Req, undefined)

+

Alias of cowboy_req:binding/3.

+
+
+

binding(Name, Req, Default) → Value

+
+
+Name = atom() +
+
+

+Binding name. +

+
+
+Default = any() +
+
+

+Default value. +

+
+
+Value = any() | Default +
+
+

+Binding value. +

+
+
+

Return the value for the given binding.

+

By default the value is a binary, however constraints may change +the type of this value (for example automatically converting +numbers to integer).

+
+
+

bindings(Req) → [{Name, Value}]

+
+
+Name = atom() +
+
+

+Binding name. +

+
+
+Value = any() +
+
+

+Binding value. +

+
+
+

Return all bindings.

+

By default the value is a binary, however constraints may change +the type of this value (for example automatically converting +numbers to integer).

+
+
+

header(Name, Req) → header(Name, Req, undefined)

+

Alias of cowboy_req:header/3.

+
+
+

header(Name, Req, Default) → Value

+
+
+Name = binary() +
+
+

+Request header name. +

+
+
+Default = any() +
+
+

+Default value. +

+
+
+Value = binary() | Default +
+
+

+Request header value. +

+
+
+

Return the value for the given header.

+

While header names are case insensitive, this function expects +the name to be a lowercase binary.

+
+
+

headers(Req) → Headers

+
+
+Headers = cowboy:http_headers() +
+
+

+Request headers. +

+
+
+

Return all headers.

+
+
+

host(Req) → Host

+
+
+Host = binary() +
+
+

+Requested host. +

+
+
+

Return the requested host.

+
+
+

host_info(Req) → HostInfo

+
+
+HostInfo = cowboy_router:tokens() | undefined +
+
+

+Extra tokens for the host. +

+
+
+

Return the extra tokens from matching against ... during routing.

+
+
+

host_url(Req) → HostURL

+
+
+HostURL = binary() | undefined +
+
+

+Requested URL, without the path component. +

+
+
+

Return the requested URL excluding the path component.

+

This function will always return undefined until the +cowboy_router middleware has been executed.

+
+
+

match_cookies(Fields, Req) → Map

+
+
+Fields = cowboy:fields() +
+
+

+Cookie fields match rules. +

+
+
+Map = map() +
+
+

+Cookie fields matched. +

+
+
+

Match cookies against the given fields.

+

Cowboy will only return the cookie values specified in the +fields list, and ignore all others. Fields can be either +the name of the cookie requested; the name along with a +list of constraints; or the name, a list of constraints +and a default value in case the cookie is missing.

+

This function will crash if the cookie is missing and no +default value is provided. This function will also crash +if a constraint fails.

+

The name of the cookie must be provided as an atom. The +key of the returned map will be that atom. The value may +be converted through the use of constraints, making this +function able to extract, validate and convert values all +in one step.

+
+
+

match_qs(Fields, Req) → Map

+
+
+Fields = cowboy:fields() +
+
+

+Query string fields match rules. +

+
+
+Map = map() +
+
+

+Query string fields matched. +

+
+
+

Match the query string against the given fields.

+

Cowboy will only return the query string values specified +in the fields list, and ignore all others. Fields can be +either the key requested; the key along with a list of +constraints; or the key, a list of constraints and a +default value in case the key is missing.

+

This function will crash if the key is missing and no +default value is provided. This function will also crash +if a constraint fails.

+

The key must be provided as an atom. The key of the +returned map will be that atom. The value may be converted +through the use of constraints, making this function able +to extract, validate and convert values all in one step.

+
+
+

meta(Name, Req) → meta(Name, Req, undefined)

+

Alias for cowboy_req:meta/3.

+
+
+

meta(Name, Req, Default) → Value

+
+
+Name = atom() +
+
+

+Metadata name. +

+
+
+Default = any() +
+
+

+Default value. +

+
+
+Value = any() +
+
+

+Metadata value. +

+
+
+

Return metadata about the request.

+
+
+

method(Req) → Method

+
+
+Method = binary() +
+
+

+Request method. +

+
+
+

Return the method.

+

Methods are case sensitive. Standard methods are always uppercase.

+
+
+

parse_cookies(Req) → [{Name, Value}]

+
+
+Name = binary() +
+
+

+Cookie name. +

+
+
+Value = binary() +
+
+

+Cookie value. +

+
+
+

Parse and return all cookies.

+

Cookie names are case sensitive.

+
+
+

parse_header(Name, Req) → see below

+

Alias of cowboy_req:parse_header/3.

+

The parse_header/2 function will call parser_header/3 with a +different default value depending on the header being parsed. The +following table summarizes the default values used.

+
+ +++ + + + + + + + + + + + + + + + + + + + + + + + +
Header name Header value

content-length

0

cookie

[]

transfer-encoding

[<<"identity">>]

Any other header

undefined

+
+
+
+

parse_header(Name, Req, Default) → ParsedValue | Default

+
+
+Name = binary() +
+
+

+Request header name. +

+
+
+Default = any() +
+
+

+Default value. +

+
+
+ParsedValue - see below +
+
+

+Parsed request header value. +

+
+
+

Parse the given header.

+

While header names are case insensitive, this function expects +the name to be a lowercase binary.

+

The parsed value differs depending on the header being parsed. The +following table summarizes the different types returned.

+
+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Header name Type of parsed header value

accept

[{{Type, SubType, Params}, Quality, AcceptExt}]

accept-charset

[{Charset, Quality}]

accept-encoding

[{Encoding, Quality}]

accept-language

[{LanguageTag, Quality}]

authorization

{AuthType, Credentials}

content-length

non_neg_integer()

content-type

{Type, SubType, ContentTypeParams}

cookie

[{binary(), binary()}]

expect

[Expect | {Expect, ExpectValue, Params}]

if-match

'*' | [{weak | strong, OpaqueTag}]

if-modified-since

calendar:datetime()

if-none-match

'*' | [{weak | strong, OpaqueTag}]

if-unmodified-since

calendar:datetime()

range

{Unit, [Range]}

sec-websocket-protocol

[binary()]

transfer-encoding

[binary()]

upgrade

[binary()]

x-forwarded-for

[binary()]

+
+

Types for the above table:

+
    +
  • +

    +Type = SubType = Charset = Encoding = LanguageTag = binary() +

    +
    • +
  • +

    +AuthType = Expect = OpaqueTag = Unit = binary() +

    +
    • +
  • +

    +Params = ContentTypeParams = [{binary(), binary()}] +

    +
    • +
  • +

    +Quality = 0..1000 +

    +
    • +
  • +

    +AcceptExt = [{binary(), binary()} | binary()] +

    +
    • +
  • +

    +Credentials - see below +

    +
    • +
  • +

    +Range = {non_neg_integer(), non_neg_integer() | infinity} | neg_integer() +

    +
    • +
+

The cookie names and values, the values of the sec-websocket-protocol +and x-forwarded-for headers, the values in AcceptExt and Params, +the authorization Credentials, the ExpectValue and OpaqueTag +are case sensitive. All values in ContentTypeParams are case sensitive +except the value of the charset parameter, which is case insensitive. +All other values are case insensitive and will be returned as lowercase.

+

The headers accept, accept-encoding and cookie headers can return +an empty list. Some other headers are expected to have a value if provided +and may crash if the value is missing.

+

The authorization header parsing code currently only supports basic +HTTP authentication. The Credentials type is thus {Username, Password} +with Username and Password being binary().

+

The range header value Range can take three forms:

+
    +
  • +

    +{From, To}: from From to To units +

    +
    • +
  • +

    +{From, infinity}: everything after From units +

    +
    • +
  • +

    +-Final: the final Final units +

    +
    • +
+

An undefined tuple will be returned if Cowboy doesn’t know how +to parse the requested header.

+
+
+

parse_qs(Req) → [{Name, Value}]

+
+
+Name = binary() +
+
+

+Query string field name. +

+
+
+Value = binary() | true +
+
+

+Query string field value. +

+
+
+

Return the request’s query string as a list of tuples.

+

The atom true is returned for keys which have no value. +Keys with no value are different from keys with an empty +value in that they do not have a = indicating the presence +of a value.

+
+
+

path(Req) → Path

+
+
+Path = binary() +
+
+

+Requested path. +

+
+
+

Return the requested path.

+
+
+

path_info(Req) → PathInfo

+
+
+PathInfo = cowboy_router:tokens() | undefined +
+
+

+Extra tokens for the path. +

+
+
+

Return the extra tokens from matching against ... during routing.

+
+
+

peer(Req) → Peer

+
+
+
+
+

+Peer IP address and port number. +

+
+
+

Return the client’s IP address and port number.

+
+
+

port(Req) → Port

+
+
+Port = inet:port_number() +
+
+

+Requested port number. +

+
+
+

Return the request’s port.

+

The port returned by this function is obtained by parsing +the host header. It may be different than the actual port +the client used to connect to the Cowboy server.

+
+
+

qs(Req) → QueryString

+
+
+QueryString = binary() +
+
+

+Unprocessed query string. +

+
+
+

Return the request’s query string.

+
+
+

set_meta(Name, Value, Req) → Req2

+
+
+Name = atom() +
+
+

+Metadata name. +

+
+
+Value = any() +
+
+

+Metadata value. +

+
+
+

Set metadata about the request.

+

An existing value will be overwritten.

+
+
+

url(Req) → URL

+
+
+URL = binary() | undefined +
+
+

+Requested URL. +

+
+
+

Return the requested URL.

+

This function will always return undefined until the +cowboy_router middleware has been executed.

+
+
+

version(Req) → Version

+
+
+Version = cowboy:http_version() +
+
+

+Client’s advertised HTTP version. +

+
+
+

Return the HTTP version used for this request.

+
+
+
+
+

Request body related exports

+
+
+

body(Req) → body(Req, [])

+

Alias of cowboy_req:body/2.

+
+
+

body(Req, Opts) → {ok, Data, Req2} | {more, Data, Req2}

+
+
+Opts = [body_opt()] +
+
+

+Request body reading options. +

+
+
+Data = binary() +
+
+

+Data read from the body. +

+
+
+

Read the request body.

+

This function will read a chunk of the request body. If there is +more data to be read after this function call, then a more tuple +is returned. Otherwise an ok tuple is returned.

+

Cowboy will automatically send a 100 Continue reply if +required. If this behavior is not desirable, it can be disabled +by setting the continue option to false.

+

Cowboy will by default attempt to read up to 8MB of the body, +but in chunks of 1MB. It will use a timeout of 15s per chunk. +All these values can be changed using the length, read_length +and read_timeout options respectively. Note that the size +of the data may not be the same as requested as the decoding +functions may grow or shrink it, and Cowboy makes not attempt +at returning an exact amount.

+

Cowboy will properly handle chunked transfer-encoding by +default. If any other transfer-encoding or content-encoding +has been used for the request, custom decoding functions +can be used. The content_decode and transfer_decode +options allow setting the decode functions manually.

+

After the body has been streamed fully, Cowboy will remove +the transfer-encoding header from the Req object, and add +the content-length header if it wasn’t already there.

+

This function can only be called once. Cowboy will not cache +the result of this call.

+
+
+

body_length(Req) → Length

+
+
+Length = non_neg_integer() | undefined +
+
+

+Length of the request body. +

+
+
+

Return the length of the request body.

+

The length will only be returned if the request does not +use any transfer-encoding and if the content-length header +is present.

+
+
+

body_qs(Req) → body_qs(Req, [{length, 64000}, {read_length, 64000}, {read_timeout, 5000}])

+

Alias of cowboy_req:body_qs/2.

+
+
+

body_qs(Req, Opts) → {ok, [{Name, Value}], Req2} | {badlength, Req2}

+
+
+Opts = [body_opt()] +
+
+

+Request body reading options. +

+
+
+Name = binary() +
+
+

+Field name. +

+
+
+Value = binary() | true +
+
+

+Field value. +

+
+
+

Return the request body as a list of tuples.

+

This function will parse the body assuming the content-type +application/x-www-form-urlencoded, commonly used for the +query string.

+

This function calls body/2 for reading the body, with the +same options it received. By default it will attempt to read +a body of 64KB in one chunk, with a timeout of 5s. If the +body is larger then a badlength tuple is returned.

+

This function can only be called once. Cowboy will not cache +the result of this call.

+
+
+

has_body(Req) → boolean()

+

Return whether the request has a body.

+
+
+

part(Req) → part(Req, [{length, 64000}, {read_length, 64000}, {read_timeout, 5000}])

+

Alias of cowboy_req:part/2.

+
+
+

part(Req, Opts) → {ok, Headers, Req2} | {done, Req2}

+
+
+Opts = [body_opt()] +
+
+

+Request body reading options. +

+
+
+Headers = cow_multipart:headers() +
+
+

+Part’s headers. +

+
+
+

Read the headers for the next part of the multipart message.

+

Cowboy will skip any data remaining until the beginning of +the next part. This includes the preamble to the multipart +message but also the body of a previous part if it hasn’t +been read. Both are skipped automatically when calling this +function.

+

The headers returned are MIME headers, NOT HTTP headers. +They can be parsed using the functions from the cow_multipart +module. In addition, the cow_multipart:form_data/1 function +can be used to quickly figure out multipart/form-data messages. +It takes the list of headers and returns whether this part is +a simple form field or a file being uploaded.

+

Note that once a part has been read, or skipped, it cannot +be read again.

+

This function calls body/2 for reading the body, with the +same options it received. By default it will only read chunks +of 64KB with a timeout of 5s. This is tailored for reading +part headers, not for skipping the previous part’s body. +You might want to consider skipping large parts manually.

+
+
+

part_body(Req) → part_body(Req, [])

+

Alias of cowboy_req:part_body/2.

+
+
+

part_body(Req, Opts) → {ok, Data, Req2} | {more, Data, Req2}

+
+
+Opts = [body_opt()] +
+
+

+Request body reading options. +

+
+
+Data = binary() +
+
+

+Part’s body. +

+
+
+

Read the body of the current part of the multipart message.

+

This function calls body/2 for reading the body, with the +same options it received. It uses the same defaults.

+

If there are more data to be read from the socket for this +part, the function will return what it could read inside a +more tuple. Otherwise, it will return an ok tuple.

+

Calling this function again after receiving a more tuple +will return another chunk of body. The last chunk will be +returned inside an ok tuple.

+

Note that once the body has been read, fully or partially, +it cannot be read again.

+
+
+
+
+

Response related exports

+
+
+

chunk(Data, Req) → ok

+
+
+Data = iodata() +
+
+

+Chunk data to be sent. +

+
+
+

Send a chunk of data.

+

This function should be called as many times as needed +to send data chunks after calling chunked_reply/{2,3}.

+

When the method is HEAD, no data will actually be sent.

+

If the request uses HTTP/1.0, the data is sent directly +without wrapping it in an HTTP/1.1 chunk, providing +compatibility with older clients.

+
+
+

chunked_reply(StatusCode, Req) → chunked_reply(StatusCode, [], Req)

+

Alias of cowboy_req:chunked_reply/3.

+
+
+

chunked_reply(StatusCode, Headers, Req) → Req2

+
+
+StatusCode = cowboy:http_status() +
+
+

+Response status code. +

+
+
+Headers = cowboy:http_headers() +
+
+

+Response headers. +

+
+
+

Send a response using chunked transfer-encoding.

+

This function effectively sends the response status line +and headers to the client.

+

This function will not send any body set previously. After +this call the handler must use the chunk/2 function +repeatedly to send the body in as many chunks as needed.

+

If the request uses HTTP/1.0, the data is sent directly +without wrapping it in an HTTP/1.1 chunk, providing +compatibility with older clients.

+

This function can only be called once, with the exception +of overriding the response in the onresponse hook.

+
+
+

continue(Req) → ok

+

Send a 100 Continue intermediate reply.

+

This reply is required before the client starts sending the +body when the request contains the expect header with the +100-continue value.

+

Cowboy will send this automatically when required. However +you may want to do it manually by disabling this behavior +with the continue body option and then calling this +function.

+
+
+

delete_resp_header(Name, Req) → Req2

+
+
+Name = binary() +
+
+

+Response header name. +

+
+
+

Delete the given response header.

+

While header names are case insensitive, this function expects +the name to be a lowercase binary.

+
+
+

has_resp_body(Req) → boolean()

+

Return whether a response body has been set.

+

This function will return false if a response body has +been set with a length of 0.

+
+
+

has_resp_header(Name, Req) → boolean()

+
+
+Name = binary() +
+
+

+Response header name. +

+
+
+

Return whether the given response header has been set.

+

While header names are case insensitive, this function expects +the name to be a lowercase binary.

+
+
+

reply(StatusCode, Req) → reply(StatusCode, [], Req)

+

Alias of cowboy_req:reply/3.

+
+
+

reply(StatusCode, Headers, Req) - see below

+

Alias of cowboy_req:reply/4, with caveats.

+
+
+

reply(StatusCode, Headers, Body, Req) → Req2

+
+
+StatusCode = cowboy:http_status() +
+
+

+Response status code. +

+
+
+Headers = cowboy:http_headers() +
+
+

+Response headers. +

+
+
+Body = iodata() +
+
+

+Response body. +

+
+
+

Send a response.

+

This function effectively sends the response status line, +headers and body to the client, in a single send function +call.

+

The reply/2 and reply/3 functions will send the body +set previously, if any. The reply/4 function overrides +any body set previously and sends Body instead.

+

If a body function was set, and reply/2 or reply/3 was +used, it will be called before returning.

+

No more data can be sent to the client after this function +returns.

+

This function can only be called once, with the exception +of overriding the response in the onresponse hook.

+
+
+

set_resp_body(Body, Req) → Req2

+
+
+Body = iodata() +
+
+

+Response body. +

+
+
+

Set a response body.

+

This body will not be sent if chunked_reply/{2,3} or +reply/4 is used, as they override it.

+
+
+

set_resp_body_fun(Fun, Req) → Req2

+

Alias of cowboy_req:set_resp_body_fun/3.

+
+
+

set_resp_body_fun(Length, Fun, Req) → Req2

+
+
+Fun = fun((Socket, Transport) → ok) +
+
+

+Fun that will send the response body. +

+
+
+Socket = inet:socket() +
+
+

+Socket for this connection. +

+
+
+Transport = module() +
+
+

+Transport module for this socket. +

+
+
+Length = non_neg_integer() +
+
+

+Length of the response body. +

+
+
+

Set a fun for sending the response body.

+

If a Length is provided, it will be sent in the +content-length header in the response. It is recommended +to set the length if it can be known in advance. Otherwise, +the transfer-encoding header will be set to identity.

+

This function will only be called if the response is sent +using the reply/2 or reply/3 function.

+

The fun will receive the Ranch Socket and Transport as +arguments. Only send and sendfile operations are supported.

+
+
+

set_resp_body_fun(chunked, Fun, Req) → Req2

+
+
+Fun = fun((ChunkFun) → ok) +
+
+

+Fun that will send the response body. +

+
+
+ChunkFun = funiodata( → ok) +
+
+

+Fun to call for every chunk to be sent. +

+
+
+

Set a fun for sending the response body using chunked transfer-encoding.

+

This function will only be called if the response is sent +using the reply/2 or reply/3 function.

+

The fun will receive another fun as argument. This fun is to +be used to send chunks in a similar way to the chunk/2 function, +except the fun only takes one argument, the data to be sent in +the chunk.

+
+
+

set_resp_cookie(Name, Value, Opts, Req) → Req2

+
+
+Name = iodata() +
+
+

+Cookie name. +

+
+
+Value = iodata() +
+
+

+Cookie value. +

+
+
+Opts = cookie_opts() +
+
+

+Cookie options. +

+
+
+

Set a cookie in the response.

+

Cookie names are case sensitive.

+
+
+

set_resp_header(Name, Value, Req) → Req2

+
+
+Name = binary() +
+
+

+Response header name. +

+
+
+Value = iodata() +
+
+

+Response header value. +

+
+
+

Set a response header.

+

You should use set_resp_cookie/4 instead of this function +to set cookies.

+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_rest/index.html b/docs/en/cowboy/2.0/manual/cowboy_rest/index.html new file mode 100644 index 00000000..7369592c --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_rest/index.html @@ -0,0 +1,508 @@ + + + + + + + + + + + + Nine Nines: cowboy_rest(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_rest(3)

+ +
+

Name

+
+

cowboy_rest - REST handlers

+
+
+
+

Description

+
+

The cowboy_rest module implements REST semantics on top of +the HTTP protocol.

+

This module is a sub protocol that defines many callbacks +be implemented by handlers. The init/2 and terminate/3 +callbacks are common to all handler types and are documented +in the manual for the cowboy_handler module.

+

All other callbacks are optional, though some may become +required depending on the return value of previous callbacks.

+
+
+
+

Meta values

+
+
+
+charset = binary() +
+
+

+ Negotiated charset. +
+ This value may not be defined if no charset was negotiated. +

+
+
+language = binary() +
+
+

+ Negotiated language. +
+ This value may not be defined if no language was negotiated. +

+
+
+media_type = {binary(), binary(), * | [{binary(), binary()}]} +
+
+

+ Negotiated media-type. +
+ The media-type is the content-type, excluding the charset. +
+ This value is always defined after the call to + content_types_provided/2. +

+
+
+
+
+
+

Terminate reasons

+
+

The following values may be received as the terminate reason +in the optional terminate/3 callback.

+
+
+normal +
+
+

+ The connection was closed normally. +

+
+
+{crash, Class, Reason} +
+
+

+ A crash occurred in the handler. Class and Reason can be + used to obtain more information about the crash. The function + erlang:get_stacktrace/0 can also be called to obtain the + stacktrace of the process when the crash occurred. +

+
+
+
+
+
+

Callbacks

+
+
+

Callback(Req, State) → {Value, Req, State} | {stop, Req, State}

+
+
+Callback +
+
+

+One of the REST callbacks described below. +

+
+
+Req = cowboy_req:req() +
+
+

+The Req object. +

+
+
+State = any() +
+
+

+Handler state. +

+
+
+Value +
+
+

+See the REST callbacks description below. +

+
+
+

Please see the REST callbacks description below for details +on the Value type, the default value if the callback is +not defined, and more general information on when the +callback is called and what its intended use is.

+

The stop tuple can be returned to stop REST processing. +It is up to the resource code to send a reply before that, +otherwise a 204 No Content will be sent.

+
+
+
+
+

REST callbacks description

+
+
+

allowed_methods

+
+
+Methods +
+
+

+all +

+
+
+Value type +
+
+

+[binary()] +

+
+
+Default value +
+
+

+[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>] +

+
+
+

Return the list of allowed methods.

+

Methods are case sensitive. Standard methods are always uppercase.

+
+
+

allow_missing_post

+
+
+Methods +
+
+

+POST +

+
+
+Value type +
+
+

+boolean() +

+
+
+Default value +
+
+

+true +

+
+
+

Return whether POST is allowed when the resource doesn’t exist.

+

Returning true here means that a new resource will be +created. The URL to the created resource should also be +returned from the AcceptResource callback.

+
+
+

charsets_provided

+
+
+Methods +
+
+

+GET, HEAD, POST, PUT, PATCH, DELETE +

+
+
+Value type +
+
+

+[binary()] +

+
+
+Default behavior +
+
+

+Skip to the next step if undefined. +

+
+
+

Return the list of charsets the resource provides.

+

The list must be ordered in order of preference.

+

If the accept-charset header was not sent, the first charset +in the list will be selected. Otherwise Cowboy will select +the most appropriate charset from the list.

+

The chosen charset will be set in the Req object as the meta +value charset.

+

While charsets are case insensitive, this callback is expected +to return them as lowercase binary.

+
+
+

content_types_accepted

+
+
+Methods +
+
+

+POST, PUT, PATCH +

+
+
+Value type +
+
+

+[{binary() | {Type, SubType, Params}, AcceptResource}] +

+
+
+Default behavior +
+
+

+Crash if undefined. +

+
+
+

With types:

+
    +
  • +

    +Type = SubType = binary() +

    +
    • +
  • +

    +Params = * | [{binary(), binary()}] +

    +
    • +
  • +

    +AcceptResource = atom() +

    +
    • +
+

Return the list of content-types the resource accepts.

+

The list must be ordered in order of preference.

+

Each content-type can be given either as a binary string or as +a tuple containing the type, subtype and parameters.

+

Cowboy will select the most appropriate content-type from the list. +If any parameter is acceptable, then the tuple form should be used +with parameters set to '*'. If the parameters value is set to [] +only content-type values with no parameters will be accepted. All +parameter values are treated in a case sensitive manner except the +charset parameter, if present, which is case insensitive.

+

This function will be called for POST, PUT and PATCH requests. +It is entirely possible to define different callbacks for different +methods if the handling of the request differs. Simply verify +what the method is with cowboy_req:method/1 and return a +different list for each methods.

+

The AcceptResource value is the name of the callback that will +be called if the content-type matches. It is defined as follows.

+
+
+Value type +
+
+

+true | {true, URL} | false +

+
+
+Default behavior +
+
+

+Crash if undefined. +

+
+
+

Process the request body.

+

This function should create or update the resource with the +information contained in the request body. This information +may be full or partial depending on the request method.

+

If the request body was processed successfully, true must +be returned. If the request method is POST, {true, URL} may +be returned instead, and Cowboy will redirect the client to +the location of the newly created resource.

+

If a response body must be sent, the appropriate media-type, charset +and language can be retrieved using the cowboy_req:meta/{2,3} +functions. The respective keys are media_type, charset +and language. The body can be set using cowboy_req:set_resp_body/2.

+
+
+

content_types_provided

+
+
+Methods +
+
+

+GET, HEAD, POST, PUT, PATCH, DELETE +

+
+
+Value type +
+
+

+[{binary() | {Type, SubType, Params}, ProvideResource}] +

+
+
+Default value +
+
+

+`[ +

+
+
+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_router/index.html b/docs/en/cowboy/2.0/manual/cowboy_router/index.html new file mode 100644 index 00000000..bdf6eb01 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_router/index.html @@ -0,0 +1,247 @@ + + + + + + + + + + + + Nine Nines: cowboy_router(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_router(3)

+ +
+

Name

+
+

cowboy_router - router middleware

+
+
+
+

Description

+
+

The cowboy_router middleware maps the requested host and +path to the handler to be used for processing the request. +It uses the dispatch rules compiled from the routes given +to the compile/1 function for this purpose. It adds the +handler name and options to the environment as the values +handler and handler_opts respectively.

+
+

Environment input

+
+
+dispatch = dispatch_rules() +
+
+

+Dispatch table. +

+
+
+
+
+

Environment output

+
+
+handler = module() +
+
+

+Handler module. +

+
+
+handler_opts = any() +
+
+

+Handler options. +

+
+
+
+
+
+
+

Types

+
+
+

bindings() = [{atom(), binary()}]

+

List of bindings found during routing.

+
+
+

dispatch_rules() - opaque to the user

+

Rules for dispatching request used by Cowboy.

+
+
+

routes() = [{Host, Paths} | {Host, cowboy:fields(), Paths}]

+

With types:

+
    +
  • +

    +Host = Path = _ | iodata() +

    +
    • +
  • +

    +Paths = [{Path, Handler, Opts} | {Path, cowboy:fields(), Handler, HandlerOpts}] +

    +
    • +
  • +

    +Handler = module() +

    +
    • +
  • +

    +HandlerOpts = any() +

    +
    • +
+

Human readable list of routes mapping hosts and paths to handlers.

+

The syntax for routes is defined in the user guide.

+
+
+

tokens() = [binary()]

+

List of host_info and path_info tokens found during routing.

+
+
+
+
+

Exports

+
+
+

compile(routes()) → dispatch_rules()

+

Compile the routes for use by Cowboy.

+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_static/index.html b/docs/en/cowboy/2.0/manual/cowboy_static/index.html new file mode 100644 index 00000000..62929c59 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_static/index.html @@ -0,0 +1,188 @@ + + + + + + + + + + + + Nine Nines: cowboy_static(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_static(3)

+ +
+

Name

+
+

cowboy_static - static file handler

+
+
+
+

Description

+
+

The cowboy_static module implements file serving capabilities +by using the REST semantics provided by cowboy_rest.

+
+
+
+

Types

+
+
+

opts() = [Option]

+
+
+
Option = {priv_file, atom(), string() | binary()}
+        | {priv_file, atom(), string() | binary(), Extra}
+        | {file, string() | binary()}
+        | {file, string() | binary(), Extra}
+        | {priv_dir, atom(), string() | binary()}
+        | {priv_dir, atom(), string() | binary(), Extra}
+        | {dir, string() | binary()}
+        | {dir, string() | binary(), Extra}
+
+Extra = [ETag | Mimetypes]
+
+ETag = {etag, module(), function()} | {etag, false}
+
+Mimetypes = {mimetypes, module(), function()}
+        | {mimetypes, binary() | {binary(), binary(), [{binary(), binary()}]}}
+

Configuration for the static handler.

+

The handler can be configured for sending either one file or +a directory (including its subdirectories).

+

Extra options allow you to define how the etag should be calculated +and how the mimetype of files should be detected.

+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_sub_protocol/index.html b/docs/en/cowboy/2.0/manual/cowboy_sub_protocol/index.html new file mode 100644 index 00000000..9559d6c4 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_sub_protocol/index.html @@ -0,0 +1,224 @@ + + + + + + + + + + + + Nine Nines: cowboy_sub_protocol(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_sub_protocol(3)

+ +
+

Name

+
+

cowboy_sub_protocol - sub protocol

+
+
+
+

Description

+
+

The cowboy_sub_protocol behaviour defines the interface used +by modules that implement a protocol on top of HTTP.

+
+
+
+

Callbacks

+
+
+

upgrade(Req, Env, Handler, HandlerOpts) → {ok, Req, Env} | {suspend, Module, Function, Args} | {stop, Req}

+
+
+Req = cowboy_req:req() +
+
+

+The Req object. +

+
+
+Env = env() +
+
+

+The request environment. +

+
+
+Handler = module() +
+
+

+Handler module. +

+
+
+Opts = any() +
+
+

+Handler options. +

+
+
+Module = module() +
+
+

+MFA to call when resuming the process. +

+
+
+Function = atom() +
+
+

+MFA to call when resuming the process. +

+
+
+Args = [any()] +
+
+

+MFA to call when resuming the process. +

+
+
+

Upgrade the protocol.

+

Please refer to the cowboy_middleware manual for a +description of the return values.

+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html new file mode 100644 index 00000000..8b3790c4 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html @@ -0,0 +1,352 @@ + + + + + + + + + + + + Nine Nines: cowboy_websocket(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_websocket(3)

+ +
+

Name

+
+

cowboy_websocket - Websocket protocol

+
+
+
+

Description

+
+

The cowboy_websocket module implements the Websocket protocol.

+

This module is a sub protocol that defines four callbacks to +be implemented by handlers. The init/2 and terminate/3 +callbacks are common to all handler types and are documented +in the manual for the cowboy_handler module.

+

The websocket_handle/3 and websocket_info/3 callbacks are +specific to Websocket handlers and will be called as many times +as necessary until the Websocket connection is closed.

+

The init/2 callback can be used to negotiate Websocket protocol +extensions with the client. It is highly recommended to return a +timeout value from this callback to ensure that the process is +terminated when no data has been received during that timespan. +The default timeout is infinity, which should only be used if +you have alternate means of ending inactive connections.

+

Cowboy will terminate the process right after closing the +Websocket connection. This means that there is no real need to +perform any cleanup in the optional terminate/3 callback.

+
+
+
+

Meta values

+
+
+
+websocket_compress = boolean() +
+
+

+ Whether a websocket compression extension in in use. +

+
+
+websocket_version = 7 | 8 | 13 +
+
+

+ The version of the Websocket protocol being used. +

+
+
+
+
+
+

Terminate reasons

+
+

The following values may be received as the terminate reason +in the optional terminate/3 callback.

+
+
+normal +
+
+

+ The connection was closed normally before establishing a Websocket + connection. This typically happens if an ok tuple is returned + from the init/2 callback. +

+
+
+remote +
+
+

+ The remote endpoint closed the connection without giving any + further details. +

+
+
+{remote, Code, Payload} +
+
+

+ The remote endpoint closed the connection with the given + Code and Payload as the reason. +

+
+
+stop +
+
+

+ The handler requested to close the connection, either by returning + a stop tuple or by sending a close frame. +

+
+
+timeout +
+
+

+ The connection has been closed due to inactivity. The timeout + value can be configured from init/2. +

+
+
+{crash, Class, Reason} +
+
+

+ A crash occurred in the handler. Class and Reason can be + used to obtain more information about the crash. The function + erlang:get_stacktrace/0 can also be called to obtain the + stacktrace of the process when the crash occurred. +

+
+
+{error, badencoding} +
+
+

+ A text frame was sent by the client with invalid encoding. All + text frames must be valid UTF-8. +

+
+
+{error, badframe} +
+
+

+ A protocol error has been detected. +

+
+
+{error, closed} +
+
+

+ The socket has been closed brutally without a close frame being + received first. +

+
+
+{error, Reason} +
+
+

+ A socket error ocurred. +

+
+
+
+
+
+

Callbacks

+
+
+

websocket_handle(InFrame, Req, State) → Ret

+
+
+
Ret = {ok, Req, State}
+        | {ok, Req, State, hibernate}
+        | {reply, OutFrame | [OutFrame], Req, State}
+        | {reply, OutFrame | [OutFrame], Req, State, hibernate}
+        | {stop, Req, State}
+
+InFrame = {text | binary | ping | pong, binary()}
+Req = cowboy_req:req()
+State = any()
+OutFrame = cow_ws:frame()
+

Handle the data received from the Websocket connection.

+

This function will be called every time data is received +from the Websocket connection.

+

The stop return value can be used to close the +connection. A close reply will also result in the connection +being closed.

+

The hibernate option will hibernate the process until +it receives new data from the Websocket connection or an +Erlang message.

+
+
+

websocket_info(Info, Req, State) → Ret

+
+
+
Ret = {ok, Req, State}
+        | {ok, Req, State, hibernate}
+        | {reply, OutFrame | [OutFrame], Req, State}
+        | {reply, OutFrame | [OutFrame], Req, State, hibernate}
+        | {stop, Req, State}
+
+Info = any()
+Req = cowboy_req:req()
+State = any()
+OutFrame = cow_ws:frame()
+

Handle the Erlang message received.

+

This function will be called every time an Erlang message +has been received. The message can be any Erlang term.

+

The stop return value can be used to close the +connection. A close reply will also result in the connection +being closed.

+

The hibernate option will hibernate the process until +it receives another message or new data from the Websocket +connection.

+
+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/http_status_codes/index.html b/docs/en/cowboy/2.0/manual/http_status_codes/index.html new file mode 100644 index 00000000..1af04219 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/http_status_codes/index.html @@ -0,0 +1,407 @@ + + + + + + + + + + + + Nine Nines: HTTP status codes(7) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

HTTP status codes(7)

+ +
+

Name

+
+

HTTP status codes - status codes used by Cowboy

+
+
+
+

Description

+
+

This chapter aims to list all HTTP status codes that Cowboy +may return, with details on the reasons why. The list given +here only includes the replies that Cowboy sends, not user +replies.

+
+
+
+

100 Continue

+
+

When the client sends an expect: 100-continue header, +Cowboy automatically sends a this status code before +trying to read the request body. This behavior can be +disabled using the appropriate body option.

+
+
+
+

101 Switching Protocols

+
+

This is the status code sent when switching to the +Websocket protocol.

+
+
+
+

200 OK

+
+

This status code is sent by cowboy_rest.

+
+
+
+

201 Created

+
+

This status code is sent by cowboy_rest.

+
+
+
+

202 Accepted

+
+

This status code is sent by cowboy_rest.

+
+
+
+

204 No Content

+
+

This status code is sent when the processing of a request +ends without any reply having been sent. It may also be +sent by cowboy_rest under normal conditions.

+
+
+
+

300 Multiple Choices

+
+

This status code is sent by cowboy_rest.

+
+
+
+

301 Moved Permanently

+
+

This status code is sent by cowboy_rest.

+
+
+
+

303 See Other

+
+

This status code is sent by cowboy_rest.

+
+
+
+

304 Not Modified

+
+

This status code is sent by cowboy_rest.

+
+
+
+

307 Temporary Redirect

+
+

This status code is sent by cowboy_rest.

+
+
+
+

400 Bad Request

+
+

Cowboy will send this status code for any of the +following reasons:

+
    +
  • +

    +Too many empty lines were sent before the request. +

    +
    • +
  • +

    +The request-line could not be parsed. +

    +
    • +
  • +

    +Too many headers were sent. +

    +
    • +
  • +

    +A header name was too long. +

    +
    • +
  • +

    +A header value was too long. +

    +
    • +
  • +

    +The host header was missing from an HTTP/1.1 request. +

    +
    • +
  • +

    +The host header could not be parsed. +

    +
    • +
  • +

    +The requested host was not found. +

    +
    • +
  • +

    +The requested path could not be parsed. +

    +
    • +
  • +

    +The accept header could not be parsed when using REST. +

    +
    • +
  • +

    +REST under normal conditions. +

    +
    • +
  • +

    +A Websocket upgrade failed. +

    +
    • +
+
+
+
+

401 Unauthorized

+
+

This status code is sent by cowboy_rest.

+
+
+
+

403 Forbidden

+
+

This status code is sent by cowboy_rest.

+
+
+
+

404 Not Found

+
+

This status code is sent when the router successfully +resolved the host but didn’t find a matching path for +the request. It may also be sent by cowboy_rest under +normal conditions.

+
+
+
+

405 Method Not Allowed

+
+

This status code is sent by cowboy_rest.

+
+
+
+

406 Not Acceptable

+
+

This status code is sent by cowboy_rest.

+
+
+
+

408 Request Timeout

+
+

Cowboy will send this status code to the client if the +client started to send a request, indicated by the +request-line being received fully, but failed to send +all headers in a reasonable time.

+
+
+
+

409 Conflict

+
+

This status code is sent by cowboy_rest.

+
+
+
+

410 Gone

+
+

This status code is sent by cowboy_rest.

+
+
+
+

412 Precondition Failed

+
+

This status code is sent by cowboy_rest.

+
+
+
+

413 Request Entity Too Large

+
+

This status code is sent by cowboy_rest.

+
+
+
+

414 Request-URI Too Long

+
+

Cowboy will send this status code to the client if the +request-line is too long. It may also be sent by +cowboy_rest under normal conditions.

+
+
+
+

415 Unsupported Media Type

+
+

This status code is sent by cowboy_rest.

+
+
+
+

500 Internal Server Error

+
+

This status code is sent when a crash occurs in HTTP, loop +or REST handlers, or when an invalid return value is +returned. It may also be sent by cowboy_rest under +normal conditions.

+
+
+
+

501 Not Implemented

+
+

This status code is sent by cowboy_rest.

+
+
+
+

503 Service Unavailable

+
+

This status code is sent by cowboy_rest.

+
+
+
+

505 HTTP Version Not Supported

+
+

Cowboy only supports the versions 1.0 and 1.1 of HTTP. +In all other cases this status code is sent back to the +client and the connection is closed.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/index.html b/docs/en/cowboy/2.0/manual/index.html new file mode 100644 index 00000000..2751944d --- /dev/null +++ b/docs/en/cowboy/2.0/manual/index.html @@ -0,0 +1,209 @@ + + + + + + + + + + + + Nine Nines: Cowboy Function Reference + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Cowboy Function Reference

+ +
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/cowboy/HEAD/guide/index.html b/docs/en/cowboy/HEAD/guide/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/cowboy/HEAD/guide/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/cowboy/HEAD/index.html b/docs/en/cowboy/HEAD/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/cowboy/HEAD/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/cowboy/HEAD/manual/index.html b/docs/en/cowboy/HEAD/manual/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/cowboy/HEAD/manual/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/cowboy/index.html b/docs/en/cowboy/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/cowboy/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/erlang.mk/1/guide/app.asciidoc b/docs/en/erlang.mk/1/guide/app.asciidoc new file mode 100644 index 00000000..99ff0527 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/app.asciidoc @@ -0,0 +1,426 @@ +[[building]] +== Building + +Erlang.mk can do a lot of things, but it is, first and +foremost, a build tool. In this chapter we will cover +the basics of building a project with Erlang.mk. + +For most of this chapter, we will assume that you are +using a project xref:getting_started[generated by Erlang.mk]. + +=== How to build + +To build a project, all you have to do is type `make`: + +[source,bash] +$ make + +It will work regardless of your project: OTP applications, +library applications, NIFs, port drivers or even releases. +Erlang.mk also automatically downloads and compiles the +dependencies for your project. + +All this is possible thanks to a combination of configuration +and conventions. Most of the conventions come from Erlang/OTP +itself so any seasoned Erlang developers should feel right at +home. + +=== What to build + +Erlang.mk gives you control over three steps of the build +process, allowing you to do a partial build if needed. + +A build has three phases: first any dependency is fetched +and built, then the project itself is built and finally a +release may be generated when applicable. A release is only +generated for projects specifically configured to do so. + +Erlang.mk handles those three phases automatically when you +type `make`. But sometimes you just want to repeat one or +two of them. + +The commands detailed in this section are most useful after +you have a successful build as they allow you to quickly +redo a step instead of going through everything. This is +especially useful for large projects or projects that end +up generating releases. + +==== Application + +You can build your application and dependencies without +generating a release by running the following command: + +[source,bash] +$ make app + +To build your application without touching dependencies +at all, you can use the `SKIP_DEPS` variable: + +[source,bash] +$ make app SKIP_DEPS=1 + +This command is very useful if you have a lot of dependencies +and develop on a machine with slow file access, like the +Raspberry Pi and many other embedded devices. + +Note that this command may fail if a required dependency +is missing. + +==== Dependencies + +You can build all dependencies, and nothing else, by +running the following command: + +[source,bash] +$ make deps + +This will fetch and compile all dependencies and their +dependencies, recursively. + +xref:deps[Packages and dependencies] are covered +in the next chapter. + +==== Release + +It is not possible to build the release without at least +building the application itself, unless of course if there's +no application to begin with. + +To generate the release, `make` will generally suffice with +a normal Erlang.mk. A separate target is however available, +and will take care of building the release, after building +the application and all dependencies: + +[source,bash] +$ make rel + +Consult the xref:relx[Releases] chapter for more +information about what releases are and how they are generated. + +=== Application resource file + +When building your application, Erlang.mk will generate the +http://www.erlang.org/doc/man/app.html[application resource file]. +This file is mandatory for all Erlang applications and is +found in 'ebin/$(PROJECT).app'. + +`PROJECT` is a variable defined in your Makefile and taken +from the name of the directory when Erlang.mk bootstraps +your project. + +Erlang.mk can build the 'ebin/$(PROJECT).app' in two different +ways: from the configuration found in the Makefile, or from +the 'src/$(PROJECT).app.src' file. + +==== Application configuration + +Erlang.mk automatically fills the `PROJECT` variable when +bootstrapping a new project, but everything else is up to +you. None of the values are required to build your project, +although it is recommended to fill everything relevant to +your situation. + +`PROJECT`:: + The name of the OTP application or library. +`PROJECT_DESCRIPTION`:: + Short description of the project. +`PROJECT_VERSION`:: + Current version of the project. +`PROJECT_REGISTERED`:: + List of the names of all registered processes. +`LOCAL_DEPS`:: + List of Erlang/OTP applications this project depends on, + excluding `erts`, `kernel` and `stdlib`, or list of + dependencies local to this repository (in `APPS_DIR`). +`DEPS`:: + List of applications this project depends on that need + to be fetched by Erlang.mk. + +There's no need for quotes or anything. The relevant part of +the Cowboy Makefile follows, if you need an example: + +[source,make] +---- +PROJECT = cowboy +PROJECT_DESCRIPTION = Small, fast, modular HTTP server. +PROJECT_VERSION = 2.0.0-pre.2 +PROJECT_REGISTERED = cowboy_clock + +LOCAL_DEPS = crypto +DEPS = cowlib ranch +---- + +Any space before and after the value is dropped. + +xref:deps[Dependencies] are covered in details in +the next chapter. + +==== Legacy method + +The 'src/$(PROJECT).app.src' file is a legacy method of +building Erlang applications. It was introduced by the original +`rebar` build tool, of which Erlang.mk owes a great deal as it +is its main inspiration. + +The '.app.src' file serves as a template to generate the '.app' +file. Erlang.mk will take it, fill in the `modules` value +dynamically, and save the result in 'ebin/$(PROJECT).app'. + +When using this method, Erlang.mk cannot fill the `applications` +key from dependencies automatically, which means you need to +add them to Erlang.mk and to the '.app.src' at the same time, +duplicating the work. + +If you really can't live without the legacy method, for one +reason or another, worry not; Erlang.mk will support it. And +if you need to create a new project that uses this method, you +just have to say so when bootstrapping: + +[source,bash] +$ make -f erlang.mk bootstrap-lib LEGACY=1 + +=== Automatic application resource file values + +When building the application resource file, Erlang.mk may +automatically add an `id` key with information about the +Git commit (if using Git), or an empty string otherwise. +It will only do this under specific conditions: + +* The application was built as a dependency of another, or +* The legacy method was used, and the '.app.src' file contained `{id, "git"}` + +This value is most useful when you need to help your users, +as it allows you to know which version they run exactly by +asking them to look in the file, or by running a simple +command on their production server: + +[source,erlang] +---- +1> application:get_all_key(cowboy). +{ok,[{description,"Small, fast, modular HTTP server."}, + {id,"2.0.0-pre.2-25-g0ffde50-dirty"}, +---- + +=== File formats + +Erlang.mk supports a variety of different source file formats. +The following formats are supported natively: + +[cols="<,3*^",options="header"] +|=== +| Extension | Location | Description | Output +| .erl | src/ | Erlang source | ebin/*.beam +| .core | src/ | Core Erlang source | ebin/*.beam +| .xrl | src/ | Leex source | src/*.erl +| .yrl | src/ | Yecc source | src/*.erl +| .asn1 | asn1/ | ASN.1 files | include/*.hrl include/*.asn1db src/*.erl +| .mib | mibs/ | SNMP MIB files | include/*.hrl priv/mibs/*.bin +|=== + +Files are always searched recursively. + +The build is ordered, so that files that generate Erlang source +files are run before, and the resulting Erlang source files are +then built normally. + +In addition, Erlang.mk keeps track of header files (`.hrl`) +as described at the end of this chapter. It can also compile +C code, as described in the xref:ports[NIFs and port drivers] +chapter. + +Erlang.mk also comes with plugins for the following formats: + +[cols="<,3*^",options="header"] +|=== +| Extension | Location | Description | Output +| .dtl | templates/ | Django templates | ebin/*.beam +| .proto | src/ | Protocol buffers | ebin/*.beam +|=== + +=== Compilation options + +Erlang.mk provides a few variables that you can use to customize +the build process and the resulting files. + +==== ERLC_OPTS + +`ERLC_OPTS` can be used to pass some options to `erlc`, the Erlang +compiler. Erlang.mk does not restrict any option. Please refer to +the http://www.erlang.org/doc/man/erlc.html[erlc Manual] for the +full list. + +By default, Erlang.mk will set the following options: + +[source,make] +ERLC_OPTS = -Werror +debug_info +warn_export_vars +warn_shadow_vars +warn_obsolete_guard + +In other words: warnings as errors, debug info (recommended) and +enable warnings for exported variables, shadow variables and +obsolete guard functions. + +You can redefine this variable in your Makefile to change it +completely, either before or after including Erlang.mk: + +[source,make] +ERLC_OPTS = +debug_info + +You can also filter out some options from the defaults Erlang.mk +sets, by defining ERLC_OPTS after including Erlang.mk using the +`:=` operator. + +[source,make] +---- +include erlang.mk + +ERLC_OPTS := $(filter-out -Werror,$(ERLC_OPTS)) +---- + +==== ERLC_EXCLUDE + +`ERLC_EXCLUDE` can be used to exclude some modules from the +compilation. It's there for handling special cases, you should +not normally need it. + +To exclude a module, simply list it in the variable, either +before or after including Erlang.mk: + +[source,make] +ERLC_EXCLUDE = cowboy_http2 + +=== Cold and hot builds + +The first time you run `make`, Erlang.mk will build everything. + +The second time you run `make`, and all subsequent times, Erlang.mk +will only rebuild what changed. Erlang.mk has been optimized for +this use case, as it is the most common during development. + +Erlang.mk figures out what changed by using the dependency tracking +feature of Make. Make automatically rebuilds a target if one of its +dependency has changed (for example if a header file has changed, +all the source files that include it will be rebuilt), and Erlang.mk +leverages this feature to cut down on rebuild times. + +Note that this applies only to building; some other features of +Erlang.mk will run every time they are called regardless of files +changed. + +=== Dependency tracking + +NOTE: This section is about the dependency tracking between files +inside your project, not application dependencies. + +Erlang.mk keeps track of the dependencies between the different +files in your project. This information is kept in the '$(PROJECT).d' +file in your directory. It is generated if missing, and will be +generated again after every file change, by default. + +Dependency tracking is what allows Erlang.mk to know when to +rebuild Erlang files when header files, behaviors or parse +transforms have changed. Erlang.mk also automatically keeps +track of which files should be compiled first, for example +when you have behaviors used by other modules in your project. + +If your project is stable, you may want to disable generating +the dependency tracking file every time you compile. You can +do this by adding the following line to your 'Makefile': + +[source,make] +NO_MAKEDEP ?= 1 + +As you can see, the snippet above uses `?=` instead of a +simple equal sign. This is to allow you to temporarily override +this value when you do make substantial changes to your project +(including a new header file, new module with dependencies, etc.) +and want to rebuild the dependency tracking file. You'll be +able to use the following command: + +[source,bash] +$ NO_MAKEDEP= make + +Otherwise, `make clean app` will of course force the +recompilation of your project. + +Erlang.mk can also keep track of the source files generated +by other means, for example if you generate code from a data +file in your repository. + +=== Generating Erlang source + +Erlang.mk provides hooks at different stages of the build process. +When your goal is to generate Erlang source files, you can +add your own rules before or after the dependency tracking +file is generated. To do this, you would add your hook before +or after including the 'erlang.mk' file. + +The easiest way is after: + +[source,make] +---- +PROJECT = example + +include erlang.mk + +$(PROJECT).d:: src/generated_mod.erl + +src/generated_mod.erl:: gen-mod.sh + $(gen_verbose) ./gen-mod.sh $@ +---- + +In this case we use `$(gen_verbose)` to hide the details of +the build by default. Erlang.mk will simply say what file +is it currently generating. + +When using an external script to generate the Erlang source +file, it is recommended to depend on that script, so that +the source file gets generated again when the script gets +modified. + +If for whatever reason you prefer to hook before including +Erlang.mk, don't forget to set the `.DEFAULT_GOAL` variable, +otherwise nothing will get built: + +[source,make] +---- +PROJECT = example + +.DEFAULT_GOAL = all + +$(PROJECT).d:: src/generated_mod.erl + +include erlang.mk + +src/generated_mod.erl:: gen-mod.sh + $(gen_verbose) ./gen-mod.sh $@ +---- + +=== Cleaning + +Building typically involves creating a lot of new files. Some +are reused in rebuilds, some are simply replaced. All can be +removed safely. + +Erlang.mk provides two commands to remove them: `clean` and +`distclean`. `clean` removes all the intermediate files that +were created as a result of building, including the BEAM files, +the dependency tracking file and the generated documentation. +`distclean` removes these and more, including the downloaded +dependencies, Dialyzer's PLT file and the generated release, +putting your directory back to the state it was before you +started working on it. + +To clean: + +[source,bash] +$ make clean + +Or distclean: + +[source,bash] +$ make distclean + +That is the question. + +Note that Erlang.mk will automatically clean some files as +part of other targets, but it will never run `distclean` if +you don't explicitly use it. diff --git a/docs/en/erlang.mk/1/guide/app/index.html b/docs/en/erlang.mk/1/guide/app/index.html new file mode 100644 index 00000000..7d2b36f8 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/app/index.html @@ -0,0 +1,699 @@ + + + + + + + + + + + + Nine Nines: Building + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Building

+ +

Erlang.mk can do a lot of things, but it is, first and +foremost, a build tool. In this chapter we will cover +the basics of building a project with Erlang.mk.

+

For most of this chapter, we will assume that you are +using a project generated by Erlang.mk.

+
+

How to build

+
+

To build a project, all you have to do is type make:

+
+
+
$ make
+

It will work regardless of your project: OTP applications, +library applications, NIFs, port drivers or even releases. +Erlang.mk also automatically downloads and compiles the +dependencies for your project.

+

All this is possible thanks to a combination of configuration +and conventions. Most of the conventions come from Erlang/OTP +itself so any seasoned Erlang developers should feel right at +home.

+
+
+
+

What to build

+
+

Erlang.mk gives you control over three steps of the build +process, allowing you to do a partial build if needed.

+

A build has three phases: first any dependency is fetched +and built, then the project itself is built and finally a +release may be generated when applicable. A release is only +generated for projects specifically configured to do so.

+

Erlang.mk handles those three phases automatically when you +type make. But sometimes you just want to repeat one or +two of them.

+

The commands detailed in this section are most useful after +you have a successful build as they allow you to quickly +redo a step instead of going through everything. This is +especially useful for large projects or projects that end +up generating releases.

+
+

Application

+

You can build your application and dependencies without +generating a release by running the following command:

+
+
+
$ make app
+

To build your application without touching dependencies +at all, you can use the SKIP_DEPS variable:

+
+
+
$ make app SKIP_DEPS=1
+

This command is very useful if you have a lot of dependencies +and develop on a machine with slow file access, like the +Raspberry Pi and many other embedded devices.

+

Note that this command may fail if a required dependency +is missing.

+
+
+

Dependencies

+

You can build all dependencies, and nothing else, by +running the following command:

+
+
+
$ make deps
+

This will fetch and compile all dependencies and their +dependencies, recursively.

+

Packages and dependencies are covered +in the next chapter.

+
+
+

Release

+

It is not possible to build the release without at least +building the application itself, unless of course if there’s +no application to begin with.

+

To generate the release, make will generally suffice with +a normal Erlang.mk. A separate target is however available, +and will take care of building the release, after building +the application and all dependencies:

+
+
+
$ make rel
+

Consult the Releases chapter for more +information about what releases are and how they are generated.

+
+
+
+
+

Application resource file

+
+

When building your application, Erlang.mk will generate the +application resource file. +This file is mandatory for all Erlang applications and is +found in ebin/$(PROJECT).app.

+

PROJECT is a variable defined in your Makefile and taken +from the name of the directory when Erlang.mk bootstraps +your project.

+

Erlang.mk can build the ebin/$(PROJECT).app in two different +ways: from the configuration found in the Makefile, or from +the src/$(PROJECT).app.src file.

+
+

Application configuration

+

Erlang.mk automatically fills the PROJECT variable when +bootstrapping a new project, but everything else is up to +you. None of the values are required to build your project, +although it is recommended to fill everything relevant to +your situation.

+
+
+PROJECT +
+
+

+ The name of the OTP application or library. +

+
+
+PROJECT_DESCRIPTION +
+
+

+ Short description of the project. +

+
+
+PROJECT_VERSION +
+
+

+ Current version of the project. +

+
+
+PROJECT_REGISTERED +
+
+

+ List of the names of all registered processes. +

+
+
+LOCAL_DEPS +
+
+

+ List of Erlang/OTP applications this project depends on, + excluding erts, kernel and stdlib, or list of + dependencies local to this repository (in APPS_DIR). +

+
+
+DEPS +
+
+

+ List of applications this project depends on that need + to be fetched by Erlang.mk. +

+
+
+

There’s no need for quotes or anything. The relevant part of +the Cowboy Makefile follows, if you need an example:

+
+
+
PROJECT = cowboy
+PROJECT_DESCRIPTION = Small, fast, modular HTTP server.
+PROJECT_VERSION = 2.0.0-pre.2
+PROJECT_REGISTERED = cowboy_clock
+
+LOCAL_DEPS = crypto
+DEPS = cowlib ranch
+

Any space before and after the value is dropped.

+

Dependencies are covered in details in +the next chapter.

+
+
+

Legacy method

+

The src/$(PROJECT).app.src file is a legacy method of +building Erlang applications. It was introduced by the original +rebar build tool, of which Erlang.mk owes a great deal as it +is its main inspiration.

+

The .app.src file serves as a template to generate the .app +file. Erlang.mk will take it, fill in the modules value +dynamically, and save the result in ebin/$(PROJECT).app.

+

When using this method, Erlang.mk cannot fill the applications +key from dependencies automatically, which means you need to +add them to Erlang.mk and to the .app.src at the same time, +duplicating the work.

+

If you really can’t live without the legacy method, for one +reason or another, worry not; Erlang.mk will support it. And +if you need to create a new project that uses this method, you +just have to say so when bootstrapping:

+
+
+
$ make -f erlang.mk bootstrap-lib LEGACY=1
+
+
+
+
+

Automatic application resource file values

+
+

When building the application resource file, Erlang.mk may +automatically add an id key with information about the +Git commit (if using Git), or an empty string otherwise. +It will only do this under specific conditions:

+
    +
  • +

    +The application was built as a dependency of another, or +

    +
    • +
  • +

    +The legacy method was used, and the .app.src file contained {id, "git"} +

    +
    • +
+

This value is most useful when you need to help your users, +as it allows you to know which version they run exactly by +asking them to look in the file, or by running a simple +command on their production server:

+
+
+
1> application:get_all_key(cowboy).
+{ok,[{description,"Small, fast, modular HTTP server."},
+     {id,"2.0.0-pre.2-25-g0ffde50-dirty"},
+
+
+
+

File formats

+
+

Erlang.mk supports a variety of different source file formats. +The following formats are supported natively:

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Extension Location Description Output

.erl

src/

Erlang source

ebin/*.beam

.core

src/

Core Erlang source

ebin/*.beam

.xrl

src/

Leex source

src/*.erl

.yrl

src/

Yecc source

src/*.erl

.asn1

asn1/

ASN.1 files

include/.hrl include/.asn1db src/*.erl

.mib

mibs/

SNMP MIB files

include/.hrl priv/mibs/.bin

+
+

Files are always searched recursively.

+

The build is ordered, so that files that generate Erlang source +files are run before, and the resulting Erlang source files are +then built normally.

+

In addition, Erlang.mk keeps track of header files (.hrl) +as described at the end of this chapter. It can also compile +C code, as described in the NIFs and port drivers +chapter.

+

Erlang.mk also comes with plugins for the following formats:

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + +
Extension Location Description Output

.dtl

templates/

Django templates

ebin/*.beam

.proto

src/

Protocol buffers

ebin/*.beam

+
+
+
+
+

Compilation options

+
+

Erlang.mk provides a few variables that you can use to customize +the build process and the resulting files.

+
+

ERLC_OPTS

+

ERLC_OPTS can be used to pass some options to erlc, the Erlang +compiler. Erlang.mk does not restrict any option. Please refer to +the erlc Manual for the +full list.

+

By default, Erlang.mk will set the following options:

+
+
+
ERLC_OPTS = -Werror +debug_info +warn_export_vars +warn_shadow_vars +warn_obsolete_guard
+

In other words: warnings as errors, debug info (recommended) and +enable warnings for exported variables, shadow variables and +obsolete guard functions.

+

You can redefine this variable in your Makefile to change it +completely, either before or after including Erlang.mk:

+
+
+
ERLC_OPTS = +debug_info
+

You can also filter out some options from the defaults Erlang.mk +sets, by defining ERLC_OPTS after including Erlang.mk using the +:= operator.

+
+
+
include erlang.mk
+
+ERLC_OPTS := $(filter-out -Werror,$(ERLC_OPTS))
+
+
+

ERLC_EXCLUDE

+

ERLC_EXCLUDE can be used to exclude some modules from the +compilation. It’s there for handling special cases, you should +not normally need it.

+

To exclude a module, simply list it in the variable, either +before or after including Erlang.mk:

+
+
+
ERLC_EXCLUDE = cowboy_http2
+
+
+
+
+

Cold and hot builds

+
+

The first time you run make, Erlang.mk will build everything.

+

The second time you run make, and all subsequent times, Erlang.mk +will only rebuild what changed. Erlang.mk has been optimized for +this use case, as it is the most common during development.

+

Erlang.mk figures out what changed by using the dependency tracking +feature of Make. Make automatically rebuilds a target if one of its +dependency has changed (for example if a header file has changed, +all the source files that include it will be rebuilt), and Erlang.mk +leverages this feature to cut down on rebuild times.

+

Note that this applies only to building; some other features of +Erlang.mk will run every time they are called regardless of files +changed.

+
+
+
+

Dependency tracking

+
+
+ + + +
+
Note
+		This section is about the dependency tracking between files +inside your project, not application dependencies.
+
+

Erlang.mk keeps track of the dependencies between the different +files in your project. This information is kept in the $(PROJECT).d +file in your directory. It is generated if missing, and will be +generated again after every file change, by default.

+

Dependency tracking is what allows Erlang.mk to know when to +rebuild Erlang files when header files, behaviors or parse +transforms have changed. Erlang.mk also automatically keeps +track of which files should be compiled first, for example +when you have behaviors used by other modules in your project.

+

If your project is stable, you may want to disable generating +the dependency tracking file every time you compile. You can +do this by adding the following line to your Makefile:

+
+
+
NO_MAKEDEP ?= 1
+

As you can see, the snippet above uses ?= instead of a +simple equal sign. This is to allow you to temporarily override +this value when you do make substantial changes to your project +(including a new header file, new module with dependencies, etc.) +and want to rebuild the dependency tracking file. You’ll be +able to use the following command:

+
+
+
$ NO_MAKEDEP= make
+

Otherwise, make clean app will of course force the +recompilation of your project.

+

Erlang.mk can also keep track of the source files generated +by other means, for example if you generate code from a data +file in your repository.

+
+
+
+

Generating Erlang source

+
+

Erlang.mk provides hooks at different stages of the build process. +When your goal is to generate Erlang source files, you can +add your own rules before or after the dependency tracking +file is generated. To do this, you would add your hook before +or after including the erlang.mk file.

+

The easiest way is after:

+
+
+
PROJECT = example
+
+include erlang.mk
+
+$(PROJECT).d:: src/generated_mod.erl
+
+src/generated_mod.erl:: gen-mod.sh
+        $(gen_verbose) ./gen-mod.sh $@
+

In this case we use $(gen_verbose) to hide the details of +the build by default. Erlang.mk will simply say what file +is it currently generating.

+

When using an external script to generate the Erlang source +file, it is recommended to depend on that script, so that +the source file gets generated again when the script gets +modified.

+

If for whatever reason you prefer to hook before including +Erlang.mk, don’t forget to set the .DEFAULT_GOAL variable, +otherwise nothing will get built:

+
+
+
PROJECT = example
+
+.DEFAULT_GOAL = all
+
+$(PROJECT).d:: src/generated_mod.erl
+
+include erlang.mk
+
+src/generated_mod.erl:: gen-mod.sh
+        $(gen_verbose) ./gen-mod.sh $@
+
+
+
+

Cleaning

+
+

Building typically involves creating a lot of new files. Some +are reused in rebuilds, some are simply replaced. All can be +removed safely.

+

Erlang.mk provides two commands to remove them: clean and +distclean. clean removes all the intermediate files that +were created as a result of building, including the BEAM files, +the dependency tracking file and the generated documentation. +distclean removes these and more, including the downloaded +dependencies, Dialyzer’s PLT file and the generated release, +putting your directory back to the state it was before you +started working on it.

+

To clean:

+
+
+
$ make clean
+

Or distclean:

+
+
+
$ make distclean
+

That is the question.

+

Note that Erlang.mk will automatically clean some files as +part of other targets, but it will never run distclean if +you don’t explicitly use it.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/asciidoc.asciidoc b/docs/en/erlang.mk/1/guide/asciidoc.asciidoc new file mode 100644 index 00000000..cc8336bf --- /dev/null +++ b/docs/en/erlang.mk/1/guide/asciidoc.asciidoc @@ -0,0 +1,82 @@ +[[asciidoc]] +== AsciiDoc documentation + +Erlang.mk provides rules for generating documentation from +AsciiDoc files. It can automatically build a user guide PDF, +chunked HTML documentation and Unix manual pages. + +=== Requirements + +It is necessary to have http://asciidoc.org/[AsciiDoc], +http://xmlsoft.org/XSLT/xsltproc2.html[xsltproc] and +http://dblatex.sourceforge.net/[dblatex] installed on your +system for Erlang.mk to generate documentation from AsciiDoc sources. + +=== Writing AsciiDoc documentation + +http://asciidoc.org/[AsciiDoc] is a text document format for +writing notes, documentation, articles, books, ebooks, slideshows, +web pages, man pages and blogs. AsciiDoc files can be translated +to many formats including HTML, PDF, EPUB, man page. + +The http://asciidoc.org/userguide.html[AsciiDoc user guide] +describes the AsciiDoc syntax. + +The https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide[Erlang.mk user guide] +is written in AsciiDoc and can be used as an example. The entry +file is https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc[book.asciidoc]. + +Erlang.mk expects you to put your documentation in a specific +location. This is 'doc/src/guide/' for the user guide, and +'doc/src/manual/' for the function reference. In the case of +the user guide, the entry point is always 'doc/src/guide/book.asciidoc'. + +For manual pages, it is good practice to use section 3 for +modules, and section 7 for the application itself. + +=== Configuration + +All of the AsciiDoc related configuration can be done directly +inside the files themselves. + +=== Usage + +To build all documentation: + +[source,bash] +$ make docs + +To build only the AsciiDoc documentation: + +[source,bash] +$ make asciidoc + +To build only the user guide: + +[source,bash] +$ make asciidoc-guide + +To build only the manual: + +[source,bash] +$ make asciidoc-manual + +To install man pages on Unix: + +[source,bash] +$ make install-docs + +Erlang.mk allows customizing the installation path and sections +of the man pages to be installed. The `MAN_INSTALL_PATH` variable +defines where man pages will be installed. It defaults to +'/usr/local/share/man'. The `MAN_SECTIONS` variable defines +which manual sections are to be installed. It defaults to `3 7`. + +To install man pages to a custom location: + +[source,bash] +$ make install-docs MAN_INSTALL_PATH=/opt/share/man + +Note that you may need to run the install commands using +`sudo` or equivalent if the location is not writeable by +your user. diff --git a/docs/en/erlang.mk/1/guide/asciidoc/index.html b/docs/en/erlang.mk/1/guide/asciidoc/index.html new file mode 100644 index 00000000..92bef918 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/asciidoc/index.html @@ -0,0 +1,230 @@ + + + + + + + + + + + + Nine Nines: AsciiDoc documentation + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

AsciiDoc documentation

+ +

Erlang.mk provides rules for generating documentation from +AsciiDoc files. It can automatically build a user guide PDF, +chunked HTML documentation and Unix manual pages.

+
+

Requirements

+
+

It is necessary to have AsciiDoc, +xsltproc and +dblatex installed on your +system for Erlang.mk to generate documentation from AsciiDoc sources.

+
+
+
+

Writing AsciiDoc documentation

+
+

AsciiDoc is a text document format for +writing notes, documentation, articles, books, ebooks, slideshows, +web pages, man pages and blogs. AsciiDoc files can be translated +to many formats including HTML, PDF, EPUB, man page.

+

The AsciiDoc user guide +describes the AsciiDoc syntax.

+

The Erlang.mk user guide +is written in AsciiDoc and can be used as an example. The entry +file is book.asciidoc.

+

Erlang.mk expects you to put your documentation in a specific +location. This is doc/src/guide/ for the user guide, and +doc/src/manual/ for the function reference. In the case of +the user guide, the entry point is always doc/src/guide/book.asciidoc.

+

For manual pages, it is good practice to use section 3 for +modules, and section 7 for the application itself.

+
+
+
+

Configuration

+
+

All of the AsciiDoc related configuration can be done directly +inside the files themselves.

+
+
+
+

Usage

+
+

To build all documentation:

+
+
+
$ make docs
+

To build only the AsciiDoc documentation:

+
+
+
$ make asciidoc
+

To build only the user guide:

+
+
+
$ make asciidoc-guide
+

To build only the manual:

+
+
+
$ make asciidoc-manual
+

To install man pages on Unix:

+
+
+
$ make install-docs
+

Erlang.mk allows customizing the installation path and sections +of the man pages to be installed. The MAN_INSTALL_PATH variable +defines where man pages will be installed. It defaults to +/usr/local/share/man. The MAN_SECTIONS variable defines +which manual sections are to be installed. It defaults to 3 7.

+

To install man pages to a custom location:

+
+
+
$ make install-docs MAN_INSTALL_PATH=/opt/share/man
+

Note that you may need to run the install commands using +sudo or equivalent if the location is not writeable by +your user.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/ci.asciidoc b/docs/en/erlang.mk/1/guide/ci.asciidoc new file mode 100644 index 00000000..24cfc053 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/ci.asciidoc @@ -0,0 +1,6 @@ +[[ci]] +== Continuous integration + +// @todo Write it. + +Placeholder chapter. diff --git a/docs/en/erlang.mk/1/guide/ci/index.html b/docs/en/erlang.mk/1/guide/ci/index.html new file mode 100644 index 00000000..aedef405 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/ci/index.html @@ -0,0 +1,137 @@ + + + + + + + + + + + + Nine Nines: Continuous integration + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Continuous integration

+ +

Placeholder chapter.

+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/common_test.asciidoc b/docs/en/erlang.mk/1/guide/common_test.asciidoc new file mode 100644 index 00000000..aec8747e --- /dev/null +++ b/docs/en/erlang.mk/1/guide/common_test.asciidoc @@ -0,0 +1,91 @@ +[[ct]] +== Common Test + +Common Test is Erlang's functional testing framework. +Erlang.mk automates the discovery and running of Common +Test suites. + +=== Writing tests + +The http://www.erlang.org/doc/apps/common_test/write_test_chapter.html[Common Test user guide] +is the best place to learn how to write tests. Erlang.mk +requires that file names for test suites end with '_SUITE.erl' +and that the files be located in the '$(TEST_DIR)' directory. +This defaults to 'test/'. + +=== Configuration + +The `CT_OPTS` variable allows you to set extra Common Test +options. Options are documented in the +http://www.erlang.org/doc/apps/common_test/run_test_chapter.html[Common Test user guide]. +You can use it to set Common Test hooks, for example: + +[source,make] +CT_OPTS = -ct_hooks cowboy_ct_hook + +The `CT_SUITES` variable can be used to override what +Common Test suites Erlang.mk will be aware of. It does +not normally need to be set as Erlang.mk will find the +test suites automatically. + +The name of the suite is the part before `_SUITE.erl`. +If the file is named 'http_SUITE.erl', the test suite +is `http`: + +[source,make] +CT_SUITES = http ws + +=== Usage + +To run all tests (including Common Test): + +[source,bash] +$ make tests + +To run all tests and static checks (including Common Test): + +[source,bash] +$ make check + +You can also run Common Test separately: + +[source,bash] +$ make ct + +Erlang.mk will create targets for all test suites it finds. +If you have a file named 'test/http_SUITE.erl', then the +target `ct-http` will run that specific test suite: + +[source,bash] +$ make ct-http + +Erlang.mk provides a convenient way to run a specific +group or a specific test case within a specific group, +using the variable `t`. Note that this only applies to +suite-specific targets, like the `ct-http` example above. + +To run all tests from the `http_compress` group in the +`http_SUITE` test suite, write: + +[source,bash] +$ make ct-http t=http_compress + +Similarly, to run a specific test case in that group: + +[source,bash] +$ make ct-http t=http_compress:headers_dupe + +To do the same against a multi-application repository, +you can use the `-C` option: + +[source,bash] +$ make -C apps/my_app ct-http t=my_group:my_case + +Note that this also applies to dependencies. When using Cowboy +as a dependency, you can run the following directly: + +[source,bash] +$ make -C deps/cowboy ct-http t=http_compress + +Finally, xref:coverage[code coverage] is available, +but covered in its own chapter. diff --git a/docs/en/erlang.mk/1/guide/common_test/index.html b/docs/en/erlang.mk/1/guide/common_test/index.html new file mode 100644 index 00000000..aae734f1 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/common_test/index.html @@ -0,0 +1,249 @@ + + + + + + + + + + + + Nine Nines: Common Test + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Common Test

+ +

Common Test is Erlang’s functional testing framework. +Erlang.mk automates the discovery and running of Common +Test suites.

+
+

Writing tests

+
+

The Common Test user guide +is the best place to learn how to write tests. Erlang.mk +requires that file names for test suites end with _SUITE.erl +and that the files be located in the $(TEST_DIR) directory. +This defaults to test/.

+
+
+
+

Configuration

+
+

The CT_OPTS variable allows you to set extra Common Test +options. Options are documented in the +Common Test user guide. +You can use it to set Common Test hooks, for example:

+
+
+
CT_OPTS = -ct_hooks cowboy_ct_hook
+

The CT_SUITES variable can be used to override what +Common Test suites Erlang.mk will be aware of. It does +not normally need to be set as Erlang.mk will find the +test suites automatically.

+

The name of the suite is the part before _SUITE.erl. +If the file is named http_SUITE.erl, the test suite +is http:

+
+
+
CT_SUITES = http ws
+
+
+
+

Usage

+
+

To run all tests (including Common Test):

+
+
+
$ make tests
+

To run all tests and static checks (including Common Test):

+
+
+
$ make check
+

You can also run Common Test separately:

+
+
+
$ make ct
+

Erlang.mk will create targets for all test suites it finds. +If you have a file named test/http_SUITE.erl, then the +target ct-http will run that specific test suite:

+
+
+
$ make ct-http
+

Erlang.mk provides a convenient way to run a specific +group or a specific test case within a specific group, +using the variable t. Note that this only applies to +suite-specific targets, like the ct-http example above.

+

To run all tests from the http_compress group in the +http_SUITE test suite, write:

+
+
+
$ make ct-http t=http_compress
+

Similarly, to run a specific test case in that group:

+
+
+
$ make ct-http t=http_compress:headers_dupe
+

To do the same against a multi-application repository, +you can use the -C option:

+
+
+
$ make -C apps/my_app ct-http t=my_group:my_case
+

Note that this also applies to dependencies. When using Cowboy +as a dependency, you can run the following directly:

+
+
+
$ make -C deps/cowboy ct-http t=http_compress
+

Finally, code coverage is available, +but covered in its own chapter.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/compat.asciidoc b/docs/en/erlang.mk/1/guide/compat.asciidoc new file mode 100644 index 00000000..8c8f935c --- /dev/null +++ b/docs/en/erlang.mk/1/guide/compat.asciidoc @@ -0,0 +1,90 @@ +[[compat]] +== Compatibility with other build tools + +Erlang.mk tries its best to be compatible with the other Erlang +build tools. It can use dependencies written with other build +tools in mind, and can also make your projects usable by those +build tools as well. Erlang.mk is like the cool kid that gets +along with everybody. + +In this chapter I will use the term _Rebar project_ to refer +to a project built using Rebar 2, Rebar 3 or Mad. These three +build tools are very similar and share the same configuration +file. + +=== Rebar projects as Erlang.mk dependencies + +Erlang.mk comes with a feature called _Autoload_ which will +use Rebar 2 to patch any Rebar project and make it compatible +with Erlang.mk. This feature essentially patches Rebar out +and adds a Makefile to the project that Erlang.mk can then +use for building: + +_Autoload_ is documented in more details in the +xref:deps[Packages and dependencies] chapter. + +=== Erlang.mk projects as Rebar dependencies + +Erlang.mk projects can be made compatible with the Rebar family +of build tools pretty easily, as Erlang.mk will generate +all the files they require for building. + +The Rebar family requires two files: a 'rebar.config' file +containing compilation options and the list of dependencies, +and the application resource file, found either at +'ebin/$(PROJECT).app' or at 'src/$(PROJECT).app.src'. + +==== Rebar configuration + +Erlang.mk comes with a target that generates a 'rebar.config' +file when invoked: + +[source,bash] +$ make rebar.config + +Careful! This will build the file even if it already existed +before. + +To build this file, Erlang.mk uses information it finds in +the `DEPS` and `ERLC_OPTS` variables, among others. This +means that the Rebar family builds your project much the +same way as Erlang.mk. + +// @todo Sanity check chapter. +Careful though! Different build tools have different fetching +strategies. If some applications provide differing dependencies, +they might be fetched differently by other build tools. Check +the upcoming Sanity check chapter to find out how to detect such +issues. + +You can automatically generate this file when you build +your application, by making it a dependency of the `app` +target: + +[source,make] +---- +app:: rebar.config +---- + +Don't forget to commit the file when it changes! + +If you run into other issues, it's probably because you use a +feature specific to Erlang.mk, like the `cp` fetch method. +It could also be that we forgot to handle something! Sorry. +We are of course interested to hear about any compatibility +problems you may have, just open a ticket! + +==== Application resource file + +Erlang.mk has two ways to generate an application resource +file: from the information found in the Makefile, or from +the information found in the 'src/$(PROJECT).app.src' file. +Needless to say, if you have this file in your repository, +then you don't need to worry about compatibility with other +build tools. + +If you don't, however, it's not much harder. Every time +Erlang.mk will compile your application, it will produce +a new 'ebin/$(PROJECT).app' file. Simply commit this file +when it changes. It will only change when you modify the +configuration, add or remove modules. diff --git a/docs/en/erlang.mk/1/guide/compat/index.html b/docs/en/erlang.mk/1/guide/compat/index.html new file mode 100644 index 00000000..6202c6a2 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/compat/index.html @@ -0,0 +1,220 @@ + + + + + + + + + + + + Nine Nines: Compatibility with other build tools + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Compatibility with other build tools

+ +

Erlang.mk tries its best to be compatible with the other Erlang +build tools. It can use dependencies written with other build +tools in mind, and can also make your projects usable by those +build tools as well. Erlang.mk is like the cool kid that gets +along with everybody.

+

In this chapter I will use the term Rebar project to refer +to a project built using Rebar 2, Rebar 3 or Mad. These three +build tools are very similar and share the same configuration +file.

+
+

Rebar projects as Erlang.mk dependencies

+
+

Erlang.mk comes with a feature called Autoload which will +use Rebar 2 to patch any Rebar project and make it compatible +with Erlang.mk. This feature essentially patches Rebar out +and adds a Makefile to the project that Erlang.mk can then +use for building:

+

Autoload is documented in more details in the +Packages and dependencies chapter.

+
+
+
+

Erlang.mk projects as Rebar dependencies

+
+

Erlang.mk projects can be made compatible with the Rebar family +of build tools pretty easily, as Erlang.mk will generate +all the files they require for building.

+

The Rebar family requires two files: a rebar.config file +containing compilation options and the list of dependencies, +and the application resource file, found either at +ebin/$(PROJECT).app or at src/$(PROJECT).app.src.

+
+

Rebar configuration

+

Erlang.mk comes with a target that generates a rebar.config +file when invoked:

+
+
+
$ make rebar.config
+

Careful! This will build the file even if it already existed +before.

+

To build this file, Erlang.mk uses information it finds in +the DEPS and ERLC_OPTS variables, among others. This +means that the Rebar family builds your project much the +same way as Erlang.mk.

+

Careful though! Different build tools have different fetching +strategies. If some applications provide differing dependencies, +they might be fetched differently by other build tools. Check +the upcoming Sanity check chapter to find out how to detect such +issues.

+

You can automatically generate this file when you build +your application, by making it a dependency of the app +target:

+
+
+
app:: rebar.config
+

Don’t forget to commit the file when it changes!

+

If you run into other issues, it’s probably because you use a +feature specific to Erlang.mk, like the cp fetch method. +It could also be that we forgot to handle something! Sorry. +We are of course interested to hear about any compatibility +problems you may have, just open a ticket!

+
+
+

Application resource file

+

Erlang.mk has two ways to generate an application resource +file: from the information found in the Makefile, or from +the information found in the src/$(PROJECT).app.src file. +Needless to say, if you have this file in your repository, +then you don’t need to worry about compatibility with other +build tools.

+

If you don’t, however, it’s not much harder. Every time +Erlang.mk will compile your application, it will produce +a new ebin/$(PROJECT).app file. Simply commit this file +when it changes. It will only change when you modify the +configuration, add or remove modules.

+
+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/contributing.asciidoc b/docs/en/erlang.mk/1/guide/contributing.asciidoc new file mode 100644 index 00000000..58e5de68 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/contributing.asciidoc @@ -0,0 +1,116 @@ +[[contributing]] +== Contributing + +You are welcome and encouraged to contribute. + +This is how. + +=== Priorities + +From the most important to the least important: + +* Bugs +* Package issues/additions +* Refactoring +* Features + +=== Bugs + +If you have found a bug, you should open a ticket. Include +everything relevant including the command you used, output, +a link to the code that triggers the issue, why you think +this is a bug, etc. + +If you think you have found a bug but you are not sure, you +should open a ticket as previously explained. + +If you have found a bug and you need it to be solved RIGHT +NOW, open a ticket as previously explained. + +Once you have opened a ticket, be patient, try to answer +questions in a timely manner and confirm that the bug was +indeed fixed when it is. + +If you can't be patient, either try to solve the bug and +contribute the fix back or become a paying customer. + +=== Code + +The code is located in the 'core/\*.mk' and 'plugins/\*.mk' files. +The tests are located in the 'test/Makefile' and 'test/*.mk' files. + +If you have a fix or a hack for a bug, you should open a +pull request. Any fix should include a test case that fails +before the fix and is working after. + +If you have a test case that reproduces a bug, but no fix for +it, you should open a pull request. + +Changes need to be tested with at least the `make check` +command. A specific test case can be tested using `make check c=CASE` +with `CASE` the name of the target to run. Output can be +modulated using the `V` variable, which is an integer +from 0 to 4. A typical use would be `make check c=dialyzer V=3`. +The value 4 is particular and shows expanded commands right +before they are executed. + +To run tests in parallel, use the `-j` option. It is generally +a good idea to also use the `-k` option to run all tests even +if one fails. For example: `make check -j 32 -k`. + +Some changes should be tested against all packages. Continue +reading for more details on testing them. + +=== Packages + +You can search existing packages using the `make search q=STRING` +command. This can be done both from an Erlang.mk project or +directly from the Erlang.mk repository. + +Packages can be added to the index using the `pkg_add.sh` script. + +[source,bash] +---- +$ git clone https://github.com/$YOURUSERNAME/erlang.mk +$ cd erlang.mk +$ ./pkg_add.sh cowboy git https://github.com/ninenines/cowboy 1.0.0 + http://ninenines.eu "Small, fast and modular HTTP server." +$ git push origin master +---- + +Before sending a pull request, you should test your package. +You can use the following command: `make check p=PACKAGE`, +where `PACKAGE` is the name of the package, for example +`cowboy`. + +To test all packages, the `make packages` command can be used. +This can take a long time. Some packages will fail with certain +versions of Erlang, or if a prerequisite is missing from your system. +You can of course speed things up using the `-j` and `-k` flags. + +After all packages have been tested, you can run the command +`make summary` to know what changed since the previous run. + +=== Documentation + +The documentation is always right. + +If you think you have found a mistake in the documentation, +this is a bug. You can either open a ticket or send a pull +request. + +To make sure that the documentation changes work, install +the listed xref:asciidoc[Requirements] on your system and +run `make docs`. + +=== Feature requests + +If you have an awesome idea or need something that Erlang.mk +doesn't provide yet, open a ticket. Provide as much detail as +possible. + +If you have code, great! Open a pull request as previously +explained. + +If not, you can still improve your feature request by writing +the related documentation. diff --git a/docs/en/erlang.mk/1/guide/contributing/index.html b/docs/en/erlang.mk/1/guide/contributing/index.html new file mode 100644 index 00000000..a8f35389 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/contributing/index.html @@ -0,0 +1,261 @@ + + + + + + + + + + + + Nine Nines: Contributing + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Contributing

+ +

You are welcome and encouraged to contribute.

+

This is how.

+
+

Priorities

+
+

From the most important to the least important:

+
    +
  • +

    +Bugs +

    +
    • +
  • +

    +Package issues/additions +

    +
    • +
  • +

    +Refactoring +

    +
    • +
  • +

    +Features +

    +
    • +
+
+
+
+

Bugs

+
+

If you have found a bug, you should open a ticket. Include +everything relevant including the command you used, output, +a link to the code that triggers the issue, why you think +this is a bug, etc.

+

If you think you have found a bug but you are not sure, you +should open a ticket as previously explained.

+

If you have found a bug and you need it to be solved RIGHT +NOW, open a ticket as previously explained.

+

Once you have opened a ticket, be patient, try to answer +questions in a timely manner and confirm that the bug was +indeed fixed when it is.

+

If you can’t be patient, either try to solve the bug and +contribute the fix back or become a paying customer.

+
+
+
+

Code

+
+

The code is located in the core/*.mk and plugins/*.mk files. +The tests are located in the test/Makefile and test/*.mk files.

+

If you have a fix or a hack for a bug, you should open a +pull request. Any fix should include a test case that fails +before the fix and is working after.

+

If you have a test case that reproduces a bug, but no fix for +it, you should open a pull request.

+

Changes need to be tested with at least the make check +command. A specific test case can be tested using make check c=CASE +with CASE the name of the target to run. Output can be +modulated using the V variable, which is an integer +from 0 to 4. A typical use would be make check c=dialyzer V=3. +The value 4 is particular and shows expanded commands right +before they are executed.

+

To run tests in parallel, use the -j option. It is generally +a good idea to also use the -k option to run all tests even +if one fails. For example: make check -j 32 -k.

+

Some changes should be tested against all packages. Continue +reading for more details on testing them.

+
+
+
+

Packages

+
+

You can search existing packages using the make search q=STRING +command. This can be done both from an Erlang.mk project or +directly from the Erlang.mk repository.

+

Packages can be added to the index using the pkg_add.sh script.

+
+
+
$ git clone https://github.com/$YOURUSERNAME/erlang.mk
+$ cd erlang.mk
+$ ./pkg_add.sh cowboy git https://github.com/ninenines/cowboy 1.0.0
+  http://ninenines.eu "Small, fast and modular HTTP server."
+$ git push origin master
+

Before sending a pull request, you should test your package. +You can use the following command: make check p=PACKAGE, +where PACKAGE is the name of the package, for example +cowboy.

+

To test all packages, the make packages command can be used. +This can take a long time. Some packages will fail with certain +versions of Erlang, or if a prerequisite is missing from your system. +You can of course speed things up using the -j and -k flags.

+

After all packages have been tested, you can run the command +make summary to know what changed since the previous run.

+
+
+
+

Documentation

+
+

The documentation is always right.

+

If you think you have found a mistake in the documentation, +this is a bug. You can either open a ticket or send a pull +request.

+

To make sure that the documentation changes work, install +the listed Requirements on your system and +run make docs.

+
+
+
+

Feature requests

+
+

If you have an awesome idea or need something that Erlang.mk +doesn’t provide yet, open a ticket. Provide as much detail as +possible.

+

If you have code, great! Open a pull request as previously +explained.

+

If not, you can still improve your feature request by writing +the related documentation.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/coverage.asciidoc b/docs/en/erlang.mk/1/guide/coverage.asciidoc new file mode 100644 index 00000000..f33f8783 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/coverage.asciidoc @@ -0,0 +1,6 @@ +[[coverage]] +== Code coverage + +// @todo Write it. + +Placeholder chapter. diff --git a/docs/en/erlang.mk/1/guide/coverage/index.html b/docs/en/erlang.mk/1/guide/coverage/index.html new file mode 100644 index 00000000..0be003b8 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/coverage/index.html @@ -0,0 +1,137 @@ + + + + + + + + + + + + Nine Nines: Code coverage + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Code coverage

+ +

Placeholder chapter.

+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/deps.asciidoc b/docs/en/erlang.mk/1/guide/deps.asciidoc new file mode 100644 index 00000000..eb6f2f0c --- /dev/null +++ b/docs/en/erlang.mk/1/guide/deps.asciidoc @@ -0,0 +1,472 @@ +[[deps]] +== Packages and dependencies + +Erlang.mk can fetch and compile the dependencies that your +project requires. Erlang.mk improves upon the concepts +introduced by Rebar, so they should be familiar to many +seasoned Erlang developers. + +Erlang.mk is not a package manager, nor is it trying to be, +but it does include an index of Erlang packages to make +discovering useful projects easier. + +This chapter will explain how to use packages, add +dependencies to your project or bundle them directly +in a single repository. + +=== Searching packages + +Erlang.mk gives you access to nearly 500 packages, with more +being added regularly. + +To find a package, search for it: + +[source,bash] +$ make search q=pool + +This will return all packages matching this word, like worker +pool and acceptor pool projects. + +You can also list everything and use regular command line +tools to find what you need, for example: + +[source,bash] +$ make search | less + +// @todo Simplify adding packages, add a new chapter explaining +// everything, then link to this new chapter from here. + +=== Adding dependencies to your project + +Once you find the package you need, adding it as a dependency +to your project is a one-liner: + +[source,make] +DEPS = cowboy + +And that's it! The next time you run `make`, Erlang.mk will +fetch and compile Cowboy. Erlang.mk will also ensure Cowboy +is available whenever you use the shell, run tests and any +other operations. + +Erlang.mk will fill in the application resource file with +all applications found in `DEPS`. But not all dependencies +are Erlang applications, and not all dependencies need to +be a runtime dependency. That's where the `BUILD_DEPS` +variable comes in: it works just like `DEPS`, except the +dependencies listed there will not be added as runtime +dependencies. + +For example, you could add a parse transform project like +this to make it available only at build time: + +[source,make] +BUILD_DEPS = erlando + +Or you could depend on a C project directly, if you are +building a NIF: + +[source,make] +BUILD_DEPS = leveldb +dep_leveldb = git https://github.com/basho/leveldb 2.1.3 + +This dependency will be built before your application, so +you could easily copy the resulting shared file into your +'priv/' directory as part of the build process. More information +about that in the xref:ports[NIFs and port drivers] +chapter. + +Another variable, `LOCAL_DEPS`, allows specifying runtime +dependencies which are part of Erlang/OTP itself, but also +dependencies that are included in the repository. Since they +are already on your system, there is no need to fetch them. +Do note that there is no way to choose the version, the +application used will be the one already on your system. + +You could depend on the Crypto application, for example: + +[source,make] +LOCAL_DEPS = crypto + +Erlang.mk comes with additional types of dependencies. +It has `TEST_DEPS` for dependencies used only for testing: + +[source,make] +TEST_DEPS = ct_helper +dep_ct_helper = git https://github.com/ninenines/ct_helper master + +`DOC_DEPS` for dependencies used only when building documentation: + +[source,make] +DOC_DEPS = edown + +`REL_DEPS` for dependencies required to build the release, +or to include extra applications in the release: + +[source,make] +REL_DEPS = recon + +And `SHELL_DEPS` for dependencies to make available when running +the `make shell` command: + +[source,make] +SHELL_DEPS = tddreloader + +All these will be documented in more details in their respective +chapters. + +==== Modifying the dependency source or version + +By default, Erlang.mk will look into its package index to +find the project you are looking for, if you only provide +its name. This is this case: + +[source,make] +DEPS = cowboy + +If you need a different version, you need to define another +variable. There are two ways to do this, each being useful +for different reasons. + +If you simply want to change the commit number, all you +need to do is to define the `dep_$(DEP_NAME)_commit` +variable. In the case of Cowboy, this would look like this: + +[source,make] +DEPS = cowboy +dep_cowboy_commit = 2.0.0-pre.2 + +Erlang.mk will use the package index to get all information +about Cowboy, except the commit number which will be overriden. + +If you need to set the fetch method or repository information +too, for example because you want to use your own fork, or +simply because the project is missing from the index, you +can define the `dep_$(DEP_NAME)` variable with everything: + +[source,make] +DEPS = cowboy +dep_cowboy = git https://github.com/essen/cowboy 2.0.0-pre.2 + +This will fetch Cowboy from your fork at the given commit. + +==== Fetch methods + +Erlang.mk comes with a number of different fetch methods. +You can fetch from Git, Mercurial, SVN, to name a few. +There are fetch methods that will work everywhere, and +fetch methods that will only work in a given environment. + +The following table lists all existing methods: + +[cols="<,2*^",options="header"] +|=== +| Name | Format | Description +| git | git repo commit | Clone the Git repository and checkout the given version +| git-submodule | git-submodule | Initialize and update the Git submodule +| hg | hg repo commit | Clone the Mercurial repository and update to the given version +| svn | svn repo | Checkout the given SVN repository +| cp | cp path/to/repo | Recursively copy a local directory +| hex | hex version | Download the given project version from hex.pm +| fail | N/A | Always fail, reserved for internal use +| legacy | N/A | Legacy Erlang.mk fetcher, reserved for internal use +|=== + +The `git` and `hg` methods both have a repository and commit. +You can use any valid commit, tag or branch in that repository +for the commit value. + +For example, to fetch Cowboy with tag 2.0.0-pre.2 from Git: + +[source,make] +dep_cowboy = git https://github.com/ninenines/cowboy 2.0.0-pre.2 + +Or to fetch Ehsa tag 4.0.3 from Mercurial: + +[source,make] +dep_ehsa = hg https://bitbucket.org/a12n/ehsa 4.0.3 + +Git also comes with a concept of submodules. Erlang.mk can +automatically initializes and updates submodules for dependencies, +as long as they were added beforehand using `git submodule add`: + +[source,make] +dep_cowboy = git-submodule + +The `svn` method only has a repository value, but that's +simply because the SVN repository URL can also contain +the path and commit. + +This would fetch an example project from the trunk: + +[source,make] +dep_ex1 = svn https://example.com/svn/trunk/project/ex1 + +And this would fetch a separate example project from a +specific commit: + +[source,make] +dep_ex2 = svn svn://example.com/svn/branches/erlang-proj/ex2@264 + +You can copy a directory from your machine using the `cp` method. +It only takes the path to copy from: + +[source,make] +dep_cowboy = cp $(HOME)/ninenines/cowboy + +Finally, you can use a package from the +link:https://hex.pm/[Hex repository]: + +[source,make] +dep_cowboy = hex 1.0.3 + +==== Custom fetch methods + +If none of the existing methods fit your use, you can simply +define your own. Erlang.mk will consider all variables that +are named as `dep_fetch_$(METHOD)` to be available fetch +methods. You can do anything inside this variable, as long +as you create a folder named '$(DEPS_DIR)/$(call dep_name,$1)'. +Or in layman terms, if your dependency is Cowboy, this would +become 'deps/cowboy'. + +To give an example, this is what the Git method does: + +[source,make] +---- +define dep_fetch_git + git clone -q -n -- $(call dep_repo,$1) $(DEPS_DIR)/$(call dep_name,$1); \ + cd $(DEPS_DIR)/$(call dep_name,$1) && git checkout -q $(call dep_commit,$1); +endef +---- + +Note that, like dependency information, this custom fetch method +must be written before including 'erlang.mk'. + +=== How deps are fetched and built + +The order in which dependencies are fetched and built is well +defined. This means that Erlang.mk will get the same applications +regardless of the command or options being used. + +In tree traversal terms, where the list of dependencies is a +tree, Erlang.mk fetches everything using the pre-order traversal +method. The steps can be summarized like this, starting from +the root application: + +. Fetch all dependencies for the application +. Build first dependency +. Build Nth dependency +. Build last dependency + +Every time a dependency is built, these same steps are followed, +recursively. + +Do note that the first step, fetching all dependencies of +an application, is not guaranteed to be ordered. The reason +for this is that it is not possible to have the same dependency +listed twice in a single application, and therefore there can +be no conflicts. Remember, this step only fetches, at no point +are different applications built in parallel. + +What about conflicts between the dependencies of different +applications? Simple. Since builds are ordered, this means +that the first version of an application that is fetched +will be the one that wins. + +This means that if project A depends on projects B and C, +in this order, and that both B and C depend on a different +version of D, it will always be B's version of D that wins, +because we fetch the dependencies of B before fetching +those from C. + +Similarly, if project A depends on projects B, C and D, +regardless of the order, and A, B and C depend on a +different version of D, it will always be A's version +that wins, because we fetch all dependencies of A before +fetching those from B or C. + +=== Ignoring unwanted dependencies + +Sometimes, you may want to ignore dependencies entirely. +Not even fetch them. You may want to do this because a +project you depend on depends on an application you do +not need (like a dependency for building documentation +or testing). Or maybe the dependency is already installed +on your system. + +To ignore a dependency, simply add it to the `IGNORE_DEPS` +variable: + +[source,make] +IGNORE_DEPS += edown proper + +This will only ignore dependencies that are needed for +building. It is therefore safe to write: + +[source,make] +IGNORE_DEPS += edown proper +TEST_DEPS = proper + +The PropEr application will be fetched as intended when +running `make tests` or `make check`. It will however +not be fetched when running `make` or `make deps`. + +=== Dependencies directory + +Dependencies are fetched in '$(DEPS_DIR)'. By default this is +the 'deps' directory. You can change this default, but you +should only do so if it was not defined previously. Erlang.mk +uses this variable to tell dependencies where to fetch their +own dependencies. + +You will therefore need to use `?=` instead of `=`. Of course, +if you know you will never use this project as a dependency, +`=` will work. But to avoid it biting you later on, do this: + +[source,make] +DEPS_DIR ?= $(CURDIR)/libs + +The `$(CURDIR)` part is important, otherwise dependencies of +dependencies will be fetched in the wrong directory. + +Erlang.mk will also export the `REBAR_DEPS_DIR` variable for +compatibility with Rebar build tools, as long as they are +recent enough. + +=== Many applications in one repository + +In addition to the dependencies that are fetched, Erlang.mk +also allows you to have dependencies local to your repository. +This kind of layout is sometimes called multi-application +repositories, or repositories with multiple applications. + +They work exactly the same as remote dependencies, except: + +* They are not fetched +* They are not autopatched +* They are not deleted on `make distclean` +* They are not automatically added to the application resource file + +To properly fill the application resource file, you will +need to define the `LOCAL_DEPS` variable for each relevant +application, the same as for OTP applications. + +If there is a conflict between a local dependency and a +remote dependency, then the local dependency always wins; +an error will be triggered when trying to fetch the +conflicting remote dependency. + +To start using dependencies local to the repository, simply +create a folder named '$(APPS_DIR)'. By default, this folder +is the 'apps/' directory. + +You can use Erlang.mk to bootstrap local dependencies by +using the command `make new-app` or `make new-lib`. This +command will create the necessary directories and bootstrap +the application. + +For example, to create a full fledged OTP application as +a local dependency: + +[source,bash] +$ make new-app in=webchat + +Or, the same as an OTP library: + +[source,bash] +$ make new-lib in=webchat + +Templates also work with local dependencies, from the root +directory of the project. You do need however to tell +Erlang.mk to create the files in the correct application: + +[source,bash] +$ make new t=gen_server n=my_server in=webchat + +=== Repositories with no application at the root level + +It's possible to use Erlang.mk with only applications in +'$(APPS_DIR)', and nothing at the root of the repository. +Just create a folder, put the 'erlang.mk' file in it, +write a Makefile that includes it, and start creating +your applications. + +Similarly, it's possible to have a repository with only +dependencies found in '$(DEPS_DIR)'. You just need to +create a Makefile and specify the dependencies you want. +This allows you to create a repository for handling the +building of releases, for example. + +=== Autopatch + +Erlang.mk will automatically patch all the dependencies it +fetches. It needs to do this to ensure that the dependencies +become compatible with not only Erlang.mk, but also with +the version of Erlang.mk that is currently used. + +When fetching a dependency, the following operations are +performed: + +* Fetch the dependency using the configured fetch method +* If it contains a 'configure.ac' or 'configure.in' file, run `autoreconf -Wall -vif -I m4` +* If it contains a 'configure' script, run it +* Run autopatch on the project + +Autopatch first checks if there is any project-specific patch +enabled. There are currently two: `RABBITMQ_CLIENT_PATCH` for +the `amqp_client` dependency, and `RABBITMQ_SERVER_PATCH` for +the `rabbit` dependency. These are needed only for RabbitMQ +versions before 3.6.0 (assuming you are using upstream RabbitMQ, +and not a fork). + +Otherwise, autopatch performs different operations depending +on the kind of project it finds the dependency to be. + +* Rebar projects are automatically converted to use Erlang.mk +as their build tool. This essentially patches Rebar out, and +fixes and converts the project to be compatible with Erlang.mk. + +* Erlang.mk projects have their 'erlang.mk' file redirect to +the top-level project's Erlang.mk. This is to ensure that +functionality works across all dependencies, even if the +dependency's Erlang.mk is outdated. + +* Other Erlang projects get a small Erlang.mk Makefile +generated automatically. + +* Projects with no source directory and no Makefile get an +empty Makefile generated, for compatibility purposes. + +* Other projects with no Makefile are left untouched. + +You can disable the replacing of the 'erlang.mk' file by +defining the `NO_AUTOPATCH_ERLANG_MK` variable: + +[source,make] +NO_AUTOPATCH_ERLANG_MK = 1 + +You can also disable autopatch entirely for a few select +projects using the `NO_AUTOPATCH` variable: + +[source,make] +NO_AUTOPATCH = cowboy ranch cowlib + +=== Skipping deps + +It is possible to temporarily skip all dependency operations. +This is done by defining the `SKIP_DEPS` variable. Use cases +include being somewhere with no connection to download them, +or perhaps a peculiar setup. + +A typical usage would be: + +[source,bash] +$ make SKIP_DEPS=1 + +When the variable is defined: + +* Dependencies will not be compiled or downloaded when required +* The dependency directory '$(DEPS_DIR)' will not be removed on `make distclean` + +This variable only applies to remote dependencies. diff --git a/docs/en/erlang.mk/1/guide/deps/index.html b/docs/en/erlang.mk/1/guide/deps/index.html new file mode 100644 index 00000000..ad4a3523 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/deps/index.html @@ -0,0 +1,768 @@ + + + + + + + + + + + + Nine Nines: Packages and dependencies + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Packages and dependencies

+ +

Erlang.mk can fetch and compile the dependencies that your +project requires. Erlang.mk improves upon the concepts +introduced by Rebar, so they should be familiar to many +seasoned Erlang developers.

+

Erlang.mk is not a package manager, nor is it trying to be, +but it does include an index of Erlang packages to make +discovering useful projects easier.

+

This chapter will explain how to use packages, add +dependencies to your project or bundle them directly +in a single repository.

+
+

Searching packages

+
+

Erlang.mk gives you access to nearly 500 packages, with more +being added regularly.

+

To find a package, search for it:

+
+
+
$ make search q=pool
+

This will return all packages matching this word, like worker +pool and acceptor pool projects.

+

You can also list everything and use regular command line +tools to find what you need, for example:

+
+
+
$ make search | less
+
+
+
+

Adding dependencies to your project

+
+

Once you find the package you need, adding it as a dependency +to your project is a one-liner:

+
+
+
DEPS = cowboy
+

And that’s it! The next time you run make, Erlang.mk will +fetch and compile Cowboy. Erlang.mk will also ensure Cowboy +is available whenever you use the shell, run tests and any +other operations.

+

Erlang.mk will fill in the application resource file with +all applications found in DEPS. But not all dependencies +are Erlang applications, and not all dependencies need to +be a runtime dependency. That’s where the BUILD_DEPS +variable comes in: it works just like DEPS, except the +dependencies listed there will not be added as runtime +dependencies.

+

For example, you could add a parse transform project like +this to make it available only at build time:

+
+
+
BUILD_DEPS = erlando
+

Or you could depend on a C project directly, if you are +building a NIF:

+
+
+
BUILD_DEPS = leveldb
+dep_leveldb = git https://github.com/basho/leveldb 2.1.3
+

This dependency will be built before your application, so +you could easily copy the resulting shared file into your +priv/ directory as part of the build process. More information +about that in the NIFs and port drivers +chapter.

+

Another variable, LOCAL_DEPS, allows specifying runtime +dependencies which are part of Erlang/OTP itself, but also +dependencies that are included in the repository. Since they +are already on your system, there is no need to fetch them. +Do note that there is no way to choose the version, the +application used will be the one already on your system.

+

You could depend on the Crypto application, for example:

+
+
+
LOCAL_DEPS = crypto
+

Erlang.mk comes with additional types of dependencies. +It has TEST_DEPS for dependencies used only for testing:

+
+
+
TEST_DEPS = ct_helper
+dep_ct_helper = git https://github.com/ninenines/ct_helper master
+

DOC_DEPS for dependencies used only when building documentation:

+
+
+
DOC_DEPS = edown
+

REL_DEPS for dependencies required to build the release, +or to include extra applications in the release:

+
+
+
REL_DEPS = recon
+

And SHELL_DEPS for dependencies to make available when running +the make shell command:

+
+
+
SHELL_DEPS = tddreloader
+

All these will be documented in more details in their respective +chapters.

+
+

Modifying the dependency source or version

+

By default, Erlang.mk will look into its package index to +find the project you are looking for, if you only provide +its name. This is this case:

+
+
+
DEPS = cowboy
+

If you need a different version, you need to define another +variable. There are two ways to do this, each being useful +for different reasons.

+

If you simply want to change the commit number, all you +need to do is to define the dep_$(DEP_NAME)_commit +variable. In the case of Cowboy, this would look like this:

+
+
+
DEPS = cowboy
+dep_cowboy_commit = 2.0.0-pre.2
+

Erlang.mk will use the package index to get all information +about Cowboy, except the commit number which will be overriden.

+

If you need to set the fetch method or repository information +too, for example because you want to use your own fork, or +simply because the project is missing from the index, you +can define the dep_$(DEP_NAME) variable with everything:

+
+
+
DEPS = cowboy
+dep_cowboy = git https://github.com/essen/cowboy 2.0.0-pre.2
+

This will fetch Cowboy from your fork at the given commit.

+
+
+

Fetch methods

+

Erlang.mk comes with a number of different fetch methods. +You can fetch from Git, Mercurial, SVN, to name a few. +There are fetch methods that will work everywhere, and +fetch methods that will only work in a given environment.

+

The following table lists all existing methods:

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Name Format Description

git

git repo commit

Clone the Git repository and checkout the given version

git-submodule

git-submodule

Initialize and update the Git submodule

hg

hg repo commit

Clone the Mercurial repository and update to the given version

svn

svn repo

Checkout the given SVN repository

cp

cp path/to/repo

Recursively copy a local directory

hex

hex version

Download the given project version from hex.pm

fail

N/A

Always fail, reserved for internal use

legacy

N/A

Legacy Erlang.mk fetcher, reserved for internal use

+
+

The git and hg methods both have a repository and commit. +You can use any valid commit, tag or branch in that repository +for the commit value.

+

For example, to fetch Cowboy with tag 2.0.0-pre.2 from Git:

+
+
+
dep_cowboy = git https://github.com/ninenines/cowboy 2.0.0-pre.2
+

Or to fetch Ehsa tag 4.0.3 from Mercurial:

+
+
+
dep_ehsa = hg https://bitbucket.org/a12n/ehsa 4.0.3
+

Git also comes with a concept of submodules. Erlang.mk can +automatically initializes and updates submodules for dependencies, +as long as they were added beforehand using git submodule add:

+
+
+
dep_cowboy = git-submodule
+

The svn method only has a repository value, but that’s +simply because the SVN repository URL can also contain +the path and commit.

+

This would fetch an example project from the trunk:

+
+
+
dep_ex1 = svn https://example.com/svn/trunk/project/ex1
+

And this would fetch a separate example project from a +specific commit:

+
+
+
dep_ex2 = svn svn://example.com/svn/branches/erlang-proj/ex2@264
+

You can copy a directory from your machine using the cp method. +It only takes the path to copy from:

+
+
+
dep_cowboy = cp $(HOME)/ninenines/cowboy
+

Finally, you can use a package from the +Hex repository:

+
+
+
dep_cowboy = hex 1.0.3
+
+
+

Custom fetch methods

+

If none of the existing methods fit your use, you can simply +define your own. Erlang.mk will consider all variables that +are named as dep_fetch_$(METHOD) to be available fetch +methods. You can do anything inside this variable, as long +as you create a folder named $(DEPS_DIR)/$(call dep_name,$1). +Or in layman terms, if your dependency is Cowboy, this would +become deps/cowboy.

+

To give an example, this is what the Git method does:

+
+
+
define dep_fetch_git
+        git clone -q -n -- $(call dep_repo,$1) $(DEPS_DIR)/$(call dep_name,$1); \
+        cd $(DEPS_DIR)/$(call dep_name,$1) && git checkout -q $(call dep_commit,$1);
+endef
+

Note that, like dependency information, this custom fetch method +must be written before including erlang.mk.

+
+
+
+
+

How deps are fetched and built

+
+

The order in which dependencies are fetched and built is well +defined. This means that Erlang.mk will get the same applications +regardless of the command or options being used.

+

In tree traversal terms, where the list of dependencies is a +tree, Erlang.mk fetches everything using the pre-order traversal +method. The steps can be summarized like this, starting from +the root application:

+
    +
  1. +

    +Fetch all dependencies for the application +

    +
    2. +
  2. +

    +Build first dependency +

    +
    3. +
  3. +

    +Build Nth dependency +

    +
    4. +
  4. +

    +Build last dependency +

    +
    5. +
+

Every time a dependency is built, these same steps are followed, +recursively.

+

Do note that the first step, fetching all dependencies of +an application, is not guaranteed to be ordered. The reason +for this is that it is not possible to have the same dependency +listed twice in a single application, and therefore there can +be no conflicts. Remember, this step only fetches, at no point +are different applications built in parallel.

+

What about conflicts between the dependencies of different +applications? Simple. Since builds are ordered, this means +that the first version of an application that is fetched +will be the one that wins.

+

This means that if project A depends on projects B and C, +in this order, and that both B and C depend on a different +version of D, it will always be B’s version of D that wins, +because we fetch the dependencies of B before fetching +those from C.

+

Similarly, if project A depends on projects B, C and D, +regardless of the order, and A, B and C depend on a +different version of D, it will always be A’s version +that wins, because we fetch all dependencies of A before +fetching those from B or C.

+
+
+
+

Ignoring unwanted dependencies

+
+

Sometimes, you may want to ignore dependencies entirely. +Not even fetch them. You may want to do this because a +project you depend on depends on an application you do +not need (like a dependency for building documentation +or testing). Or maybe the dependency is already installed +on your system.

+

To ignore a dependency, simply add it to the IGNORE_DEPS +variable:

+
+
+
IGNORE_DEPS += edown proper
+

This will only ignore dependencies that are needed for +building. It is therefore safe to write:

+
+
+
IGNORE_DEPS += edown proper
+TEST_DEPS = proper
+

The PropEr application will be fetched as intended when +running make tests or make check. It will however +not be fetched when running make or make deps.

+
+
+
+

Dependencies directory

+
+

Dependencies are fetched in $(DEPS_DIR). By default this is +the deps directory. You can change this default, but you +should only do so if it was not defined previously. Erlang.mk +uses this variable to tell dependencies where to fetch their +own dependencies.

+

You will therefore need to use ?= instead of =. Of course, +if you know you will never use this project as a dependency, += will work. But to avoid it biting you later on, do this:

+
+
+
DEPS_DIR ?= $(CURDIR)/libs
+

The $(CURDIR) part is important, otherwise dependencies of +dependencies will be fetched in the wrong directory.

+

Erlang.mk will also export the REBAR_DEPS_DIR variable for +compatibility with Rebar build tools, as long as they are +recent enough.

+
+
+
+

Many applications in one repository

+
+

In addition to the dependencies that are fetched, Erlang.mk +also allows you to have dependencies local to your repository. +This kind of layout is sometimes called multi-application +repositories, or repositories with multiple applications.

+

They work exactly the same as remote dependencies, except:

+
    +
  • +

    +They are not fetched +

    +
    • +
  • +

    +They are not autopatched +

    +
    • +
  • +

    +They are not deleted on make distclean +

    +
    • +
  • +

    +They are not automatically added to the application resource file +

    +
    • +
+

To properly fill the application resource file, you will +need to define the LOCAL_DEPS variable for each relevant +application, the same as for OTP applications.

+

If there is a conflict between a local dependency and a +remote dependency, then the local dependency always wins; +an error will be triggered when trying to fetch the +conflicting remote dependency.

+

To start using dependencies local to the repository, simply +create a folder named $(APPS_DIR). By default, this folder +is the apps/ directory.

+

You can use Erlang.mk to bootstrap local dependencies by +using the command make new-app or make new-lib. This +command will create the necessary directories and bootstrap +the application.

+

For example, to create a full fledged OTP application as +a local dependency:

+
+
+
$ make new-app in=webchat
+

Or, the same as an OTP library:

+
+
+
$ make new-lib in=webchat
+

Templates also work with local dependencies, from the root +directory of the project. You do need however to tell +Erlang.mk to create the files in the correct application:

+
+
+
$ make new t=gen_server n=my_server in=webchat
+
+
+
+

Repositories with no application at the root level

+
+

It’s possible to use Erlang.mk with only applications in +$(APPS_DIR), and nothing at the root of the repository. +Just create a folder, put the erlang.mk file in it, +write a Makefile that includes it, and start creating +your applications.

+

Similarly, it’s possible to have a repository with only +dependencies found in $(DEPS_DIR). You just need to +create a Makefile and specify the dependencies you want. +This allows you to create a repository for handling the +building of releases, for example.

+
+
+
+

Autopatch

+
+

Erlang.mk will automatically patch all the dependencies it +fetches. It needs to do this to ensure that the dependencies +become compatible with not only Erlang.mk, but also with +the version of Erlang.mk that is currently used.

+

When fetching a dependency, the following operations are +performed:

+
    +
  • +

    +Fetch the dependency using the configured fetch method +

    +
    • +
  • +

    +If it contains a configure.ac or configure.in file, run autoreconf -Wall -vif -I m4 +

    +
    • +
  • +

    +If it contains a configure script, run it +

    +
    • +
  • +

    +Run autopatch on the project +

    +
    • +
+

Autopatch first checks if there is any project-specific patch +enabled. There are currently two: RABBITMQ_CLIENT_PATCH for +the amqp_client dependency, and RABBITMQ_SERVER_PATCH for +the rabbit dependency. These are needed only for RabbitMQ +versions before 3.6.0 (assuming you are using upstream RabbitMQ, +and not a fork).

+

Otherwise, autopatch performs different operations depending +on the kind of project it finds the dependency to be.

+
    +
  • +

    +Rebar projects are automatically converted to use Erlang.mk +as their build tool. This essentially patches Rebar out, and +fixes and converts the project to be compatible with Erlang.mk. +

    +
    • +
  • +

    +Erlang.mk projects have their erlang.mk file redirect to +the top-level project’s Erlang.mk. This is to ensure that +functionality works across all dependencies, even if the +dependency’s Erlang.mk is outdated. +

    +
    • +
  • +

    +Other Erlang projects get a small Erlang.mk Makefile +generated automatically. +

    +
    • +
  • +

    +Projects with no source directory and no Makefile get an +empty Makefile generated, for compatibility purposes. +

    +
    • +
  • +

    +Other projects with no Makefile are left untouched. +

    +
    • +
+

You can disable the replacing of the erlang.mk file by +defining the NO_AUTOPATCH_ERLANG_MK variable:

+
+
+
NO_AUTOPATCH_ERLANG_MK = 1
+

You can also disable autopatch entirely for a few select +projects using the NO_AUTOPATCH variable:

+
+
+
NO_AUTOPATCH = cowboy ranch cowlib
+
+
+
+

Skipping deps

+
+

It is possible to temporarily skip all dependency operations. +This is done by defining the SKIP_DEPS variable. Use cases +include being somewhere with no connection to download them, +or perhaps a peculiar setup.

+

A typical usage would be:

+
+
+
$ make SKIP_DEPS=1
+

When the variable is defined:

+
    +
  • +

    +Dependencies will not be compiled or downloaded when required +

    +
    • +
  • +

    +The dependency directory $(DEPS_DIR) will not be removed on make distclean +

    +
    • +
+

This variable only applies to remote dependencies.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/dialyzer.asciidoc b/docs/en/erlang.mk/1/guide/dialyzer.asciidoc new file mode 100644 index 00000000..58fe53ff --- /dev/null +++ b/docs/en/erlang.mk/1/guide/dialyzer.asciidoc @@ -0,0 +1,73 @@ +[[dialyzer]] +== Dialyzer + +Dialyzer is a tool that will detect discrepancies in your +program. It does so using a technique known as success +typing analysis which has the advantage of providing no +false positives. Dialyzer is able to detect type errors, +dead code and more. + +Erlang.mk provides a wrapper around Dialyzer. + +=== How it works + +Dialyzer requires a PLT file to work. The PLT file contains +the analysis information from all applications which are not +expected to change, or rarely do. These would be all the +dependencies of the application or applications you are +currently working on, including standard applications in +Erlang/OTP itself. + +Dialyzer can generate this PLT file. Erlang.mk includes rules +to automatically generate the PLT file when it is missing. + +Once the PLT file is generated, Dialyzer can perform the +analysis in record time. + +=== Configuration + +In a typical usage scenario, no variable needs to be set. +The defaults should be enough. Do note however that the +dependencies need to be set properly using the `DEPS` and +`LOCAL_DEPS` variables. + +The `DIALYZER_PLT` file indicates where the PLT file will +be written to (and read from). By default this is +'$(PROJECT).plt' in the project's directory. Note that +the `DIALYZER_PLT` variable is exported and is understood +by Dialyzer directly. + +The `PLT_APPS` variable can be used to add additional +applications to the PLT. You can either list application +names or paths to these applications. + +Erlang.mk defines two variables for specifying options +for the analysis: `DIALYZER_DIRS` and `DIALYZER_OPTS`. +The former one defines which directories should be part +of the analysis. The latter defines what extra warnings +Dialyzer should report. + +Note that Erlang.mk enables the race condition warnings +by default. As it can take considerably large resources +to run, you may want to disable it on larger projects. + +=== Usage + +To perform an analysis, run the following command: + +[source,bash] +$ make dialyze + +This will create the PLT file if it doesn't exist. + +The analysis will also be performed when you run the +following command, alongside tests: + +[source,bash] +$ make check + +You can use the `plt` target to create the PLT file if +it doesn't exist. This is normally not necessary as +Dialyzer creates it automatically. + +The PLT file will be removed when you run `make distclean`. diff --git a/docs/en/erlang.mk/1/guide/dialyzer/index.html b/docs/en/erlang.mk/1/guide/dialyzer/index.html new file mode 100644 index 00000000..8846ff60 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/dialyzer/index.html @@ -0,0 +1,207 @@ + + + + + + + + + + + + Nine Nines: Dialyzer + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Dialyzer

+ +

Dialyzer is a tool that will detect discrepancies in your +program. It does so using a technique known as success +typing analysis which has the advantage of providing no +false positives. Dialyzer is able to detect type errors, +dead code and more.

+

Erlang.mk provides a wrapper around Dialyzer.

+
+

How it works

+
+

Dialyzer requires a PLT file to work. The PLT file contains +the analysis information from all applications which are not +expected to change, or rarely do. These would be all the +dependencies of the application or applications you are +currently working on, including standard applications in +Erlang/OTP itself.

+

Dialyzer can generate this PLT file. Erlang.mk includes rules +to automatically generate the PLT file when it is missing.

+

Once the PLT file is generated, Dialyzer can perform the +analysis in record time.

+
+
+
+

Configuration

+
+

In a typical usage scenario, no variable needs to be set. +The defaults should be enough. Do note however that the +dependencies need to be set properly using the DEPS and +LOCAL_DEPS variables.

+

The DIALYZER_PLT file indicates where the PLT file will +be written to (and read from). By default this is +$(PROJECT).plt in the project’s directory. Note that +the DIALYZER_PLT variable is exported and is understood +by Dialyzer directly.

+

The PLT_APPS variable can be used to add additional +applications to the PLT. You can either list application +names or paths to these applications.

+

Erlang.mk defines two variables for specifying options +for the analysis: DIALYZER_DIRS and DIALYZER_OPTS. +The former one defines which directories should be part +of the analysis. The latter defines what extra warnings +Dialyzer should report.

+

Note that Erlang.mk enables the race condition warnings +by default. As it can take considerably large resources +to run, you may want to disable it on larger projects.

+
+
+
+

Usage

+
+

To perform an analysis, run the following command:

+
+
+
$ make dialyze
+

This will create the PLT file if it doesn’t exist.

+

The analysis will also be performed when you run the +following command, alongside tests:

+
+
+
$ make check
+

You can use the plt target to create the PLT file if +it doesn’t exist. This is normally not necessary as +Dialyzer creates it automatically.

+

The PLT file will be removed when you run make distclean.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/edoc.asciidoc b/docs/en/erlang.mk/1/guide/edoc.asciidoc new file mode 100644 index 00000000..9fc1a740 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/edoc.asciidoc @@ -0,0 +1,48 @@ +[[edoc]] +== EDoc comments + +Erlang.mk provides a thin wrapper on top of EDoc, an application +that generates documentation based on comments found in modules. + +=== Writing EDoc comments + +The http://www.erlang.org/doc/apps/edoc/chapter.html[EDoc user guide] +explains everything you need to know about EDoc comments. + +=== Configuration + +The `EDOC_OPTS` variable allows you to specify additional +EDoc options. Options are documented in the +http://www.erlang.org/doc/man/edoc.html#run-2[EDoc manual]. + +A common use for this variable is to enable Markdown in doc +comments, using the `edown` application: + +[source,make] +DOC_DEPS = edown +EDOC_OPTS = {doclet, edown_doclet} + +=== Usage + +To build all documentation, you would typically use: + +[source,bash] +$ make docs + +Do note, however, that EDoc comments will only be generated +automatically if the 'doc/overview.edoc' file exists. If you +do not want that file and still want to generate doc comments, +two solutions are available. + +You can generate EDoc documentation directly: + +[source,bash] +$ make edoc + +You can enable automatic generation on `make docs` by adding +the following to your Makefile: + +[source,make] +---- +docs:: edoc +---- diff --git a/docs/en/erlang.mk/1/guide/edoc/index.html b/docs/en/erlang.mk/1/guide/edoc/index.html new file mode 100644 index 00000000..97ab6018 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/edoc/index.html @@ -0,0 +1,193 @@ + + + + + + + + + + + + Nine Nines: EDoc comments + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

EDoc comments

+ +

Erlang.mk provides a thin wrapper on top of EDoc, an application +that generates documentation based on comments found in modules.

+
+

Writing EDoc comments

+
+

The EDoc user guide +explains everything you need to know about EDoc comments.

+
+
+
+

Configuration

+
+

The EDOC_OPTS variable allows you to specify additional +EDoc options. Options are documented in the +EDoc manual.

+

A common use for this variable is to enable Markdown in doc +comments, using the edown application:

+
+
+
DOC_DEPS = edown
+EDOC_OPTS = {doclet, edown_doclet}
+
+
+
+

Usage

+
+

To build all documentation, you would typically use:

+
+
+
$ make docs
+

Do note, however, that EDoc comments will only be generated +automatically if the doc/overview.edoc file exists. If you +do not want that file and still want to generate doc comments, +two solutions are available.

+

You can generate EDoc documentation directly:

+
+
+
$ make edoc
+

You can enable automatic generation on make docs by adding +the following to your Makefile:

+
+
+
docs:: edoc
+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/escripts.asciidoc b/docs/en/erlang.mk/1/guide/escripts.asciidoc new file mode 100644 index 00000000..3d68c77b --- /dev/null +++ b/docs/en/erlang.mk/1/guide/escripts.asciidoc @@ -0,0 +1,6 @@ +[[escript]] +== Escripts + +// @todo Write it. + +Placeholder chapter. diff --git a/docs/en/erlang.mk/1/guide/escripts/index.html b/docs/en/erlang.mk/1/guide/escripts/index.html new file mode 100644 index 00000000..155ae1d3 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/escripts/index.html @@ -0,0 +1,137 @@ + + + + + + + + + + + + Nine Nines: Escripts + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Escripts

+ +

Placeholder chapter.

+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/eunit.asciidoc b/docs/en/erlang.mk/1/guide/eunit.asciidoc new file mode 100644 index 00000000..496b6749 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/eunit.asciidoc @@ -0,0 +1,122 @@ +[[eunit]] +== EUnit + +EUnit is the tool of choice for unit testing. Erlang.mk +automates a few things on top of EUnit, including the +discovery and running of unit tests. + +=== Writing tests + +The http://www.erlang.org/doc/apps/eunit/chapter.html[EUnit user guide] +is the best place to learn how to write tests. Of note is +that all functions ending with `_test` or `_test_` will be +picked up as EUnit test cases. + +Erlang.mk will automatically pick up tests found in any of +the Erlang modules of your application. It will also pick up +tests located in the '$(TEST_DIR)' directory, which defaults +to 'test/'. + +It is generally a good practice to hide test code from +the code you ship to production. With Erlang.mk, you can +do this thanks to the `TEST` macro. It is only defined +when running tests: + +[source,erlang] +---- +-ifdef(TEST). + +%% Insert tests here. + +-endif. +---- + +Be careful, however, if you include the EUnit header file, +as it also defines the `TEST` macro. Make sure to only include +it inside an `ifdef` block, otherwise tests will always be +compiled. + +[source,erlang] +---- +-ifdef(TEST). + +-include_lib(\"eunit/include/eunit.hrl\"). + +%% Insert tests here. + +-endif. +---- + +Erlang.mk will automatically recompile your code when you +perform a normal build after running tests, and vice versa. + +=== Configuration + +The `EUNIT_OPTS` variable allows you to specify additional +EUnit options. Options are documented in the +http://www.erlang.org/doc/man/eunit.html#test-2[EUnit manual]. +At the time of writing, the only available option is `verbose`: + +[source,make] +EUNIT_OPTS = verbose + +The `EUNIT_ERL_OPTS` variable allows you to specify options +to be passed to `erl` when running EUnit tests. For example, +you can load the 'vm.args' and 'sys.config' files: + +[source,make] +EUNIT_ERL_OPTS = -args_file rel/vm.args -config rel/sys.config + +=== Usage + +To run all tests (including EUnit): + +[source,bash] +$ make tests + +To run all tests and static checks (including EUnit): + +[source,bash] +$ make check + +You can also run EUnit separately: + +[source,bash] +$ make eunit + +EUnit will be quiet by default, only outputting errors. +You can easily make it verbose for a single invocation: + +[source,bash] +$ make eunit EUNIT_OPTS=verbose + +Erlang.mk allows you to run all tests from a specific +module, or a specific test case from that module, using +the variable `t`. + +For example, to run all tests from the `cow_http_hd` +module (instead of all tests from the entire project), +one could write: + +[source,bash] +$ make eunit t=cow_http_hd + +Similarly, to run a specific test case: + +[source,bash] +$ make eunit t=cow_http_hd:parse_accept_test_ + +To do the same against a multi-application repository, +you can use the `-C` option: + +[source,bash] +$ make -C apps/my_app eunit t=my_module:hello_test + +Note that this also applies to dependencies. From Cowboy, +you can run the following directly: + +[source,bash] +$ make -C deps/cowlib eunit t=cow_http_hd + +Finally, xref:coverage[code coverage] is available, +but covered in its own chapter. diff --git a/docs/en/erlang.mk/1/guide/eunit/index.html b/docs/en/erlang.mk/1/guide/eunit/index.html new file mode 100644 index 00000000..b4d2ca59 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/eunit/index.html @@ -0,0 +1,279 @@ + + + + + + + + + + + + Nine Nines: EUnit + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

EUnit

+ +

EUnit is the tool of choice for unit testing. Erlang.mk +automates a few things on top of EUnit, including the +discovery and running of unit tests.

+
+

Writing tests

+
+

The EUnit user guide +is the best place to learn how to write tests. Of note is +that all functions ending with _test or _test_ will be +picked up as EUnit test cases.

+

Erlang.mk will automatically pick up tests found in any of +the Erlang modules of your application. It will also pick up +tests located in the $(TEST_DIR) directory, which defaults +to test/.

+

It is generally a good practice to hide test code from +the code you ship to production. With Erlang.mk, you can +do this thanks to the TEST macro. It is only defined +when running tests:

+
+
+
-ifdef(TEST).
+
+%% Insert tests here.
+
+-endif.
+

Be careful, however, if you include the EUnit header file, +as it also defines the TEST macro. Make sure to only include +it inside an ifdef block, otherwise tests will always be +compiled.

+
+
+
-ifdef(TEST).
+
+-include_lib(\"eunit/include/eunit.hrl\").
+
+%% Insert tests here.
+
+-endif.
+

Erlang.mk will automatically recompile your code when you +perform a normal build after running tests, and vice versa.

+
+
+
+

Configuration

+
+

The EUNIT_OPTS variable allows you to specify additional +EUnit options. Options are documented in the +EUnit manual. +At the time of writing, the only available option is verbose:

+
+
+
EUNIT_OPTS = verbose
+

The EUNIT_ERL_OPTS variable allows you to specify options +to be passed to erl when running EUnit tests. For example, +you can load the vm.args and sys.config files:

+
+
+
EUNIT_ERL_OPTS = -args_file rel/vm.args -config rel/sys.config
+
+
+
+

Usage

+
+

To run all tests (including EUnit):

+
+
+
$ make tests
+

To run all tests and static checks (including EUnit):

+
+
+
$ make check
+

You can also run EUnit separately:

+
+
+
$ make eunit
+

EUnit will be quiet by default, only outputting errors. +You can easily make it verbose for a single invocation:

+
+
+
$ make eunit EUNIT_OPTS=verbose
+

Erlang.mk allows you to run all tests from a specific +module, or a specific test case from that module, using +the variable t.

+

For example, to run all tests from the cow_http_hd +module (instead of all tests from the entire project), +one could write:

+
+
+
$ make eunit t=cow_http_hd
+

Similarly, to run a specific test case:

+
+
+
$ make eunit t=cow_http_hd:parse_accept_test_
+

To do the same against a multi-application repository, +you can use the -C option:

+
+
+
$ make -C apps/my_app eunit t=my_module:hello_test
+

Note that this also applies to dependencies. From Cowboy, +you can run the following directly:

+
+
+
$ make -C deps/cowlib eunit t=cow_http_hd
+

Finally, code coverage is available, +but covered in its own chapter.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/external_plugins.asciidoc b/docs/en/erlang.mk/1/guide/external_plugins.asciidoc new file mode 100644 index 00000000..d3dafaac --- /dev/null +++ b/docs/en/erlang.mk/1/guide/external_plugins.asciidoc @@ -0,0 +1,77 @@ +[[plugins_usage]] +== External plugins + +It is often convenient to be able to keep the build files +used by all your projects in one place. Those files could +be Makefiles, configuration files, templates and more. + +Erlang.mk allows you to automatically load plugins from +dependencies. Plugins can do anything, including defining +new variables, defining file templates, hooking themselves +inside the normal Erlang.mk processing or even adding new +rules. + +You can load plugins using one of two methods. You can +either load all plugins from a dependency, or just one. +We will also cover conventions about writing external +plugins. + +=== Loading all plugins from a dependency + +To load plugins from a dependency, all you need to do is add +the dependency name to `DEP_PLUGINS` in addition to the list +of dependencies. + +For example, if you have `cowboy` in `DEPS`, add `cowboy` in +`DEP_PLUGINS` also: + +[source,make] +DEPS = cowboy +DEP_PLUGINS = cowboy + +This will load the file 'plugins.mk' in the root folder of +the Cowboy repository. + +=== Loading one plugin from a dependency + +Now that we know how to load all plugins, let's take a look +at how to load one specific plugin from a dependency. + +To do this, instead of writing only the name of the dependency, +we will write its name and the path to the plugin file. This +means that writing `DEP_PLUGINS = cowboy` is equivalent to +writing `DEP_PLUGINS = cowboy/plugins.mk`. + +Knowing this, if we were to load the plugin 'mk/dist.mk' +from Cowboy and no other, we would write the following in +our Makefile: + +[source,make] +DEPS = cowboy +DEP_PLUGINS = cowboy/mk/dist.mk + +=== Writing external plugins + +The 'plugins.mk' file is a convention. It is meant to load +all the plugins from the dependency. The code for the plugin +can be written directly in 'plugins.mk' or be separate. + +If you are providing more than one plugin with your repository, +the recommended way is to create one file per plugin in the +'mk/' folder in your repository, and then include those +individual plugins in 'plugins.mk'. + +For example, if you have two plugins 'mk/dist.mk' and +'mk/templates.mk', you could write the following 'plugins.mk' +file: + +[source,make] +THIS := $(dir $(realpath $(lastword $(MAKEFILE_LIST)))) +include $(THIS)/mk/dist.mk +include $(THIS)/mk/templates.mk + +The `THIS` variable is required to relatively include files. + +This allows users to not only be able to select individual +plugins, but also select all plugins from the dependency +in one go if they wish to do so. diff --git a/docs/en/erlang.mk/1/guide/external_plugins/index.html b/docs/en/erlang.mk/1/guide/external_plugins/index.html new file mode 100644 index 00000000..8b52c986 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/external_plugins/index.html @@ -0,0 +1,215 @@ + + + + + + + + + + + + Nine Nines: External plugins + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

External plugins

+ +

It is often convenient to be able to keep the build files +used by all your projects in one place. Those files could +be Makefiles, configuration files, templates and more.

+

Erlang.mk allows you to automatically load plugins from +dependencies. Plugins can do anything, including defining +new variables, defining file templates, hooking themselves +inside the normal Erlang.mk processing or even adding new +rules.

+

You can load plugins using one of two methods. You can +either load all plugins from a dependency, or just one. +We will also cover conventions about writing external +plugins.

+
+

Loading all plugins from a dependency

+
+

To load plugins from a dependency, all you need to do is add +the dependency name to DEP_PLUGINS in addition to the list +of dependencies.

+

For example, if you have cowboy in DEPS, add cowboy in +DEP_PLUGINS also:

+
+
+
DEPS = cowboy
+DEP_PLUGINS = cowboy
+

This will load the file plugins.mk in the root folder of +the Cowboy repository.

+
+
+
+

Loading one plugin from a dependency

+
+

Now that we know how to load all plugins, let’s take a look +at how to load one specific plugin from a dependency.

+

To do this, instead of writing only the name of the dependency, +we will write its name and the path to the plugin file. This +means that writing DEP_PLUGINS = cowboy is equivalent to +writing DEP_PLUGINS = cowboy/plugins.mk.

+

Knowing this, if we were to load the plugin mk/dist.mk +from Cowboy and no other, we would write the following in +our Makefile:

+
+
+
DEPS = cowboy
+DEP_PLUGINS = cowboy/mk/dist.mk
+
+
+
+

Writing external plugins

+
+

The plugins.mk file is a convention. It is meant to load +all the plugins from the dependency. The code for the plugin +can be written directly in plugins.mk or be separate.

+

If you are providing more than one plugin with your repository, +the recommended way is to create one file per plugin in the +mk/ folder in your repository, and then include those +individual plugins in plugins.mk.

+

For example, if you have two plugins mk/dist.mk and +mk/templates.mk, you could write the following plugins.mk +file:

+
+
+
THIS := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+include $(THIS)/mk/dist.mk
+include $(THIS)/mk/templates.mk
+

The THIS variable is required to relatively include files.

+

This allows users to not only be able to select individual +plugins, but also select all plugins from the dependency +in one go if they wish to do so.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc b/docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc new file mode 100644 index 00000000..f30797fd --- /dev/null +++ b/docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc @@ -0,0 +1,48 @@ +[[plugins_list]] +== List of plugins + +This is a non-exhaustive list of Erlang.mk plugins, sorted +alphabetically. + +=== efene.mk + +An https://github.com/ninenines/efene.mk[Efene plugin] for Erlang.mk. +http://efene.org/[Efene] is an alternative language for the BEAM. + +=== elixir.mk + +An https://github.com/botsunit/elixir.mk[Elixir plugin] for +Erlang.mk. http://elixir-lang.org/[Elixir] is an alternative +language for the BEAM. + +=== elvis.mk + +An https://github.com/inaka/elvis.mk[Elvis plugin] for Erlang.mk. +Elvis is an https://github.com/inaka/elvis[Erlang style reviewer]. + +=== geas + +https://github.com/crownedgrouse/geas[Geas] gives aggregated +information on a project and its dependencies, and is available +as an Erlang.mk plugin. + +=== hexer.mk + +An https://github.com/inaka/hexer.mk[Hex plugin] for Erlang.mk. +Hex is a https://hex.pm/[package manager for the Elixir ecosystem]. + +=== lfe.mk + +An https://github.com/ninenines/lfe.mk[LFE plugin] for Erlang.mk. +LFE, or http://lfe.io/[Lisp Flavoured Erlang], is an alternative +language for the BEAM. + +=== mix.mk + +A https://github.com/botsunit/mix.mk[Mix plugin] for Erlang.mk, +to generate a compatible configuration file for +http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html[Mix]. + +=== reload.mk + +A https://github.com/bullno1/reload.mk[live reload plugin] for Erlang.mk. diff --git a/docs/en/erlang.mk/1/guide/external_plugins_list/index.html b/docs/en/erlang.mk/1/guide/external_plugins_list/index.html new file mode 100644 index 00000000..405783c5 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/external_plugins_list/index.html @@ -0,0 +1,197 @@ + + + + + + + + + + + + Nine Nines: List of plugins + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

List of plugins

+ +

This is a non-exhaustive list of Erlang.mk plugins, sorted +alphabetically.

+
+

efene.mk

+
+

An Efene plugin for Erlang.mk. +Efene is an alternative language for the BEAM.

+
+
+
+

elixir.mk

+
+

An Elixir plugin for +Erlang.mk. Elixir is an alternative +language for the BEAM.

+
+
+
+

elvis.mk

+
+

An Elvis plugin for Erlang.mk. +Elvis is an Erlang style reviewer.

+
+
+
+

geas

+
+

Geas gives aggregated +information on a project and its dependencies, and is available +as an Erlang.mk plugin.

+
+
+
+

hexer.mk

+
+

An Hex plugin for Erlang.mk. +Hex is a package manager for the Elixir ecosystem.

+
+
+
+

lfe.mk

+
+

An LFE plugin for Erlang.mk. +LFE, or Lisp Flavoured Erlang, is an alternative +language for the BEAM.

+
+
+
+

mix.mk

+
+

A Mix plugin for Erlang.mk, +to generate a compatible configuration file for +Mix.

+
+
+
+

reload.mk

+
+

A live reload plugin for Erlang.mk.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/getting_started.asciidoc b/docs/en/erlang.mk/1/guide/getting_started.asciidoc new file mode 100644 index 00000000..ef2f6e8e --- /dev/null +++ b/docs/en/erlang.mk/1/guide/getting_started.asciidoc @@ -0,0 +1,299 @@ +[[getting_started]] +== Getting started + +This chapter explains how to get started using Erlang.mk. + +=== Creating a folder for your project + +The first step is always to create a new folder that will +contain your project. + +[source,bash] +$ mkdir hello_joe +$ cd hello_joe + +Most people tend to put all their projects side by side in +a common folder. We recommend keeping an organization similar +to your remote repositories. For example, for GitHub users, +put all your projects in a common folder with the same name +as your username. For example '$HOME/ninenines/cowboy' for +the Cowboy project. + +=== Downloading Erlang.mk + +At the time of writing, Erlang.mk is unlikely to be present +in your Erlang distribution, or even in your OS packages. + +The next step is therefore to download it: + +[source,bash] +$ wget https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk + +Or: + +[source,bash] +$ curl https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk + +Alternatively, just https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk[click on this link]. + +Make sure you put the file inside the folder we created previously. + +=== Getting started with OTP applications + +An OTP application is an Erlang application that has a supervision +tree. In other words, it will always have processes running. + +This kind of project can be automatically generated by Erlang.mk. +All you need to do is use the `bootstrap` target: + +[source,bash] +$ make -f erlang.mk bootstrap + +Something similar to the following snippet will then appear +on your screen: + +[source,bash] +---- +git clone https://github.com/ninenines/erlang.mk .erlang.mk.build +Cloning into '.erlang.mk.build'... +remote: Counting objects: 4035, done. +remote: Compressing objects: 100% (12/12), done. +remote: Total 4035 (delta 8), reused 4 (delta 4), pack-reused 4019 +Receiving objects: 100% (4035/4035), 1.10 MiB | 784.00 KiB/s, done. +Resolving deltas: 100% (2442/2442), done. +Checking connectivity... done. +if [ -f build.config ]; then cp build.config .erlang.mk.build; fi +cd .erlang.mk.build && make +make[1]: Entering directory '/home/essen/tmp/hello_joe/.erlang.mk.build' +awk 'FNR==1 && NR!=1{print ""}1' core/core.mk index/*.mk core/index.mk core/deps.mk plugins/protobuffs.mk core/erlc.mk core/docs.mk core/test.mk plugins/asciidoc.mk plugins/bootstrap.mk plugins/c_src.mk plugins/ci.mk plugins/ct.mk plugins/dialyzer.mk plugins/edoc.mk plugins/elvis.mk plugins/erlydtl.mk plugins/escript.mk plugins/eunit.mk plugins/relx.mk plugins/shell.mk plugins/triq.mk plugins/xref.mk plugins/cover.mk \ + | sed 's/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/' > erlang.mk +make[1]: Leaving directory '/home/essen/tmp/hello_joe/.erlang.mk.build' +cp .erlang.mk.build/erlang.mk ./erlang.mk +rm -rf .erlang.mk.build +---- + +This is Erlang.mk bootstrapping itself. Indeed, the file you +initially downloaded contains nothing more than the code needed +to bootstrap. This operation is done only once. Consult the +xref:updating[Updating Erlang.mk] chapter for more +information. + +Of course, the generated project can now be compiled: + +[source,bash] +$ make + +Cheers! + +=== Getting started with OTP libraries + +An OTP library is an Erlang application that has no supervision +tree. In other words, it is nothing but modules. + +This kind of project can also be generated by Erlang.mk, using +the `bootstrap-lib` target: + +[source,bash] +$ make -f erlang.mk bootstrap-lib + +Erlang.mk will once again bootstrap itself and generate all +the files for your project. You can now compile it: + +[source,bash] +$ make + +Enjoy! + +=== Getting started with OTP releases + +An OTP release is the combination of the Erlang RunTime System (ERTS) +along with all the libraries and files that your node will need +to run. It is entirely self contained, and can often be sent as-is +to your production system and run without any extra setup. + +Erlang.mk can of course bootstrap your project to generate releases. +You can use the `bootstrap-rel` target for this purpose: + +[source,bash] +$ make bootstrap-rel + +This target can be combined with `bootstrap` or `bootstrap-lib` to +create a project that will build a release: + +[source,bash] +$ make -f erlang.mk bootstrap-lib bootstrap-rel + +It is often very useful to keep the top-level project for +commands useful during operations, and put the components +of the system in separate applications that you will then +depend on. Consult the xref:deps[Packages and dependencies] +chapter for more information. + +When you run `make` from now on, Erlang.mk will compile your +project and build the release: + +[source,bash] +$ make + APP hello_joe.app.src + GEN distclean-relx-rel + GEN /home/essen/tmp/hello_joe/relx +===> Starting relx build process ... +===> Resolving OTP Applications from directories: + /home/essen/tmp/hello_joe/ebin + /usr/lib/erlang/lib + /home/essen/tmp/hello_joe/deps +===> Resolved hello_joe_release-1 +===> Including Erts from /usr/lib/erlang +===> release successfully created! + +The first time you run this command, Erlang.mk will download +_relx_, the release building tool. So don't worry if you see +more output than above. + +If building the release is slow, no need to upgrade your +hardware just yet. Just consult the xref:relx[Releases] +chapter for various tips to speed up build time during +development. + +You can start the release using the './_rel/hello_joe_release/bin/hello_joe_release' +script, or simply run `make run`. The latter will also compile +your project and build the release if it wasn't already: + +[source,bash] +---- +$ make run + APP hello_joe.app.src + GEN distclean-relx-rel +===> Starting relx build process ... +===> Resolving OTP Applications from directories: + /home/essen/tmp/hello_joe/ebin + /usr/lib/erlang/lib + /home/essen/tmp/hello_joe/deps +===> Resolved hello_joe_release-1 +===> Including Erts from /usr/lib/erlang +===> release successfully created! +Exec: /home/essen/tmp/hello_joe/_rel/hello_joe_release/erts-7.0/bin/erlexec -boot /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe/_rel/hello_joe_release/erts-7.0/../lib -env ERL_LIBS /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/lib -config /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/sys.config -args_file /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/vm.args -- console +Root: /home/essen/tmp/hello_joe/_rel/hello_joe_release +/home/essen/tmp/hello_joe/_rel/hello_joe_release +heart_beat_kill_pid = 16389 +Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false] + +Eshell V7.0 (abort with ^G) +(hello_joe@127.0.0.1)1> +---- + +Simple as that! + +=== Using spaces instead of tabs + +Erlang.mk defaults to tabs when creating files from templates. +This is in part because of a personal preference, and in part +because it is much easier to convert tabs to spaces than the +opposite. + +Use the `SP` variable if you prefer spaces. Set it to the number +of spaces per indentation level you want. + +For example, if you prefer two spaces per indentation level: + +[source,bash] +$ make -f erlang.mk bootstrap SP=2 + +When you bootstrap the project initially, the variable automatically +gets added to the Makefile, so you only need to provide it when +you get started. + +=== Using templates + +It is no secret that Erlang's OTP behaviors tend to have some +boilerplate. It is rarely an issue of course, except when +creating new modules. That's why Erlang.mk not only comes with +templates for generating projects, but also individual modules! + +You can list all available templates with the `list-templates` +target: + +[source,bash] +$ make list-templates +Available templates: cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor + +To generate a module, let's say a `gen_server`, all you need to +do is to call `make new` with the appropriate arguments: + +[source,bash] +$ make new t=gen_server n=my_server + +This will create a module located in 'src/my_server.erl' +using the `gen_server` template. + +This module is automatically compiled the next time you run +`make`: + +[source,bash] +$ make + ERLC my_server.erl + APP hello_joe.app.src + +All that's left to do is to open it in your favorite editor +and make it do something! + +=== Hiding Erlang.mk from git + +Erlang.mk is a large text file. It can easily take a large part of +a `git diff` or a `git grep` command. You can avoid this by telling +Git that 'erlang.mk' is a binary file. + +Add this to your '.gitattributes' file. This is a file that you +can create at the root of your repository: + +---- +erlang.mk -diff +---- + +The 'erlang.mk' file will still appear in diffs and greps, but +as a binary file, meaning its contents won't be shown by default +anymore. + +=== Getting help + +During development, if you don't remember the name of a target, +you can always run `make help`: + +[source,bash] +---- +$ make help +erlang.mk (version 1.2.0-642-gccd2b9f) is distributed under the terms of the ISC License. +Copyright (c) 2013-2015 Loïc Hoguin + +Usage: [V=1] make [target]... + +Core targets: + all Run deps, app and rel targets in that order + app Compile the project + deps Fetch dependencies (if needed) and compile them + search q=... Search for a package in the built-in index + rel Build a release for this project, if applicable + docs Build the documentation for this project + install-docs Install the man pages for this project + check Compile and run all tests and analysis for this project + tests Run the tests for this project + clean Delete temporary and output files from most targets + distclean Delete all temporary and output files + help Display this help and exit + erlang-mk Update erlang.mk to the latest version + +Bootstrap targets: + bootstrap Generate a skeleton of an OTP application + bootstrap-lib Generate a skeleton of an OTP library + bootstrap-rel Generate the files needed to build a release + new t=TPL n=NAME Generate a module NAME based on the template TPL + list-templates List available templates +... +---- + +This guide should provide any other answer. If not, please +open a ticket on https://github.com/ninenines/erlang.mk/issues[the official repository] +and we will work on improving the guide. + +Commercial support is available through Nine Nines. Please contact +Loïc Hoguin by sending an email to mailto:contact@ninenines.eu[]. diff --git a/docs/en/erlang.mk/1/guide/getting_started/index.html b/docs/en/erlang.mk/1/guide/getting_started/index.html new file mode 100644 index 00000000..5619b384 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/getting_started/index.html @@ -0,0 +1,462 @@ + + + + + + + + + + + + Nine Nines: Getting started + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Getting started

+ +

This chapter explains how to get started using Erlang.mk.

+
+

Creating a folder for your project

+
+

The first step is always to create a new folder that will +contain your project.

+
+
+
$ mkdir hello_joe
+$ cd hello_joe
+

Most people tend to put all their projects side by side in +a common folder. We recommend keeping an organization similar +to your remote repositories. For example, for GitHub users, +put all your projects in a common folder with the same name +as your username. For example $HOME/ninenines/cowboy for +the Cowboy project.

+
+
+
+

Downloading Erlang.mk

+
+

At the time of writing, Erlang.mk is unlikely to be present +in your Erlang distribution, or even in your OS packages.

+

The next step is therefore to download it:

+
+
+
$ wget https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk
+

Or:

+
+
+
$ curl https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk
+

Alternatively, just click on this link.

+

Make sure you put the file inside the folder we created previously.

+
+
+
+

Getting started with OTP applications

+
+

An OTP application is an Erlang application that has a supervision +tree. In other words, it will always have processes running.

+

This kind of project can be automatically generated by Erlang.mk. +All you need to do is use the bootstrap target:

+
+
+
$ make -f erlang.mk bootstrap
+

Something similar to the following snippet will then appear +on your screen:

+
+
+
git clone https://github.com/ninenines/erlang.mk .erlang.mk.build
+Cloning into '.erlang.mk.build'...
+remote: Counting objects: 4035, done.
+remote: Compressing objects: 100% (12/12), done.
+remote: Total 4035 (delta 8), reused 4 (delta 4), pack-reused 4019
+Receiving objects: 100% (4035/4035), 1.10 MiB | 784.00 KiB/s, done.
+Resolving deltas: 100% (2442/2442), done.
+Checking connectivity... done.
+if [ -f build.config ]; then cp build.config .erlang.mk.build; fi
+cd .erlang.mk.build && make
+make[1]: Entering directory '/home/essen/tmp/hello_joe/.erlang.mk.build'
+awk 'FNR==1 && NR!=1{print ""}1' core/core.mk index/*.mk core/index.mk core/deps.mk plugins/protobuffs.mk core/erlc.mk core/docs.mk core/test.mk plugins/asciidoc.mk plugins/bootstrap.mk plugins/c_src.mk plugins/ci.mk plugins/ct.mk plugins/dialyzer.mk plugins/edoc.mk plugins/elvis.mk plugins/erlydtl.mk plugins/escript.mk plugins/eunit.mk plugins/relx.mk plugins/shell.mk plugins/triq.mk plugins/xref.mk plugins/cover.mk \
+        | sed 's/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/' > erlang.mk
+make[1]: Leaving directory '/home/essen/tmp/hello_joe/.erlang.mk.build'
+cp .erlang.mk.build/erlang.mk ./erlang.mk
+rm -rf .erlang.mk.build
+

This is Erlang.mk bootstrapping itself. Indeed, the file you +initially downloaded contains nothing more than the code needed +to bootstrap. This operation is done only once. Consult the +Updating Erlang.mk chapter for more +information.

+

Of course, the generated project can now be compiled:

+
+
+
$ make
+

Cheers!

+
+
+
+

Getting started with OTP libraries

+
+

An OTP library is an Erlang application that has no supervision +tree. In other words, it is nothing but modules.

+

This kind of project can also be generated by Erlang.mk, using +the bootstrap-lib target:

+
+
+
$ make -f erlang.mk bootstrap-lib
+

Erlang.mk will once again bootstrap itself and generate all +the files for your project. You can now compile it:

+
+
+
$ make
+

Enjoy!

+
+
+
+

Getting started with OTP releases

+
+

An OTP release is the combination of the Erlang RunTime System (ERTS) +along with all the libraries and files that your node will need +to run. It is entirely self contained, and can often be sent as-is +to your production system and run without any extra setup.

+

Erlang.mk can of course bootstrap your project to generate releases. +You can use the bootstrap-rel target for this purpose:

+
+
+
$ make bootstrap-rel
+

This target can be combined with bootstrap or bootstrap-lib to +create a project that will build a release:

+
+
+
$ make -f erlang.mk bootstrap-lib bootstrap-rel
+

It is often very useful to keep the top-level project for +commands useful during operations, and put the components +of the system in separate applications that you will then +depend on. Consult the Packages and dependencies +chapter for more information.

+

When you run make from now on, Erlang.mk will compile your +project and build the release:

+
+
+
$ make
+ APP    hello_joe.app.src
+ GEN    distclean-relx-rel
+ GEN    /home/essen/tmp/hello_joe/relx
+===> Starting relx build process ...
+===> Resolving OTP Applications from directories:
+          /home/essen/tmp/hello_joe/ebin
+          /usr/lib/erlang/lib
+          /home/essen/tmp/hello_joe/deps
+===> Resolved hello_joe_release-1
+===> Including Erts from /usr/lib/erlang
+===> release successfully created!
+

The first time you run this command, Erlang.mk will download +relx, the release building tool. So don’t worry if you see +more output than above.

+

If building the release is slow, no need to upgrade your +hardware just yet. Just consult the Releases +chapter for various tips to speed up build time during +development.

+

You can start the release using the ./_rel/hello_joe_release/bin/hello_joe_release +script, or simply run make run. The latter will also compile +your project and build the release if it wasn’t already:

+
+
+
$ make run
+ APP    hello_joe.app.src
+ GEN    distclean-relx-rel
+===> Starting relx build process ...
+===> Resolving OTP Applications from directories:
+          /home/essen/tmp/hello_joe/ebin
+          /usr/lib/erlang/lib
+          /home/essen/tmp/hello_joe/deps
+===> Resolved hello_joe_release-1
+===> Including Erts from /usr/lib/erlang
+===> release successfully created!
+Exec: /home/essen/tmp/hello_joe/_rel/hello_joe_release/erts-7.0/bin/erlexec -boot /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe/_rel/hello_joe_release/erts-7.0/../lib -env ERL_LIBS /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/lib -config /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/sys.config -args_file /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/vm.args -- console
+Root: /home/essen/tmp/hello_joe/_rel/hello_joe_release
+/home/essen/tmp/hello_joe/_rel/hello_joe_release
+heart_beat_kill_pid = 16389
+Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false]
+
+Eshell V7.0  (abort with ^G)
+(hello_joe@127.0.0.1)1>
+

Simple as that!

+
+
+
+

Using spaces instead of tabs

+
+

Erlang.mk defaults to tabs when creating files from templates. +This is in part because of a personal preference, and in part +because it is much easier to convert tabs to spaces than the +opposite.

+

Use the SP variable if you prefer spaces. Set it to the number +of spaces per indentation level you want.

+

For example, if you prefer two spaces per indentation level:

+
+
+
$ make -f erlang.mk bootstrap SP=2
+

When you bootstrap the project initially, the variable automatically +gets added to the Makefile, so you only need to provide it when +you get started.

+
+
+
+

Using templates

+
+

It is no secret that Erlang’s OTP behaviors tend to have some +boilerplate. It is rarely an issue of course, except when +creating new modules. That’s why Erlang.mk not only comes with +templates for generating projects, but also individual modules!

+

You can list all available templates with the list-templates +target:

+
+
+
$ make list-templates
+Available templates: cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor
+

To generate a module, let’s say a gen_server, all you need to +do is to call make new with the appropriate arguments:

+
+
+
$ make new t=gen_server n=my_server
+

This will create a module located in src/my_server.erl +using the gen_server template.

+

This module is automatically compiled the next time you run +make:

+
+
+
$ make
+ ERLC   my_server.erl
+ APP    hello_joe.app.src
+

All that’s left to do is to open it in your favorite editor +and make it do something!

+
+
+
+

Hiding Erlang.mk from git

+
+

Erlang.mk is a large text file. It can easily take a large part of +a git diff or a git grep command. You can avoid this by telling +Git that erlang.mk is a binary file.

+

Add this to your .gitattributes file. This is a file that you +can create at the root of your repository:

+
+
+
erlang.mk -diff
+
+

The erlang.mk file will still appear in diffs and greps, but +as a binary file, meaning its contents won’t be shown by default +anymore.

+
+
+
+

Getting help

+
+

During development, if you don’t remember the name of a target, +you can always run make help:

+
+
+
$ make help
+erlang.mk (version 1.2.0-642-gccd2b9f) is distributed under the terms of the ISC License.
+Copyright (c) 2013-2015 Loïc Hoguin <essen@ninenines.eu>
+
+Usage: [V=1] make [target]...
+
+Core targets:
+  all           Run deps, app and rel targets in that order
+  app           Compile the project
+  deps          Fetch dependencies (if needed) and compile them
+  search q=...  Search for a package in the built-in index
+  rel           Build a release for this project, if applicable
+  docs          Build the documentation for this project
+  install-docs  Install the man pages for this project
+  check         Compile and run all tests and analysis for this project
+  tests         Run the tests for this project
+  clean         Delete temporary and output files from most targets
+  distclean     Delete all temporary and output files
+  help          Display this help and exit
+  erlang-mk     Update erlang.mk to the latest version
+
+Bootstrap targets:
+  bootstrap          Generate a skeleton of an OTP application
+  bootstrap-lib      Generate a skeleton of an OTP library
+  bootstrap-rel      Generate the files needed to build a release
+  new t=TPL n=NAME   Generate a module NAME based on the template TPL
+  list-templates     List available templates
+...
+

This guide should provide any other answer. If not, please +open a ticket on the official repository +and we will work on improving the guide.

+

Commercial support is available through Nine Nines. Please contact +Loïc Hoguin by sending an email to contact@ninenines.eu.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/history.asciidoc b/docs/en/erlang.mk/1/guide/history.asciidoc new file mode 100644 index 00000000..92027430 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/history.asciidoc @@ -0,0 +1,66 @@ +[[history]] +== Short history + +This chapter aims to be a brief record of the life of the +Erlang.mk project. + +=== Before Erlang.mk + +Erlang.mk originates from the Cowboy project. Cowboy started +as a Rebar project and I, Loïc Hoguin, was very happy with it +for a couple years. Over time however I started getting annoyed +and frustrated by a number of things, including bad defaults, +changing defaults and overall slowness. + +In particular, at the time I gave up on Rebar, the Cowboy +test suite was taking about five minutes to run. A quick experiment +showed I could get much lower times by simply invoking `ct_run` +directly. On January 4th, 2013, the Cowboy test suite took less +than a minute to complete. + +Following this success I started removing a little more and, +on the fateful day of January 5th, 2013, removed the dependency +on Rebar entirely. Rebar, and in particular the concept of +dependencies, was, and still is, a pretty strong influence. + +Erlang.mk was conceived. + +A few months passed and, on May 1st, 2013, the Erlang.mk +repository was created. Erlang.mk was born. + +Little did I know how much it would grow. + +=== Lifetime of the project + +Erlang.mk would eventually become a much larger file able to +deal with many more projects than just Cowboy. From the birth +of the project, the biggest force for growth was user contributions, +because Erlang.mk appealed to a variety of people with different +needs, needs that Erlang.mk was not fulfilling yet. + +The project was split into smaller files focused on a different +feature each, and a build script was written to build the single +Erlang.mk file. + +A test suite was contributed by a user, and later taken as a basis +for the current, much more complete test suite. Turns out testing +a Makefile is pretty straightforward. + +A package index was added to solve the problem of discovering +Erlang projects. + +After trying to see if Erlang build tools could cooperate, the +decision was made to improve compatibility with existing Rebar +projects by patching Rebar out, using Rebar. This feature, called +autopatch, proved very successful and made Erlang.mk compatible +with more than 90% of all Erlang projects. + +Erlang.mk documentation was much improved and the Erlang.mk website +was created in the summer of 2015. + +Over the year of 2015, Erlang.mk went from curiosity to a serious +alternative to other Erlang build tools. The user base increased +immensely and large projects started using it, including RabbitMQ +from the 3.6.0 release onward. + +A bright future lies ahead. diff --git a/docs/en/erlang.mk/1/guide/history/index.html b/docs/en/erlang.mk/1/guide/history/index.html new file mode 100644 index 00000000..cffc5f93 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/history/index.html @@ -0,0 +1,191 @@ + + + + + + + + + + + + Nine Nines: Short history + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Short history

+ +

This chapter aims to be a brief record of the life of the +Erlang.mk project.

+
+

Before Erlang.mk

+
+

Erlang.mk originates from the Cowboy project. Cowboy started +as a Rebar project and I, Loïc Hoguin, was very happy with it +for a couple years. Over time however I started getting annoyed +and frustrated by a number of things, including bad defaults, +changing defaults and overall slowness.

+

In particular, at the time I gave up on Rebar, the Cowboy +test suite was taking about five minutes to run. A quick experiment +showed I could get much lower times by simply invoking ct_run +directly. On January 4th, 2013, the Cowboy test suite took less +than a minute to complete.

+

Following this success I started removing a little more and, +on the fateful day of January 5th, 2013, removed the dependency +on Rebar entirely. Rebar, and in particular the concept of +dependencies, was, and still is, a pretty strong influence.

+

Erlang.mk was conceived.

+

A few months passed and, on May 1st, 2013, the Erlang.mk +repository was created. Erlang.mk was born.

+

Little did I know how much it would grow.

+
+
+
+

Lifetime of the project

+
+

Erlang.mk would eventually become a much larger file able to +deal with many more projects than just Cowboy. From the birth +of the project, the biggest force for growth was user contributions, +because Erlang.mk appealed to a variety of people with different +needs, needs that Erlang.mk was not fulfilling yet.

+

The project was split into smaller files focused on a different +feature each, and a build script was written to build the single +Erlang.mk file.

+

A test suite was contributed by a user, and later taken as a basis +for the current, much more complete test suite. Turns out testing +a Makefile is pretty straightforward.

+

A package index was added to solve the problem of discovering +Erlang projects.

+

After trying to see if Erlang build tools could cooperate, the +decision was made to improve compatibility with existing Rebar +projects by patching Rebar out, using Rebar. This feature, called +autopatch, proved very successful and made Erlang.mk compatible +with more than 90% of all Erlang projects.

+

Erlang.mk documentation was much improved and the Erlang.mk website +was created in the summer of 2015.

+

Over the year of 2015, Erlang.mk went from curiosity to a serious +alternative to other Erlang build tools. The user base increased +immensely and large projects started using it, including RabbitMQ +from the 3.6.0 release onward.

+

A bright future lies ahead.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/index.html b/docs/en/erlang.mk/1/guide/index.html new file mode 100644 index 00000000..f175edf1 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/index.html @@ -0,0 +1,298 @@ + + + + + + + + + + + + Nine Nines: Erlang.mk User Guide + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Erlang.mk User Guide

+ +
+
+

Code

+
+
+
+
+
+

Documentation

+
+
+
+
+
+

Tests

+
+
+
+
+
+

Third-party plugins

+
+
+
+
+
+

About Erlang.mk

+
+
+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/installation.asciidoc b/docs/en/erlang.mk/1/guide/installation.asciidoc new file mode 100644 index 00000000..cc18e7f1 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/installation.asciidoc @@ -0,0 +1,124 @@ +[[installation]] +== Installation + +This chapter explains how to setup your system in +order to use Erlang.mk. + +=== On Unix + +Erlang.mk requires GNU Make to be installed. GNU Make 3.81 +or later is required. GNU Make 4.1 or later is recommended, +as this is the version Erlang.mk is developed on. + +Some functionality requires that Autoconf 2.59 or later be +installed, in order to compile Erlang/OTP. Erlang/OTP may +have further requirements depending on your needs. + +Erlang.mk currently requires Erlang/OTP to be installed in +order to compile Erlang projects. + +Some packages may require additional libraries. + +=== On Windows + +Erlang.mk can be used on Windows inside an MSYS2 environment. +Cygwin, MSYS (the original) and native Windows (both Batch +and PowerShell) are currently not supported. + +The rest of this section details how to setup Erlang/OTP and +MSYS2 in order to use Erlang.mk. + +==== Installing Erlang/OTP + +Erlang.mk requires Erlang/OTP to be installed. The OTP team +provides binaries of Erlang/OTP for all major and minor releases, +available from the http://www.erlang.org/download.html[official download page]. +It is recommended that you use the 64-bit installer unless +technically impossible. Please follow the instructions from +the installer to complete the installation. + +The OTP team also provides a short guide to +http://www.erlang.org/download.html[installing Erlang/OTP on Windows] +if you need additional references. + +You can install Erlang/OTP silently using the `/S` switch +on the command line: + +---- +C:\Users\essen\Downloads> otp_win64_18.0.exe /S +---- + +==== Installing MSYS2 + +The only supported environment on Windows is MSYS2. MSYS2 is +a lightweight Unix-like environment for Windows that comes +with the Arch Linux package manager, `pacman`. + +The MSYS2 project provides a http://msys2.github.io[one click installer] +and instructions to set things up post-installation. + +It is currently not possible to use the installer silently. +Thankfully, the MSYS2 project provides an archive that can +be used in lieu of the installer. The archive however requires +_7zip_ to decompress it. + +First, download the +http://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-base-x86_64-20150512.tar.xz/download[MSYS2 base archive] +and extract it under 'C:\'. Assuming you downloaded the +archive as 'msys2.tar.xz' and put it in 'C:\', you can +use the following commands to extract it: + +---- +C:\> 7z x msys2.tar.xz +C:\> 7z x msys2.tar > NUL +---- + +Then you can run the two commands needed to perform the +post-installation setup: + +---- +C:\> C:\msys64\usr\bin\bash -lc "pacman --needed --noconfirm -Sy bash pacman pacman-mirrors msys2-runtime" +C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu" +---- + +==== Installing the required MSYS2 packages + +After following these instructions, you can install GNU Make, +Git and any other required softwares. From an MSYS2 shell, +you can call `pacman` directly: + +[source,bash] +$ pacman -S git make + +You can use `pacman -Ss` to search packages. For example, +to find all packages related to GCC: + +[source,bash] +$ pacman -Ss gcc + +If you are going to compile C/C++ code, you will need to +install this package, as Erlang.mk cannot use the normal +"gcc" package: + +[source,bash] +$ pacman -S mingw-w64-x86_64-gcc + +You can also run commands under the MSYS2 environment from +the Windows command line or batch files. This command will +install GNU Make and Git: + +---- +C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -S git make" +---- + +You can use similar `bash` commands if you need to run programs +inside the MSYS2 environment from a batch file. + +==== Gotchas + +While most of the basic functionality will just work, there are +still some issues. Erlang.mk needs to be fixed to pass the +right paths when running Erlang scripts. We are working on it. +Erlang.mk is fully tested on both Linux and Windows, but is +lacking tests in the areas not yet covered by this guide, +so expect bugs to be fixed as more tests are added. diff --git a/docs/en/erlang.mk/1/guide/installation/index.html b/docs/en/erlang.mk/1/guide/installation/index.html new file mode 100644 index 00000000..3eebaa95 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/installation/index.html @@ -0,0 +1,256 @@ + + + + + + + + + + + + Nine Nines: Installation + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Installation

+ +

This chapter explains how to setup your system in +order to use Erlang.mk.

+
+

On Unix

+
+

Erlang.mk requires GNU Make to be installed. GNU Make 3.81 +or later is required. GNU Make 4.1 or later is recommended, +as this is the version Erlang.mk is developed on.

+

Some functionality requires that Autoconf 2.59 or later be +installed, in order to compile Erlang/OTP. Erlang/OTP may +have further requirements depending on your needs.

+

Erlang.mk currently requires Erlang/OTP to be installed in +order to compile Erlang projects.

+

Some packages may require additional libraries.

+
+
+
+

On Windows

+
+

Erlang.mk can be used on Windows inside an MSYS2 environment. +Cygwin, MSYS (the original) and native Windows (both Batch +and PowerShell) are currently not supported.

+

The rest of this section details how to setup Erlang/OTP and +MSYS2 in order to use Erlang.mk.

+
+

Installing Erlang/OTP

+

Erlang.mk requires Erlang/OTP to be installed. The OTP team +provides binaries of Erlang/OTP for all major and minor releases, +available from the official download page. +It is recommended that you use the 64-bit installer unless +technically impossible. Please follow the instructions from +the installer to complete the installation.

+

The OTP team also provides a short guide to +installing Erlang/OTP on Windows +if you need additional references.

+

You can install Erlang/OTP silently using the /S switch +on the command line:

+
+
+
C:\Users\essen\Downloads> otp_win64_18.0.exe /S
+
+
+
+

Installing MSYS2

+

The only supported environment on Windows is MSYS2. MSYS2 is +a lightweight Unix-like environment for Windows that comes +with the Arch Linux package manager, pacman.

+

The MSYS2 project provides a one click installer +and instructions to set things up post-installation.

+

It is currently not possible to use the installer silently. +Thankfully, the MSYS2 project provides an archive that can +be used in lieu of the installer. The archive however requires +7zip to decompress it.

+

First, download the +MSYS2 base archive +and extract it under C:\. Assuming you downloaded the +archive as msys2.tar.xz and put it in C:\, you can +use the following commands to extract it:

+
+
+
C:\> 7z x msys2.tar.xz
+C:\> 7z x msys2.tar > NUL
+
+

Then you can run the two commands needed to perform the +post-installation setup:

+
+
+
C:\> C:\msys64\usr\bin\bash -lc "pacman --needed --noconfirm -Sy bash pacman pacman-mirrors msys2-runtime"
+C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu"
+
+
+
+

Installing the required MSYS2 packages

+

After following these instructions, you can install GNU Make, +Git and any other required softwares. From an MSYS2 shell, +you can call pacman directly:

+
+
+
$ pacman -S git make
+

You can use pacman -Ss to search packages. For example, +to find all packages related to GCC:

+
+
+
$ pacman -Ss gcc
+

If you are going to compile C/C++ code, you will need to +install this package, as Erlang.mk cannot use the normal +"gcc" package:

+
+
+
$ pacman -S mingw-w64-x86_64-gcc
+

You can also run commands under the MSYS2 environment from +the Windows command line or batch files. This command will +install GNU Make and Git:

+
+
+
C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -S git make"
+
+

You can use similar bash commands if you need to run programs +inside the MSYS2 environment from a batch file.

+
+
+

Gotchas

+

While most of the basic functionality will just work, there are +still some issues. Erlang.mk needs to be fixed to pass the +right paths when running Erlang scripts. We are working on it. +Erlang.mk is fully tested on both Linux and Windows, but is +lacking tests in the areas not yet covered by this guide, +so expect bugs to be fixed as more tests are added.

+
+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/limitations.asciidoc b/docs/en/erlang.mk/1/guide/limitations.asciidoc new file mode 100644 index 00000000..1bf33d21 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/limitations.asciidoc @@ -0,0 +1,46 @@ +[[limitations]] +== Limitations + +No software is perfect. + +It's very important, when evaluating and when using a tool, +to understand its limitations, so as to avoid making mistakes +and wasting valuable time. + +This chapter lists all known limitations of Erlang.mk. + +=== Erlang must be available + +Currently Erlang.mk requires you to install Erlang beforehand. +Installing Erlang is not always easy, particularly if you need +a specific version of Erlang for a specific project. + +In addition, the Erlang being used must be in your `$PATH` +before you use Erlang.mk. + +In the future we envision, Erlang.mk could manage the Erlang +version you need to use a project. Erlang.mk already does this +for running tests when using `make ci`, so doing this during +development is just a step away. + +=== Spaces in path + +Erlang.mk will currently not work properly if the path to the +project contains spaces. To check if that is the case, use the +command `pwd`. + +This issue is due to how Makefiles work. There might be ways +to solve it, we have not given up on it, but it's very low +priority considering how simple the workaround is. + +=== Dependency tracking and modification times + +Erlang source files that depend on other files will have their +modification time updated when they need to be recompiled due +to a dependency having changed. This could cause some editors to +think the file changed when it didn't. + +Erlang.mk must use this method in order to be able to compile +files in one `erlc` invocation. The benefits greatly outweigh +the issue in this case and so there are currently no plans to +fix this behavior. diff --git a/docs/en/erlang.mk/1/guide/limitations/index.html b/docs/en/erlang.mk/1/guide/limitations/index.html new file mode 100644 index 00000000..85b72139 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/limitations/index.html @@ -0,0 +1,179 @@ + + + + + + + + + + + + Nine Nines: Limitations + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Limitations

+ +

No software is perfect.

+

It’s very important, when evaluating and when using a tool, +to understand its limitations, so as to avoid making mistakes +and wasting valuable time.

+

This chapter lists all known limitations of Erlang.mk.

+
+

Erlang must be available

+
+

Currently Erlang.mk requires you to install Erlang beforehand. +Installing Erlang is not always easy, particularly if you need +a specific version of Erlang for a specific project.

+

In addition, the Erlang being used must be in your $PATH +before you use Erlang.mk.

+

In the future we envision, Erlang.mk could manage the Erlang +version you need to use a project. Erlang.mk already does this +for running tests when using make ci, so doing this during +development is just a step away.

+
+
+
+

Spaces in path

+
+

Erlang.mk will currently not work properly if the path to the +project contains spaces. To check if that is the case, use the +command pwd.

+

This issue is due to how Makefiles work. There might be ways +to solve it, we have not given up on it, but it’s very low +priority considering how simple the workaround is.

+
+
+
+

Dependency tracking and modification times

+
+

Erlang source files that depend on other files will have their +modification time updated when they need to be recompiled due +to a dependency having changed. This could cause some editors to +think the file changed when it didn’t.

+

Erlang.mk must use this method in order to be able to compile +files in one erlc invocation. The benefits greatly outweigh +the issue in this case and so there are currently no plans to +fix this behavior.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/overview.asciidoc b/docs/en/erlang.mk/1/guide/overview.asciidoc new file mode 100644 index 00000000..8fa57fe4 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/overview.asciidoc @@ -0,0 +1,87 @@ +[[overview]] +== Overview + +Now that you know how to get started, let's take a look at +what Erlang.mk can do for you. + +=== Building your project + +Erlang.mk is first and foremost a build tool. It is especially +tailored for Erlang developers and follows widely accepted +practices in the Erlang community. + +Erlang.mk will happily build all xref:building[Erlang-specific files] +you throw at it. Other kinds of files too, like C or C++ code +when you are working on xref:ports[a NIF or a port driver]. + +Erlang.mk embraces the concept of xref:deps[source dependencies]. +It can fetch dependency source code using a variety of mechanisms, +including fetching from Git, Mercurial or SVN. + +Erlang.mk will automatically xref:relx[generate releases] +when applicable. It can also xref:escript[generate escripts]. + +=== Exploring the package index + +Erlang.mk comes with a xref:deps[built-in package index]. +It is built as an extension of the dependency system and is +meant to be used for discovery purposes. + +No package is ever installed, they are only used as dependencies +and are always project-specific. They can be thought of as a +shortcut over plain dependencies. + +You can get a list of all packages known to Erlang.mk by using +the `search` target: + +[source,bash] +$ make search + +You can also use this target to search across all packages, for +example to find all packages related to Cowboy: + +[source,bash] +$ make search q=cowboy + +=== Generating documentation + +Erlang.mk supports _EDoc_ and _Asciidoc_. + +xref:edoc[EDoc] generates HTML documentation directly from +your source code. + +While it is convenient, ask yourself: if all the documentation is +inside the source code, why not just open the source code directly? +That's where _Asciidoc_ comes in. + +The xref:asciidoc[Asciidoc] plugin expects all documentation +to be separate from source. It will generate HTML, PDF, man pages and +more from the documentation you write in the 'doc/src/' folder in +your repository. + +=== Running tests + +Erlang.mk supports a lot of different testing and static +analysis tools. + +The xref:shell[make shell] command allows you +to test your project manually. You can automate these +unit tests with xref:eunit[EUnit] and test +your entire system with xref:ct[Common Test]. +xref:coverage[Code coverage] can of course +be enabled during tests. + +Erlang.mk comes with features to make your life easier when +setting up and using xref:ci[Continuous integration]. + +On the static analysis side of things, Erlang.mk comes with +support for xref:dialyzer[Dialyzer] and xref:xref[Xref], +to perform success typing analysis and cross referencing +of the code. + +=== Need more? + +Not convinced yet? You can read about xref:why[why you should use Erlang.mk] +and its xref:history[history]. And if you're still not +convinced after that, it's OK! The world would be boring if +everyone agreed on everything all the time. diff --git a/docs/en/erlang.mk/1/guide/overview/index.html b/docs/en/erlang.mk/1/guide/overview/index.html new file mode 100644 index 00000000..428db1c3 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/overview/index.html @@ -0,0 +1,224 @@ + + + + + + + + + + + + Nine Nines: Overview + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Overview

+ +

Now that you know how to get started, let’s take a look at +what Erlang.mk can do for you.

+
+

Building your project

+
+

Erlang.mk is first and foremost a build tool. It is especially +tailored for Erlang developers and follows widely accepted +practices in the Erlang community.

+

Erlang.mk will happily build all Erlang-specific files +you throw at it. Other kinds of files too, like C or C++ code +when you are working on a NIF or a port driver.

+

Erlang.mk embraces the concept of source dependencies. +It can fetch dependency source code using a variety of mechanisms, +including fetching from Git, Mercurial or SVN.

+

Erlang.mk will automatically generate releases +when applicable. It can also generate escripts.

+
+
+
+

Exploring the package index

+
+

Erlang.mk comes with a built-in package index. +It is built as an extension of the dependency system and is +meant to be used for discovery purposes.

+

No package is ever installed, they are only used as dependencies +and are always project-specific. They can be thought of as a +shortcut over plain dependencies.

+

You can get a list of all packages known to Erlang.mk by using +the search target:

+
+
+
$ make search
+

You can also use this target to search across all packages, for +example to find all packages related to Cowboy:

+
+
+
$ make search q=cowboy
+
+
+
+

Generating documentation

+
+

Erlang.mk supports EDoc and Asciidoc.

+

EDoc generates HTML documentation directly from +your source code.

+

While it is convenient, ask yourself: if all the documentation is +inside the source code, why not just open the source code directly? +That’s where Asciidoc comes in.

+

The Asciidoc plugin expects all documentation +to be separate from source. It will generate HTML, PDF, man pages and +more from the documentation you write in the doc/src/ folder in +your repository.

+
+
+
+

Running tests

+
+

Erlang.mk supports a lot of different testing and static +analysis tools.

+

The make shell command allows you +to test your project manually. You can automate these +unit tests with EUnit and test +your entire system with Common Test. +Code coverage can of course +be enabled during tests.

+

Erlang.mk comes with features to make your life easier when +setting up and using Continuous integration.

+

On the static analysis side of things, Erlang.mk comes with +support for Dialyzer and Xref, +to perform success typing analysis and cross referencing +of the code.

+
+
+
+

Need more?

+
+

Not convinced yet? You can read about why you should use Erlang.mk +and its history. And if you’re still not +convinced after that, it’s OK! The world would be boring if +everyone agreed on everything all the time.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/ports.asciidoc b/docs/en/erlang.mk/1/guide/ports.asciidoc new file mode 100644 index 00000000..02c636fd --- /dev/null +++ b/docs/en/erlang.mk/1/guide/ports.asciidoc @@ -0,0 +1,100 @@ +[[ports]] +== NIFs and port drivers + +Erlang.mk can not only build Erlang projects, but also the C code +that some projects come with, like NIFs and port drivers. + +There are two ways to build the C code: using a custom Makefile, +or making Erlang.mk do it directly. The C code will be built +as needed when you run `make`. + +// @todo something for easier bootstrapping + +=== C source code location and Erlang environment + +The C source code should be located in the '$(C_SRC_DIR)' directory. +It defaults to 'c_src/'. Should you need to modify it, all you +need to do is to set the variable in your Makefile before including +Erlang.mk: + +[source,make] +C_SRC_DIR = $(CURDIR)/my_nif_source + +When this directory exists, Erlang.mk will automatically create a +file named '$(C_SRC_ENV)'. This file defaults to '$(C_SRC_DIR)/env.mk'. +This can also be changed: + +[source,make] +C_SRC_ENV = $(C_SRC_DIR)/erlang_env.mk + +It contains a few variable definitions for the environment used for the build: + +`ERTS_INCLUDE_DIR`:: + Path to the ERTS include files ('erl_driver.h', 'erl_nif.h' and more). +`ERL_INTERFACE_INCLUDE_DIR`:: + Path to the Erl_Interface include files ('ei.h' and related). +`ERL_INTERFACE_LIB_DIR`:: + Path to the Erl_Interface static libraries. + +=== Using a custom Makefile + +Erlang.mk will automatically run `make` if it detects a Makefile +in '$(C_SRC_DIR)/Makefile'. + +The Makefile should have at least two targets: a default target +(which can be anything, for example `all`) which is invoked when +building the C code, and a `clean` target invoked when cleaning +it. + +You can include the 'env.mk' file to benefit from the Erlang +environment detection: + +[source,make] +include env.mk + +=== Using Erlang.mk directly + +You don't need to write a Makefile to build C source code, however. +Erlang.mk comes with rules to build both shared libraries and +executables, using the source files it finds in '$(C_SRC_DIR)'. + +By default, Erlang.mk will create a shared library. To change +this and create an executable instead, put this in your Makefile +before including Erlang.mk: + +[source,make] +C_SRC_TYPE = executable + +The generated file name varies depending on the type of project +you have (shared library or executable) and on the platform you +build the project on. + +For shared libraries, the generated file name will be +'$(C_SRC_OUTPUT)$(C_SRC_SHARED_EXTENSION)', with the default +being '$(CURDIR)/priv/$(PROJECT)' followed by the extension: +`.dll` on Windows, `.so` everywhere else. + +For executables, the generated file name is +'$(C_SRC_OUTPUT)$(C_SRC_EXECUTABLE_EXTENSION)', with the same +default except for the extension: `.exe` on Windows, and otherwise +nothing. + +Erlang.mk sets appropriate compile and linker flags by default. +These flags vary depending on the platform, and can of course +be overriden. + +`CC`:: + The compiler to be used. +`CFLAGS`:: + C compiler flags. +`CXXFLAGS`:: + C++ compiler flags. +`LDFLAGS`:: + Linker flags. +`LDLIBS`:: + Libraries to link against. + +The source files are automatically gathered from the contents +of '$(C_SRC_DIR)'. Erlang.mk looks for '.c', '.C', '.cc' and '.cpp' +source files. You can define the variable `SOURCES` to manually +list the files to compile. diff --git a/docs/en/erlang.mk/1/guide/ports/index.html b/docs/en/erlang.mk/1/guide/ports/index.html new file mode 100644 index 00000000..8a9a9066 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/ports/index.html @@ -0,0 +1,288 @@ + + + + + + + + + + + + Nine Nines: NIFs and port drivers + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

NIFs and port drivers

+ +

Erlang.mk can not only build Erlang projects, but also the C code +that some projects come with, like NIFs and port drivers.

+

There are two ways to build the C code: using a custom Makefile, +or making Erlang.mk do it directly. The C code will be built +as needed when you run make.

+
+

C source code location and Erlang environment

+
+

The C source code should be located in the $(C_SRC_DIR) directory. +It defaults to c_src/. Should you need to modify it, all you +need to do is to set the variable in your Makefile before including +Erlang.mk:

+
+
+
C_SRC_DIR = $(CURDIR)/my_nif_source
+

When this directory exists, Erlang.mk will automatically create a +file named $(C_SRC_ENV). This file defaults to $(C_SRC_DIR)/env.mk. +This can also be changed:

+
+
+
C_SRC_ENV = $(C_SRC_DIR)/erlang_env.mk
+

It contains a few variable definitions for the environment used for the build:

+
+
+ERTS_INCLUDE_DIR +
+
+

+ Path to the ERTS include files (erl_driver.h, erl_nif.h and more). +

+
+
+ERL_INTERFACE_INCLUDE_DIR +
+
+

+ Path to the Erl_Interface include files (ei.h and related). +

+
+
+ERL_INTERFACE_LIB_DIR +
+
+

+ Path to the Erl_Interface static libraries. +

+
+
+
+
+
+

Using a custom Makefile

+
+

Erlang.mk will automatically run make if it detects a Makefile +in $(C_SRC_DIR)/Makefile.

+

The Makefile should have at least two targets: a default target +(which can be anything, for example all) which is invoked when +building the C code, and a clean target invoked when cleaning +it.

+

You can include the env.mk file to benefit from the Erlang +environment detection:

+
+
+
include env.mk
+
+
+
+

Using Erlang.mk directly

+
+

You don’t need to write a Makefile to build C source code, however. +Erlang.mk comes with rules to build both shared libraries and +executables, using the source files it finds in $(C_SRC_DIR).

+

By default, Erlang.mk will create a shared library. To change +this and create an executable instead, put this in your Makefile +before including Erlang.mk:

+
+
+
C_SRC_TYPE = executable
+

The generated file name varies depending on the type of project +you have (shared library or executable) and on the platform you +build the project on.

+

For shared libraries, the generated file name will be +$(C_SRC_OUTPUT)$(C_SRC_SHARED_EXTENSION), with the default +being $(CURDIR)/priv/$(PROJECT) followed by the extension: +.dll on Windows, .so everywhere else.

+

For executables, the generated file name is +$(C_SRC_OUTPUT)$(C_SRC_EXECUTABLE_EXTENSION), with the same +default except for the extension: .exe on Windows, and otherwise +nothing.

+

Erlang.mk sets appropriate compile and linker flags by default. +These flags vary depending on the platform, and can of course +be overriden.

+
+
+CC +
+
+

+ The compiler to be used. +

+
+
+CFLAGS +
+
+

+ C compiler flags. +

+
+
+CXXFLAGS +
+
+

+ C++ compiler flags. +

+
+
+LDFLAGS +
+
+

+ Linker flags. +

+
+
+LDLIBS +
+
+

+ Libraries to link against. +

+
+
+

The source files are automatically gathered from the contents +of $(C_SRC_DIR). Erlang.mk looks for .c, .C, .cc and .cpp +source files. You can define the variable SOURCES to manually +list the files to compile.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/releases.asciidoc b/docs/en/erlang.mk/1/guide/releases.asciidoc new file mode 100644 index 00000000..46183e63 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/releases.asciidoc @@ -0,0 +1,70 @@ +[[relx]] +== Releases + +Erlang.mk relies on _Relx_ for generating releases. This +chapter covers the Erlang.mk-specific bits. Consult the +https://erlware.github.io/relx/[Relx website] for more information. + +=== Setup + +Erlang.mk will create a release if it detects a Relx configuration +file in the '$(RELX_CONFIG)' location. This defaults to +'$(CURDIR)/relx.config'. You can override it by defining +the variable before including Erlang.mk: + +[source,make] +RELX_CONFIG = $(CURDIR)/webchat.config + +Relx does not need to be installed. Erlang.mk will download +and build it automatically. +// @todo We are going to fetch relx from repository in the future. + +The Relx executable will be saved in the '$(RELX)' file. This +location defaults to '$(CURDIR)/relx' and can be overriden. + +// @todo You can use a custom repository by ??? + +=== Configuration + +You can specify additional Relx options using the `RELX_OPTS` +variable. For example, to enable `dev_mode`: + +[source,make] +RELX_OPTS = -d true + +While you can specify the output directory for the release +in the Relx options directly, Erlang.mk provides a specific +variable for it: `RELX_OUTPUT_DIR`. It defaults to the '_rel' +directory. You can also override it: + +[source,make] +RELX_OUTPUT_DIR = /path/to/staging/directory + +=== Generating the release + +Now that you're all set, all you need to do is generate the +release. As mentioned before, Erlang.mk will automatically +generate it when it detects the '$(RELX_CONFIG)' file. This +means the following command will also build the release: + +[source,bash] +$ make + +If you need to generate the release, and only the release, +the `rel` target can be used: + +[source,bash] +$ make rel + +=== Running the release + +Erlang.mk provides a convenience function for running the +release with one simple command: + +[source,bash] +$ make run + +This command will also build the project and generate the +release if they weren't already. It starts the release in +_console mode_, meaning you will also have a shell ready to +use to check things as needed. diff --git a/docs/en/erlang.mk/1/guide/releases/index.html b/docs/en/erlang.mk/1/guide/releases/index.html new file mode 100644 index 00000000..40022d86 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/releases/index.html @@ -0,0 +1,221 @@ + + + + + + + + + + + + Nine Nines: Releases + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Releases

+ +

Erlang.mk relies on Relx for generating releases. This +chapter covers the Erlang.mk-specific bits. Consult the +Relx website for more information.

+
+

Setup

+
+

Erlang.mk will create a release if it detects a Relx configuration +file in the $(RELX_CONFIG) location. This defaults to +$(CURDIR)/relx.config. You can override it by defining +the variable before including Erlang.mk:

+
+
+
RELX_CONFIG = $(CURDIR)/webchat.config
+

Relx does not need to be installed. Erlang.mk will download +and build it automatically.

+

The Relx executable will be saved in the $(RELX) file. This +location defaults to $(CURDIR)/relx and can be overriden.

+
+
+
+

Configuration

+
+

You can specify additional Relx options using the RELX_OPTS +variable. For example, to enable dev_mode:

+
+
+
RELX_OPTS = -d true
+

While you can specify the output directory for the release +in the Relx options directly, Erlang.mk provides a specific +variable for it: RELX_OUTPUT_DIR. It defaults to the _rel +directory. You can also override it:

+
+
+
RELX_OUTPUT_DIR = /path/to/staging/directory
+
+
+
+

Generating the release

+
+

Now that you’re all set, all you need to do is generate the +release. As mentioned before, Erlang.mk will automatically +generate it when it detects the $(RELX_CONFIG) file. This +means the following command will also build the release:

+
+
+
$ make
+

If you need to generate the release, and only the release, +the rel target can be used:

+
+
+
$ make rel
+
+
+
+

Running the release

+
+

Erlang.mk provides a convenience function for running the +release with one simple command:

+
+
+
$ make run
+

This command will also build the project and generate the +release if they weren’t already. It starts the release in +console mode, meaning you will also have a shell ready to +use to check things as needed.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/shell.asciidoc b/docs/en/erlang.mk/1/guide/shell.asciidoc new file mode 100644 index 00000000..a5272531 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/shell.asciidoc @@ -0,0 +1,46 @@ +[[shell]] +== Erlang shell + +Erlang.mk provides a convenient target for starting a shell +with all the paths set properly to experiment with your code. + +=== Configuration + +The `SHELL_DEPS` variable can be used to define dependencies +that are only to be used when the `make shell` command is called. +For example, if you want to use _kjell_ as your shell: + +[source,make] +SHELL_DEPS = kjell + +Dependencies are downloaded and compiled the first time you +run the `make shell` command. + +You can customize the executable used to start the Erlang shell. +To continue with our example, if you want to use _kjell_ as your +shell, you also need to change `SHELL_ERL` and point it to the +`kjell` executable: + +[source,make] +SHELL_ERL = $(DEPS_DIR)/kjell/bin/kjell + +You can specify additional options to be used when starting the +shell using the `SHELL_OPTS` variable: + +[source,make] +SHELL_OPTS = -setcookie chocolate + +Any of the usual `erl` options can be used, including `-eval`: + +[source,make] +SHELL_OPTS = -eval 'my_app:run()' + +=== Usage + +To start the shell, all you need is the following command: + +[source,bash] +$ make shell + +The shell can be stopped as usual with a double Ctrl+C or the +command `q().`. diff --git a/docs/en/erlang.mk/1/guide/shell/index.html b/docs/en/erlang.mk/1/guide/shell/index.html new file mode 100644 index 00000000..ed093c95 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/shell/index.html @@ -0,0 +1,193 @@ + + + + + + + + + + + + Nine Nines: Erlang shell + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Erlang shell

+ +

Erlang.mk provides a convenient target for starting a shell +with all the paths set properly to experiment with your code.

+
+

Configuration

+
+

The SHELL_DEPS variable can be used to define dependencies +that are only to be used when the make shell command is called. +For example, if you want to use kjell as your shell:

+
+
+
SHELL_DEPS = kjell
+

Dependencies are downloaded and compiled the first time you +run the make shell command.

+

You can customize the executable used to start the Erlang shell. +To continue with our example, if you want to use kjell as your +shell, you also need to change SHELL_ERL and point it to the +kjell executable:

+
+
+
SHELL_ERL = $(DEPS_DIR)/kjell/bin/kjell
+

You can specify additional options to be used when starting the +shell using the SHELL_OPTS variable:

+
+
+
SHELL_OPTS = -setcookie chocolate
+

Any of the usual erl options can be used, including -eval:

+
+
+
SHELL_OPTS = -eval 'my_app:run()'
+
+
+
+

Usage

+
+

To start the shell, all you need is the following command:

+
+
+
$ make shell
+

The shell can be stopped as usual with a double Ctrl+C or the +command q()..

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/updating.asciidoc b/docs/en/erlang.mk/1/guide/updating.asciidoc new file mode 100644 index 00000000..61d913db --- /dev/null +++ b/docs/en/erlang.mk/1/guide/updating.asciidoc @@ -0,0 +1,63 @@ +[[updating]] +== Updating Erlang.mk + +This chapter describes how to update the 'erlang.mk' file +in your repository. + +=== Initial bootstrap + +The first time you use Erlang.mk, it will bootstrap itself. +It always uses the most recent version for this, so you don't +have to update after creating your project. + +=== Updating + +Later on though, updating becomes a necessity. Erlang.mk +developers and contributors relentlessly improve the project +and add new features; it would be a waste not to benefit +from this. + +That's why updating Erlang.mk is so simple. All you need +to do is to call `make erlang-mk`: + +[source,bash] +---- +$ make erlang-mk +git clone https://github.com/ninenines/erlang.mk .erlang.mk.build +Cloning into '.erlang.mk.build'... +remote: Counting objects: 4035, done. +remote: Compressing objects: 100% (12/12), done. +remote: Total 4035 (delta 8), reused 4 (delta 4), pack-reused 4019 +Receiving objects: 100% (4035/4035), 1.10 MiB | 1000.00 KiB/s, done. +Resolving deltas: 100% (2442/2442), done. +Checking connectivity... done. +if [ -f build.config ]; then cp build.config .erlang.mk.build; fi +cd .erlang.mk.build && make +make[1]: Entering directory '/home/essen/tmp/emkg/hello_joe/.erlang.mk.build' +awk 'FNR==1 && NR!=1{print ""}1' core/core.mk index/*.mk core/index.mk core/deps.mk plugins/protobuffs.mk core/erlc.mk core/docs.mk core/test.mk plugins/asciidoc.mk plugins/bootstrap.mk plugins/c_src.mk plugins/ci.mk plugins/ct.mk plugins/dialyzer.mk plugins/edoc.mk plugins/elvis.mk plugins/erlydtl.mk plugins/escript.mk plugins/eunit.mk plugins/relx.mk plugins/shell.mk plugins/triq.mk plugins/xref.mk plugins/cover.mk \ + | sed 's/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/' > erlang.mk +make[1]: Leaving directory '/home/essen/tmp/emkg/hello_joe/.erlang.mk.build' +cp .erlang.mk.build/erlang.mk ./erlang.mk +rm -rf .erlang.mk.build +---- + +All that's left to do is to commit the file! + +Yep, it's that easy. + +=== Customizing the build + +Erlang.mk allows you to customize which plugins are to be included +in the 'erlang.mk' file. You can do so by maintaining your own +'build.config' file in your repository. Erlang.mk will automatically +use it the next time you run `make erlang-mk`. + +The 'build.config' file contains the list of all files that will +be built into the resulting 'erlang.mk' file. You can start from +the https://github.com/ninenines/erlang.mk/blob/master/build.config[most recent version] +and customize to your needs. + +You can also name the file differently or put it in a separate folder +by modifying the value for `ERLANG_MK_BUILD_CONFIG`. You can also +tell Erlang.mk to use a different temporary directory by changing +the `ERLANG_MK_BUILD_DIR` variable. diff --git a/docs/en/erlang.mk/1/guide/updating/index.html b/docs/en/erlang.mk/1/guide/updating/index.html new file mode 100644 index 00000000..d52442fd --- /dev/null +++ b/docs/en/erlang.mk/1/guide/updating/index.html @@ -0,0 +1,198 @@ + + + + + + + + + + + + Nine Nines: Updating Erlang.mk + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Updating Erlang.mk

+ +

This chapter describes how to update the erlang.mk file +in your repository.

+
+

Initial bootstrap

+
+

The first time you use Erlang.mk, it will bootstrap itself. +It always uses the most recent version for this, so you don’t +have to update after creating your project.

+
+
+
+

Updating

+
+

Later on though, updating becomes a necessity. Erlang.mk +developers and contributors relentlessly improve the project +and add new features; it would be a waste not to benefit +from this.

+

That’s why updating Erlang.mk is so simple. All you need +to do is to call make erlang-mk:

+
+
+
$ make erlang-mk
+git clone https://github.com/ninenines/erlang.mk .erlang.mk.build
+Cloning into '.erlang.mk.build'...
+remote: Counting objects: 4035, done.
+remote: Compressing objects: 100% (12/12), done.
+remote: Total 4035 (delta 8), reused 4 (delta 4), pack-reused 4019
+Receiving objects: 100% (4035/4035), 1.10 MiB | 1000.00 KiB/s, done.
+Resolving deltas: 100% (2442/2442), done.
+Checking connectivity... done.
+if [ -f build.config ]; then cp build.config .erlang.mk.build; fi
+cd .erlang.mk.build && make
+make[1]: Entering directory '/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'
+awk 'FNR==1 && NR!=1{print ""}1' core/core.mk index/*.mk core/index.mk core/deps.mk plugins/protobuffs.mk core/erlc.mk core/docs.mk core/test.mk plugins/asciidoc.mk plugins/bootstrap.mk plugins/c_src.mk plugins/ci.mk plugins/ct.mk plugins/dialyzer.mk plugins/edoc.mk plugins/elvis.mk plugins/erlydtl.mk plugins/escript.mk plugins/eunit.mk plugins/relx.mk plugins/shell.mk plugins/triq.mk plugins/xref.mk plugins/cover.mk \
+        | sed 's/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/' > erlang.mk
+make[1]: Leaving directory '/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'
+cp .erlang.mk.build/erlang.mk ./erlang.mk
+rm -rf .erlang.mk.build
+

All that’s left to do is to commit the file!

+

Yep, it’s that easy.

+
+
+
+

Customizing the build

+
+

Erlang.mk allows you to customize which plugins are to be included +in the erlang.mk file. You can do so by maintaining your own +build.config file in your repository. Erlang.mk will automatically +use it the next time you run make erlang-mk.

+

The build.config file contains the list of all files that will +be built into the resulting erlang.mk file. You can start from +the most recent version +and customize to your needs.

+

You can also name the file differently or put it in a separate folder +by modifying the value for ERLANG_MK_BUILD_CONFIG. You can also +tell Erlang.mk to use a different temporary directory by changing +the ERLANG_MK_BUILD_DIR variable.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/why.asciidoc b/docs/en/erlang.mk/1/guide/why.asciidoc new file mode 100644 index 00000000..e91b64ca --- /dev/null +++ b/docs/en/erlang.mk/1/guide/why.asciidoc @@ -0,0 +1,81 @@ +[[why]] +== Why Erlang.mk + +Why would you choose Erlang.mk, if not for its +xref:overview[many features]? This chapter will +attempt to answer that. + +=== Erlang.mk is fast + +Erlang.mk is as fast as it gets. + +Erlang.mk will group the compilation of files so as to avoid +running the BEAM more than necessary. This saves many seconds +compared to traditional Makefiles, even on small projects. + +Erlang.mk will not try to be too smart. It provides a simple +solution that works for most people, and gives additional +options for projects that run into edge cases, often in the +form of extra variables or rules to be defined. + +=== Erlang.mk gives you the full power of Unix + +Erlang.mk is a Makefile. + +You could use Erlang.mk directly without configuring anything +and it would just work. But you can also extend it greatly +either through configuration or hooks, and you can of course +add your own rules to the Makefile. + +In all cases: for configuration, hooks or custom rules, you +have all the power of Unix at your disposal, and can call +any utility _or even any language interpreter_ you want, +every time you need to. Erlang.mk also allows you to write +scripts in this small language called Erlang directly inside +your Makefile if you ever need to... + +=== Erlang.mk is a text file + +Erlang.mk is a Makefile. + +Which means Erlang.mk is a simple text file. You can edit a +text file. Nothing stops you. If you run into any bug, or +behavior that does not suit you, you can just open the +'erlang.mk' file in your favorite editor, fix and/or comment +a few lines, save, and try again. It's as simple as it gets. + +Currently using a binary build tool? Good luck with that. + +=== Erlang.mk can manage Erlang itself + +Erlang.mk isn't written in Erlang. + +That's not a good thing, you say? Well, here's one thing +that Erlang.mk and Makefiles can do for you that Erlang +build tool can't easily: choose what version of Erlang is +to be used for compiling the project. + +This really is a one-liner in Erlang.mk (a few more lines +if you also let it download and build Erlang directly) +and allows for even greater things, like testing your +project across all supported Erlang versions in one small +command: `make -k ci`. + +=== Erlang.mk can do more than Erlang + +Erlang.mk doesn't care what your dependencies are written in. + +Erlang.mk will happily compile any dependency, as long as +they come with a Makefile. The dependency can be written +in C, C++ or even Javascript... Who cares, really? If you +need Erlang.mk to fetch it, then Erlang.mk will fetch it +and compile it as needed. + +=== Erlang.mk integrates nicely in Make and Automake projects + +If you are planning to put your project in the middle of +a Make or Automake-based build environment, then the most +logical thing to do is to use a Makefile. + +Erlang.mk will happily sit in such an environment and behave +as you expect it to. diff --git a/docs/en/erlang.mk/1/guide/why/index.html b/docs/en/erlang.mk/1/guide/why/index.html new file mode 100644 index 00000000..845d7867 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/why/index.html @@ -0,0 +1,216 @@ + + + + + + + + + + + + Nine Nines: Why Erlang.mk + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Why Erlang.mk

+ +

Why would you choose Erlang.mk, if not for its +many features? This chapter will +attempt to answer that.

+
+

Erlang.mk is fast

+
+

Erlang.mk is as fast as it gets.

+

Erlang.mk will group the compilation of files so as to avoid +running the BEAM more than necessary. This saves many seconds +compared to traditional Makefiles, even on small projects.

+

Erlang.mk will not try to be too smart. It provides a simple +solution that works for most people, and gives additional +options for projects that run into edge cases, often in the +form of extra variables or rules to be defined.

+
+
+
+

Erlang.mk gives you the full power of Unix

+
+

Erlang.mk is a Makefile.

+

You could use Erlang.mk directly without configuring anything +and it would just work. But you can also extend it greatly +either through configuration or hooks, and you can of course +add your own rules to the Makefile.

+

In all cases: for configuration, hooks or custom rules, you +have all the power of Unix at your disposal, and can call +any utility or even any language interpreter you want, +every time you need to. Erlang.mk also allows you to write +scripts in this small language called Erlang directly inside +your Makefile if you ever need to…

+
+
+
+

Erlang.mk is a text file

+
+

Erlang.mk is a Makefile.

+

Which means Erlang.mk is a simple text file. You can edit a +text file. Nothing stops you. If you run into any bug, or +behavior that does not suit you, you can just open the +erlang.mk file in your favorite editor, fix and/or comment +a few lines, save, and try again. It’s as simple as it gets.

+

Currently using a binary build tool? Good luck with that.

+
+
+
+

Erlang.mk can manage Erlang itself

+
+

Erlang.mk isn’t written in Erlang.

+

That’s not a good thing, you say? Well, here’s one thing +that Erlang.mk and Makefiles can do for you that Erlang +build tool can’t easily: choose what version of Erlang is +to be used for compiling the project.

+

This really is a one-liner in Erlang.mk (a few more lines +if you also let it download and build Erlang directly) +and allows for even greater things, like testing your +project across all supported Erlang versions in one small +command: make -k ci.

+
+
+
+

Erlang.mk can do more than Erlang

+
+

Erlang.mk doesn’t care what your dependencies are written in.

+

Erlang.mk will happily compile any dependency, as long as +they come with a Makefile. The dependency can be written +in C, C++ or even Javascript… Who cares, really? If you +need Erlang.mk to fetch it, then Erlang.mk will fetch it +and compile it as needed.

+
+
+
+

Erlang.mk integrates nicely in Make and Automake projects

+
+

If you are planning to put your project in the middle of +a Make or Automake-based build environment, then the most +logical thing to do is to use a Makefile.

+

Erlang.mk will happily sit in such an environment and behave +as you expect it to.

+
+
+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/guide/xref.asciidoc b/docs/en/erlang.mk/1/guide/xref.asciidoc new file mode 100644 index 00000000..44ed1908 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/xref.asciidoc @@ -0,0 +1,6 @@ +[[xref]] +== Xref + +// @todo Write it. + +Placeholder chapter. diff --git a/docs/en/erlang.mk/1/guide/xref/index.html b/docs/en/erlang.mk/1/guide/xref/index.html new file mode 100644 index 00000000..1def98ab --- /dev/null +++ b/docs/en/erlang.mk/1/guide/xref/index.html @@ -0,0 +1,137 @@ + + + + + + + + + + + + Nine Nines: Xref + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Xref

+ +

Placeholder chapter.

+ + + +
+ +
+ + +

+ Erlang.mk + 1 + + User Guide +

+ +
    + + + +
+ +

Navigation

+ +

Version select

+
    + + + +
  • 1
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/erlang.mk/1/index.html b/docs/en/erlang.mk/1/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/erlang.mk/1/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/erlang.mk/index.html b/docs/en/erlang.mk/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/erlang.mk/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/gun/1.0/guide/connect.asciidoc b/docs/en/gun/1.0/guide/connect.asciidoc new file mode 100644 index 00000000..c2e887c1 --- /dev/null +++ b/docs/en/gun/1.0/guide/connect.asciidoc @@ -0,0 +1,154 @@ +== Connection + +This chapter describes how to open, monitor and close +a connection using the Gun client. + +=== Gun connections + +Gun is designed with the SPDY and Websocket protocols in mind. +They are built for long-running connections that allow concurrent +exchange of data, either in the form of request/responses for +SPDY or in the form of messages for Websocket. + +A Gun connection is an Erlang process that manages a socket to +a remote endpoint. This Gun connection is owned by a user +process that is called the _owner_ of the connection, and is +managed by the supervision tree of the `gun` application. + +The owner process communicates with the Gun connection +by calling functions from the module `gun`. All functions +perform their respective operations asynchronously. The Gun +connection will send Erlang messages to the owner process +whenever needed. + +When the remote endpoint closes the connection, Gun attempts +to reconnect automatically. + +=== Opening a new connection + +The `gun:open/{2,3}` function must be used to open a connection. + +.Opening a connection to example.org on port 443 + +[source,erlang] +{ok, ConnPid} = gun:open("example.org", 443). + +If the port given is 443, Gun will attempt to connect using +SSL. The protocol will be selected automatically using the +NPN extension for TLS. By default Gun supports SPDY/3.1, +SPDY/3 and HTTP/1.1 when connecting using SSL. + +For any other port, Gun will attempt to connect using TCP +and will use the HTTP/1.1 protocol. + +The transport and protocol used can be overriden using +options. The manual documents all available options. + +Options can be provided as a third argument, and take the +form of a map. + +.Opening an SSL connection to example.org on port 8443 + +[source,erlang] +{ok, ConnPid} = gun:open("example.org", 8443, #{transport=>ssl}). + +=== Waiting for the connection to be established + +When Gun successfully connects to the server, it sends a +`gun_up` message with the protocol that has been selected +for the connection. + +Gun provides the functions `gun:await_up/{1,2,3}` that wait +for the `gun_up` message. They can optionally take a monitor +reference and/or timeout value. If no monitor is provided, +one will be created for the duration of the function call. + +.Synchronous opening of a connection + +[source,erlang] +{ok, ConnPid} = gun:open("example.org", 443), +{ok, Protocol} = gun:await_up(ConnPid). + +=== Handling connection loss + +When the connection is lost, Gun will send a `gun_down` +message indicating the current protocol, the reason the +connection was lost and two list of stream references. + +The first list indicates open streams that _may_ have been +processed by the server. The second list indicates open +streams that the server did not process. + +=== Monitoring the connection process + +@todo Gun should detect the owner process being killed + +Because software errors are unavoidable, it is important to +detect when the Gun process crashes. It is also important +to detect when it exits normally. Erlang provides two ways +to do that: links and monitors. + +Gun leaves you the choice as to which one will be used. +However, if you use the `gun:await/{2,3}` or `gun:await_body/{2,3}` +functions, a monitor may be used for you to avoid getting +stuck waiting for a message that will never come. + +If you choose to monitor yourself you can do it on a permanent +basis rather than on every message you will receive, saving +resources. Indeed, the `gun:await/{3,4}` and `gun:await_body/{3,4}` +functions both accept a monitor argument if you have one already. + +.Monitoring the connection process + +[source,erlang] +{ok, ConnPid} = gun:open("example.org", 443). +MRef = monitor(process, ConnPid). + +This monitor reference can be kept and used until the connection +process exits. + +.Handling `DOWN` messages + +[source,erlang] +receive + %% Receive Gun messages here... + {'DOWN', Mref, process, ConnPid, Reason} -> + error_logger:error_msg("Oops!"), + exit(Reason); +end. + +What to do when you receive a `DOWN` message is entirely up to you. + +=== Closing the connection abruptly + +The connection can be stopped abruptly at any time by calling +the `gun:close/1` function. + +.Immediate closing of the connection + +[source,erlang] +gun:close(ConnPid). + +The process is stopped immediately without having a chance to +perform the protocol's closing handshake, if any. + +=== Closing the connection gracefully + +The connection can also be stopped gracefully by calling the +`gun:shutdown/1` function. + +.Graceful shutdown of the connection + +[source,erlang] +gun:shutdown(ConnPid). + +Gun will refuse any new requests or messages after you call +this function. It will however continue to send you messages +for existing streams until they are all completed. + +For example if you performed a GET request just before calling +`gun:shutdown/1`, you will still receive the response before +Gun closes the connection. + +If you set a monitor beforehand, you will receive a message +when the connection has been closed. diff --git a/docs/en/gun/1.0/guide/connect/index.html b/docs/en/gun/1.0/guide/connect/index.html new file mode 100644 index 00000000..ba463db5 --- /dev/null +++ b/docs/en/gun/1.0/guide/connect/index.html @@ -0,0 +1,302 @@ + + + + + + + + + + + + Nine Nines: Connection + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Connection

+ +

This chapter describes how to open, monitor and close +a connection using the Gun client.

+
+

Gun connections

+
+

Gun is designed with the SPDY and Websocket protocols in mind. +They are built for long-running connections that allow concurrent +exchange of data, either in the form of request/responses for +SPDY or in the form of messages for Websocket.

+

A Gun connection is an Erlang process that manages a socket to +a remote endpoint. This Gun connection is owned by a user +process that is called the owner of the connection, and is +managed by the supervision tree of the gun application.

+

The owner process communicates with the Gun connection +by calling functions from the module gun. All functions +perform their respective operations asynchronously. The Gun +connection will send Erlang messages to the owner process +whenever needed.

+

When the remote endpoint closes the connection, Gun attempts +to reconnect automatically.

+
+
+
+

Opening a new connection

+
+

The gun:open/{2,3} function must be used to open a connection.

+
+
Opening a connection to example.org on port 443
+
+
{ok, ConnPid} = gun:open("example.org", 443).
+

If the port given is 443, Gun will attempt to connect using +SSL. The protocol will be selected automatically using the +NPN extension for TLS. By default Gun supports SPDY/3.1, +SPDY/3 and HTTP/1.1 when connecting using SSL.

+

For any other port, Gun will attempt to connect using TCP +and will use the HTTP/1.1 protocol.

+

The transport and protocol used can be overriden using +options. The manual documents all available options.

+

Options can be provided as a third argument, and take the +form of a map.

+
+
Opening an SSL connection to example.org on port 8443
+
+
{ok, ConnPid} = gun:open("example.org", 8443, #{transport=>ssl}).
+
+
+
+

Waiting for the connection to be established

+
+

When Gun successfully connects to the server, it sends a +gun_up message with the protocol that has been selected +for the connection.

+

Gun provides the functions gun:await_up/{1,2,3} that wait +for the gun_up message. They can optionally take a monitor +reference and/or timeout value. If no monitor is provided, +one will be created for the duration of the function call.

+
+
Synchronous opening of a connection
+
+
{ok, ConnPid} = gun:open("example.org", 443),
+{ok, Protocol} = gun:await_up(ConnPid).
+
+
+
+

Handling connection loss

+
+

When the connection is lost, Gun will send a gun_down +message indicating the current protocol, the reason the +connection was lost and two list of stream references.

+

The first list indicates open streams that may have been +processed by the server. The second list indicates open +streams that the server did not process.

+
+
+
+

Monitoring the connection process

+
+

@todo Gun should detect the owner process being killed

+

Because software errors are unavoidable, it is important to +detect when the Gun process crashes. It is also important +to detect when it exits normally. Erlang provides two ways +to do that: links and monitors.

+

Gun leaves you the choice as to which one will be used. +However, if you use the gun:await/{2,3} or gun:await_body/{2,3} +functions, a monitor may be used for you to avoid getting +stuck waiting for a message that will never come.

+

If you choose to monitor yourself you can do it on a permanent +basis rather than on every message you will receive, saving +resources. Indeed, the gun:await/{3,4} and gun:await_body/{3,4} +functions both accept a monitor argument if you have one already.

+
+
Monitoring the connection process
+
+
{ok, ConnPid} = gun:open("example.org", 443).
+MRef = monitor(process, ConnPid).
+

This monitor reference can be kept and used until the connection +process exits.

+
+
Handling DOWN messages
+
+
receive
+        %% Receive Gun messages here...
+        {'DOWN', Mref, process, ConnPid, Reason} ->
+                error_logger:error_msg("Oops!"),
+                exit(Reason);
+end.
+

What to do when you receive a DOWN message is entirely up to you.

+
+
+
+

Closing the connection abruptly

+
+

The connection can be stopped abruptly at any time by calling +the gun:close/1 function.

+
+
Immediate closing of the connection
+
+
gun:close(ConnPid).
+

The process is stopped immediately without having a chance to +perform the protocol’s closing handshake, if any.

+
+
+
+

Closing the connection gracefully

+
+

The connection can also be stopped gracefully by calling the +gun:shutdown/1 function.

+
+
Graceful shutdown of the connection
+
+
gun:shutdown(ConnPid).
+

Gun will refuse any new requests or messages after you call +this function. It will however continue to send you messages +for existing streams until they are all completed.

+

For example if you performed a GET request just before calling +gun:shutdown/1, you will still receive the response before +Gun closes the connection.

+

If you set a monitor beforehand, you will receive a message +when the connection has been closed.

+
+
+ + + +
+ +
+ + +

+ Gun + 1.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.0
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/gun/1.0/guide/http.asciidoc b/docs/en/gun/1.0/guide/http.asciidoc new file mode 100644 index 00000000..465a4c53 --- /dev/null +++ b/docs/en/gun/1.0/guide/http.asciidoc @@ -0,0 +1,362 @@ +== HTTP + +This chapter describes how to use the Gun client for +communicating with an HTTP/1.1 or SPDY server. + +=== Streams + +Every time a request is initiated, Gun creates a _stream_. +A _stream reference_ uniquely identifies a set of request and +response(s) and must be used to perform additional operations +with a stream or to identify its messages. + +Stream references use the Erlang _reference_ data type and +are therefore unique. + +Streams can be canceled at any time. This will stop any further +messages from being sent to the owner process. Depending on +its capabilities, the server will also be instructed to cancel +the request. + +Canceling a stream may result in Gun dropping the connection +temporarily, to avoid uploading or downloading data that will +not be used. + +.Cancelling a stream +[source,erlang] +gun:cancel(ConnPid, StreamRef). + +=== Sending requests + +Gun provides many convenient functions for performing common +operations, like GET, POST or DELETE. It also provides a +general purpose function in case you need other methods. + +The availability of these methods on the server can vary +depending on the software used but also on a per-resource +basis. + +Gun will automatically set a few headers depending on the +method used. For all methods however it will set the host +header if it has not been provided in the request arguments. + +This section focuses on the act of sending a request. The +handling of responses will be explained further on. + +==== GET and HEAD + +Use `gun:get/{2,3}` to request a resource. + +.GET "/organizations/ninenines" + +[source,erlang] +StreamRef = gun:get(ConnPid, "/organizations/ninenines"). + +.GET "/organizations/ninenines" with custom headers + +[source,erlang] +StreamRef = gun:get(ConnPid, "/organizations/ninenines", [ + {<<"accept">>, "application/json"}, + {<<"user-agent">>, "revolver/1.0"} +]). + +Note that the list of headers has the field name as a binary. +The field value is iodata, which is either a binary or an +iolist. + +Use `gun:head/{2,3}` if you don't need the response body. + +.HEAD "/organizations/ninenines" + +[source,erlang] +StreamRef = gun:head(ConnPid, "/organizations/ninenines"). + +.HEAD "/organizations/ninenines" with custom headers + +[source,erlang] +StreamRef = gun:head(ConnPid, "/organizations/ninenines", [ + {<<"accept">>, "application/json"}, + {<<"user-agent">>, "revolver/1.0"} +]). + +It is not possible to send a request body with a GET or HEAD +request. + +==== POST, PUT and PATCH + +HTTP defines three methods to create or update a resource. + +POST is generally used when the resource identifier (URI) isn't known +in advance when creating the resource. POST can also be used to +replace an existing resource, although PUT is more appropriate +in that situation. + +PUT creates or replaces a resource identified by the URI. + +PATCH provides instructions on how to modify the resource. + +Both POST and PUT send the entire resource representation in their +request body. The PATCH method can be used when this is not +desirable. The request body of a PATCH method may be a partial +representation or a list of instructions on how to update the +resource. + +The `gun:post/4`, `gun:put/4` and `gun:patch/4` functions +take a body as their fourth argument. These functions do +not require any body-specific header to be set, although +it is always recommended to set the content-type header. +Gun will set the other headers automatically. + +In this and the following examples in this section, `gun:post` +can be replaced by `gun:put` or `gun:patch` for performing +a PUT or PATCH request, respectively. + +.POST "/organizations/ninenines" + +[source,erlang] +Body = "{\"msg\": \"Hello world!\"}", +StreamRef = gun:post(ConnPid, "/organizations/ninenines", [ + {<<"content-type">>, "application/json"} +], Body). + +The `gun:post/3`, `gun:put/3` and `gun:patch/3` functions +do not take a body in their arguments. If a body is to be +provided later on, using the `gun:data/4` function, then +the request headers must indicate this. This can be done +by setting the content-length or content-type request +headers. If these headers are not set then Gun will assume +the request has no body. + +It is recommended to send the content-length header if you +know it in advance, although this is not required. If it +is not set, HTTP/1.1 will use the chunked transfer-encoding, +and SPDY will continue normally as it is chunked by design. + +.POST "/organizations/ninenines" with delayed body + +[source,erlang] +Body = "{\"msg\": \"Hello world!\"}", +StreamRef = gun:post(ConnPid, "/organizations/ninenines", [ + {<<"content-length">>, integer_to_binary(length(Body))}, + {<<"content-type">>, "application/json"} +]), +gun:data(ConnPid, StreamRef, fin, Body). + +The atom `fin` indicates this is the last chunk of data to +be sent. You can call the `gun:data/4` function as many +times as needed until you have sent the entire body. The +last call must use `fin` and all the previous calls must +use `nofin`. The last chunk may be empty. + +@todo what to do about empty chunk, ignore? + +.Streaming the request body + +[source,erlang] +---- +sendfile(ConnPid, StreamRef, Filepath) -> + {ok, IoDevice} = file:open(Filepath, [read, binary, raw]), + do_sendfile(ConnPid, StreamRef, IoDevice). + +do_sendfile(ConnPid, StreamRef, IoDevice) -> + case file:read(IoDevice, 8000) of + eof -> + gun:data(ConnPid, StreamRef, fin, <<>>), + file:close(IoDevice); + {ok, Bin} -> + gun:data(ConnPid, StreamRef, nofin, Bin), + do_sendfile(ConnPid, StreamRef, IoDevice) + end. +---- + +==== DELETE + +Use `gun:delete/{2,3}` to delete a resource. + +.DELETE "/organizations/ninenines" + +[source,erlang] +StreamRef = gun:delete(ConnPid, "/organizations/ninenines"). + +.DELETE "/organizations/ninenines" with custom headers + +[source,erlang] +StreamRef = gun:delete(ConnPid, "/organizations/ninenines", [ + {<<"user-agent">>, "revolver/1.0"} +]). + +==== OPTIONS + +Use `gun:options/{2,3}` to request information about a resource. + +.OPTIONS "/organizations/ninenines" + +[source,erlang] +StreamRef = gun:options(ConnPid, "/organizations/ninenines"). + +.OPTIONS "/organizations/ninenines" with custom headers + +[source,erlang] +StreamRef = gun:options(ConnPid, "/organizations/ninenines", [ + {<<"user-agent">>, "revolver/1.0"} +]). + +You can also use this function to request information about +the server itself. + +.OPTIONS "*" + +[source,erlang] +StreamRef = gun:options(ConnPid, "*"). + +==== Requests with an arbitrary method + +The `gun:request/{4,5}` function can be used to send requests +with a configurable method name. It is mostly useful when you +need a method that Gun does not understand natively. + +.Example of a TRACE request + +[source,erlang] +gun:request(ConnPid, "TRACE", "/", [ + {<<"max-forwards">>, "30"} +]). + +=== Processing responses + +All data received from the server is sent to the owner +process as a message. First a `gun_response` message is sent, +followed by zero or more `gun_data` messages. If something goes wrong, +a `gun_error` message is sent instead. + +The response message will inform you whether there will be +data messages following. If it contains `fin` there will be +no data messages. If it contains `nofin` then one or more data +messages will follow. + +When using SPDY this value is sent with the frame and simply +passed on in the message. When using HTTP/1.1 however Gun must +guess whether data will follow by looking at the response headers. + +You can receive messages directly, or you can use the _await_ +functions to let Gun receive them for you. + +.Receiving a response using receive + +[source,erlang] +---- +print_body(ConnPid, MRef) -> + StreamRef = gun:get(ConnPid, "/"), + receive + {gun_response, ConnPid, StreamRef, fin, Status, Headers} -> + no_data; + {gun_response, ConnPid, StreamRef, nofin, Status, Headers} -> + receive_data(ConnPid, MRef, StreamRef); + {'DOWN', MRef, process, ConnPid, Reason} -> + error_logger:error_msg("Oops!"), + exit(Reason) + after 1000 -> + exit(timeout) + end. + +receive_data(ConnPid, MRef, StreamRef) -> + receive + {gun_data, ConnPid, StreamRef, nofin, Data} -> + io:format("~s~n", [Data]), + receive_data(ConnPid, MRef, StreamRef); + {gun_data, ConnPid, StreamRef, fin, Data} -> + io:format("~s~n", [Data]); + {'DOWN', MRef, process, ConnPid, Reason} -> + error_logger:error_msg("Oops!"), + exit(Reason) + after 1000 -> + exit(timeout) + end. +---- + +While it may seem verbose, using messages like this has the +advantage of never locking your process, allowing you to +easily debug your code. It also allows you to start more than +one connection and concurrently perform queries on all of them +at the same time. + +You can also use Gun in a synchronous manner by using the _await_ +functions. + +The `gun:await/{2,3,4}` function will wait until it receives +a response to, a pushed resource related to, or data from +the given stream. + +When calling `gun:await/{2,3}` and not passing a monitor +reference, one is automatically created for you for the +duration of the call. + +The `gun:await_body/{2,3,4}` works similarly, but returns the +body received. Both functions can be combined to receive the +response and its body sequentially. + +.Receiving a response using await + +[source,erlang] +StreamRef = gun:get(ConnPid, "/"), +case gun:await(ConnPid, StreamRef) of + {response, fin, Status, Headers} -> + no_data; + {response, nofin, Status, Headers} -> + {ok, Body} = gun:await_body(ConnPid, StreamRef), + io:format("~s~n", [Body]) +end. + +=== Handling streams pushed by the server + +The SPDY protocol allows the server to push more than one +resource for every request. It will start sending those +extra resources before it starts sending the response itself, +so Gun will send you `gun_push` messages before `gun_response` +when that happens. + +You can safely choose to ignore `gun_push` messages, or +you can handle them. If you do, you can either receive the +messages directly or use _await_ functions. + +The `gun_push` message contains both the new stream reference +and the stream reference of the original request. + +.Receiving a pushed response using receive + +[source,erlang] +receive + {gun_push, ConnPid, OriginalStreamRef, PushedStreamRef, + Method, Host, Path, Headers} -> + enjoy() +end. + +If you use the `gun:await/{2,3,4}` function, however, Gun +will use the original reference to identify the message but +will return a tuple that doesn't contain it. + +.Receiving a pushed response using await + +[source,erlang] +{push, PushedStreamRef, Method, Host, Path, Headers} + = gun:await(ConnPid, OriginalStreamRef). + +The `PushedStreamRef` variable can then be used with `gun:await_body/{2,3,4}` +if needed. + +=== Flushing unwanted messages + +Gun provides the function `gun:flush/1` to quickly get rid +of unwanted messages sitting in the process mailbox. You +can use it to get rid of all messages related to a connection, +or just the messages related to a stream. + +.Flush all messages from a Gun connection + +[source,erlang] +gun:flush(ConnPid). + +.Flush all messages from a specific stream + +[source,erlang] +gun:flush(StreamRef). diff --git a/docs/en/gun/1.0/guide/http/index.html b/docs/en/gun/1.0/guide/http/index.html new file mode 100644 index 00000000..6934835d --- /dev/null +++ b/docs/en/gun/1.0/guide/http/index.html @@ -0,0 +1,515 @@ + + + + + + + + + + + + Nine Nines: HTTP + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

HTTP

+ +

This chapter describes how to use the Gun client for +communicating with an HTTP/1.1 or SPDY server.

+
+

Streams

+
+

Every time a request is initiated, Gun creates a stream. +A stream reference uniquely identifies a set of request and +response(s) and must be used to perform additional operations +with a stream or to identify its messages.

+

Stream references use the Erlang reference data type and +are therefore unique.

+

Streams can be canceled at any time. This will stop any further +messages from being sent to the owner process. Depending on +its capabilities, the server will also be instructed to cancel +the request.

+

Canceling a stream may result in Gun dropping the connection +temporarily, to avoid uploading or downloading data that will +not be used.

+
+
Cancelling a stream
+
+
gun:cancel(ConnPid, StreamRef).
+
+
+
+

Sending requests

+
+

Gun provides many convenient functions for performing common +operations, like GET, POST or DELETE. It also provides a +general purpose function in case you need other methods.

+

The availability of these methods on the server can vary +depending on the software used but also on a per-resource +basis.

+

Gun will automatically set a few headers depending on the +method used. For all methods however it will set the host +header if it has not been provided in the request arguments.

+

This section focuses on the act of sending a request. The +handling of responses will be explained further on.

+
+

GET and HEAD

+

Use gun:get/{2,3} to request a resource.

+
+
GET "/organizations/ninenines"
+
+
StreamRef = gun:get(ConnPid, "/organizations/ninenines").
+
+
GET "/organizations/ninenines" with custom headers
+
+
StreamRef = gun:get(ConnPid, "/organizations/ninenines", [
+        {<<"accept">>, "application/json"},
+        {<<"user-agent">>, "revolver/1.0"}
+]).
+

Note that the list of headers has the field name as a binary. +The field value is iodata, which is either a binary or an +iolist.

+

Use gun:head/{2,3} if you don’t need the response body.

+
+
HEAD "/organizations/ninenines"
+
+
StreamRef = gun:head(ConnPid, "/organizations/ninenines").
+
+
HEAD "/organizations/ninenines" with custom headers
+
+
StreamRef = gun:head(ConnPid, "/organizations/ninenines", [
+        {<<"accept">>, "application/json"},
+        {<<"user-agent">>, "revolver/1.0"}
+]).
+

It is not possible to send a request body with a GET or HEAD +request.

+
+
+

POST, PUT and PATCH

+

HTTP defines three methods to create or update a resource.

+

POST is generally used when the resource identifier (URI) isn’t known +in advance when creating the resource. POST can also be used to +replace an existing resource, although PUT is more appropriate +in that situation.

+

PUT creates or replaces a resource identified by the URI.

+

PATCH provides instructions on how to modify the resource.

+

Both POST and PUT send the entire resource representation in their +request body. The PATCH method can be used when this is not +desirable. The request body of a PATCH method may be a partial +representation or a list of instructions on how to update the +resource.

+

The gun:post/4, gun:put/4 and gun:patch/4 functions +take a body as their fourth argument. These functions do +not require any body-specific header to be set, although +it is always recommended to set the content-type header. +Gun will set the other headers automatically.

+

In this and the following examples in this section, gun:post +can be replaced by gun:put or gun:patch for performing +a PUT or PATCH request, respectively.

+
+
POST "/organizations/ninenines"
+
+
Body = "{\"msg\": \"Hello world!\"}",
+StreamRef = gun:post(ConnPid, "/organizations/ninenines", [
+        {<<"content-type">>, "application/json"}
+], Body).
+

The gun:post/3, gun:put/3 and gun:patch/3 functions +do not take a body in their arguments. If a body is to be +provided later on, using the gun:data/4 function, then +the request headers must indicate this. This can be done +by setting the content-length or content-type request +headers. If these headers are not set then Gun will assume +the request has no body.

+

It is recommended to send the content-length header if you +know it in advance, although this is not required. If it +is not set, HTTP/1.1 will use the chunked transfer-encoding, +and SPDY will continue normally as it is chunked by design.

+
+
POST "/organizations/ninenines" with delayed body
+
+
Body = "{\"msg\": \"Hello world!\"}",
+StreamRef = gun:post(ConnPid, "/organizations/ninenines", [
+        {<<"content-length">>, integer_to_binary(length(Body))},
+        {<<"content-type">>, "application/json"}
+]),
+gun:data(ConnPid, StreamRef, fin, Body).
+

The atom fin indicates this is the last chunk of data to +be sent. You can call the gun:data/4 function as many +times as needed until you have sent the entire body. The +last call must use fin and all the previous calls must +use nofin. The last chunk may be empty.

+

@todo what to do about empty chunk, ignore?

+
+
Streaming the request body
+
+
sendfile(ConnPid, StreamRef, Filepath) ->
+        {ok, IoDevice} = file:open(Filepath, [read, binary, raw]),
+        do_sendfile(ConnPid, StreamRef, IoDevice).
+
+do_sendfile(ConnPid, StreamRef, IoDevice) ->
+        case file:read(IoDevice, 8000) of
+                eof ->
+                        gun:data(ConnPid, StreamRef, fin, <<>>),
+                        file:close(IoDevice);
+                {ok, Bin} ->
+                        gun:data(ConnPid, StreamRef, nofin, Bin),
+                        do_sendfile(ConnPid, StreamRef, IoDevice)
+        end.
+
+
+

DELETE

+

Use gun:delete/{2,3} to delete a resource.

+
+
DELETE "/organizations/ninenines"
+
+
StreamRef = gun:delete(ConnPid, "/organizations/ninenines").
+
+
DELETE "/organizations/ninenines" with custom headers
+
+
StreamRef = gun:delete(ConnPid, "/organizations/ninenines", [
+        {<<"user-agent">>, "revolver/1.0"}
+]).
+
+
+

OPTIONS

+

Use gun:options/{2,3} to request information about a resource.

+
+
OPTIONS "/organizations/ninenines"
+
+
StreamRef = gun:options(ConnPid, "/organizations/ninenines").
+
+
OPTIONS "/organizations/ninenines" with custom headers
+
+
StreamRef = gun:options(ConnPid, "/organizations/ninenines", [
+        {<<"user-agent">>, "revolver/1.0"}
+]).
+

You can also use this function to request information about +the server itself.

+
+
OPTIONS "*"
+
+
StreamRef = gun:options(ConnPid, "*").
+
+
+

Requests with an arbitrary method

+

The gun:request/{4,5} function can be used to send requests +with a configurable method name. It is mostly useful when you +need a method that Gun does not understand natively.

+
+
Example of a TRACE request
+
+
gun:request(ConnPid, "TRACE", "/", [
+        {<<"max-forwards">>, "30"}
+]).
+
+
+
+
+

Processing responses

+
+

All data received from the server is sent to the owner +process as a message. First a gun_response message is sent, +followed by zero or more gun_data messages. If something goes wrong, +a gun_error message is sent instead.

+

The response message will inform you whether there will be +data messages following. If it contains fin there will be +no data messages. If it contains nofin then one or more data +messages will follow.

+

When using SPDY this value is sent with the frame and simply +passed on in the message. When using HTTP/1.1 however Gun must +guess whether data will follow by looking at the response headers.

+

You can receive messages directly, or you can use the await +functions to let Gun receive them for you.

+
+
Receiving a response using receive
+
+
print_body(ConnPid, MRef) ->
+        StreamRef = gun:get(ConnPid, "/"),
+        receive
+                {gun_response, ConnPid, StreamRef, fin, Status, Headers} ->
+                        no_data;
+                {gun_response, ConnPid, StreamRef, nofin, Status, Headers} ->
+                        receive_data(ConnPid, MRef, StreamRef);
+                {'DOWN', MRef, process, ConnPid, Reason} ->
+                        error_logger:error_msg("Oops!"),
+                        exit(Reason)
+        after 1000 ->
+                exit(timeout)
+        end.
+
+receive_data(ConnPid, MRef, StreamRef) ->
+        receive
+                {gun_data, ConnPid, StreamRef, nofin, Data} ->
+                        io:format("~s~n", [Data]),
+                        receive_data(ConnPid, MRef, StreamRef);
+                {gun_data, ConnPid, StreamRef, fin, Data} ->
+                        io:format("~s~n", [Data]);
+                {'DOWN', MRef, process, ConnPid, Reason} ->
+                        error_logger:error_msg("Oops!"),
+                        exit(Reason)
+        after 1000 ->
+                exit(timeout)
+        end.
+

While it may seem verbose, using messages like this has the +advantage of never locking your process, allowing you to +easily debug your code. It also allows you to start more than +one connection and concurrently perform queries on all of them +at the same time.

+

You can also use Gun in a synchronous manner by using the await +functions.

+

The gun:await/{2,3,4} function will wait until it receives +a response to, a pushed resource related to, or data from +the given stream.

+

When calling gun:await/{2,3} and not passing a monitor +reference, one is automatically created for you for the +duration of the call.

+

The gun:await_body/{2,3,4} works similarly, but returns the +body received. Both functions can be combined to receive the +response and its body sequentially.

+
+
Receiving a response using await
+
+
StreamRef = gun:get(ConnPid, "/"),
+case gun:await(ConnPid, StreamRef) of
+        {response, fin, Status, Headers} ->
+                no_data;
+        {response, nofin, Status, Headers} ->
+                {ok, Body} = gun:await_body(ConnPid, StreamRef),
+                io:format("~s~n", [Body])
+end.
+
+
+
+

Handling streams pushed by the server

+
+

The SPDY protocol allows the server to push more than one +resource for every request. It will start sending those +extra resources before it starts sending the response itself, +so Gun will send you gun_push messages before gun_response +when that happens.

+

You can safely choose to ignore gun_push messages, or +you can handle them. If you do, you can either receive the +messages directly or use await functions.

+

The gun_push message contains both the new stream reference +and the stream reference of the original request.

+
+
Receiving a pushed response using receive
+
+
receive
+        {gun_push, ConnPid, OriginalStreamRef, PushedStreamRef,
+                        Method, Host, Path, Headers} ->
+                enjoy()
+end.
+

If you use the gun:await/{2,3,4} function, however, Gun +will use the original reference to identify the message but +will return a tuple that doesn’t contain it.

+
+
Receiving a pushed response using await
+
+
{push, PushedStreamRef, Method, Host, Path, Headers}
+        = gun:await(ConnPid, OriginalStreamRef).
+

The PushedStreamRef variable can then be used with gun:await_body/{2,3,4} +if needed.

+
+
+
+

Flushing unwanted messages

+
+

Gun provides the function gun:flush/1 to quickly get rid +of unwanted messages sitting in the process mailbox. You +can use it to get rid of all messages related to a connection, +or just the messages related to a stream.

+
+
Flush all messages from a Gun connection
+
+
gun:flush(ConnPid).
+
+
Flush all messages from a specific stream
+
+
gun:flush(StreamRef).
+
+
+ + + +
+ +
+ + +

+ Gun + 1.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.0
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/gun/1.0/guide/index.html b/docs/en/gun/1.0/guide/index.html new file mode 100644 index 00000000..bc2b9831 --- /dev/null +++ b/docs/en/gun/1.0/guide/index.html @@ -0,0 +1,172 @@ + + + + + + + + + + + + Nine Nines: Gun User Guide + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Gun User Guide

+ +
+ + + +
+ +
+ + +

+ Gun + 1.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.0
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/gun/1.0/guide/introduction.asciidoc b/docs/en/gun/1.0/guide/introduction.asciidoc new file mode 100644 index 00000000..81a7c7f4 --- /dev/null +++ b/docs/en/gun/1.0/guide/introduction.asciidoc @@ -0,0 +1,28 @@ +== Introduction + +Gun is an Erlang HTTP client with support for HTTP/1.1, SPDY and Websocket. + +=== Prerequisites + +Knowledge of Erlang, but also of the HTTP/1.1, SPDY and Websocket +protocols is required in order to read this guide. + +=== Supported platforms + +Gun is tested and supported on Linux. + +Gun is developed for Erlang 18+. + +Gun may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as intended. + +=== Conventions + +In the HTTP protocol, the method name is case sensitive. All standard +method names are uppercase. + +Header names are case insensitive. Gun converts all the header names +to lowercase, and expects your application to provide lowercase header +names. + +The same applies to any other case insensitive value. diff --git a/docs/en/gun/1.0/guide/introduction/index.html b/docs/en/gun/1.0/guide/introduction/index.html new file mode 100644 index 00000000..c8f85e5b --- /dev/null +++ b/docs/en/gun/1.0/guide/introduction/index.html @@ -0,0 +1,168 @@ + + + + + + + + + + + + Nine Nines: Introduction + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Introduction

+ +

Gun is an Erlang HTTP client with support for HTTP/1.1, SPDY and Websocket.

+
+

Prerequisites

+
+

Knowledge of Erlang, but also of the HTTP/1.1, SPDY and Websocket +protocols is required in order to read this guide.

+
+
+
+

Supported platforms

+
+

Gun is tested and supported on Linux.

+

Gun is developed for Erlang 18+.

+

Gun may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as intended.

+
+
+
+

Conventions

+
+

In the HTTP protocol, the method name is case sensitive. All standard +method names are uppercase.

+

Header names are case insensitive. Gun converts all the header names +to lowercase, and expects your application to provide lowercase header +names.

+

The same applies to any other case insensitive value.

+
+
+ + + +
+ +
+ + +

+ Gun + 1.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.0
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/gun/1.0/guide/protocols.asciidoc b/docs/en/gun/1.0/guide/protocols.asciidoc new file mode 100644 index 00000000..2180c5b4 --- /dev/null +++ b/docs/en/gun/1.0/guide/protocols.asciidoc @@ -0,0 +1,119 @@ +== Supported protocols + +This chapter describes the protocols supported and the +operations available to them. + +=== HTTP/1.1 + +HTTP/1.1 is a text request-response protocol. The client +sends a request, the server sends back a response. + +Gun provides convenience functions for performing GET, HEAD, +OPTIONS, POST, PATCH, PUT, and DELETE requests. All these +functions are aliases of `gun:request/{4,5}` for each respective +methods. Gun also provides a `gun:data/4` function for streaming +the request body. + +Gun will send a `gun_response` message for every response +received, followed by zero or more `gun_data` messages for +the response body. If something goes wrong, a `gun_error` +will be sent instead. + +Gun provides convenience functions for dealing with messages. +The `gun:await/{2,3,4}` function waits for a response to the given +request, and the `gun:await_body/{2,3,4}` function for the +response's body. The `gun:flush/1` function can be used to clear all +messages related to a request or a connection from the mailbox +of the process. + +The function `gun:cancel/2` can be used to silence the +response to a request previously sent if it is no longer +needed. When using HTTP/1.1 there is no multiplexing so +Gun will have to receive the response fully before any +other response can be received. + +Finally, Gun can upgrade an HTTP/1.1 connection to Websocket. +It provides the `gun:ws_upgrade/{2,3,4}` function for that +purpose. A `gun_ws_upgrade` message will be sent on success; +a `gun_response` message otherwise. + +=== SPDY + +SPDY is a binary protocol based on HTTP, compatible with +the HTTP semantics, that reduces the complexity of parsing +requests and responses, compresses the HTTP headers and +allows the server to push multiple responses to a single +request. + +The SPDY interface is very similar to HTTP/1.1, so this +section instead focuses on the differences in the interface +for the two protocols. + +Because a SPDY server can push multiple responses to a +single request, Gun might send `gun_push` messages for +every push received. They can be ignored safely if they +are not needed. + +The `gun:cancel/2` function will use the SPDY stream +cancellation mechanism which allows Gun to inform the +server to stop sending a response for this particular +request, saving resources. + +It is not possible to upgrade a SPDY connection to Websocket +due to protocol limitations. + +=== Websocket + +Websocket is a binary protocol built on top of HTTP that +allows asynchronous concurrent communication between the +client and the server. A Websocket server can push data to +the client at any time. + +Websocket is only available as a connection upgrade over +an HTTP/1.1 connection. + +Once the Websocket connection is established, the only +operation available on this connection is sending Websocket +frames using `gun:ws_send/2`. + +Gun will send a `gun_ws` message for every frame received. + +=== Summary + +The two following tables summarize the supported operations +and the messages Gun sends depending on the connection's +current protocol. + +.Supported operations per protocol +[cols="<,3*^",options="header"] +|=== +| Operation | HTTP/1.1 | SPDY | Websocket +| delete | yes | yes | no +| get | yes | yes | no +| head | yes | yes | no +| options | yes | yes | no +| patch | yes | yes | no +| post | yes | yes | no +| put | yes | yes | no +| request | yes | yes | no +| data | yes | yes | no +| await | yes | yes | no +| await_body | yes | yes | no +| flush | yes | yes | no +| cancel | yes | yes | no +| ws_upgrade | yes | no | no +| ws_send | no | no | yes +|=== + +.Messages sent per protocol +[cols="<,3*^",options="header"] +|=== +| Message | HTTP/1.1 | SPDY | Websocket +| gun_push | no | yes | no +| gun_response | yes | yes | no +| gun_data | yes | yes | no +| gun_error (StreamRef) | yes | yes | no +| gun_error | yes | yes | yes +| gun_ws_upgrade | yes | no | no +| gun_ws | no | no | yes +|=== diff --git a/docs/en/gun/1.0/guide/protocols/index.html b/docs/en/gun/1.0/guide/protocols/index.html new file mode 100644 index 00000000..ed694fce --- /dev/null +++ b/docs/en/gun/1.0/guide/protocols/index.html @@ -0,0 +1,395 @@ + + + + + + + + + + + + Nine Nines: Supported protocols + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Supported protocols

+ +

This chapter describes the protocols supported and the +operations available to them.

+
+

HTTP/1.1

+
+

HTTP/1.1 is a text request-response protocol. The client +sends a request, the server sends back a response.

+

Gun provides convenience functions for performing GET, HEAD, +OPTIONS, POST, PATCH, PUT, and DELETE requests. All these +functions are aliases of gun:request/{4,5} for each respective +methods. Gun also provides a gun:data/4 function for streaming +the request body.

+

Gun will send a gun_response message for every response +received, followed by zero or more gun_data messages for +the response body. If something goes wrong, a gun_error +will be sent instead.

+

Gun provides convenience functions for dealing with messages. +The gun:await/{2,3,4} function waits for a response to the given +request, and the gun:await_body/{2,3,4} function for the +response’s body. The gun:flush/1 function can be used to clear all +messages related to a request or a connection from the mailbox +of the process.

+

The function gun:cancel/2 can be used to silence the +response to a request previously sent if it is no longer +needed. When using HTTP/1.1 there is no multiplexing so +Gun will have to receive the response fully before any +other response can be received.

+

Finally, Gun can upgrade an HTTP/1.1 connection to Websocket. +It provides the gun:ws_upgrade/{2,3,4} function for that +purpose. A gun_ws_upgrade message will be sent on success; +a gun_response message otherwise.

+
+
+
+

SPDY

+
+

SPDY is a binary protocol based on HTTP, compatible with +the HTTP semantics, that reduces the complexity of parsing +requests and responses, compresses the HTTP headers and +allows the server to push multiple responses to a single +request.

+

The SPDY interface is very similar to HTTP/1.1, so this +section instead focuses on the differences in the interface +for the two protocols.

+

Because a SPDY server can push multiple responses to a +single request, Gun might send gun_push messages for +every push received. They can be ignored safely if they +are not needed.

+

The gun:cancel/2 function will use the SPDY stream +cancellation mechanism which allows Gun to inform the +server to stop sending a response for this particular +request, saving resources.

+

It is not possible to upgrade a SPDY connection to Websocket +due to protocol limitations.

+
+
+
+

Websocket

+
+

Websocket is a binary protocol built on top of HTTP that +allows asynchronous concurrent communication between the +client and the server. A Websocket server can push data to +the client at any time.

+

Websocket is only available as a connection upgrade over +an HTTP/1.1 connection.

+

Once the Websocket connection is established, the only +operation available on this connection is sending Websocket +frames using gun:ws_send/2.

+

Gun will send a gun_ws message for every frame received.

+
+
+
+

Summary

+
+

The two following tables summarize the supported operations +and the messages Gun sends depending on the connection’s +current protocol.

+
+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1. Supported operations per protocol
Operation HTTP/1.1 SPDY Websocket

delete

yes

yes

no

get

yes

yes

no

head

yes

yes

no

options

yes

yes

no

patch

yes

yes

no

post

yes

yes

no

put

yes

yes

no

request

yes

yes

no

data

yes

yes

no

await

yes

yes

no

await_body

yes

yes

no

flush

yes

yes

no

cancel

yes

yes

no

ws_upgrade

yes

no

no

ws_send

no

no

yes

+
+
+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 2. Messages sent per protocol
Message HTTP/1.1 SPDY Websocket

gun_push

no

yes

no

gun_response

yes

yes

no

gun_data

yes

yes

no

gun_error (StreamRef)

yes

yes

no

gun_error

yes

yes

yes

gun_ws_upgrade

yes

no

no

gun_ws

no

no

yes

+
+
+
+ + + +
+ +
+ + +

+ Gun + 1.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.0
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/gun/1.0/guide/start.asciidoc b/docs/en/gun/1.0/guide/start.asciidoc new file mode 100644 index 00000000..6d93e2e8 --- /dev/null +++ b/docs/en/gun/1.0/guide/start.asciidoc @@ -0,0 +1,67 @@ +== Starting and stopping + +This chapter describes how to start and stop the Gun application. + +=== Setting up + +Before Gun can be used it needs to be in Erlang's `ERL_LIBS` path variable. +If you use `erlang.mk` or a similar build tool, you only need to specify +Gun as a dependency to your application and the tool will take care +of downloading Gun and setting up paths. + +With `erlang.mk` this is done by adding `gun` to the `DEPS` variable +in your Makefile. + +.Adding Gun as an erlang.mk dependency + +[source,make] +DEPS = gun + +=== Starting + +Gun is an _OTP application_. It needs to be started before you can +use it. + +.Starting Gun in an Erlang shell + +[source,erlang] +---- +1> application:ensure_all_started(gun). +{ok,[ranch,crypto,cowlib,asn1,public_key,ssl,gun]} +---- + +=== Stopping + +You can stop Gun using the `application:stop/1` function, however +only Gun will be stopped. This is the equivalent of `application:start/1`. +The `application_ensure_all_started/1` function has no equivalent for +stopping all applications. + +.Stopping Gun + +[source,erlang] +application:stop(gun). + +=== Using Gun with releases + +An _OTP release_ starts applications automatically. All you need +to do is to set up your application resource file so that Gun can +be included in the release. The application resource file can be +found in `ebin/your_application.app`, or in `src/your_application.app.src` +if you are using a build tool like `erlang.mk`. + +The key you need to change is the `applications` key. By default +it only includes `kernel` and `stdlib`. You need to add `gun` to +that list. + +.Adding Gun to the application resource file + +[source,erlang] +{applications, [ + kernel, + stdlib, + gun +]} + +Do not put an extra comma at the end, the comma is a separator +between the elements of the list. diff --git a/docs/en/gun/1.0/guide/start/index.html b/docs/en/gun/1.0/guide/start/index.html new file mode 100644 index 00000000..d8b8cc96 --- /dev/null +++ b/docs/en/gun/1.0/guide/start/index.html @@ -0,0 +1,216 @@ + + + + + + + + + + + + Nine Nines: Starting and stopping + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Starting and stopping

+ +

This chapter describes how to start and stop the Gun application.

+
+

Setting up

+
+

Before Gun can be used it needs to be in Erlang’s ERL_LIBS path variable. +If you use erlang.mk or a similar build tool, you only need to specify +Gun as a dependency to your application and the tool will take care +of downloading Gun and setting up paths.

+

With erlang.mk this is done by adding gun to the DEPS variable +in your Makefile.

+
+
Adding Gun as an erlang.mk dependency
+
+
DEPS = gun
+
+
+
+

Starting

+
+

Gun is an OTP application. It needs to be started before you can +use it.

+
+
Starting Gun in an Erlang shell
+
+
1> application:ensure_all_started(gun).
+{ok,[ranch,crypto,cowlib,asn1,public_key,ssl,gun]}
+
+
+
+

Stopping

+
+

You can stop Gun using the application:stop/1 function, however +only Gun will be stopped. This is the equivalent of application:start/1. +The application_ensure_all_started/1 function has no equivalent for +stopping all applications.

+
+
Stopping Gun
+
+
application:stop(gun).
+
+
+
+

Using Gun with releases

+
+

An OTP release starts applications automatically. All you need +to do is to set up your application resource file so that Gun can +be included in the release. The application resource file can be +found in ebin/your_application.app, or in src/your_application.app.src +if you are using a build tool like erlang.mk.

+

The key you need to change is the applications key. By default +it only includes kernel and stdlib. You need to add gun to +that list.

+
+
Adding Gun to the application resource file
+
+
{applications, [
+        kernel,
+        stdlib,
+        gun
+]}
+

Do not put an extra comma at the end, the comma is a separator +between the elements of the list.

+
+
+ + + +
+ +
+ + +

+ Gun + 1.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.0
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/gun/1.0/guide/websocket.asciidoc b/docs/en/gun/1.0/guide/websocket.asciidoc new file mode 100644 index 00000000..4869a2e4 --- /dev/null +++ b/docs/en/gun/1.0/guide/websocket.asciidoc @@ -0,0 +1,112 @@ +== Websocket + +This chapter describes how to use the Gun client for +communicating with a Websocket server. + +@todo recovering from connection failure +reconnecting to Websocket etc. + +=== HTTP upgrade + +Websocket is a protocol built on top of HTTP. To use Websocket, +you must first request for the connection to be upgraded. Only +HTTP/1.1 connections can be upgraded to Websocket, so you might +need to restrict the protocol to HTTP/1.1 if you are planning +to use Websocket over TLS. + +You must use the `gun_ws:upgrade/{2,3,4}` function to upgrade +to Websocket. This function can be called anytime after connection, +so you can send HTTP requests before upgrading to Websocket. + +.Upgrade to Websocket + +[source,erlang] +gun:ws_upgrade(ConnPid, "/websocket"). + +Gun will set all the necessary headers for performing the +Websocket upgrade, but you can specify additional headers +if needed. For example you can request a custom sub-protocol. + +.Upgrade to Websocket and request a protocol + +[source,erlang] +gun:ws_upgrade(ConnPid, "/websocket", [ + {<<"sec-websocket-protocol">>, "mychat"} +]). + +You can pass the Websocket options as part of the `gun:open/{2,3}` +call when opening the connection, or using the `gun:ws_upgrade/4`. +The fourth argument is those same options. This function call +will crash if the options are incorrect, unlike when passing +them through `gun:open/{2,3}`. + +When the upgrade succeeds, a `gun_ws_upgrade` message is sent. +If the server does not understand Websocket or refused the +upgrade, a `gun_response` message is sent. If Gun couldn't +perform the upgrade due to an error (for example attempting +to upgrade to Websocket on an HTTP/1.0 connection) then a +`gun_error` message is sent. + +When the server does not understand Websocket, it may send +a meaningful response which should be processed. In the +following example we however ignore it: + +[source,erlang] +receive + {gun_ws_upgrade, ConnPid, ok, Headers} -> + upgrade_success(ConnPid); + {gun_response, ConnPid, _, _, Status, Headers} -> + exit({ws_upgrade_failed, Status, Headers}); + {gun_error, ConnPid, StreamRef, Reason} -> + exit({ws_upgrade_failed, Reason}) + %% More clauses here as needed. +after 1000 -> + exit(timeout) +end. + +=== Sending data + +Once the Websocket upgrade has completed successfully, you no +longer have access to functions for performing requests. You +can only send and receive Websocket messages. + +Use `gun:ws_send/2` to send one or more messages to the server. + +@todo Implement sending of N frames + +.Send a text frame + +[source,erlang] +gun:ws_send(ConnPid, {text, "Hello!"}). + +.Send a text frame, a binary frame and then close the connection + +[source,erlang] +gun:ws_send(ConnPid, [ + {text, "Hello!"}, + {binary, BinaryValue}, + close +]). + +Note that if you send a close frame, Gun will close the connection +cleanly and will not attempt to reconnect afterwards, similar to +calling `gun:shutdown/1`. + +=== Receiving data + +Gun sends an Erlang message to the owner process for every +Websocket message it receives. + +[source,erlang] +receive + {gun_ws, ConnPid, Frame} -> + handle_frame(ConnPid, Frame) +end. + +@todo auto ping has not been implemented yet + +Gun will automatically send ping messages to the server to keep +the connection alive, however if the connection dies and Gun has +to reconnect it will not upgrade to Websocket automatically, you +need to perform the operation when you receive the `gun_error` +message. diff --git a/docs/en/gun/1.0/guide/websocket/index.html b/docs/en/gun/1.0/guide/websocket/index.html new file mode 100644 index 00000000..78a34d42 --- /dev/null +++ b/docs/en/gun/1.0/guide/websocket/index.html @@ -0,0 +1,259 @@ + + + + + + + + + + + + Nine Nines: Websocket + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Websocket

+ +

This chapter describes how to use the Gun client for +communicating with a Websocket server.

+

@todo recovering from connection failure +reconnecting to Websocket etc.

+
+

HTTP upgrade

+
+

Websocket is a protocol built on top of HTTP. To use Websocket, +you must first request for the connection to be upgraded. Only +HTTP/1.1 connections can be upgraded to Websocket, so you might +need to restrict the protocol to HTTP/1.1 if you are planning +to use Websocket over TLS.

+

You must use the gun_ws:upgrade/{2,3,4} function to upgrade +to Websocket. This function can be called anytime after connection, +so you can send HTTP requests before upgrading to Websocket.

+
+
Upgrade to Websocket
+
+
gun:ws_upgrade(ConnPid, "/websocket").
+

Gun will set all the necessary headers for performing the +Websocket upgrade, but you can specify additional headers +if needed. For example you can request a custom sub-protocol.

+
+
Upgrade to Websocket and request a protocol
+
+
gun:ws_upgrade(ConnPid, "/websocket", [
+        {<<"sec-websocket-protocol">>, "mychat"}
+]).
+

You can pass the Websocket options as part of the gun:open/{2,3} +call when opening the connection, or using the gun:ws_upgrade/4. +The fourth argument is those same options. This function call +will crash if the options are incorrect, unlike when passing +them through gun:open/{2,3}.

+

When the upgrade succeeds, a gun_ws_upgrade message is sent. +If the server does not understand Websocket or refused the +upgrade, a gun_response message is sent. If Gun couldn’t +perform the upgrade due to an error (for example attempting +to upgrade to Websocket on an HTTP/1.0 connection) then a +gun_error message is sent.

+

When the server does not understand Websocket, it may send +a meaningful response which should be processed. In the +following example we however ignore it:

+
+
+
receive
+        {gun_ws_upgrade, ConnPid, ok, Headers} ->
+                upgrade_success(ConnPid);
+        {gun_response, ConnPid, _, _, Status, Headers} ->
+                exit({ws_upgrade_failed, Status, Headers});
+        {gun_error, ConnPid, StreamRef, Reason} ->
+                exit({ws_upgrade_failed, Reason})
+        %% More clauses here as needed.
+after 1000 ->
+        exit(timeout)
+end.
+
+
+
+

Sending data

+
+

Once the Websocket upgrade has completed successfully, you no +longer have access to functions for performing requests. You +can only send and receive Websocket messages.

+

Use gun:ws_send/2 to send one or more messages to the server.

+

@todo Implement sending of N frames

+
+
Send a text frame
+
+
gun:ws_send(ConnPid, {text, "Hello!"}).
+
+
Send a text frame, a binary frame and then close the connection
+
+
gun:ws_send(ConnPid, [
+        {text, "Hello!"},
+        {binary, BinaryValue},
+        close
+]).
+

Note that if you send a close frame, Gun will close the connection +cleanly and will not attempt to reconnect afterwards, similar to +calling gun:shutdown/1.

+
+
+
+

Receiving data

+
+

Gun sends an Erlang message to the owner process for every +Websocket message it receives.

+
+
+
receive
+        {gun_ws, ConnPid, Frame} ->
+                handle_frame(ConnPid, Frame)
+end.
+

@todo auto ping has not been implemented yet

+

Gun will automatically send ping messages to the server to keep +the connection alive, however if the connection dies and Gun has +to reconnect it will not upgrade to Websocket automatically, you +need to perform the operation when you receive the gun_error +message.

+
+
+ + + +
+ +
+ + +

+ Gun + 1.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.0
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/gun/1.0/index.html b/docs/en/gun/1.0/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/gun/1.0/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/gun/1.0/manual/gun/index.html b/docs/en/gun/1.0/manual/gun/index.html new file mode 100644 index 00000000..dc40e30e --- /dev/null +++ b/docs/en/gun/1.0/manual/gun/index.html @@ -0,0 +1,1734 @@ + + + + + + + + + + + + Nine Nines: gun(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

gun(3)

+ +
+

Name

+
+

gun - asynchronous HTTP client

+
+
+
+

Description

+
+

The gun module provides an asynchronous interface for +connecting and communicating with Web servers over SPDY, +HTTP or Websocket.

+
+
+
+

Types

+
+
+

opts() = map()

+

Configuration for the connection.

+

The following keys are defined:

+
+
+http_opts ⇒ http_opts() +
+
+

+ Options specific to the HTTP protocol. See below. +

+
+
+protocols ⇒ [http | spdy] +
+
+

+ Ordered list of preferred protocols. When the transport is tcp, + this list must contain exactly one protocol. When the transport + is ssl, this list must contain at least one protocol and will be + used using the NPN protocol negotiation method. When the server + does not support NPN then http will always be used. Defaults to + [http] when the transport is tcp, and [spdy, http] when the + transport is ssl. +

+
+
+retry ⇒ non_neg_integer() +
+
+

+ Number of times Gun will try to reconnect on failure before giving up. + Defaults to 5. +

+
+
+retry_timeout ⇒ pos_integer() +
+
+

+ Time between retries in milliseconds. Defaults to 5000. +

+
+
+spdy_opts ⇒ spdy_opts() +
+
+

+ Options specific to the SPDY protocol. See below. +

+
+
+trace ⇒ boolean() +
+
+

+ Whether to enable dbg tracing of the connection process. Should + only be used during debugging. Defaults to false. +

+
+
+transport ⇒ tcp | ssl +
+
+

+ Whether to use SSL or plain TCP. The default varies depending on the + port used. Port 443 defaults to ssl. All other ports default to tcp. +

+
+
+transport_opts ⇒ proplists:proplist() +
+
+

+ Transport options. They are TCP options or SSL options depending on + the selected transport. +

+
+
+ws_opts ⇒ ws_opts() +
+
+

+ Options specific to the Websocket protocol. See below. +

+
+
+
+
+

http_opts() = map()

+

Configuration for the HTTP protocol.

+

The following keys are defined:

+
+
+keepalive ⇒ pos_integer() +
+
+

+ Time between pings in milliseconds. Since the HTTP protocol has + no standardized way to ping the server, Gun will simply send an + empty line when the connection is idle. Gun only makes a best + effort here as servers usually have configurable limits to drop + idle connections. Defaults to 5000. +

+
+
+version ⇒ HTTP/1.1 | HTTP/1.0 +
+
+

+ HTTP version to use. Defaults to HTTP/1.1. +

+
+
+
+
+

spdy_opts() = map()

+

Configuration for the SPDY protocol.

+

The following keys are defined:

+
+
+keepalive ⇒ pos_integer() +
+
+

+ Time between pings in milliseconds. Defaults to 5000. +

+
+
+
+
+

ws_opts() = map()

+

Configuration for the Websocket protocol.

+

The following keys are defined:

+
+
+compress ⇒ boolean() +
+
+

+ Whether to enable permessage-deflate compression. This does + not guarantee that compression will be used as it is the + server that ultimately decides. Defaults to false. +

+
+
+
+
+
+
+

Messages

+
+

Calling functions from this module may result in the following +messages being sent.

+
+

{gun_up, ConnPid, Protocol}

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Protocol = http | spdy +
+
+

+The protocol selected for this connection. +

+
+
+

The connection is up.

+

This message informs the owner process that the connection or +reconnection completed.

+

The protocol selected during the connection is sent in this +message. It can be used to determine the capabilities of the +server.

+

Gun will now start processing the messages it received while +waiting for the connection to be up. If this is a reconnection, +then this may not be desirable for all requests. Those requests +should be cancelled when the connection goes down, and any +subsequent messages ignored.

+
+
+

{gun_down, ConnPid, Protocol, Reason, KilledStreams, UnprocessedStreams}

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Protocol = http | spdy | ws +
+
+

+The protocol in use when the connection was lost. +

+
+
+Reason = normal | closed | {error, atom()} +
+
+

+The reason for the loss of the connection. +

+
+
+KilledStreams = [reference()] +
+
+

+List of streams that have been brutally terminated. +

+
+
+UnprocessedStreams = [reference()] +
+
+

+List of streams that have not been processed by the server. +

+
+
+

The connection is down.

+

This message informs the owner process that the connection is +currently down. Gun will automatically attempt to reconnect +depending on the retry and retry_timeout options.

+

The reason of the termination is there for debugging purposes +only. You should not rely on this value to know what streams +were processed or completed.

+

The killed streams are the active streams that did not complete +before the closing of the connection. Whether they can be retried +safely depends on the protocol used and the idempotence property +of the requests.

+

The unprocessed streams are streams that the server did not +start processing yet. They may be retried safely depending on +what streams were killed before.

+

When the connection goes back up, Gun will not attempt to retry +requests. It will also not upgrade to Websocket automatically +if that was the protocol in use when the connection was lost.

+
+
+

{gun_push, ConnPid, StreamRef, NewStreamRef, URI, Headers}

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream initiated by the owner process. +

+
+
+NewStreamRef = reference() +
+
+

+Identifier of the stream being pushed. +

+
+
+URI = binary() +
+
+

+URI of the resource. +

+
+
+Headers = [{binary(), binary()}] +
+
+

+Headers @todo +

+
+
+

A resource pushed alongside an HTTP response.

+

This message can only be sent when the protocol is SPDY.

+

@todo I fear we also need the scheme; resource is identified by URI +@todo Perhaps we really should send the URI entirely, because cache +@todo relies on URI to work and this feature is for caching… +@todo Not sure why Method is there, spec says it is only for GET

+
+
+

{gun_response, ConnPid, StreamRef, IsFin, Status, Headers}

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream initiated by the owner process. +

+
+
+IsFin = fin | nofin +
+
+

+Whether this message terminates the response. +

+
+
+Status = binary() +
+
+

+Status line for the response. +

+
+
+Headers = [{binary(), binary()}] +
+
+

+Headers sent with the response. +

+
+
+

A response to an HTTP request.

+
+
+

{gun_data, ConnPid, StreamRef, IsFin, Data}

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream this data belongs to. +

+
+
+IsFin = fin | nofin +
+
+

+Whether this message terminates the response. +

+
+
+Data = binary() +
+
+

+Data from the stream. +

+
+
+

Data associated with a stream.

+

The stream in question can be either one initiated by the owner +process or a stream initiated by the server through the push +mechanism. In any case a gun_response or a gun_push message +will be sent before any gun_data message.

+
+
+

{gun_error, ConnPid, StreamRef, Reason}

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream this error relates to. +

+
+
+Reason = any() +
+
+

+Error reason. +

+
+
+

Stream-specific error.

+
+
+

{gun_error, ConnPid, Reason}

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Reason = any() +
+
+

+Error reason. +

+
+
+

General error.

+
+
+

{gun_ws_upgrade, ConnPid, ok, Headers}

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Headers = [{binary(), binary()}] +
+
+

+Headers sent with the response. +

+
+
+

Successful upgrade to the Websocket protocol.

+
+
+

{gun_ws, ConnPid, Frame}

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Frame = @todo +
+
+

+Frame. +

+
+
+

Websocket frame.

+
+
+
+
+

Exports

+
+
+

open(Host, Port) → open(Host, Port, [])

+

Alias of gun:open/3.

+
+
+

open(Host, Port, Opts) → {ok, ConnPid} | {error, Reason}

+
+
+Host = inet:hostname() +
+
+

+Host to connect to. +

+
+
+Port = inet:port_number() +
+
+

+Port to connect to. +

+
+
+Opts = opts() +
+
+

+Options for this connection. +

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Reason = any() +
+
+

+Error reason. @todo really any? +

+
+
+

Open a connection to the given host and port.

+
+
+

close(ConnPid) → ok

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+

Brutally close the connection.

+
+
+

shutdown(ConnPid) → ok

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+

Gracefully close the connection.

+

A monitor can be used to be notified when the connection is +effectively closed.

+
+
+

delete(ConnPid, Path) → delete(ConnPid, Path, [])

+

Alias of gun:delete/3.

+
+
+

delete(ConnPid, Path, Headers) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Path = iodata() +
+
+

+Path to the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Delete a resource.

+
+
+

get(ConnPid, Path) → get(ConnPid, Path, [])

+

Alias of gun:get/3.

+
+
+

get(ConnPid, Path, Headers) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Path = iodata() +
+
+

+Path to the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Get a resource.

+
+
+

head(ConnPid, Path) → head(ConnPid, Path, [])

+

Alias of gun:head/3.

+
+
+

head(ConnPid, Path, Headers) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Path = iodata() +
+
+

+Path to the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Get headers of a resource.

+

This function performs the same operation as get/{2,3} except +the server will not send the resource representation, only the +response’s status line and headers.

+

While servers should send the same headers they would if the +request was a GET, like content-length, it is not always +the case and differences may exist.

+
+
+

options(ConnPid, Path) → options(ConnPid, Path, [])

+

Alias of gun:options/3.

+
+
+

options(ConnPid, Path, Headers) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Path = iodata() +
+
+

+Path to the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Obtain information about the capabilities of the server or of a resource.

+

The special path "*" can be used to obtain information about +the server as a whole. Any other path will return information +about the resource only.

+
+
+

patch(ConnPid, Path, Headers) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Path = iodata() +
+
+

+Path to the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Request that a set of changes be applied to the resource.

+

This function expects either content-length or content-type +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.

+

The body sent in this request should be a patch document +with instructions on how to update the resource.

+

You can use the gun:data/4 function to send the body, if any.

+
+
+

patch(ConnPid, Path, Headers, Body) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Path = iodata() +
+
+

+Path to the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+Body = iodata() +
+
+

+Body of the request. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Request that a set of changes be applied to the resource.

+

It is highly recommended to set the content-type header +to inform the server what media type the body contains. +Gun will automatically set the content-length header.

+

The body sent in this request should be a patch document +with instructions on how to update the resource.

+

The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.

+
+
+

post(ConnPid, Path, Headers) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Path = iodata() +
+
+

+Path to the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Process the enclosed representation according to the resource’s own semantics.

+

This function expects either content-length or content-type +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.

+

The body sent in this request will be processed +according to the resource’s own semantics. A new +resource may be created as a result, and may be +located at a different URI.

+

You can use the gun:data/4 function to send the body, if any.

+
+
+

post(ConnPid, Path, Headers, Body) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Path = iodata() +
+
+

+Path to the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+Body = iodata() +
+
+

+Body of the request. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Process the enclosed representation according to the resource’s own semantics.

+

It is highly recommended to set the content-type header +to inform the server what media type the body contains. +Gun will automatically set the content-length header.

+

The body sent in this request will be processed +according to the resource’s own semantics. A new +resource may be created as a result, and may be +located at a different URI.

+

The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.

+
+
+

put(ConnPid, Path, Headers) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Path = iodata() +
+
+

+Path to the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Create or replace a resource.

+

The body of the request is the entire representation of the resource.

+

This function expects either content-length or content-type +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.

+

You can use the gun:data/4 function to send the body, if any.

+
+
+

put(ConnPid, Path, Headers, Body) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Path = iodata() +
+
+

+Path to the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+Body = iodata() +
+
+

+Body of the request. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Create or replace a resource.

+

The body of the request is the entire representation of the resource.

+

It is highly recommended to set the content-type header +to inform the server what media type the body contains. +Gun will automatically set the content-length header.

+

The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.

+
+
+

request(ConnPid, Method, Path, Headers) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Method = iodata() +
+
+

+Request method. +

+
+
+Path = iodata() +
+
+

+Path of the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Perform the given request.

+

This is a general purpose function that should only be used +when existing method-specific functions don’t apply.

+

This function expects either content-length or content-type +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.

+

You can use the gun:data/4 function to send the body, if any.

+
+
+

request(ConnPid, Method, Path, Headers, Body) → StreamRef

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Method = iodata() +
+
+

+Request method. +

+
+
+Path = iodata() +
+
+

+Path of the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+Body = iodata() +
+
+

+Body of the request. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream for this request. +

+
+
+

Perform the given request.

+

This is a general purpose function that should only be used +when existing method-specific functions don’t apply.

+

It is highly recommended to set the content-type header +to inform the server what media type the body contains. +Gun will automatically set the content-length header.

+

The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.

+
+
+

data(ConnPid, StreamRef, IsFin, Data) → ok

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream this data belongs to. +

+
+
+IsFin = fin | nofin +
+
+

+Whether this message terminates the request. +

+
+
+Data = iodata() +
+
+

+Data to be sent with the request. +

+
+
+

Stream the body of a request.

+

@todo empty chunks

+

This function can only be used if the request identified by +StreamRef came with headers indicating the presence of a +body and that body not being given when creating the request.

+

All calls to this function must use nofin except for the +last which must use fin to indicate the end of the request +body.

+

Empty data is allowed regardless of the value of IsFin. +Gun will not send empty data chunks unless required to +indicate the request body is finished, however.

+
+
+

await(ConnPid, StreamRef) → await(ConnPid, StreamRef, 5000, MonitorRef)

+

Alias of gun:await/4.

+

A monitor MonitorRef is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.

+
+
+

await(ConnPid, StreamRef, MonitorRef) → await(ConnPid, StreamRef, 5000, MonitorRef)

+

Alias of gun:await/4.

+
+
+

await(ConnPid, StreamRef, Timeout) → await(ConnPid, StreamRef, Timeout, MonitorRef)

+

Alias of gun:await/4.

+

A monitor MonitorRef is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.

+
+
+

await(ConnPid, StreamRef, Timeout, MonitorRef) → tuple() — see below

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream to await messages from. +

+
+
+Timeout = timeout() +
+
+

+How long this function will wait for messages. +

+
+
+MonitorRef = reference() +
+
+

+Monitor reference for the Gun connection process. +

+
+
+

Wait for a response message.

+

This function can be used when a synchronous handling of +responses is desired. It will only return when a message +for the given stream is received, on error or on timeout.

+

The return values are described in the next few subsections.

+
+

{response, IsFin, Status, Headers}

+
+
+IsFin = fin | nofin +
+
+

+Whether this message terminates the response. +

+
+
+Status = binary() +
+
+

+Status line for the response. +

+
+
+Headers = [{binary(), binary()}] +
+
+

+Headers sent with the response. +

+
+
+

Equivalent of a gun_response message.

+
+
+

{data, IsFin, Data}

+
+
+IsFin = fin | nofin +
+
+

+Whether this message terminates the response. +

+
+
+Data = binary() +
+
+

+Data from the stream. +

+
+
+

Equivalent of a gun_data message.

+
+
+

{push, NewStreamRef, URI, Headers}

+
+
+NewStreamRef = reference() +
+
+

+Identifier of the stream being pushed. +

+
+
+URI = binary() +
+
+

+URI of the resource. +

+
+
+Headers = [{binary(), binary()}] +
+
+

+Headers @todo +

+
+
+

Equivalent of a gun_push message.

+

@todo Same changes as gun_push

+
+
+

{error, Reason}

+
+
+Reason = any() +
+
+

+Error reason. @todo any? +

+
+
+

Equivalent of a gun_error message.

+

@todo I think we want to distinguish a stream error, a general error, +@todo a DOWN and a timeout error

+
+
+
+

await_body(ConnPid, StreamRef) → await_body(ConnPid, StreamRef, 5000, MonitorRef)

+

Alias of gun:await_body/4.

+

A monitor MonitorRef is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.

+
+
+

await_body(ConnPid, StreamRef, MonitorRef) → await_body(ConnPid, StreamRef, 5000, MonitorRef)

+

Alias of gun:await_body/4.

+
+
+

await_body(ConnPid, StreamRef, Timeout) → await_body(ConnPid, StreamRef, Timeout, MonitorRef)

+

Alias of gun:await_body/4.

+

A monitor MonitorRef is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.

+
+
+

await_body(ConnPid, StreamRef, Timeout, MonitorRef) → {ok, Body} | {error, Reason}

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream to await messages from. +

+
+
+Timeout = timeout() +
+
+

+How long this function will wait for each message. +

+
+
+MonitorRef = reference() +
+
+

+Monitor reference for the Gun connection process. +

+
+
+Body = binary() +
+
+

+Body for the given stream. +

+
+
+Reason = any() +
+
+

+Error reason. @todo any? +

+
+
+

Wait for a response body.

+

This function can be used when a synchronous handling of +responses is desired. It will only return when it has +finished fetching the entire response body.

+

The timeout value is per message. The actual function call +can last much longer for large bodies.

+

@todo I think we want to distinguish a stream error, a general error, +@todo a DOWN and a timeout error

+

@todo guide might be a little incorrect about await/await_body

+
+
+

flush(ConnPid) → ok

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+

Flush all messages from the Gun connection process from the mailbox.

+
+
+

flush(StreamRef) → ok

+
+
+StreamRef = reference() +
+
+

+Stream identifier. +

+
+
+

Flush all messages related to the given stream.

+
+
+

cancel(ConnPid, StreamRef) → ok

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+StreamRef = reference() +
+
+

+Identifier of the stream to cancel. +

+
+
+

Cancel the given stream.

+

HTTP/1.1 streams can’t be cancelled. Gun will simply silence +the stream and stop relaying messages.

+

@todo Depending on the length +@todo of a response Gun may also attempt to reconnect rather than +@todo receive the entire response body.

+

SPDY streams can however be cancelled at any time.

+
+
+

ws_upgrade(ConnPid, Path) → ws_upgrade(ConnPid, Path, [], #{})

+

Alias of gun:ws_upgrade/3.

+
+
+

ws_upgrade(ConnPid, Path, Headers) → ok

+

Similar to gun:ws_upgrade/4, except WsOpts is taken from +the options given in the gun:open/{2,3} call when opening +the connection.

+
+
+

ws_upgrade(ConnPid, Path, Headers, WsOpts) → ok

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Path = iodata() +
+
+

+Path to the resource. +

+
+
+Headers = [{binary(), iodata()}] +
+
+

+Additional request headers. +

+
+
+WsOpts = map() +
+
+

+Options for the Websocket connection. +

+
+
+

Request the connection to be upgraded to the Websocket protocol.

+

This function can only be used when the current protocol is http.

+
+
+

ws_send(ConnPid, Frames) → ok

+
+
+ConnPid = pid() +
+
+

+The pid of the Gun connection process. +

+
+
+Frames = @todo +
+
+

+@todo +

+
+
+

Send one or more Websocket frames.

+

This function can only be used following a successful ws_upgrade call.

+
+
+
+ + + +
+ +
+ + +

+ Gun + 1.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.0
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/gun/1.0/manual/gun_app/index.html b/docs/en/gun/1.0/manual/gun_app/index.html new file mode 100644 index 00000000..2d5404b3 --- /dev/null +++ b/docs/en/gun/1.0/manual/gun_app/index.html @@ -0,0 +1,168 @@ + + + + + + + + + + + + Nine Nines: gun(7) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

gun(7)

+ +
+

Name

+
+

gun - Erlang HTTP client with support for HTTP/1.1, SPDY and Websocket.

+
+
+
+

Dependencies

+
+

The gun application uses the Erlang applications ranch +for abstracting TCP and TLS over a common interface, and +the ssl application for TLS support, required for HTTPS +and SPDY support. In addition, Gun requires the crypto +application (a dependency of ssl) for Websocket.

+

These dependencies must be started for the gun +application to work. In an embedded environment +this means that they need to be started with the +application:start/{1,2} function before the gun +application is started.

+
+
+
+

Environment

+
+

The gun application does not define any application +environment configuration parameters.

+
+
+ + + +
+ +
+ + +

+ Gun + 1.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.0
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/gun/1.0/manual/index.html b/docs/en/gun/1.0/manual/index.html new file mode 100644 index 00000000..d919d90c --- /dev/null +++ b/docs/en/gun/1.0/manual/index.html @@ -0,0 +1,152 @@ + + + + + + + + + + + + Nine Nines: Gun Function Reference + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Gun Function Reference

+ +
+ + + +
+ +
+ + +

+ Gun + 1.0 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.0
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/gun/index.html b/docs/en/gun/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/gun/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/index.html b/docs/en/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/ranch/1.2/guide/embedded.asciidoc b/docs/en/ranch/1.2/guide/embedded.asciidoc new file mode 100644 index 00000000..593a8079 --- /dev/null +++ b/docs/en/ranch/1.2/guide/embedded.asciidoc @@ -0,0 +1,48 @@ +== Embedded mode + +Embedded mode allows you to insert Ranch listeners directly +in your supervision tree. This allows for greater fault tolerance +control by permitting the shutdown of a listener due to the +failure of another part of the application and vice versa. + +=== Embedding + +To embed Ranch in your application you can simply add the child specs +to your supervision tree. This can all be done in the `init/1` function +of one of your application supervisors. + +Ranch requires at the minimum two kinds of child specs for embedding. +First, you need to add `ranch_sup` to your supervision tree, only once, +regardless of the number of listeners you will use. Then you need to +add the child specs for each listener. + +Ranch has a convenience function for getting the listeners child specs +called `ranch:child_spec/6`, that works like `ranch:start_listener/6`, +except that it doesn't start anything, it only returns child specs. + +As for `ranch_sup`, the child spec is simple enough to not require a +convenience function. + +The following example adds both `ranch_sup` and one listener to another +application's supervision tree. + +.Embed Ranch directly in your supervision tree + +[source,erlang] +---- +init([]) -> + RanchSupSpec = {ranch_sup, {ranch_sup, start_link, []}, + permanent, 5000, supervisor, [ranch_sup]}, + ListenerSpec = ranch:child_spec(echo, 100, + ranch_tcp, [{port, 5555}], + echo_protocol, [] + ), + {ok, {{one_for_one, 10, 10}, [RanchSupSpec, ListenerSpec]}}. +---- + +Remember, you can add as many listener child specs as needed, but only +one `ranch_sup` spec! + +It is recommended that your architecture makes sure that all listeners +are restarted if `ranch_sup` fails. See the Ranch internals chapter for +more details on how Ranch does it. diff --git a/docs/en/ranch/1.2/guide/embedded/index.html b/docs/en/ranch/1.2/guide/embedded/index.html new file mode 100644 index 00000000..e8cd3eca --- /dev/null +++ b/docs/en/ranch/1.2/guide/embedded/index.html @@ -0,0 +1,182 @@ + + + + + + + + + + + + Nine Nines: Embedded mode + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Embedded mode

+ +

Embedded mode allows you to insert Ranch listeners directly +in your supervision tree. This allows for greater fault tolerance +control by permitting the shutdown of a listener due to the +failure of another part of the application and vice versa.

+
+

Embedding

+
+

To embed Ranch in your application you can simply add the child specs +to your supervision tree. This can all be done in the init/1 function +of one of your application supervisors.

+

Ranch requires at the minimum two kinds of child specs for embedding. +First, you need to add ranch_sup to your supervision tree, only once, +regardless of the number of listeners you will use. Then you need to +add the child specs for each listener.

+

Ranch has a convenience function for getting the listeners child specs +called ranch:child_spec/6, that works like ranch:start_listener/6, +except that it doesn’t start anything, it only returns child specs.

+

As for ranch_sup, the child spec is simple enough to not require a +convenience function.

+

The following example adds both ranch_sup and one listener to another +application’s supervision tree.

+
+
Embed Ranch directly in your supervision tree
+
+
init([]) ->
+        RanchSupSpec = {ranch_sup, {ranch_sup, start_link, []},
+                permanent, 5000, supervisor, [ranch_sup]},
+        ListenerSpec = ranch:child_spec(echo, 100,
+                ranch_tcp, [{port, 5555}],
+                echo_protocol, []
+        ),
+        {ok, {{one_for_one, 10, 10}, [RanchSupSpec, ListenerSpec]}}.
+

Remember, you can add as many listener child specs as needed, but only +one ranch_sup spec!

+

It is recommended that your architecture makes sure that all listeners +are restarted if ranch_sup fails. See the Ranch internals chapter for +more details on how Ranch does it.

+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/guide/index.html b/docs/en/ranch/1.2/guide/index.html new file mode 100644 index 00000000..cb3d49c1 --- /dev/null +++ b/docs/en/ranch/1.2/guide/index.html @@ -0,0 +1,182 @@ + + + + + + + + + + + + Nine Nines: Ranch User Guide + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Ranch User Guide

+ +
+ + + +
+ +
+ + +

+ Ranch + 1.2 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/guide/internals.asciidoc b/docs/en/ranch/1.2/guide/internals.asciidoc new file mode 100644 index 00000000..fa63f1d3 --- /dev/null +++ b/docs/en/ranch/1.2/guide/internals.asciidoc @@ -0,0 +1,94 @@ +== Internals + +This chapter may not apply to embedded Ranch as embedding allows you +to use an architecture specific to your application, which may or may +not be compatible with the description of the Ranch application. + +Note that for everything related to efficiency and performance, +you should perform the benchmarks yourself to get the numbers that +matter to you. Generic benchmarks found on the web may or may not +be of use to you, you can never know until you benchmark your own +system. + +=== Architecture + +Ranch is an OTP application. + +Like all OTP applications, Ranch has a top supervisor. It is responsible +for supervising the `ranch_server` process and all the listeners that +will be started. + +The `ranch_server` gen_server is a central process keeping track of the +listeners and their acceptors. It does so through the use of a public ets +table called `ranch_server`. The table is owned by the top supervisor +to improve fault tolerance. This way if the `ranch_server` gen_server +fails, it doesn't lose any information and the restarted process can +continue as if nothing happened. + +Ranch uses a custom supervisor for managing connections. This supervisor +keeps track of the number of connections and handles connection limits +directly. While it is heavily optimized to perform the task of creating +connection processes for accepted connections, it is still following the +OTP principles and the usual `sys` and `supervisor` calls will work on +it as expected. + +Listeners are grouped into the `ranch_listener_sup` supervisor and +consist of three kinds of processes: the listener gen_server, the +acceptor processes and the connection processes, both grouped under +their own supervisor. All of these processes are registered to the +`ranch_server` gen_server with varying amount of information. + +All socket operations, including listening for connections, go through +transport handlers. Accepted connections are given to the protocol handler. +Transport handlers are simple callback modules for performing operations on +sockets. Protocol handlers start a new process, which receives socket +ownership, with no requirements on how the code should be written inside +that new process. + +=== Number of acceptors + +The second argument to `ranch:start_listener/6` is the number of +processes that will be accepting connections. Care should be taken +when choosing this number. + +First of all, it should not be confused with the maximum number +of connections. Acceptor processes are only used for accepting and +have nothing else in common with connection processes. Therefore +there is nothing to be gained from setting this number too high, +in fact it can slow everything else down. + +Second, this number should be high enough to allow Ranch to accept +connections concurrently. But the number of cores available doesn't +seem to be the only factor for choosing this number, as we can +observe faster accepts if we have more acceptors than cores. It +might be entirely dependent on the protocol, however. + +Our observations suggest that using 100 acceptors on modern hardware +is a good solution, as it's big enough to always have acceptors ready +and it's low enough that it doesn't have a negative impact on the +system's performances. + +=== Platform-specific TCP features + +Some socket options are platform-specific and not supported by `inet`. +They can be of interest because they generally are related to +optimizations provided by the underlying OS. They can still be enabled +thanks to the `raw` option, for which we will see an example. + +One of these features is `TCP_DEFER_ACCEPT` on Linux. It is a simplified +accept mechanism which will wait for application data to come in before +handing out the connection to the Erlang process. + +This is especially useful if you expect many connections to be mostly +idle, perhaps part of a connection pool. They can be handled by the +kernel directly until they send any real data, instead of allocating +resources to idle connections. + +To enable this mechanism, the following option can be used. + +.Using raw transport options + +[source,erlang] +{raw, 6, 9, << 30:32/native >>} + +It means go on layer 6, turn on option 9 with the given integer parameter. diff --git a/docs/en/ranch/1.2/guide/internals/index.html b/docs/en/ranch/1.2/guide/internals/index.html new file mode 100644 index 00000000..bd7610c7 --- /dev/null +++ b/docs/en/ranch/1.2/guide/internals/index.html @@ -0,0 +1,227 @@ + + + + + + + + + + + + Nine Nines: Internals + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Internals

+ +

This chapter may not apply to embedded Ranch as embedding allows you +to use an architecture specific to your application, which may or may +not be compatible with the description of the Ranch application.

+

Note that for everything related to efficiency and performance, +you should perform the benchmarks yourself to get the numbers that +matter to you. Generic benchmarks found on the web may or may not +be of use to you, you can never know until you benchmark your own +system.

+
+

Architecture

+
+

Ranch is an OTP application.

+

Like all OTP applications, Ranch has a top supervisor. It is responsible +for supervising the ranch_server process and all the listeners that +will be started.

+

The ranch_server gen_server is a central process keeping track of the +listeners and their acceptors. It does so through the use of a public ets +table called ranch_server. The table is owned by the top supervisor +to improve fault tolerance. This way if the ranch_server gen_server +fails, it doesn’t lose any information and the restarted process can +continue as if nothing happened.

+

Ranch uses a custom supervisor for managing connections. This supervisor +keeps track of the number of connections and handles connection limits +directly. While it is heavily optimized to perform the task of creating +connection processes for accepted connections, it is still following the +OTP principles and the usual sys and supervisor calls will work on +it as expected.

+

Listeners are grouped into the ranch_listener_sup supervisor and +consist of three kinds of processes: the listener gen_server, the +acceptor processes and the connection processes, both grouped under +their own supervisor. All of these processes are registered to the +ranch_server gen_server with varying amount of information.

+

All socket operations, including listening for connections, go through +transport handlers. Accepted connections are given to the protocol handler. +Transport handlers are simple callback modules for performing operations on +sockets. Protocol handlers start a new process, which receives socket +ownership, with no requirements on how the code should be written inside +that new process.

+
+
+
+

Number of acceptors

+
+

The second argument to ranch:start_listener/6 is the number of +processes that will be accepting connections. Care should be taken +when choosing this number.

+

First of all, it should not be confused with the maximum number +of connections. Acceptor processes are only used for accepting and +have nothing else in common with connection processes. Therefore +there is nothing to be gained from setting this number too high, +in fact it can slow everything else down.

+

Second, this number should be high enough to allow Ranch to accept +connections concurrently. But the number of cores available doesn’t +seem to be the only factor for choosing this number, as we can +observe faster accepts if we have more acceptors than cores. It +might be entirely dependent on the protocol, however.

+

Our observations suggest that using 100 acceptors on modern hardware +is a good solution, as it’s big enough to always have acceptors ready +and it’s low enough that it doesn’t have a negative impact on the +system’s performances.

+
+
+
+

Platform-specific TCP features

+
+

Some socket options are platform-specific and not supported by inet. +They can be of interest because they generally are related to +optimizations provided by the underlying OS. They can still be enabled +thanks to the raw option, for which we will see an example.

+

One of these features is TCP_DEFER_ACCEPT on Linux. It is a simplified +accept mechanism which will wait for application data to come in before +handing out the connection to the Erlang process.

+

This is especially useful if you expect many connections to be mostly +idle, perhaps part of a connection pool. They can be handled by the +kernel directly until they send any real data, instead of allocating +resources to idle connections.

+

To enable this mechanism, the following option can be used.

+
+
Using raw transport options
+
+
{raw, 6, 9, << 30:32/native >>}
+

It means go on layer 6, turn on option 9 with the given integer parameter.

+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/guide/introduction.asciidoc b/docs/en/ranch/1.2/guide/introduction.asciidoc new file mode 100644 index 00000000..3199fb2f --- /dev/null +++ b/docs/en/ranch/1.2/guide/introduction.asciidoc @@ -0,0 +1,25 @@ +== Introduction + +Ranch is a socket acceptor pool for TCP protocols. + +Ranch aims to provide everything you need to accept TCP connections +with a small code base and low latency while being easy to use directly +as an application or to embed into your own. + +=== Prerequisites + +It is assumed the developer already knows Erlang and has some experience +with socket programming and TCP protocols. + +=== Supported platforms + +Ranch is tested and supported on Linux. + +Ranch is developed for Erlang R15B01+. + +Ranch may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as expected. + +=== Versioning + +Ranch uses http://semver.org/[Semantic Versioning 2.0.0] diff --git a/docs/en/ranch/1.2/guide/introduction/index.html b/docs/en/ranch/1.2/guide/introduction/index.html new file mode 100644 index 00000000..2a6d275c --- /dev/null +++ b/docs/en/ranch/1.2/guide/introduction/index.html @@ -0,0 +1,166 @@ + + + + + + + + + + + + Nine Nines: Introduction + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Introduction

+ +

Ranch is a socket acceptor pool for TCP protocols.

+

Ranch aims to provide everything you need to accept TCP connections +with a small code base and low latency while being easy to use directly +as an application or to embed into your own.

+
+

Prerequisites

+
+

It is assumed the developer already knows Erlang and has some experience +with socket programming and TCP protocols.

+
+
+
+

Supported platforms

+
+

Ranch is tested and supported on Linux.

+

Ranch is developed for Erlang R15B01+.

+

Ranch may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as expected.

+
+
+
+

Versioning

+
+

Ranch uses Semantic Versioning 2.0.0

+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/guide/listeners.asciidoc b/docs/en/ranch/1.2/guide/listeners.asciidoc new file mode 100644 index 00000000..ef2d49c7 --- /dev/null +++ b/docs/en/ranch/1.2/guide/listeners.asciidoc @@ -0,0 +1,251 @@ +== Listeners + +A listener is a set of processes whose role is to listen on a port +for new connections. It manages a pool of acceptor processes, each +of them indefinitely accepting connections. When it does, it starts +a new process executing the protocol handler code. All the socket +programming is abstracted through the user of transport handlers. + +The listener takes care of supervising all the acceptor and connection +processes, allowing developers to focus on building their application. + +=== Starting a listener + +Ranch does nothing by default. It is up to the application developer +to request that Ranch listens for connections. + +A listener can be started and stopped at will. + +When starting a listener, a number of different settings are required: + +* A name to identify it locally and be able to interact with it. +* The number of acceptors in the pool. +* A transport handler and its associated options. +* A protocol handler and its associated options. + +Ranch includes both TCP and SSL transport handlers, respectively +`ranch_tcp` and `ranch_ssl`. + +A listener can be started by calling the `ranch:start_listener/6` +function. Before doing so however, you must ensure that the `ranch` +application is started. + +.Starting the Ranch application + +[source,erlang] +ok = application:start(ranch). + +You are then ready to start a listener. Let's call it `tcp_echo`. It will +have a pool of 100 acceptors, use a TCP transport and forward connections +to the `echo_protocol` handler. + +.Starting a listener for TCP connections on port 5555 + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 5555}], + echo_protocol, [] +). + +You can try this out by compiling and running the `tcp_echo` example in the +examples directory. To do so, open a shell in the 'examples/tcp_echo/' +directory and run the following command: + +.Building and starting a Ranch example + +[source,bash] +$ make run + +You can then connect to it using telnet and see the echo server reply +everything you send to it. Then when you're done testing, you can use +the `Ctrl+]` key to escape to the telnet command line and type +`quit` to exit. + +.Connecting to the example listener with telnet + +[source,bash] +---- +$ telnet localhost 5555 +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. +Hello! +Hello! +It works! +It works! +^] + +telnet> quit +Connection closed. +---- + +=== Stopping a listener + +All you need to stop a Ranch listener is to call the +`ranch:stop_listener/1` function with the listener's name +as argument. In the previous section we started the listener +named `tcp_echo`. We can now stop it. + +.Stopping a listener + +[source,erlang] +ranch:stop_listener(tcp_echo). + +=== Default transport options + +By default the socket will be set to return `binary` data, with the +options `{active, false}`, `{packet, raw}`, `{reuseaddr, true}` set. +These values can't be overriden when starting the listener, but +they can be overriden using `Transport:setopts/2` in the protocol. + +It will also set `{backlog, 1024}` and `{nodelay, true}`, which +can be overriden at listener startup. + +=== Listening on a random port + +You do not have to specify a specific port to listen on. If you give +the port number 0, or if you omit the port number entirely, Ranch will +start listening on a random port. + +You can retrieve this port number by calling `ranch:get_port/1`. The +argument is the name of the listener you gave in `ranch:start_listener/6`. + +.Starting a listener for TCP connections on a random port + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 0}], + echo_protocol, [] +). +Port = ranch:get_port(tcp_echo). + +=== Listening on privileged ports + +Some systems limit access to ports below 1024 for security reasons. +This can easily be identified by an `{error, eacces}` error when trying +to open a listening socket on such a port. + +The methods for listening on privileged ports vary between systems, +please refer to your system's documentation for more information. + +We recommend the use of port rewriting for systems with a single server, +and load balancing for systems with multiple servers. Documenting these +solutions is however out of the scope of this guide. + +=== Accepting connections on an existing socket + +If you want to accept connections on an existing socket, you can use the +`socket` transport option, which should just be the relevant data returned +from the connect function for the transport or the underlying socket library +(`gen_tcp:connect`, `ssl:connect`). The accept function will then be +called on the passed in socket. You should connect the socket in +`{active, false}` mode, as well. + +Note, however, that because of a bug in SSL, you cannot change ownership of an +SSL listen socket prior to R16. Ranch will catch the error thrown, but the +owner of the SSL socket will remain as whatever process created the socket. +However, this will not affect accept behaviour unless the owner process dies, +in which case the socket is closed. Therefore, to use this feature with SSL +with an erlang release prior to R16, ensure that the SSL socket is opened in a +persistant process. + +=== Limiting the number of concurrent connections + +The `max_connections` transport option allows you to limit the number +of concurrent connections. It defaults to 1024. Its purpose is to +prevent your system from being overloaded and ensuring all the +connections are handled optimally. + +.Customizing the maximum number of concurrent connections + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 5555}, {max_connections, 100}], + echo_protocol, [] +). + +You can disable this limit by setting its value to the atom `infinity`. + +.Disabling the limit for the number of connections + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 5555}, {max_connections, infinity}], + echo_protocol, [] +). + +You may not always want connections to be counted when checking for +`max_connections`. For example you might have a protocol where both +short-lived and long-lived connections are possible. If the long-lived +connections are mostly waiting for messages, then they don't consume +much resources and can safely be removed from the count. + +To remove the connection from the count, you must call the +`ranch:remove_connection/1` from within the connection process, +with the name of the listener as the only argument. + +.Removing a connection from the count of connections + +[source,erlang] +ranch:remove_connection(Ref). + +As seen in the chapter covering protocols, this pid is received as the +first argument of the protocol's `start_link/4` callback. + +You can modify the `max_connections` value on a running listener by +using the `ranch:set_max_connections/2` function, with the name of the +listener as first argument and the new value as the second. + +.Upgrading the maximum number of connections + +[source,erlang] +ranch:set_max_connections(tcp_echo, MaxConns). + +The change will occur immediately. + +=== Using a supervisor for connection processes + +Ranch allows you to define the type of process that will be used +for the connection processes. By default it expects a `worker`. +When the `connection_type` configuration value is set to `supervisor`, +Ranch will consider that the connection process it manages is a +supervisor and will reflect that in its supervision tree. + +Connection processes of type `supervisor` can either handle the +socket directly or through one of their children. In the latter +case the start function for the connection process must return +two pids: the pid of the supervisor you created (that will be +supervised) and the pid of the protocol handling process (that +will receive the socket). + +Instead of returning `{ok, ConnPid}`, simply return +`{ok, SupPid, ConnPid}`. + +It is very important that the connection process be created +under the supervisor process so that everything works as intended. +If not, you will most likely experience issues when the supervised +process is stopped. + +=== Upgrading + +Ranch allows you to upgrade the protocol options. This takes effect +immediately and for all subsequent connections. + +To upgrade the protocol options, call `ranch:set_protocol_options/2` +with the name of the listener as first argument and the new options +as the second. + +.Upgrading the protocol options + +[source,erlang] +ranch:set_protocol_options(tcp_echo, NewOpts). + +All future connections will use the new options. + +You can also retrieve the current options similarly by +calling `ranch:get_protocol_options/1`. + +.Retrieving the current protocol options + +[source,erlang] +Opts = ranch:get_protocol_options(tcp_echo). diff --git a/docs/en/ranch/1.2/guide/listeners/index.html b/docs/en/ranch/1.2/guide/listeners/index.html new file mode 100644 index 00000000..638b15af --- /dev/null +++ b/docs/en/ranch/1.2/guide/listeners/index.html @@ -0,0 +1,421 @@ + + + + + + + + + + + + Nine Nines: Listeners + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Listeners

+ +

A listener is a set of processes whose role is to listen on a port +for new connections. It manages a pool of acceptor processes, each +of them indefinitely accepting connections. When it does, it starts +a new process executing the protocol handler code. All the socket +programming is abstracted through the user of transport handlers.

+

The listener takes care of supervising all the acceptor and connection +processes, allowing developers to focus on building their application.

+
+

Starting a listener

+
+

Ranch does nothing by default. It is up to the application developer +to request that Ranch listens for connections.

+

A listener can be started and stopped at will.

+

When starting a listener, a number of different settings are required:

+
    +
  • +

    +A name to identify it locally and be able to interact with it. +

    +
    • +
  • +

    +The number of acceptors in the pool. +

    +
    • +
  • +

    +A transport handler and its associated options. +

    +
    • +
  • +

    +A protocol handler and its associated options. +

    +
    • +
+

Ranch includes both TCP and SSL transport handlers, respectively +ranch_tcp and ranch_ssl.

+

A listener can be started by calling the ranch:start_listener/6 +function. Before doing so however, you must ensure that the ranch +application is started.

+
+
Starting the Ranch application
+
+
ok = application:start(ranch).
+

You are then ready to start a listener. Let’s call it tcp_echo. It will +have a pool of 100 acceptors, use a TCP transport and forward connections +to the echo_protocol handler.

+
+
Starting a listener for TCP connections on port 5555
+
+
{ok, _} = ranch:start_listener(tcp_echo, 100,
+        ranch_tcp, [{port, 5555}],
+        echo_protocol, []
+).
+

You can try this out by compiling and running the tcp_echo example in the +examples directory. To do so, open a shell in the examples/tcp_echo/ +directory and run the following command:

+
+
Building and starting a Ranch example
+
+
$ make run
+

You can then connect to it using telnet and see the echo server reply +everything you send to it. Then when you’re done testing, you can use +the Ctrl+] key to escape to the telnet command line and type +quit to exit.

+
+
Connecting to the example listener with telnet
+
+
$ telnet localhost 5555
+Trying 127.0.0.1...
+Connected to localhost.
+Escape character is '^]'.
+Hello!
+Hello!
+It works!
+It works!
+^]
+
+telnet> quit
+Connection closed.
+
+
+
+

Stopping a listener

+
+

All you need to stop a Ranch listener is to call the +ranch:stop_listener/1 function with the listener’s name +as argument. In the previous section we started the listener +named tcp_echo. We can now stop it.

+
+
Stopping a listener
+
+
ranch:stop_listener(tcp_echo).
+
+
+
+

Default transport options

+
+

By default the socket will be set to return binary data, with the +options {active, false}, {packet, raw}, {reuseaddr, true} set. +These values can’t be overriden when starting the listener, but +they can be overriden using Transport:setopts/2 in the protocol.

+

It will also set {backlog, 1024} and {nodelay, true}, which +can be overriden at listener startup.

+
+
+
+

Listening on a random port

+
+

You do not have to specify a specific port to listen on. If you give +the port number 0, or if you omit the port number entirely, Ranch will +start listening on a random port.

+

You can retrieve this port number by calling ranch:get_port/1. The +argument is the name of the listener you gave in ranch:start_listener/6.

+
+
Starting a listener for TCP connections on a random port
+
+
{ok, _} = ranch:start_listener(tcp_echo, 100,
+        ranch_tcp, [{port, 0}],
+        echo_protocol, []
+).
+Port = ranch:get_port(tcp_echo).
+
+
+
+

Listening on privileged ports

+
+

Some systems limit access to ports below 1024 for security reasons. +This can easily be identified by an {error, eacces} error when trying +to open a listening socket on such a port.

+

The methods for listening on privileged ports vary between systems, +please refer to your system’s documentation for more information.

+

We recommend the use of port rewriting for systems with a single server, +and load balancing for systems with multiple servers. Documenting these +solutions is however out of the scope of this guide.

+
+
+
+

Accepting connections on an existing socket

+
+

If you want to accept connections on an existing socket, you can use the +socket transport option, which should just be the relevant data returned +from the connect function for the transport or the underlying socket library +(gen_tcp:connect, ssl:connect). The accept function will then be +called on the passed in socket. You should connect the socket in +{active, false} mode, as well.

+

Note, however, that because of a bug in SSL, you cannot change ownership of an +SSL listen socket prior to R16. Ranch will catch the error thrown, but the +owner of the SSL socket will remain as whatever process created the socket. +However, this will not affect accept behaviour unless the owner process dies, +in which case the socket is closed. Therefore, to use this feature with SSL +with an erlang release prior to R16, ensure that the SSL socket is opened in a +persistant process.

+
+
+
+

Limiting the number of concurrent connections

+
+

The max_connections transport option allows you to limit the number +of concurrent connections. It defaults to 1024. Its purpose is to +prevent your system from being overloaded and ensuring all the +connections are handled optimally.

+
+
Customizing the maximum number of concurrent connections
+
+
{ok, _} = ranch:start_listener(tcp_echo, 100,
+        ranch_tcp, [{port, 5555}, {max_connections, 100}],
+        echo_protocol, []
+).
+

You can disable this limit by setting its value to the atom infinity.

+
+
Disabling the limit for the number of connections
+
+
{ok, _} = ranch:start_listener(tcp_echo, 100,
+        ranch_tcp, [{port, 5555}, {max_connections, infinity}],
+        echo_protocol, []
+).
+

You may not always want connections to be counted when checking for +max_connections. For example you might have a protocol where both +short-lived and long-lived connections are possible. If the long-lived +connections are mostly waiting for messages, then they don’t consume +much resources and can safely be removed from the count.

+

To remove the connection from the count, you must call the +ranch:remove_connection/1 from within the connection process, +with the name of the listener as the only argument.

+
+
Removing a connection from the count of connections
+
+
ranch:remove_connection(Ref).
+

As seen in the chapter covering protocols, this pid is received as the +first argument of the protocol’s start_link/4 callback.

+

You can modify the max_connections value on a running listener by +using the ranch:set_max_connections/2 function, with the name of the +listener as first argument and the new value as the second.

+
+
Upgrading the maximum number of connections
+
+
ranch:set_max_connections(tcp_echo, MaxConns).
+

The change will occur immediately.

+
+
+
+

Using a supervisor for connection processes

+
+

Ranch allows you to define the type of process that will be used +for the connection processes. By default it expects a worker. +When the connection_type configuration value is set to supervisor, +Ranch will consider that the connection process it manages is a +supervisor and will reflect that in its supervision tree.

+

Connection processes of type supervisor can either handle the +socket directly or through one of their children. In the latter +case the start function for the connection process must return +two pids: the pid of the supervisor you created (that will be +supervised) and the pid of the protocol handling process (that +will receive the socket).

+

Instead of returning {ok, ConnPid}, simply return +{ok, SupPid, ConnPid}.

+

It is very important that the connection process be created +under the supervisor process so that everything works as intended. +If not, you will most likely experience issues when the supervised +process is stopped.

+
+
+
+

Upgrading

+
+

Ranch allows you to upgrade the protocol options. This takes effect +immediately and for all subsequent connections.

+

To upgrade the protocol options, call ranch:set_protocol_options/2 +with the name of the listener as first argument and the new options +as the second.

+
+
Upgrading the protocol options
+
+
ranch:set_protocol_options(tcp_echo, NewOpts).
+

All future connections will use the new options.

+

You can also retrieve the current options similarly by +calling ranch:get_protocol_options/1.

+
+
Retrieving the current protocol options
+
+
Opts = ranch:get_protocol_options(tcp_echo).
+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/guide/parsers.asciidoc b/docs/en/ranch/1.2/guide/parsers.asciidoc new file mode 100644 index 00000000..9eacbfa9 --- /dev/null +++ b/docs/en/ranch/1.2/guide/parsers.asciidoc @@ -0,0 +1,92 @@ +== Writing parsers + +There are three kinds of protocols: + +* Text protocols +* Schema-less binary protocols +* Schema-based binary protocols + +This chapter introduces the first two kinds. It will not cover +more advanced topics such as continuations or parser generators. + +This chapter isn't specifically about Ranch, we assume here that +you know how to read data from the socket. The data you read and +the data that hasn't been parsed is saved in a buffer. Every +time you read from the socket, the data read is appended to the +buffer. What happens next depends on the kind of protocol. We +will only cover the first two. + +=== Parsing text + +Text protocols are generally line based. This means that we can't +do anything with them until we receive the full line. + +A simple way to get a full line is to use `binary:split/{2,3}`. + +.Using binary:split/2 to get a line of input + +[source,erlang] +case binary:split(Buffer, <<"\n">>) of + [_] -> + get_more_data(Buffer); + [Line, Rest] -> + handle_line(Line, Rest) +end. + +In the above example, we can have two results. Either there was +a line break in the buffer and we get it split into two parts, +the line and the rest of the buffer; or there was no line break +in the buffer and we need to get more data from the socket. + +Next, we need to parse the line. The simplest way is to again +split, here on space. The difference is that we want to split +on all spaces character, as we want to tokenize the whole string. + +.Using binary:split/3 to split text + +[source,erlang] +case binary:split(Line, <<" ">>, [global]) of + [<<"HELLO">>] -> + be_polite(); + [<<"AUTH">>, User, Password] -> + authenticate_user(User, Password); + [<<"QUIT">>, Reason] -> + quit(Reason) + %% ... +end. + +Pretty simple, right? Match on the command name, get the rest +of the tokens in variables and call the respective functions. + +After doing this, you will want to check if there is another +line in the buffer, and handle it immediately if any. +Otherwise wait for more data. + +=== Parsing binary + +Binary protocols can be more varied, although most of them are +pretty similar. The first four bytes of a frame tend to be +the size of the frame, which is followed by a certain number +of bytes for the type of frame and then various parameters. + +Sometimes the size of the frame includes the first four bytes, +sometimes not. Other times this size is encoded over two bytes. +And even other times little-endian is used instead of big-endian. + +The general idea stays the same though. + +.Using binary pattern matching to split frames + +[source,erlang] +<< Size:32, _/bits >> = Buffer, +case Buffer of + << Frame:Size/binary, Rest/bits >> -> + handle_frame(Frame, Rest); + _ -> + get_more_data(Buffer) +end. + +You will then need to parse this frame using binary pattern +matching, and handle it. Then you will want to check if there +is another frame fully received in the buffer, and handle it +immediately if any. Otherwise wait for more data. diff --git a/docs/en/ranch/1.2/guide/parsers/index.html b/docs/en/ranch/1.2/guide/parsers/index.html new file mode 100644 index 00000000..364cd757 --- /dev/null +++ b/docs/en/ranch/1.2/guide/parsers/index.html @@ -0,0 +1,243 @@ + + + + + + + + + + + + Nine Nines: Writing parsers + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Writing parsers

+ +

There are three kinds of protocols:

+
    +
  • +

    +Text protocols +

    +
    • +
  • +

    +Schema-less binary protocols +

    +
    • +
  • +

    +Schema-based binary protocols +

    +
    • +
+

This chapter introduces the first two kinds. It will not cover +more advanced topics such as continuations or parser generators.

+

This chapter isn’t specifically about Ranch, we assume here that +you know how to read data from the socket. The data you read and +the data that hasn’t been parsed is saved in a buffer. Every +time you read from the socket, the data read is appended to the +buffer. What happens next depends on the kind of protocol. We +will only cover the first two.

+
+

Parsing text

+
+

Text protocols are generally line based. This means that we can’t +do anything with them until we receive the full line.

+

A simple way to get a full line is to use binary:split/{2,3}.

+
+
Using binary:split/2 to get a line of input
+
+
case binary:split(Buffer, <<"\n">>) of
+        [_] ->
+                get_more_data(Buffer);
+        [Line, Rest] ->
+                handle_line(Line, Rest)
+end.
+

In the above example, we can have two results. Either there was +a line break in the buffer and we get it split into two parts, +the line and the rest of the buffer; or there was no line break +in the buffer and we need to get more data from the socket.

+

Next, we need to parse the line. The simplest way is to again +split, here on space. The difference is that we want to split +on all spaces character, as we want to tokenize the whole string.

+
+
Using binary:split/3 to split text
+
+
case binary:split(Line, <<" ">>, [global]) of
+        [<<"HELLO">>] ->
+                be_polite();
+        [<<"AUTH">>, User, Password] ->
+                authenticate_user(User, Password);
+        [<<"QUIT">>, Reason] ->
+                quit(Reason)
+        %% ...
+end.
+

Pretty simple, right? Match on the command name, get the rest +of the tokens in variables and call the respective functions.

+

After doing this, you will want to check if there is another +line in the buffer, and handle it immediately if any. +Otherwise wait for more data.

+
+
+
+

Parsing binary

+
+

Binary protocols can be more varied, although most of them are +pretty similar. The first four bytes of a frame tend to be +the size of the frame, which is followed by a certain number +of bytes for the type of frame and then various parameters.

+

Sometimes the size of the frame includes the first four bytes, +sometimes not. Other times this size is encoded over two bytes. +And even other times little-endian is used instead of big-endian.

+

The general idea stays the same though.

+
+
Using binary pattern matching to split frames
+
+
<< Size:32, _/bits >> = Buffer,
+case Buffer of
+        << Frame:Size/binary, Rest/bits >> ->
+                handle_frame(Frame, Rest);
+        _ ->
+                get_more_data(Buffer)
+end.
+

You will then need to parse this frame using binary pattern +matching, and handle it. Then you will want to check if there +is another frame fully received in the buffer, and handle it +immediately if any. Otherwise wait for more data.

+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/guide/protocols.asciidoc b/docs/en/ranch/1.2/guide/protocols.asciidoc new file mode 100644 index 00000000..80603432 --- /dev/null +++ b/docs/en/ranch/1.2/guide/protocols.asciidoc @@ -0,0 +1,125 @@ +== Protocols + +A protocol handler starts a connection process and defines the +protocol logic executed in this process. + +=== Writing a protocol handler + +All protocol handlers must implement the `ranch_protocol` behavior +which defines a single callback, `start_link/4`. This callback is +responsible for spawning a new process for handling the connection. +It receives four arguments: the name of the listener, the socket, the +transport handler being used and the protocol options defined in +the call to `ranch:start_listener/6`. This callback must +return `{ok, Pid}`, with `Pid` the pid of the new process. + +The newly started process can then freely initialize itself. However, +it must call `ranch:accept_ack/1` before doing any socket operation. +This will ensure the connection process is the owner of the socket. +It expects the listener's name as argument. + +.Acknowledge accepting the socket + +[source,erlang] +ok = ranch:accept_ack(Ref). + +If your protocol code requires specific socket options, you should +set them while initializing your connection process, after +calling `ranch:accept_ack/1`. You can use `Transport:setopts/2` +for that purpose. + +Following is the complete protocol code for the example found +in `examples/tcp_echo/`. + +.Protocol module that echoes everything it receives + +[source,erlang] +---- +-module(echo_protocol). +-behaviour(ranch_protocol). + +-export([start_link/4]). +-export([init/4]). + +start_link(Ref, Socket, Transport, Opts) -> + Pid = spawn_link(?MODULE, init, [Ref, Socket, Transport, Opts]), + {ok, Pid}. + +init(Ref, Socket, Transport, _Opts = []) -> + ok = ranch:accept_ack(Ref), + loop(Socket, Transport). + +loop(Socket, Transport) -> + case Transport:recv(Socket, 0, 5000) of + {ok, Data} -> + Transport:send(Socket, Data), + loop(Socket, Transport); + _ -> + ok = Transport:close(Socket) + end. +---- + +=== Using gen_server + +Special processes like the ones that use the `gen_server` or `gen_fsm` +behaviours have the particularity of having their `start_link` call not +return until the `init` function returns. This is problematic, because +you won't be able to call `ranch:accept_ack/1` from the `init` callback +as this would cause a deadlock to happen. + +There are two ways of solving this problem. + +The first, and probably the most elegant one, is to make use of the +`gen_server:enter_loop/3` function. It allows you to start your process +normally (although it must be started with `proc_lib` like all special +processes), then perform any needed operations before falling back into +the normal `gen_server` execution loop. + +.Use a gen_server for protocol handling + +[source,erlang] +---- +-module(my_protocol). +-behaviour(gen_server). +-behaviour(ranch_protocol). + +-export([start_link/4]). +-export([init/4]). +%% Exports of other gen_server callbacks here. + +start_link(Ref, Socket, Transport, Opts) -> + proc_lib:start_link(?MODULE, init, [Ref, Socket, Transport, Opts]). + +init(Ref, Socket, Transport, _Opts = []) -> + ok = proc_lib:init_ack({ok, self()}), + %% Perform any required state initialization here. + ok = ranch:accept_ack(Ref), + ok = Transport:setopts(Socket, [{active, once}]), + gen_server:enter_loop(?MODULE, [], {state, Socket, Transport}). + +%% Other gen_server callbacks here. +---- + +The second method involves triggering a timeout just after `gen_server:init` +ends. If you return a timeout value of `0` then the `gen_server` will call +`handle_info(timeout, _, _)` right away. + +.Use a gen_server for protocol handling, method 2 + +[source,erlang] +---- +-module(my_protocol). +-behaviour(gen_server). +-behaviour(ranch_protocol). + +%% Exports go here. + +init([Ref, Socket, Transport]) -> + {ok, {state, Ref, Socket, Transport}, 0}. + +handle_info(timeout, State={state, Ref, Socket, Transport}) -> + ok = ranch:accept_ack(Ref), + ok = Transport:setopts(Socket, [{active, once}]), + {noreply, State}; +%% ... +---- diff --git a/docs/en/ranch/1.2/guide/protocols/index.html b/docs/en/ranch/1.2/guide/protocols/index.html new file mode 100644 index 00000000..cd44a06b --- /dev/null +++ b/docs/en/ranch/1.2/guide/protocols/index.html @@ -0,0 +1,263 @@ + + + + + + + + + + + + Nine Nines: Protocols + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Protocols

+ +

A protocol handler starts a connection process and defines the +protocol logic executed in this process.

+
+

Writing a protocol handler

+
+

All protocol handlers must implement the ranch_protocol behavior +which defines a single callback, start_link/4. This callback is +responsible for spawning a new process for handling the connection. +It receives four arguments: the name of the listener, the socket, the +transport handler being used and the protocol options defined in +the call to ranch:start_listener/6. This callback must +return {ok, Pid}, with Pid the pid of the new process.

+

The newly started process can then freely initialize itself. However, +it must call ranch:accept_ack/1 before doing any socket operation. +This will ensure the connection process is the owner of the socket. +It expects the listener’s name as argument.

+
+
Acknowledge accepting the socket
+
+
ok = ranch:accept_ack(Ref).
+

If your protocol code requires specific socket options, you should +set them while initializing your connection process, after +calling ranch:accept_ack/1. You can use Transport:setopts/2 +for that purpose.

+

Following is the complete protocol code for the example found +in examples/tcp_echo/.

+
+
Protocol module that echoes everything it receives
+
+
-module(echo_protocol).
+-behaviour(ranch_protocol).
+
+-export([start_link/4]).
+-export([init/4]).
+
+start_link(Ref, Socket, Transport, Opts) ->
+        Pid = spawn_link(?MODULE, init, [Ref, Socket, Transport, Opts]),
+        {ok, Pid}.
+
+init(Ref, Socket, Transport, _Opts = []) ->
+        ok = ranch:accept_ack(Ref),
+        loop(Socket, Transport).
+
+loop(Socket, Transport) ->
+        case Transport:recv(Socket, 0, 5000) of
+                {ok, Data} ->
+                        Transport:send(Socket, Data),
+                        loop(Socket, Transport);
+                _ ->
+                        ok = Transport:close(Socket)
+        end.
+
+
+
+

Using gen_server

+
+

Special processes like the ones that use the gen_server or gen_fsm +behaviours have the particularity of having their start_link call not +return until the init function returns. This is problematic, because +you won’t be able to call ranch:accept_ack/1 from the init callback +as this would cause a deadlock to happen.

+

There are two ways of solving this problem.

+

The first, and probably the most elegant one, is to make use of the +gen_server:enter_loop/3 function. It allows you to start your process +normally (although it must be started with proc_lib like all special +processes), then perform any needed operations before falling back into +the normal gen_server execution loop.

+
+
Use a gen_server for protocol handling
+
+
-module(my_protocol).
+-behaviour(gen_server).
+-behaviour(ranch_protocol).
+
+-export([start_link/4]).
+-export([init/4]).
+%% Exports of other gen_server callbacks here.
+
+start_link(Ref, Socket, Transport, Opts) ->
+        proc_lib:start_link(?MODULE, init, [Ref, Socket, Transport, Opts]).
+
+init(Ref, Socket, Transport, _Opts = []) ->
+        ok = proc_lib:init_ack({ok, self()}),
+        %% Perform any required state initialization here.
+        ok = ranch:accept_ack(Ref),
+        ok = Transport:setopts(Socket, [{active, once}]),
+        gen_server:enter_loop(?MODULE, [], {state, Socket, Transport}).
+
+%% Other gen_server callbacks here.
+

The second method involves triggering a timeout just after gen_server:init +ends. If you return a timeout value of 0 then the gen_server will call +handle_info(timeout, _, _) right away.

+
+
Use a gen_server for protocol handling, method 2
+
+
-module(my_protocol).
+-behaviour(gen_server).
+-behaviour(ranch_protocol).
+
+%% Exports go here.
+
+init([Ref, Socket, Transport]) ->
+        {ok, {state, Ref, Socket, Transport}, 0}.
+
+handle_info(timeout, State={state, Ref, Socket, Transport}) ->
+        ok = ranch:accept_ack(Ref),
+        ok = Transport:setopts(Socket, [{active, once}]),
+        {noreply, State};
+%% ...
+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/guide/ssl_auth.asciidoc b/docs/en/ranch/1.2/guide/ssl_auth.asciidoc new file mode 100644 index 00000000..de0bbaf0 --- /dev/null +++ b/docs/en/ranch/1.2/guide/ssl_auth.asciidoc @@ -0,0 +1,120 @@ +== SSL client authentication + +=== Purpose + +SSL client authentication is a mechanism allowing applications to +identify certificates. This allows your application to make sure that +the client is an authorized certificate, but makes no claim about +whether the user can be trusted. This can be combined with a password +based authentication to attain greater security. + +The server only needs to retain the certificate serial number and +the certificate issuer to authenticate the certificate. Together, +they can be used to uniquely identify a certicate. + +As Ranch allows the same protocol code to be used for both SSL and +non-SSL transports, you need to make sure you are in an SSL context +before attempting to perform an SSL client authentication. This +can be done by checking the return value of `Transport:name/0`. + +=== Obtaining client certificates + +You can obtain client certificates from various sources. You can +generate them yourself, or you can use a service like CAcert.org +which allows you to generate client and server certificates for +free. + +Following are the steps you need to take to create a CAcert.org +account, generate a certificate and install it in your favorite +browser. + +* Open http://cacert.org in your favorite browser +* Root Certificate link: install both certificates +* Join (Register an account) +* Verify your account (check your email inbox!) +* Log in +* Client Certificates: New +* Follow instructions to create the certificate +* Install the certificate in your browser + +You can optionally save the certificate for later use, for example +to extract the `IssuerID` information as will be detailed later on. + +=== Transport configuration + +The SSL transport does not request a client certificate by default. +You need to specify the `{verify, verify_peer}` option when starting +the listener to enable this behavior. + +.Configure a listener for SSL authentication + +[source,erlang] +{ok, _} = ranch:start_listener(my_ssl, 100, + ranch_ssl, [ + {port, SSLPort}, + {certfile, PathToCertfile}, + {cacertfile, PathToCACertfile}, + {verify, verify_peer} + ], + my_protocol, [] +). + +In this example we set the required `port` and `certfile`, but also +the `cacertfile` containing the CACert.org root certificate, and +the option to request the client certificate. + +If you enable the `{verify, verify_peer}` option and the client does +not have a client certificate configured for your domain, then no +certificate will be sent. This allows you to use SSL for more than +just authenticated clients. + +=== Authentication + +To authenticate users, you must first save the certificate information +required. If you have your users' certificate files, you can simply +load the certificate and retrieve the information directly. + +.Retrieve the issuer ID from a certificate + +[source,erlang] +---- +certfile_to_issuer_id(Filename) -> + {ok, Data} = file:read_file(Filename), + [{'Certificate', Cert, not_encrypted}] = public_key:pem_decode(Data), + {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self), + IssuerID. +---- + +The `IssuerID` variable contains both the certificate serial number +and the certificate issuer stored in a tuple, so this value alone can +be used to uniquely identify the user certificate. You can save this +value in a database, a configuration file or any other place where an +Erlang term can be stored and retrieved. + +To retrieve the `IssuerID` from a running connection, you need to first +retrieve the client certificate and then extract this information from +it. Ranch does not provide a function to retrieve the client certificate. +Instead you can use the `ssl:peercert/1` function. Once you have the +certificate, you can again use the `public_key:pkix_issuer_id/2` to +extract the `IssuerID` value. + +The following function returns the `IssuerID` or `false` if no client +certificate was found. This snippet is intended to be used from your +protocol code. + +.Retrieve the issuer ID from the certificate for the current connection + +[source,erlang] +---- +socket_to_issuer_id(Socket) -> + case ssl:peercert(Socket) of + {error, no_peercert} -> + false; + {ok, Cert} -> + {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self), + IssuerID + end. +---- + +You then only need to match the `IssuerID` value to authenticate the +user. diff --git a/docs/en/ranch/1.2/guide/ssl_auth/index.html b/docs/en/ranch/1.2/guide/ssl_auth/index.html new file mode 100644 index 00000000..a1018d85 --- /dev/null +++ b/docs/en/ranch/1.2/guide/ssl_auth/index.html @@ -0,0 +1,292 @@ + + + + + + + + + + + + Nine Nines: SSL client authentication + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

SSL client authentication

+ +
+

Purpose

+
+

SSL client authentication is a mechanism allowing applications to +identify certificates. This allows your application to make sure that +the client is an authorized certificate, but makes no claim about +whether the user can be trusted. This can be combined with a password +based authentication to attain greater security.

+

The server only needs to retain the certificate serial number and +the certificate issuer to authenticate the certificate. Together, +they can be used to uniquely identify a certicate.

+

As Ranch allows the same protocol code to be used for both SSL and +non-SSL transports, you need to make sure you are in an SSL context +before attempting to perform an SSL client authentication. This +can be done by checking the return value of Transport:name/0.

+
+
+
+

Obtaining client certificates

+
+

You can obtain client certificates from various sources. You can +generate them yourself, or you can use a service like CAcert.org +which allows you to generate client and server certificates for +free.

+

Following are the steps you need to take to create a CAcert.org +account, generate a certificate and install it in your favorite +browser.

+
    +
  • +

    +Open http://cacert.org in your favorite browser +

    +
    • +
  • +

    +Root Certificate link: install both certificates +

    +
    • +
  • +

    +Join (Register an account) +

    +
    • +
  • +

    +Verify your account (check your email inbox!) +

    +
    • +
  • +

    +Log in +

    +
    • +
  • +

    +Client Certificates: New +

    +
    • +
  • +

    +Follow instructions to create the certificate +

    +
    • +
  • +

    +Install the certificate in your browser +

    +
    • +
+

You can optionally save the certificate for later use, for example +to extract the IssuerID information as will be detailed later on.

+
+
+
+

Transport configuration

+
+

The SSL transport does not request a client certificate by default. +You need to specify the {verify, verify_peer} option when starting +the listener to enable this behavior.

+
+
Configure a listener for SSL authentication
+
+
{ok, _} = ranch:start_listener(my_ssl, 100,
+        ranch_ssl, [
+                {port, SSLPort},
+                {certfile, PathToCertfile},
+                {cacertfile, PathToCACertfile},
+                {verify, verify_peer}
+        ],
+        my_protocol, []
+).
+

In this example we set the required port and certfile, but also +the cacertfile containing the CACert.org root certificate, and +the option to request the client certificate.

+

If you enable the {verify, verify_peer} option and the client does +not have a client certificate configured for your domain, then no +certificate will be sent. This allows you to use SSL for more than +just authenticated clients.

+
+
+
+

Authentication

+
+

To authenticate users, you must first save the certificate information +required. If you have your users' certificate files, you can simply +load the certificate and retrieve the information directly.

+
+
Retrieve the issuer ID from a certificate
+
+
certfile_to_issuer_id(Filename) ->
+        {ok, Data} = file:read_file(Filename),
+        [{'Certificate', Cert, not_encrypted}] = public_key:pem_decode(Data),
+        {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self),
+        IssuerID.
+

The IssuerID variable contains both the certificate serial number +and the certificate issuer stored in a tuple, so this value alone can +be used to uniquely identify the user certificate. You can save this +value in a database, a configuration file or any other place where an +Erlang term can be stored and retrieved.

+

To retrieve the IssuerID from a running connection, you need to first +retrieve the client certificate and then extract this information from +it. Ranch does not provide a function to retrieve the client certificate. +Instead you can use the ssl:peercert/1 function. Once you have the +certificate, you can again use the public_key:pkix_issuer_id/2 to +extract the IssuerID value.

+

The following function returns the IssuerID or false if no client +certificate was found. This snippet is intended to be used from your +protocol code.

+
+
Retrieve the issuer ID from the certificate for the current connection
+
+
socket_to_issuer_id(Socket) ->
+        case ssl:peercert(Socket) of
+                {error, no_peercert} ->
+                        false;
+                {ok, Cert} ->
+                        {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self),
+                        IssuerID
+        end.
+

You then only need to match the IssuerID value to authenticate the +user.

+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/guide/transports.asciidoc b/docs/en/ranch/1.2/guide/transports.asciidoc new file mode 100644 index 00000000..91953762 --- /dev/null +++ b/docs/en/ranch/1.2/guide/transports.asciidoc @@ -0,0 +1,169 @@ +== Transports + +A transport defines the interface to interact with a socket. + +Transports can be used for connecting, listening and accepting +connections, but also for receiving and sending data. Both +passive and active mode are supported, although all sockets +are initialized as passive. + +=== TCP transport + +The TCP transport is a thin wrapper around `gen_tcp`. + +=== SSL transport + +The SSL transport is a thin wrapper around `ssl`. It requires +the `crypto`, `asn1`, `public_key` and `ssl` applications +to be started. When starting an SSL listener, Ranch will attempt +to automatically start them. It will not try to stop them when +the listener is removed, however. + +.Starting the SSL application + +[source,erlang] +ssl:start(). + +In a proper OTP setting, you will need to make your application +depend on the `crypto`, `public_key` and `ssl` applications. +They will be started automatically when starting your release. + +The SSL transport `accept/2` function performs both transport +and SSL accepts. Errors occurring during the SSL accept phase +are returned as `{error, {ssl_accept, atom()}}` to differentiate +on which socket the problem occurred. + +=== Sending and receiving data + +This section assumes that `Transport` is a valid transport handler +(like `ranch_tcp` or `ranch_ssl`) and `Socket` is a connected +socket obtained through the listener. + +You can send data to a socket by calling the `Transport:send/2` +function. The data can be given as `iodata()`, which is defined as +`binary() | iolist()`. All the following calls will work: + +.Sending data to the socket + +[source,erlang] +---- +Transport:send(Socket, <<"Ranch is cool!">>). +Transport:send(Socket, "Ranch is cool!"). +Transport:send(Socket, ["Ranch", ["is", "cool!"]]). +Transport:send(Socket, ["Ranch", [<<"is">>, "cool!"]]). +---- + +You can receive data either in passive or in active mode. Passive mode +means that you will perform a blocking `Transport:recv/3` call, while +active mode means that you will receive the data as a message. + +By default, all data will be received as binary. It is possible to +receive data as strings, although this is not recommended as binaries +are a more efficient construct, especially for binary protocols. + +Receiving data using passive mode requires a single function call. The +first argument is the socket, and the third argument is a timeout duration +before the call returns with `{error, timeout}`. + +The second argument is the amount of data in bytes that we want to receive. +The function will wait for data until it has received exactly this amount. +If you are not expecting a precise size, you can specify 0 which will make +this call return as soon as data was read, regardless of its size. + +.Receiving data from the socket in passive mode + +[source,erlang] +{ok, Data} = Transport:recv(Socket, 0, 5000). + +Active mode requires you to inform the socket that you want to receive +data as a message and to write the code to actually receive it. + +There are two kinds of active modes: `{active, once}` and +`{active, true}`. The first will send a single message before going +back to passive mode; the second will send messages indefinitely. +We recommend not using the `{active, true}` mode as it could quickly +flood your process mailbox. It's better to keep the data in the socket +and read it only when required. + +Three different messages can be received: + +* `{OK, Socket, Data}` +* `{Closed, Socket}` +* `{Error, Socket, Reason}` + +The value of `OK`, `Closed` and `Error` can be different +depending on the transport being used. To be able to properly match +on them you must first call the `Transport:messages/0` function. + +.Retrieving the transport's active message identifiers + +[source,erlang] +{OK, Closed, Error} = Transport:messages(). + +To start receiving messages you will need to call the `Transport:setopts/2` +function, and do so every time you want to receive data. + +.Receiving messages from the socket in active mode + +[source,erlang] +---- +{OK, Closed, Error} = Transport:messages(), +Transport:setopts(Socket, [{active, once}]), +receive + {OK, Socket, Data} -> + io:format("data received: ~p~n", [Data]); + {Closed, Socket} -> + io:format("socket got closed!~n"); + {Error, Socket, Reason} -> + io:format("error happened: ~p~n", [Reason]) +end. +---- + +You can easily integrate active sockets with existing Erlang code as all +you really need is just a few more clauses when receiving messages. + +=== Sending files + +As in the previous section it is assumed `Transport` is a valid transport +handler and `Socket` is a connected socket obtained through the listener. + +To send a whole file, with name `Filename`, over a socket: + +.Sending a file by filename + +[source,erlang] +{ok, SentBytes} = Transport:sendfile(Socket, Filename). + +Or part of a file, with `Offset` greater than or equal to 0, `Bytes` number of +bytes and chunks of size `ChunkSize`: + +.Sending part of a file by filename in chunks + +[source,erlang] +Opts = [{chunk_size, ChunkSize}], +{ok, SentBytes} = Transport:sendfile(Socket, Filename, Offset, Bytes, Opts). + +To improve efficiency when sending multiple parts of the same file it is also +possible to use a file descriptor opened in raw mode: + +.Sending a file opened in raw mode + +[source,erlang] +{ok, RawFile} = file:open(Filename, [raw, read, binary]), +{ok, SentBytes} = Transport:sendfile(Socket, RawFile, Offset, Bytes, Opts). + +=== Writing a transport handler + +A transport handler is a module implementing the `ranch_transport` behavior. +It defines a certain number of callbacks that must be written in order to +allow transparent usage of the transport handler. + +The behavior doesn't define the socket options available when opening a +socket. These do not need to be common to all transports as it's easy enough +to write different initialization functions for the different transports that +will be used. With one exception though. The `setopts/2` function *must* +implement the `{active, once}` and the `{active, true}` options. + +If the transport handler doesn't have a native implementation of `sendfile/5` a +fallback is available, `ranch_transport:sendfile/6`. The extra first argument +is the transport's module. See `ranch_ssl` for an example. diff --git a/docs/en/ranch/1.2/guide/transports/index.html b/docs/en/ranch/1.2/guide/transports/index.html new file mode 100644 index 00000000..a3ce9983 --- /dev/null +++ b/docs/en/ranch/1.2/guide/transports/index.html @@ -0,0 +1,323 @@ + + + + + + + + + + + + Nine Nines: Transports + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Transports

+ +

A transport defines the interface to interact with a socket.

+

Transports can be used for connecting, listening and accepting +connections, but also for receiving and sending data. Both +passive and active mode are supported, although all sockets +are initialized as passive.

+
+

TCP transport

+
+

The TCP transport is a thin wrapper around gen_tcp.

+
+
+
+

SSL transport

+
+

The SSL transport is a thin wrapper around ssl. It requires +the crypto, asn1, public_key and ssl applications +to be started. When starting an SSL listener, Ranch will attempt +to automatically start them. It will not try to stop them when +the listener is removed, however.

+
+
Starting the SSL application
+
+
ssl:start().
+

In a proper OTP setting, you will need to make your application +depend on the crypto, public_key and ssl applications. +They will be started automatically when starting your release.

+

The SSL transport accept/2 function performs both transport +and SSL accepts. Errors occurring during the SSL accept phase +are returned as {error, {ssl_accept, atom()}} to differentiate +on which socket the problem occurred.

+
+
+
+

Sending and receiving data

+
+

This section assumes that Transport is a valid transport handler +(like ranch_tcp or ranch_ssl) and Socket is a connected +socket obtained through the listener.

+

You can send data to a socket by calling the Transport:send/2 +function. The data can be given as iodata(), which is defined as +binary() | iolist(). All the following calls will work:

+
+
Sending data to the socket
+
+
Transport:send(Socket, <<"Ranch is cool!">>).
+Transport:send(Socket, "Ranch is cool!").
+Transport:send(Socket, ["Ranch", ["is", "cool!"]]).
+Transport:send(Socket, ["Ranch", [<<"is">>, "cool!"]]).
+

You can receive data either in passive or in active mode. Passive mode +means that you will perform a blocking Transport:recv/3 call, while +active mode means that you will receive the data as a message.

+

By default, all data will be received as binary. It is possible to +receive data as strings, although this is not recommended as binaries +are a more efficient construct, especially for binary protocols.

+

Receiving data using passive mode requires a single function call. The +first argument is the socket, and the third argument is a timeout duration +before the call returns with {error, timeout}.

+

The second argument is the amount of data in bytes that we want to receive. +The function will wait for data until it has received exactly this amount. +If you are not expecting a precise size, you can specify 0 which will make +this call return as soon as data was read, regardless of its size.

+
+
Receiving data from the socket in passive mode
+
+
{ok, Data} = Transport:recv(Socket, 0, 5000).
+

Active mode requires you to inform the socket that you want to receive +data as a message and to write the code to actually receive it.

+

There are two kinds of active modes: {active, once} and +{active, true}. The first will send a single message before going +back to passive mode; the second will send messages indefinitely. +We recommend not using the {active, true} mode as it could quickly +flood your process mailbox. It’s better to keep the data in the socket +and read it only when required.

+

Three different messages can be received:

+
    +
  • +

    +{OK, Socket, Data} +

    +
    • +
  • +

    +{Closed, Socket} +

    +
    • +
  • +

    +{Error, Socket, Reason} +

    +
    • +
+

The value of OK, Closed and Error can be different +depending on the transport being used. To be able to properly match +on them you must first call the Transport:messages/0 function.

+
+
Retrieving the transport’s active message identifiers
+
+
{OK, Closed, Error} = Transport:messages().
+

To start receiving messages you will need to call the Transport:setopts/2 +function, and do so every time you want to receive data.

+
+
Receiving messages from the socket in active mode
+
+
{OK, Closed, Error} = Transport:messages(),
+Transport:setopts(Socket, [{active, once}]),
+receive
+        {OK, Socket, Data} ->
+                io:format("data received: ~p~n", [Data]);
+        {Closed, Socket} ->
+                io:format("socket got closed!~n");
+        {Error, Socket, Reason} ->
+                io:format("error happened: ~p~n", [Reason])
+end.
+

You can easily integrate active sockets with existing Erlang code as all +you really need is just a few more clauses when receiving messages.

+
+
+
+

Sending files

+
+

As in the previous section it is assumed Transport is a valid transport +handler and Socket is a connected socket obtained through the listener.

+

To send a whole file, with name Filename, over a socket:

+
+
Sending a file by filename
+
+
{ok, SentBytes} = Transport:sendfile(Socket, Filename).
+

Or part of a file, with Offset greater than or equal to 0, Bytes number of +bytes and chunks of size ChunkSize:

+
+
Sending part of a file by filename in chunks
+
+
Opts = [{chunk_size, ChunkSize}],
+{ok, SentBytes} = Transport:sendfile(Socket, Filename, Offset, Bytes, Opts).
+

To improve efficiency when sending multiple parts of the same file it is also +possible to use a file descriptor opened in raw mode:

+
+
Sending a file opened in raw mode
+
+
{ok, RawFile} = file:open(Filename, [raw, read, binary]),
+{ok, SentBytes} = Transport:sendfile(Socket, RawFile, Offset, Bytes, Opts).
+
+
+
+

Writing a transport handler

+
+

A transport handler is a module implementing the ranch_transport behavior. +It defines a certain number of callbacks that must be written in order to +allow transparent usage of the transport handler.

+

The behavior doesn’t define the socket options available when opening a +socket. These do not need to be common to all transports as it’s easy enough +to write different initialization functions for the different transports that +will be used. With one exception though. The setopts/2 function must +implement the {active, once} and the {active, true} options.

+

If the transport handler doesn’t have a native implementation of sendfile/5 a +fallback is available, ranch_transport:sendfile/6. The extra first argument +is the transport’s module. See ranch_ssl for an example.

+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + + User Guide +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/index.html b/docs/en/ranch/1.2/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/ranch/1.2/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/ranch/1.2/manual/index.html b/docs/en/ranch/1.2/manual/index.html new file mode 100644 index 00000000..339f6643 --- /dev/null +++ b/docs/en/ranch/1.2/manual/index.html @@ -0,0 +1,172 @@ + + + + + + + + + + + + Nine Nines: Ranch Function Reference + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Ranch Function Reference

+ +
+ + + +
+ +
+ + +

+ Ranch + 1.2 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/manual/ranch/index.html b/docs/en/ranch/1.2/manual/ranch/index.html new file mode 100644 index 00000000..bdec4cca --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch/index.html @@ -0,0 +1,557 @@ + + + + + + + + + + + + Nine Nines: ranch(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

ranch(3)

+ +
+

Name

+
+

ranch - socket acceptor pool

+
+
+
+

Description

+
+

The ranch module provides functions for starting and +manipulating Ranch listeners.

+
+
+
+

Types

+
+
+

max_conns() = non_neg_integer() | infinity

+

Maximum number of connections allowed on this listener.

+

This is a soft limit. The actual number of connections +might be slightly above the limit due to concurrency +when accepting new connections. Some connections may +also be removed from this count explicitly by the user +code.

+
+
+

opt()

+
+
+
opt() = {ack_timeout, timeout()}
+        | {connection_type, worker | supervisor}
+        | {max_connections, max_conns()}
+        | {shutdown, timeout() | brutal_kill}
+        | {socket, any()}
+

Ranch-specific transport options.

+

These options are not passed on to the transports. +They are used by Ranch while setting up the listeners.

+
+
+

ref() = any()

+

Unique name used to refer to a listener.

+
+
+
+
+

Option descriptions

+
+

None of the options are required.

+
+
+ack_timeout (5000) +
+
+

+ Maximum allowed time for the ranch:accept_ack/1 call to finish. +

+
+
+connection_type (worker) +
+
+

+ Type of process that will handle the connection. +

+
+
+max_connections (1024) +
+
+

+ Maximum number of active connections. Soft limit. Using infinity will disable the limit entirely. +

+
+
+shutdown (5000) +
+
+

+ Maximum allowed time for children to stop on listener shutdown. +

+
+
+socket +
+
+

+ Listening socket opened externally to be used instead of calling Transport:listen/1. +

+
+
+
+
+
+

Exports

+
+
+

accept_ack(Ref) → ok

+
+
+Ref = ref() +
+
+

+Listener name. +

+
+
+

Acknowledge that the connection is accepted.

+

This function MUST be used by a connection process to inform +Ranch that it initialized properly and let it perform any +additional operations before the socket can be safely used.

+
+
+

child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()

+
+
+Ref = ref() +
+
+

+Listener name. +

+
+
+NbAcceptors = non_neg_integer() +
+
+

+Number of acceptor processes. +

+
+
+Transport = module() +
+
+

+Transport module. +

+
+
+TransOpts = any() +
+
+

+Transport options. +

+
+
+Protocol = module() +
+
+

+Protocol module. +

+
+
+ProtoOpts = any() +
+
+

+Protocol options. +

+
+
+

Return child specifications for a new listener.

+

This function can be used to embed a listener directly +in an application instead of letting Ranch handle it.

+
+
+

get_addr(Ref) → {IP, Port}

+
+
+Ref = ref() +
+
+

+Listener name. +

+
+
+IP = inet:ip_address() +
+
+

+IP of the interface used by this listener. +

+
+
+Port = inet:port_number() +
+
+

+Port number used by this listener. +

+
+
+

Return the IP address and port for the given listener.

+
+
+

get_max_connections(Ref) → MaxConns

+
+
+Ref = ref() +
+
+

+Listener name. +

+
+
+MaxConns = max_conns() +
+
+

+Current maximum number of connections. +

+
+
+

Return the max number of connections allowed for the given listener.

+
+
+

get_port(Ref) → Port

+
+
+Ref = ref() +
+
+

+Listener name. +

+
+
+Port = inet:port_number() +
+
+

+Port number used by this listener. +

+
+
+

Return the port for the given listener.

+
+
+

get_protocol_options(Ref) → ProtoOpts

+
+
+Ref = ref() +
+
+

+Listener name. +

+
+
+ProtoOpts = any() +
+
+

+Current protocol options. +

+
+
+

Return the protocol options set for the given listener.

+
+
+

remove_connection(Ref) → ok

+
+
+Ref = ref() +
+
+

+Listener name. +

+
+
+

Do not count this connection when limiting the number of connections.

+

You can use this function for long-running connection processes +which spend most of their time idling rather than consuming +resources. This allows Ranch to accept a lot more connections +without sacrificing the latency of the system.

+

This function may only be called from a connection process.

+
+
+

set_max_connections(Ref, MaxConns) → ok

+
+
+Ref = ref() +
+
+

+Listener name. +

+
+
+MaxConns = max_conns() +
+
+

+New maximum number of connections. +

+
+
+

Set the max number of connections for the given listener.

+

The change will be applied immediately. If the new value is +smaller than the previous one, Ranch will not kill the extra +connections, but will wait for them to terminate properly.

+
+
+

set_protocol_options(Ref, ProtoOpts) → ok

+
+
+Ref = ref() +
+
+

+Listener name. +

+
+
+ProtoOpts = any() +
+
+

+New protocol options. +

+
+
+

Set the protocol options for the given listener.

+

The change will be applied immediately for all new connections. +Old connections will not receive the new options.

+
+
+

start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}

+
+
+Ref = ref() +
+
+

+Listener name. +

+
+
+NbAcceptors = non_neg_integer() +
+
+

+Number of acceptor processes. +

+
+
+Transport = module() +
+
+

+Transport module. +

+
+
+TransOpts = any() +
+
+

+Transport options. +

+
+
+Protocol = module() +
+
+

+Protocol module. +

+
+
+ProtoOpts = any() +
+
+

+Protocol options. +

+
+
+

Start listening for connections using the given transport +and protocol. Returns the pid for this listener’s supervisor.

+

There are additional transport options that apply +regardless of transport. They allow configuring how the +connections are supervised, rate limited and more. Please +consult the previous section for more details.

+
+
+

stop_listener(Ref) → ok | {error, not_found}

+
+
+Ref = ref() +
+
+

+Listener name. +

+
+
+

Stop the given listener.

+

The listener is stopped gracefully, first by closing the +listening port, then by stopping the connection processes. +These processes are stopped according to the shutdown +transport option, which may be set to brutally kill all +connection processes or give them some time to stop properly.

+

This function does not return until the listener is +completely stopped.

+
+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/manual/ranch_app/index.html b/docs/en/ranch/1.2/manual/ranch_app/index.html new file mode 100644 index 00000000..ac3ffd08 --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch_app/index.html @@ -0,0 +1,177 @@ + + + + + + + + + + + + Nine Nines: ranch(7) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

ranch(7)

+ +
+

Name

+
+

ranch - Socket acceptor pool for TCP protocols.

+
+
+
+

Dependencies

+
+

The ranch application has no particular dependency required +to start.

+

It has optional dependencies that are only required when +listening for SSL connections. The dependencies are crypto, +asn1, public_key and ssl. They are started automatically +if they weren’t before.

+
+
+
+

Environment

+
+

The ranch application defines one application environment +configuration parameter.

+
+
+profile (false) +
+
+

+ When enabled, Ranch will start eprof profiling automatically. +

+
+
+

You can use the ranch_app:profile_output/0 function to stop +profiling and output the results to the files procs.profile +and total.profile. Do not use in production.

+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/manual/ranch_protocol/index.html b/docs/en/ranch/1.2/manual/ranch_protocol/index.html new file mode 100644 index 00000000..aa0001c6 --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch_protocol/index.html @@ -0,0 +1,217 @@ + + + + + + + + + + + + Nine Nines: ranch_protocol(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

ranch_protocol(3)

+ +
+

Name

+
+

ranch_protocol - behaviour for protocol modules

+
+
+
+

Description

+
+

The ranch_protocol behaviour defines the interface used +by Ranch protocols.

+
+
+
+

Types

+
+

None.

+
+
+
+

Callbacks

+
+
+

start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}

+
+
+Ref = ranch:ref() +
+
+

+Listener name. +

+
+
+Socket = any() +
+
+

+Socket for this connection. +

+
+
+Transport = module() +
+
+

+Transport module for this socket. +

+
+
+ProtoOpts = any() +
+
+

+Protocol options. +

+
+
+

Start a new connection process for the given socket.

+

The only purpose of this callback is to start a process that +will handle the socket. It must spawn the process, link and +then return the new pid. This function will always be called +from inside a supervisor.

+

This callback can also return two pids. The first pid is the +pid of the process that will be supervised. The second pid is +the pid of the process that will receive ownership of the +socket. This second process must be a child of the first. This +form is only available when connection_type is set to +supervisor.

+

If any other value is returned, the supervisor will close the +socket and assume no process has been started.

+

Do not perform any operations in this callback, as this would +block the supervisor responsible for starting connection +processes and degrade performance severely.

+
+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/manual/ranch_ssl/index.html b/docs/en/ranch/1.2/manual/ranch_ssl/index.html new file mode 100644 index 00000000..2c0ef14f --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch_ssl/index.html @@ -0,0 +1,483 @@ + + + + + + + + + + + + Nine Nines: ranch_ssl(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

ranch_ssl(3)

+ +
+

Name

+
+

ranch_ssl - SSL transport module

+
+
+
+

Description

+
+

The ranch_ssl module implements an SSL Ranch transport.

+
+
+
+

Types

+
+
+

ssl_opt()

+
+
+
ssl_opt() = {alpn_preferred_protocols, [binary()]}
+        | {cacertfile, string()}
+        | {cacerts, [public_key:der_encoded()]}
+        | {cert, public_key:der_encoded()}
+        | {certfile, string()}
+        | {ciphers, [ssl:erl_cipher_suite()] | string()}
+        | {client_renegotiation, boolean()}
+        | {crl_cache, {module(), {internal | any(), list()}}}
+        | {crl_check, boolean() | peer | best_effort}
+        | {depth, 0..255}
+        | {dh, public_key:der_encoded()}
+        | {dhfile, string()}
+        | {fail_if_no_peer_cert, boolean()}
+        | {hibernate_after, integer() | undefined}
+        | {honor_cipher_order, boolean()}
+        | {key, {'RSAPrivateKey' | 'DSAPrivateKey' | 'PrivateKeyInfo', public_key:der_encoded()}}
+        | {keyfile, string()}
+        | {log_alert, boolean()}
+        | {next_protocols_advertised, [binary()]}
+        | {partial_chain, fun(([public_key:der_encoded()]) -> {trusted_ca, public_key:der_encoded()} | unknown_ca)}
+        | {password, string()}
+        | {psk_identity, string()}
+        | {reuse_session, fun()}
+        | {reuse_sessions, boolean()}
+        | {secure_renegotiate, boolean()}
+        | {sni_fun, fun()}
+        | {sni_hosts, [{string(), ssl_opt()}]}
+        | {user_lookup_fun, {fun(), any()}}
+        | {verify, ssl:verify_type()}
+        | {verify_fun, {fun(), any()}}
+        | {versions, [atom()]}.
+

SSL-specific listen options.

+
+
+

opt() = ranch_tcp:opt() | ssl_opt()

+

Listen options.

+
+
+

opts() = [opt()]

+

List of listen options.

+
+
+
+
+

Option descriptions

+
+

Specifying a certificate is mandatory, either through the cert +or the certfile option. None of the other options are required.

+

The default value is given next to the option name.

+
+
+alpn_preferred_protocols +
+
+

+ Perform Application-Layer Protocol Negotiation with the given list of preferred protocols. +

+
+
+cacertfile +
+
+

+ Path to PEM encoded trusted certificates file used to verify peer certificates. +

+
+
+cacerts +
+
+

+ List of DER encoded trusted certificates. +

+
+
+cert +
+
+

+ DER encoded user certificate. +

+
+
+certfile +
+
+

+ Path to the PEM encoded user certificate file. May also contain the private key. +

+
+
+ciphers +
+
+

+ List of ciphers that clients are allowed to use. +

+
+
+client_renegotiation (true) +
+
+

+ Whether to allow client-initiated renegotiation. +

+
+
+crl_cache ({ssl_crl_cache, {internal, []}}) +
+
+

+ Customize the module used to cache Certificate Revocation Lists. +

+
+
+crl_check (false) +
+
+

+ Whether to perform CRL check on all certificates in the chain during validation. +

+
+
+depth (1) +
+
+

+ Maximum of intermediate certificates allowed in the certification path. +

+
+
+dh +
+
+

+ DER encoded Diffie-Hellman parameters. +

+
+
+dhfile +
+
+

+ Path to the PEM encoded Diffie-Hellman parameters file. +

+
+
+fail_if_no_peer_cert (false) +
+
+

+ Whether to refuse the connection if the client sends an empty certificate. +

+
+
+hibernate_after (undefined) +
+
+

+ Time in ms after which SSL socket processes go into hibernation to reduce memory usage. +

+
+
+honor_cipher_order (false) +
+
+

+ If true, use the server’s preference for cipher selection. If false, use the client’s preference. +

+
+
+key +
+
+

+ DER encoded user private key. +

+
+
+keyfile +
+
+

+ Path to the PEM encoded private key file, if different than the certfile. +

+
+
+log_alert (true) +
+
+

+ If false, error reports will not be displayed. +

+
+
+next_protocols_advertised +
+
+

+ List of protocols to send to the client if it supports the Next Protocol extension. +

+
+
+nodelay (true) +
+
+

+ Whether to enable TCP_NODELAY. +

+
+
+partial_chain +
+
+

+ Claim an intermediate CA in the chain as trusted. +

+
+
+password +
+
+

+ Password to the private key file, if password protected. +

+
+
+psk_identity +
+
+

+ Provide the given PSK identity hint to the client during the handshake. +

+
+
+reuse_session +
+
+

+ Custom policy to decide whether a session should be reused. +

+
+
+reuse_sessions (false) +
+
+

+ Whether to allow session reuse. +

+
+
+secure_renegotiate (false) +
+
+

+ Whether to reject renegotiation attempts that do not conform to RFC5746. +

+
+
+sni_fun +
+
+

+ Function called when the client requests a host using Server Name Indication. Returns options to apply. +

+
+
+sni_hosts +
+
+

+ Options to apply for the host that matches what the client requested with Server Name Indication. +

+
+
+user_lookup_fun +
+
+

+ Function called to determine the shared secret when using PSK, or provide parameters when using SRP. +

+
+
+verify (verify_none) +
+
+

+ Use verify_peer to request a certificate from the client. +

+
+
+verify_fun +
+
+

+ Custom policy to decide whether a client certificate is valid. +

+
+
+versions +
+
+

+ TLS protocol versions that will be supported. +

+
+
+

Note that the client will not send a certificate unless the +value for the verify option is set to verify_peer. This +means that the fail_if_no_peer_cert only apply when combined +with the verify option. The verify_fun option allows +greater control over the client certificate validation.

+

The options sni_fun and sni_hosts are mutually exclusive.

+
+
+
+

Exports

+
+

None.

+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/manual/ranch_tcp/index.html b/docs/en/ranch/1.2/manual/ranch_tcp/index.html new file mode 100644 index 00000000..845e3022 --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch_tcp/index.html @@ -0,0 +1,408 @@ + + + + + + + + + + + + Nine Nines: ranch_tcp(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

ranch_tcp(3)

+ +
+

Name

+
+

ranch_tcp - TCP transport module

+
+
+
+

Description

+
+

The ranch_tcp module implements a TCP Ranch transport.

+

Note that due to bugs in OTP up to at least R16B02, it is +recommended to disable async threads when using the +sendfile function of this transport, as it can make +the threads stuck indefinitely.

+
+
+
+

Types

+
+
+

opt()

+
+
+
opt() = {backlog, non_neg_integer()}
+        | {buffer, non_neg_integer()}
+        | {delay_send, boolean()}
+        | {dontroute, boolean()}
+        | {exit_on_close, boolean()}
+        | {fd, non_neg_integer()}
+        | {high_msgq_watermark, non_neg_integer()}
+        | {high_watermark, non_neg_integer()}
+        | inet
+        | inet6
+        | {ip, inet:ip_address()}
+        | {keepalive, boolean()}
+        | {linger, {boolean(), non_neg_integer()}}
+        | {low_msgq_watermark, non_neg_integer()}
+        | {low_watermark, non_neg_integer()}
+        | {nodelay, boolean()}
+        | {port, inet:port_number()}
+        | {priority, integer()}
+        | {raw, non_neg_integer(), non_neg_integer(), binary()}
+        | {recbuf, non_neg_integer()}
+        | {send_timeout, timeout()}
+        | {send_timeout_close, boolean()}
+        | {sndbuf, non_neg_integer()}
+        | {tos, integer()}
+

Listen options.

+

This does not represent the entirety of the options that can +be set on the socket, but only the options that may be +set independently of protocol implementation.

+
+
+

opts() = [opt()]

+

List of listen options.

+
+
+
+
+

Option descriptions

+
+

None of the options are required.

+

Please consult the gen_tcp and inet manuals for a more +thorough description of these options. This manual only aims +to provide a short description along with what the defaults +are. Defaults may be different in Ranch compared to gen_tcp. +Defaults are given next to the option name.

+
+
+backlog (1024) +
+
+

+ Max length of the queue of pending connections. +

+
+
+buffer +
+
+

+ Size of the buffer used by the Erlang driver. Default is system-dependent. +

+
+
+delay_send (false) +
+
+

+ Always queue packets before sending, to send fewer, larger packets over the network. +

+
+
+dontroute (false) +
+
+

+ Don’t send via a gateway, only send to directly connected hosts. +

+
+
+exit_on_close (true) +
+
+

+ Disable to allow sending data after a close has been detected. +

+
+
+fd +
+
+

+ File descriptor of the socket, if it was opened externally. +

+
+
+high_msgq_watermark (8192) +
+
+

+ Limit in the amount of data in the socket message queue before the socket queue becomes busy. +

+
+
+high_watermark (8192) +
+
+

+ Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy. +

+
+
+inet +
+
+

+ Set up the socket for IPv4. +

+
+
+inet6 +
+
+

+ Set up the socket for IPv6. +

+
+
+ip +
+
+

+ Interface to listen on. Listen on all interfaces by default. +

+
+
+keepalive (false) +
+
+

+ Enable sending of keep-alive messages. +

+
+
+linger ({false, 0}) +
+
+

+ Whether to wait and how long to flush data sent before closing the socket. +

+
+
+low_msgq_watermark (4096) +
+
+

+ Amount of data in the socket message queue before the socket queue leaves busy state. +

+
+
+low_watermark (4096) +
+
+

+ Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state. +

+
+
+nodelay (true) +
+
+

+ Whether to enable TCP_NODELAY. +

+
+
+port (0) +
+
+

+ TCP port number to listen on. 0 means a random port will be used. +

+
+
+priority (0) +
+
+

+ Priority value for all packets to be sent by this socket. +

+
+
+recbuf +
+
+

+ Minimum size of the socket’s receive buffer. Default is system-dependent. +

+
+
+send_timeout (30000) +
+
+

+ How long the send call may wait for confirmation before returning. +

+
+
+send_timeout_close (true) +
+
+

+ Whether to close the socket when the confirmation wasn’t received. +

+
+
+sndbuf +
+
+

+ Minimum size of the socket’s send buffer. Default is system-dependent. +

+
+
+tos +
+
+

+ Value for the IP_TOS IP level option. Use with caution. +

+
+
+

In addition, the raw option can be used to set system-specific +options by specifying the protocol level, the option number and +the actual option value specified as a binary. This option is not +portable. Use with caution.

+
+
+
+

Exports

+
+

None.

+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/manual/ranch_transport/index.html b/docs/en/ranch/1.2/manual/ranch_transport/index.html new file mode 100644 index 00000000..40b22b39 --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch_transport/index.html @@ -0,0 +1,628 @@ + + + + + + + + + + + + Nine Nines: ranch_transport(3) + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

ranch_transport(3)

+ +
+

Name

+
+

ranch_transport - behaviour for transport modules

+
+
+
+

Description

+
+

The ranch_transport behaviour defines the interface used +by Ranch transports.

+
+
+
+

Types

+
+
+

sendfile_opts() = [{chunk_size, non_neg_integer()}]

+

Options used by the sendfile function and callbacks.

+

Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.

+
+
+
+
+

Callbacks

+
+
+

accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}

+
+
+LSocket = CSocket = any() +
+
+

+Listening socket. +

+
+
+Timeout = timeout() +
+
+

+Accept timeout. +

+
+
+

Accept a connection on the given listening socket.

+

The accept_ack callback will be used to initialize the socket +after accepting the connection. This is most useful when the +transport is not raw TCP, like with SSL for example.

+
+
+

accept_ack(CSocket, Timeout) → ok

+
+
+CSocket = any() +
+
+

+Socket for this connection. +

+
+
+Timeout = timeout() +
+
+

+Ack timeout. +

+
+
+

Perform post-accept initialization of the connection.

+

This function will be called by connection processes +before performing any socket operation. It allows +transports that require extra initialization to perform +their task and make the socket ready to use.

+
+
+

close(Socket) → ok

+
+
+Socket = any() +
+
+

+Socket opened with listen/1 or accept/2. +

+
+
+

Close the given socket.

+
+
+

controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}

+
+
+Socket = any() +
+
+

+Socket opened with listen/1 or accept/2. +

+
+
+Pid = pid() +
+
+

+Pid of the new owner of the socket. +

+
+
+

Change the controlling process for the given socket.

+

The controlling process is the process that is allowed to +perform operations on the socket, and that will receive +messages from the socket when active mode is used. When +the controlling process dies, the socket is closed.

+
+
+

listen(TransOpts) → {ok, LSocket} | {error, atom()}

+
+
+TransOpts = any() +
+
+

+Transport options. +

+
+
+LSocket = any() +
+
+

+Listening socket. +

+
+
+

Listen for connections on the given port.

+

The port is given as part of the transport options under +the key port. Any other option is transport dependent.

+

The socket returned by this call can then be used to +accept connections. It is not possible to send or receive +data from the listening socket.

+
+
+

messages() → {OK, Closed, Error}

+
+
+OK = Closed = Error = atom() +
+
+

+Tuple names. +

+
+
+

Return the atoms used to identify messages sent in active mode.

+
+
+

name() → Name

+
+
+Name = atom() +
+
+

+Transport module name. +

+
+
+

Return the name of the transport.

+
+
+

peername(CSocket) → {ok, {IP, Port}} | {error, atom()}

+
+
+CSocket = any() +
+
+

+Socket for this connection. +

+
+
+IP = inet:ip_address() +
+
+

+IP of the remote endpoint. +

+
+
+Port = inet:port_number() +
+
+

+Port of the remote endpoint. +

+
+
+

Return the IP and port of the remote endpoint.

+
+
+

recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}

+
+
+CSocket = any() +
+
+

+Socket for this connection. +

+
+
+Length = non_neg_integer() +
+
+

+Requested length. +

+
+
+Timeout = timeout() +
+
+

+Receive timeout. +

+
+
+Packet = iodata() | any() +
+
+

+Data received. +

+
+
+

Receive data from the given socket when in passive mode.

+

Trying to receive data from a socket that is in active mode +will return an error.

+

A length of 0 will return any data available on the socket.

+

While it is possible to use the timeout value infinity, +this is highly discouraged as this could cause your process +to get stuck waiting for data that will never come. This may +happen when a socket becomes half-open due to a crash of the +remote endpoint. Wi-Fi going down is another common culprit +of this issue.

+
+
+

send(CSocket, Packet) → ok | {error, atom()}

+
+
+CSocket = any() +
+
+

+Socket for this connection. +

+
+
+Packet = iodata() +
+
+

+Data to be sent. +

+
+
+

Send data to the given socket.

+
+
+

sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])

+

Alias of ranch_transport:sendfile/5.

+
+
+

sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])

+

Alias of ranch_transport:sendfile/5.

+
+
+

sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}

+
+
+CSocket = any() +
+
+

+Socket for this connection. +

+
+
+File = file:filename_all() | file:fd() +
+
+

+Filename or file descriptor for the file to be sent. +

+
+
+Offset = non_neg_integer() +
+
+

+Begin sending at this position in the file. +

+
+
+Bytes = non_neg_integer() +
+
+

+Send this many bytes. +

+
+
+SentBytes = non_neg_integer() +
+
+

+This many bytes were sent. +

+
+
+SfOpts = sendfile_opts() +
+
+

+Sendfile options. +

+
+
+

Send data from a file to the given socket.

+

The file may be sent full or in parts, and may be specified +by its filename or by an already open file descriptor.

+

Transports that manipulate TCP directly may use the +file:sendfile/{2,4,5} function, which calls the sendfile +syscall where applicable (on Linux, for example). Other +transports can use the sendfile/6 function exported from +this module.

+
+
+

setopts(CSocket, SockOpts) → ok | {error, atom()}

+
+
+CSocket = any() +
+
+

+Socket for this connection. +

+
+
+SockOpts = any() +
+
+

+Socket options. +

+
+
+

Change options for the given socket.

+

This is mainly useful for switching to active or passive mode +or to set protocol-specific options.

+
+
+

shutdown(CSocket, How) → ok | {error, atom()}

+
+
+CSocket = any() +
+
+

+Socket for this connection. +

+
+
+How = read | write | read_write +
+
+

+Which side(s) of the socket to close. +

+
+
+

Immediately close the socket in one or two directions.

+
+
+

sockname(Socket) → {ok, {IP, Port}} | {error, atom()}

+
+
+Socket = any() +
+
+

+Socket opened with listen/1 or accept/2. +

+
+
+IP = inet:ip_address() +
+
+

+IP of the local endpoint. +

+
+
+Port = inet:port_number() +
+
+

+Port of the local endpoint. +

+
+
+

Return the IP and port of the local endpoint.

+
+
+
+
+

Exports

+
+
+

sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}

+
+
+Transport = module() +
+
+

+Transport module for this socket. +

+
+
+CSocket = any() +
+
+

+Socket for this connection. +

+
+
+File = file:filename_all() | file:fd() +
+
+

+Filename or file descriptor for the file to be sent. +

+
+
+Offset = non_neg_integer() +
+
+

+Begin sending at this position in the file. +

+
+
+Bytes = non_neg_integer() +
+
+

+Send this many bytes. +

+
+
+SentBytes = non_neg_integer() +
+
+

+This many bytes were sent. +

+
+
+SfOpts = sendfile_opts() +
+
+

+Sendfile options. +

+
+
+

Send data from a file to the given socket.

+

This function emulates the function file:sendfile/{2,4,5} +and may be used when transports are not manipulating TCP +directly.

+
+
+
+ + + +
+ +
+ + +

+ Ranch + 1.2 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+
    + + + +
  • 1.2
    • + +
+ +
+
+
+
+ + + + + + + + + + + + diff --git a/docs/en/ranch/index.html b/docs/en/ranch/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/ranch/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000..55161c52 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,203 @@ + + + + + + + + + + + + Nine Nines: Documentation + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Documentation

+ + + + + + + +

Cowboy

+ + + + + + + +

Erlang.mk

+ + + + + + +

Gun

+ + + + + +

Ranch

+ + + + +
+
+

Navigation

+ + +
+

Contribute

+

Do you have examples, tutorials, videos about one or more +of my projects? I would happily include them on this page.

+

Send me an email with the details.

+
+ +
+
+
+
+ + + + + + + + + + + diff --git a/docs/index.xml b/docs/index.xml new file mode 100644 index 00000000..b62edf2e --- /dev/null +++ b/docs/index.xml @@ -0,0 +1,2001 @@ + + + + Docs on Nine Nines + http://ninenines.eu/docs/ + Recent content in Docs on Nine Nines + Hugo -- gohugo.io + en-us + + + + Architecture + http://ninenines.eu/docs/en/cowboy/2.0/guide/architecture/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/cowboy/2.0/guide/architecture/ + <div class="paragraph"><p>Cowboy is a lightweight HTTP server.</p></div> +<div class="paragraph"><p>It is built on top of Ranch. Please see the Ranch guide for more +information.</p></div> +<div class="sect1"> +<h2 id="_one_process_per_connection">One process per connection</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It uses only one process per connection. The process where your +code runs is the process controlling the socket. Using one process +instead of two allows for lower memory usage.</p></div> +<div class="paragraph"><p>Because there can be more than one request per connection with the +keepalive feature of HTTP/1.1, that means the same process will be +used to handle many requests.</p></div> +<div class="paragraph"><p>Because of this, you are expected to make sure your process cleans +up before terminating the handling of the current request. This may +include cleaning up the process dictionary, timers, monitoring and +more.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_binaries">Binaries</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It uses binaries. Binaries are more efficient than lists for +representing strings because they take less memory space. Processing +performance can vary depending on the operation. Binaries are known +for generally getting a great boost if the code is compiled natively. +Please see the HiPE documentation for more details.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_date_header">Date header</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Because querying for the current date and time can be expensive, +Cowboy generates one <code>Date</code> header value every second, shares it +to all other processes, which then simply copy it in the response. +This allows compliance with HTTP/1.1 with no actual performance loss.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_max_connections">Max connections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default the maximum number of active connections is set to a +generally accepted big enough number. This is meant to prevent having +too many processes performing potentially heavy work and slowing +everything else down, or taking up all the memory.</p></div> +<div class="paragraph"><p>Disabling this feature, by setting the <code>{max_connections, infinity}</code> +protocol option, would give you greater performance when you are +only processing short-lived requests.</p></div> +</div> +</div> + + + + + AsciiDoc documentation + http://ninenines.eu/docs/en/erlang.mk/1/guide/asciidoc/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/erlang.mk/1/guide/asciidoc/ + <div class="paragraph"><p>Erlang.mk provides rules for generating documentation from +AsciiDoc files. It can automatically build a user guide PDF, +chunked HTML documentation and Unix manual pages.</p></div> +<div class="sect1"> +<h2 id="_requirements">Requirements</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is necessary to have <a href="http://asciidoc.org/">AsciiDoc</a>, +<a href="http://xmlsoft.org/XSLT/xsltproc2.html">xsltproc</a> and +<a href="http://dblatex.sourceforge.net/">dblatex</a> installed on your +system for Erlang.mk to generate documentation from AsciiDoc sources.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_writing_asciidoc_documentation">Writing AsciiDoc documentation</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="http://asciidoc.org/">AsciiDoc</a> is a text document format for +writing notes, documentation, articles, books, ebooks, slideshows, +web pages, man pages and blogs. AsciiDoc files can be translated +to many formats including HTML, PDF, EPUB, man page.</p></div> +<div class="paragraph"><p>The <a href="http://asciidoc.org/userguide.html">AsciiDoc user guide</a> +describes the AsciiDoc syntax.</p></div> +<div class="paragraph"><p>The <a href="https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide">Erlang.mk user guide</a> +is written in AsciiDoc and can be used as an example. The entry +file is <a href="https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc">book.asciidoc</a>.</p></div> +<div class="paragraph"><p>Erlang.mk expects you to put your documentation in a specific +location. This is <em>doc/src/guide/</em> for the user guide, and +<em>doc/src/manual/</em> for the function reference. In the case of +the user guide, the entry point is always <em>doc/src/guide/book.asciidoc</em>.</p></div> +<div class="paragraph"><p>For manual pages, it is good practice to use section 3 for +modules, and section 7 for the application itself.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All of the AsciiDoc related configuration can be done directly +inside the files themselves.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To build all documentation:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make docs</tt></pre></div></div> +<div class="paragraph"><p>To build only the AsciiDoc documentation:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make asciidoc</tt></pre></div></div> +<div class="paragraph"><p>To build only the user guide:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make asciidoc-guide</tt></pre></div></div> +<div class="paragraph"><p>To build only the manual:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make asciidoc-manual</tt></pre></div></div> +<div class="paragraph"><p>To install man pages on Unix:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make install-docs</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk allows customizing the installation path and sections +of the man pages to be installed. The <code>MAN_INSTALL_PATH</code> variable +defines where man pages will be installed. It defaults to +<em>/usr/local/share/man</em>. The <code>MAN_SECTIONS</code> variable defines +which manual sections are to be installed. It defaults to <code>3 7</code>.</p></div> +<div class="paragraph"><p>To install man pages to a custom location:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make install-docs <span style="color: #009900">MAN_INSTALL_PATH</span><span style="color: #990000">=</span>/opt/share/man</tt></pre></div></div> +<div class="paragraph"><p>Note that you may need to run the install commands using +<code>sudo</code> or equivalent if the location is not writeable by +your user.</p></div> +</div> +</div> + + + + + Building + http://ninenines.eu/docs/en/erlang.mk/1/guide/app/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/erlang.mk/1/guide/app/ + <div class="paragraph"><p>Erlang.mk can do a lot of things, but it is, first and +foremost, a build tool. In this chapter we will cover +the basics of building a project with Erlang.mk.</p></div> +<div class="paragraph"><p>For most of this chapter, we will assume that you are +using a project <a href="../getting_started">generated by Erlang.mk</a>.</p></div> +<div class="sect1"> +<h2 id="_how_to_build">How to build</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To build a project, all you have to do is type <code>make</code>:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make</tt></pre></div></div> +<div class="paragraph"><p>It will work regardless of your project: OTP applications, +library applications, NIFs, port drivers or even releases. +Erlang.mk also automatically downloads and compiles the +dependencies for your project.</p></div> +<div class="paragraph"><p>All this is possible thanks to a combination of configuration +and conventions. Most of the conventions come from Erlang/OTP +itself so any seasoned Erlang developers should feel right at +home.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_what_to_build">What to build</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk gives you control over three steps of the build +process, allowing you to do a partial build if needed.</p></div> +<div class="paragraph"><p>A build has three phases: first any dependency is fetched +and built, then the project itself is built and finally a +release may be generated when applicable. A release is only +generated for projects specifically configured to do so.</p></div> +<div class="paragraph"><p>Erlang.mk handles those three phases automatically when you +type <code>make</code>. But sometimes you just want to repeat one or +two of them.</p></div> +<div class="paragraph"><p>The commands detailed in this section are most useful after +you have a successful build as they allow you to quickly +redo a step instead of going through everything. This is +especially useful for large projects or projects that end +up generating releases.</p></div> +<div class="sect3"> +<h4 id="_application">Application</h4> +<div class="paragraph"><p>You can build your application and dependencies without +generating a release by running the following command:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make app</tt></pre></div></div> +<div class="paragraph"><p>To build your application without touching dependencies +at all, you can use the <code>SKIP_DEPS</code> variable:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make app <span style="color: #009900">SKIP_DEPS</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>This command is very useful if you have a lot of dependencies +and develop on a machine with slow file access, like the +Raspberry Pi and many other embedded devices.</p></div> +<div class="paragraph"><p>Note that this command may fail if a required dependency +is missing.</p></div> +</div> +<div class="sect3"> +<h4 id="_dependencies">Dependencies</h4> +<div class="paragraph"><p>You can build all dependencies, and nothing else, by +running the following command:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make deps</tt></pre></div></div> +<div class="paragraph"><p>This will fetch and compile all dependencies and their +dependencies, recursively.</p></div> +<div class="paragraph"><p><a href="../deps">Packages and dependencies</a> are covered +in the next chapter.</p></div> +</div> +<div class="sect3"> +<h4 id="_release">Release</h4> +<div class="paragraph"><p>It is not possible to build the release without at least +building the application itself, unless of course if there&#8217;s +no application to begin with.</p></div> +<div class="paragraph"><p>To generate the release, <code>make</code> will generally suffice with +a normal Erlang.mk. A separate target is however available, +and will take care of building the release, after building +the application and all dependencies:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make rel</tt></pre></div></div> +<div class="paragraph"><p>Consult the <a href="../relx">Releases</a> chapter for more +information about what releases are and how they are generated.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_application_resource_file">Application resource file</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When building your application, Erlang.mk will generate the +<a href="http://www.erlang.org/doc/man/app.html">application resource file</a>. +This file is mandatory for all Erlang applications and is +found in <em>ebin/$(PROJECT).app</em>.</p></div> +<div class="paragraph"><p><code>PROJECT</code> is a variable defined in your Makefile and taken +from the name of the directory when Erlang.mk bootstraps +your project.</p></div> +<div class="paragraph"><p>Erlang.mk can build the <em>ebin/$(PROJECT).app</em> in two different +ways: from the configuration found in the Makefile, or from +the <em>src/$(PROJECT).app.src</em> file.</p></div> +<div class="sect3"> +<h4 id="_application_configuration">Application configuration</h4> +<div class="paragraph"><p>Erlang.mk automatically fills the <code>PROJECT</code> variable when +bootstrapping a new project, but everything else is up to +you. None of the values are required to build your project, +although it is recommended to fill everything relevant to +your situation.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +<code>PROJECT</code> +</dt> +<dd> +<p> + The name of the OTP application or library. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_DESCRIPTION</code> +</dt> +<dd> +<p> + Short description of the project. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_VERSION</code> +</dt> +<dd> +<p> + Current version of the project. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_REGISTERED</code> +</dt> +<dd> +<p> + List of the names of all registered processes. +</p> +</dd> +<dt class="hdlist1"> +<code>LOCAL_DEPS</code> +</dt> +<dd> +<p> + List of Erlang/OTP applications this project depends on, + excluding <code>erts</code>, <code>kernel</code> and <code>stdlib</code>, or list of + dependencies local to this repository (in <code>APPS_DIR</code>). +</p> +</dd> +<dt class="hdlist1"> +<code>DEPS</code> +</dt> +<dd> +<p> + List of applications this project depends on that need + to be fetched by Erlang.mk. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>There&#8217;s no need for quotes or anything. The relevant part of +the Cowboy Makefile follows, if you need an example:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">PROJECT =</span> cowboy +<span style="color: #009900">PROJECT_DESCRIPTION =</span> Small<span style="color: #990000">,</span> fast<span style="color: #990000">,</span> modular HTTP server<span style="color: #990000">.</span> +<span style="color: #009900">PROJECT_VERSION =</span> 2.0.0-pre.2 +<span style="color: #009900">PROJECT_REGISTERED =</span> cowboy_clock + +<span style="color: #009900">LOCAL_DEPS =</span> crypto +<span style="color: #009900">DEPS =</span> cowlib ranch</tt></pre></div></div> +<div class="paragraph"><p>Any space before and after the value is dropped.</p></div> +<div class="paragraph"><p><a href="../deps">Dependencies</a> are covered in details in +the next chapter.</p></div> +</div> +<div class="sect3"> +<h4 id="_legacy_method">Legacy method</h4> +<div class="paragraph"><p>The <em>src/$(PROJECT).app.src</em> file is a legacy method of +building Erlang applications. It was introduced by the original +<code>rebar</code> build tool, of which Erlang.mk owes a great deal as it +is its main inspiration.</p></div> +<div class="paragraph"><p>The <em>.app.src</em> file serves as a template to generate the <em>.app</em> +file. Erlang.mk will take it, fill in the <code>modules</code> value +dynamically, and save the result in <em>ebin/$(PROJECT).app</em>.</p></div> +<div class="paragraph"><p>When using this method, Erlang.mk cannot fill the <code>applications</code> +key from dependencies automatically, which means you need to +add them to Erlang.mk and to the <em>.app.src</em> at the same time, +duplicating the work.</p></div> +<div class="paragraph"><p>If you really can&#8217;t live without the legacy method, for one +reason or another, worry not; Erlang.mk will support it. And +if you need to create a new project that uses this method, you +just have to say so when bootstrapping:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib <span style="color: #009900">LEGACY</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_automatic_application_resource_file_values">Automatic application resource file values</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When building the application resource file, Erlang.mk may +automatically add an <code>id</code> key with information about the +Git commit (if using Git), or an empty string otherwise. +It will only do this under specific conditions:</p></div> +<div class="ulist"><ul> +<li> +<p> +The application was built as a dependency of another, or +</p> +</li> +<li> +<p> +The legacy method was used, and the <em>.app.src</em> file contained <code>{id, "git"}</code> +</p> +</li> +</ul></div> +<div class="paragraph"><p>This value is most useful when you need to help your users, +as it allows you to know which version they run exactly by +asking them to look in the file, or by running a simple +command on their production server:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #993399">1</span><span style="color: #990000">&gt;</span> <span style="font-weight: bold"><span style="color: #000000">application:get_all_key</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span> +{<span style="color: #FF6600">ok</span>,[{<span style="color: #FF6600">description</span>,<span style="color: #FF0000">"Small, fast, modular HTTP server."</span>}, + {<span style="color: #FF6600">id</span>,<span style="color: #FF0000">"2.0.0-pre.2-25-g0ffde50-dirty"</span>},</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_file_formats">File formats</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk supports a variety of different source file formats. +The following formats are supported natively:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<thead> +<tr> +<th align="left" valign="top"> Extension </th> +<th align="center" valign="top"> Location </th> +<th align="center" valign="top"> Description </th> +<th align="center" valign="top"> Output</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">.erl</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Erlang source</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.core</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Core Erlang source</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.xrl</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Leex source</p></td> +<td align="center" valign="top"><p class="table">src/*.erl</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.yrl</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Yecc source</p></td> +<td align="center" valign="top"><p class="table">src/*.erl</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.asn1</p></td> +<td align="center" valign="top"><p class="table">asn1/</p></td> +<td align="center" valign="top"><p class="table">ASN.1 files</p></td> +<td align="center" valign="top"><p class="table">include/<strong>.hrl include/</strong>.asn1db src/*.erl</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.mib</p></td> +<td align="center" valign="top"><p class="table">mibs/</p></td> +<td align="center" valign="top"><p class="table">SNMP MIB files</p></td> +<td align="center" valign="top"><p class="table">include/<strong>.hrl priv/mibs/</strong>.bin</p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>Files are always searched recursively.</p></div> +<div class="paragraph"><p>The build is ordered, so that files that generate Erlang source +files are run before, and the resulting Erlang source files are +then built normally.</p></div> +<div class="paragraph"><p>In addition, Erlang.mk keeps track of header files (<code>.hrl</code>) +as described at the end of this chapter. It can also compile +C code, as described in the <a href="../ports">NIFs and port drivers</a> +chapter.</p></div> +<div class="paragraph"><p>Erlang.mk also comes with plugins for the following formats:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<thead> +<tr> +<th align="left" valign="top"> Extension </th> +<th align="center" valign="top"> Location </th> +<th align="center" valign="top"> Description </th> +<th align="center" valign="top"> Output</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">.dtl</p></td> +<td align="center" valign="top"><p class="table">templates/</p></td> +<td align="center" valign="top"><p class="table">Django templates</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.proto</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Protocol buffers</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_compilation_options">Compilation options</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides a few variables that you can use to customize +the build process and the resulting files.</p></div> +<div class="sect3"> +<h4 id="_erlc_opts">ERLC_OPTS</h4> +<div class="paragraph"><p><code>ERLC_OPTS</code> can be used to pass some options to <code>erlc</code>, the Erlang +compiler. Erlang.mk does not restrict any option. Please refer to +the <a href="http://www.erlang.org/doc/man/erlc.html">erlc Manual</a> for the +full list.</p></div> +<div class="paragraph"><p>By default, Erlang.mk will set the following options:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">ERLC_OPTS =</span> -Werror <span style="color: #990000">+</span>debug_info <span style="color: #990000">+</span>warn_export_vars <span style="color: #990000">+</span>warn_shadow_vars <span style="color: #990000">+</span>warn_obsolete_guard</tt></pre></div></div> +<div class="paragraph"><p>In other words: warnings as errors, debug info (recommended) and +enable warnings for exported variables, shadow variables and +obsolete guard functions.</p></div> +<div class="paragraph"><p>You can redefine this variable in your Makefile to change it +completely, either before or after including Erlang.mk:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">ERLC_OPTS =</span> <span style="color: #990000">+</span>debug_info</tt></pre></div></div> +<div class="paragraph"><p>You can also filter out some options from the defaults Erlang.mk +sets, by defining ERLC_OPTS after including Erlang.mk using the +<code>:=</code> operator.</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>include erlang.mk + +<span style="color: #990000">ERLC_OPTS :=</span> <span style="color: #009900">$(</span>filter-out -Werror<span style="color: #990000">,</span><span style="color: #009900">$(ERLC_OPTS))</span></tt></pre></div></div> +</div> +<div class="sect3"> +<h4 id="_erlc_exclude">ERLC_EXCLUDE</h4> +<div class="paragraph"><p><code>ERLC_EXCLUDE</code> can be used to exclude some modules from the +compilation. It&#8217;s there for handling special cases, you should +not normally need it.</p></div> +<div class="paragraph"><p>To exclude a module, simply list it in the variable, either +before or after including Erlang.mk:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">ERLC_EXCLUDE =</span> cowboy_http2</tt></pre></div></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_cold_and_hot_builds">Cold and hot builds</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The first time you run <code>make</code>, Erlang.mk will build everything.</p></div> +<div class="paragraph"><p>The second time you run <code>make</code>, and all subsequent times, Erlang.mk +will only rebuild what changed. Erlang.mk has been optimized for +this use case, as it is the most common during development.</p></div> +<div class="paragraph"><p>Erlang.mk figures out what changed by using the dependency tracking +feature of Make. Make automatically rebuilds a target if one of its +dependency has changed (for example if a header file has changed, +all the source files that include it will be rebuilt), and Erlang.mk +leverages this feature to cut down on rebuild times.</p></div> +<div class="paragraph"><p>Note that this applies only to building; some other features of +Erlang.mk will run every time they are called regardless of files +changed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependency_tracking">Dependency tracking</h2> +<div class="sectionbody"> +<div class="admonitionblock"> +<table><tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content">This section is about the dependency tracking between files +inside your project, not application dependencies.</td> +</tr></table> +</div> +<div class="paragraph"><p>Erlang.mk keeps track of the dependencies between the different +files in your project. This information is kept in the <em>$(PROJECT).d</em> +file in your directory. It is generated if missing, and will be +generated again after every file change, by default.</p></div> +<div class="paragraph"><p>Dependency tracking is what allows Erlang.mk to know when to +rebuild Erlang files when header files, behaviors or parse +transforms have changed. Erlang.mk also automatically keeps +track of which files should be compiled first, for example +when you have behaviors used by other modules in your project.</p></div> +<div class="paragraph"><p>If your project is stable, you may want to disable generating +the dependency tracking file every time you compile. You can +do this by adding the following line to your <em>Makefile</em>:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>NO_MAKEDEP <span style="color: #990000">?=</span> <span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>As you can see, the snippet above uses <code>?=</code> instead of a +simple equal sign. This is to allow you to temporarily override +this value when you do make substantial changes to your project +(including a new header file, new module with dependencies, etc.) +and want to rebuild the dependency tracking file. You&#8217;ll be +able to use the following command:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ <span style="color: #009900">NO_MAKEDEP</span><span style="color: #990000">=</span> make</tt></pre></div></div> +<div class="paragraph"><p>Otherwise, <code>make clean app</code> will of course force the +recompilation of your project.</p></div> +<div class="paragraph"><p>Erlang.mk can also keep track of the source files generated +by other means, for example if you generate code from a data +file in your repository.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generating_erlang_source">Generating Erlang source</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides hooks at different stages of the build process. +When your goal is to generate Erlang source files, you can +add your own rules before or after the dependency tracking +file is generated. To do this, you would add your hook before +or after including the <em>erlang.mk</em> file.</p></div> +<div class="paragraph"><p>The easiest way is after:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">PROJECT =</span> example + +include erlang.mk + +<span style="color: #009900">$(PROJECT)</span>.d<span style="color: #990000">::</span> src/generated_mod.erl + +src/generated_mod.erl<span style="color: #990000">::</span> gen-mod.sh + <span style="color: #009900">$(gen_verbose)</span> <span style="color: #990000">.</span>/gen-mod.sh <span style="color: #009900">$@</span></tt></pre></div></div> +<div class="paragraph"><p>In this case we use <code>$(gen_verbose)</code> to hide the details of +the build by default. Erlang.mk will simply say what file +is it currently generating.</p></div> +<div class="paragraph"><p>When using an external script to generate the Erlang source +file, it is recommended to depend on that script, so that +the source file gets generated again when the script gets +modified.</p></div> +<div class="paragraph"><p>If for whatever reason you prefer to hook before including +Erlang.mk, don&#8217;t forget to set the <code>.DEFAULT_GOAL</code> variable, +otherwise nothing will get built:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">PROJECT =</span> example + +.DEFAULT_GOAL <span style="color: #990000">=</span> all + +<span style="color: #009900">$(PROJECT)</span>.d<span style="color: #990000">::</span> src/generated_mod.erl + +include erlang.mk + +src/generated_mod.erl<span style="color: #990000">::</span> gen-mod.sh + <span style="color: #009900">$(gen_verbose)</span> <span style="color: #990000">.</span>/gen-mod.sh <span style="color: #009900">$@</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_cleaning">Cleaning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Building typically involves creating a lot of new files. Some +are reused in rebuilds, some are simply replaced. All can be +removed safely.</p></div> +<div class="paragraph"><p>Erlang.mk provides two commands to remove them: <code>clean</code> and +<code>distclean</code>. <code>clean</code> removes all the intermediate files that +were created as a result of building, including the BEAM files, +the dependency tracking file and the generated documentation. +<code>distclean</code> removes these and more, including the downloaded +dependencies, Dialyzer&#8217;s PLT file and the generated release, +putting your directory back to the state it was before you +started working on it.</p></div> +<div class="paragraph"><p>To clean:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make clean</tt></pre></div></div> +<div class="paragraph"><p>Or distclean:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make distclean</tt></pre></div></div> +<div class="paragraph"><p>That is the question.</p></div> +<div class="paragraph"><p>Note that Erlang.mk will automatically clean some files as +part of other targets, but it will never run <code>distclean</code> if +you don&#8217;t explicitly use it.</p></div> +</div> +</div> + + + + + Code coverage + http://ninenines.eu/docs/en/erlang.mk/1/guide/coverage/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/erlang.mk/1/guide/coverage/ + <div class="paragraph"><p>Placeholder chapter.</p></div> + + + + + Common Test + http://ninenines.eu/docs/en/erlang.mk/1/guide/common_test/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/erlang.mk/1/guide/common_test/ + <div class="paragraph"><p>Common Test is Erlang&#8217;s functional testing framework. +Erlang.mk automates the discovery and running of Common +Test suites.</p></div> +<div class="sect1"> +<h2 id="_writing_tests">Writing tests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/common_test/write_test_chapter.html">Common Test user guide</a> +is the best place to learn how to write tests. Erlang.mk +requires that file names for test suites end with <em>_SUITE.erl</em> +and that the files be located in the <em>$(TEST_DIR)</em> directory. +This defaults to <em>test/</em>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>CT_OPTS</code> variable allows you to set extra Common Test +options. Options are documented in the +<a href="http://www.erlang.org/doc/apps/common_test/run_test_chapter.html">Common Test user guide</a>. +You can use it to set Common Test hooks, for example:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">CT_OPTS =</span> -ct_hooks cowboy_ct_hook</tt></pre></div></div> +<div class="paragraph"><p>The <code>CT_SUITES</code> variable can be used to override what +Common Test suites Erlang.mk will be aware of. It does +not normally need to be set as Erlang.mk will find the +test suites automatically.</p></div> +<div class="paragraph"><p>The name of the suite is the part before <code>_SUITE.erl</code>. +If the file is named <em>http_SUITE.erl</em>, the test suite +is <code>http</code>:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">CT_SUITES =</span> http ws</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To run all tests (including Common Test):</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make tests</tt></pre></div></div> +<div class="paragraph"><p>To run all tests and static checks (including Common Test):</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make check</tt></pre></div></div> +<div class="paragraph"><p>You can also run Common Test separately:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make ct</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will create targets for all test suites it finds. +If you have a file named <em>test/http_SUITE.erl</em>, then the +target <code>ct-http</code> will run that specific test suite:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make ct-http</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk provides a convenient way to run a specific +group or a specific test case within a specific group, +using the variable <code>t</code>. Note that this only applies to +suite-specific targets, like the <code>ct-http</code> example above.</p></div> +<div class="paragraph"><p>To run all tests from the <code>http_compress</code> group in the +<code>http_SUITE</code> test suite, write:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div> +<div class="paragraph"><p>Similarly, to run a specific test case in that group:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress<span style="color: #990000">:</span>headers_dupe</tt></pre></div></div> +<div class="paragraph"><p>To do the same against a multi-application repository, +you can use the <code>-C</code> option:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make -C apps/my_app ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>my_group<span style="color: #990000">:</span>my_case</tt></pre></div></div> +<div class="paragraph"><p>Note that this also applies to dependencies. When using Cowboy +as a dependency, you can run the following directly:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make -C deps/cowboy ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div> +<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available, +but covered in its own chapter.</p></div> +</div> +</div> + + + + + Compatibility with other build tools + http://ninenines.eu/docs/en/erlang.mk/1/guide/compat/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/erlang.mk/1/guide/compat/ + <div class="paragraph"><p>Erlang.mk tries its best to be compatible with the other Erlang +build tools. It can use dependencies written with other build +tools in mind, and can also make your projects usable by those +build tools as well. Erlang.mk is like the cool kid that gets +along with everybody.</p></div> +<div class="paragraph"><p>In this chapter I will use the term <em>Rebar project</em> to refer +to a project built using Rebar 2, Rebar 3 or Mad. These three +build tools are very similar and share the same configuration +file.</p></div> +<div class="sect1"> +<h2 id="_rebar_projects_as_erlang_mk_dependencies">Rebar projects as Erlang.mk dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk comes with a feature called <em>Autoload</em> which will +use Rebar 2 to patch any Rebar project and make it compatible +with Erlang.mk. This feature essentially patches Rebar out +and adds a Makefile to the project that Erlang.mk can then +use for building:</p></div> +<div class="paragraph"><p><em>Autoload</em> is documented in more details in the +<a href="../deps">Packages and dependencies</a> chapter.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_projects_as_rebar_dependencies">Erlang.mk projects as Rebar dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk projects can be made compatible with the Rebar family +of build tools pretty easily, as Erlang.mk will generate +all the files they require for building.</p></div> +<div class="paragraph"><p>The Rebar family requires two files: a <em>rebar.config</em> file +containing compilation options and the list of dependencies, +and the application resource file, found either at +<em>ebin/$(PROJECT).app</em> or at <em>src/$(PROJECT).app.src</em>.</p></div> +<div class="sect3"> +<h4 id="_rebar_configuration">Rebar configuration</h4> +<div class="paragraph"><p>Erlang.mk comes with a target that generates a <em>rebar.config</em> +file when invoked:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make rebar<span style="color: #990000">.</span>config</tt></pre></div></div> +<div class="paragraph"><p>Careful! This will build the file even if it already existed +before.</p></div> +<div class="paragraph"><p>To build this file, Erlang.mk uses information it finds in +the <code>DEPS</code> and <code>ERLC_OPTS</code> variables, among others. This +means that the Rebar family builds your project much the +same way as Erlang.mk.</p></div> +<div class="paragraph"><p>Careful though! Different build tools have different fetching +strategies. If some applications provide differing dependencies, +they might be fetched differently by other build tools. Check +the upcoming Sanity check chapter to find out how to detect such +issues.</p></div> +<div class="paragraph"><p>You can automatically generate this file when you build +your application, by making it a dependency of the <code>app</code> +target:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #990000">app::</span> rebar.config</tt></pre></div></div> +<div class="paragraph"><p>Don&#8217;t forget to commit the file when it changes!</p></div> +<div class="paragraph"><p>If you run into other issues, it&#8217;s probably because you use a +feature specific to Erlang.mk, like the <code>cp</code> fetch method. +It could also be that we forgot to handle something! Sorry. +We are of course interested to hear about any compatibility +problems you may have, just open a ticket!</p></div> +</div> +<div class="sect3"> +<h4 id="_application_resource_file">Application resource file</h4> +<div class="paragraph"><p>Erlang.mk has two ways to generate an application resource +file: from the information found in the Makefile, or from +the information found in the <em>src/$(PROJECT).app.src</em> file. +Needless to say, if you have this file in your repository, +then you don&#8217;t need to worry about compatibility with other +build tools.</p></div> +<div class="paragraph"><p>If you don&#8217;t, however, it&#8217;s not much harder. Every time +Erlang.mk will compile your application, it will produce +a new <em>ebin/$(PROJECT).app</em> file. Simply commit this file +when it changes. It will only change when you modify the +configuration, add or remove modules.</p></div> +</div> +</div> +</div> + + + + + Connection + http://ninenines.eu/docs/en/gun/1.0/guide/connect/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/gun/1.0/guide/connect/ + <div class="paragraph"><p>This chapter describes how to open, monitor and close +a connection using the Gun client.</p></div> +<div class="sect1"> +<h2 id="_gun_connections">Gun connections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun is designed with the SPDY and Websocket protocols in mind. +They are built for long-running connections that allow concurrent +exchange of data, either in the form of request/responses for +SPDY or in the form of messages for Websocket.</p></div> +<div class="paragraph"><p>A Gun connection is an Erlang process that manages a socket to +a remote endpoint. This Gun connection is owned by a user +process that is called the <em>owner</em> of the connection, and is +managed by the supervision tree of the <code>gun</code> application.</p></div> +<div class="paragraph"><p>The owner process communicates with the Gun connection +by calling functions from the module <code>gun</code>. All functions +perform their respective operations asynchronously. The Gun +connection will send Erlang messages to the owner process +whenever needed.</p></div> +<div class="paragraph"><p>When the remote endpoint closes the connection, Gun attempts +to reconnect automatically.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_opening_a_new_connection">Opening a new connection</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>gun:open/{2,3}</code> function must be used to open a connection.</p></div> +<div class="listingblock"> +<div class="title">Opening a connection to example.org on port 443</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">443</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If the port given is 443, Gun will attempt to connect using +SSL. The protocol will be selected automatically using the +NPN extension for TLS. By default Gun supports SPDY/3.1, +SPDY/3 and HTTP/1.1 when connecting using SSL.</p></div> +<div class="paragraph"><p>For any other port, Gun will attempt to connect using TCP +and will use the HTTP/1.1 protocol.</p></div> +<div class="paragraph"><p>The transport and protocol used can be overriden using +options. The manual documents all available options.</p></div> +<div class="paragraph"><p>Options can be provided as a third argument, and take the +form of a map.</p></div> +<div class="listingblock"> +<div class="title">Opening an SSL connection to example.org on port 8443</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">8443</span>, #{<span style="color: #0000FF">transport</span><span style="color: #990000">=&gt;</span><span style="color: #FF6600">ssl</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_waiting_for_the_connection_to_be_established">Waiting for the connection to be established</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When Gun successfully connects to the server, it sends a +<code>gun_up</code> message with the protocol that has been selected +for the connection.</p></div> +<div class="paragraph"><p>Gun provides the functions <code>gun:await_up/{1,2,3}</code> that wait +for the <code>gun_up</code> message. They can optionally take a monitor +reference and/or timeout value. If no monitor is provided, +one will be created for the duration of the function call.</p></div> +<div class="listingblock"> +<div class="title">Synchronous opening of a connection</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">443</span>), +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Protocol</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await_up</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_handling_connection_loss">Handling connection loss</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When the connection is lost, Gun will send a <code>gun_down</code> +message indicating the current protocol, the reason the +connection was lost and two list of stream references.</p></div> +<div class="paragraph"><p>The first list indicates open streams that <em>may</em> have been +processed by the server. The second list indicates open +streams that the server did not process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_monitoring_the_connection_process">Monitoring the connection process</h2> +<div class="sectionbody"> +<div class="paragraph"><p>@todo Gun should detect the owner process being killed</p></div> +<div class="paragraph"><p>Because software errors are unavoidable, it is important to +detect when the Gun process crashes. It is also important +to detect when it exits normally. Erlang provides two ways +to do that: links and monitors.</p></div> +<div class="paragraph"><p>Gun leaves you the choice as to which one will be used. +However, if you use the <code>gun:await/{2,3}</code> or <code>gun:await_body/{2,3}</code> +functions, a monitor may be used for you to avoid getting +stuck waiting for a message that will never come.</p></div> +<div class="paragraph"><p>If you choose to monitor yourself you can do it on a permanent +basis rather than on every message you will receive, saving +resources. Indeed, the <code>gun:await/{3,4}</code> and <code>gun:await_body/{3,4}</code> +functions both accept a monitor argument if you have one already.</p></div> +<div class="listingblock"> +<div class="title">Monitoring the connection process</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">443</span>)<span style="color: #990000">.</span> +<span style="color: #009900">MRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">monitor</span></span>(<span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This monitor reference can be kept and used until the connection +process exits.</p></div> +<div class="listingblock"> +<div class="title">Handling <code>DOWN</code> messages</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> + <span style="font-style: italic"><span style="color: #9A1900">%% Receive Gun messages here...</span></span> + {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">Mref</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-&gt;</span> + <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>), + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</span>); +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>What to do when you receive a <code>DOWN</code> message is entirely up to you.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_closing_the_connection_abruptly">Closing the connection abruptly</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The connection can be stopped abruptly at any time by calling +the <code>gun:close/1</code> function.</p></div> +<div class="listingblock"> +<div class="title">Immediate closing of the connection</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">gun:close</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The process is stopped immediately without having a chance to +perform the protocol&#8217;s closing handshake, if any.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_closing_the_connection_gracefully">Closing the connection gracefully</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The connection can also be stopped gracefully by calling the +<code>gun:shutdown/1</code> function.</p></div> +<div class="listingblock"> +<div class="title">Graceful shutdown of the connection</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">gun:shutdown</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Gun will refuse any new requests or messages after you call +this function. It will however continue to send you messages +for existing streams until they are all completed.</p></div> +<div class="paragraph"><p>For example if you performed a GET request just before calling +<code>gun:shutdown/1</code>, you will still receive the response before +Gun closes the connection.</p></div> +<div class="paragraph"><p>If you set a monitor beforehand, you will receive a message +when the connection has been closed.</p></div> +</div> +</div> + + + + + Constraints + http://ninenines.eu/docs/en/cowboy/2.0/guide/constraints/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/cowboy/2.0/guide/constraints/ + <div class="paragraph"><p>Cowboy provides an optional constraints based validation feature +when interacting with user input.</p></div> +<div class="paragraph"><p>Constraints are first used during routing. The router uses +constraints to more accurately match bound values, allowing +to create routes where a segment is an integer for example, +and rejecting the others.</p></div> +<div class="paragraph"><p>Constraints are also used when performing a match operation +on input data, like the query string or cookies. There, a +default value can also be provided for optional values.</p></div> +<div class="paragraph"><p>Finally, constraints can be used to not only validate input, +but also convert said input into proper Erlang terms, all in +one step.</p></div> +<div class="sect1"> +<h2 id="_structure">Structure</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Constraints are provided as a list of fields and for each +field a list of constraints for that field can be provided.</p></div> +<div class="paragraph"><p>Fields are either the name of the field; the name and +one or more constraints; or the name, one or more constraints +and a default value.</p></div> +<div class="paragraph"><p>When no default value is provided then the field is required. +Otherwise the default value is used.</p></div> +<div class="paragraph"><p>All constraints for a field will be used to match its value +in the order they are given. If the value is modified by a +constraint, the next constraint receives the updated value.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_built_in_constraints">Built-in constraints</h2> +<div class="sectionbody"> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="50%" /> +<col width="50%" /> +<thead> +<tr> +<th align="left" valign="top"> Constraint </th> +<th align="left" valign="top"> Description</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">int</p></td> +<td align="left" valign="top"><p class="table">Convert binary value to integer.</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">nonempty</p></td> +<td align="left" valign="top"><p class="table">Ensures the binary value is non-empty.</p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_custom_constraint">Custom constraint</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In addition to the predefined constraints, Cowboy will accept +a fun. This fun must accept one argument and return one of +<code>true</code>, <code>{true, NewValue}</code> or <code>false</code>. The result indicates +whether the value matches the constraint, and if it does it +can optionally be modified. This allows converting the value +to a more appropriate Erlang term.</p></div> +<div class="paragraph"><p>Note that constraint functions SHOULD be pure and MUST NOT crash.</p></div> +</div> +</div> + + + + + Continuous integration + http://ninenines.eu/docs/en/erlang.mk/1/guide/ci/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/erlang.mk/1/guide/ci/ + <div class="paragraph"><p>Placeholder chapter.</p></div> + + + + + Contributing + http://ninenines.eu/docs/en/erlang.mk/1/guide/contributing/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/erlang.mk/1/guide/contributing/ + <div class="paragraph"><p>You are welcome and encouraged to contribute.</p></div> +<div class="paragraph"><p>This is how.</p></div> +<div class="sect1"> +<h2 id="_priorities">Priorities</h2> +<div class="sectionbody"> +<div class="paragraph"><p>From the most important to the least important:</p></div> +<div class="ulist"><ul> +<li> +<p> +Bugs +</p> +</li> +<li> +<p> +Package issues/additions +</p> +</li> +<li> +<p> +Refactoring +</p> +</li> +<li> +<p> +Features +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_bugs">Bugs</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you have found a bug, you should open a ticket. Include +everything relevant including the command you used, output, +a link to the code that triggers the issue, why you think +this is a bug, etc.</p></div> +<div class="paragraph"><p>If you think you have found a bug but you are not sure, you +should open a ticket as previously explained.</p></div> +<div class="paragraph"><p>If you have found a bug and you need it to be solved RIGHT +NOW, open a ticket as previously explained.</p></div> +<div class="paragraph"><p>Once you have opened a ticket, be patient, try to answer +questions in a timely manner and confirm that the bug was +indeed fixed when it is.</p></div> +<div class="paragraph"><p>If you can&#8217;t be patient, either try to solve the bug and +contribute the fix back or become a paying customer.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_code">Code</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The code is located in the <em>core/*.mk</em> and <em>plugins/*.mk</em> files. +The tests are located in the <em>test/Makefile</em> and <em>test/*.mk</em> files.</p></div> +<div class="paragraph"><p>If you have a fix or a hack for a bug, you should open a +pull request. Any fix should include a test case that fails +before the fix and is working after.</p></div> +<div class="paragraph"><p>If you have a test case that reproduces a bug, but no fix for +it, you should open a pull request.</p></div> +<div class="paragraph"><p>Changes need to be tested with at least the <code>make check</code> +command. A specific test case can be tested using <code>make check c=CASE</code> +with <code>CASE</code> the name of the target to run. Output can be +modulated using the <code>V</code> variable, which is an integer +from 0 to 4. A typical use would be <code>make check c=dialyzer V=3</code>. +The value 4 is particular and shows expanded commands right +before they are executed.</p></div> +<div class="paragraph"><p>To run tests in parallel, use the <code>-j</code> option. It is generally +a good idea to also use the <code>-k</code> option to run all tests even +if one fails. For example: <code>make check -j 32 -k</code>.</p></div> +<div class="paragraph"><p>Some changes should be tested against all packages. Continue +reading for more details on testing them.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_packages">Packages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can search existing packages using the <code>make search q=STRING</code> +command. This can be done both from an Erlang.mk project or +directly from the Erlang.mk repository.</p></div> +<div class="paragraph"><p>Packages can be added to the index using the <code>pkg_add.sh</code> script.</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com<span style="color: #990000">/</span><span style="color: #009900">$YOURUSERNAME</span>/erlang<span style="color: #990000">.</span>mk +$ cd erlang<span style="color: #990000">.</span>mk +$ <span style="color: #990000">.</span>/pkg_add<span style="color: #990000">.</span>sh cowboy git https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/cowboy <span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span> + http<span style="color: #990000">:</span>//ninenines<span style="color: #990000">.</span>eu <span style="color: #FF0000">"Small, fast and modular HTTP server."</span> +$ git push origin master</tt></pre></div></div> +<div class="paragraph"><p>Before sending a pull request, you should test your package. +You can use the following command: <code>make check p=PACKAGE</code>, +where <code>PACKAGE</code> is the name of the package, for example +<code>cowboy</code>.</p></div> +<div class="paragraph"><p>To test all packages, the <code>make packages</code> command can be used. +This can take a long time. Some packages will fail with certain +versions of Erlang, or if a prerequisite is missing from your system. +You can of course speed things up using the <code>-j</code> and <code>-k</code> flags.</p></div> +<div class="paragraph"><p>After all packages have been tested, you can run the command +<code>make summary</code> to know what changed since the previous run.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_documentation">Documentation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The documentation is always right.</p></div> +<div class="paragraph"><p>If you think you have found a mistake in the documentation, +this is a bug. You can either open a ticket or send a pull +request.</p></div> +<div class="paragraph"><p>To make sure that the documentation changes work, install +the listed <a href="../asciidoc">Requirements</a> on your system and +run <code>make docs</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_feature_requests">Feature requests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you have an awesome idea or need something that Erlang.mk +doesn&#8217;t provide yet, open a ticket. Provide as much detail as +possible.</p></div> +<div class="paragraph"><p>If you have code, great! Open a pull request as previously +explained.</p></div> +<div class="paragraph"><p>If not, you can still improve your feature request by writing +the related documentation.</p></div> +</div> +</div> + + + + + Cowboy Function Reference + http://ninenines.eu/docs/en/cowboy/2.0/manual/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/cowboy/2.0/manual/ + <div class="ulist"><ul> +<li> +<p> +<a href="cowboy_app">cowboy(7)</a> +</p> +</li> +<li> +<p> +<a href="cowboy">cowboy(3)</a> +</p> +</li> +<li> +<p> +<a href="cowboy_handler">cowboy_handler(3)</a> +</p> +</li> +<li> +<p> +<a href="cowboy_loop">cowboy_loop(3)</a> +</p> +</li> +<li> +<p> +<a href="cowboy_middleware">cowboy_middleware(3)</a> +</p> +</li> +<li> +<p> +<a href="cowboy_protocol">cowboy_protocol(3)</a> +</p> +</li> +<li> +<p> +<a href="cowboy_req">cowboy_req(3)</a> +</p> +</li> +<li> +<p> +<a href="cowboy_rest">cowboy_rest(3)</a> +</p> +</li> +<li> +<p> +<a href="cowboy_router">cowboy_router(3)</a> +</p> +</li> +<li> +<p> +<a href="cowboy_static">cowboy_static(3)</a> +</p> +</li> +<li> +<p> +<a href="cowboy_sub_protocol">cowboy_sub_protocol(3)</a> +</p> +</li> +<li> +<p> +<a href="cowboy_websocket">cowboy_websocket(3)</a> +</p> +</li> +<li> +<p> +<a href="http_status_codes">HTTP status codes(7)</a> +</p> +</li> +</ul></div> + + + + + Cowboy User Guide + http://ninenines.eu/docs/en/cowboy/2.0/guide/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/cowboy/2.0/guide/ + <div class="sect1"> +<h2 id="_rationale">Rationale</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="modern_web/">The modern Web</a> +</p> +</li> +<li> +<p> +<a href="erlang_web/">Erlang and the Web</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_introduction">Introduction</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="introduction/">Introduction</a> +</p> +</li> +<li> +<p> +<a href="getting_started/">Getting started</a> +</p> +</li> +<li> +<p> +<a href="overview/">Request overview</a> +</p> +</li> +<li> +<p> +<a href="erlang_beginners/">Erlang for beginners</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="routing/">routing</a> +</p> +</li> +<li> +<p> +<a href="constraints/">Constraints</a> +</p> +</li> +<li> +<p> +<a href="static_files/">Static files</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_request_and_response">Request and response</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="handlers/">Handlers</a> +</p> +</li> +<li> +<p> +<a href="loop_handlers/">Loop handlers</a> +</p> +</li> +<li> +<p> +<a href="req/">The Req object</a> +</p> +</li> +<li> +<p> +<a href="req_body/">Reading the request body</a> +</p> +</li> +<li> +<p> +<a href="resp/">Sending a response</a> +</p> +</li> +<li> +<p> +<a href="cookies/">Using cookies</a> +</p> +</li> +<li> +<p> +<a href="multipart/">Multipart</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_rest">REST</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="rest_principles/">REST principles</a> +</p> +</li> +<li> +<p> +<a href="rest_handlers/">Handling REST requests</a> +</p> +</li> +<li> +<p> +<a href="rest_flowcharts/">REST flowcharts</a> +</p> +</li> +<li> +<p> +<a href="resource_design/">Designing a resource handler</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_websocket">Websocket</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="ws_protocol/">The Websocket protocol</a> +</p> +</li> +<li> +<p> +<a href="ws_handlers/">Handling Websocket connections</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_internals">Internals</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="architecture/">Architecture</a> +</p> +</li> +<li> +<p> +<a href="broken_clients/">Dealing with broken clients</a> +</p> +</li> +<li> +<p> +<a href="middlewares/">Middlewares</a> +</p> +</li> +<li> +<p> +<a href="sub_protocols/">Sub protocols</a> +</p> +</li> +<li> +<p> +<a href="hooks/">Hooks</a> +</p> +</li> +</ul></div> +</div> +</div> + + + + + Dealing with broken clients + http://ninenines.eu/docs/en/cowboy/2.0/guide/broken_clients/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/cowboy/2.0/guide/broken_clients/ + <div class="paragraph"><p>There exists a very large number of implementations for the +HTTP protocol. Most widely used clients, like browsers, +follow the standard quite well, but others may not. In +particular custom enterprise clients tend to be very badly +written.</p></div> +<div class="paragraph"><p>Cowboy tries to follow the standard as much as possible, +but is not trying to handle every possible special cases. +Instead Cowboy focuses on the cases reported in the wild, +on the public Web.</p></div> +<div class="paragraph"><p>That means clients that ignore the HTTP standard completely +may fail to understand Cowboy&#8217;s responses. There are of +course workarounds. This chapter aims to cover them.</p></div> +<div class="sect1"> +<h2 id="_lowercase_headers">Lowercase headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy converts all headers it receives to lowercase, and +similarly sends back headers all in lowercase. Some broken +HTTP clients have issues with that.</p></div> +<div class="paragraph"><p>A simple way to solve this is to create an <code>onresponse</code> hook +that will format the header names with the expected case.</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">capitalize_hook</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-&gt;</span> + <span style="color: #009900">Headers2</span> <span style="color: #990000">=</span> [{<span style="font-weight: bold"><span style="color: #000000">cowboy_bstr:capitalize_token</span></span>(<span style="color: #009900">N</span>), <span style="color: #009900">V</span>} + || {<span style="color: #009900">N</span>, <span style="color: #009900">V</span>} <span style="color: #990000">&lt;-</span> <span style="color: #009900">Headers</span>], + <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers2</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that HTTP/2 clients do not have that particular issue +because the specification explicitly says all headers are +lowercase, unlike HTTP which allows any case but treats +them as case insensitive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_camel_case_headers">Camel-case headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Sometimes it is desirable to keep the actual case used by +clients, for example when acting as a proxy between two broken +implementations. There is no easy solution for this other than +forking the project and editing the <code>cowboy_protocol</code> file +directly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_chunked_transfer_encoding">Chunked transfer-encoding</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Sometimes an HTTP client advertises itself as HTTP/1.1 but +does not support chunked transfer-encoding. This is invalid +behavior, as HTTP/1.1 clients are required to support it.</p></div> +<div class="paragraph"><p>A simple workaround exists in these cases. By changing the +Req object response state to <code>waiting_stream</code>, Cowboy will +understand that it must use the identity transfer-encoding +when replying, just like if it was an HTTP/1.0 client.</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set</span></span>(<span style="color: #FF6600">resp_state</span>, <span style="color: #FF6600">waiting_stream</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> + + + + + Designing a resource handler + http://ninenines.eu/docs/en/cowboy/2.0/guide/resource_design/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/cowboy/2.0/guide/resource_design/ + <div class="paragraph"><p>This chapter aims to provide you with a list of questions +you must answer in order to write a good resource handler. +It is meant to be usable as a step by step guide.</p></div> +<div class="sect1"> +<h2 id="_the_service">The service</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Can the service become unavailable, and when it does, can +we detect it? For example, database connectivity problems +may be detected early. We may also have planned outages +of all or parts of the system. Implement the +<code>service_available</code> callback.</p></div> +<div class="paragraph"><p>What HTTP methods does the service implement? Do we need +more than the standard OPTIONS, HEAD, GET, PUT, POST, +PATCH and DELETE? Are we not using one of those at all? +Implement the <code>known_methods</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_type_of_resource_handler">Type of resource handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Am I writing a handler for a collection of resources, +or for a single resource?</p></div> +<div class="paragraph"><p>The semantics for each of these are quite different. +You should not mix collection and single resource in +the same handler.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_collection_handler">Collection handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Skip this section if you are not doing a collection.</p></div> +<div class="paragraph"><p>Is the collection hardcoded or dynamic? For example, +if you use the route <code>/users</code> for the collection of +users then the collection is hardcoded; if you use +<code>/forums/:category</code> for the collection of threads +then it isn&#8217;t. When the collection is hardcoded you +can safely assume the resource always exists.</p></div> +<div class="paragraph"><p>What methods should I implement?</p></div> +<div class="paragraph"><p>OPTIONS is used to get some information about the +collection. It is recommended to allow it even if you +do not implement it, as Cowboy has a default +implementation built-in.</p></div> +<div class="paragraph"><p>HEAD and GET are used to retrieve the collection. +If you allow GET, also allow HEAD as there&#8217;s no extra +work required to make it work.</p></div> +<div class="paragraph"><p>POST is used to create a new resource inside the +collection. Creating a resource by using POST on +the collection is useful when resources may be +created before knowing their URI, usually because +parts of it are generated dynamically. A common +case is some kind of auto incremented integer +identifier.</p></div> +<div class="paragraph"><p>The next methods are more rarely allowed.</p></div> +<div class="paragraph"><p>PUT is used to create a new collection (when +the collection isn&#8217;t hardcoded), or replace +the entire collection.</p></div> +<div class="paragraph"><p>DELETE is used to delete the entire collection.</p></div> +<div class="paragraph"><p>PATCH is used to modify the collection using +instructions given in the request body. A PATCH +operation is atomic. The PATCH operation may +be used for such things as reordering; adding, +modifying or deleting parts of the collection.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_single_resource_handler">Single resource handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Skip this section if you are doing a collection.</p></div> +<div class="paragraph"><p>What methods should I implement?</p></div> +<div class="paragraph"><p>OPTIONS is used to get some information about the +resource. It is recommended to allow it even if you +do not implement it, as Cowboy has a default +implementation built-in.</p></div> +<div class="paragraph"><p>HEAD and GET are used to retrieve the resource. +If you allow GET, also allow HEAD as there&#8217;s no extra +work required to make it work.</p></div> +<div class="paragraph"><p>POST is used to update the resource.</p></div> +<div class="paragraph"><p>PUT is used to create a new resource (when it doesn&#8217;t +already exist) or replace the resource.</p></div> +<div class="paragraph"><p>DELETE is used to delete the resource.</p></div> +<div class="paragraph"><p>PATCH is used to modify the resource using +instructions given in the request body. A PATCH +operation is atomic. The PATCH operation may +be used for adding, removing or modifying specific +values in the resource.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_resource">The resource</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Following the above discussion, implement the +<code>allowed_methods</code> callback.</p></div> +<div class="paragraph"><p>Does the resource always exist? If it may not, implement +the <code>resource_exists</code> callback.</p></div> +<div class="paragraph"><p>Do I need to authenticate the client before they can +access the resource? What authentication mechanisms +should I provide? This may include form-based, token-based +(in the URL or a cookie), HTTP basic, HTTP digest, +SSL certificate or any other form of authentication. +Implement the <code>is_authorized</code> callback.</p></div> +<div class="paragraph"><p>Do I need fine-grained access control? How do I determine +that they are authorized access? Handle that in your +<code>is_authorized</code> callback.</p></div> +<div class="paragraph"><p>Can access to a resource be forbidden regardless of access +being authorized? A simple example of that is censorship +of a resource. Implement the <code>forbidden</code> callback.</p></div> +<div class="paragraph"><p>Are there any constraints on the length of the resource URI? +For example, the URI may be used as a key in storage and may +have a limit in length. Implement <code>uri_too_long</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_representations">Representations</h2> +<div class="sectionbody"> +<div class="paragraph"><p>What media types do I provide? If text based, what charsets +are provided? What languages do I provide?</p></div> +<div class="paragraph"><p>Implement the mandatory <code>content_types_provided</code>. Prefix +the callbacks with <code>to_</code> for clarity. For example, <code>to_html</code> +or <code>to_text</code>.</p></div> +<div class="paragraph"><p>Implement the <code>languages_provided</code> or <code>charsets_provided</code> +callbacks if applicable.</p></div> +<div class="paragraph"><p>Is there any other header that may make the representation +of the resource vary? Implement the <code>variances</code> callback.</p></div> +<div class="paragraph"><p>Depending on your choices for caching content, you may +want to implement one or more of the <code>generate_etag</code>, +<code>last_modified</code> and <code>expires</code> callbacks.</p></div> +<div class="paragraph"><p>Do I want the user or user agent to actively choose a +representation available? Send a list of available +representations in the response body and implement +the <code>multiple_choices</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_redirections">Redirections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Do I need to keep track of what resources were deleted? +For example, you may have a mechanism where moving a +resource leaves a redirect link to its new location. +Implement the <code>previously_existed</code> callback.</p></div> +<div class="paragraph"><p>Was the resource moved, and is the move temporary? If +it is explicitly temporary, for example due to maintenance, +implement the <code>moved_temporarily</code> callback. Otherwise, +implement the <code>moved_permanently</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_request">The request</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Do we need to perform extra checks to make sure the request +is valid? Cowboy will do many checks when receiving the +request already, do we need more? Note that this only +applies to the request-line and headers of the request, +and not the body. Implement <code>malformed_request</code>.</p></div> +<div class="paragraph"><p>May there be a request body? Will I know its size? +What&#8217;s the maximum size of the request body I&#8217;m willing +to accept? Implement <code>valid_entity_length</code>.</p></div> +<div class="paragraph"><p>Finally, take a look at the sections corresponding to the +methods you are implementing.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_options_method">OPTIONS method</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy by default will send back a list of allowed methods. +Do I need to add more information to the response? Implement +the <code>options</code> method.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_get_and_head_methods">GET and HEAD methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you implement the methods GET and/or HEAD, you must +implement one <code>ProvideResource</code> callback for each +content-type returned by the <code>content_types_provided</code> +callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_put_post_and_patch_methods">PUT, POST and PATCH methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you implement the methods PUT, POST and/or PATCH, +you must implement the <code>content_types_accepted</code> callback, +and one <code>AcceptResource</code> callback for each content-type +it returns. Prefix the <code>AcceptResource</code> callback names +with <code>from_</code> for clarity. For example, <code>from_html</code> or +<code>from_json</code>.</p></div> +<div class="paragraph"><p>Do we want to allow the POST method to create individual +resources directly through their URI (like PUT)? Implement +the <code>allow_missing_post</code> callback. It is recommended to +explicitly use PUT in these cases instead.</p></div> +<div class="paragraph"><p>May there be conflicts when using PUT to create or replace +a resource? Do we want to make sure that two updates around +the same time are not cancelling one another? Implement the +<code>is_conflict</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_delete_methods">DELETE methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you implement the method DELETE, you must implement +the <code>delete_resource</code> callback.</p></div> +<div class="paragraph"><p>When <code>delete_resource</code> returns, is the resource completely +removed from the server, including from any caching service? +If not, and/or if the deletion is asynchronous and we have +no way of knowing it has been completed yet, implement the +<code>delete_completed</code> callback.</p></div> +</div> +</div> + + + + + Dialyzer + http://ninenines.eu/docs/en/erlang.mk/1/guide/dialyzer/ + Mon, 01 Jan 0001 00:00:00 +0000 + + http://ninenines.eu/docs/en/erlang.mk/1/guide/dialyzer/ + <div class="paragraph"><p>Dialyzer is a tool that will detect discrepancies in your +program. It does so using a technique known as success +typing analysis which has the advantage of providing no +false positives. Dialyzer is able to detect type errors, +dead code and more.</p></div> +<div class="paragraph"><p>Erlang.mk provides a wrapper around Dialyzer.</p></div> +<div class="sect1"> +<h2 id="_how_it_works">How it works</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Dialyzer requires a PLT file to work. The PLT file contains +the analysis information from all applications which are not +expected to change, or rarely do. These would be all the +dependencies of the application or applications you are +currently working on, including standard applications in +Erlang/OTP itself.</p></div> +<div class="paragraph"><p>Dialyzer can generate this PLT file. Erlang.mk includes rules +to automatically generate the PLT file when it is missing.</p></div> +<div class="paragraph"><p>Once the PLT file is generated, Dialyzer can perform the +analysis in record time.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In a typical usage scenario, no variable needs to be set. +The defaults should be enough. Do note however that the +dependencies need to be set properly using the <code>DEPS</code> and +<code>LOCAL_DEPS</code> variables.</p></div> +<div class="paragraph"><p>The <code>DIALYZER_PLT</code> file indicates where the PLT file will +be written to (and read from). By default this is +<em>$(PROJECT).plt</em> in the project&#8217;s directory. Note that +the <code>DIALYZER_PLT</code> variable is exported and is understood +by Dialyzer directly.</p></div> +<div class="paragraph"><p>The <code>PLT_APPS</code> variable can be used to add additional +applications to the PLT. You can either list application +names or paths to these applications.</p></div> +<div class="paragraph"><p>Erlang.mk defines two variables for specifying options +for the analysis: <code>DIALYZER_DIRS</code> and <code>DIALYZER_OPTS</code>. +The former one defines which directories should be part +of the analysis. The latter defines what extra warnings +Dialyzer should report.</p></div> +<div class="paragraph"><p>Note that Erlang.mk enables the race condition warnings +by default. As it can take considerably large resources +to run, you may want to disable it on larger projects.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To perform an analysis, run the following command:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make dialyze</tt></pre></div></div> +<div class="paragraph"><p>This will create the PLT file if it doesn&#8217;t exist.</p></div> +<div class="paragraph"><p>The analysis will also be performed when you run the +following command, alongside tests:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make check</tt></pre></div></div> +<div class="paragraph"><p>You can use the <code>plt</code> target to create the PLT file if +it doesn&#8217;t exist. This is normally not necessary as +Dialyzer creates it automatically.</p></div> +<div class="paragraph"><p>The PLT file will be removed when you run <code>make distclean</code>.</p></div> +</div> +</div> + + + + + \ No newline at end of file -- cgit v1.2.3