@runic-artifex/vite-plugin-runic 0.18.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/README.md
CHANGED
|
@@ -19,15 +19,25 @@ omit the plugin entirely. A Runic Views frontend needs neither: its page loads
|
|
|
19
19
|
`base: "./"` builds one page for Runic Desktop and CS-WebUI. The Views build
|
|
20
20
|
passes the host it builds for as `RUNIC_APPLICATION_HOST` for a configuration
|
|
21
21
|
that still differs per host. The optional
|
|
22
|
-
`@vitejs/devtools` peer enables the Runic
|
|
23
|
-
|
|
24
|
-
or
|
|
22
|
+
`@vitejs/devtools` peer enables the Runic panel of the Vite DevTools dock (in
|
|
23
|
+
this README, "the dock"; not the browser's own developer tools, which open with
|
|
24
|
+
F12 or Inspect): register `DevTools()` in your Vite configuration, as the
|
|
25
|
+
`runic-app` template's Vite starters do. The plugin runs on Node 24.18 or later
|
|
26
|
+
24.x, or Node 26.
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { defineConfig } from "vite";
|
|
30
|
+
import { DevTools } from "@vitejs/devtools";
|
|
31
|
+
import { runic } from "@runic-artifex/vite-plugin-runic";
|
|
32
|
+
|
|
33
|
+
export default defineConfig({ plugins: [runic(), DevTools()] });
|
|
34
|
+
```
|
|
25
35
|
|
|
26
36
|
`devtools` takes `true`, `false` or `"auto"`. `"auto"` is the default and the
|
|
27
37
|
same as omitting the option: the development client is injected while serving,
|
|
28
38
|
and the Runic dock appears when `DevTools()` is registered. `true` also requires
|
|
29
39
|
`DevTools()`: serving without it fails with
|
|
30
|
-
[`RUNICP007`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
40
|
+
[`RUNICP007`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/docs/diagnostics.md#runicp007).
|
|
31
41
|
`false` turns off both the dock and the development client.
|
|
32
42
|
`maxTimelineEntries` sets how many timeline entries the dock keeps: 200 by
|
|
33
43
|
default, rounded down and limited to 1 to 500.
|
|
@@ -87,7 +97,7 @@ or large states are shown shallower. It is part of `/__runic/state` (`views`)
|
|
|
87
97
|
and of the copied diagnostic state, which hold no failures.
|
|
88
98
|
|
|
89
99
|
A command that the Bridge answered `superseded` (a
|
|
90
|
-
[command scoped to its page](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
100
|
+
[command scoped to its page](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../views/README.md#scoped-commands) called from an earlier page)
|
|
91
101
|
resolves like one that ran, so the page shows nothing. The client reports it
|
|
92
102
|
as a timeline entry (`kind: "command"`, label `<member> superseded`,
|
|
93
103
|
`detail.code: "superseded"` with the route, member, the epoch it was issued for
|
|
@@ -97,7 +107,490 @@ commands** card. With the Angular CLI, read both from `/__runic/state`.
|
|
|
97
107
|
The inspector runs only where the development client does: never in a build.
|
|
98
108
|
`@runic-artifex/views` reports to it only once the client asked for it
|
|
99
109
|
(`runic.views.inspector` in the
|
|
100
|
-
[shared globals](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
110
|
+
[shared globals](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/specs/application/README.md#shared-globals)).
|
|
111
|
+
|
|
112
|
+
### Bridge calls in the Performance panel
|
|
113
|
+
|
|
114
|
+
With `@runic-artifex/views` 0.20 or later the development client also listens
|
|
115
|
+
to the Bridge-call channel (`runic.views.calls`). It draws each settled call
|
|
116
|
+
on a **Bridge calls** track in a **Runic** track group of a Chromium engine's
|
|
117
|
+
Performance recording (turn on "Show custom tracks"), and its listening turns
|
|
118
|
+
on the async stack segments that lead from a reply back to the click that made
|
|
119
|
+
the call. See
|
|
120
|
+
[Bridge calls in the browser's developer tools](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../views/README.md#bridge-calls-in-the-browsers-developer-tools).
|
|
121
|
+
The dock lists the same calls with their C# handlers (next section).
|
|
122
|
+
Only the
|
|
123
|
+
[development build](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../views/README.md#development-build) of
|
|
124
|
+
`@runic-artifex/views` reports calls, which `vite dev` resolves; `vite build`
|
|
125
|
+
bundles the production build, which has no reporting code. A .NET host in Development names each call's C#
|
|
126
|
+
handler and its duration, which the client lists on the call's entry and draws
|
|
127
|
+
on a **C# handlers** track below it.
|
|
128
|
+
|
|
129
|
+
### OTLP export of the page's spans
|
|
130
|
+
|
|
131
|
+
While serving, the plugin exports a span per Bridge call to an OTLP/HTTP
|
|
132
|
+
endpoint, so the page's call, the .NET `runic.bridge.*` span and the
|
|
133
|
+
ViewModel's own spans form one trace. It is on when `OTEL_EXPORTER_OTLP_ENDPOINT`
|
|
134
|
+
or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` is set in the development server's
|
|
135
|
+
environment (and off with `OTEL_SDK_DISABLED=true` or `OTEL_TRACES_EXPORTER=none`):
|
|
136
|
+
the development client then gives each call a W3C trace context, which its
|
|
137
|
+
requests carry to .NET, and sends the settled call to the development server,
|
|
138
|
+
which posts it as OTLP/JSON. The page loads no OpenTelemetry code and posts
|
|
139
|
+
nothing cross-origin; a production build contains none of it.
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
runic({ otlp: false }); // never
|
|
143
|
+
runic({ otlp: { url: "http://localhost:4318/v1/traces", serviceName: "notes-page" } });
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`url` is the full traces URL; `headers` defaults to `OTEL_EXPORTER_OTLP_HEADERS`,
|
|
147
|
+
and `serviceName` to `OTEL_SERVICE_NAME`, or else the root's package name, with
|
|
148
|
+
`-page` appended. [Tracing Bridge calls](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../../../docs/tracing.md) sets it up
|
|
149
|
+
with the Aspire dashboard.
|
|
150
|
+
|
|
151
|
+
### Bridge call timeline in the dock
|
|
152
|
+
|
|
153
|
+
The client also sends each settled call to the development server, and the
|
|
154
|
+
dock's **Bridge calls** card shows the latest 20, the newest first:
|
|
155
|
+
|
|
156
|
+
```text
|
|
157
|
+
command EditorViewModel.save → SaveAsync() 23 ms
|
|
158
|
+
C# 21 ms · revision 4 · EditorViewModel.cs:42 · 2026-11-15T10:12:03.120Z
|
|
159
|
+
[Open SaveAsync()]
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
- **The call.** Its kind (`command`, `set`, `write`, `can`, `region`,
|
|
163
|
+
`operation`, `query`), the C# ViewModel and the member, and how long the page
|
|
164
|
+
waited from the call to its settled reply. A call that did not end `ok` adds
|
|
165
|
+
its outcome and reason, such as `· cancelled (superseded)` or
|
|
166
|
+
`· error (domain-failed)`.
|
|
167
|
+
- **The C# handler.** The plugin looks the call up in the
|
|
168
|
+
[source map](#source-map-and-open-in-editor): `SaveAsync()` for a command's
|
|
169
|
+
`[RelayCommand]` method, `Title.set` for a setter. The button opens it in the
|
|
170
|
+
editor (see [the dock's open action](#the-docks-open-action)). Without a map (no build yet, or
|
|
171
|
+
`sourceMap: false`) the row has no handler.
|
|
172
|
+
- **The handler's own duration.** When the reply carries .NET's timing of the
|
|
173
|
+
handler (a .NET host in Development that measures it), the second line
|
|
174
|
+
starts with `C# <n> ms`, and the call's `handlerDuration` holds it; without it
|
|
175
|
+
the row shows the page's duration only.
|
|
176
|
+
- **Failures.** A failed call shows .NET's exception (the development detail of
|
|
177
|
+
the error reply) and a button for each stack frame in a file of the source
|
|
178
|
+
map, which opens that line, such as `EditorViewModel.SaveAsync() ·
|
|
179
|
+
EditorViewModel.cs:12`. Other frames stay text on the **Last failure** card,
|
|
180
|
+
which links the same frames.
|
|
181
|
+
- **Bounds and privacy.** The server keeps as many calls as timeline entries
|
|
182
|
+
(`maxTimelineEntries`, 200 by default). What the page sends is checked like a
|
|
183
|
+
timeline entry: names and routes of a fixed shape, finite durations, and the
|
|
184
|
+
failure under the failure rules (bounded, credential values redacted). The
|
|
185
|
+
handler comes from the server's own map, and an entry names it by the map's
|
|
186
|
+
member id and the file's name, never a path. `/__runic/state` has the calls
|
|
187
|
+
(`calls`, typed `RunicBridgeCall`) without failures, like the timeline.
|
|
188
|
+
|
|
189
|
+
Under `dotnet runic dev` the window's document is the .NET host's page, which
|
|
190
|
+
loads Vite's modules from Vite's origin, so the dock's own loader (a script
|
|
191
|
+
that loads `/__devtools/embedded.js` relative to the document) finds nothing.
|
|
192
|
+
The development client is one of Vite's modules, so it loads the dock from
|
|
193
|
+
Vite's origin whenever the document's scripts did not; with `html: false`
|
|
194
|
+
(SvelteKit) it always does, and `runic()` removes the dock's HTML hook, which
|
|
195
|
+
SvelteKit would warn about. The first time a page opens the dock, the dock asks
|
|
196
|
+
for the one-time code that Vite DevTools prints in the development server's
|
|
197
|
+
output (shown by `dotnet runic dev`); keep that check on, as it is what keeps
|
|
198
|
+
other pages of this machine out of the dock.
|
|
199
|
+
|
|
200
|
+
## Source map and open in editor
|
|
201
|
+
|
|
202
|
+
The Bridge generator writes a development source map beside its generated C#
|
|
203
|
+
in `obj` (`obj/<Configuration>/<TargetFramework>/runic-bridge/sources.json`).
|
|
204
|
+
It lists every ViewModel with a generated Bridge and every member its client
|
|
205
|
+
and the Bridge frames name, with the C# that runs for it and where it is.
|
|
206
|
+
`vite dev` serves it at `/__runic/sources`, and `/__runic/open` opens one of
|
|
207
|
+
its locations in your editor. The map never enters the generated TypeScript,
|
|
208
|
+
a `vite build` or a package: production output is the same with and without
|
|
209
|
+
it.
|
|
210
|
+
|
|
211
|
+
```jsonc
|
|
212
|
+
// GET /__runic/sources
|
|
213
|
+
{
|
|
214
|
+
"format": "runic-bridge-sources/1",
|
|
215
|
+
"viewModels": [{
|
|
216
|
+
"id": "Demo.CounterViewModel", "name": "Counter", "route": "counter",
|
|
217
|
+
"contract": "Demo.CounterViewModel:EE06…", "pageKinds": ["counter"],
|
|
218
|
+
"symbol": "Demo.CounterViewModel",
|
|
219
|
+
"location": { "file": "/src/Demo/CounterViewModel.cs", "line": 6, "column": 29 }
|
|
220
|
+
}],
|
|
221
|
+
"members": [{
|
|
222
|
+
"id": "Demo.CounterViewModel/command/increment", "viewModel": "Demo.CounterViewModel",
|
|
223
|
+
"member": "increment", "kind": "command",
|
|
224
|
+
"symbol": "Demo.CounterViewModel.Increment()", "property": "Demo.CounterViewModel.IncrementCommand",
|
|
225
|
+
"location": { "file": "/src/Demo/CounterViewModel.cs", "line": 18, "column": 18 }
|
|
226
|
+
}]
|
|
227
|
+
}
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
- **Lookup.** A ViewModel's `id` is the part of a generated client's contract
|
|
231
|
+
before the colon, and `route` is the route `connect<Name>()` connects. A
|
|
232
|
+
member's `id` is `{viewModel}/{kind}/{member}`, where `member` is the name the
|
|
233
|
+
client and the Bridge frames use (`count`, `increment`), and `kind` is one of
|
|
234
|
+
`state` (read through the getter), `setter` (`set…` and `write…`, through the
|
|
235
|
+
setter), `command` (located at its handler: the `[RelayCommand]` method, a
|
|
236
|
+
method group the command is created from, such as
|
|
237
|
+
`ReactiveCommand.CreateFromTask(SaveAsync)`, or else the line that creates
|
|
238
|
+
it), `commandState` (`canSave` and other state a command adds), `interaction`
|
|
239
|
+
and `request`. The TypeScript types are exported as `RunicSourceMap`,
|
|
240
|
+
`RunicSourceMember` and `RunicSourceLocation`.
|
|
241
|
+
- **Locations.** A location is `{ file, line, column }`: the absolute path of a
|
|
242
|
+
local source file and a 1-based line and column, as in a compiler
|
|
243
|
+
diagnostic. They come from the application assembly's portable PDB (the
|
|
244
|
+
default), then from the source of members a source generator writes, such as
|
|
245
|
+
a CommunityToolkit `[ObservableProperty]`. A method is located at its name and
|
|
246
|
+
an accessor at its `get` or `set`, not at the first statement the PDB
|
|
247
|
+
records, so a Debug and a Release build give the same map. Without a PDB or source file an
|
|
248
|
+
entry has no `location`; the build does not fail. A map is as current as the
|
|
249
|
+
last build: `dotnet watch`, and so `dotnet runic dev`, rebuilds it after a C#
|
|
250
|
+
edit, and the plugin reads it again when the file changes.
|
|
251
|
+
- **Where the plugin finds it.** `dotnet runic dev` passes the map's path in
|
|
252
|
+
`RUNIC_APPLICATION_DEV_SOURCE_MAP`. Otherwise, or when that file does not
|
|
253
|
+
exist, the plugin takes the newest `runic-bridge/sources.json` under `obj` of
|
|
254
|
+
the project `dotnet runic dev` runs, else of the Vite root or its parent (the
|
|
255
|
+
project of a `Frontend/` directory). `runic({ sourceMap:
|
|
256
|
+
"../obj/Debug/net10.0/runic-bridge/sources.json" })` names the file, or a
|
|
257
|
+
directory to search, relative to the Vite root. `sourceMap: false` reads no
|
|
258
|
+
map: `/__runic/sources` is gone, and `/__runic/open` opens only frontend
|
|
259
|
+
files. Without a map `/__runic/sources` answers 404.
|
|
260
|
+
- **Opening.** `POST /__runic/open` with `{ "id": "<entry id>" }`, or with
|
|
261
|
+
`{ "file", "line", "column" }` in a file of an entry (`column` defaults to 1;
|
|
262
|
+
a .NET stack frame's line) or in a frontend file Vite serves to the page
|
|
263
|
+
(`server.fs.allow`, without `server.fs.deny`; an absolute, normalized path,
|
|
264
|
+
such as a component that [Runic Inspect](#runic-inspect) links to), opens that
|
|
265
|
+
location with [launch-editor](https://github.com/vitejs/launch-editor), the
|
|
266
|
+
package behind Vite's own editor launcher (`LAUNCH_EDITOR`, else a running
|
|
267
|
+
editor such as VS Code or a JetBrains IDE like Rider, else
|
|
268
|
+
`VISUAL`/`EDITOR`), and answers 200. It is meant for the page and
|
|
269
|
+
other development tools:
|
|
270
|
+
|
|
271
|
+
```ts
|
|
272
|
+
await fetch("/__runic/open", {
|
|
273
|
+
method: "POST",
|
|
274
|
+
headers: { "Content-Type": "application/json" },
|
|
275
|
+
body: JSON.stringify({ id: "Demo.CounterViewModel/command/increment" }),
|
|
276
|
+
});
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
- **What it refuses.** Vite's `/__open-in-editor` opens any path; the Runic
|
|
280
|
+
action opens only a file the map lists or a frontend file Vite serves (with
|
|
281
|
+
`server.fs.strict: false`, any file, as Vite then serves any), at a positive
|
|
282
|
+
line and column, and only while the file exists, so a page cannot open
|
|
283
|
+
anything else. It answers a POST of JSON (415 otherwise)
|
|
284
|
+
from a page of the development server's own origin (`Origin` and
|
|
285
|
+
`Sec-Fetch-Site`; a cross-origin page cannot send JSON without a CORS
|
|
286
|
+
preflight, which it never grants) and from this machine (a loopback client
|
|
287
|
+
address), else 403; an id or file the map does not list, an entry
|
|
288
|
+
without a location, and a file that no longer exists answer 404. The map
|
|
289
|
+
itself answers only same-origin requests from this machine too, unless
|
|
290
|
+
other machines are allowed ([Runic Inspect from another machine](#runic-inspect-from-another-machine));
|
|
291
|
+
the open action stays loopback-only, as it launches the editor on this
|
|
292
|
+
machine.
|
|
293
|
+
- **Only development servers.** Both endpoints exist only on the development
|
|
294
|
+
server (`vite dev`, and `ng serve` through `runicDevSessionProxy()`), not in
|
|
295
|
+
`vite build` or `vite preview`.
|
|
296
|
+
|
|
297
|
+
### The dock's open action
|
|
298
|
+
|
|
299
|
+
The dock's open buttons call the `runic:open-in-editor` Vite DevTools action
|
|
300
|
+
with `{ id }` or a stack frame's `{ file, line }`. It decides what may open
|
|
301
|
+
exactly as `/__runic/open` does (`resolveOpenLocation`: a location in a file
|
|
302
|
+
the current map lists, while the file exists) and refuses everything else,
|
|
303
|
+
launching nothing. Then it opens the location with
|
|
304
|
+
[launch-editor](https://github.com/vitejs/launch-editor) 2.14.2 itself, the
|
|
305
|
+
package behind Vite's `/__open-in-editor`, so the editor is chosen the same
|
|
306
|
+
way (`LAUNCH_EDITOR`, a running editor, `VISUAL`/`EDITOR`). The action makes
|
|
307
|
+
no HTTP request: only clients that Vite DevTools trusts (its one-time code)
|
|
308
|
+
can call an action, which takes the place of the endpoint's origin checks.
|
|
309
|
+
With `sourceMap: false` it opens nothing. It does not open frontend files:
|
|
310
|
+
the dock links only what the map lists.
|
|
311
|
+
|
|
312
|
+
## Runic Inspect
|
|
313
|
+
|
|
314
|
+
**Runic Inspect** is a select mode of the development client: press
|
|
315
|
+
**Alt+Shift+X** in the page (or call `toggle()`, below), hover an element to
|
|
316
|
+
outline it, and click it to see how it is connected. The selecting click
|
|
317
|
+
reaches no handler of the page: while the mode is on, a transparent layer of
|
|
318
|
+
the overlay takes every pointer event, and the window's capture phase stops
|
|
319
|
+
them. **Esc** or Alt+Shift+X turns it off. The overview shows:
|
|
320
|
+
|
|
321
|
+
- **Component**: the element's framework component and the components around
|
|
322
|
+
it, from each framework's own development metadata, with an editor link:
|
|
323
|
+
|
|
324
|
+
| Framework | What it shows |
|
|
325
|
+
| --- | --- |
|
|
326
|
+
| React 19 | The component and its owners from the element's fiber, and the file:line of the element's JSX: the fiber's `_debugStack` frame resolved through the served module's source map. |
|
|
327
|
+
| Svelte 5 | The component and the file:line:column of the element (`__svelte_meta`). |
|
|
328
|
+
| Vue 3 | The component (`__vueParentComponent`) and its file (`__file`, from the SFC compiler), without a line. |
|
|
329
|
+
| Angular 17.1+ | The component class (`ng.getComponent`/`ng.getOwningComponent`) and, with the compiler's debug info, its file:line (`ɵcmp.debugInfo`). |
|
|
330
|
+
|
|
331
|
+
- **Commands**: the commands the element calls, each with its C# handler (such
|
|
332
|
+
as the `[RelayCommand]` method) and file:line from the
|
|
333
|
+
[source map](#source-map-and-open-in-editor), how often the element called
|
|
334
|
+
it, and its availability state (`canSave`) when the ViewModel has one.
|
|
335
|
+
- **ViewModel members**: the members the element sets (`set…`/`write…`, with
|
|
336
|
+
the C# setter), and state members whose value is the element's text or a
|
|
337
|
+
form control's value, each with its current value and C# member. A value
|
|
338
|
+
match is marked as such: it is a match, not proof.
|
|
339
|
+
- **ViewModels** the element is connected to, with the C# class.
|
|
340
|
+
- **Recent Bridge calls** the element made: kind, member, duration, outcome and
|
|
341
|
+
the reply's revision.
|
|
342
|
+
- **Texts from the ViewModel**: text references (`TextReference` members) the
|
|
343
|
+
element shows, with their catalog, key, locale and arguments.
|
|
344
|
+
- **Messages**: the messages of generated `m.*()` calls the element shows, in
|
|
345
|
+
its text or in an attribute (`title`, `aria-label`, `placeholder`, `alt`, an
|
|
346
|
+
input's value), each with its catalog, key, locale, its text as authored and
|
|
347
|
+
the `.rmf2`/`.mf2` file:line that defines it, and **Edit**, which edits its
|
|
348
|
+
text in every locale in place. See
|
|
349
|
+
[Messages of `m.*()` calls](#messages-of-m-calls) and
|
|
350
|
+
[Edit a translation on the page](#edit-a-translation-on-the-page).
|
|
351
|
+
|
|
352
|
+
C# locations and frontend files open in your editor through
|
|
353
|
+
[`/__runic/open`](#source-map-and-open-in-editor): a C# location by its source
|
|
354
|
+
map id, a frontend file by its path, which the endpoint opens only when Vite
|
|
355
|
+
serves that file to the page. Runic Inspect does not use Vite's
|
|
356
|
+
`/__open-in-editor`, which opens any path for any page.
|
|
357
|
+
|
|
358
|
+
**Under `dotnet runic dev`** the window's document is the .NET host's page,
|
|
359
|
+
which loads Vite's modules from Vite's origin, so a relative URL such as
|
|
360
|
+
`/__runic/sources` names the host. Runic Inspect therefore asks the Vite server
|
|
361
|
+
over the development client's HMR connection instead of HTTP: a
|
|
362
|
+
`runic:request` event (`{ id, kind }` with `kind` `sources`, `handlers` with a
|
|
363
|
+
`file`, `message` with a `target` `{ catalog, key }`, or `open` with a
|
|
364
|
+
`target`), answered by `runic:response` with the same id. The server answers
|
|
365
|
+
as `/__runic/sources`, `/__runic/handlers`, the Translations message API and
|
|
366
|
+
`/__runic/open` do, with the same decision of what opens and the same access
|
|
367
|
+
rules, judged per request from the connection's address (Vite reports it):
|
|
368
|
+
`sources`, `handlers` and `message` for this machine and the hosts and
|
|
369
|
+
networks `allow` and `RUNIC_DEV_ALLOW` admit, `open` for this machine only
|
|
370
|
+
(403 otherwise). Vite admits that connection only with the token in its own client
|
|
371
|
+
module, which only the page's origins Vite's CORS allows can read (by default
|
|
372
|
+
`localhost`, `127.0.0.1` and `[::1]`, the .NET host's page among them), so it
|
|
373
|
+
needs no CORS rule of its own. Without an HMR connection (the Angular CLI, or
|
|
374
|
+
a page that loads the client without Vite's HMR) Inspect uses the HTTP
|
|
375
|
+
endpoints, which also serve tools such as `curl`.
|
|
376
|
+
|
|
377
|
+
**Before the first click.** The development server reads the element's
|
|
378
|
+
component file and finds which of its event handlers reach which client call:
|
|
379
|
+
directly (`client.save()`, `client.command("save")`), through Runic's helpers
|
|
380
|
+
(`useCommand`, `useOperation`, `injectCommand`, `injectOperation`), or through
|
|
381
|
+
other declarations of the same file (a function, a variable, a destructured
|
|
382
|
+
`run`, a class method, `this.x`). The overview lists the calls that are
|
|
383
|
+
commands of a ViewModel in the [source map](#source-map-and-open-in-editor),
|
|
384
|
+
with the C# handler, "from the source, not called yet", and a link to the
|
|
385
|
+
line that calls the client:
|
|
386
|
+
|
|
387
|
+
```tsx
|
|
388
|
+
const increment = useCommand(() => client?.increment()); // ← found here
|
|
389
|
+
return <button onClick={() => void increment.run()}>Increment</button>;
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
| Framework | Handlers read | How the element is found |
|
|
393
|
+
| --- | --- | --- |
|
|
394
|
+
| React (JSX/TSX) | `onClick={…}` and every other `on…` prop, of elements and components | The element's JSX line (`_debugStack`); for a `<button onClick={props.onClick}>`, the `<Button onClick={…}>` around it |
|
|
395
|
+
| Vue 3 (SFC) | `@click`/`v-on:click` in the template, with `<script setup>` and the Options API (`methods`, `setup()`) | The element's compiled listeners (`$setup.increment()`), else its component's only binding of the event |
|
|
396
|
+
| Svelte 5 | `onclick={…}` and `on:click={…}`, of elements and components | The element's file, line and column (`__svelte_meta`), then the component tags around it |
|
|
397
|
+
| Angular 17.1+ | `(click)="…"` in `template` and `templateUrl` files, with the class's fields and methods | The component file (`ɵcmp.debugInfo`) and `ng.getListeners`: the template's binding of the event and tag, by its order when there are several |
|
|
398
|
+
|
|
399
|
+
Svelte and Vue files are read with the application's own `svelte/compiler`
|
|
400
|
+
and `vue/compiler-sfc`, scripts with Vite's parser. Served modules are not
|
|
401
|
+
changed: the analysis answers `GET /__runic/handlers?file=…` for pages of this
|
|
402
|
+
machine, for frontend source files below the Vite root (not `node_modules`).
|
|
403
|
+
|
|
404
|
+
What it does not see, so the command is learned on first click:
|
|
405
|
+
|
|
406
|
+
- calls in other files: a store, a service, a custom hook or a function
|
|
407
|
+
imported from another module. The overview names the import
|
|
408
|
+
(`saveAll from ./store`);
|
|
409
|
+
- handlers that come from outside the component: a prop passed down several
|
|
410
|
+
components, a context, an event bus;
|
|
411
|
+
- elements that a template repeats with different handlers where the
|
|
412
|
+
framework does not say which one it is: an Angular `@for` with listeners that
|
|
413
|
+
differ per item, a Vue listener whose compiled code is the method itself
|
|
414
|
+
(`@click="save"`) when the component has several such bindings;
|
|
415
|
+
- render functions (`h("button", { onClick })`) and Vue JSX.
|
|
416
|
+
|
|
417
|
+
**On first click.** The development client also listens to the Bridge-call
|
|
418
|
+
channel (`runic.views.calls`), whose `start` report arrives in the stack of
|
|
419
|
+
the code that made the call. The DOM event being dispatched names the element
|
|
420
|
+
(its `target`, so React's delegation to the root does not matter), and the
|
|
421
|
+
nearest button, link or form field is recorded as calling that member. A
|
|
422
|
+
command found this way is marked with its call count; it covers what the
|
|
423
|
+
source analysis does not see. Use the element once with the mode off, then
|
|
424
|
+
inspect it. A call that does not run during the event, such as a write a
|
|
425
|
+
field controller sends after its previous one finished, is not attributed.
|
|
426
|
+
|
|
427
|
+
**For agents and tests**, the development client puts an API on the page at
|
|
428
|
+
`globalThis[Symbol.for("runic.vite.inspect")]`:
|
|
429
|
+
|
|
430
|
+
```ts
|
|
431
|
+
const inspect = (globalThis as any)[Symbol.for("runic.vite.inspect")];
|
|
432
|
+
inspect.toggle(true); // select mode on, which marks m.*() text; returns whether it is on
|
|
433
|
+
const overview = await inspect.describe(document.querySelector("#save"));
|
|
434
|
+
// { element, component, viewModels, members, commands, calls, texts, messages, notes }
|
|
435
|
+
await inspect.select(document.querySelector("#save")); // shows the overview card
|
|
436
|
+
await inspect.open(overview.commands[0].location); // opens it in the editor
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
`describe(element)` resolves to JSON-safe data (the type is exported as
|
|
440
|
+
`RunicInspectDescription`); values are shortened, and `notes` says what the
|
|
441
|
+
overview cannot tell, such as a missing source map. `messages` is filled only
|
|
442
|
+
while select mode is on: call `toggle(true)` and let the page render once
|
|
443
|
+
before `describe`. With `chrome-devtools-mcp` or Playwright, evaluate it in
|
|
444
|
+
the page.
|
|
445
|
+
|
|
446
|
+
Runic Inspect is plain DOM in a shadow root, so it works in every engine
|
|
447
|
+
`dotnet runic dev` runs: an installed browser, WebView2, WKWebView and
|
|
448
|
+
WebKitGTK. It is part of the development client, which a build replaces with
|
|
449
|
+
an empty module: `vite build` output is byte-identical with and without it.
|
|
450
|
+
`runic({ inspect: false })` leaves it out of the client (with the translation
|
|
451
|
+
editor) and turns off `/__runic/handlers`. Under the Angular CLI, `runicDevSessionProxy()` answers
|
|
452
|
+
`/__runic/sources`, `/__runic/open` and `/__runic/handlers` too
|
|
453
|
+
([SvelteKit and Angular](#sveltekit-and-angular)), so the overview has the C#
|
|
454
|
+
handlers and the commands before the first click there as well.
|
|
455
|
+
|
|
456
|
+
### Messages of `m.*()` calls
|
|
457
|
+
|
|
458
|
+
A generated message function returns a plain string, so nothing in the page
|
|
459
|
+
says which message a text came from. Runic Inspect asks Runic Translations to
|
|
460
|
+
mark it, **only while select mode is on**:
|
|
461
|
+
|
|
462
|
+
- Turning select mode on calls `markers.set(true)` on the Translations
|
|
463
|
+
text-change channel (`globalThis[Symbol.for("runic.translations.text")]`).
|
|
464
|
+
The page renders its messages again, as on a language switch, and every
|
|
465
|
+
`m.*()` call puts an invisible marker in front of its text that names the
|
|
466
|
+
message. Turning select mode off renders the plain text again. Outside
|
|
467
|
+
select mode the page's text, `textContent`, copied text and tests see no
|
|
468
|
+
markers.
|
|
469
|
+
- The markers are invisible format characters that take no width, so the
|
|
470
|
+
layout does not change. While select mode is on they are also in attribute
|
|
471
|
+
values and anything else the text went into; the overview strips them from
|
|
472
|
+
the element's text.
|
|
473
|
+
- For each message it finds, the overview asks the Translations dev server
|
|
474
|
+
for its source (`GET /__runic-translations/message`, or over Vite's
|
|
475
|
+
connection as above, where the server asks it), and its link opens it
|
|
476
|
+
through `/__runic/open` with `{ "message": { catalog, key, locale } }`. The
|
|
477
|
+
open action never takes a path for a message: it asks the same API and
|
|
478
|
+
opens only the `.rmf2`/`.mf2` source it names.
|
|
479
|
+
|
|
480
|
+
It needs `@runic-artifex/vite-plugin-runic-translations` 0.12 or later under
|
|
481
|
+
`vite dev` (the markers, and in project mode with in-page editing on, the
|
|
482
|
+
source locations), and text helpers that render again on the text-change
|
|
483
|
+
channel: `useTextLocale` in React and Vue, Svelte's `useTextLocale` or
|
|
484
|
+
`useMessageLocale`, Angular's `textLocaleSignal`, as for a language switch. A
|
|
485
|
+
component that does not render again, or a value computed once (such as
|
|
486
|
+
`document.title`), keeps its text unmarked. Text formatted from a ViewModel's
|
|
487
|
+
text reference is listed under **Texts from the ViewModel** instead. With an
|
|
488
|
+
earlier plugin, the overview has no messages and its notes say why.
|
|
489
|
+
|
|
490
|
+
### Edit a translation on the page
|
|
491
|
+
|
|
492
|
+
Select a text in Runic Inspect and press **Edit** next to its message. The
|
|
493
|
+
panel below the overview reads the message from Runic Translations' in-page
|
|
494
|
+
editing API (`GET /__runic-translations/message`) and shows:
|
|
495
|
+
|
|
496
|
+
- a **locale** list, base locale first, starting with the locale the page
|
|
497
|
+
shows; a locale without text of its own is marked `(missing)`, and saving it
|
|
498
|
+
adds the message beside the base locale's;
|
|
499
|
+
- where the locale's text is defined (`translations/de.rmf2:4`), and for a
|
|
500
|
+
library's text, the application override a save writes instead;
|
|
501
|
+
- its **structure**: the inputs (`$count :integer`), what it selects on
|
|
502
|
+
(`$count (plural): one · *`), the locale's plural categories, with the ones
|
|
503
|
+
that have no variant, and the markup it uses (`{#strong}`);
|
|
504
|
+
- the **MF2 source** of that locale, exactly as authored: declarations,
|
|
505
|
+
`.match` and its variants, placeholders and markup. Plural, selector, markup
|
|
506
|
+
and document messages are edited as their whole source.
|
|
507
|
+
|
|
508
|
+
**Save** (or Ctrl+Enter, ⌘+Enter) posts the text with the hash of the file it
|
|
509
|
+
was read from. Runic Translations compiles it with the rest of the catalog and
|
|
510
|
+
writes it with the Translations Editor's source-preserving writer: only that
|
|
511
|
+
entry changes, and the file keeps its comments, formatting and order. The dev
|
|
512
|
+
server then updates the page **in place**, as for a save in an editor: no
|
|
513
|
+
reload, the page keeps its state, and the card keeps its selection and
|
|
514
|
+
describes the element again with the new text. Each locale keeps its own
|
|
515
|
+
unsaved text while you switch between them. There is no separate preview: the
|
|
516
|
+
page itself shows the saved text.
|
|
517
|
+
|
|
518
|
+
- **The text does not compile** (422): the panel lists the RTR diagnostics
|
|
519
|
+
with their lines, keeps your text, and nothing is written.
|
|
520
|
+
- **The file changed since it was read** (409), for example saved in an
|
|
521
|
+
editor: the panel shows the text in the file now. **Reapply my text** keeps
|
|
522
|
+
your text and saves it over the current file; **Use the file's text** drops
|
|
523
|
+
your edit. When the page's text changes and you have not edited the locale,
|
|
524
|
+
the panel reads the message again on its own.
|
|
525
|
+
- **Not allowed** (403): the panel says how to allow this machine (below).
|
|
526
|
+
|
|
527
|
+
The panel is plain DOM in the overlay's shadow root, so it works in every
|
|
528
|
+
engine `dotnet runic dev` runs. Tab moves through the locale list, the text,
|
|
529
|
+
Save and Revert; **Esc** in the panel closes it and returns to its Edit button.
|
|
530
|
+
Typing in it does not reach the page's own key handlers. Selecting another
|
|
531
|
+
element closes the panel unless it has unsaved text.
|
|
532
|
+
|
|
533
|
+
It needs `@runic-artifex/vite-plugin-runic-translations` 0.12 or later in
|
|
534
|
+
project mode (the `project` option), with `inPageEditing` on, which is the
|
|
535
|
+
default under `vite dev`. Without it, the overview lists messages without
|
|
536
|
+
**Edit**.
|
|
537
|
+
|
|
538
|
+
### Runic Inspect from another machine
|
|
539
|
+
|
|
540
|
+
The development server can serve a page to another machine: a laptop on the
|
|
541
|
+
same [Tailscale](https://tailscale.com/kb/1015/100.x-addresses) network, or
|
|
542
|
+
the browser of a laptop that shows a page of a dev server an agent runs on a
|
|
543
|
+
local server. Start Vite on a reachable address (`server.host`, `vite --host`)
|
|
544
|
+
and name the machines that may use Runic Inspect's data there:
|
|
545
|
+
|
|
546
|
+
```sh
|
|
547
|
+
RUNIC_DEV_ALLOW="100.64.0.0/10, fd7a:115c:a1e0::/48" vite dev --host
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
```ts
|
|
551
|
+
runic({ allow: ["100.64.0.0/10", "192.168.1.20", "laptop.tailnet.ts.net"] })
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
Entries are IPv4 or IPv6 addresses, CIDR networks, or host names (resolved
|
|
555
|
+
when a request arrives, and cached for 30 seconds); the environment variable
|
|
556
|
+
takes the same entries separated by commas or spaces and adds to the option.
|
|
557
|
+
An invalid entry stops the dev server with its name, and a non-empty list is
|
|
558
|
+
logged at start. `RUNIC_DEV_ALLOW` is one setting for both plugins: Runic
|
|
559
|
+
Translations' in-page editing API reads it too (its older
|
|
560
|
+
`RUNIC_TRANSLATIONS_EDIT_ALLOW` and `inPageEditing: { allow }` still work), so
|
|
561
|
+
the same variable lets that machine read the source map and handler analysis
|
|
562
|
+
and edit translations.
|
|
563
|
+
|
|
564
|
+
| Endpoint | Loopback | An allowed machine | Any other machine |
|
|
565
|
+
| --- | --- | --- | --- |
|
|
566
|
+
| `/__runic/sources`, `/__runic/handlers` | yes | yes | 403 |
|
|
567
|
+
| `/__runic-translations/message` (Runic Translations) | yes | yes | 403 |
|
|
568
|
+
| `/__runic/open` | yes | 403 | 403 |
|
|
569
|
+
|
|
570
|
+
`/__runic/open` launches an editor **on the development machine**, so it stays
|
|
571
|
+
loopback-only. A page opened from another machine (its address is not
|
|
572
|
+
`localhost`) shows file:line locations without links, and its notes say why.
|
|
573
|
+
When a machine is refused, the overview's notes name what was refused and the
|
|
574
|
+
setting that allows it.
|
|
575
|
+
|
|
576
|
+
**Security.**
|
|
577
|
+
|
|
578
|
+
- **Loopback by default.** Without a list, every endpoint answers only the
|
|
579
|
+
machine the dev server runs on (`127.0.0.0/8`, `::1`), judged by the TCP
|
|
580
|
+
connection's address; `X-Forwarded-For` and similar headers are ignored. A
|
|
581
|
+
reverse proxy on the same machine makes every client look like loopback.
|
|
582
|
+
- **Same origin.** A request must come from a page of the dev server itself
|
|
583
|
+
(`Sec-Fetch-Site`, `Origin`), so another site, or another dev server on a
|
|
584
|
+
different port, cannot read the data or write a translation. Vite's host check
|
|
585
|
+
(`server.allowedHosts`) runs first and refuses DNS-rebinding hosts; allow the
|
|
586
|
+
host names your other machines use there (IP addresses are allowed by
|
|
587
|
+
default).
|
|
588
|
+
- **Allow only machines you trust with your sources.** An allowed machine can
|
|
589
|
+
read the source map and the analysis of frontend files, and change the
|
|
590
|
+
catalog's translation sources.
|
|
591
|
+
- **Development only.** Nothing of it is in `vite build` or `vite preview`
|
|
592
|
+
output: the build is byte-identical with and without Runic Inspect, the
|
|
593
|
+
editor and the allow list.
|
|
101
594
|
|
|
102
595
|
## Component build target
|
|
103
596
|
|
|
@@ -114,7 +607,12 @@ export default defineConfig({
|
|
|
114
607
|
```
|
|
115
608
|
|
|
116
609
|
The entry's default export is the mount function of
|
|
117
|
-
[`@runic-artifex/views/component`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
610
|
+
[`@runic-artifex/views/component`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../views/README.md#components). With Angular,
|
|
611
|
+
the Analog plugin (`angular()`) compiles the component's code ahead of time as
|
|
612
|
+
it does the page's, and `runicComponentMount` of `@runic-artifex/angular/experimental`
|
|
613
|
+
is the mount function; it keeps Angular's component styles, which Angular adds
|
|
614
|
+
to the document at run time rather than to the build's CSS, in the shadow root
|
|
615
|
+
([Angular components](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../angular/README.md#components-experimental)). `vite build`
|
|
118
616
|
then builds every environment, as `vite build --app` does, and after them the
|
|
119
617
|
`runic_component` environment into `_runic_component/` of the build output:
|
|
120
618
|
|
|
@@ -158,6 +656,12 @@ a component's.
|
|
|
158
656
|
|
|
159
657
|
## SvelteKit and Angular
|
|
160
658
|
|
|
659
|
+
Angular built with Vite, through the Analog Angular plugin
|
|
660
|
+
(`plugins: [angular({ liveReload: true }), runic()]`), uses `runic()` as the other
|
|
661
|
+
frameworks do (`dotnet new runic-app --frontend angular --angular-build vite`);
|
|
662
|
+
see the [Angular package](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../angular/README.md#building-with-the-angular-cli-or-vite).
|
|
663
|
+
What follows covers SvelteKit and the Angular CLI.
|
|
664
|
+
|
|
161
665
|
SvelteKit renders its pages itself and warns about every plugin with a
|
|
162
666
|
`transformIndexHtml` hook. Use `runic({ html: false })`: the plugin then has no
|
|
163
667
|
such hook, injects nothing into HTML and leaves host scripts alone, and keeps
|
|
@@ -166,7 +670,7 @@ The page loads the client from its client hooks:
|
|
|
166
670
|
|
|
167
671
|
```ts
|
|
168
672
|
// vite.config.ts
|
|
169
|
-
plugins: [sveltekit({ adapter: runicAdapter() }), runic({ html: false })],
|
|
673
|
+
plugins: [sveltekit({ adapter: runicAdapter() }), runic({ html: false }), DevTools()],
|
|
170
674
|
```
|
|
171
675
|
|
|
172
676
|
```ts
|
|
@@ -174,6 +678,10 @@ plugins: [sveltekit({ adapter: runicAdapter() }), runic({ html: false })],
|
|
|
174
678
|
import "@runic-artifex/vite-plugin-runic/client";
|
|
175
679
|
```
|
|
176
680
|
|
|
681
|
+
With `DevTools()` registered the client loads the dock as well, and `runic()`
|
|
682
|
+
removes the dock's own HTML hook, which SvelteKit would warn about and never
|
|
683
|
+
run.
|
|
684
|
+
|
|
177
685
|
`html: false` cannot be combined with `desktop`, whose bootstrap is a script
|
|
178
686
|
tag in the HTML: `runic({ html: false, desktop: true })` throws.
|
|
179
687
|
|
|
@@ -204,7 +712,8 @@ the build cannot evaluate a function call.
|
|
|
204
712
|
The entries keep the development state in the `ng serve` process and answer:
|
|
205
713
|
|
|
206
714
|
- `/__runic/state` with that state, as `runic()` does: the connection, the
|
|
207
|
-
timeline
|
|
715
|
+
timeline and the Bridge calls (without C# handlers: the Angular CLI's server
|
|
716
|
+
reads no source map) without failures, and under `dotnet runic dev` the session header
|
|
208
717
|
([Dev session](#dev-session-and-host-scripts)). The answer is `200` with JSON; without `dotnet runic dev` the
|
|
209
718
|
entry answers too, without the header.
|
|
210
719
|
- `/__runic/diagnostics`, which the client posts its reports to. Each Views
|
|
@@ -217,9 +726,20 @@ The entries keep the development state in the `ng serve` process and answer:
|
|
|
217
726
|
at Notes.Editor.Save() in /src/Notes/Editor.cs:line 12
|
|
218
727
|
```
|
|
219
728
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
729
|
+
For [Runic Inspect](#runic-inspect), the entries also answer
|
|
730
|
+
`/__runic/sources` (the development source map, found as `runic()` finds it,
|
|
731
|
+
relative to the `ng serve` working directory), `/__runic/open` (a C# location,
|
|
732
|
+
opened through the Angular development server's `/__open-in-editor`) and
|
|
733
|
+
`/__runic/handlers` (the handler analysis of a component and its
|
|
734
|
+
`templateUrl`), each for pages of this machine only, unless `allow` or
|
|
735
|
+
`RUNIC_DEV_ALLOW` admits other machines to `/__runic/sources` and
|
|
736
|
+
`/__runic/handlers` ([Runic Inspect from another machine](#runic-inspect-from-another-machine)).
|
|
737
|
+
|
|
738
|
+
`runicDevSessionProxy({ maxTimelineEntries, printFailures, sourceMap, inspect, allow })`
|
|
739
|
+
takes the same timeline limit as `runic()`, `printFailures: false` to keep the
|
|
740
|
+
terminal quiet, `sourceMap` as `runic({ sourceMap })` takes it (`false` turns
|
|
741
|
+
off `/__runic/sources` and `/__runic/open`), `inspect: false` to turn off
|
|
742
|
+
`/__runic/handlers`, and `allow` as `runic({ allow })` takes it. The `stale-input` warning works the same as with `runic()`; turn it off
|
|
223
743
|
from the page with the registered symbol above.
|
|
224
744
|
|
|
225
745
|
### The client's channel
|
package/dist/access.d.ts
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { IncomingMessage } from "node:http";
|
|
2
|
+
/** Hosts and networks, besides loopback, that may read the development data: comma- or space-separated. */
|
|
3
|
+
export declare const allowVariable = "RUNIC_DEV_ALLOW";
|
|
4
|
+
/** One entry of the allow list, validated. */
|
|
5
|
+
export type AccessRule = {
|
|
6
|
+
readonly kind: "address";
|
|
7
|
+
readonly text: string;
|
|
8
|
+
readonly address: string;
|
|
9
|
+
readonly family: "ipv4" | "ipv6";
|
|
10
|
+
} | {
|
|
11
|
+
readonly kind: "network";
|
|
12
|
+
readonly text: string;
|
|
13
|
+
readonly address: string;
|
|
14
|
+
readonly prefix: number;
|
|
15
|
+
readonly family: "ipv4" | "ipv6";
|
|
16
|
+
} | {
|
|
17
|
+
readonly kind: "host";
|
|
18
|
+
readonly text: string;
|
|
19
|
+
readonly name: string;
|
|
20
|
+
};
|
|
21
|
+
/** Validates allow-list entries; throws a TypeError naming the entry and `source` for an invalid one. */
|
|
22
|
+
export declare function parseAllowList(entries: unknown, source: string): AccessRule[];
|
|
23
|
+
/** The entries of the environment variable: separated by commas or whitespace. */
|
|
24
|
+
export declare function allowListFromEnvironment(value: string | undefined): string[];
|
|
25
|
+
/** An IPv4-mapped IPv6 address (`::ffff:192.0.2.1`) as its IPv4 address; any other address unchanged, without a zone. */
|
|
26
|
+
export declare function normalizeAddress(address: string): string;
|
|
27
|
+
/** Whether a client address is loopback: 127.0.0.0/8 or ::1 (also IPv4-mapped). */
|
|
28
|
+
export declare function isLoopbackAddress(address: string | undefined): boolean;
|
|
29
|
+
/** Decides whether a client address may read the development data: loopback, or one of the rules. */
|
|
30
|
+
export declare class AccessList {
|
|
31
|
+
#private;
|
|
32
|
+
readonly rules: readonly AccessRule[];
|
|
33
|
+
constructor(rules?: readonly AccessRule[], lookup?: (name: string) => Promise<readonly string[]>);
|
|
34
|
+
/** Whether the list admits more than loopback. */
|
|
35
|
+
get remote(): boolean;
|
|
36
|
+
allows(address: string | undefined): Promise<boolean>;
|
|
37
|
+
/** Whether the request's client (its connection's address) is admitted. */
|
|
38
|
+
allowsRequest(request: IncomingMessage): Promise<boolean>;
|
|
39
|
+
}
|
|
40
|
+
/** Loopback only: what the endpoints accept without configuration. */
|
|
41
|
+
export declare const loopbackOnly: AccessList;
|
|
42
|
+
/**
|
|
43
|
+
* The access list of a development server: the option's entries (validated when the plugin is created), then
|
|
44
|
+
* `RUNIC_DEV_ALLOW`'s, each validated under its own name.
|
|
45
|
+
*/
|
|
46
|
+
export declare function resolveAccessList(option: readonly AccessRule[], environment?: Readonly<Record<string, string | undefined>>): AccessList;
|