aboutsummaryrefslogtreecommitdiffhomepage
path: root/docs
diff options
context:
space:
mode:
authorGravatar Brendan Taylor <whateley@gmail.com>2010-11-24 00:21:33 -0700
committerGravatar Brendan Taylor <whateley@gmail.com>2010-11-24 00:21:33 -0700
commitdbcad132f983f98914ea65ead03bd487332388a8 (patch)
tree45697991ca1cb3acb7894f0be48d0d2bdcedbae6 /docs
parent29798af949a55a66f392b237733d8bf8373dab7d (diff)
parent923d52944b6fb51d2a1a51e60997d9d02e7bde91 (diff)
Merge branch 'dev/soup-cookied'
Diffstat (limited to 'docs')
-rw-r--r--docs/README.cookies63
1 files changed, 63 insertions, 0 deletions
diff --git a/docs/README.cookies b/docs/README.cookies
new file mode 100644
index 0000000..148603f
--- /dev/null
+++ b/docs/README.cookies
@@ -0,0 +1,63 @@
+# 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.