# flare.http.cookie

> A module of flare_mlake's API.

HTTP cookie support (RFC 6265).

Provides ``Cookie`` for individual cookies and ``CookieJar`` for managing
collections of cookies on both request and response sides.

Example:
    ```mojo
    from flare.http.cookie import Cookie, CookieJar

    var jar = CookieJar()
    jar.set(Cookie("session", "abc123", secure=True, http_only=True))
    var header = jar.to_request_header() # "session=abc123"
    ```

## Structs

### `SameSite`

```mojo
struct SameSite
```

SameSite attribute values for cookies.

Implements: `Movable`

#### `NONE`

```mojo
comptime NONE = String("None")
```

#### `LAX`

```mojo
comptime LAX = String("Lax")
```

#### `STRICT`

```mojo
comptime STRICT = String("Strict")
```

### `Cookie`

```mojo
struct Cookie
```

An HTTP cookie (RFC 6265).

Fields:
    name: Cookie name (must not be empty).
    value: Cookie value.
    domain: Domain attribute (empty = not set).
    path: Path attribute (empty = not set).
    max_age: Max-Age in seconds (-1 = not set, 0 = delete).
    secure: Secure flag (HTTPS only).
    http_only: HttpOnly flag (not accessible to JavaScript).
    same_site: SameSite attribute (empty = not set).

Implements: `Copyable`, `Movable`

Fields:

- `name: String`
- `value: String`
- `domain: String`
- `path: String`
- `max_age: Int`
- `secure: Bool`
- `http_only: Bool`
- `same_site: String`

#### `__init__`

```mojo
def __init__(out self, name: String, value: String, domain: String = "", path: String = "", max_age: Int = Int(-1), secure: Bool = False, http_only: Bool = False, same_site: String = "")
```

#### `session`

```mojo
def session(name: String, value: String) -> Self
```

A cookie with the attributes a session cookie should have: ``Path=/``, ``Secure``, ``HttpOnly``, ``SameSite=Lax``.

The plain constructor leaves all three flags off, which is the
RFC 6265 default but the wrong one for anything that
authenticates a user.

#### `to_set_cookie_header`

```mojo
def to_set_cookie_header(self) -> String
```

Serialise this cookie as a ``Set-Cookie`` header value.

Validates against RFC 6265 sec 4.1.1 first. ``;`` is the
attribute separator, so a value or path holding one used to
inject attributes of the sender's choosing -- ``value =
"x; Domain=.evil.com"`` widened the cookie's scope.
``SameSite=None`` implies ``Secure``, which browsers require.

Raises: Error: On an empty or non-token name, a value outside
cookie-octet, a ``Domain`` or ``Path`` with a control
byte or ``;``, or an unknown ``SameSite``.

#### `to_request_pair`

```mojo
def to_request_pair(self) -> String
```

Serialise as ``name=value`` for a ``Cookie`` request header.

### `CookieJar`

```mojo
struct CookieJar
```

A collection of cookies for request/response management.

Stores cookies by name. Supports serialisation to request ``Cookie``
header and response ``Set-Cookie`` headers.

Implements: `Copyable`, `Defaultable`, `Movable`

#### `__init__`

```mojo
def __init__(out self)
```

#### `set`

```mojo
def set(mut self, var cookie: Cookie)
```

Add or replace a cookie by name.

Args:

- `cookie`: The cookie to set (ownership taken).

#### `get`

```mojo
def get(self, name: String) -> String
```

Return the value of a cookie by name, or ``""`` if absent.

Args:

- `name`: Cookie name.

#### `remove`

```mojo
def remove(mut self, name: String) -> Bool
```

Remove a cookie by name.

Args:

- `name`: Cookie name to remove.

#### `contains`

```mojo
def contains(self, name: String) -> Bool
```

Return True if a cookie with this name exists.

#### `len`

```mojo
def len(self) -> Int
```

Return the number of cookies.

#### `to_request_header`

```mojo
def to_request_header(self) -> String
```

Serialise all cookies as a ``Cookie`` request header value.

## Functions

### `parse_cookie_header`

```mojo
def parse_cookie_header(header: String) -> List[Cookie]
```

Parse a ``Cookie`` request header value into individual cookies.

Format: ``name1=value1; name2=value2; ...``

Args:

- `header`: The ``Cookie`` header value string.

### `parse_set_cookie_header`

```mojo
def parse_set_cookie_header(header: String) -> Cookie
```

Parse a ``Set-Cookie`` response header value.

Args:

- `header`: The ``Set-Cookie`` header value string.