Skip to content

Make CookieJar obey RFC 6265's domain rules #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hellerve merged 2 commits into from
Aug 23, 2026
Merged

Make CookieJar obey RFC 6265's domain rules #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c5e1554
Make CookieJar obey RFC 6265's domain rules
Aug 23, 2026
e39af86
Keep a Domain identical to a single-label host, host-only
Aug 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 11 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,10 +98,14 @@ subsequent requests automatically:
(Result.Error e) (IO.errorln &e)))
```

The jar handles domain matching (RFC 6265 suffix rules), path matching,
Secure flag enforcement, and expiry. Cookies are deduplicated by
name+domain+path. During redirects, cookies from every hop are stored and
re-applied for each new URL.
The jar follows RFC 6265 §5.3 and §5.4. A cookie that arrives with no
`Domain` attribute is host-only: it goes back to the host that set it and to
no subdomain. A `Domain` attribute the responding host does not domain-match
is rejected outright, and so is a single-label one such as `Domain=com`. On
top of that the jar enforces path matching, the `Secure` flag, and expiry;
cookies are deduplicated by name+domain+path and serialized longest path
first. During redirects, cookies from every hop are stored and re-applied for
each new URL.

### Multipart uploads

Expand Down Expand Up @@ -207,9 +211,9 @@ given.
| Function | Purpose |
|----------|---------|
| `CookieJar.create` | Create an empty jar |
| `CookieJar.store! jar cookie` | Store a cookie, replacing duplicates by name+domain+path |
| `CookieJar.store-response! jar response url` | Store cookies from a response, defaulting domain from URL |
| `CookieJar.matching jar url` | Return cookies matching the URL by domain, path, security, and expiry |
| `CookieJar.store! jar cookie` | Store a cookie as a domain cookie, replacing duplicates by name+domain+path |
| `CookieJar.store-response! jar response url` | Store a response's cookies, applying RFC 6265 §5.3's origin checks |
| `CookieJar.matching jar url` | Return cookies matching the URL by domain, path, security, and expiry, longest path first |
| `CookieJar.cookie-header jar url` | Build a `Cookie` header value, or `Nothing` if no cookies match |
| `CookieJar.apply-to-headers jar url headers` | Add a `Cookie` header to the headers map |
| `CookieJar.size jar` | Number of stored cookies |
Expand Down
5 changes: 5 additions & 0 deletions docs/Client.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@
CookieJar
</a>
</li>
<li>
<a href="JarCookie.html">
JarCookie
</a>
</li>
<li>
<a href="Multipart.html">
Multipart
Expand Down
5 changes: 5 additions & 0 deletions docs/Connection.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@
CookieJar
</a>
</li>
<li>
<a href="JarCookie.html">
JarCookie
</a>
</li>
<li>
<a href="Multipart.html">
Multipart
Expand Down
42 changes: 30 additions & 12 deletions docs/CookieJar.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@
CookieJar
</a>
</li>
<li>
<a href="JarCookie.html">
JarCookie
</a>
</li>
<li>
<a href="Multipart.html">
Multipart
Expand Down Expand Up @@ -117,7 +122,7 @@ <h3 id="cookie-header">
</pre>
<p class="doc">
<p>builds a Cookie header value for the URL, or Nothing
if no cookies match.</p>
if no cookies match. Cookies are serialized longest path first.</p>

</p>
</div>
Expand All @@ -131,7 +136,7 @@ <h3 id="cookies">
instantiate
</div>
<p class="sig">
(Fn [(Ref CookieJar a)] (Ref (Array Cookie) a))
(Fn [(Ref CookieJar a)] (Ref (Array JarCookie) a))
</p>
<span>

Expand Down Expand Up @@ -211,7 +216,7 @@ <h3 id="init">
instantiate
</div>
<p class="sig">
(Fn [(Array Cookie)] CookieJar)
(Fn [(Array JarCookie)] CookieJar)
</p>
<span>

Expand All @@ -238,7 +243,12 @@ <h3 id="matching">
</pre>
<p class="doc">
<p>returns cookies matching the given URL by domain, path,
security, and expiry.</p>
security, and expiry, longest path first (RFC 6265 §5.4 step 2). Cookies of
equal path length keep their insertion order; the creation time §5.4 asks for
as the second sort key is not recorded.</p>
<p>A cookie stored without a <code>Domain</code> attribute is host-only and matches its
origin host alone; one stored with a <code>Domain</code> attribute also matches that
domain’s subdomains, unless the request host is an IP literal.</p>

</p>
</div>
Expand Down Expand Up @@ -272,7 +282,7 @@ <h3 id="set-cookies">
instantiate
</div>
<p class="sig">
(Fn [CookieJar, (Array Cookie)] CookieJar)
(Fn [CookieJar, (Array JarCookie)] CookieJar)
</p>
<span>

Expand All @@ -292,7 +302,7 @@ <h3 id="set-cookies!">
instantiate
</div>
<p class="sig">
(Fn [(Ref CookieJar a), (Array Cookie)] ())
(Fn [(Ref CookieJar a), (Array JarCookie)] ())
</p>
<span>

Expand Down Expand Up @@ -332,14 +342,16 @@ <h3 id="store!">
defn
</div>
<p class="sig">
(Fn [(Ref CookieJar a), (Ref Cookie a)] ())
(Fn [(Ref CookieJar a), (Ref Cookie b)] ())
</p>
<pre class="args">
(store! jar c)
</pre>
<p class="doc">
<p>stores a cookie, replacing any with the same name, domain,
and path.</p>
<p>stores a cookie as a domain cookie, replacing any with the same
name, domain, and path. The cookie is trusted as given: there is no request
origin to check it against, so prefer <code>store-response!</code> for anything that came
off the wire.</p>

</p>
</div>
Expand All @@ -359,8 +371,14 @@ <h3 id="store-response!">
(store-response! jar resp url)
</pre>
<p class="doc">
<p>stores cookies from a response. The URL provides the
default domain for cookies without a Domain attribute.</p>
<p>stores cookies from a response, applying RFC 6265 §5.3.</p>
<p>A cookie with no <code>Domain</code> attribute becomes host-only: it is replayed to the
URL’s host and to no other. A <code>Domain</code> attribute the URL’s host does not
domain-match is rejected outright. So is one with no embedded dot — the
pre-public-suffix-list approximation of §5.3 step 5, which lets through
registrable multi-label suffixes such as <code>co.uk</code> — unless it is identical to
the host, in which case the cookie is kept host-only, so <code>Domain=localhost</code>
from <code>http://localhost/</code> still works.</p>

</p>
</div>
Expand Down Expand Up @@ -394,7 +412,7 @@ <h3 id="update-cookies">
instantiate
</div>
<p class="sig">
(Fn [CookieJar, (Ref (Fn [(Array Cookie)] (Array Cookie) a) b)] CookieJar)
(Fn [CookieJar, (Ref (Fn [(Array JarCookie)] (Array JarCookie) a) b)] CookieJar)
</p>
<span>

Expand Down
Loading