Skip to content

Read Stats through remote functions - #45

Open
vivecuervo7 wants to merge 8 commits into
kit-3-idiomsfrom
stats-remote
Open

vivecuervo7 wants to merge 8 commits into
kit-3-idiomsfrom
stats-remote

Conversation

@vivecuervo7

@vivecuervo7 vivecuervo7 commented Nov 7, 2026 •

Copy link
Copy Markdown
Owner

What

The Stats page reads and changes its data through SvelteKit's remote functions, as the trial of whether the rest of Docent should.

  • stats.remote.ts: getStats (query), getAnalysis (query.live, yielding the analysis whenever it changes), and startAnalysis / resetAnalysis (command; reset while a run is going is a 409).
  • The analysis state tells those waiting when it changes (a Proxy over it, so its eight update sites stay as they are), a moment after a burst so progress is read once, and stops the wait when the page's request ends.
  • The page awaits the stats, which it can't show anything without, and reads the analysis as it arrives (getAnalysis().current / .error), so an analysis failure shows inline beside the stats rather than replacing the page. Its fetches, its polling, its loading and error flags and template branches, the native confirm() and the /api/stats routes are gone.
  • messageOf reads a remote function's error, which isn't an Error: its message is in its body.
  • A root +error.svelte, so a failing query, or an unknown URL, shows on a page of Docent's own with its header and a way back.
  • server.js ends live streams straight away on shutdown, as an open page would otherwise hold it for the full half-minute.
  • experimental.remoteFunctions and compilerOptions.experimental.async are on, each with a comment on why.

Why

Remote functions are where SvelteKit is heading, and this page has every shape the rest of Docent needs: reads, changes, and a value that changes while a job runs. What it shows decides how the remaining pages move off their hand-written fetching.

How

What the trial found, all on a production build (npm start) with a copy of the data:

  • Navigation waits for a top-level await, as it would for a load. From the start page, the URL changes at 51 ms with the old page still showing, and Stats appears whole at 76–102 ms, with no loading flash and no placeholder to write. A cold load is blank until the stats arrive (94 ms here), as with any load; the old page showed a spinner.
  • query.live streams. The response is text/event-stream, carries the guard's frame-ancestors header without trouble, and a reset updates the open page in about 290 ms, with no reload.
  • Shutdown isn't held. With a live stream open, SIGTERM exits in 0.07 s.
  • The wait ends with the page. Instrumented, the server's waiter count went back to 0 on navigating away and on closing the tab. Unit tests pin it.
  • The origin checks Answer only this machine, and serve a built Docent on http #44 prepared for hold. A command from the page passes SvelteKit's remote origin check. A foreign Origin gets 403 from SvelteKit, and a rebound Host gets 403 from the guard, on commands and on the live query.
  • Errors reach the page. A command's 409 shows as "Couldn't analyse: …", and a failing query lands on the new error page.

Lines: the page loses 44 and gains 25 (ignoring whitespace), and the two routes lose 25. The new remote module, change notification and error helper add about 65, with their tests. The gain is behaviour more than size: no leaking poll, no hand-written loading states, live updates, and a real error page.

Not checked: starting an analysis for real, as it costs model calls. The command's error path was checked by answering it with SvelteKit's error envelope in the browser.

🤖 Generated with Claude Code

vivecuervo7 and others added 7 commits November 8, 2026 09:30
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The page no longer fetches, polls or tracks loading and errors itself: navigating to it waits for its data, the analysis updates as it changes, and the polling that carried on after leaving the page is gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hile one runs

The live read now listens before it reads, so a change made while a value is on its way isn't missed, and the analysis state is wrapped afresh each time its module loads, so a dev server keeps telling those waiting after an edit. A reset that fails for any other reason is an error, not a conflict.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An open Stats page held each shutdown for the full half-minute.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…error page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread web/src/routes/stats/+page.svelte Resolved
Comment thread web/src/routes/+error.svelte Resolved
…n, and style the error page's heading

A failed stream keeps its last value, so a run's frozen progress, or results just reset, went on showing in place of the error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@vivecuervo7 vivecuervo7 left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Second review cycle, covering 27c33dd..9a8f532.

Comment thread web/src/routes/stats/+page.svelte Resolved
Comment thread web/src/routes/stats/+page.svelte Resolved
Comment thread web/src/routes/+error.svelte Resolved
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