From 89602232b3b0af777e3aa3541264f70d568b984f Mon Sep 17 00:00:00 2001 From: c-cube Date: Wed, 24 May 2023 19:50:48 +0000 Subject: [PATCH] deploy: 163d7206415a11a51f30baa3c6b142dc1de63dbe --- dev/tiny_httpd/Tiny_httpd/index.html | 10 +++++----- dev/tiny_httpd/Tiny_httpd_server/Headers/index.html | 2 +- dev/tiny_httpd/Tiny_httpd_server/Middleware/index.html | 2 +- dev/tiny_httpd/Tiny_httpd_server/Request/index.html | 2 +- dev/tiny_httpd/Tiny_httpd_server/Response/index.html | 4 ++-- dev/tiny_httpd/Tiny_httpd_server/Route/index.html | 2 +- dev/tiny_httpd/Tiny_httpd_server/index.html | 8 ++++---- dev/tiny_httpd/Tiny_httpd_stream/index.html | 2 +- dev/tiny_httpd/index.html | 2 +- dev/tiny_httpd_camlzip/Tiny_httpd_camlzip/index.html | 4 ++-- 10 files changed, 19 insertions(+), 19 deletions(-) diff --git a/dev/tiny_httpd/Tiny_httpd/index.html b/dev/tiny_httpd/Tiny_httpd/index.html index c6a51dbc..403f6782 100644 --- a/dev/tiny_httpd/Tiny_httpd/index.html +++ b/dev/tiny_httpd/Tiny_httpd/index.html @@ -1,5 +1,5 @@ -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
+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
@@ -49,7 +49,7 @@ echo:
          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.
module Buf = Tiny_httpd_buf
Generic stream of data
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.
module Byte_stream = Tiny_httpd_stream
Main Server Type
type buf = Tiny_httpd_buf.t
type byte_stream = Tiny_httpd_stream.t
Methods
Headers
Headers are metadata associated with a request or response.
module Headers = Tiny_httpd_server.Headers
Requests
Requests are sent by a client, e.g. a web browser or cURL.
module Request = Tiny_httpd_server.Request
Response Codes
module Response_code = Tiny_httpd_server.Response_code
Responses
Responses are what a http server, such as Tiny_httpd, send back to the client to answer a Request.t
module Response = Tiny_httpd_server.Response
module Middleware = Tiny_httpd_server.Middleware
Main Server type
A HTTP server. See create for more details.
val create : 
+ 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.

module Buf = Tiny_httpd_buf

Generic byte streams

module Byte_stream = Tiny_httpd_stream

Main Server Type

type buf = Tiny_httpd_buf.t
type byte_stream = Tiny_httpd_stream.t
HTTP Methods
Headers

Headers are metadata associated with a request or response.

module Headers = Tiny_httpd_server.Headers
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.

module Request = Tiny_httpd_server.Request
Response Codes
module Response_code = Tiny_httpd_server.Response_code
Responses

Responses are what a http server, such as Tiny_httpd, send back to the client to answer a Request.t

module Response = Tiny_httpd_server.Response
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.

  • since 0.6
Middlewares

A middleware can be inserted in a handler to modify or observe its behavior.

  • since 0.11
module Middleware = Tiny_httpd_server.Middleware
Main Server type

A HTTP server. See create for more details.

val create : ?masksigpipe:bool -> ?max_connections:int -> ?timeout:float -> @@ -61,7 +61,7 @@ echo: ?sock:Unix.file_descr -> ?middlewares:([ `Encoding | `Stage of int ] * Middleware.t) list -> unit -> - t

Create a new webserver.

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.

  • 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.

val addr : t -> string

Address on which the server listens.

val is_ipv6 : t -> bool

is_ipv6 server returns true iff the address of the server is an IPv6 address.

  • since 0.3
val port : t -> int

Port on which the server listens.

val active_connections : t -> int

Number of active connections

val add_decode_request_cb : + t

Create a new webserver.

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.

  • 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.

val addr : t -> string

Address on which the server listens.

val is_ipv6 : t -> bool

is_ipv6 server returns true iff the address of the server is an IPv6 address.

  • since 0.3
val port : t -> int

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 -> int

Number of currently active connections.

