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="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_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="https://ninenines.eu/docs">ranch(7)</a> - Socket acceptor pool for TCP protocols </p> </li> <li> <p> <a href="https://ninenines.eu/docs">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="https://ninenines.eu/docs">ranch(7)</a>, <a href="https://ninenines.eu/docs">cowlib(7)</a></p></div> </div> </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> <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="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/">Websocket handlers</a> </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="_advanced">Advanced</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> <a href="streams/">Streams</a> </p> </li> <li> <p> <a href="middlewares/">Middlewares</a> </p> </li> </ul></div> <div class="ulist"><ul> <li> <p> <a href="sub_protocols/">Sub protocols</a> </p> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="_deprecated_chapters">Deprecated chapters</h2> <div class="sectionbody"> </div> </div> <div class="sect1"> <h2 id="_about_the_deprecated_chapters">About the deprecated chapters</h2> <div class="sectionbody"> <div class="paragraph"><p>The following chapters were relevant in Cowboy 1.0. They have not been updated for Cowboy 2.0 yet. The information in these chapters may or may not be useful.</p></div> <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="hooks/">Hooks</a> </p> </li> <li> <p> <a href="overview/">Overview</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> 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(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_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> cowboy:start_tls(3) https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_tls/ Mon, 01 Jan 0001 00:00:00 +0000 https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_tls/ <div class="sect1"> <h2 id="_name">Name</h2> <div class="sectionbody"> <div class="paragraph"><p>cowboy:start_tls - Listen for connections using TLS</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_tls</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_ssl: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 secure TLS channel.</p></div> <div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener. The ALPN TLS extension must be used to initiate an HTTP/2 connection.</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. They also contain the TLS options, like the server’s certificate. Transport options are provided as a list of keys and values, for example <code>[{port, 8443}, {certfile, "path/to/cert.pem"}]</code>. </p> <div class="paragraph"><p>The available options are documented in the <a href="../ranch_ssl">ranch_ssl(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_https/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_tls</span></span>(<span style="color: #FF6600">example</span>, <span style="color: #993399">100</span>, [ {<span style="color: #FF6600">port</span>, <span style="color: #993399">8443</span>}, {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</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_tls</span></span>(<span style="color: #009900">Name</span>, <span style="color: #993399">100</span>, [ {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</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_clear">cowboy:start_clear(3)</a>, <a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>, <a href="../ranch">ranch(3)</a></p></div> </div> </div>