### Start HttpCookie Jar Server

Source: https://context7.com/reisub/http_cookie/llms.txt

Starts a GenServer process to manage a cookie jar, enabling stateful and concurrent cookie management. Can be started with default options, custom jar options, or a pre-populated jar.

```elixir
# Start with default empty jar
{:ok, pid} = HttpCookie.Jar.Server.start_link()

# Start with custom jar options
{:ok, pid} = HttpCookie.Jar.Server.start_link(
  jar: HttpCookie.Jar.new(max_cookies: 500)
)

# Start with pre-populated jar
existing_jar = HttpCookie.Jar.new()
{:ok, pid} = HttpCookie.Jar.Server.start_link(jar: existing_jar)
```

--------------------------------

### HttpCookie.Jar.Server.start_link/1

Source: https://context7.com/reisub/http_cookie/llms.txt

Starts a GenServer process that wraps a cookie jar, enabling stateful cookie management.

```APIDOC
## HttpCookie.Jar.Server.start_link/1

### Description
Starts a GenServer process that wraps a cookie jar, enabling stateful cookie management for HTTP clients that don't support passing updated state between requests. The server maintains the jar state internally and handles concurrent access.

### Method
`HttpCookie.Jar.Server.start_link/1`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
# Start with default empty jar
{:ok, pid} = HttpCookie.Jar.Server.start_link()

# Start with custom jar options
{:ok, pid} = HttpCookie.Jar.Server.start_link(
  jar: HttpCookie.Jar.new(max_cookies: 500)
)

# Start with pre-populated jar
existing_jar = HttpCookie.Jar.new()
{:ok, pid} = HttpCookie.Jar.Server.start_link(jar: existing_jar)
```

### Response
#### Success Response (200)
Returns `{:ok, pid}` where `pid` is the PID of the started GenServer process.

#### Response Example
```elixir
{:ok, #PID<0.123.0>}
```
```

--------------------------------

### HttpCookie Tesla Middleware Setup

Source: https://context7.com/reisub/http_cookie/llms.txt

Configures Tesla middleware for automatic cookie management using a jar server process. Ensure this middleware is placed after redirect-handling middleware.

```elixir
# Start a jar server for the client
{:ok, jar_pid} = HttpCookie.Jar.Server.start_link()

# Create a Tesla client with cookie middleware
client = Tesla.client([
  Tesla.Middleware.FollowRedirects,  # Must come before cookie middleware
  {HttpCookie.TeslaMiddleware, jar_server: jar_pid}
])

# Make requests - cookies are handled automatically
{:ok, %Tesla.Env{}} = Tesla.post(client, "https://example.com/login",
  %{username: "user", password: "pass"},
  headers: [{"content-type", "application/json"}]
)

# Subsequent requests automatically include cookies from previous responses
{:ok, %Tesla.Env{body: profile}} = Tesla.get(client, "https://example.com/profile")

# Access the jar directly if needed
jar = HttpCookie.Jar.Server.get_cookie_jar(jar_pid)
```

--------------------------------

### Get Matching Cookies from HttpCookie.Jar

Source: https://context7.com/reisub/http_cookie/llms.txt

Returns all non-expired cookies matching a URL, along with an updated jar reflecting refreshed last access times. Useful for direct access to cookie structs.

```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com/dashboard")

headers = [
  {"Set-Cookie", "session=active"},
  {"Set-Cookie", "theme=dark"},
  {"Set-Cookie", "admin=true; Path=/admin"}  # Won't match /dashboard
]
jar = HttpCookie.Jar.put_cookies_from_headers(jar, url, headers)

{matching_cookies, updated_jar} = HttpCookie.Jar.get_matching_cookies(jar, url)
# matching_cookies => [%HttpCookie{name: "session"}, %HttpCookie{name: "theme"}]

Enum.each(matching_cookies, fn cookie ->
  IO.puts("#{cookie.name}: secure=#{cookie.secure_only?}, http_only=#{cookie.http_only?}")
end)
```

--------------------------------

### Get Cookie Header Value from HttpCookie.Jar

Source: https://context7.com/reisub/http_cookie/llms.txt

Retrieves matching cookies for a URL and formats them into a `Cookie` header string, sorted by path length and creation time. Updates the last access time for matched cookies.

```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com/api/users")

# Add some cookies
headers = [
  {"Set-Cookie", "session=abc123; Path=/"},
  {"Set-Cookie", "api_token=xyz789; Path=/api"}
]
jar = HttpCookie.Jar.put_cookies_from_headers(jar, url, headers)

# Get cookie header for a request
case HttpCookie.Jar.get_cookie_header_value(jar, url) do
  {:ok, header_value, updated_jar} ->
    # header_value => "api_token=xyz789; session=abc123"
    # Note: longer path cookie comes first
    IO.puts("Cookie: #{header_value}")
    # Use updated_jar for subsequent requests (last_access_time updated)

  {:error, :no_matching_cookies} ->
    IO.puts("No cookies to send")
end
```

--------------------------------

### Get Cookie Header Value from Jar Server

Source: https://context7.com/reisub/http_cookie/llms.txt

Retrieves the formatted cookie header string for a request URL from the jar server. Returns `{:error, :no_matching_cookies}` if no cookies are found.

```elixir
{:ok, pid} = HttpCookie.Jar.Server.start_link()
url = URI.parse("https://example.com")

