package opium

You can search for identifiers within the package.

in-package search v0.2.0

On This Page

Working with stream bodies
Constructors
1. make
2. get
3. post
4. put
5. delete
6. of_plain_text
7. of_json
8. of_urlencoded
Decoders
Getters and Setters
Utilities

opium
- Opium
  - App
  - Auth
    
    Challenge
    
    Credential
  - Body
  - Context
    
    Key
  - Cookie
    
    Signer
  - Handler
  - Headers
  - Method
  - Middleware
  - Request
  - Response
  - Route
  - Router
  - Status
  - Version

Legend:
Library
Module
Module type
Parameter
Class
Class type

Module to create and work with HTTP requests.

It offers convenience functions to read headers, decode a request body or URI.

The requests are most likely provided to you by Opium when you are writing your application, but this module contains all the constructors and setters that you need to initialize new requests.

Working with stream bodies

All the functions in this module will clone the stream before reading from it, so you can process the body multiple times if needed. Just make sure that you didn't drain the body before calling a function that reads from it.

Functions from other modules may drain the body stream. You can use Body.copy to copy the body yourself.

type t = Rock.Request.t = {

version : Version.t;
target : string;
headers : Headers.t;
meth : Method.t;
body : Body.t;
env : Context.t;

}

Constructors

`make`

val make : 
  ?version:Version.t ->
  ?body:Body.t ->
  ?env:Context.t ->
  ?headers:Headers.t ->
  string ->
  Method.t ->
  t

make ?version ?body ?env ?headers target method creates a new request from the given values.

By default, the HTTP version will be set to 1.1 and the request will not contain any header or body.

`get`

val get : 
  ?version:Version.t ->
  ?body:Body.t ->
  ?env:Context.t ->
  ?headers:Headers.t ->
  string ->
  t

get ?version ?body ?env ?headers target creates a new GET request from the given values.

By default, the HTTP version will be set to 1.1 and the request will not contain any header or body.

`post`

val post : 
  ?version:Version.t ->
  ?body:Body.t ->
  ?env:Context.t ->
  ?headers:Headers.t ->
  string ->
  t

post ?version ?body ?env ?headers target creates a new POST request from the given values.

By default, the HTTP version will be set to 1.1 and the request will not contain any header or body.

`put`

val put : 
  ?version:Version.t ->
  ?body:Body.t ->
  ?env:Context.t ->
  ?headers:Headers.t ->
  string ->
  t

put ?version ?body ?env ?headers target creates a new PUT request from the given values.

By default, the HTTP version will be set to 1.1 and the request will not contain any header or body.

`delete`

val delete : 
  ?version:Version.t ->
  ?body:Body.t ->
  ?env:Context.t ->
  ?headers:Headers.t ->
  string ->
  t

delete ?version ?body ?env ?headers target creates a new DELETE request from the given values.

By default, the HTTP version will be set to 1.1 and the request will not contain any header or body.

`of_plain_text`

val of_plain_text : 
  ?version:Version.t ->
  ?headers:Headers.t ->
  ?env:Context.t ->
  body:string ->
  string ->
  Method.t ->
  t

of_plain_text ?version ?headers ?env ~body target method creates a new request from the given values and a string body.

The content type of the request will be set to text/plain and the body will contain the string body.

Example

The request initialized with:

Request.of_plain_text ~body:"Hello World" "/target" `POST

Will be represented as:

POST /target HTTP/HTTP/1.1
Content-Type: text/plain

Hello World

`of_json`

val of_json : 
  ?version:Version.t ->
  ?headers:Headers.t ->
  ?env:Context.t ->
  body:Yojson.Safe.t ->
  string ->
  Method.t ->
  t

of_json ?version ?headers ?env ~body target method creates a new request from the given values and a json body.

The content type of the request will be set to application/json and the body will contain the json payload body.

Example

The request initialized with:

Request.of_json ~body:(`Assoc [ "Hello", `String "World" ]) "/target" `POST

Will be represented as:

POST /target HTTP/HTTP/1.1
Content-Type: application/json

{"Hello":"World"}

`of_urlencoded`

val of_urlencoded : 
  ?version:Version.t ->
  ?headers:Headers.t ->
  ?env:Context.t ->
  body:(string * string list) list ->
  string ->
  Method.t ->
  t

of_urlencoded ?version ?headers ?env ~body target method creates a new request from the given values and a urlencoded body.

The content type of the request will be set to application/x-www-form-urlencoded and the body will contain the key value pairs body formatted in the urlencoded format.

Example

The request initialized with:

Request.of_urlencoded ~body:[ "key", [ "value" ] ] "/target" `POST

Will be represented as:

POST /target HTTP/HTTP/1.1
Content-Type: application/x-www-form-urlencoded

key=value

Decoders

`to_plain_text`

val to_plain_text : t -> string Lwt.t

to_plain_text t parses the body of the request t as a string.

Example

let request = Request.of_plain_text "Hello world!"
let body = Request.to_json request

body will be:

"Hello world!"

`to_json`

val to_json : t -> Yojson.Safe.t option Lwt.t

to_json t parses the body of the request t as a JSON structure.

If the body of the request cannot be parsed as a JSON structure, None is returned. Use to_json_exn to raise an exception instead.

Example

let request = Request.of_json (`Assoc [ "Hello", `String "World" ])
let body = Request.to_json request

body will be:

`Assoc [ "Hello", `String "World" ]

`to_json_exn`

val to_json_exn : t -> Yojson.Safe.t Lwt.t

to_json_exn t parses the body of the request t as a JSON structure.

If the body of the request cannot be parsed as a JSON structure, an Invalid_argument exception is raised. Use to_json to return an option instead.

`to_urlencoded`

val to_urlencoded : t -> (string * string list) list Lwt.t

to_urlencoded t parses the body of the request t from a urlencoded format to a list of key-values pairs.

This function exist to offer a simple way to get all of the key-values pairs, but most of the time, you'll probably only want the value of a key given. If you don't need the entire list of values, it is recommended to use urlencoded instead.

If the body of the request cannot be parsed as a urlencoded string, an empty list is returned.

Example

let request =
  Request.of_urlencoded
    ~body:[ "username", [ "admin" ]; "password", [ "password" ] ]
    "/"
    `POST
;;

let values = Request.to_urlencoded request

values will be:

[ "username", [ "admin" ]; "password", [ "password" ] ]

`to_multipart_form_data`

val to_multipart_form_data : 
  ?callback:(name:string -> filename:string -> string -> unit Lwt.t) ->
  t ->
  (string * string) list option Lwt.t

to_multipart_form_data ?callback t parses the body of the request t from a multipart/form-data format to a list of key-values pairs.

The request has to to contain a Content-Type header with a value multipart/form-data and the HTTP method has to be POST, otherwise the request will not be parsed an None will be returned. See to_multipart_form_data_exn to raise an exception instead.

If the body of the request cannot be parsed as a multipart/form-data string, an empty list is returned.

When provided, the callback is a function of type val _ : ~filename:string ~name:string string -> Lwt.unit that is called for each part of the body.

`to_multipart_form_data_exn`

val to_multipart_form_data_exn : 
  ?callback:(name:string -> filename:string -> string -> unit Lwt.t) ->
  t ->
  (string * string) list Lwt.t

to_multipart_form_data_exn ?callback t parses the body of the request t from a multipart/form-data format to a list of key-values pairs.

The request has to to contain a Content-Type header with a value multipart/form-data and the HTTP method has to be POST, otherwise the request will not be parsed and an Invalid_argument exception will be raised. See to_multipart_form_data to return an option instead.

If the body of the request cannot be parsed as a multipart/form-data string, an empty list is returned.

When provided, the callback is a function of type val _ : ~filename:string ~name:string string -> Lwt.unit that is called for each part of the body.

Getters and Setters

General Headers

`header`

val header : string -> t -> string option

header key t returns the value of the header with key key in the request t.

If multiple headers have the key key, only the value of the first header will be returned.

If you want to return all the values if multiple headers are found, you can use headers.

`headers`

val headers : string -> t -> string list

headers returns the values of all headers with the key key in the request t.

If you want to return the value of only the first header with the key key, you can use header.

`add_header`

val add_header : (string * string) -> t -> t

add_header (key, value) t adds a header with the key key and the value value to the request t.

If a header with the same key is already persent, a new header is appended to the list of headers regardless. If you want to add the header only if an header with the same key could not be found, you can use add_header_unless_exists.

See also add_headers to add multiple headers.

`add_header_or_replace`

val add_header_or_replace : (string * string) -> t -> t

add_header_or_replace (key, value) t adds a header with the key key and the value value to the request t.

If a header with the same key already exist, its value is replaced by value. If you want to add the header only if it doesn't already exist, you can use add_header_unless_exists.

See also add_headers_or_replace to add multiple headers.

`add_header_unless_exists`

val add_header_unless_exists : (string * string) -> t -> t

add_header_unless_exists (key, value) t adds a header with the key key and the value value to the request t if an header with the same key does not already exist.

If a header with the same key already exist, the request remains unmodified. If you want to add the header regardless of whether the header is already present, you can use add_header.

See also add_headers_unless_exists to add multiple headers.

`add_headers`

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

add_headers headers t adds the headers headers to the request t.

The headers are added regardless of whether a header with the same key is already present. If you want to add the header only if an header with the same key could not be found, you can use add_headers_unless_exists.

See also add_header to add a single header.

`add_headers_or_replace`

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

add_headers_or_replace (key, value) t adds a headers headers to the request t.

If a header with the same key already exist, its value is replaced by value. If you want to add the header only if it doesn't already exist, you can use add_headers_unless_exists.

See also add_header_or_replace to add a single header.

`add_headers_unless_exists`

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

add_headers_unless_exists headers t adds the headers headers to the request t if an header with the same key does not already exist.

If a header with the same key already exist, the header is will not be added to the request. If you want to add the header regardless of whether the header is already present, you can use add_headers.

See also add_header_unless_exists to add a single header.

`remove_header`

val remove_header : string -> t -> t

remove_header (key, value) t removes all the headers with the key key from the request t.

If no header with the key key exist, the request remains unmodified.

Specific Headers

`content_type`

val content_type : t -> string option

content_type t returns the value of the header Content-Type of the request t.

`set_content_type`

val set_content_type : string -> t -> t

set_content_type content_type t returns a copy of t with the value of the header Content-Type set to content_type.

`authorization`

val authorization : t -> Auth.Credential.t option

authorization t returns the value of the header Authorization of the request t.

`set_authorization`

val set_authorization : Auth.Credential.t -> t -> t

set_authorization authorization t returns a copy of t with the value of the header Authorization set to authorization.

Cookies

`cookie`

val cookie : ?signed_with:Cookie.Signer.t -> string -> t -> string option

cookie ?signed_with key t returns the value of the cookie with key key in the Cookie header of the request t.

If signed_with is provided, the cookies will be unsigned with the given Signer and only a cookie with a valid signature will be returned.

If the request does not contain a valid Cookie or if no cookie with the key key exist, None will be returned.

`cookies`

val cookies : ?signed_with:Cookie.Signer.t -> t -> Cookie.value list

cookies ?signed_with t returns all the value of the cookies in the Cookie header of the request t.

If signed_with is provided, the cookies will be unsigned with the given Signer and only the cookies with a valid signature will be returned.

If the request does not contain a valid Cookie, None will be returned.

`add_cookie`

val add_cookie : ?sign_with:Cookie.Signer.t -> Cookie.value -> t -> t

add_cookie ?sign_with ?expires ?scope ?same_site ?secure ?http_only value t adds a cookie with value value to the request t.

If a cookie with the same key already exists, its value will be replaced with the new value of value.

If sign_with is provided, the cookie will be signed with the given Signer.

`add_cookie_unless_exists`

val add_cookie_unless_exists : 
  ?sign_with:Cookie.Signer.t ->
  Cookie.value ->
  t ->
  t

add_cookie_unless_exists ?sign_with ?expires ?scope ?same_site ?secure ?http_only value t adds a cookie with value value to the request t.

If a cookie with the same key already exists, it will remain untouched.

If sign_with is provided, the cookie will be signed with the given Signer.

`remove_cookie`

val remove_cookie : string -> t -> t

remove_cookie key t removes the cookie of key key from the Cookie header of the request t.

Body

`urlencoded`

val urlencoded : string -> t -> string option Lwt.t

urlencoded key t returns the first value associated to key in the urlencoded body of the request t.

The function only returns the first value for the given key, because in the great majority of cases, there is only one parameter per key. If you want to return all the values associated to the key, you can use to_urlencoded.

If the key could not be found or if the request could not be parsed as urlencoded, None is returned. Use urlencoded_exn to raise an exception instead.

Example

let request =
  Request.of_urlencoded
    ~body:[ "username", [ "admin" ]; "password", [ "password" ] ]
    "/"
    `POST
;;

let username = Request.urlencoded "username" request

username will be:

Some "admin"

`urlencoded_exn`

val urlencoded_exn : string -> t -> string Lwt.t

urlencoded_exn key t returns the first value associated to key in the urlencoded body of the request t.

The function only returns the first value for the given key, because in the great majority of cases, there is only one parameter per key. If you want to return all the values associated to the key, you can use to_urlencoded.

If the key could not be found or if the request could not be parsed as urlencoded, an Invalid_argument exception is raised. Use urlencoded to return an option instead.

`urlencoded_list`

val urlencoded_list : string -> t -> string list Lwt.t

urlencoded_list key t returns all the values associated to key in the urlencoded body of the request t.

If the key could not be found or if the request could not be parsed as urlencoded, an empty list [] is returned instead.

URI

`query`

val query : string -> t -> string option

query key t returns the first value associated to key in the URI query parameters of the request t.

The function only returns the first value for the given key, because in the great majority of cases, there is only one parameter per key. If you want to return all the values associated to the key, you can use query_list.

If the key could not be found or if the request URI does not contain any query parameter, None is returned. Use query_exn to raise an exception instead.

Example

let request = Request.make "/target?key=value" `GET
let query = Request.query "key" request

query will be:

Some "value"

`query_exn`

val query_exn : string -> t -> string

query_exn key t returns the first value associated to key in the URI query parameters of the request t.

The function only returns the first value for the given key, because in the great majority of cases, there is only one parameter per key. If you want to return all the values associated to the key, you can use query_list.

If the key could not be found or if the request URI does not contain any query parameter, an Invalid_argument exception is raised. Use query to return an option instead.

`query_list`

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

query_list key t returns all the values associated to key in the URI query parameters of the request t.

This function exist to offer a simple way to get all of the values associated to a key, but most of the time, there is only one value per key. If you're not specifically trying to decode a request with multiple values per key, it is recommended to use query instead.

If the key could not be found or if the request could not be parsed as query, an empty list is returned.

Example

let request = Request.make "/target?key=value&key2=value2" `GET
let values = Request.query_list request

values will be:

[ "key", [ "value" ]; "key2", [ "value2" ] ]

Utilities

`sexp_of_t`

val sexp_of_t : t -> Sexplib0.Sexp.t

sexp_of_t t converts the request t to an s-expression

`pp`

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

pp formats the request t as an s-expression

`pp_hum`

val pp_hum : Format.formatter -> t -> unit

pp_hum formats the request t as a standard HTTP request