@botiverse/porthole 0.2.4 → 0.3.1
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 +17 -11
- package/dist/check/check.d.ts +100 -0
- package/dist/check/check.js +247 -0
- package/dist/check/drivers.d.ts +43 -0
- package/dist/check/drivers.js +181 -0
- package/dist/check/index.d.ts +8 -0
- package/dist/check/index.js +8 -0
- package/dist/check/instrument.d.ts +71 -0
- package/dist/check/instrument.js +84 -0
- package/dist/check/lint.d.ts +21 -0
- package/dist/check/lint.js +131 -0
- package/dist/check/page-source.d.ts +2 -0
- package/dist/check/page-source.js +2 -0
- package/dist/check/page.d.ts +13 -0
- package/dist/check/page.js +170 -0
- package/dist/check/tools.d.ts +61 -0
- package/dist/check/tools.js +140 -0
- package/dist/conformance/host-kit.d.ts +26 -5
- package/dist/conformance/host-kit.js +46 -22
- package/dist/conformance/index.d.ts +1 -1
- package/dist/conformance/reporter.d.ts +14 -0
- package/dist/conformance/reporter.js +28 -0
- package/dist/displays/displays.d.ts +61 -0
- package/dist/displays/displays.js +113 -0
- package/dist/host/client.d.ts +110 -0
- package/dist/host/client.js +274 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +6 -0
- package/dist/node/index.d.ts +26 -1
- package/dist/node/index.js +91 -1
- package/dist/react/frame.d.ts +79 -3
- package/dist/react/frame.js +183 -42
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +1 -0
- package/dist/react/view.d.ts +54 -0
- package/dist/react/view.js +151 -0
- package/dist/server/bootstrap.d.ts +27 -0
- package/dist/server/bootstrap.js +63 -0
- package/dist/server/host.d.ts +77 -8
- package/dist/server/host.js +268 -11
- package/dist/server/index.d.ts +4 -2
- package/dist/server/index.js +3 -1
- package/dist/server/pages.d.ts +19 -0
- package/dist/server/pages.js +8 -0
- package/dist/server/proxy.d.ts +24 -0
- package/dist/server/proxy.js +67 -0
- package/dist/server/server.js +14 -1
- package/dist/server/types.d.ts +8 -0
- package/docs/ADOPTING.md +278 -108
- package/docs/DECISIONS.md +280 -0
- package/docs/DESIGN.md +84 -2
- package/examples/app.mjs +82 -78
- package/examples/conformance/page.spec.mjs +23 -0
- package/examples/conformance/playwright.config.mjs +3 -2
- package/examples/conformance/porthole.spec.mjs +6 -3
- package/examples/displays.mjs +21 -0
- package/examples/mcp/server.mjs +121 -0
- package/examples/node/server.mjs +16 -34
- package/examples/workers/worker.mjs +19 -7
- package/package.json +13 -1
- package/src/check/check.ts +386 -0
- package/src/check/drivers.ts +242 -0
- package/src/check/index.ts +22 -0
- package/src/check/instrument.ts +138 -0
- package/src/check/lint.ts +238 -0
- package/src/check/page-source.ts +19 -0
- package/src/check/page.ts +230 -0
- package/src/check/tools.ts +206 -0
- package/src/conformance/host-kit.ts +82 -27
- package/src/conformance/index.ts +1 -0
- package/src/conformance/reporter.ts +38 -0
- package/src/displays/displays.ts +191 -0
- package/src/host/client.ts +395 -0
- package/src/index.ts +25 -0
- package/src/node/index.ts +112 -2
- package/src/react/frame.tsx +271 -57
- package/src/react/index.ts +9 -0
- package/src/react/view.tsx +237 -0
- package/src/server/bootstrap.ts +97 -0
- package/src/server/host.ts +372 -18
- package/src/server/index.ts +11 -1
- package/src/server/pages.ts +28 -0
- package/src/server/proxy.ts +86 -0
- package/src/server/server.ts +26 -2
- package/src/server/types.ts +5 -0
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
import {
|
|
2
|
+
useCallback,
|
|
3
|
+
useContext,
|
|
4
|
+
useEffect,
|
|
5
|
+
useState,
|
|
6
|
+
useSyncExternalStore,
|
|
7
|
+
type ReactElement,
|
|
8
|
+
type ReactNode,
|
|
9
|
+
} from "react";
|
|
10
|
+
import type { ColorScheme } from "../config/schema.ts";
|
|
11
|
+
import { frameFallback, type FrameFallback, type PortholeClient } from "../host/client.ts";
|
|
12
|
+
import type { FrameOutcome } from "../host/types.ts";
|
|
13
|
+
import type { InstanceRef } from "../isolation/types.ts";
|
|
14
|
+
import { PortholeFrame, PortholeContext, type PortholeFrameProps } from "./frame.tsx";
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* The host kit's React side (P072): a display by its kind, served or opaque as the server says
|
|
18
|
+
* now, located through the provider's client, with a fallback when its frame shows nothing.
|
|
19
|
+
*
|
|
20
|
+
* <PortholeProvider client={porthole} scheme={mode}>
|
|
21
|
+
* <PortholeView display="page" instance={instance} content={opaqueCopy}
|
|
22
|
+
* fallback={({ title, message, link, retry }) => <Fallback … />} />
|
|
23
|
+
* </PortholeProvider>
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
/** What a fallback is drawn from: why the frame showed nothing, its clean address, a retry. */
|
|
27
|
+
export interface PortholeFallbackProps extends FrameFallback {
|
|
28
|
+
/** The instance's clean address (its "open in a new tab"), or null. */
|
|
29
|
+
readonly link: string | null;
|
|
30
|
+
/** Shows the display again. */
|
|
31
|
+
readonly retry: () => void;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export interface PortholeViewProps extends Omit<
|
|
35
|
+
PortholeFrameProps,
|
|
36
|
+
"config" | "instance" | "content" | "fill"
|
|
37
|
+
> {
|
|
38
|
+
/** The display kind (`defineDisplays`). */
|
|
39
|
+
readonly display: string;
|
|
40
|
+
/** The instance to show while frames are served. */
|
|
41
|
+
readonly instance?: InstanceRef;
|
|
42
|
+
/**
|
|
43
|
+
* The content: a served shell's to draw, and what an opaque frame shows while frames aren't
|
|
44
|
+
* served (a stored page's HTML). Without it, a served-only display shows the fallback then.
|
|
45
|
+
*/
|
|
46
|
+
readonly content?: string;
|
|
47
|
+
/** Drawn instead of the frame when it showed nothing. Default: a line and a link. */
|
|
48
|
+
readonly fallback?: (props: PortholeFallbackProps) => ReactNode;
|
|
49
|
+
/** Drawn while the server's meta isn't known yet. */
|
|
50
|
+
readonly pending?: ReactNode;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function useClient(): PortholeClient {
|
|
54
|
+
const client = useContext(PortholeContext).client;
|
|
55
|
+
if (client === undefined) {
|
|
56
|
+
throw new Error("PortholeView needs a PortholeProvider with a client (portholeClient)");
|
|
57
|
+
}
|
|
58
|
+
return client;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** The client's meta, as a React value (re-renders when frames start or stop being served). */
|
|
62
|
+
/**
|
|
63
|
+
* The client's meta. On the server too (P074): a client made with the meta it will start with
|
|
64
|
+
* (`portholeClient({ meta })`) renders the frame's placeholder or the fallback there, and the
|
|
65
|
+
* page hydrates from the same.
|
|
66
|
+
*/
|
|
67
|
+
function useMeta(client: PortholeClient) {
|
|
68
|
+
return useSyncExternalStore(
|
|
69
|
+
(listener) => client.subscribe(listener),
|
|
70
|
+
() => client.meta(),
|
|
71
|
+
() => client.meta(),
|
|
72
|
+
);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
function DefaultFallback({ title, message, link }: PortholeFallbackProps): ReactElement {
|
|
76
|
+
return (
|
|
77
|
+
<div data-porthole-fallback="" role="status" style={{ padding: 16 }}>
|
|
78
|
+
<strong>{title}</strong> <span>{message}</span>{" "}
|
|
79
|
+
{link === null ? null : (
|
|
80
|
+
<a href={link} target="_blank" rel="noopener">
|
|
81
|
+
Open in a new tab
|
|
82
|
+
</a>
|
|
83
|
+
)}
|
|
84
|
+
</div>
|
|
85
|
+
);
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export function PortholeView(props: PortholeViewProps): ReactElement | null {
|
|
89
|
+
const client = useClient();
|
|
90
|
+
const meta = useMeta(client);
|
|
91
|
+
const { display, instance, content, fallback, pending, onOutcome, ...frame } = props;
|
|
92
|
+
const [failed, setFailed] = useState<FrameFallback | null>(null);
|
|
93
|
+
const [generation, setGeneration] = useState(0);
|
|
94
|
+
const [link, setLink] = useState<string | null>(null);
|
|
95
|
+
const kind = display;
|
|
96
|
+
const config = client.config(kind);
|
|
97
|
+
const served = meta?.served === true && config?.isolation !== "opaque";
|
|
98
|
+
const url = config?.mode === "url";
|
|
99
|
+
|
|
100
|
+
const retry = useCallback(() => {
|
|
101
|
+
setFailed(null);
|
|
102
|
+
setGeneration((each) => each + 1);
|
|
103
|
+
}, []);
|
|
104
|
+
useEffect(() => {
|
|
105
|
+
if (failed === null || instance === undefined) {
|
|
106
|
+
return;
|
|
107
|
+
}
|
|
108
|
+
let live = true;
|
|
109
|
+
void client.link(instance).then((found) => {
|
|
110
|
+
if (live) {
|
|
111
|
+
setLink(found);
|
|
112
|
+
}
|
|
113
|
+
});
|
|
114
|
+
return () => {
|
|
115
|
+
live = false;
|
|
116
|
+
};
|
|
117
|
+
}, [client, failed, instance]);
|
|
118
|
+
|
|
119
|
+
if (meta === null || config === null) {
|
|
120
|
+
// Not known yet; or a url kind while frames aren't served.
|
|
121
|
+
if (meta !== null && config === null) {
|
|
122
|
+
const said: FrameFallback = {
|
|
123
|
+
kind: "failed",
|
|
124
|
+
title: "This can't be shown now",
|
|
125
|
+
message: "Its content isn't being served.",
|
|
126
|
+
};
|
|
127
|
+
return <>{(fallback ?? DefaultFallback)({ ...said, link: null, retry })}</>;
|
|
128
|
+
}
|
|
129
|
+
return <>{pending ?? null}</>;
|
|
130
|
+
}
|
|
131
|
+
if (!served && content === undefined) {
|
|
132
|
+
const said: FrameFallback = {
|
|
133
|
+
kind: "failed",
|
|
134
|
+
title: "This can't be shown now",
|
|
135
|
+
message: "Its content isn't being served.",
|
|
136
|
+
};
|
|
137
|
+
return <>{(fallback ?? DefaultFallback)({ ...said, link: null, retry })}</>;
|
|
138
|
+
}
|
|
139
|
+
if (failed !== null) {
|
|
140
|
+
return <>{(fallback ?? DefaultFallback)({ ...failed, link, retry })}</>;
|
|
141
|
+
}
|
|
142
|
+
return (
|
|
143
|
+
<PortholeFrame
|
|
144
|
+
{...frame}
|
|
145
|
+
config={config}
|
|
146
|
+
generation={(frame.generation ?? 0) + generation}
|
|
147
|
+
{...(served && instance !== undefined ? { instance } : {})}
|
|
148
|
+
{...(content === undefined ? {} : { content })}
|
|
149
|
+
onOutcome={(outcome: FrameOutcome) => {
|
|
150
|
+
onOutcome?.(outcome);
|
|
151
|
+
const said = frameFallback(outcome, { url });
|
|
152
|
+
if (said !== null) {
|
|
153
|
+
setFailed(said);
|
|
154
|
+
}
|
|
155
|
+
}}
|
|
156
|
+
/>
|
|
157
|
+
);
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** An instance's clean address, and its "open in a new tab" and "copy link" (P072). */
|
|
161
|
+
export function usePortholeLink(instance: InstanceRef | null): {
|
|
162
|
+
readonly link: string | null;
|
|
163
|
+
readonly open: () => void;
|
|
164
|
+
readonly copy: () => Promise<boolean>;
|
|
165
|
+
} {
|
|
166
|
+
const client = useClient();
|
|
167
|
+
const key = instance === null ? "" : JSON.stringify(instance);
|
|
168
|
+
// The address found for the instance it was found for: another instance shows none until its own.
|
|
169
|
+
const [found, setFound] = useState<{ readonly key: string; readonly link: string | null }>(
|
|
170
|
+
() => ({ key, link: instance === null ? null : client.knownLink(instance) }),
|
|
171
|
+
);
|
|
172
|
+
useEffect(() => {
|
|
173
|
+
if (key === "") {
|
|
174
|
+
return;
|
|
175
|
+
}
|
|
176
|
+
let live = true;
|
|
177
|
+
void client.link(JSON.parse(key) as InstanceRef).then((each) => {
|
|
178
|
+
if (live) {
|
|
179
|
+
setFound({ key, link: each });
|
|
180
|
+
}
|
|
181
|
+
});
|
|
182
|
+
return () => {
|
|
183
|
+
live = false;
|
|
184
|
+
};
|
|
185
|
+
}, [client, key]);
|
|
186
|
+
const link = found.key === key ? found.link : null;
|
|
187
|
+
const open = useCallback(() => {
|
|
188
|
+
if (key !== "") {
|
|
189
|
+
client.openInTab(JSON.parse(key) as InstanceRef);
|
|
190
|
+
}
|
|
191
|
+
}, [client, key]);
|
|
192
|
+
const copy = useCallback(async () => {
|
|
193
|
+
if (link === null) {
|
|
194
|
+
return false;
|
|
195
|
+
}
|
|
196
|
+
try {
|
|
197
|
+
await navigator.clipboard.writeText(link);
|
|
198
|
+
return true;
|
|
199
|
+
} catch {
|
|
200
|
+
return false;
|
|
201
|
+
}
|
|
202
|
+
}, [link]);
|
|
203
|
+
return { link, open, copy };
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/**
|
|
207
|
+
* Theme values read from the page's own CSS variables (P072): `tokens` maps each of Porthole's
|
|
208
|
+
* theme variables to the app's (`{ "--color-text-primary": "--app-fg" }`). Read when a frame asks,
|
|
209
|
+
* so pass `themeKey` to re-read after the app's theme changes.
|
|
210
|
+
*/
|
|
211
|
+
export function cssVariableTheme(
|
|
212
|
+
tokens: Readonly<Record<string, string>>,
|
|
213
|
+
root?: () => Element,
|
|
214
|
+
): (scheme: ColorScheme) => Record<string, string> {
|
|
215
|
+
return () => {
|
|
216
|
+
const element = root?.() ?? globalThis.document?.documentElement;
|
|
217
|
+
if (element === undefined) {
|
|
218
|
+
return {};
|
|
219
|
+
}
|
|
220
|
+
const style = getComputedStyle(element);
|
|
221
|
+
const values: Record<string, string> = {};
|
|
222
|
+
for (const [ours, theirs] of Object.entries(tokens)) {
|
|
223
|
+
const value = style.getPropertyValue(theirs).trim();
|
|
224
|
+
if (value !== "") {
|
|
225
|
+
values[ours] = value;
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
return values;
|
|
229
|
+
};
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/** A display's "run again": pass `generation` to the frame, call `runAgain` from a button. */
|
|
233
|
+
export function useRunAgain(): { readonly generation: number; readonly runAgain: () => void } {
|
|
234
|
+
const [generation, setGeneration] = useState(0);
|
|
235
|
+
const runAgain = useCallback(() => setGeneration((each) => each + 1), []);
|
|
236
|
+
return { generation, runAgain };
|
|
237
|
+
}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import { createContentHost, type ContentHost, type ContentHostOptions } from "./host.ts";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The host kit on a runtime that hands each request its settings (Cloudflare Workers' `env`)
|
|
5
|
+
* (P072): one content host per settings object, made on first use. Settings that can't be served
|
|
6
|
+
* fail closed: every request is a plain 503 naming why, told to the log once.
|
|
7
|
+
*
|
|
8
|
+
* const porthole = contentHostFor((env) => ({ domain: env.CONTENT_DOMAIN, secret: env.PORTHOLE_SECRET, … }));
|
|
9
|
+
* export default {
|
|
10
|
+
* async fetch(request, env) {
|
|
11
|
+
* return (await porthole.fetch(request, env)) ?? app.fetch(request, env);
|
|
12
|
+
* },
|
|
13
|
+
* };
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
export interface ContentHostFor<E extends object, V> {
|
|
17
|
+
/** The content host for these settings; throws, naming why, where they can't be served. */
|
|
18
|
+
host(env: E): ContentHost<V>;
|
|
19
|
+
/**
|
|
20
|
+
* The content domain's answer for a request (`ContentHost.fetch`), or null for the app's own;
|
|
21
|
+
* a plain 503 for every request while the settings can't be served.
|
|
22
|
+
*/
|
|
23
|
+
fetch(request: Request, env: E): Promise<Response | null>;
|
|
24
|
+
/** `ContentHost.routes`, for these settings. */
|
|
25
|
+
routes(
|
|
26
|
+
request: Request,
|
|
27
|
+
env: E,
|
|
28
|
+
viewerOf: (request: Request) => V | null | Promise<V | null>,
|
|
29
|
+
): Promise<Response | null>;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Why the content host can't be made for some settings. */
|
|
33
|
+
class Unservable extends Error {
|
|
34
|
+
override readonly name = "ContentHostUnservable";
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export function contentHostFor<E extends object, V>(
|
|
38
|
+
build: (env: E) => ContentHostOptions<V>,
|
|
39
|
+
options: { readonly log?: (problem: string) => void } = {},
|
|
40
|
+
): ContentHostFor<E, V> {
|
|
41
|
+
const made = new WeakMap<E, ContentHost<V> | Unservable>();
|
|
42
|
+
const hostOf = (env: E): ContentHost<V> => {
|
|
43
|
+
let found = made.get(env);
|
|
44
|
+
if (found === undefined) {
|
|
45
|
+
try {
|
|
46
|
+
found = createContentHost(build(env));
|
|
47
|
+
} catch (error) {
|
|
48
|
+
found = new Unservable(
|
|
49
|
+
`the content domain can't be served: ${error instanceof Error ? error.message : String(error)}`,
|
|
50
|
+
);
|
|
51
|
+
(options.log ?? (() => {}))(found.message);
|
|
52
|
+
}
|
|
53
|
+
made.set(env, found);
|
|
54
|
+
}
|
|
55
|
+
if (found instanceof Unservable) {
|
|
56
|
+
throw found;
|
|
57
|
+
}
|
|
58
|
+
return found;
|
|
59
|
+
};
|
|
60
|
+
const unavailable = (error: Unservable) =>
|
|
61
|
+
new Response(`Unavailable: ${error.message}.`, {
|
|
62
|
+
status: 503,
|
|
63
|
+
headers: {
|
|
64
|
+
"content-type": "text/plain; charset=utf-8",
|
|
65
|
+
"cache-control": "no-store",
|
|
66
|
+
"x-content-type-options": "nosniff",
|
|
67
|
+
"x-robots-tag": "noindex, nofollow",
|
|
68
|
+
},
|
|
69
|
+
});
|
|
70
|
+
return {
|
|
71
|
+
host: hostOf,
|
|
72
|
+
async fetch(request, env) {
|
|
73
|
+
let host: ContentHost<V>;
|
|
74
|
+
try {
|
|
75
|
+
host = hostOf(env);
|
|
76
|
+
} catch (error) {
|
|
77
|
+
if (error instanceof Unservable) {
|
|
78
|
+
return unavailable(error);
|
|
79
|
+
}
|
|
80
|
+
throw error;
|
|
81
|
+
}
|
|
82
|
+
return host.fetch(request);
|
|
83
|
+
},
|
|
84
|
+
async routes(request, env, viewerOf) {
|
|
85
|
+
let host: ContentHost<V>;
|
|
86
|
+
try {
|
|
87
|
+
host = hostOf(env);
|
|
88
|
+
} catch (error) {
|
|
89
|
+
if (error instanceof Unservable) {
|
|
90
|
+
return unavailable(error);
|
|
91
|
+
}
|
|
92
|
+
throw error;
|
|
93
|
+
}
|
|
94
|
+
return host.routes(viewerOf)(request);
|
|
95
|
+
},
|
|
96
|
+
};
|
|
97
|
+
}
|