val add_decode_request_cb : t -> (unit Request.t -> (unit Request.t * (byte_stream -> byte_stream)) option) -> unit

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.

val add_encode_response_cb : @@ -85,9 +85,9 @@ echo: t -> ('a, byte_stream Request.t -> Response.t) Route.t -> 'a -> - unit

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.

  • since 0.6
Server-sent events

EXPERIMENTAL: this API is not stable yet.

module type SERVER_SENT_GENERATOR = Tiny_httpd_server.SERVER_SENT_GENERATOR

A server-side function to generate of Server-sent events.

type server_sent_generator = (module SERVER_SENT_GENERATOR)

Server-sent event generator

  • since 0.9
val add_route_server_sent_handler : + unit

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.

  • since 0.6
Server-sent events

EXPERIMENTAL: this API is not stable yet.

module type SERVER_SENT_GENERATOR = Tiny_httpd_server.SERVER_SENT_GENERATOR

A 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 -> - unit

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).

  • since 0.9
Run the server
val stop : t -> unit

Ask the server to stop. This might not have an immediate effect as run might currently be waiting on IO.

val run : t -> (unit, exn) Stdlib.result

Run 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.

Utils

module Util = Tiny_httpd_util

Static directory serving

module Dir = Tiny_httpd_dir
module Html = Tiny_httpd_html

Alias to Tiny_httpd_html

\ No newline at end of file + unit

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
val stop : t -> unit

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.result

Run 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 NEXT_RELEASE .

Utils

module Util = Tiny_httpd_util

Static directory serving

module Dir = Tiny_httpd_dir
module Html = Tiny_httpd_html

Alias to Tiny_httpd_html

\ No newline at end of file diff --git a/dev/tiny_httpd/Tiny_httpd_server/Headers/index.html b/dev/tiny_httpd/Tiny_httpd_server/Headers/index.html index 0def9442..4ff41616 100644 --- a/dev/tiny_httpd/Tiny_httpd_server/Headers/index.html +++ b/dev/tiny_httpd/Tiny_httpd_server/Headers/index.html @@ -1,2 +1,2 @@ -Headers (tiny_httpd.Tiny_httpd_server.Headers)

Module Tiny_httpd_server.Headers

type t = (string * string) list

The 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 : t

Empty list of headers

  • since 0.5
val get : ?f:(string -> string) -> string -> t -> string option

get 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 -> t

set k v headers sets the key k to value v. It erases any previous entry for k

val remove : string -> t -> t

Remove the key from the headers, if present.

val contains : string -> t -> bool

Is there a header with the given key?

val pp : Stdlib.Format.formatter -> t -> unit

Pretty print the headers.

\ No newline at end of file +Headers (tiny_httpd.Tiny_httpd_server.Headers)

Module Tiny_httpd_server.Headers

type t = (string * string) list

The 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 : t

Empty list of headers.

  • since 0.5
val get : ?f:(string -> string) -> string -> t -> string option

get 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 -> t

set k v headers sets the key k to value v. It erases any previous entry for k

val remove : string -> t -> t

Remove the key from the headers, if present.

val contains : string -> t -> bool

Is there a header with the given key?

val pp : Stdlib.Format.formatter -> t -> unit

Pretty print the headers.

\ No newline at end of file diff --git a/dev/tiny_httpd/Tiny_httpd_server/Middleware/index.html b/dev/tiny_httpd/Tiny_httpd_server/Middleware/index.html index eb818850..e9c30121 100644 --- a/dev/tiny_httpd/Tiny_httpd_server/Middleware/index.html +++ b/dev/tiny_httpd/Tiny_httpd_server/Middleware/index.html @@ -1,2 +1,2 @@ -Middleware (tiny_httpd.Tiny_httpd_server.Middleware)

Module Tiny_httpd_server.Middleware

Middlewares

A middleware can be inserted in a handler to modify or observe its behavior.

type handler = byte_stream Request.t -> resp:(Response.t -> unit) -> unit

Handlers 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 -> handler

A middleware is a handler transformation.

It takes the existing handler h, and returns a new one which, given a query, modify it or log it before passing it to h, or fail. It can also log or modify or drop the response.

val nil : t

Trivial middleware that does nothing.

\ No newline at end of file +Middleware (tiny_httpd.Tiny_httpd_server.Middleware)

