WeKnora/frontend/src/extensions/pluginFrame/bridgeHost.ts

215 lines
7.2 KiB
TypeScript

// The app's side of the plugin page bridge (packages/plugin-ui is the
// page's side). A plugin page runs in a sandboxed iframe with an opaque
// origin; it can only post messages to the app, and the app answers only
// messages that come from that iframe, at a bounded rate.
/** Protocol version; also marks bridge messages. */
export const BRIDGE_PROTOCOL = 1
export interface BridgeTheme {
mode: 'light' | 'dark'
tokens: Record<string, string>
}
/** What the page receives in `init`. */
export interface BridgeInit {
pluginId: string
version: string
mount: string
locale: string
/** The user's workspace role, for what the page offers; the server decides. */
role: string
theme: BridgeTheme
context: Record<string, unknown>
}
export interface ApiResult {
status: number
body: unknown
}
/** What the app does for each call a page makes. */
export interface BridgeHandlers {
apiRequest(params: { method: string; path: string; body?: unknown }): Promise<ApiResult>
toast(message: string, theme: ToastTheme): void
confirm(message: string, title?: string): Promise<boolean>
navigate(path: string): void
resize(height: number): void
close(): void
}
export type ToastTheme = 'info' | 'success' | 'warning' | 'error'
export interface BridgeHostOptions {
/** The iframe's window; messages from any other source are ignored. */
frame: () => Window | null | undefined
init: () => BridgeInit
handlers: BridgeHandlers
/** Calls allowed in a burst and per second after it. */
burst?: number
perSecond?: number
now?: () => number
}
interface RequestMessage {
weknora: number
kind: 'request'
id: number
method: string
params?: unknown
}
export class BridgeCallError extends Error {
constructor(
message: string,
readonly status?: number,
) {
super(message)
}
}
const MAX_TOAST = 300
const MAX_HEIGHT = 20_000
const TOAST_THEMES = new Set<ToastTheme>(['info', 'success', 'warning', 'error'])
function isObject(v: unknown): v is Record<string, unknown> {
return v !== null && typeof v === 'object' && !Array.isArray(v)
}
/** A path inside the app: "/platform/...", never another origin. */
export function isAppPath(path: unknown): path is string {
return typeof path === 'string' && path.startsWith('/') && !path.startsWith('//') && !path.includes('\\')
}
/** A token bucket: `burst` calls at once, refilled at `perSecond`. */
export function createRateLimiter(burst: number, perSecond: number, now: () => number = Date.now) {
let tokens = burst
let last = now()
return () => {
const t = now()
tokens = Math.min(burst, tokens + ((t - last) / 1000) * perSecond)
last = t
if (tokens < 1) return false
tokens -= 1
return true
}
}
export interface BridgeHost {
/** Feed every window `message` event here. */
handle(event: MessageEvent): void
/** Sends an event to the page (init, theme, locale). */
send(name: string, data: unknown): void
}
export function createBridgeHost(opts: BridgeHostOptions): BridgeHost {
const allow = createRateLimiter(opts.burst ?? 30, opts.perSecond ?? 10, opts.now)
const post = (msg: Record<string, unknown>) => {
// The page's origin is opaque ("null"), so it cannot be named as the
// target; only that window receives the message.
opts.frame()?.postMessage({ weknora: BRIDGE_PROTOCOL, ...msg }, '*')
}
const send = (name: string, data: unknown) => post({ kind: 'event', name, data })
const reply = (id: number, result: unknown) => post({ kind: 'response', id, ok: true, result })
const fail = (id: number, err: unknown) => {
const message = err instanceof Error ? err.message : String(err)
const status = err instanceof BridgeCallError ? err.status : undefined
post({ kind: 'response', id, ok: false, error: { message, status } })
}
const dispatch = async (method: string, params: Record<string, unknown>): Promise<unknown> => {
const h = opts.handlers
switch (method) {
case 'api.request': {
const verb = typeof params.method === 'string' ? params.method.toUpperCase() : 'GET'
if (!/^[A-Z]{3,7}$/.test(verb)) throw new BridgeCallError('bad method', 400)
if (typeof params.path !== 'string' || !params.path.startsWith('/')) {
throw new BridgeCallError('path must start with /', 400)
}
return h.apiRequest({ method: verb, path: params.path, body: params.body })
}
case 'ui.toast': {
if (typeof params.message !== 'string' || !params.message) throw new BridgeCallError('message is required', 400)
const theme = TOAST_THEMES.has(params.theme as ToastTheme) ? (params.theme as ToastTheme) : 'info'
h.toast(params.message.slice(0, MAX_TOAST), theme)
return null
}
case 'ui.confirm': {
if (typeof params.message !== 'string' || !params.message) throw new BridgeCallError('message is required', 400)
const title = typeof params.title === 'string' ? params.title.slice(0, 100) : undefined
return h.confirm(params.message.slice(0, MAX_TOAST), title)
}
case 'ui.navigate':
if (!isAppPath(params.path)) throw new BridgeCallError('path must be a path of the app', 400)
h.navigate(params.path)
return null
case 'ui.resize': {
const height = Number(params.height)
if (!Number.isFinite(height) || height < 0) throw new BridgeCallError('height must be a number', 400)
h.resize(Math.min(Math.ceil(height), MAX_HEIGHT))
return null
}
case 'ui.close':
h.close()
return null
default:
throw new BridgeCallError(`unknown method ${method}`, 404)
}
}
return {
send,
handle(event: MessageEvent) {
const frame = opts.frame()
if (!frame || event.source !== frame) return
const data = event.data as unknown
if (!isObject(data) || data.weknora !== BRIDGE_PROTOCOL) return
if (data.kind === 'hello') {
send('init', opts.init())
return
}
if (data.kind !== 'request') return
const msg = data as unknown as RequestMessage
if (typeof msg.id !== 'number' || typeof msg.method !== 'string') return
if (!allow()) {
fail(msg.id, new BridgeCallError('too many requests', 429))
return
}
dispatch(msg.method, isObject(msg.params) ? msg.params : {}).then(
(result) => reply(msg.id, result ?? null),
(err) => fail(msg.id, err),
)
},
}
}
/** The app's design tokens a page may use, read from the root element. */
export const THEME_TOKENS = [
'brand-color',
'brand-color-light',
'text-color-primary',
'text-color-secondary',
'text-color-placeholder',
'bg-color-page',
'bg-color-container',
'bg-color-secondarycontainer',
'component-border',
'border-level-1-color',
'error-color',
'warning-color',
'success-color',
'radius-default',
'font-family',
] as const
export function readTheme(doc: Document = document): BridgeTheme {
const root = doc.documentElement
const style = getComputedStyle(root)
const tokens: Record<string, string> = {}
for (const name of THEME_TOKENS) {
const value = style.getPropertyValue(`--td-${name}`).trim()
if (value) tokens[name] = value
}
return { mode: root.getAttribute('theme-mode') === 'dark' ? 'dark' : 'light', tokens }
}