Skip to content

convexLoad: one subscription per query, SSR payload for hydration - #60

Merged
mikecann merged 6 commits into
mainfrom
fix/convexload-single-subscription
Oct 13, 2026
Merged

mikecann merged 6 commits into
mainfrom
fix/convexload-single-subscription

Conversation

@mmailaender

@mmailaender mmailaender commented Sep 26, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #58. Review the diff against fix/release-route-scoped-queries.

TL;DR: convexLoad now opens one subscription instead of two, and during hydration it reuses the server's result instead of querying Convex before setupAuth() has run. Also fixes a loading flash over server-rendered paginated data.

None of these problems were introduced by #58. They all exist on main.

Why

1. Hydration queries Convex without auth

SvelteKit re-runs universal loads (+page.ts, +layout.ts) in the browser during hydration. That happens before the root layout's setupAuth() has authenticated the client, so convexLoad queried Convex anonymously. The WebSocket traffic on /tests/convex-load-auth shows it:

Add#0 [{"muteWords":["__e2e_auth_hydration__"]}]   ← hydration query, unauthenticated
Remove#0
Authenticate(token)
Add#1 [...]                                         ← live subscription

For signed-in users, this replaced the server-rendered (authenticated) data with an anonymous result, or failed the load for queries that throw without auth. Hydration also had to wait for the WebSocket connection and a query round trip before the page became interactive.

Two obvious fixes don't work:

  • Waiting for auth inside the load: SvelteKit awaits the loads before it even creates the layout that calls setupAuth.
  • SvelteKit's fetch replay: its cache key includes request headers, and so the token.

2. Two subscriptions per convexLoad

On client-side navigation, convexLoad ran a one-shot client.query() (subscribe → first result → unsubscribe) and then subscribed again, so every query ran twice. convexLoadPaginated couldn't even reuse a live result, because the paginated subscription adds an id to its paginationOpts.

3. Loading flash over paginated SSR data

convexLoadPaginated, and usePaginatedQuery with initialData, briefly rendered their loading state over the server-rendered results right after hydration. The paginated state machine marked SSR data as loading on the initial onArgsChange (since 8da778f2), and its keepPreviousData branch ran before the hydration guard (since 97e072f). Codex found this during review.

How

1. SSR payload, reused during hydration

A new opt-in handle, convexLoadHydration, embeds the server's convexLoad results in the page. During hydration, convexLoad reuses them and defers the live subscription until setupAuth / setupConvex, exactly like the transport path already does. No query and no waiting.

  • Server: results of universal loads only are collected per request (AsyncLocalStorage) and embedded in <head> as <script type="application/json" data-convex-load>. Placing it in <head> means it exists before SvelteKit's start script runs the loads. The JSON is serialized with convexToJson and escaped like SvelteKit's own serialize_data.
  • Finding </head>: a small scanner skips comments, tags (including quoted attribute values), and raw-text elements such as <script>. So a "</head>" string inside a head script can't split the document.
  • Browser: results are keyed by function name and args (plus page size for paginated queries). The payload is used only during the initial hydration. The flag that tracks this is permanent, so a stale payload is never reused on a later navigation, not even after closeConvex().
  • Why only universal loads: a +page.server.ts load may fetch private data and return only part of it. Universal loads are detected with SvelteKit's internal state.is_in_universal_load flag, which SvelteKit's remote functions use for the same purpose. Because it's internal API, it's read defensively: if it's missing (SvelteKit < 2.56) or unreadable, nothing is embedded and a warning is logged once.
  • Why a separate entry point: convex-svelte/sveltekit/server/hydration is the only module that imports SvelteKit internals. convex-svelte/sveltekit/server (withServerConvexToken) keeps working on SvelteKit < 2.31.

2. One subscription

convexLoad now opens the live subscription immediately and awaits its first value, then returns that same subscription. The immediate subscribe bypasses the deferred queue, which would deadlock inside a load.

3. No loading flash

SSR data is treated as current data: it isn't loading until the args change, and the hydration guard runs first.

What changes

// hooks.server.ts
import { sequence } from '@sveltejs/kit/hooks';
import { withServerConvexToken } from 'convex-svelte/sveltekit/server';
import { convexLoadHydration } from 'convex-svelte/sveltekit/server/hydration';

