Getting an HTTP Cookie

When a script (client-side or server-side) requests a URL from an HTTP server, the browser will match the URL against all cookies, and if any of them matches, a line containing the name and value pairs of all matching cookies will be included in the HTTP request. The format is straightforward:

Cookie: name1=value1; name2=value2

Notice that the Cookie field in a request header contains only the names and values of all valid cookies. The Set-Cookie field in the response header includes additional attributes such as expiration date. These attributes are not actually part of the cookie, but rather are used to determine if a specific cookie is valid for the purpose of entering the HTTP request header.

Notes and Limitations

The only way to overwrite a cookie is by creating another cookie with the same name and path as an existing one. Creating a cookie with the same name but with a different path than that of an existing one will add an additional cookie. The only way to instantly delete a cookie is by overwriting it with an expired cookie. A cookie may be deleted by the browser before its expiration date but only if the number of cookies exceeds its internal limit.

When sending cookies to a server, all cookies with more specific path mapping should be sent before cookies with less-specific path mapping. If both are sent, the cookie “name1=foo” with a path mapping of “/”, for example, should be sent after the cookie “name1=foo2” with a path mapping of “/bar”.

There are several extremely important limitations on the size and number of cookies a client can store at any given time:

• The client can hold up to 300 cookies.
• A cookie can be up to 4KB, including its name and values. Cookies that exceed this length are trimmed to fit, so remember to keep within this length.
• A maximum of 20 cookies per server or domain are allowed.

A client is not expected to exceed these limits. The oldest cookies are deleted in case this rule is violated.

Proxy servers should propagate the Set-Cookie header to the client, regardless of whether the response was 304 (“not modified”) or 200 (“OK”). Proxy servers work fine with cookies.

Examples

Here are some sample exchanges from Netscape documentation which are designed to illustrate the use of cookies.

First Transaction Sequence Example

Client requests a document and receives in the response:

Set-Cookie: CUSTOMER=WILE_E_COYOTE;
   path=/; expires=Wednesday, 09-Nov-99 23:12:40 GMT

When client requests a URL in the path “/” on this server, it sends:

Cookie: CUSTOMER=WILE_E_COYOTE

Client requests a document and receives in the response:

Set-Cookie: PART_NUMBER=ROCKET_LAUNCHER_0001; path=/

When client requests a URL in the path “/” on this server, it sends:

Cookie: CUSTOMER=WILE_E_COYOTE; PART_NUMBER=ROCKET_LAUNCHER_0001

Client receives:

Set-Cookie: SHIPPING=FEDEX; path=/foo

When client requests a URL in the path “/” on this server, it sends:

Cookie: CUSTOMER=WILE_E_COYOTE; PART_NUMBER=ROCKET_LAUNCHER_0001

When client requests a URL in the path “/foo” on this server, it sends:

Cookie: CUSTOMER=WILE_E_COYOTE;
  PART_NUMBER=ROCKET_LAUNCHER_0001; SHIPPING=FEDEX

Second Transaction Sequence Example

Assume all mappings from above have been cleared.

Client receives:

Set-Cookie: PART_NUMBER=ROCKET_LAUNCHER_0001; path=/

When client requests a URL in the path “/” on this server, it sends:

Cookie: PART_NUMBER=ROCKET_LAUNCHER_0001

Client receives:

Set-Cookie: PART_NUMBER=RIDING_ROCKET_0023; path=/ammo

When client requests a URL in the path “/ammo” on this server, it sends:

Cookie: PART_NUMBER=RIDING_ROCKET_0023;
   PART_NUMBER=ROCKET_LAUNCHER_0001

Note that there are two attributes named “PART_NUMBER” due to the two different paths, “/” and “/ammo”.

Cookies and JavaScript

Setting and getting cookies with a server-side application relies on HTTP headers. You cannot set a cookie or retrieve one after the page has loaded. However, a JavaScript script is a client-side application and thus enables you to process cookies at any time, without contacting the server.

The cookie property of the document object reflects all cookies that are valid for the Web page hosting the script; that is, document.cookie is equivalent to the Cookie field in the HTTP request header.

In the same way you set a cookie via the Set-Cookie field in an HTTP response header, you can do so with JavaScript, by assigning a value to document.cookie.