trail 0.0.1 · OCaml Package

The `Conn` module includes functions for handling an ongoing connection.

type peer = {

ip : Riot.Net.Addr.tcp_addr;
port : int;

}

type t = {

adapter : Adapter.t;
before_send_cbs : (t -> unit) list;
after_send_cbs : (t -> unit) list;
conn : Atacama.Connection.t;
halted : bool;
chunked : bool;
headers : (string * string) list;
meth : Http.Method.t;
path : string;
params : (string * string) list;
peer : peer;
req : Request.t;
resp_body : Riot.Bytestring.t;
status : Http.Status.t;
switch : [ `websocket of Sock.upgrade_opts * Sock.t | `h2c ] option;

}

The core connection type.

A `Conn.t` represents an active connection, and is the main value passed across the trails.

val register_after_send : (t -> unit) -> t -> t

val register_before_send : (t -> unit) -> t -> t

`register_before_send fn` will call the function `fn` with the current connection immediately before any calls to `send`.

This is useful for measuring, performing sanity checks on the connection, or just for logging.

val with_header : string -> string -> t -> t

`with_header header value conn` will add a new header named `header` and set it to the value `value`. Note that only the new connection object will have this header set.

val with_body : Riot.Bytestring.t -> t -> t

`with_body body conn` will set the response body to `body`

val with_status : Http.Status.t -> t -> t

`with_status status conn` will set the response status to `status`

val respond : status:Http.Status.t -> ?body:Riot.Bytestring.t -> t -> t

Set the status code and optionally the response body for a connection.

val send : t -> t

Send a connection. Typically within a trail, once `send` is called, the rest of the trails will be skipped.

If the connection has already been sent, this function will raise an exception.

If the returned connection object is ignored, and the old connection object is used, the underlying socket may already be closed and other operations would raise.

val send_status : Http.Status.t -> t -> t

Send a response with a status but no body

val send_response : Http.Status.t -> Riot.Bytestring.t -> t -> t

Convenience function to set a response and send it in one go.

val send_chunked : Http.Status.t -> t -> t

send_chunked `OK conn initializes a stream response in the connection.

You can use the chunk data conn function to send more data.

val chunk : Riot.Bytestring.t -> t -> t

chunk data conn will send data to the streamed connection.

val set_params : (string * string) list -> t -> t

set_params params conn updates the connection with parameters. Note that this is primarily useful when building connection values that will be handled by user trails.

type read_result =

| Ok of t * Riot.Bytestring.t
| More of t * Riot.Bytestring.t
| Error of t * [ `Excess_body_read | `Closed | `Process_down | `Timeout | Riot.IO.io_error ]

val read_body : ?limit:int -> t -> read_result

read_body ?limit conn will do a read on the body and return a buffer with it. If `limit` is set, the response will be at most of length `limit`.

If there is no more to read, this returns a Ok (conn, buf). If there is more to be read, this returns a More (conn, buf). On errors, this returns an Error (conn, reason).

val send_file : Http.Status.t -> ?off:int -> ?len:int -> path:string -> t -> t

send_file code path conn sets up the connection conn and transfers the file at path with status code code.

val inform : Http.Status.t -> (string * string) list -> t -> t

inform status headers sends an information message back to the client and does not close the connection.

val upgrade : [ `h2c | `websocket of Sock.upgrade_opts * Sock.t ] -> t -> t

upgrade p conn upgrades the connection conn to the new protocol p.

val close : t -> t

close conn will mark this connection as closed.

package trail