NAME

cookiejar - Implementation of the Tcl http package cookie jar protocol

SYNOPSIS

package require cookiejar ?0.1?
::http::cookiejar configure ?optionName? ?optionValue?
::http::cookiejar create name ?filename?
::http::cookiejar new ?filename?
cookiejar destroy
cookiejar forceLoadDomainData
cookiejar getCookies protocol host path
cookiejar storeCookie options
cookiejar lookup ?host? ?key?

DESCRIPTION

The cookiejar package provides an implementation of the http package's cookie jar protocol using an SQLite database. It provides one main command, ::http::cookiejar, which is a TclOO class that should be instantiated to create a cookie jar that manages a particular HTTP session.

The database management policy can be controlled at the package level by the configure method on the ::http::cookiejar class object:

::http::cookiejar configure ?optionName? ?optionValue?: If neither optionName nor optionValue are supplied, this returns a copy of the configuration as a Tcl dictionary. If just optionName is supplied, just the value of the named option is returned. If both optionName and optionValue are given, the named option is changed to be the given value.

Supported options are:

-domainfile filename: A file (defaulting to within the cookiejar package) with a description of the list of top-level domains (e.g., .com or .co.jp). Such domains must not accept cookies set upon them. Note that the list of such domains is both security-sensitive and not constant and should be periodically refetched. Cookie jars maintain their own cache of the domain list.
-domainlist url: A URL to fetch the list of top-level domains (e.g., .com or .co.jp) from. Such domains must not accept cookies set upon them. Note that the list of such domains is both security-sensitive and not constant and should be periodically refetched. Cookie jars maintain their own cache of the domain list.
-domainrefresh intervalMilliseconds: The number of milliseconds between checks of the -domainlist for new domains.
-loglevel level: The logging level of this package. The logging level must be (in order of decreasing verbosity) one of debug, info, warn, or error.
-offline flag: Allows the cookie managment engine to be placed into offline mode. In offline mode, the list of domains is read immediately from the file configured in the -domainfile option, and the -domainlist option is not used; it also makes the -domainrefresh option be effectively ignored.
-purgeold intervalMilliseconds: The number of milliseconds between checks of the database for expired cookies; expired cookies are deleted.
-retain cookieCount: The maximum number of cookies to retain in the database.
-vacuumtrigger deletionCount: A count of the number of persistent cookie deletions to go between vacuuming the database.

Cookie jar instances may be made with any of the standard TclOO instance creation methods (create or new).

::http::cookiejar new ?filename?: If a filename argument is provided, it is the name of a file containing an SQLite database that will contain the persistent cookies maintained by the cookie jar; the database will be created if the file does not already exist. If filename is not supplied, the database will be held entirely within memory, which effectively forces all cookies within it to be session cookies.

INSTANCE METHODS

The following methods are supported on the instances:

cookiejar destroy: This is the standard TclOO destruction method. It does not delete the SQLite database if it is written to disk. Callers are responsible for ensuring that the cookie jar is not in use by the http package at the time of destruction.
cookiejar forceLoadDomainData: This method causes the cookie jar to immediately load (and cache) the domain list data. The domain list will be loaded from the -domainlist configured a the package level if that is enabled, and otherwise will be obtained from the -domainfile configured at the package level.
cookiejar getCookies protocol host path: This method obtains the cookies for a particular HTTP request. This implements the http cookie jar protocol.
cookiejar policyAllow operation domain path: This method is called by the storeCookie method to get a decision on whether to allow operation to be performed for the domain and path. This is checked immediately before the database is updated but after the built-in security checks are done, and should return a boolean value; if the value is false, the operation is rejected and the database is not modified. The supported operations are:

delete: The domain is seeking to delete a cookie.
session: The domain is seeking to create or update a session cookie.
set: The domain is seeking to create or update a persistent cookie (with a defined lifetime).

The default implementation of this method just returns true, but subclasses of this class may impose their own rules.

cookiejar storeCookie options: This method stores a single cookie from a particular HTTP response. Cookies that fail security checks are ignored. This implements the http cookie jar protocol.
cookiejar lookup ?host? ?key?: This method looks a cookie by exact host (or domain) matching. If neither host nor key are supplied, the list of hosts for which a cookie is stored is returned. If just host (which may be a hostname or a domain name) is supplied, the list of cookie keys stored for that host is returned. If both host and key are supplied, the value for that key is returned; it is an error if no such host or key match exactly.

EXAMPLES

The simplest way of using a cookie jar is to just permanently configure it at the start of the application.

package require http
package require cookiejar
set cookiedb ~/.tclcookies.db
http::configure -cookiejar [http::cookiejar new $cookiedb]
# No further explicit steps are required to use cookies
set tok [http::geturl http://core.tcl.tk/]

To only allow a particular domain to use cookies, perhaps because you only want to enable a particular host to create and manipulate sessions, create a subclass that imposes that policy.

package require http
package require cookiejar
oo::class create MyCookieJar {
    superclass http::cookiejar
    method policyAllow {operation domain path} {
        return [expr {$domain eq "my.example.com"}]
    }
}
set cookiedb ~/.tclcookies.db
http::configure -cookiejar [MyCookieJar new $cookiedb]
# No further explicit steps are required to use cookies
set tok [http::geturl http://core.tcl.tk/]

KEYWORDS