roc-lang / roc-lang/basic-webserver

Add typed request-cookie parsing and Set-Cookie rendering

Open
#199 0 comments 0 reactions 0 assignees View on GitHub

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:

  1. Parsing all Cookie request header fields while preserving duplicates.
  2. Strictly rendering one Set-Cookie header from typed attributes.
  3. Rendering a deletion cookie with matching Path and Domain.

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 Cookie header field.
  • Preserve cookie order and duplicate names as a List, not a dictionary.
  • Treat names as case-sensitive.
  • Provide an explicit get_unique helper 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-Cookie header.
  • Support Path, Domain, Max-Age, Secure, HttpOnly, and SameSite.
  • Reject SameSite=None without Secure.
  • Enforce the __Secure- and __Host- prefix requirements.
  • A deletion helper must accept the original Path and Domain scope and emit an empty value with Max-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-Cookie fields.
  • Invalid values and unsafe attribute combinations produce typed errors.
  • The implementation is pure Roc and requires no host ABI change.

References

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.