Module Tiny_httpd_server.Middleware

type handler = byte_stream Request.t -> resp:(Response.t -> unit) -> unit

Handlers 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 -> handler

A middleware is a handler transformation.

It takes the existing handler h, and returns a new one which, given a query, modify it or log it before passing it to h, or fail. It can also log or modify or drop the response.

val nil : t

Trivial middleware that does nothing.

\ No newline at end of file diff --git a/dev/tiny_httpd/Tiny_httpd_server/Request/index.html b/dev/tiny_httpd/Tiny_httpd_server/Request/index.html index cb4829fc..d8af39d7 100644 --- a/dev/tiny_httpd/Tiny_httpd_server/Request/index.html +++ b/dev/tiny_httpd/Tiny_httpd_server/Request/index.html @@ -1,2 +1,2 @@ -Request (tiny_httpd.Tiny_httpd_server.Request)

Module Tiny_httpd_server.Request

type 'body t = private {
  1. meth : Meth.t;
  2. host : string;
  3. headers : Headers.t;
  4. http_version : int * int;
  5. path : string;
  6. path_components : string list;
  7. query : (string * string) list;
  8. body : 'body;
  9. 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 -> unit

Pretty print the request and its body

val pp_ : Stdlib.Format.formatter -> _ t -> unit

Pretty print the request without its body

val headers : _ t -> Headers.t

List of headers of the request, including "Host"

val get_header : ?f:(string -> string) -> _ t -> string -> string option
val get_header_int : _ t -> string -> int option
val set_header : string -> string -> 'a t -> 'a t

set_header k v req sets k: v in the request req's headers.

val update_headers : (Headers.t -> Headers.t) -> 'a t -> 'a t

Modify headers

  • since 0.11
val set_body : 'a -> _ t -> 'a t

set_body b req returns a new query whose body is b.

  • since 0.11
val host : _ t -> string

Host field of the request. It also appears in the headers.

val meth : _ t -> Meth.t

Method for the request.

val path : _ t -> string

Request path.

val query : _ t -> (string * string) list

Decode the query part of the path field

  • since 0.4
val body : 'b t -> 'b

Request body, possibly empty.

val start_time : _ t -> float

time 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 t

Limit the body size to max_size bytes, or return a 413 error.

  • since 0.3
val read_body_full : ?buf_size:int -> byte_stream t -> string t

Read the whole body into a string. Potentially blocking.

  • parameter buf_size

    initial size of underlying buffer (since 0.11)

\ No newline at end of file +Request (tiny_httpd.Tiny_httpd_server.Request)

Module Tiny_httpd_server.Request

type 'body t = private {
  1. meth : Meth.t;
    (*

    HTTP method for this request.

    *)
  2. host : string;
    (*

    Host header, mandatory. It can also be found in headers.

    *)
  3. headers : Headers.t;
    (*

    List of headers.

    *)
  4. http_version : int * int;
    (*

    HTTP version. This should be either 1, 0 or 1, 1.

    *)
  5. path : string;
    (*

    Full path of the requested URL.

    *)
  6. path_components : string list;
    (*

    Components of the path of the requested URL.

    *)
  7. query : (string * string) list;
    (*

    Query part of the requested URL.

    *)
  8. body : 'body;
    (*

    Body of the request.

    *)
  9. 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 -> unit

Pretty print the request and its body. The exact format of this printing is not specified.

val pp_ : Stdlib.Format.formatter -> _ t -> unit

Pretty print the request without its body. The exact format of this printing is not specified.

val headers : _ t -> Headers.t

List of headers of the request, including "Host".

val get_header : ?f:(string -> string) -> _ t -> string -> string option

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.

val get_header_int : _ t -> string -> int option

Same as get_header but also performs a string to integer conversion.

val set_header : string -> string -> 'a t -> 'a t

set_header k v req sets k: v in the request req's headers.

val update_headers : (Headers.t -> Headers.t) -> 'a t -> 'a t

Modify headers using the given function.

  • since 0.11
val set_body : 'a -> _ t -> 'a t

set_body b req returns a new query whose body is b.

  • since 0.11
val host : _ t -> string

Host field of the request. It also appears in the headers.

val meth : _ t -> Meth.t