# Store some cookies first
HttpCookie.Jar.Server.put_cookies_from_headers(pid, url, [
  {"Set-Cookie", "foo=bar"},
  {"Set-Cookie", "baz=qux"}
])

case HttpCookie.Jar.Server.get_cookie_header_value(pid, url) do
  {:ok, header_value} ->
    # header_value => "foo=bar; baz=qux"
    :ok

  {:error, :no_matching_cookies} ->
    :no_cookies
end
```

--------------------------------

### Create a new HttpCookie.Jar

Source: https://context7.com/reisub/http_cookie/llms.txt

Creates a new cookie jar with optional configuration for maximum cookies and cookies per domain. Default limits are 5000 cookies total and 100 per domain.

```elixir
jar = HttpCookie.Jar.new()
```

```elixir
jar = HttpCookie.Jar.new(
  max_cookies: 1000,
  max_cookies_per_domain: 50,
  cookie_opts: [max_cookie_size: 4096]
)
```

```elixir
jar = HttpCookie.Jar.new(
  max_cookies: :infinity,
  max_cookies_per_domain: :infinity
)
```

--------------------------------

### Manage HttpCookie Jar

Source: https://github.com/reisub/http_cookie/blob/main/README.md

Create a cookie jar, add cookies from response headers, and retrieve cookie header values for requests.

```elixir
url = URI.parse("https://example.com")

# create a cookie jar
jar = HttpCookie.Jar.new()

# when a response is received, save any cookies that might have been returned
received_headers = [{"Set-Cookie", "foo=bar"}]
jar = HttpCookie.Jar.put_cookies_from_headers(jar, url, received_headers)

# before making requests, prepare the cookie header
{:ok, cookie_header_value, jar} = HttpCookie.Jar.get_cookie_header_value(jar, url)
```

--------------------------------

### Populate HttpCookie.Jar from Response Headers

Source: https://context7.com/reisub/http_cookie/llms.txt

Processes HTTP response headers to extract and store `Set-Cookie` or `Set-Cookie2` headers into the jar. Invalid cookies are ignored. This is the primary method for populating the jar from HTTP responses.

```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com/login")

response_headers = [
  {"Content-Type", "application/json"},
  {"Set-Cookie", "session_id=abc123; HttpOnly; Secure"},
  {"Set-Cookie", "user_pref=dark; Max-Age=86400"},
  {"X-Request-Id", "12345"}
]

jar = HttpCookie.Jar.put_cookies_from_headers(jar, url, response_headers)

{cookies, _jar} = HttpCookie.Jar.get_matching_cookies(jar, url)
# cookies contains both session_id and user_pref cookies
```

--------------------------------

### HttpCookie.Jar.new/1

Source: https://context7.com/reisub/http_cookie/llms.txt

Creates a new empty cookie jar with optional configuration for maximum cookies, maximum cookies per domain, and cookie parsing options. The jar automatically enforces these limits by evicting the least recently accessed cookies when limits are exceeded.

```APIDOC
## HttpCookie.Jar.new/1

### Description
Creates a new empty cookie jar with optional configuration for maximum cookies, maximum cookies per domain, and cookie parsing options. The jar automatically enforces these limits by evicting the least recently accessed cookies when limits are exceeded.

### Method
`HttpCookie.Jar.new/1`

### Parameters
#### Keyword Arguments
- **max_cookies** (integer | :infinity) - Optional - Maximum number of cookies the jar can hold.
- **max_cookies_per_domain** (integer | :infinity) - Optional - Maximum number of cookies allowed per domain.
- **cookie_opts** (list) - Optional - Options for cookie parsing, e.g., `[max_cookie_size: 4096]`.

### Request Example
```elixir
# Create a default jar (max 5000 cookies, 100 per domain)
jar = HttpCookie.Jar.new()

# Create a jar with custom limits
jar = HttpCookie.Jar.new(
  max_cookies: 1000,
  max_cookies_per_domain: 50,
  cookie_opts: [max_cookie_size: 4096]
)

# Create an unlimited jar
jar = HttpCookie.Jar.new(
  max_cookies: :infinity,
  max_cookies_per_domain: :infinity
)
```
```

--------------------------------

### Add HttpCookie Dependency to Mix Project

Source: https://github.com/reisub/http_cookie/blob/main/README.md

Add the http_cookie package to your project's dependencies in mix.exs.

```elixir
def deps do
  [
    {:http_cookie, "~> 0.9.1"}
  ]
end
```

--------------------------------

### Integrate HttpCookie with Tesla

Source: https://github.com/reisub/http_cookie/blob/main/README.md

Use HttpCookie.TeslaMiddleware with a running cookie jar server to manage cookies in Tesla requests.

```elixir
 {:ok, server_pid} = HttpCookie.Jar.Server.start_link()
tesla = Tesla.client([{HttpCookie.TeslaMiddleware, jar_server: server_pid}])

Tesla.get!(tesla, "https://example.com/one")
Tesla.get!(tesla, "https://example.com/two")
```

--------------------------------

### Put Cookies from Headers to Jar Server

Source: https://context7.com/reisub/http_cookie/llms.txt

Processes response headers and stores cookies in the jar server. This is the server-based equivalent of `HttpCookie.Jar.put_cookies_from_headers/3`.

```elixir
{:ok, pid} = HttpCookie.Jar.Server.start_link()
url = URI.parse("https://example.com/api")

response_headers = [
  {"Set-Cookie", "auth=token123; Secure; HttpOnly"},
  {"Content-Type", "application/json"}
]

