@api-client/core 0.6.30 → 0.7.1

package/src/runtime/http-runner/HttpRequestRunner.ts

@@ -0,0 +1,353 @@
+import { IRequest } from '../../models/Request.js';
+import { IHttpRequest } from '../../models/HttpRequest.js';
+import { IRequestConfig } from '../../models/RequestConfig.js';
+import { IRequestAuthorization } from '../../models/RequestAuthorization.js';
+import { IRequestLog } from '../../models/RequestLog.js';
+import { VariablesProcessor } from '../variables/VariablesProcessor.js';
+import { IHttpActionFlow } from '../../models/http-actions/HttpActions.js';
+import { HttpEngineOptions } from '../http-engine/HttpEngine.js';
+import { CoreEngine } from '../http-engine/CoreEngine.js';
+import { Logger } from '../../lib/logging/Logger.js';
+import { CookieJar } from '../../cookies/CookieJar.js';
+import { RequestAuthorizationProcessor } from './RequestAuthorizationProcessor.js';
+import { RequestCookiesProcessor } from './RequestCookiesProcessor.js';
+import { HttpFlowRunner } from './HttpFlowRunner.js';
+import { ISentRequest } from "../../models/SentRequest.js";
+import { IResponse } from "../../models/Response.js";
+import { IErrorResponse } from "../../models/ErrorResponse.js";
+import { HttpCertificate } from '../../models/ClientCertificate.js';
+
+/**
+ * A class that takes a single HttpRequest definition and executes it.
+ * 
+ * This class does the following (in order):
+ * 
+ * - applies variables
+ * - applies authorization configuration
+ * - applies cookies
+ * - runs request actions 
+ * - transports the request
+ * - processes response and redirect cookies
+ * - runs response actions
+ * - reports the request log
+ */
+export class HttpRequestRunner {
+  /**
+   * Request processing configuration.
+   */
+  config?: IRequestConfig;
+
+  /**
+   * Request authorization configuration
+   */
+  authorization?: IRequestAuthorization[];
+
+  /**
+   * Actions to be performed when the request is executed.
+   */
+  flows?: IHttpActionFlow[];
+
+  /**
+   * 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;
+
+  /**
+   * The abort signal to set on this request.
+   * Aborts the request when the signal fires.
+   * @type {(AbortSignal | undefined)}
+   */
+  signal?: AbortSignal;
+
+  /**
+   * An instance of a cookie jar (store) to put/read cookies.
+   */
+  cookies?: CookieJar;
+
+  /**
+   * Certificates to send with the request.
+   */
+  certificates?: HttpCertificate[]
+
+  /**
+   * Creates an instance from the IRequest object with setting the corresponding variables.
+   * @param request The request object to use.
+   */
+  static fromRequest(request: IRequest): HttpRequestRunner {
+    const instance = new HttpRequestRunner();
+    instance.flows = request.flows;
+    instance.authorization = request.authorization;
+    instance.config = request.config;
+    return instance;
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * 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> {
+    let copy = await this.applyVariables(request);
+    copy = await this.applyAuthorization(copy);
+    copy = await this.applyCookies(copy);
+    await this.runRequestFlows(copy);
+    return copy;
+  }
+
+  /**
+   * Runs the request through the variables processor.
+   * @returns A copy of the passed request with possibly changed values.
+   */
+  async applyVariables(request: IHttpRequest): Promise<IHttpRequest> {
+    const { variables, variablesProcessor } = this;
+    let copy: IHttpRequest = { ...request };
+    if (variables) {
+      copy = await variablesProcessor.evaluateVariablesWithContext(copy, variables);
+    }
+    return copy;
+  }
+
+  async applyAuthorization(request: IHttpRequest): Promise<IHttpRequest> {
+    const auth = await this.readAuthorization();
+    RequestAuthorizationProcessor.setAuthorization(request, auth);
+    return request;
+  }
+
+  async applyCookies(request: IHttpRequest): Promise<IHttpRequest> {
+    const { cookies } = this;
+    if (!cookies || !this.sessionCookies) {
+      return request;
+    }
+    const list = await cookies.listCookies(request.url);
+    RequestCookiesProcessor.request(request, list);
+    return request;
+  }
+
+  /**
+   * Executes the request actions and modules.
+   */
+  async runRequestFlows(request: IHttpRequest): Promise<void> {
+    const flows = await this.readFlows('request');
+    const runner = new HttpFlowRunner();
+    runner.cookies = this.cookies;
+    runner.variables = this.variables;
+    await runner.request(request, flows);
+  }
+
+  /**
+   * Executes the request actions and modules.
+   */
+  async runResponseFlows(request: ISentRequest, response: IResponse | IErrorResponse): Promise<void> {
+    const flows = await this.readFlows('response');
+    const runner = new HttpFlowRunner();
+    runner.cookies = this.cookies;
+    runner.variables = this.variables;
+    await runner.response(request, response, flows);
+  }
+
+  /**
+   * Reads and evaluates action flows.
+   * 
+   * @param trigger The trigger name to read the flows for.
+   */
+  protected async readFlows(trigger: 'request' | 'response'): Promise<IHttpActionFlow[]> {
+    const result: IHttpActionFlow[] = [];
+    const { flows, variables = {}, variablesProcessor } = this;
+    if (!Array.isArray(flows) || !flows.length) {
+      return result;
+    }
+    for (const flow of flows) {
+      if (flow.trigger !== trigger) {
+        continue;
+      }
+      if (!Array.isArray(flow.actions) || !flow.actions.length) {
+        continue;
+      }
+      const copy = { ...flow } as IHttpActionFlow;
+      const actions = copy.actions.map(async (action) => {
+        const actionCopy = { ...action };
+        if (actionCopy.condition) {
+          actionCopy.condition = await variablesProcessor.evaluateVariablesWithContext(actionCopy.condition, variables);
+        }
+        if (Array.isArray(actionCopy.steps) && actionCopy.steps.length) {
+          const stepsPromises = actionCopy.steps.map((step) => variablesProcessor.evaluateVariablesWithContext(step, variables));
+          actionCopy.steps = await Promise.all(stepsPromises);
+        }
+        return actionCopy;
+      });
+      copy.actions = await Promise.all(actions);
+      result.push(copy);
+    }
+    return result;
+  }
+
+  /**
+   * 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 CoreEngine(request, opts);
+    return engine.send();
+  }
+
+  /**
+   * Creates a configuration options for the HTTP engine.
+   */
+  async prepareEngineConfig(): Promise<HttpEngineOptions> {
+    const { logger, signal } = this;
+    const auth = await this.readAuthorization();
+    const config = await this.readConfig();
+    const cert = RequestAuthorizationProcessor.readCertificate(auth);
+    const opts: HttpEngineOptions = {};
+    if (cert) {
+      opts.certificates = [cert];
+    }
+    if (this.certificates) {
+      if (!opts.certificates) {
+        opts.certificates = [];
+      }
+      opts.certificates = opts.certificates.concat(this.certificates);
+    }
+    if (Array.isArray(auth)) {
+      opts.authorization = auth;
+    }
+    if (logger) {
+      opts.logger = logger;
+    }
+    if (signal) {
+      opts.signal = signal;
+    }
+    if (!config || config.enabled === false) {
+      return opts;
+    }
+    if (typeof config.timeout === 'number') {
+      opts.timeout = config.timeout;
+    }
+    if (typeof config.sentMessageLimit === 'number') {
+      opts.sentMessageLimit = config.sentMessageLimit;
+    }
+    if (typeof config.followRedirects === 'boolean') {
+      opts.followRedirects = config.followRedirects;
+    }
+    if (typeof config.defaultHeaders === 'boolean') {
+      opts.defaultHeaders = config.defaultHeaders;
+    }
+    if (typeof config.validateCertificates === 'boolean') {
+      opts.validateCertificates = config.validateCertificates;
+    }
+    if (config.defaultUserAgent) {
+      opts.defaultUserAgent = config.defaultUserAgent;
+    }
+    if (config.defaultAccept) {
+      opts.defaultAccept = config.defaultAccept;
+    }
+    if (config.proxy) {
+      opts.proxy = config.proxy;
+    }
+    if (config.proxyUsername) {
+      opts.proxyUsername = config.proxyUsername;
+    }
+    if (config.proxyPassword) {
+      opts.proxyPassword = config.proxyPassword;
+    }
+    if (Array.isArray(config.hosts) ) {
+      opts.hosts = config.hosts;
+    }
+    return opts;
+  }
+
+  async processResponse(log: IRequestLog): Promise<void> {
+    const { request, response } = log;
+    if (!request || !response) {
+      return;
+    }
+    if (this.cookies && this.sessionCookies) {
+      const cookies = RequestCookiesProcessor.response(log);
+      if (cookies) {
+        const ps = Object.keys(cookies).map((url) => {
+          const items = cookies[url];
+          this.cookies?.setCookies(url, items);
+        });
+        await Promise.allSettled(ps);
+      }
+    }
+    await this.runResponseFlows(request, response);
+  }
+
+  get sessionCookies(): boolean {
+    const { config } = this;
+    if (!config) {
+      return true;
+    }
+    if (config.enabled === false) {
+      return true;
+    }
+    return !config.ignoreSessionCookies;
+  }
+}

package/src/runtime/http-runner/HttpRuntimeEnvironment.ts

@@ -0,0 +1,27 @@
+import { CookieJar } from "../../cookies/CookieJar";
+
+/**
+ * The request(s) execution environment.
+ * An environment is applied to each request in the iteration (if running a project request)
+ * or to the HTTP request (when running a single request).
+ * 
+ * In the iteration mode, the environment is shared across all requests in the iteration.
+ * After that the environment is discarded and re-created for the next iteration.
+ * 
+ * Cookies, depending on the implementation, most likely are shared across all iterations.
+ * This is why the implementation must to make sure it is safe to run the cookie functions
+ * in the parallel mode of a project runner.
+ */
+export interface IHttpRuntimeEnvironment {
+  /**
+   * The computed environment variables to use with this request or iteration.
+   * Variables can be changed but this change is not persistent. After each iteration
+   * the environment is restored it its default values.
+   */
+  variables: Record<string, string>;
+
+  /**
+   * An instance of a cookie jar (store) to put/read cookies.
+   */
+  cookies: CookieJar;
+}

package/src/runtime/http-runner/RequestAuthorizationProcessor.ts

@@ -0,0 +1,144 @@
+import { IHttpRequest } from '../../models/HttpRequest.js';
+import { IRequestAuthorization } from '../../models/RequestAuthorization.js';
+import { IBearerAuthorization, IBasicAuthorization, IOidcAuthorization, IOAuth2Authorization, ICCAuthorization } from '../../models/Authorization.js';
+import { HttpCertificate } from '../../models/ClientCertificate.js';
+import { Headers } from '../../lib/headers/Headers.js';
+
+/**
+ * Applies authorization data to the HttpRequest from 
+ * request authorization configuration.
+ */
+export class RequestAuthorizationProcessor {
+
+  /**
+   * Applies the auth data from the authorization config.
+   * 
+   * Note, this mutates the original request. Make a copy of you don't want to change 
+   * the values in the source request.
+   * 
+   * Note, this does not process client certificates. Use the `#readCertificates()` method to 
+   * get a certificate to use with the HTTP request,
+   * 
+   * @param request The request to apply the authorization to.
+   * @returns The same request (a reference)
+   */
+  static setAuthorization(request: IHttpRequest, authorization?: IRequestAuthorization[]): IHttpRequest {
+    if (!Array.isArray(authorization) || !authorization.length) {
+      return request;
+    }
+
+    for (const auth of authorization) {
+      if (auth.enabled === false || !auth.config) {
+        continue;
+      }
+      switch (auth.type) {
+        case 'basic': this.processBasicAuth(request, auth.config as IBasicAuthorization); break;
+        case 'oauth 2': this.processOAuth2(request, auth.config as IOAuth2Authorization); break;
+        case 'open id': this.processOpenId(request, auth.config as IOidcAuthorization); break;
+        case 'bearer': this.processBearer(request, auth.config as IBearerAuthorization); break;
+        default:
+      }
+    }
+    return request;
+  }
+
+  /**
+   * Reads the client certificate from the authorization configuration.
+   * 
+   * @param authorization The HTTP request authorization configuration.
+   * @returns The certificate to use with the HTTP request or undefined when not configured.
+   */
+  static readCertificate(authorization?: IRequestAuthorization[]): HttpCertificate | undefined {
+    if (!Array.isArray(authorization) || !authorization.length) {
+      return undefined;
+    }
+    const item = authorization.find(i => i.enabled !== false && i.type === 'client certificate');
+    if (!item || !item.config) {
+      return undefined;
+    }
+    const init = item.config as ICCAuthorization;
+    return init.certificate;
+  }
+
+  /**
+   * Injects basic auth header into the request headers.
+   */
+  protected static processBasicAuth(request: IHttpRequest, config: IBasicAuthorization): void {
+    const { username } = config;
+    if (!username) {
+      return;
+    }
+    this.applyRequestBasicAuthData(request, config);
+  }
+
+  /**
+   * Injects oauth 2 auth header into the request headers.
+   */
+  protected static processOAuth2(request: IHttpRequest, config: IOAuth2Authorization): void {
+    const { accessToken, tokenType='Bearer', deliveryMethod='header', deliveryName='authorization' } = config;
+    if (!accessToken) {
+      return;
+    }
+    const value = `${tokenType} ${accessToken}`;
+    if (deliveryMethod === 'header') {
+      const headers = new Headers(request.headers || '');
+      headers.append(deliveryName, value);
+      request.headers = headers.toString();
+    } else if (deliveryMethod === 'query') {
+      const { url } = request;
+      try {
+        const parsed = new URL(url);
+        parsed.searchParams.append(deliveryName, value);
+        request.url = parsed.toString();
+      } catch (e) {
+        // ...
+      }
+    }
+  }
+
+  /**
+   * Injects OpenID Connect auth header into the request headers.
+   */
+  protected static processOpenId(request: IHttpRequest, config: IOidcAuthorization): void {
+    const { accessToken } = config;
+    if (accessToken) {
+      this.processOAuth2(request, config);
+    }
+    // todo - if AT is missing find the current token from the tokens list in the passed configuration.
+    // Currently the authorization method UI sets the token when the requests is generated so it's not as much important.
+  }
+
+  /**
+   * Injects bearer auth header into the request headers.
+   */
+  protected static processBearer(request: IHttpRequest, config: IBearerAuthorization): void {
+    const { token } = config;
+    const value = `Bearer ${token}`;
+    const headers = new Headers(request.headers || '');
+    headers.append('authorization', value);
+    request.headers = headers.toString();
+  }
+
+  /**
+   * Applies the basic authorization data to the request.
+   *
+   * If the header value have changed then it fires `request-headers-changed` custom event.
+   * It sets computed value of the readers to the event's detail object.
+   *
+   * @param request The event's detail object. Changes made here will be propagated to the event.
+   * @param data The authorization data to apply.
+   */
+  protected static applyRequestBasicAuthData(request: IHttpRequest, data: IBasicAuthorization): void {
+    const { username='', password='' } = data;
+    const headers = new Headers(request.headers || '');
+    let hash: string;
+    const decoded = `${username}:${password}`;
+    if (typeof Buffer === 'function' && typeof Buffer.from === 'function') {
+      hash = Buffer.from(decoded).toString('base64');
+    } else {
+      hash = btoa(decoded);
+    }
+    headers.set('authorization', `Basic ${hash}`);
+    request.headers = headers.toString();
+  }
+}

package/src/runtime/http-runner/RequestCookiesProcessor.ts

@@ -0,0 +1,74 @@
+import { IHttpCookie, HttpCookie } from "../../models/HttpCookie.js";
+import { IHttpRequest } from "../../models/HttpRequest.js";
+import { IRequestLog } from "../../models/RequestLog.js";
+import { IErrorResponse } from "../../models/ErrorResponse.js";
+import { IResponse } from "../../models/Response.js";
+import { IResponseRedirect } from '../../models/ResponseRedirect.js';
+import { Headers } from '../../lib/headers/Headers.js';
+import { CookieParser } from "../../cookies/CookieParser.js";
+
+export class RequestCookiesProcessor {
+  /**
+   * Applies cookies to the request object.
+   * 
+   * Note, this mutates the request object.
+   * 
+   * @param request The request to which apply the cookies.
+   * @param cookies The cookies to apply
+   */
+  static request(request: IHttpRequest, cookies?: (IHttpCookie | HttpCookie)[]): void {
+    if (!Array.isArray(cookies) || !cookies.length) {
+      return;
+    }
+    const header = cookies.map((c) => `${c.name}=${c.value}`).join('; ');
+    const headers = new Headers(request.headers);
+    headers.append('cookie', header);
+    request.headers = headers.toString();
+  }
+
+  /**
+   * Computes a list of cookies in the response. This includes the redirect cookies and the final response.
+   * 
+   * @param log The HTTP log.
+   * @returns A map where keys are the URL of the request and the values are cookies. It may be empty map when no cookies.
+   */
+  static response(log: IRequestLog): Record<string, HttpCookie[]> | undefined {
+    if (!log.response || !log.request) {
+      return;
+    }
+    const typedError = log.response as IErrorResponse;
+    if (typedError.error) {
+      return;
+    }
+    const typedResponse = log.response as IResponse;
+    return this.extract(typedResponse, log.request.url, log.redirects);
+  }
+
+  protected static extract(response: IResponse, url: string, redirects?: IResponseRedirect[]): Record<string, HttpCookie[]> {
+    const result: Record<string, HttpCookie[]> = {};
+    let redirectUrl = url;
+    if (redirects && redirects.length) {
+      for (const redirect of redirects) {
+        const headers = new Headers(redirect.response.headers);
+        const sc = headers.get('set-cookie');
+        if (sc) {
+          const cookies = CookieParser.parse(redirectUrl, sc);
+          if (cookies.length) {
+            result[redirectUrl] = cookies;
+          }
+        }
+        redirectUrl = redirect.url;
+      }
+    }
+
+    const headers = new Headers(response.headers);
+    const sc = headers.get('set-cookie');
+    if (sc) {
+      const cookies = CookieParser.parse(redirectUrl, sc);
+      if (cookies.length) {
+        result[redirectUrl] = cookies;
+      }
+    }
+    return result;
+  }
+}

package/src/runtime/node/InteropInterfaces.ts

@@ -1,9 +1,11 @@
+/* eslint-disable @typescript-eslint/no-empty-interface */
 import { IProjectRequestIterator, IHttpProject } from '../../models/HttpProject.js';
 import { Environment } from '../../models/Environment.js';
 import { Logger } from '../../lib/logging/Logger.js';
 import { IRequestLog } from '../../models/RequestLog.js';
+import { CookieJar } from '../../cookies/CookieJar.js';
 
-export interface ProjectRunnerOptions {
+export interface IRequestRunnerOptions {
   /**
    * When provided it overrides any project / folder defined environment.
    */
@@ -20,16 +22,27 @@ export interface ProjectRunnerOptions {
    */
   logger?: Logger;
   /**
-   * The event target to use.
-   * By default it creates its own target.
+   * An instance of a cookie jar (store) to put/read cookies.
    */
-  eventTarget?: EventTarget;
+  cookies?: CookieJar;
 }
 
-export interface ProjectRunnerRunOptions extends IProjectRequestIterator {
+export interface IRequestRunnerRunOptions extends IProjectRequestIterator {
 }
 
-export interface RunResult {
+export interface IProjectExecutionResult {
+  /**
+   * The variables evaluated during the run. 
+   * These variables have values set by requests' HTTP flows.
+   */
+  variables: Record<string, string>;
+  /**
+   * The executed items.
+   */
+  items: IRunResult[];
+}
+
+export interface IRunResult {
   /**
    * The key of the request from the HttpProject that was executed.
    */
@@ -124,4 +137,9 @@ export interface IProjectRunnerOptions {
    * It aborts the execution when the ``abort` event is dispatched.
    */
   signal?: AbortSignal;
+
+  /**
+   * An instance of a cookie jar (store) to put/read cookies.
+   */
+  cookies?: CookieJar;
 }

package/src/runtime/node/ProjectParallelRunner.ts

@@ -141,7 +141,7 @@ export class ProjectParallelRunner extends BaseRunner {
       }
     });
     if (this.mainRejecter) {
-      this.mainRejecter!(new Error(`The execution has been aborted.`));
+      this.mainRejecter(new Error(`The execution has been aborted.`));
       this.mainRejecter = undefined;
       this.mainResolver = undefined;
     }
@@ -172,7 +172,9 @@ export class ProjectParallelRunner extends BaseRunner {
       cluster.on('exit', this._exitHandler);
     } catch (e) {
       const cause = e as Error;
-      this.mainRejecter!(cause);
+      if (this.mainRejecter) {
+        this.mainRejecter(cause);
+      }
       this.mainResolver = undefined
       this.mainRejecter = undefined
       this._state = State.Idle as State;