docs: document the session name option for multiple sessions by harshagarwalnyu · Pull Request #1405 · h3js/h3

harshagarwalnyu · 2026-06-02T09:03:54Z

Closes #969.

The session example already uses the name option (name: "my-session") but never explains what it does, and the ability to run multiple independent sessions isn't documented anywhere. #969 asks for exactly this.

This adds two things to docs/4.examples/handle-session.md:

A short explanation after the existing Options example: name sets the cookie (and the x-{name}-session header) and defaults to h3, which is why the earlier examples produce a cookie named h3.
A "Use Multiple Sessions" section showing that distinct names give you independent sessions stored in separate cookies, with a note that reusing a name reuses the same cookie.

Verified against the current SessionConfig on main (name?: string, default h3, also used to derive the x-{name}-session header). Docs only, no code changes.

Summary by CodeRabbit

Documentation
- Stronger warning: password is required for session encryption; avoid hardcoding and load a strong (32+ character) secret from an environment variable.
- Clarified session options: all are optional except password; name controls the session cookie and the derived request header (lowercased).
- Added “Use Multiple Sessions” guidance: sessions with different name values can coexist without interference; reusing a name shares the cookie (last-write-wins).

coderabbitai · 2026-06-02T09:04:08Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6130be90-2214-40b0-90c7-c7586f4266c0

📥 Commits

Reviewing files that changed from the base of the PR and between 7567774 and 96e117b.

📒 Files selected for processing (1)

docs/4.examples/handle-session.md

📝 Walkthrough

Walkthrough

Documentation clarifies session password requirements, explains how name selects the cookie and x-<name>-session header, and adds an example showing two independent named sessions plus same-name cookie reuse behavior.

Changes

Session documentation: Multiple sessions

Layer / File(s)	Summary
Password encryption warning `docs/4.examples/handle-session.md`	Adds a warning that `password` must be provided to encrypt sessions and recommends sourcing a strong secret from an environment variable rather than hardcoding.
Options and multiple sessions docs `docs/4.examples/handle-session.md`	States only `password` is required, documents how `name` determines the cookie and matching `x-<name>-session` header (default `h3` → `x-h3-session`), and adds a "Use Multiple Sessions" section with separate `auth` and `flash` sessions plus a note that identical `name` values reuse the same cookie.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

h3js/h3#1409: Updates the same session example documentation and expands the options guidance around password and cookie behavior.

Suggested reviewers: pi0

Poem

🐰 I hopped through docs with careful care,
Two named sessions dance in pairs,
One cookie shared when names align,
Strong secrets tucked in envs shine,
H3 hops on, all tidy there.

🚥 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 clearly and specifically describes the main change: documenting the session name option for multiple sessions, which is exactly what this PR accomplishes.
Linked Issues check	✅ Passed	The PR fully addresses issue `#969` by documenting that useSession accepts a name option, explaining how distinct names create independent sessions, clarifying that name determines the cookie and x-{name}-session header pattern, and showing practical examples.
Out of Scope Changes check	✅ Passed	All changes are scoped to documenting the session name option and multiple sessions feature as requested in `#969`; no code modifications or unrelated documentation changes are included.
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

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

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

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

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds documentation explaining session option defaults and demonstrates how to use multiple independent sessions in the same request.

Changes:

Clarifies that all session options are optional except password, and explains the name option’s impact on cookie/header naming.
Adds an example showing two independent sessions (auth and flash) coexisting without overwriting each other.
Adds a note warning that sessions sharing a name share the same cookie and will overwrite.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

