request-iframe 0.1.0 → 0.2.0

package/esm/message/channel-cache.js

@@ -0,0 +1,108 @@
+import "core-js/modules/es.array.iterator.js";
+import "core-js/modules/es.map.js";
+import "core-js/modules/esnext.global-this.js";
+import "core-js/modules/web.dom-collections.for-each.js";
+import "core-js/modules/web.dom-collections.iterator.js";
+import { MessageChannel, ChannelType } from './channel';
+
+/**
+ * Global cache Symbol (used to store MessageChannel instance cache on window/globalThis).
+ *
+ * NOTE:
+ * - We MUST use Symbol.for() so multiple library copies (different bundles/versions)
+ *   can share the same cache.
+ * - Keep the symbol key stable for backward compatibility with older releases.
+ */
+var MESSAGE_CHANNEL_CACHE_SYMBOL = Symbol.for('__requestIframeMessageChannelCache__');
+
+/**
+ * Get the cache host object.
+ *
+ * We prefer `window` because MessageChannel itself is window-based (postMessage listener),
+ * and existing versions store the cache on window as well.
+ */
+function getCacheHost() {
+  if (typeof window !== 'undefined') return window;
+  // Fallback for non-browser environments; creating MessageChannel will likely fail anyway.
+  return globalThis;
+}
+
+/**
+ * Get the MessageChannel cache Map from the host.
+ */
+function getChannelCache() {
+  var host = getCacheHost();
+  if (!(MESSAGE_CHANNEL_CACHE_SYMBOL in host)) {
+    host[MESSAGE_CHANNEL_CACHE_SYMBOL] = new Map();
+  }
+  return host[MESSAGE_CHANNEL_CACHE_SYMBOL];
+}
+
+/**
+ * Generate cache key.
+ * Format: "type:secretKey" or "type:" when no secretKey.
+ */
+function getCacheKey(type, secretKey) {
+  return `${type}:${secretKey !== null && secretKey !== void 0 ? secretKey : ''}`;
+}
+
+/**
+ * Get or create MessageChannel instance.
+ *
+ * - Within the same window, only one channel is created per type + secretKey.
+ * - Uses reference counting to manage lifecycle.
+ */
+export function getOrCreateMessageChannel(secretKey, type = ChannelType.POST_MESSAGE) {
+  var cache = getChannelCache();
+  var key = getCacheKey(type, secretKey);
+  var channel = cache.get(key);
+  if (!channel) {
+    channel = new MessageChannel(secretKey, type);
+    cache.set(key, channel);
+  }
+  channel.addRef();
+  return channel;
+}
+
+/**
+ * Release MessageChannel reference.
+ *
+ * - When reference count reaches 0, destroy channel and remove from cache.
+ */
+export function releaseMessageChannel(channel) {
+  var refCount = channel.release();
+  if (refCount > 0) return;
+  var cache = getChannelCache();
+  var key = getCacheKey(channel.type, channel.secretKey);
+  if (cache.get(key) === channel) {
+    cache.delete(key);
+    channel.destroy();
+  }
+}
+
+/**
+ * Clear MessageChannel cache (mainly for testing).
+ *
+ * - No args: clear all channels
+ * - string arg: treated as secretKey filter
+ * - params arg: filter by secretKey/type
+ */
+export function clearMessageChannelCache(arg) {
+  var cache = getChannelCache();
+  if (!arg) {
+    cache.forEach(channel => {
+      channel.destroy();
+    });
+    cache.clear();
+    return;
+  }
+  var params = typeof arg === 'string' ? {
+    secretKey: arg
+  } : arg;
+  cache.forEach((channel, key) => {
+    if (params.type && channel.type !== params.type) return;
+    if (typeof params.secretKey === 'string' && channel.secretKey !== params.secretKey) return;
+    cache.delete(key);
+    channel.destroy();
+  });
+}

package/esm/message/channel.js

@@ -7,11 +7,25 @@ import "core-js/modules/es.object.get-own-property-descriptors.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 { isValidPostMessage, createPostMessage, isWindowAvailable } from '../utils';
+import { isValidPostMessage, createPostMessage } from '../utils/protocol';
+import { isWindowAvailable } from '../utils/window';
+import { OriginConstant } from '../constants';
+import { requestIframeLog } from '../utils/logger';
+import { SyncHook } from '../utils/hooks';
 
 /**
  * Message context (extracted from MessageEvent, transport-agnostic)
  */
