You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 17fbb6d
Browse filesBrowse the repository at this point in the historyBrowse files
committed
feat(diagnostics,solid,web,signals): server records in the artifact, and the checks derived from them
server-dev-build-plan P4. Three parts:
(a) `InvocationEvent.boundary`: a direct server-function call made during a
`<Loading>` boundary's render pass carries that boundary's hydration id (read
from the shared context at call start, the id the pass set) — the join
between a boundary's wait and the calls under it.
(b) Two dev checks read off the boundary facts in `ssrLoadingBoundary`:
`ASYNC_WATERFALL` with `data.side: "server"` (`passes - 1` sequential
flights, exact where the client's proof is inferred; 2 → info, structured
only; 3+ → console warn) and the new `SSR_CLIENT_CONTENT_MASKED` (warn, ssr)
for client-only content that surfaced only after a real server wait. The
boundary clock now runs in dev without a listener; `emitFinding` keeps info
findings off the console, as the core does.
(c) `@solidjs/diagnostics` format v5: `artifact.server: { boundaries,
invocations } | null`, folded from `OBSERVE.server.records` when the server
runtime installed its surface. The package still depends on signals alone —
it reads the channel by its contract and mirrors the two record types; the
web server suite pins the mirrors to the runtime types at compile time. JSONL
adds boundary/invocation lines. Contract test:
web/test/server/diagnostics-server-scenario.spec.tsx.
Docs: RFC 08 (two check entries, the join, the harness), RFC 10, both
skills, the diagnostics README, plan status.
Co-authored-by: Claude via Cursor <[email protected]>
Co-authored-by: Cursor <[email protected]>
Server records reach the diagnostics artifact and the dev checks (server-dev-build-plan P4)
9
+
10
+
-`@solidjs/diagnostics` artifact format **v5**: `artifact.server: { boundaries, invocations } | null` folds `OBSERVE.server.records` when the scenario runs under the server runtime — `captureArtifact(() => renderToStream(…))` — one row per `<Loading>` boundary that waited and per server-function execution; `null` for client captures and the browser bridge. New exported types `ArtifactServer`, `ServerBoundaryRecord`, `ServerInvocationRecord` (mirrors of the runtime's `BoundaryEvent`/`InvocationEvent`; the package still depends on `@solidjs/signals` alone). JSONL egress adds `boundary` and `invocation` lines and the header counts.
11
+
-`InvocationEvent.boundary`: a direct server-function call made during a `<Loading>` boundary's render pass carries that boundary's hydration id, the `"boundary"` record's `id` — the join between a boundary's wait and the calls under it.
12
+
- Two dev checks derived from the boundary facts in `ssrLoadingBoundary`: `ASYNC_WATERFALL` with `data.side: "server"` (`passes - 1` sequential flights; 2 → `info`, structured only; 3+ → console `warn`) and a new code `SSR_CLIENT_CONTENT_MASKED` (`warn`, `ssr`) for client-only content that surfaced only after a real server wait — the server's work discarded, the fallback shown for the wait. Dev tier only; the boundary clock now runs in dev without a listener.
13
+
-`solid-js`'s server `emitFinding` keeps `info` findings off the console (structured channel only), matching the core.
Copy file name to clipboardExpand all lines: documentation/solid-2.0/08-dev-diagnostics.md
+21-4Lines changed: 21 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -514,6 +514,18 @@ The client's code, `data.side: "server"`, and a hard **error** on the server in
514
514
515
515
Check (`warn`, dev only). `renderToString` has no stream to coordinate reveal order on. `data.order`, `data.collapsed`.
516
516
517
+
#### `ASYNC_WATERFALL` (server)
518
+
519
+
**Message:** "[ASYNC_WATERFALL] 2 sequential async flights in a <Loading> boundary — 84ms over 3 render passes: each read could start only after the previous one answered. If a later read doesn't need the earlier answer, derive both from the same inputs so they start together; if the dependency is intrinsic, preload the dependent data or join the requests."
520
+
521
+
The client's code, `data.side: "server"`, `kind: "perf"`; a check (dev only) read off the boundary's facts — the same ones the `"boundary"` record carries (below), no listener needed. A `<Loading>` boundary is rendered in passes: discovery, then one per wait, each pass a read that could only start once the previous pass's async answered — so `passes - 1` is the number of sequential flights, and the proof is exact where the client's is graph-inferred. Same thresholds: two flights (`passes: 3`) are `info`, structured-channel only, since a dependent fetch is sometimes intrinsic; three or more earn the console `warn`. Once per boundary per render. `data.boundary` is the boundary's hydration id (the record's `id`), `data.passes`, `data.sequentialMs` (discovery → settle). Located by component.
522
+
523
+
#### `SSR_CLIENT_CONTENT_MASKED`
524
+
525
+
**Message:** "[SSR_CLIENT_CONTENT_MASKED] Client-only content (ssrSource: "client") in a <Loading> boundary surfaced only after 1 server wait (52ms): the boundary streamed its fallback and then handed the subtree to the client, discarding the server's work. Give the client-only content its own <Loading>, or read it before the async data, so the handoff ships with the shell."
526
+
527
+
Check (`warn`, dev only, `kind: "ssr"`). A boundary whose content turned out to be client-only — a `ssrSource: "client"` read — but only after a real server wait: an async read on an earlier pass masked it. The server did the work, streamed the fallback, then handed the whole subtree to the client anyway, so the work was discarded and the user saw the fallback for the wait's duration before the client rendered. A client-only read found on the **first** pass is the well-behaved case — the boundary hands off with the shell, nothing extra is paid, no finding. `data.boundary`, `data.passes`, `data.durationMs`.
A boundary whose content rendered on its first pass emits nothing — there was no wait to attribute, the same rule as the client's `hold` records. For one that waited: `id` is the boundary's hydration id, the id the `SSR_RENDER_ERROR_CONTAINED` finding names in `data.boundary`, so a record and a finding pair by it; `at` is `performance.now()` at discovery; `durationMs` runs discovery → settle — to the content being complete, or to the decision that the server will not produce it; `passes` counts render passes over the content (the discovery pass plus one per wait — `2` is one round of async, more is a sequential chain, a read that depended on the answer to the previous one); `streamed` says whether the outcome reached the client after the shell had flushed (the user saw the fallback, then the swap) or in time to inline into it. `outcome` is how it ended: `"settled"` — rendered on the server and swapped in; `"fallback"` — the renderer had no stream to settle into (`renderToString`), the fallback shipped final and the client renders the content; `"client"` — the content is client-only (`ssrSource: "client"`); `"error"` — the content threw, `live.error` is the value as thrown, and the paired finding says where it went. Under a `<Reveal>` group the record names the group and waits for the group's reveal, so `heldMs` is real: how long the finished content sat behind its siblings (`order="together"`, a sequential tail) — `0` for every boundary whose swap was issued as it settled. `ownerPath` locates the boundary by component, the same labels the diagnostics carry. The cost is paid only with a listener installed: a boundary with none takes no clock readings.
631
+
A boundary whose content rendered on its first pass emits nothing — there was no wait to attribute, the same rule as the client's `hold` records. For one that waited: `id` is the boundary's hydration id, the id the `SSR_RENDER_ERROR_CONTAINED` finding names in `data.boundary`, so a record and a finding pair by it; `at` is `performance.now()` at discovery; `durationMs` runs discovery → settle — to the content being complete, or to the decision that the server will not produce it; `passes` counts render passes over the content (the discovery pass plus one per wait — `2` is one round of async, more is a sequential chain, a read that depended on the answer to the previous one); `streamed` says whether the outcome reached the client after the shell had flushed (the user saw the fallback, then the swap) or in time to inline into it. `outcome` is how it ended: `"settled"` — rendered on the server and swapped in; `"fallback"` — the renderer had no stream to settle into (`renderToString`), the fallback shipped final and the client renders the content; `"client"` — the content is client-only (`ssrSource: "client"`); `"error"` — the content threw, `live.error` is the value as thrown, and the paired finding says where it went. Under a `<Reveal>` group the record names the group and waits for the group's reveal, so `heldMs` is real: how long the finished content sat behind its siblings (`order="together"`, a sequential tail) — `0` for every boundary whose swap was issued as it settled. `ownerPath` locates the boundary by component, the same labels the diagnostics carry. The cost is paid only with a listener installed (or in dev, where the checks below read the same facts): a boundary with none takes no clock readings.
632
+
633
+
Two dev checks are derived from these facts, so the console and a test's `expectNoDiagnostics` see what an agent would otherwise have to read off the record: `ASYNC_WATERFALL` (server) when `passes - 1` sequential flights reach two, and `SSR_CLIENT_CONTENT_MASKED` when a client-only outcome surfaced only after a wait. Both key by `data.boundary` — the record's `id`.
620
634
621
635
The **`"invocation"` record** (from `@solidjs/web`) is one server-function execution:
One record per call, delivered when the call **settles** — synchronously for a synchronous direct call, at resolution for a promise. `id` is the function's registered id; `direct` says whether this was an in-process SSR call (`true`, no `request`) or HTTP dispatch (`false`, `request` is the `Request` the handler dispatched). `outcome: "error"` carries the value **as thrown** in `live.error` — the sanitized `Error` the wire gets in production is the client's view, not the observer's. `deferred: true` marks a result the caller drives after the record (a stream or async generator): `durationMs` then measures to the handoff, not to the last chunk.
644
+
One record per call, delivered when the call **settles** — synchronously for a synchronous direct call, at resolution for a promise. `id` is the function's registered id; `direct` says whether this was an in-process SSR call (`true`, no `request`) or HTTP dispatch (`false`, `request` is the `Request` the handler dispatched). `outcome: "error"` carries the value **as thrown** in `live.error` — the sanitized `Error` the wire gets in production is the client's view, not the observer's. `deferred: true` marks a result the caller drives after the record (a stream or async generator): `durationMs` then measures to the handoff, not to the last chunk. For a direct call made during a `<Loading>` boundary's render pass, `boundary` is that boundary's hydration id — the `"boundary"` record's `id` — so a boundary's wait reads as the server-function calls it consisted of; absent for a call outside any boundary's pass (the shell) and for HTTP dispatch.
645
+
646
+
`@solidjs/diagnostics` folds both record types into the artifact it captures (`artifact.server.{boundaries, invocations}`, format v5) when the scenario runs under the server runtime — `captureArtifact(() => renderToStream(…))` — so a server render's waits and calls are evidence a test or an agent can hold beside the findings; see the package README.
631
647
632
648
Listeners on the channel are observers: a throwing listener is reported through `console.error` and the render or call and the other listeners are unaffected; nothing a listener does reaches the result. This is the seam for tooling that watches the server — APM adapters, devtools — and deliberately not a policy hook: `configureServerFunctionsServer({ wrapInvocation })` remains the single, last-writer-wins wrap around execution for code that must **change** a call (guards, error mapping), and an observer that installed itself there would either displace the host's policy or be displaced by it. Subscribe here, wrap there.
633
649
@@ -684,7 +700,7 @@ The runtime derives a request's trace itself in every tier — the W3C `tracepar
684
700
|`HOT_SCOPE_TIME`| warn | perf | 8ms+ self-time in one scope in 1s (attribution enabled) |
|`ASYNC_WATERFALL`| info/warn | perf | 2+/3+ sequential async flights: origin-proven (attribution enabled), or a `<Loading>` boundary's passes (server, dev)|
688
704
|`UNSTABLE_MEMO_OUTPUT`| warn | perf | Memo returned a new-but-equivalent container 4+ runs running (attribution enabled) |
689
705
|`EFFECT_WRITES_OWN_SOURCE`| info/warn | perf | Effect's write provably feeds back into its own inputs; `info` for multi-effect rings (attribution enabled) |
690
706
|`EFFECT_RELAY_TEAR`| info/warn | perf | Reader ran twice for one root change because an effect relayed it; `warn` when derivable or repeated (attribution enabled) |
@@ -700,6 +716,7 @@ The runtime derives a request's trace itself in every tier — the W3C `tracepar
700
716
|`FRAME_MARKER_CORRUPTED`| error | ssr | Frame slot range missing its end marker on the client — nesting or an HTML rewriter (observe + dev) |
701
717
|`SERVER_WRITE`| warn | write | Signal/store/optimistic setter ran during a server render; inert, will throw (dev; once per category) |
702
718
|`REVEAL_IN_RENDER_TO_STRING`| warn | ssr | Nested `<Reveal>` with collapsed/together under `renderToString` (dev) |
719
+
|`SSR_CLIENT_CONTENT_MASKED`| warn | ssr | Client-only content in a `<Loading>` surfaced only after a server wait; the server's work was discarded (dev) |
703
720
|`LAZY_ASSET_UNMAPPED`| warn | ssr |`lazy()` component's client assets could not be resolved for the page (dev) |
704
721
|`PRELOAD_DESCRIPTOR_INVALID`| warn | head |`registerAsset("preload")` descriptor broke a field rule; link dropped or field ignored (dev) |
705
722
|`HEAD_TAG_INVALID`| warn | head |`useHead` registration the render could not honor; `data.reason` names the rule (dev) |
0 commit comments