Skip to content

Commit bae6b06

Browse files
feat(solid,web,signals): server diagnostics on OBSERVE.diagnostics; OBSERVE.server owned by solid-js's server entry
The server runtime reports on the same structured channel as the client (server-dev-build-plan P1 + P2, one PR). Two helper modules hold the gates — packages/solid/src/server/diagnostics.ts and packages/web/src/diagnostics.ts — with three verbs: emitFinding (observe + dev: emit, and in dev report through DEV.report), recordFinding (emit only, for a site that throws its message), devCheck (emitFinding behind the dev gate). Call sites are wrapped in literal "_SOLID_OBSERVE_" / "_SOLID_DEV_" tests so Rollup drops the message strings from the tiers below; the prod server artifacts carry none of it. Findings (observe + dev): SSR_RENDER_ERROR_CONTAINED (data.handling: fallback from createErrorBoundary, client/failed from the Loading boundary's routing, failed from the root — the structured face of renderToStream's onError, on the process-wide channel), SSR_SUBTREE_ABANDONED, SSR_STREAM_ABANDONED (consumer | sink), LATE_HEADER_WRITE (recorded beside the dev throw / prod log), SERVER_FN_ERROR_SANITIZED (the original the wire replaced), FRAME_MARKER_CORRUPTED (frames client). Checks (dev): every server console.warn becomes a code — SERVER_WRITE, REVEAL_IN_RENDER_TO_STRING, LAZY_ASSET_UNMAPPED, PRELOAD_DESCRIPTOR_INVALID, HEAD_TAG_INVALID, BEHAVIOR_CLAIM_DROPPED, UNRECOGNIZED_INSERT_VALUE (one code and a new `render` kind on both platforms; the client's console.warn is converted too). ASYNC_OUTSIDE_LOADING_BOUNDARY on the server records with data.side: "server" before it throws. DiagnosticKind gains ssr, head, render. ownerPath: the server createComponent runs the body under a transparent owner labelled <Name> in observe/dev (createComponentOwner — no hydration id consumed, no ownerCreations tick); the core's ownerPath walk reads SSROwner._parent/_name unchanged. The repair-guide console footer moves to src/console-footer.ts and both entries install it, so a server render's [SERVER_WRITE] points at the same skill section. The server entry also exports the Dev/Observe/Diagnostic* types the client entry does. OBSERVE.server (C0/C1 follow-ups J.23/J.24): the invocation listener set and trace-provider slot are created by solid-js's server entry (src/server/observe.ts), once per process under Symbol.for("solid-js/observe/server") on globalThis — not by web's module init (an observer's init() importing only solid-js found the slot empty) and not by the signals core (one artifact per tier for both platforms; a draft there cost the client observe tier 138 B). The core keeps `server: {}`; web reads the containers by the registered names. Docs: RFC 08 "Server rendering" reference + quick-reference rows, the corrected OBSERVE.server ownership paragraph; reactivity-diagnostics skill gains a section per server code; plan doc records P1/P2 landed and the compiler gap (SSR output inlines Comp(props); labels need createComponent emitted under componentNames — separate PR). Specs: solid/test/server/{server-diagnostics,observe-server,console-footer}.spec.ts, web/test/server/server-diagnostics.spec.tsx, web/test/frames-marker-corruption.spec.tsx, a client UNRECOGNIZED_INSERT_VALUE case in web/test/dev-warning.spec.tsx. Size: observe CSR 15493 B (cap 15550), attribution 27093 B (cap 27160). Co-authored-by: Cursor <[email protected]>
1 parent a031271 commit bae6b06

32 files changed

