roc-lang / roc-lang/basic-webserver
Add typed request-cookie parsing and Set-Cookie rendering
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 107
- Forks
- 20
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 11
Description
Summary
Add a pure Cookie module for:
- Parsing all
Cookierequest header fields while preserving duplicates. - Strictly rendering one
Set-Cookieheader from typed attributes. - Rendering a deletion cookie with matching
PathandDomain.
Illustrative API:
cookies = Cookie.parse_request(request.headers())?
header = Cookie.set_header({
name: "session",
value: session_id,
path: Present("/"),
domain: Absent,
max_age_seconds: Present(3600),
secure: True,
http_only: True,
same_site: Present(Lax),
})?
Why this belongs in the platform
Cookies are a conventional HTTP primitive needed by sessions, authentication, CSRF protection, and browser-facing applications. Hand-building cookie strings is error-prone because Set-Cookie has unusual header semantics and security-sensitive attribute combinations.
The current cookie specification permits multiple Set-Cookie fields and forbids combining them with commas. Servers must also tolerate multiple request Cookie fields, particularly because HTTP/2 and HTTP/3 intermediaries may split them.
Required contract
- Parse every case-insensitive
Cookieheader field. - Preserve cookie order and duplicate names as a
List, not a dictionary. - Treat names as case-sensitive.
- Provide an explicit
get_uniquehelper that reports duplicates instead of silently choosing one. - Validate names and values against the cookie grammar and reject control characters or header injection.
- Do not implicitly percent-encode, Base64-encode, or reinterpret values.
- Render each cookie as its own
Set-Cookieheader. - Support
Path,Domain,Max-Age,Secure,HttpOnly, andSameSite. - Reject
SameSite=NonewithoutSecure. - Enforce the
__Secure-and__Host-prefix requirements. - A deletion helper must accept the original
PathandDomainscope and emit an empty value withMax-Age=0. - Header resource use remains bounded by the server's existing header limits.
Expires, Partitioned, cookie priority, and browser cookie-jar behavior can be follow-ups. Max-Age provides the initial persistent-expiry and deletion contract without introducing a general calendar API.
Tests
Include multiple header fields, duplicate names, case-sensitive names, whitespace, empty values, invalid bytes, commas, CR/LF injection, prefix rules, SameSite=None, and multiple independent Set-Cookie response headers.
Non-goals
- A browser cookie jar with domain/path matching
- Signed or encrypted cookies
- Sessions or authentication
- Public-suffix-list processing
- Automatic mutation of every request or response
- Selecting one duplicate cookie based on serialization order
Acceptance criteria
- Applications can parse all request cookie fields without losing duplicates.
- Applications can render security-sensitive cookie attributes through typed values.
- Multiple response cookies remain multiple
Set-Cookiefields. - Invalid values and unsafe attribute combinations produce typed errors.
- The implementation is pure Roc and requires no host ABI change.
References
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the request header access used by request.headers() and the response header representation for separate Set-Cookie fields. Define the pure Cookie module around the illustrated parse_request and set_header APIs, then add the listed parsing, validation, prefix, SameSite, deletion, and duplicate-header tests. Done means all acceptance criteria pass without a host ABI change.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, backend, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100