Method for the request.

val path : _ t -> string

Request path.

val query : _ t -> (string * string) list

Decode the query part of the path field.

  • since 0.4
val body : 'b t -> 'b

Request body, possibly empty.

val start_time : _ t -> float

time 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 t

Limit the body size to max_size bytes, or return a 413 error.

  • since 0.3
val read_body_full : ?buf_size:int -> byte_stream t -> string t

Read the whole body into a string. Potentially blocking.

  • parameter buf_size

    initial size of underlying buffer (since 0.11)

\ No newline at end of file diff --git a/dev/tiny_httpd/Tiny_httpd_server/Response/index.html b/dev/tiny_httpd/Tiny_httpd_server/Response/index.html index 242f2725..a032f347 100644 --- a/dev/tiny_httpd/Tiny_httpd_server/Response/index.html +++ b/dev/tiny_httpd/Tiny_httpd_server/Response/index.html @@ -1,5 +1,5 @@ -Response (tiny_httpd.Tiny_httpd_server.Response)

Module Tiny_httpd_server.Response

type body = [
  1. | `String of string
  2. | `Stream of byte_stream
  3. | `Void
]

Body of a response, either as a simple string, or a stream of bytes, or nothing (for server-sent events).

type t = private {
  1. code : Response_code.t;
    (*

    HTTP response code. See Response_code.

    *)
  2. headers : Headers.t;
    (*

    Headers of the reply. Some will be set by Tiny_httpd automatically.

    *)
  3. body : body;
    (*

    Body of the response. Can be empty.

    *)
}

A response to send back to a client.

val set_body : body -> t -> t

Set the body of the response.

  • since 0.11
val set_header : string -> string -> t -> t

Set a header.

  • since 0.11
val update_headers : (Headers.t -> Headers.t) -> t -> t

Modify headers

  • since 0.11
val set_headers : Headers.t -> t -> t

Set all headers.

  • since 0.11
val set_code : Response_code.t -> t -> t

Set the response code.

  • since 0.11
val make_raw : ?headers:Headers.t -> code:Response_code.t -> string -> t

Make a response from its raw components, with a string body. Use "" to not send a body at all.

val make_raw_stream : +Response (tiny_httpd.Tiny_httpd_server.Response)

Module Tiny_httpd_server.Response

type body = [
  1. | `String of string
  2. | `Stream of byte_stream
  3. | `Void
]

Body of a response, either as a simple string, or a stream of bytes, or nothing (for server-sent events notably).

type t = private {
  1. code : Response_code.t;
    (*

    HTTP response code. See Response_code.

    *)
  2. headers : Headers.t;
    (*

    Headers of the reply. Some will be set by Tiny_httpd automatically.

    *)
  3. body : body;
    (*

    Body of the response. Can be empty.

    *)
}

A response to send back to a client.

val set_body : body -> t -> t

Set the body of the response.

  • since 0.11
val set_header : string -> string -> t -> t

Set a header.

  • since 0.11
val update_headers : (Headers.t -> Headers.t) -> t -> t

Modify headers.

  • since 0.11
val set_headers : Headers.t -> t -> t

Set all headers.

  • since 0.11
val set_code : Response_code.t -> t -> t

Set the response code.

  • since 0.11
val make_raw : ?headers:Headers.t -> code:Response_code.t -> string -> t

