Expose an idiomatic `Wreq::CookieJar` collection and URL-scoped lookup

[ZilvinasKucinskas]

Priority: P2

Blocked by: Rust wreq cookie-store correctness work

Related API contract: Provide a stable error hierarchy and safe, class-specific metadata

Describe the issue

The public type is currently named Wreq::Jar. It can add, remove, clear, and return all stored cookies, but the short name is ambiguous outside the cookie implementation and the object does not follow normal Ruby collection protocols.

The first Ruby-facing improvement should stay close to the cookie operations that Rust wreq can support reliably:

• use the descriptive public name Wreq::CookieJar while retaining Wreq::Jar as a compatibility alias;
• provide ordinary Enumerable inspection;
• expose the cookie jar owned by a client; and
• provide URL-scoped selection using the exact same matching and ordering as the outbound Cookie header.

This issue intentionally does not design persistence or a browser database API. Cookie storage correctness and the metadata needed for reliable URL selection must first be fixed in the underlying Rust wreq cookie-store issues linked above; the Ruby API should ship after those prerequisites rather than expose incorrect selection in the meantime.

Proposed Ruby API

jar = Wreq::CookieJar.new
Wreq::Jar == Wreq::CookieJar # => true, compatibility alias

jar.add("session=abc; Path=/", "https://www.example.com/login")

jar.each { |cookie| puts cookie.name }
jar.each # => Enumerator
jar.size
jar.empty?
jar.to_a

client = Wreq::Client.new(cookie_store: true, cookie_provider: jar)
client.cookie_jar # => jar, or an equivalent wrapper over the same store

jar.cookies_for("https://www.example.com/account")
# => [#<Wreq::Cookie ...>]

cookies_for(uri) must return every eligible cookie in the same order used to construct an outbound request. It must not implement a second Ruby matching algorithm. If Rust wreq cannot expose the selected cookie records separately from the serialized header, that capability should be added upstream before this method ships.

A single get(name, uri) API is not required by this issue. Multiple applicable cookies can legitimately have the same name at different paths or domains, so returning one cookie is ambiguous.

Collection and mutation semantics

• Wreq::CookieJar includes Enumerable.
• each yields stored Wreq::Cookie values and returns an Enumerator without a block.
• size, empty?, and to_a behave like ordinary Ruby collections.
• add, delete, and clear return self on success.
• delete(cookie) removes one precise stored identity once upstream exposes enough identity metadata. Existing remove(name, uri) remains available with its exact-match behavior documented.
• Unsupported Ruby value types raise TypeError; malformed cookie strings and URIs raise ArgumentError or a documented Wreq::CookieError.
• Errors and inspect do not expose cookie values, URL credentials, or other secrets.

Metadata intentionally deferred

The current binding already exposes domain, path, max_age, expires, secure?, and http_only?. Additional readers such as host_only?, session?, expires_at, created_at, and complete SameSite state are useful, but they should be added only when Rust wreq retains authoritative values for them.

In particular, the Ruby wrapper must not infer host-only scope from domain text or compute an absolute Max-Age deadline without the original storage time. Such guesses would make the inspection API disagree with actual outbound behavior.

Cookie time conversion itself is tracked separately in the cookie time-value draft.

Acceptance criteria

• Wreq::CookieJar is the documented public name and Wreq::Jar remains compatible.
• The jar includes Enumerable; blockless each returns an Enumerator.
• size, empty?, and to_a are implemented and documented.
• Client#cookie_jar returns the configured/store-enabled jar, and returns nil when the client has no cookie store.
• Invalid Ruby argument types raise instead of being silently ignored.
• cookies_for(uri) is backed by the native store's canonical selection and ordering rather than reimplemented in Ruby.
• No metadata reader ships until its underlying stored value and semantics are authoritative.
• Tests cover aliases, enumeration, client access, invalid input, duplicate-name cookies, and URL-scoped lookup when supported upstream.

Ruby and binding precedent

• Ruby libraries use the explicit term CookieJar: HTTP::CookieJar and HTTPX::Plugins::Cookies::Jar both place the jar within an explicit cookie namespace.
• wreq-python exposes the same native jar with a deliberately small get/get_all/add/remove/clear surface, and its client exposes the configured cookie jar.

Relevant source

• Rust wreq cookie jar
• wreq-ruby src/cookie.rs
• wreq-ruby lib/wreq_ruby/cookie.rb