<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Http_cookie (http-cookie.Http_cookie)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../odoc.support/odoc.css"/><meta name="generator" content="odoc 2.4.1"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../odoc.support/highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> â€“ <a href="../index.html">http-cookie</a> &#x00BB; Http_cookie</nav><header class="odoc-preamble"><h1>Module <code><span>Http_cookie</span></code></h1><p>A comprehensive and standards compliant HTTP cookies library for ocaml.</p><p>HTTP cookie is serialized as follows:</p><ul><li>In a <code>Cookie</code> header in a HTTP request</li><li>In a <code>Set-Cookie</code> header in a HTTP response.</li></ul><p>The library supports consuming and creating HTTP cookie in both requests and responses.</p><p>The standards implemented by the library is</p><ol><li><a href="https://tools.ietf.org/html/rfc6265">RFC 6265 - Cookies</a>.</li><li><a href="https://datatracker.ietf.org/doc/html/rfc1123">Section 3.3.1 - HTTP Date</a></li><li><a href="https://datatracker.ietf.org/doc/html/rfc1034#section-3.5">Domain Name</a></li><li><a href="https://datatracker.ietf.org/doc/html/rfc1123#section-2.1">Hosts</a></li><li><a href="https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-02#section-3">IPv4/IPv6 Address</a></li></ol></header><nav class="odoc-toc"><ul><li><a href="#pretty-printers">Pretty Printers</a></li><li><a href="#create/decode/encode">Create/Decode/Encode</a></li><li><a href="#cookie-attributes">Cookie Attributes</a></li><li><a href="#compare">Compare</a></li><li><a href="#updates">Updates</a></li></ul></nav><div class="odoc-content"><div class="odoc-spec"><div class="spec type anchored" id="type-t"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span></code></div><div class="spec-doc"><p>A HTTP cookie.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-date_time"><a href="#type-date_time" class="anchor"></a><code><span><span class="keyword">and</span> date_time</span></code></div><div class="spec-doc"><p>normalized date time value in GMT.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-same_site"><a href="#type-same_site" class="anchor"></a><code><span><span class="keyword">and</span> same_site</span><span> = </span><span>[ </span></code><ol><li id="type-same_site.None" class="def variant constructor anchored"><a href="#type-same_site.None" class="anchor"></a><code><span>| </span><span>`None</span></code></li><li id="type-same_site.Lax" class="def variant constructor anchored"><a href="#type-same_site.Lax" class="anchor"></a><code><span>| </span><span>`Lax</span></code></li><li id="type-same_site.Strict" class="def variant constructor anchored"><a href="#type-same_site.Strict" class="anchor"></a><code><span>| </span><span>`Strict</span></code></li></ol><code><span> ]</span></code></div><div class="spec-doc"><p>'Same-site' cookie attribute. <a href="https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00">Same-site</a></p></div></div><h2 id="pretty-printers"><a href="#pretty-printers" class="anchor"></a>Pretty Printers</h2><div class="odoc-spec"><div class="spec value anchored" id="val-pp"><a href="#val-pp" class="anchor"></a><code><span><span class="keyword">val</span> pp : <span><span class="xref-unresolved">Stdlib</span>.Format.formatter <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-pp_same_site"><a href="#val-pp_same_site" class="anchor"></a><code><span><span class="keyword">val</span> pp_same_site : <span><span class="xref-unresolved">Stdlib</span>.Format.formatter <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-same_site">same_site</a> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-pp_date_time"><a href="#val-pp_date_time" class="anchor"></a><code><span><span class="keyword">val</span> pp_date_time : <span><span class="xref-unresolved">Stdlib</span>.Format.formatter <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-date_time">date_time</a> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>pp_date_time fmt date_time</code> pretty prints <a href="#type-date_time"><code>date_time</code></a> in RFC 1123 format.</p><p>Example:</p><pre class="language-ocaml"><code>Sun, 06 Nov 1994 08:49:37 GMT</code></pre></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-pp_rfc1123"><a href="#val-pp_rfc1123" class="anchor"></a><code><span><span class="keyword">val</span> pp_rfc1123 : <span><span class="xref-unresolved">Stdlib</span>.Format.formatter <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-date_time">date_time</a> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p>Alias of <a href="#val-pp_date_time"><code>pp_date_time</code></a>.</p></div></div><h2 id="create/decode/encode"><a href="#create/decode/encode" class="anchor"></a>Create/Decode/Encode</h2><div class="odoc-spec"><div class="spec value anchored" id="val-date_time"><a href="#val-date_time" class="anchor"></a><code><span><span class="keyword">val</span> date_time : 
  <span><span class="label">year</span>:int <span class="arrow">&#45;&gt;</span></span>
  <span><span class="label">month</span>:
    <span>[ `Jan
    <span>| `Feb</span>
    <span>| `Mar</span>
    <span>| `Apr</span>
    <span>| `May</span>
    <span>| `Jun</span>
    <span>| `Jul</span>
    <span>| `Aug</span>
    <span>| `Sep</span>
    <span>| `Oct</span>
    <span>| `Nov</span>
    <span>| `Dec</span> ]</span> <span class="arrow">&#45;&gt;</span></span>
  <span><span class="label">weekday</span>:<span>[ `Sun <span>| `Mon</span> <span>| `Tue</span> <span>| `Wed</span> <span>| `Thu</span> <span>| `Fri</span> <span>| `Sat</span> ]</span> <span class="arrow">&#45;&gt;</span></span>
  <span><span class="label">day</span>:int <span class="arrow">&#45;&gt;</span></span>
  <span><span class="label">hour</span>:int <span class="arrow">&#45;&gt;</span></span>
  <span><span class="label">minutes</span>:int <span class="arrow">&#45;&gt;</span></span>
  <span><span class="label">seconds</span>:int <span class="arrow">&#45;&gt;</span></span>
  <span><span>(<a href="#type-date_time">date_time</a>, string)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div><div class="spec-doc"><p><code>date_time</code> is <code>Ok dt</code> if all of the given parameters are valid for creating <a href="#type-date_time"><code>date_time</code></a> value, otherwise it is <code>Error err</code> where err denotes the error.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-create"><a href="#val-create" class="anchor"></a><code><span><span class="keyword">val</span> create : 
  <span><span class="optlabel">?path</span>:string <span class="arrow">&#45;&gt;</span></span>
  <span><span class="optlabel">?domain</span>:string <span class="arrow">&#45;&gt;</span></span>
  <span><span class="optlabel">?expires</span>:<a href="#type-date_time">date_time</a> <span class="arrow">&#45;&gt;</span></span>
  <span><span class="optlabel">?max_age</span>:int64 <span class="arrow">&#45;&gt;</span></span>
  <span><span class="optlabel">?secure</span>:bool <span class="arrow">&#45;&gt;</span></span>
  <span><span class="optlabel">?http_only</span>:bool <span class="arrow">&#45;&gt;</span></span>
  <span><span class="optlabel">?same_site</span>:<a href="#type-same_site">same_site</a> <span class="arrow">&#45;&gt;</span></span>
  <span><span class="optlabel">?extension</span>:string <span class="arrow">&#45;&gt;</span></span>
  <span><span class="label">name</span>:string <span class="arrow">&#45;&gt;</span></span>
  <span>string <span class="arrow">&#45;&gt;</span></span>
  <span><span>(<a href="#type-t">t</a>, string)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div><div class="spec-doc"><p><code>create ~path ~domain ~expires ~max_age ~secure ~http_only ~same_site ~extension ~name
    value</code> is <code>Ok cookie</code> if all of the given parameters are valid cookie attribute values. Otherwise it is <code>Error error</code> where <code>error</code> is the description of the error.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_cookie"><a href="#val-of_cookie" class="anchor"></a><code><span><span class="keyword">val</span> of_cookie : <span>string <span class="arrow">&#45;&gt;</span></span> <span><span>(<span><a href="#type-t">t</a> list</span>, string)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div><div class="spec-doc"><p><code>of_cookie header</code> parses <code>header</code> - a string value which represents HTTP <code>Cookie</code> header value as defined in <a href="https://tools.ietf.org/html/rfc6265#section-4.2">https://tools.ietf.org/html/rfc6265#section-4.2</a>. It returns a list of <code>Cookie</code>s if it is able to successfully parse <code>s</code>, otherwise it returns <code>Error err</code>.</p><p>It is an error to include duplicate cookie names.</p><p>Examples</p><p>This returns two cookies with cookie names <code>SID</code> and <code>lang</code>.</p><pre class="language-ocaml"><code>Http_cookie.of_cookie &quot;SID=31d4d96e407aad42; lang=en-US&quot;</code></pre></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_cookie"><a href="#val-to_cookie" class="anchor"></a><code><span><span class="keyword">val</span> to_cookie : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> string</span></code></div><div class="spec-doc"><p><code>to_cookie c</code> serializes <code>c</code> into a string which can be encoded as value for HTTP <code>Cookie</code> header.</p><p>Example of a string returned by the function.</p><pre>SID=31d4d96e407aad42</pre></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_set_cookie"><a href="#val-to_set_cookie" class="anchor"></a><code><span><span class="keyword">val</span> to_set_cookie : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> string</span></code></div><div class="spec-doc"><p><code>to_set_cookie c</code> serializes cookie <code>c</code> into a string which can be encoded as value for HTTP <code>Set-Cookie</code> header.</p><p>The datetime format for <code>expires</code> attribute is specified in <a href="https://tools.ietf.org/html/rfc2616#section-3.3.1">RFC 2616</a></p><p>Example of a string returned by the function,</p><pre>SID=31d4d96e407aad42; Path=/; Secure; HttpOnly; Expires=Sun, 06 Nov 1994 08:49:37 GMT</pre></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_set_cookie"><a href="#val-of_set_cookie" class="anchor"></a><code><span><span class="keyword">val</span> of_set_cookie : <span>string <span class="arrow">&#45;&gt;</span></span> <span><span>(<a href="#type-t">t</a>, string)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div><div class="spec-doc"><p><code>of_set_cookie s</code> is <code>Ok cookie</code> if <code>s</code> can be parsed successfully to create <a href="#type-t"><code>t</code></a>.</p><p><code>s</code> is the HTTP 'Set-Cookie' header value. The syntax for the value is defined as <code>set-cookie-string</code> in <a href="https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1">RFC 6265, 4.1</a></p></div></div><h2 id="cookie-attributes"><a href="#cookie-attributes" class="anchor"></a>Cookie Attributes</h2><p>Cookie attributes are defined precisely at <a href="https://tools.ietf.org/html/rfc6265#section-4.1.1">RFC 6262</a></p><div class="odoc-spec"><div class="spec value anchored" id="val-name"><a href="#val-name" class="anchor"></a><code><span><span class="keyword">val</span> name : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> string</span></code></div><div class="spec-doc"><p><code>name t</code> returns a cookie name.</p><p>See <a href="https://tools.ietf.org/html/rfc6265#section-4.1.1">cookie-name</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-value"><a href="#val-value" class="anchor"></a><code><span><span class="keyword">val</span> value : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> string</span></code></div><div class="spec-doc"><p><code>value t</code> returns a cookie value.</p><p>See <a href="https://tools.ietf.org/html/rfc6265#section-4.1.1">cookie-value</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-path"><a href="#val-path" class="anchor"></a><code><span><span class="keyword">val</span> path : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span>string option</span></span></code></div><div class="spec-doc"><p><code>path t</code> returns cookie path attribute.</p><p>See <a href="https://tools.ietf.org/html/rfc6265#section-5.2.4">cookie-path</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-domain"><a href="#val-domain" class="anchor"></a><code><span><span class="keyword">val</span> domain : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span>string option</span></span></code></div><div class="spec-doc"><p><code>domain t</code> returns cookie domain attribute.</p><p>See <a href="https://tools.ietf.org/html/rfc6265#section-4.1.2.3">cookie-domain</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-expires"><a href="#val-expires" class="anchor"></a><code><span><span class="keyword">val</span> expires : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-date_time">date_time</a> option</span></span></code></div><div class="spec-doc"><p><code>expires t</code> returns a coookie expires attribute.</p><p>See <a href="https://tools.ietf.org/html/rfc6265#section-4.1.2.1.">cookie-expires</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-max_age"><a href="#val-max_age" class="anchor"></a><code><span><span class="keyword">val</span> max_age : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span>int64 option</span></span></code></div><div class="spec-doc"><p><code>max_age t</code> returns a cookie max_age attribute.</p><p>See <a href="https://tools.ietf.org/html/rfc6265#section-4.1.2.2">max-age</a> and <a href="https://tools.ietf.org/html/rfc6265#section-4.1.1">max-age-av</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-secure"><a href="#val-secure" class="anchor"></a><code><span><span class="keyword">val</span> secure : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> bool</span></code></div><div class="spec-doc"><p><code>secure t</code> returns a secure attribute.</p><p>See <a href="https://tools.ietf.org/html/rfc6265#section-4.1.2.5">cookie-secure</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-http_only"><a href="#val-http_only" class="anchor"></a><code><span><span class="keyword">val</span> http_only : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> bool</span></code></div><div class="spec-doc"><p><code>http_only t</code> returns a http_only attribute.</p><p>See <a href="https://tools.ietf.org/html/rfc6265#section-4.1.2.6">http-only</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-same_site"><a href="#val-same_site" class="anchor"></a><code><span><span class="keyword">val</span> same_site : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-same_site">same_site</a> option</span></span></code></div><div class="spec-doc"><p><code>same_site t</code> returns a same_site attribute.</p><p>See <a href="https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00">same-site</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-extension"><a href="#val-extension" class="anchor"></a><code><span><span class="keyword">val</span> extension : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span>string option</span></span></code></div><div class="spec-doc"><p><code>extension t</code> returns a cookie extension value.</p><p>See <a href="https://tools.ietf.org/html/rfc6265#section-4.1.1">cookie-extension</a></p></div></div><h2 id="compare"><a href="#compare" class="anchor"></a>Compare</h2><div class="odoc-spec"><div class="spec value anchored" id="val-compare"><a href="#val-compare" class="anchor"></a><code><span><span class="keyword">val</span> compare : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> int</span></code></div><div class="spec-doc"><p><code>compare c1 c2</code> returns <code>0</code> if <code>c1</code> and <code>c2</code> are equal, a positive integer if <code>c1</code> is greater than <code>c2</code> and a negative integer if <code>c1</code> is less than <code>c2</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-compare_date_time"><a href="#val-compare_date_time" class="anchor"></a><code><span><span class="keyword">val</span> compare_date_time : <span><a href="#type-date_time">date_time</a> <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-date_time">date_time</a> <span class="arrow">&#45;&gt;</span></span> int</span></code></div></div><h2 id="updates"><a href="#updates" class="anchor"></a>Updates</h2><div class="odoc-spec"><div class="spec value anchored" id="val-update_value"><a href="#val-update_value" class="anchor"></a><code><span><span class="keyword">val</span> update_value : <span>string <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span><span>(<a href="#type-t">t</a>, string)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-update_name"><a href="#val-update_name" class="anchor"></a><code><span><span class="keyword">val</span> update_name : <span>string <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span><span>(<a href="#type-t">t</a>, string)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-update_path"><a href="#val-update_path" class="anchor"></a><code><span><span class="keyword">val</span> update_path : <span><span>string option</span> <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span><span>(<a href="#type-t">t</a>, string)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-update_domain"><a href="#val-update_domain" class="anchor"></a><code><span><span class="keyword">val</span> update_domain : <span><span>string option</span> <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span><span>(<a href="#type-t">t</a>, string)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-update_expires"><a href="#val-update_expires" class="anchor"></a><code><span><span class="keyword">val</span> update_expires : <span><span><a href="#type-date_time">date_time</a> option</span> <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <a href="#type-t">t</a></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-update_max_age"><a href="#val-update_max_age" class="anchor"></a><code><span><span class="keyword">val</span> update_max_age : <span><span>int64 option</span> <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span><span>(<a href="#type-t">t</a>, string)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-update_secure"><a href="#val-update_secure" class="anchor"></a><code><span><span class="keyword">val</span> update_secure : <span>bool <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <a href="#type-t">t</a></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-update_http_only"><a href="#val-update_http_only" class="anchor"></a><code><span><span class="keyword">val</span> update_http_only : <span>bool <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <a href="#type-t">t</a></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-update_same_site"><a href="#val-update_same_site" class="anchor"></a><code><span><span class="keyword">val</span> update_same_site : <span><span><a href="#type-same_site">same_site</a> option</span> <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <a href="#type-t">t</a></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-update_extension"><a href="#val-update_extension" class="anchor"></a><code><span><span class="keyword">val</span> update_extension : <span><span>string option</span> <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <span><span>(<a href="#type-t">t</a>, string)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-expire"><a href="#val-expire" class="anchor"></a><code><span><span class="keyword">val</span> expire : <span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>expire c</code> expires cookie <code>c</code> with a Max-Age value of <code>-1L</code>. All other cookie attribute values are removed. Cookies with <code>Max-Age</code> value <code>&lt; 0</code> are removed by HTTP agents such as web browsers.</p></div></div></div></body></html>
