@runic-artifex/vite-plugin-runic 0.13.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,53 +1,177 @@
1
+ import { connectionEvent, diagnosticEvent, diagnosticsPath, maximumClientMessageBytes, viewEvent } 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;
10
12
  }
11
- function answerSession(response, session) {
12
- response.statusCode = 204;
13
+ /** Answers `/__runic/state` with the path-free state, and with the `dotnet runic dev` session when there is one. */
14
+ export function answerState(response, state, session) {
15
+ response.statusCode = 200;
16
+ response.setHeader("Content-Type", "application/json; charset=utf-8");
13
17
  response.setHeader("Cache-Control", "no-store");
14
- response.setHeader(devSessionHeader, session);
18
+ if (session !== undefined)
19
+ response.setHeader(devSessionHeader, session);
20
+ response.end(JSON.stringify(withoutFailures(state)));
21
+ }
22
+ function answerStatus(response, status, headers = {}) {
23
+ if (response.writableEnded)
24
+ return;
25
+ response.statusCode = status;
26
+ response.setHeader("Cache-Control", "no-store");
27
+ for (const [name, value] of Object.entries(headers))
28
+ response.setHeader(name, value);
15
29
  response.end();
16
30
  }
17
31
  /**
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.
32
+ * Whether a request comes from a page of this server: a browser sends `Origin` with every POST, and a cross-site
33
+ * page that posts JSON needs a CORS preflight, which the endpoint never grants.
21
34
  */
22
- export function runicDevSession() {
23
- return {
24
- name: "runic:dev-session",
25
- configureServer(server) {
26
- const session = devSessionValue(process.env[devSessionVariable]);
27
- if (session === undefined)
35
+ function sameOrigin(request) {
36
+ const site = request.headers["sec-fetch-site"];
37
+ if (site !== undefined && site !== "same-origin")
38
+ return false;
39
+ const origin = request.headers.origin;
40
+ const host = request.headers.host;
41
+ if (typeof origin !== "string" || typeof host !== "string")
42
+ return false;
43
+ try {
44
+ const url = new URL(origin);
45
+ return (url.protocol === "http:" || url.protocol === "https:") && url.host === host.toLowerCase();
46
+ }
47
+ catch {
48
+ return false;
49
+ }
50
+ }
51
+ /**
52
+ * Answers a development client's POST to `/__runic/diagnostics`: `{ "event", "data" }` from the same origin, as JSON
53
+ * of at most `maximumClientMessageBytes`. Calls `deliver` with an accepted message and answers 204.
54
+ */
55
+ export async function answerClientMessage(request, response, deliver) {
56
+ if (request.method !== "POST") {
57
+ request.resume();
58
+ return answerStatus(response, 405, { Allow: "POST" });
59
+ }
60
+ if (!sameOrigin(request)) {
61
+ request.resume();
62
+ return answerStatus(response, 403);
63
+ }
64
+ const type = request.headers["content-type"];
65
+ if (typeof type !== "string" || !/^application\/json\s*(?:;|$)/iu.test(type)) {
66
+ request.resume();
67
+ return answerStatus(response, 415);
68
+ }
69
+ const declared = Number(request.headers["content-length"]);
70
+ if (Number.isFinite(declared) && declared > maximumClientMessageBytes) {
71
+ request.resume();
72
+ return answerStatus(response, 413);
73
+ }
74
+ const body = await readBody(request);
75
+ if (body === undefined)
76
+ return answerStatus(response, 413);
77
+ let message;
78
+ try {
79
+ message = JSON.parse(body);
80
+ }
81
+ catch {
82
+ return answerStatus(response, 400);
83
+ }
84
+ if (typeof message !== "object" || message === null || Array.isArray(message))
85
+ return answerStatus(response, 400);
86
+ const { event, data } = message;
87
+ if (event !== diagnosticEvent && event !== connectionEvent && event !== viewEvent)
88
+ return answerStatus(response, 400);
89
+ deliver(event, data);
90
+ answerStatus(response, 204);
91
+ }
92
+ // The body as UTF-8, or undefined once it exceeds the limit; the rest is drained so that the answer reaches the client.
93
+ function readBody(request) {
94
+ return new Promise((resolve) => {
95
+ const chunks = [];
96
+ let size = 0;
97
+ let exceeded = false;
98
+ request.on("data", (chunk) => {
99
+ if (exceeded)
28
100
  return;
29
- server.middlewares.use(statePath, (_request, response) => answerSession(response, session));
30
- },
31
- };
101
+ size += chunk.byteLength;
102
+ if (size > maximumClientMessageBytes) {
103
+ exceeded = true;
104
+ chunks.length = 0;
105
+ return;
106
+ }
107
+ chunks.push(chunk);
108
+ });
109
+ request.on("end", () => resolve(exceeded ? undefined : Buffer.concat(chunks).toString("utf8")));
110
+ request.on("error", () => resolve(undefined));
111
+ });
32
112
  }
33
113
  /**
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.
114
+ * Vite proxy entries for a development server that takes a Vite proxy configuration but no Vite plugins: the
115
+ * Angular CLI's `proxyConfig`. Spread the result into the proxy configuration. The entries never proxy; they answer:
116
+ *
117
+ * - `/__runic/state` with the path-free development state, and under `dotnet runic dev` with its session;
118
+ * - `/__runic/diagnostics`, which the development client (`@runic-artifex/vite-plugin-runic/client`) posts the
119
+ * page's Views diagnostics, connection state and View states to. The timeline is bounded, and failures go to the
120
+ * terminal.
37
121
  */
38
- export function runicDevSessionProxy() {
122
+ export function runicDevSessionProxy(options = {}) {
123
+ if (options.printFailures !== undefined && typeof options.printFailures !== "boolean") {
124
+ throw new TypeError("printFailures must be true or false.");
125
+ }
39
126
  const session = devSessionValue(process.env[devSessionVariable]);
40
- if (session === undefined)
41
- return {};
127
+ const printFailures = options.printFailures !== false;
128
+ const timeline = createDevelopmentTimeline(initialDevelopmentState(undefined, { command: "serve", mode: "development", root: process.cwd() }), timelineLimit(options.maxTimelineEntries), () => undefined);
129
+ const deliver = (event, data) => {
130
+ if (event === connectionEvent) {
131
+ timeline.applyConnection(data);
132
+ return;
133
+ }
134
+ if (event === viewEvent) {
135
+ timeline.applyView(data);
136
+ return;
137
+ }
138
+ const entry = timeline.appendDiagnostic(data);
139
+ if (entry?.failure && printFailures)
140
+ console.warn(formatFailure(entry));
141
+ };
42
142
  return {
43
143
  "^/__runic/state(?:[/?#]|$)": {
44
- // The entry never proxies: it answers in bypass, and Vite then ends the request.
144
+ // The entries answer in bypass and return the URL; Vite then sees the ended response and stops.
45
145
  bypass(request, response) {
46
146
  if (response === undefined)
47
147
  return false;
48
- answerSession(response, session);
148
+ request.resume();
149
+ answerState(response, timeline.state, session);
49
150
  return request.url ?? statePath;
50
151
  },
51
152
  },
153
+ [`^${diagnosticsPath}(?:[/?#]|$)`]: {
154
+ async bypass(request, response) {
155
+ if (response === undefined)
156
+ return false;
157
+ await answerClientMessage(request, response, deliver);
158
+ return request.url ?? diagnosticsPath;
159
+ },
160
+ },
52
161
  };
53
162
  }
163
+ /** A failure for the terminal: the entry's source and label, then the exception type, message and stack. */
164
+ export function formatFailure(entry) {
165
+ const failure = entry.failure;
166
+ const lines = [`[runic] ${entry.source ?? "runic"} ${entry.label}`];
167
+ if (failure) {
168
+ const heading = `${failure.type}: ${failure.message}`;
169
+ lines.push(` ${heading}`);
170
+ // A .NET stack often starts with the same line.
171
+ const stack = failure.stack?.split("\n") ?? [];
172
+ if (stack[0]?.trim() === heading)
173
+ stack.shift();
174
+ lines.push(...stack.map((line) => ` ${line.trim()}`));
175
+ }
176
+ return lines.join("\n");
177
+ }
@@ -41,3 +41,15 @@ export interface RunicDiagnosticSummary {
41
41
  */
42
42
  export declare function sanitizeDiagnosticSummary(candidate: unknown, forcedSource?: RunicDiagnosticSource): RunicDiagnosticSummary | undefined;
43
43
  export declare function diagnosticSource(value: unknown): RunicDiagnosticSource | undefined;
44
+ /** A View state value as the state inspector shows it: JSON, bounded and redacted. */
45
+ export type RunicViewStateValue = string | number | boolean | null | readonly RunicViewStateValue[] | {
46
+ readonly [member: string]: RunicViewStateValue;
47
+ };
48
+ /**
49
+ * A View's state for the state inspector, under the rules of timeline details: a member whose name suggests a
50
+ * credential or a path, and a string that looks like a credential or a path, is `[redacted]`; a member whose name
51
+ * looks like a path is left out. Strings are shortened,
52
+ * objects and arrays end with a `…` entry that counts what was left out, and nesting stops at `…` once the state is
53
+ * deep. Functions, symbols and `undefined` are left out; other non-JSON values are their type.
54
+ */
55
+ export declare function sanitizeViewState(value: unknown): RunicViewStateValue;
@@ -140,6 +140,90 @@ function sanitizeText(value, maximumLength) {
140
140
  return undefined;
141
141
  return sensitiveContent.test(value) || pathLikeContent.test(value) ? redacted : value;
142
142
  }
143
+ // The state inspector's bounds: a View's sanitized state is at most about 16,000 characters of JSON. Larger states
144
+ // are shown shallower and with fewer entries.
145
+ const viewStateBudgets = [
146
+ { depth: 6, entries: 50, text: 200 },
147
+ { depth: 4, entries: 20, text: 96 },
148
+ { depth: 2, entries: 10, text: 48 },
149
+ ];
150
+ const maximumViewStateLength = 16_000;
151
+ const maximumViewStateKeyLength = 80;
152
+ const tooLarge = "[too large]";
153
+ /**
154
+ * A View's state for the state inspector, under the rules of timeline details: a member whose name suggests a
155
+ * credential or a path, and a string that looks like a credential or a path, is `[redacted]`; a member whose name
156
+ * looks like a path is left out. Strings are shortened,
157
+ * objects and arrays end with a `…` entry that counts what was left out, and nesting stops at `…` once the state is
158
+ * deep. Functions, symbols and `undefined` are left out; other non-JSON values are their type.
159
+ */
160
+ export function sanitizeViewState(value) {
161
+ for (const budget of viewStateBudgets) {
162
+ const sanitized = viewStateValue(value, budget, 0, new Set());
163
+ if (JSON.stringify(sanitized).length <= maximumViewStateLength)
164
+ return sanitized;
165
+ }
166
+ return tooLarge;
167
+ }
168
+ function viewStateValue(value, budget, depth, seen) {
169
+ if (value === null || typeof value === "boolean")
170
+ return value;
171
+ if (typeof value === "number")
172
+ return Number.isFinite(value) ? value : String(value);
173
+ if (typeof value === "bigint")
174
+ return `${value}n`;
175
+ if (typeof value === "string") {
176
+ if (sensitiveContent.test(value) || pathLikeContent.test(value))
177
+ return redacted;
178
+ const text = value.replace(failureControlCharacters, "");
179
+ return text.length > budget.text ? `${text.slice(0, budget.text - 1)}…` : text;
180
+ }
181
+ if (typeof value !== "object")
182
+ return `[${typeof value}]`;
183
+ if (depth >= budget.depth)
184
+ return "…";
185
+ if (seen.has(value))
186
+ return "[circular]";
187
+ seen.add(value);
188
+ try {
189
+ if (Array.isArray(value)) {
190
+ const items = value.slice(0, budget.entries).map((item) => viewStateValue(item, budget, depth + 1, seen));
191
+ if (value.length > budget.entries)
192
+ items.push(`… ${value.length - budget.entries} more`);
193
+ return items;
194
+ }
195
+ if (value instanceof Date)
196
+ return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
197
+ if (value instanceof Map || value instanceof Set)
198
+ return `[${value.constructor.name}(${value.size})]`;
199
+ const output = {};
200
+ let count = 0;
201
+ let omitted = 0;
202
+ for (const key of Object.keys(value)) {
203
+ const member = value[key];
204
+ if (member === undefined || typeof member === "function" || typeof member === "symbol")
205
+ continue;
206
+ if (count >= budget.entries) {
207
+ omitted += 1;
208
+ continue;
209
+ }
210
+ // A key that looks like a path is one, so it is left out like a detail's.
211
+ if (key.length > maximumViewStateKeyLength || controlCharacters.test(key) || pathLikeContent.test(key) ||
212
+ key === "__proto__" || key === "constructor" || key === "prototype") {
213
+ omitted += 1;
214
+ continue;
215
+ }
216
+ output[key] = sensitiveKey.test(key) ? redacted : viewStateValue(member, budget, depth + 1, seen);
217
+ count += 1;
218
+ }
219
+ if (omitted > 0)
220
+ output["…"] = `${omitted} more`;
221
+ return output;
222
+ }
223
+ finally {
224
+ seen.delete(value);
225
+ }
226
+ }
143
227
  function isRecord(value) {
144
228
  return typeof value === "object" && value !== null && !Array.isArray(value);
145
229
  }
package/dist/index.d.ts CHANGED
@@ -1,7 +1,9 @@
1
1
  import type { Plugin } from "vite";
2
- import type { RunicDiagnosticEntry, RunicDiagnosticDetail, RunicDiagnosticFailure, RunicDiagnosticSource } from "./diagnostics.js";
3
- export { runicDevSession, runicDevSessionProxy } from "./dev-session.js";
4
- export type { RunicDiagnosticDetail, RunicDiagnosticDetailValue, RunicDiagnosticFailure, RunicDiagnosticEntry, RunicDiagnosticSource, RunicTraceKind, } from "./diagnostics.js";
2
+ import type { RunicDiagnosticEntry } from "./diagnostics.js";
3
+ export { runicDevSessionProxy } from "./dev-session.js";
4
+ export type { RunicDevSessionProxyOptions } from "./dev-session.js";
5
+ export type { RunicDevelopmentState, RunicViewSnapshot } from "./timeline.js";
6
+ export type { RunicDiagnosticDetail, RunicDiagnosticDetailValue, RunicDiagnosticFailure, RunicDiagnosticEntry, RunicDiagnosticSource, RunicTraceKind, RunicViewStateValue, } from "./diagnostics.js";
5
7
  /** The API another Vite plugin reaches through `plugin.api`, Vite's inter-plugin convention. */
6
8
  export interface RunicVitePluginApi {
7
9
  /** Adds a display-safe entry to the DevTools timeline, for example from a companion plugin. */
@@ -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;