mirror of
https://github.com/c-cube/tiny_httpd.git
synced 2025-12-06 11:15:35 -05:00
47 lines
No EOL
24 KiB
HTML
47 lines
No EOL
24 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Tiny_httpd_server (tiny_httpd.Tiny_httpd_server)</title><link rel="stylesheet" href="../../odoc.css"/><meta charset="utf-8"/><meta name="generator" content="odoc 2.1.1"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../index.html">tiny_httpd</a> » Tiny_httpd_server</nav><header class="odoc-preamble"><h1>Module <code><span>Tiny_httpd_server</span></code></h1><p>HTTP server.</p><p>This module implements a very simple, basic HTTP/1.1 server using blocking IOs and threads.</p><p>It is possible to use a thread pool, see <a href="#val-create"><code>create</code></a>'s argument <code>new_thread</code>.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> NEXT_RELEASE</li></ul></header><nav class="odoc-toc"><ul><li><a href="#methods">Methods</a></li><li><a href="#headers">Headers</a></li><li><a href="#requests">Requests</a></li><li><a href="#response-codes">Response Codes</a></li><li><a href="#responses">Responses</a></li><li><a href="#main-server-type">Main Server type</a></li><li><a href="#request-handlers">Request handlers</a></li><li><a href="#server-sent-events">Server-sent events</a></li><li><a href="#run-the-server">Run the server</a></li></ul></nav><div class="odoc-content"><div class="odoc-spec"><div class="spec type" id="type-buf" class="anchored"><a href="#type-buf" class="anchor"></a><code><span><span class="keyword">type</span> buf</span><span> = <a href="../Tiny_httpd_buf/index.html#type-t">Tiny_httpd_buf.t</a></span></code></div></div><div class="odoc-spec"><div class="spec type" id="type-byte_stream" class="anchored"><a href="#type-byte_stream" class="anchor"></a><code><span><span class="keyword">type</span> byte_stream</span><span> = <a href="../Tiny_httpd_stream/index.html#type-t">Tiny_httpd_stream.t</a></span></code></div></div><h3 id="methods"><a href="#methods" class="anchor"></a>Methods</h3><div class="odoc-spec"><div class="spec module" id="module-Meth" class="anchored"><a href="#module-Meth" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Meth/index.html">Meth</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h3 id="headers"><a href="#headers" class="anchor"></a>Headers</h3><p>Headers are metadata associated with a request or response.</p><div class="odoc-spec"><div class="spec module" id="module-Headers" class="anchored"><a href="#module-Headers" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Headers/index.html">Headers</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h3 id="requests"><a href="#requests" class="anchor"></a>Requests</h3><p>Requests are sent by a client, e.g. a web browser or cURL.</p><div class="odoc-spec"><div class="spec module" id="module-Request" class="anchored"><a href="#module-Request" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Request/index.html">Request</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h3 id="response-codes"><a href="#response-codes" class="anchor"></a>Response Codes</h3><div class="odoc-spec"><div class="spec module" id="module-Response_code" class="anchored"><a href="#module-Response_code" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Response_code/index.html">Response_code</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h3 id="responses"><a href="#responses" class="anchor"></a>Responses</h3><p>Responses are what a http server, such as <a href="../Tiny_httpd/index.html"><code>Tiny_httpd</code></a>, send back to the client to answer a <a href="Request/index.html#type-t"><code>Request.t</code></a></p><div class="odoc-spec"><div class="spec module" id="module-Response" class="anchored"><a href="#module-Response" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Response/index.html">Response</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-spec"><div class="spec module" id="module-Route" class="anchored"><a href="#module-Route" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Route/index.html">Route</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-spec"><div class="spec module" id="module-Middleware" class="anchored"><a href="#module-Middleware" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Middleware/index.html">Middleware</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h3 id="main-server-type"><a href="#main-server-type" class="anchor"></a>Main Server type</h3><div class="odoc-spec"><div class="spec type" id="type-t" class="anchored"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span></code></div><div class="spec-doc"><p>A HTTP server. See <a href="#val-create"><code>create</code></a> for more details.</p></div></div><div class="odoc-spec"><div class="spec value" id="val-create" class="anchored"><a href="#val-create" class="anchor"></a><code><span><span class="keyword">val</span> create :
|
||
<span>?masksigpipe:bool <span class="arrow">-></span></span>
|
||
<span>?max_connections:int <span class="arrow">-></span></span>
|
||
<span>?timeout:float <span class="arrow">-></span></span>
|
||
<span>?buf_size:int <span class="arrow">-></span></span>
|
||
<span>?get_time_s:<span>( <span>unit <span class="arrow">-></span></span> float )</span> <span class="arrow">-></span></span>
|
||
<span>?new_thread:<span>( <span><span>( <span>unit <span class="arrow">-></span></span> unit )</span> <span class="arrow">-></span></span> unit )</span> <span class="arrow">-></span></span>
|
||
<span>?addr:string <span class="arrow">-></span></span>
|
||
<span>?port:int <span class="arrow">-></span></span>
|
||
<span>?sock:<span class="xref-unresolved">Unix</span>.file_descr <span class="arrow">-></span></span>
|
||
<span>?middlewares:<span><span>(<span>[ `Encoding <span><span>| `Stage</span> of int</span> ]</span> * <a href="Middleware/index.html#type-t">Middleware.t</a>)</span> list</span> <span class="arrow">-></span></span>
|
||
<span>unit <span class="arrow">-></span></span>
|
||
<a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Create a new webserver.</p><p>The server will not do anything until <a href="#val-run"><code>run</code></a> is called on it. Before starting the server, one can use <code>add_path_handler</code> and <a href="#val-set_top_handler"><code>set_top_handler</code></a> to specify how to handle incoming requests.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">masksigpipe</span> <p>if true, block the signal <code>Sys</code>.sigpipe which otherwise tends to kill client threads when they try to write on broken sockets. Default: <code>true</code>.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">buf_size</span> <p>size for buffers (since 0.11)</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">new_thread</span> <p>a function used to spawn a new thread to handle a new client connection. By default it is <code>Thread</code>.create but one could use a thread pool instead.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">middlewares</span> <p>see <code>add_middleware</code> for more details.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">max_connections</span> <p>maximum number of simultaneous connections.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">timeout</span> <p>connection is closed if the socket does not do read or write for the amount of second. Default: 0.0 which means no timeout. timeout is not recommended when using proxy.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">addr</span> <p>address (IPv4 or IPv6) to listen on. Default <code>"127.0.0.1"</code>.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">port</span> <p>to listen on. Default <code>8080</code>.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">sock</span> <p>an existing socket given to the server to listen on, e.g. by systemd on Linux (or launchd on macOS). If passed in, this socket will be used instead of the <code>addr</code> and <code>port</code>. If not passed in, those will be used. This parameter exists since 0.10.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">get_time_s</span> <p>obtain the current timestamp in seconds. This parameter exists since 0.11.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value" id="val-addr" class="anchored"><a href="#val-addr" class="anchor"></a><code><span><span class="keyword">val</span> addr : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p>Address on which the server listens.</p></div></div><div class="odoc-spec"><div class="spec value" id="val-is_ipv6" class="anchored"><a href="#val-is_ipv6" class="anchor"></a><code><span><span class="keyword">val</span> is_ipv6 : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>is_ipv6 server</code> returns <code>true</code> iff the address of the server is an IPv6 address.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.3</li></ul></div></div><div class="odoc-spec"><div class="spec value" id="val-port" class="anchored"><a href="#val-port" class="anchor"></a><code><span><span class="keyword">val</span> port : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p>Port on which the server listens.</p></div></div><div class="odoc-spec"><div class="spec value" id="val-active_connections" class="anchored"><a href="#val-active_connections" class="anchor"></a><code><span><span class="keyword">val</span> active_connections : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p>Number of active connections</p></div></div><div class="odoc-spec"><div class="spec value" id="val-add_decode_request_cb" class="anchored"><a href="#val-add_decode_request_cb" class="anchor"></a><code><span><span class="keyword">val</span> add_decode_request_cb :
|
||
<span><a href="#type-t">t</a> <span class="arrow">-></span></span>
|
||
<span><span>( <span><span>unit <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span>(<span>unit <a href="Request/index.html#type-t">Request.t</a></span> * <span>( <span><a href="#type-byte_stream">byte_stream</a> <span class="arrow">-></span></span> <a href="#type-byte_stream">byte_stream</a> )</span>)</span> option</span> )</span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p>Add a callback for every request. The callback can provide a stream transformer and a new request (with modified headers, typically). A possible use is to handle decompression by looking for a <code>Transfer-Encoding</code> header and returning a stream transformer that decompresses on the fly.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>use <code>add_middleware</code> instead</p></li></ul></div></div><div class="odoc-spec"><div class="spec value" id="val-add_encode_response_cb" class="anchored"><a href="#val-add_encode_response_cb" class="anchor"></a><code><span><span class="keyword">val</span> add_encode_response_cb :
|
||
<span><a href="#type-t">t</a> <span class="arrow">-></span></span>
|
||
<span><span>( <span><span>unit <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">-></span></span> <span><a href="Response/index.html#type-t">Response.t</a> <span class="arrow">-></span></span> <span><a href="Response/index.html#type-t">Response.t</a> option</span> )</span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p>Add a callback for every request/response pair. Similarly to <a href="#val-add_encode_response_cb"><code>add_encode_response_cb</code></a> the callback can return a new response, for example to compress it. The callback is given the query with only its headers, as well as the current response.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>use <code>add_middleware</code> instead</p></li></ul></div></div><div class="odoc-spec"><div class="spec value" id="val-add_middleware" class="anchored"><a href="#val-add_middleware" class="anchor"></a><code><span><span class="keyword">val</span> add_middleware :
|
||
<span>stage:<span>[ `Encoding <span><span>| `Stage</span> of int</span> ]</span> <span class="arrow">-></span></span>
|
||
<span><a href="#type-t">t</a> <span class="arrow">-></span></span>
|
||
<span><a href="Middleware/index.html#type-t">Middleware.t</a> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p>Add a middleware to every request/response pair.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">stage</span> <p>specify when middleware applies. Encoding comes first (outermost layer), then stages in increasing order.</p></li></ul><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <span class="value">Invalid_argument</span> <p>if stage is <code>`Stage n</code> where <code>n < 1</code></p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.11</li></ul></div></div><h3 id="request-handlers"><a href="#request-handlers" class="anchor"></a>Request handlers</h3><div class="odoc-spec"><div class="spec value" id="val-set_top_handler" class="anchored"><a href="#val-set_top_handler" class="anchor"></a><code><span><span class="keyword">val</span> set_top_handler : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><span>( <span><span>string <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">-></span></span> <a href="Response/index.html#type-t">Response.t</a> )</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Setup a handler called by default.</p><p>This handler is called with any request not accepted by any handler installed via <code>add_path_handler</code>. If no top handler is installed, unhandled paths will return a <code>404</code> not found.</p></div></div><div class="odoc-spec"><div class="spec value" id="val-add_route_handler" class="anchored"><a href="#val-add_route_handler" class="anchor"></a><code><span><span class="keyword">val</span> add_route_handler :
|
||
<span>?accept:
|
||
<span>( <span><span>unit <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">-></span></span> <span><span>( unit, <a href="Response_code/index.html#type-t">Response_code.t</a> * string )</span> <span class="xref-unresolved">Stdlib</span>.result</span> )</span> <span class="arrow">-></span></span>
|
||
<span>?middlewares:<span><a href="Middleware/index.html#type-t">Middleware.t</a> list</span> <span class="arrow">-></span></span>
|
||
<span>?meth:<a href="Meth/index.html#type-t">Meth.t</a> <span class="arrow">-></span></span>
|
||
<span><a href="#type-t">t</a> <span class="arrow">-></span></span>
|
||
<span><span><span>( <span class="type-var">'a</span>, <span><span>string <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">-></span></span> <a href="Response/index.html#type-t">Response.t</a> )</span> <a href="Route/index.html#type-t">Route.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p><code>add_route_handler server Route.(exact "path" @/ string @/ int @/ return) f</code> calls <code>f "foo" 42 request</code> when a <code>request</code> with path "path/foo/42/" is received.</p><p>Note that the handlers are called in the reverse order of their addition, so the last registered handler can override previously registered ones.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">meth</span> <p>if provided, only accept requests with the given method. Typically one could react to <code>`GET</code> or <code>`PUT</code>.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">accept</span> <p>should return <code>Ok()</code> if the given request (before its body is read) should be accepted, <code>Error (code,message)</code> if it's to be rejected (e.g. because its content is too big, or for some permission error). See the <code>http_of_dir</code> program for an example of how to use <code>accept</code> to filter uploads that are too large before the upload even starts. The default always returns <code>Ok()</code>, i.e. it accepts all requests.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.6</li></ul></div></div><div class="odoc-spec"><div class="spec value" id="val-add_route_handler_stream" class="anchored"><a href="#val-add_route_handler_stream" class="anchor"></a><code><span><span class="keyword">val</span> add_route_handler_stream :
|
||
<span>?accept:
|
||
<span>( <span><span>unit <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">-></span></span> <span><span>( unit, <a href="Response_code/index.html#type-t">Response_code.t</a> * string )</span> <span class="xref-unresolved">Stdlib</span>.result</span> )</span> <span class="arrow">-></span></span>
|
||
<span>?middlewares:<span><a href="Middleware/index.html#type-t">Middleware.t</a> list</span> <span class="arrow">-></span></span>
|
||
<span>?meth:<a href="Meth/index.html#type-t">Meth.t</a> <span class="arrow">-></span></span>
|
||
<span><a href="#type-t">t</a> <span class="arrow">-></span></span>
|
||
<span><span><span>( <span class="type-var">'a</span>, <span><span><a href="#type-byte_stream">byte_stream</a> <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">-></span></span> <a href="Response/index.html#type-t">Response.t</a> )</span> <a href="Route/index.html#type-t">Route.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p>Similar to <a href="#val-add_route_handler"><code>add_route_handler</code></a>, but where the body of the request is a stream of bytes that has not been read yet. This is useful when one wants to stream the body directly into a parser, json decoder (such as <code>Jsonm</code>) or into a file.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.6</li></ul></div></div><h3 id="server-sent-events"><a href="#server-sent-events" class="anchor"></a>Server-sent events</h3><p><b>EXPERIMENTAL</b>: this API is not stable yet.</p><div class="odoc-spec"><div class="spec module-type" id="module-type-SERVER_SENT_GENERATOR" class="anchored"><a href="#module-type-SERVER_SENT_GENERATOR" class="anchor"></a><code><span><span class="keyword">module</span> <span class="keyword">type</span> <a href="module-type-SERVER_SENT_GENERATOR/index.html">SERVER_SENT_GENERATOR</a></span><span> = <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>A server-side function to generate of Server-sent events.</p></div></div><div class="odoc-spec"><div class="spec type" id="type-server_sent_generator" class="anchored"><a href="#type-server_sent_generator" class="anchor"></a><code><span><span class="keyword">type</span> server_sent_generator</span><span> = <span>(<span class="keyword">module</span> <a href="module-type-SERVER_SENT_GENERATOR/index.html">SERVER_SENT_GENERATOR</a>)</span></span></code></div><div class="spec-doc"><p>Server-sent event generator</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.9</li></ul></div></div><div class="odoc-spec"><div class="spec value" id="val-add_route_server_sent_handler" class="anchored"><a href="#val-add_route_server_sent_handler" class="anchor"></a><code><span><span class="keyword">val</span> add_route_server_sent_handler :
|
||
<span>?accept:
|
||
<span>( <span><span>unit <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">-></span></span> <span><span>( unit, <a href="Response_code/index.html#type-t">Response_code.t</a> * string )</span> <span class="xref-unresolved">Stdlib</span>.result</span> )</span> <span class="arrow">-></span></span>
|
||
<span><a href="#type-t">t</a> <span class="arrow">-></span></span>
|
||
<span><span><span>( <span class="type-var">'a</span>, <span><span>string <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">-></span></span> <span><a href="#type-server_sent_generator">server_sent_generator</a> <span class="arrow">-></span></span> unit )</span> <a href="Route/index.html#type-t">Route.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p>Add a handler on an endpoint, that serves server-sent events.</p><p>The callback is given a generator that can be used to send events as it pleases. The connection is always closed by the client, and the accepted method is always <code>GET</code>. This will set the header "content-type" to "text/event-stream" automatically and reply with a 200 immediately. See <a href="#type-server_sent_generator"><code>server_sent_generator</code></a> for more details.</p><p>This handler stays on the original thread (it is synchronous).</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.9</li></ul></div></div><h3 id="run-the-server"><a href="#run-the-server" class="anchor"></a>Run the server</h3><div class="odoc-spec"><div class="spec value" id="val-stop" class="anchored"><a href="#val-stop" class="anchor"></a><code><span><span class="keyword">val</span> stop : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Ask the server to stop. This might not have an immediate effect as <a href="#val-run"><code>run</code></a> might currently be waiting on IO.</p></div></div><div class="odoc-spec"><div class="spec value" id="val-run" class="anchored"><a href="#val-run" class="anchor"></a><code><span><span class="keyword">val</span> run : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><span>( unit, exn )</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div><div class="spec-doc"><p>Run the main loop of the server, listening on a socket described at the server's creation time, using <code>new_thread</code> to start a thread for each new client.</p><p>This returns <code>Ok ()</code> if the server exits gracefully, or <code>Error e</code> if it exits with an error.</p></div></div></div></body></html> |