request-iframe 0.1.0 → 0.2.0

package/esm/constants/log.js

@@ -0,0 +1,11 @@
+/**
+ * Log level constants for request-iframe.
+ */
+
+export var LogLevel = {
+  TRACE: 'trace',
+  INFO: 'info',
+  WARN: 'warn',
+  ERROR: 'error',
+  SILENT: 'silent'
+};

package/esm/constants/messages.js

@@ -41,11 +41,14 @@ var defaultMessages = {
   MIDDLEWARE_ERROR: 'Middleware error',
   ERROR: 'Error',
   TOO_MANY_REQUESTS: 'Too many concurrent requests (limit: {0})',
+  HUB_REGISTER_HANDLERS_NOT_SET: 'RequestIframeEndpointHub: registerHandlers is not set',
   /** Client errors */
   IFRAME_NOT_READY: 'iframe.contentWindow is not available',
   TARGET_WINDOW_CLOSED: 'Target window is closed or no longer available',
   /** ClientServer warnings */
   CLIENT_SERVER_IGNORED_MESSAGE_WHEN_CLOSED: 'Ignored message because client server is closed/destroyed (type: {0}, requestId: {1})',
+  /** Server warnings */
+  SERVER_IGNORED_MESSAGE_WHEN_CLOSED: 'Ignored message because server is closed/destroyed (type: {0}, requestId: {1})',
   /** Stream related messages */
   STREAM_NOT_BOUND: 'Stream is not bound to a request context',
   STREAM_ALREADY_STARTED: 'Stream has already started',
@@ -57,6 +60,8 @@ var defaultMessages = {
   STREAM_ENDED: 'Stream has ended',
   STREAM_READ_ERROR: 'Failed to read stream data',
   STREAM_WRITE_ONLY_IN_PUSH_MODE: 'Stream write() is only available when mode is "push"',
+  STREAM_PENDING_QUEUE_OVERFLOW: 'Stream pending queue overflow (limit: {0})',
+  STREAM_PENDING_BYTES_OVERFLOW: 'Stream pending bytes overflow (limit: {0})',
   /** Debug messages - Client */
   DEBUG_CLIENT_REQUEST_START: '📤 [Client] Request Start',
   DEBUG_CLIENT_REQUEST_SUCCESS: '✅ [Client] Request Success',
@@ -73,7 +78,7 @@ var defaultMessages = {
   DEBUG_CLIENT_REQUEST_TIMEOUT: '⏱️ [Client] Request Timeout',
   DEBUG_CLIENT_SENDING_REQUEST: '📤 [Client] Sending Request',
   DEBUG_CLIENT_SENDING_PING: '📤 [Client] Sending Ping',
-  DEBUG_CLIENT_SENDING_RECEIVED_ACK: '📤 [Client] Sending Received ACK',
+  DEBUG_CLIENT_SENDING_RECEIVED_ACK: '📤 [Client] Sending ACK',
   /** Debug messages - Server */
   DEBUG_SERVER_RECEIVED_REQUEST: '📥 [Server] Received Request',
   DEBUG_SERVER_SETTING_STATUS_CODE: '📝 [Server] Setting Status Code',

package/esm/constants/warn-once.js

@@ -0,0 +1,15 @@
+import "core-js/modules/es.array.map.js";
+/**
+ * warnOnce keys (for deduplication).
+ *
+ * Keep these centralized to avoid scattered magic strings.
+ */
+
+export var WarnOnceKey = {
+  INBOX_MISSING_PENDING_WHEN_CLOSED: 'inbox:missingPendingWhenClosed',
+  SERVER_MISSING_PENDING_WHEN_CLOSED: 'server:missingPendingWhenClosed'
+};
+export function buildWarnOnceKey(prefix, ...parts) {
+  if (!parts.length) return prefix;
+  return `${prefix}:${parts.map(String).join(':')}`;
+}

package/esm/endpoint/facade.js

@@ -0,0 +1,390 @@
+import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
+import "core-js/modules/es.promise.js";
+import "core-js/modules/es.string.starts-with.js";
+import "core-js/modules/web.dom-collections.for-each.js";
+import { MessageType } from '../constants';
+import { matchOrigin } from '../utils/origin';
+import { RequestIframeEndpointHub } from './infra/hub';
+import { RequestIframeEndpointInbox } from './infra/inbox';
+import { RequestIframeStreamDispatcher } from './stream/dispatcher';
+import { RequestIframeEndpointHeartbeat } from './heartbeat/heartbeat';
+import { createPingResponder } from './heartbeat/ping';
+import { createReadableStreamFromStart } from './stream/factory';
+import { createStreamMessageHandler } from './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)
+ */
+export class RequestIframeEndpointFacade {
+  constructor(params) {
+    var _params$streamDispatc, _params$streamDispatc2;
+    _defineProperty(this, "openHooks", []);
+    this.hub = new RequestIframeEndpointHub(params.role, params.instanceId, {
+      secretKey: params.secretKey,
+      versionValidator: params.versionValidator,
+      autoAckMaxMetaLength: params.autoAckMaxMetaLength,
+      autoAckMaxIdLength: params.autoAckMaxIdLength
+    });
+    this.streamDispatcher = new 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 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 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 !== 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(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(MessageType.PONG, (data, context) => {
+        this.handlePong(data, context);
+      }, params.handlerOptions);
+    });
+  }
+
+  /**
+   * Register ACK handler for receipt confirmation waiters.
+   */
+  registerAckWaiterHandler(params) {
+    this.onOpen(() => {
+      this.hub.registerHandler(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(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 !== 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;
+    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 = createStreamMessageHandler({
+      dispatcher: this.streamDispatcher,
+      postMessage: message => {
+        this.hub.messageDispatcher.send(pending.targetWindow, message, pending.targetOrigin);
+      }
+    });
+    var created = 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 => matchOrigin(origin, matcher);
+    }
+    return undefined;
+  }
+}
+_defineProperty(RequestIframeEndpointFacade, "DEFAULT_PENDING_ACKS_BUCKET", 'endpoint:pendingAcks');

package/esm/endpoint/heartbeat/heartbeat.js

@@ -0,0 +1,60 @@
+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 } from '../../constants';
+/**
+ * RequestIframeEndpointHeartbeat
+ *
+ * Shared "ping -> wait pong" helper.
+ * - Works for both server and client endpoints
+ * - Uses core.pending for timeout management
+ */
+export class RequestIframeEndpointHeartbeat {
+  constructor(params) {
+    this.hub = params.hub;
+    this.pendingBucket = params.pendingBucket;
+    this.handledBy = params.handledBy;
+    this.isOriginAllowed = params.isOriginAllowed;
+    this.warnMissingPendingWhenClosed = params.warnMissingPendingWhenClosed;
+  }
+
+  /**
+   * Send PING and resolve true when PONG arrives, false on timeout.
+   */
+  ping(peer, timeoutMs, targetId) {
+    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(this.pendingBucket, requestId);
+        resolve(false);
+      }, timeoutMs);
+      this.hub.pending.set(this.pendingBucket, requestId, {
+        resolve,
+        timeoutId
+      });
+      peer.sendMessage(MessageType.PING, requestId, {
+        requireAck: true,
+        targetId
+      });
+    });
+  }
+
+  /**
+   * Handle incoming PONG for ping() waiter.
+   */
+  handlePong(data, context) {
+    if (this.isOriginAllowed && !this.isOriginAllowed(data, context)) return;
+    var pending = this.hub.pending.get(this.pendingBucket, data.requestId);
+    if (!pending) {
+      if (!this.hub.isOpen) {
+        var _this$warnMissingPend;
+        (_this$warnMissingPend = this.warnMissingPendingWhenClosed) === null || _this$warnMissingPend === void 0 || _this$warnMissingPend.call(this, data);
+      }
+      return;
+    }
+    context.markAcceptedBy(this.handledBy);
+    this.hub.pending.clearTimeout(pending.timeoutId);
+    this.hub.pending.delete(this.pendingBucket, data.requestId);
+    pending.resolve(true);
+  }
+}