Lines changed: 2212 additions & 225 deletions
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
"@solidjs/signals": patch
3+
"solid-js": patch
4+
"@solidjs/web": patch
5+
---
6+
7+
Server diagnostics on `OBSERVE.diagnostics`; `OBSERVE.server` owned by `solid-js`'s server entry
8+
9+
The server runtime now reports on the same structured channel as the client. **Findings** — facts about a render, present in observe and dev builds — `SSR_RENDER_ERROR_CONTAINED` (a render error a boundary routed; `data.handling` is `fallback`, `client`, or `failed` — the structured face of what `renderToStream`'s `onError` receives, on the process-wide channel), `SSR_SUBTREE_ABANDONED` (a failed fragment's pending descendants discarded), `SSR_STREAM_ABANDONED` (consumer cancelled or sink failed mid-render), `LATE_HEADER_WRITE` (recorded beside the existing dev throw / prod log), `SERVER_FN_ERROR_SANITIZED` (the original error the production wire replaced), and `FRAME_MARKER_CORRUPTED` from the frames client. **Checks** — dev-only guidance — convert every server `console.warn` to a code: `SERVER_WRITE`, `REVEAL_IN_RENDER_TO_STRING`, `LAZY_ASSET_UNMAPPED`, `PRELOAD_DESCRIPTOR_INVALID`, `HEAD_TAG_INVALID`, `BEHAVIOR_CLAIM_DROPPED`, and `UNRECOGNIZED_INSERT_VALUE` (now one code and a `render` kind on both platforms); `ASYNC_OUTSIDE_LOADING_BOUNDARY` on the server records with `data.side: "server"` before it throws. Server components are labelled for `ownerPath` (`createComponent` runs the body under a transparent `<Name>` owner in observe/dev — no hydration id consumed), so `in <App> › <Page>` reads the same on both sides, and the server entry installs the same repair-guide console footer as the client. Prod artifacts carry none of it; `DiagnosticKind` gains `ssr`, `head`, `render`.
10+
11+
`OBSERVE.server`'s objects (the invocation listener set, the trace-provider slot) are now created by `solid-js`'s server entry, once per process under `Symbol.for("solid-js/observe/server")` on `globalThis`, rather than by `@solidjs/web`'s module init: an observer's `init()` that imports only `solid-js` can subscribe and `provide` before the web runtime has loaded, and a host that bundles the runtime into its server build and instruments through a `--import`ed module finds one listener set and one provider across both copies. The core keeps `server: {}`; the client pays nothing.

‎.changeset/server-observe-install-point.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,6 @@
66

77
Server observe surface: `OBSERVE.server` and the invocation channel
88

9-
`OBSERVE` gains a `server` slot — an augmentable `ServerObserve` interface declared empty in `@solidjs/signals` (re-exported by `solid-js`) and populated by `@solidjs/web`'s server runtime, so server-side observability consumers subscribe on the one `OBSERVE` object they already know from the client. The first channel is `OBSERVE.server.invocations`: `subscribe("invocation", (event, live) => …)` delivers one `{ id, direct, at, durationMs, outcome, deferred? }` record per server-function execution — HTTP dispatch and direct SSR calls alike — when it settles, with the request event, `request`, `args`, and the result or the error as thrown beside it. Observers, not policy: any number of listeners, none able to alter the call; `wrapInvocation` remains the single policy hook.
9+
`OBSERVE` gains a `server` slot — an augmentable `ServerObserve` interface declared empty in `@solidjs/signals` (re-exported by `solid-js`), typed and emitted into by `@solidjs/web`'s server runtime, so server-side observability consumers subscribe on the one `OBSERVE` object they already know from the client. The first channel is `OBSERVE.server.invocations`: `subscribe("invocation", (event, live) => …)` delivers one `{ id, direct, at, durationMs, outcome, deferred? }` record per server-function execution — HTTP dispatch and direct SSR calls alike — when it settles, with the request event, `request`, `args`, and the result or the error as thrown beside it. Observers, not policy: any number of listeners, none able to alter the call; `wrapInvocation` remains the single policy hook.
1010

