request-iframe 0.1.1 → 0.2.1

package/library/endpoint/facade.d.ts

@@ -0,0 +1,238 @@
+import type { OriginMatcher, OriginValidator, PostMessageData } from '../types';
+import type { HandlerOptions, MessageContext, VersionValidator } from '../message';
+import type { MessageRoleValue } from '../constants';
+import { RequestIframeEndpointHub } from './infra/hub';
+import { RequestIframeEndpointInbox } from './infra/inbox';
+import { RequestIframeStreamDispatcher } from './stream/dispatcher';
+import { RequestIframeEndpointHeartbeat } from './heartbeat/heartbeat';
+import type { RequestIframeEndpointOutbox } from './infra/outbox';
+/**
+ * RequestIframeEndpointFacade
+ *
+ * Centralizes the common "composition/assembly logic" for endpoints so client/server can reuse it as thin wrappers:
+ * - hub (MessageDispatcher lifecycle + shared infra)
+ * - inbox (inbound message handling: ACK/ASYNC/RESPONSE/ERROR/PING/PONG/STREAM_START, optional)
+ * - streamDispatcher (dispatch `stream_*` frames)
+ * - heartbeat (ping -> wait pong helper, optional)
+ * - originValidator (unified construction for allowedOrigins/validateOrigin)
+ */
+export declare class RequestIframeEndpointFacade {
+    readonly hub: RequestIframeEndpointHub;
+    readonly streamDispatcher: RequestIframeStreamDispatcher;
+    readonly inbox?: RequestIframeEndpointInbox;
+    readonly heartbeat?: RequestIframeEndpointHeartbeat;
+    readonly originValidator?: (origin: string, data: PostMessageData, context: MessageContext) => boolean;
+    private readonly openHooks;
+    constructor(params: {
+        role: MessageRoleValue;
+        instanceId: string;
+        secretKey?: string;
+        versionValidator?: VersionValidator;
+        autoAckMaxMetaLength?: number;
+        autoAckMaxIdLength?: number;
+        /**
+         * Custom handler registration logic (typically for server: REQUEST/ACK/STREAM_START, etc.).
+         * If inbox is provided, prefer inbox.registerHandlers.
+         */
+        registerHandlers?: () => void;
+        /**
+         * Whether to create inbox (typically for client: inbound handling + pending driving).
+         */
+        inbox?: {
+            versionValidator?: VersionValidator;
+        };
+        /**
+         * streamDispatcher handledBy (default: instanceId).
+         */
+        streamDispatcher?: {
+            handledBy?: string;
+        };
+        /**
+         * Whether to create heartbeat (typically for server: pingPeer/handlePong).
+         */
+        heartbeat?: {
+            pendingBucket: string;
+            handledBy: string;
+            isOriginAllowed?: (data: PostMessageData, context: MessageContext) => boolean;
+            warnMissingPendingWhenClosed?: (data: PostMessageData) => void;
+        };
+        originValidator?: {
+            allowedOrigins?: OriginMatcher;
+            validateOrigin?: OriginValidator;
+        };
+    });
+    /**
+     * Add a handler registration hook that will run on core.open().
+     */
+    onOpen(fn: () => void): void;
+    private isOriginAllowedByValidator;
+    /**
+     * Register client-side stream callback handlers:
+     * - stream_* (except stream_start) -> core.getStreamCallback()
+     *
+     * This makes stream dispatching pluggable and owned by the facade.
+     */
+    registerClientStreamCallbackHandlers(params: {
+        handlerOptions: HandlerOptions;
+    }): void;
+    /**
+     * Enable default stream dispatching: dispatch stream_* messages to streamDispatcher.
+     */
+    enableStreamDispatcherCallback(params?: {
+        isOriginAllowed?: (data: PostMessageData, context: MessageContext) => boolean;
+    }): void;
+    disableStreamDispatcherCallback(): void;
+    /**
+     * Register server-side base handlers:
+     * - PING/PONG (heartbeat)
+     * - ACK (receipt confirmation waiter)
+     * - STREAM_START + stream_* routing (request-body stream)
+     *
+     * Server wrapper should still register REQUEST handler itself.
+     */
+    registerServerBaseHandlers(params: {
+        handlerOptions: HandlerOptions;
+        handledBy: string;
+        includeTargetIdInPong?: boolean;
+        isOriginAllowed?: (data: PostMessageData, context: MessageContext) => boolean;
+        warnMissingPendingWhenClosed?: (data: PostMessageData) => void;
+        pendingAckBucket: string;
+        pendingStreamStartBucket: string;
+        expectedStreamStartRole: MessageRoleValue;
+    }): void;
+    /**
+     * Register PING responder (reply PONG).
+     */
+    registerPingResponderHandler(params: {
+        handlerOptions: HandlerOptions;
+        handledBy: string;
+        includeTargetIdInPong?: boolean;
+        isOriginAllowed?: (data: PostMessageData, context: MessageContext) => boolean;
+    }): void;
+    /**
+     * Register PONG handler for heartbeat waiter (if heartbeat is configured).
+     */
+    registerHeartbeatPongHandler(params: {
+        handlerOptions: HandlerOptions;
+    }): void;
+    /**
+     * Register ACK handler for receipt confirmation waiters.
+     */
+    registerAckWaiterHandler(params: {
+        handlerOptions: HandlerOptions;
+        pendingBucket: string;
+        handledBy: string;
+        isOriginAllowed?: (data: PostMessageData, context: MessageContext) => boolean;
+        warnMissingPendingWhenClosed?: (data: PostMessageData) => void;
+    }): void;
+    /**
+     * Register stream handlers (STREAM_START + stream_* routing).
+     */
+    registerStreamHandlers(params: {
+        handlerOptions: HandlerOptions;
+        expectedRole: MessageRoleValue;
+        pendingBucket: string;
+        isOriginAllowed?: (data: PostMessageData, context: MessageContext) => boolean;
+        warnMissingPendingWhenClosed?: (data: PostMessageData) => void;
+    }): void;
+    /**
+     * Server-side: register a waiter for an incoming stream_start (request-body stream handshake).
+     *
+     * This centralizes:
+     * - pending map bookkeeping
+     * - timeout cleanup
+     * - STREAM_START_TIMEOUT error response hook
+     */
+    registerIncomingStreamStartWaiter(params: {
+        pendingBucket: string;
+        requestId: string;
+        streamId: string;
+        timeoutMs: number;
+        targetWindow: Window;
+        targetOrigin: string;
+        onTimeout: () => void;
+        continue: (payload: {
+            stream: any;
+            info: any;
+            data: PostMessageData;
+            context: MessageContext;
+        }) => void;
+    }): void;
+    /**
+     * Handle incoming PING and reply PONG.
+     *
+     * This is a base infrastructure capability for all endpoints.
+     */
+    handlePing(data: PostMessageData, context: MessageContext, params: {
+        handledBy: string;
+        includeTargetId?: boolean;
+        isOriginAllowed?: (data: PostMessageData, context: MessageContext) => boolean;
+    }): void;
+    /**
+     * Handle incoming PONG for facade heartbeat waiter (if configured).
+     */
+    handlePong(data: PostMessageData, context: MessageContext): void;
+    /**
+     * Ping a peer and resolve true when PONG arrives (requires heartbeat configured).
+     */
+    pingPeer(targetWindow: Window, targetOrigin: string, timeoutMs: number, targetId?: string): Promise<boolean>;
+    /**
+     * Client-side "isConnect" ping helper (requires inbox configured).
+     *
+     * - Sends PING(requireAck=true)
+     * - Resolves true when ACK or PONG arrives, false on timeout
+     */
+    pingIsConnect(params: {
+        peer: RequestIframeEndpointOutbox;
+        timeoutMs: number;
+        targetOrigin: string;
+        targetId?: string;
+        onPeerId?: (peerId?: string) => void;
+    }): Promise<boolean>;
+    /**
+     * Pending ACK waiter bucket entry.
+     */
+    private static readonly DEFAULT_PENDING_ACKS_BUCKET;
+    /**
+     * Register an ACK waiter (used by server response requireAck).
+     */
+    registerPendingAck(params: {
+        requestId: string;
+        timeoutMs: number;
+        pendingBucket?: string;
+        resolve: (received: boolean, ack?: any) => void;
+    }): void;
+    /**
+     * Handle incoming ACK for a registered waiter.
+     */
+    handleAck(params: {
+        data: PostMessageData;
+        context: MessageContext;
+        pendingBucket?: string;
+        handledBy: string;
+        isOriginAllowed?: (data: PostMessageData, context: MessageContext) => boolean;
+        warnMissingPendingWhenClosed?: (data: PostMessageData) => void;
+    }): void;
+    /**
+     * Dispatch incoming stream_* messages (stream_data/stream_end/...) to bound handler.
+     */
+    dispatchStreamMessage(data: PostMessageData, context: MessageContext, params?: {
+        isOriginAllowed?: (data: PostMessageData, context: MessageContext) => boolean;
+    }): void;
+    /**
+     * Pending stream_start waiter entry.
+     *
+     * Server stores this entry when it receives a REQUEST that declares a streamId.
+     * When stream_start arrives, facade creates a ReadableStream and calls `continue`.
+     */
+    handleStreamStart(params: {
+        data: PostMessageData;
+        context: MessageContext;
+        expectedRole?: MessageRoleValue;
+        pendingBucket: string;
+        isOriginAllowed?: (data: PostMessageData, context: MessageContext) => boolean;
+        warnMissingPendingWhenClosed?: (data: PostMessageData) => void;
+    }): void;
+    private static buildOriginValidator;
+}
+//# sourceMappingURL=facade.d.ts.map

