Skip to content

perf(auth): collapse the session lookup from seven round trips to one - #6743

Merged
saddlepaddle merged 1 commit into
mainfrom
perf/collapse-session-queries
Aug 22, 2026
Merged

saddlepaddle merged 1 commit into
mainfrom
perf/collapse-session-queries

Conversation

@saddlepaddle

@saddlepaddle saddlepaddle commented Aug 21, 2026 •

Copy link
Copy Markdown
Collaborator

Not a candidate for admin-merge. This touches the auth path for every authenticated request across desktop, web, mobile, CLI and MCP. It's the biggest win available, but it wants a human read — see What to look at below.

The problem

Every authenticated request resolves a session, and each resolution was seven HTTP round trips to Neon. The database is in us-west-2; every Vercel function is in iad1. So one query costs 73-100ms, not a few.

Scale: api's GET /api/trpc/[trpc] alone has 360M Neon spans at 73ms average.

# query
1 findOne sessions covered by cookieCache ~2/3 of the time
2 findOne users ditto
3 update sessions updateAge refresh
4 findMany jwkss every call, 136ms
5 members.findMany customSession
6 subscriptions.findFirst customSession
7 users.findFirst the same row as #2

cookieCache was already hitting on 40 of 60 sampled requests — but customSession re-ran its callback regardless, so 4-7 were paid even on a cache hit.

The changes

#5, #6, #7 → one statement. They were sequential only because the active-organization fallback made the order matter, and that fallback is expressible in SQL. #7 was reading a row better-auth had already handed us; the old comment blamed additionalFields not surfacing on the passed-in user.

#4 cached, not disabled. disableSettingJwtHeader would remove the round trip outright, but desktop (auth-client.ts:142) and mobile (client.ts:45) both read set-auth-jwt off response headers to refresh opportunistically. So the read is cached behind the plugin's adapter.getJwks hook instead, with createJwk writing through and invalidating.

Net: 7 → 1 on a cookie-cache hit, 7 → 3 on a miss.

Verification

A differential harness ran old vs. new against a real database branch across 64 cases — multi-membership users at every active-organization permutation, paid and unpaid, stale organization ids, no active organization, and a user with no memberships.

0 mismatches. 104ms → 36ms per call.

What to look at

The harness caught a genuine bug, which is the best argument for reviewing this carefully:

onboardedAt came back 8 hours off on every user. These are timestamp (not timestamptz) columns, so Postgres returns a naive string with no zone — new Date() reads that as local time, while drizzle's mapping treats it as UTC. Silent, and it would have shifted the onboarding gate by the function's offset. Fixed in toDate(), re-verified.

