request-iframe 0.1.1 → 0.2.1

package/esm/impl/server.js

@@ -0,0 +1,568 @@
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+import "core-js/modules/es.array.includes.js";
+import "core-js/modules/es.symbol.description.js";
+import "core-js/modules/es.array.from.js";
+import "core-js/modules/es.array.iterator.js";
+import "core-js/modules/es.array.slice.js";
+import "core-js/modules/es.map.js";
+import "core-js/modules/es.object.entries.js";
+import "core-js/modules/es.promise.js";
+import "core-js/modules/es.regexp.exec.js";
+import "core-js/modules/es.string.includes.js";
+import "core-js/modules/es.string.match.js";
+import "core-js/modules/web.dom-collections.for-each.js";
+import "core-js/modules/es.regexp.to-string.js";
+import "core-js/modules/web.dom-collections.iterator.js";
+import { matchPath, matchPathWithParams } from '../utils/path-match';
+import { ServerRequestImpl } from './request';
+import { ServerResponseImpl } from './response';
+import { generateInstanceId } from '../utils/id';
+import { RequestIframeEndpointFacade, buildStreamStartTimeoutErrorPayload, autoResolveIframeFileReadableStream } from '../endpoint';
+import { MessageType, ErrorCode, HttpStatus, HttpStatusText, Messages, DefaultTimeout, ProtocolVersion, formatMessage, MessageRole, StreamType as StreamTypeConstant, WarnOnceKey, buildWarnOnceKey } from '../constants';
+import { isPromise } from '../utils/promise';
+import { isFunction } from '../utils/is';
+import { requestIframeLog } from '../utils/logger';
+
+/**
+ * Middleware item (contains path matcher and middleware function)
+ */
+
+/**
+ * Server configuration options
+ */
+
+/**
+ * RequestIframeServer implementation
+ * Uses shared MessageDispatcher (backed by MessageChannel) to listen for and send messages
+ */
+export class RequestIframeServerImpl {
+  constructor(options) {
+    var _options$ackTimeout, _options$maxConcurren;
+    _defineProperty(this, "handlers", new Map());
+    _defineProperty(this, "middlewares", []);
+    /** Use custom id if provided, otherwise generate one */
+    this.id = (options === null || options === void 0 ? void 0 : options.id) || generateInstanceId();
+    var endpoint = new RequestIframeEndpointFacade({
+      role: MessageRole.SERVER,
+      instanceId: this.id,
+      secretKey: options === null || options === void 0 ? void 0 : options.secretKey,
+      versionValidator: options === null || options === void 0 ? void 0 : options.versionValidator,
+      autoAckMaxMetaLength: options === null || options === void 0 ? void 0 : options.autoAckMaxMetaLength,
+      autoAckMaxIdLength: options === null || options === void 0 ? void 0 : options.autoAckMaxIdLength,
+      streamDispatcher: {
+        handledBy: this.id
+      },
+      heartbeat: {
+        pendingBucket: RequestIframeServerImpl.PENDING_PONGS,
+        handledBy: this.id,
+        isOriginAllowed: (d, ctx) => this.isOriginAllowed(d, ctx),
+        warnMissingPendingWhenClosed: d => {
+          this.hub.warnOnce(buildWarnOnceKey(WarnOnceKey.SERVER_MISSING_PENDING_WHEN_CLOSED, d.type, d.requestId), () => {
+            requestIframeLog('warn', formatMessage(Messages.SERVER_IGNORED_MESSAGE_WHEN_CLOSED, d.type, d.requestId));
+          });
+        }
+      },
+      originValidator: {
+        allowedOrigins: options === null || options === void 0 ? void 0 : options.allowedOrigins,
+        validateOrigin: options === null || options === void 0 ? void 0 : options.validateOrigin
+      }
+    });
+    this.endpoint = endpoint;
+    this.hub = endpoint.hub;
+    this.originValidator = endpoint.originValidator;
+    this.ackTimeout = (_options$ackTimeout = options === null || options === void 0 ? void 0 : options.ackTimeout) !== null && _options$ackTimeout !== void 0 ? _options$ackTimeout : DefaultTimeout.ACK;
+    this.maxConcurrentRequestsPerClient = (_options$maxConcurren = options === null || options === void 0 ? void 0 : options.maxConcurrentRequestsPerClient) !== null && _options$maxConcurren !== void 0 ? _options$maxConcurren : Number.POSITIVE_INFINITY;
+    var warnMissingPendingWhenClosed = d => {
+      this.hub.warnOnce(buildWarnOnceKey(WarnOnceKey.SERVER_MISSING_PENDING_WHEN_CLOSED, d.type, d.requestId), () => {
+        requestIframeLog('warn', formatMessage(Messages.SERVER_IGNORED_MESSAGE_WHEN_CLOSED, d.type, d.requestId));
+      });
+    };
+    var handlerOptions = this.hub.createHandlerOptions(this.handleVersionError.bind(this));
+
+    // Server business entry: REQUEST handler
+    this.endpoint.onOpen(() => {
+      this.hub.registerHandler(MessageType.REQUEST, (data, context) => this.handleRequest(data, context), handlerOptions);
+    });
+
+    // Server base infra: ping/pong/ack/stream handlers (facade-managed)
+    this.endpoint.registerServerBaseHandlers({
+      handlerOptions,
+      handledBy: this.id,
+      includeTargetIdInPong: false,
+      isOriginAllowed: (d, ctx) => this.isOriginAllowed(d, ctx),
+      warnMissingPendingWhenClosed,
+      pendingAckBucket: RequestIframeServerImpl.PENDING_ACKS,
+      pendingStreamStartBucket: RequestIframeServerImpl.PENDING_STREAM_REQUESTS,
+      expectedStreamStartRole: MessageRole.CLIENT
+    });
+
+    /** Auto-open by default (unless explicitly set to false) */
+    if ((options === null || options === void 0 ? void 0 : options.autoOpen) !== false) {
+      this.open();
+    }
+  }
+  get dispatcher() {
+    return this.hub.messageDispatcher;
+  }
+
+  /** Message isolation key (read-only) */
+  get secretKey() {
+    return this.hub.secretKey;
+  }
+
+  /** Whether message handling is enabled */
+  get isOpen() {
+    return this.hub.isOpen;
+  }
+
+  /** Enable message handling (register message handler) */
+  open() {
+    this.hub.open();
+  }
+
+  /** Disable message handling (unregister message handler, but don't release resources) */
+  close() {
+    this.hub.close();
+  }
+
+  /** Get the underlying MessageDispatcher */
+  get messageDispatcher() {
+    return this.hub.messageDispatcher;
+  }
+
+  /**
+   * Check whether an incoming message origin is allowed.
+   */
+  isOriginAllowed(data, context) {
+    if (!this.originValidator) return true;
+    try {
+      return this.originValidator(context.origin, data, context);
+    } catch (_unused) {
+      return false;
+    }
+  }
+
+  /**
+   * Build a per-client key used for concurrency limiting.
+   * We intentionally include origin to prevent cross-origin collisions.
+   */
+  getClientKey(origin, creatorId) {
+    return `${origin}::${creatorId || 'unknown'}`;
+  }
+
+  /**
+   * Handle protocol version error
+   */
+  handleVersionError(data, context, version) {
+    if (!context.source) return;
+
+    // Send protocol version incompatibility error
+    // Window check is handled in MessageDispatcher
+    this.dispatcher.sendMessage(context.source, context.origin, MessageType.ERROR, data.requestId, {
+      path: data.path,
+      status: HttpStatus.BAD_REQUEST,
+      statusText: Messages.PROTOCOL_VERSION_UNSUPPORTED,
+      error: {
+        message: formatMessage(Messages.PROTOCOL_VERSION_TOO_LOW, version, ProtocolVersion.MIN_SUPPORTED),
+        code: ErrorCode.PROTOCOL_UNSUPPORTED
+      }
+    });
+  }
+  handleRequestError(res, targetWindow, targetOrigin, data, err) {
+    if (!res._sent) {
+      res._markSent();
+      /** 
+       * Use INTERNAL_SERVER_ERROR (500) for handler errors unless a different error status code was explicitly set.
+       * If statusCode is still the default OK (200), override it to INTERNAL_SERVER_ERROR.
+       */
+      var errorStatus = res.statusCode === HttpStatus.OK ? HttpStatus.INTERNAL_SERVER_ERROR : res.statusCode;
+
+      // Window check is handled in MessageDispatcher
+      this.dispatcher.sendMessage(targetWindow, targetOrigin, MessageType.ERROR, data.requestId, {
+        path: data.path,
+        error: {
+          message: err && err.message || Messages.REQUEST_FAILED,
+          code: err && err.code || ErrorCode.REQUEST_ERROR
+        },
+        status: errorStatus,
+        statusText: HttpStatusText[errorStatus] || HttpStatusText[HttpStatus.INTERNAL_SERVER_ERROR],
+        headers: res.headers,
+        targetId: data.creatorId
+      });
+    }
+  }
+  handleRequestResult(res, targetWindow, targetOrigin, data, result) {
+    if (!res._sent && result !== undefined) {
+      res.send(result);
+    } else if (!res._sent) {
+      res._markSent();
+      this.dispatcher.sendMessage(targetWindow, targetOrigin, MessageType.ERROR, data.requestId, {
+        path: data.path,
+        error: {
+          message: Messages.NO_RESPONSE_SENT,
+          code: ErrorCode.NO_RESPONSE
+        },
+        status: HttpStatus.INTERNAL_SERVER_ERROR,
+        statusText: HttpStatusText[HttpStatus.INTERNAL_SERVER_ERROR],
+        headers: res.headers
+      });
+    }
+  }
+
+  /**
+   * Find matching handler and extract path parameters
+   * @param requestPath The actual request path
+   * @returns Handler function and extracted parameters, or null if not found
+   */
+  findHandler(requestPath) {
+    var prefixedRequestPath = this.dispatcher.prefixPath(requestPath);
+
+    // First try exact match (for backward compatibility and performance)
+    var exactHandler = this.handlers.get(prefixedRequestPath);
+    if (exactHandler) {
+      return {
+        handler: exactHandler,
+        params: {}
+      };
+    }
+
+    // Then try parameter matching (e.g., '/api/users/:id' matches '/api/users/123')
+    var _iterator = _createForOfIteratorHelper(this.handlers.entries()),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var _step$value = _slicedToArray(_step.value, 2),
+          registeredPath = _step$value[0],
+          handler = _step$value[1];
+        // Check if registered path contains parameters
+        if (registeredPath.includes(':')) {
+          var matchResult = matchPathWithParams(prefixedRequestPath, registeredPath);
+          if (matchResult.match) {
+            return {
+              handler,
+              params: matchResult.params
+            };
+          }
+        }
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+    return null;
+  }
+
+  /**
+   * Handle request
+   */
+  handleRequest(data, context) {
+    // If targetId is specified, only process if it matches this server's id
+    if (!data.path || data.targetId && data.targetId !== this.id) return;
+    if (!context.source) return;
+    if (!this.isOriginAllowed(data, context)) return;
+
+    // If message has already been handled by another server instance, skip processing
+    if (context.handledBy) {
+      return;
+    }
+    var targetWindow = context.source;
+    var targetOrigin = context.origin;
+
+    // Find matching handler and extract path parameters
+    var handlerMatch = this.findHandler(data.path);
+    if (!handlerMatch) {
+      // No handler found in this instance
+      // Mark as handled by this instance (using special marker) to prevent other instances from processing
+      // This ensures only one instance sends the error response
+      context.markHandledBy(this.id);
+
+      // Send METHOD_NOT_FOUND error
+      // Use request's creatorId as targetId to route back to the correct client
+      // Window check is handled in MessageDispatcher
+      this.dispatcher.sendMessage(targetWindow, targetOrigin, MessageType.ERROR, data.requestId, {
+        path: data.path,
+        error: {
+          message: Messages.METHOD_NOT_FOUND,
+          code: ErrorCode.METHOD_NOT_FOUND
+        },
+        status: HttpStatus.NOT_FOUND,
+        statusText: HttpStatusText[HttpStatus.NOT_FOUND],
+        targetId: data.creatorId
+      });
+      return;
+    }
+    var handlerFn = handlerMatch.handler,
+      params = handlerMatch.params;
+    var clientKey = this.getClientKey(targetOrigin, data.creatorId);
+    var acquired = this.hub.limiter.tryAcquire(RequestIframeServerImpl.LIMIT_IN_FLIGHT_BY_CLIENT, clientKey, this.maxConcurrentRequestsPerClient);
+    if (!acquired) {
+      // Prevent other server instances from also responding
+      context.markHandledBy(this.id);
+      this.dispatcher.sendMessage(targetWindow, targetOrigin, MessageType.ERROR, data.requestId, {
+        path: data.path,
+        error: {
+          message: formatMessage(Messages.TOO_MANY_REQUESTS, this.maxConcurrentRequestsPerClient),
+          code: ErrorCode.TOO_MANY_REQUESTS
+        },
+        status: HttpStatus.TOO_MANY_REQUESTS,
+        statusText: HttpStatusText[HttpStatus.TOO_MANY_REQUESTS],
+        requireAck: data.requireAck,
+        ack: data.ack,
+        targetId: data.creatorId
+      });
+      return;
+    }
+
+    // Mark as accepted so MessageDispatcher can auto-send ACK (delivery confirmation)
+    context.markAcceptedBy(this.id);
+
+    // Create response object with channel reference
+    // Pass request's creatorId as targetId so responses are routed back to the correct client
+    var peer = this.hub.createOutbox(targetWindow, targetOrigin, data.creatorId);
+    var res = new ServerResponseImpl(data.requestId, data.path || '', this.id, peer, {
+      registerStreamHandler: (streamId, handler) => {
+        this.endpoint.streamDispatcher.register(streamId, handler);
+      },
+      unregisterStreamHandler: streamId => {
+        this.endpoint.streamDispatcher.unregister(streamId);
+      },
+      heartbeat: () => this.endpoint.pingPeer(targetWindow, targetOrigin, this.ackTimeout, data.creatorId),
+      onSent: () => this.hub.limiter.release(RequestIframeServerImpl.LIMIT_IN_FLIGHT_BY_CLIENT, clientKey)
+    });
+
+    // Register callback waiting for client acknowledgment
+    this.endpoint.registerPendingAck({
+      requestId: data.requestId,
+      timeoutMs: this.ackTimeout,
+      pendingBucket: RequestIframeServerImpl.PENDING_ACKS,
+      resolve: (received, ack) => {
+        res._triggerAck(received, ack);
+      }
+    });
+
+    // Client sends body as stream: wait for stream_start, then create readable stream and call handler
+    // If streamId is present, this is a stream request
+    var streamId = data.streamId;
+    if (streamId) {
+      var streamStartTimeout = this.ackTimeout;
+      this.endpoint.registerIncomingStreamStartWaiter({
+        pendingBucket: RequestIframeServerImpl.PENDING_STREAM_REQUESTS,
+        requestId: data.requestId,
+        streamId,
+        timeoutMs: streamStartTimeout,
+        targetWindow,
+        targetOrigin,
+        onTimeout: () => {
+          if (!res._sent) {
+            res._markSent();
+            this.dispatcher.sendMessage(targetWindow, targetOrigin, MessageType.ERROR, data.requestId, buildStreamStartTimeoutErrorPayload({
+              path: data.path || '',
+              timeoutMs: streamStartTimeout,
+              requireAck: data.requireAck,
+              ack: data.ack,
+              targetId: data.creatorId
+            }));
+          }
+        },
+        continue: ({
+          stream,
+          info,
+          data: streamStartData
+        }) => {
+          // Create request object with path parameters
+          var req = new ServerRequestImpl(data, context, res, params);
+
+          // File stream: optionally auto-resolve to File/Blob before calling handler
+          if ((info === null || info === void 0 ? void 0 : info.type) === StreamTypeConstant.FILE) {
+            var fileStream = stream;
+            if (info !== null && info !== void 0 && info.autoResolve) {
+              autoResolveIframeFileReadableStream({
+                fileStream,
+                info
+              }).then(fileData => {
+                req.body = fileData;
+                req.stream = undefined;
+                this.runMiddlewares(req, res, () => {
+                  try {
+                    var result = handlerFn(req, res);
+                    if (isPromise(result)) {
+                      this.dispatcher.sendMessage(targetWindow, targetOrigin, MessageType.ASYNC, streamStartData.requestId, {
+                        path: data.path,
+                        targetId: streamStartData.creatorId
+                      });
+                      result.then(this.handleRequestResult.bind(this, res, targetWindow, targetOrigin, data)).catch(this.handleRequestError.bind(this, res, targetWindow, targetOrigin, data));
+                    } else {
+                      this.handleRequestResult(res, targetWindow, targetOrigin, data, result);
+                    }
+                  } catch (error) {
+                    this.handleRequestError(res, targetWindow, targetOrigin, data, error);
+                  }
+                });
+              }).catch(error => {
+                this.handleRequestError(res, targetWindow, targetOrigin, data, error);
+              });
+              return;
+            }
+
+            // Non-autoResolve: expose stream directly
+            req.body = fileStream;
+            req.stream = fileStream;
+          } else {
+            // Non-file stream
+            req.body = undefined;
+            req.stream = stream;
+          }
+          this.runMiddlewares(req, res, () => {
+            try {
+              var result = handlerFn(req, res);
+              if (isPromise(result)) {
+                this.dispatcher.sendMessage(targetWindow, targetOrigin, MessageType.ASYNC, streamStartData.requestId, {
+                  path: data.path,
+                  targetId: streamStartData.creatorId
+                });
+                result.then(this.handleRequestResult.bind(this, res, targetWindow, targetOrigin, data)).catch(this.handleRequestError.bind(this, res, targetWindow, targetOrigin, data));
+              } else {
+                this.handleRequestResult(res, targetWindow, targetOrigin, data, result);
+              }
+            } catch (error) {
+              this.handleRequestError(res, targetWindow, targetOrigin, data, error);
+            }
+          });
+        }
+      });
+      return;
+    }
+
+    // Create request object with path parameters
+    var req = new ServerRequestImpl(data, context, res, params);
+
+    // Execute middleware chain
+    this.runMiddlewares(req, res, () => {
+      try {
+        var result = handlerFn(req, res);
+        if (isPromise(result)) {
+          // Async task
+          // Window check is handled in MessageDispatcher
+          // Use request's creatorId as targetId to route back to the correct client
+          this.dispatcher.sendMessage(targetWindow, targetOrigin, MessageType.ASYNC, data.requestId, {
+            path: data.path,
+            targetId: data.creatorId
+          });
+          result.then(this.handleRequestResult.bind(this, res, targetWindow, targetOrigin, data)).catch(this.handleRequestError.bind(this, res, targetWindow, targetOrigin, data));
+        } else {
+          // Synchronous processing
+          this.handleRequestResult(res, targetWindow, targetOrigin, data, result);
+        }
+      } catch (error) {
+        this.handleRequestError(res, targetWindow, targetOrigin, data, error);
+      }
+    });
+  }
+  use(pathOrMiddleware, middleware) {
+    if (isFunction(pathOrMiddleware)) {
+      this.middlewares.push({
+        matcher: null,
+        middleware: pathOrMiddleware
+      });
+    } else if (middleware) {
+      this.middlewares.push({
+        matcher: pathOrMiddleware,
+        middleware
+      });
+    }
+  }
+  on(path, handler) {
+    var prefixedPath = this.dispatcher.prefixPath(path);
+    this.handlers.set(prefixedPath, handler);
+
+    // Return unregister function
+    return () => {
+      this.handlers.delete(prefixedPath);
+    };
+  }
+  runMiddlewares(req, res, finalHandler) {
+    var path = req.path;
+    var index = 0;
+    var next = () => {
+      if (res._sent) {
+        return;
+      }
+      while (index < this.middlewares.length) {
+        var item = this.middlewares[index++];
+        if (item.matcher === null || matchPath(path, item.matcher)) {
+          try {
+            var result = item.middleware(req, res, next);
+            if (result instanceof Promise) {
+              result.catch(err => {
+                if (!res._sent) {
+                  res.status(HttpStatus.INTERNAL_SERVER_ERROR).send({
+                    error: err.message || Messages.MIDDLEWARE_ERROR
+                  });
+                }
+              });
+            }
+            return;
+          } catch (err) {
+            if (!res._sent) {
+              res.status(HttpStatus.INTERNAL_SERVER_ERROR).send({
+                error: (err === null || err === void 0 ? void 0 : err.message) || Messages.MIDDLEWARE_ERROR
+              });
+            }
+            return;
+          }
+        }
+      }
+      if (index >= this.middlewares.length) {
+        finalHandler();
+      }
+    };
+    next();
+  }
+  off(path) {
+    if (Array.isArray(path)) {
+      // Batch unregister
+      path.forEach(p => {
+        this.handlers.delete(this.dispatcher.prefixPath(p));
+      });
+    } else {
+      // Single unregister
+      this.handlers.delete(this.dispatcher.prefixPath(path));
+    }
+  }
+  map(handlers) {
+    var unregisterFns = [];
+    Object.entries(handlers).forEach(([path, h]) => {
+      unregisterFns.push(this.on(path, h));
+    });
+    return () => {
+      unregisterFns.forEach(fn => fn());
+    };
+  }
+
+  /**
+   * Cleanup before destroy
+   */
+  cleanup() {
+    // Clean up handlers
+    this.handlers.clear();
+    this.middlewares.length = 0;
+    this.endpoint.streamDispatcher.clear();
+  }
+
+  /**
+   * Destroy server (close and release resources)
+   */
+  destroy() {
+    this.cleanup();
+    this.hub.destroy();
+  }
+}
+_defineProperty(RequestIframeServerImpl, "PENDING_ACKS", 'server:pendingAcks');
+_defineProperty(RequestIframeServerImpl, "PENDING_PONGS", 'server:pendingPongs');
+_defineProperty(RequestIframeServerImpl, "PENDING_STREAM_REQUESTS", 'server:pendingStreamRequests');
+_defineProperty(RequestIframeServerImpl, "LIMIT_IN_FLIGHT_BY_CLIENT", 'server:inFlightByClientKey');