:ok = HttpCookie.Jar.Server.put_cookies_from_headers(pid, url, response_headers)
```

--------------------------------

### HttpCookie.TeslaMiddleware

Source: https://context7.com/reisub/http_cookie/llms.txt

Tesla middleware for automatic cookie management using a jar server process.

```APIDOC
## HttpCookie.TeslaMiddleware

### Description
Tesla middleware for automatic cookie management using a jar server process. Must be listed after redirect-handling middleware to ensure cookies are properly handled during redirects.

### Method
`HttpCookie.TeslaMiddleware`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
# Start a jar server for the client
{:ok, jar_pid} = HttpCookie.Jar.Server.start_link()

# Create a Tesla client with cookie middleware
client = Tesla.client([
  Tesla.Middleware.FollowRedirects,  # Must come before cookie middleware
  {HttpCookie.TeslaMiddleware, jar_server: jar_pid}
])

# Make requests - cookies are handled automatically
{:ok, %Tesla.Env{}} = Tesla.post(client, "https://example.com/login",
  %{username: "user", password: "pass"},
  headers: [{"content-type", "application/json"}]
)

# Subsequent requests automatically include cookies from previous responses
{:ok, %Tesla.Env{body: profile}} = Tesla.get(client, "https://example.com/profile")

# Access the jar directly if needed
jar = HttpCookie.Jar.Server.get_cookie_jar(jar_pid)
```

### Response
#### Success Response (200)
Handles cookie management automatically during Tesla requests.

#### Response Example
```elixir
# Cookies are automatically sent with requests and updated from responses.
```
```

--------------------------------

### HttpCookie.Jar.put_cookies_from_headers/3

Source: https://context7.com/reisub/http_cookie/llms.txt

Processes HTTP response headers and extracts any `Set-Cookie` or `Set-Cookie2` headers, parsing them into cookies and storing valid ones in the jar. Invalid cookies are silently ignored. This is the primary method for populating a cookie jar from HTTP responses.

```APIDOC
## HttpCookie.Jar.put_cookies_from_headers/3

### Description
Processes HTTP response headers and extracts any `Set-Cookie` or `Set-Cookie2` headers, parsing them into cookies and storing valid ones in the jar. Invalid cookies are silently ignored. This is the primary method for populating a cookie jar from HTTP responses.

### Method
`HttpCookie.Jar.put_cookies_from_headers/3`

### Parameters
#### Arguments
- **jar** (HttpCookie.Jar.t()) - The current cookie jar.
- **url** (URI.t()) - The URL associated with the response headers.
- **headers** (list) - A list of response headers, typically `[{"Header-Name", "Header-Value"}, ...]`. Expects headers like `{"Set-Cookie", "cookie_string"}`.

### Request Example
```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com/login")

response_headers = [
  {"Content-Type", "application/json"},
  {"Set-Cookie", "session_id=abc123; HttpOnly; Secure"},
  {"Set-Cookie", "user_pref=dark; Max-Age=86400"},
  {"X-Request-Id", "12345"}
]

jar = HttpCookie.Jar.put_cookies_from_headers(jar, url, response_headers)

# Verify cookies were stored
{cookies, _jar} = HttpCookie.Jar.get_matching_cookies(jar, url)
# cookies contains both session_id and user_pref cookies
```
```

--------------------------------

### Format Cookie for Request Header with HttpCookie.to_header_value/1

Source: https://context7.com/reisub/http_cookie/llms.txt

Formats a cookie into a 'name=value' string suitable for the 'Cookie' request header.

```elixir
url = URI.parse("https://example.com")
{:ok, cookie} = HttpCookie.from_cookie_string("session=abc123; Secure; HttpOnly", url)

HttpCookie.to_header_value(cookie)
# => "session=abc123"
```

--------------------------------

### Check Cookie URL Matching with HttpCookie.matches_url?/2

Source: https://context7.com/reisub/http_cookie/llms.txt

Checks if a cookie should be sent with a request to a given URL based on RFC6265 rules for domain, path, and secure flag. Useful for testing cookie matching behavior.

```elixir
url = URI.parse("https://example.com/api")

# Host-only cookie matches exact domain only
{:ok, host_cookie} = HttpCookie.from_cookie_string("foo=bar", url)
HttpCookie.matches_url?(host_cookie, URI.parse("https://example.com/api"))       # => true
HttpCookie.matches_url?(host_cookie, URI.parse("https://sub.example.com/api"))   # => false

# Domain cookie matches subdomains
{:ok, domain_cookie} = HttpCookie.from_cookie_string("foo=bar; Domain=example.com", url)
HttpCookie.matches_url?(domain_cookie, URI.parse("https://sub.example.com/api")) # => true
HttpCookie.matches_url?(domain_cookie, URI.parse("https://other.com/api"))       # => false

# Secure cookie only matches HTTPS
{:ok, secure_cookie} = HttpCookie.from_cookie_string("foo=bar; Secure", url)
HttpCookie.matches_url?(secure_cookie, URI.parse("https://example.com/api"))     # => true
HttpCookie.matches_url?(secure_cookie, URI.parse("http://example.com/api"))      # => false

# Path cookie matches path prefix
{:ok, path_cookie} = HttpCookie.from_cookie_string("foo=bar; Path=/api", url)
HttpCookie.matches_url?(path_cookie, URI.parse("https://example.com/api/users")) # => true
HttpCookie.matches_url?(path_cookie, URI.parse("https://example.com/other"))     # => false
```

