[Summary view] [Print] [Text view]

   1  /**
   2   * Heartbeat API
   3   *
   4   * Note: this API is "experimental" meaning it will likely change a lot
   5   * in the next few releases based on feedback from 3.6.0. If you intend
   6   * to use it, please follow the development closely.
   7   *
   8   * Heartbeat is a simple server polling API that sends XHR requests to
   9   * the server every 15 - 60 seconds and triggers events (or callbacks) upon
  10   * receiving data. Currently these 'ticks' handle transports for post locking,
  11   * login-expiration warnings, and related tasks while a user is logged in.
  12   *
  13   * Available PHP filters (in ajax-actions.php):
  14   * - heartbeat_received
  15   * - heartbeat_send
  16   * - heartbeat_tick
  17   * - heartbeat_nopriv_received
  18   * - heartbeat_nopriv_send
  19   * - heartbeat_nopriv_tick
  20   * @see wp_ajax_nopriv_heartbeat(), wp_ajax_heartbeat()
  21   *
  22   * Custom jQuery events:
  23   * - heartbeat-send
  24   * - heartbeat-tick
  25   * - heartbeat-error
  26   * - heartbeat-connection-lost
  27   * - heartbeat-connection-restored
  28   * - heartbeat-nonces-expired
  29   *
  30   * @since 3.6.0
  31   */
  32  
  33  ( function( $, window, undefined ) {
  34      var Heartbeat = function() {
  35          var $document = $(document),
  36              settings = {
  37                  // Suspend/resume
  38                  suspend: false,
  39  
  40                  // Whether suspending is enabled
  41                  suspendEnabled: true,
  42  
  43                  // Current screen id, defaults to the JS global 'pagenow' when present (in the admin) or 'front'
  44                  screenId: '',
  45  
  46                  // XHR request URL, defaults to the JS global 'ajaxurl' when present
  47                  url: '',
  48  
  49                  // Timestamp, start of the last connection request
  50                  lastTick: 0,
  51  
  52                  // Container for the enqueued items
  53                  queue: {},
  54  
  55                  // Connect interval (in seconds)
  56                  mainInterval: 60,
  57  
  58                  // Used when the interval is set to 5 sec. temporarily
  59                  tempInterval: 0,
  60  
  61                  // Used when the interval is reset
  62                  originalInterval: 0,
  63  
  64                  // Used together with tempInterval
  65                  countdown: 0,
  66  
  67                  // Whether a connection is currently in progress
  68                  connecting: false,
  69  
  70                  // Whether a connection error occured
  71                  connectionError: false,
  72  
  73                  // Used to track non-critical errors
  74                  errorcount: 0,
  75  
  76                  // Whether at least one connection has completed successfully
  77                  hasConnected: false,
  78  
  79                  // Whether the current browser window is in focus and the user is active
  80                  hasFocus: true,
  81  
  82                  // Timestamp, last time the user was active. Checked every 30 sec.
  83                  userActivity: 0,
  84  
  85                  // Flags whether events tracking user activity were set
  86                  userActivityEvents: false,
  87  
  88                  // References to various timeouts
  89                  beatTimer: 0,
  90                  winBlurTimer: 0,
  91                  frameBlurTimer: 0
  92              };
  93  
  94          /**
  95           * Set local vars and events, then start
  96           *
  97           * @access private
  98           *
  99           * @return void
 100           */
 101  		function initialize() {
 102              if ( typeof window.pagenow === 'string' ) {
 103                  settings.screenId = window.pagenow;
 104              }
 105  
 106              if ( typeof window.ajaxurl === 'string' ) {
 107                  settings.url = window.ajaxurl;
 108              }
 109  
 110              // Pull in options passed from PHP
 111              if ( typeof window.heartbeatSettings === 'object' ) {
 112                  var options = window.heartbeatSettings;
 113  
 114                  // The XHR URL can be passed as option when window.ajaxurl is not set
 115                  if ( ! settings.url && options.ajaxurl ) {
 116                      settings.url = options.ajaxurl;
 117                  }
 118  
 119                  // The interval can be from 15 to 60 sec. and can be set temporarily to 5 sec.
 120                  if ( options.interval ) {
 121                      settings.mainInterval = options.interval;
 122  
 123                      if ( settings.mainInterval < 15 ) {
 124                          settings.mainInterval = 15;
 125                      } else if ( settings.mainInterval > 60 ) {
 126                          settings.mainInterval = 60;
 127                      }
 128                  }
 129  
 130                  // 'screenId' can be added from settings on the front-end where the JS global 'pagenow' is not set
 131                  if ( ! settings.screenId ) {
 132                      settings.screenId = options.screenId || 'front';
 133                  }
 134  
 135                  if ( options.suspension === 'disable' ) {
 136                      settings.suspendEnabled = false;
 137                  }
 138              }
 139  
 140              // Convert to milliseconds
 141              settings.mainInterval = settings.mainInterval * 1000;
 142              settings.originalInterval = settings.mainInterval;
 143  
 144              // Set focus/blur events on the window
 145              $(window).on( 'blur.wp-heartbeat-focus', function() {
 146                  setFrameFocusEvents();
 147                  // We don't know why the 'blur' was fired. Either the user clicked in an iframe or outside the browser.
 148                  // Running blurred() after some timeout lets us cancel it if the user clicked in an iframe.
 149                  settings.winBlurTimer = window.setTimeout( function(){ blurred(); }, 500 );
 150              }).on( 'focus.wp-heartbeat-focus', function() {
 151                  removeFrameFocusEvents();
 152                  focused();
 153              }).on( 'unload.wp-heartbeat', function() {
 154                  // Don't connect any more
 155                  settings.suspend = true;
 156  
 157                  // Abort the last request if not completed
 158                  if ( settings.xhr && settings.xhr.readyState !== 4 ) {
 159                      settings.xhr.abort();
 160                  }
 161              });
 162  
 163              // Check for user activity every 30 seconds.
 164              window.setInterval( function(){ checkUserActivity(); }, 30000 );
 165  
 166              // Start one tick after DOM ready
 167              $document.ready( function() {
 168                  settings.lastTick = time();
 169                  scheduleNextTick();
 170              });
 171          }
 172  
 173          /**
 174           * Return the current time according to the browser
 175           *
 176           * @access private
 177           *
 178           * @return int
 179           */
 180  		function time() {
 181              return (new Date()).getTime();
 182          }
 183  
 184          /**
 185           * Check if the iframe is from the same origin
 186           *
 187           * @access private
 188           *
 189           * @return bool
 190           */
 191  		function isLocalFrame( frame ) {
 192              var origin, src = frame.src;
 193  
 194              // Need to compare strings as WebKit doesn't throw JS errors when iframes have different origin.
 195              // It throws uncatchable exceptions.
 196              if ( src && /^https?:\/\//.test( src ) ) {
 197                  origin = window.location.origin ? window.location.origin : window.location.protocol + '//' + window.location.host;
 198  
 199                  if ( src.indexOf( origin ) !== 0 ) {
 200                      return false;
 201                  }
 202              }
 203  
 204              try {
 205                  if ( frame.contentWindow.document ) {
 206                      return true;
 207                  }
 208              } catch(e) {}
 209  
 210              return false;
 211          }
 212  
 213          /**
 214           * Set error state and fire an event on XHR errors or timeout
 215           *
 216           * @access private
 217           *
 218           * @param string error The error type passed from the XHR
 219           * @param int status The HTTP status code passed from jqXHR (200, 404, 500, etc.)
 220           * @return void
 221           */
 222  		function setErrorState( error, status ) {
 223              var trigger;
 224  
 225              if ( error ) {
 226                  switch ( error ) {
 227                      case 'abort':
 228                          // do nothing
 229                          break;
 230                      case 'timeout':
 231                          // no response for 30 sec.
 232                          trigger = true;
 233                          break;
 234                      case 'error':
 235                          if ( 503 === status && settings.hasConnected ) {
 236                              trigger = true;
 237                              break;
 238                          }
 239                          /* falls through */
 240                      case 'parsererror':
 241                      case 'empty':
 242                      case 'unknown':
 243                          settings.errorcount++;
 244  
 245                          if ( settings.errorcount > 2 && settings.hasConnected ) {
 246                              trigger = true;
 247                          }
 248  
 249                          break;
 250                  }
 251  
 252                  if ( trigger && ! hasConnectionError() ) {
 253                      settings.connectionError = true;
 254                      $document.trigger( 'heartbeat-connection-lost', [error, status] );
 255                  }
 256              }
 257          }
 258  
 259          /**
 260           * Clear the error state and fire an event
 261           *
 262           * @access private
 263           *
 264           * @return void
 265           */
 266  		function clearErrorState() {
 267              // Has connected successfully
 268              settings.hasConnected = true;
 269  
 270              if ( hasConnectionError() ) {
 271                  settings.errorcount = 0;
 272                  settings.connectionError = false;
 273                  $document.trigger( 'heartbeat-connection-restored' );
 274              }
 275          }
 276  
 277          /**
 278           * Gather the data and connect to the server
 279           *
 280           * @access private
 281           *
 282           * @return void
 283           */
 284  		function connect() {
 285              var ajaxData, heartbeatData;
 286  
 287              // If the connection to the server is slower than the interval,
 288              // heartbeat connects as soon as the previous connection's response is received.
 289              if ( settings.connecting || settings.suspend ) {
 290                  return;
 291              }
 292  
 293              settings.lastTick = time();
 294  
 295              heartbeatData = $.extend( {}, settings.queue );
 296              // Clear the data queue, anything added after this point will be send on the next tick
 297              settings.queue = {};
 298  
 299              $document.trigger( 'heartbeat-send', [ heartbeatData ] );
 300  
 301              ajaxData = {
 302                  data: heartbeatData,
 303                  interval: settings.tempInterval ? settings.tempInterval / 1000 : settings.mainInterval / 1000,
 304                  _nonce: typeof window.heartbeatSettings === 'object' ? window.heartbeatSettings.nonce : '',
 305                  action: 'heartbeat',
 306                  screen_id: settings.screenId,
 307                  has_focus: settings.hasFocus
 308              };
 309  
 310              settings.connecting = true;
 311              settings.xhr = $.ajax({
 312                  url: settings.url,
 313                  type: 'post',
 314                  timeout: 30000, // throw an error if not completed after 30 sec.
 315                  data: ajaxData,
 316                  dataType: 'json'
 317              }).always( function() {
 318                  settings.connecting = false;
 319                  scheduleNextTick();
 320              }).done( function( response, textStatus, jqXHR ) {
 321                  var newInterval;
 322  
 323                  if ( ! response ) {
 324                      setErrorState( 'empty' );
 325                      return;
 326                  }
 327  
 328                  clearErrorState();
 329  
 330                  if ( response.nonces_expired ) {
 331                      $document.trigger( 'heartbeat-nonces-expired' );
 332                      return;
 333                  }
 334  
 335                  // Change the interval from PHP
 336                  if ( response.heartbeat_interval ) {
 337                      newInterval = response.heartbeat_interval;
 338                      delete response.heartbeat_interval;
 339                  }
 340  
 341                  $document.trigger( 'heartbeat-tick', [response, textStatus, jqXHR] );
 342  
 343                  // Do this last, can trigger the next XHR if connection time > 5 sec. and newInterval == 'fast'
 344                  if ( newInterval ) {
 345                      interval( newInterval );
 346                  }
 347              }).fail( function( jqXHR, textStatus, error ) {
 348                  setErrorState( textStatus || 'unknown', jqXHR.status );
 349                  $document.trigger( 'heartbeat-error', [jqXHR, textStatus, error] );
 350              });
 351          }
 352  
 353          /**
 354           * Schedule the next connection
 355           *
 356           * Fires immediately if the connection time is longer than the interval.
 357           *
 358           * @access private
 359           *
 360           * @return void
 361           */
 362  		function scheduleNextTick() {
 363              var delta = time() - settings.lastTick,
 364                  interval = settings.mainInterval;
 365  
 366              if ( settings.suspend ) {
 367                  return;
 368              }
 369  
 370              if ( ! settings.hasFocus ) {
 371                  interval = 120000; // 120 sec. Post locks expire after 150 sec.
 372              } else if ( settings.countdown > 0 && settings.tempInterval ) {
 373                  interval = settings.tempInterval;
 374                  settings.countdown--;
 375  
 376                  if ( settings.countdown < 1 ) {
 377                      settings.tempInterval = 0;
 378                  }
 379              }
 380  
 381              window.clearTimeout( settings.beatTimer );
 382  
 383              if ( delta < interval ) {
 384                  settings.beatTimer = window.setTimeout(
 385                      function() {
 386                              connect();
 387                      },
 388                      interval - delta
 389                  );
 390              } else {
 391                  connect();
 392              }
 393          }
 394  
 395          /**
 396           * Set the internal state when the browser window looses focus
 397           *
 398           * @access private
 399           *
 400           * @return void
 401           */
 402  		function blurred() {
 403              clearFocusTimers();
 404              settings.hasFocus = false;
 405          }
 406  
 407          /**
 408           * Set the internal state when the browser window is focused
 409           *
 410           * @access private
 411           *
 412           * @return void
 413           */
 414  		function focused() {
 415              clearFocusTimers();
 416              settings.userActivity = time();
 417  
 418              // Resume if suspended
 419              settings.suspend = false;
 420  
 421              if ( ! settings.hasFocus ) {
 422                  settings.hasFocus = true;
 423                  scheduleNextTick();
 424              }
 425          }
 426  
 427          /**
 428           * Add focus/blur events to all local iframes
 429           *
 430           * Used to detect when focus is moved from the main window to an iframe
 431           *
 432           * @access private
 433           *
 434           * @return void
 435           */
 436  		function setFrameFocusEvents() {
 437              $('iframe').each( function( i, frame ) {
 438                  if ( ! isLocalFrame( frame ) ) {
 439                      return;
 440                  }
 441  
 442                  if ( $.data( frame, 'wp-heartbeat-focus' ) ) {
 443                      return;
 444                  }
 445  
 446                  $.data( frame, 'wp-heartbeat-focus', 1 );
 447  
 448                  $( frame.contentWindow ).on( 'focus.wp-heartbeat-focus', function() {
 449                      focused();
 450                  }).on('blur.wp-heartbeat-focus', function() {
 451                      setFrameFocusEvents();
 452                      // We don't know why 'blur' was fired. Either the user clicked in the main window or outside the browser.
 453                      // Running blurred() after some timeout lets us cancel it if the user clicked in the main window.
 454                      settings.frameBlurTimer = window.setTimeout( function(){ blurred(); }, 500 );
 455                  });
 456              });
 457          }
 458  
 459          /**
 460           * Remove the focus/blur events to all local iframes
 461           *
 462           * @access private
 463           *
 464           * @return void
 465           */
 466  		function removeFrameFocusEvents() {
 467              $('iframe').each( function( i, frame ) {
 468                  if ( ! isLocalFrame( frame ) ) {
 469                      return;
 470                  }
 471  
 472                  $.removeData( frame, 'wp-heartbeat-focus' );
 473                  $( frame.contentWindow ).off( '.wp-heartbeat-focus' );
 474              });
 475          }
 476  
 477          /**
 478           * Clear the reset timers for focus/blur events on the window and iframes
 479           *
 480           * @access private
 481           *
 482           * @return void
 483           */
 484  		function clearFocusTimers() {
 485              window.clearTimeout( settings.winBlurTimer );
 486              window.clearTimeout( settings.frameBlurTimer );
 487          }
 488  
 489          /**
 490           * Runs when the user becomes active after a period of inactivity
 491           *
 492           * @access private
 493           *
 494           * @return void
 495           */
 496  		function userIsActive() {
 497              settings.userActivityEvents = false;
 498              $document.off( '.wp-heartbeat-active' );
 499  
 500              $('iframe').each( function( i, frame ) {
 501                  if ( ! isLocalFrame( frame ) ) {
 502                      return;
 503                  }
 504  
 505                  $( frame.contentWindow ).off( '.wp-heartbeat-active' );
 506              });
 507  
 508              focused();
 509          }
 510  
 511          /**
 512           * Check for user activity
 513           *
 514           * Runs every 30 sec.
 515           * Sets 'hasFocus = true' if user is active and the window is in the background.
 516           * Set 'hasFocus = false' if the user has been inactive (no mouse or keyboard activity)
 517           * for 5 min. even when the window has focus.
 518           *
 519           * @access private
 520           *
 521           * @return void
 522           */
 523  		function checkUserActivity() {
 524              var lastActive = settings.userActivity ? time() - settings.userActivity : 0;
 525  
 526              if ( lastActive > 300000 && settings.hasFocus ) {
 527                  // Throttle down when no mouse or keyboard activity for 5 min
 528                  blurred();
 529              }
 530  
 531              if ( settings.suspendEnabled && lastActive > 1200000 ) {
 532                  // Suspend after 20 min. of inactivity
 533                  settings.suspend = true;
 534              }
 535  
 536              if ( ! settings.userActivityEvents ) {
 537                  $document.on( 'mouseover.wp-heartbeat-active keyup.wp-heartbeat-active', function(){ userIsActive(); } );
 538  
 539                  $('iframe').each( function( i, frame ) {
 540                      if ( ! isLocalFrame( frame ) ) {
 541                          return;
 542                      }
 543  
 544                      $( frame.contentWindow ).on( 'mouseover.wp-heartbeat-active keyup.wp-heartbeat-active', function(){ userIsActive(); } );
 545                  });
 546  
 547                  settings.userActivityEvents = true;
 548              }
 549          }
 550  
 551          // Public methods
 552  
 553          /**
 554           * Whether the window (or any local iframe in it) has focus, or the user is active
 555           *
 556           * @return bool
 557           */
 558  		function hasFocus() {
 559              return settings.hasFocus;
 560          }
 561  
 562          /**
 563           * Whether there is a connection error
 564           *
 565           * @return bool
 566           */
 567  		function hasConnectionError() {
 568              return settings.connectionError;
 569          }
 570  
 571          /**
 572           * Connect asap regardless of 'hasFocus'
 573           *
 574           * Will not open two concurrent connections. If a connection is in progress,
 575           * will connect again immediately after the current connection completes.
 576           *
 577           * @return void
 578           */
 579  		function connectNow() {
 580              settings.lastTick = 0;
 581              scheduleNextTick();
 582          }
 583  
 584          /**
 585           * Disable suspending
 586           *
 587           * Should be used only when Heartbeat is performing critical tasks like autosave, post-locking, etc.
 588           * Using this on many screens may overload the user's hosting account if several
 589           * browser windows/tabs are left open for a long time.
 590           *
 591           * @return void
 592           */
 593  		function disableSuspend() {
 594              settings.suspendEnabled = false;
 595          }
 596  
 597          /**
 598           * Get/Set the interval
 599           *
 600           * When setting to 'fast' or 5, by default interval is 5 sec. for the next 30 ticks (for 2 min and 30 sec).
 601           * In this case the number of 'ticks' can be passed as second argument.
 602           * If the window doesn't have focus, the interval slows down to 2 min.
 603           *
 604           * @param mixed speed Interval: 'fast' or 5, 15, 30, 60
 605           * @param string ticks Used with speed = 'fast' or 5, how many ticks before the interval reverts back
 606           * @return int Current interval in seconds
 607           */
 608  		function interval( speed, ticks ) {
 609              var newInterval,
 610                  oldInterval = settings.tempInterval ? settings.tempInterval : settings.mainInterval;
 611  
 612              if ( speed ) {
 613                  switch ( speed ) {
 614                      case 'fast':
 615                      case 5:
 616                          newInterval = 5000;
 617                          break;
 618                      case 15:
 619                          newInterval = 15000;
 620                          break;
 621                      case 30:
 622                          newInterval = 30000;
 623                          break;
 624                      case 60:
 625                          newInterval = 60000;
 626                          break;
 627                      case 'long-polling':
 628                          // Allow long polling, (experimental)
 629                          settings.mainInterval = 0;
 630                          return 0;
 631                      default:
 632                          newInterval = settings.originalInterval;
 633                  }
 634  
 635                  if ( 5000 === newInterval ) {
 636                      ticks = parseInt( ticks, 10 ) || 30;
 637                      ticks = ticks < 1 || ticks > 30 ? 30 : ticks;
 638  
 639                      settings.countdown = ticks;
 640                      settings.tempInterval = newInterval;
 641                  } else {
 642                      settings.countdown = 0;
 643                      settings.tempInterval = 0;
 644                      settings.mainInterval = newInterval;
 645                  }
 646  
 647                  // Change the next connection time if new interval has been set.
 648                  // Will connect immediately if the time since the last connection
 649                  // is greater than the new interval.
 650                  if ( newInterval !== oldInterval ) {
 651                      scheduleNextTick();
 652                  }
 653              }
 654  
 655              return settings.tempInterval ? settings.tempInterval / 1000 : settings.mainInterval / 1000;
 656          }
 657  
 658          /**
 659           * Enqueue data to send with the next XHR
 660           *
 661           * As the data is send asynchronously, this function doesn't return the XHR response.
 662           * To see the response, use the custom jQuery event 'heartbeat-tick' on the document, example:
 663           *        $(document).on( 'heartbeat-tick.myname', function( event, data, textStatus, jqXHR ) {
 664           *            // code
 665           *        });
 666           * If the same 'handle' is used more than once, the data is not overwritten when the third argument is 'true'.
 667           * Use wp.heartbeat.isQueued('handle') to see if any data is already queued for that handle.
 668           *
 669           * $param string handle Unique handle for the data. The handle is used in PHP to receive the data.
 670           * $param mixed data The data to send.
 671           * $param bool noOverwrite Whether to overwrite existing data in the queue.
 672           * $return bool Whether the data was queued or not.
 673           */
 674  		function enqueue( handle, data, noOverwrite ) {
 675              if ( handle ) {
 676                  if ( noOverwrite && this.isQueued( handle ) ) {
 677                      return false;
 678                  }
 679  
 680                  settings.queue[handle] = data;
 681                  return true;
 682              }
 683              return false;
 684          }
 685  
 686          /**
 687           * Check if data with a particular handle is queued
 688           *
 689           * $param string handle The handle for the data
 690           * $return bool Whether some data is queued with this handle
 691           */
 692  		function isQueued( handle ) {
 693              if ( handle ) {
 694                  return settings.queue.hasOwnProperty( handle );
 695              }
 696          }
 697  
 698          /**
 699           * Remove data with a particular handle from the queue
 700           *
 701           * $param string handle The handle for the data
 702           * $return void
 703           */
 704  		function dequeue( handle ) {
 705              if ( handle ) {
 706                  delete settings.queue[handle];
 707              }
 708          }
 709  
 710          /**
 711           * Get data that was enqueued with a particular handle
 712           *
 713           * $param string handle The handle for the data
 714           * $return mixed The data or undefined
 715           */
 716  		function getQueuedItem( handle ) {
 717              if ( handle ) {
 718                  return this.isQueued( handle ) ? settings.queue[handle] : undefined;
 719              }
 720          }
 721  
 722          initialize();
 723  
 724          // Expose public methods
 725          return {
 726              hasFocus: hasFocus,
 727              connectNow: connectNow,
 728              disableSuspend: disableSuspend,
 729              interval: interval,
 730              hasConnectionError: hasConnectionError,
 731              enqueue: enqueue,
 732              dequeue: dequeue,
 733              isQueued: isQueued,
 734              getQueuedItem: getQueuedItem
 735          };
 736      };
 737  
 738      // Ensure the global `wp` object exists.
 739      window.wp = window.wp || {};
 740      window.wp.heartbeat = new Heartbeat();
 741  
 742  }( jQuery, window ));