request-iframe 0.1.0 → 0.2.0

package/esm/endpoint/infra/hub.js

@@ -0,0 +1,316 @@
+import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
+import "core-js/modules/es.array.iterator.js";
+import "core-js/modules/es.array.map.js";
+import "core-js/modules/es.map.js";
+import "core-js/modules/es.set.js";
+import "core-js/modules/web.dom-collections.for-each.js";
+import "core-js/modules/web.dom-collections.iterator.js";
+import { MessageDispatcher } from '../../message';
+import { isCompatibleVersion } from '../../utils/protocol';
+import { OriginConstant, Messages } from '../../constants';
+import { getOrCreateMessageChannel, releaseMessageChannel } from '../../message/channel-cache';
+import { RequestIframeEndpointOutbox } from './outbox';
+import { SyncHook } from '../../utils/hooks';
+
+/**
+ * Pending manager for maps and timers.
+ *
+ * - Track all pending maps created by hub
+ * - Track all timeouts created by hub
+ * - Provide a unified cleanup when destroying
+ */
+class RequestIframePendingManager {
+  constructor() {
+    _defineProperty(this, "maps", new Map());
+    _defineProperty(this, "timeouts", new Set());
+  }
+  /**
+   * Get or create a named pending map that will be auto-cleared on destroy.
+   */
+  map(name) {
+    var existing = this.maps.get(name);
+    if (existing) return existing;
+    var m = new Map();
+    this.maps.set(name, m);
+    return m;
+  }
+  get(name, key) {
+    return this.map(name).get(key);
+  }
+  set(name, key, value) {
+    this.map(name).set(key, value);
+  }
+  has(name, key) {
+    return this.map(name).has(key);
+  }
+  delete(name, key) {
+    return this.map(name).delete(key);
+  }
+
+  /**
+   * Create a timeout that will be auto-cleared on destroy.
+   */
+  setTimeout(fn, ms) {
+    var id = setTimeout(() => {
+      this.timeouts.delete(id);
+      fn();
+    }, ms);
+    this.timeouts.add(id);
+    return id;
+  }
+
+  /**
+   * Clear a tracked timeout.
+   */
+  clearTimeout(id) {
+    clearTimeout(id);
+    this.timeouts.delete(id);
+  }
+
+  /**
+   * Clear all tracked pending maps and timeouts.
+   */
+  clearAll() {
+    this.timeouts.forEach(id => clearTimeout(id));
+    this.timeouts.clear();
+    this.maps.forEach(m => m.clear());
+  }
+}
+
+/**
+ * Generic counter/limiter utilities (built on hub.pending maps).
+ *
+ * This is intended as a shared infrastructure for both client/server:
+ * - server can limit max concurrent in-flight requests per client
+ * - client can limit max concurrent streams / in-flight sends in future
+ */
+class RequestIframeLimiter {
+  constructor(pending) {
+    this.pending = pending;
+  }
+  get(bucket, key) {
+    var _this$pending$get;
+    return (_this$pending$get = this.pending.get(bucket, key)) !== null && _this$pending$get !== void 0 ? _this$pending$get : 0;
+  }
+
+  /**
+   * Try acquire one permit for the given key.
+   * Returns true if acquired, false if limit reached.
+   */
+  tryAcquire(bucket, key, limit) {
+    if (!Number.isFinite(limit)) {
+      /** Treat Infinity as always allowed but still count for symmetry */
+      var next = this.get(bucket, key) + 1;
+      this.pending.set(bucket, key, next);
+      return true;
+    }
+    var current = this.get(bucket, key);
+    if (current >= limit) return false;
+    this.pending.set(bucket, key, current + 1);
+    return true;
+  }
+
+  /**
+   * Release one permit for the given key.
+   */
+  release(bucket, key) {
+    var current = this.get(bucket, key);
+    var next = current - 1;
+    if (next <= 0) {
+      this.pending.delete(bucket, key);
+      return;
+    }
+    this.pending.set(bucket, key, next);
+  }
+}
+
+/**
+ * Shared options for endpoint hub.
+ */
+
+/**
+ * RequestIframeEndpointHub
+ *
+ * Endpoint "hub" responsible for:
+ * - MessageDispatcher lifecycle
+ * - handler registration/unregistration
+ * - pending + timeout management
+ * - limiter counters
+ */
+export class RequestIframeEndpointHub {
+  constructor(role, instanceId, options) {
+    var _options$versionValid;
+    _defineProperty(this, "hooks", {
+      beforeOpen: new SyncHook(),
+      afterOpen: new SyncHook(),
+      beforeClose: new SyncHook(),
+      afterClose: new SyncHook(),
+      beforeDestroy: new SyncHook(),
+      afterDestroy: new SyncHook(),
+      registerHandler: new SyncHook(),
+      unregisterHandler: new SyncHook()
+    });
+    _defineProperty(this, "pending", new RequestIframePendingManager());
+    _defineProperty(this, "limiter", new RequestIframeLimiter(this.pending));
+    _defineProperty(this, "unregisterFns", []);
+    _defineProperty(this, "warnOnceKeys", new Set());
+    /** Whether it is open */
+    _defineProperty(this, "_isOpen", false);
+    this.instanceId = instanceId;
+    this.versionValidator = (_options$versionValid = options === null || options === void 0 ? void 0 : options.versionValidator) !== null && _options$versionValid !== void 0 ? _options$versionValid : isCompatibleVersion;
+
+    /** Get or create shared channel and create dispatcher */
+    var channel = getOrCreateMessageChannel(options === null || options === void 0 ? void 0 : options.secretKey);
+    this.messageDispatcher = new MessageDispatcher(channel, role, instanceId);
+    this.messageDispatcher.setAutoAckLimits({
+      maxMetaLength: options === null || options === void 0 ? void 0 : options.autoAckMaxMetaLength,
+      maxIdLength: options === null || options === void 0 ? void 0 : options.autoAckMaxIdLength
+    });
+  }
+
+  /**
+   * Set registerHandlers callback.
+   *
+   * This is used by composition-based implementations to define handler bindings.
+   */
+  setRegisterHandlers(fn) {
+    this.registerHandlersFn = fn;
+  }
+
+  /**
+   * Register a dispatcher handler and track its unregister function.
+   */
+  registerHandler(matcher, handler, options) {
+    this.hooks.registerHandler.call(matcher);
+    var unreg = this.messageDispatcher.registerHandler(matcher, handler, options);
+    this.unregisterFns.push(unreg);
+    return unreg;
+  }
+
+  /**
+   * Create common handler options object.
+   */
+  createHandlerOptions(onVersionError) {
+    return {
+      versionValidator: this.versionValidator,
+      onVersionError
+    };
+  }
+
+  /**
+   * Warn once per key.
+   */
+  warnOnce(key, fn) {
+    if (this.warnOnceKeys.has(key)) return;
+    this.warnOnceKeys.add(key);
+    fn();
+  }
+
+  /**
+   * Set stream callback (used by client-side stream routing).
+   */
+  setStreamCallback(callback) {
+    this.streamCallback = callback;
+  }
+
+  /**
+   * Get stream callback (used by handler registration side).
+   */
+  getStreamCallback() {
+    return this.streamCallback;
+  }
+
+  /**
+   * Validate origin safely (originValidator wins over origin string).
+   */
+  isOriginAllowedBy(contextOrigin, data, context, origin, originValidator) {
+    if (originValidator) {
+      try {
+        return originValidator(contextOrigin, data, context);
+      } catch (_unused) {
+        return false;
+      }
+    }
+    if (!origin || origin === OriginConstant.ANY) return true;
+    return contextOrigin === origin;
+  }
+
+  /**
+   * Set a fixed peer (fallback target) for cases where MessageEvent.source is missing.
+   *
+   * This is useful for "response endpoint" style usage where the peer is already known
+   * (e.g. a client bound to an iframe window).
+   */
+  setFallbackTarget(targetWindow, targetOrigin) {
+    this.messageDispatcher.setFallbackTarget(targetWindow, targetOrigin);
+  }
+
+  /**
+   * Create a peer-bound outbox using this hub's dispatcher.
+   */
+  createOutbox(targetWindow, targetOrigin, defaultTargetId) {
+    return new RequestIframeEndpointOutbox(this.messageDispatcher, targetWindow, targetOrigin, defaultTargetId);
+  }
+
+  /**
+   * Open message processing (register message handlers)
+   */
+  open() {
+    if (this._isOpen) return;
+    this.hooks.beforeOpen.call();
+    this._isOpen = true;
+    if (!this.registerHandlersFn) {
+      throw new Error(Messages.HUB_REGISTER_HANDLERS_NOT_SET);
+    }
+    this.registerHandlersFn();
+    this.hooks.afterOpen.call();
+  }
+
+  /**
+   * Close message processing (unregister message handlers, but don't release channel)
+   */
+  close() {
+    if (!this._isOpen) return;
+    this.hooks.beforeClose.call();
+    this._isOpen = false;
+
+    /** Unregister all handlers */
+    this.unregisterFns.forEach(fn => fn());
+    this.unregisterFns.length = 0;
+    this.hooks.unregisterHandler.call();
+    this.hooks.afterClose.call();
+  }
+
+  /**
+   * Whether it is open
+   */
+  get isOpen() {
+    return this._isOpen;
+  }
+
+  /**
+   * Get secretKey
+   */
+  get secretKey() {
+    return this.messageDispatcher.secretKey;
+  }
+
+  /**
+   * Destroy (close and release channel reference)
+   */
+  destroy() {
+    this.hooks.beforeDestroy.call();
+    /** Close first */
+    this.close();
+
+    /** Clear all pending maps and timeouts */
+    this.pending.clearAll();
+    this.warnOnceKeys.clear();
+    this.streamCallback = undefined;
+
+    /** Destroy dispatcher and release channel reference */
+    this.messageDispatcher.destroy();
+    releaseMessageChannel(this.messageDispatcher.getChannel());
+    this.hooks.afterDestroy.call();
+  }
+}

