@runic-artifex/vite-plugin-runic 0.12.1 → 0.14.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 +107 -25
- package/dist/channel.d.ts +14 -0
- package/dist/channel.js +17 -0
- package/dist/client.js +103 -27
- package/dist/dev-session.d.ts +34 -7
- package/dist/dev-session.js +156 -12
- package/dist/index.d.ts +16 -25
- package/dist/index.js +108 -128
- package/dist/stale-input.d.ts +19 -0
- package/dist/stale-input.js +202 -0
- package/dist/timeline.d.ts +43 -0
- package/dist/timeline.js +69 -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.14.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.
|
|
@@ -47,12 +47,111 @@ 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
|
|
54
58
|
discover it, and Vite would reload the page and close the host's connection.
|
|
55
59
|
|
|
60
|
+
The development client also warns about a text field that loses typed
|
|
61
|
+
characters: when script sets the focused `<input>` or `<textarea>` to a value
|
|
62
|
+
it had before the user's last edit while a Bridge request is in flight, which
|
|
63
|
+
happens when a field is bound with a command per key. It reports a
|
|
64
|
+
`stale-input` Views diagnostic, shown on the timeline and passed to
|
|
65
|
+
`onBridgeDiagnostic` listeners, and logs a console warning, once per field.
|
|
66
|
+
The warning names the field by its `id` or `name`, never its value. Bind text
|
|
67
|
+
fields with the text-field binding of your framework package
|
|
68
|
+
(`injectTextField` in `@runic-artifex/angular`, `useTextField` in
|
|
69
|
+
`@runic-artifex/react`, `vue` or `svelte`) or a setter. Turn the warning off with
|
|
70
|
+
`runic({ staleInputWarning: false })`, or from the page by setting
|
|
71
|
+
`globalThis[Symbol.for("runic.vite.staleInputWarning")] = false`.
|
|
72
|
+
|
|
73
|
+
## SvelteKit and Angular
|
|
74
|
+
|
|
75
|
+
SvelteKit renders its pages itself and warns about every plugin with a
|
|
76
|
+
`transformIndexHtml` hook. Use `runic({ html: false })`: the plugin then has no
|
|
77
|
+
such hook, injects nothing into HTML and leaves host scripts alone, and keeps
|
|
78
|
+
everything else: the timeline, the dock, `/__runic/state` and the dev session.
|
|
79
|
+
The page loads the client from its client hooks:
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
// vite.config.ts
|
|
83
|
+
plugins: [sveltekit({ adapter: runicAdapter() }), runic({ html: false })],
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
// src/hooks.client.ts
|
|
88
|
+
import "@runic-artifex/vite-plugin-runic/client";
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
`html: false` cannot be combined with `desktop`, whose bootstrap is a script
|
|
92
|
+
tag in the HTML: `runic({ html: false, desktop: true })` throws.
|
|
93
|
+
|
|
94
|
+
The Angular CLI's development server loads no Vite plugins, only a proxy
|
|
95
|
+
configuration. `runicDevSessionProxy()` returns Vite proxy entries that answer
|
|
96
|
+
locally and never proxy. Spread it into the file that the serve target's
|
|
97
|
+
`proxyConfig` in `angular.json` names:
|
|
98
|
+
|
|
99
|
+
```js
|
|
100
|
+
// proxy.conf.mjs
|
|
101
|
+
import { runicDevSessionProxy } from "@runic-artifex/vite-plugin-runic";
|
|
102
|
+
|
|
103
|
+
export default { ...runicDevSessionProxy() };
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
and load the client from `main.ts` in development only:
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
// src/main.ts, before bootstrapApplication
|
|
110
|
+
if (typeof ngDevMode === "undefined" || ngDevMode) await import("@runic-artifex/vite-plugin-runic/client");
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
A production build (`optimization` on, the default `production`
|
|
114
|
+
configuration) defines `ngDevMode` as `false`, so the import and the client's
|
|
115
|
+
chunk are left out. `isDevMode()` would keep the chunk in the output, because
|
|
116
|
+
the build cannot evaluate a function call.
|
|
117
|
+
|
|
118
|
+
The entries keep the development state in the `ng serve` process and answer:
|
|
119
|
+
|
|
120
|
+
- `/__runic/state` with that state, as `runic()` does: the connection, the
|
|
121
|
+
timeline without failures, and under `dotnet runic dev` the session header
|
|
122
|
+
([Dev session](#dev-session-and-host-scripts)). The answer is `200` with JSON; without `dotnet runic dev` the
|
|
123
|
+
entry answers too, without the header.
|
|
124
|
+
- `/__runic/diagnostics`, which the client posts its reports to. Each Views
|
|
125
|
+
failure is printed to the `ng serve` terminal with its exception type,
|
|
126
|
+
message and stack:
|
|
127
|
+
|
|
128
|
+
```text
|
|
129
|
+
[runic] views editorSave failed
|
|
130
|
+
System.InvalidOperationException: Disk full.
|
|
131
|
+
at Notes.Editor.Save() in /src/Notes/Editor.cs:line 12
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`runicDevSessionProxy({ maxTimelineEntries, printFailures })` takes the same
|
|
135
|
+
timeline limit as `runic()` and `printFailures: false` to keep the terminal
|
|
136
|
+
quiet. The `stale-input` warning works the same as with `runic()`; turn it off
|
|
137
|
+
from the page with the registered symbol above.
|
|
138
|
+
|
|
139
|
+
### The client's channel
|
|
140
|
+
|
|
141
|
+
Loaded by `runic()`, the client reports over Vite's HMR connection. Loaded
|
|
142
|
+
otherwise, it posts each report as `{ "event", "data" }` JSON to
|
|
143
|
+
`/__runic/diagnostics` on its own origin, one at a time and in order, and keeps
|
|
144
|
+
at most 100 waiting. `runic()` answers that endpoint too. The endpoint accepts
|
|
145
|
+
only a `POST` with `Content-Type: application/json` and an `Origin` of the
|
|
146
|
+
server itself (a cross-site page would need a CORS preflight, which it never
|
|
147
|
+
grants), rejects a `Sec-Fetch-Site` other than `same-origin` and a body over
|
|
148
|
+
64 KiB, and sanitizes every entry like any other timeline entry. If the first
|
|
149
|
+
report gets no `204` answer, the page has no Runic development server, and the
|
|
150
|
+
client stops and removes its listeners. Without Vite's HMR context the client
|
|
151
|
+
installs the `stale-input` warning only after that first answer.
|
|
152
|
+
|
|
153
|
+
## Dev session and host scripts
|
|
154
|
+
|
|
56
155
|
Under `dotnet runic dev`, the Vite process gets a random value for the session
|
|
57
156
|
in `RUNIC_APPLICATION_DEV_SESSION`, and `/__runic/state` answers with it in the
|
|
58
157
|
`X-Runic-Dev-Session` header. Since 0.11, `dev` treats the server as ready
|
|
@@ -62,29 +161,12 @@ Pages and other responses do not carry the header. Use the plugin from the same
|
|
|
62
161
|
release as `dotnet-runic`, because an older plugin does not answer and `dev`
|
|
63
162
|
times out with `RAPPDEV1007`.
|
|
64
163
|
|
|
65
|
-
|
|
66
|
-
`
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
```ts
|
|
72
|
-
plugins: [sveltekit({ adapter: runicAdapter() }), runicDevSession()],
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
- `runicDevSessionProxy()` returns Vite proxy entries, for the Angular CLI,
|
|
76
|
-
which takes a proxy configuration but no Vite plugins. Spread it into the
|
|
77
|
-
file that the serve target's `proxyConfig` in `angular.json` names:
|
|
78
|
-
|
|
79
|
-
```js
|
|
80
|
-
// proxy.conf.mjs
|
|
81
|
-
import { runicDevSessionProxy } from "@runic-artifex/vite-plugin-runic";
|
|
82
|
-
|
|
83
|
-
export default { ...runicDevSessionProxy() };
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
`dotnet runic dev` expects the answer from an Angular frontend whose
|
|
87
|
-
`package.json` declares this package.
|
|
164
|
+
`runicDevSessionProxy()` answers the session for the Angular CLI (above).
|
|
165
|
+
`dotnet runic dev` expects the answer from an Angular frontend whose
|
|
166
|
+
`package.json` declares this package. `runicDevSession()` is a Vite plugin
|
|
167
|
+
that answers only the session, without the development client; SvelteKit
|
|
168
|
+
configurations from before 0.14 use it. It is deprecated in 0.14 and removed
|
|
169
|
+
in 0.15: use `runic({ html: false })` instead.
|
|
88
170
|
|
|
89
171
|
The `runic-app` template's SvelteKit and Angular frontends are set up this way.
|
|
90
172
|
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export declare const diagnosticEvent = "runic:diagnostic";
|
|
2
|
+
export declare const connectionEvent = "runic:connection";
|
|
3
|
+
/** The endpoint a client posts `{ "event", "data" }` to, one message per request, answered with 204. */
|
|
4
|
+
export declare const diagnosticsPath = "/__runic/diagnostics";
|
|
5
|
+
/**
|
|
6
|
+
* The largest request body the endpoint accepts. A sanitized diagnostic with a failure is at most about 12,000
|
|
7
|
+
* characters, so this leaves room for JSON escaping and multibyte text.
|
|
8
|
+
*/
|
|
9
|
+
export declare const maximumClientMessageBytes = 65536;
|
|
10
|
+
/** `{ channel?: "hot" }` on `globalThis`, set by `virtual:runic/client` before the client evaluates. */
|
|
11
|
+
export declare const clientOptionsKey: unique symbol;
|
|
12
|
+
export interface RunicClientOptions {
|
|
13
|
+
readonly channel?: "hot";
|
|
14
|
+
}
|
package/dist/channel.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
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
|
+
export const diagnosticEvent = "runic:diagnostic";
|
|
8
|
+
export const connectionEvent = "runic:connection";
|
|
9
|
+
/** The endpoint a client posts `{ "event", "data" }` to, one message per request, answered with 204. */
|
|
10
|
+
export const diagnosticsPath = "/__runic/diagnostics";
|
|
11
|
+
/**
|
|
12
|
+
* The largest request body the endpoint accepts. A sanitized diagnostic with a failure is at most about 12,000
|
|
13
|
+
* characters, so this leaves room for JSON escaping and multibyte text.
|
|
14
|
+
*/
|
|
15
|
+
export const maximumClientMessageBytes = 65_536;
|
|
16
|
+
/** `{ channel?: "hot" }` on `globalThis`, set by `virtual:runic/client` before the client evaluates. */
|
|
17
|
+
export const clientOptionsKey = Symbol.for("runic.vite.client");
|
package/dist/client.js
CHANGED
|
@@ -1,14 +1,73 @@
|
|
|
1
|
-
|
|
2
|
-
// diagnostics and connection state of `@runic-artifex/views` to the DevTools dock. It has
|
|
3
|
-
// no exports: applications do not import it.
|
|
1
|
+
import { clientOptionsKey, connectionEvent, diagnosticEvent, diagnosticsPath, maximumClientMessageBytes, } from "./channel.js";
|
|
4
2
|
import { sanitizeDiagnosticSummary } from "./diagnostics.js";
|
|
3
|
+
import { installStaleInputWarning } from "./stale-input.js";
|
|
4
|
+
const host = globalThis;
|
|
5
5
|
const hot = import.meta.hot;
|
|
6
|
-
const
|
|
7
|
-
|
|
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;
|
|
8
67
|
function sendDiagnostic(candidate) {
|
|
9
68
|
const summary = sanitizeDiagnosticSummary(candidate);
|
|
10
69
|
if (summary)
|
|
11
|
-
|
|
70
|
+
send(diagnosticEvent, summary);
|
|
12
71
|
}
|
|
13
72
|
// @runic-artifex/views publishes runtime failures on a page-wide listener set
|
|
14
73
|
// under this registered symbol, so this client needs no dependency on it.
|
|
@@ -20,9 +79,11 @@ function fallbackType(code) {
|
|
|
20
79
|
return "Error";
|
|
21
80
|
if (code === "uncertain")
|
|
22
81
|
return "BridgeOperationUncertainError";
|
|
82
|
+
if (code === "stale-input")
|
|
83
|
+
return "StaleInputWarning";
|
|
23
84
|
return "BridgeError";
|
|
24
85
|
}
|
|
25
|
-
/** Forwards a Views runtime diagnostic to the
|
|
86
|
+
/** Forwards a Views runtime diagnostic to the timeline. */
|
|
26
87
|
function reportViewsDiagnostic(diagnostic) {
|
|
27
88
|
const route = typeof diagnostic.route === "string" ? diagnostic.route.slice(0, 120) : undefined;
|
|
28
89
|
const code = typeof diagnostic.code === "string" ? diagnostic.code.slice(0, 32) : "error";
|
|
@@ -44,17 +105,18 @@ function reportViewsDiagnostic(diagnostic) {
|
|
|
44
105
|
...(error ? { failure: diagnostic.detail ?? { type: fallbackType(code), message } } : {}),
|
|
45
106
|
});
|
|
46
107
|
}
|
|
108
|
+
function viewsDiagnostics() {
|
|
109
|
+
const listeners = host;
|
|
110
|
+
return listeners[viewsDiagnosticsKey] ??= new Set();
|
|
111
|
+
}
|
|
47
112
|
function connectViewsDiagnostics() {
|
|
48
|
-
|
|
49
|
-
return;
|
|
50
|
-
const host = globalThis;
|
|
51
|
-
const listeners = host[viewsDiagnosticsKey] ??= new Set();
|
|
113
|
+
const listeners = viewsDiagnostics();
|
|
52
114
|
// HMR re-evaluates this module; replace the listener of the previous copy.
|
|
53
|
-
const previous =
|
|
115
|
+
const previous = data[viewsListenerKey];
|
|
54
116
|
if (previous)
|
|
55
117
|
listeners.delete(previous);
|
|
56
118
|
listeners.add(reportViewsDiagnostic);
|
|
57
|
-
|
|
119
|
+
data[viewsListenerKey] = reportViewsDiagnostic;
|
|
58
120
|
}
|
|
59
121
|
// @runic-artifex/views publishes the page's connection state on this channel once a View
|
|
60
122
|
// connects, or from page load when this client asks for it with `requested` and `start`
|
|
@@ -62,25 +124,39 @@ function connectViewsDiagnostics() {
|
|
|
62
124
|
const viewsConnectionKey = Symbol.for("runic.views.connection");
|
|
63
125
|
const connectionListenerKey = "runic:connection-listener";
|
|
64
126
|
function reportConnection(state) {
|
|
65
|
-
|
|
127
|
+
send(connectionEvent, { state });
|
|
128
|
+
}
|
|
129
|
+
function viewsConnection() {
|
|
130
|
+
const channels = host;
|
|
131
|
+
return channels[viewsConnectionKey] ??= { listeners: new Set() };
|
|
66
132
|
}
|
|
67
133
|
function connectViewsConnection() {
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
const host = globalThis;
|
|
71
|
-
const channel = host[viewsConnectionKey] ??= { listeners: new Set() };
|
|
72
|
-
const previous = hot.data[connectionListenerKey];
|
|
134
|
+
const connection = viewsConnection();
|
|
135
|
+
const previous = data[connectionListenerKey];
|
|
73
136
|
if (previous)
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
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");
|
|
79
143
|
// Observe from page load, not only once a View connects: a copy of @runic-artifex/views that
|
|
80
144
|
// loads later sees `requested`, and one that already loaded has set `start`.
|
|
81
|
-
|
|
82
|
-
if (typeof
|
|
83
|
-
|
|
145
|
+
connection.requested = true;
|
|
146
|
+
if (typeof connection.start === "function")
|
|
147
|
+
connection.start();
|
|
148
|
+
}
|
|
149
|
+
// Removes this copy's listeners once the HTTP channel has no server to report to.
|
|
150
|
+
function close() {
|
|
151
|
+
channel = "closed";
|
|
152
|
+
pending.length = 0;
|
|
153
|
+
viewsDiagnostics().delete(reportViewsDiagnostic);
|
|
154
|
+
viewsConnection().listeners.delete(reportConnection);
|
|
84
155
|
}
|
|
85
156
|
connectViewsDiagnostics();
|
|
86
157
|
connectViewsConnection();
|
|
158
|
+
// Vite's HMR context shows that a development server serves the page: install the warning now. Without it
|
|
159
|
+
// (a production build that kept the client), the HTTP channel installs it once the server answers. Installs once
|
|
160
|
+
// per page; HMR re-evaluation leaves it in place.
|
|
161
|
+
if (hot)
|
|
162
|
+
installStaleInputWarning(globalThis);
|
package/dist/dev-session.d.ts
CHANGED
|
@@ -1,17 +1,44 @@
|
|
|
1
|
+
import type { IncomingMessage, ServerResponse } from "node:http";
|
|
1
2
|
import type { Plugin, 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
|
-
|
|
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.
|
|
14
|
+
*/
|
|
15
|
+
export declare function answerClientMessage(request: IncomingMessage, response: ServerResponse, deliver: (event: string, data: unknown) => void): Promise<void>;
|
|
16
|
+
/**
|
|
17
|
+
* A Vite plugin that only answers `/__runic/state` with the `dotnet runic dev` session. Without `dotnet runic dev`
|
|
18
|
+
* the plugin does nothing.
|
|
19
|
+
*
|
|
20
|
+
* @deprecated Use `runic({ html: false })`, which answers the session too and adds the development client (load it
|
|
21
|
+
* with `import "@runic-artifex/vite-plugin-runic/client"` from SvelteKit's `src/hooks.client.ts`). `runicDevSession`
|
|
22
|
+
* is removed in 0.15.
|
|
10
23
|
*/
|
|
11
24
|
export declare function runicDevSession(): Plugin;
|
|
25
|
+
export interface RunicDevSessionProxyOptions {
|
|
26
|
+
/** How many timeline entries `/__runic/state` keeps: 200 by default, rounded down and limited to 1 to 500. */
|
|
27
|
+
readonly maxTimelineEntries?: number;
|
|
28
|
+
/**
|
|
29
|
+
* `false` stops printing the development client's failures (an `error` entry with its exception type, message and
|
|
30
|
+
* stack) to the development server's terminal. Defaults to `true`.
|
|
31
|
+
*/
|
|
32
|
+
readonly printFailures?: boolean;
|
|
33
|
+
}
|
|
12
34
|
/**
|
|
13
|
-
* Vite proxy entries
|
|
14
|
-
*
|
|
15
|
-
*
|
|
35
|
+
* Vite proxy entries for a development server that takes a Vite proxy configuration but no Vite plugins: the
|
|
36
|
+
* Angular CLI's `proxyConfig`. Spread the result into the proxy configuration. The entries never proxy; they answer:
|
|
37
|
+
*
|
|
38
|
+
* - `/__runic/state` with the path-free development state, and under `dotnet runic dev` with its session;
|
|
39
|
+
* - `/__runic/diagnostics`, which the development client (`@runic-artifex/vite-plugin-runic/client`) posts the
|
|
40
|
+
* page's Views diagnostics and connection state to. The timeline is bounded, and failures go to the terminal.
|
|
16
41
|
*/
|
|
17
|
-
export declare function runicDevSessionProxy(): Record<string, ProxyOptions>;
|
|
42
|
+
export declare function runicDevSessionProxy(options?: RunicDevSessionProxyOptions): Record<string, ProxyOptions>;
|
|
43
|
+
/** A failure for the terminal: the entry's source and label, then the exception type, message and stack. */
|
|
44
|
+
export declare function formatFailure(entry: RunicTimelineEntry): string;
|
package/dist/dev-session.js
CHANGED
|
@@ -1,9 +1,11 @@
|
|
|
1
|
+
import { connectionEvent, diagnosticEvent, diagnosticsPath, maximumClientMessageBytes } from "./channel.js";
|
|
2
|
+
import { createDevelopmentTimeline, initialDevelopmentState, timelineLimit, withoutFailures } from "./timeline.js";
|
|
1
3
|
// `dotnet runic dev` gives the development server process a random session value and accepts the server as ready
|
|
2
4
|
// only when /__runic/state answers with it, so another process that takes the port first is not mistaken for this
|
|
3
5
|
// server.
|
|
4
6
|
export const devSessionVariable = "RUNIC_APPLICATION_DEV_SESSION";
|
|
5
7
|
export const devSessionHeader = "X-Runic-Dev-Session";
|
|
6
|
-
const statePath = "/__runic/state";
|
|
8
|
+
export const statePath = "/__runic/state";
|
|
7
9
|
/** The session value `dotnet runic dev` set, when it has the shape the tool writes: 32 to 128 hex digits. */
|
|
8
10
|
export function devSessionValue(value) {
|
|
9
11
|
return value !== undefined && /^[0-9a-f]{32,128}$/.test(value) ? value : undefined;
|
|
@@ -14,10 +16,113 @@ function answerSession(response, session) {
|
|
|
14
16
|
response.setHeader(devSessionHeader, session);
|
|
15
17
|
response.end();
|
|
16
18
|
}
|
|
19
|
+
/** Answers `/__runic/state` with the path-free state, and with the `dotnet runic dev` session when there is one. */
|
|
20
|
+
export function answerState(response, state, session) {
|
|
21
|
+
response.statusCode = 200;
|
|
22
|
+
response.setHeader("Content-Type", "application/json; charset=utf-8");
|
|
23
|
+
response.setHeader("Cache-Control", "no-store");
|
|
24
|
+
if (session !== undefined)
|
|
25
|
+
response.setHeader(devSessionHeader, session);
|
|
26
|
+
response.end(JSON.stringify(withoutFailures(state)));
|
|
27
|
+
}
|
|
28
|
+
function answerStatus(response, status, headers = {}) {
|
|
29
|
+
if (response.writableEnded)
|
|
30
|
+
return;
|
|
31
|
+
response.statusCode = status;
|
|
32
|
+
response.setHeader("Cache-Control", "no-store");
|
|
33
|
+
for (const [name, value] of Object.entries(headers))
|
|
34
|
+
response.setHeader(name, value);
|
|
35
|
+
response.end();
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Whether a request comes from a page of this server: a browser sends `Origin` with every POST, and a cross-site
|
|
39
|
+
* page that posts JSON needs a CORS preflight, which the endpoint never grants.
|
|
40
|
+
*/
|
|
41
|
+
function sameOrigin(request) {
|
|
42
|
+
const site = request.headers["sec-fetch-site"];
|
|
43
|
+
if (site !== undefined && site !== "same-origin")
|
|
44
|
+
return false;
|
|
45
|
+
const origin = request.headers.origin;
|
|
46
|
+
const host = request.headers.host;
|
|
47
|
+
if (typeof origin !== "string" || typeof host !== "string")
|
|
48
|
+
return false;
|
|
49
|
+
try {
|
|
50
|
+
const url = new URL(origin);
|
|
51
|
+
return (url.protocol === "http:" || url.protocol === "https:") && url.host === host.toLowerCase();
|
|
52
|
+
}
|
|
53
|
+
catch {
|
|
54
|
+
return false;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Answers a development client's POST to `/__runic/diagnostics`: `{ "event", "data" }` from the same origin, as JSON
|
|
59
|
+
* of at most `maximumClientMessageBytes`. Calls `deliver` with an accepted message and answers 204.
|
|
60
|
+
*/
|
|
61
|
+
export async function answerClientMessage(request, response, deliver) {
|
|
62
|
+
if (request.method !== "POST") {
|
|
63
|
+
request.resume();
|
|
64
|
+
return answerStatus(response, 405, { Allow: "POST" });
|
|
65
|
+
}
|
|
66
|
+
if (!sameOrigin(request)) {
|
|
67
|
+
request.resume();
|
|
68
|
+
return answerStatus(response, 403);
|
|
69
|
+
}
|
|
70
|
+
const type = request.headers["content-type"];
|
|
71
|
+
if (typeof type !== "string" || !/^application\/json\s*(?:;|$)/iu.test(type)) {
|
|
72
|
+
request.resume();
|
|
73
|
+
return answerStatus(response, 415);
|
|
74
|
+
}
|
|
75
|
+
const declared = Number(request.headers["content-length"]);
|
|
76
|
+
if (Number.isFinite(declared) && declared > maximumClientMessageBytes) {
|
|
77
|
+
request.resume();
|
|
78
|
+
return answerStatus(response, 413);
|
|
79
|
+
}
|
|
80
|
+
const body = await readBody(request);
|
|
81
|
+
if (body === undefined)
|
|
82
|
+
return answerStatus(response, 413);
|
|
83
|
+
let message;
|
|
84
|
+
try {
|
|
85
|
+
message = JSON.parse(body);
|
|
86
|
+
}
|
|
87
|
+
catch {
|
|
88
|
+
return answerStatus(response, 400);
|
|
89
|
+
}
|
|
90
|
+
if (typeof message !== "object" || message === null || Array.isArray(message))
|
|
91
|
+
return answerStatus(response, 400);
|
|
92
|
+
const { event, data } = message;
|
|
93
|
+
if (event !== diagnosticEvent && event !== connectionEvent)
|
|
94
|
+
return answerStatus(response, 400);
|
|
95
|
+
deliver(event, data);
|
|
96
|
+
answerStatus(response, 204);
|
|
97
|
+
}
|
|
98
|
+
// The body as UTF-8, or undefined once it exceeds the limit; the rest is drained so that the answer reaches the client.
|
|
99
|
+
function readBody(request) {
|
|
100
|
+
return new Promise((resolve) => {
|
|
101
|
+
const chunks = [];
|
|
102
|
+
let size = 0;
|
|
103
|
+
let exceeded = false;
|
|
104
|
+
request.on("data", (chunk) => {
|
|
105
|
+
if (exceeded)
|
|
106
|
+
return;
|
|
107
|
+
size += chunk.byteLength;
|
|
108
|
+
if (size > maximumClientMessageBytes) {
|
|
109
|
+
exceeded = true;
|
|
110
|
+
chunks.length = 0;
|
|
111
|
+
return;
|
|
112
|
+
}
|
|
113
|
+
chunks.push(chunk);
|
|
114
|
+
});
|
|
115
|
+
request.on("end", () => resolve(exceeded ? undefined : Buffer.concat(chunks).toString("utf8")));
|
|
116
|
+
request.on("error", () => resolve(undefined));
|
|
117
|
+
});
|
|
118
|
+
}
|
|
17
119
|
/**
|
|
18
|
-
* A Vite plugin that only answers `/__runic/state` with the `dotnet runic dev` session
|
|
19
|
-
*
|
|
20
|
-
*
|
|
120
|
+
* A Vite plugin that only answers `/__runic/state` with the `dotnet runic dev` session. Without `dotnet runic dev`
|
|
121
|
+
* the plugin does nothing.
|
|
122
|
+
*
|
|
123
|
+
* @deprecated Use `runic({ html: false })`, which answers the session too and adds the development client (load it
|
|
124
|
+
* with `import "@runic-artifex/vite-plugin-runic/client"` from SvelteKit's `src/hooks.client.ts`). `runicDevSession`
|
|
125
|
+
* is removed in 0.15.
|
|
21
126
|
*/
|
|
22
127
|
export function runicDevSession() {
|
|
23
128
|
return {
|
|
@@ -31,23 +136,62 @@ export function runicDevSession() {
|
|
|
31
136
|
};
|
|
32
137
|
}
|
|
33
138
|
/**
|
|
34
|
-
* Vite proxy entries
|
|
35
|
-
*
|
|
36
|
-
*
|
|
139
|
+
* Vite proxy entries for a development server that takes a Vite proxy configuration but no Vite plugins: the
|
|
140
|
+
* Angular CLI's `proxyConfig`. Spread the result into the proxy configuration. The entries never proxy; they answer:
|
|
141
|
+
*
|
|
142
|
+
* - `/__runic/state` with the path-free development state, and under `dotnet runic dev` with its session;
|
|
143
|
+
* - `/__runic/diagnostics`, which the development client (`@runic-artifex/vite-plugin-runic/client`) posts the
|
|
144
|
+
* page's Views diagnostics and connection state to. The timeline is bounded, and failures go to the terminal.
|
|
37
145
|
*/
|
|
38
|
-
export function runicDevSessionProxy() {
|
|
146
|
+
export function runicDevSessionProxy(options = {}) {
|
|
147
|
+
if (options.printFailures !== undefined && typeof options.printFailures !== "boolean") {
|
|
148
|
+
throw new TypeError("printFailures must be true or false.");
|
|
149
|
+
}
|
|
39
150
|
const session = devSessionValue(process.env[devSessionVariable]);
|
|
40
|
-
|
|
41
|
-
|
|
151
|
+
const printFailures = options.printFailures !== false;
|
|
152
|
+
const timeline = createDevelopmentTimeline(initialDevelopmentState(undefined, { command: "serve", mode: "development", root: process.cwd() }), timelineLimit(options.maxTimelineEntries), () => undefined);
|
|
153
|
+
const deliver = (event, data) => {
|
|
154
|
+
if (event === connectionEvent) {
|
|
155
|
+
timeline.applyConnection(data);
|
|
156
|
+
return;
|
|
157
|
+
}
|
|
158
|
+
const entry = timeline.appendDiagnostic(data);
|
|
159
|
+
if (entry?.failure && printFailures)
|
|
160
|
+
console.warn(formatFailure(entry));
|
|
161
|
+
};
|
|
42
162
|
return {
|
|
43
163
|
"^/__runic/state(?:[/?#]|$)": {
|
|
44
|
-
// The
|
|
164
|
+
// The entries answer in bypass and return the URL; Vite then sees the ended response and stops.
|
|
45
165
|
bypass(request, response) {
|
|
46
166
|
if (response === undefined)
|
|
47
167
|
return false;
|
|
48
|
-
|
|
168
|
+
request.resume();
|
|
169
|
+
answerState(response, timeline.state, session);
|
|
49
170
|
return request.url ?? statePath;
|
|
50
171
|
},
|
|
51
172
|
},
|
|
173
|
+
[`^${diagnosticsPath}(?:[/?#]|$)`]: {
|
|
174
|
+
async bypass(request, response) {
|
|
175
|
+
if (response === undefined)
|
|
176
|
+
return false;
|
|
177
|
+
await answerClientMessage(request, response, deliver);
|
|
178
|
+
return request.url ?? diagnosticsPath;
|
|
179
|
+
},
|
|
180
|
+
},
|
|
52
181
|
};
|
|
53
182
|
}
|
|
183
|
+
/** A failure for the terminal: the entry's source and label, then the exception type, message and stack. */
|
|
184
|
+
export function formatFailure(entry) {
|
|
185
|
+
const failure = entry.failure;
|
|
186
|
+
const lines = [`[runic] ${entry.source ?? "runic"} ${entry.label}`];
|
|
187
|
+
if (failure) {
|
|
188
|
+
const heading = `${failure.type}: ${failure.message}`;
|
|
189
|
+
lines.push(` ${heading}`);
|
|
190
|
+
// A .NET stack often starts with the same line.
|
|
191
|
+
const stack = failure.stack?.split("\n") ?? [];
|
|
192
|
+
if (stack[0]?.trim() === heading)
|
|
193
|
+
stack.shift();
|
|
194
|
+
lines.push(...stack.map((line) => ` ${line.trim()}`));
|
|
195
|
+
}
|
|
196
|
+
return lines.join("\n");
|
|
197
|
+
}
|