@runic-artifex/vite-plugin-runic 0.13.0 → 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 +94 -25
- package/dist/channel.d.ts +14 -0
- package/dist/channel.js +17 -0
- package/dist/client.js +98 -30
- package/dist/dev-session.d.ts +34 -7
- package/dist/dev-session.js +156 -12
- package/dist/index.d.ts +10 -25
- package/dist/index.js +104 -139
- package/dist/stale-input.js +2 -1
- 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,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,88 @@ 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
|
+
## 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
|
+
|
|
69
155
|
Under `dotnet runic dev`, the Vite process gets a random value for the session
|
|
70
156
|
in `RUNIC_APPLICATION_DEV_SESSION`, and `/__runic/state` answers with it in the
|
|
71
157
|
`X-Runic-Dev-Session` header. Since 0.11, `dev` treats the server as ready
|
|
@@ -75,29 +161,12 @@ Pages and other responses do not carry the header. Use the plugin from the same
|
|
|
75
161
|
release as `dotnet-runic`, because an older plugin does not answer and `dev`
|
|
76
162
|
times out with `RAPPDEV1007`.
|
|
77
163
|
|
|
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.
|
|
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.
|
|
101
170
|
|
|
102
171
|
The `runic-app` template's SvelteKit and Angular frontends are set up this way.
|
|
103
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,16 +1,73 @@
|
|
|
1
|
-
|
|
2
|
-
// diagnostics and connection state of `@runic-artifex/views` to the DevTools dock and warns
|
|
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.
|
|
1
|
+
import { clientOptionsKey, connectionEvent, diagnosticEvent, diagnosticsPath, maximumClientMessageBytes, } from "./channel.js";
|
|
5
2
|
import { sanitizeDiagnosticSummary } 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,39 @@ 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
|
+
// 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);
|
|
88
155
|
}
|
|
89
156
|
connectViewsDiagnostics();
|
|
90
157
|
connectViewsConnection();
|
|
91
|
-
//
|
|
92
|
-
//
|
|
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.
|
|
93
161
|
if (hot)
|
|
94
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
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import type { Plugin } from "vite";
|
|
2
|
-
import type { RunicDiagnosticEntry
|
|
2
|
+
import type { RunicDiagnosticEntry } from "./diagnostics.js";
|
|
3
3
|
export { runicDevSession, runicDevSessionProxy } from "./dev-session.js";
|
|
4
|
+
export type { RunicDevSessionProxyOptions } from "./dev-session.js";
|
|
5
|
+
export type { RunicDevelopmentState } from "./timeline.js";
|
|
4
6
|
export type { RunicDiagnosticDetail, RunicDiagnosticDetailValue, RunicDiagnosticFailure, RunicDiagnosticEntry, RunicDiagnosticSource, RunicTraceKind, } from "./diagnostics.js";
|
|
5
7
|
/** The API another Vite plugin reaches through `plugin.api`, Vite's inter-plugin convention. */
|
|
6
8
|
export interface RunicVitePluginApi {
|
|
@@ -29,34 +31,17 @@ export interface RunicViteOptions {
|
|
|
29
31
|
* is in flight. Defaults to `true`.
|
|
30
32
|
*/
|
|
31
33
|
readonly staleInputWarning?: boolean;
|
|
34
|
+
/**
|
|
35
|
+
* `false` leaves HTML alone: the plugin has no `transformIndexHtml` hook, which SvelteKit warns about, injects
|
|
36
|
+
* neither the development client nor the Desktop bootstrap, and does not rewrite host scripts. The page loads the
|
|
37
|
+
* client itself with `import "@runic-artifex/vite-plugin-runic/client"`, which the plugin serves while serving and
|
|
38
|
+
* replaces with an empty module in the build. Cannot be combined with `desktop`. Defaults to `true`.
|
|
39
|
+
*/
|
|
40
|
+
readonly html?: boolean;
|
|
32
41
|
/** Injects the Runic Desktop bootstrap without taking ownership of Vite or HMR. */
|
|
33
42
|
readonly desktop?: boolean | Readonly<{
|
|
34
43
|
/** Absolute development bootstrap URL; production uses the surface-relative default. */
|
|
35
44
|
bootstrapUrl?: string;
|
|
36
45
|
}>;
|
|
37
46
|
}
|
|
38
|
-
export interface RunicDevelopmentState {
|
|
39
|
-
readonly contract: Readonly<{
|
|
40
|
-
identity: string;
|
|
41
|
-
version: string;
|
|
42
|
-
fingerprint: string;
|
|
43
|
-
}>;
|
|
44
|
-
readonly vite: Readonly<{
|
|
45
|
-
command: string;
|
|
46
|
-
mode: string;
|
|
47
|
-
root: string;
|
|
48
|
-
}>;
|
|
49
|
-
/**
|
|
50
|
-
* The page's connection to its .NET host, as `@runic-artifex/views` reports it
|
|
51
|
-
* (`BridgeConnectionState`), or `unknown` until a View connects.
|
|
52
|
-
*/
|
|
53
|
-
readonly connection: Readonly<{
|
|
54
|
-
state: "connecting" | "connected" | "reconnecting" | "lost" | "unknown";
|
|
55
|
-
}>;
|
|
56
|
-
readonly timeline: readonly Readonly<Required<Pick<RunicDiagnosticEntry, "id" | "timestamp" | "kind" | "label">> & {
|
|
57
|
-
source?: RunicDiagnosticSource;
|
|
58
|
-
detail: RunicDiagnosticDetail;
|
|
59
|
-
failure?: RunicDiagnosticFailure;
|
|
60
|
-
}>[];
|
|
61
|
-
}
|
|
62
47
|
export declare function runic(options?: RunicViteOptions): RunicVitePlugin;
|
package/dist/index.js
CHANGED
|
@@ -1,62 +1,79 @@
|
|
|
1
1
|
/// <reference types="@vitejs/devtools-kit" />
|
|
2
2
|
import { isAbsolute, relative } from "node:path";
|
|
3
|
-
import { sanitizeDiagnosticSummary } from "./diagnostics.js";
|
|
4
3
|
import { rewriteHostScripts, webRootPrefix } from "./host-scripts.js";
|
|
5
|
-
import {
|
|
4
|
+
import { clientOptionsKey, connectionEvent, diagnosticEvent, diagnosticsPath } from "./channel.js";
|
|
5
|
+
import { answerClientMessage, answerState, devSessionValue, devSessionVariable, statePath } from "./dev-session.js";
|
|
6
|
+
import { createDevelopmentTimeline, initialDevelopmentState, timelineLimit, withoutFailures } from "./timeline.js";
|
|
6
7
|
export { runicDevSession, runicDevSessionProxy } from "./dev-session.js";
|
|
7
8
|
const virtualClientId = "virtual:runic/client";
|
|
8
9
|
const resolvedVirtualClientId = `\0${virtualClientId}`;
|
|
9
10
|
const clientPackageId = "@runic-artifex/vite-plugin-runic/client";
|
|
10
|
-
//
|
|
11
|
-
// client is hoisted above any statement in the virtual client module.
|
|
12
|
-
const
|
|
13
|
-
const
|
|
11
|
+
// Sets the client's options (the HMR channel, the `stale-input` warning) on `globalThis`. A separate module, because
|
|
12
|
+
// the import of the client is hoisted above any statement in the virtual client module.
|
|
13
|
+
const clientOptionsId = "virtual:runic/client-options";
|
|
14
|
+
const resolvedClientOptionsId = `\0${clientOptionsId}`;
|
|
15
|
+
// What an import of the client resolves to where it must not run: the build, the server, `devtools: false`.
|
|
16
|
+
const resolvedEmptyClientId = "\0virtual:runic/client-disabled";
|
|
14
17
|
const stateEvent = "runic:state";
|
|
15
|
-
const diagnosticEvent = "runic:diagnostic";
|
|
16
|
-
const connectionEvent = "runic:connection";
|
|
17
18
|
const stateKey = "runic:state";
|
|
18
|
-
const defaultTimelineLimit = 200;
|
|
19
|
-
const maximumTimelineLimit = 500;
|
|
20
19
|
export function runic(options = {}) {
|
|
21
20
|
const maxTimelineEntries = timelineLimit(options.maxTimelineEntries);
|
|
22
21
|
if (options.staleInputWarning !== undefined && typeof options.staleInputWarning !== "boolean") {
|
|
23
22
|
throw new TypeError("staleInputWarning must be true or false.");
|
|
24
23
|
}
|
|
24
|
+
if (options.html !== undefined && typeof options.html !== "boolean") {
|
|
25
|
+
throw new TypeError("html must be true or false.");
|
|
26
|
+
}
|
|
27
|
+
const html = options.html !== false;
|
|
28
|
+
const client = options.devtools !== false;
|
|
25
29
|
let server;
|
|
26
30
|
let sharedState;
|
|
27
31
|
let jsonRenderer;
|
|
28
|
-
let state = initialState(options);
|
|
29
|
-
let nextDiagnosticSequence = 1;
|
|
30
32
|
let resolvedRoot = process.cwd();
|
|
31
33
|
let base = "/";
|
|
32
34
|
const desktopBootstrapUrl = resolveDesktopBootstrapUrl(options.desktop);
|
|
33
|
-
|
|
35
|
+
if (!html && desktopBootstrapUrl !== undefined) {
|
|
36
|
+
throw new TypeError("desktop requires html: true: the Desktop bootstrap is a script tag the plugin adds to the HTML.");
|
|
37
|
+
}
|
|
38
|
+
const timeline = createDevelopmentTimeline(initialDevelopmentState(options.contract), maxTimelineEntries, (state) => {
|
|
34
39
|
sharedState?.mutate((draft) => Object.assign(draft, structuredClone(state)));
|
|
35
40
|
void jsonRenderer?.updateSpec(createDevtoolsSpec(state));
|
|
36
41
|
server?.ws.send({ type: "custom", event: stateEvent, data: state });
|
|
42
|
+
});
|
|
43
|
+
const deliver = (event, data) => {
|
|
44
|
+
if (event === connectionEvent)
|
|
45
|
+
timeline.applyConnection(data);
|
|
46
|
+
else if (event === diagnosticEvent)
|
|
47
|
+
timeline.appendDiagnostic(data);
|
|
37
48
|
};
|
|
38
|
-
const
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
49
|
+
const command = () => timeline.state.vite.command;
|
|
50
|
+
const transformIndexHtml = {
|
|
51
|
+
order: "post",
|
|
52
|
+
handler: (document, context) => {
|
|
53
|
+
const prefix = webRootPrefix(context.path);
|
|
54
|
+
const tags = [
|
|
55
|
+
...(desktopBootstrapUrl === undefined ? [] : [{
|
|
56
|
+
tag: "script",
|
|
57
|
+
attrs: {
|
|
58
|
+
src: command() === "build" || desktopBootstrapUrl === "./runic-desktop.js"
|
|
59
|
+
? `${prefix}runic-desktop.js`
|
|
60
|
+
: desktopBootstrapUrl,
|
|
61
|
+
},
|
|
62
|
+
injectTo: "head-prepend",
|
|
63
|
+
}]),
|
|
64
|
+
// The development client forwards Views runtime failures to the
|
|
65
|
+
// timeline. It loads before application modules, so a missing Bridge
|
|
66
|
+
// at startup is reported too.
|
|
67
|
+
...(command() !== "serve" || !client ? [] : [{
|
|
68
|
+
tag: "script",
|
|
69
|
+
attrs: { type: "module", src: `${base}@id/${virtualClientId}` },
|
|
70
|
+
injectTo: "head",
|
|
71
|
+
}]),
|
|
72
|
+
];
|
|
73
|
+
return command() === "serve"
|
|
74
|
+
? { html: rewriteHostScripts(document, context.path, false), tags }
|
|
75
|
+
: tags;
|
|
76
|
+
},
|
|
60
77
|
};
|
|
61
78
|
return {
|
|
62
79
|
name: "runic",
|
|
@@ -67,7 +84,7 @@ export function runic(options = {}) {
|
|
|
67
84
|
// which the dependency scanner cannot see. Pre-bundling it up front
|
|
68
85
|
// keeps a cold optimizer cache from discovering it on the first page
|
|
69
86
|
// load and reloading the page, which drops a host's Bridge connection.
|
|
70
|
-
return
|
|
87
|
+
return client ? { optimizeDeps: { include: [clientPackageId] } } : undefined;
|
|
71
88
|
}
|
|
72
89
|
if (desktopBootstrapUrl === undefined)
|
|
73
90
|
return undefined;
|
|
@@ -76,49 +93,25 @@ export function runic(options = {}) {
|
|
|
76
93
|
}
|
|
77
94
|
return { base: "./" };
|
|
78
95
|
},
|
|
79
|
-
//
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
96
|
+
// With html: false there is no transformIndexHtml property at all: SvelteKit warns about any plugin that has one.
|
|
97
|
+
...(html ? {
|
|
98
|
+
// The build parses HTML in a later transform, so host scripts are marked
|
|
99
|
+
// vite-ignore here; the dev server has no such pass and uses the hook below.
|
|
100
|
+
transform: {
|
|
101
|
+
filter: { id: /\.html$/ },
|
|
102
|
+
handler(code, id) {
|
|
103
|
+
if (command() !== "build" || !id.endsWith(".html"))
|
|
104
|
+
return undefined;
|
|
105
|
+
const documentPath = relative(resolvedRoot, id);
|
|
106
|
+
if (documentPath.startsWith("..") || isAbsolute(documentPath))
|
|
107
|
+
return undefined;
|
|
108
|
+
const rewritten = rewriteHostScripts(code, documentPath, true);
|
|
109
|
+
return rewritten === code ? undefined : { code: rewritten, map: null };
|
|
110
|
+
},
|
|
91
111
|
},
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
handler: (html, context) => {
|
|
96
|
-
const prefix = webRootPrefix(context.path);
|
|
97
|
-
const tags = [
|
|
98
|
-
...(desktopBootstrapUrl === undefined ? [] : [{
|
|
99
|
-
tag: "script",
|
|
100
|
-
attrs: {
|
|
101
|
-
src: state.vite.command === "build" || desktopBootstrapUrl === "./runic-desktop.js"
|
|
102
|
-
? `${prefix}runic-desktop.js`
|
|
103
|
-
: desktopBootstrapUrl,
|
|
104
|
-
},
|
|
105
|
-
injectTo: "head-prepend",
|
|
106
|
-
}]),
|
|
107
|
-
// The development client forwards Views runtime failures to the
|
|
108
|
-
// timeline. It loads before application modules, so a missing Bridge
|
|
109
|
-
// at startup is reported too.
|
|
110
|
-
...(state.vite.command !== "serve" || options.devtools === false ? [] : [{
|
|
111
|
-
tag: "script",
|
|
112
|
-
attrs: { type: "module", src: `${base}@id/${virtualClientId}` },
|
|
113
|
-
injectTo: "head",
|
|
114
|
-
}]),
|
|
115
|
-
];
|
|
116
|
-
return state.vite.command === "serve"
|
|
117
|
-
? { html: rewriteHostScripts(html, context.path, false), tags }
|
|
118
|
-
: tags;
|
|
119
|
-
},
|
|
120
|
-
},
|
|
121
|
-
api: { reportDiagnostic: (entry) => appendDiagnostic(entry) },
|
|
112
|
+
transformIndexHtml,
|
|
113
|
+
} : {}),
|
|
114
|
+
api: { reportDiagnostic: (entry) => { timeline.appendDiagnostic(entry); } },
|
|
122
115
|
configResolved(resolved) {
|
|
123
116
|
if (resolved.command === "build" && desktopBootstrapUrl !== undefined && resolved.base !== "./") {
|
|
124
117
|
throw new TypeError("desktop: true requires the resolved Vite base to be './' for relocatable surface output.");
|
|
@@ -130,50 +123,58 @@ export function runic(options = {}) {
|
|
|
130
123
|
resolvedRoot = resolved.root;
|
|
131
124
|
const configuredBase = resolved.base || "/";
|
|
132
125
|
base = configuredBase.endsWith("/") ? configuredBase : `${configuredBase}/`;
|
|
133
|
-
state
|
|
126
|
+
timeline.configure((state) => ({
|
|
134
127
|
...state,
|
|
135
128
|
vite: { command: resolved.command, mode: resolved.mode, root: resolved.root },
|
|
136
|
-
};
|
|
129
|
+
}));
|
|
137
130
|
},
|
|
138
131
|
async configureServer(viteServer) {
|
|
139
132
|
server = viteServer;
|
|
140
|
-
viteServer.ws.on(connectionEvent, (payload) =>
|
|
141
|
-
viteServer.ws.on(diagnosticEvent, (payload) =>
|
|
133
|
+
viteServer.ws.on(connectionEvent, (payload) => deliver(connectionEvent, payload));
|
|
134
|
+
viteServer.ws.on(diagnosticEvent, (payload) => deliver(diagnosticEvent, payload));
|
|
142
135
|
const devSession = devSessionValue(process.env[devSessionVariable]);
|
|
143
|
-
viteServer.middlewares.use(
|
|
144
|
-
response.
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
response.end(JSON.stringify(withoutFailures(state)));
|
|
136
|
+
viteServer.middlewares.use(statePath, (_request, response) => {
|
|
137
|
+
answerState(response, timeline.state, devSession);
|
|
138
|
+
});
|
|
139
|
+
// A client that the page loads without the HMR channel posts here (channel.ts).
|
|
140
|
+
viteServer.middlewares.use(diagnosticsPath, (request, response, next) => {
|
|
141
|
+
answerClientMessage(request, response, deliver).catch(next);
|
|
150
142
|
});
|
|
151
143
|
viteServer.httpServer?.once("close", () => {
|
|
152
144
|
server = undefined;
|
|
153
145
|
});
|
|
154
146
|
},
|
|
155
|
-
resolveId(id) {
|
|
156
|
-
if (id === virtualClientId)
|
|
157
|
-
|
|
158
|
-
|
|
147
|
+
resolveId(id, importer, resolveOptions) {
|
|
148
|
+
if (id === virtualClientId || (id === clientPackageId && importer !== resolvedVirtualClientId)) {
|
|
149
|
+
// The client runs only in a served page. An application import of the package goes through the virtual
|
|
150
|
+
// module too, so that it takes this plugin's options and channel, and is empty in the build.
|
|
151
|
+
const served = client && command() === "serve" && resolveOptions?.ssr !== true &&
|
|
152
|
+
this.environment?.config.consumer !== "server";
|
|
153
|
+
return served ? resolvedVirtualClientId : resolvedEmptyClientId;
|
|
154
|
+
}
|
|
155
|
+
return id === clientOptionsId ? resolvedClientOptionsId : undefined;
|
|
159
156
|
},
|
|
160
157
|
load(id) {
|
|
161
|
-
if (id ===
|
|
162
|
-
return
|
|
158
|
+
if (id === resolvedEmptyClientId)
|
|
159
|
+
return "export {};";
|
|
160
|
+
if (id === resolvedClientOptionsId) {
|
|
161
|
+
const statements = [`globalThis[Symbol.for(${JSON.stringify(clientOptionsKey.description)})] = { channel: "hot" };`];
|
|
162
|
+
if (options.staleInputWarning === false) {
|
|
163
|
+
statements.push(`globalThis[Symbol.for("runic.vite.staleInputWarning")] = false;`);
|
|
164
|
+
}
|
|
165
|
+
return statements.join("\n");
|
|
163
166
|
}
|
|
164
167
|
if (id !== resolvedVirtualClientId)
|
|
165
168
|
return undefined;
|
|
166
|
-
// Imports evaluate in order, so the
|
|
167
|
-
return
|
|
168
|
-
? `import ${JSON.stringify(staleInputOffId)};\nimport ${JSON.stringify(clientPackageId)};`
|
|
169
|
-
: `import ${JSON.stringify(clientPackageId)};`;
|
|
169
|
+
// Imports evaluate in order, so the options are set before the client reads them.
|
|
170
|
+
return `import ${JSON.stringify(clientOptionsId)};\nimport ${JSON.stringify(clientPackageId)};`;
|
|
170
171
|
},
|
|
171
172
|
devtools: {
|
|
172
173
|
async setup(context) {
|
|
173
|
-
if (
|
|
174
|
+
if (!client)
|
|
174
175
|
return;
|
|
175
|
-
sharedState = await context.rpc.sharedState.get(stateKey, { initialValue: state });
|
|
176
|
-
const renderer = context.createJsonRenderer(createDevtoolsSpec(state));
|
|
176
|
+
sharedState = await context.rpc.sharedState.get(stateKey, { initialValue: timeline.state });
|
|
177
|
+
const renderer = context.createJsonRenderer(createDevtoolsSpec(timeline.state));
|
|
177
178
|
jsonRenderer = renderer;
|
|
178
179
|
context.docks.register({
|
|
179
180
|
id: "runic:overview",
|
|
@@ -185,7 +186,7 @@ export function runic(options = {}) {
|
|
|
185
186
|
context.commands.register({
|
|
186
187
|
id: "runic:copy-diagnostic-state",
|
|
187
188
|
title: "Runic: Copy sanitized diagnostic state",
|
|
188
|
-
handler: () => JSON.stringify(withoutFailures(state), null, 2),
|
|
189
|
+
handler: () => JSON.stringify(withoutFailures(timeline.state), null, 2),
|
|
189
190
|
});
|
|
190
191
|
},
|
|
191
192
|
},
|
|
@@ -211,18 +212,6 @@ function resolveDesktopBootstrapUrl(options) {
|
|
|
211
212
|
}
|
|
212
213
|
return url.href;
|
|
213
214
|
}
|
|
214
|
-
function initialState(options) {
|
|
215
|
-
return {
|
|
216
|
-
contract: {
|
|
217
|
-
identity: cleanString(options.contract?.identity),
|
|
218
|
-
version: cleanString(options.contract?.version),
|
|
219
|
-
fingerprint: cleanString(options.contract?.fingerprint),
|
|
220
|
-
},
|
|
221
|
-
vite: { command: "serve", mode: "development", root: "" },
|
|
222
|
-
connection: { state: "unknown" },
|
|
223
|
-
timeline: [],
|
|
224
|
-
};
|
|
225
|
-
}
|
|
226
215
|
function createDevtoolsSpec(current) {
|
|
227
216
|
const section = (id, title, data) => ({
|
|
228
217
|
[id]: { type: "Card", props: { title }, children: [`${id}-data`] },
|
|
@@ -254,14 +243,6 @@ function createDevtoolsSpec(current) {
|
|
|
254
243
|
},
|
|
255
244
|
};
|
|
256
245
|
}
|
|
257
|
-
// Failures keep file paths and stacks for the local dock only. The state
|
|
258
|
-
// endpoint and the copied state stay path-free.
|
|
259
|
-
function withoutFailures(current) {
|
|
260
|
-
return {
|
|
261
|
-
...current,
|
|
262
|
-
timeline: current.timeline.map(({ failure: _failure, ...entry }) => entry),
|
|
263
|
-
};
|
|
264
|
-
}
|
|
265
246
|
function lastFailure(current) {
|
|
266
247
|
const entry = [...current.timeline].reverse().find((candidate) => candidate.failure !== undefined);
|
|
267
248
|
if (!entry?.failure)
|
|
@@ -274,19 +255,3 @@ function lastFailure(current) {
|
|
|
274
255
|
...(entry.failure.stack ? { Stack: entry.failure.stack } : {}),
|
|
275
256
|
};
|
|
276
257
|
}
|
|
277
|
-
function connectionState(value) {
|
|
278
|
-
return value === "connecting" || value === "connected" || value === "reconnecting" || value === "lost"
|
|
279
|
-
? value
|
|
280
|
-
: "unknown";
|
|
281
|
-
}
|
|
282
|
-
function timelineLimit(value) {
|
|
283
|
-
if (typeof value !== "number" || !Number.isFinite(value))
|
|
284
|
-
return defaultTimelineLimit;
|
|
285
|
-
return Math.min(maximumTimelineLimit, Math.max(1, Math.floor(value)));
|
|
286
|
-
}
|
|
287
|
-
function cleanString(value) {
|
|
288
|
-
return typeof value === "string" ? value.slice(0, 512) : "";
|
|
289
|
-
}
|
|
290
|
-
function isRecord(value) {
|
|
291
|
-
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
292
|
-
}
|
package/dist/stale-input.js
CHANGED
|
@@ -34,7 +34,8 @@ export const staleInputMessage = "to a value it had before the user's last edit
|
|
|
34
34
|
"typed characters. Bind text inputs with the text-field binding of your framework package " +
|
|
35
35
|
"(`injectTextField` in @runic-artifex/angular, `useTextField` in @runic-artifex/react, vue or svelte) " +
|
|
36
36
|
"or a setter instead of a command per key. This warning comes from @runic-artifex/vite-plugin-runic " +
|
|
37
|
-
"in development; turn it off with runic({ staleInputWarning: false })
|
|
37
|
+
"in development; turn it off with runic({ staleInputWarning: false }) or, without runic(), by setting " +
|
|
38
|
+
"globalThis[Symbol.for(\"runic.vite.staleInputWarning\")] = false.";
|
|
38
39
|
/**
|
|
39
40
|
* Installs the warning on `host` (normally `globalThis`) once. Does nothing without a DOM,
|
|
40
41
|
* when it is already installed, or when `host[staleInputWarningKey]` is `false`.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import type { RunicDiagnosticDetail, RunicDiagnosticEntry, RunicDiagnosticFailure, RunicDiagnosticSource } from "./diagnostics.js";
|
|
2
|
+
export interface RunicDevelopmentState {
|
|
3
|
+
readonly contract: Readonly<{
|
|
4
|
+
identity: string;
|
|
5
|
+
version: string;
|
|
6
|
+
fingerprint: string;
|
|
7
|
+
}>;
|
|
8
|
+
readonly vite: Readonly<{
|
|
9
|
+
command: string;
|
|
10
|
+
mode: string;
|
|
11
|
+
root: string;
|
|
12
|
+
}>;
|
|
13
|
+
/**
|
|
14
|
+
* The page's connection to its .NET host, as `@runic-artifex/views` reports it
|
|
15
|
+
* (`BridgeConnectionState`), or `unknown` until a View connects.
|
|
16
|
+
*/
|
|
17
|
+
readonly connection: Readonly<{
|
|
18
|
+
state: "connecting" | "connected" | "reconnecting" | "lost" | "unknown";
|
|
19
|
+
}>;
|
|
20
|
+
readonly timeline: readonly RunicTimelineEntry[];
|
|
21
|
+
}
|
|
22
|
+
export type RunicTimelineEntry = Readonly<Required<Pick<RunicDiagnosticEntry, "id" | "timestamp" | "kind" | "label">> & {
|
|
23
|
+
source?: RunicDiagnosticSource;
|
|
24
|
+
detail: RunicDiagnosticDetail;
|
|
25
|
+
failure?: RunicDiagnosticFailure;
|
|
26
|
+
}>;
|
|
27
|
+
export interface DevelopmentTimeline {
|
|
28
|
+
readonly state: RunicDevelopmentState;
|
|
29
|
+
/** Replaces the state without notifying, for configuration such as the resolved Vite command. */
|
|
30
|
+
configure(update: (current: RunicDevelopmentState) => RunicDevelopmentState): void;
|
|
31
|
+
/** Sanitizes and appends an entry; returns it, or `undefined` for a candidate that is not a diagnostic. */
|
|
32
|
+
appendDiagnostic(candidate: unknown, defaultSource?: RunicDiagnosticSource): RunicTimelineEntry | undefined;
|
|
33
|
+
/** Applies a `{ state }` connection report; returns whether the state changed. */
|
|
34
|
+
applyConnection(candidate: unknown): boolean;
|
|
35
|
+
}
|
|
36
|
+
export declare function createDevelopmentTimeline(initial: RunicDevelopmentState, maxTimelineEntries: number, changed: (state: RunicDevelopmentState) => void): DevelopmentTimeline;
|
|
37
|
+
export declare function initialDevelopmentState(contract: Readonly<{
|
|
38
|
+
identity?: string;
|
|
39
|
+
version?: string;
|
|
40
|
+
fingerprint?: string;
|
|
41
|
+
}> | undefined, vite?: RunicDevelopmentState["vite"]): RunicDevelopmentState;
|
|
42
|
+
export declare function withoutFailures(current: RunicDevelopmentState): RunicDevelopmentState;
|
|
43
|
+
export declare function timelineLimit(value: number | undefined): number;
|
package/dist/timeline.js
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { sanitizeDiagnosticSummary } from "./diagnostics.js";
|
|
2
|
+
const defaultTimelineLimit = 200;
|
|
3
|
+
const maximumTimelineLimit = 500;
|
|
4
|
+
export function createDevelopmentTimeline(initial, maxTimelineEntries, changed) {
|
|
5
|
+
let state = initial;
|
|
6
|
+
let nextSequence = 1;
|
|
7
|
+
return {
|
|
8
|
+
get state() { return state; },
|
|
9
|
+
configure(update) { state = update(state); },
|
|
10
|
+
appendDiagnostic(candidate, defaultSource) {
|
|
11
|
+
const summary = sanitizeDiagnosticSummary(candidate, defaultSource);
|
|
12
|
+
if (!summary)
|
|
13
|
+
return undefined;
|
|
14
|
+
const entry = {
|
|
15
|
+
...summary,
|
|
16
|
+
id: `diagnostic-${nextSequence}`,
|
|
17
|
+
timestamp: new Date().toISOString(),
|
|
18
|
+
};
|
|
19
|
+
nextSequence += 1;
|
|
20
|
+
state = { ...state, timeline: [...state.timeline, entry].slice(-maxTimelineEntries) };
|
|
21
|
+
changed(state);
|
|
22
|
+
return entry;
|
|
23
|
+
},
|
|
24
|
+
applyConnection(candidate) {
|
|
25
|
+
const next = connectionState(isRecord(candidate) ? candidate.state : undefined);
|
|
26
|
+
if (next === state.connection.state)
|
|
27
|
+
return false;
|
|
28
|
+
state = { ...state, connection: { state: next } };
|
|
29
|
+
changed(state);
|
|
30
|
+
return true;
|
|
31
|
+
},
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
export function initialDevelopmentState(contract, vite = { command: "serve", mode: "development", root: "" }) {
|
|
35
|
+
return {
|
|
36
|
+
contract: {
|
|
37
|
+
identity: cleanString(contract?.identity),
|
|
38
|
+
version: cleanString(contract?.version),
|
|
39
|
+
fingerprint: cleanString(contract?.fingerprint),
|
|
40
|
+
},
|
|
41
|
+
vite,
|
|
42
|
+
connection: { state: "unknown" },
|
|
43
|
+
timeline: [],
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
// Failures keep file paths and stacks for local display only (the dock, the development server's terminal). The
|
|
47
|
+
// state endpoint and the copied state stay path-free.
|
|
48
|
+
export function withoutFailures(current) {
|
|
49
|
+
return {
|
|
50
|
+
...current,
|
|
51
|
+
timeline: current.timeline.map(({ failure: _failure, ...entry }) => entry),
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
export function timelineLimit(value) {
|
|
55
|
+
if (typeof value !== "number" || !Number.isFinite(value))
|
|
56
|
+
return defaultTimelineLimit;
|
|
57
|
+
return Math.min(maximumTimelineLimit, Math.max(1, Math.floor(value)));
|
|
58
|
+
}
|
|
59
|
+
function connectionState(value) {
|
|
60
|
+
return value === "connecting" || value === "connected" || value === "reconnecting" || value === "lost"
|
|
61
|
+
? value
|
|
62
|
+
: "unknown";
|
|
63
|
+
}
|
|
64
|
+
function cleanString(value) {
|
|
65
|
+
return typeof value === "string" ? value.slice(0, 512) : "";
|
|
66
|
+
}
|
|
67
|
+
function isRecord(value) {
|
|
68
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
69
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@runic-artifex/vite-plugin-runic",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
4
4
|
"description": "Vite 8 development and DevTools integration for Runic applications",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -61,7 +61,7 @@
|
|
|
61
61
|
"url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
|
|
62
62
|
"directory": "packages/web/vite-plugin-runic"
|
|
63
63
|
},
|
|
64
|
-
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
64
|
+
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/packages/web/vite-plugin-runic#readme",
|
|
65
65
|
"bugs": {
|
|
66
66
|
"url": "https://github.com/Runic-Artifex/runic-sdk/issues"
|
|
67
67
|
},
|
|
@@ -72,5 +72,5 @@
|
|
|
72
72
|
"vite-plugin",
|
|
73
73
|
"devtools"
|
|
74
74
|
],
|
|
75
|
-
"gitHead": "
|
|
75
|
+
"gitHead": "11dc038ea80315c4d2b7e15cbd03dfe175ed6124"
|
|
76
76
|
}
|