Files
hyperframes/packages/core/src/runtime/runtimeData.ts
T
Vance Ingalls 859ac622c2 fix(player): report and fail closed on runtime delivery errors (#3472)
* feat(player): report runtime data application

* fix(player): fail closed on runtime data delivery

* fix(player): close runtime delivery and sandbox gaps

* fix(player): satisfy runtime contract and CodeQL

* refactor(player): simplify runtime tag scanner

* style(player): apply repository formatter

* fix(player): type runtime tag boundaries

* fix(core): mint guest-local runtime-data ids in a separate space from host ids
2026-08-30 13:00:14 -07:00

108 lines
3.5 KiB
TypeScript

export type RuntimeDataHandler = (payload: unknown) => void | Promise<void>;
export type RuntimeDataErrorReporter = (channel: string, requestId: number, error: unknown) => void;
export type RuntimeDataAppliedReporter = (channel: string, requestId: number) => void;
type RetainedRuntimeData = {
payload: unknown;
requestId: number;
generation: number;
};
const retained = new Map<string, RetainedRuntimeData>();
const handlers = new Map<string, RuntimeDataHandler>();
const generations = new Map<string, number>();
let reportError: RuntimeDataErrorReporter = () => undefined;
let reportApplied: RuntimeDataAppliedReporter = () => undefined;
let localRequestId = 0;
function validChannel(channel: string): boolean {
return /^[a-z][a-z0-9-]{0,63}$/.test(channel);
}
function nextGeneration(channel: string): number {
const generation = (generations.get(channel) ?? 0) + 1;
generations.set(channel, generation);
return generation;
}
function resolveRequestId(requestId: number | undefined): number {
if (typeof requestId === "number" && Number.isSafeInteger(requestId) && requestId > 0)
return requestId;
// Guest-local ids count down so they can never collide with a host id, which is
// required above to be positive. A shared id space lets a composition-side call
// report `applied` under a host request's id while that host payload is still in flight.
localRequestId -= 1;
return localRequestId;
}
function deliver(channel: string, retainedData: RetainedRuntimeData): void {
const handler = handlers.get(channel);
if (!handler) return;
const isCurrent = () =>
generations.get(channel) === retainedData.generation && handlers.get(channel) === handler;
try {
void Promise.resolve(handler(retainedData.payload)).then(
() => {
if (isCurrent()) reportApplied(channel, retainedData.requestId);
},
(error) => {
if (isCurrent()) reportError(channel, retainedData.requestId, error);
},
);
} catch (error) {
if (isCurrent()) reportError(channel, retainedData.requestId, error);
}
}
export function setRuntimeDataErrorReporter(reporter: RuntimeDataErrorReporter): void {
reportError = reporter;
}
export function setRuntimeDataAppliedReporter(reporter: RuntimeDataAppliedReporter): void {
reportApplied = reporter;
}
export function setRuntimeData(channel: string, payload: unknown, requestId?: number): void {
if (!validChannel(channel)) return;
const retainedData = {
payload,
requestId: resolveRequestId(requestId),
generation: nextGeneration(channel),
};
retained.set(channel, retainedData);
deliver(channel, retainedData);
}
export function clearRuntimeData(channel: string, requestId?: number): void {
if (!validChannel(channel)) return;
retained.delete(channel);
deliver(channel, {
payload: undefined,
requestId: resolveRequestId(requestId),
generation: nextGeneration(channel),
});
}
export function registerRuntimeDataHandler(
channel: string,
handler: RuntimeDataHandler,
): () => void {
if (!validChannel(channel))
throw new Error(`Invalid HyperFrames runtime-data channel: ${channel}`);
handlers.set(channel, handler);
const retainedData = retained.get(channel);
if (retainedData) deliver(channel, retainedData);
return () => {
if (handlers.get(channel) === handler) handlers.delete(channel);
};
}
export function resetRuntimeDataForTests(): void {
retained.clear();
handlers.clear();
generations.clear();
localRequestId = 0;
reportError = () => undefined;
reportApplied = () => undefined;
}