Module Opium.Response
Module to create and work with HTTP responses.
It offers convenience functions to create common responses and update them.
type t
= Rock.Response.t
=
{
version : Version.t;
status : Status.t;
reason : string option;
headers : Headers.t;
body : Body.t;
env : Context.t;
}
Constructors
make
val make : ?version:Version.t -> ?status:Status.t -> ?reason:string -> ?headers:Headers.t -> ?body:Body.t -> ?env:Context.t -> unit -> t
make ?version ?status ?reason ?headers ?body ?env ()
creates a new response from the given values.By default, the HTTP version will be set to 1.1, the HTTP status to 200 and the response will not contain any header or body.
of_plain_text
val of_plain_text : ?version:Version.t -> ?status:Status.t -> ?reason:string -> ?headers:Headers.t -> ?env:Context.t -> string -> t
of_plain_text ?status ?version ?reason ?headers ?env body
creates a new response from the given values and a string body.The content type of the response will be set to
text/plain
and the body will contain the stringbody
.Example
The response initialized with:
Response.of_plain_text "Hello World"
Will be represented as:
HTTP/1.1 200 Content-Type: text/plain Hello World
of_json
val of_json : ?version:Version.t -> ?status:Status.t -> ?reason:string -> ?headers:Headers.t -> ?env:Context.t -> Yojson.Safe.t -> t
of_json ?status ?version ?reason ?headers ?env payload
creates a new response from the given values and a JSON body.The content type of the response will be set to
application/json
and the body will contain the json payloadbody
.Example
The response initialized with:
Response.of_json (`Assoc [ "Hello", `String "World" ])
Will be represented as:
HTTP/1.1 200 Content-Type: application/json {"Hello":"World"}
of_html
val of_html : ?version:Version.t -> ?status:Status.t -> ?reason:string -> ?headers:Headers.t -> ?env:Context.t -> ?indent:bool -> [ `Html ] Tyxml_html.elt -> t
of_html ?status ?version ?reason ?headers ?env ?indent payload
creates a new response from the given values and a HTML body.The content type of the response will be set to
text/html; charset=utf-8
and the body will contain the HTML payloadpayload
.The header
Connection
will be set toKeep-Alive
to opimize for bandwitdh, since it is assumed that users who response HTML content will be likely to make further responses.Example
The response initialized with:
let my_page = let open Tyxml.Html in html (head (title (txt "Title")) []) (body [ h1 [ txt "Hello World!" ] ]) ;; let res = Response.of_html ~indent:true my_page
res
will be represented as:HTTP/1.1 200 Connection: Keep-Alive Content-Type: text/html; charset=utf-8 <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"><head><title>Title</title></head> <body><h1>Hello World!</h1></body> </html>
of_xml
val of_xml : ?version:Version.t -> ?status:Status.t -> ?reason:string -> ?headers:Headers.t -> ?env:Context.t -> ?indent:bool -> Tyxml_xml.elt -> t
of_xml ?status ?version ?reason ?headers ?env ?indent payload
creates a new response from the given values and a XML body.The content type of the response will be set to
text/xml; charset=utf-8
and the body will contain the XML payloadpayload
.Example
The response initialized with:
let xml = let open Tyxml.Xml in node "note" [ node "to" [ pcdata "Tove" ] ; node "from" [ pcdata "Jani" ] ; node "heading" [ pcdata "Reminder" ] ; node "body" [ pcdata "Don't forget me this weekend!" ] ] ;; let res = Response.of_xml ~indent:true xml
res
will be represented as:HTTP/1.1 200 Content-Type: application/xml charset=utf-8 <note><to>Tove</to><from>Jani</from><heading>Reminder</heading> <body>Don't forget me this weekend!</body> </note>
of_svg
val of_svg : ?version:Version.t -> ?status:Status.t -> ?reason:string -> ?headers:Headers.t -> ?env:Context.t -> ?indent:bool -> [ `Svg ] Tyxml_svg.elt -> t
of_svg ?status ?version ?reason ?headers ?env ?indent payload
creates a new response from the given values and a SVG body.The content type of the response will be set to
image/svg+xml
and the body will contain the SVG payloadpayload
.The header
Connection
will be set toKeep-Alive
to opimize for bandwitdh, since it is assumed that users who response SVG content will be likely to make further responses.Example
The response initialized with:
let my_svg = let open Tyxml.Svg in svg [ circle ~a: [ a_cx (50., None) ; a_cy (50., None) ; a_r (40., None) ; a_fill (`Color ("black", None)) ] [] ] ;; let res = Response.of_svg ~indent:true my_svg
res
will be represented as:HTTP/1.1 200 Connection: Keep-Alive Content-Type: image/svg+xml <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> <circle cx="50" cy="50" r="40" fill="black"></circle> </svg>
redirect_to
val redirect_to : ?status:Status.redirection -> ?version:Version.t -> ?reason:string -> ?headers:Headers.t -> ?env:Context.t -> string -> t
redirect_to ?status ?version ?reason ?headers ?env target
creates a new Redirect response from the given values.The response will contain the header
Location
with the valuetarget
and a Redirect HTTP status (a Redirect HTTP status starts with 3).By default, the HTTP status is
302 Found
.The response initialized with:
Response.redirect_to "/redirected"
Will be represented as:
HTTP/1.1 302 Location: /redirected
Decoders
to_json
val to_json : t -> Yojson.Safe.t option Lwt.t
to_json t
parses the body of the responset
as a JSON structure.If the body of the response cannot be parsed as a JSON structure,
None
is returned. Useto_json_exn
to raise an exception instead.Example
let response = Response.of_json (`Assoc [ "Hello", `String "World" ]) let body = Response.to_json response
body
will be:`Assoc [ "Hello", `String "World" ]
to_json_exn
to_plain_text
val to_plain_text : t -> string Lwt.t
to_plain_text t
parses the body of the responset
as a string.Example
let response = Response.of_plain_text "Hello world!" let body = Response.to_json response
body
will be:"Hello world!"
Getters and Setters
status
set_status
General Headers
val header : string -> t -> string option
header key t
returns the value of the header with keykey
in the responset
.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
add_header
val add_header : (string * string) -> t -> t
add_header (key, value) t
adds a header with the keykey
and the valuevalue
to the responset
.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 keykey
and the valuevalue
to the responset
.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 useadd_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 keykey
and the valuevalue
to the responset
if an header with the same key does not already exist.If a header with the same key already exist, the response 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 response
adds the headersheaders
to the responset
.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 headersheaders
to the responset
.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 useadd_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 response
adds the headersheaders
to the responset
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 response. 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
Specific Headers
content_type
val content_type : t -> string option
content_type response
returns the value of the headerContent-Type
of the responseresponse
.
set_content_type
etag
val etag : t -> string option
etag response
returns the value of the headerETag
of the responseresponse
.
set_etag
location
val location : t -> string option
location response
returns the value of the headerLocation
of the responseresponse
.
set_location
cache_control
val cache_control : t -> string option
cache_control response
returns the value of the headerCache-Control
of the responseresponse
.
set_cache_control
cookie
val cookie : ?signed_with:Cookie.Signer.t -> string -> t -> Cookie.t option
cookie ?signed_with key t
returns the value of the cookie with keykey
in theSet-Cookie
header of the responset
.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 response does not contain a valid
Set-Cookie
or if no cookie with the keykey
exist,None
will be returned.
cookies
val cookies : ?signed_with:Cookie.Signer.t -> t -> Cookie.t list
cookies ?signed_with t
returns all the value of the cookies in theSet-Cookie
header of the responset
.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 response does not contain a valid
Set-Cookie
,None
will be returned.
add_cookie
val add_cookie : ?sign_with:Cookie.Signer.t -> ?expires:Cookie.expires -> ?scope:Uri.t -> ?same_site:Cookie.same_site -> ?secure:bool -> ?http_only:bool -> Cookie.value -> t -> t
add_cookie ?sign_with ?expires ?scope ?same_site ?secure ?http_only value t
adds a cookie with valuevalue
to the responset
.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_or_replace
val add_cookie_or_replace : ?sign_with:Cookie.Signer.t -> ?expires:Cookie.expires -> ?scope:Uri.t -> ?same_site:Cookie.same_site -> ?secure:bool -> ?http_only:bool -> Cookie.value -> t -> t
add_cookie_or_replace ?sign_with ?expires ?scope ?same_site ?secure ?http_only value t
adds a cookie with valuevalue
to the responset
. If a cookie with the same key already exists, its value will be replaced with the new value ofvalue
. Ifsign_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 -> ?expires:Cookie.expires -> ?scope:Uri.t -> ?same_site:Cookie.same_site -> ?secure:bool -> ?http_only:bool -> Cookie.value -> t -> t
add_cookie_unless_exists ?sign_with ?expires ?scope ?same_site ?secure ?http_only value t
adds a cookie with valuevalue
to the responset
.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
Utilities
sexp_of_t
val sexp_of_t : t -> Sexplib0.Sexp.t
sexp_of_t t
converts the responset
to an s-expression
pp
val pp : Stdlib.Format.formatter -> t -> unit
pp
formats the responset
as an s-expression
pp_hum
val pp_hum : Stdlib.Format.formatter -> t -> unit
pp_hum
formats the responset
as a standard HTTP response