package/library/endpoint/facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../../src/endpoint/facade.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,8BAA8B,EAAE,MAAM,uBAAuB,CAAC;AAMvE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAElE;;;;;;;;;GASG;AACH,qBAAa,2BAA2B;IACtC,SAAgB,GAAG,EAAE,wBAAwB,CAAC;IAC9C,SAAgB,gBAAgB,EAAE,6BAA6B,CAAC;IAChE,SAAgB,KAAK,CAAC,EAAE,0BAA0B,CAAC;IACnD,SAAgB,SAAS,CAAC,EAAE,8BAA8B,CAAC;IAC3D,SAAgB,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;IAC9G,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;gBAEhC,MAAM,EAAE;QACzB,IAAI,EAAE,gBAAgB,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;QACpC,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B;;;WAGG;QACH,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;QAC9B;;WAEG;QACH,KAAK,CAAC,EAAE;YACN,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;SACrC,CAAC;QACF;;WAEG;QACH,gBAAgB,CAAC,EAAE;YACjB,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB,CAAC;QACF;;WAEG;QACH,SAAS,CAAC,EAAE;YACV,aAAa,EAAE,MAAM,CAAC;YACtB,SAAS,EAAE,MAAM,CAAC;YAClB,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;YAC9E,4BAA4B,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;SAChE,CAAC;QACF,eAAe,CAAC,EAAE;YAChB,cAAc,CAAC,EAAE,aAAa,CAAC;YAC/B,cAAc,CAAC,EAAE,eAAe,CAAC;SAClC,CAAC;KACH;IAwCD;;OAEG;IACI,MAAM,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI;IAInC,OAAO,CAAC,0BAA0B;IASlC;;;;;OAKG;IACI,oCAAoC,CAAC,MAAM,EAAE;QAAE,cAAc,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI;IAU7F;;OAEG;IACI,8BAA8B,CAAC,MAAM,CAAC,EAAE;QAC7C,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;KAC/E,GAAG,IAAI;IAMD,+BAA+B,IAAI,IAAI;IAI9C;;;;;;;OAOG;IACI,0BAA0B,CAAC,MAAM,EAAE;QACxC,cAAc,EAAE,cAAc,CAAC;QAC/B,SAAS,EAAE,MAAM,CAAC;QAClB,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAChC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;QAC9E,4BAA4B,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;QAC/D,gBAAgB,EAAE,MAAM,CAAC;QACzB,wBAAwB,EAAE,MAAM,CAAC;QACjC,uBAAuB,EAAE,gBAAgB,CAAC;KAC3C,GAAG,IAAI;IAwBR;;OAEG;IACI,4BAA4B,CAAC,MAAM,EAAE;QAC1C,cAAc,EAAE,cAAc,CAAC;QAC/B,SAAS,EAAE,MAAM,CAAC;QAClB,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAChC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;KAC/E,GAAG,IAAI;IAgBR;;OAEG;IACI,4BAA4B,CAAC,MAAM,EAAE;QAAE,cAAc,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI;IAYrF;;OAEG;IACI,wBAAwB,CAAC,MAAM,EAAE;QACtC,cAAc,EAAE,cAAc,CAAC;QAC/B,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;QAC9E,4BAA4B,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;KAChE,GAAG,IAAI;IAmBR;;OAEG;IACI,sBAAsB,CAAC,MAAM,EAAE;QACpC,cAAc,EAAE,cAAc,CAAC;QAC/B,YAAY,EAAE,gBAAgB,CAAC;QAC/B,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;QAC9E,4BAA4B,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;KAChE,GAAG,IAAI;IA2BR;;;;;;;OAOG;IACI,iCAAiC,CAAC,MAAM,EAAE;QAC/C,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,IAAI,CAAC;QACtB,QAAQ,EAAE,CAAC,OAAO,EAAE;YAAE,MAAM,EAAE,GAAG,CAAC;YAAC,IAAI,EAAE,GAAG,CAAC;YAAC,IAAI,EAAE,eAAe,CAAC;YAAC,OAAO,EAAE,cAAc,CAAA;SAAE,KAAK,IAAI,CAAC;KACzG,GAAG,IAAI;IAiBR;;;;OAIG;IACI,UAAU,CACf,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE;QACN,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;KAC/E,GACA,IAAI;IAUP;;OAEG;IACI,UAAU,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAIvE;;OAEG;IACI,QAAQ,CACb,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IAQnB;;;;;OAKG;IACI,aAAa,CAAC,MAAM,EAAE;QAC3B,IAAI,EAAE,2BAA2B,CAAC;QAClC,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;KACtC,GAAG,OAAO,CAAC,OAAO,CAAC;IAapB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,2BAA2B,CAA0B;IAE7E;;OAEG;IACI,kBAAkB,CAAC,MAAM,EAAE;QAChC,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,OAAO,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;KACjD,GAAG,IAAI;IASR;;OAEG;IACI,SAAS,CAAC,MAAM,EAAE;QACvB,IAAI,EAAE,eAAe,CAAC;QACtB,OAAO,EAAE,cAAc,CAAC;QACxB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;QAC9E,4BAA4B,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;KAChE,GAAG,IAAI;IAmBR;;OAEG;IACI,qBAAqB,CAC1B,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAA;KAAE,GACzF,IAAI;IAKP;;;;;OAKG;IACI,iBAAiB,CAAC,MAAM,EAAE;QAC/B,IAAI,EAAE,eAAe,CAAC;QACtB,OAAO,EAAE,cAAc,CAAC;QACxB,YAAY,CAAC,EAAE,gBAAgB,CAAC;QAChC,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;QAC9E,4BAA4B,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;KAChE,GAAG,IAAI;IA2CR,OAAO,CAAC,MAAM,CAAC,oBAAoB;CAcpC"}

