Module `Trail.Conn`Source

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

Sourcetype peer = {

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

}

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

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

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

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

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

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

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

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

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

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

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

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

Send a response with a status but no body

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

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

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

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

chunk data conn will send data to the streamed connection.

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

Sourcetype 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 ]

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

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

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

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

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

Sourceval close : t -> t

close conn will mark this connection as closed.

package trail

Module Trail.ConnSource

Module `Trail.Conn`Source