12.43 rfc.cookie - HTTP cookie handling

Module: rfc.cookie ¶

Defines a set of functions to parse and construct a “cookie” information defined in RFC 6265.

Function: parse-cookie-string string :optional version ¶

{rfc.cookie} Parse a cookie string string, which is the value of “Cookie” request header. Usually, the same information is available to CGI program via the environment variable HTTP_COOKIE.

If the cookie version is known, via “Cookie2” request header, the integer version must be passed to version. Otherwise, parse-cookie-string figures out the version from string.

The result has the following format.

((<name> <value> [:path <path>] [:domain <domain>] [:port <port>])
 …)

where <name> is the attribute name, and <value> is the corresponding value. If the attribute doesn’t have value, <value> is #f. (Note that it differs from the attribute having null value, "".) If the attribute has path, domain or port options, it is given as a form of keyword-value pair.

Note: To retrieve the value of a specific cookie conveniently, you can use rfc822-header-ref (see rfc.822 - RFC822 message parsing).

Function: construct-cookie-string specs :optional version ¶

{rfc.cookie} Given list of cookie specs, creates a cookie string suitable for Set-cookie2 or Set-cookie header.

Optional version argument is accepted but ignored; it’s for the backward compatibility.

Each cookie spec has the following format.

(<name> <value> [:expires <data/time>] [:max-age <age>]
                [:domain <domain>] [:path <path>]
                [:secure <boolean>] [:http-only <boolean>]

Where,

<name>

A string. Name of the cookie.

<value>

Value of the cookie. May be a string, or #f if no value is needed.

<domain> <path>

Strings.

<boolean>

Boolean value

<age>

Non-negative exact integers

<date/time>

Either an integer (seconds since Epoch), a formatted date string, <time> or <date> objects (see Time, see srfi.19 - Time data types and procedures).

The order of attributes does not matter. The attribute values are quoted appropriately.

For the backward compatibility to the older specification (RFC2965, RFC2109, and old Netscape cookie specification), it recognizes a few more attributes (comment, comment-url, discard, port, and version). They are rendered to the output, but the new code should not use them.

Return value is a list of cookie strings, each of which stands for each cookie. For old-style protocol (using Set-cookie header) you must send each of them by individual header. For new-style protocol (using Set-cookie2 header), you can join them with comma and send it at once. See RFC6265 for further details.

Example:

(construct-cookie-string
   `(("name" "foo" :domain "foo.com" :path "/" :max-age 86400)))
 ⇒ ("name=foo;Domain=foo.com;Path=/;Max-age=86400")