# Cookies and Uzbl #

The speed of cookie lookups is important, since a single page load can involve
dozens of HTTP requests, each of which needs a separate cookie lookup (since
another instance of uzbl may have obtained new cookies for a site).

It is possible handle cookie lookup (and storage) using a `spawn_async` cookie
handler, but spawning new processes is inherently slow so a `talk_to_socket`
cookie daemon (like the default uzbl-cookie-manager) is recommended.

## uzbl-cookie-manager ##

uzbl-cookie-manager is a cookie daemon based on libsoup's SoupCookieJar. Cookies
are stored in a file in the Mozilla cookies.txt format (default location
$XDG_DATA_HOME/.local/share/cookies.txt).

### uzbl-cookie-manager Whitelist ###

If a whitelist file is present (default location
$XDG_CONFIG_HOME/uzbl/cookie_whitelist), then website attempts to set cookies
will be ignored unless the site's domain is present in the whitelist.

The whitelist can contain comment lines beginning with `#`, and domain lines. A
domain line beginning with . will whitelist the given domain name and any
subdomain of it. Otherwise only exact matches of the domain are whitelisted.

For instance, given this whitelist file:

    example.com
    .uzbl.org

uzbl-cookie-manager would accept cookies for example.com, uzbl.org and
www.uzbl.org, but ignore cookies set for www.example.com (and any other
domain that is not a subdomain of uzbl.org).

## uzbl-cookie-daemon ##

uzbl-cookie-daemon is a Python cookie daemon based on Python's cookielib.
Cookielib's lookup algorithm isn't very efficient for our needs, so
uzbl-cookie-daemon is noticeably slow.

## Cookie Daemon Protocol ##

When uzbl's `cookie_handler` variable is set to `talk_to_socket path`, uzbl
connects to the Unix domain socket located at `path`. uzbl will send a cookie
lookup request on this socket every time it makes an HTTP request. The format of
this lookup request is:

    GET\0scheme\0host\0path\0

where `\0` is the null character, `scheme` is the URL scheme (http or https),
`host` is the hostname from the URL and `path` is the requested path. The cookie
daemon should respond with the names and values of cookies that match the
request, in the format used by the `Cookie` header, terminated with a `\0`.

When a website adds, deletes or changes a cookie, uzbl notifies the cookie
daemon with a request in the format:

    PUT\0scheme\0host\0path\0name=value\0

where `scheme`, `host` and `path` are (approximately) as above, and `name=value`
is the cookie name-value pair to store. The cookie daemon should respond by
writing `\0` to the socket.