package/library/endpoint/facade.js

@@ -0,0 +1,398 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.RequestIframeEndpointFacade = void 0;
+require("core-js/modules/es.promise.js");
+require("core-js/modules/es.string.starts-with.js");
+require("core-js/modules/web.dom-collections.for-each.js");
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _constants = require("../constants");
+var _origin = require("../utils/origin");
+var _hub = require("./infra/hub");
+var _inbox = require("./infra/inbox");
+var _dispatcher = require("./stream/dispatcher");
+var _heartbeat = require("./heartbeat/heartbeat");
+var _ping = require("./heartbeat/ping");
+var _factory = require("./stream/factory");
+var _handler = require("./stream/handler");
+/**
+ * RequestIframeEndpointFacade
+ *
+ * Centralizes the common "composition/assembly logic" for endpoints so client/server can reuse it as thin wrappers:
+ * - hub (MessageDispatcher lifecycle + shared infra)
+ * - inbox (inbound message handling: ACK/ASYNC/RESPONSE/ERROR/PING/PONG/STREAM_START, optional)
+ * - streamDispatcher (dispatch `stream_*` frames)
+ * - heartbeat (ping -> wait pong helper, optional)
+ * - originValidator (unified construction for allowedOrigins/validateOrigin)
+ */
+class RequestIframeEndpointFacade {
+  constructor(params) {
+    var _params$streamDispatc, _params$streamDispatc2;
+    (0, _defineProperty2.default)(this, "openHooks", []);
+    this.hub = new _hub.RequestIframeEndpointHub(params.role, params.instanceId, {
+      secretKey: params.secretKey,
+      versionValidator: params.versionValidator,
+      autoAckMaxMetaLength: params.autoAckMaxMetaLength,
+      autoAckMaxIdLength: params.autoAckMaxIdLength
+    });
+    this.streamDispatcher = new _dispatcher.RequestIframeStreamDispatcher({
+      handledBy: (_params$streamDispatc = (_params$streamDispatc2 = params.streamDispatcher) === null || _params$streamDispatc2 === void 0 ? void 0 : _params$streamDispatc2.handledBy) !== null && _params$streamDispatc !== void 0 ? _params$streamDispatc : params.instanceId
+    });
+    this.originValidator = RequestIframeEndpointFacade.buildOriginValidator(params.originValidator);
+
+    /**
+     * Facade is the infrastructure owner: always register handlers via facade hooks.
+     */
+    this.hub.setRegisterHandlers(() => {
+      this.openHooks.forEach(fn => fn());
+    });
+    if (params.heartbeat) {
+      this.heartbeat = new _heartbeat.RequestIframeEndpointHeartbeat({
+        hub: this.hub,
+        pendingBucket: params.heartbeat.pendingBucket,
+        handledBy: params.heartbeat.handledBy,
+        isOriginAllowed: params.heartbeat.isOriginAllowed,
+        warnMissingPendingWhenClosed: params.heartbeat.warnMissingPendingWhenClosed
+      });
+    }
+    if (params.inbox) {
+      this.inbox = new _inbox.RequestIframeEndpointInbox(this.hub, params.inbox.versionValidator);
+    }
+    if (params.registerHandlers) {
+      this.onOpen(params.registerHandlers);
+    }
+  }
+
+  /**
+   * Add a handler registration hook that will run on core.open().
+   */
+  onOpen(fn) {
+    this.openHooks.push(fn);
+  }
+  isOriginAllowedByValidator(origin, data, context) {
+    if (!this.originValidator) return true;
+    try {
+      return this.originValidator(origin, data, context);
+    } catch (_unused) {
+      return false;
+    }
+  }
+
+  /**
+   * Register client-side stream callback handlers:
+   * - stream_* (except stream_start) -> core.getStreamCallback()
+   *
+   * This makes stream dispatching pluggable and owned by the facade.
+   */
+  registerClientStreamCallbackHandlers(params) {
+    this.onOpen(() => {
+      this.hub.registerHandler(type => type.startsWith('stream_') && type !== _constants.MessageType.STREAM_START, (data, context) => {
+        var _this$hub$getStreamCa;
+        return (_this$hub$getStreamCa = this.hub.getStreamCallback()) === null || _this$hub$getStreamCa === void 0 ? void 0 : _this$hub$getStreamCa(data, context);
+      }, params.handlerOptions);
+    });
+  }
+
+  /**
+   * Enable default stream dispatching: dispatch stream_* messages to streamDispatcher.
+   */
+  enableStreamDispatcherCallback(params) {
+    this.hub.setStreamCallback((data, context) => {
+      this.dispatchStreamMessage(data, context, {
+        isOriginAllowed: params === null || params === void 0 ? void 0 : params.isOriginAllowed
+      });
+    });
+  }
+  disableStreamDispatcherCallback() {
+    this.hub.setStreamCallback(undefined);
+  }
+
+  /**
+   * Register server-side base handlers:
+   * - PING/PONG (heartbeat)
+   * - ACK (receipt confirmation waiter)
+   * - STREAM_START + stream_* routing (request-body stream)
+   *
+   * Server wrapper should still register REQUEST handler itself.
+   */
+  registerServerBaseHandlers(params) {
+    this.registerPingResponderHandler({
+      handlerOptions: params.handlerOptions,
+      handledBy: params.handledBy,
+      includeTargetIdInPong: params.includeTargetIdInPong,
+      isOriginAllowed: params.isOriginAllowed
+    });
+    this.registerHeartbeatPongHandler({
+      handlerOptions: params.handlerOptions
+    });
+    this.registerAckWaiterHandler({
+      handlerOptions: params.handlerOptions,
+      pendingBucket: params.pendingAckBucket,
+      handledBy: params.handledBy,
+      isOriginAllowed: params.isOriginAllowed,
+      warnMissingPendingWhenClosed: params.warnMissingPendingWhenClosed
+    });
+    this.registerStreamHandlers({
+      handlerOptions: params.handlerOptions,
+      expectedRole: params.expectedStreamStartRole,
+      pendingBucket: params.pendingStreamStartBucket,
+      isOriginAllowed: params.isOriginAllowed,
+      warnMissingPendingWhenClosed: params.warnMissingPendingWhenClosed
+    });
+  }
+
+  /**
+   * Register PING responder (reply PONG).
+   */
+  registerPingResponderHandler(params) {
+    this.onOpen(() => {
+      this.hub.registerHandler(_constants.MessageType.PING, (data, context) => {
+        this.handlePing(data, context, {
+          handledBy: params.handledBy,
+          includeTargetId: params.includeTargetIdInPong,
+          isOriginAllowed: params.isOriginAllowed
+        });
+      }, params.handlerOptions);
+    });
+  }
+
+  /**
+   * Register PONG handler for heartbeat waiter (if heartbeat is configured).
+   */
+  registerHeartbeatPongHandler(params) {
+    this.onOpen(() => {
+      this.hub.registerHandler(_constants.MessageType.PONG, (data, context) => {
+        this.handlePong(data, context);
+      }, params.handlerOptions);
+    });
+  }
+
+  /**
+   * Register ACK handler for receipt confirmation waiters.
+   */
+  registerAckWaiterHandler(params) {
+    this.onOpen(() => {
+      this.hub.registerHandler(_constants.MessageType.ACK, (data, context) => {
+        this.handleAck({
+          data,
+          context,
+          pendingBucket: params.pendingBucket,
+          handledBy: params.handledBy,
+          isOriginAllowed: params.isOriginAllowed,
+          warnMissingPendingWhenClosed: params.warnMissingPendingWhenClosed
+        });
+      }, params.handlerOptions);
+    });
+  }
+
+  /**
+   * Register stream handlers (STREAM_START + stream_* routing).
+   */
+  registerStreamHandlers(params) {
+    this.onOpen(() => {
+      var isOriginAllowed = params.isOriginAllowed;
+      this.hub.registerHandler(_constants.MessageType.STREAM_START, (data, context) => {
+        this.handleStreamStart({
+          data,
+          context,
+          expectedRole: params.expectedRole,
+          pendingBucket: params.pendingBucket,
+          isOriginAllowed,
+          warnMissingPendingWhenClosed: params.warnMissingPendingWhenClosed
+        });
+      }, params.handlerOptions);
+      this.hub.registerHandler(type => type.startsWith('stream_') && type !== _constants.MessageType.STREAM_START, (data, context) => {
+        this.dispatchStreamMessage(data, context, {
+          isOriginAllowed
+        });
+      }, params.handlerOptions);
+    });
+  }
+
+  /**
+   * Server-side: register a waiter for an incoming stream_start (request-body stream handshake).
+   *
+   * This centralizes:
+   * - pending map bookkeeping
+   * - timeout cleanup
+   * - STREAM_START_TIMEOUT error response hook
+   */
+  registerIncomingStreamStartWaiter(params) {
+    var timeoutId = this.hub.pending.setTimeout(() => {
+      var pending = this.hub.pending.get(params.pendingBucket, params.requestId);
+      if (!pending) return;
+      this.hub.pending.delete(params.pendingBucket, params.requestId);
+      params.onTimeout();
+    }, params.timeoutMs);
+    this.hub.pending.set(params.pendingBucket, params.requestId, {
+      streamId: params.streamId,
+      timeoutId,
+      targetWindow: params.targetWindow,
+      targetOrigin: params.targetOrigin,
+      continue: params.continue
+    });
+  }
+
+  /**
+   * Handle incoming PING and reply PONG.
+   *
+   * This is a base infrastructure capability for all endpoints.
+   */
+  handlePing(data, context, params) {
+    if (!context.source) return;
+    if (params.isOriginAllowed && !params.isOriginAllowed(data, context)) return;
+    (0, _ping.createPingResponder)({
+      hub: this.hub,
+      handledBy: params.handledBy,
+      includeTargetId: params.includeTargetId
+    })(data, context);
+  }
+
+  /**
+   * Handle incoming PONG for facade heartbeat waiter (if configured).
+   */
+  handlePong(data, context) {
+    var _this$heartbeat;
+    (_this$heartbeat = this.heartbeat) === null || _this$heartbeat === void 0 || _this$heartbeat.handlePong(data, context);
+  }
+
+  /**
+   * Ping a peer and resolve true when PONG arrives (requires heartbeat configured).
+   */
+  pingPeer(targetWindow, targetOrigin, timeoutMs, targetId) {
+    if (!this.heartbeat) {
+      return Promise.resolve(false);
+    }
+    var peer = this.hub.createOutbox(targetWindow, targetOrigin, targetId);
+    return this.heartbeat.ping(peer, timeoutMs, targetId);
+  }
+
+  /**
+   * Client-side "isConnect" ping helper (requires inbox configured).
+   *
+   * - Sends PING(requireAck=true)
+   * - Resolves true when ACK or PONG arrives, false on timeout
+   */
+  pingIsConnect(params) {
+    var inbox = this.inbox;
+    if (!inbox) return Promise.resolve(false);
+    return inbox.pingIsConnect({
+      peer: params.peer,
+      timeoutMs: params.timeoutMs,
+      targetOrigin: params.targetOrigin,
+      targetId: params.targetId,
+      onPeerId: params.onPeerId,
+      originValidator: this.originValidator
+    });
+  }
+
+  /**
+   * Pending ACK waiter bucket entry.
+   */
+
+  /**
+   * Register an ACK waiter (used by server response requireAck).
+   */
+  registerPendingAck(params) {
+    var _params$pendingBucket;
+    var bucket = (_params$pendingBucket = params.pendingBucket) !== null && _params$pendingBucket !== void 0 ? _params$pendingBucket : RequestIframeEndpointFacade.DEFAULT_PENDING_ACKS_BUCKET;
+    var timeoutId = this.hub.pending.setTimeout(() => {
+      this.hub.pending.delete(bucket, params.requestId);
+      params.resolve(false);
+    }, params.timeoutMs);
+    this.hub.pending.set(bucket, params.requestId, {
+      resolve: params.resolve,
+      timeoutId
+    });
+  }
+
+  /**
+   * Handle incoming ACK for a registered waiter.
+   */
+  handleAck(params) {
+    var _params$pendingBucket2;
+    var bucket = (_params$pendingBucket2 = params.pendingBucket) !== null && _params$pendingBucket2 !== void 0 ? _params$pendingBucket2 : RequestIframeEndpointFacade.DEFAULT_PENDING_ACKS_BUCKET;
+    if (params.isOriginAllowed && !params.isOriginAllowed(params.data, params.context)) return;
+    var pending = this.hub.pending.get(bucket, params.data.requestId);
+    if (!pending) {
+      if (!this.hub.isOpen) {
+        var _params$warnMissingPe;
+        (_params$warnMissingPe = params.warnMissingPendingWhenClosed) === null || _params$warnMissingPe === void 0 || _params$warnMissingPe.call(params, params.data);
+      }
+      return;
+    }
+    params.context.markHandledBy(params.handledBy);
+    this.hub.pending.clearTimeout(pending.timeoutId);
+    this.hub.pending.delete(bucket, params.data.requestId);
+    pending.resolve(true, params.data.ack);
+  }
+
+  /**
+   * Dispatch incoming stream_* messages (stream_data/stream_end/...) to bound handler.
+   */
+  dispatchStreamMessage(data, context, params) {
+    if (params !== null && params !== void 0 && params.isOriginAllowed && !params.isOriginAllowed(data, context)) return;
+    this.streamDispatcher.dispatch(data, context);
+  }
+
+  /**
+   * Pending stream_start waiter entry.
+   *
+   * Server stores this entry when it receives a REQUEST that declares a streamId.
+   * When stream_start arrives, facade creates a ReadableStream and calls `continue`.
+   */
+  handleStreamStart(params) {
+    var data = params.data,
+      context = params.context;
+    if (params.expectedRole && data.role !== params.expectedRole) return;
+    if (params.isOriginAllowed && !params.isOriginAllowed(data, context)) return;
+    var body = data.body;
+    if (!(body !== null && body !== void 0 && body.streamId)) return;
+    var pending = this.hub.pending.get(params.pendingBucket, data.requestId);
+    if (!pending) {
+      if (!this.hub.isOpen) {
+        var _params$warnMissingPe2;
+        (_params$warnMissingPe2 = params.warnMissingPendingWhenClosed) === null || _params$warnMissingPe2 === void 0 || _params$warnMissingPe2.call(params, data);
+      }
+      return;
+    }
+    if (pending.streamId !== body.streamId) return;
+    this.hub.pending.clearTimeout(pending.timeoutId);
+    this.hub.pending.delete(params.pendingBucket, data.requestId);
+    var streamHandler = (0, _handler.createStreamMessageHandler)({
+      dispatcher: this.streamDispatcher,
+      postMessage: message => {
+        this.hub.messageDispatcher.send(pending.targetWindow, message, pending.targetOrigin);
+      }
+    });
+    var created = (0, _factory.createReadableStreamFromStart)({
+      requestId: data.requestId,
+      data,
+      handler: streamHandler,
+      secretKey: data.secretKey
+    });
+    if (!created) return;
+    pending.continue({
+      stream: created.stream,
+      info: created.info,
+      data,
+      context
+    });
+  }
+  static buildOriginValidator(input) {
+    if (!input) return undefined;
+    if (input.validateOrigin) {
+      return (origin, data, context) => input.validateOrigin(origin, data, context);
+    }
+    if (input.allowedOrigins) {
+      var matcher = input.allowedOrigins;
+      return origin => (0, _origin.matchOrigin)(origin, matcher);
+    }
+    return undefined;
+  }
+}
+exports.RequestIframeEndpointFacade = RequestIframeEndpointFacade;
+(0, _defineProperty2.default)(RequestIframeEndpointFacade, "DEFAULT_PENDING_ACKS_BUCKET", 'endpoint:pendingAcks');