export const handle = sequence(convexLoadHydration, async ({ event, resolve }) =>
  withServerConvexToken(await getToken(event), () => resolve(event))
);
// keep a result out of the payload; this load then queries Convex during hydration, as before
convexLoad(api.feed.heavy, args, { hydrate: false });
  • New entry point: convex-svelte/sveltekit/server/hydration with convexLoadHydration (SvelteKit 2.56+).
  • New option: hydrate: false on convexLoad / convexLoadPaginated.
  • Contract: everything convexLoad fetches while a universal load runs ends up in the HTML, including calls in helpers that load invokes. hydrate: false opts a result out.
  • Limitation: a streamed (not awaited) result is only embedded if it finished before the page HTML was generated. In development, a warning points out loads that miss the payload while the handle is active.
  • Without the handle: hydration behaves as before, but still with a single subscription.

Tests

  • Unit: 212 tests (+73).
    • hydration.spec.ts: XSS-safe escaping, exact round trips of Convex values (bigint, bytes, nested, null), placement in <head> across tricky markup, payload only during the initial hydration, malformed or missing payload, dev warning.
    • hydration-server.spec.ts: the real handle and AsyncLocalStorage with the real server path. Server-load results are never embedded; concurrent requests stay apart; fail-safe with one warning when the SvelteKit marker is missing.
    • server-token.spec.ts: convex-svelte/sveltekit/server still imports without SvelteKit internals.
    • Detached query, transport, lifecycle and state machine specs: single subscription, first value, errors, dispose before the first value, inactive client, held queries, and paginated SSR data not marked as loading.
  • E2E: 42 tests (+11), asserted on real WebSocket frames, with new routes /tests/convex-load-auth, /tests/convex-load-server and /tests/convex-load-nested.
    • Hydration: no query before Authenticate, exactly one Add per query, only universal-load results in the HTML (also with nested server and universal layouts and parent()).
    • A message body containing </script><script>… doesn't execute.
    • No loading state from SSR through hydration and the first live update, for regular and paginated queries.
    • Client navigation: exactly one Add.
  • Checked against the old code: 7 of the new e2e tests fail on Release convexLoad subscriptions when the route no longer uses them #58's code; the rest can't fail there by design. The paginated first-page guard and the loadMore generation guard were removed temporarily to confirm their tests fail without them. The new e2e tests passed 3 repeated runs.
  • Limitation: the auth e2e test uses a fake token (the test backend has no auth provider). It proves the order of messages on the wire, not a real authenticated result.

pnpm test, pnpm check, pnpm lint, pnpm lint:package, and convex dev --once pass.

Review

Four rounds with an independent Codex (gpt-6-astra) reviewer. Final verdict: ready to merge, no blockers.

