@runic-artifex/vite-plugin-runic 0.13.0 → 0.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +123 -26
- package/dist/channel.d.ts +16 -0
- package/dist/channel.js +21 -0
- package/dist/client.js +180 -31
- package/dist/dev-session.d.ts +28 -9
- package/dist/dev-session.js +148 -24
- package/dist/diagnostics.d.ts +12 -0
- package/dist/diagnostics.js +84 -0
- package/dist/index.d.ts +12 -27
- package/dist/index.js +141 -138
- package/dist/stale-input.js +2 -1
- package/dist/timeline.d.ts +70 -0
- package/dist/timeline.js +112 -0
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -27,7 +27,7 @@ or later 24.x, or Node 26.
|
|
|
27
27
|
same as omitting the option: the development client is injected while serving,
|
|
28
28
|
and the Runic dock appears when `DevTools()` is registered. `true` also requires
|
|
29
29
|
`DevTools()`: serving without it fails with
|
|
30
|
-
[`RUNICP007`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
30
|
+
[`RUNICP007`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.0/docs/diagnostics.md#runicp007).
|
|
31
31
|
`false` turns off both the dock and the development client.
|
|
32
32
|
`maxTimelineEntries` sets how many timeline entries the dock keeps: 200 by
|
|
33
33
|
default, rounded down and limited to 1 to 500.
|
|
@@ -36,7 +36,7 @@ While serving, the plugin adds `virtual:runic/client`, which loads the
|
|
|
36
36
|
development client (`@runic-artifex/vite-plugin-runic/client`), to `index.html`.
|
|
37
37
|
The client has no exports. It shows the page's connection to its .NET host, as
|
|
38
38
|
`@runic-artifex/views` reports it (`connecting`, `connected`, `reconnecting`,
|
|
39
|
-
`lost`), on the dock's **Connection** card from page load, before a View
|
|
39
|
+
`lost`, and `closed` once the application closed the window), on the dock's **Connection** card from page load, before a View
|
|
40
40
|
connects (with `@runic-artifex/views` 0.11 or later; earlier releases start it
|
|
41
41
|
when the first View connects), and forwards
|
|
42
42
|
`@runic-artifex/views` failures to the timeline: the failed route, the
|
|
@@ -47,7 +47,11 @@ dock shows the most recent one. A failure keeps file paths, so that a stack is
|
|
|
47
47
|
useful, but is bounded and has credential values redacted. Failures stay in
|
|
48
48
|
the dock: `/__runic/state` and the copied diagnostic state leave them out, and
|
|
49
49
|
the other timeline fields stay path-free. An application without a Vite-served `index.html` imports
|
|
50
|
-
|
|
50
|
+
the client itself, with `import "@runic-artifex/vite-plugin-runic/client"` (or
|
|
51
|
+
`virtual:runic/client`): `runic()` resolves that import to the same module it
|
|
52
|
+
injects while serving, and to an empty module in the build and on the server,
|
|
53
|
+
so nothing reaches production output. `devtools: false` turns the client off:
|
|
54
|
+
no injection, and an import of it is empty.
|
|
51
55
|
The plugin adds `@runic-artifex/vite-plugin-runic/client` to
|
|
52
56
|
`optimizeDeps.include`, because the dependency scanner cannot see the injected
|
|
53
57
|
client: with a cold `node_modules/.vite` cache, the first page would otherwise
|
|
@@ -66,6 +70,117 @@ fields with the text-field binding of your framework package
|
|
|
66
70
|
`runic({ staleInputWarning: false })`, or from the page by setting
|
|
67
71
|
`globalThis[Symbol.for("runic.vite.staleInputWarning")] = false`.
|
|
68
72
|
|
|
73
|
+
### State inspector
|
|
74
|
+
|
|
75
|
+
With `@runic-artifex/views` 0.15 or later the development client also reports
|
|
76
|
+
each open View's state, as the page shows it, and the dock shows it on the
|
|
77
|
+
**Views** card: one card per View with its route, revision and presentation
|
|
78
|
+
epoch, the most recently changed first, and the state as a tree. The client
|
|
79
|
+
sends a View's latest state at most every 250 ms, and the server keeps the 32
|
|
80
|
+
Views that changed last, per page (several windows can share one development
|
|
81
|
+
server), and forgets a View when it closes and a page's Views when the page
|
|
82
|
+
goes away. The state is redacted and bounded like timeline details: a member
|
|
83
|
+
whose name suggests a credential or a path (`password`, `accessToken`,
|
|
84
|
+
`filePath`, …) and a string that looks like a credential or a path read
|
|
85
|
+
`[redacted]`, strings are shortened, long lists end with `… N more`, and deep
|
|
86
|
+
or large states are shown shallower. It is part of `/__runic/state` (`views`)
|
|
87
|
+
and of the copied diagnostic state, which hold no failures.
|
|
88
|
+
|
|
89
|
+
A command that the Bridge answered `superseded` (a
|
|
90
|
+
[command scoped to its page](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.0/packages/web/vite-plugin-runic/../views/README.md#scoped-commands) called from an earlier page)
|
|
91
|
+
resolves like one that ran, so the page shows nothing. The client reports it
|
|
92
|
+
as a timeline entry (`kind: "command"`, label `<member> superseded`,
|
|
93
|
+
`detail.code: "superseded"` with the route, member, the epoch it was issued for
|
|
94
|
+
and the reply's revision), and the dock lists the latest on the **Superseded
|
|
95
|
+
commands** card. With the Angular CLI, read both from `/__runic/state`.
|
|
96
|
+
|
|
97
|
+
The inspector runs only where the development client does: never in a build.
|
|
98
|
+
`@runic-artifex/views` reports to it only once the client asked for it
|
|
99
|
+
(`runic.views.inspector` in the
|
|
100
|
+
[shared globals](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.0/specs/application/README.md#shared-globals)).
|
|
101
|
+
|
|
102
|
+
## SvelteKit and Angular
|
|
103
|
+
|
|
104
|
+
SvelteKit renders its pages itself and warns about every plugin with a
|
|
105
|
+
`transformIndexHtml` hook. Use `runic({ html: false })`: the plugin then has no
|
|
106
|
+
such hook, injects nothing into HTML and leaves host scripts alone, and keeps
|
|
107
|
+
everything else: the timeline, the dock, `/__runic/state` and the dev session.
|
|
108
|
+
The page loads the client from its client hooks:
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
// vite.config.ts
|
|
112
|
+
plugins: [sveltekit({ adapter: runicAdapter() }), runic({ html: false })],
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
// src/hooks.client.ts
|
|
117
|
+
import "@runic-artifex/vite-plugin-runic/client";
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`html: false` cannot be combined with `desktop`, whose bootstrap is a script
|
|
121
|
+
tag in the HTML: `runic({ html: false, desktop: true })` throws.
|
|
122
|
+
|
|
123
|
+
The Angular CLI's development server loads no Vite plugins, only a proxy
|
|
124
|
+
configuration. `runicDevSessionProxy()` returns Vite proxy entries that answer
|
|
125
|
+
locally and never proxy. Spread it into the file that the serve target's
|
|
126
|
+
`proxyConfig` in `angular.json` names:
|
|
127
|
+
|
|
128
|
+
```js
|
|
129
|
+
// proxy.conf.mjs
|
|
130
|
+
import { runicDevSessionProxy } from "@runic-artifex/vite-plugin-runic";
|
|
131
|
+
|
|
132
|
+
export default { ...runicDevSessionProxy() };
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
and load the client from `main.ts` in development only:
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
// src/main.ts, before bootstrapApplication
|
|
139
|
+
if (typeof ngDevMode === "undefined" || ngDevMode) await import("@runic-artifex/vite-plugin-runic/client");
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
A production build (`optimization` on, the default `production`
|
|
143
|
+
configuration) defines `ngDevMode` as `false`, so the import and the client's
|
|
144
|
+
chunk are left out. `isDevMode()` would keep the chunk in the output, because
|
|
145
|
+
the build cannot evaluate a function call.
|
|
146
|
+
|
|
147
|
+
The entries keep the development state in the `ng serve` process and answer:
|
|
148
|
+
|
|
149
|
+
- `/__runic/state` with that state, as `runic()` does: the connection, the
|
|
150
|
+
timeline without failures, and under `dotnet runic dev` the session header
|
|
151
|
+
([Dev session](#dev-session-and-host-scripts)). The answer is `200` with JSON; without `dotnet runic dev` the
|
|
152
|
+
entry answers too, without the header.
|
|
153
|
+
- `/__runic/diagnostics`, which the client posts its reports to. Each Views
|
|
154
|
+
failure is printed to the `ng serve` terminal with its exception type,
|
|
155
|
+
message and stack:
|
|
156
|
+
|
|
157
|
+
```text
|
|
158
|
+
[runic] views editorSave failed
|
|
159
|
+
System.InvalidOperationException: Disk full.
|
|
160
|
+
at Notes.Editor.Save() in /src/Notes/Editor.cs:line 12
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
`runicDevSessionProxy({ maxTimelineEntries, printFailures })` takes the same
|
|
164
|
+
timeline limit as `runic()` and `printFailures: false` to keep the terminal
|
|
165
|
+
quiet. The `stale-input` warning works the same as with `runic()`; turn it off
|
|
166
|
+
from the page with the registered symbol above.
|
|
167
|
+
|
|
168
|
+
### The client's channel
|
|
169
|
+
|
|
170
|
+
Loaded by `runic()`, the client reports over Vite's HMR connection. Loaded
|
|
171
|
+
otherwise, it posts each report as `{ "event", "data" }` JSON to
|
|
172
|
+
`/__runic/diagnostics` on its own origin, one at a time and in order, and keeps
|
|
173
|
+
at most 100 waiting. `runic()` answers that endpoint too. The endpoint accepts
|
|
174
|
+
only a `POST` with `Content-Type: application/json` and an `Origin` of the
|
|
175
|
+
server itself (a cross-site page would need a CORS preflight, which it never
|
|
176
|
+
grants), rejects a `Sec-Fetch-Site` other than `same-origin` and a body over
|
|
177
|
+
64 KiB, and sanitizes every entry like any other timeline entry. If the first
|
|
178
|
+
report gets no `204` answer, the page has no Runic development server, and the
|
|
179
|
+
client stops and removes its listeners. Without Vite's HMR context the client
|
|
180
|
+
installs the `stale-input` warning only after that first answer.
|
|
181
|
+
|
|
182
|
+
## Dev session and host scripts
|
|
183
|
+
|
|
69
184
|
Under `dotnet runic dev`, the Vite process gets a random value for the session
|
|
70
185
|
in `RUNIC_APPLICATION_DEV_SESSION`, and `/__runic/state` answers with it in the
|
|
71
186
|
`X-Runic-Dev-Session` header. Since 0.11, `dev` treats the server as ready
|
|
@@ -75,29 +190,11 @@ Pages and other responses do not carry the header. Use the plugin from the same
|
|
|
75
190
|
release as `dotnet-runic`, because an older plugin does not answer and `dev`
|
|
76
191
|
times out with `RAPPDEV1007`.
|
|
77
192
|
|
|
78
|
-
|
|
79
|
-
`
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
```ts
|
|
85
|
-
plugins: [sveltekit({ adapter: runicAdapter() }), runicDevSession()],
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
- `runicDevSessionProxy()` returns Vite proxy entries, for the Angular CLI,
|
|
89
|
-
which takes a proxy configuration but no Vite plugins. Spread it into the
|
|
90
|
-
file that the serve target's `proxyConfig` in `angular.json` names:
|
|
91
|
-
|
|
92
|
-
```js
|
|
93
|
-
// proxy.conf.mjs
|
|
94
|
-
import { runicDevSessionProxy } from "@runic-artifex/vite-plugin-runic";
|
|
95
|
-
|
|
96
|
-
export default { ...runicDevSessionProxy() };
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
`dotnet runic dev` expects the answer from an Angular frontend whose
|
|
100
|
-
`package.json` declares this package.
|
|
193
|
+
`runicDevSessionProxy()` answers the session for the Angular CLI (above).
|
|
194
|
+
`dotnet runic dev` expects the answer from an Angular frontend whose
|
|
195
|
+
`package.json` declares this package. `runicDevSession()`, which answered only
|
|
196
|
+
the session, was removed in 0.15: SvelteKit uses `runic({ html: false })`
|
|
197
|
+
(above).
|
|
101
198
|
|
|
102
199
|
The `runic-app` template's SvelteKit and Angular frontends are set up this way.
|
|
103
200
|
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
export declare const diagnosticEvent = "runic:diagnostic";
|
|
2
|
+
export declare const connectionEvent = "runic:connection";
|
|
3
|
+
/** The state inspector: a View's state, a closed View, or a page that went away (`DevelopmentTimeline.applyView`). */
|
|
4
|
+
export declare const viewEvent = "runic:view";
|
|
5
|
+
/** The endpoint a client posts `{ "event", "data" }` to, one message per request, answered with 204. */
|
|
6
|
+
export declare const diagnosticsPath = "/__runic/diagnostics";
|
|
7
|
+
/**
|
|
8
|
+
* The largest request body the endpoint accepts. A sanitized diagnostic with a failure is at most about 12,000
|
|
9
|
+
* characters, so this leaves room for JSON escaping and multibyte text.
|
|
10
|
+
*/
|
|
11
|
+
export declare const maximumClientMessageBytes = 65536;
|
|
12
|
+
/** `{ channel?: "hot" }` on `globalThis`, set by `virtual:runic/client` before the client evaluates. */
|
|
13
|
+
export declare const clientOptionsKey: unique symbol;
|
|
14
|
+
export interface RunicClientOptions {
|
|
15
|
+
readonly channel?: "hot";
|
|
16
|
+
}
|
package/dist/channel.js
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
// The channel between the development client and the development server, shared by both sides.
|
|
2
|
+
//
|
|
3
|
+
// `runic()` loads the client through `virtual:runic/client`, which sets the client options below to the HMR channel:
|
|
4
|
+
// the client sends with `import.meta.hot.send`, and the plugin listens on `server.ws`. A client that loads otherwise
|
|
5
|
+
// (the Angular CLI's development server, which runs no Vite plugins, or an application import of the package) posts
|
|
6
|
+
// each message to `diagnosticsPath` instead, which `runic()` and `runicDevSessionProxy()` answer.
|
|
7
|
+
//
|
|
8
|
+
// A sanitized View state is at most about 16,000 characters (diagnostics.ts, `sanitizeViewState`).
|
|
9
|
+
export const diagnosticEvent = "runic:diagnostic";
|
|
10
|
+
export const connectionEvent = "runic:connection";
|
|
11
|
+
/** The state inspector: a View's state, a closed View, or a page that went away (`DevelopmentTimeline.applyView`). */
|
|
12
|
+
export const viewEvent = "runic:view";
|
|
13
|
+
/** The endpoint a client posts `{ "event", "data" }` to, one message per request, answered with 204. */
|
|
14
|
+
export const diagnosticsPath = "/__runic/diagnostics";
|
|
15
|
+
/**
|
|
16
|
+
* The largest request body the endpoint accepts. A sanitized diagnostic with a failure is at most about 12,000
|
|
17
|
+
* characters, so this leaves room for JSON escaping and multibyte text.
|
|
18
|
+
*/
|
|
19
|
+
export const maximumClientMessageBytes = 65_536;
|
|
20
|
+
/** `{ channel?: "hot" }` on `globalThis`, set by `virtual:runic/client` before the client evaluates. */
|
|
21
|
+
export const clientOptionsKey = Symbol.for("runic.vite.client");
|
package/dist/client.js
CHANGED
|
@@ -1,16 +1,73 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
// about script that overwrites a focused text field with an older value (`stale-input`). It
|
|
4
|
-
// has no exports: applications do not import it.
|
|
5
|
-
import { sanitizeDiagnosticSummary } from "./diagnostics.js";
|
|
1
|
+
import { clientOptionsKey, connectionEvent, diagnosticEvent, diagnosticsPath, maximumClientMessageBytes, viewEvent, } from "./channel.js";
|
|
2
|
+
import { sanitizeDiagnosticSummary, sanitizeViewState } from "./diagnostics.js";
|
|
6
3
|
import { installStaleInputWarning } from "./stale-input.js";
|
|
4
|
+
const host = globalThis;
|
|
7
5
|
const hot = import.meta.hot;
|
|
8
|
-
const
|
|
9
|
-
|
|
6
|
+
const options = host[clientOptionsKey];
|
|
7
|
+
// The listeners of a previous evaluation (HMR), so this copy replaces them.
|
|
8
|
+
const data = hot?.data ?? {};
|
|
9
|
+
// Messages wait in order, one request at a time, so a later connection state never overtakes an earlier one.
|
|
10
|
+
const maximumPendingMessages = 100;
|
|
11
|
+
const pending = [];
|
|
12
|
+
let posting = false;
|
|
13
|
+
// `open` after the endpoint first answered, `closed` after it did not: then the page has no Runic development server
|
|
14
|
+
// (a build that kept the client, a server without the endpoint), and the client stops.
|
|
15
|
+
let channel = "unknown";
|
|
16
|
+
function post(event, payload) {
|
|
17
|
+
if (channel === "closed")
|
|
18
|
+
return;
|
|
19
|
+
const body = JSON.stringify({ event, data: payload });
|
|
20
|
+
const encoder = host.TextEncoder;
|
|
21
|
+
const size = encoder ? new encoder().encode(body).byteLength : body.length * 3;
|
|
22
|
+
if (size > maximumClientMessageBytes)
|
|
23
|
+
return;
|
|
24
|
+
pending.push(body);
|
|
25
|
+
if (pending.length > maximumPendingMessages)
|
|
26
|
+
pending.shift();
|
|
27
|
+
if (!posting)
|
|
28
|
+
void drain();
|
|
29
|
+
}
|
|
30
|
+
async function drain() {
|
|
31
|
+
const fetch = host.fetch;
|
|
32
|
+
posting = true;
|
|
33
|
+
try {
|
|
34
|
+
while (pending.length > 0 && channel !== "closed") {
|
|
35
|
+
const body = pending.shift();
|
|
36
|
+
let answered = false;
|
|
37
|
+
try {
|
|
38
|
+
const response = await fetch?.(diagnosticsPath, {
|
|
39
|
+
method: "POST",
|
|
40
|
+
headers: { "Content-Type": "application/json" },
|
|
41
|
+
body,
|
|
42
|
+
credentials: "same-origin",
|
|
43
|
+
cache: "no-store",
|
|
44
|
+
});
|
|
45
|
+
answered = response?.status === 204;
|
|
46
|
+
}
|
|
47
|
+
catch { /* answered stays false */ }
|
|
48
|
+
if (!answered) {
|
|
49
|
+
close();
|
|
50
|
+
return;
|
|
51
|
+
}
|
|
52
|
+
if (channel === "unknown") {
|
|
53
|
+
channel = "open";
|
|
54
|
+
// Without Vite's HMR context only the answer shows that a development server serves the page.
|
|
55
|
+
if (!hot)
|
|
56
|
+
installStaleInputWarning(globalThis);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
finally {
|
|
61
|
+
posting = false;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
const send = hot && options?.channel === "hot"
|
|
65
|
+
? (event, payload) => hot.send(event, payload)
|
|
66
|
+
: post;
|
|
10
67
|
function sendDiagnostic(candidate) {
|
|
11
68
|
const summary = sanitizeDiagnosticSummary(candidate);
|
|
12
69
|
if (summary)
|
|
13
|
-
|
|
70
|
+
send(diagnosticEvent, summary);
|
|
14
71
|
}
|
|
15
72
|
// @runic-artifex/views publishes runtime failures on a page-wide listener set
|
|
16
73
|
// under this registered symbol, so this client needs no dependency on it.
|
|
@@ -26,7 +83,7 @@ function fallbackType(code) {
|
|
|
26
83
|
return "StaleInputWarning";
|
|
27
84
|
return "BridgeError";
|
|
28
85
|
}
|
|
29
|
-
/** Forwards a Views runtime diagnostic to the
|
|
86
|
+
/** Forwards a Views runtime diagnostic to the timeline. */
|
|
30
87
|
function reportViewsDiagnostic(diagnostic) {
|
|
31
88
|
const route = typeof diagnostic.route === "string" ? diagnostic.route.slice(0, 120) : undefined;
|
|
32
89
|
const code = typeof diagnostic.code === "string" ? diagnostic.code.slice(0, 32) : "error";
|
|
@@ -48,17 +105,18 @@ function reportViewsDiagnostic(diagnostic) {
|
|
|
48
105
|
...(error ? { failure: diagnostic.detail ?? { type: fallbackType(code), message } } : {}),
|
|
49
106
|
});
|
|
50
107
|
}
|
|
108
|
+
function viewsDiagnostics() {
|
|
109
|
+
const listeners = host;
|
|
110
|
+
return listeners[viewsDiagnosticsKey] ??= new Set();
|
|
111
|
+
}
|
|
51
112
|
function connectViewsDiagnostics() {
|
|
52
|
-
|
|
53
|
-
return;
|
|
54
|
-
const host = globalThis;
|
|
55
|
-
const listeners = host[viewsDiagnosticsKey] ??= new Set();
|
|
113
|
+
const listeners = viewsDiagnostics();
|
|
56
114
|
// HMR re-evaluates this module; replace the listener of the previous copy.
|
|
57
|
-
const previous =
|
|
115
|
+
const previous = data[viewsListenerKey];
|
|
58
116
|
if (previous)
|
|
59
117
|
listeners.delete(previous);
|
|
60
118
|
listeners.add(reportViewsDiagnostic);
|
|
61
|
-
|
|
119
|
+
data[viewsListenerKey] = reportViewsDiagnostic;
|
|
62
120
|
}
|
|
63
121
|
// @runic-artifex/views publishes the page's connection state on this channel once a View
|
|
64
122
|
// connects, or from page load when this client asks for it with `requested` and `start`
|
|
@@ -66,29 +124,120 @@ function connectViewsDiagnostics() {
|
|
|
66
124
|
const viewsConnectionKey = Symbol.for("runic.views.connection");
|
|
67
125
|
const connectionListenerKey = "runic:connection-listener";
|
|
68
126
|
function reportConnection(state) {
|
|
69
|
-
|
|
127
|
+
send(connectionEvent, { state });
|
|
128
|
+
}
|
|
129
|
+
function viewsConnection() {
|
|
130
|
+
const channels = host;
|
|
131
|
+
return channels[viewsConnectionKey] ??= { listeners: new Set() };
|
|
70
132
|
}
|
|
71
133
|
function connectViewsConnection() {
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
const host = globalThis;
|
|
75
|
-
const channel = host[viewsConnectionKey] ??= { listeners: new Set() };
|
|
76
|
-
const previous = hot.data[connectionListenerKey];
|
|
134
|
+
const connection = viewsConnection();
|
|
135
|
+
const previous = data[connectionListenerKey];
|
|
77
136
|
if (previous)
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
137
|
+
connection.listeners.delete(previous);
|
|
138
|
+
connection.listeners.add(reportConnection);
|
|
139
|
+
data[connectionListenerKey] = reportConnection;
|
|
140
|
+
// The first report also opens the HTTP channel, so it is sent even before a View has a state.
|
|
141
|
+
if (typeof connection.state === "string" || send === post)
|
|
142
|
+
reportConnection(connection.state ?? "unknown");
|
|
83
143
|
// Observe from page load, not only once a View connects: a copy of @runic-artifex/views that
|
|
84
144
|
// loads later sees `requested`, and one that already loaded has set `start`.
|
|
85
|
-
|
|
86
|
-
if (typeof
|
|
87
|
-
|
|
145
|
+
connection.requested = true;
|
|
146
|
+
if (typeof connection.start === "function")
|
|
147
|
+
connection.start();
|
|
148
|
+
}
|
|
149
|
+
// The state inspector. @runic-artifex/views 0.15 or later reports to this channel once a reader set `requested`
|
|
150
|
+
// (specs/application, "Shared globals"): each route's state as its presentations receive it, a closed route, and a
|
|
151
|
+
// command the producer answered `superseded`. The client sends a route's latest state at most every 250 ms.
|
|
152
|
+
const viewsInspectorKey = Symbol.for("runic.views.inspector");
|
|
153
|
+
const inspectorListenerKey = "runic:inspector-listener";
|
|
154
|
+
const pageHideListenerKey = "runic:page-hide-listener";
|
|
155
|
+
const pageKey = "runic:page";
|
|
156
|
+
const stateInterval = 250;
|
|
157
|
+
// Several windows can share one development server, so the server keeps Views per page.
|
|
158
|
+
const page = typeof data[pageKey] === "string" ? data[pageKey] : (data[pageKey] = randomPage());
|
|
159
|
+
const pendingStates = new Map();
|
|
160
|
+
let stateTimer;
|
|
161
|
+
function randomPage() {
|
|
162
|
+
return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`.slice(0, 32);
|
|
163
|
+
}
|
|
164
|
+
function sendStates() {
|
|
165
|
+
stateTimer = undefined;
|
|
166
|
+
for (const event of pendingStates.values()) {
|
|
167
|
+
send(viewEvent, {
|
|
168
|
+
page, route: event.route, revision: event.revision, epoch: event.epoch, presentations: event.presentations,
|
|
169
|
+
// Sanitized here too, so that the state leaves the page bounded and redacted.
|
|
170
|
+
state: sanitizeViewState(event.state),
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
pendingStates.clear();
|
|
174
|
+
}
|
|
175
|
+
function reportInspector(event) {
|
|
176
|
+
if (typeof event !== "object" || event === null || typeof event.route !== "string")
|
|
177
|
+
return;
|
|
178
|
+
if (event.kind === "state") {
|
|
179
|
+
pendingStates.set(event.route, event);
|
|
180
|
+
stateTimer ??= setTimeout(sendStates, stateInterval);
|
|
181
|
+
}
|
|
182
|
+
else if (event.kind === "closed") {
|
|
183
|
+
pendingStates.delete(event.route);
|
|
184
|
+
send(viewEvent, { page, route: event.route, closed: true });
|
|
185
|
+
}
|
|
186
|
+
else if (event.kind === "superseded") {
|
|
187
|
+
// The call resolved like one that ran, so only the timeline shows that nothing ran.
|
|
188
|
+
sendDiagnostic({
|
|
189
|
+
source: "views",
|
|
190
|
+
kind: "command",
|
|
191
|
+
label: `${String(event.member).slice(0, 80)} superseded`,
|
|
192
|
+
detail: {
|
|
193
|
+
code: "superseded", route: event.route.slice(0, 120), member: String(event.member).slice(0, 80),
|
|
194
|
+
...(typeof event.epoch === "number" ? { epoch: event.epoch } : {}),
|
|
195
|
+
...(typeof event.revision === "number" ? { revision: event.revision } : {}),
|
|
196
|
+
},
|
|
197
|
+
});
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
function viewsInspector() {
|
|
201
|
+
const channels = host;
|
|
202
|
+
return channels[viewsInspectorKey] ??= { listeners: new Set() };
|
|
203
|
+
}
|
|
204
|
+
function pageHidden() {
|
|
205
|
+
pendingStates.clear();
|
|
206
|
+
send(viewEvent, { page, closed: true });
|
|
207
|
+
}
|
|
208
|
+
function connectViewsInspector() {
|
|
209
|
+
const inspector = viewsInspector();
|
|
210
|
+
const previous = data[inspectorListenerKey];
|
|
211
|
+
if (previous)
|
|
212
|
+
inspector.listeners.delete(previous);
|
|
213
|
+
inspector.listeners.add(reportInspector);
|
|
214
|
+
data[inspectorListenerKey] = reportInspector;
|
|
215
|
+
inspector.requested = true;
|
|
216
|
+
// The page's Views go away with it; the server also keeps only the 32 most recent.
|
|
217
|
+
const previousHide = data[pageHideListenerKey];
|
|
218
|
+
if (previousHide)
|
|
219
|
+
host.removeEventListener?.("pagehide", previousHide);
|
|
220
|
+
host.addEventListener?.("pagehide", pageHidden);
|
|
221
|
+
data[pageHideListenerKey] = pageHidden;
|
|
222
|
+
}
|
|
223
|
+
// Removes this copy's listeners once the HTTP channel has no server to report to.
|
|
224
|
+
function close() {
|
|
225
|
+
channel = "closed";
|
|
226
|
+
pending.length = 0;
|
|
227
|
+
viewsDiagnostics().delete(reportViewsDiagnostic);
|
|
228
|
+
viewsConnection().listeners.delete(reportConnection);
|
|
229
|
+
viewsInspector().listeners.delete(reportInspector);
|
|
230
|
+
host.removeEventListener?.("pagehide", pageHidden);
|
|
231
|
+
if (stateTimer !== undefined)
|
|
232
|
+
clearTimeout(stateTimer);
|
|
233
|
+
stateTimer = undefined;
|
|
234
|
+
pendingStates.clear();
|
|
88
235
|
}
|
|
89
236
|
connectViewsDiagnostics();
|
|
90
237
|
connectViewsConnection();
|
|
91
|
-
|
|
92
|
-
//
|
|
238
|
+
connectViewsInspector();
|
|
239
|
+
// Vite's HMR context shows that a development server serves the page: install the warning now. Without it
|
|
240
|
+
// (a production build that kept the client), the HTTP channel installs it once the server answers. Installs once
|
|
241
|
+
// per page; HMR re-evaluation leaves it in place.
|
|
93
242
|
if (hot)
|
|
94
243
|
installStaleInputWarning(globalThis);
|
package/dist/dev-session.d.ts
CHANGED
|
@@ -1,17 +1,36 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type { IncomingMessage, ServerResponse } from "node:http";
|
|
2
|
+
import type { ProxyOptions } from "vite";
|
|
3
|
+
import type { RunicDevelopmentState, RunicTimelineEntry } from "./timeline.js";
|
|
2
4
|
export declare const devSessionVariable = "RUNIC_APPLICATION_DEV_SESSION";
|
|
3
5
|
export declare const devSessionHeader = "X-Runic-Dev-Session";
|
|
6
|
+
export declare const statePath = "/__runic/state";
|
|
4
7
|
/** The session value `dotnet runic dev` set, when it has the shape the tool writes: 32 to 128 hex digits. */
|
|
5
8
|
export declare function devSessionValue(value: string | undefined): string | undefined;
|
|
9
|
+
/** Answers `/__runic/state` with the path-free state, and with the `dotnet runic dev` session when there is one. */
|
|
10
|
+
export declare function answerState(response: ServerResponse, state: RunicDevelopmentState, session: string | undefined): void;
|
|
6
11
|
/**
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* answers it. Without `dotnet runic dev` the plugin does nothing.
|
|
12
|
+
* Answers a development client's POST to `/__runic/diagnostics`: `{ "event", "data" }` from the same origin, as JSON
|
|
13
|
+
* of at most `maximumClientMessageBytes`. Calls `deliver` with an accepted message and answers 204.
|
|
10
14
|
*/
|
|
11
|
-
export declare function
|
|
15
|
+
export declare function answerClientMessage(request: IncomingMessage, response: ServerResponse, deliver: (event: string, data: unknown) => void): Promise<void>;
|
|
16
|
+
export interface RunicDevSessionProxyOptions {
|
|
17
|
+
/** How many timeline entries `/__runic/state` keeps: 200 by default, rounded down and limited to 1 to 500. */
|
|
18
|
+
readonly maxTimelineEntries?: number;
|
|
19
|
+
/**
|
|
20
|
+
* `false` stops printing the development client's failures (an `error` entry with its exception type, message and
|
|
21
|
+
* stack) to the development server's terminal. Defaults to `true`.
|
|
22
|
+
*/
|
|
23
|
+
readonly printFailures?: boolean;
|
|
24
|
+
}
|
|
12
25
|
/**
|
|
13
|
-
* Vite proxy entries
|
|
14
|
-
*
|
|
15
|
-
*
|
|
26
|
+
* Vite proxy entries for a development server that takes a Vite proxy configuration but no Vite plugins: the
|
|
27
|
+
* Angular CLI's `proxyConfig`. Spread the result into the proxy configuration. The entries never proxy; they answer:
|
|
28
|
+
*
|
|
29
|
+
* - `/__runic/state` with the path-free development state, and under `dotnet runic dev` with its session;
|
|
30
|
+
* - `/__runic/diagnostics`, which the development client (`@runic-artifex/vite-plugin-runic/client`) posts the
|
|
31
|
+
* page's Views diagnostics, connection state and View states to. The timeline is bounded, and failures go to the
|
|
32
|
+
* terminal.
|
|
16
33
|
*/
|
|
17
|
-
export declare function runicDevSessionProxy(): Record<string, ProxyOptions>;
|
|
34
|
+
export declare function runicDevSessionProxy(options?: RunicDevSessionProxyOptions): Record<string, ProxyOptions>;
|
|
35
|
+
/** A failure for the terminal: the entry's source and label, then the exception type, message and stack. */
|
|
36
|
+
export declare function formatFailure(entry: RunicTimelineEntry): string;
|