package/library/endpoint/heartbeat/heartbeat.d.ts

@@ -0,0 +1,34 @@
+import type { PostMessageData } from '../../types';
+import type { MessageContext } from '../../message';
+import type { RequestIframeEndpointHub } from '../infra/hub';
+import type { RequestIframeEndpointOutbox } from '../infra/outbox';
+/**
+ * RequestIframeEndpointHeartbeat
+ *
+ * Shared "ping -> wait pong" helper.
+ * - Works for both server and client endpoints
+ * - Uses core.pending for timeout management
+ */
+export declare class RequestIframeEndpointHeartbeat {
+    readonly hub: RequestIframeEndpointHub;
+    private readonly pendingBucket;
+    private readonly handledBy;
+    private readonly isOriginAllowed?;
+    private readonly warnMissingPendingWhenClosed?;
+    constructor(params: {
+        hub: RequestIframeEndpointHub;
+        pendingBucket: string;
+        handledBy: string;
+        isOriginAllowed?: (data: PostMessageData, context: MessageContext) => boolean;
+        warnMissingPendingWhenClosed?: (data: PostMessageData) => void;
+    });
+    /**
+     * Send PING and resolve true when PONG arrives, false on timeout.
+     */
+    ping(peer: RequestIframeEndpointOutbox, timeoutMs: number, targetId?: string): Promise<boolean>;
+    /**
+     * Handle incoming PONG for ping() waiter.
+     */
+    handlePong(data: PostMessageData, context: MessageContext): void;
+}
+//# sourceMappingURL=heartbeat.d.ts.map

package/library/endpoint/heartbeat/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../../src/endpoint/heartbeat/heartbeat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;;;;;GAMG;AACH,qBAAa,8BAA8B;IACzC,SAAgB,GAAG,EAAE,wBAAwB,CAAC;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAA8D;IAC/F,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAAkC;gBAE7D,MAAM,EAAE;QACzB,GAAG,EAAE,wBAAwB,CAAC;QAC9B,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;QAC9E,4BAA4B,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;KAChE;IAQD;;OAEG;IACI,IAAI,CAAC,IAAI,EAAE,2BAA2B,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYtG;;OAEG;IACI,UAAU,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;CAgBxE"}