Skip to content

Commit 61a114c

Browse files
ryansolidcursoragentClaude via Cursor
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]>
1 parent 08fe835 commit 61a114c

22 files changed

Lines changed: 951 additions & 131 deletions
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
"@solidjs/signals": patch
3+
"solid-js": patch
4+
"@solidjs/web": patch
5+
---
6+
7+
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.

‎documentation/plans/server-dev-build-plan.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -297,7 +297,12 @@ type/tooling reuse, with unused members no-op.
297297
> `solid-js`, and populated (object at load, type by `declare module
298298
"solid-js"` augmentation) by `@solidjs/web`'s server entries. First channel:
299299
> `OBSERVE.server.invocations` (`subscribe("invocation", (event, live) =>
300-
…)`), emitted from both server-function legs. Observe-tier only: web now
300+
…)`), emitted from both server-function legs. _(Since C3, 2026-09-14: the
301+
> channel is `OBSERVE.server.records`, generic over record type — the
302+
> `"boundary"` record from solid-js's server entry joined the `"invocation"`
303+
> one — and the objects and the `records`/`trace` members are solid-js's,
304+
> with web augmenting solid-js's `ServerRecords`/`ServerTrace`; see
305+
> `sentry-integration-plan.md` C3.)_ Observe-tier only: web now
301306
> ships `dist/server.observe.js`, `server-functions/dist/server.observe.js`
302307
> and `frames/dist/server.observe.js` under the `observe` condition (the P0
303308
> plumbing, third flavour), and every emit site folds out of prod behind

‎documentation/solid-2.0/08-dev-diagnostics.md‎

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -599,22 +599,37 @@ Each `DiagnosticEvent` has:
599599

600600
`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.
601601

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.
603603

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:
605607

606608
```js
607609
import { OBSERVE } from "solid-js";
608610

609-
const off = OBSERVE.server.invocations.subscribe("invocation", (event, live) => {
611+
const off = OBSERVE.server.records.subscribe("boundary", (event, live) => {
612+
// event: { id, at, durationMs, heldMs, passes,
613+
// outcome: "settled" | "fallback" | "client" | "error",
614+
// streamed, revealGroup?, ownerPath? }
615+
// live: { error? }
616+
});
617+
```
618+
619+
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:
622+
623+
```js
624+
const off = OBSERVE.server.records.subscribe("invocation", (event, live) => {
610625
// event: { id, direct, at, durationMs, outcome: "ok" | "error", deferred? }
611626
// live: { event: RequestEvent, request?, args, result? | error? }
612627
});
613628
```
614629

615-
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.
616631

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.
618633

619634
The second member is the **trace-provider slot**, `OBSERVE.server.trace`:
620635

‎documentation/solid-2.0/10-server-functions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ The handler resolves the function id, decodes arguments, runs the function under
7171

7272
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`.
7373

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)).
7575

7676
`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).
7777

‎packages/signals/src/core/dev.ts‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -186,11 +186,20 @@ export interface AttributionSlot {
186186
/**
187187
* The server runtime's observe surface — the one place a server-side
188188
* consumer (an APM adapter's `init()`) installs on, beside `diagnostics`.
189-
* Declared EMPTY here and typed by the runtime that owns the facts:
190-
* `@solidjs/web`'s server entries augment this interface with their
191-
* members (the server-function invocation channel, the trace-provider
192-
* slot), so the core never learns those shapes and the consumer still finds
193-
* everything on the one `OBSERVE`.
189+
* Declared EMPTY here and typed by the runtime that owns the surface:
190+
* `solid-js`'s server entry augments this interface with its members — the
191+
* records channel (`ServerRecords`) and the trace-provider slot
192+
* (`ServerTrace`), each an interface of its own that `@solidjs/web`'s
193+
* server entries fill in further — so the core never learns those shapes
194+
* and the consumer still finds everything on the one `OBSERVE`.
195+
*
196+
* One augmenter per interface, by design: TypeScript merges an
197+
* augmentation into a re-exported interface by following the alias, and
198+
* two augmentations reaching the same interface through DIFFERENT aliases
199+
* (`"@solidjs/signals"` from solid-js, `"solid-js"` from web) merge
200+
* order-dependently — one set is lost. So each layer augments only the
201+
* layer beneath it, through one module name, and declares the interfaces
202+
* the layer above fills in.
194203
*
195204
* The OBJECTS behind those members are not the core's either: the core has
196205
* one artifact per tier for both platforms, and the client would carry
@@ -315,7 +324,10 @@ export const OBSERVE: Observe = __OBSERVE__
315324
? {
316325
diagnostics,
317326
attribution: attributionSlot,
318-
server: {},
327+
// Replaced by solid-js's server entry (see `ServerObserve`); on the
328+
// client the slot stays this placeholder. The cast: the interface is
329+
// empty HERE and gains its members by augmentation downstream.
330+
server: {} as ServerObserve,
319331
subjectOf(event) {
320332
return eventSubjects.get(event);
321333
},

‎packages/signals/src/core/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ export type {
7676
export {
7777
DEV,
7878
OBSERVE,
79+
ownerPath,
7980
type AttributionSlot,
8081
type Dev,
8182
type Observe,

‎packages/signals/src/index.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@ export {
2828
clearSnapshots,
2929
enforceLoadingBoundary,
3030
enableExternalSource,
31-
resetErrorHalt
31+
resetErrorHalt,
32+
ownerPath
3233
} from "./core/index.js";
3334
import { DEV as _DEV, OBSERVE as _OBSERVE, type Dev, type Observe } from "./core/index.js";
3435
/**

‎packages/solid/src/index.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,20 @@ export type {
173173
DiagnosticSeverity,
174174
DiagnosticSubject
175175
} from "@solidjs/signals";
176+
// The server observe surface's types — the members solid-js declares onto
177+
// `OBSERVE.server` (`records`, `trace`) and the record it emits — and with
178+
// them the `ServerObserve` augmentation that module declares: the published
179+
// types resolve to THIS entry under every condition, so this re-export is
180+
// what puts the surface in an observer's program (and what `@solidjs/web`
181+
// augments further, through `"solid-js"`). Type-only — the module's runtime
182+
// never enters the client build.
183+
export type {
184+
BoundaryEvent,
185+
BoundaryLive,
186+
BoundaryListener,
187+
ServerRecords,
188+
ServerTrace
189+
} from "./server/observe.js";
176190
export type {
177191
Acknowledgement,
178192
AttributionRecords,

0 commit comments

Comments
 (0)