21 Cookie: Legacy HTTP Client Storage

▼ |  | Net: Networking Libraries

1 | HTTP Client
2 | URLs and HTTP
3 | URI Codec: Encoding and Decoding URIs
4 | FTP: Client
5 | Send URL: Opening a Web Browser
6 | SMTP: Sending E-Mail
7 | sendmail: Sending E-Mail
8 | Headers: Parsing and Constructing
9 | Header Field Encoding
10 | IMAP: Reading Mail
11 | POP3: Reading Mail
12 | MIME: Decoding Internet Data
13 | Base 64: Encoding and Decoding
14 | Quoted-Printable: Encoding and Decoding
15 | DNS: Domain Name Service Queries
16 | NNTP: Newsgroup Protocol
17 | TCP: Unit and Signature
18 | TCP Redirect: tcp^ via Channels
19 | SSL Unit: tcp^ via SSL
20 | CGI Scripts
21 | Cookie: Legacy HTTP Client Storage
22 | Git Repository Checkout
| Bibliography
| Index

► | 21 | Cookie: Legacy HTTP Client Storage

21.1 | Functions
21.2 | Examples
21.3 | Cookie Unit
21.4 | Cookie Signature

On this page:

21.1`` Functions
cookie?
valid-domain?
cookie-name?
cookie-value?
set-cookie
cookie: add-comment
cookie: add-domain
cookie: add-max-age
cookie: add-path
cookie: add-expires
cookie: secure
cookie: version
print-cookie
get-cookie
get-cookie/ single
cookie-error
21.2`` Examples
21.2.1`` Creating a cookie
21.2.2`` Parsing a cookie
21.3`` Cookie Unit
cookie@
21.4`` Cookie Signature
cookie^

top contents ← prev up next →

### 21`` Cookie: Legacy HTTP Client Storage🔗ℹ

> NOTE: This library is deprecated; use the net-cookies package, instead. That package (source on GitHub) implements RFC 6265 [RFC6265] (which supersedes RFC 2109) and supports creating cookies on the server in an idiom more typical of Racket.

(require net/cookie) | package: net-lib

The net/cookie library provides utilities for using cookies as specified in RFC 2109 [RFC2109].

#### 21.1`` Functions🔗ℹ

> procedure (cookie? v) → boolean?
> v : any/c

Returns #t if v represents a cookie, #f otherwise.

> procedure (valid-domain? v) → boolean?
> v : any/c

Returns #t if v represents a valid domain, #f otherwise.

> procedure (cookie-name? v) → boolean?
> v : any/c

Returns #t if v is a valid cookie name string, #f otherwise.

> procedure (cookie-value? v) → boolean?
> v : any/c

Returns #t if v is a valid cookie value string, #f otherwise.

> procedure (set-cookie name value) → cookie?
> name : cookie-name?
> value : cookie-value?

Creates a new cookie, with default values for required fields.

> procedure (cookie:add-comment cookie comment) → cookie?
> cookie : cookie?
> comment : string?

Modifies cookie with a comment, and also returns cookie.

> procedure (cookie:add-domain cookie domain) → cookie?
> cookie : cookie?
> domain : valid-domain?

Modifies cookie with a domain, and also returns cookie. The domain must match a prefix of the request URI.

> procedure (cookie:add-max-age cookie seconds) → cookie?
> cookie : cookie?
> seconds : exact-nonnegative-integer?

Modifies cookie with a maximum age, and also returns cookie. The seconds argument is number of seconds that a client should retain the cookie.

> procedure (cookie:add-path cookie path) → cookie?
> cookie : cookie?
> path : valid-path?

Modifies cookie with a path, and also returns cookie.

> procedure (cookie:add-expires cookie path) → cookie?
> cookie : cookie?
> path : string

Modifies cookie with an expiration, and also returns cookie.

> procedure (cookie:secure cookie secure) → cookie?
> cookie : cookie?
> secure : boolean?

Modifies cookie with a security flag, and also returns cookie.

> procedure (cookie:version cookie version) → cookie?
> cookie : cookie?
> version : exact-nonnegative-integer?

Modifies cookie with a version, and also returns cookie. The default is the only known incarnation of HTTP cookies: 1.

> procedure (print-cookie cookie) → string?
> cookie : cookie?

Prints cookie to a string. Empty fields do not appear in the output except when there is a required default.

> procedure (get-cookie name cookies) → (listof cookie-value?)
> name : cookie-name?
> cookies : string?

Returns a list with all the values (strings) associated with name.

The method used to obtain the "Cookie" header depends on the web server. It may be an environment variable (CGI), or you may have to read it from the input port (FastCGI), or maybe it comes in an initial-request structure, etc. The get-cookie and get-cookie/single procedure can be used to extract fields from a "Cookie" field value.

> procedure (get-cookie/single name cookies) → (or/c cookie-value? #f)
> name : cookie-name?
> cookies : string?

Like get-cookie, but returns the just first value string associated to name, or #f if no association is found.

> > struct
> > (struct |  | cookie-error exn:fail ()
> #:extra-constructor-name make-cookie-error)

Raised for errors when handling cookies.

#### 21.2`` Examples🔗ℹ

##### 21.2.1`` Creating a cookie🔗ℹ

> (let ([c (cookie:add-max-age
> (cookie:add-path
> (set-cookie "foo" "bar")
> "/servlets")
> 3600)])
> (print-cookie c))

Produces

> "foo=bar; Max-Age=3600; Path=/servlets; Version=1"

To use this output in a “regular” CGI, instead of the last line use:

> (display (format "Set-Cookie: ~a" (print-cookie c)))

and to use with the PLT Web Server, use:

> (make-response/full code message (current-seconds) mime
> (list (make-header #"Set-Cookie" (string->bytes/utf-8 (print-cookie c))))
> body)

##### 21.2.2`` Parsing a cookie🔗ℹ

Imagine your Cookie header looks like this:

> > (define cookies
> "test2=2; test3=3; xfcTheme=theme6; xfcTheme=theme2")

Then, to get the values of the xfcTheme cookie, use

> > (get-cookie "xfcTheme" cookies)
> '("theme6" "theme2")
> > (get-cookie/single "xfcTheme" cookies)
> "theme6"

If you try to get a cookie that simply is not there:

> > (get-cookie/single "foo" cookies)
> #f
> > (get-cookie "foo" cookies)
> '()

Note that not having a cookie is normally not an error. Most clients won’t have a cookie set then first arrive at your site.

#### 21.3`` Cookie Unit🔗ℹ

> > > cookie@ and cookie^ are deprecated. They exist for backward-compatibility and will likely be removed in the future. New code should use the net-cookies package.

(require net/cookie-unit) | package: compatibility-lib

> value cookie@ : unit?

Imports nothing, exports cookie^.

#### 21.4`` Cookie Signature🔗ℹ

(require net/cookie-sig) | package: compatibility-lib

> signature cookie^ : signature

Includes everything exported by the net/cookie module.

top contents ← prev up next →