class

HTTP::Cookie

Inherits Reference / Object

Represents a cookie with all its attributes. Provides convenient access and modification of them.

NOTE: To use Cookie, you must explicitly import it with require "http/cookie"

Constructors

new(name : String, value : String, path : String | Nil = nil, expires : Time | Nil = nil, domain : String | Nil = nil, secure : Bool | Nil = nil, http_only : Bool = false, samesite : SameSite | Nil = nil, extension : String | Nil = nil, max_age : Time::Span | Nil = nil, creation_time : Time = Time.utc)

Creates a new Cookie instance.

Raises IO::Error if name or value are invalid as per RFC 6265 §4.1.1. Raises ArgumentError if name has a security prefix but the requirements are not met as per RFC 6265 bis §4.1.3. Alternatively, if name has a security prefix, and the related properties are nil, the prefix will automatically be applied to the cookie.

Instance methods

==(other : self)

Returns true if this reference is the same as other. Invokes same?.

creation_time

domain

domain=(domain : String | Nil)

expiration_time

Returns the expiration time of this cookie.

expire

Expires the cookie.

Causes the cookie to be destroyed. Sets the value to the empty string and expires its lifetime.

cookie = HTTP::Cookie.new("hello", "world")
cookie.expire

cookie.value    # => ""
cookie.expired? # => true

expired?(time_reference : Time = Time.utc) : Bool

Returns the expiration status of this cookie as a Bool.

time_reference can be passed to use a different reference time for comparison. Default is the current time (Time.utc).

expires

expires=(expires : Time | Nil)

extension

extension=(extension : String | Nil)

hash(hasher)

See Object#hash(hasher)

http_only

http_only=(http_only : Bool)

inspect(io : IO) : Nil

Returns an unambiguous string representation of this cookie.

It uses the Set-Cookie serialization from #to_set_cookie_header which represents the full state of the cookie.

HTTP::Cookie.new("foo", "bar").inspect                        # => HTTP::Cookie["foo=bar"]
HTTP::Cookie.new("foo", "bar", domain: "example.com").inspect # => HTTP::Cookie["foo=bar; domain=example.com"]

max_age

max_age=(max_age : Time::Span | Nil)

name

name=(name : String) : Nil

Sets the name of this cookie.

Raises IO::Error if the value is invalid as per RFC 6265 §4.1.1.

path

path=(path : String | Nil)

samesite

samesite=(samesite : SameSite | Nil)

secure

Returns true if this cookie has the Secure flag.

secure=(secure : Bool) : Bool

to_cookie_header(io : IO) : Nil

Returns a string representation of this cookie in the format used by the Cookie header of an HTTP request. This includes only the #name and #value. All other attributes are left out.

HTTP::Cookie.new("foo", "bar").to_cookie_header                        # => "foo=bar"
HTTP::Cookie.new("foo", "bar", domain: "example.com").to_cookie_header # => "foo=bar

to_cookie_header

Returns a string representation of this cookie in the format used by the Cookie header of an HTTP request. This includes only the #name and #value. All other attributes are left out.

HTTP::Cookie.new("foo", "bar").to_cookie_header                        # => "foo=bar"
HTTP::Cookie.new("foo", "bar", domain: "example.com").to_cookie_header # => "foo=bar

to_s(io : IO) : Nil

Returns a string representation of this cookie.

It uses the Set-Cookie serialization from #to_set_cookie_header which represents the full state of the cookie.

HTTP::Cookie.new("foo", "bar").to_s                        # => "foo=bar"
HTTP::Cookie.new("foo", "bar", domain: "example.com").to_s # => "foo=bar; domain=example.com"

to_set_cookie_header(io : IO) : Nil

Returns a string representation of this cookie in the format used by the Set-Cookie header of an HTTP response.

HTTP::Cookie.new("foo", "bar").to_set_cookie_header                        # => "foo=bar"
HTTP::Cookie.new("foo", "bar", domain: "example.com").to_set_cookie_header # => "foo=bar; domain=example.com"

to_set_cookie_header

Returns a string representation of this cookie in the format used by the Set-Cookie header of an HTTP response.

HTTP::Cookie.new("foo", "bar").to_set_cookie_header                        # => "foo=bar"
HTTP::Cookie.new("foo", "bar", domain: "example.com").to_set_cookie_header # => "foo=bar; domain=example.com"

valid?

Returns false if #name has a security prefix but the requirements are not met as per RFC 6265 bis §4.1.3, otherwise returns true.

validate!

Raises ArgumentError if self is not #valid?.

value

value=(value : String) : String

Sets the value of this cookie.

Raises IO::Error if the value is invalid as per RFC 6265 §4.1.1.

Nested types

HTTP::Cookie::SameSite