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 61a114c
Browse filesBrowse the repository at this point in the historyBrowse files
authored
feat(solid,web,signals): server boundary records on OBSERVE.server.records (#3452)
* feat(solid,web,signals): server boundary records on OBSERVE.server.records
The `"boundary"` record — one per `<Loading>` boundary that WAITED during
a server render, delivered when it settles: `{ id, at, durationMs, heldMs,
passes, outcome: "settled" | "fallback" | "client" | "error", streamed,
revealGroup?, ownerPath? }`, the thrown error beside it. `id` is the
boundary's hydration id, the one `SSR_RENDER_ERROR_CONTAINED` names in
`data.boundary`, so a record and a finding pair by it. `passes` counts
render passes over the content (discovery plus one per wait — `2` is one
round of async, more is a sequential chain) and doubles as the convergence
budget's counter. `streamed` is `registerFragment`'s answer — whether the
outcome reached the client after the shell flushed. Under a `<Reveal>`
group the record waits for the group's swap, via a per-leaf `onReveal`
hook every `revealFragments` site in `Reveal` now fires, so `heldMs` is
how long finished content sat behind its siblings. A boundary that
renders on its first pass emits nothing (the client `hold` rule); no clock
is read without a listener; the slots and emitter fold out of prod.
The channel is `OBSERVE.server.records.subscribe(type, listener)` — the
server twin of `OBSERVE.attribution.subscribe(type, …)`. C0's
`OBSERVE.server.invocations` (unreleased) is renamed onto it as the
`"invocation"` type; `InvocationChannel` is gone.
The types now layer one augmenter per interface, matching the package
chain. First cut had signals declare `ServerRecords`, solid-js augment it
through `"@solidjs/signals"` and web through `"solid-js"`; each side then
saw only its own overload. Reproduced in isolation: TypeScript merges two
augmentations of one re-exported interface through DIFFERENT alias paths
order-dependently, dropping one set with no error. So: signals declares
`ServerObserve` empty; solid-js augments it once with `records:
ServerRecords` and `trace: ServerTrace`, declaring both (the `"boundary"`
overload inline); web augments those two through `"solid-js"`
(`"invocation"`, `provide`). `TraceSlot` is an alias of `ServerTrace`.
The rule is documented on `ServerObserve`; the web type tests require
both overloads. (`core/index.ts` had also never re-exported the new name.)
Specs: web/test/server/server-boundary-records.spec.tsx against the real
renderers and Reveal — settled/streamed/inlined, a 3-pass chain,
renderToString fallback, client holes at discovery and after a wait, error
paired with the finding, together/natural holds, grouped error, listener
resilience, prod fold-out. Docs: RFC 08 (`OBSERVE.server`, the record),
RFC 10, the plans (C3 landed).
Co-authored-by: Cursor <[email protected]>
* refactor(solid,signals): boundary records use the core's ownerPath; Reveal onReveal plumbing folds out of prod
- `@solidjs/signals` exports `ownerPath`; the server boundary record uses it
instead of a verbatim copy (`ownerLabels`) in solid-js's server observe module.
- The Reveal group's `onReveal` hook registration and dispatch are gated on
`IS_OBSERVE` so the prod artifact carries neither; a second tier pin in
server-boundary-records.spec asserts `onReveal` is absent from server.js and
present in server.observe.js / server.dev.js.
- Merged origin/next.
Co-authored-by: Claude via Cursor <[email protected]>
Co-authored-by: Cursor <[email protected]>
---------
Co-authored-by: Cursor <[email protected]>
Co-authored-by: Claude via Cursor <[email protected]>
Server boundary records on `OBSERVE.server.records` (observe/dev tiers)
8
+
9
+
- New `"boundary"` record: one per `<Loading>` boundary that waited during a server render, delivered when it settles — `{ id, at, durationMs, heldMs, passes, outcome: "settled" | "fallback" | "client" | "error", streamed, revealGroup?, ownerPath? }`, with the thrown error beside it. `id` pairs it with `SSR_RENDER_ERROR_CONTAINED`; `passes` counts render passes (a sequential chain reads as `3+`); under a `<Reveal>` group the record waits for the group's swap so `heldMs` measures how long finished content was held for its siblings. No clock is read without a listener, and the emitter folds out of prod.
10
+
- The server records channel is `OBSERVE.server.records.subscribe(type, listener)` — the server twin of `OBSERVE.attribution.subscribe(type, …)`. `OBSERVE.server.invocations` (unreleased) is renamed onto it: `subscribe("invocation", …)`. The `InvocationChannel` type is gone; `ServerRecords` is the channel's interface.
11
+
- Types now layer one augmenter per interface: `@solidjs/signals` declares `ServerObserve` empty; `solid-js` augments it with `records: ServerRecords` and `trace: ServerTrace`, declaring both; `@solidjs/web` augments those two through `"solid-js"`. `TraceSlot` in `@solidjs/web` is now an alias of `solid-js`'s `ServerTrace`. (Two augmentations of one re-exported interface through different module aliases merge order-dependently in TypeScript — one set was silently lost.)
12
+
-`@solidjs/signals` exports `ownerPath(subject)` — the root-first component-label walk its diagnostics already make — so a record's `ownerPath` and the finding it pairs with come from the one walk.
Copy file name to clipboardExpand all lines: documentation/solid-2.0/08-dev-diagnostics.md
+20-5Lines changed: 20 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -599,22 +599,37 @@ Each `DiagnosticEvent` has:
599
599
600
600
`OBSERVE` is one object per process, shared by every package that reads it, so it is also where the **server** runtime publishes what it has to observe. `OBSERVE.server` is an empty slot on the object `@solidjs/signals` ships; `solid-js`'s **server entry** fills it the moment it evaluates, with containers it registers once per process on `globalThis` (under `Symbol.for("solid-js/observe/server")`). Two consequences an observer can rely on: the slots exist as soon as `import { OBSERVE } from "solid-js"` resolves on the server — an APM's `init()` can subscribe or install a provider before `@solidjs/web` (which emits into them) has loaded, and without importing it — and a host that bundles the runtime into its server build and instruments through a `--import`ed module still finds one listener set and one provider across both copies. Same tiers as the rest of `OBSERVE`: present in dev and observe builds, absent in prod — the prod server artifacts fold the surface and every emit site out, so an observer that finds `OBSERVE === undefined` has nothing to subscribe to. On the client `OBSERVE.server` stays empty.
601
601
602
-
The type is an augmentable interface — `ServerObserve`, declared empty in `solid-js` and filled in by `@solidjs/web` through `declare module "solid-js"`— so `OBSERVE.server.invocations` types without `@solidjs/web` having to be the place `OBSERVE` is imported from. Observers import `OBSERVE` from `solid-js`, as on the client.
602
+
The types layer the way the packages do, each layer augmenting only the one beneath it: `ServerObserve` is declared empty in `@solidjs/signals`; `solid-js`augments it with its two members, `records: ServerRecords`and `trace: ServerTrace`, declaring both interfaces itself; `@solidjs/web`augments those two through `declare module "solid-js"`with what it emits (the `"invocation"` record) and what it defines (the trace provider). So `OBSERVE.server.records.subscribe(…)` types with both packages' records without `@solidjs/web` having to be the place `OBSERVE` is imported from. Observers import `OBSERVE` from `solid-js`, as on the client.
603
603
604
-
Two members so far. The first is the **server-function invocation channel**:
604
+
Two members. The first is the **records channel**, `OBSERVE.server.records` — the server twin of `OBSERVE.attribution.subscribe(type, …)`: a record is a completed, serializable summary of one thing the server did, delivered synchronously the moment it is complete, with the live handles an in-process observer may want passed beside it rather than on it. Subscribe by record type; the types available are whatever the loaded runtimes declared. Two so far.
605
+
606
+
The **`"boundary"` record** (from `solid-js`) is one `<Loading>` boundary that **waited** during a server render:
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.
620
+
621
+
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. Listeners are observers: a throwing listener is reported through `console.error` and the call and the other listeners are unaffected; nothing a listener does reaches the result. The record is the settled, serializable summary; the second argument holds the live handles beside it for observers that want them.
630
+
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.
616
631
617
-
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.
632
+
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.
618
633
619
634
The second member is the **trace-provider slot**, `OBSERVE.server.trace`:
Copy file name to clipboardExpand all lines: documentation/solid-2.0/10-server-functions.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -71,7 +71,7 @@ The handler resolves the function id, decodes arguments, runs the function under
71
71
72
72
Inside a function body, `getRequestEvent()` (from `@solidjs/web`) reads the current event and `getServerFunctionInvocation()` reads the in-flight call’s id — usable for keying caches or logs. (Renamed from `getServerFunctionMeta` to keep clear of `getServerFunctionMetadata(fn)`, which reads a reference’s _static declaration_ metadata; the invocation accessor describes the call currently executing.) In-process SSR calls run the original function directly (no HTTP loopback) under a derived event marked `serverOnly`.
73
73
74
-
**Observing invocations (dev and observe builds).** Both legs — HTTP dispatch and direct SSR calls — report each execution on `OBSERVE.server.invocations`, the server half of the `OBSERVE` object described in [RFC 08](08-dev-diagnostics.md#observeserver--the-server-runtimes-observe-surface): `subscribe("invocation", (event, live) => …)` delivers one `{ id, direct, at, durationMs, outcome, deferred? }` record per call when it settles, with the request event, `request` (HTTP only), `args`, and the result or the error **as thrown** beside it. The measured execution is the `wrapInvocation`-wrapped run, so what the observer times is what the request spent on the call, policy included; a stream or generator result is flagged `deferred` and timed to handoff. This is the client’s `observeServerFunctionCalls` mirrored on the server: observers, any number, none able to change the call. Prod server artifacts carry neither the channel nor the emit sites. A listener that wants the trace a call belongs to reads `getTraceContext()` — in scope during delivery — and a function body forwards it downstream the same way (`getTraceContext()?.entries.traceparent`); the handler’s responses carry it back to the caller as `Server-Timing` (see [RFC 12](12-ssr-http.md#the-trace-the-request-belongs-to-gettracecontext)).
74
+
**Observing invocations (dev and observe builds).** Both legs — HTTP dispatch and direct SSR calls — report each execution as the `"invocation"` record on `OBSERVE.server.records`, the server records channel described in [RFC 08](08-dev-diagnostics.md#observeserver--the-server-runtimes-observe-surface): `subscribe("invocation", (event, live) => …)` delivers one `{ id, direct, at, durationMs, outcome, deferred? }` record per call when it settles, with the request event, `request` (HTTP only), `args`, and the result or the error **as thrown** beside it. The measured execution is the `wrapInvocation`-wrapped run, so what the observer times is what the request spent on the call, policy included; a stream or generator result is flagged `deferred` and timed to handoff. This is the client’s `observeServerFunctionCalls` mirrored on the server: observers, any number, none able to change the call. Prod server artifacts carry neither the channel nor the emit sites. A listener that wants the trace a call belongs to reads `getTraceContext()` — in scope during delivery — and a function body forwards it downstream the same way (`getTraceContext()?.entries.traceparent`); the handler’s responses carry it back to the caller as `Server-Timing` (see [RFC 12](12-ssr-http.md#the-trace-the-request-belongs-to-gettracecontext)).
75
75
76
76
`registerServerFunction(id, fn)` / `getServerFunction(id)` remain exported for integrations building custom dispatch or introspection. Registry _mutation_ as a userland extension pattern is rejected (see Alternatives).
0 commit comments