Source code
Revision control
Copy as Markdown
Other Tools
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this file,
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { resolveFrameVariant } from "common/WidgetsRegistry.mjs";
// Protocol v1 rules from the framed-widgets host integration doc.
const TOKEN = /^[a-z][a-z0-9_]{0,63}$/;
const VALUE = /^[a-z0-9][a-z0-9_]{0,31}$/;
// RegExp#test coerces its argument, so undefined would pass as "undefined".
const isToken = x => typeof x === "string" && TOKEN.test(x);
const isValue = x => typeof x === "string" && VALUE.test(x);
const onlyKeys = (payload, keys) =>
Object.keys(payload).every(key => keys.includes(key));
// Telemetry checks by message. Each new Glean event is opted in here.
const TELEMETRY_VALIDATORS = {
user_event: p =>
onlyKeys(p, ["user_action", "action_value"]) &&
isToken(p.user_action) &&
(p.action_value === undefined || isValue(p.action_value)),
};
// Payload checks by message type. Messages of any other type, or that fail
// their check, are dropped.
const PAYLOAD_VALIDATORS = {
widget_ready: p =>
onlyKeys(p, ["protocol", "variant"]) &&
Number.isInteger(p.protocol) &&
(p.variant === undefined || isValue(p.variant)),
widget_error: p =>
onlyKeys(p, ["reason", "terminal"]) &&
isToken(p.reason) &&
typeof p.terminal === "boolean",
action: (p, message) => isToken(message),
telemetry: (p, message) =>
Object.hasOwn(TELEMETRY_VALIDATORS, message) &&
TELEMETRY_VALIDATORS[message](p),
};
// Without widget_ready by then, the widget is treated as failed. The iframe
// itself always loads, even when its URL is wrong, so widget_ready is the
// only sign that the widget's document works.
export const FRAMED_WIDGET_LOAD_TIMEOUT_MS = 12000;
/**
* Calls onMessage for every valid message a framed widget's document posts.
* The frame posts with targetOrigin "*" (about:newtab is opaque), so a message
* only counts when it comes from the frame's window and origin on the
* widget's channel, `<telemetryName>_widget`.
*
* @param {object} options
* @param {object} options.widget - a WIDGET_REGISTRY entry
* @param {string} options.src - URL of the widget's document
* @param {object} options.iframeRef - ref to the widget's iframe
* @param {Function} options.onMessage - called with (type, message, payload)
*/
export function useFramedWidgetMessages({ widget, src, iframeRef, onMessage }) {
const onMessageRef = useRef(onMessage);
onMessageRef.current = onMessage;
const channel = `${widget.telemetryName}_widget`;
const frameOrigin = useMemo(() => {
try {
return new URL(src).origin;
} catch {
return null;
}
}, [src]);
useEffect(() => {
if (!frameOrigin) {
return undefined;
}
function handleMessage(event) {
const { data } = event;
if (
event.origin !== frameOrigin ||
event.source !== iframeRef.current?.contentWindow ||
data?.channel !== channel ||
typeof data.payload !== "object" ||
data.payload === null ||
!PAYLOAD_VALIDATORS[data.type]?.(data.payload, data.message)
) {
return;
}
onMessageRef.current(data.type, data.message, data.payload);
}
window.addEventListener("message", handleMessage);
return () => window.removeEventListener("message", handleMessage);
}, [frameOrigin, channel, iframeRef]);
}
/**
* Returns whether a framed widget's document has sent widget_ready, so the
* frame can stay hidden until it has, and the variant it sent with it when
* the widget's frameVariants list it. Calls onError with (reason, terminal)
* for widget_errors, and with ("load_timeout", true) when widget_ready doesn't
* arrive in time. So a frame can't flood telemetry, each load reports a
* non-terminal reason once and nothing after its first terminal error. A
* terminal error means the widget is unusable.
*
* @param {object} options - see useFramedWidgetMessages, without onMessage
* @param {Function} options.onError - called with (reason, terminal)
* @returns {{ready: boolean, variant: string|undefined}}
*/
export function useFramedWidgetReady({ widget, src, iframeRef, onError }) {
const [readyPayload, setReadyPayload] = useState(null);
const ready = readyPayload !== null;
const onErrorRef = useRef(onError);
onErrorRef.current = onError;
const [reportedReasons] = useState(() => new Set());
const failedRef = useRef(false);
useEffect(() => {
setReadyPayload(null);
reportedReasons.clear();
failedRef.current = false;
}, [src, reportedReasons]);
useEffect(() => {
// Without a document there is nothing to wait for.
if (ready || !src) {
return undefined;
}
const timer = setTimeout(() => {
if (!failedRef.current) {
failedRef.current = true;
onErrorRef.current("load_timeout", true);
}
}, FRAMED_WIDGET_LOAD_TIMEOUT_MS);
return () => clearTimeout(timer);
}, [src, ready]);
useFramedWidgetMessages({
widget,
src,
iframeRef,
onMessage(type, message, payload) {
if (type === "widget_ready") {
setReadyPayload(payload);
} else if (type === "widget_error") {
if (
failedRef.current ||
(!payload.terminal && reportedReasons.has(payload.reason))
) {
return;
}
reportedReasons.add(payload.reason);
failedRef.current = payload.terminal;
onErrorRef.current(payload.reason, payload.terminal);
}
},
});
return { ready, variant: resolveFrameVariant(widget, readyPayload?.variant) };
}
/**
* Returns the size a framed widget's document last asked for with a
* `change_size` action (or null), and a function that drops it. Only the
* widget's validSizes are accepted. The request is never written to the
* widget's size pref. It is dropped when the widget's URL or its own size
* changes; call clearRequestedSize when the user picks a size, so their
* choice wins even when it matches the size pref.
*
* @param {object} options - see useFramedWidgetMessages, without onMessage
* @param {string} options.widgetSize - the widget's size from its prefs
* @param {Function} [options.onAction] - called with (message, payload) for
* every action, change_size included
* @returns {{requestedSize: string|null, clearRequestedSize: Function}}
*/
export function useFramedWidgetSize({
widget,
src,
iframeRef,
widgetSize,
onAction,
}) {
const [requestedSize, setRequestedSize] = useState(null);
useEffect(() => setRequestedSize(null), [src, widgetSize]);
useFramedWidgetMessages({
widget,
src,
iframeRef,
onMessage(type, message, payload) {
if (type !== "action") {
return;
}
onAction?.(message, payload);
if (
message === "change_size" &&
onlyKeys(payload, ["size"]) &&
widget.validSizes.includes(payload.size)
) {
setRequestedSize(payload.size);
}
},
});
const clearRequestedSize = useCallback(() => setRequestedSize(null), []);
return { requestedSize, clearRequestedSize };
}