Specific things worth a second opinion:

  1. toDate() in load-custom-session-data.ts — the fix above. If it's wrong, onboarding and pending-deletion gates move.
  2. The raw SQL. It's the only db.execute in packages/auth, deliberately: the single statement is the point. Worth checking the active-org CTE matches resolveSessionOrganizationState's TS fallback exactly (it takes memberships ordered created_at DESC and picks the session's org if present, else the first).
  3. The concurrent-move path. If another request changes the session's active organization between the query and resolveSessionOrganizationState settling, the plan fetched belongs to the wrong org. Handled by comparing planOrganizationId and re-reading — rare, but confirm the fallback is right.
  4. JWKS cache TTL (60s). A key created on another instance is absent from /jwks until expiry, so tokens signed with it would fail verification for up to a minute. createJwk invalidates locally. Keys effectively never rotate here (no expiry configured), but the window is real.

Testing

  • 64-case differential harness against a live branch, 0 mismatches
  • JWKS cache: 3 calls → 1 read; createJwk invalidates
  • better-auth instance constructs cleanly with the adapter option (106 endpoints)
  • Lint, typecheck, full suite green

https://claude.ai/code/session_014D6wif8HDRCXEFf5Ku4w7V


Summary by cubic

Collapses session resolution from seven DB round trips per request to one on a cookie-cache hit (three on a miss) by combining membership/subscription/user reads into a single SQL statement and caching JWKS reads. This reduces per-request latency and fixes timestamp parsing that could shift onboarding/deletion gates.

Review and rollout

  • Verify the raw SQL active-org fallback matches the TypeScript logic: prefer the session’s org if present, else the most-recent membership (created_at DESC).
  • Confirm toDate() treats Postgres timestamp (no tz) as UTC; a mismatch moves onboarding/deletion gates by the server offset.
  • Check the concurrent move path: if planOrganizationId differs from the resolved active org, we re-read the subscription; this avoids serializing the common path.
  • JWKS caching: 60s per-instance TTL. Keys created on another instance may fail verification until expiry; createJwk invalidates locally. We keep the set-auth-jwt header for desktop/mobile refresh behavior.
  • Expected impact: 7→1 round trip on cache hit (7→3 on miss); ~104ms→36ms per call over 64 cases. No migrations required.

Written for commit e5167e6. Summary will update on new commits.

Review in cubic

Summary by CodeRabbit

  • New Features

    • Improved session loading with memberships, active organization details, subscription plans, onboarding status, and deletion-request status.
    • Added caching for authentication keys to improve repeated sign-in and session checks.
    • Session data now stays accurate when the active organization changes.
  • Bug Fixes

    • Improved fallback behavior when an active organization is unavailable.
    • Ensured session timestamps are handled consistently.

Every authenticated request in the product resolves a session, and each
resolution was seven separate HTTP round trips to Neon. The database is
in us-west-2 while every function runs in iad1, so a single query costs
73-100ms rather than a few. api's `GET /api/trpc/[trpc]` alone accounts
for 360M such spans at 73ms average.

The seven were: the session row, the user row, a session refresh, the
jwks table, then customSession's memberships, subscription and a second
read of the user row it had already been handed.

That last one was pure waste — the same row, read twice. It existed
because additionalFields were not surfacing on the passed-in user. The
memberships and subscription reads were sequential only because the
active-organization fallback made the order matter, and that fallback is
expressible in SQL. All three collapse into one statement.

The jwks read is cached behind the plugin's adapter.getJwks hook rather
than disabled outright: `disableSettingJwtHeader` would drop the round
trip entirely, but desktop and mobile both read `set-auth-jwt` off
response headers to refresh their token opportunistically. createJwk
writes through and invalidates, so a newly created key is never masked.

cookieCache already covers the session and user rows two thirds of the
time, but customSession re-ran regardless, so the remaining reads were
paid on every call including cache hits. Net: seven round trips become
one on a cookie-cache hit and three on a miss.

Verified against a real database branch with a differential harness
comparing old and new across 64 cases — multi-membership users at every
active-organization permutation, paid and unpaid, stale organization ids,
and no active organization — 0 mismatches, 104ms to 36ms per call.

That harness caught a real bug worth noting for review: these are
`timestamp` columns, so Postgres returns a naive string with no zone, and
`new Date()` reads it as local time while drizzle treats it as UTC. Every
onboardedAt came back 8 hours off. Fixed in toDate().

Claude-Session: https://claude.ai/code/session_014D6wif8HDRCXEFf5Ku4w7V
@coderabbitai

coderabbitai Bot commented Aug 21, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f1a8d731-9c20-4342-b84f-506443a9f1ee

📥 Commits

Reviewing files that changed from the base of the PR and between b423f0a and e5167e6.

📒 Files selected for processing (4)
  • packages/auth/src/lib/cached-jwks.ts
  • packages/auth/src/lib/load-custom-session-data.ts
  • packages/auth/src/lib/resolve-session-organization-state.ts
  • packages/auth/src/server.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 3 remain after this review.


📝 Walkthrough

Walkthrough

The authentication package adds cached JWKS retrieval, consolidates custom session data into one query, updates session organization resolution dependencies, and uses the shared data loader in the custom session handler.

Changes

Authentication updates

Layer / File(s) Summary
JWKS caching and JWT wiring
packages/auth/src/lib/cached-jwks.ts, packages/auth/src/server.ts
JWKS values now use a 60-second in-memory cache. Cache misses and expirations load keys from the database. Successful key creation invalidates the cache. JWT configuration uses jwksAdapter().
Custom session data loading
packages/auth/src/lib/load-custom-session-data.ts
loadCustomSessionData loads memberships, the selected organization, its active plan, and user lifecycle timestamps in one SQL query. It maps timestamps to UTC Date values and returns empty defaults when no user row exists.
Session handler integration
packages/auth/src/lib/resolve-session-organization-state.ts, packages/auth/src/server.ts
Organization-state resolution now accepts partial dependency overrides. The custom session handler uses loaded memberships, rechecks plans after concurrent organization changes, and uses loaded lifecycle timestamps.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to e5167

This change reduces authenticated-request database round trips and adds JWKS caching; no concrete merge-blocking correctness or availability risk is identified at the current head, so it is merge-ready after normal checks.

Sequence Diagram(s)

sequenceDiagram
  participant CustomSessionHandler
  participant loadCustomSessionData
  participant Database
  participant resolveSessionOrganizationState
  CustomSessionHandler->>loadCustomSessionData: load data for user and active organization
  loadCustomSessionData->>Database: query memberships, plan, and lifecycle timestamps
  Database-->>loadCustomSessionData: return session data
  loadCustomSessionData-->>CustomSessionHandler: return mapped session data
  CustomSessionHandler->>resolveSessionOrganizationState: resolve organization using loaded memberships
  resolveSessionOrganizationState-->>CustomSessionHandler: return organization state
Loading

Suggested reviewers: kitenite

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description check ✅ Passed The description explains the problem, changes, performance impact, verification results, review risks, and testing, but it omits the template headings and checklist.
Title check ✅ Passed The title uses conventional commit format and clearly summarizes the primary performance improvement in the authentication session lookup.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch perf/collapse-session-queries

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.

@github-actions

github-actions Bot commented Aug 21, 2026 •

Copy link
Copy Markdown
Contributor

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

  • ✅ Neon database branch

Thank you for your contribution! 🎉

@saddlepaddle
saddlepaddle merged commit dbd7d9d into main Aug 22, 2026
20 checks passed
@saddlepaddle
saddlepaddle deleted the perf/collapse-session-queries branch August 22, 2026 01:29

This branch was previously deployed

1 inactive deployment
preview — e5167e6b Deployed Aug 21, 2026 by saddlepaddle via Deploy Admin #8245
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant