@api-client/core 0.3.5 → 0.3.8

package/src/runtime/node/ProjectRunner.ts

@@ -1,71 +1,94 @@
-import { EventEmitter } from 'events';
-import { Environment } from '../../models/Environment.js';
+import { SerializableError } from '../../models/SerializableError.js';
+import { HttpProject } from '../../models/HttpProject.js';
+import { ProjectFolder } from '../../models/ProjectFolder.js';
+import { Environment, IEnvironment } from '../../models/Environment.js';
+import { DummyLogger } from '../../lib/logging/DummyLogger.js';
 import { Logger } from '../../lib/logging/Logger.js';
-import { IRequestLog, RequestLog } from '../../models/RequestLog.js';
-import { Property } from '../../models/Property.js';
-import { ProjectFolder, Kind as ProjectFolderKind } from '../../models/ProjectFolder.js';
-import { ProjectRequest } from '../../models/ProjectRequest.js';
+import { IRequestLog } from '../../models/RequestLog.js';
 import { IHttpRequest } from '../../models/HttpRequest.js';
-import { HttpProject, IProjectRequestIterator } from '../../models/HttpProject.js';
-import { SentRequest } from '../..//models/SentRequest.js';
-import { ErrorResponse } from '../../models/ErrorResponse.js';
-import { VariablesStore } from './VariablesStore.js';
-import { VariablesProcessor } from '../variables/VariablesProcessor.js';
-import { RequestFactory } from './RequestFactory.js';
-import { EventTypes } from '../../events/EventTypes.js';
+import { ProjectRequestRunner } from './ProjectRequestRunner.js';
+import { IProjectExecutionIteration, IProjectExecutionLog } from '../reporters/Reporter.js';
+import { pathExists, readJson } from '../../lib/fs/Fs.js';
+import { BaseRunner } from './BaseRunner.js';
 
