-
- OCaml package documentation
--
-
- tiny_httpd 0.14 -
- tiny_httpd_camlzip 0.14 -
Tiny_httpdTiny Http Server
This library implements a very simple, basic HTTP/1.1 server using blocking IOs and threads. Basic routing based on Scanf is provided for convenience, so that several handlers can be registered.
It is possible to use a thread pool, see create's argument new_thread.
The echo example (see src/examples/echo.ml) demonstrates some of the features by declaring a few endpoints, including one for uploading files:
module S = Tiny_httpd
-
-let () =
- let server = S.create () in
-
- (* say hello *)
- S.add_route_handler ~meth:`GET server
- S.Route.(exact "hello" @/ string @/ return)
- (fun name _req -> S.Response.make_string (Ok ("hello " ^name ^"!\n")));
-
- (* echo request *)
- S.add_route_handler server
- S.Route.(exact "echo" @/ return)
- (fun req -> S.Response.make_string
- (Ok (Format.asprintf "echo:@ %a@." S.Request.pp req)));
-
- (* file upload *)
- S.add_route_handler ~meth:`PUT server
- S.Route.(exact "upload" @/ string_urlencoded @/ return)
- (fun path req ->
- try
- let oc = open_out @@ "/tmp/" ^ path in
- output_string oc req.S.Request.body;
- flush oc;
- S.Response.make_string (Ok "uploaded file")
- with e ->
- S.Response.fail ~code:500 "couldn't upload file: %s"
- (Printexc.to_string e)
- );
-
- (* run the server *)
- Printf.printf "listening on http://%s:%d\n%!" (S.addr server) (S.port server);
- match S.run server with
- | Ok () -> ()
- | Error e -> raise eIt is then possible to query it using curl:
$ dune exec src/examples/echo.exe &
-listening on http://127.0.0.1:8080
-
-# the path "hello/name" greets you.
-$ curl -X GET http://localhost:8080/hello/quadrarotaphile
-hello quadrarotaphile!
-
-# the path "echo" just prints the request.
-$ curl -X GET http://localhost:8080/echo --data "howdy y'all"
-echo:
-{meth=GET;
- headers=Host: localhost:8080
- User-Agent: curl/7.66.0
- Accept: */*
- Content-Length: 10
- Content-Type: application/x-www-form-urlencoded;
- path="/echo"; body="howdy y'all"}These buffers are used to avoid allocating too many byte arrays when processing streams and parsing requests.
module Buf = Tiny_httpd_bufmodule Byte_stream = Tiny_httpd_streammodule IO = Tiny_httpd_iotype buf = Tiny_httpd_buf.ttype byte_stream = Tiny_httpd_stream.tmodule Meth = Tiny_httpd_server.MethHeaders are metadata associated with a request or response.
module Headers = Tiny_httpd_server.HeadersRequests are sent by a client, e.g. a web browser or cURL. From the point of view of the server, they're inputs.
module Request = Tiny_httpd_server.Requestmodule Response_code = Tiny_httpd_server.Response_codeResponses are what a http server, such as Tiny_httpd, send back to the client to answer a Request.t
module Response = Tiny_httpd_server.ResponseBasic type-safe routing of handlers based on URL paths. This is optional, it is possible to only define the root handler with something like Routes.
module Route = Tiny_httpd_server.RouteA middleware can be inserted in a handler to modify or observe its behavior.
module Middleware = Tiny_httpd_server.Middlewaretype t = Tiny_httpd_server.tA HTTP server. See create for more details.
val create :
- ?masksigpipe:bool ->
- ?max_connections:int ->
- ?timeout:float ->
- ?buf_size:int ->
- ?get_time_s:(unit -> float) ->
- ?new_thread:((unit -> unit) -> unit) ->
- ?addr:string ->
- ?port:int ->
- ?sock:Unix.file_descr ->
- ?middlewares:([ `Encoding | `Stage of int ] * Middleware.t) list ->
- unit ->
- tCreate a new webserver using UNIX abstractions.
The server will not do anything until run is called on it. Before starting the server, one can use add_path_handler and set_top_handler to specify how to handle incoming requests.
module type IO_BACKEND = Tiny_httpd_server.IO_BACKENDA backend that provides IO operations, network operations, etc.
val create_from :
- ?buf_size:int ->
- ?middlewares:([ `Encoding | `Stage of int ] * Middleware.t) list ->
- backend:(module IO_BACKEND) ->
- unit ->
- tCreate a new webserver using provided backend.
The server will not do anything until run is called on it. Before starting the server, one can use add_path_handler and set_top_handler to specify how to handle incoming requests.
val addr : t -> stringAddress on which the server listens.
val is_ipv6 : t -> boolis_ipv6 server returns true iff the address of the server is an IPv6 address.
val port : t -> intPort on which the server listens. Note that this might be different than the port initially given if the port was 0 (meaning that the OS picks a port for us).
val active_connections : t -> intNumber of currently active connections.
val add_decode_request_cb :
- t ->
- (unit Request.t -> (unit Request.t * (byte_stream -> byte_stream)) option) ->
- unitAdd 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 Transfer-Encoding header and returning a stream transformer that decompresses on the fly.
val add_encode_response_cb :
- t ->
- (unit Request.t -> Response.t -> Response.t option) ->
- unitAdd a callback for every request/response pair. Similarly to add_encode_response_cb 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.
val add_middleware :
- stage:[ `Encoding | `Stage of int ] ->
- t ->
- Middleware.t ->
- unitAdd a middleware to every request/response pair.
val set_top_handler : t -> (byte_stream Request.t -> Response.t) -> unitSetup a handler called by default.
This handler is called with any request not accepted by any handler installed via add_path_handler. If no top handler is installed, unhandled paths will return a 404 not found
This used to take a string Request.t but it now takes a byte_stream Request.t since 0.14 . Use Request.read_body_full to read the body into a string if needed.
val add_route_handler :
- ?accept:(unit Request.t -> (unit, Response_code.t * string) Stdlib.result) ->
- ?middlewares:Middleware.t list ->
- ?meth:Meth.t ->
- t ->
- ('a, string Request.t -> Response.t) Route.t ->
- 'a ->
- unitadd_route_handler server Route.(exact "path" @/ string @/ int @/ return) f calls f "foo" 42 request when a request with path "path/foo/42/" is received.
Note that the handlers are called in the reverse order of their addition, so the last registered handler can override previously registered ones.
val add_route_handler_stream :
- ?accept:(unit Request.t -> (unit, Response_code.t * string) Stdlib.result) ->
- ?middlewares:Middleware.t list ->
- ?meth:Meth.t ->
- t ->
- ('a, byte_stream Request.t -> Response.t) Route.t ->
- 'a ->
- unitSimilar to add_route_handler, 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 Jsonm) or into a file.
EXPERIMENTAL: this API is not stable yet.
module type SERVER_SENT_GENERATOR = Tiny_httpd_server.SERVER_SENT_GENERATORA server-side function to generate of Server-sent events.
type server_sent_generator = (module SERVER_SENT_GENERATOR)Server-sent event generator. This generates events that are forwarded to the client (e.g. the browser).
val add_route_server_sent_handler :
- ?accept:(unit Request.t -> (unit, Response_code.t * string) Stdlib.result) ->
- t ->
- ('a, string Request.t -> server_sent_generator -> unit) Route.t ->
- 'a ->
- unitAdd a handler on an endpoint, that serves server-sent events.
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 GET. This will set the header "content-type" to "text/event-stream" automatically and reply with a 200 immediately. See server_sent_generator for more details.
This handler stays on the original thread (it is synchronous).
val running : t -> boolIs the server running?
val stop : t -> unitAsk the server to stop. This might not have an immediate effect as run might currently be waiting on IO.
val run : ?after_init:(unit -> unit) -> t -> (unit, exn) Stdlib.resultRun the main loop of the server, listening on a socket described at the server's creation time, using new_thread to start a thread for each new client.
This returns Ok () if the server exits gracefully, or Error e if it exits with an error.
val run_exn : ?after_init:(unit -> unit) -> t -> unitrun_exn s is like run s but re-raises an exception if the server exits with an error.
module Util = Tiny_httpd_utilmodule Pool = Tiny_httpd_poolmodule Dir = Tiny_httpd_dirmodule Html = Tiny_httpd_htmlAlias to Tiny_httpd_html
Tiny_httpd_atomic_Tiny_httpd_bufSimple buffer.
These buffers are used to avoid allocating too many byte arrays when processing streams and parsing requests.
val size : t -> intval clear : t -> unitval create : ?size:int -> unit -> tval contents : t -> stringval clear_and_zero : t -> unitClear the buffer and zero out its storage.
val bytes_slice : t -> bytesAccess underlying slice of bytes.
val contents_and_clear : t -> stringGet contents of the buffer and clear it.
val add_char : t -> char -> unitAdd a single char.
val add_bytes : t -> bytes -> int -> int -> unitAppend given bytes slice to the buffer.
val add_string : t -> string -> unitAdd string.
val add_buffer : t -> Stdlib.Buffer.t -> unitAppend bytes from buffer.
Tiny_httpd_dir.Embedded_fsAn embedded file system, as a list of files with (relative) paths. This is useful in combination with the "tiny-httpd-mkfs" tool, which embeds the files it's given into a OCaml module.
val create : ?mtime:float -> unit -> tval add_file : ?mtime:float -> t -> path:string -> string -> unitAdd file to the virtual file system.
Tiny_httpd_dirServing static content from directories
This module provides the same functionality as the "http_of_dir" tool. It exposes a directory (and its subdirectories), with the optional ability to delete or upload files.
type dir_behavior = | IndexRedirect to index.html if present, else fails.
*)| ListsLists content of directory. Be careful of security implications.
*)| Index_or_listsRedirect to index.html if present and lists content otherwise. This is useful for tilde ("~") directories and other per-user behavior, but be mindful of security implications
*)| ForbiddenForbid access to directory. This is suited for serving assets, for example.
*)behavior of static directory.
This controls what happens when the user requests the path to a directory rather than a file.
Type used to prevent users from building a config directly. Use default_config or config instead.
type config = {mutable download : bool;Is downloading files allowed?
*)mutable dir_behavior : dir_behavior;Behavior when serving a directory and not a file
*)mutable delete : bool;Is deleting a file allowed? (with method DELETE)
*)mutable upload : bool;Is uploading a file allowed? (with method PUT)
*)mutable max_upload_size : int;_rest : hidden;Just ignore this field.
*)}configuration for static file handlers. This might get more fields over time.
val default_config : unit -> configdefault configuration:
- { download=true
- ; dir_behavior=Forbidden
- ; delete=false
- ; upload=false
- ; max_upload_size = 10 * 1024 * 1024
- }
val config :
- ?download:bool ->
- ?dir_behavior:dir_behavior ->
- ?delete:bool ->
- ?upload:bool ->
- ?max_upload_size:int ->
- unit ->
- configBuild a config from default_config.
val add_dir_path :
- config:config ->
- dir:string ->
- prefix:string ->
- Tiny_httpd_server.t ->
- unitadd_dirpath ~config ~dir ~prefix server adds route handle to the server to serve static files in dir when url starts with prefix, using the given configuration config.
module type VFS = sig ... endVirtual file system.
val vfs_of_dir : string -> (module VFS)vfs_of_dir dir makes a virtual file system that reads from the disk.
val add_vfs :
- config:config ->
- vfs:(module VFS) ->
- prefix:string ->
- Tiny_httpd_server.t ->
- unitSimilar to add_dir_path but using a virtual file system instead.
module Embedded_fs : sig ... endAn embedded file system, as a list of files with (relative) paths. This is useful in combination with the "tiny-httpd-mkfs" tool, which embeds the files it's given into a OCaml module.
Tiny_httpd_dir.VFSVirtual file system.
This is used to emulate a file system from pure OCaml functions and data, e.g. for resources bundled inside the web server.
file_exists vfs path returns true if path points to a file or directory inside vfs.
List directory. This only returns basenames, the files need to be put in the directory path using Filename.concat.
Create a file and obtain a pair write, close
val read_file_content : string -> Tiny_httpd_stream.tRead content of a file
Tiny_httpd_htmlHTML combinators.
This module provides combinators to produce html. It doesn't enforce the well-formedness of the html, unlike Tyxml, but it's simple and should be reasonably efficient.
module IO = Tiny_httpd_iomodule Out = Tiny_httpd_html_.OutOutput for HTML combinators.
type elt = Out.t -> unitA html element. It is represented by its output function, so we can directly print it.
Element with children, represented as a list.
A chunk of sub-elements, possibly empty.
Element with children, represented as a list of sub_elt to be flattened
val sub_empty : sub_eltSub-element with nothing inside. Useful in conditionals, when one decides not to emit a sub-element at all.
val txt : string -> eltEmit a string value, which will be escaped.
val txtf :
- ('a, Stdlib.Format.formatter, unit, Out.t -> unit) Stdlib.format4 ->
- 'bFormatted version of txt
val raw_html : string -> eltEmit raw HTML. Caution, this can lead to injection vulnerabilities, never use with text that comes from untrusted users.
tag "menuitem", see mdn
tag "footer", see mdn
tag "footer", see mdn
tag "menu", see mdn
tag "menu", see mdn
tag "nav", see mdn
tag "nav", see mdn
module A = Tiny_httpd_html_.AAttributes.
val to_output : ?top:bool -> elt -> IO.Output.t -> unitWrite an HTML element to this output.
val to_string : ?top:bool -> elt -> stringConvert a HTML element to a string.
val to_string_l : elt list -> stringConvert a list of HTML elements to a string. This is designed for fragments of HTML that are to be injected inside a bigger context, as it's invalid to have multiple elements at the toplevel of a HTML document.
val to_string_top : elt -> stringval to_out_channel_top : elt -> IO.Output.t -> unitWrite a toplevel element to an output channel.
val to_writer : ?top:bool -> elt -> IO.Writer.tProduce a streaming writer from this HTML element.
val to_stream : elt -> Tiny_httpd_stream.tConvert a HTML element to a stream. This might just convert it to a string first, do not assume it to be more efficient.
Tiny_httpd_html_.AAttributes.
This module contains combinator for the standard attributes. One can also just use a pair of strings.
type t = string -> attributeAttribute builder
val accept : tAttribute "accept".
val accept_charset : tAttribute "accept-charset".
val accesskey : tAttribute "accesskey".
val action : tAttribute "action".
val align : tAttribute "align".
val allow : tAttribute "allow".
val alt : tAttribute "alt".
val async : tAttribute "async".
val autocapitalize : tAttribute "autocapitalize".
val autocomplete : tAttribute "autocomplete".
val autofocus : tAttribute "autofocus".
val autoplay : tAttribute "autoplay".
val buffered : tAttribute "buffered".
val capture : tAttribute "capture".
val challenge : tAttribute "challenge".
val charset : tAttribute "charset".
val checked : tAttribute "checked".
val cite : tAttribute "cite".
val class_ : tAttribute "class".
val code : tAttribute "code".
val codebase : tAttribute "codebase".
val cols : tAttribute "cols".
val colspan : tAttribute "colspan".
val content : tAttribute "content".
val contenteditable : tAttribute "contenteditable".
Attribute "contextmenu".
val controls : tAttribute "controls".
val coords : tAttribute "coords".
val crossorigin : tAttribute "crossorigin".
val csp : tAttribute "csp".
val data : tAttribute "data".
val data_star : tAttribute "data-*".
val datetime : tAttribute "datetime".
val decoding : tAttribute "decoding".
val default : tAttribute "default".
val defer : tAttribute "defer".
val dir : tAttribute "dir".
val dirname : tAttribute "dirname".
val disabled : tAttribute "disabled".
val download : tAttribute "download".
val draggable : tAttribute "draggable".
val enctype : tAttribute "enctype".
val enterkeyhint : tAttribute "enterkeyhint".
val for_ : tAttribute "for".
val form : tAttribute "form".
val formaction : tAttribute "formaction".
val formenctype : tAttribute "formenctype".
val formmethod : tAttribute "formmethod".
val formnovalidate : tAttribute "formnovalidate".
val formtarget : tAttribute "formtarget".
val headers : tAttribute "headers".
Attribute "hidden".
val high : tAttribute "high".
val href : tAttribute "href".
val hreflang : tAttribute "hreflang".
val http_equiv : tAttribute "http-equiv".
val icon : tAttribute "icon".
val id : tAttribute "id".
val importance : tAttribute "importance".
val integrity : tAttribute "integrity".
val ismap : tAttribute "ismap".
val itemprop : tAttribute "itemprop".
val keytype : tAttribute "keytype".
val kind : tAttribute "kind".
val label : tAttribute "label".
val lang : tAttribute "lang".
val language : tAttribute "language".
val list : tAttribute "list".
val loop : tAttribute "loop".
val low : tAttribute "low".
val manifest : tAttribute "manifest".
val max : tAttribute "max".
val maxlength : tAttribute "maxlength".
val minlength : tAttribute "minlength".
val media : tAttribute "media".
val method_ : tAttribute "method".
val min : tAttribute "min".
val multiple : tAttribute "multiple".
val muted : tAttribute "muted".
val name : tAttribute "name".
val novalidate : tAttribute "novalidate".
val open_ : tAttribute "open".
val optimum : tAttribute "optimum".
val pattern : tAttribute "pattern".
val ping : tAttribute "ping".
val placeholder : tAttribute "placeholder".
val poster : tAttribute "poster".
val preload : tAttribute "preload".
val radiogroup : tAttribute "radiogroup".
val readonly : tAttribute "readonly".
val referrerpolicy : tAttribute "referrerpolicy".
val rel : tAttribute "rel".
val required : tAttribute "required".
val reversed : tAttribute "reversed".
val rows : tAttribute "rows".
val rowspan : tAttribute "rowspan".
val sandbox : tAttribute "sandbox".
val scope : tAttribute "scope".
val scoped : tAttribute "scoped".
val selected : tAttribute "selected".
val shape : tAttribute "shape".
val size : tAttribute "size".
val sizes : tAttribute "sizes".
val slot : tAttribute "slot".
val span : tAttribute "span".
val spellcheck : tAttribute "spellcheck".
val src : tAttribute "src".
val srcdoc : tAttribute "srcdoc".
val srclang : tAttribute "srclang".
val srcset : tAttribute "srcset".
val start : tAttribute "start".
val step : tAttribute "step".
val style : tAttribute "style".
val summary : tAttribute "summary".
val tabindex : tAttribute "tabindex".
val target : tAttribute "target".
val title : tAttribute "title".
val translate : tAttribute "translate".
val text : tAttribute "Text".
val type_ : tAttribute "type".
val usemap : tAttribute "usemap".
val value : tAttribute "value".
val width : tAttribute "width".
val wrap : tAttribute "wrap".
Tiny_httpd_html_.OutOutput for HTML combinators.
This output type is used to produce a string reasonably efficiently from a tree of combinators.
NOTE: this is experimental and an unstable API.
val create_of_buffer : Stdlib.Buffer.t -> tval create_of_out : Tiny_httpd_io.Output.t -> tval flush : t -> unitval add_char : t -> char -> unitval add_string : t -> string -> unitval add_format_nl : t -> unitval with_no_format_nl : t -> (unit -> 'a) -> 'aTiny_httpd_html_module Out : sig ... endOutput for HTML combinators.
type elt = Out.t -> unitA html element. It is represented by its output function, so we can directly print it.
Element with children, represented as a list.
A chunk of sub-elements, possibly empty.
Element with children, represented as a list of sub_elt to be flattened
val sub_empty : sub_eltSub-element with nothing inside. Useful in conditionals, when one decides not to emit a sub-element at all.
val txt : string -> eltEmit a string value, which will be escaped.
val txtf :
- ('a, Stdlib.Format.formatter, unit, Out.t -> unit) Stdlib.format4 ->
- 'bFormatted version of txt
val raw_html : string -> eltEmit raw HTML. Caution, this can lead to injection vulnerabilities, never use with text that comes from untrusted users.
tag "menuitem", see mdn
tag "footer", see mdn
tag "footer", see mdn
tag "menu", see mdn
tag "menu", see mdn
tag "nav", see mdn
tag "nav", see mdn
module A : sig ... endAttributes.
Tiny_httpd_io.InputInput channel (byte source)
type t = {input : bytes -> int -> int -> int;Read into the slice. Returns 0 only if the channel is closed.
close : unit -> unit;Close the input. Must be idempotent.
*)}An input channel, i.e an incoming stream of bytes.
This can be a string, an int_channel, an Unix.file_descr, a decompression wrapper around another input channel, etc.
val of_in_channel : ?close_noerr:bool -> Stdlib.in_channel -> tval of_unix_fd : ?close_noerr:bool -> Unix.file_descr -> tval input : t -> bytes -> int -> int -> intRead into the given slice.
val close : t -> unitClose the channel.
Tiny_httpd_io.OutputOutput channel (byte sink)
type t = {output_char : char -> unit;Output a single char
*)output : bytes -> int -> int -> unit;Output slice
*)flush : unit -> unit;Flush underlying buffer
*)close : unit -> unit;Close the output. Must be idempotent.
*)}An output channel, ie. a place into which we can write bytes.
This can be a Buffer.t, an out_channel, a Unix.file_descr, etc.
val of_out_channel : ?close_noerr:bool -> Stdlib.out_channel -> tof_out_channel oc wraps the channel into a Output.t.
val of_buffer : Stdlib.Buffer.t -> tof_buffer buf is an output channel that writes directly into buf. flush and close have no effect.
val output_char : t -> char -> unitOutput the buffer slice into this channel
val output : t -> bytes -> int -> int -> unitOutput the buffer slice into this channel
val output_string : t -> string -> unitval close : t -> unitClose the channel.
val flush : t -> unitFlush (ie. force write) any buffered bytes.
Tiny_httpd_io.TCP_serverA TCP server abstraction.
type t = {endpoint : unit -> string * int;Endpoint we listen on. This can only be called from within serve.
active_connections : unit -> int;Number of connections currently active
*)running : unit -> bool;Is the server currently running?
*)stop : unit -> unit;Ask the server to stop. This might not take effect immediately, and is idempotent. After this server.running() must return false.
}A running TCP server.
This contains some functions that provide information about the running server, including whether it's active (as opposed to stopped), a function to stop it, and statistics about the number of connections.
type builder = {serve : after_init:(t -> unit) -> handle:conn_handler -> unit -> unit;Blocking call to listen for incoming connections and handle them. Uses the connection handler handle to handle individual client connections in individual threads/fibers/tasks.
}A TCP server builder implementation.
Calling builder.serve ~after_init ~handle () starts a new TCP server on an unspecified endpoint (most likely coming from the function returning this builder) and returns the running server.
Tiny_httpd_io.WriterA writer abstraction.
Writer.
A writer is a push-based stream of bytes. Give it an output channel and it will write the bytes in it.
This is useful for responses: an http endpoint can return a writer as its response's body; the writer is given access to the connection to the client and can write into it as if it were a regular out_channel, including controlling calls to flush. Tiny_httpd will convert these writes into valid HTTP chunks.
val empty : tEmpty writer, will output 0 bytes.
val of_string : string -> tA writer that just emits the bytes from the given string.
Tiny_httpd_ioIO abstraction.
We abstract IO so we can support classic unix blocking IOs with threads, and modern async IO with Eio.
NOTE: experimental.
module Buf = Tiny_httpd_bufmodule Input : sig ... endInput channel (byte source)
module Output : sig ... endOutput channel (byte sink)
module Writer : sig ... endA writer abstraction.
module TCP_server : sig ... endA TCP server abstraction.
Tiny_httpd_poolResource pool.
This pool is used for buffers. It can be used for other resources but do note that it assumes resources are still reasonably cheap to produce and discard, and will never block waiting for a resource — it's not a good pool for DB connections.
val create :
- ?clear:('a -> unit) ->
- mk_item:(unit -> 'a) ->
- ?max_size:int ->
- unit ->
- 'a tCreate a new pool.
val with_resource : 'a t -> ('a -> 'b) -> 'bwith_resource pool f runs f x with x a resource; when f fails or returns, x is returned to the pool for future reuse.
Tiny_httpd_server.HeadersThe header files of a request or response.
Neither the key nor the value can contain '\r' or '\n'. See https://tools.ietf.org/html/rfc7230#section-3.2
val empty : tEmpty list of headers.
val get : ?f:(string -> string) -> string -> t -> string optionget k headers looks for the header field with key k.
set k v headers sets the key k to value v. It erases any previous entry for k
val contains : string -> t -> boolIs there a header with the given key?
val pp : Stdlib.Format.formatter -> t -> unitPretty print the headers.
Tiny_httpd_server.MethA HTTP method. For now we only handle a subset of these.
See https://tools.ietf.org/html/rfc7231#section-4
val pp : Stdlib.Format.formatter -> t -> unitval to_string : t -> stringTiny_httpd_server.Middlewaretype handler = byte_stream Request.t -> resp:(Response.t -> unit) -> unitHandlers are functions returning a response to a request. The response can be delayed, hence the use of a continuation as the resp parameter.
A middleware is a handler transformation.
It takes the existing handler h, and returns a new one which, given a query, modify it or log it before passing it to h, or fail. It can also log or modify or drop the response.
val nil : tTrivial middleware that does nothing.
Tiny_httpd_server.Requesttype 'body t = private {meth : Meth.t;HTTP method for this request.
*)host : string;client_addr : Unix.sockaddr;Client address. Available since 0.14.
*)headers : Headers.t;List of headers.
*)http_version : int * int;HTTP version. This should be either 1, 0 or 1, 1.
path : string;Full path of the requested URL.
*)path_components : string list;Components of the path of the requested URL.
*)query : (string * string) list;Query part of the requested URL.
*)body : 'body;Body of the request.
*)start_time : float;}A request with method, path, host, headers, and a body, sent by a client.
The body is polymorphic because the request goes through several transformations. First it has no body, as only the request and headers are read; then it has a stream body; then the body might be entirely read as a string via read_body_full.
val pp : Stdlib.Format.formatter -> string t -> unitPretty print the request and its body. The exact format of this printing is not specified.
val pp_ : Stdlib.Format.formatter -> _ t -> unitPretty print the request without its body. The exact format of this printing is not specified.
val get_header : ?f:(string -> string) -> _ t -> string -> string optionget_header req h looks up header h in req. It returns None if the header is not present. This is case insensitive and should be used rather than looking up h verbatim in headers.
val get_header_int : _ t -> string -> int optionSame as get_header but also performs a string to integer conversion.
set_header k v req sets k: v in the request req's headers.
Modify headers using the given function.
val host : _ t -> stringHost field of the request. It also appears in the headers.
val path : _ t -> stringRequest path.
val body : 'b t -> 'bRequest body, possibly empty.
val start_time : _ t -> floattime stamp (from Unix.gettimeofday) after parsing the first line of the request
val limit_body_size : max_size:int -> byte_stream t -> byte_stream tLimit the body size to max_size bytes, or return a 413 error.
val read_body_full :
- ?buf:Tiny_httpd_buf.t ->
- ?buf_size:int ->
- byte_stream t ->
- string tRead the whole body into a string. Potentially blocking.
Tiny_httpd_server.Responsetype body = [ | `String of string| `Stream of byte_stream| `Writer of Tiny_httpd_io.Writer.t| `Void ]Body of a response, either as a simple string, or a stream of bytes, or nothing (for server-sent events notably).
`String str replies with a body set to this string, and a known content-length.`Stream str replies with a body made from this string, using chunked encoding.`Void replies with no body.`Writer w replies with a body created by the writer w, using a chunked encoding. It is available since 0.14.type t = private {code : Response_code.t;headers : Headers.t;Headers of the reply. Some will be set by Tiny_httpd automatically.
body : body;Body of the response. Can be empty.
*)}A response to send back to a client.
val set_code : Response_code.t -> t -> tSet the response code.
val make_raw : ?headers:Headers.t -> code:Response_code.t -> string -> tMake a response from its raw components, with a string body. Use "" to not send a body at all.
val make_raw_stream :
- ?headers:Headers.t ->
- code:Response_code.t ->
- byte_stream ->
- tSame as make_raw but with a stream body. The body will be sent with the chunked transfer-encoding.
val make :
- ?headers:Headers.t ->
- ?code:int ->
- (body, Response_code.t * string) Stdlib.result ->
- tmake r turns a result into a response.
make (Ok body) replies with 200 and the body.make (Error (code,msg)) replies with the given error code and message as body.val make_string :
- ?headers:Headers.t ->
- ?code:int ->
- (string, Response_code.t * string) Stdlib.result ->
- tSame as make but with a string body.
val make_writer :
- ?headers:Headers.t ->
- ?code:int ->
- (Tiny_httpd_io.Writer.t, Response_code.t * string) Stdlib.result ->
- tSame as make but with a writer body.
val make_stream :
- ?headers:Headers.t ->
- ?code:int ->
- (byte_stream, Response_code.t * string) Stdlib.result ->
- tSame as make but with a stream body.
Make the current request fail with the given code and message. Example: fail ~code:404 "oh noes, %s not found" "waldo".
Similar to fail but raises an exception that exits the current handler. This should not be used outside of a (path) handler. Example: fail_raise ~code:404 "oh noes, %s not found" "waldo"; never_executed()
val pp : Stdlib.Format.formatter -> t -> unitPretty print the response. The exact format is not specified.
Tiny_httpd_server.Response_codeval ok : tThe code 200
val not_found : tThe code 404
val descr : t -> stringA description of some of the error codes. NOTE: this is not complete (yet).
Tiny_httpd_server.Routeval int : (int -> 'a, 'a) compMatches an integer.
val string : (string -> 'a, 'a) compMatches a string not containing '/' and binds it as is.
val string_urlencoded : (string -> 'a, 'a) compMatches a URL-encoded string, and decodes it.
val exact : string -> ('a, 'a) compexact "s" matches "s" and nothing else.
val return : ('a, 'a) tMatches the empty path.
val rest_of_path : (string -> 'a, 'a) tMatches a string, even containing '/'. This will match the entirety of the remaining route.
val rest_of_path_urlencoded : (string -> 'a, 'a) tMatches a string, even containing '/', an URL-decode it. This will match the entirety of the remaining route.
comp / route matches "foo/bar/…" iff comp matches "foo", and route matches "bar/…".
exact_path "foo/bar/..." r is equivalent to exact "foo" @/ exact "bar" @/ ... @/ r
val pp : Stdlib.Format.formatter -> (_, _) t -> unitPrint the route.
val to_string : (_, _) t -> stringPrint the route.
Tiny_httpd_serverHTTP server.
This module implements a very simple, basic HTTP/1.1 server using blocking IOs and threads.
It is possible to use a thread pool, see create's argument new_thread.
type buf = Tiny_httpd_buf.ttype byte_stream = Tiny_httpd_stream.tmodule Meth : sig ... endHeaders are metadata associated with a request or response.
module Headers : sig ... endRequests are sent by a client, e.g. a web browser or cURL. From the point of view of the server, they're inputs.
module Request : sig ... endmodule Response_code : sig ... endResponses are what a http server, such as Tiny_httpd, send back to the client to answer a Request.t
module Response : sig ... endBasic type-safe routing of handlers based on URL paths. This is optional, it is possible to only define the root handler with something like Routes.
module Route : sig ... endA middleware can be inserted in a handler to modify or observe its behavior.
module Middleware : sig ... endA HTTP server. See create for more details.
val create :
- ?masksigpipe:bool ->
- ?max_connections:int ->
- ?timeout:float ->
- ?buf_size:int ->
- ?get_time_s:(unit -> float) ->
- ?new_thread:((unit -> unit) -> unit) ->
- ?addr:string ->
- ?port:int ->
- ?sock:Unix.file_descr ->
- ?middlewares:([ `Encoding | `Stage of int ] * Middleware.t) list ->
- unit ->
- tCreate a new webserver using UNIX abstractions.
The server will not do anything until run is called on it. Before starting the server, one can use add_path_handler and set_top_handler to specify how to handle incoming requests.
module type IO_BACKEND = sig ... endA backend that provides IO operations, network operations, etc.
val create_from :
- ?buf_size:int ->
- ?middlewares:([ `Encoding | `Stage of int ] * Middleware.t) list ->
- backend:(module IO_BACKEND) ->
- unit ->
- tCreate a new webserver using provided backend.
The server will not do anything until run is called on it. Before starting the server, one can use add_path_handler and set_top_handler to specify how to handle incoming requests.
val addr : t -> stringAddress on which the server listens.
val is_ipv6 : t -> boolis_ipv6 server returns true iff the address of the server is an IPv6 address.
val port : t -> intPort on which the server listens. Note that this might be different than the port initially given if the port was 0 (meaning that the OS picks a port for us).
val active_connections : t -> intNumber of currently active connections.
val add_decode_request_cb :
- t ->
- (unit Request.t -> (unit Request.t * (byte_stream -> byte_stream)) option) ->
- unitAdd 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 Transfer-Encoding header and returning a stream transformer that decompresses on the fly.
val add_encode_response_cb :
- t ->
- (unit Request.t -> Response.t -> Response.t option) ->
- unitAdd a callback for every request/response pair. Similarly to add_encode_response_cb 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.
val add_middleware :
- stage:[ `Encoding | `Stage of int ] ->
- t ->
- Middleware.t ->
- unitAdd a middleware to every request/response pair.
val set_top_handler : t -> (byte_stream Request.t -> Response.t) -> unitSetup a handler called by default.
This handler is called with any request not accepted by any handler installed via add_path_handler. If no top handler is installed, unhandled paths will return a 404 not found
This used to take a string Request.t but it now takes a byte_stream Request.t since 0.14 . Use Request.read_body_full to read the body into a string if needed.
val add_route_handler :
- ?accept:(unit Request.t -> (unit, Response_code.t * string) Stdlib.result) ->
- ?middlewares:Middleware.t list ->
- ?meth:Meth.t ->
- t ->
- ('a, string Request.t -> Response.t) Route.t ->
- 'a ->
- unitadd_route_handler server Route.(exact "path" @/ string @/ int @/ return) f calls f "foo" 42 request when a request with path "path/foo/42/" is received.
Note that the handlers are called in the reverse order of their addition, so the last registered handler can override previously registered ones.
val add_route_handler_stream :
- ?accept:(unit Request.t -> (unit, Response_code.t * string) Stdlib.result) ->
- ?middlewares:Middleware.t list ->
- ?meth:Meth.t ->
- t ->
- ('a, byte_stream Request.t -> Response.t) Route.t ->
- 'a ->
- unitSimilar to add_route_handler, 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 Jsonm) or into a file.
EXPERIMENTAL: this API is not stable yet.
module type SERVER_SENT_GENERATOR = sig ... endA server-side function to generate of Server-sent events.
type server_sent_generator = (module SERVER_SENT_GENERATOR)Server-sent event generator. This generates events that are forwarded to the client (e.g. the browser).
val add_route_server_sent_handler :
- ?accept:(unit Request.t -> (unit, Response_code.t * string) Stdlib.result) ->
- t ->
- ('a, string Request.t -> server_sent_generator -> unit) Route.t ->
- 'a ->
- unitAdd a handler on an endpoint, that serves server-sent events.
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 GET. This will set the header "content-type" to "text/event-stream" automatically and reply with a 200 immediately. See server_sent_generator for more details.
This handler stays on the original thread (it is synchronous).
val running : t -> boolIs the server running?
val stop : t -> unitAsk the server to stop. This might not have an immediate effect as run might currently be waiting on IO.
val run : ?after_init:(unit -> unit) -> t -> (unit, exn) Stdlib.resultRun the main loop of the server, listening on a socket described at the server's creation time, using new_thread to start a thread for each new client.
This returns Ok () if the server exits gracefully, or Error e if it exits with an error.
val run_exn : ?after_init:(unit -> unit) -> t -> unitrun_exn s is like run s but re-raises an exception if the server exits with an error.
Tiny_httpd_server.IO_BACKENDA backend that provides IO operations, network operations, etc.
This is used to decouple tiny_httpd from the scheduler/IO library used to actually open a TCP server and talk to clients. The classic way is based on Unix and blocking IOs, but it's also possible to use an OCaml 5 library using effects and non blocking IOs.
val tcp_server : unit -> Tiny_httpd_io.TCP_server.builderTCP server builder, to create servers that can listen on a port and handle clients.
Tiny_httpd_server.SERVER_SENT_GENERATORA server-side function to generate of Server-sent events.
See the w3c page and this blog post.
val set_headers : Headers.t -> unitSet headers of the response. This is not mandatory but if used at all, it must be called before any call to send_event (once events are sent the response is already sent too).
Tiny_httpd_streamByte streams.
Streams are used to represent a series of bytes that can arrive progressively. For example, an uploaded file will be sent as a series of chunks.
These used to live in Tiny_httpd but are now in their own module.
type t = {mutable bs : bytes;The bytes
*)mutable off : int;mutable len : int;fill_buf : unit -> unit;See the current slice of the internal buffer as bytes, i, len, where the slice is bytes[i] .. [bytes[i+len-1]]. Can block to refill the buffer if there is currently no content. If len=0 then there is no more data.
consume : int -> unit;Consume n bytes from the buffer. This should only be called with n <= len.
close : unit -> unit;Close the stream.
*)_rest : hidden;}A buffered stream, with a view into the current buffer (or refill if empty), and a function to consume n bytes.
The point of this type is that it gives the caller access to its internal buffer (bs, with the slice off,len). This is convenient for things like line reading where one needs to peek ahead.
Some core invariant for this type of stream are:
off,len delimits a valid slice in bs (indices: off, off+1, … off+len-1)fill_buf() was just called, then either len=0 which indicates the end of stream; or len>0 and the slice contains some data.To actually move forward in the stream, you can call consume n to consume n bytes (where n <= len). If len gets to 0, calling fill_buf() is required, so it can try to obtain a new slice.
To emulate a classic OCaml reader with a read: bytes -> int -> int -> int function, the simplest is:
let read (self:t) buf offset max_len : int =
- self.fill_buf();
- let len = min max_len self.len in
- if len > 0 then (
- Bytes.blit self.bs self.off buf offset len;
- self.consume len;
- );
- lenval close : t -> unitClose stream
val empty : tStream with 0 bytes inside
val of_input : ?buf_size:int -> Tiny_httpd_io.Input.t -> tMake a buffered stream from the given channel.
val of_chan : ?buf_size:int -> Stdlib.in_channel -> tMake a buffered stream from the given channel.
val of_chan_close_noerr : ?buf_size:int -> Stdlib.in_channel -> tSame as of_chan but the close method will never fail.
val of_fd : ?buf_size:int -> Unix.file_descr -> tMake a buffered stream from the given file descriptor.
val of_fd_close_noerr : ?buf_size:int -> Unix.file_descr -> tSame as of_fd but the close method will never fail.
val of_bytes : ?i:int -> ?len:int -> bytes -> tA stream that just returns the slice of bytes starting from i and of length len.
val of_string : string -> tval iter : (bytes -> int -> int -> unit) -> t -> unitIterate on the chunks of the stream
val to_chan : Stdlib.out_channel -> t -> unitWrite the stream to the channel.
val to_chan' : Tiny_httpd_io.Output.t -> t -> unitWrite to the IO channel.
val to_writer : t -> Tiny_httpd_io.Writer.tTurn this stream into a writer.
val make :
- ?bs:bytes ->
- ?close:(t -> unit) ->
- consume:(t -> int -> unit) ->
- fill:(t -> unit) ->
- unit ->
- tmake ~fill () creates a byte stream.
val with_file : ?buf_size:int -> string -> (t -> 'a) -> 'aOpen a file with given name, and obtain an input stream on its content. When the function returns, the stream (and file) are closed.
val read_line : ?buf:Tiny_httpd_buf.t -> t -> stringRead a line from the stream.
val read_all : ?buf:Tiny_httpd_buf.t -> t -> stringRead the whole stream into a string.
val read_chunked : ?buf:Tiny_httpd_buf.t -> fail:(string -> exn) -> t -> tConvert a stream into a stream of byte chunks using the chunked encoding. The size of chunks is not specified.
read_exactly ~size bs returns a new stream that reads exactly size bytes from bs, and then closes.
val output_chunked : ?buf:Tiny_httpd_buf.t -> Stdlib.out_channel -> t -> unitWrite the stream into the channel, using the chunked encoding.
val output_chunked' :
- ?buf:Tiny_httpd_buf.t ->
- Tiny_httpd_io.Output.t ->
- t ->
- unitWrite the stream into the channel, using the chunked encoding.
Tiny_httpd_utilEncode the string into a valid path following https://tools.ietf.org/html/rfc3986#section-2.1
Inverse operation of percent_encode. Can fail since some strings are not valid percent encodings.
This library exposes the following toplevel modules:
Tiny_httpd Tiny Http ServerTiny_httpd_atomic_ Tiny_httpd_buf Simple buffer.Tiny_httpd_dir Serving static content from directoriesTiny_httpd_html HTML combinators.Tiny_httpd_html_ Tiny_httpd_io IO abstraction.Tiny_httpd_pool Resource pool.Tiny_httpd_server HTTP server.Tiny_httpd_stream Byte streams.Tiny_httpd_util Tiny_httpd_camlzipMiddleware for compression.
This uses camlzip to provide deflate compression/decompression. If installed, the middleware will compress responses' bodies when they are streams or fixed-size above a given limit (but it will not compress small, fixed-size bodies).
val middleware :
- ?compress_above:int ->
- ?buf_size:int ->
- unit ->
- Tiny_httpd_server.Middleware.tMiddleware responsible for deflate compression/decompression.
val setup : ?compress_above:int -> ?buf_size:int -> Tiny_httpd_server.t -> unitInstall middleware for tiny_httpd to be able to encode/decode compressed streams
The entry point of this library is the module: Tiny_httpd_camlzip.