What the review rounds fixed
  • Round 1: server-load results leaking into the HTML, paginated loads resolving before their first page, payload placed after SvelteKit's start script, a server-load result suppressing a universal one with the same key, missing warning for streamed loads.
  • Round 2: </head> inside head scripts, missing warning when the SvelteKit marker is absent, separate entry point for SvelteKit < 2.31, docs wording (confidentiality contract, streamed-result timing, 30 s release timing).
  • Round 3: scanner offsets with non-ASCII text, </head> in attribute values and after </script-not-a-tag>, the paginated SSR loading flash (Why 3).
  • Round 4: optional scanner hardening for doctype, <?…> and <![CDATA[…>, included.

Kept as is, and the reviewer agreed:

  • Pending loads aren't cancelled while offline. Same as the old one-shot query; they settle on reconnect.
  • Streamed results that finish after the HTML aren't embedded (documented, with a dev warning).

Possible follow-ups, none blocking:

  • Scanner: <template> in <head> and legacy script double-escaping (only affects hand-written markup).
  • Two paginated quirks that also exist on main: 'skip' with initialData, and isLoading during LoadingMore while SSR data applies.

Related

@vercel

vercel Bot commented Sep 26, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
convex-svelte Error Error Oct 12, 2026 3:58pm UTC

Request Review

@mikecann mikecann left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks again @mmailaender, this one is a big one! Same deal, had my agent go through it and it's looking really good. The escaping matches SvelteKit's own and server load results stay out of the payload, which was my main worry. Two things I think need fixing before we merge tho:

  1. Remote functions. When SvelteKit runs a remote function it copies the request state and just adds is_in_remote_function: true (derive_remote_function_event in runtime/app/server/remote/shared.js), so is_in_universal_load is still true inside it. So if a +page.ts calls a remote query() that uses convexLoad and only returns part of the result, the full result still ends up in the HTML. My agent reproduced it with a fake secret and it came out in the <head>. I think also checking is_in_remote_function !== true in hydration-server.ts:35 should sort it.

  2. If the scanner can't find </head> or <body, the payload gets put before the <!doctype> (hydration.ts:169), which puts the page into quirks mode. Seems safer to just embed nothing in that case since the client already falls back fine.

A few smaller ones if you fancy it: the empty payload on ssr = false routes means every convexLoad there gets the dev warning, a malformed payload throws at jsonToConvex (hydration.ts:202) instead of falling back, and the first Fixes heading in the changeset says hydration no longer queries without auth, but that's only with the handle.

Cheers!

- On client-side navigation, open the live subscription and await its
  first value instead of a one-shot client.query() followed by a second
  subscription (Add → Remove → Add). convexLoadPaginated no longer fetches
  the first page twice.
- New convexLoadHydration handle (convex-svelte/sveltekit/server) embeds
  convexLoad results of universal loads in the SSR HTML. Loads re-running
  during hydration reuse them instead of querying before setupAuth, and
  the live subscription is deferred until auth is set up. Server-load
  results (transport) are not embedded twice. hydrate: false opts out.
- A load awaiting its first value holds its query (no unclaimed timeout
  while e.g. offline).
…ginated first page

- Record convexLoad results only while a universal load runs (SvelteKit's
  is_in_universal_load request-store flag, as used by its remote
  functions). Server loads never contribute, so results they only use
  internally can't leak into the HTML, and a transported server-load
  result no longer suppresses a universal one with the same key.
  Fail-safe: without the flag nothing is embedded (warned once).
- Inject the payload in <head>, before SvelteKit's start script.
- Paginated: settle the first value only once a page arrived (Convex
  reports LoadingFirstPage immediately).
- Dev warning when a hydration load misses the payload (e.g. streamed
  convexLoad); hydrate: false skips lookup and warning.
- Move convexLoadHydration to convex-svelte/sveltekit/server/hydration.
  It needs @sveltejs/kit/internal/server (2.31+) and the universal-load
  marker (2.56+); keeping it out of convex-svelte/sveltekit/server means
  withServerConvexToken keeps working on older SvelteKit versions.
- Warn once (and embed nothing) whenever the marker can't be read: missing
  accessor, store without the marker, or a throwing accessor.
- Find the real </head> with a scanner that skips comments and raw-text
  elements, so '</head>' inside a head script can't be split.
- Document that everything convexLoad fetches while a universal load runs
  is embedded (hydrate: false for private helper queries), and that a
  streamed result is only embedded if it finished before the HTML.
- e2e: universal + server layouts with parent(), exact payload contents.
- findTag: ASCII-only case folding (toLowerCase() can change the length,
  e.g. 'İ', shifting the insertion point), skip whole tags respecting
  quoted attribute values, and require a tag boundary for raw-text end
  tags (</script-not-a-tag> doesn't close a script).
- Paginated state machine: SSR initialData is current data, not previous
  data — the initial args no longer mark it as loading, and the hydration
  guard runs before keepPreviousData. Fixes a loading flash right after
  hydration for convexLoadPaginated and usePaginatedQuery with initialData.
- e2e: no loading state from SSR through hydration and the first live
  update (regular and paginated).
They are read up to the next '>' (doctype or bogus comment), so a
'</head>' inside a processing instruction or CDATA-like declaration no
longer counts as the end of the head.
…and safer client

- Embed only when SvelteKit's request state says universal load AND not
  remote function. A remote function called from +page.ts copies the
  state, so its full result used to end up in the HTML. Unknown or
  missing flags embed nothing (fail closed).
- Replace the </head> scanner with a %convex.hydration% placeholder in
  app.html, replaced in transformPageChunk (SvelteKit's documented way to
  inject request-specific markup). A missing placeholder embeds nothing
  and warns once in dev, instead of inserting before <!doctype>.
- Emit no payload when nothing was collected, so ssr = false pages no
  longer get a dev warning for every convexLoad.
- An unreadable payload value is treated as a miss (warn once in dev)
  instead of failing the load.
- Rebased on the updated #58: holdWhile's timeout closes like the
  unclaimed timeout.
- Changeset: the hydration fix applies with the handle.

@mikecann mikecann left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @mmailaender, looks good! The app.html placeholder is a much nicer way of doing it. Cheers!

@mikecann
mikecann changed the base branch from fix/release-route-scoped-queries to main October 13, 2026 01:52
@pkg-pr-new

pkg-pr-new Bot commented Oct 13, 2026

Copy link
Copy Markdown

commit: a1050e0

@mikecann
mikecann merged commit 92531a5 into main Oct 13, 2026
4 of 5 checks passed

This branch had an error being deployed

1 failed deployment
Preview — 5afe9928 Deployed Oct 12, 2026 by vercel[bot]
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.

2 participants