+export var MessageContextStage = {
+  /** Message is not handled by any instance yet */
+  PENDING: 'pending',
+  /** Message is claimed/being handled (handledBy is set, but not accepted) */
+  HANDLING: 'handling',
+  /** Message is accepted for processing (acceptedBy is set) */
+  ACCEPTED: 'accepted',
+  /** Message handling finished (synchronous dispatch finished) */
+  DONE: 'done'
+};
 
 /**
  * Message receiver callback
@@ -98,10 +112,83 @@ export class MessageChannel {
    * This encapsulates transport-specific details
    */
   extractContext(event) {
-    return {
-      source: event.source,
+    var _ref;
+    var context = {
+      source: (_ref = event.source) !== null && _ref !== void 0 ? _ref : undefined,
       origin: event.origin
     };
+    var stateChangeHook;
+    var ensureStateChangeHook = () => {
+      if (!stateChangeHook) {
+        stateChangeHook = new SyncHook();
+      }
+      return stateChangeHook;
+    };
+    var emitStateChange = (prev, next) => {
+      if (!stateChangeHook) return;
+      stateChangeHook.call(prev, next, context);
+    };
+
+    /**
+     * Attach stable internal helper methods.
+     *
+     * We intentionally make them non-enumerable so typical object inspection won't be polluted.
+     */
+    var markHandledBy = handledBy => {
+      var prev = getStage();
+      if (!context.handledBy) {
+        context.handledBy = handledBy;
+      }
+      var next = getStage();
+      if (prev !== next) emitStateChange(prev, next);
+    };
+    var markAcceptedBy = handledBy => {
+      var prev = getStage();
+      if (!context.acceptedBy) {
+        context.acceptedBy = handledBy;
+      }
+      markHandledBy(handledBy);
+      var next = getStage();
+      if (prev !== next) emitStateChange(prev, next);
+    };
+    var markDoneBy = doneBy => {
+      var prev = getStage();
+      if (!context.doneBy) {
+        context.doneBy = doneBy;
+      }
+      var next = getStage();
+      if (prev !== next) emitStateChange(prev, next);
+    };
+    var getStage = () => {
+      if (context.doneBy) return MessageContextStage.DONE;
+      if (context.acceptedBy) return MessageContextStage.ACCEPTED;
+      if (context.handledBy) return MessageContextStage.HANDLING;
+      return MessageContextStage.PENDING;
+    };
+    var onStateChange = (name, fn) => {
+      return ensureStateChangeHook().tap(name, fn);
+    };
+    Object.defineProperty(context, 'markHandledBy', {
+      value: markHandledBy,
+      enumerable: false
+    });
+    Object.defineProperty(context, 'markAcceptedBy', {
+      value: markAcceptedBy,
+      enumerable: false
+    });
+    Object.defineProperty(context, 'markDoneBy', {
+      value: markDoneBy,
+      enumerable: false
+    });
+    Object.defineProperty(context, 'getStage', {
+      value: getStage,
+      enumerable: false
+    });
+    Object.defineProperty(context, 'onStateChange', {
+      value: onStateChange,
+      enumerable: false
+    });
+    return context;
   }
 
   /**
@@ -130,7 +217,7 @@ export class MessageChannel {
       try {
         receiver(data, context);
       } catch (e) {
-        console.error('[request-iframe] Receiver error:', e);
+        requestIframeLog('error', 'Receiver error', e);
       }
     });
   }
@@ -141,7 +228,7 @@ export class MessageChannel {
    * @param message message data (already formatted as PostMessageData)
    * @param targetOrigin target origin (defaults to '*')
    */
-  send(target, message, targetOrigin = '*') {
+  send(target, message, targetOrigin = OriginConstant.ANY) {
     if (!isWindowAvailable(target)) {
       return false;
     }

package/esm/message/dispatcher.js

@@ -18,8 +18,12 @@ import "core-js/modules/es.object.get-own-property-descriptors.js";
 import "core-js/modules/es.regexp.constructor.js";
 import "core-js/modules/es.regexp.exec.js";
 import "core-js/modules/es.regexp.to-string.js";
-import { MessageRole, MessageType } from '../constants';
-import { getProtocolVersion, createPostMessage } from '../utils';
+import { AutoAckConstant, MessageRole, MessageType, OriginConstant } from '../constants';
+import { getProtocolVersion, createPostMessage } from '../utils/protocol';
+import { isFunction } from '../utils/is';
+import { getAckId, getAckMeta } from '../utils/ack';
+import { SyncHook } from '../utils/hooks';
+import { requestIframeLog } from '../utils/logger';
 
 /**
  * Message handler function type
@@ -60,17 +64,15 @@ import { getProtocolVersion, createPostMessage } from '../utils';
  */
 export class MessageDispatcher {
   constructor(channel, role, instanceId) {
-    /** Secret key for message isolation */
-    /** Channel type */
-    /** Role of this dispatcher ('client' or 'server') */
-    /** Instance ID of the client/server that owns this dispatcher */
-    /** Underlying message channel */
-    /**
-     * Fallback target for sending auto-ack messages when MessageEvent.source is unavailable.
-     * - In real browser postMessage events, `source` should normally exist.
-     * - This is primarily used for unit tests or edge environments that synthesize MessageEvent without `source`.
-     */
-    _defineProperty(this, "fallbackTargetOrigin", '*');
+    _defineProperty(this, "hooks", {
+      inbound: new SyncHook(),
+      beforeSend: new SyncHook(),
+      afterSend: new SyncHook(),
+      sendError: new SyncHook()
+    });
+    _defineProperty(this, "autoAckMaxMetaLength", AutoAckConstant.MAX_META_LENGTH);
+    _defineProperty(this, "autoAckMaxIdLength", AutoAckConstant.MAX_ID_LENGTH);
+    _defineProperty(this, "fallbackTargetOrigin", OriginConstant.ANY);
     /** Message handler list */
     _defineProperty(this, "handlers", []);
     /** Reference count (for determining if can be destroyed when cached) */
@@ -93,11 +95,26 @@ export class MessageDispatcher {
   /**
    * Set fallback target for outgoing auto-ack messages.
    */
-  setFallbackTarget(targetWindow, targetOrigin = '*') {
+  setFallbackTarget(targetWindow, targetOrigin = OriginConstant.ANY) {
     this.fallbackTargetWindow = targetWindow;
     this.fallbackTargetOrigin = targetOrigin;
   }
 
+  /**
+   * Configure auto-ack echo limits (advanced/internal).
+   *
+   * @internal
+   */
+  setAutoAckLimits(limits) {
+    if (!limits || typeof limits !== 'object') return;
+    if (typeof limits.maxMetaLength === 'number' && Number.isFinite(limits.maxMetaLength) && limits.maxMetaLength >= 0) {
+      this.autoAckMaxMetaLength = limits.maxMetaLength;
+    }
+    if (typeof limits.maxIdLength === 'number' && Number.isFinite(limits.maxIdLength) && limits.maxIdLength >= 0) {
+      this.autoAckMaxIdLength = limits.maxIdLength;
+    }
+  }
+
   // ==================== Reference Counting ====================
 
   /**
@@ -183,79 +200,80 @@ export class MessageDispatcher {
         return;
       }
     }
-    var type = data.type;
-    var version = getProtocolVersion(data);
-
-    /**
-     * Auto-ack state for this incoming message.
-     * - We intentionally couple this to `context.handledBy` as the "accepted/handled" signal.
-     * - For some message types we only ack if they are truly handled (e.g. response requireAck),
-     *   so we avoid incorrectly acknowledging messages when there is no pending consumer.
-     *
-     * Implementation note:
-     * We avoid using Proxy for compatibility and instead hook the `handledBy` property
-     * with a setter so handlers can trigger the ack immediately when they "accept" a message.
-     */
-    var autoAckState = {
-      sent: false
-    };
-    var originalHandledBy = context.handledBy;
-    var handledByValue = originalHandledBy;
     try {
-      Object.defineProperty(context, 'handledBy', {
-        configurable: true,
-        enumerable: true,
-        get() {
-          return handledByValue;
-        },
-        set: value => {
-          handledByValue = value;
-          if (value && !autoAckState.sent) {
-            autoAckState.sent = true;
-            this.tryAutoAck(data, context);
-          }
-        }
-      });
-    } catch (_unused) {
+      this.hooks.inbound.call(data, context);
+      var _type = data.type;
+      var _version = getProtocolVersion(data);
+
       /**
-       * In very rare cases `defineProperty` may fail (frozen object).
-       * We still proceed without auto-ack; handlers will continue to work as before.
+       * Auto-ack state for this incoming message.
+       *
+       * Design notes:
+       * - We only auto-ack after the message is truly handled (context.handledBy is set)
+       *   AND accepted (context.acceptedBy is set).
+       * - This prevents incorrectly acknowledging messages when there is no pending consumer.
        */
-    }
-    var _iterator = _createForOfIteratorHelper(this.handlers),
-      _step;
-    try {
-      for (_iterator.s(); !(_step = _iterator.n()).done;) {
-        var entry = _step.value;
-        if (this.matchType(type, entry.matcher)) {
-          // If message has been handled by a previous handler, stop processing
-          if (context.handledBy) {
-            break;
-          }
+      var autoAckState = {
+        sent: false
+      };
+      var maybeAutoAck = () => {
+        if (autoAckState.sent) return;
+        if (!context.handledBy) return;
+        if (!context.acceptedBy) return;
+        autoAckState.sent = true;
+        this.tryAutoAck(data, context);
+      };
+      var _iterator = _createForOfIteratorHelper(this.handlers),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var entry = _step.value;
+          if (this.matchType(_type, entry.matcher)) {
+            // If message has been handled by a previous handler, stop processing
+            if (context.handledBy) {
+              break;
+            }
 
-          // If handler specified version validation
-          if (entry.versionValidator && version !== undefined) {
-            if (!entry.versionValidator(version)) {
-              var _entry$onVersionError;
-              // Version incompatible, call error handler (if any)
-              (_entry$onVersionError = entry.onVersionError) === null || _entry$onVersionError === void 0 || _entry$onVersionError.call(entry, data, context, version);
-              continue; // Skip this handler, try other handlers
+            // If handler specified version validation
+            if (entry.versionValidator && _version !== undefined) {
+              if (!entry.versionValidator(_version)) {
+                var _entry$onVersionError;
+                // Version incompatible, call error handler (if any)
+                (_entry$onVersionError = entry.onVersionError) === null || _entry$onVersionError === void 0 || _entry$onVersionError.call(entry, data, context, _version);
+                continue; // Skip this handler, try other handlers
+              }
+            }
+            try {
+              entry.handler(data, context);
+              // After handler execution, check if it marked the message as handled
+              // If context.handledBy is set by the handler, subsequent handlers will be skipped
+            } catch (e) {
+              // Ignore handler exception, continue executing other handlers
+              requestIframeLog('error', 'Handler error', e);
+            } finally {
+              // Auto-ack once the message is accepted + handled.
+              maybeAutoAck();
             }
-          }
-          try {
-            entry.handler(data, context);
-            // After handler execution, check if it marked the message as handled
-            // If context.handledBy is set by the handler, subsequent handlers will be skipped
-          } catch (e) {
-            // Ignore handler exception, continue executing other handlers
-            console.error('[request-iframe] Handler error:', e);
           }
         }
+
+        // Fallback: if a handler accepted+handled without throwing, ensure we auto-ack.
+        // (This is safe due to autoAckState guard.)
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
       }
-    } catch (err) {
-      _iterator.e(err);
+      maybeAutoAck();
     } finally {
-      _iterator.f();
+      /**
+       * Mark as "done" only when this dispatcher actually claimed/handled this message.
+       * - If the message was never claimed (handledBy not set), we keep `doneBy` empty so another
+       *   dispatcher/handler still has a chance to process it.
+       */
+      if (context.handledBy) {
+        context.markDoneBy(context.handledBy);
+      }
     }
   }
 
@@ -277,29 +295,54 @@ export class MessageDispatcher {
     var type = data.type;
 
     // Don't auto-ack ack messages (avoid loops)
-    if (type === MessageType.ACK || type === MessageType.RECEIVED) return;
-    var shouldAckRequest = type === MessageType.REQUEST && data.requireAck !== false;
-    var shouldAckPing = type === MessageType.PING && data.requireAck === true;
-    var shouldAckResponse = (type === MessageType.RESPONSE || type === MessageType.ERROR) && data.requireAck === true;
-    if ((shouldAckRequest || shouldAckPing) && context.accepted === true) {
-      // Delivery acknowledgment for request/ping
+    if (type === MessageType.ACK) return;
+
+    /**
+     * ACK-only requireAck workflow (no compatibility guarantees):
+     * - For any message with `requireAck === true`, once the message is accepted/handled
+     *   (via `context.acceptedBy` + `context.handledBy`),
+     *   we reply with `ack`.
+     *
+     * This unifies:
+     * - request delivery confirmation
+     * - response receipt confirmation
+     * - stream frame delivery confirmation (e.g. stream_data per-frame ack)
+     */
+    if (data.requireAck === true && !!context.acceptedBy) {
+      var ack = this.getAutoAckEchoPayload(data.ack);
       this.sendMessage(targetWindow, targetOrigin, MessageType.ACK, data.requestId, {
         path: data.path,
         targetId: data.creatorId,
-        ackMeta: data.ackMeta
-      });
-      return;
-    }
-    if (shouldAckResponse && context.accepted === true) {
-      // Receipt acknowledgment for response/error
-      this.sendMessage(targetWindow, targetOrigin, MessageType.RECEIVED, data.requestId, {
-        path: data.path,
-        targetId: data.creatorId,
-        ackMeta: data.ackMeta
+        ack
       });
     }
   }
 
+  /**
+   * Limit echoed ack payload size for auto-ack replies.
+   *
+   * We only echo a fixed shape `{ id, meta?: string }`:
+   * - If meta is too long, we drop meta and only echo `{ id }`.
+   * - If id is missing or too long, omit `ack` field.
+   */
+  getAutoAckEchoPayload(rawAck) {
+    if (rawAck === undefined) return undefined;
+    var id = getAckId(rawAck);
+    if (id === undefined) return undefined;
+    if (typeof id === 'string' && id.length > this.autoAckMaxIdLength) return undefined;
+    var meta = getAckMeta(rawAck);
+    if (meta === undefined) return {
+      id
+    };
+    if (meta.length > this.autoAckMaxMetaLength) return {
+      id
+    };
+    return {
+      id,
+      meta
+    };
+  }
+
   /**
    * Check if message type matches
    */
@@ -310,7 +353,7 @@ export class MessageDispatcher {
     if (matcher instanceof RegExp) {
       return matcher.test(type);
     }
-    if (typeof matcher === 'function') {
+    if (isFunction(matcher)) {
       return matcher(type);
     }
     return false;
@@ -324,7 +367,7 @@ export class MessageDispatcher {
    * @param message message data (already formatted as PostMessageData)
    * @param targetOrigin target origin (defaults to '*')
    */
-  send(target, message, targetOrigin = '*') {
+  send(target, message, targetOrigin = OriginConstant.ANY) {
     // Automatically set role and creatorId if not already set (for backward compatibility)
     if (message.role === undefined) {
       message.role = this.role;
@@ -332,7 +375,15 @@ export class MessageDispatcher {
     if (message.creatorId === undefined && this.instanceId) {
       message.creatorId = this.instanceId;
     }
-    return this.channel.send(target, message, targetOrigin);
+    this.hooks.beforeSend.call(target, targetOrigin, message);
+    try {
+      var _ok = this.channel.send(target, message, targetOrigin);
+      this.hooks.afterSend.call(target, targetOrigin, message, _ok);
+      return _ok;
+    } catch (e) {
+      this.hooks.sendError.call(target, targetOrigin, message, e);
+      throw e;
+    }
   }
 
   /**
@@ -351,7 +402,7 @@ export class MessageDispatcher {
       creatorId: this.instanceId,
       secretKey: this.secretKey
     }));
-    return this.channel.send(target, message, targetOrigin);
+    return this.send(target, message, targetOrigin);
   }
 
   // ==================== Utilities ====================

package/esm/stream/error.js

@@ -0,0 +1,22 @@
+/**
+ * Stream-specific error type.
+ *
+ * Notes:
+ * - This is for stream lifecycle / protocol / binding errors (not request/response errors).
+ * - Use `RequestIframeError` for request/response level failures.
+ */
+export class RequestIframeStreamError extends Error {
+  constructor(params) {
+    super(params.message);
+    this.name = 'RequestIframeStreamError';
+    this.code = params.code;
+    this.streamId = params.streamId;
+    this.requestId = params.requestId;
+    this.cause = params.cause;
+
+    // Maintain proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, RequestIframeStreamError);
+    }
+  }
+}

package/esm/stream/index.js

@@ -7,8 +7,10 @@ export * from './types';
 export { IframeWritableStream } from './writable-stream';
 export { IframeFileWritableStream } from './file-stream';
 
+// Stream error
+export { RequestIframeStreamError } from './error';
 // Readable stream (client-side)
-export { IframeReadableStream, StreamMessageHandler } from './readable-stream';
+export { IframeReadableStream } from './readable-stream';
 export { IframeFileReadableStream } from './file-stream';
 
 // Type checking utility functions