runner.html

<script>
/***************************************************************************
*
*  Copyright 2020 Google Inc.
*
*  Licensed under the Apache License, Version 2.0 (the "License");
*  you may not use this file except in compliance with the License.
*  You may obtain a copy of the License at
*
*      https://www.apache.org/licenses/LICENSE-2.0
*
*  Unless required by applicable law or agreed to in writing, software
*  distributed under the License is distributed on an "AS IS" BASIS,
*  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
*  See the License for the specific language governing permissions and
*  limitations under the License.
*
*  Note that these code samples being shared are not official Google
*  products and are not formally supported.
*
***************************************************************************/

/**
 * Handles the orchestration of running parallel jobs in apps script on the
 * server side. Handles splitting jobs, waiting for jobs to complete, compiling
 * results and logs, etc.
 */
var Runner = function() {
  var runnerCallback = null;

  const RUNNER_STATUS_IDLE = 'IDLE';
  const RUNNER_STATUS_RUNNING = 'RUNNING';

  const JOB_STATUS_RUNNING = 'RUNNING';
  const JOB_STATUS_PENDING = 'PENDING';
  const JOB_STATUS_COMPLETE = 'COMPLETE';
  const JOB_STATUS_ERROR = 'ERROR';
  const MAX_RUNNING_JOBS = 28;

  var runnerStatus = RUNNER_STATUS_IDLE;
  var runnerJobs = {};
  var _command = '';
  var _progressCallback;

  /**
   * Executes pending jobs respecting limit set by MAX_RUNNING_JOBS
   */
  function runJobs() {
    var jobKeys = Object.getOwnPropertyNames(runnerJobs);
    var pendingJobs = [];

    var runningCount = 0;

    for(var i = 0; i < jobKeys.length; i++) {
      var job = runnerJobs[jobKeys[i]];

      if(job.status == JOB_STATUS_PENDING) {
        pendingJobs.push(job);
      } else if(job.status == JOB_STATUS_RUNNING) {
        runningCount++;
      }
    }

    while(pendingJobs.length > 0 && runningCount < MAX_RUNNING_JOBS) {
      var job = pendingJobs.shift();

      job.status = JOB_STATUS_RUNNING;

      if(job) {
        google.script.run.withSuccessHandler(successHandler).withFailureHandler(errorHandler)[_command](JSON.stringify(job));
        runningCount++;
      } else {
        console.log(job);
      }
    }
  }

  /**
   * Checks the status of the jobs, if all jobs are finished invokes callback
   * and passes the jobs as a parameter
   */
  function processStatus() {
    var jobKeys = Object.getOwnPropertyNames(runnerJobs);
    var jobs = [];
    var allJobsDone = true;

    runJobs();

    for(var i = 0; i < jobKeys.length; i++) {
      var job = runnerJobs[jobKeys[i]];

      jobs.push(job);

      if(job.status == JOB_STATUS_RUNNING) {
        return;
      }
    }

    if(runnerCallback) {
      runnerCallback(jobs);
    }
  }

  /**
   * Default success handler for server side interactions
   *
   * params:
   *  job: the job that was executed
   */
  function successHandler(input) {
    var job = JSON.parse(input);
    job.status = JOB_STATUS_COMPLETE;
    runnerJobs[job.id] = job;

    if(_progressCallback) {
      _progressCallback(job);
    }

    processStatus();
  }

  /**
   * Default error handler for server side interactions
   *
   * params:
   *  error: the error returned by the backend
   */
  function errorHandler(input) {
    var job = null;

    // This if chain was added because all of a sudden the error returned
    // by the backend when exceptions are thrown changed from a simple string
    // to an object that contains the error payload sent from the backend
    // in a "message" field. We'll keep this logic here for now to ensure
    // backward compatibility, but it can be removed in future releases
    if(typeof(input) == 'object') {
      console.log("error type is object");
      job = JSON.parse(input.message);
    } else if(typeof(input) == 'string'){
      console.log("error type is string");
      job = JSON.parse(input);
    } else {
      throw "Could not parse job error returned from backend"
    }

    job.status = JOB_STATUS_ERROR;
    runnerJobs[job.id] = job;

    if(_progressCallback) {
      _progressCallback(job);
    }

    processStatus();
  }

  /**
   * Executes commands on the server side, each instance in the jobs array will
   * be processed as one call to the function identified.
   *
   * The caller can control which jobs should run or be skipped by setting the
   * job.run flag to false. If the flag isn't present (undefined) or true the
   * job will run. This helps to handle environments with promises where only
   * certain jobs should run at a time, but the context of previous jobs should
   * be maintained.
   *
   * params:
   *  command: string with the name of the function to be called on the server
   *  side
   *
   *  jobs: list of jobs to be passed to each instance of the server side
   *  execution, each job in the list will spawn one server side call, and it
   *  will be passed as parameter
   *
   *  progressCallback: Optional. Callback to be invoked for each job that finishes.
   */
  this.run = function(command, jobs, progressCallback) {
    return new Promise(function(resolve, reject) {
      if(runnerStatus == RUNNER_STATUS_RUNNING) {
        reject('Runner is already processing a job!');
      } else {
        runnerCallback = resolve;
        _progressCallback = progressCallback;
        _command = command;
        runnerJobs = {};

        for(var i = 0; i < jobs.length; i++) {
          var job = jobs[i];
          job.id = i;

          runnerJobs[job.id] = job;

          if(job.run === false) {
            job.status = JOB_STATUS_COMPLETE;
          } else {
            job.status = JOB_STATUS_PENDING;
          }
        }

        processStatus();
      }
    });
  }
}
</script>