package/esm/endpoint/heartbeat/ping.js

@@ -0,0 +1,20 @@
+import { MessageType } from '../../constants';
+/**
+ * Create a PING responder handler (reply PONG).
+ *
+ * This is a shared building block for both client/server endpoints.
+ */
+export function createPingResponder(params) {
+  var hub = params.hub,
+    handledBy = params.handledBy,
+    includeTargetId = params.includeTargetId;
+  return (data, context) => {
+    if (!context.source) return;
+    /** Mark accepted so MessageDispatcher can auto-send ACK when requireAck === true */
+    context.markAcceptedBy(handledBy);
+    /** Reply PONG */
+    hub.messageDispatcher.sendMessage(context.source, context.origin, MessageType.PONG, data.requestId, includeTargetId ? {
+      targetId: data.creatorId
+    } : undefined);
+  };
+}

package/esm/endpoint/index.js

@@ -0,0 +1,13 @@
+export { RequestIframeEndpointHub } from './infra/hub';
+export { RequestIframeEndpointInbox } from './infra/inbox';
+export { RequestIframeEndpointOutbox } from './infra/outbox';
+export { createPingResponder } from './heartbeat/ping';
+export { buildExpectedAck, isExpectedAckMatch } from '../message/ack';
+export { RequestIframeStreamDispatcher } from './stream/dispatcher';
+export { RequestIframeEndpointHeartbeat } from './heartbeat/heartbeat';
+export { parseStreamStart, createReadableStreamFromStart } from './stream/factory';
+export { RequestIframeEndpointFacade } from './facade';
+export { createStreamMessageHandler } from './stream/handler';
+export { buildStreamStartTimeoutErrorPayload } from './stream/errors';
+export { autoResolveIframeFileReadableStream, parseFilenameFromContentDisposition } from './stream/file-auto-resolve';
+export { createIframeFileWritableStreamFromContent } from './stream/file-writable';