@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 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.12.1/docs/diagnostics.md#runicp007).
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
- `virtual:runic/client` itself. `devtools: false` disables the injection.
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
- Two exports answer only the session, for development servers that cannot use
66
- `runic()`. Without `dotnet runic dev` neither changes anything.
67
-
68
- - `runicDevSession()` is a Vite plugin without `runic()`'s HTML hooks, for
69
- SvelteKit, which warns about plugins with a `transformIndexHtml` hook:
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
+ }
@@ -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
- // The development client that the plugin injects into served pages. It forwards the
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 diagnosticEvent = "runic:diagnostic";
7
- const connectionEvent = "runic:connection";
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
- hot?.send(diagnosticEvent, summary);
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 DevTools timeline. */
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
- if (!hot)
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 = hot.data[viewsListenerKey];
115
+ const previous = data[viewsListenerKey];
54
116
  if (previous)
55
117
  listeners.delete(previous);
56
118
  listeners.add(reportViewsDiagnostic);
57
- hot.data[viewsListenerKey] = reportViewsDiagnostic;
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
- hot?.send(connectionEvent, { state });
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
- if (!hot)
69
- return;
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
- channel.listeners.delete(previous);
75
- channel.listeners.add(reportConnection);
76
- hot.data[connectionListenerKey] = reportConnection;
77
- if (typeof channel.state === "string")
78
- reportConnection(channel.state);
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
- channel.requested = true;
82
- if (typeof channel.start === "function")
83
- channel.start();
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);
@@ -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
- * A Vite plugin that only answers `/__runic/state` with the `dotnet runic dev` session, for a configuration that
8
- * cannot use `runic()`: SvelteKit, which warns about `runic()`'s `transformIndexHtml` hook. `runic()` already
9
- * answers it. Without `dotnet runic dev` the plugin does nothing.
12
+ * Answers a development client's POST to `/__runic/diagnostics`: `{ "event", "data" }` from the same origin, as JSON
13
+ * of at most `maximumClientMessageBytes`. Calls `deliver` with an accepted message and answers 204.
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 that answer `/__runic/state` with the `dotnet runic dev` session, for a development server
14
- * that takes a Vite proxy configuration but no Vite plugins: the Angular CLI's `proxyConfig`. Spread the result
15
- * into the proxy configuration. Without `dotnet runic dev` it is empty and changes nothing.
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;
@@ -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, for a configuration that
19
- * cannot use `runic()`: SvelteKit, which warns about `runic()`'s `transformIndexHtml` hook. `runic()` already
20
- * answers it. Without `dotnet runic dev` the plugin does nothing.
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 that answer `/__runic/state` with the `dotnet runic dev` session, for a development server
35
- * that takes a Vite proxy configuration but no Vite plugins: the Angular CLI's `proxyConfig`. Spread the result
36
- * into the proxy configuration. Without `dotnet runic dev` it is empty and changes nothing.
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
- if (session === undefined)
41
- return {};
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 entry never proxies: it answers in bypass, and Vite then ends the request.
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
- answerSession(response, session);
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
+ }