Make 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 -> @@ -16,4 +16,4 @@ ?headers:Headers.t -> code:int -> ('a, unit, string, t) Stdlib.format4 -> - 'a

Make 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 -> 'a

Similar to fail but raises an exception that exits the current handler. This should not be used outside of a (path) handler. Example: fail_raise ~code:404 "oh noes, %s not found" "waldo"; never_executed()

val pp : Stdlib.Format.formatter -> t -> unit

Pretty print the response.

\ No newline at end of file + 'a

Make 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 -> 'a

Similar to fail but raises an exception that exits the current handler. This should not be used outside of a (path) handler. Example: fail_raise ~code:404 "oh noes, %s not found" "waldo"; never_executed()

val pp : Stdlib.Format.formatter -> t -> unit

Pretty print the response. The exact format is not specified.

\ No newline at end of file diff --git a/dev/tiny_httpd/Tiny_httpd_server/Route/index.html b/dev/tiny_httpd/Tiny_httpd_server/Route/index.html index 8ab7d489..bfda0b32 100644 --- a/dev/tiny_httpd/Tiny_httpd_server/Route/index.html +++ b/dev/tiny_httpd/Tiny_httpd_server/Route/index.html @@ -1,2 +1,2 @@ -Route (tiny_httpd.Tiny_httpd_server.Route)

Module Tiny_httpd_server.Route

Routing

Basic type-safe routing.

type ('a, 'b) comp

An atomic component of a path

type ('a, 'b) t

A route, composed of path components

val int : (int -> 'a, 'a) comp

Matches an integer.

val string : (string -> 'a, 'a) comp

Matches a string not containing '/' and binds it as is.

val string_urlencoded : (string -> 'a, 'a) comp

Matches a URL-encoded string, and decodes it.

val exact : string -> ('a, 'a) comp

exact "s" matches "s" and nothing else.

val return : ('a, 'a) t

Matches the empty path.

val rest_of_path : (string -> 'a, 'a) t

Matches a string, even containing '/'. This will match the entirety of the remaining route.

  • since 0.7
val rest_of_path_urlencoded : (string -> 'a, 'a) t

Matches 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) t

comp / route matches "foo/bar/…" iff comp matches "foo", and route matches "bar/…".

val exact_path : string -> ('a, 'b) t -> ('a, 'b) t

exact_path "foo/bar/..." r is equivalent to exact "foo" @/ exact "bar" @/ ... @/ r

  • since 0.11 *
val pp : Stdlib.Format.formatter -> (_, _) t -> unit

Print the route.

  • since 0.7
val to_string : (_, _) t -> string

Print the route.

  • since 0.7
\ No newline at end of file +Route (tiny_httpd.Tiny_httpd_server.Route)

Module Tiny_httpd_server.Route

type ('a, 'b) comp

An atomic component of a path

type ('a, 'b) t

A route, composed of path components

val int : (int -> 'a, 'a) comp

Matches an integer.

val string : (string -> 'a, 'a) comp

Matches a string not containing '/' and binds it as is.

val string_urlencoded : (string -> 'a, 'a) comp

Matches a URL-encoded string, and decodes it.

val exact : string -> ('a, 'a) comp

exact "s" matches "s" and nothing else.

val return : ('a, 'a) t

Matches the empty path.

val rest_of_path : (string -> 'a, 'a) t

Matches a string, even containing '/'. This will match the entirety of the remaining route.

  • since 0.7
val rest_of_path_urlencoded : (string -> 'a, 'a) t

Matches 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) t

comp / route matches "foo/bar/…" iff comp matches "foo", and route matches "bar/…".

val exact_path : string -> ('a, 'b) t -> ('a, 'b) t

exact_path "foo/bar/..." r is equivalent to exact "foo" @/ exact "bar" @/ ... @/ r

  • since 0.11 *
val pp : Stdlib.Format.formatter -> (_, _) t -> unit

Print the route.

  • since 0.7
val to_string : (_, _) t -> string

Print the route.

  • since 0.7
\ No newline at end of file diff --git a/dev/tiny_httpd/Tiny_httpd_server/index.html b/dev/tiny_httpd/Tiny_httpd_server/index.html index 9c653d7c..ca943d08 100644 --- a/dev/tiny_httpd/Tiny_httpd_server/index.html +++ b/dev/tiny_httpd/Tiny_httpd_server/index.html @@ -1,5 +1,5 @@ -Tiny_httpd_server (tiny_httpd.Tiny_httpd_server)

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.

type buf = Tiny_httpd_buf.t
type byte_stream = Tiny_httpd_stream.t

Methods

module Meth : sig ... end

Headers

Headers are metadata associated with a request or response.

module Headers : sig ... end

Requests

Requests are sent by a client, e.g. a web browser or cURL.

module Request : sig ... end

Response Codes

module Response_code : sig ... end

Responses

Responses are what a http server, such as Tiny_httpd, send back to the client to answer a Request.t

module Response : sig ... end
module Route : sig ... end
module Middleware : sig ... end

Main Server type

type t

A HTTP server. See create for more details.

val create : +Tiny_httpd_server (tiny_httpd.Tiny_httpd_server)

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 NEXT_RELEASE
type buf = Tiny_httpd_buf.t
type byte_stream = Tiny_httpd_stream.t

HTTP Methods

module Meth : sig ... end

Headers

Headers are metadata associated with a request or response.

module Headers : sig ... end

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.

module Request : sig ... end

Response Codes

module Response_code : sig ... end

Responses

Responses are what a http server, such as Tiny_httpd, send back to the client to answer a Request.t

module Response : sig ... end

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.

  • since 0.6
module Route : sig ... end

Middlewares

A middleware can be inserted in a handler to modify or observe its behavior.

  • since 0.11
module Middleware : sig ... end

Main Server type

type t

A HTTP server. See create for more details.

val create : ?masksigpipe:bool -> ?max_connections:int -> ?timeout:float -> @@ -11,7 +11,7 @@ ?sock:Unix.file_descr -> ?middlewares:([ `Encoding | `Stage of int ] * Middleware.t) list -> unit -> - t

Create a new webserver.

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.

  • 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.

val addr : t -> string

Address on which the server listens.

val is_ipv6 : t -> bool

is_ipv6 server returns true iff the address of the server is an IPv6 address.

  • since 0.3
val port : t -> int

Port on which the server listens.

val active_connections : t -> int

Number of active connections

val add_decode_request_cb : + t

Create a new webserver.

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.

  • 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.

val addr : t -> string

Address on which the server listens.

val is_ipv6 : t -> bool

is_ipv6 server returns true iff the address of the server is an IPv6 address.

  • since 0.3
val port : t -> int

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 -> int

Number of currently active connections.

val add_decode_request_cb : t -> (unit Request.t -> (unit Request.t * (byte_stream -> byte_stream)) option) -> unit

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.

val add_encode_response_cb : @@ -35,9 +35,9 @@ t -> ('a, byte_stream Request.t -> Response.t) Route.t -> 'a -> - unit

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.

  • since 0.6

Server-sent events

EXPERIMENTAL: this API is not stable yet.

module type SERVER_SENT_GENERATOR = sig ... end

A server-side function to generate of Server-sent events.

type server_sent_generator = (module SERVER_SENT_GENERATOR)

Server-sent event generator

  • since 0.9
val add_route_server_sent_handler : + unit

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.

  • since 0.6

Server-sent events

EXPERIMENTAL: this API is not stable yet.

module type SERVER_SENT_GENERATOR = sig ... end

A 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 -> - unit

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).

  • since 0.9

Run the server

val stop : t -> unit

Ask the server to stop. This might not have an immediate effect as run might currently be waiting on IO.

val run : t -> (unit, exn) Stdlib.result

Run 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.

\ No newline at end of file + unit

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).

  • since 0.9

Run the server

val stop : t -> unit

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.result

Run 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 NEXT_RELEASE .

\ No newline at end of file diff --git a/dev/tiny_httpd/Tiny_httpd_stream/index.html b/dev/tiny_httpd/Tiny_httpd_stream/index.html index 168bb140..7274e1e1 100644 --- a/dev/tiny_httpd/Tiny_httpd_stream/index.html +++ b/dev/tiny_httpd/Tiny_httpd_stream/index.html @@ -1,5 +1,5 @@ -Tiny_httpd_stream (tiny_httpd.Tiny_httpd_stream)

Module Tiny_httpd_stream

Byte streams.

These used to live in Tiny_httpd but are now in their own module.

type hidden

Type used to make t unbuildable via a record literal. Use make instead.

type t = {
  1. mutable bs : bytes;
    (*

    The bytes

    *)
  2. mutable off : int;
    (*

    Beginning of valid slice in bs

    *)
  3. mutable len : int;
    (*

    Length of valid slice in bs. If len = 0 after a call to fill, then the stream is finished.

    *)
  4. 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.

    *)
  5. consume : int -> unit;
    (*

    Consume n bytes from the buffer. This should only be called with n <= len.

    *)
  6. close : unit -> unit;
    (*

    Close the stream.

    *)
  7. _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. See Byte_stream for more details.

val close : t -> unit

Close stream

val empty : t

Stream with 0 bytes inside

val of_chan : ?buf_size:int -> Stdlib.in_channel -> t

Make a buffered stream from the given channel.

val of_chan_close_noerr : ?buf_size:int -> Stdlib.in_channel -> t

Same as of_chan but the close method will never fail.

val of_fd : ?buf_size:int -> Unix.file_descr -> t

Make a buffered stream from the given file descriptor.

val of_fd_close_noerr : ?buf_size:int -> Unix.file_descr -> t

Same as of_fd but the close method will never fail.

val of_bytes : ?i:int -> ?len:int -> bytes -> t

A stream that just returns the slice of bytes starting from i and of length len.

val of_string : string -> t
val iter : (bytes -> int -> int -> unit) -> t -> unit

Iterate on the chunks of the stream

  • since 0.3
val to_chan : Stdlib.out_channel -> t -> unit

Write the stream to the channel.

  • since 0.3
val make : +Tiny_httpd_stream (tiny_httpd.Tiny_httpd_stream)

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 hidden

Type used to make t unbuildable via a record literal. Use make instead.

type t = {
  1. mutable bs : bytes;
    (*

    The bytes

    *)
  2. mutable off : int;
    (*

    Beginning of valid slice in bs

    *)
  3. mutable len : int;
    (*

    Length of valid slice in bs. If len = 0 after a call to fill, then the stream is finished.

    *)
  4. 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.

    *)
  5. consume : int -> unit;
    (*

    Consume n bytes from the buffer. This should only be called with n <= len.

    *)
  6. close : unit -> unit;
    (*

    Close the stream.

    *)
  7. _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. See Byte_stream for more details.

val close : t -> unit

Close stream

val empty : t

Stream with 0 bytes inside

val of_chan : ?buf_size:int -> Stdlib.in_channel -> t

Make a buffered stream from the given channel.

val of_chan_close_noerr : ?buf_size:int -> Stdlib.in_channel -> t

Same as of_chan but the close method will never fail.

val of_fd : ?buf_size:int -> Unix.file_descr -> t

Make a buffered stream from the given file descriptor.

val of_fd_close_noerr : ?buf_size:int -> Unix.file_descr -> t

Same as of_fd but the close method will never fail.

val of_bytes : ?i:int -> ?len:int -> bytes -> t

A stream that just returns the slice of bytes starting from i and of length len.

val of_string : string -> t
val iter : (bytes -> int -> int -> unit) -> t -> unit

Iterate on the chunks of the stream

  • since 0.3
val to_chan : Stdlib.out_channel -> t -> unit

Write the stream to the channel.

  • since 0.3
val make : ?bs:bytes -> ?close:(t -> unit) -> consume:(t -> int -> unit) -> diff --git a/dev/tiny_httpd/index.html b/dev/tiny_httpd/index.html index 9259b96f..e36e7060 100644 --- a/dev/tiny_httpd/index.html +++ b/dev/tiny_httpd/index.html @@ -1,2 +1,2 @@ -index (tiny_httpd.index)

tiny_httpd index

Library tiny_httpd

This library exposes the following toplevel modules:

\ No newline at end of file +index (tiny_httpd.index)

tiny_httpd index

Library tiny_httpd

This library exposes the following toplevel modules:

\ No newline at end of file diff --git a/dev/tiny_httpd_camlzip/Tiny_httpd_camlzip/index.html b/dev/tiny_httpd_camlzip/Tiny_httpd_camlzip/index.html index 63fa1255..1cf17118 100644 --- a/dev/tiny_httpd_camlzip/Tiny_httpd_camlzip/index.html +++ b/dev/tiny_httpd_camlzip/Tiny_httpd_camlzip/index.html @@ -1,6 +1,6 @@ -Tiny_httpd_camlzip (tiny_httpd_camlzip.Tiny_httpd_camlzip)

Module Tiny_httpd_camlzip

val middleware : +Tiny_httpd_camlzip (tiny_httpd_camlzip.Tiny_httpd_camlzip)

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.t

Middleware responsible for deflate compression/decompression.

  • since 0.11
val setup : ?compress_above:int -> ?buf_size:int -> Tiny_httpd_server.t -> unit

Install 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

\ No newline at end of file + Tiny_httpd_server.Middleware.t

Middleware 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 -> unit

Install 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

\ No newline at end of file