1111
`@solidjs/web` now publishes observe-tier server artifacts (`dist/server.observe.js`, `server-functions/dist/server.observe.js`, `frames/dist/server.observe.js`) under the `observe` export condition, alongside the existing dev/prod pairs. The surface and every emit site fold out of the prod artifacts.

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

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,40 @@ Decision: **reuse `@solidjs/signals`'s channel, do not fork it.**
170170
> `dist/server.observe.*` already exists (exporting a live `OBSERVE`); P1
171171
> gives it content. Read `DEV.diagnostics` below as `OBSERVE.diagnostics`.
172172
173+
> **Landed 2026-09-13 (P1 + P2, one PR).** Two helper modules hold the
174+
> gates — `packages/solid/src/server/diagnostics.ts` and
175+
> `packages/web/src/diagnostics.ts` — with three verbs: `emitFinding`
176+
> (observe + dev: emit, and in dev report through `DEV.report`),
177+
> `recordFinding` (emit only, for a site that throws its message — the throw
178+
> is the console face), `devCheck` (`emitFinding` behind the dev gate, so the
179+
> observe artifact carries neither the call nor the text). Every call site is
180+
> additionally wrapped in a literal `if ("_SOLID_OBSERVE_")` / `if
181+
("_SOLID_DEV_")` so Rollup drops the message strings from the tiers below.
182+
> `ownerPath`: `createComponent` on the server wraps the call in a
183+
> transparent owner labelled `_name` (`createComponentOwner` — no hydration
184+
> id consumed, no `ownerCreations` tick) in observe/dev, and the core's
185+
> `ownerPath` walk reads `SSROwner._parent`/`_name` unchanged. The wiring
186+
> findings: `SSR_RENDER_ERROR_CONTAINED` (`data.handling`:
187+
> `fallback` from `createErrorBoundary`, `client`/`failed` from the Loading
188+
> boundary's routing, `failed` from the root), `SSR_SUBTREE_ABANDONED`
189+
> (`abandonSubtree` with pending work discarded), `SSR_STREAM_ABANDONED`
190+
> (`abandon("consumer" | "sink")`), `LATE_HEADER_WRITE` (recorded, then the
191+
> existing dev throw / prod log), `SERVER_FN_ERROR_SANITIZED`
192+
> (`sanitizeServerError`, `data.error` the original). The server entry also
193+
> installs the client's repair-guide console footer (`src/console-footer.ts`,
194+
> shared). Specs: `packages/solid/test/server/server-diagnostics.spec.ts`,
195+
> `packages/web/test/server/server-diagnostics.spec.tsx`,
196+
> `packages/web/test/frames-marker-corruption.spec.tsx`. Docs: RFC 08
197+
> "Server rendering" + quick reference; the reactivity-diagnostics skill.
198+
>
199+
> Known gap, deliberately out of this PR: the SSR compiler inlines component
200+
> calls (`Comp({})`) instead of `createComponent`, so compiled JSX does not
201+
> get the label — `ownerPath` is populated for `createComponent` callers
202+
> (the runtime's own flow components, `Dynamic`, tests) and empty for a
203+
> plain compiled `<Comp/>` tree. The fix is the compiler emitting
204+
> `createComponent` under the `componentNames` option for SSR output as it
205+
> does for the client; tracked separately.
206+
173207
- The server facade imports `DEV` (and the `emitDiagnostic` /
174208
`DiagnosticEvent` types) from `@solidjs/signals`, every use behind
175209
`"_SOLID_DEV_"` so the prod server build folds it out and never touches
@@ -243,9 +277,9 @@ type/tooling reuse, with unused members no-op.
243277
> failed, a boundary flushed. That surface is `OBSERVE.server` — an empty
244278
> `ServerObserve` interface declared in `@solidjs/signals`, re-exported by
245279
> `solid-js`, and populated (object at load, type by `declare module
246-
> "solid-js"` augmentation) by `@solidjs/web`'s server entries. First channel:
280+
"solid-js"` augmentation) by `@solidjs/web`'s server entries. First channel:
247281
> `OBSERVE.server.invocations` (`subscribe("invocation", (event, live) =>
248-
> …)`), emitted from both server-function legs. Observe-tier only: web now
282+
…)`), emitted from both server-function legs. Observe-tier only: web now
249283
> ships `dist/server.observe.js`, `server-functions/dist/server.observe.js`
250284
> and `frames/dist/server.observe.js` under the `observe` condition (the P0
251285
> plumbing, third flavour), and every emit site folds out of prod behind

0 commit comments

Comments
 (0)