--------------------------------

### HttpCookie.Jar.Server.put_cookies_from_headers/3

Source: https://context7.com/reisub/http_cookie/llms.txt

Processes response headers and stores cookies in the jar server.

```APIDOC
## HttpCookie.Jar.Server.put_cookies_from_headers/3

### Description
Processes response headers and stores cookies in the jar server. This is the server-based equivalent of `HttpCookie.Jar.put_cookies_from_headers/3`.

### Method
`HttpCookie.Jar.Server.put_cookies_from_headers/3`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
{:ok, pid} = HttpCookie.Jar.Server.start_link()
url = URI.parse("https://example.com/api")

response_headers = [
  {"Set-Cookie", "auth=token123; Secure; HttpOnly"},
  {"Content-Type", "application/json"}
]

:ok = HttpCookie.Jar.Server.put_cookies_from_headers(pid, url, response_headers)
```

### Response
#### Success Response (200)
Returns `:ok` upon successful processing of headers and storing cookies.

#### Response Example
```elixir
:ok
```
```

--------------------------------

### Parse Set-Cookie Header with HttpCookie.from_cookie_string/3

Source: https://context7.com/reisub/http_cookie/llms.txt

Parses a Set-Cookie header value into an HttpCookie struct. Handles simple session cookies, persistent cookies with attributes, and domain cookies. Rejects invalid cookies like those on public suffixes or exceeding size limits. Custom size limits can be enforced.

```elixir
url = URI.parse("https://example.com/api")

# Parse a simple session cookie
{:ok, session_cookie} = HttpCookie.from_cookie_string("session_id=abc123", url)
# => %HttpCookie{name: "session_id", value: "abc123", domain: "example.com", path: "/", persistent?: false}

# Parse a persistent cookie with attributes
{:ok, persistent_cookie} = HttpCookie.from_cookie_string(
  "auth_token=xyz789; Max-Age=3600; Path=/api; Secure; HttpOnly",
  url
)
# => %HttpCookie{name: "auth_token", value: "xyz789", path: "/api", secure_only?: true, http_only?: true, persistent?: true}

# Parse a domain cookie that applies to subdomains
{:ok, domain_cookie} = HttpCookie.from_cookie_string(
  "tracking=uuid; Domain=example.com; Expires=Sun, 31-Dec-2045 16:17:18 GMT",
  url
)
# => %HttpCookie{name: "tracking", domain: "example.com", host_only?: false, persistent?: true}

# Handle invalid cookies gracefully
{:error, :cookie_domain_public_suffix} = HttpCookie.from_cookie_string(
  "evil=cookie; Domain=co.uk",
  URI.parse("https://example.co.uk")
)

# Enforce custom size limits
{:error, :cookie_exceeds_max_size} = HttpCookie.from_cookie_string(
  String.duplicate("x", 10000),
  url,
  max_cookie_size: 8192
)
```

--------------------------------

### HttpCookie.Jar.get_matching_cookies/2

Source: https://context7.com/reisub/http_cookie/llms.txt

Returns all non-expired cookies that match the given URL along with an updated jar (with refreshed last access times). Useful when you need direct access to cookie structs rather than a formatted header string.

```APIDOC
## HttpCookie.Jar.get_matching_cookies/2

### Description
Returns all non-expired cookies that match the given URL along with an updated jar (with refreshed last access times). Useful when you need direct access to cookie structs rather than a formatted header string.

### Method
`HttpCookie.Jar.get_matching_cookies/2`

### Parameters
#### Arguments
- **jar** (HttpCookie.Jar.t()) - The current cookie jar.
- **url** (URI.t()) - The URL for which to retrieve matching cookies.

### Response
#### Success Response
- **{matching_cookies, updated_jar}** - A tuple containing a list of matching `HttpCookie.t()` structs and the updated jar.

### Request Example
```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com/dashboard")

headers = [
  {"Set-Cookie", "session=active"},
  {"Set-Cookie", "theme=dark"},
  {"Set-Cookie", "admin=true; Path=/admin"}  # Won't match /dashboard
]
jar = HttpCookie.Jar.put_cookies_from_headers(jar, url, headers)

{matching_cookies, updated_jar} = HttpCookie.Jar.get_matching_cookies(jar, url)
# matching_cookies => [%HttpCookie{name: "session"}, %HttpCookie{name: "theme"}]

Enum.each(matching_cookies, fn cookie ->
  IO.puts("#{cookie.name}: secure=#{cookie.secure_only?}, http_only=#{cookie.http_only?}")
end)
```
```

--------------------------------

### Store a Single Cookie in HttpCookie.Jar

Source: https://context7.com/reisub/http_cookie/llms.txt

Stores a single cookie directly in the jar, replacing existing cookies with the same name, domain, and path while preserving the original creation time. Expired cookies are removed, and limits are enforced.

```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com")

{:ok, cookie1} = HttpCookie.from_cookie_string("foo=bar", url)
jar = HttpCookie.Jar.put_cookie(jar, cookie1)

{:ok, cookie2} = HttpCookie.from_cookie_string("baz=qux; Path=/api", url)
jar = HttpCookie.Jar.put_cookie(jar, cookie2)

# Updating an existing cookie preserves creation time
{:ok, updated_cookie} = HttpCookie.from_cookie_string("foo=newvalue", url)
jar = HttpCookie.Jar.put_cookie(jar, updated_cookie)
```

--------------------------------

### Integrate HttpCookie with Req

Source: https://github.com/reisub/http_cookie/blob/main/README.md

Attach the HttpCookie ReqPlugin to automatically handle cookies in Req requests. The cookie jar is updated after each request.

```elixir
empty_jar = HttpCookie.Jar.new()

