@api-client/core 0.3.3 → 0.3.4

package/src/runtime/node/ProjectRunner.ts

@@ -0,0 +1,275 @@
+import { EventEmitter } from 'events';
+import { Environment } from '../../models/Environment.js';
+import { Logger } from '../../lib/logging/Logger.js';
+import { IRequestLog } 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 { IHttpRequest } from '../../models/HttpRequest.js';
+import { HttpProject, IProjectRequestIterator } from '../../models/HttpProject.js';
+import { VariablesStore } from './VariablesStore.js';
+import { VariablesProcessor } from '../variables/VariablesProcessor.js';
+import { RequestFactory } from './RequestFactory.js';
+import { EventTypes } from '../../events/EventTypes.js';
+
+export interface ProjectRunnerOptions {
+  /**
+   * When provided it overrides any project / folder defined environment.
+   */
+  environment?: Environment;
+  /**
+   * 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`;
+   */
+  variables?: Record<string, string>;
+  /**
+   * Overrides the default logger (console).
+   */
+  logger?: Logger;
+  /**
+   * The event target to use.
+   * By default it creates its own target.
+   */
+  eventTarget?: EventTarget;
+}
+
+export interface ProjectRunnerRunOptions extends IProjectRequestIterator {
+}
+
+export interface RunResult {
+  /**
+   * The key of the request from the HttpProject that was executed.
+   */
+  key: string;
+  /**
+   * The key of parent folder of the executed request.
+   */
+  parent?: string;
+  /**
+   * 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.
+   */
+  error?: boolean;
+  /**
+   * The error message. Always set when the `error` is `true`.
+   */
+  errorMessage?: string;
+  /**
+   * The request log.
+   * Always set when the `error` is `false`.
+   */
+  log?: IRequestLog;
+}
+
+export interface ProjectRunner {
+  /**
+   * The request object is prepared and about to be sent to the HTTP engine
+   */
+  on(event: 'request', listener: (key: string, request: IHttpRequest) => void): this;
+  /**
+   * The response is ready.
+   */
+  on(event: 'response', listener: (key: string, log: IRequestLog) => void): this;
+  /**
+   * There was a general error during the request
+   */
+  on(event: 'error', listener: (key: string, request: IHttpRequest, message: string) => void): this;
+  /**
+   * The request object is prepared and about to be sent to the HTTP engine
+   */
+  once(event: 'request', listener: (key: string, request: IHttpRequest) => void): this;
+  /**
+   * The response is ready.
+   */
+  once(event: 'response', listener: (key: string, log: IRequestLog) => void): this;
+  /**
+   * There was a general error during the request
+   */
+  once(event: 'error', listener: (key: string, request: IHttpRequest, message: string) => void): this;
+}
+
+/**
+ * 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.
+ * 
+ * Requests are executed in order defined in the folder.
+ */
+export class ProjectRunner extends EventEmitter {
+  eventTarget: EventTarget;
+  logger?: Logger;
+  project: HttpProject;
+
+  protected masterEnvironment?: Environment;
+  protected extraVariables?: Record<string, string>;
+
+  /**
+   * The variables processor instance.
+   */
+  protected variablesProcessor = new VariablesProcessor();
+
+  constructor(project: HttpProject, opts: ProjectRunnerOptions = {}) {
+    super();
+    this.project = project;
+    this.logger = opts.logger;
+    this.eventTarget = opts.eventTarget || new EventTarget();
+    this.masterEnvironment = opts.environment;
+    this.extraVariables = opts.variables;
+  }
+
+  /**
+   * 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);
+    }
+    return executed;
+  }
+
+  protected async execute(request: ProjectRequest, variables: Record<string, string>): Promise<RunResult> {
+    const config = request.getConfig();
+    const factory = new RequestFactory(this.eventTarget);
+
+    factory.variables = variables;
+    if (request.authorization) {
+      factory.authorization = request.authorization.map(i => i.toJSON());
+    }
+    if (request.actions) {
+      factory.actions = request.actions.toJSON();
+    }
+    if (request.clientCertificate) {
+      factory.certificates = [request.clientCertificate];
+    }
+    if (config.enabled !== false) {
+      factory.config = config.toJSON();
+    }
+    if (this.logger) {
+      factory.logger = this.logger;
+    }
+    const info: RunResult = {
+      key: request.key,
+    };
+    const requestData = request.expects.toJSON();
+    requestData.url = this.prepareRequestUrl(requestData.url, variables);
+
+    function variableHandler(e: CustomEvent): void {
+      if (e.defaultPrevented) {
+        return;
+      }
+      const { name, value } = e.detail;
+      variables[name] = value;
+      e.preventDefault();
+      e.detail.result = Promise.resolve();
+    }
+
+    this.eventTarget.addEventListener(EventTypes.Environment.set, variableHandler as any);
+
+    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 });
+    } catch (e) {
+      info.error = true;
+      info.errorMessage = (e as Error).message;
+      this.emit('error', request.key, { ...requestData }, info.errorMessage);
+    }
+
+    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]);
+    }
+    return this.createEnvironment(parent);
+  }
+
+  protected async createEnvironment(parent: HttpProject | ProjectFolder): Promise<Record<string, string>> {
+    const envs = await this.readEnvironments(parent);
+    return this.applyVariables(envs);
+  }
+
+  /**
+   * Reads the list of the environments to apply to this runtime.
+   */
+  protected async readEnvironments(parent: HttpProject | ProjectFolder): Promise<Environment[]> {
+    const folderKey = parent.kind === ProjectFolderKind ? (parent as ProjectFolder).key : undefined;
+    return this.project.readEnvironments({ folderKey });
+  }
+
+  /**
+   * Reads the variables and the base URI from the passed environments.
+   */
+  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];
+      });
+    }
+    // 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.
+   */
+  protected prepareRequestUrl(currentUrl: string, variables: Record<string, string>): string {
+    const { baseUri } = variables;
+    if (!baseUri) {
+      return currentUrl;
+    }
+    if (currentUrl.startsWith('http:') || currentUrl.startsWith('https:')) {
+      return currentUrl;
+    }
+    if (currentUrl.startsWith('/')) {
+      return `${baseUri}${currentUrl}`;
+    }
+    return `${baseUri}/${currentUrl}`;
+  }
+}

