feat: add stored cookie request matching

[medz]

Summary

• add StoredCookie as a normalized client-side Set-Cookie representation
• track host-only state, normalized domain, effective path, and absolute expiry time
• implement request matching for domain, path, secure-only, and optional expiry checks
• document the new API and cover the RFC policy cases with tests

Closes #8.

Scope

This intentionally stops at single-cookie normalization and matching. The in-memory jar work remains separate for #9.

Validation

• dart test && dart analyze
• dart pub publish --dry-run

Summary by CodeRabbit

Release Notes

• New Features

  • Added cookie normalization and request-matching functionality supporting domain validation, path derivation, expiration handling, and secure flag requirements.
  • Enables conversion between Set-Cookie headers and HTTP request cookie formats.

• Documentation

  • Extended README with usage examples demonstrating cookie normalization workflows and request matching.

[coderabbitai]

Warning

Review limit reached

@medz, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 4 minutes and 10 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: de61606c-9da9-4e2f-b861-5ae507f998b3

📥 Commits

Reviewing files that changed from the base of the PR and between 3cc22ed and 70a50a0.

📒 Files selected for processing (2)

• lib/src/stored_cookie.dart
• test/stored_cookie_test.dart

📝 Walkthrough

Walkthrough

Introduces StoredCookie, a new public class in lib/src/stored_cookie.dart that normalizes a parsed Cookie against a requestUri, computing host-only status, canonical domain, effective path (with default-path derivation), and absolute expiry (Max-Age over Expires). Exposes isExpired, matches, and toRequestCookie methods. Re-exports the new file from lib/ocookie.dart and adds usage examples and utility documentation to README.md. A new test file validates all normalization and matching behaviors.

Changes

StoredCookie: normalized Set-Cookie matching primitives

Layer / File(s)	Summary
StoredCookie class and internal normalization helpers lib/src/stored_cookie.dart	Defines final class StoredCookie with fromSetCookie/fromCookie factories, isExpired, matches, and toRequestCookie. Internal helpers cover request-host normalization, domain normalization/validation, domain/path matching (including host-only vs. domain cookies, IP rejection, and RFC cookie-path prefix rules), default-path derivation, and Max-Age/Expires expiry computation with a private IPv4 regex.
StoredCookie tests test/stored_cookie_test.dart	Tests cover host-only normalization, domain attribute normalization with subdomain matching, ArgumentError for out-of-scope/single-label/IP domains, default-path derivation, path-match semantics (/docs vs /docs2), Max-Age precedence over Expires with boundary checks, immediate expiry for Max-Age <= 0, and toRequestCookie serialization with percent-encoding.
Library export and README documentation lib/ocookie.dart, README.md	Adds export 'src/stored_cookie.dart' to the library barrel and extends the README with a Basic Usage example for StoredCookie.fromSetCookie/matches/toRequestCookie and a Utils entry for the new factory.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Add normalized Set-Cookie request matching primitives #8 — This PR directly implements the StoredCookie API proposed in that issue, including fromSetCookie, hostOnly, domain, path, isExpired, matches, and toRequestCookie with all listed RFC 6265 behaviors (domain normalization, host-only flag, default-path, Max-Age precedence, secure-only matching).
• Add pluggable cookie jar primitives #9 — The new StoredCookie primitives (isExpired, matches, toRequestCookie) are explicitly identified in issue #9 as a prerequisite for building the proposed MemoryCookieJar abstraction.

Possibly related PRs

• odroe/ocookie#6: Changes Cookie.secure from nullable to non-nullable boolean, which directly affects how StoredCookie evaluates the secure-only request matching condition (cookie.secure must be truthy to enforce HTTPS).

Poem

🐇 Hop, hop! A cookie's been stored with great care,
Domain normalized, host-only declared.
Max-Age wins over Expires, every time,
Path-prefix matching, all logic sublime.
toRequestCookie() hops into the header just right—
This bunny's RFC 6265 delight! 🍪

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add stored cookie request matching' directly and clearly describes the main change: introducing StoredCookie with request matching capabilities.
Linked Issues check	✅ Passed	The PR fully implements all requirements from issue #8: StoredCookie class with host-only tracking, normalized domain, effective path, absolute expiry, and RFC 6265 request matching logic including domain/path/secure validation.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #8: StoredCookie implementation, export additions, usage documentation, and comprehensive test coverage with no extraneous modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/stored-cookie-request-matching

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/src/stored_cookie.dart`:
- Around line 128-139: The _requestHost and _normalizeDomain functions normalize
values by lowercasing and trimming but do not remove trailing dots, causing
example.com. to be treated differently from example.com. To fix this, modify the
_requestHost function to strip any trailing dot from the lowercased uri.host
value before returning it, and modify the _normalizeDomain function to strip any
trailing dot from the normalized (trimmed and lowercased) value before returning
it.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6a7fe34e-a0a2-4fce-9651-89b2afae16d8

📥 Commits

Reviewing files that changed from the base of the PR and between 546b29f and 3cc22ed.

📒 Files selected for processing (4)

• README.md
• lib/ocookie.dart
• lib/src/stored_cookie.dart
• test/stored_cookie_test.dart

[medz]

@codex review

[medz]

@codex review

[medz]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3cc22ed4a0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e14a3a4734

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".