@runic-artifex/vite-plugin-runic 0.13.0 → 0.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +123 -26
- package/dist/channel.d.ts +16 -0
- package/dist/channel.js +21 -0
- package/dist/client.js +180 -31
- package/dist/dev-session.d.ts +28 -9
- package/dist/dev-session.js +148 -24
- package/dist/diagnostics.d.ts +12 -0
- package/dist/diagnostics.js +84 -0
- package/dist/index.d.ts +12 -27
- package/dist/index.js +141 -138
- package/dist/stale-input.js +2 -1
- package/dist/timeline.d.ts +70 -0
- package/dist/timeline.js +112 -0
- package/package.json +3 -3
package/dist/dev-session.js
CHANGED
|
@@ -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
|
-
|
|
12
|
-
|
|
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
|
-
|
|
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
|
-
*
|
|
19
|
-
*
|
|
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
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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
|
-
|
|
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
|
|
35
|
-
*
|
|
36
|
-
*
|
|
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
|
-
|
|
41
|
-
|
|
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
|
|
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
|
-
|
|
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
|
+
}
|
package/dist/diagnostics.d.ts
CHANGED
|
@@ -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;
|
package/dist/diagnostics.js
CHANGED
|
@@ -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
|
|
3
|
-
export {
|
|
4
|
-
export type {
|
|
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;
|