li {
- margin-left: 22px;
-}
-
-ol>li {
- margin-left: 27.2px;
-}
-
-li>*:first-child {
- margin-top: 0
-}
-
-/* Text alignements, this should be forbidden. */
-
-.left {
- text-align: left;
-}
-
-.right {
- text-align: right;
-}
-
-.center {
- text-align: center;
-}
-
-/* Links and anchors */
-
-a {
- text-decoration: none;
- color: var(--link-color);
-}
-
-a:hover {
- box-shadow: 0 1px 0 0 var(--link-color);
-}
-
-/* Linked highlight */
-*:target {
- background-color: var(--target-background) !important;
- box-shadow: 0 0px 0 1px var(--target-shadow) !important;
- border-radius: 1px;
-}
-
-*:hover > a.anchor {
- visibility: visible;
-}
-
-a.anchor:before {
- content: "#";
-}
-
-a.anchor:hover {
- box-shadow: none;
- text-decoration: none;
- color: var(--anchor-hover);
-}
-
-a.anchor {
- visibility: hidden;
- position: absolute;
- /* top: 0px; */
- /* margin-left: -3ex; */
- margin-left: -1.3em;
- font-weight: normal;
- font-style: normal;
- padding-right: 0.4em;
- padding-left: 0.4em;
- /* To remain selectable */
- color: var(--anchor-color);
-}
-
-.spec > a.anchor {
- margin-left: -2.3em;
- padding-right: 0.9em;
-}
-
-.xref-unresolved {
- color: #2C94BD;
-}
-.xref-unresolved:hover {
- box-shadow: 0 1px 0 0 var(--xref-shadow);
-}
-
-/* Section and document divisions.
- Until at least 4.03 many of the modules of the stdlib start at .h7,
- we restart the sequence there like h2 */
-
-h1, h2, h3, h4, h5, h6, .h7, .h8, .h9, .h10 {
- font-family: "Fira Sans", Helvetica, Arial, sans-serif;
- font-weight: 400;
- padding-top: 0.1em;
- line-height: 1.2;
- overflow-wrap: break-word;
-}
-
-h1 {
- font-weight: 500;
- font-size: 2.441em;
-}
-
-h1 {
- font-weight: 500;
- font-size: 1.953em;
- box-shadow: 0 1px 0 0 var(--header-shadow);
-}
-
-h2 {
- font-size: 1.563em;
-}
-
-h3 {
- font-size: 1.25em;
-}
-
-small, .font_small {
- font-size: 0.8em;
-}
-
-h1 code, h1 tt {
- font-size: inherit;
- font-weight: inherit;
-}
-
-h2 code, h2 tt {
- font-size: inherit;
- font-weight: inherit;
-}
-
-h3 code, h3 tt {
- font-size: inherit;
- font-weight: inherit;
-}
-
-h3 code, h3 tt {
- font-size: inherit;
- font-weight: inherit;
-}
-
-h4 {
- font-size: 1.12em;
-}
-
-/* Comment delimiters, hidden but accessible to screen readers and
- selected for copy/pasting */
-
-/* Taken from bootstrap */
-/* See also https://stackoverflow.com/a/27769435/4220738 */
-.comment-delim {
- position: absolute;
- width: 1px;
- height: 1px;
- padding: 0;
- margin: -1px;
- overflow: hidden;
- clip: rect(0, 0, 0, 0);
- white-space: nowrap;
- border: 0;
-}
-
-/* Preformatted and code */
-
-tt, code, pre {
- font-family: "Fira Mono", courier;
- font-weight: 400;
-}
-
-pre {
- padding: 0.1em;
- border: 1px solid var(--pre-border-color);
- border-radius: 5px;
- overflow-x: auto;
-}
-
-p code,
-li code {
- background-color: var(--li-code-background);
- color: var(--li-code-color);
- border-radius: 3px;
- padding: 0 0.3ex;
-}
-
-p a > code {
- color: var(--link-color);
-}
-
-code {
- white-space: pre-wrap;
-}
-
-/* Code blocks (e.g. Examples) */
-
-pre code {
- font-size: 0.893rem;
-}
-
-/* Code lexemes */
-
-.keyword {
- font-weight: 500;
-}
-
-.arrow { white-space: nowrap }
-
-/* Module member specification */
-
-.spec {
- background-color: var(--spec-summary-background);
- border-radius: 3px;
- border-left: 4px solid var(--spec-summary-border-color);
- border-right: 5px solid transparent;
- padding: 0.35em 0.5em;
-}
-
-li:not(:last-child) > .def-doc {
- margin-bottom: 15px;
-}
-
-/* Spacing between items */
-div.odoc-spec,.odoc-include {
- margin-bottom: 2em;
-}
-
-.spec.type .variant p, .spec.type .record p {
- margin: 5px;
-}
-
-.spec.type .variant, .spec.type .record {
- margin-left: 2ch;
- list-style: none;
- display: flex;
- flex-wrap: wrap;
- row-gap: 4px;
-}
-
-.spec.type .record > code, .spec.type .variant > code {
- min-width: 40%;
-}
-
-.spec.type > ol {
- margin-top: 0;
- margin-bottom: 0;
-}
-
-.spec.type .record > .def-doc, .spec.type .variant > .def-doc {
- min-width:50%;
- padding: 0.25em 0.5em;
- margin-left: 10%;
- border-radius: 3px;
- flex-grow:1;
- background: var(--main-background);
- box-shadow: 2px 2px 4px lightgrey;
-}
-
-div.def {
- margin-top: 0;
- text-indent: -2ex;
- padding-left: 2ex;
-}
-
-div.def-doc>*:first-child {
- margin-top: 0;
-}
-
-/* Collapsible inlined include and module */
-
-.odoc-include details {
- position: relative;
-}
-
-.odoc-include.shadowed-include {
- display: none;
-}
-
-.odoc-include details:after {
- z-index: -100;
- display: block;
- content: " ";
- position: absolute;
- border-radius: 0 1ex 1ex 0;
- right: -20px;
- top: 1px;
- bottom: 1px;
- width: 15px;
- background: var(--spec-details-after-background, rgba(0, 4, 15, 0.05));
- box-shadow: 0 0px 0 1px var(--spec-details-after-shadow, rgba(204, 204, 204, 0.53));
-}
-
-.odoc-include summary {
- position: relative;
- margin-bottom: 1em;
- cursor: pointer;
- outline: none;
-}
-
-.odoc-include summary:hover {
- background-color: var(--spec-summary-hover-background);
-}
-
-/* FIXME: Does not work in Firefox. */
-.odoc-include summary::-webkit-details-marker {
- color: #888;
- transform: scaleX(-1);
- position: absolute;
- top: calc(50% - 5px);
- height: 11px;
- right: -29px;
-}
-
-/* Records and variants FIXME */
-
-div.def table {
- text-indent: 0em;
- padding: 0;
- margin-left: -2ex;
-}
-
-td.def {
- padding-left: 2ex;
-}
-
-td.def-doc *:first-child {
- margin-top: 0em;
-}
-
-/* Lists of @tags */
-
-.at-tags { list-style-type: none; margin-left: -3ex; }
-.at-tags li { padding-left: 3ex; text-indent: -3ex; }
-.at-tags .at-tag { text-transform: capitalize }
-
-/* Lists of modules */
-
-.modules { list-style-type: none; margin-left: -3ex; }
-.modules li { padding-left: 3ex; text-indent: -3ex; margin-top: 5px }
-.modules .synopsis { padding-left: 1ch; }
-
-/* Odig package index */
-
-.packages { list-style-type: none; margin-left: -3ex; }
-.packages li { padding-left: 3ex; text-indent: -3ex }
-.packages li a.anchor { padding-right: 0.5ch; padding-left: 3ch; }
-.packages .version { font-size: 10px; color: var(--by-name-version-color); }
-.packages .synopsis { padding-left: 1ch }
-
-.by-name nav a {
- text-transform: uppercase;
- font-size: 18px;
- margin-right: 1ex;
- color: var(--by-name-nav-link-color,);
- display: inline-block;
-}
-
-.by-tag nav a {
- margin-right: 1ex;
- color: var(--by-name-nav-link-color);
- display: inline-block;
-}
-
-.by-tag ol { list-style-type: none; }
-.by-tag ol.tags li { margin-left: 1ch; display: inline-block }
-.by-tag td:first-child { text-transform: uppercase; }
-
-/* Odig package page */
-
-.package nav {
- display: inline;
- font-size: 14px;
- font-weight: normal;
-}
-
-.package .version {
- font-size: 14px;
-}
-
-.package.info {
- margin: 0;
-}
-
-.package.info td:first-child {
- font-style: italic;
- padding-right: 2ex;
-}
-
-.package.info ul {
- list-style-type: none;
- display: inline;
- margin: 0;
-}
-
-.package.info li {
- display: inline-block;
- margin: 0;
- margin-right: 1ex;
-}
-
-#info-authors li, #info-maintainers li {
- display: block;
-}
-
-/* Sidebar and TOC */
-
-.odoc-toc:before {
- display: block;
- content: "Contents";
- text-transform: uppercase;
- font-size: 1em;
- margin: 1.414em 0 0.5em;
- font-weight: 500;
- color: var(--toc-before-color);
- line-height: 1.2;
-}
-
-.odoc-toc {
- position: fixed;
- top: 0px;
- bottom: 0px;
- left: 0px;
- max-width: 30ex;
- min-width: 26ex;
- width: 20%;
- background: var(--toc-background);
- overflow: auto;
- color: var(--toc-color);
- padding-left: 2ex;
- padding-right: 2ex;
-}
-
-.odoc-toc ul li a {
- font-family: "Fira Sans", sans-serif;
- font-size: 0.95em;
- color: var(--color);
- font-weight: 400;
- line-height: 1.6em;
- display: block;
-}
-
-.odoc-toc ul li a:hover {
- box-shadow: none;
- text-decoration: underline;
-}
-
-/* First level titles */
-
-.odoc-toc>ul>li>a {
- font-weight: 500;
-}
-
-.odoc-toc li ul {
- margin: 0px;
-}
-
-.odoc-toc ul {
- list-style-type: none;
-}
-
-.odoc-toc ul li {
- margin: 0;
-}
-.odoc-toc>ul>li {
- margin-bottom: 0.3em;
-}
-
-.odoc-toc ul li li {
- border-left: 1px solid var(--toc-list-border);
- margin-left: 5px;
- padding-left: 12px;
-}
-
-/* Mobile adjustements. */
-
-@media only screen and (max-width: 95ex) {
- body.odoc {
- margin: 2em;
- }
- .odoc-toc {
- position: static;
- width: auto;
- min-width: unset;
- max-width: unset;
- border: none;
- padding: 0.2em 1em;
- border-radius: 5px;
- margin-bottom: 2em;
- }
-}
-
-/* Print adjustements. */
-
-@media print {
- body {
- color: black;
- background: white;
- }
- body nav:first-child {
- visibility: hidden;
- }
-}
-
-/* Syntax highlighting (based on github-gist) */
-
-.hljs {
- display: block;
- background: var(--code-background);
- padding: 0.5em;
- color: var(--color);
- overflow-x: auto;
-}
-
-.hljs-comment,
-.hljs-meta {
- color: #969896;
-}
-
-.hljs-string,
-.hljs-variable,
-.hljs-template-variable,
-.hljs-strong,
-.hljs-emphasis,
-.hljs-quote {
- color: #df5000;
-}
-
-.hljs-keyword,
-.hljs-selector-tag {
- color: #a71d5d;
-}
-
-.hljs-type,
-.hljs-class .hljs-title {
- color: #458;
- font-weight: 500;
-}
-
-.hljs-literal,
-.hljs-symbol,
-.hljs-bullet,
-.hljs-attribute {
- color: #0086b3;
-}
-
-.hljs-section,
-.hljs-name {
- color: #63a35c;
-}
-
-.hljs-tag {
- color: #333333;
-}
-
-.hljs-attr,
-.hljs-selector-id,
-.hljs-selector-class,
-.hljs-selector-attr,
-.hljs-selector-pseudo {
- color: #795da3;
-}
-
-.hljs-addition {
- color: #55a532;
- background-color: #eaffea;
-}
-
-.hljs-deletion {
- color: #bd2c00;
- background-color: #ffecec;
-}
-
-.hljs-link {
- text-decoration: underline;
-}
-
-/*---------------------------------------------------------------------------
- Copyright (c) 2016 The odoc contributors
-
- Permission to use, copy, modify, and/or distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
- WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
- MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
- ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
- ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
- OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
- ---------------------------------------------------------------------------*/
diff --git a/dev/tiny_httpd/Tiny_httpd/index.html b/dev/tiny_httpd/Tiny_httpd/index.html
deleted file mode 100644
index b123af18..00000000
--- a/dev/tiny_httpd/Tiny_httpd/index.html
+++ /dev/null
@@ -1,98 +0,0 @@
-
-Tiny_httpd (tiny_httpd.Tiny_httpd)Module Tiny_httpd
Tiny 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 e
It 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"}
Tiny buffer implementation
These buffers are used to avoid allocating too many byte arrays when processing streams and parsing requests.
Generic byte streams
IO Abstraction
Main Server Type
HTTP Methods
Headers are metadata associated with a request or response.
Requests
Requests are sent by a client, e.g. a web browser or cURL. From the point of view of the server, they're inputs.
Response Codes
Responses
Responses are what a http server, such as Tiny_httpd, send back to the client to answer a Request.t
Routing
Basic 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.
Middlewares
A middleware can be inserted in a handler to modify or observe its behavior.
Main Server type
A 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.
A 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.
Address on which the server listens.
is_ipv6 server returns true iff the address of the server is an IPv6 address.
Port 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.
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 Transfer-Encoding header and returning a stream transformer that decompresses on the fly.
Add 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.
Request handlers
Setup 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 NEXT_RELEASE . Use Request.read_body_full to read the body into a string if needed.
add_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.
Similar 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.
Server-sent events
EXPERIMENTAL: this API is not stable yet.
A server-side function to generate of Server-sent events.
Server-sent event generator. This generates events that are forwarded to the client (e.g. the browser).
Add 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).
Run the server
Ask 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.
Utils
Resource pool
Static directory serving
Module Tiny_httpd_atomic_
include module type of struct include Stdlib.Atomic end
type !'a t = 'a Stdlib__Atomic.tval set : 'a t -> 'a -> unitval exchange : 'a t -> 'a -> 'aval compare_and_set : 'a t -> 'a -> 'a -> boolval fetch_and_add : int t -> int -> intval create : ?size:int -> unit -> tval contents : t -> stringval 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 -> unitval add_bytes : t -> bytes -> int -> int -> unitAppend given bytes slice to the buffer.
val add_string : t -> string -> unitval add_buffer : t -> Stdlib.Buffer.t -> unitAppend bytes from buffer.
Module Tiny_httpd_dir.Embedded_fs
An 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.
val to_vfs : t -> (module VFS)Module Tiny_httpd_dir
Serving 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 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;If upload is true, this is the maximum size in bytes for uploaded files.
_rest : hidden;
}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 ->
- configadd_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 ... endval vfs_of_dir : string -> (module VFS)vfs_of_dir dir makes a virtual file system that reads from the disk.
Similar to add_dir_path but using a virtual file system instead.
An 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 is_directory : string -> boolval contains : string -> boolfile_exists vfs path returns true if path points to a file or directory inside vfs.
val list_dir : string -> string arrayList directory. This only returns basenames, the files need to be put in the directory path using Filename.concat.
val delete : string -> unitval create : string -> (bytes -> int -> int -> unit) * (unit -> unit)Create a file and obtain a pair write, close
val file_size : string -> int optionFile size, e.g. using "stat"
val file_mtime : string -> float optionFile modification time, e.g. using "stat"
Module Tiny_httpd_html
HTML 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.
Output for HTML combinators.
type attribute = string * stringAn attribute, i.e. a key/value pair
A html element. It is represented by its output function, so we can directly print it.
Element without children.
Element with children, represented as a list.
type sub_elt = [ | `E of elt| `L of elt list| `S of elt Stdlib.Seq.t| `Nil
]A chunk of sub-elements, possibly empty.
Element with children, represented as a list of sub_elt to be flattened
Sub-element with a single element inside.
Sub-element with a list of items inside.
Sub-element with a sequence (Seq.t) of items inside.
val seq_of_array : 'a array -> 'b Stdlib.Seq.tHelper to build a Seq.t from an array.
Sub-element with nothing inside. Useful in conditionals, when one decides not to emit a sub-element at all.
Emit a string value, which will be escaped.
val txtf :
- ('a, Stdlib.Format.formatter, unit, Out.t -> unit) Stdlib.format4 ->
- 'bval raw_html : string -> eltEmit raw HTML. Caution, this can lead to injection vulnerabilities, never use with text that comes from untrusted users.
tag "blockquote", see mdn
tag "blockquote", see mdn
tag "figcaption", see mdn
tag "figcaption", see mdn
Write an HTML element to this out channel.
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 -> stringWrite a toplevel element to an output channel.
Produce a streaming writer from this HTML element.
Convert a HTML element to a stream. This might just convert it to a string first, do not assume it to be more efficient.
Output for HTML combinators.
type attribute = string * stringAn attribute, i.e. a key/value pair
A html element. It is represented by its output function, so we can directly print it.
Element without children.
Element with children, represented as a list.
type sub_elt = [ | `E of elt| `L of elt list| `S of elt Stdlib.Seq.t| `Nil
]A chunk of sub-elements, possibly empty.
Element with children, represented as a list of sub_elt to be flattened
Sub-element with a single element inside.
Sub-element with a list of items inside.
Sub-element with a sequence (Seq.t) of items inside.
val seq_of_array : 'a array -> 'b Stdlib.Seq.tHelper to build a Seq.t from an array.
Sub-element with nothing inside. Useful in conditionals, when one decides not to emit a sub-element at all.
Emit a string value, which will be escaped.
val txtf :
- ('a, Stdlib.Format.formatter, unit, Out.t -> unit) Stdlib.format4 ->
- 'bval raw_html : string -> eltEmit raw HTML. Caution, this can lead to injection vulnerabilities, never use with text that comes from untrusted users.
tag "blockquote", see mdn
tag "blockquote", see mdn
tag "figcaption", see mdn
tag "figcaption", see mdn
Input channel (byte source)
Output channel (byte sink)
A TCP server abstraction.
Module Tiny_httpd_pool
Resource 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.
Pool of values of type 'a
val create :
- ?clear:('a -> unit) ->
- mk_item:(unit -> 'a) ->
- ?max_size:int ->
- unit ->
- 'a tval 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.
Module Tiny_httpd_server.Headers
type t = (string * string) listThe 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 get : ?f:(string -> string) -> string -> t -> string optionget k headers looks for the header field with key k.
val set : string -> string -> t -> tset k v headers sets the key k to value v. It erases any previous entry for k
val remove : string -> t -> tRemove the key from the headers, if present.
val contains : string -> t -> boolIs there a header with the given key?
val pp : Stdlib.Format.formatter -> t -> unitPretty print the headers.
Module Tiny_httpd_server.Meth
type t = [ | `GET| `PUT| `POST| `HEAD| `DELETE| `OPTIONS
]A 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 -> stringModule Tiny_httpd_server.Middleware
Handlers 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.
Trivial middleware that does nothing.
Module Tiny_httpd_server.Request
type 'body t = private {meth : Meth.t;HTTP method for this request.
host : string;Host header, mandatory. It can also be found in headers.
client_addr : Unix.sockaddr;Client address. Available since NEXT_RELEASE.
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;start_time : float;Obtained via get_time_s in create
}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.
List of headers of the request, including "Host".
get_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.
Same 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 set_body : 'a -> _ t -> 'a tset_body b req returns a new query whose body is b.
Host field of the request. It also appears in the headers.
val query : _ t -> (string * string) listDecode the query part of the path field.
Request 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.
Module Tiny_httpd_server.Response
type 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 NEXT_RELEASE.
A response to send back to a client.
val set_body : body -> t -> tSet the body of the response.
Make a response from its raw components, with a string body. Use "" to not send a body at all.
Same as make_raw but with a stream body. The body will be sent with the chunked transfer-encoding.
val make_void : ?headers:Headers.t -> code:int -> unit -> tReturn a response without a body at all.
make 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.
Same as make but with a string body.
Same as make but with a writer body.
Same as make but with a stream body.
val fail :
- ?headers:Headers.t ->
- code:int ->
- ('a, unit, string, t) Stdlib.format4 ->
- 'aMake the current request fail with the given code and message. Example: fail ~code:404 "oh noes, %s not found" "waldo".
val fail_raise : code:int -> ('a, unit, string, 'b) Stdlib.format4 -> 'aSimilar 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.
Module Tiny_httpd_server.Response_code
A standard HTTP code.
https://tools.ietf.org/html/rfc7231#section-6
A description of some of the error codes. NOTE: this is not complete (yet).
Module Tiny_httpd_server.Route
An atomic component of a path
A route, composed of path components
val int : (int -> 'a, 'a) compval 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 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.
val (@/) : ('a, 'b) comp -> ('b, 'c) t -> ('a, 'c) tcomp / route matches "foo/bar/…" iff comp matches "foo", and route matches "bar/…".
val exact_path : string -> ('a, 'b) t -> ('a, 'b) texact_path "foo/bar/..." r is equivalent to exact "foo" @/ exact "bar" @/ ... @/ r
val pp : Stdlib.Format.formatter -> (_, _) t -> unitval to_string : (_, _) t -> stringModule Tiny_httpd_server
HTTP 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.
HTTP Methods
module Meth : sig ... endHeaders are metadata associated with a request or response.
Requests
Requests are sent by a client, e.g. a web browser or cURL. From the point of view of the server, they're inputs.
Response Codes
Responses
Responses are what a http server, such as Tiny_httpd, send back to the client to answer a Request.t
Routing
Basic 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 ... endMiddlewares
A middleware can be inserted in a handler to modify or observe its behavior.
Main Server type
A 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.
A 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.
Address on which the server listens.
is_ipv6 server returns true iff the address of the server is an IPv6 address.
Port 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.
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 Transfer-Encoding header and returning a stream transformer that decompresses on the fly.
Add 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.
Request handlers
Setup 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 NEXT_RELEASE . Use Request.read_body_full to read the body into a string if needed.
add_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.
Similar 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.
Server-sent events
EXPERIMENTAL: this API is not stable yet.
A server-side function to generate of Server-sent events.
Server-sent event generator. This generates events that are forwarded to the client (e.g. the browser).
Add 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).
Run the server
Ask 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 type Tiny_httpd_server.IO_BACKEND
A 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 init_addr : unit -> stringval init_port : unit -> intval get_time_s : unit -> floatObtain the current timestamp in seconds.
TCP server builder, to create servers that can listen on a port and handle clients.
Set 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).
val send_event :
- ?event:string ->
- ?id:string ->
- ?retry:string ->
- data:string ->
- unit ->
- unitSend an event from the server. If data is a multiline string, it will be sent on separate "data:" lines.
Module Tiny_httpd_stream
Byte 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 used to make t unbuildable via a record literal. Use make instead.
type t = {mutable bs : bytes;mutable off : int;Beginning of valid slice in bs
mutable len : int;Length of valid slice in bs. If len = 0 after a call to fill, then the stream is finished.
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;_rest : hidden;Use make to build a stream.
}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)- if
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;
- );
- len
Stream with 0 bytes inside
Make 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.
Turn 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.
Read a line from the stream.
Read the whole stream into a string.
val limit_size_to :
- close_rec:bool ->
- max_size:int ->
- too_big:(int -> unit) ->
- t ->
- tConvert a stream into a stream of byte chunks using the chunked encoding. The size of chunks is not specified.
val read_exactly :
- close_rec:bool ->
- size:int ->
- too_short:(int -> unit) ->
- t ->
- tread_exactly ~size bs returns a new stream that reads exactly size bytes from bs, and then closes.
Write the stream into the channel, using the chunked encoding.
Write the stream into the channel, using the chunked encoding.
Some utils for writing web servers
val percent_encode : ?skip:(char -> bool) -> string -> stringEncode the string into a valid path following https://tools.ietf.org/html/rfc3986#section-2.1
val percent_decode : string -> string optionInverse operation of percent_encode. Can fail since some strings are not valid percent encodings.
val split_query : string -> string * stringSplit a path between the path and the query
val split_on_slash : string -> string listSplit a string on '/', remove the trailing '/' if any.
val get_non_query_path : string -> stringget the part of the path that is not the query parameters.
val get_query : string -> stringObtain the query part of a path.
val parse_query : string -> ((string * string) list, string) Stdlib.resultParse a query as a list of '&' or ';' separated key=value pairs. The order might not be preserved.
Library tiny_httpd
This library exposes the following toplevel modules:
Module Tiny_httpd_camlzip
Middleware 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).
Middleware responsible for deflate compression/decompression.
Install middleware for tiny_httpd to be able to encode/decode compressed streams
Library tiny_httpd_camlzip
The entry point of this library is the module: Tiny_httpd_camlzip.
Module Tiny_httpd
Tiny 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 e
It 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"}
type buf = Tiny_httpd_buf.ttype byte_stream = Tiny_httpd_stream.t
type t = Tiny_httpd_server.t
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 -> t
val create_from : ?buf_size:int -> ?middlewares:([ `Encoding | `Stage of int ] * Middleware.t) list -> backend:(module IO_BACKEND) -> unit -> tval addr : t -> stringval is_ipv6 : t -> boolval port : t -> intval active_connections : t -> intval add_decode_request_cb : t -> (unit Request.t -> (unit Request.t * (byte_stream -> byte_stream)) option) -> unitval add_encode_response_cb : t -> (unit Request.t -> Response.t -> Response.t option) -> unitval add_middleware : stage:[ `Encoding | `Stage of int ] -> t -> Middleware.t -> unitval set_top_handler : t -> (byte_stream Request.t -> Response.t) -> unitval 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 -> unitval 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 -> unit
type server_sent_generator = (module SERVER_SENT_GENERATOR)
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 -> unitval running : t -> boolval stop : t -> unitval run : ?after_init:(unit -> unit) -> t -> (unit, exn) Stdlib.resultval run_exn : ?after_init:(unit -> unit) -> t -> unitval _debug : ((('a, Stdlib.out_channel, unit, unit, unit, unit) Stdlib.format6 -> 'a) -> unit) -> unitval _enable_debug : bool -> unit
val init_addr : unit -> stringval init_port : unit -> intval get_time_s : unit -> floatval tcp_server : unit -> Tiny_httpd_io.TCP_server.builder
val send_event : ?event:string -> ?id:string -> ?retry:string -> data:string -> unit -> unitval close : unit -> unit
Module Tiny_httpd_atomic_
include Stdlib.Atomic
type !'a t = 'a Stdlib__atomic.t
val make : 'a -> 'a tval get : 'a t -> 'aval set : 'a t -> 'a -> unitval exchange : 'a t -> 'a -> 'aval compare_and_set : 'a t -> 'a -> 'a -> boolval fetch_and_add : int t -> int -> intval incr : int t -> unitval decr : int t -> unit
type t
val size : t -> intval clear : t -> unitval create : ?size:int -> unit -> tval contents : t -> stringval bytes_slice : t -> bytesAccess underlying slice of bytes.
- since
- 0.5
val contents_and_clear : t -> stringGet contents of the buffer and clear it.
- since
- 0.5
val add_char : t -> char -> unitAdd a single char.
- since
- 0.14
val add_bytes : t -> bytes -> int -> int -> unitAppend given bytes slice to the buffer.
- since
- 0.5
val add_string : t -> string -> unitAdd string.
- since
- 0.14
val add_buffer : t -> Stdlib.Buffer.t -> unitAppend bytes from buffer.
- since
- 0.14
Module Tiny_httpd_dir.Embedded_fs
An 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.
- since
- 0.12
type tThe pseudo-filesystem
val create : ?mtime:float -> unit -> tval add_file : ?mtime:float -> t -> path:string -> string -> unitAdd file to the virtual file system.
- raises Invalid_argument
if the path contains '..' or if it tries to make a directory out of an existing path that is a file.
val to_vfs : t -> (module VFS)
Module Tiny_httpd_dir
Serving 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.
- since
- 0.11
type dir_behavior = | Index | Redirect to index.html if present, else fails. |
| Lists | Lists content of directory. Be careful of security implications. |
| Index_or_lists | Redirect 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 |
| Forbidden | Forbid 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 hiddenType 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; | If upload is true, this is the maximum size in bytes for uploaded files. |
_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.
- since
- 0.12
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.
- since
- 0.12
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.
- since
- 0.12
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.
val descr : stringDescription of the VFS
val is_directory : string -> boolval contains : string -> boolfile_exists vfs path returns true if path points to a file or directory inside vfs.
val list_dir : string -> string arrayList directory. This only returns basenames, the files need to be put in the directory path using Filename.concat.
val delete : string -> unitDelete path
val create : string -> (bytes -> int -> int -> unit) * (unit -> unit)Create a file and obtain a pair write, close
val read_file_content : string -> Tiny_httpd_stream.tRead content of a file
val file_size : string -> int optionFile size, e.g. using "stat"
val file_mtime : string -> float optionFile modification time, e.g. using "stat"
Module Tiny_httpd_html
HTML 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.
- since
- 0.12
module Out = Tiny_httpd_html_.OutOutput for HTML combinators.
type attribute = string * stringAn attribute, i.e. a key/value pair
type elt = Out.t -> unitA html element. It is represented by its output function, so we can directly print it.
type void = ?if_:bool -> attribute list -> eltElement without children.
type nary = ?if_:bool -> attribute list -> elt list -> eltElement with children, represented as a list.
- parameter if_
if false, do not print anything (default true)
type sub_elt = [ | `E of elt |
| `L of elt list |
| `S of elt Stdlib.Seq.t |
| `Nil |
]A chunk of sub-elements, possibly empty.
type nary' = ?if_:bool -> attribute list -> sub_elt list -> eltElement with children, represented as a list of sub_elt to be flattened
- parameter if_
if false, do not print anything (default true)
val sub_e : elt -> sub_eltSub-element with a single element inside.
val sub_l : elt list -> sub_eltSub-element with a list of items inside.
val sub_seq : elt Stdlib.Seq.t -> sub_eltSub-element with a sequence (Seq.t) of items inside.
val seq_of_array : 'a array -> 'a Stdlib.Seq.tHelper to build a Seq.t from an array.
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 -> 'aFormatted 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.
val area : voidtag "area", see mdn
val base : voidtag "base", see mdn
val br : voidtag "br", see mdn
val col : voidtag "col", see mdn
val embed : voidtag "embed", see mdn
val hr : voidtag "hr", see mdn
val img : voidtag "img", see mdn
val input : voidtag "input", see mdn
val link : voidtag "link", see mdn
tag "menuitem", see mdn
val meta : voidtag "meta", see mdn
val param : voidtag "param", see mdn
val source : voidtag "source", see mdn
val track : voidtag "track", see mdn
val wbr : voidtag "wbr", see mdn
val a : narytag "a", see mdn
val a' : nary'tag "a", see mdn
val abbr : narytag "abbr", see mdn
val abbr' : nary'tag "abbr", see mdn
val address : narytag "address", see mdn
val address' : nary'tag "address", see mdn
val article : narytag "article", see mdn
val article' : nary'tag "article", see mdn
val aside : narytag "aside", see mdn
val aside' : nary'tag "aside", see mdn
val audio : narytag "audio", see mdn
val audio' : nary'tag "audio", see mdn
val b : narytag "b", see mdn
val b' : nary'tag "b", see mdn
val bdi : narytag "bdi", see mdn
val bdi' : nary'tag "bdi", see mdn
val bdo : narytag "bdo", see mdn
val bdo' : nary'tag "bdo", see mdn
val blockquote : narytag "blockquote", see mdn
val blockquote' : nary'tag "blockquote", see mdn
val body : narytag "body", see mdn
val body' : nary'tag "body", see mdn
val button : narytag "button", see mdn
val button' : nary'tag "button", see mdn
val canvas : narytag "canvas", see mdn
val canvas' : nary'tag "canvas", see mdn
val caption : narytag "caption", see mdn
val caption' : nary'tag "caption", see mdn
val cite : narytag "cite", see mdn
val cite' : nary'tag "cite", see mdn
val code : narytag "code", see mdn
val code' : nary'tag "code", see mdn
val colgroup : narytag "colgroup", see mdn
val colgroup' : nary'tag "colgroup", see mdn
val data : narytag "data", see mdn
val data' : nary'tag "data", see mdn
val datalist : narytag "datalist", see mdn
val datalist' : nary'tag "datalist", see mdn
val dd : narytag "dd", see mdn
val dd' : nary'tag "dd", see mdn
val del : narytag "del", see mdn
val del' : nary'tag "del", see mdn
val details : narytag "details", see mdn
val details' : nary'tag "details", see mdn
val dfn : narytag "dfn", see mdn
val dfn' : nary'tag "dfn", see mdn
val dialog : narytag "dialog", see mdn
val dialog' : nary'tag "dialog", see mdn
val div : narytag "div", see mdn
val div' : nary'tag "div", see mdn
val dl : narytag "dl", see mdn
val dl' : nary'tag "dl", see mdn
val dt : narytag "dt", see mdn
val dt' : nary'tag "dt", see mdn
val em : narytag "em", see mdn
val em' : nary'tag "em", see mdn
val fieldset : narytag "fieldset", see mdn
val fieldset' : nary'tag "fieldset", see mdn
val figcaption : narytag "figcaption", see mdn
val figcaption' : nary'tag "figcaption", see mdn
val figure : narytag "figure", see mdn
val figure' : nary'tag "figure", see mdn
tag "footer", see mdn
tag "footer", see mdn
val form : narytag "form", see mdn
val form' : nary'tag "form", see mdn
val h1 : narytag "h1", see mdn
val h1' : nary'tag "h1", see mdn
val h2 : narytag "h2", see mdn
val h2' : nary'tag "h2", see mdn
val h3 : narytag "h3", see mdn
val h3' : nary'tag "h3", see mdn
val h4 : narytag "h4", see mdn
val h4' : nary'tag "h4", see mdn
val h5 : narytag "h5", see mdn
val h5' : nary'tag "h5", see mdn
val h6 : narytag "h6", see mdn
val h6' : nary'tag "h6", see mdn
val head : narytag "head", see mdn
val head' : nary'tag "head", see mdn
tag "header", see mdn
tag "header", see mdn
val hgroup : narytag "hgroup", see mdn
val hgroup' : nary'tag "hgroup", see mdn
val html : narytag "html", see mdn
val html' : nary'tag "html", see mdn
val i : narytag "i", see mdn
val i' : nary'tag "i", see mdn
val iframe : narytag "iframe", see mdn
val iframe' : nary'tag "iframe", see mdn
val ins : narytag "ins", see mdn
val ins' : nary'tag "ins", see mdn
val kbd : narytag "kbd", see mdn
val kbd' : nary'tag "kbd", see mdn
val label : narytag "label", see mdn
val label' : nary'tag "label", see mdn
val legend : narytag "legend", see mdn
val legend' : nary'tag "legend", see mdn
val li : narytag "li", see mdn
val li' : nary'tag "li", see mdn
val main : narytag "main", see mdn
val main' : nary'tag "main", see mdn
val map : narytag "map", see mdn
val map' : nary'tag "map", see mdn
val mark : narytag "mark", see mdn
val mark' : nary'tag "mark", see mdn
val math : narytag "math", see mdn
val math' : nary'tag "math", see mdn
tag "menu", see mdn
tag "menu", see mdn
val meter : narytag "meter", see mdn
val meter' : nary'tag "meter", see mdn
val nav : narytag "nav", see mdn
val nav' : nary'tag "nav", see mdn
val noscript : narytag "noscript", see mdn
val noscript' : nary'tag "noscript", see mdn
val object_ : narytag "object", see mdn
val object_' : nary'tag "object", see mdn
val ol : narytag "ol", see mdn
val ol' : nary'tag "ol", see mdn
val optgroup : narytag "optgroup", see mdn
val optgroup' : nary'tag "optgroup", see mdn
val option : narytag "option", see mdn
val option' : nary'tag "option", see mdn
val output : narytag "output", see mdn
val output' : nary'tag "output", see mdn
val p : narytag "p", see mdn
val p' : nary'tag "p", see mdn
val picture : narytag "picture", see mdn
val picture' : nary'tag "picture", see mdn
val pre : narytag "pre", see mdn
val pre' : nary'tag "pre", see mdn
val progress : narytag "progress", see mdn
val progress' : nary'tag "progress", see mdn
val q : narytag "q", see mdn
val q' : nary'tag "q", see mdn
val rb : narytag "rb", see mdn
val rb' : nary'tag "rb", see mdn
val rp : narytag "rp", see mdn
val rp' : nary'tag "rp", see mdn
val rt : narytag "rt", see mdn
val rt' : nary'tag "rt", see mdn
val rtc : narytag "rtc", see mdn
val rtc' : nary'tag "rtc", see mdn
val ruby : narytag "ruby", see mdn
val ruby' : nary'tag "ruby", see mdn
val s : narytag "s", see mdn
val s' : nary'tag "s", see mdn
val samp : narytag "samp", see mdn
val samp' : nary'tag "samp", see mdn
val script : narytag "script", see mdn
val script' : nary'tag "script", see mdn
val section : narytag "section", see mdn
val section' : nary'tag "section", see mdn
val select : narytag "select", see mdn
val select' : nary'tag "select", see mdn
val slot : narytag "slot", see mdn
val slot' : nary'tag "slot", see mdn
val small : narytag "small", see mdn
val small' : nary'tag "small", see mdn
val span : narytag "span", see mdn
val span' : nary'tag "span", see mdn
val strong : narytag "strong", see mdn
val strong' : nary'tag "strong", see mdn
val style : narytag "style", see mdn
val style' : nary'tag "style", see mdn
val sub : narytag "sub", see mdn
val sub' : nary'tag "sub", see mdn
val summary : narytag "summary", see mdn
val summary' : nary'tag "summary", see mdn
val sup : narytag "sup", see mdn
val sup' : nary'tag "sup", see mdn
val svg : narytag "svg", see mdn
val svg' : nary'tag "svg", see mdn
val table : narytag "table", see mdn
val table' : nary'tag "table", see mdn
val tbody : narytag "tbody", see mdn
val tbody' : nary'tag "tbody", see mdn
val td : narytag "td", see mdn
val td' : nary'tag "td", see mdn
val template : narytag "template", see mdn
val template' : nary'tag "template", see mdn
val textarea : narytag "textarea", see mdn
val textarea' : nary'tag "textarea", see mdn
tag "tfoot", see mdn
tag "tfoot", see mdn
val th : narytag "th", see mdn
val th' : nary'tag "th", see mdn
val thead : narytag "thead", see mdn
val thead' : nary'tag "thead", see mdn
val time : narytag "time", see mdn
val time' : nary'tag "time", see mdn
val title : narytag "title", see mdn
val title' : nary'tag "title", see mdn
val tr : narytag "tr", see mdn
val tr' : nary'tag "tr", see mdn
val u : narytag "u", see mdn
val u' : nary'tag "u", see mdn
val ul : narytag "ul", see mdn
val ul' : nary'tag "ul", see mdn
val var : narytag "var", see mdn
val var' : nary'tag "var", see mdn
val video : narytag "video", see mdn
val video' : nary'tag "video", see mdn
module A = Tiny_httpd_html_.AAttributes.
val to_output : ?top:bool -> elt -> IO.Output.t -> unitWrite an HTML element to this output.
- parameter top
if true, add DOCTYPE at the beginning. The top element should then be a "html" tag.
- since
- 0.14
val to_string : ?top:bool -> elt -> stringConvert a HTML element to a string.
- parameter top
if true, add DOCTYPE at the beginning. The top element should then be a "html" tag.
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.
- since
- 0.14
val to_writer : ?top:bool -> elt -> IO.Writer.tProduce a streaming writer from this HTML element.
- parameter top
if true, add a DOCTYPE. See to_out_channel.
- since
- 0.14
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.
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".
Attribute "headers".
val hidden : tAttribute "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".
Module Tiny_httpd_html_.Out
Output 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.
- since
- 0.12
type t
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) -> 'a
module Out : sig ... endOutput for HTML combinators.
type attribute = string * stringAn attribute, i.e. a key/value pair
type elt = Out.t -> unitA html element. It is represented by its output function, so we can directly print it.
type void = ?if_:bool -> attribute list -> eltElement without children.
type nary = ?if_:bool -> attribute list -> elt list -> eltElement with children, represented as a list.
- parameter if_
if false, do not print anything (default true)
type sub_elt = [ | `E of elt |
| `L of elt list |
| `S of elt Stdlib.Seq.t |
| `Nil |
]A chunk of sub-elements, possibly empty.
type nary' = ?if_:bool -> attribute list -> sub_elt list -> eltElement with children, represented as a list of sub_elt to be flattened
- parameter if_
if false, do not print anything (default true)
val sub_e : elt -> sub_eltSub-element with a single element inside.
val sub_l : elt list -> sub_eltSub-element with a list of items inside.
val sub_seq : elt Stdlib.Seq.t -> sub_eltSub-element with a sequence (Seq.t) of items inside.
val seq_of_array : 'a array -> 'a Stdlib.Seq.tHelper to build a Seq.t from an array.
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 -> 'aFormatted 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.
val area : voidtag "area", see mdn
val base : voidtag "base", see mdn
val br : voidtag "br", see mdn
val col : voidtag "col", see mdn
val embed : voidtag "embed", see mdn
val hr : voidtag "hr", see mdn
val img : voidtag "img", see mdn
val input : voidtag "input", see mdn
val link : voidtag "link", see mdn
tag "menuitem", see mdn
val meta : voidtag "meta", see mdn
val param : voidtag "param", see mdn
val source : voidtag "source", see mdn
val track : voidtag "track", see mdn
val wbr : voidtag "wbr", see mdn
val a : narytag "a", see mdn
val a' : nary'tag "a", see mdn
val abbr : narytag "abbr", see mdn
val abbr' : nary'tag "abbr", see mdn
val address : narytag "address", see mdn
val address' : nary'tag "address", see mdn
val article : narytag "article", see mdn
val article' : nary'tag "article", see mdn
val aside : narytag "aside", see mdn
val aside' : nary'tag "aside", see mdn
val audio : narytag "audio", see mdn
val audio' : nary'tag "audio", see mdn
val b : narytag "b", see mdn
val b' : nary'tag "b", see mdn
val bdi : narytag "bdi", see mdn
val bdi' : nary'tag "bdi", see mdn
val bdo : narytag "bdo", see mdn
val bdo' : nary'tag "bdo", see mdn
val blockquote : narytag "blockquote", see mdn
val blockquote' : nary'tag "blockquote", see mdn
val body : narytag "body", see mdn
val body' : nary'tag "body", see mdn
val button : narytag "button", see mdn
val button' : nary'tag "button", see mdn
val canvas : narytag "canvas", see mdn
val canvas' : nary'tag "canvas", see mdn
val caption : narytag "caption", see mdn
val caption' : nary'tag "caption", see mdn
val cite : narytag "cite", see mdn
val cite' : nary'tag "cite", see mdn
val code : narytag "code", see mdn
val code' : nary'tag "code", see mdn
val colgroup : narytag "colgroup", see mdn
val colgroup' : nary'tag "colgroup", see mdn
val data : narytag "data", see mdn
val data' : nary'tag "data", see mdn
val datalist : narytag "datalist", see mdn
val datalist' : nary'tag "datalist", see mdn
val dd : narytag "dd", see mdn
val dd' : nary'tag "dd", see mdn
val del : narytag "del", see mdn
val del' : nary'tag "del", see mdn
val details : narytag "details", see mdn
val details' : nary'tag "details", see mdn
val dfn : narytag "dfn", see mdn
val dfn' : nary'tag "dfn", see mdn
val dialog : narytag "dialog", see mdn
val dialog' : nary'tag "dialog", see mdn
val div : narytag "div", see mdn
val div' : nary'tag "div", see mdn
val dl : narytag "dl", see mdn
val dl' : nary'tag "dl", see mdn
val dt : narytag "dt", see mdn
val dt' : nary'tag "dt", see mdn
val em : narytag "em", see mdn
val em' : nary'tag "em", see mdn
val fieldset : narytag "fieldset", see mdn
val fieldset' : nary'tag "fieldset", see mdn
val figcaption : narytag "figcaption", see mdn
val figcaption' : nary'tag "figcaption", see mdn
val figure : narytag "figure", see mdn
val figure' : nary'tag "figure", see mdn
tag "footer", see mdn
tag "footer", see mdn
val form : narytag "form", see mdn
val form' : nary'tag "form", see mdn
val h1 : narytag "h1", see mdn
val h1' : nary'tag "h1", see mdn
val h2 : narytag "h2", see mdn
val h2' : nary'tag "h2", see mdn
val h3 : narytag "h3", see mdn
val h3' : nary'tag "h3", see mdn
val h4 : narytag "h4", see mdn
val h4' : nary'tag "h4", see mdn
val h5 : narytag "h5", see mdn
val h5' : nary'tag "h5", see mdn
val h6 : narytag "h6", see mdn
val h6' : nary'tag "h6", see mdn
val head : narytag "head", see mdn
val head' : nary'tag "head", see mdn
tag "header", see mdn
tag "header", see mdn
val hgroup : narytag "hgroup", see mdn
val hgroup' : nary'tag "hgroup", see mdn
val html : narytag "html", see mdn
val html' : nary'tag "html", see mdn
val i : narytag "i", see mdn
val i' : nary'tag "i", see mdn
val iframe : narytag "iframe", see mdn
val iframe' : nary'tag "iframe", see mdn
val ins : narytag "ins", see mdn
val ins' : nary'tag "ins", see mdn
val kbd : narytag "kbd", see mdn
val kbd' : nary'tag "kbd", see mdn
val label : narytag "label", see mdn
val label' : nary'tag "label", see mdn
val legend : narytag "legend", see mdn
val legend' : nary'tag "legend", see mdn
val li : narytag "li", see mdn
val li' : nary'tag "li", see mdn
val main : narytag "main", see mdn
val main' : nary'tag "main", see mdn
val map : narytag "map", see mdn
val map' : nary'tag "map", see mdn
val mark : narytag "mark", see mdn
val mark' : nary'tag "mark", see mdn
val math : narytag "math", see mdn
val math' : nary'tag "math", see mdn
tag "menu", see mdn
tag "menu", see mdn
val meter : narytag "meter", see mdn
val meter' : nary'tag "meter", see mdn
val nav : narytag "nav", see mdn
val nav' : nary'tag "nav", see mdn
val noscript : narytag "noscript", see mdn
val noscript' : nary'tag "noscript", see mdn
val object_ : narytag "object", see mdn
val object_' : nary'tag "object", see mdn
val ol : narytag "ol", see mdn
val ol' : nary'tag "ol", see mdn
val optgroup : narytag "optgroup", see mdn
val optgroup' : nary'tag "optgroup", see mdn
val option : narytag "option", see mdn
val option' : nary'tag "option", see mdn
val output : narytag "output", see mdn
val output' : nary'tag "output", see mdn
val p : narytag "p", see mdn
val p' : nary'tag "p", see mdn
val picture : narytag "picture", see mdn
val picture' : nary'tag "picture", see mdn
val pre : narytag "pre", see mdn
val pre' : nary'tag "pre", see mdn
val progress : narytag "progress", see mdn
val progress' : nary'tag "progress", see mdn
val q : narytag "q", see mdn
val q' : nary'tag "q", see mdn
val rb : narytag "rb", see mdn
val rb' : nary'tag "rb", see mdn
val rp : narytag "rp", see mdn
val rp' : nary'tag "rp", see mdn
val rt : narytag "rt", see mdn
val rt' : nary'tag "rt", see mdn
val rtc : narytag "rtc", see mdn
val rtc' : nary'tag "rtc", see mdn
val ruby : narytag "ruby", see mdn
val ruby' : nary'tag "ruby", see mdn
val s : narytag "s", see mdn
val s' : nary'tag "s", see mdn
val samp : narytag "samp", see mdn
val samp' : nary'tag "samp", see mdn
val script : narytag "script", see mdn
val script' : nary'tag "script", see mdn
val section : narytag "section", see mdn
val section' : nary'tag "section", see mdn
val select : narytag "select", see mdn
val select' : nary'tag "select", see mdn
val slot : narytag "slot", see mdn
val slot' : nary'tag "slot", see mdn
val small : narytag "small", see mdn
val small' : nary'tag "small", see mdn
val span : narytag "span", see mdn
val span' : nary'tag "span", see mdn
val strong : narytag "strong", see mdn
val strong' : nary'tag "strong", see mdn
val style : narytag "style", see mdn
val style' : nary'tag "style", see mdn
val sub : narytag "sub", see mdn
val sub' : nary'tag "sub", see mdn
val summary : narytag "summary", see mdn
val summary' : nary'tag "summary", see mdn
val sup : narytag "sup", see mdn
val sup' : nary'tag "sup", see mdn
val svg : narytag "svg", see mdn
val svg' : nary'tag "svg", see mdn
val table : narytag "table", see mdn
val table' : nary'tag "table", see mdn
val tbody : narytag "tbody", see mdn
val tbody' : nary'tag "tbody", see mdn
val td : narytag "td", see mdn
val td' : nary'tag "td", see mdn
val template : narytag "template", see mdn
val template' : nary'tag "template", see mdn
val textarea : narytag "textarea", see mdn
val textarea' : nary'tag "textarea", see mdn
tag "tfoot", see mdn
tag "tfoot", see mdn
val th : narytag "th", see mdn
val th' : nary'tag "th", see mdn
val thead : narytag "thead", see mdn
val thead' : nary'tag "thead", see mdn
val time : narytag "time", see mdn
val time' : nary'tag "time", see mdn
val title : narytag "title", see mdn
val title' : nary'tag "title", see mdn
val tr : narytag "tr", see mdn
val tr' : nary'tag "tr", see mdn
val u : narytag "u", see mdn
val u' : nary'tag "u", see mdn
val ul : narytag "ul", see mdn
val ul' : nary'tag "ul", see mdn
val var : narytag "var", see mdn
val var' : nary'tag "var", see mdn
val video : narytag "video", see mdn
val video' : nary'tag "video", see mdn
module A : sig ... endAttributes.
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.
- returns
the number of bytes read, 0 means end of input.
val close : t -> unitClose the channel.
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.
- parameter close_noerr
if true, then closing the result uses close_out_noerr instead of close_out to close oc
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.
val output_buf : t -> Buf.t -> unitval chunk_encoding : ?buf:Buf.t -> close_rec:bool -> t -> tchunk_encoding oc makes a new channel that outputs its content into oc in chunk encoding form.
- parameter close_rec
if true, closing the result will also close oc
- parameter buf
a buffer used to accumulate data into chunks. Chunks are emitted when buf's size gets over a certain threshold, or when flush is called.
type conn_handler = {handle : client_addr:Unix.sockaddr -> Input.t -> Output.t -> unit; | Handle client connection |
}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. - parameter after_init
is called once with the server after the server has started.
|
}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.
type t = {}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, and output into it as if it were a regular out_channel, including controlling calls to flush.
- since
- 0.14
val make : write:(Output.t -> unit) -> unit -> tval write : Output.t -> t -> unitWrite into the channel.
val empty : tEmpty writer, will output 0 bytes.
val of_string : string -> tA writer that just emits the bytes from the given string.
module 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.
Module Tiny_httpd_pool
Resource 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.
- since
- 0.14.
type 'a tPool of values of type 'a
val create : ?clear:('a -> unit) -> mk_item:(unit -> 'a) -> ?max_size:int -> unit -> 'a tCreate a new pool.
- parameter mk_item
produce a new item in case the pool is empty
- parameter max_size
maximum number of item in the pool before we start dropping resources on the floor. This controls resource consumption.
- parameter clear
a function called on items before recycling them.
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.
type t = (string * string) listThe 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.
- since
- 0.5
val get : ?f:(string -> string) -> string -> t -> string optionget k headers looks for the header field with key k.
- parameter f
if provided, will transform the value before it is returned.
val set : string -> string -> t -> tset k v headers sets the key k to value v. It erases any previous entry for k
val remove : string -> t -> tRemove the key from the headers, if present.
val contains : string -> t -> boolIs there a header with the given key?
val pp : Stdlib.Format.formatter -> t -> unitPretty print the headers.
type t = [ | `GET |
| `PUT |
| `POST |
| `HEAD |
| `DELETE |
| `OPTIONS |
]A 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 -> string
type 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.
type t = handler -> handlerA 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.
type 'body t = private {meth : Meth.t; | HTTP method for this request. |
host : string; | Host header, mandatory. It can also be found in headers. |
client_addr : Unix.sockaddr; | Client address. Available since 0.14. |
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; | Obtained via get_time_s in create - since
- 0.11
|
}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.
- since
- 0.6 The field [query] was added and contains the query parameters in ["?foo=bar,x=y"]
- since
- 0.6 The field [path_components] is the part of the path that precedes [query] and is split on ["/"].
- since
- 0.11 the type is a private alias
- since
- 0.11 the field [start_time] was added
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.
List of headers of the request, including "Host".
get_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.
Same 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.
- since
- 0.11
val set_body : 'a -> _ t -> 'a tset_body b req returns a new query whose body is b.
- since
- 0.11
val host : _ t -> stringHost field of the request. It also appears in the headers.
val meth : _ t -> Meth.tMethod for the request.
val path : _ t -> stringRequest path.
val query : _ t -> (string * string) listDecode the query part of the path field.
- since
- 0.4
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
- since
- 0.11
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.
- since
- 0.3
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.
- parameter buf_size
initial size of underlying buffer (since 0.11)
- parameter buf
the initial buffer (since 0.14)
type body = [ ]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 {}A response to send back to a client.
val set_body : body -> t -> tSet the body of the response.
- since
- 0.11
Set a header.
- since
- 0.11
Modify headers.
- since
- 0.11
Set all headers.
- since
- 0.11
val set_code : Response_code.t -> t -> tSet the response code.
- since
- 0.11
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_void : ?headers:Headers.t -> code:int -> unit -> tReturn a response without a body at all.
- since
- 0.13
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.
val fail : ?headers:Headers.t -> code:int -> ('a, unit, string, t) Stdlib.format4 -> 'aMake the current request fail with the given code and message. Example: fail ~code:404 "oh noes, %s not found" "waldo".
val fail_raise : code:int -> ('a, unit, string, 'b) Stdlib.format4 -> 'aSimilar 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.
type t = intA standard HTTP code.
https://tools.ietf.org/html/rfc7231#section-6
val 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).
type ('a, 'b) compAn atomic component of a path
type ('a, 'b) tA route, composed of path components
val 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.
- since
- 0.7
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.
- since
- 0.7
val (@/) : ('a, 'b) comp -> ('b, 'c) t -> ('a, 'c) tcomp / route matches "foo/bar/…" iff comp matches "foo", and route matches "bar/…".
val exact_path : string -> ('a, 'b) t -> ('a, 'b) texact_path "foo/bar/..." r is equivalent to exact "foo" @/ exact "bar" @/ ... @/ r
- since
- 0.11 *
val pp : Stdlib.Format.formatter -> (_, _) t -> unitPrint the route.
- since
- 0.7
val to_string : (_, _) t -> stringPrint the route.
- since
- 0.7
Module Tiny_httpd_server
HTTP 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.
- since
- 0.13
type buf = Tiny_httpd_buf.ttype byte_stream = Tiny_httpd_stream.t
module Meth : sig ... endRequests
Requests are sent by a client, e.g. a web browser or cURL. From the point of view of the server, they're inputs.
module Route : sig ... endtype 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.
- parameter masksigpipe
if true, block the signal Sys.sigpipe which otherwise tends to kill client threads when they try to write on broken sockets. Default: true.
- parameter buf_size
size for buffers (since 0.11)
- parameter new_thread
a function used to spawn a new thread to handle a new client connection. By default it is Thread.create but one could use a thread pool instead. See for example this use of moonpool.
- parameter middlewares
see add_middleware for more details.
- parameter max_connections
maximum number of simultaneous connections.
- parameter timeout
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.
- parameter addr
address (IPv4 or IPv6) to listen on. Default "127.0.0.1".
- parameter port
to listen on. Default 8080.
- parameter sock
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 addr and port. If not passed in, those will be used. This parameter exists since 0.10.
- parameter get_time_s
obtain the current timestamp in seconds. This parameter exists since 0.11.
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.
- parameter buf_size
size for buffers (since 0.11)
- parameter middlewares
see add_middleware for more details.
- since
- 0.14
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.
- since
- 0.3
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.
- deprecated
use add_middleware instead
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.
- deprecated
use add_middleware instead
val add_middleware : stage:[ `Encoding | `Stage of int ] -> t -> Middleware.t -> unitAdd a middleware to every request/response pair.
- parameter stage
specify when middleware applies. Encoding comes first (outermost layer), then stages in increasing order.
- raises Invalid_argument
if stage is `Stage n where n < 1
- since
- 0.11
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.
- parameter meth
if provided, only accept requests with the given method. Typically one could react to `GET or `PUT.
- parameter accept
should return Ok() if the given request (before its body is read) should be accepted, Error (code,message) if it's to be rejected (e.g. because its content is too big, or for some permission error). See the http_of_dir program for an example of how to use accept to filter uploads that are too large before the upload even starts. The default always returns Ok(), i.e. it accepts all requests.
- since
- 0.6
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.
- since
- 0.6
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).
- since
- 0.9
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).
- since
- 0.9
val running : t -> boolIs the server running?
- since
- 0.14
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.
- parameter after_init
is called after the server starts listening. since 0.13 .
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.
- since
- 0.14
Module type Tiny_httpd_server.IO_BACKEND
A 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 init_addr : unit -> stringInitial TCP address
val init_port : unit -> intInitial port
val get_time_s : unit -> floatObtain the current timestamp in seconds.
val tcp_server : unit -> Tiny_httpd_io.TCP_server.builderTCP server builder, to create servers that can listen on a port and handle clients.
Set 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).
val send_event : ?event:string -> ?id:string -> ?retry:string -> data:string -> unit -> unitSend an event from the server. If data is a multiline string, it will be sent on separate "data:" lines.
val close : unit -> unitClose connection.
- since
- 0.11
Module Tiny_httpd_stream
Byte 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.
- since
- 0.12
type hiddenType used to make t unbuildable via a record literal. Use make instead.
type t = {mutable bs : bytes; | The bytes |
mutable off : int; | Beginning of valid slice in bs |
mutable len : int; | Length of valid slice in bs. If len = 0 after a call to fill, then the stream is finished. |
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; | Use make to build a stream. |
}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)- if
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;
+ );
+ len
val 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.
- since
- 0.14
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
- since
- 0.3
val to_chan : Stdlib.out_channel -> t -> unitWrite the stream to the channel.
- since
- 0.3
val to_chan' : Tiny_httpd_io.Output.t -> t -> unitWrite to the IO channel.
- since
- 0.14
val to_writer : t -> Tiny_httpd_io.Writer.tTurn this stream into a writer.
- since
- 0.14
val make : ?bs:bytes -> ?close:(t -> unit) -> consume:(t -> int -> unit) -> fill:(t -> unit) -> unit -> tmake ~fill () creates a byte stream.
- parameter fill
is used to refill the buffer, and is called initially.
- parameter close
optional closing.
- parameter init_size
size of the buffer.
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.
- parameter buf
a buffer to (re)use. Its content will be cleared.
val read_all : ?buf:Tiny_httpd_buf.t -> t -> stringRead the whole stream into a string.
- parameter buf
a buffer to (re)use. Its content will be cleared.
val limit_size_to : close_rec:bool -> max_size:int -> too_big:(int -> unit) -> t -> tval 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.
- parameter buf
buffer used for intermediate storage.
- parameter fail
used to build an exception if reading fails.
val read_exactly : close_rec:bool -> size:int -> too_short:(int -> unit) -> t -> tread_exactly ~size bs returns a new stream that reads exactly size bytes from bs, and then closes.
- parameter close_rec
if true, closing the resulting stream also closes bs
- parameter too_short
is called if bs closes with still n bytes remaining
val output_chunked : ?buf:Tiny_httpd_buf.t -> Stdlib.out_channel -> t -> unitWrite the stream into the channel, using the chunked encoding.
- parameter buf
optional buffer for chunking (since 0.14)
val output_chunked' : ?buf:Tiny_httpd_buf.t -> Tiny_httpd_io.Output.t -> t -> unitWrite the stream into the channel, using the chunked encoding.
- since
- 0.14
Module Tiny_httpd_util
Some utils for writing web servers
- since
- 0.2
val percent_encode : ?skip:(char -> bool) -> string -> stringEncode the string into a valid path following https://tools.ietf.org/html/rfc3986#section-2.1
- parameter skip
if provided, allows to preserve some characters, e.g. '/' in a path.
val percent_decode : string -> string optionInverse operation of percent_encode. Can fail since some strings are not valid percent encodings.
val split_query : string -> string * stringSplit a path between the path and the query
- since
- 0.5
val split_on_slash : string -> string listSplit a string on '/', remove the trailing '/' if any.
- since
- 0.6
val get_non_query_path : string -> stringget the part of the path that is not the query parameters.
- since
- 0.5
val get_query : string -> stringObtain the query part of a path.
- since
- 0.4
val parse_query : string -> ((string * string) list, string) Stdlib.resultParse a query as a list of '&' or ';' separated key=value pairs. The order might not be preserved.
- since
- 0.3
Module Tiny_httpd_util
Some utils for writing web servers
- since
- 0.2
val percent_encode : ?skip:(char -> bool) -> string -> stringEncode the string into a valid path following https://tools.ietf.org/html/rfc3986#section-2.1
- parameter skip
if provided, allows to preserve some characters, e.g. '/' in a path.
val percent_decode : string -> string optionInverse operation of percent_encode. Can fail since some strings are not valid percent encodings.
val split_query : string -> string * stringSplit a path between the path and the query
- since
- 0.5
val split_on_slash : string -> string listSplit a string on '/', remove the trailing '/' if any.
- since
- 0.6
val get_non_query_path : string -> stringget the part of the path that is not the query parameters.
- since
- 0.5
val get_query : string -> stringObtain the query part of a path.
- since
- 0.4
val parse_query : string -> ((string * string) list, string) Stdlib.resultParse a query as a list of '&' or ';' separated key=value pairs. The order might not be preserved.
- since
- 0.3
tiny_httpd index
Library tiny_httpd
This library exposes the following toplevel modules:
Module Tiny_httpd_camlzip
Middleware 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.
- parameter compress_above
threshold, in bytes, above which a response body that has a known content-length is compressed. Stream bodies are always compressed.
- parameter buf_size
size of the underlying buffer for compression/decompression
- since
- 0.11
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
- parameter compress_above
threshold above with string responses are compressed
- parameter buf_size
size of the underlying buffer for compression/decompression
tiny_httpd_camlzip index
Library tiny_httpd_camlzip
The entry point of this library is the module: Tiny_httpd_camlzip.
tiny_httpd_camlzip index
Library tiny_httpd_camlzip
The entry point of this library is the module: Tiny_httpd_camlzip.