package/esm/index.js

@@ -1,19 +1,26 @@
 // API
 export { requestIframeClient, clearRequestIframeClientCache } from './api/client';
 export { requestIframeServer, clearRequestIframeServerCache } from './api/server';
+export { requestIframeEndpoint } from './api/endpoint';
 // Implementation classes
-export { RequestIframeClientImpl } from './core/client';
-export { RequestIframeServerImpl } from './core/server';
-export { RequestIframeClientServer } from './core/client-server';
+export { RequestIframeClientImpl } from './impl/client';
+export { RequestIframeServerImpl } from './impl/server';
 // MessageChannel and MessageDispatcher
 export { MessageChannel, ChannelType, MessageDispatcher } from './message';
 // Cache utilities
-export { getOrCreateMessageChannel, releaseMessageChannel, clearMessageChannelCache } from './utils/cache';
-export { ServerRequestImpl } from './core/request';
-export { ServerResponseImpl } from './core/response';
+export { getOrCreateMessageChannel, releaseMessageChannel, clearMessageChannelCache } from './message/channel-cache';
+export { ServerRequestImpl } from './impl/request';
+export { ServerResponseImpl } from './impl/response';
 // Stream
 export { IframeWritableStream, IframeReadableStream, IframeFileWritableStream, IframeFileReadableStream, isIframeReadableStream, isIframeFileReadableStream, isIframeFileWritableStream, isIframeWritableStream } from './stream';
 // Types and utilities
