Docs-rsses on Nine Nines

Docs-rsses on Nine Nines https://ninenines.eu/docs/index.xml Recent content in Docs-rsses on Nine Nines Hugo -- gohugo.io en-us Cowboy Function Reference https://ninenines.eu/docs/en/cowboy/2.0/manual/ Mon, 01 Jan 0001 00:00:00 +0000 https://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_http2">cowboy_http2(3)</a> </p> </li> <li> <p> <a href="cowboy_http">cowboy_http(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_req">cowboy_req(3)</a> </p> </li> <li> <p> <a href="cowboy_req.binding">cowboy_req:binding(3)</a> </p> </li> <li> <p> <a href="cowboy_req.bindings">cowboy_req:bindings(3)</a> </p> </li> <li> <p> <a href="cowboy_req.body_length">cowboy_req:body_length(3)</a> </p> </li> <li> <p> <a href="cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a> </p> </li> <li> <p> <a href="cowboy_req.has_body">cowboy_req:has_body(3)</a> </p> </li> <li> <p> <a href="cowboy_req.has_resp_body">cowboy_req:has_resp_body(3)</a> </p> </li> <li> <p> <a href="cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a> </p> </li> <li> <p> <a href="cowboy_req.header">cowboy_req:header(3)</a> </p> </li> <li> <p> <a href="cowboy_req.headers">cowboy_req:headers(3)</a> </p> </li> <li> <p> <a href="cowboy_req.host">cowboy_req:host(3)</a> </p> </li> <li> <p> <a href="cowboy_req.host_info">cowboy_req:host_info(3)</a> </p> </li> <li> <p> <a href="cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a> </p> </li> <li> <p> <a href="cowboy_req.match_qs">cowboy_req:match_qs(3)</a> </p> </li> <li> <p> <a href="cowboy_req.method">cowboy_req:method(3)</a> </p> </li> <li> <p> <a href="cowboy_req.parse_cookies">cowboy_req:parse_cookies(3)</a> </p> </li> <li> <p> <a href="cowboy_req.parse_header">cowboy_req:parse_header(3)</a> </p> </li> <li> <p> <a href="cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a> </p> </li> <li> <p> <a href="cowboy_req.path">cowboy_req:path(3)</a> </p> </li> <li> <p> <a href="cowboy_req.path_info">cowboy_req:path_info(3)</a> </p> </li> <li> <p> <a href="cowboy_req.peer">cowboy_req:peer(3)</a> </p> </li> <li> <p> <a href="cowboy_req.port">cowboy_req:port(3)</a> </p> </li> <li> <p> <a href="cowboy_req.push">cowboy_req:push(3)</a> </p> </li> <li> <p> <a href="cowboy_req.qs">cowboy_req:qs(3)</a> </p> </li> <li> <p> <a href="cowboy_req.read_body">cowboy_req:read_body(3)</a> </p> </li> <li> <p> <a href="cowboy_req.read_part">cowboy_req:read_part(3)</a> </p> </li> <li> <p> <a href="cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a> </p> </li> <li> <p> <a href="cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a> </p> </li> <li> <p> <a href="cowboy_req.reply">cowboy_req:reply(3)</a> </p> </li> <li> <p> <a href="cowboy_req.scheme">cowboy_req:scheme(3)</a> </p> </li> <li> <p> <a href="cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a> </p> </li> <li> <p> <a href="cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> </p> </li> <li> <p> <a href="cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a> </p> </li> <li> <p> <a href="cowboy_req.stream_body">cowboy_req:stream_body(3)</a> </p> </li> <li> <p> <a href="cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a> </p> </li> <li> <p> <a href="cowboy_req.uri">cowboy_req:uri(3)</a> </p> </li> <li> <p> <a href="cowboy_req.version">cowboy_req:version(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_router.compile">cowboy_router:compile(3)</a> </p> </li> <li> <p> <a href="cowboy.set_env">cowboy:set_env(3)</a> </p> </li> <li> <p> <a href="cowboy.start_clear">cowboy:start_clear(3)</a> </p> </li> <li> <p> <a href="cowboy.start_tls">cowboy:start_tls(3)</a> </p> </li> <li> <p> <a href="cowboy_static">cowboy_static(3)</a> </p> </li> <li> <p> <a href="cowboy.stop_listener">cowboy:stop_listener(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 https://ninenines.eu/docs/en/cowboy/2.0/guide/ Mon, 01 Jan 0001 00:00:00 +0000 https://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> </ul></div> <div class="ulist"><ul> <li> <p> <a href="flow_diagram/">Flow diagram</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="listeners/">Listeners</a> </p> </li> <li> <p> <a href="streams/">Streams</a> </p> </li> <li> <p> <a href="routing/">Routing</a> </p> </li> <li> <p> <a href="constraints/">Constraints</a> </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="_handlers">Handlers</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="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="req/">Request details</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> </ul></div> <div class="ulist"><ul> <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> </ul></div> <div class="ulist"><ul> <li> <p> <a href="hooks/">Hooks</a> </p> </li> </ul></div> </div> </div> Erlang.mk User Guide https://ninenines.eu/docs/en/erlang.mk/1/guide/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/erlang.mk/1/guide/ <div class="ulist"><ul> <li> <p> <a href="installation/">Installation</a> </p> </li> <li> <p> <a href="getting_started/">Getting started</a> </p> </li> <li> <p> <a href="overview/">Overview</a> </p> </li> <li> <p> <a href="updating/">Updating Erlang.mk</a> </p> </li> <li> <p> <a href="limitations/">Limitations</a> </p> </li> </ul></div> <div class="sect1"> <h2 id="code">Code</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> <a href="app/">Building</a> </p> </li> <li> <p> <a href="deps/">Packages and dependencies</a> </p> </li> <li> <p> <a href="ports/">NIFs and port drivers</a> </p> </li> <li> <p> <a href="releases/">Releases</a> </p> </li> <li> <p> <a href="sfx/">Self-extracting releases</a> </p> </li> <li> <p> <a href="escripts/">Escripts</a> </p> </li> <li> <p> <a href="compat/">Compatibility with other build tools</a> </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="docs">Documentation</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> <a href="asciidoc/">Asciidoc documentation</a> </p> </li> <li> <p> <a href="edoc/">EDoc comments</a> </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="tests">Tests</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> <a href="shell/">Erlang shell</a> </p> </li> <li> <p> <a href="eunit/">EUnit</a> </p> </li> <li> <p> <a href="common_test/">Common Test</a> </p> </li> <li> <p> <a href="coverage/">Code coverage</a> </p> </li> <li> <p> <a href="ci/">Continuous integration</a> </p> </li> <li> <p> <a href="dialyzer/">Dialyzer</a> </p> </li> <li> <p> <a href="xref/">Xref</a> </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="plugins">Third-party plugins</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> <a href="external_plugins/">External plugins</a> </p> </li> <li> <p> <a href="external_plugins_list/">List of plugins</a> </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="about">About Erlang.mk</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> <a href="why/">Why erlang.mk?</a> </p> </li> <li> <p> <a href="history/">Short history</a> </p> </li> <li> <p> <a href="contributing/">Contributing</a> </p> </li> </ul></div> </div> </div> Gun Function Reference https://ninenines.eu/docs/en/gun/1.0/manual/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/gun/1.0/manual/ <div class="ulist"><ul> <li> <p> <a href="gun_app">gun(7)</a> </p> </li> <li> <p> <a href="gun">gun(3)</a> </p> </li> </ul></div> Gun User Guide https://ninenines.eu/docs/en/gun/1.0/guide/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/gun/1.0/guide/ <div class="ulist"><ul> <li> <p> <a href="introduction/">Introduction</a> </p> </li> <li> <p> <a href="start/">Starting and stopping</a> </p> </li> <li> <p> <a href="protocols/">Supported protocols</a> </p> </li> <li> <p> <a href="connect/">Connection</a> </p> </li> <li> <p> <a href="http/">Using HTTP</a> </p> </li> <li> <p> <a href="websocket/">Using Websocket</a> </p> </li> </ul></div> HTTP status codes(7) https://ninenines.eu/docs/en/cowboy/2.0/manual/http_status_codes/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/cowboy/2.0/manual/http_status_codes/ <div class="sect1"> <h2 id="_name">Name</h2> <div class="sectionbody"> <div class="paragraph"><p>HTTP status codes - status codes used by Cowboy</p></div> </div> </div> <div class="sect1"> <h2 id="_description">Description</h2> <div class="sectionbody"> <div class="paragraph"><p>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.</p></div> </div> </div> <div class="sect1"> <h2 id="_100_continue">100 Continue</h2> <div class="sectionbody"> <div class="paragraph"><p>When the client sends an <code>expect: 100-continue</code> 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.</p></div> </div> </div> <div class="sect1"> <h2 id="_101_switching_protocols">101 Switching Protocols</h2> <div class="sectionbody"> <div class="paragraph"><p>This is the status code sent when switching to the Websocket protocol.</p></div> </div> </div> <div class="sect1"> <h2 id="_200_ok">200 OK</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_201_created">201 Created</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_202_accepted">202 Accepted</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_204_no_content">204 No Content</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent when the processing of a request ends without any reply having been sent. It may also be sent by <code>cowboy_rest</code> under normal conditions.</p></div> </div> </div> <div class="sect1"> <h2 id="_300_multiple_choices">300 Multiple Choices</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_301_moved_permanently">301 Moved Permanently</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_303_see_other">303 See Other</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_304_not_modified">304 Not Modified</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_307_temporary_redirect">307 Temporary Redirect</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_400_bad_request">400 Bad Request</h2> <div class="sectionbody"> <div class="paragraph"><p>Cowboy will send this status code for any of the following reasons:</p></div> <div class="ulist"><ul> <li> <p> Too many empty lines were sent before the request. </p> </li> <li> <p> The request-line could not be parsed. </p> </li> <li> <p> Too many headers were sent. </p> </li> <li> <p> A header name was too long. </p> </li> <li> <p> A header value was too long. </p> </li> <li> <p> The host header was missing from an HTTP/1.1 request. </p> </li> <li> <p> The host header could not be parsed. </p> </li> <li> <p> The requested host was not found. </p> </li> <li> <p> The requested path could not be parsed. </p> </li> <li> <p> The accept header could not be parsed when using REST. </p> </li> <li> <p> REST under normal conditions. </p> </li> <li> <p> A Websocket upgrade failed. </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="_401_unauthorized">401 Unauthorized</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_403_forbidden">403 Forbidden</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_404_not_found">404 Not Found</h2> <div class="sectionbody"> <div class="paragraph"><p>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 <code>cowboy_rest</code> under normal conditions.</p></div> </div> </div> <div class="sect1"> <h2 id="_405_method_not_allowed">405 Method Not Allowed</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_406_not_acceptable">406 Not Acceptable</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_408_request_timeout">408 Request Timeout</h2> <div class="sectionbody"> <div class="paragraph"><p>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.</p></div> </div> </div> <div class="sect1"> <h2 id="_409_conflict">409 Conflict</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_410_gone">410 Gone</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_412_precondition_failed">412 Precondition Failed</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_413_request_entity_too_large">413 Request Entity Too Large</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_414_request_uri_too_long">414 Request-URI Too Long</h2> <div class="sectionbody"> <div class="paragraph"><p>Cowboy will send this status code to the client if the request-line is too long. It may also be sent by <code>cowboy_rest</code> under normal conditions.</p></div> </div> </div> <div class="sect1"> <h2 id="_415_unsupported_media_type">415 Unsupported Media Type</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_500_internal_server_error">500 Internal Server Error</h2> <div class="sectionbody"> <div class="paragraph"><p>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 <code>cowboy_rest</code> under normal conditions.</p></div> </div> </div> <div class="sect1"> <h2 id="_501_not_implemented">501 Not Implemented</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_503_service_unavailable">503 Service Unavailable</h2> <div class="sectionbody"> <div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> </div> </div> <div class="sect1"> <h2 id="_505_http_version_not_supported">505 HTTP Version Not Supported</h2> <div class="sectionbody"> <div class="paragraph"><p>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.</p></div> </div> </div> Ranch Function Reference https://ninenines.eu/docs/en/ranch/1.2/manual/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/ranch/1.2/manual/ <div class="ulist"><ul> <li> <p> <a href="ranch_app">ranch(7)</a> </p> </li> <li> <p> <a href="ranch">ranch(3)</a> </p> </li> <li> <p> <a href="ranch_protocol">ranch_protocol(3)</a> </p> </li> <li> <p> <a href="ranch_ssl">ranch_ssl(3)</a> </p> </li> <li> <p> <a href="ranch_tcp">ranch_tcp(3)</a> </p> </li> <li> <p> <a href="ranch_transport">ranch_transport(3)</a> </p> </li> </ul></div> Ranch Function Reference https://ninenines.eu/docs/en/ranch/1.3/manual/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/ranch/1.3/manual/ <div class="ulist"><ul> <li> <p> <a href="ranch_app">ranch(7)</a> </p> </li> <li> <p> <a href="ranch">ranch(3)</a> </p> </li> <li> <p> <a href="ranch_protocol">ranch_protocol(3)</a> </p> </li> <li> <p> <a href="ranch_ssl">ranch_ssl(3)</a> </p> </li> <li> <p> <a href="ranch_tcp">ranch_tcp(3)</a> </p> </li> <li> <p> <a href="ranch_transport">ranch_transport(3)</a> </p> </li> </ul></div> Ranch User Guide https://ninenines.eu/docs/en/ranch/1.2/guide/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/ranch/1.2/guide/ <div class="ulist"><ul> <li> <p> <a href="introduction/">Introduction</a> </p> </li> <li> <p> <a href="listeners/">Listeners</a> </p> </li> <li> <p> <a href="transports/">Transports</a> </p> </li> <li> <p> <a href="protocols/">Protocols</a> </p> </li> <li> <p> <a href="embedded/">Embedded mode</a> </p> </li> <li> <p> <a href="parsers/">Writing parsers</a> </p> </li> <li> <p> <a href="ssl_auth/">SSL client authentication</a> </p> </li> <li> <p> <a href="internals/">Internals</a> </p> </li> </ul></div> Ranch User Guide https://ninenines.eu/docs/en/ranch/1.3/guide/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/ranch/1.3/guide/ <div class="ulist"><ul> <li> <p> <a href="introduction/">Introduction</a> </p> </li> <li> <p> <a href="listeners/">Listeners</a> </p> </li> <li> <p> <a href="transports/">Transports</a> </p> </li> <li> <p> <a href="protocols/">Protocols</a> </p> </li> <li> <p> <a href="embedded/">Embedded mode</a> </p> </li> <li> <p> <a href="parsers/">Writing parsers</a> </p> </li> <li> <p> <a href="ssl_auth/">SSL client authentication</a> </p> </li> <li> <p> <a href="internals/">Internals</a> </p> </li> </ul></div> Request overview https://ninenines.eu/docs/en/cowboy/2.0/guide/overview/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/cowboy/2.0/guide/overview/ <div class="paragraph"><p>This chapter explains the different steps a request goes through until a response is sent, along with details of the Cowboy implementation.</p></div> <div class="sect1"> <h2 id="_request_response">Request/response</h2> <div class="sectionbody"> <div class="paragraph"><p>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.</p></div> <div class="paragraph"><p>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.</p></div> <div class="paragraph"><p>Requests take the following route in Cowboy:</p></div> <div class="imageblock"> <div class="content"> <img src="../http_req_resp.png" alt="HTTP request/response flowchart" /> </div> </div> <div class="paragraph"><p>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.</p></div> <div class="paragraph"><p>The <code>acceptor</code> is the part of the server that accepts the connection and create an Erlang process to handle it. The <code>parser</code> then starts reading from the socket and handling requests as they come until the socket is closed.</p></div> <div class="paragraph"><p>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.</p></div> <div class="paragraph"><p>When a response is sent, you can optionally modify it or act upon it by enabling the <code>onresponse</code> hook. By default the response is sent directly to the client.</p></div> </div> </div> <div class="sect1"> <h2 id="_and_then">And then?</h2> <div class="sectionbody"> <div class="paragraph"><p>Behavior depends on what protocol is in use.</p></div> <div class="paragraph"><p>HTTP/1.0 can only process one request per connection, so Cowboy will close the connection immediately after it sends the response.</p></div> <div class="paragraph"><p>HTTP/1.1 allows the client to request that the server keeps the connection alive. This mechanism is described in the next section.</p></div> <div class="paragraph"><p>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.</p></div> </div> </div> <div class="sect1"> <h2 id="_keep_alive_http_1_1">Keep-alive (HTTP/1.1)</h2> <div class="sectionbody"> <div class="paragraph"><p>With HTTP/1.1, the connection may be left open for subsequent requests to come. This mechanism is called <code>keep-alive</code>.</p></div> <div class="paragraph"><p>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.</p></div> <div class="paragraph"><p>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 <code>connection: close</code> header, it will not override it and will close the connection as soon as the reply is sent.</p></div> <div class="paragraph"><p>This snippet will force Cowboy to close the connection.</p></div> <div class="listingblock"> <div class="content"> <pre><tt><span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, [ {<span style="color: #990000"><<</span><span style="color: #FF0000">"connection"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"close"</span><span style="color: #990000">>></span>}, ], <span style="color: #990000"><<</span><span style="color: #FF0000">"Closing the socket in 3.. 2.. 1.."</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>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 <code>max_keepalive</code> configuration value when starting an HTTP listener.</p></div> <div class="listingblock"> <div class="content"> <pre><tt><span style="font-weight: bold"><span style="color: #000000">cowboy:start_http</span></span>(<span style="color: #FF6600">my_http_listener</span>, <span style="color: #993399">100</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}], [ {<span style="color: #FF6600">env</span>, [{<span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>}]}, {<span style="color: #FF6600">max_keepalive</span>, <span style="color: #993399">5</span>} ])<span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>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 <code>terminate/3</code> function can be used for this purpose.</p></div> </div> </div> <div class="sect1"> <h2 id="_pipelining_http_1_1">Pipelining (HTTP/1.1)</h2> <div class="sectionbody"> <div class="paragraph"><p>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.</p></div> <div class="paragraph"><p>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.</p></div> <div class="paragraph"><p>This is handled automatically by the server.</p></div> </div> </div> <div class="sect1"> <h2 id="_asynchronous_requests_http_2">Asynchronous requests (HTTP/2)</h2> <div class="sectionbody"> <div class="paragraph"><p>In HTTP/2, the client can send a request at any time. And the server can send a response at any time too.</p></div> <div class="paragraph"><p>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.</p></div> <div class="paragraph"><p>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.</p></div> <div class="paragraph"><p>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.</p></div> </div> </div> cowboy(3) https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy/ <div class="sect1"> <h2 id="_name">Name</h2> <div class="sectionbody"> <div class="paragraph"><p>cowboy - HTTP server</p></div> </div> </div> <div class="sect1"> <h2 id="_description">Description</h2> <div class="sectionbody"> <div class="paragraph"><p>The module <code>cowboy</code> provides convenience functions for manipulating Ranch listeners.</p></div> </div> </div> <div class="sect1"> <h2 id="_exports">Exports</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> <a href="../cowboy.start_clear">cowboy:start_clear(3)</a> - Listen for connections using plain TCP </p> </li> <li> <p> <a href="../cowboy.start_tls">cowboy:start_tls(3)</a> - Listen for connections using TLS </p> </li> <li> <p> <a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a> - Stop the given listener </p> </li> <li> <p> <a href="../cowboy.set_env">cowboy:set_env(3)</a> - Update a listener’s environment value </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="_types">Types</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_fields">fields()</h3> <div class="listingblock"> <div class="content"> <pre><tt><span style="font-weight: bold"><span style="color: #000000">fields</span></span>() <span style="color: #990000">::</span> [<span style="color: #009900">Name</span> | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>} | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Default</span>}] <span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #009900">Constraints</span> <span style="color: #990000">::</span> <span style="color: #009900">Constraint</span> | [<span style="color: #009900">Constraint</span>] <span style="color: #009900">Constraint</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_constraints:constraint</span></span>() <span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> <div class="paragraph"><p>Fields description for match operations.</p></div> <div class="paragraph"><p>This type is used in <a href="../cowboy_router">cowboy_router(3)</a> for matching bindings and in the match functions found in <a href="../cowboy_req">cowboy_req(3)</a>.</p></div> </div> <div class="sect2"> <h3 id="_http_headers">http_headers()</h3> <div class="listingblock"> <div class="content"> <pre><tt><span style="font-weight: bold"><span style="color: #000000">http_headers</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div> <div class="paragraph"><p>HTTP headers.</p></div> </div> <div class="sect2"> <h3 id="_http_status">http_status()</h3> <div class="listingblock"> <div class="content"> <pre><tt><span style="font-weight: bold"><span style="color: #000000">http_status</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> <div class="paragraph"><p>HTTP response status.</p></div> <div class="paragraph"><p>A binary status can be used to set a reason phrase. Note however that HTTP/2 only sends the status code and drops the reason phrase entirely.</p></div> </div> <div class="sect2"> <h3 id="_http_version">http_version()</h3> <div class="listingblock"> <div class="content"> <pre><tt><span style="font-weight: bold"><span style="color: #000000">http_version</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">'HTTP/2'</span> | <span style="color: #FF6600">'HTTP/1.1'</span> | <span style="color: #FF6600">'HTTP/1.0'</span></tt></pre></div></div> <div class="paragraph"><p>HTTP version.</p></div> <div class="paragraph"><p>Note that semantically, HTTP/1.1 and HTTP/2 are equivalent.</p></div> </div> <div class="sect2"> <h3 id="_opts">opts()</h3> <div class="listingblock"> <div class="content"> <pre><tt><span style="font-weight: bold"><span style="color: #000000">opts</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>()</tt></pre></div></div> <div class="paragraph"><p>Options for the HTTP/1.1, HTTP/2 and Websocket protocols.</p></div> <div class="paragraph"><p>The protocol options are in a map containing all the options for the different protocols that may be involved when connecting to the listener, including HTTP/1.1 and HTTP/2 but also subprotocols like Websocket.</p></div> <div class="paragraph"><p>The HTTP/1.1 options are documented in the <a href="../cowboy_http">cowboy_http(3)</a> manual; the HTTP/2 options in <a href="../cowboy_http2">cowboy_http2(3)</a>; and the Websocket options in <a href="../cowboy_websocket">cowboy_websocket(3)</a>.</p></div> </div> </div> </div> <div class="sect1"> <h2 id="_see_also">See also</h2> <div class="sectionbody"> <div class="paragraph"><p><a href="../cowboy_app">cowboy(7)</a>, <a href="../ranch">ranch(3)</a></p></div> </div> </div> cowboy(7) https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_app/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_app/ <div class="sect1"> <h2 id="_name">Name</h2> <div class="sectionbody"> <div class="paragraph"><p>cowboy - Small, fast, modern HTTP server for Erlang/OTP</p></div> </div> </div> <div class="sect1"> <h2 id="_description">Description</h2> <div class="sectionbody"> <div class="paragraph"><p>Cowboy is an HTTP server for Erlang/OTP with support for the HTTP/1.1, HTTP/2 and Websocket protocols.</p></div> <div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack. This includes the implementation of the HTTP RFCs but also any directly related standards, like Websocket or Server-Sent Events.</p></div> </div> </div> <div class="sect1"> <h2 id="_modules">Modules</h2> <div class="sectionbody"> <div class="paragraph"><p>Functions:</p></div> <div class="ulist"><ul> <li> <p> <a href="../cowboy">cowboy(3)</a> - Listener management </p> </li> <li> <p> <a href="../cowboy_req">cowboy_req(3)</a> - Request and response </p> </li> <li> <p> <a href="../cowboy_router">cowboy_router(3)</a> - Router </p> </li> </ul></div> <div class="paragraph"><p>Protocols:</p></div> <div class="ulist"><ul> <li> <p> <a href="../cowboy_http">cowboy_http(3)</a> - HTTP/1.1 </p> </li> <li> <p> <a href="../cowboy_http2">cowboy_http2(3)</a> - HTTP/2 </p> </li> <li> <p> <a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket </p> </li> </ul></div> <div class="paragraph"><p>Handlers:</p></div> <div class="ulist"><ul> <li> <p> <a href="../cowboy_static">cowboy_static(3)</a> - Static file handler </p> </li> </ul></div> <div class="paragraph"><p>Behaviors:</p></div> <div class="ulist"><ul> <li> <p> <a href="../cowboy_handler">cowboy_handler(3)</a> - Plain HTTP handlers </p> </li> <li> <p> <a href="../cowboy_loop">cowboy_loop(3)</a> - Loop handlers </p> </li> <li> <p> <a href="../cowboy_middleware">cowboy_middleware(3)</a> - Middlewares </p> </li> <li> <p> <a href="../cowboy_rest">cowboy_rest(3)</a> - REST handlers </p> </li> <li> <p> <a href="../cowboy_stream">cowboy_stream(3)</a> - Stream handlers </p> </li> <li> <p> <a href="../cowboy_sub_protocol">cowboy_sub_protocol(3)</a> - Sub protocols </p> </li> <li> <p> <a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket handlers </p> </li> </ul></div> <div class="paragraph"><p>Middlewares:</p></div> <div class="ulist"><ul> <li> <p> <a href="../cowboy_router">cowboy_router(3)</a> - Router middleware </p> </li> <li> <p> <a href="../cowboy_handler">cowboy_handler(3)</a> - Handler middleware </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="_dependencies">Dependencies</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> <a href="../ranch">ranch(7)</a> - Socket acceptor pool for TCP protocols </p> </li> <li> <p> <a href="../cowlib">cowlib(7)</a> - Support library for manipulating Web protocols </p> </li> <li> <p> ssl - Secure communication over sockets </p> </li> <li> <p> crypto - Crypto functions </p> </li> </ul></div> <div class="paragraph"><p>All these applications must be started before the <code>cowboy</code> application. To start Cowboy and all dependencies at once:</p></div> <div class="listingblock"> <div class="content"> <pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:ensure_all_started</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span></tt></pre></div></div> </div> </div> <div class="sect1"> <h2 id="_environment">Environment</h2> <div class="sectionbody"> <div class="paragraph"><p>The <code>cowboy</code> application does not define any application environment configuration parameters.</p></div> </div> </div> <div class="sect1"> <h2 id="_see_also">See also</h2> <div class="sectionbody"> <div class="paragraph"><p><a href="../ranch">ranch(7)</a>, <a href="../cowlib">cowlib(7)</a></p></div> </div> </div> cowboy:set_env(3) https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.set_env/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.set_env/ <div class="sect1"> <h2 id="_name">Name</h2> <div class="sectionbody"> <div class="paragraph"><p>cowboy:set_env - Update a listener’s environment value</p></div> </div> </div> <div class="sect1"> <h2 id="_description">Description</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre><tt><span style="font-weight: bold"><span style="color: #000000">set_env</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(), <span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span></tt></pre></div></div> <div class="paragraph"><p>Set or update an environment value for a previously started listener.</p></div> <div class="paragraph"><p>This is most useful for updating the routes dynamically, without having to restart the listener.</p></div> <div class="paragraph"><p>The new value will only be available to new connections. Pre-existing connections will still use the old value.</p></div> </div> </div> <div class="sect1"> <h2 id="_arguments">Arguments</h2> <div class="sectionbody"> <div class="dlist"><dl> <dt class="hdlist1"> Name </dt> <dd> <p> The name of the listener to update. </p> <div class="paragraph"><p>The name of the listener is the first argument given to the <a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, <a href="../cowboy.start_tls">cowboy:start_tls(3)</a> or <a href="../ranch.start_listener">ranch:start_listener(3)</a> function.</p></div> </dd> <dt class="hdlist1"> Key </dt> <dd> <p> The key in the environment map. Common keys include <code>dispatch</code> and <code>middlewares</code>. </p> </dd> <dt class="hdlist1"> Value </dt> <dd> <p> The new value. </p> <div class="paragraph"><p>The type of the value differs depending on the key.</p></div> </dd> </dl></div> </div> </div> <div class="sect1"> <h2 id="_return_value">Return value</h2> <div class="sectionbody"> <div class="paragraph"><p>The atom <code>ok</code> is returned on success.</p></div> <div class="paragraph"><p>An <code>exit:badarg</code> exception is thrown when the listener does not exist.</p></div> </div> </div> <div class="sect1"> <h2 id="_changelog">Changelog</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> <strong>1.0</strong>: Function introduced. </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="_examples">Examples</h2> <div class="sectionbody"> <div class="listingblock"> <div class="title">Update a listener’s routes</div> <div class="content"> <pre><tt><span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([ {<span style="color: #FF6600">'_'</span>, [ {<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">toppage_h</span>, []}, {<span style="color: #FF0000">"/ws"</span>, <span style="color: #FF6600">websocket_h</span>, []} ]} ]), <span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">example</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div> </div> </div> <div class="sect1"> <h2 id="_see_also">See also</h2> <div class="sectionbody"> <div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>, <a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, <a href="../cowboy.start_tls">cowboy:start_tls(3)</a>, <a href="../ranch.set_protocol_options">ranch:set_protocol_options(3)</a></p></div> </div> </div> cowboy:start_clear(3) https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_clear/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_clear/ <div class="sect1"> <h2 id="_name">Name</h2> <div class="sectionbody"> <div class="paragraph"><p>cowboy:start_clear - Listen for connections using plain TCP</p></div> </div> </div> <div class="sect1"> <h2 id="_description">Description</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre><tt><span style="font-weight: bold"><span style="color: #000000">start_clear</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(), <span style="color: #009900">NumAcceptors</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="color: #009900">TransportOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch_tcp:opts</span></span>(), <span style="color: #009900">ProtocolOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">opts</span></span>()) <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">ListenerPid</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">pid</span></span>()} | {<span style="color: #FF6600">error</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> <div class="paragraph"><p>Start listening for connections over a clear TCP channel.</p></div> <div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener. HTTP/2 has two methods of establishing a connection over a clear TCP channel. Both the upgrade and the prior knowledge methods are supported.</p></div> </div> </div> <div class="sect1"> <h2 id="_arguments">Arguments</h2> <div class="sectionbody"> <div class="dlist"><dl> <dt class="hdlist1"> Name </dt> <dd> <p> The listener name is used to refer to this listener in future calls, for example when stopping it or when updating the routes defined. </p> <div class="paragraph"><p>It can be any Erlang term. An atom is generally good enough, for example <code>api</code>, <code>my_app_clear</code> or <code>my_app_tls</code>.</p></div> </dd> <dt class="hdlist1"> NumAcceptors </dt> <dd> <p> The number of acceptors is the number of processes that will accept connections. Tweak this value to improve the accept rate for incoming connections. </p> <div class="paragraph"><p>The ideal value is between 10 and 100 on most systems. Larger values may have the opposite effect and reduce the accept rate. It’s generally safe to start with a value of 100 (or 10 on low memory systems). Then, when accept rates become a concern, measure the performance and update the value accordingly.</p></div> <div class="paragraph"><p>This value is unrelated to the maximum number of concurrent connections.</p></div> </dd> <dt class="hdlist1"> TransportOpts </dt> <dd> <p> The transport options are where the TCP options, including the listener’s port number, are defined. Transport options are provided as a list of keys and values, for example <code>[{port, 8080}]</code>. </p> <div class="paragraph"><p>The available options are documented in the <a href="../ranch_tcp">ranch_tcp(3)</a> manual.</p></div> </dd> <dt class="hdlist1"> ProtocolOpts </dt> <dd> <p> The protocol options are in a map containing all the options for the different protocols that may be involved when connecting to the listener, including HTTP/1.1 and HTTP/2 but also subprotocols like Websocket. </p> <div class="paragraph"><p>The HTTP/1.1 options are documented in the <a href="../cowboy_http">cowboy_http(3)</a> manual; the HTTP/2 options in <a href="../cowboy_http2">cowboy_http2(3)</a>; and the Websocket options in <a href="../cowboy_websocket">cowboy_websocket(3)</a>.</p></div> </dd> </dl></div> </div> </div> <div class="sect1"> <h2 id="_return_value">Return value</h2> <div class="sectionbody"> <div class="paragraph"><p>An ok tuple is returned on success. It contains the pid of the top-level supervisor for the listener.</p></div> <div class="paragraph"><p>An error tuple is returned on error. The error reason may be any Erlang term.</p></div> <div class="paragraph"><p>A common error is <code>eaddrinuse</code>. It indicates that the port configured for Cowboy is already in use.</p></div> </div> </div> <div class="sect1"> <h2 id="_changelog">Changelog</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> <strong>2.0</strong>: HTTP/2 support added. </p> </li> <li> <p> <strong>2.0</strong>: Function introduced. Replaces <code>cowboy:start_http/4</code>. </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="_examples">Examples</h2> <div class="sectionbody"> <div class="listingblock"> <div class="title">Start a listener</div> <div class="content"> <pre><tt><span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([ {<span style="color: #FF6600">'_'</span>, [ {<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">toppage_h</span>, []} ]} ]), {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">example</span>, <span style="color: #993399">100</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}], #{ <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>} })<span style="color: #990000">.</span></tt></pre></div></div> <div class="listingblock"> <div class="title">Start a listener on a random port</div> <div class="content"> <pre><tt><span style="color: #009900">Name</span> <span style="color: #990000">=</span> <span style="color: #FF6600">example</span>, {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #009900">Name</span>, <span style="color: #993399">100</span>, [], #{ <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>} }), <span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #009900">Name</span>)<span style="color: #990000">.</span></tt></pre></div></div> </div> </div> <div class="sect1"> <h2 id="_see_also">See also</h2> <div class="sectionbody"> <div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>, <a href="../cowboy.start_tls">cowboy:start_tls(3)</a>, <a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>, <a href="../ranch">ranch(3)</a></p></div> </div> </div>