req =
  Req.new(base_url: "https://example.com", plug: plug)
  |> HttpCookie.ReqPlugin.attach()

%{private: %{cookie_jar: updated_jar}} = Req.get!(req, url: "/one", cookie_jar: empty_jar)
%{private: %{cookie_jar: updated_jar}} = Req.get!(req, url: "/two", cookie_jar: updated_jar)
```

--------------------------------

### HttpCookie.Jar.get_cookie_header_value/2

Source: https://context7.com/reisub/http_cookie/llms.txt

Retrieves all cookies matching the request URL and formats them as a single `Cookie` header value string. Cookies are sorted by path length (longest first) and creation time (oldest first) as specified by RFC6265. Updates the last access time for all matched cookies.

```APIDOC
## HttpCookie.Jar.get_cookie_header_value/2

### Description
Retrieves all cookies matching the request URL and formats them as a single `Cookie` header value string. Cookies are sorted by path length (longest first) and creation time (oldest first) as specified by RFC6265. Updates the last access time for all matched cookies.

### Method
`HttpCookie.Jar.get_cookie_header_value/2`

### Parameters
#### Arguments
- **jar** (HttpCookie.Jar.t()) - The current cookie jar.
- **url** (URI.t()) - The URL for which to retrieve matching cookies.

### Response
#### Success Response
- **{:ok, header_value, updated_jar}** - A tuple containing the formatted `Cookie` header string and the updated jar.
- **{:error, :no_matching_cookies}** - If no cookies match the given URL.

### Request Example
```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com/api/users")

# Add some cookies
headers = [
  {"Set-Cookie", "session=abc123; Path=/"},
  {"Set-Cookie", "api_token=xyz789; Path=/api"}
]
jar = HttpCookie.Jar.put_cookies_from_headers(jar, url, headers)

# Get cookie header for a request
case HttpCookie.Jar.get_cookie_header_value(jar, url) do
  {:ok, header_value, updated_jar} ->
    # header_value => "api_token=xyz789; session=abc123"
    # Note: longer path cookie comes first
    IO.puts("Cookie: #{header_value}")
    # Use updated_jar for subsequent requests (last_access_time updated)

  {:error, :no_matching_cookies} ->
    IO.puts("No cookies to send")
end
```
```

--------------------------------

### Parse Cookie String to HttpCookie Struct

Source: https://context7.com/reisub/http_cookie/llms.txt

Parses a cookie string into an HttpCookie struct. This is a foundational step for managing cookies, often used before adding them to a jar.

```elixir
{:ok, session} = HttpCookie.from_cookie_string("session=temp", url)
HttpCookie.expired?(session)  # => false
```

--------------------------------

### HttpCookie.matches_url?/2

Source: https://context7.com/reisub/http_cookie/llms.txt

Checks if a cookie should be sent with a request to a given URL, adhering to RFC6265 matching rules for domain, path, and secure flag. This is useful for testing cookie matching logic.

```APIDOC
## HttpCookie.matches_url?/2

### Description
Checks if a cookie should be sent with a request to the given URL, following RFC6265 matching rules for domain, path, and secure flag. This function is used internally by the cookie jar but can also be called directly to test cookie matching behavior.

### Method
`HttpCookie.matches_url?/2`

### Parameters
#### Path Parameters
- **cookie** (HttpCookie.t()) - Required - The cookie struct to check.
- **url** (URI.t()) - Required - The URL to match against.

### Request Example
```elixir
url = URI.parse("https://example.com/api")

# Host-only cookie matches exact domain only
{:ok, host_cookie} = HttpCookie.from_cookie_string("foo=bar", url)
HttpCookie.matches_url?(host_cookie, URI.parse("https://example.com/api"))       # => true
HttpCookie.matches_url?(host_cookie, URI.parse("https://sub.example.com/api"))   # => false

# Domain cookie matches subdomains
{:ok, domain_cookie} = HttpCookie.from_cookie_string("foo=bar; Domain=example.com", url)
HttpCookie.matches_url?(domain_cookie, URI.parse("https://sub.example.com/api")) # => true
HttpCookie.matches_url?(domain_cookie, URI.parse("https://other.com/api"))       # => false

# Secure cookie only matches HTTPS
{:ok, secure_cookie} = HttpCookie.from_cookie_string("foo=bar; Secure", url)
HttpCookie.matches_url?(secure_cookie, URI.parse("https://example.com/api"))     # => true
HttpCookie.matches_url?(secure_cookie, URI.parse("http://example.com/api"))      # => false

# Path cookie matches path prefix
{:ok, path_cookie} = HttpCookie.from_cookie_string("foo=bar; Path=/api", url)
HttpCookie.matches_url?(path_cookie, URI.parse("https://example.com/api/users")) # => true
HttpCookie.matches_url?(path_cookie, URI.parse("https://example.com/other"))     # => false
```

### Response
#### Success Response (200)
- **boolean** - Returns `true` if the cookie matches the URL, `false` otherwise.
```

--------------------------------

### HttpCookie.to_header_value/1

Source: https://context7.com/reisub/http_cookie/llms.txt

Formats an HttpCookie struct into a string suitable for the `Cookie` request header.

```APIDOC
## HttpCookie.to_header_value/1