+/**
+ * NOTE:
+ * Root entry re-exports are kept for convenience, but for better tree-shaking and clearer dependencies,
+ * prefer subpath imports:
+ * - `request-iframe/types`
+ * - `request-iframe/constants`
+ */
 export * from './types';
 export { detectContentType, blobToBase64, RequestIframeError } from './utils';
 export { InterceptorManager, RequestInterceptorManager, ResponseInterceptorManager } from './interceptors';

package/esm/message/ack.js

@@ -0,0 +1,27 @@
+import { generateRequestId } from '../utils/id';
+import { isAckMatch } from '../utils/ack';
+
+/**
+ * Build the expected ack payload for requireAck workflows.
+ *
+ * - If `ack` is provided, it wins.
+ * - If `requireAck` is true and ack not provided, generate `{ id }`.
+ * - Otherwise return undefined.
+ */
+export function buildExpectedAck(requireAck, ack) {
+  if (ack !== undefined) return ack;
+  if (!requireAck) return undefined;
+  return {
+    id: generateRequestId()
+  };
+}
+
+/**
+ * Check whether received ack matches expected.
+ *
+ * If expected is undefined, treat as "no matching required" and return true.
+ */
+export function isExpectedAckMatch(expectedAck, receivedAck) {
+  if (expectedAck === undefined) return true;
+  return isAckMatch(expectedAck, receivedAck);
+}