diff options
Diffstat (limited to 'doc/cookiejar.n')
| -rw-r--r-- | doc/cookiejar.n | 217 |
1 files changed, 0 insertions, 217 deletions
diff --git a/doc/cookiejar.n b/doc/cookiejar.n deleted file mode 100644 index 7d2f46b..0000000 --- a/doc/cookiejar.n +++ /dev/null @@ -1,217 +0,0 @@ -'\" -'\" Copyright (c) 2014-2018 Donal K. Fellows. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH "cookiejar" n 0.1 http "Tcl Bundled Packages" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -cookiejar \- Implementation of the Tcl http package cookie jar protocol -.SH SYNOPSIS -.nf -\fBpackage require\fR \fBcookiejar\fR ?\fB0.1\fR? - -\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? -\fB::http::cookiejar create\fR \fIname\fR ?\fIfilename\fR? -\fB::http::cookiejar new\fR ?\fIfilename\fR? - -\fIcookiejar\fR \fBdestroy\fR -\fIcookiejar\fR \fBforceLoadDomainData\fR -\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR -\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR -\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? -.fi -.SH DESCRIPTION -.PP -The cookiejar package provides an implementation of the http package's cookie -jar protocol using an SQLite database. It provides one main command, -\fB::http::cookiejar\fR, which is a TclOO class that should be instantiated to -create a cookie jar that manages a particular HTTP session. -.PP -The database management policy can be controlled at the package level by the -\fBconfigure\fR method on the \fB::http::cookiejar\fR class object: -.TP -\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? -. -If neither \fIoptionName\fR nor \fIoptionValue\fR are supplied, this returns a -copy of the configuration as a Tcl dictionary. If just \fIoptionName\fR is -supplied, just the value of the named option is returned. If both -\fIoptionName\fR and \fIoptionValue\fR are given, the named option is changed -to be the given value. -.RS -.PP -Supported options are: -.TP -\fB\-domainfile \fIfilename\fR -. -A file (defaulting to within the cookiejar package) with a description of the -list of top-level domains (e.g., \fB.com\fR or \fB.co.jp\fR). Such domains -\fImust not\fR accept cookies set upon them. Note that the list of such -domains is both security-sensitive and \fInot\fR constant and should be -periodically refetched. Cookie jars maintain their own cache of the domain -list. -.TP -\fB\-domainlist \fIurl\fR -. -A URL to fetch the list of top-level domains (e.g., \fB.com\fR or -\fB.co.jp\fR) from. Such domains \fImust not\fR accept cookies set upon -them. Note that the list of such domains is both security-sensitive and -\fInot\fR constant and should be periodically refetched. Cookie jars maintain -their own cache of the domain list. -.TP -\fB\-domainrefresh \fIintervalMilliseconds\fR -. -The number of milliseconds between checks of the \fI\-domainlist\fR for new -domains. -.TP -\fB\-loglevel \fIlevel\fR -. -The logging level of this package. The logging level must be (in order of -decreasing verbosity) one of \fBdebug\fR, \fBinfo\fR, \fBwarn\fR, or -\fBerror\fR. -.TP -\fB\-offline \fIflag\fR -. -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 -\fB\-domainfile\fR option, and the \fB\-domainlist\fR option is not used; it -also makes the \fB\-domainrefresh\fR option be effectively ignored. -.TP -\fB\-purgeold \fIintervalMilliseconds\fR -. -The number of milliseconds between checks of the database for expired -cookies; expired cookies are deleted. -.TP -\fB\-retain \fIcookieCount\fR -. -The maximum number of cookies to retain in the database. -.TP -\fB\-vacuumtrigger \fIdeletionCount\fR -. -A count of the number of persistent cookie deletions to go between vacuuming -the database. -.RE -.PP -Cookie jar instances may be made with any of the standard TclOO instance -creation methods (\fBcreate\fR or \fBnew\fR). -.TP -\fB::http::cookiejar new\fR ?\fIfilename\fR? -. -If a \fIfilename\fR 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 \fIfilename\fR is not supplied, the database will be held entirely within -memory, which effectively forces all cookies within it to be session cookies. -.SS "INSTANCE METHODS" -.PP -The following methods are supported on the instances: -.TP -\fIcookiejar\fR \fBdestroy\fR -. -This is the standard TclOO destruction method. It does \fInot\fR 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. -.TP -\fIcookiejar\fR \fBforceLoadDomainData\fR -. -This method causes the cookie jar to immediately load (and cache) the domain -list data. The domain list will be loaded from the \fB\-domainlist\fR -configured a the package level if that is enabled, and otherwise will be -obtained from the \fB\-domainfile\fR configured at the package level. -.TP -\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR -. -This method obtains the cookies for a particular HTTP request. \fIThis -implements the http cookie jar protocol.\fR -.TP -\fIcookiejar\fR \fBpolicyAllow\fR \fIoperation domain path\fR -. -This method is called by the \fBstoreCookie\fR method to get a decision on -whether to allow \fIoperation\fR to be performed for the \fIdomain\fR and -\fIpath\fR. 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 \fIoperation\fRs are: -.RS -.TP -\fBdelete\fR -. -The \fIdomain\fR is seeking to delete a cookie. -.TP -\fBsession\fR -. -The \fIdomain\fR is seeking to create or update a session cookie. -.TP -\fBset\fR -. -The \fIdomain\fR is seeking to create or update a persistent cookie (with a -defined lifetime). -.PP -The default implementation of this method just returns true, but subclasses of -this class may impose their own rules. -.RE -.TP -\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR -. -This method stores a single cookie from a particular HTTP response. Cookies -that fail security checks are ignored. \fIThis implements the http cookie jar -protocol.\fR -.TP -\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? -. -This method looks a cookie by exact host (or domain) matching. If neither -\fIhost\fR nor \fIkey\fR are supplied, the list of hosts for which a cookie is -stored is returned. If just \fIhost\fR (which may be a hostname or a domain -name) is supplied, the list of cookie keys stored for that host is returned. -If both \fIhost\fR and \fIkey\fR are supplied, the value for that key is -returned; it is an error if no such host or key match exactly. -.SH "EXAMPLES" -.PP -The simplest way of using a cookie jar is to just permanently configure it at -the start of the application. -.PP -.CS -package require http -\fBpackage require cookiejar\fR - -set cookiedb ~/.tclcookies.db -http::configure -cookiejar [\fBhttp::cookiejar new\fR $cookiedb] - -# No further explicit steps are required to use cookies -set tok [http::geturl http://core.tcl-lang.org/] -.CE -.PP -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. -.PP -.CS -package require http -\fBpackage require cookiejar\fR - -oo::class create MyCookieJar { - superclass \fBhttp::cookiejar\fR - - method \fBpolicyAllow\fR {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-lang.org/] -.CE -.SH "SEE ALSO" -http(n), oo::class(n), sqlite3(n) -.SH KEYWORDS -cookie, internet, security policy, www -'\" Local Variables: -'\" mode: nroff -'\" fill-column: 78 -'\" End: |