### Description
Formats a cookie for inclusion in a `Cookie` request header by returning the `name=value` pair as a string.

### Method
`HttpCookie.to_header_value/1`

### Parameters
#### Path Parameters
- **cookie** (HttpCookie.t()) - Required - The cookie struct to format.

### Request Example
```elixir
url = URI.parse("https://example.com")
{:ok, cookie} = HttpCookie.from_cookie_string("session=abc123; Secure; HttpOnly", url)

HttpCookie.to_header_value(cookie)
# => "session=abc123"
```

### Response
#### Success Response (200)
- **string** - The formatted `name=value` string for the `Cookie` header.
```

--------------------------------

### HttpCookie.ReqPlugin.attach/2

Source: https://context7.com/reisub/http_cookie/llms.txt

Attaches the HttpCookie plugin to a Req request pipeline for automatic cookie handling.

```APIDOC
## HttpCookie.ReqPlugin.attach/2

### Description
Attaches the HttpCookie plugin to a Req request pipeline, enabling automatic cookie handling for all requests made with that client. The plugin extracts cookies from responses and includes matching cookies in subsequent requests.

### Method
`HttpCookie.ReqPlugin.attach/2`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
# Create a Req client with cookie support
jar = HttpCookie.Jar.new()

req = Req.new(base_url: "https://api.example.com")
      |> HttpCookie.ReqPlugin.attach()

# Make requests with cookie jar
# First request - login and receive cookies
%Req.Response{private: %{cookie_jar: updated_jar}} =
  Req.post!(req, url: "/auth/login",
    json: %{username: "user", password: "pass"},
    cookie_jar: jar
  )

# Subsequent request - cookies are automatically included
%Req.Response{private: %{cookie_jar: final_jar}} =
  Req.get!(req, url: "/api/profile", cookie_jar: updated_jar)

# The jar is passed through each request and returned in response.private.cookie_jar
# Manual cookie headers take precedence if set explicitly
```

### Response
#### Success Response (200)
Returns the modified Req client with the HttpCookie plugin attached.

#### Response Example
```elixir
# Req client with cookie plugin attached
```
```

--------------------------------

### HttpCookie.Jar.put_cookie/2

Source: https://context7.com/reisub/http_cookie/llms.txt

Stores a single cookie directly in the jar. If a cookie with the same name, domain, and path already exists, it is replaced but the original creation time is preserved. Expired cookies are automatically removed and limits are enforced after insertion.

```APIDOC
## HttpCookie.Jar.put_cookie/2

### Description
Stores a single cookie directly in the jar. If a cookie with the same name, domain, and path already exists, it is replaced but the original creation time is preserved. Expired cookies are automatically removed and limits are enforced after insertion.

### Method
`HttpCookie.Jar.put_cookie/2`

### Parameters
#### Arguments
- **jar** (HttpCookie.Jar.t()) - The current cookie jar.
- **cookie** (HttpCookie.t()) - The cookie struct to add or update.

### Request Example
```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com")

{:ok, cookie1} = HttpCookie.from_cookie_string("foo=bar", url)
jar = HttpCookie.Jar.put_cookie(jar, cookie1)

{:ok, cookie2} = HttpCookie.from_cookie_string("baz=qux; Path=/api", url)
jar = HttpCookie.Jar.put_cookie(jar, cookie2)

# Updating an existing cookie preserves creation time
{:ok, updated_cookie} = HttpCookie.from_cookie_string("foo=newvalue", url)
jar = HttpCookie.Jar.put_cookie(jar, updated_cookie)
```
```

--------------------------------

### HttpCookie.from_cookie_string/3

Source: https://context7.com/reisub/http_cookie/llms.txt

Parses a `Set-Cookie` header value into an HttpCookie struct. It validates the cookie against the request URL and RFC6265 rules, processing attributes like Expires, Max-Age, Domain, Path, Secure, and HttpOnly. It rejects cookies with public suffix domains or exceeding size limits.

```APIDOC
## HttpCookie.from_cookie_string/3

### Description
Parses a `Set-Cookie` header value into an HttpCookie struct, validating the cookie against the request URL and RFC6265 rules. The function processes all standard cookie attributes including `Expires`, `Max-Age`, `Domain`, `Path`, `Secure`, and `HttpOnly`, automatically rejecting cookies that attempt to set domains on public suffixes or exceed size limits.

### Method
`HttpCookie.from_cookie_string/3`

### Parameters
#### Path Parameters
- **cookie_string** (string) - Required - The `Set-Cookie` header value to parse.
- **url** (URI.t()) - Required - The URL the cookie is associated with.
- **opts** (keyword) - Optional - Options for parsing, e.g., `max_cookie_size`.

### Request Example
```elixir
url = URI.parse("https://example.com/api")

# Parse a simple session cookie
{:ok, session_cookie} = HttpCookie.from_cookie_string("session_id=abc123", url)
# => %HttpCookie{name: "session_id", value: "abc123", domain: "example.com", path: "/", persistent?: false}

# Parse a persistent cookie with attributes
{:ok, persistent_cookie} = HttpCookie.from_cookie_string(
  "auth_token=xyz789; Max-Age=3600; Path=/api; Secure; HttpOnly",
  url
)
# => %HttpCookie{name: "auth_token", value: "xyz789", path: "/api", secure_only?: true, http_only?: true, persistent?: true}