-export interface ProjectRunnerOptions {
+type ProjectParent = HttpProject | ProjectFolder;
+
+export interface IProjectRunnerOptions {
   /**
-   * When provided it overrides any project / folder defined environment.
+   * The environment to use.
+   * This can be a name or the key of the environment located under the parent or root.
+   * It can also be a path to the environment definition. If the file exists it is used. Otherwise it tried to 
+   * find the environment in the project.
    */
-  environment?: Environment;
+  environment?: string;
   /**
-   * Additional variables to pass to the selected environment.
-   * This can be use to pass system variables, when needed.
-   * 
-   * To use system variables tou can use `init.variables = process.env`;
+   * The parent folder to execute.
    */
-  variables?: Record<string, string>;
+  parent?: string;
   /**
-   * Overrides the default logger (console).
+   * The names or the keys of requests to execute.
+   * This can be used to limit the number of requests.
    */
-  logger?: Logger;
+  request?: string[];
   /**
-   * The event target to use.
-   * By default it creates its own target.
+   * The number of times the execution should be repeated.
+   * Default to 1.
    */
-  eventTarget?: EventTarget;
-}
-
-export interface ProjectRunnerRunOptions extends IProjectRequestIterator {
-}
-
-export interface RunResult {
+  iterations?: number;
   /**
-   * The key of the request from the HttpProject that was executed.
+   * The number of milliseconds to wait between each iteration.
+   * Default to the next frame (vary from 1 to tens of milliseconds).
    */
-  key: string;
+  iterationDelay?: number;
   /**
-   * The key of parent folder of the executed request.
+   * When set it performs parallel execution for each iteration.
+   * The number of executions at the same time depends on the number of processor cores
+   * available on the current machine. The maximum of the parallel execution
+   * is the number of available cores. When the `iterations` number is higher
+   * then the "rest" is added to the iterations per each core.
    */
-  parent?: string;
+  parallel?: boolean;
   /**
-   * Set when a fatal error occurred so the request couldn't be executed.
-   * This is not the same as error reported during a request. The log's response can still be IResponseError.
+   * When set it includes requests in the current folder and sub-folder according to the order
+   * defined in the folder.
    */
-  error?: boolean;
+  recursive?: boolean;
   /**
-   * The error message. Always set when the `error` is `true`.
+   * The opposite of the `requests`. The list of names or keys of requests or folders to ignore.
+   * Note, ignore is tested before the `requests`.
    */
-  errorMessage?: string;
+  ignore?: string[];
+  /**
+   * The logger to use with the request factory.
+   * When not set it uses the dummy logger (no output).
+   */
+  logger?: Logger;
   /**
-   * The request log.
-   * Always set when the `error` is `false`.
+   * When true it copies all system variables to the execution environment.
+   * When an array of strings, only takes system variables that are listed in the array.
+   * When a map, it uses this map as a list of variables.
+   * When not set it does not read system variables.
    */
-  log?: IRequestLog;
+  variables?: boolean | string[] | Record<string, string>;
 }
 
 export interface ProjectRunner {
+  /**
+   * Event dispatched when an iteration is about to start.
+   */
+  on(event: 'before-iteration', listener: (index: number, iterated: boolean) => void): this;
+  /**
+   * Event dispatched when an iteration finished.
+   */
+  on(event: 'after-iteration', listener: (index: number, iterated: boolean) => void): this;
+  /**
+   * Event dispatched before the iteration is going to sleep for the set period of time.
+   */
+  on(event: 'before-sleep', listener: () => void): this;
+  /**
+   * Event dispatched after the iteration is woke up.
+   */
+  on(event: 'after-sleep', listener: () => void): this;
   /**
    * The request object is prepared and about to be sent to the HTTP engine
    */
@@ -78,6 +101,22 @@ export interface ProjectRunner {
    * There was a general error during the request
    */
   on(event: 'error', listener: (key: string, log: IRequestLog, message: string) => void): this;
+  /**
+   * Event dispatched when an iteration is about to start.
+   */
+  once(event: 'before-iteration', listener: (index: number, iterated: boolean) => void): this;
+  /**
+   * Event dispatched when an iteration finished.
+   */
+  once(event: 'after-iteration', listener: (index: number, iterated: boolean) => void): this;
+  /**
+   * Event dispatched before the iteration is going to sleep for the set period of time.
+   */
+  once(event: 'before-sleep', listener: () => void): this;
+  /**
+   * Event dispatched after the iteration is woke up.
+   */
+  once(event: 'after-sleep', listener: () => void): this;
   /**
    * The request object is prepared and about to be sent to the HTTP engine
    */
@@ -93,189 +132,243 @@ export interface ProjectRunner {
 }
 
 /**
- * Runs requests in a project.
- * Developers can run the entire project with the `recursive` flag set. They can also 
- * set the starting point with the `parent` options.
+ * A class to be extended to run an entire API Project for the given configuration options.
  * 
- * Requests are executed in order defined in the folder.
+ * The main purpose of this class (and its children) is to iterate over requests
+ * in the project and execute them one-by-one.
+ * 
+ * Implementations allow to execute the requests in a serial model or in parallel mode, where
+ * a separate workers are created to run the same HTTP requests in each worker.
+ * 
+ * This class generates a run report which other programs can use to build all kinds of UIs
+ * around the data collected during the run.
  */
-export class ProjectRunner extends EventEmitter {
-  eventTarget: EventTarget;
-  logger?: Logger;
-  project: HttpProject;
-
-  protected masterEnvironment?: Environment;
-  protected extraVariables?: Record<string, string>;
-
+export abstract class ProjectRunner extends BaseRunner {
+  /**
+   * The HTTP project to run requests from.
+   */
+  project?: HttpProject;
+  /**
+   * The execution options for the project.
+   */
+  options?: IProjectRunnerOptions;
+  /**
+   * The root object (project or a folder) where the program starts iterating over the requests.
+   */
+  root?: ProjectParent;
+  /**
+   * The selected environment to apply to the requests.
+   */
+  environment?: Environment;
+  /**
+   * The events target instance for events dispatched by the request factory.
+   */
+  target = new EventTarget();
+  /**
+   * This is used with `--iterations`. The index of the current iteration.
+   */
+  protected index = 0;
+  /**
+   * The currently executed iteration loop.
+   */
+  protected currentIteration?: IProjectExecutionIteration;
+  /**
+   * The number of remaining iterations to run.
+   */
+  protected remaining = 1;
+  /**
+   * Whether the configuration allows iterations (the parallel mode).
+   */
+  protected hasIterations = false;
   /**
-   * The variables processor instance.
+   * When set it won't amit any event.
+   * This can be used in a background worker when events are never handled.
    */
-  protected variablesProcessor = new VariablesProcessor();
+  noEmit = false;
 
-  constructor(project: HttpProject, opts: ProjectRunnerOptions = {}) {
+  constructor() {
     super();
-    this.project = project;
-    this.logger = opts.logger;
-    this.eventTarget = opts.eventTarget || new EventTarget();
-    this.masterEnvironment = opts.environment;
-    this.extraVariables = opts.variables;
+    this._requestHandler = this._requestHandler.bind(this);
+    this._responseHandler = this._responseHandler.bind(this);
+    this._errorHandler = this._errorHandler.bind(this);
   }
 
   /**
-   * Runs the request from the project root or a specified folder.
-   * @param options Run options.
-   * @returns A promise with the run result.
-   */
-  async run(options?: ProjectRunnerRunOptions): Promise<RunResult[]> {
-    const { project } = this;
-    const executed: RunResult[] = [];
-    for (const request of project.requestIterator(options)) {
-      const parent = request.getParent() || project;
-      let variables: Record<string, string>;
-      if (VariablesStore.has(parent)) {
-        variables = VariablesStore.get(parent);
-      } else {
-        variables = await this.getVariables(parent);
-        VariablesStore.set(parent, variables);
-      }
-      const info = await this.execute(request, variables);
-      executed.push(info);
+   * A required step before running the project.
+   * It configures the execution context. It may throw an error when configuration is not valid.
+   */
+  async configure(project: HttpProject, opts: IProjectRunnerOptions = {}): Promise<void> {
+    this.project = project;
+    this.options = opts || {};
+    if (typeof this.options.iterations === 'number' && this.options.iterations >= 0) {
+      this.remaining = this.options.iterations;
     }
-    return executed;
+    this.hasIterations = this.remaining > 1;
+
+    const root = opts.parent ? project.findFolder(opts.parent) : project;
+    if (!root) {
+      throw new Error(`Unable to locate the folder: ${opts.parent}`);
+    }
+    this.root = root;
+    this.environment = await this.getEnvironment();
   }
 
-  protected async execute(request: ProjectRequest, variables: Record<string, string>): Promise<RunResult> {
-    const config = request.getConfig();
-    const factory = new RequestFactory(this.eventTarget);
+  /**
+   * Executes the requests in the project.
+   * @returns The execution log created by calling the `createReport()` function.
+   */
+  abstract execute(): Promise<IProjectExecutionLog>;
 
-    factory.variables = variables;
-    if (request.authorization) {
-      factory.authorization = request.authorization.map(i => i.toJSON());
-    }
-    if (request.actions) {
-      factory.actions = request.actions.toJSON();
+  /**
+   * Creates the report of the execution.
+   */
+  protected async createReport(): Promise<IProjectExecutionLog> {
+    const log: IProjectExecutionLog = {
+      started: this.startTime as number,
+      ended: this.endTime as number,
+      iterations: this.executed,
+    };
+    return log;
+  }
+
+  /**
+   * Reads the environment data to use with the execution.
+   * If the configured environment is a location of a file
+   * it is read as API Client's environment and used in the execution.
+   * Otherwise it searches for the environment in the list of the defined 
+   * environments by the name of the key.
+   * 
+   * It throws when the environment cannot be found or when the file contents is invalid.
+   */
+  protected async getEnvironment(): Promise<Environment | undefined> {
+    const { options } = this;
+    if (!options) {
+      throw new Error(`Run configure() first.`);
     }
-    if (request.clientCertificate) {
-      factory.certificates = [request.clientCertificate];
+    if (!options.environment) {
+      return;
     }
-    if (config.enabled !== false) {
-      factory.config = config.toJSON();
+    const fileExists = await pathExists(options.environment);
+    if (fileExists) {
+      const contents = await readJson(options.environment);
+      return new Environment(contents as IEnvironment);
     }
-    if (this.logger) {
-      factory.logger = this.logger;
+    const root = this.root as ProjectParent;
+    const envs = root.getEnvironments();
+    const env = envs.find(i => i.key === options.environment || i.info.name === options.environment);
+    if (!env) {
+      throw new SerializableError(`The environment cannot be found: ${options.environment}.`, 'EENVNOTFOUND');
     }
-    const info: RunResult = {
-      key: request.key,
-    };
-    const requestData = request.expects.toJSON();
-    requestData.url = this.prepareRequestUrl(requestData.url, variables);
+    return env;
+  }
 
-    function variableHandler(e: CustomEvent): void {
-      if (e.defaultPrevented) {
-        return;
-      }
-      const { name, value } = e.detail;
-      variables[name] = value;
-      e.preventDefault();
-      e.detail.result = Promise.resolve();
+  /**
+   * Runs the requests from the project as configured.
+   */
+  protected async executeIteration(): Promise<void> {
+    const { environment, project, options, hasIterations, index, noEmit } = this;
+    if (!options || !project) {
+      throw new Error(`Run configure() first.`);
     }
-
-    this.eventTarget.addEventListener(EventTypes.Environment.set, variableHandler as any);
-
+    if (!noEmit) {
+      this.emit('before-iteration', index, hasIterations);
+    }
+    
+    const runner = new ProjectRequestRunner(project, {
+      environment,
+      logger: options.logger ? options.logger : new DummyLogger(),
+      eventTarget: this.target,
+      variables: this.getSystemVariables(),
+    });
+    
+    runner.on('request', this._requestHandler);
+    runner.on('response', this._responseHandler);
+    runner.on('error', this._errorHandler);
+    this.currentIteration = {
+      index: this.index,
+      executed: [],
+    };
     try {
-      // Below replaces the single call to the `run()` function of the factory to 
-      // report via the events a request object that has evaluated with the Jexl library.
-      const requestCopy = await factory.processRequestVariables(requestData);
-      this.emit('request', request.key, { ...requestCopy });
-      await factory.processRequestLogic(requestCopy);
-      const result = await factory.executeRequest(requestCopy);
-      await factory.processResponse(result);
-      request.setLog(result);
-      info.log = result;
-      this.emit('response', request.key, { ...result });
+      await runner.run({ 
+        parent: options.parent, 
+        requests: options.request, 
+        ignore: options.ignore, 
+        recursive: options.recursive 
+      });
     } catch (e) {
       const cause = e as Error;
-      info.error = true;
-      info.errorMessage = cause.message;
-      const sent = new SentRequest({ ...requestData, startTime: 0, endTime: 0, });
-      const response = ErrorResponse.fromError(info.errorMessage);
-      const log = RequestLog.fromRequestResponse(sent.toJSON(), response.toJSON()).toJSON();
-      this.emit('error', request.key, log, info.errorMessage);
+      console.error(e);
+      this.currentIteration.error = cause.message || 'Unknown error ocurred';
+      // ...
     }
-
-    this.eventTarget.removeEventListener(EventTypes.Environment.set, variableHandler as any);
-    return info;
-  }
-
-  protected async getVariables(parent: HttpProject | ProjectFolder): Promise<Record<string, string>> {
-    if (this.masterEnvironment) {
-      return this.applyVariables([this.masterEnvironment]);
+    this.executed.push(this.currentIteration);
+    if (!noEmit) {
+      this.emit('after-iteration', index, hasIterations);
     }
-    return this.createEnvironment(parent);
   }
 
-  protected async createEnvironment(parent: HttpProject | ProjectFolder): Promise<Record<string, string>> {
-    const envs = await this.readEnvironments(parent);
-    return this.applyVariables(envs);
+  /**
+   * Retargets the "request" event from the factory.
+   */
+  protected _requestHandler(key: string, request: IHttpRequest): void {
+    if (!this.noEmit) {
+      this.emit('request', key, request);
+    }
   }
 
   /**
-   * Reads the list of the environments to apply to this runtime.
+   * Retargets the "response" event from the factory.
    */
-  protected async readEnvironments(parent: HttpProject | ProjectFolder): Promise<Environment[]> {
-    const folderKey = parent.kind === ProjectFolderKind ? (parent as ProjectFolder).key : undefined;
-    return this.project.readEnvironments({ folderKey });
+  protected _responseHandler(key: string, log: IRequestLog): void {
+    this.currentIteration?.executed.push(log);
+    if (!this.noEmit) {
+      this.emit('response', key, log);
+    }
   }
 
   /**
-   * Reads the variables and the base URI from the passed environments.
+   * Retargets the "error" event from the factory.
    */
-  protected async applyVariables(environments: Environment[]): Promise<Record<string, string>> {
-    let baseUri = '';
-    const variables: Property[] = [];
-    environments.forEach((environment) => {
-      const { server, variables: envVariables } = environment;
-      if (server) {
-        baseUri = server.readUri();
-      }
-      if (envVariables.length) {
-        envVariables.forEach((item) => {
-          const defined = variables.findIndex(i => i.name === item.name);
-          if (defined >= 0) {
-            variables[defined] = item;
-          } else {
-            variables.push(item);
-          }
-        });
-      }
-    });
-    const { extraVariables } = this;
-    const ctx = VariablesProcessor.createContextFromProperties(variables);
-    if (extraVariables) {
-      Object.keys(extraVariables).forEach((key) => {
-        ctx[key] = extraVariables[key];
-      });
+  protected _errorHandler(key: string, log: IRequestLog, message: string): void {
+    this.currentIteration?.executed.push(log);
+    if (!this.noEmit) {
+      this.emit('error', key, log, message);
     }
-    // the `baseUri` is reserved and always set to the environment's `baseUri`.
-    ctx.baseUri = baseUri || '';
-    return this.variablesProcessor.buildContext(ctx);
   }
 
   /**
-   * When defined it applies the serve's base URI to relative URLs.
-   * @param currentUrl The URL to process.
+   * @returns Reads the system variables based on the library configuration.
    */
-  protected prepareRequestUrl(currentUrl: string, variables: Record<string, string>): string {
-    const { baseUri } = variables;
-    if (!baseUri) {
-      return currentUrl;
+  protected getSystemVariables(): Record<string, string> {
+    const result: Record<string, string> = {};
+    const { options } = this;
+    if (!options) {
+      return result;
+    }
+    const { variables } = options;
+    if (typeof variables === 'undefined') {
+      return result;
     }
-    if (currentUrl.startsWith('http:') || currentUrl.startsWith('https:')) {
-      return currentUrl;
+    if (typeof variables === 'boolean') {
+      return variables ? this._readSystemVariables() : result;
     }
-    if (currentUrl.startsWith('/')) {
-      return `${baseUri}${currentUrl}`;
+    if (Array.isArray(variables)) {
+      return this._readSystemVariables(variables);
     }
-    return `${baseUri}/${currentUrl}`;
+    return variables;
+  }
+
+  private _readSystemVariables(names?: string[]): Record<string, string> {
+    const result: Record<string, string> = {};
+    Object.keys(process.env).forEach((key) => {
+      if (names && !names.includes(key)) {
+        return;
+      }
+      const value = process.env[key];
+      if (value) {
+        result[key] = value;
+      }
+    });
+    return result;
   }
 }

package/src/runtime/node/ProjectRunnerWorker.ts

@@ -0,0 +1,62 @@
+/* eslint-disable no-unused-vars */
+import process from 'process';
+import cluster from 'cluster';
+import { HttpProject } from '../../models/HttpProject.js';
+import { IProjectExecutionLog } from '../reporters/Reporter.js';
+import { IWorkerMessage, IProjectParallelWorkerOptions } from './ProjectParallelRunner.js';
+import { sleep } from '../../lib/timers/Timers.js';
+import { ProjectRunner } from './ProjectRunner.js';
+
+class ProjectExeWorker extends ProjectRunner {
+  initialize(): void {
+    if (cluster.isPrimary) {
+      throw new Error(`This file should not be called directly.`);
+    }
+    process.send!({ cmd: 'online' });
+    process.on('message', this.messageHandler.bind(this));
+  }
+
+  messageHandler(message: IWorkerMessage): void {
+    switch (message.cmd) {
+      case 'run': this.run(message.data as IProjectParallelWorkerOptions); break;
+    }
+  }
+
+  async run(options: IProjectParallelWorkerOptions): Promise<void> {
+    try {
+      await this.configure(new HttpProject(options.project), options);
+      await this.execute();
+    } catch (e) {
+      const cause = e as Error;
+      process.send!({ cmd: 'error', data: cause.message });
+    }
+  }
+
+  async execute(): Promise<IProjectExecutionLog> {
+    const { root } = this;
+    if (!root) {
+      throw new Error(`The project runner is not configured.`);
+    }
+    function unhandledRejection(): void {}
+    process.on('unhandledRejection', unhandledRejection);
+    this.startTime = Date.now();
+    while (this.remaining > 0) {
+      this.remaining--;
+      await this.executeIteration();
+      this.index++;
+      if (this.remaining && this.options?.iterationDelay) {
+        await sleep(this.options.iterationDelay);
+      }
+    }
+    process.off('unhandledRejection', unhandledRejection);
+    this.endTime = Date.now();
+
+    const log = await this.createReport();
+    process.send!({ cmd: 'result', data: log.iterations });
+    return log;
+  }
+}
+
+const instance = new ProjectExeWorker();
+instance.noEmit = true;
+instance.initialize();

package/src/runtime/node/ProjectSerialRunner.ts

@@ -0,0 +1,36 @@
+import { SerializableError } from '../../models/SerializableError.js';
+import { sleep } from '../../lib/timers/Timers.js';
+import { ProjectRunner } from './ProjectRunner.js';
+import { IProjectExecutionLog } from '../reporters/Reporter.js';
+
+/**
+ * Project runner that runs the requests in the project one-by-one.
+ */
+export class ProjectSerialRunner extends ProjectRunner {
+  /**
+   * Executes the requests in the project.
+   */
+  async execute(): Promise<IProjectExecutionLog> {
+    const { root } = this;
+    if (!root) {
+      throw new SerializableError(`The project runner is not configured.`, 'ECONFIGURE');
+    }
+    
+    this.startTime = Date.now();
+    while (this.remaining > 0) {
+      this.remaining--;
+      await this.executeIteration();
+      this.index++;
+      if (this.remaining && this.options?.iterationDelay) {
+        this.emit('before-sleep');
+        await sleep(this.options.iterationDelay);
+        this.emit('after-sleep');
+      } else {
+        await sleep(0);
+      }
+    }
+
+    this.endTime = Date.now();
+    return this.createReport();
+  }
+}