package/src/runtime/node/RequestFactory.ts

@@ -0,0 +1,422 @@
+import { IRequest } from '../../models/Request.js';
+import { IHttpRequest } from '../../models/HttpRequest.js';
+import { IRequestConfig, IRequestBaseConfig } from '../../models/RequestConfig.js';
+import { IRequestAuthorization } from '../../models/RequestAuthorization.js';
+import { IRequestActions } from '../../models/RequestActions.js';
+import { IRequestCertificate } from '../../models/ClientCertificate.js';
+import { IRequestLog } from '../../models/RequestLog.js';
+import { VariablesProcessor } from '../variables/VariablesProcessor.js';
+import { IRunnableAction } from '../../models/actions/RunnableAction.js';
+import { Action } from '../../models/actions/Action.js';
+import { RunnableCondition } from '../actions/RunnableCondition.js';
+import { ActionRunner } from '../actions/ActionRunner.js';
+import { HttpEngineOptions } from '../http-engine/HttpEngine.js';
+import { ArcEngine } from '../http-engine/ArcEngine.js';
+import { ModulesRegistry, RegisteredRequestModule, RegisteredResponseModule, ExecutionContext, RegistryPermission } from '../modules/ModulesRegistry.js';
+import { ExecutionResponse } from '../modules/ExecutionResponse.js';
+import { Events } from '../../events/Events.js';
+import { Logger } from '../../lib/logging/Logger.js';
+
+/**
+ * The main class to make HTTP requests in the API Client / ARC.
+ * This factory includes all logic components to perform the entire HTTP request lifecycle. This includes:
+ * 
+ * - variables evaluation on the request object
+ * - running request actions
+ * - running request modules
+ * - choosing the execution engine
+ * - performing the request
+ * - running response actions
+ * - running response modules
+ * - reporting the response
+ * 
+ * This class may not be used when not necessary but the logic should take care of the items listed above.
+ * 
+ * This class splits the `IRequest` object into it's components and use them when defined.
+ * This way it is possible to use the factory only with the `IHttpRequest` interface.
+ */
+export class RequestFactory {
+  /**
+   * The main events bus.
+   * This target is used to dispatch the events on.
+   * The runtime should handle the events and proxy them to the corresponding context store.
+   */
+  eventTarget: EventTarget;
+  /**
+   * Request processing configuration.
+   */
+  config?: IRequestConfig;
+  /**
+   * Request authorization configuration
+   */
+  authorization?: IRequestAuthorization[];
+  /**
+   * Actions to be performed when the request is executed.
+   */
+  actions?: IRequestActions;
+  /**
+   * The list of certificates to use with the request.
+   */
+  certificates?: IRequestCertificate[];
+  /**
+   * The cumulative list of all variables to be applied to the request and other properties.
+   * The variables must be already processed for variables in values (evaluated).
+   * 
+   * These variables are passed by reference. Changes made anywhere to the variables will result 
+   * with updating this list.
+   */
+  variables?: Record<string, string>;
+  /**
+   * The variables processor instance.
+   */
+  variablesProcessor = new VariablesProcessor();
+
+  logger?: Logger;
+
+  /**
+   * Creates an instance from the IRequest object with setting the corresponding variables.
+   * @param eventTarget The main events bus.
+   * This target is used to dispatch the events on.
+   * The runtime should handle the events and proxy them to the corresponding context store.
+   * @param request The request object to use.
+   */
+  static fromRequest(eventTarget: EventTarget, request: IRequest): RequestFactory {
+    const instance = new RequestFactory(eventTarget);
+    instance.actions = request.actions;
+    instance.authorization = request.authorization;
+    if (request.clientCertificate) {
+      instance.certificates = [request.clientCertificate];
+    }
+    instance.config = request.config;
+    return instance;
+  }
+
+  /**
+   * @param eventTarget The main events bus.
+   * This target is used to dispatch the events on.
+   * The runtime should handle the events and proxy them to the corresponding context store.
+   */
+  constructor(eventTarget: EventTarget) {
+    this.eventTarget = eventTarget;
+  }
+
+  /**
+   * Runs the request and all tasks around the HTTp request execution like gathering 
+   * environment information, running actions, and HTTP modules.
+   * 
+   * @param request The request object to execute.
+   * @returns The execution log.
+   */
+  async run(request: IHttpRequest): Promise<IRequestLog> {
+    const requestCopy = await this.processRequest(request);
+    const result = await this.executeRequest(requestCopy);
+    await this.processResponse(result);
+    return result;
+  }
+
+  /**
+   * @returns the configuration processed by the variables processor.
+   */
+  async readConfig(): Promise<IRequestConfig | undefined> {
+    const { config, variables, variablesProcessor } = this;
+    if (!config) {
+      return undefined;
+    }
+    if (!variables) {
+      return config;
+    }
+    return variablesProcessor.evaluateVariablesWithContext(config, variables);
+  }
+
+  /**
+   * @returns the authorization data processed by the variables processor.
+   */
+  async readAuthorization(): Promise<IRequestAuthorization[] | undefined> {
+    const { variables, authorization, variablesProcessor } = this;
+    if (!Array.isArray(authorization) || !authorization.length) {
+      return undefined;
+    }
+    if (!variables) {
+      return authorization;
+    }
+    
+    const ps = authorization.filter(i => i.enabled !== false).map(async (item) => {
+      const copy = await variablesProcessor.evaluateVariablesWithContext(item, variables);
+      if (copy.config) {
+        copy.config = await variablesProcessor.evaluateVariablesWithContext(copy.config, variables);
+      }
+      return copy;
+    });
+    const result = await Promise.all(ps);
+    return result;
+  }
+
+  /**
+   * @returns the actions for the passed type processed by the variables processor.
+   */
+  async readActions(type: keyof IRequestActions): Promise<IRunnableAction[] | undefined> {
+    const { variables, actions, variablesProcessor } = this;
+    if (!actions) {
+      return undefined;
+    }
+    const list = actions[type];
+    if (!Array.isArray(list) || !list.length) {
+      return undefined;
+    }
+    if (!variables) {
+      return list;
+    }
+    const ps = list.filter(i => i.enabled !== false).map(async (item) => {
+      const copy = await variablesProcessor.evaluateVariablesWithContext(item, variables);
+      if (copy.condition) {
+        copy.condition = await variablesProcessor.evaluateVariablesWithContext(copy.condition, variables);
+      }
+      if (Array.isArray(copy.actions) && copy.actions.length) {
+        const actionsPs = copy.actions.map(async (action) => {
+          const actionCopy =  await variablesProcessor.evaluateVariablesWithContext(action, variables);
+          if (actionCopy.config) {
+            actionCopy.config = await variablesProcessor.evaluateVariablesWithContext(actionCopy.config, variables);
+          }
+          return actionCopy;
+        });
+        copy.actions = await Promise.all(actionsPs);
+      }
+      return copy;
+    });
+    const result: IRunnableAction[] = await Promise.all(ps);
+    return result;
+  }
+
+  /**
+   * Prepares the request object before making the HTTP request
+   * and runs actions and modules.
+   * 
+   * @param request The request to execute.
+   * @returns the copy of the request object.
+   */
+  async processRequest(request: IHttpRequest): Promise<IHttpRequest> {
+    const copy = await this.processRequestVariables(request);
+    await this.processRequestLogic(copy);
+    return copy;
+  }
+
+  /**
+   * Runs the request through the variables processor.
+   * @returns A copy of the passed request with possibly changed values.
+   */
+  async processRequestVariables(request: IHttpRequest): Promise<IHttpRequest> {
+    const { variables, variablesProcessor } = this;
+    let copy: IHttpRequest = { ...request };
+    if (variables) {
+      copy = await variablesProcessor.evaluateVariablesWithContext(copy, variables);
+    }
+    return copy;
+  }
+
+  /**
+   * Executes the request actions and modules.
+   */
+  async processRequestLogic(request: IHttpRequest): Promise<void> {
+    const actions = await this.readActions('request');
+    if (Array.isArray(actions) && actions.length) {
+      await this.processRequestActions(request, actions);
+    }
+    await this.processRequestModules(request);
+  }
+
+  /**
+   * Runs each action one by one.
+   * @param request The request object associated with actions
+   * @param actions The list of actions to execute.
+   */
+  async processRequestActions(request: IHttpRequest, actions: IRunnableAction[]): Promise<void> {
+    const runnables = actions.filter((item) => item.enabled !== false && !!item.actions && !!item.actions.length);
+    if (!runnables.length) {
+      return;
+    }
+    for (let i = 0, len = runnables.length; i < len; i++) {
+      const runnable = new RunnableCondition(runnables[i]);
+      const passed = await runnable.satisfied(request);
+      if (!passed) {
+        continue;
+      }
+      const execs = runnable.actions.filter(i => i.enabled !== false);
+      execs.sort(Action.sortActions);
+      for (let j = 0, eLen = execs.length; j < eLen; j++) {
+        const action = execs[j];
+        const runner = new ActionRunner(action, this.eventTarget);
+        try {
+          await runner.request(request);
+        } catch (e) {
+          if (action.failOnError) {
+            throw e;
+          } else {
+            const err = e as Error;
+            console.error(`Unable to run a request action: ${action.name || 'unknown name'}: ${err.message}`);
+          }
+        }
+      }
+    }
+  }
+
+  async processRequestModules(request: IHttpRequest): Promise<void> {
+    const modules = ModulesRegistry.get(ModulesRegistry.request);
+    for (const [id, main] of modules) {
+      const mod = main as RegisteredRequestModule;
+      const context = await this.buildExecutionContext(mod.permissions);
+
+      let result: number|undefined;
+      try {
+        result = await mod.fn(request, context);
+      } catch (e) {
+        // eslint-disable-next-line no-console
+        const err = e as Error;
+        console.warn(e);
+        const message = `Request module ${id} reported error: ${err.message}`;
+        throw new Error(message);
+      }
+      if (result === ExecutionResponse.ABORT) {
+        return;
+      }
+      if (Array.isArray(context.certificates)) {
+        if (!Array.isArray(this.certificates)) {
+          this.certificates = [];
+        }
+        this.certificates.concat(context.certificates);
+      }
+    }
+  }
+
+  /**
+   * Prepares the HTTP engine configuration and executes the request,
+   * @param request The request to execute.
+   * @returns The execution log.
+   */
+  async executeRequest(request: IHttpRequest): Promise<IRequestLog> {
+    const opts = await this.prepareEngineConfig();
+    const engine = new ArcEngine(request, opts);
+    return engine.send();
+  }
+
+  /**
+   * Creates a configuration options for the HTTP engine.
+   */
+  async prepareEngineConfig(): Promise<HttpEngineOptions> {
+    const { certificates, logger } = this;
+    const auth = await this.readAuthorization();
+    const config = await this.readConfig();
+    const opts: HttpEngineOptions = {};
+    if (Array.isArray(certificates) && certificates.length) {
+      opts.certificates = certificates;
+    }
+    if (Array.isArray(auth)) {
+      opts.authorization = auth;
+    }
+    if (logger) {
+      opts.logger = logger;
+    }
+    if (!config || config.enabled === false) {
+      return opts;
+    }
+    const exclude = ['kind', 'enabled', 'ignoreSessionCookies', 'variables'];
+    (Object.keys(config) as (keyof IRequestBaseConfig)[]).forEach(key => {
+      if (exclude.includes(key)) {
+        return;
+      }
+      const value: any = config[key];
+      opts[key] = value;
+    });
+    return opts;
+  }
+
+  async processResponse(log: IRequestLog): Promise<void> {
+    const { request, response } = log;
+    if (!request || !response) {
+      return;
+    }
+    await this.processResponseActions(log);
+    await this.processResponseModules(log);
+  }
+
+  async processResponseActions(log: IRequestLog): Promise<void> {
+    const actions = await this.readActions('response');
+    if (!Array.isArray(actions) || !actions.length) {
+      return;
+    }
+    if (!log.request || !log.response) {
+      return;
+    }
+    const runnables = actions.filter((item) => item.enabled !== false && !!item.actions && !!item.actions.length);
+    if (!runnables.length) {
+      return;
+    }
+    for (let i = 0, len = runnables.length; i < len; i++) {
+      const runnable = new RunnableCondition(runnables[i]);
+      const passed = await runnable.satisfied(log.request, log.response);
+      if (!passed) {
+        continue;
+      }
+      const execs = runnable.actions.filter(i => i.enabled !== false);
+      execs.sort(Action.sortActions);
+      for (let j = 0, eLen = execs.length; j < eLen; j++) {
+        const action = execs[j];
+        const runner = new ActionRunner(action, this.eventTarget);
+        try {
+          await runner.response(log);
+        } catch (e) {
+          if (action.failOnError) {
+            throw e;
+          } else {
+            const err = e as Error;
+            console.error(`Unable to run a request action: ${action.name || 'unknown name'}: ${err.message}`);
+          }
+        }
+      }
+    }
+  }
+
+  async processResponseModules(log: IRequestLog): Promise<void> {
+    const modules = ModulesRegistry.get(ModulesRegistry.response);
+    for (const [id, main] of modules) {
+      const mod = main as RegisteredResponseModule;
+      const context = await this.buildExecutionContext(mod.permissions);
+
+      let result: number|undefined;
+      try {
+        result = await mod.fn(log, context);
+      } catch (e) {
+        // eslint-disable-next-line no-console
+        const err = e as Error;
+        console.warn(e);
+        const message = `Response module ${id} reported error: ${err.message}`;
+        throw new Error(message);
+      }
+      if (result === ExecutionResponse.ABORT) {
+        return;
+      }
+    }
+  }
+
+  async buildExecutionContext(permissions: RegistryPermission[]): Promise<ExecutionContext> {
+    const result: ExecutionContext = {
+      eventsTarget: this.eventTarget,
+    };
+    const hasEnvironment = permissions.includes(RegistryPermission.environment);
+    if (hasEnvironment) {
+      result.variables = this.variables;
+    }
+    if (permissions.includes(RegistryPermission.events)) {
+      result.Events = {
+        Authorization: Events.Authorization,
+        ClientCertificate: Events.Model.ClientCertificate,
+        Cookie: Events.Cookie,
+        Encryption: Events.Encryption,
+        Process: Events.Process,
+        Environment: Events.Environment,
+      };
+    }
+    result.authorization = this.authorization;
+    result.config = await this.readConfig();
+    return result;
+  }
+}