classDocs / http / CookieJar

http.CookieJar

classsharedsource

Object → http.CookieJar

A cookie jar, stores cookies from Set-Cookie response headers and builds the Cookie request header, following RFC 6265.

Pass it as cookies to http.request to use it automatically.

Known limits:

the public suffix list is not checked, only bare top-level domains (Domain=com) are rejected, so a server can still set a cookie for a suffix like Domain=co.uk, keep jars per service you talk to;
reqwest passes only the last Set-Cookie header of a response, the others are lost;
cookies set by redirect responses are only stored with chttp, where redirects are followed in Lua, reqwest and HTTP follow redirects on their own and show only the final response;
cookies live in memory, use CookieJar:save and CookieJar:load to keep them between restarts.

lua

local jar = http.CookieJar()

http.request( { url = "https://example.com/login", method = "POST", cookies = jar } )
http.request( { url = "https://example.com/profile", cookies = jar } ) -- sends the session cookie

jar:set( "lang", "en", { domain = "example.com" } )
jar:get( "lang", "https://example.com/" ).value -- "en"

Constructor

http.CookieJar(): http.CookieJar

Fields

Name	Type	Description
`[ integer ]`	`http.Cookie`	The stored cookies, in creation order.

Methods

`clear`	Removes every cookie, or only the session ones (without expires).
`delete`	Removes every cookie with the given name, only from domain if it is given.
`get`	Returns the cookie with the given name that would be sent to url, the one with the longest path if there are several.
`header`	Builds the Cookie request header for url, expired cookies are removed.
`load`	Loads cookies saved with CookieJar:save, replacing the ones with the same name, domain and path.
`save`	Saves the persistent cookies (the ones with expires) to dreamwork.storage.cookies under name, session cookies are skipp…
`set`	Sets a cookie, replacing the one with the same name, domain and path.
`store`	Stores cookies from the Set-Cookie response header(s) of a response from url.

#CookieJar:clear

sharedsource

function http.CookieJar:clear(session_only?: boolean)

Removes every cookie, or only the session ones (without expires).

Parameters

Name	Type	Description
`session_only`optional	`boolean`	If `true`, only session cookies are removed.

#CookieJar:delete

sharedsource

function http.CookieJar:delete(name: string, domain?: string)

Removes every cookie with the given name, only from domain if it is given.

Parameters

Name	Type	Description
`name`	`string`	The cookie name.
`domain`optional	`string`	The domain to remove the cookie from.

#CookieJar:get

sharednodiscardsource

function http.CookieJar:get(name: string, url?: ( string | URL )?): http.Cookie | nil

Returns the cookie with the given name that would be sent to url, the one with the longest path if there are several.

Without url the first not expired cookie with this name is returned.

Parameters

Name	Type	Description
`name`	`string`	The cookie name.
`url`optional	`( string \| URL )?`	The URL the cookie would be sent to.

Returns

Type	Name	Description
`http.Cookie \| nil`	`cookie`	The cookie, or `nil` if there is none.

#CookieJar:header

sharednodiscardsource

function http.CookieJar:header(url: string | URL): string | nil

Builds the Cookie request header for url, expired cookies are removed.

Cookies with longer paths come first, see RFC 6265 5.4.

Parameters

Name	Type	Description
`url`	`string \| URL`	The URL the request is sent to.

Returns

Type	Name	Description
`string \| nil`	`header`	The header value, or `nil` if no cookies match.

#CookieJar:load

sharedsource

function http.CookieJar:load(name: string): integer

Loads cookies saved with CookieJar:save, replacing the ones with the same name, domain and path.

Expired cookies are skipped.

Parameters

Name	Type	Description
`name`	`string`	The name the jar was saved under.

Returns

Type	Name	Description
`integer`	`count`	The number of loaded cookies, `0` if nothing was saved.

#CookieJar:save

sharedsource

function http.CookieJar:save(name: string)

Saves the persistent cookies (the ones with expires) to dreamwork.storage.cookies under name, session cookies are skipped, like a browser does on exit.

Saving a jar without persistent cookies removes the saved one.

Parameters

Name	Type	Description
`name`	`string`	The name to save the jar under.

#CookieJar:set

sharedsource

function http.CookieJar:set(name: string, value: string, options: http.CookieOptions): http.Cookie

Sets a cookie, replacing the one with the same name, domain and path.

An expired expires or a max_age of 0 or less removes the cookie, the returned cookie is not stored in that case.

Raises a TypeError on wrong argument types and a ValueError if name or value would break the Cookie header, or if neither domain nor a url with a host is given.

Parameters

Name	Type	Description
`name`	`string`	The cookie name, without `"="`, `";"`, `","`, whitespace or control characters.
`value`	`string`	The cookie value, sent as is, without `";"` or control characters.
`options`	`http.CookieOptions`	The cookie options, `domain` or `url` is required.

Returns

Type	Name	Description
`http.Cookie`	`cookie`	The cookie.

#CookieJar:store

sharedsource

function http.CookieJar:store(set_cookie: string | string[], url: string | URL)

Stores cookies from the Set-Cookie response header(s) of a response from url.

Values joined with "," by the http client are split back, invalid cookies and cookies for other domains are ignored.

Nothing is stored if url has no host (e.g. file:///).

Parameters

Name	Type	Description
`set_cookie`	`string \| string[]`	The `Set-Cookie` header value, or a list of values.
`url`	`string \| URL`	The URL of the response.