cookiejar(n)

✨ NAME ✨

cookiejar — the Tcl http package's cookie jar protocol, but implemented. Yes bestie, this is the cookiejar(n) page from the Tcl Bundled Packages, and we're gonna read it together 💖

---

🌸 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 🍓

okay so the cookiejar package is literally an implementation of the http package's cookie jar protocol, and it's built on top of an SQLite database. That's the whole vibe. 🫶

It gives you one main command, ::http::cookiejar, which is a TclOO</> class. You're supposed to instantiate it to make a cookie jar that manages a particular HTTP session. One session, one jar. Iconic.

The database management policy? That's controlled at the package level, through the configure method on the ::http::cookiejar class object. Let's get into it 👑

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

So here's the tea on how this behaves:

• If you supply neither optionName nor optionValue, it hands you back a copy of the whole configuration as a Tcl dictionary. The full download. 📦
• If you supply just optionName, you get just the value of that named option. A little peek.
• If you give it both optionName and optionValue, then the named option gets changed to be the value you passed. Glow-up applied 💅

Supported options are:

• -domainfile filename — a file (defaulting to within the cookiejar package) that describes the list of top-level domains (think .com or .co.jp). Those domains must not accept cookies set upon them. Heads up though: that list is both security-sensitive and not constant, so you should periodically refetch it. Cookie jars keep their own cache of the domain list.
• -domainlist url — a URL to fetch that list of top-level domains (.com, .co.jp, you know the ones) from. Same deal: such domains must not accept cookies set upon them. And again — security-sensitive, not constant, periodically refetch. 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. It must be one of debug, info, warn, or error, listed here in order of decreasing verbosity.
• -offline flag — lets the cookie management engine go 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 effectively ignored. No internet, no problem 🌈
• -purgeold intervalMilliseconds — the number of milliseconds between checks of the database for expired cookies; expired cookies get deleted. bye bestie 💀
• -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 you pass a filename argument, that's the name of a file containing an SQLite database that will hold the persistent cookies maintained by the cookie jar. If the file doesn't already exist, the database gets created. ✨

If you don't supply filename, the database lives entirely within memory, which effectively forces all cookies within it to be session cookies. Poof, gone when you're gone 🦋

---

💅 INSTANCE METHODS 💅

The following methods are supported on the instances:

• cookiejar destroy — the standard TclOO destruction method. It does not delete the SQLite database if it's written to disk, so don't come for me. Callers are responsible for making sure the cookie jar isn't in use by the http package at the time of destruction. 👀
• 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's enabled, and otherwise it's obtained from the -domainfile configured at the package level.
• cookiejar getCookies protocol host path — obtains the cookies for a particular HTTP request. This implements the http cookie jar protocol. 🍪
• cookiejar policyAllow operation domain path — this one is called by the storeCookie method to get a decision on whether to allow operation to be performed for the domain and path. It's checked immediately before the database is updated, but after the built-in security checks are done, and it should return a boolean value. If that 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. Main character energy, honestly 👑

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

---

🎀 EXAMPLES 🎀

The simplest way of using a cookie jar is to just permanently configure it at the start of the application. Set it and forget it bestie:

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/]

To only allow a particular domain to use cookies — maybe because you only want to enable a particular host to create and manipulate sessions — create a subclass that imposes that policy. Custom rules, custom vibes 🦋

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 🌈

http(n), oo::class(n), sqlite3(n)

---

⭐ KEYWORDS ⭐

cookie, internet, security policy, www

---

okay and that's the whole page, you ate it fr fr 💖 this cookiejar(n) page is part of the http package, version 0.1 — so go forth and manage those cookies, iykyk 🍪✨