package/esm/endpoint/infra/inbox.js

@@ -0,0 +1,232 @@
+import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
+import "core-js/modules/es.array.slice.js";
+import "core-js/modules/es.promise.js";
+import "core-js/modules/es.regexp.to-string.js";
+import { MessageType, ProtocolVersion, Messages, formatMessage, MessageRole, WarnOnceKey, buildWarnOnceKey } from '../../constants';
+import { createPingResponder } from '../heartbeat/ping';
+import { SyncHook } from '../../utils/hooks';
+import { requestIframeLog } from '../../utils/logger';
+
+/**
+ * Pending request awaiting response
+ */
+
+/**
+ * RequestIframeEndpointInbox
+ *
+ * The endpoint "inbox" is responsible for handling inbound framework messages and
+ * driving pending request resolution by requestId.
+ *
+ * - Registers dispatcher handlers for ACK/ASYNC/RESPONSE/ERROR/STREAM_START + PING/PONG
+ * - Manages pending requests via hub.pending
+ */
+export class RequestIframeEndpointInbox {
+  constructor(hub, versionValidator) {
+    _defineProperty(this, "hooks", {
+      inbound: new SyncHook(),
+      pendingRegistered: new SyncHook(),
+      pendingUnregistered: new SyncHook(),
+      pendingResolved: new SyncHook(),
+      missingPending: new SyncHook()
+    });
+    this.hub = hub;
+    this.versionValidator = versionValidator !== null && versionValidator !== void 0 ? versionValidator : hub.versionValidator;
+  }
+
+  /**
+   * Register message handlers on hub.
+   */
+  registerHandlers() {
+    var handlerOptions = this.hub.createHandlerOptions(this.handleVersionError.bind(this));
+    handlerOptions.versionValidator = this.versionValidator;
+    var boundHandleClientResponse = this.handleClientResponse.bind(this);
+    this.hub.registerHandler(MessageType.ACK, boundHandleClientResponse, handlerOptions);
+    this.hub.registerHandler(MessageType.ASYNC, boundHandleClientResponse, handlerOptions);
+    this.hub.registerHandler(MessageType.RESPONSE, boundHandleClientResponse, handlerOptions);
+    this.hub.registerHandler(MessageType.ERROR, boundHandleClientResponse, handlerOptions);
+    this.hub.registerHandler(MessageType.PONG, this.handlePong.bind(this), handlerOptions);
+    this.hub.registerHandler(MessageType.PING, this.handlePing.bind(this), handlerOptions);
+    this.hub.registerHandler(MessageType.STREAM_START, boundHandleClientResponse, handlerOptions);
+  }
+
+  /**
+   * Client-side "isConnect" ping helper.
+   *
+   * - Sends PING(requireAck=true)
+   * - Resolves true when ACK or PONG arrives, false on timeout
+   */
+  pingIsConnect(params) {
+    var requestId = `ping_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    return new Promise(resolve => {
+      var timeoutId = this.hub.pending.setTimeout(() => {
+        this.hub.pending.delete(RequestIframeEndpointInbox.PENDING_IS_CONNECT, requestId);
+        resolve(false);
+      }, params.timeoutMs);
+      this.hub.pending.set(RequestIframeEndpointInbox.PENDING_IS_CONNECT, requestId, {
+        resolve,
+        timeoutId,
+        targetOrigin: params.targetOrigin,
+        originValidator: params.originValidator,
+        onPeerId: params.onPeerId
+      });
+      params.peer.sendMessage(MessageType.PING, requestId, {
+        requireAck: true,
+        targetId: params.targetId
+      });
+    });
+  }
+
+  /**
+   * Register pending request awaiting response
+   */
+  registerPendingRequest(requestId, resolve, reject, origin, originValidator) {
+    this.hub.pending.set(RequestIframeEndpointInbox.PENDING_REQUESTS, requestId, {
+      resolve,
+      reject,
+      origin,
+      originValidator
+    });
+    this.hooks.pendingRegistered.call(requestId, {
+      origin
+    });
+  }
+
+  /**
+   * Cancel pending response
+   */
+  unregisterPendingRequest(requestId) {
+    this.hub.pending.delete(RequestIframeEndpointInbox.PENDING_REQUESTS, requestId);
+    this.hooks.pendingUnregistered.call(requestId);
+  }
+  handlePing(data, context) {
+    var _this$hub$instanceId;
+    this.hooks.inbound.call(data, context);
+    var responder = createPingResponder({
+      hub: this.hub,
+      handledBy: (_this$hub$instanceId = this.hub.instanceId) !== null && _this$hub$instanceId !== void 0 ? _this$hub$instanceId : MessageRole.CLIENT,
+      includeTargetId: true
+    });
+    responder(data, context);
+  }
+
+  /**
+   * Handle protocol version error
+   */
+  handleVersionError(data, context, version) {
+    void context;
+    var pending = this.hub.pending.get(RequestIframeEndpointInbox.PENDING_REQUESTS, data.requestId);
+    if (pending) {
+      this.hub.pending.delete(RequestIframeEndpointInbox.PENDING_REQUESTS, data.requestId);
+      pending.reject(new Error(formatMessage(Messages.PROTOCOL_VERSION_TOO_LOW, version, ProtocolVersion.MIN_SUPPORTED)));
+    }
+  }
+
+  /**
+   * Handle client response
+   */
+  handleClientResponse(data, context) {
+    var _this$hub$instanceId4;
+    this.hooks.inbound.call(data, context);
+
+    /**
+     * isConnect waiter:
+     * - ACK is sent by the peer when it accepted the PING (auto-ack workflow)
+     * - We treat either ACK or PONG as a successful connectivity signal
+     */
+    if (data.type === MessageType.ACK) {
+      var pendingIsConnect = this.hub.pending.get(RequestIframeEndpointInbox.PENDING_IS_CONNECT, data.requestId);
+      if (pendingIsConnect) {
+        var _this$hub$instanceId3, _pendingIsConnect$onP;
+        // Must match the pending target origin (and originValidator if configured)
+        if (!this.hub.isOriginAllowedBy(context.origin, data, context, pendingIsConnect.targetOrigin, pendingIsConnect.originValidator)) {
+          var _this$hub$instanceId2;
+          // Mark handled (and auto-ack if requireAck) but ignore the signal
+          context.markAcceptedBy((_this$hub$instanceId2 = this.hub.instanceId) !== null && _this$hub$instanceId2 !== void 0 ? _this$hub$instanceId2 : MessageRole.CLIENT);
+          return;
+        }
+        context.markAcceptedBy((_this$hub$instanceId3 = this.hub.instanceId) !== null && _this$hub$instanceId3 !== void 0 ? _this$hub$instanceId3 : MessageRole.CLIENT);
+        this.hub.pending.clearTimeout(pendingIsConnect.timeoutId);
+        this.hub.pending.delete(RequestIframeEndpointInbox.PENDING_IS_CONNECT, data.requestId);
+        (_pendingIsConnect$onP = pendingIsConnect.onPeerId) === null || _pendingIsConnect$onP === void 0 || _pendingIsConnect$onP.call(pendingIsConnect, data.creatorId);
+        pendingIsConnect.resolve(true);
+        return;
+      }
+    }
+    var pending = this.hub.pending.get(RequestIframeEndpointInbox.PENDING_REQUESTS, data.requestId);
+    if (!pending) {
+      /**
+       * Pending request not found - ignore by default.
+       *
+       * If endpoint is already closed/destroyed, emit a warning to help debugging:
+       * this usually means the client was recreated/unmounted before the response arrived.
+       */
+      if (!this.hub.isOpen) {
+        this.hooks.missingPending.call(data, context);
+        this.hub.warnOnce(buildWarnOnceKey(WarnOnceKey.INBOX_MISSING_PENDING_WHEN_CLOSED, data.requestId), () => {
+          requestIframeLog('warn', formatMessage(Messages.CLIENT_SERVER_IGNORED_MESSAGE_WHEN_CLOSED, data.type, data.requestId));
+        });
+      }
+      return;
+    }
+
+    /** Validate origin */
+    if (!this.hub.isOriginAllowedBy(context.origin, data, context, pending.origin, pending.originValidator)) {
+      return;
+    }
+
+    /**
+     * Mark as handled so:
+     * - other client instances sharing the same channel won't also process it
+     * - MessageDispatcher can run its generalized requireAck auto-ack logic
+     */
+    context.markAcceptedBy((_this$hub$instanceId4 = this.hub.instanceId) !== null && _this$hub$instanceId4 !== void 0 ? _this$hub$instanceId4 : MessageRole.CLIENT);
+
+    /** ack, async, and stream_start don't delete pending (stream_start needs to keep pending for stream_data/stream_end) */
+    if (data.type === MessageType.ACK || data.type === MessageType.ASYNC || data.type === MessageType.STREAM_START) {
+      this.hooks.pendingResolved.call(data.requestId, data);
+      pending.resolve(data);
+      return;
+    }
+
+    /** response and error delete pending */
+    this.hub.pending.delete(RequestIframeEndpointInbox.PENDING_REQUESTS, data.requestId);
+    this.hooks.pendingResolved.call(data.requestId, data);
+    pending.resolve(data);
+  }
+
+  /**
+   * Handle PONG:
+   * - If it matches an existing pending request, resolve it.
+   * - Otherwise, ignore (facade may still use PONG for isConnect waiter).
+   */
+  handlePong(data, context) {
+    var _this$hub$instanceId7;
+    this.hooks.inbound.call(data, context);
+    var pendingIsConnect = this.hub.pending.get(RequestIframeEndpointInbox.PENDING_IS_CONNECT, data.requestId);
+    if (pendingIsConnect) {
+      var _this$hub$instanceId6, _pendingIsConnect$onP2;
+      if (!this.hub.isOriginAllowedBy(context.origin, data, context, pendingIsConnect.targetOrigin, pendingIsConnect.originValidator)) {
+        var _this$hub$instanceId5;
+        context.markAcceptedBy((_this$hub$instanceId5 = this.hub.instanceId) !== null && _this$hub$instanceId5 !== void 0 ? _this$hub$instanceId5 : MessageRole.CLIENT);
+        return;
+      }
+      context.markAcceptedBy((_this$hub$instanceId6 = this.hub.instanceId) !== null && _this$hub$instanceId6 !== void 0 ? _this$hub$instanceId6 : MessageRole.CLIENT);
+      this.hub.pending.clearTimeout(pendingIsConnect.timeoutId);
+      this.hub.pending.delete(RequestIframeEndpointInbox.PENDING_IS_CONNECT, data.requestId);
+      (_pendingIsConnect$onP2 = pendingIsConnect.onPeerId) === null || _pendingIsConnect$onP2 === void 0 || _pendingIsConnect$onP2.call(pendingIsConnect, data.creatorId);
+      pendingIsConnect.resolve(true);
+      return;
+    }
+    var pending = this.hub.pending.get(RequestIframeEndpointInbox.PENDING_REQUESTS, data.requestId);
+    if (!pending) return;
+    if (!this.hub.isOriginAllowedBy(context.origin, data, context, pending.origin, pending.originValidator)) {
+      return;
+    }
+    context.markAcceptedBy((_this$hub$instanceId7 = this.hub.instanceId) !== null && _this$hub$instanceId7 !== void 0 ? _this$hub$instanceId7 : MessageRole.CLIENT);
+    this.hub.pending.delete(RequestIframeEndpointInbox.PENDING_REQUESTS, data.requestId);
+    this.hooks.pendingResolved.call(data.requestId, data);
+    pending.resolve(data);
+  }
+}
+_defineProperty(RequestIframeEndpointInbox, "PENDING_REQUESTS", 'inbox:pendingRequests');
+_defineProperty(RequestIframeEndpointInbox, "PENDING_IS_CONNECT", 'inbox:pendingIsConnect');