# Parse a domain cookie that applies to subdomains
{:ok, domain_cookie} = HttpCookie.from_cookie_string(
  "tracking=uuid; Domain=example.com; Expires=Sun, 31-Dec-2045 16:17:18 GMT",
  url
)
# => %HttpCookie{name: "tracking", domain: "example.com", host_only?: false, persistent?: true}

# Handle invalid cookies gracefully
{:error, :cookie_domain_public_suffix} = HttpCookie.from_cookie_string(
  "evil=cookie; Domain=co.uk",
  URI.parse("https://example.co.uk")
)

# Enforce custom size limits
{:error, :cookie_exceeds_max_size} = HttpCookie.from_cookie_string(
  String.duplicate("x", 10000),
  url,
  max_cookie_size: 8192
)
```

### Response
#### Success Response (200)
- **:ok** (tuple) - A tuple containing `:ok` and the parsed `HttpCookie` struct.
- **:error** (tuple) - A tuple containing `:error` and an atom indicating the reason for failure (e.g., `:cookie_domain_public_suffix`, `:cookie_exceeds_max_size`).
```

--------------------------------

### Attach HttpCookie Req Plugin

Source: https://context7.com/reisub/http_cookie/llms.txt

Attaches the HttpCookie plugin to a Req request pipeline for automatic cookie handling. The plugin manages cookies across requests, extracting them from responses and including them in subsequent requests.

```elixir
# Create a Req client with cookie support
jar = HttpCookie.Jar.new()

req = Req.new(base_url: "https://api.example.com")
      |> HttpCookie.ReqPlugin.attach()

# Make requests with cookie jar
# First request - login and receive cookies
%Req.Response{private: %{cookie_jar: updated_jar}} =
  Req.post!(req, url: "/auth/login",
    json: %{username: "user", password: "pass"},
    cookie_jar: jar
  )

# Subsequent request - cookies are automatically included
%Req.Response{private: %{cookie_jar: final_jar}} =
  Req.get!(req, url: "/api/profile", cookie_jar: updated_jar)

# The jar is passed through each request and returned in response.private.cookie_jar
# Manual cookie headers take precedence if set explicitly
```

--------------------------------

### HttpCookie.Jar.Server.get_cookie_header_value/2

Source: https://context7.com/reisub/http_cookie/llms.txt

Retrieves the cookie header value for a request URL from the jar server.

```APIDOC
## HttpCookie.Jar.Server.get_cookie_header_value/2

### Description
Retrieves the cookie header value for a request URL from the jar server. Returns the formatted header string ready to include in outgoing requests.

### Method
`HttpCookie.Jar.Server.get_cookie_header_value/2`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
{:ok, pid} = HttpCookie.Jar.Server.start_link()
url = URI.parse("https://example.com")

# Store some cookies first
HttpCookie.Jar.Server.put_cookies_from_headers(pid, url, [
  {"Set-Cookie", "foo=bar"},
  {"Set-Cookie", "baz=qux"}
])

case HttpCookie.Jar.Server.get_cookie_header_value(pid, url) do
  {:ok, header_value} ->
    # header_value => "foo=bar; baz=qux"
    :ok

  {:error, :no_matching_cookies} ->
    :no_cookies
end
```

### Response
#### Success Response (200)
Returns `{:ok, header_value}` where `header_value` is the formatted cookie header string.

#### Error Response
Returns `{:error, :no_matching_cookies}` if no cookies are found for the given URL.

#### Response Example
```elixir
{:ok, "foo=bar; baz=qux"}
```
```

--------------------------------

### Clear Expired Cookies

Source: https://context7.com/reisub/http_cookie/llms.txt

Removes cookies that have expired before a specified future time. Ensure the jar is initialized before use.

```elixir
future_time = DateTime.add(DateTime.utc_now(), 60, :second)
jar = HttpCookie.Jar.clear_expired_cookies(jar, future_time)
```

--------------------------------

### Check Cookie Expiration with HttpCookie.expired?/2

Source: https://context7.com/reisub/http_cookie/llms.txt

Checks if a cookie has expired against the current time or a provided time. Session cookies without explicit expiry are considered non-expiring.

```elixir
url = URI.parse("https://example.com")

# Expired cookie
{:ok, expired} = HttpCookie.from_cookie_string("old=data; Max-Age=0", url)
HttpCookie.expired?(expired)  # => true

# Future cookie
{:ok, future} = HttpCookie.from_cookie_string("new=data; Expires=Sun, 31-Dec-2045 16:17:18 GMT", url)
HttpCookie.expired?(future)                               # => false
HttpCookie.expired?(future, ~U[2045-12-31 16:17:18Z])     # => false
HttpCookie.expired?(future, ~U[2045-12-31 16:17:19Z])     # => true
```

--------------------------------

### Clear Session Cookies

Source: https://context7.com/reisub/http_cookie/llms.txt

Removes all session cookies (those without an explicit expiry) from the cookie jar. This is useful for simulating the end of a user session.

```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com")

headers = [
  {"Set-Cookie", "session_id=temp"},           # Session cookie (no expiry)
  {"Set-Cookie", "remember_me=abc; Max-Age=604800"}  # Persistent cookie (1 week)
]
jar = HttpCookie.Jar.put_cookies_from_headers(jar, url, headers)

# Simulate session end
jar = HttpCookie.Jar.clear_session_cookies(jar)

