diff options
author | Brendan Taylor <whateley@gmail.com> | 2010-11-24 00:21:33 -0700 |
---|---|---|
committer | Brendan Taylor <whateley@gmail.com> | 2010-11-24 00:21:33 -0700 |
commit | dbcad132f983f98914ea65ead03bd487332388a8 (patch) | |
tree | 45697991ca1cb3acb7894f0be48d0d2bdcedbae6 | |
parent | 29798af949a55a66f392b237733d8bf8373dab7d (diff) | |
parent | 923d52944b6fb51d2a1a51e60997d9d02e7bde91 (diff) |
Merge branch 'dev/soup-cookied'
-rw-r--r-- | docs/README.cookies | 63 | ||||
-rw-r--r-- | examples/config/cookies | 22 |
2 files changed, 63 insertions, 22 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. diff --git a/examples/config/cookies b/examples/config/cookies deleted file mode 100644 index 9b7374a..0000000 --- a/examples/config/cookies +++ /dev/null @@ -1,22 +0,0 @@ -# This file demonstrates how one *could* manage his cookies. this file is used by the example cookie handler script. -# stick to this format. -# trusted -> always store what we get, send what we have (TODO: by default, or when requested?) -# deny -> deny storing + sending - -# if you don't like to edit this file manually, you could even write a script that adds/removes entries using sed, and call the script from uzbl with a keybind... - - -TRUSTED -bbs.archlinux.org -archlinux.org -linux.com - - - - -DENY -www.icanhascheezburger.com - - - -# rest -> ask
\ No newline at end of file |