@runic-artifex/vite-plugin-runic 0.19.0 → 0.20.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 +532 -12
- package/dist/access.d.ts +46 -0
- package/dist/access.js +123 -0
- package/dist/calls.d.ts +83 -0
- package/dist/calls.js +140 -0
- package/dist/channel.d.ts +58 -1
- package/dist/channel.js +20 -1
- package/dist/client.js +210 -1
- package/dist/dev-session.d.ts +19 -2
- package/dist/dev-session.js +67 -46
- package/dist/diagnostics.d.ts +2 -0
- package/dist/diagnostics.js +2 -1
- package/dist/handlers.d.ts +140 -0
- package/dist/handlers.js +773 -0
- package/dist/index.d.ts +39 -0
- package/dist/index.js +226 -11
- package/dist/inspect-data.d.ts +268 -0
- package/dist/inspect-data.js +442 -0
- package/dist/inspect-edit.d.ts +164 -0
- package/dist/inspect-edit.js +273 -0
- package/dist/inspect-editor.d.ts +34 -0
- package/dist/inspect-editor.js +282 -0
- package/dist/inspect-frameworks.d.ts +72 -0
- package/dist/inspect-frameworks.js +333 -0
- package/dist/inspect-handlers.d.ts +84 -0
- package/dist/inspect-handlers.js +331 -0
- package/dist/inspect.d.ts +42 -0
- package/dist/inspect.js +783 -0
- package/dist/otlp.d.ts +80 -0
- package/dist/otlp.js +254 -0
- package/dist/requests.d.ts +17 -0
- package/dist/requests.js +67 -0
- package/dist/sources.d.ts +135 -0
- package/dist/sources.js +343 -0
- package/dist/timeline.d.ts +12 -0
- package/dist/timeline.js +14 -0
- package/dist/translations-source.d.ts +36 -0
- package/dist/translations-source.js +109 -0
- package/package.json +12 -6
package/dist/client.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
|
-
import { clientOptionsKey, connectionEvent, diagnosticEvent, diagnosticsPath, maximumClientMessageBytes, viewEvent, } from "./channel.js";
|
|
1
|
+
import { callEvent, clientOptionsKey, connectionEvent, diagnosticEvent, diagnosticsPath, maximumClientMessageBytes, requestEvent, responseEvent, spanEvent, viewEvent, } from "./channel.js";
|
|
2
2
|
import { sanitizeDiagnosticSummary, sanitizeViewState } from "./diagnostics.js";
|
|
3
|
+
import { sanitizeCallReport } from "./calls.js";
|
|
3
4
|
import { installStaleInputWarning } from "./stale-input.js";
|
|
5
|
+
import { installInspect } from "./inspect.js";
|
|
4
6
|
const host = globalThis;
|
|
5
7
|
const hot = import.meta.hot;
|
|
6
8
|
const options = host[clientOptionsKey];
|
|
@@ -220,6 +222,141 @@ function connectViewsInspector() {
|
|
|
220
222
|
host.addEventListener?.("pagehide", pageHidden);
|
|
221
223
|
data[pageHideListenerKey] = pageHidden;
|
|
222
224
|
}
|
|
225
|
+
// The Bridge-call channel. @runic-artifex/views 0.20 or later reports each generated client call to it once a reader
|
|
226
|
+
// set `requested` and listens (specs/application, "Shared globals"), and then runs each call in a V8 async stack task,
|
|
227
|
+
// so a breakpoint after a reply shows the click that made the call. This client sends each settled call to the
|
|
228
|
+
// development server for the dock's call timeline (calls.ts), and draws it as an entry of the "Bridge calls" track in
|
|
229
|
+
// the "Runic" track group of Chromium's Performance panel (`performance.measure` with `detail.devtools`); other engines
|
|
230
|
+
// keep a plain measure or skip it. A .NET host in Development names each call's C# handler and its duration
|
|
231
|
+
// (handler-timing/1), which goes on the "C# handlers" track and in the dock's row. When the server exports traces
|
|
232
|
+
// (`trace` in the client options), the client also gives each call a W3C trace context, which its request carries to
|
|
233
|
+
// .NET (trace-context/1), and sends each settled call's span to the server.
|
|
234
|
+
const viewsCallsKey = Symbol.for("runic.views.calls");
|
|
235
|
+
const callsListenerKey = "runic:calls-listener";
|
|
236
|
+
const callsTraceKey = "runic:calls-trace";
|
|
237
|
+
const runicTrackGroup = "Runic";
|
|
238
|
+
const bridgeCallsTrack = "Bridge calls";
|
|
239
|
+
// .NET's own handler timing goes below the calls: an end event with `handler: { name, start, end }` (in
|
|
240
|
+
// `performance.now()` milliseconds) becomes an entry of this track.
|
|
241
|
+
const handlersTrack = "C# handlers";
|
|
242
|
+
// A new root span for a call: a random trace id and span id, sampled, as W3C traceparent version 00.
|
|
243
|
+
function newTrace() {
|
|
244
|
+
const crypto = globalThis.crypto;
|
|
245
|
+
if (typeof crypto?.getRandomValues !== "function")
|
|
246
|
+
return undefined;
|
|
247
|
+
const hex = (length) => Array.from(crypto.getRandomValues(new Uint8Array(length)), byte => byte.toString(16).padStart(2, "0")).join("");
|
|
248
|
+
return { traceparent: `00-${hex(16)}-${hex(8)}-01` };
|
|
249
|
+
}
|
|
250
|
+
function viewsCalls() {
|
|
251
|
+
const channels = host;
|
|
252
|
+
return channels[viewsCallsKey] ??= { listeners: new Set() };
|
|
253
|
+
}
|
|
254
|
+
// A track entry. It is cleared from the page's timeline buffer at once: a recording already has it, and a long
|
|
255
|
+
// development session should not fill the buffer. An engine without User Timing level 3 skips it.
|
|
256
|
+
function measure(name, start, end, devtools) {
|
|
257
|
+
const timing = globalThis.performance;
|
|
258
|
+
if (typeof timing?.measure !== "function")
|
|
259
|
+
return;
|
|
260
|
+
try {
|
|
261
|
+
timing.measure(name, { start, end, detail: { devtools } });
|
|
262
|
+
timing.clearMeasures?.(name);
|
|
263
|
+
}
|
|
264
|
+
catch { /* Not supported. */ }
|
|
265
|
+
}
|
|
266
|
+
const outcomeColors = { ok: "primary", error: "error", cancelled: "tertiary" };
|
|
267
|
+
// The exception of a failed call: .NET's development detail of a `BridgeError`, else a browser error's own.
|
|
268
|
+
function callFailure(error) {
|
|
269
|
+
if (typeof error !== "object" || error === null)
|
|
270
|
+
return undefined;
|
|
271
|
+
const { name, message, stack, detail } = error;
|
|
272
|
+
if (typeof detail === "object" && detail !== null) {
|
|
273
|
+
const { type, message: detailMessage, stack: detailStack } = detail;
|
|
274
|
+
return { type: typeof type === "string" ? type : name, message: detailMessage, stack: detailStack };
|
|
275
|
+
}
|
|
276
|
+
return { type: name, message, stack };
|
|
277
|
+
}
|
|
278
|
+
// The dock's call timeline. The server names the handler from its source map.
|
|
279
|
+
function sendCall(event) {
|
|
280
|
+
const handler = typeof event.handler === "object" && event.handler !== null ? event.handler : undefined;
|
|
281
|
+
const handlerDuration = typeof handler?.duration === "number" ? handler.duration
|
|
282
|
+
: typeof handler?.start === "number" && typeof handler.end === "number" ? handler.end - handler.start : undefined;
|
|
283
|
+
const report = sanitizeCallReport({
|
|
284
|
+
page, kind: event.kind, route: event.route, contract: event.contract, member: event.member,
|
|
285
|
+
duration: event.end - event.start, outcome: event.outcome, reason: event.reason, revision: event.revision,
|
|
286
|
+
handlerDuration, handlerName: handler?.name,
|
|
287
|
+
failure: event.outcome === "error" ? callFailure(event.error) : undefined,
|
|
288
|
+
});
|
|
289
|
+
if (report)
|
|
290
|
+
send(callEvent, report);
|
|
291
|
+
}
|
|
292
|
+
// The span of a settled call with a trace context, for the server's OTLP export: epoch milliseconds, so the server
|
|
293
|
+
// needs no page clock.
|
|
294
|
+
function sendSpan(event, label) {
|
|
295
|
+
const trace = event.trace;
|
|
296
|
+
if (options?.trace !== true || typeof trace?.traceparent !== "string" || typeof event.end !== "number")
|
|
297
|
+
return;
|
|
298
|
+
const origin = globalThis.performance?.timeOrigin;
|
|
299
|
+
if (typeof origin !== "number")
|
|
300
|
+
return;
|
|
301
|
+
const handler = event.handler;
|
|
302
|
+
send(spanEvent, {
|
|
303
|
+
traceparent: trace.traceparent, name: `${event.kind} ${label}`, start: origin + event.start, end: origin + event.end,
|
|
304
|
+
kind: event.kind, request: event.request, route: event.route, contract: event.contract, member: event.member,
|
|
305
|
+
outcome: event.outcome, reason: event.reason, revision: event.revision,
|
|
306
|
+
...typeof handler?.name === "string" && typeof handler.duration === "number" ? { handler: { name: handler.name, duration: handler.duration } } : {},
|
|
307
|
+
});
|
|
308
|
+
}
|
|
309
|
+
function reportCall(event) {
|
|
310
|
+
if (typeof event !== "object" || event === null || event.phase !== "end")
|
|
311
|
+
return;
|
|
312
|
+
if (typeof event.start !== "number" || typeof event.end !== "number")
|
|
313
|
+
return;
|
|
314
|
+
sendCall(event);
|
|
315
|
+
// `Demo.EditorViewModel:3F2A…` names the C# view model `EditorViewModel`.
|
|
316
|
+
const model = String(event.contract).split(":", 1)[0].split(".").pop() || event.route;
|
|
317
|
+
const label = `${model}.${event.member}`;
|
|
318
|
+
sendSpan(event, label);
|
|
319
|
+
if (viewsCalls().devtools === false)
|
|
320
|
+
return;
|
|
321
|
+
const outcome = String(event.outcome);
|
|
322
|
+
const handler = event.handler;
|
|
323
|
+
const timed = typeof handler === "object" && handler !== null && typeof handler.start === "number" && typeof handler.end === "number";
|
|
324
|
+
const properties = [
|
|
325
|
+
["Kind", String(event.request)], ["Route", String(event.route)], ["Contract", String(event.contract)],
|
|
326
|
+
["Request id", String(event.id)], ["Outcome", event.reason === undefined ? outcome : `${outcome} (${event.reason})`],
|
|
327
|
+
];
|
|
328
|
+
if (typeof event.revision === "number")
|
|
329
|
+
properties.push(["Revision", String(event.revision)]);
|
|
330
|
+
if (timed)
|
|
331
|
+
properties.push(["C# handler", `${String(handler.name)} (${(handler.end - handler.start).toFixed(2)} ms)`]);
|
|
332
|
+
if (typeof event.trace?.traceparent === "string")
|
|
333
|
+
properties.push(["traceparent", event.trace.traceparent]);
|
|
334
|
+
measure(`${label} #${event.id}`, event.start, event.end, {
|
|
335
|
+
dataType: "track-entry", track: bridgeCallsTrack, trackGroup: runicTrackGroup, color: outcomeColors[outcome] ?? "warning",
|
|
336
|
+
properties, tooltipText: `${event.kind} ${label}: ${outcome}, ${(event.end - event.start).toFixed(1)} ms`,
|
|
337
|
+
});
|
|
338
|
+
if (timed) {
|
|
339
|
+
measure(`${handler.name} #${event.id}`, handler.start, handler.end, {
|
|
340
|
+
dataType: "track-entry", track: handlersTrack, trackGroup: runicTrackGroup, color: "secondary",
|
|
341
|
+
properties: [["Request id", String(event.id)], ["Route", String(event.route)], ["Member", String(event.member)]],
|
|
342
|
+
});
|
|
343
|
+
}
|
|
344
|
+
}
|
|
345
|
+
function connectViewsCalls() {
|
|
346
|
+
const calls = viewsCalls();
|
|
347
|
+
const previous = data[callsListenerKey];
|
|
348
|
+
if (previous)
|
|
349
|
+
calls.listeners.delete(previous);
|
|
350
|
+
calls.listeners.add(reportCall);
|
|
351
|
+
data[callsListenerKey] = reportCall;
|
|
352
|
+
// Only while the server exports traces; otherwise no call gets a trace context.
|
|
353
|
+
if (options?.trace === true)
|
|
354
|
+
calls.trace = newTrace;
|
|
355
|
+
else if (calls.trace === newTrace || data[callsTraceKey] === calls.trace)
|
|
356
|
+
delete calls.trace;
|
|
357
|
+
data[callsTraceKey] = calls.trace;
|
|
358
|
+
calls.requested = true;
|
|
359
|
+
}
|
|
223
360
|
// Removes this copy's listeners once the HTTP channel has no server to report to.
|
|
224
361
|
function close() {
|
|
225
362
|
channel = "closed";
|
|
@@ -227,17 +364,89 @@ function close() {
|
|
|
227
364
|
viewsDiagnostics().delete(reportViewsDiagnostic);
|
|
228
365
|
viewsConnection().listeners.delete(reportConnection);
|
|
229
366
|
viewsInspector().listeners.delete(reportInspector);
|
|
367
|
+
const calls = viewsCalls();
|
|
368
|
+
calls.listeners.delete(reportCall);
|
|
369
|
+
if (calls.trace === newTrace)
|
|
370
|
+
delete calls.trace;
|
|
371
|
+
disposeInspect();
|
|
230
372
|
host.removeEventListener?.("pagehide", pageHidden);
|
|
231
373
|
if (stateTimer !== undefined)
|
|
232
374
|
clearTimeout(stateTimer);
|
|
233
375
|
stateTimer = undefined;
|
|
234
376
|
pendingStates.clear();
|
|
235
377
|
}
|
|
378
|
+
// The Vite DevTools dock. Its own loader is an inline module that loads `/__devtools/embedded.js` relative to the
|
|
379
|
+
// document. Under `dotnet runic dev` the document is the .NET host's page, which loads Vite's modules from Vite's
|
|
380
|
+
// origin, so that URL names the host and the dock never appears; SvelteKit runs no `transformIndexHtml` and adds no
|
|
381
|
+
// loader at all. This client is a module of Vite's origin, so it loads the dock from there once the document's own
|
|
382
|
+
// scripts ran, unless one of them already loads that script.
|
|
383
|
+
const dockPath = "/__devtools/embedded.js";
|
|
384
|
+
function loadDock() {
|
|
385
|
+
const document = globalThis.document;
|
|
386
|
+
if (options?.dock !== true || document === undefined)
|
|
387
|
+
return;
|
|
388
|
+
const source = new URL(dockPath, import.meta.url).href;
|
|
389
|
+
const load = () => {
|
|
390
|
+
for (const script of document.querySelectorAll("script[src]")) {
|
|
391
|
+
if (script.src === source)
|
|
392
|
+
return;
|
|
393
|
+
}
|
|
394
|
+
const script = document.createElement("script");
|
|
395
|
+
script.type = "module";
|
|
396
|
+
script.src = source;
|
|
397
|
+
document.body.appendChild(script);
|
|
398
|
+
};
|
|
399
|
+
// The document's module scripts, the dock's loader among them, all ran by the window's load event; this client runs
|
|
400
|
+
// first, while the document is still "interactive", or later from a page module (SvelteKit's hooks.client.ts).
|
|
401
|
+
if (document.readyState === "complete")
|
|
402
|
+
load();
|
|
403
|
+
else
|
|
404
|
+
host.addEventListener?.("load", load);
|
|
405
|
+
}
|
|
236
406
|
connectViewsDiagnostics();
|
|
237
407
|
connectViewsConnection();
|
|
238
408
|
connectViewsInspector();
|
|
409
|
+
connectViewsCalls();
|
|
410
|
+
// Requests to the development server over Vite's HMR connection (channel.ts, requestEvent). Under `dotnet runic dev` the
|
|
411
|
+
// page is the .NET host's, so a relative URL such as /__runic/open names the host; the HMR connection is Vite's own, and
|
|
412
|
+
// Vite admits it only with the token of its client module. Without that connection (the Angular CLI, or a page that
|
|
413
|
+
// loaded the client without Vite's HMR) there is no request, and Runic Inspect uses the HTTP endpoints.
|
|
414
|
+
const requestTimeout = 10_000;
|
|
415
|
+
const pendingRequests = new Map();
|
|
416
|
+
let nextRequest = 1;
|
|
417
|
+
const hotRequest = hot && options?.channel === "hot" && typeof hot.on === "function"
|
|
418
|
+
? (kind, target) => new Promise((resolve) => {
|
|
419
|
+
const id = nextRequest++;
|
|
420
|
+
const timer = setTimeout(() => {
|
|
421
|
+
pendingRequests.delete(id);
|
|
422
|
+
resolve({ status: 0 });
|
|
423
|
+
}, requestTimeout);
|
|
424
|
+
pendingRequests.set(id, (response) => {
|
|
425
|
+
clearTimeout(timer);
|
|
426
|
+
resolve(response);
|
|
427
|
+
});
|
|
428
|
+
hot.send(requestEvent, kind === "sources" ? { id, kind } : kind === "handlers" ? { id, kind, file: target } : { id, kind, target });
|
|
429
|
+
})
|
|
430
|
+
: undefined;
|
|
431
|
+
hot?.on?.(responseEvent, (data) => {
|
|
432
|
+
const response = data;
|
|
433
|
+
if (typeof response?.id !== "number")
|
|
434
|
+
return;
|
|
435
|
+
const settle = pendingRequests.get(response.id);
|
|
436
|
+
pendingRequests.delete(response.id);
|
|
437
|
+
settle?.(response);
|
|
438
|
+
});
|
|
439
|
+
const inspectListenerKey = "runic:inspect";
|
|
440
|
+
let disposeInspect = () => { };
|
|
441
|
+
function connectInspect() {
|
|
442
|
+
data[inspectListenerKey]?.();
|
|
443
|
+
disposeInspect = options?.inspect === false ? () => { } : installInspect({ base: options?.base, root: options?.root, request: hotRequest });
|
|
444
|
+
data[inspectListenerKey] = disposeInspect;
|
|
445
|
+
}
|
|
446
|
+
connectInspect();
|
|
239
447
|
// Vite's HMR context shows that a development server serves the page: install the warning now. Without it
|
|
240
448
|
// (a production build that kept the client), the HTTP channel installs it once the server answers. Installs once
|
|
241
449
|
// per page; HMR re-evaluation leaves it in place.
|
|
242
450
|
if (hot)
|
|
243
451
|
installStaleInputWarning(globalThis);
|
|
452
|
+
loadDock();
|
package/dist/dev-session.d.ts
CHANGED
|
@@ -4,6 +4,7 @@ import type { RunicDevelopmentState, RunicTimelineEntry } from "./timeline.js";
|
|
|
4
4
|
export declare const devSessionVariable = "RUNIC_APPLICATION_DEV_SESSION";
|
|
5
5
|
export declare const devSessionHeader = "X-Runic-Dev-Session";
|
|
6
6
|
export declare const statePath = "/__runic/state";
|
|
7
|
+
export { isLoopbackRequest, readLimitedBody, sameOrigin } from "./requests.js";
|
|
7
8
|
/** The session value `dotnet runic dev` set, when it has the shape the tool writes: 32 to 128 hex digits. */
|
|
8
9
|
export declare function devSessionValue(value: string | undefined): string | undefined;
|
|
9
10
|
/** Answers `/__runic/state` with the path-free state, and with the `dotnet runic dev` session when there is one. */
|
|
@@ -21,6 +22,18 @@ export interface RunicDevSessionProxyOptions {
|
|
|
21
22
|
* stack) to the development server's terminal. Defaults to `true`.
|
|
22
23
|
*/
|
|
23
24
|
readonly printFailures?: boolean;
|
|
25
|
+
/**
|
|
26
|
+
* The development source map for Runic Inspect, as `runic({ sourceMap })` takes it: a path relative to the
|
|
27
|
+
* server's working directory, or `false` to answer neither `/__runic/sources` nor `/__runic/open`.
|
|
28
|
+
*/
|
|
29
|
+
readonly sourceMap?: string | false;
|
|
30
|
+
/** `false` turns off `/__runic/handlers`, Runic Inspect's handler analysis. Defaults to `true`. */
|
|
31
|
+
readonly inspect?: boolean;
|
|
32
|
+
/**
|
|
33
|
+
* Hosts and networks besides this machine whose pages may read `/__runic/sources` and `/__runic/handlers`, as
|
|
34
|
+
* `runic({ allow })` takes them; `RUNIC_DEV_ALLOW` adds to them. `/__runic/open` stays loopback-only.
|
|
35
|
+
*/
|
|
36
|
+
readonly allow?: readonly string[];
|
|
24
37
|
}
|
|
25
38
|
/**
|
|
26
39
|
* Vite proxy entries for a development server that takes a Vite proxy configuration but no Vite plugins: the
|
|
@@ -28,8 +41,12 @@ export interface RunicDevSessionProxyOptions {
|
|
|
28
41
|
*
|
|
29
42
|
* - `/__runic/state` with the path-free development state, and under `dotnet runic dev` with its session;
|
|
30
43
|
* - `/__runic/diagnostics`, which the development client (`@runic-artifex/vite-plugin-runic/client`) posts the
|
|
31
|
-
* page's Views diagnostics, connection state
|
|
32
|
-
* terminal
|
|
44
|
+
* page's Views diagnostics, connection state, View states and Bridge calls to. The timeline is bounded, and failures go
|
|
45
|
+
* to the terminal;
|
|
46
|
+
* - for Runic Inspect: `/__runic/sources` (the development source map), `/__runic/open` (opens a location in a file
|
|
47
|
+
* the source map lists, with launch-editor as `runic()` does) and `/__runic/handlers` (which event handlers of a
|
|
48
|
+
* component reach which commands, from its source and template), each for pages of this machine, or of the hosts
|
|
49
|
+
* and networks `allow` and `RUNIC_DEV_ALLOW` admit (`/__runic/open` for this machine only).
|
|
33
50
|
*/
|
|
34
51
|
export declare function runicDevSessionProxy(options?: RunicDevSessionProxyOptions): Record<string, ProxyOptions>;
|
|
35
52
|
/** A failure for the terminal: the entry's source and label, then the exception type, message and stack. */
|
package/dist/dev-session.js
CHANGED
|
@@ -1,4 +1,8 @@
|
|
|
1
|
-
import { connectionEvent, diagnosticEvent, diagnosticsPath, maximumClientMessageBytes, viewEvent } from "./channel.js";
|
|
1
|
+
import { callEvent, connectionEvent, diagnosticEvent, diagnosticsPath, handlersPath, maximumClientMessageBytes, openPath, sourcesPath, spanEvent, viewEvent } from "./channel.js";
|
|
2
|
+
import { readLimitedBody, sameOrigin } from "./requests.js";
|
|
3
|
+
import { parseAllowList, resolveAccessList } from "./access.js";
|
|
4
|
+
import { answerOpen, answerSources, createSourceMapReader, launchSourceEditor } from "./sources.js";
|
|
5
|
+
import { answerHandlers, createHandlerAnalyzer } from "./handlers.js";
|
|
2
6
|
import { createDevelopmentTimeline, initialDevelopmentState, timelineLimit, withoutFailures } from "./timeline.js";
|
|
3
7
|
// `dotnet runic dev` gives the development server process a random session value and accepts the server as ready
|
|
4
8
|
// only when /__runic/state answers with it, so another process that takes the port first is not mistaken for this
|
|
@@ -6,6 +10,7 @@ import { createDevelopmentTimeline, initialDevelopmentState, timelineLimit, with
|
|
|
6
10
|
export const devSessionVariable = "RUNIC_APPLICATION_DEV_SESSION";
|
|
7
11
|
export const devSessionHeader = "X-Runic-Dev-Session";
|
|
8
12
|
export const statePath = "/__runic/state";
|
|
13
|
+
export { isLoopbackRequest, readLimitedBody, sameOrigin } from "./requests.js";
|
|
9
14
|
/** The session value `dotnet runic dev` set, when it has the shape the tool writes: 32 to 128 hex digits. */
|
|
10
15
|
export function devSessionValue(value) {
|
|
11
16
|
return value !== undefined && /^[0-9a-f]{32,128}$/.test(value) ? value : undefined;
|
|
@@ -28,26 +33,6 @@ function answerStatus(response, status, headers = {}) {
|
|
|
28
33
|
response.setHeader(name, value);
|
|
29
34
|
response.end();
|
|
30
35
|
}
|
|
31
|
-
/**
|
|
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.
|
|
34
|
-
*/
|
|
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
36
|
/**
|
|
52
37
|
* Answers a development client's POST to `/__runic/diagnostics`: `{ "event", "data" }` from the same origin, as JSON
|
|
53
38
|
* of at most `maximumClientMessageBytes`. Calls `deliver` with an accepted message and answers 204.
|
|
@@ -71,7 +56,7 @@ export async function answerClientMessage(request, response, deliver) {
|
|
|
71
56
|
request.resume();
|
|
72
57
|
return answerStatus(response, 413);
|
|
73
58
|
}
|
|
74
|
-
const body = await
|
|
59
|
+
const body = await readLimitedBody(request, maximumClientMessageBytes);
|
|
75
60
|
if (body === undefined)
|
|
76
61
|
return answerStatus(response, 413);
|
|
77
62
|
let message;
|
|
@@ -84,46 +69,38 @@ export async function answerClientMessage(request, response, deliver) {
|
|
|
84
69
|
if (typeof message !== "object" || message === null || Array.isArray(message))
|
|
85
70
|
return answerStatus(response, 400);
|
|
86
71
|
const { event, data } = message;
|
|
87
|
-
if (event !== diagnosticEvent && event !== connectionEvent && event !== viewEvent)
|
|
72
|
+
if (event !== diagnosticEvent && event !== connectionEvent && event !== viewEvent && event !== callEvent && event !== spanEvent) {
|
|
88
73
|
return answerStatus(response, 400);
|
|
74
|
+
}
|
|
89
75
|
deliver(event, data);
|
|
90
76
|
answerStatus(response, 204);
|
|
91
77
|
}
|
|
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)
|
|
100
|
-
return;
|
|
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
|
-
});
|
|
112
|
-
}
|
|
113
78
|
/**
|
|
114
79
|
* Vite proxy entries for a development server that takes a Vite proxy configuration but no Vite plugins: the
|
|
115
80
|
* Angular CLI's `proxyConfig`. Spread the result into the proxy configuration. The entries never proxy; they answer:
|
|
116
81
|
*
|
|
117
82
|
* - `/__runic/state` with the path-free development state, and under `dotnet runic dev` with its session;
|
|
118
83
|
* - `/__runic/diagnostics`, which the development client (`@runic-artifex/vite-plugin-runic/client`) posts the
|
|
119
|
-
* page's Views diagnostics, connection state
|
|
120
|
-
* terminal
|
|
84
|
+
* page's Views diagnostics, connection state, View states and Bridge calls to. The timeline is bounded, and failures go
|
|
85
|
+
* to the terminal;
|
|
86
|
+
* - for Runic Inspect: `/__runic/sources` (the development source map), `/__runic/open` (opens a location in a file
|
|
87
|
+
* the source map lists, with launch-editor as `runic()` does) and `/__runic/handlers` (which event handlers of a
|
|
88
|
+
* component reach which commands, from its source and template), each for pages of this machine, or of the hosts
|
|
89
|
+
* and networks `allow` and `RUNIC_DEV_ALLOW` admit (`/__runic/open` for this machine only).
|
|
121
90
|
*/
|
|
122
91
|
export function runicDevSessionProxy(options = {}) {
|
|
123
92
|
if (options.printFailures !== undefined && typeof options.printFailures !== "boolean") {
|
|
124
93
|
throw new TypeError("printFailures must be true or false.");
|
|
125
94
|
}
|
|
95
|
+
if (options.inspect !== undefined && typeof options.inspect !== "boolean")
|
|
96
|
+
throw new TypeError("inspect must be true or false.");
|
|
97
|
+
if (options.sourceMap !== undefined && options.sourceMap !== false &&
|
|
98
|
+
(typeof options.sourceMap !== "string" || options.sourceMap.length === 0)) {
|
|
99
|
+
throw new TypeError("sourceMap must be a path or false.");
|
|
100
|
+
}
|
|
101
|
+
const access = resolveAccessList(options.allow === undefined ? [] : parseAllowList(options.allow, "allow"));
|
|
126
102
|
const session = devSessionValue(process.env[devSessionVariable]);
|
|
103
|
+
const root = process.cwd();
|
|
127
104
|
const printFailures = options.printFailures !== false;
|
|
128
105
|
const timeline = createDevelopmentTimeline(initialDevelopmentState(undefined, { command: "serve", mode: "development", root: process.cwd() }), timelineLimit(options.maxTimelineEntries), () => undefined);
|
|
129
106
|
const deliver = (event, data) => {
|
|
@@ -135,11 +112,55 @@ export function runicDevSessionProxy(options = {}) {
|
|
|
135
112
|
timeline.applyView(data);
|
|
136
113
|
return;
|
|
137
114
|
}
|
|
115
|
+
// The Angular CLI's server has no source map reader for the calls, so they name no handler.
|
|
116
|
+
if (event === callEvent) {
|
|
117
|
+
timeline.appendCall(data);
|
|
118
|
+
return;
|
|
119
|
+
}
|
|
120
|
+
// This proxy exports no spans: its client is not configured to send them.
|
|
121
|
+
if (event === spanEvent)
|
|
122
|
+
return;
|
|
138
123
|
const entry = timeline.appendDiagnostic(data);
|
|
139
124
|
if (entry?.failure && printFailures)
|
|
140
125
|
console.warn(formatFailure(entry));
|
|
141
126
|
};
|
|
127
|
+
const inspect = {};
|
|
128
|
+
if (options.sourceMap !== false) {
|
|
129
|
+
const readSourceMap = createSourceMapReader(options.sourceMap, () => root);
|
|
130
|
+
inspect[`^${sourcesPath}(?:[/?#]|$)`] = {
|
|
131
|
+
async bypass(request, response) {
|
|
132
|
+
if (response === undefined)
|
|
133
|
+
return false;
|
|
134
|
+
await answerSources(request, response, readSourceMap, access);
|
|
135
|
+
return request.url ?? sourcesPath;
|
|
136
|
+
},
|
|
137
|
+
};
|
|
138
|
+
inspect[`^${openPath}(?:[/?#]|$)`] = {
|
|
139
|
+
// The same decision and launcher as runic()'s /__runic/open (sources.ts), for the source map's files only: the
|
|
140
|
+
// Angular CLI gives this proxy no Vite configuration to tell which frontend files it serves.
|
|
141
|
+
async bypass(request, response) {
|
|
142
|
+
if (response === undefined)
|
|
143
|
+
return false;
|
|
144
|
+
await answerOpen(request, response, readSourceMap, (location) => {
|
|
145
|
+
launchSourceEditor(location, (message) => console.warn(`[runic] ${message}`));
|
|
146
|
+
});
|
|
147
|
+
return request.url ?? openPath;
|
|
148
|
+
},
|
|
149
|
+
};
|
|
150
|
+
}
|
|
151
|
+
if (options.inspect !== false) {
|
|
152
|
+
const analyze = createHandlerAnalyzer(() => root);
|
|
153
|
+
inspect[`^${handlersPath}(?:[/?#]|$)`] = {
|
|
154
|
+
async bypass(request, response) {
|
|
155
|
+
if (response === undefined)
|
|
156
|
+
return false;
|
|
157
|
+
await answerHandlers(request, response, analyze, root, access);
|
|
158
|
+
return request.url ?? handlersPath;
|
|
159
|
+
},
|
|
160
|
+
};
|
|
161
|
+
}
|
|
142
162
|
return {
|
|
163
|
+
...inspect,
|
|
143
164
|
"^/__runic/state(?:[/?#]|$)": {
|
|
144
165
|
// The entries answer in bypass and return the URL; Vite then sees the ended response and stops.
|
|
145
166
|
bypass(request, response) {
|
package/dist/diagnostics.d.ts
CHANGED
|
@@ -40,6 +40,8 @@ export interface RunicDiagnosticSummary {
|
|
|
40
40
|
* transported or displayed. The caller still owns identifier and timestamp.
|
|
41
41
|
*/
|
|
42
42
|
export declare function sanitizeDiagnosticSummary(candidate: unknown, forcedSource?: RunicDiagnosticSource): RunicDiagnosticSummary | undefined;
|
|
43
|
+
/** A failure under the failure rules: bounded, file paths kept, credentials redacted. */
|
|
44
|
+
export declare function sanitizeFailure(candidate: unknown): RunicDiagnosticFailure | undefined;
|
|
43
45
|
export declare function diagnosticSource(value: unknown): RunicDiagnosticSource | undefined;
|
|
44
46
|
/** A View state value as the state inspector shows it: JSON, bounded and redacted. */
|
|
45
47
|
export type RunicViewStateValue = string | number | boolean | null | readonly RunicViewStateValue[] | {
|
package/dist/diagnostics.js
CHANGED
|
@@ -52,7 +52,8 @@ export function sanitizeDiagnosticSummary(candidate, forcedSource) {
|
|
|
52
52
|
const fitted = fitSummary(summary);
|
|
53
53
|
return failure ? { ...fitted, failure } : fitted;
|
|
54
54
|
}
|
|
55
|
-
|
|
55
|
+
/** A failure under the failure rules: bounded, file paths kept, credentials redacted. */
|
|
56
|
+
export function sanitizeFailure(candidate) {
|
|
56
57
|
if (!isRecord(candidate))
|
|
57
58
|
return undefined;
|
|
58
59
|
const type = failureText(candidate.type, maximumFailureTypeLength, false);
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
import type { IncomingMessage, ServerResponse } from "node:http";
|
|
2
|
+
import type { AccessList } from "./access.js";
|
|
3
|
+
/** A position in a file: 1-based line and column. */
|
|
4
|
+
export interface RunicHandlerPosition {
|
|
5
|
+
readonly file: string;
|
|
6
|
+
readonly line: number;
|
|
7
|
+
readonly column: number;
|
|
8
|
+
}
|
|
9
|
+
/** A generated-client call a handler reaches: `client.save()` is `save`. */
|
|
10
|
+
export interface RunicHandlerCall extends RunicHandlerPosition {
|
|
11
|
+
readonly member: string;
|
|
12
|
+
/**
|
|
13
|
+
* `direct`: in the handler's expression; `helper`: in the callback of a Runic helper (`useCommand`, `injectCommand`,
|
|
14
|
+
* …) the handler uses; `local`: through another declaration of the file.
|
|
15
|
+
*/
|
|
16
|
+
readonly via: "direct" | "helper" | "local";
|
|
17
|
+
}
|
|
18
|
+
/** An event binding of the markup and what it reaches. */
|
|
19
|
+
export interface RunicHandlerBinding extends RunicHandlerPosition {
|
|
20
|
+
/** The element or component tag: `button`, `MyButton`. */
|
|
21
|
+
readonly tag: string;
|
|
22
|
+
/** The event, lower case without `on`: `click`. */
|
|
23
|
+
readonly event: string;
|
|
24
|
+
/** The handler's source text, shortened. */
|
|
25
|
+
readonly expression: string;
|
|
26
|
+
readonly calls: readonly RunicHandlerCall[];
|
|
27
|
+
/** Names the handler uses that are imported from another file; their calls are not followed. */
|
|
28
|
+
readonly external: readonly {
|
|
29
|
+
readonly name: string;
|
|
30
|
+
readonly source: string;
|
|
31
|
+
}[];
|
|
32
|
+
}
|
|
33
|
+
export interface RunicHandlerAnalysis {
|
|
34
|
+
readonly format: "runic-handlers/1";
|
|
35
|
+
readonly file: string;
|
|
36
|
+
readonly framework: "react" | "vue" | "svelte" | "angular" | "unknown";
|
|
37
|
+
readonly bindings: readonly RunicHandlerBinding[];
|
|
38
|
+
/** Why a file has no analysis: its framework's compiler was not found. */
|
|
39
|
+
readonly note?: string;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Loads the parser, Vite's `parseSync` (oxc). Imported on first use, so that `runicDevSessionProxy()` under a server
|
|
43
|
+
* without Vite plugins loads without it. Returns whether it is available.
|
|
44
|
+
*/
|
|
45
|
+
export declare function loadHandlerParser(): Promise<boolean>;
|
|
46
|
+
/** The JSX event bindings of a script (`onClick={…}`), at the opening element's `<`. */
|
|
47
|
+
export declare function analyzeJsx(file: string, code: string): RunicHandlerBinding[];
|
|
48
|
+
/** The `(event)="…"` and `on-event="…"` bindings of an Angular template, with their element's tag and position. */
|
|
49
|
+
export declare function angularTemplateBindings(template: string): {
|
|
50
|
+
tag: string;
|
|
51
|
+
event: string;
|
|
52
|
+
expression: string;
|
|
53
|
+
offset: number;
|
|
54
|
+
expressionOffset: number;
|
|
55
|
+
}[];
|
|
56
|
+
/**
|
|
57
|
+
* The template bindings of the Angular components of a script: `@Component({ template })` or `templateUrl`, which
|
|
58
|
+
* `readTemplate` reads (relative to the script).
|
|
59
|
+
*/
|
|
60
|
+
export declare function analyzeAngular(file: string, code: string, readTemplate: (path: string) => string | undefined): RunicHandlerBinding[];
|
|
61
|
+
interface SvelteCompiler {
|
|
62
|
+
parse(source: string, options: {
|
|
63
|
+
modern: true;
|
|
64
|
+
filename?: string;
|
|
65
|
+
}): Record<string, unknown>;
|
|
66
|
+
}
|
|
67
|
+
/** The event bindings of a Svelte 5 component (`onclick={…}`, `on:click={…}`), at the element's `<`. */
|
|
68
|
+
export declare function analyzeSvelte(file: string, code: string, compiler: SvelteCompiler): RunicHandlerBinding[];
|
|
69
|
+
interface VueBlock {
|
|
70
|
+
readonly content: string;
|
|
71
|
+
readonly lang?: string;
|
|
72
|
+
readonly loc: {
|
|
73
|
+
readonly start: {
|
|
74
|
+
readonly offset: number;
|
|
75
|
+
};
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
interface VueTemplateNode {
|
|
79
|
+
readonly type: number;
|
|
80
|
+
readonly tag?: string;
|
|
81
|
+
readonly loc: {
|
|
82
|
+
readonly start: {
|
|
83
|
+
readonly offset: number;
|
|
84
|
+
};
|
|
85
|
+
};
|
|
86
|
+
readonly props?: readonly {
|
|
87
|
+
readonly type: number;
|
|
88
|
+
readonly name: string;
|
|
89
|
+
readonly arg?: {
|
|
90
|
+
readonly content?: string;
|
|
91
|
+
readonly isStatic?: boolean;
|
|
92
|
+
};
|
|
93
|
+
readonly exp?: {
|
|
94
|
+
readonly content: string;
|
|
95
|
+
readonly loc: {
|
|
96
|
+
readonly start: {
|
|
97
|
+
readonly offset: number;
|
|
98
|
+
};
|
|
99
|
+
};
|
|
100
|
+
};
|
|
101
|
+
}[];
|
|
102
|
+
readonly children?: readonly VueTemplateNode[];
|
|
103
|
+
readonly branches?: readonly VueTemplateNode[];
|
|
104
|
+
}
|
|
105
|
+
interface VueCompiler {
|
|
106
|
+
parse(source: string, options: {
|
|
107
|
+
filename: string;
|
|
108
|
+
sourceMap: false;
|
|
109
|
+
}): {
|
|
110
|
+
descriptor: {
|
|
111
|
+
template: {
|
|
112
|
+
ast?: VueTemplateNode;
|
|
113
|
+
lang?: string;
|
|
114
|
+
} | null;
|
|
115
|
+
script: VueBlock | null;
|
|
116
|
+
scriptSetup: VueBlock | null;
|
|
117
|
+
};
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
/** The `v-on` bindings of a Vue single-file component, at the element's `<`. */
|
|
121
|
+
export declare function analyzeVue(file: string, code: string, compiler: VueCompiler): RunicHandlerBinding[];
|
|
122
|
+
/** Whether a file may be analyzed: a frontend source file below `root`, outside `node_modules`. */
|
|
123
|
+
export declare function mayAnalyze(file: string, root: string): boolean;
|
|
124
|
+
/**
|
|
125
|
+
* Analyzes files on request, each again only when it (or an Angular component's template) changed. The Svelte and Vue
|
|
126
|
+
* compilers are the application's own (`svelte/compiler`, `vue/compiler-sfc`), loaded from `root`.
|
|
127
|
+
*/
|
|
128
|
+
export declare function createHandlerAnalyzer(root: () => string): (file: string) => Promise<RunicHandlerAnalysis | undefined>;
|
|
129
|
+
/**
|
|
130
|
+
* `file` as the analyzer takes it: an absolute path below `root` as it is, a `/@fs/` URL path, a root-relative URL
|
|
131
|
+
* path (`/src/App.tsx`), or a path relative to `root` (`src/app/counter.ts`, as Angular's debug info names it).
|
|
132
|
+
*/
|
|
133
|
+
export declare function handlerFile(value: string, root: string): string;
|
|
134
|
+
/**
|
|
135
|
+
* Answers `GET /__runic/handlers?file=…` with the file's analysis: for a page of this server on this machine or a
|
|
136
|
+
* client the allow list admits (access.ts), and a
|
|
137
|
+
* frontend source file below the root (not `node_modules`); 404 otherwise.
|
|
138
|
+
*/
|
|
139
|
+
export declare function answerHandlers(request: IncomingMessage, response: ServerResponse, analyze: (file: string) => Promise<RunicHandlerAnalysis | undefined>, root: string, access?: AccessList): Promise<void>;
|
|
140
|
+
export {};
|