{remaining, _} = HttpCookie.Jar.get_matching_cookies(jar, url)
# remaining => [%HttpCookie{name: "remember_me", persistent?: true}]
```

--------------------------------

### HttpCookie.Jar.clear_expired_cookies/2

Source: https://context7.com/reisub/http_cookie/llms.txt

Clears cookies from a jar that have expired before a specified time.

```APIDOC
## HttpCookie.Jar.clear_expired_cookies/2

### Description
Clears cookies from a jar that have expired before a specified time.

### Method
`HttpCookie.Jar.clear_expired_cookies/2`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
future_time = DateTime.add(DateTime.utc_now(), 60, :second)
jar = HttpCookie.Jar.clear_expired_cookies(jar, future_time)
```

### Response
#### Success Response (200)
Returns the updated cookie jar.

#### Response Example
```elixir
# jar is updated with expired cookies removed
```
```

--------------------------------

### Clear Expired Cookies from HttpCookie.Jar

Source: https://context7.com/reisub/http_cookie/llms.txt

Removes all cookies that have expired before a specified time, defaulting to the current time. This operation is performed automatically during cookie insertion and retrieval but can be invoked manually for cleanup.

```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com")

# Add cookies with different expiry times
headers = [
  {"Set-Cookie", "short=lived; Max-Age=10"},
  {"Set-Cookie", "long=lived; Max-Age=86400"}
]
jar = HttpCookie.Jar.put_cookies_from_headers(jar, url, headers)
```

--------------------------------

### HttpCookie.Jar.clear_session_cookies/1

Source: https://context7.com/reisub/http_cookie/llms.txt

Removes all session cookies (cookies without an explicit expiry time) from the jar.

```APIDOC
## HttpCookie.Jar.clear_session_cookies/1

### Description
Removes all session cookies (cookies without an explicit expiry time set via `Expires` or `Max-Age`) from the jar. This simulates ending a browser session where session cookies are discarded but persistent cookies remain.

### Method
`HttpCookie.Jar.clear_session_cookies/1`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com")

headers = [
  {"Set-Cookie", "session_id=temp"},           # Session cookie (no expiry)
  {"Set-Cookie", "remember_me=abc; Max-Age=604800"}  # Persistent cookie (1 week)
]
jar = HttpCookie.Jar.put_cookies_from_headers(jar, url, headers)

# Simulate session end
jar = HttpCookie.Jar.clear_session_cookies(jar)

{remaining, _} = HttpCookie.Jar.get_matching_cookies(jar, url)
# remaining => [%HttpCookie{name: "remember_me", persistent?: true}]
```

### Response
#### Success Response (200)
Returns the updated cookie jar with session cookies removed.

#### Response Example
```elixir
# jar now only contains persistent cookies
```
```

--------------------------------

### HttpCookie.Jar.clear_expired_cookies/2

Source: https://context7.com/reisub/http_cookie/llms.txt

Removes all cookies that have expired before the given time (defaults to current time). This is called automatically during cookie insertion and retrieval, but can be called manually for cleanup.

```APIDOC
## HttpCookie.Jar.clear_expired_cookies/2

### Description
Removes all cookies that have expired before the given time (defaults to current time). This is called automatically during cookie insertion and retrieval, but can be called manually for cleanup.

### Method
`HttpCookie.Jar.clear_expired_cookies/2`

### Parameters
#### Arguments
- **jar** (HttpCookie.Jar.t()) - The current cookie jar.
- **time** (DateTime.t() | NaiveDateTime.t() | integer) - Optional - The time before which cookies are considered expired. Defaults to the current time.

### Request Example
```elixir
jar = HttpCookie.Jar.new()
url = URI.parse("https://example.com")

# Add cookies with different expiry times
headers = [
  {"Set-Cookie", "short=lived; Max-Age=10"},
  {"Set-Cookie", "long=lived; Max-Age=86400"}
]
jar = HttpCookie.Jar.put_cookies_from_headers(jar, url, headers)

# Manually clear expired cookies (e.g., after 15 seconds)
# Process.sleep(15)
# jar = HttpCookie.Jar.clear_expired_cookies(jar)
```
```

--------------------------------

### HttpCookie.expired?/2

Source: https://context7.com/reisub/http_cookie/llms.txt

Checks if a cookie has expired based on its expiry time. Session cookies without an explicit expiry are considered non-expiring.

```APIDOC
## HttpCookie.expired?/2

### Description
Checks if a cookie has expired by comparing its expiry time against the current time (or a provided time). Session cookies that have no explicit expiry time are set to the latest representable date and never expire according to this function.

### Method
`HttpCookie.expired?/2`

### Parameters
#### Path Parameters
- **cookie** (HttpCookie.t()) - Required - The cookie struct to check.
- **time** (NaiveDateTime.t() | DateTime.t() | nil) - Optional - The time to compare against. Defaults to the current time.

### Request Example
```elixir
url = URI.parse("https://example.com")

# Expired cookie
{:ok, expired} = HttpCookie.from_cookie_string("old=data; Max-Age=0", url)
HttpCookie.expired?(expired)  # => true

# Future cookie
{:ok, future} = HttpCookie.from_cookie_string("new=data; Expires=Sun, 31-Dec-2045 16:17:18 GMT", url)
HttpCookie.expired?(future)                               # => false
HttpCookie.expired?(future, ~U[2045-12-31 16:17:18Z])     # => false
HttpCookie.expired?(future, ~U[2045-12-31 16:17:19Z])     # => true
```

### Response
#### Success Response (200)
- **boolean** - Returns `true` if the cookie has expired, `false` otherwise.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.