cookiejar(3tcl)

📦
version 9.0.4 · 2 versions
, in ubuntu stonking

okay bestie, this is cookiejar(3tcl), part of the Tcl Bundled Packages crew. It's the implementation of the Tcl http package's cookie jar protocol. Cookies are literally everywhere and this lil package is the one holding the snack drawer, no cap. 🍪

🌸 NAME 🌸

cookiejar — the implementation of the Tcl http package cookie jar protocol. That's the whole vibe. She stores cookies, she respects security checks, she slays.

🎀 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 💖

So like, the cookiejar package is an implementation of the http package's cookie jar protocol, and it does it with an SQLite database. Main character behavior, honestly. 🗄️✨

There's one main command: ::http::cookiejar. That's a TclOO class, and you instantiate it to make a cookie jar that manages one particular HTTP session. One session, one jar, very committed, very loyal. 🫶

the configuration moment (package level) 👑

The database management policy gets controlled by the configure method on the ::http::cookiejar class object. Cute, right? You configure the whole class, not one lil instance.

::http::cookiejar configure ?optionName? ?optionValue?

  • If you give it neither optionName nor optionValue, it hands back a copy of the configuration as a Tcl dictionary. Full receipt. 🧾
  • If you give it just optionName, you get just the value of that named option back.
  • If you give it both optionName and optionValue, the named option gets changed to the value you gave. Periodt.

Supported options are (and bestie, this is the full list, we do NOT skip):

  • -domainfile filename — A file (defaulting to somewhere inside the cookiejar package) that describes the list of top-level domains, like .com or .co.jp. Those domains must not accept cookies set upon them. Heads up though: this list is both security-sensitive and not constant, so it should be periodically refetched. Cookie jars keep their own cache of the domain list. 🔐
  • -domainlist url — A URL to fetch that same list of top-level domains (.com, .co.jp, you know the ones) from. Those domains must not accept cookies set upon them. Same warning, same energy: the list is security-sensitive and not constant, so refetch it periodically. Cookie jars maintain their own cache of the domain list. 🌈
  • -domainrefresh intervalMilliseconds — How many milliseconds between checks of the -domainlist for new domains. Tick tock, check the clock. ⏰
  • -loglevel level — The logging level of this package. Must be one of, in order of decreasing verbosity: debug, info, warn, or error.
  • -offline flag — Puts the cookie management engine into offline mode. In offline mode the list of domains gets read immediately from the file configured in -domainfile, and the -domainlist option isn't used at all. It also makes -domainrefresh effectively ignored. Ghost mode. 👻
  • -purgeold intervalMilliseconds — How many milliseconds between checks of the database for expired cookies; expired cookies get deleted. Old cookies, be gone. 💀
  • -retain cookieCount — The maximum number of cookies to keep in the database. A cap. A limit. Boundaries, we love them.
  • -vacuumtrigger deletionCount — The count of persistent cookie deletions to go between vacuuming the database. 🧹

Cookie jar instances get made with any of the standard TclOO instance creation methods (create or new). Pick your fighter.

::http::cookiejar new ?filename?

If you pass a filename, that's the name of a file containing an SQLite database that will hold the persistent cookies your cookie jar maintains — and the database gets created if that file doesn't already exist. If you don't pass filename, the database lives entirely in memory, which effectively forces every cookie inside it to be a session cookie. Gone when you go. 😭

💅 INSTANCE METHODS 💅

Here's what the instances themselves support, bestie:

cookiejar destroy

The standard TclOO destruction method. It does not delete the SQLite database if that database is written to disk. And listen: callers are responsible for making sure the cookie jar isn't in use by the http package at the moment of destruction. Do not yeet her while she's working. 🛑

cookiejar forceLoadDomainData

Makes the cookie jar immediately load (and cache) the domain list data. The domain list gets loaded from the -domainlist configured at the package level if that is enabled, and otherwise it comes from the -domainfile configured at the package level. Loading, but make it urgent. ⚡

cookiejar getCookies protocol host path

Obtains the cookies for a particular HTTP request. This implements the http cookie jar protocol. She's giving request-cookies.

cookiejar policyAllow operation domain path

This one gets called by the storeCookie method to get a decision on whether to allow operation to be performed for the domain and path. Important timing tea: it's checked immediately before the database is updated but after the built-in security checks are done. It should return a boolean value; if it's 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 can impose their own rules. Build your own bouncer, honestly. 💪

cookiejar storeCookie options

Stores a single cookie from a particular HTTP response. Cookies that fail security checks are ignored — bye. This implements the http cookie jar protocol.

cookiejar lookup ?host? ?key?

Looks a cookie up by exact host (or domain) matching. The deets:

  • Neither host nor key supplied → you get the list of hosts for which a cookie is stored.
  • Just host supplied (may be a hostname or a domain name) → you get the list of cookie keys stored for that host.
  • Both host and key supplied → you get the value for that key. And it is an error if no such host or key matches exactly. No fuzzy matching, no mercy. 😤

🌈 EXAMPLES 🌈

The simplest way to use a cookie jar: just permanently configure it at the start of the application. Set it and forget it, iconic behavior.

package require http
package require cookiejar

set cookiedb [file join [file home] cookiejar]
http::config -cookiejar [http::cookiejar new $cookiedb]

# No further explicit steps are required to use cookies
set tok [http::geturl http://core.tcl-lang.org/]

Now, if you only want a particular domain to be allowed to use cookies — maybe because you only want one host to be able to create and manipulate sessions — you make a subclass that imposes that policy. Custom rules, custom queen. 👑

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 [file join [file home] cookiejar]
http::configure -cookiejar [MyCookieJar new $cookiedb]

# No further explicit steps are required to use cookies
set tok [http::geturl http://core.tcl-lang.org/]

🦋 SEE ALSO 🦋

Note: these are all 3tcl, so the whole squad is in the Tcl section together. Family reunion. 🫶

⭐ KEYWORDS ⭐

cookie, internet, security policy, www

ok that's the whole page bestie!! every flag, every method, every example, every warning — all of it, preserved, because we do not gatekeep documentation in this house. 💖

that's a wrap on cookiejar, queen of the cookie drawer 🍪👑

xoxo, this page came to you from the http source, version 0.1, filed under cookiejar(3tcl) — stay hydrated, refetch your domain list, and don't forget to periodically check for expired cookies bestie 💜✨🎀

📦 where this page comes from