harshagarwalnyu · 2026-06-03T10:29:03Z

 });
 ```
+
+Every option is optional except `password`. The `name` option is worth calling out: it sets the cookie (and the `x-{name}-session` header) used to store the session, and defaults to `h3`. That default is why the earlier examples set a cookie named `h3`.


Fixed in 1924aa6. That line now reads x-<name>-session and ties it to the concrete x-h3-session header the earlier examples produce, so it can no longer be misread as a literal header name.

coderabbitai

🧹 Nitpick comments (1)

docs/4.examples/handle-session.md (1)
137-137: ⚡ Quick win

Clarify header name normalization for name.

Line 137: the implementation lowercases the derived header key (x-${name.toLowerCase()}-session). Consider noting this explicitly so mixed-case name values don’t cause confusion when users inspect/request headers.
🤖 Prompt for 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.

In `@docs/4.examples/handle-session.md` at line 137, Update the docs to explicitly
state that the session header is normalized to lowercase by the implementation:
the header is constructed as `x-${name.toLowerCase()}-session`, so if a user
supplies a mixed-case `name` value the header key seen in requests/responses
will be lowercased; reference the `name` option and the derived header format
`x-${name.toLowerCase()}-session` so readers understand header normalization and
avoid confusion.

🤖 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.

Nitpick comments:
In `@docs/4.examples/handle-session.md`:
- Line 137: Update the docs to explicitly state that the session header is
normalized to lowercase by the implementation: the header is constructed as
`x-${name.toLowerCase()}-session`, so if a user supplies a mixed-case `name`
value the header key seen in requests/responses will be lowercased; reference
the `name` option and the derived header format
`x-${name.toLowerCase()}-session` so readers understand header normalization and
avoid confusion.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b6df0a33-42c0-49cc-a4a2-7c9382da71a9

📥 Commits

Reviewing files that changed from the base of the PR and between 84244b4 and e62ab0d.

📒 Files selected for processing (1)

docs/4.examples/handle-session.md

harshagarwalnyu · 2026-06-03T03:23:09Z

Pushed a small fix for the header placeholder point: it now reads x-<name>-session and ties it to the concrete x-h3-session header already shown earlier in the same page, so it's clear it's a pattern rather than a literal header name.

On the password comments: I kept the literal password value on purpose to stay consistent with the rest of this page. Every existing example here (Initialize, Get Data, Add Data, Clear, Options) uses the same 80d42cfb-... literal, so swapping only the two new examples to process.env.SESSION_PASSWORD would make the file inconsistent, and converting all of them is out of scope for a docs PR that's just about the name option. Happy to do a follow-up that moves the whole page to an env-var placeholder + a "use a strong secret, don't commit it" note if you'd prefer that as a separate change.

pi0x

Note: this review was performed by AI agents (Claude Code) on behalf of the maintainer, in two independent passes.

Pass 1 reviewed the diff for correctness, edge cases, and test coverage. Pass 2 (a fresh agent, adversarial by design) independently re-read the diff, checked for merge conflicts/CI status, and tried to find a reason to block approval before this review was posted. Both passes agree this change is correct, adequately tested, and safe to merge.

Caveat: this repo's real CI workflow (lint + build + vitest) requires maintainer approval to run on fork PRs and has not executed on this PR yet — only automated third-party checks (CodeRabbit, Socket Security) have run. Please trigger/approve the CI workflow before merging.

pi0

Thanks

docs: document the session name option for multiple sessions

e62ab0d

harshagarwalnyu requested a review from pi0 as a code owner June 2, 2026 09:03

Copilot AI review requested due to automatic review settings June 2, 2026 09:03

Copilot AI reviewed Jun 2, 2026

View reviewed changes

coderabbitai Bot reviewed Jun 2, 2026

View reviewed changes

harshagarwalnyu added 2 commits June 2, 2026 16:45

Merge branch 'main' into docs/session-name-option

8713600

docs: clarify x-<name>-session header placeholder in session example

1924aa6

harshagarwalnyu added 2 commits June 3, 2026 14:28

docs: note that session password should come from env in production

7567774

docs: clarify session header is lowercased from the name option

e489811

pi0x approved these changes Jul 2, 2026

View reviewed changes

pi0 approved these changes Jul 2, 2026

View reviewed changes

Merge branch 'main' into docs/session-name-option

96e117b

pi0 merged commit 23c8c48 into h3js:main Jul 2, 2026
2 of 3 checks passed

pi0x pushed a commit to mixelburg/h3 that referenced this pull request Jul 2, 2026

docs: document the session name option for multiple sessions (h3js#1405)

4e7632c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: document the session name option for multiple sessions#1405

docs: document the session name option for multiple sessions#1405
pi0 merged 6 commits into
h3js:mainfrom
harshagarwalnyu:docs/session-name-option

harshagarwalnyu commented Jun 2, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 2, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Review ran into problems

Uh oh!

Copilot AI left a comment

Uh oh!

harshagarwalnyu Jun 3, 2026

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

harshagarwalnyu commented Jun 3, 2026 •

edited

Loading

Uh oh!

pi0x left a comment

Uh oh!

pi0 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

harshagarwalnyu commented Jun 2, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Review ran into problems

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

harshagarwalnyu Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

harshagarwalnyu commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pi0x left a comment

Choose a reason for hiding this comment

Uh oh!

pi0 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

harshagarwalnyu commented Jun 2, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 2, 2026 •

edited

Loading

harshagarwalnyu commented Jun 3, 2026 •

edited

Loading